Creating a rubygem - a story and help request

ruby-talk
1

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.

2

Phrogz wrote:

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,

···

--
Bil Kleb
http://fun3d.larc.nasa.gov

3

Gavin Kistner wrote:

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.

···

--
Posted via http://www.ruby-forum.com/\.

4

  $ 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!

···

On Nov 25, 11:26 am, Bil Kleb <Bil.K...@NASA.gov> wrote:

5

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.

···

On Nov 25, 10:01 pm, 7stud -- <bbxx789_0...@yahoo.com> wrote:

Gavin Kistner wrote:
> 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.

6

Welcome to the apparent nature of learning important Ruby libs. :slight_smile:

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

···

On Nov 26, 2007 9:30 AM, Phrogz <phrogz@mac.com> wrote:

On Nov 25, 10:01 pm, 7stud -- <bbxx789_0...@yahoo.com> wrote:
> Gavin Kistner wrote:
> > 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.

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

My free Ruby e-book

My blogs:

http://www.rubyinpractice.com/

7

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.

···

--
Posted via http://www.ruby-forum.com/\.

8

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 :slight_smile:

Here it is:

Have fun!

-Ari Brown

···

On Nov 26, 2007, at 9:30 AM, Phrogz wrote:

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.

9

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/

···

2007/11/26, thefed <fedzor@gmail.com>:

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

--
Jaime Iniesta
http://jaimeiniesta.com - http://railes.net

10

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

···

On Nov 26, 2007, at 07:53 AM, Jeremy McAnally wrote:

On Nov 26, 2007 9:30 AM, Phrogz <phrogz@mac.com> wrote:

On Nov 25, 10:01 pm, 7stud -- <bbxx789_0...@yahoo.com> wrote:

Gavin Kistner wrote:

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.

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.

Welcome to the apparent nature of learning important Ruby libs. :slight_smile:

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

11

Jaime Iniesta wrote:

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

  "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,

···

From my earlier post:
--
Bil Kleb
http://fun3d.larc.nasa.gov