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      ...
Why?●   Youve seen all the Ruby gems available, and    heard a lot about them. Where do they come    from? How do you crea...
Pick a Licence●   Why? Well, because Ruby is an interpreter,    and offering up a gem to the chaos of the    Internet is e...
Source Control●   Youre gonna make mistakes, and want to back    away from them – possibly hurriedly●   You might want to ...
Disorder of Battle●   These are not necessarily in order:       –   Set up source control       –   Set up the directory t...
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 director...
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 .gitig...
Write code!●   Nows the time to start actually writing the code.●   Or, if its already written, copying it into the gem   ...
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...
Documentation (rdoc)●   Okey, so your code works. Youve tested it    nigh unto death, and sent it off to the showers    to...
The spec file●   The .gemspec file is what tells the gem build    everything it needs to know●   Gemspecs can be complicat...
Building your gem●   Once your code is written, your tests pass, your    documentation is written (and verified), and    y...
Uploading●   Very simple!       –   gem push bitstring-1.0.0.gem●   Well, you need to have an account on the    system fir...
Monitor on RubyGems●   Once your gem has been uploaded, you can    see statistics about its usage at       –   https://rub...
Notes and hints●   Look at other gems●   So far, this has all been done in your local    environment. Once you feel confid...
Wrapup●   Questions? Sure. Answers? Maybe. :-)
Upcoming SlideShare
Loading in...5
×

Writing a Ruby Gem for beginners

3,172

Published on

0 Comments
4 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
3,172
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
9
Comments
0
Likes
4
Embeds 0
No embeds

No notes for slide

Writing a Ruby Gem for beginners

  1. 1. How to Write a Gem for Beginners Ken C oar
  2. 2. 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
  3. 3. 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.
  4. 4. 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.
  5. 5. 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
  6. 6. 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
  7. 7. Our victim: BitString● Im going to use one of my own gems as an example, pretending to create it anew.
  8. 8. 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/
  9. 9. What newgem did History.txt lib/ LICENCE.txt Manifest.txt PostInstall.txt Rakefile README.rdoc script/ test/
  10. 10. Set up source controlmv bitstring rubygem-bitstringcd rubygem-bitstringgit initgit add *echo *~ >>.gitignoregit add .gitignoregit commit -m Initial commit
  11. 11. 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
  12. 12. The lib/ tree$ tree liblib├── bitstring│   └── operators.rb└── bitstring.rb1 directory, 2 files
  13. 13. 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
  14. 14. 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
  15. 15. 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
  16. 16. 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
  17. 17. 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
  18. 18. Monitor on RubyGems● Once your gem has been uploaded, you can see statistics about its usage at – https://rubygems.org/gems/yourgem
  19. 19. 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!
  20. 20. Wrapup● Questions? Sure. Answers? Maybe. :-)
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×