Building Your First
Gem With Hoe
• You know how to install a gem already.
• You probably have a ton of them installed.
• But have you ever thought of writing one?
• Isn't it time to share your own coding
brilliance with the Ruby community?
• But what are the steps for that?
Making a Gem
• Run and audit your tests
• Layout your ﬁles into the proper directories
• Create a manifest of ﬁles in the gem
• Create a Gem Speciﬁcation ﬁle
• Run gem build on your gem speciﬁcation
• Release the gem to your Rubyforge account
• Dump rdocs for your gem
• Upload to your website on Rubyforge
• Those are a lot of manual steps there
• Worse still, you need to repeat them for
every gem you want to write
• Hoe can automate that administrivia for you
• More time for coding
• Faster releases
• Less mistakes
• More likely you'll actually write that gem
What Is Hoe?
• Very useful tool by Ryan Davis and Eric
Hodel of the Seattle Ruby Brigade.
• Hoe deﬁnes a set of useful rake tasks that
makes gem building simple.
• It also includes the sow script to create a
gem skeleton for you.
• Spade, trowel, shovel, plow, and till are all still
available for your naming needs.
Making Gems With Hoe
• gem install hoe ‐‐include‐dependencies
• Setup rubyforge gem
• sow your gem directory.
• Write your code and tests
• Use rake to test, build docs, release, etc.
• Think about the next gem you'll write
• Introducing our contrived example...
• It's simple, but it's my ﬁrst gem.
• It's also my ﬁrst Hoe gem.
• So, what exactly does it do?
• Pardon me for a little self-promotion...
Playing With Links
url = 'http://www.amazon.com/Ruby‐Way‐Second‐Addison‐
l = Amazon::Hacks::Link.new(url)
# => :us
# => "0672328844"
# => "http://www.amazon.com/o/asin/0672328844"
Playing With Images
i = Amazon::Hacks::Image.build_from_url(url)
# => "http://images.amazon.com/images/P/0672328844.01._SCMZZZZZZZ_.jpg"
• rake email - generate email announcement
• rake post_news - post notice to Rubyforge
• rake publish_docs - post docs to Rubyforge
• rake release - upload release to Rubyforge
harrisj% rubyforge ‐‐config ‐‐user=harrisj ‐‐password=topsekrit
Add the following to /Users/harrisj/.rubyforge/config.yml
You need to be setup on
rubyforge.com ﬁrst though.
harrisj% sudo rake release VERSION=0.5.0
** Invoke package
** Execute pkg/amazon‐hacks‐0.5.0
* Execute pkg/amazon‐hacks‐0.5.0.tgz
tar zcvf amazon‐hacks‐0.5.0.tgz amazon‐hacks‐0.5.0
** Execute pkg/amazon‐hacks‐0.5.0.gem
Successfully built RubyGem
mv amazon‐hacks‐0.5.0.gem pkg/amazon‐hacks‐0.5.0.gem
** Execute gem
** Execute package
** Execute release
Logging in at depth 0 ‐ 18: self signed certificate
Releasing amazon‐hacks v. 0.5.0
Don't Forget Testing
• rake audit - run ZenTest against your code
• rake multi - run tests against multiple versions
• rake test - run your tests
• rake test_deps - verify there are no hidden
dependencies in your tests
harrisj% rake test
/usr/local/bin/ruby ‐w ‐Ilib:ext:bin:test ‐e 'require
"test/test_amazon‐hacks.rb"; require "test/unit"'
Loaded suite ‐e
Finished in 0.124621 seconds.
32 tests, 45 assertions, 0 failures, 0 errors
Until You Have A Long Line of Dots,
Don’t Even Think Of Releasing!
• A list of hoe‐built gems
• gem unpack any hoe-built gem and read
the code yourself
• and of course, rake ‐T in any hoe gem