Today, to get used to the Ruby HTTP api I wrote a little gem to talk to the hostip.info service, which handles things like getting current IP, and location services like country and geo location. Since I also need to get used to packaging Software for my Thesis which will be written mostly in Ruby I decided to work my way through setting up a Ruby gem to be installed via the gem tool.
Coming from a background of C/ObjC and Python packaging software and libraries is not new to be and Ruby makes this really easy, too. I decided to do a quick walkthrough since I had to piece everything together from about 20 sources, most of which I will probably never find again anyway. The Process is documented on the Ruby-gems Webpage, but is not completely obvious. Over all its a 3 step Process:
- Setup the directory structure for the gem, and copy the code in the correct directories
- Setup a Rakefile which also functions as the spec file (Manifest) for the gem to build
- Build the gem
Part 1 is really easy, just setup the directories as follows
The lib directory is where all your code is going to live the pkg directory is the place where the gem will be located after the build. Also quite important are the tests which in my opinion should be included in every gem since they provide a nice way to check the gem against your current ruby install, and will also detect missing dependencies and so on. 2 more files are needed to complete the gem, the Rakefile and the README. I choose rdoc as the format for the README since it can be used by Ruby directly for documentation, and will also be parsed and displayed by SCMs like Github.
The last part to complete the whole setup is the Rakefile, it includes all the specifications, like author, webpage, version, included files, tests and so on. The Rakefile will later be used to build the gem. Since I build a real simple one, it might be a good idea to just look at my source to figure out the basic format.
Lastly the gem can be build by issuing rake in the gem directory which will put the finished gem in pkg to be installed via gem install, afterwards it can be tested via gem check -t GEMNAME.
Thats pretty much it! Of course I build a really simple gem to get started, gems can also include things like native code, which would be located in ext, also the build instructions can be as complex as needed because rake is as powerful or maybe even more powerful then unix make. All in all to Ruby gems to me seem like a really nice and easy way to package and publish code comparable to CPAN for perl or easy_install eggs for Python.
Check out the code at Bitbucket and feel free to contact me about things I’m doing wrong or right.