Creating a rubygem - a story and help request

[Phrogz]

The Story
I decided that it is finally time for me to stop just putting .rb
files on my own server, and instead start hosting them as gems.
(Mostly because I now have one library that relies on another, and I
need them installed in some common spot for require to work cleanly.)

So, last night I googled "rubygems create gem gemspec" and the second
hit was:
http://rubygems.org/read/chapter/5
which says "This is a skimpy overview; see the DeveloperGuide for the
real meat."

But I couldn't figure out what the DeveloperGuide is, so I googled
"rubygems DeveloperGuide wiki", and the first hit was:
http://osdir.com/ml/lang.ruby.gems.devel/2006-06/msg00044.html
....
which is a post from 1.5 years ago by Jim Weirich saying:
"The wiki is totally decommissioned. I should see if there is a way
for Tom to disable it."

OK, so apparently I was looking at bad data. That's not uncommon. I
decided to start at the source. I go to rubygems.org and...well, you
can go there and see that it has a link to the same documentation I
was seeing previously.

I googled for "DeveloperGuide site:rubygems.org" and found 5 hits that
all refered to the absent DeveloperGuide.

I look around on the rubygems.org site in the other documentation. The
FAQ surprisingly (to me) doesn't have an entry on how to create a
gemspec. The gemspec reference is a reference, about as useful for
creating a gemspec as a dictionary is useful for learning how to write
an English paper.

The Request
Help! How do I create a gem? I know that once I do, and upload it to
rubyforge, that it will magically be available to all. But first I
need to create one, and...I'm stumped.

The Request II
Hey rubygems developers, please put up a simple HOWTO that walks
someone through the basics of creating their first gem. Preferably,
put it in prominent locations on your website, in the places where
Google is bound to land. Please, clean up the documentation to remove
references to DeveloperGuide, or hotlink the existing link to
something useful.

 

[Bil Kleb]

Help! How do I create a gem? I know that once I do, and upload it to
rubyforge, that it will magically be available to all. But first I
need to create one, and...I'm stumped.

When I went through this process the first time, I used the Pick Axe
chapter written by Chad Fowler and browsed gem specs I found online
for Hoe, Rake, and the like.

The next time, I tried Dr. Nic's newgem, but it was overwhelming.

Now, I use 'sow' that comes with the Hoe gem to create a nice,
minimalistic gem skeleton, e.g.,

$ sudo gem install hoe
$ sow gem_of_gems
creating project gem_of_gems
... done, now go fix all occurrences of 'FIX'

GemOfGems/Rakefile:9: # p.author = 'FIX'
GemOfGems/Rakefile:10: # p.email = 'FIX'
GemOfGems/Rakefile:11: # p.summary = 'FIX'
GemOfGems/README.txt:2: by FIX (your name)
GemOfGems/README.txt:3: FIX (url)
GemOfGems/README.txt:7:FIX (describe your package)
GemOfGems/README.txt:11:* FIX (list of features or problems)
GemOfGems/README.txt:15: FIX (code sample of usage)
GemOfGems/README.txt:19:* FIX (list of requirements)
GemOfGems/README.txt:23:* FIX (sudo gem install, anything else)
GemOfGems/README.txt:29:Copyright (c) 2007 FIX

I leaned on topfunky's blog post to get going:

http://nubyonrails.com/articles/tutorial-publishing-rubygems-with-hoe

Regards,

 

[Phrogz]

$ sudo gem install hoe
$ sow gem_of_gems

Thanks, hoe/sow certainly do help fill the blank canvas.

I leaned on topfunky's blog post to get going:

http://nubyonrails.com/articles/tutorial-publishing-rubygems-with-hoe

Ah, that's even more helpful. Thanks!

 

[7stud --]

The Request
Help! How do I create a gem? I know that once I do, and upload it to
rubyforge, that it will magically be available to all. But first I
need to create one, and...I'm stumped.

pickaxe2, Chapter 17 has a section titled: Creating Your Own Gems. I
haven't read it yet, so I don't know how helpful it is. It's 10 pages
long.

 

[Phrogz]

pickaxe2, Chapter 17 has a section titled: Creating Your Own Gems. I
haven't read it yet, so I don't know how helpful it is. It's 10 pages
long.

So it does. I'll read through that, but I maintain that Rubygems
should not rely on a 3rd party must-buy book to document what ought to
be described on their website.

 

[Jeremy McAnally]

Welcome to the apparent nature of learning important Ruby libs.

Take a look around for some solid docs on Rails. You probably won't
find anything outside of the RDocs, which aren't sufficient in a lot
of cases. Though these kinds of docs are being worked on for Rails, I
think that's just the nature of the beast for other libs until someone
takes it upon themselves to create something.

I didn't realize RubyGems lacked something like that; it may be worth
creating at least a quick reference...

--Jeremy

So it does. I'll read through that, but I maintain that Rubygems
should not rely on a 3rd party must-buy book to document what ought to
be described on their website.

--
http://www.jeremymcanally.com/

My books:
Ruby in Practice
http://www.manning.com/mcanally/

My free Ruby e-book
http://www.humblelittlerubybook.com/

My blogs:
http://www.mrneighborly.com/
http://www.rubyinpractice.com/

 

[Marc Heiler]

So it does. I'll read through that, but I maintain that Rubygems

should not rely on a 3rd party must-buy book to document what ought to
be described on their website.

No, you are 100% right on this. And I state this while saying that
Pickaxe2 was one of the best computer-related books I ever bought and
read.

This is why I appreciate noobkit, because it provides good online
documentation which is freely accessible.

 

[thefed]

So it does. I'll read through that, but I maintain that Rubygems
should not rely on a 3rd party must-buy book to document what ought to
be described on their website.

That section is pretty good, but I found that it is easiest with hoe
(or echoe, haven't does that one yet). I chose to use hoe for my two
gems because I found a really nice example of how to do it

Here it is:
http://www.nimblecode.com/files/hoetalk.pdf

Have fun!

-Ari Brown

 

[Jaime Iniesta]

Note: parts of this message were removed by the gateway to make it a legal Usenet post.

http://www.nimblecode.com/files/hoetalk.pdf

Hi! I'm also trying to make my first Ruby gem. I've read that Hoe PDF, but
what about the newgem gem?

http://newgem.rubyforge.org/

 

[Bil Kleb]

Hi! I'm also trying to make my first Ruby gem. I've read that Hoe PDF, but
what about the newgem gem?

From my earlier post:

"The next time, I tried Dr. Nic's newgem, but it was overwhelming."

The amount of files it produced was more than my little
brain could handle.

Regards,

 

[Eric Hodel]

Welcome to the apparent nature of learning important Ruby libs.

Take a look around for some solid docs on Rails. You probably won't
find anything outside of the RDocs, which aren't sufficient in a lot
of cases. Though these kinds of docs are being worked on for Rails, I
think that's just the nature of the beast for other libs until someone
takes it upon themselves to create something.

I didn't realize RubyGems lacked something like that; it may be worth
creating at least a quick reference...

I could easily throw a quickref under `gem help` somewhere.