Go back to the main page

Create a Ruby Gem. Real World, play by play. Part 1



Code from screencast and tutorial is available on Github.

Yet another Gem how to tutorial? No way, this one covers the making of a real Gem.

So you want to create a Ruby Gem but you desire a tutorial more advanced than extending the Ruby String object with a 5 line method? With this tutorial you can follow my steps that led to the conception of a real library, the quickbooks-ruby-base Gem.

  1. Why do you want to create a Gem?
    • You make a Gem because you want to reuse code. You'll notice a pattern of something you're doing that you'd like to take across projects. In my case, I do Quickbooks/Rails integration consulting so I was noticing a convention emerging where I was making a base class which would handle some of the dirty work when interacting with the "main" Ruby/QBO library, quickbooks-ruby.
    • Here is the rough formula of code that would I would like to reuse across integration projects.
  2. How do I name the Gem?
    • Starting point: The Gem name should be lowercase with the only special characters being hyphens and underscores.
    • I was calling this class, 'QBBase', therefore, I settled on the Gem name 'quickbooks-ruby-base'.
  3. Since I am extending an existing Gem, what namespace shall I use?
    • The quickbooks-ruby Gem simply uses the top-level namespace of 'Quickbooks'.
    • So, Quickbooks::Base would appear to be good design but let me check that there is no conflicts.
    • $ irb
      >> require 'quickbooks-ruby'
      => true
      >> Quickbooks::Base
      NameError: uninitialized constant Quickbooks::Base
              from (irb):2
              from /Users/christian/.rvm/rubies/ruby-1.9.3-p484/bin/irb:12:in `
    • Nice. That namespace is not taken.
  4. I am now ready to starting coding, so I start by leveraging Bundler's bundle gem command to generate a Gem scaffolding.
  5. $  cd ~/github/labs
    $  bundle gem quickbooks-ruby-base && cd $_
    I start this Gem in my experiments directory located @ ~/github/labs.
  6. Modify the lib/ directory structure.
  7. Before
    Bundler creates a directory structure off of the hyphens in the name passed into the bundle gem command. I don't need the Ruby directory because quickbooks-ruby only uses the Quickbooks namespace. The proper directory structure follows the namespacing, which again, is to Quickbooks::Base.
  8. Next, edit the quickbooks-ruby-base.gemspec file to look like this:
  9. Gemspec commentary is located at the 8:47 mark in the screencast.
    Stop at the spec.files section and let's make sure that the git ls-files is working as expected.
  10. Open a new console window and run git ls-files command.
  11. The output stills has the 'ruby' directory references, which I deleted.
    Get the ls-files command cleaned up to properly respresent the Gem's files correctly.
    The git ls-files remarks are located at the 11:40 mark.
  12. After getting the git ls-files command in order this is how the the final quickbooks-ruby-base.gemspec should look in the figure below. Lastly, run the bundle install command.
  13. Dependencies of rspec and quickbooks-ruby were added also.
  14. Setup Rspec.
    • Create a blank spec/spec_helper.rb.
    • $ mkdir ~/github/labs/quickbooks-ruby-base/spec
      $ touch ~/github/labs/quickbooks-ruby-base/spec/spec_helper.rb
    • Edit the Rakefile, setting a default task that runs the specs.
    • require "bundler/gem_tasks"
      require "rspec/core/rake_task"
      task :default => :spec
      task :test => :spec
    • Create the main spec spec/quickbooks_ruby_base_spec.rb with the following basic test.
    • This simply spec will at least make sure we have things wired up correctly.
  15. Run the spec.
    • In the figures you may notice the be command. That is an alias for bundle exec.
      Running specs begin at the 19:07 mark in the screencast.
      I get an error uninitialized Constant Quickbooks. I know I am going to get an error as I haven't even created the 'Base' class as of yet. Running the specs at this stage act as a guide.
    • First, I add the lib/quickbooks-ruby-base.rb file.
    • Use require_relative within the lib/ directory as this is the directory that is to be included in other projects and libraries.
      You will notice the name of file is exactly the same as the Gem. This is so we can do a require 'quickbooks-ruby-base' once the Gem is installed.
    • Next, add the lib/base/base.rb file.
    • I am just wiring up the basics to get past the spec error.
  16. Let's switch gears and add these new files to git repo so our git ls-files is still in order.
  17.   $ git add spec/ lib/
      $ git ls-files
      # Verify output
  18. Now, re-run the spec.
  19. I again get the error uninitialized Constant Quickbooks.
    The problem is in the spec itself. I have no references to the code in the lib/ directory.
    • Edit the spec/spec_helper.rb file to properly reference the core Gem code.
    • In this case using just require instead of require_relative is fine as specs are for internal development of the Gem.
    • Edit the spec/quickbooks_ruby_base_spec.rb file to require the spec_helper.rb.
    • Now, I may finally get this spec to pass.
  20. Re-run the spec.
  21. Yah! But where is the green?
  22. To add color to the spec edit spec/spec_helper.rb like so.
  23. Add and re-run the spec to now we have green.

Good place to stop for Part 1

Please note that the screencasts are already completed for the next 3 parts.

  • Pushed on 04/28/2014 by Christian