Building Your First
 Gem With Hoe

               Jacob Harris
                   NYC.rb
RubyGems
• You know how to install a gem already.
• You probably have a ton of them installed.
• But have you ever thought...
Making a Gem
• Run and audit your tests
• Layout your files into the proper directories
• Create a manifest of files in the ...
Fight Administrivia
• Those are a lot of manual steps there
• Worse still, you need to repeat them for
  every gem you wan...
What Is Hoe?
• Very useful tool by Ryan Davis and Eric
  Hodel of the Seattle Ruby Brigade.
• Hoe defines a set of useful r...
Making Gems With Hoe
• gem
install
hoe
‐‐include‐dependencies
• Setup rubyforge gem
• sow your gem directory.
• Write your...
Amazon Hacks
• Introducing our contrived example...
• http://amazon-hacks.rubyforge.com
• It's simple, but it's my first ge...
Playing With Links
require
'rubygems'
require
'amazon‐hacks'

url
=
'http://www.amazon.com/Ruby‐Way‐Second‐Addison‐
Wesley...
Playing With Images



i = Amazon::Hacks::Image.build_from_url(url)
i.set_size! :medium
i.url
# => "http://images.amazon.c...
Getting Perverse



i.blur!
25
i.add_shadow!
:right
i.tilt!
15
i.url
#
=>
"http://images.amazon.com/images/P/
0672328844.0...
Getting Started
harrisj%
sow
AmazonHacks
creating
project
AmazonHacks
...
done,
now
go
fix
all
occurances
of
'FIX'



Amaz...
Gem File Layout


           Your code
            goes here



           Your tests
             go here
Getting Started
#
cat
Rakefile

require
'rubygems'
require
'hoe'
require
'./lib/amazon_hacks.rb'

Hoe.new('AmazonHacks',
A...
Filling It In
#
mate
Rakefile

require
'rubygems'
require
'hoe'
require
'./lib/amazon‐hacks'

Hoe.new('amazon‐hacks',
Amaz...
Packaging Tasks
• rake
check_manifest - verify the manifest
• rake
clean - clean up extras from code
• rake
docs - build t...
Local Installation
harrisj%
rake
install_gem
(in
/Users/harrisj/projects/AmazonHacks)
rm
‐r
doc
rm
‐r
pkg
sudo
gem
install...
Dependencies
From the Rakefile
p.extra_deps
<<
['color‐tools',
'>=
1.3.0']

harrisj%
gem
dependency
amazon‐hacks
Gem
amazon...
Publishing Tasks
• rake
email - generate email announcement
• rake
post_news - post notice to Rubyforge
• rake
publish_doc...
Configuring Rubyforge
harrisj%
rubyforge
‐‐config
‐‐user=harrisj
‐‐password=topsekrit


                                   ...
Publishing
harrisj%
sudo
rake
release
VERSION=0.5.0
**
Invoke
package
**
Execute
pkg/amazon‐hacks‐0.5.0
*
Execute
pkg/amaz...
Publishing Docs
harrisj%
rake
publish_docs
(in
/Users/harrisj/projects/AmazonHacks)
rm
‐r
doc
rm
‐r
pkg
rm
‐r
doc








...
Publishing Docs
Don't Forget Testing

• rake
audit - run ZenTest against your code
• rake
multi - run tests against multiple versions
  of...
Testing Example
harrisj%
rake
test
(in
/Users/harrisj/projects/AmazonHacks)
/usr/local/bin/ruby
‐w
‐Ilib:ext:bin:test
‐e
'...
Further References
• http://rubygems.org/
• http://seattlerb.rubyforge.com/hoe
• http://seattlerb.rubyforge.org/hoedown.ht...
Upcoming SlideShare
Loading in...5
×

Hoe Talk

6,604

Published on

Jacob Harris
NYC.rb

Published in: Technology, Design
3 Comments
2 Likes
Statistics
Notes
No Downloads
Views
Total Views
6,604
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
0
Comments
3
Likes
2
Embeds 0
No embeds

No notes for slide

Hoe Talk

  1. 1. Building Your First Gem With Hoe Jacob Harris NYC.rb
  2. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 12. Gem File Layout Your code goes here Your tests go here
  13. 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. 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. 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. 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. 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. 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. 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. 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. 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. 22. Publishing Docs
  23. 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. 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. 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

×