A long time ago, on an internet far away, publishing code to RubyForge was a scary thing to do.
After a bit of setup, publishing a gem to RubyForge is this easy:
rake release VERSION=1.0.1
Unfortunately, not many tutorials exist that show you how to harness the raw power of hoe. Until now.
I’ve been using hoe for a few months to package my projects as RubyGems, but realized today that I was only using part of the functionality. I know that I’ve neglected to release some updates to my gems because the process of logging in to RubyForge, creating a new release, and uploading the gem with various types of compression was too cumbersome. It’s not that there’s any problem with the system, it’s just that there are three or four steps involved and usually takes 10 to 20 minutes.
Hoe turns that into a 1 minute process, once you’ve done the initial setup.
It also provides a set of tasks for running tests, generating documentation, etc.
Finally, it provides a way to release your gem with a single command. You can also publish your documentation which is a real benefit to people who are learning how to use your library.
First, install hoe.
sudo gem install hoe --include-dependencies
This will also install the useful
rubyforge gem which we will use to publish our gem. Previously, the
rubyforge command required a lot of manual configuration, but now it’s nearly automatic.
This creates a basic config file in your home directory and opens it in the
EDITOR of your choice. Enter your RubyForge username and password, save and close (signup if you don’t have one). I have my shell’s
EDITOR variable set to
/usr/bin/mate -w so I can edit files in TextMate.
rubyforge do its magic. It will scrape the list of existing projects and setup the necessary IDs for your projects.
If you haven’t registered any projects, you can do it after signing up for an account. It usually takes a day or less for a project to be approved. I’ve never heard of any project application being rejected.
You should re-run the
config command after registering (and receiving confirmation for) a new project.
Finally, run the
login command to cache a cookie for further operations.
Next, use the included
sow command to start a new gem project.
You may also want to look at the prolific Dr. Nic’s newgem. I like sow because it generates the smallest number of files necessary to make a gem.
newgem is more powerful and provides a lot more functionality. Try both and see which one you like.
sow creates the following files.
History.txt Manifest.txt Rakefile README.txt bin sparklines lib sparklines.rb test test_sparklines.rb
Now, you’ll need to edit the Rakefile and the README.txt with your information. Most of the options are self-explanatory, but here are a few resources:
Two things to note…
If you only have one project, you’ll want to set
p.remote_rdoc_dir = '' # Release to root
This will configure your documentation to be published to the root of your RubyForge subdomain (http://sparklines.rubyforge.org). By default, the documentation goes into a subdirectory and you’ll have to make an index page that links to it, such as the one for the Seattle.rb.
Tip: Register one project with RubyForge, then publish multiple gems to it. This way you don’t have to make a new project for every new gem you want to write. See the Seattle.rb page or the NYC.rb page for examples.
I’m not sure whether or not Ryan is a fan of the Fugees, but hoe does require a Manifest. This is a text file that lists the files to package in the gem.
sow creates one for you with the basic set of files, and you can run
rake check_manifest to see if you’ve created new files that aren’t mentioned in the Manifest.
$ rake check_manifest
@ -4,4 +4,4@ Rakefile bin/sparklines lib/sparklines.rb -lib/doesnt_exist.rb +test/test_sparklines.rb
The lines with a
- are listed in the Manifest but don’t exist on disk. The lines with a
+ are not in the Manifest but are on the disk.
Order is relevant, and you’ll do best if you close the file with a newline.
NOTE: Newer versions of Hoe require a .hoerc in your home directory. Here’s a sample .hoerc
Once you’ve written your code and tested it, you can generate a gem and send it to RubyForge. Edit the top of
History.txt with the changes you made.
== 1.0.1 * New version
VERSION with the new version number.
# lib/sparklines.rb class Sparklines VERSION = '1.0.1' end
rake release VERSION=1.0.1
If you’ve run
rubyforge login recently, your gem will be created and sent to RubyForge. It’s that easy!
There are a few other tasks. Use
rake -T to see them all. I like to see what message will be generated by typing
You should also publish the documentation for your gem.
rsync, so you’ll be asked for your RubyForge password.
Much work has been put into making rubygems a great system for publishing code, managing dependencies, and maintaining versions. Some people have been so bold as to suggest that the Rails plugin system should die and we should all use rubygems instead. (I agree with them.)