So head over and check out the workflow site and read not only my fine fine article, but also the other news and podcasts he’s got going on over there.

First of all, I’m fairly new to this myself, so it’s very possible that I’ll miss something vital, please feel free to flame me in the comments, as long as you tell me where I messed up so I can fix it

Lets take a couple of examples.  One is a gem for dissecting XML feeds that I just discovered, feedzirra, the other is a bit more complex, Cinch, the IRC micro-framework I was talking about a few days ago.  Starting with feedzirra, here’s the listing of the files and directories in the root of the gem, I’ll take them one by one.

README.rdoc
README.textile
Rakefile
feedzirra.gemspec
lib/
spec/

README.*

The first two are pretty obvious, they are the README files with GitHub (and others) automatically parses out and displays when you hit the main project page.  Here is a list of the README formats that github supports, as well the order that it will display them in.  Here the author has included a README file as well as a README.textile (texttile is a simple markup language), and github displays the REAMDE.[something] first.

Rakefile

Rake, as you know is the ruby version of “make” the venerable Unix utility.  Inside the Rakefile you find a formatted set of rules in the form of tasks and targets.  Hit this tutorial for some more details.  The short story is that there are targets (with prerequisite/dependency information) such as install, uninstall, and release, supporting functions if needed, and some boilerplate info (description, name, contact, etc).  The targets can be anything it seems, for example Feedzirra has a task for releasing and uploading a new release, whereas cinch just has an ‘install’ task.  Rake is used a lot to help the creation of gems, but I don’t think that it’s used in the actual installation.

[gemname].gemspec

Here is the meat of it all, the gemspec file consists of the control information for the entire gem.  If you check out this tutorial you’ll see that it’s ruby code and can be created with a few utility scripts including Rake, and has some of the following information:

• Gem name and information (homepage, description)
• Author information (email, etc)
• Version and Date
• Other gem dependencies
• One or more boolean flags (ie: is there documentation that needs to be generated)
• A file list of what files need to be installed
• A list of executables of files that will be put in the bin directory when they’re installed

lib/ And Other Files or Directories

Basically what’s left are directories of files that are going to be installed on your system.  Of course, “lib” isn’t always going to be there, but for most gems that are adding a new class into your ruby environment, it will be.  The gemspec file has the list of the files and directories that will actually be taken out of the gem and installed into your system.  There are different ways to specify these files in gemspec, as you’ll see by comparing the s.files directive in the Cinch gemspec and the Feedzirra gemspec.

Inside the lib/ directory there will generally be one or two main files.  In Cinch you have:

cinch/
cinch.rb

This is the module that is loaded when you do a ‘require “cinch”‘ and the cinch/ directory has the supporting files.  The cinch.rb module file has a bunch of requires of “cinch/irc”, “cinch/rbase”, etc which are the sub-modules that it uses.  More on Modules vs Classes in a later post.

spec/

This will be the specs that the author has put in his source tree and includes so that other developers can look and use their tests.  Again, this isn’t going to always be there, but it seems to be very in vogue to do this whole “testing” thing, and including your spec or test directory is The Right Thing To Do.

File Locations

So when you run ‘gem install [foo]‘ where do the files go?  Lets use Cinch again for this one as it’s fairly simple.  Here’s a listing of the files that are in the source on github:

./LICENSE
./lib/cinch.rb
./lib/cinch/irc
./lib/cinch/irc/parser.rb
./lib/cinch/* [ more library module files ]
./examples/hello.rb
./examples/* [ more example files ]
./README.rdoc
./spec/irc/parser_spec.rb
./spec/* [ more specs ]
./Rakefile
./cinch.gemspec

(Note some of the directories are abbreviated).

When you do a gem install the files moved into the path defined in $GEM_HOME thusly:

cinch/lib           => $GEM_HOME/gems/cinch-0.2.6/lib
cinch/examples      => $GEM_HOME/gems/cinch-0.2.6/examples
[...]
cinch/README.rdoc   => $GEM_HOME/gems/cinch-0.2.6/README.rdoc
                    => $GEM_HOME/doc/cinch-0.2.6/ri/*
                    => $GEM_HOME/doc/cinch-0.2.6/rdoc/*

Nothing hugely interesting, files are basically just moved into your gem home directory under a directory named with the name and version of the gem you’re installing.  Note that the doc/*/ri and doc/*/rdoc files are auto-created when the gem install runs, if you don’t pass the –no-ri or –no-rdoc flags of course.  The internal magic in rubygems and ruby allow your programs to find the gems when they are ‘required’.

How to Examine A Gem

One of the nicest ways to play with these things, and what I did was to use RVM and then doing a gem install, as well as using git clone to pull down the source files from github.  RVM, combined with it’s great gemset support, is a great tool and makes it really easy to add, remove, and play with no fear of mucking things up.

Conclusion

So that’s about it for the normal library gems that you’ll find on github.  Hopefully you now understand a bit more about how a gem is structured and what happens when you install and use gems, and how they will interact with each other.  I found lots of resources out there, including some great stuff on how to create your own gems, gemspec files, and so on, listed below.

Additional Reading

• http://docs.rubygems.org/read/chapter/5
• http://rubygems.org/pages/gem_docs
• http://railscasts.com/episodes/135-making-a-gem
• http://asciicasts.com/episodes/183-gemcutter-jeweler
• http://buzaz.com/index.php/2010/01/03/how-to-build-a-ruby-gem/
• http://docs.rubygems.org/read/chapter/20
• http://yehudakatz.com/2010/04/02/using-gemspecs-as-intended/

• Gem – The basic distribution of most of the plugins and addon libraries for Ruby.  Thing CPAN.  A lot of times you can either install a gem onto your system or as a plugin to a rails project.  The basics are you can run “gem list”, “gem install <gem>” and “gem search –remote <search>” to list installed gems, install a new gem by name, or search the configured remote gem servers.  Speaking of CPAN, the main two places for gems (currently anyway) are github and rubygems.  The main rubygems distribution is essential to get most of the gem functionality, so you’ll need to make sure you have the rubygems package (for your OS) installed and working before you can start doing “gem install” all crazy like.  More information can be found on the rubygems site.
• TDD – Test Driven Development.  Ruby and Rails people love testing.  They love it like mom’s homemade pasta and meatballs served to you with lots of Parmesan cheese after a long day. The TDD philosophy basically means that before you write code, you write a test.  In the simplest “hello world” case you would write a test to say “does the program print out ‘hello world’”.  It of course fails because there is no program written yet.  Then you write the code and work on it until it prints out “hello world” and the test passes.  Some people follow TDD to extremes, some ignore it completely (but shouldn’t) and others work in the grey area in between extremes.
• Waterfall – The waterfall model is another design philosophy, but this is more of the old school, not web 2.0, evil-used-by-suits philosophy.  It’s your classic “wait till Bob gets the requirements done, then we need the architect team to design the models and system, then we’ll get you to implement it, it’ll head into QA for them to test, and eventually it’ll go into maintenance mode”.  Yawn.  That’s not to say that there aren’t good reasons to use this model, but it’s considered an old school way of doing things.  You’ll know what your mentor means and not think he’s talking about a trip to look at waterfalls anyway.
• DHH – This of course is the creator of Rails, David Heinemeir Hansson.  You might also hear names like Obie Fernandez, Wayne Seguin, and JEG2 (James Edward Gray II), and these too are people high up in the community.  There are a lot of them, and it’s a big community, so don’t feel too bad if you don’t recognize a name or two.
• MVC – The Model, View, Controller model is at the core of Rails, and if you somehow managed to miss this in the first chapter of any Rails book, I’m shocked!  However, if you somehow did, you may hear it thrown around and get confused, especially if you come from another programming language and are still used to the old world “SQL and code inside your HTML file” world that you’ll be so happy to escape.
• DRY – Another big one I’d be shocked if you didn’t know, it’s Don’t Repeat Yourself, another tenant of the Ruby and Rails world.  Basically this means that copy and paste programming is not a desired thing, and if you find yourself doing the same bit of code more than once (ie: formatting a price with a $ and decimal places) it’s best to find a way to move that into it’s own function so it’s only in one place.  This makes code easier to maintain, and keeps you happy.  Not a Rails specific philosophy, but definitely a core value.  Next time someone looks at your work and tells you it’s not DRY you’ll know what they mean.
• Refactoring – Closely related to DRY, refactoring is the act of going back and seeing where you can extract common functionality or make the code more idiomatic or simple.  Different from Golf challenges in Perl by far.  Check out Refactor My Code if you want to get some great examples of how different people take the approach.  This site is awesome as you don’t just see the end result of good coding (as you’d see by reading (some) other people’s source code), but both the start and several alternative results.
• Convention over Configuration – The idea that by following naming and file conventions, and following them, productivity goes up over a framework that allows you to configure where files are, how classes are named, etc.  By having a set of standard practices that you know your system follows, you can concentrate on what you’re doing and get sh$t done!  This is probably the most important tenant of Rails, and is pretty much what the entire thing is built on.
• Framework – Going back a bit, what the heck is a framework.  Short answer is it’s something you build your applications in which provides you with everything you need.  In other words, instead of you having to deal with HTTP POST parameters for string processing, it provides you with libraries for data handling and common functionality.
• CRUD – Speaking of things you don’t have to deal with, the biggest thing that I think web app developers have to deal with is the four common actions you’re taking with data (think editing a list of blog posts): Create, Retrieve, Update, and Delete.  This is shorthand for telling people that the data you’re dealing with has (or needs) the standard set of actions to edit, delete, show and create functionality.  This goes hand in hand with our last one…
• Scaffolding – This is the concept of creating a default set of functionality that the programmer can update later on.  This is a quick and dirty way of getting things working, and is, in most cases, either only used for learning purposes or is rewritten later.  Creating a scaffold for a set of data (say a blog post) can be done in rails by running “script/generate scaffold Post title:string body:text”.  This will create a scaffolding which lets you have access to the CRUD operations on this new data model.  With just that one line above you get all the HTML, form processing, and database layer interaction needed to fully perform CRUD operations.  The concept of using scaffolding to create quick and easy access to data is a huge part of Rails’ success (even if you do end up rewriting them eventually, or grow out of using scaffolding as your skills improve).

There are lots more out there (this page has a great list).  Phusion, Heroku, nginx, nokogiri, sass, haml, copilot and scout are other terms for some specific software and sites and libraries you might come across.

First was that Rails 3 isn’t that different than Rails 2 (which BTW, is apparently obselete at least for the “normal” tasks of CRUD like operations in the demo application.  A few bits of different syntax here and there, but for the most part it was all pretty recognizable.

I was secondly surprised at how much I understood.  Not that I’m dumb of course, but a lot of things in rails I just let wash over me and accept that I Just Don’t Get Yet^(tm)(r)(c).  This stuff however, was perfectly recognizable and grokkable, and because of that I actually picked up a couple of new things.

So my personal revelation of the day (I’m not going to call them tips cause that’d indicate that other people don’t all know this stuff already) is to go back and re-watch, re-read, or re-listen to things that you maybe didn’t fully grasp, or didn’t grasp that fully, and see if the second viewing with a few weeks or months of time gives you a better grasp of it.

The last request that came in was for the ability to take a game object with a non-boolean, but discreet bit of data to specify if it is a boys only, girls only, or coed game.  A constant you might say.

Back in the old perl world I’d probably look at doing something like adding an integer field to the database and then just remember that 1 = boys, 2 = girls and 0 = coed.  Or something.  Or was it 3 = coed?  You see the problem here though.  Having to remember the settings, and make sure that all the different files output the same values for the same settings… ugh.  Even putting an output filter of some sort (or in rails parlance, a helper), is a bit of an ugly situation because that doesn’t help you with your database layer either.  I might also have used the “Constant” or “ReadOnly”modules to do the same, or even gone with the more complex solution is to create a foreign key into another table called “gamegendertype” or something that just has the 1 = boys, 2 = girls, 3 = coded, but that’s unneeded complexity, database lookups/joins, etc (though it doesmake it easier to add another data type).

So I dug into it to find out what the canonical “rails way” was to do it.  And that search led to enums.  Enums allow you to specify your own discreet data types that can be searched on as if they were integers or the like, but are words like “Diamonds” “Hearts” “Clubs” and “Spades” for a solitaire game.

Rails doesn’t seem to have a built in way to do it, but the way that the various links I found had you do it were to store the string value in the backend database, but turn that into a :symbol for when it’s accessed to and from the front end.  A link is worth a thousand words though

• Using constants in RoR, or how to use them with migrations, from StackOverflow
• Enumeration columns in rails
• An (older) Enum plugin
• ActiveRecord enums (#3 in the list, via the StackOverflow link)

For my project I’d rather not use a plugin (trying to learn by doing and all) so I’ll probably go with the virtual attribute method (last link).  Keep an eye on the commit log on my github account to see where it goes