Writing a Ruby Gem for beginners

How to Write a Gem for Beginners Ken C oar

Disclaimer● Dont be confused by the session title; this isnt – How to write a gem for beginners● Its – How to write a gem for beginners● Also, Ken (thats me) doesnt profess to be an expert at any of this; hes just sharing experiences of what worked

Why?● Youve seen all the Ruby gems available, and heard a lot about them. Where do they come from? How do you create one? And why would you want to?● There is no One True Way to create a gem, and different people will give you different recommendations.● This session describes one of the many paths available from why? to ta-daah! It worked for me; it might work for you too.

Pick a Licence● Why? Well, because Ruby is an interpreter, and offering up a gem to the chaos of the Internet is essentially opening the source code to the Universe● Do you care how your code may be used? To save lives? To crack banks? To guide missiles? To run gigantic financial institutions? To run schools? Think about it.● If you really dont care at all, maybe putting it in the public domain is the answer.

Source Control● Youre gonna make mistakes, and want to back away from them – possibly hurriedly● You might want to have co-developers● Git is currently very popular with the Ruby crowd; after an initial bad reaction (because of a basic misunderstanding I had about it), Ive come to prefer it myself● There are also Subversion, CVS, Arch, BitKeeper, and who-knows-what other options● Youre going to want one, think about it up front

Disorder of Battle● These are not necessarily in order: – Set up source control – Set up the directory tree – Write tests – Learn Rake (if you havent yet) – Document, document, document – Build – Upload

Our victim: BitString● Im going to use one of my own gems as an example, pretending to create it anew.

Creating the layout: newgem● Ive got a lot of projects up in the air; as a consequence, I like to prefix the directories for my gems with rubygem-● That doesnt play well with newgem, though, so well work around it later● Here we go: – newgem bitstring cp erehwon/LICENCE.txt bitstring/

What newgem did History.txt lib/ LICENCE.txt Manifest.txt PostInstall.txt Rakefile README.rdoc script/ test/

Set up source controlmv bitstring rubygem-bitstringcd rubygem-bitstringgit initgit add *echo *~ >>.gitignoregit add .gitignoregit commit -m Initial commit

Write code!● Nows the time to start actually writing the code.● Or, if its already written, copying it into the gem directory tree.● Code goes under the lib/ subdirectory● Ive already got mine, so I just copy it in

The lib/ tree$ tree liblib├── bitstring│ └── operators.rb└── bitstring.rb1 directory, 2 files

Now youve got your code. Does it work?● Time to write tests. newgem started us off: $ tree test test ├── test_bitstring.rb └── test_helper.rb $ cat test/test_bitstring.rb require File.dirname(__FILE__) + /test_helper.rb class TestRubygemBitstring < Test::Unit::TestCase def setup end def test_truth assert true end end

Documentation (rdoc)● Okey, so your code works. Youve tested it nigh unto death, and sent it off to the showers to recover.● But wait! Theres more! While its in the shower, you need to bring in a tattoo artist to..● Okey, that analogy isnt going anywhere useful. Try this: – Add the internal rdoc documentation● Build the docs with rake docs and look at them (on your local filesystem) in your browser

The spec file● The .gemspec file is what tells the gem build everything it needs to know● Gemspecs can be complicated; fortunately, theres a shortcut to get you started: – rake gemspec● After that, look at the foo.gemspec file and read up on gemspecs to see what changes you want/need to make

Building your gem● Once your code is written, your tests pass, your documentation is written (and verified), and your gemspec file has been created, you can actually build your gem! $ gem build bitstring.gemspec Successfully built RubyGem Name: bitstring Version: 1.0.0 File: bitstring-1.0.0.gem● The name comes from the version and other details in the gemspec file

Uploading● Very simple! – gem push bitstring-1.0.0.gem● Well, you need to have an account on the system first. Get one at – http://rubygems.org/sign_up

Monitor on RubyGems● Once your gem has been uploaded, you can see statistics about its usage at – https://rubygems.org/gems/yourgem

Notes and hints● Look at other gems● So far, this has all been done in your local environment. Once you feel confident, consider creating a project for your gem at RubyForge and uploading your code there. – I highly recommend it!

Wrapup● Questions? Sure. Answers? Maybe. :-)

Writing a Ruby Gem for beginners

by ConFoo on Mar 28, 2011

Accessibility

Upload Details

Usage Rights

Statistics

Writing a Ruby Gem for beginners Presentation Transcript