1. Building Your First
Gem With Hoe
Jacob Harris
NYC.rb

2. RubyGems
• 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?

3. Making a Gem
• Run and audit your tests
• Layout your files into the proper directories
• Create a manifest of files in the gem
• Create a Gem Specification file
• Run gem build on your gem specification
• Release the gem to your Rubyforge account
• Dump rdocs for your gem
• Upload to your website on Rubyforge

4. Fight Administrivia
• 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

5. What Is Hoe?
• Very useful tool by Ryan Davis and Eric
Hodel of the Seattle Ruby Brigade.
• Hoe defines 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.

6. 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

7. Amazon Hacks
• Introducing our contrived example...
• http://amazon-hacks.rubyforge.com
• It's simple, but it's my first gem.
• It's also my first Hoe gem.
• So, what exactly does it do?
• Pardon me for a little self-promotion...

8. Playing With Links
require 'rubygems'
require 'amazon‐hacks'
url = 'http://www.amazon.com/Ruby‐Way‐Second‐Addison‐
Wesley‐Professional/dp/0672328844/sr=8‐1/
qid=1167793316/ref=pd_bbs_sr_1/102‐5040752‐5512947?
ie=UTF8&s=books'
l = Amazon::Hacks::Link.new(url)
url.country
# => :us
url.asin
# => "0672328844"
url.normalize
# => "http://www.amazon.com/o/asin/0672328844"

9. Playing With Images
i = Amazon::Hacks::Image.build_from_url(url)
i.set_size! :medium
i.url
# => "http://images.amazon.com/images/P/0672328844.01._SCMZZZZZZZ_.jpg"

10. Getting Perverse
i.blur! 25
i.add_shadow! :right
i.tilt! 15
i.url
# => "http://images.amazon.com/images/P/
0672328844.01._SCMZZZZZZZ_BL25_PC_PT15_.jpg"

11. Getting Started
harrisj% sow AmazonHacks
creating project AmazonHacks
... done, now go fix all occurances of 'FIX'
AmazonHacks/Rakefile:9: # p.summary = 'FIX'
AmazonHacks/README.txt:2: by FIX (your name)
AmazonHacks/README.txt:3: FIX (url)
AmazonHacks/README.txt:7:FIX (describe your package)
AmazonHacks/README.txt:11:* FIX (list of features or problems)
AmazonHacks/README.txt:15: FIX (code sample of usage)
AmazonHacks/README.txt:19:* FIX (list of requirements)
AmazonHacks/README.txt:23:* FIX (sudo gem install, anything else)
AmazonHacks/README.txt:29:Copyright (c) 2007 FIX

12. Gem File Layout
Your code
goes here
Your tests
go here

13. Getting Started
# cat Rakefile
require 'rubygems'
require 'hoe'
require './lib/amazon_hacks.rb'
Hoe.new('AmazonHacks', Amazonhacks::VERSION) do |p|
p.rubyforge_name = 'AmazonHacks'
# p.summary = 'FIX'
# p.description = p.paragraphs_of('README.txt', 2..5).join("
")
# p.url = p.paragraphs_of('README.txt', 0).first.split(/
/)[1..‐1]
p.changes = p.paragraphs_of('History.txt', 0..1).join("
")
end

14. Filling It In
# mate Rakefile
require 'rubygems'
require 'hoe'
require './lib/amazon‐hacks'
Hoe.new('amazon‐hacks', AmazonHacks::VERSION) do |p|
p.rubyforge_name = 'amazon‐hacks'
p.summary = 'A collection of useful snippets against the Amazon website'
p.author = 'Jacob Harris'
p.email = 'harrisj@schizopolis.net'
p.url = 'http://amazon‐hacks.rubyforge.com/'
p.description = p.paragraphs_of('README.txt', 2..6).join("
")
# p.url = p.paragraphs_of('README.txt', 0).first.split(/
/)[1..‐1]
p.changes = p.paragraphs_of('History.txt', 0..1).join("
")
p.extra_deps << ['color‐tools', '>= 1.3.0']
end

15. Packaging Tasks
• rake check_manifest - verify the manifest
• rake clean - clean up extras from code
• rake docs - build the docs from your code
• rake install_gem - install gem locally
• rake package - build the gem package
• rake ridocs - build docs for ri

16. Local Installation
harrisj% rake install_gem
(in /Users/harrisj/projects/AmazonHacks)
rm ‐r doc
rm ‐r pkg
sudo gem install pkg/*.gem
Password:
Successfully installed amazon‐hacks, version 0.5.0
Installing ri documentation for amazon‐hacks‐0.5.0...
Installing RDoc documentation for amazon‐hacks‐0.5.0...
harrisj% irb
irb> require 'rubygems'
=> true
irb> require 'amazon‐hacks'
=> true

17. Dependencies
From the Rakefile
p.extra_deps << ['color‐tools', '>= 1.3.0']
harrisj% gem dependency amazon‐hacks
Gem amazon‐hacks‐0.5.1
hoe (>= 1.1.6)
color‐tools (>= 1.3.0)

18. Publishing Tasks
• 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

19. Configuring Rubyforge
harrisj% rubyforge ‐‐config ‐‐user=harrisj ‐‐password=topsekrit
Add the following to /Users/harrisj/.rubyforge/config.yml
‐‐‐
rubyforge:
release_ids:
amazon‐hacks:
0.5.0: 8743
0.1.0: 8410
group_ids:
amazon‐hacks: 2731
package_ids:
amazon‐hacks: 3223
You need to be setup on
rubyforge.com first though.

20. Publishing
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
cd pkg
tar zcvf amazon‐hacks‐0.5.0.tgz amazon‐hacks‐0.5.0
** Execute pkg/amazon‐hacks‐0.5.0.gem
Successfully built RubyGem
Name: amazon‐hacks
Version: 0.5.0
File: amazon‐hacks‐0.5.0.gem
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

21. Publishing Docs
harrisj% rake publish_docs
(in /Users/harrisj/projects/AmazonHacks)
rm ‐r doc
rm ‐r pkg
rm ‐r doc
History.txt:
README.txt:
amazon‐hacks.rb: cmmm...c........mmc...............
Generating HTML...
Files: 3
Classes: 3
Modules: 5
Methods: 26
Elapsed: 4.645s
scp ‐rq doc/* harrisj@rubyforge.org:/var/www/gforge‐projects/amazon‐hacks
harrisj@rubyforge.org's password:

22. Publishing Docs

23. Don't Forget Testing
• rake audit - run ZenTest against your code
• rake multi - run tests against multiple versions
of Ruby
• rake test - run your tests
• rake test_deps - verify there are no hidden
dependencies in your tests

24. Testing Example
harrisj% rake test
(in /Users/harrisj/projects/AmazonHacks)
/usr/local/bin/ruby ‐w ‐Ilib:ext:bin:test ‐e 'require
"test/test_amazon‐hacks.rb"; require "test/unit"'
Loaded suite ‐e
Started
................................
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!

25. Further References
• http://rubygems.org/
• http://seattlerb.rubyforge.com/hoe
• http://seattlerb.rubyforge.org/hoedown.html
• 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