Writing a Ruby Gem for beginners
Upcoming SlideShare
Loading in...5
×
 

Writing a Ruby Gem for beginners

on

  • 3,544 views

 

Statistics

Views

Total Views
3,544
Views on SlideShare
3,544
Embed Views
0

Actions

Likes
4
Downloads
8
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

Writing a Ruby Gem for beginners Writing a Ruby Gem for beginners Presentation Transcript

  • 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. :-)