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

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.



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.

$  cd ~/github/labs
$  bundle gem quickbooks-ruby-base && cd $_



5. Modify the lib/ directory structure.





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.
6. Next, edit the quickbooks-ruby-base.gemspec file to look like this:
Gemspec commentary is located at the 8:47 mark in the screencast.



7. Open a new console window and run git ls-files command.





The git ls-files remarks are located at the 11:40 mark.
8. 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.



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

RSpec::Core::RakeTask.new

task :default => :spec
task :test => :spec

• Create the main spec spec/quickbooks_ruby_base_spec.rb with the following basic test.



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



• First, I add the lib/quickbooks-ruby-base.rb file.



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.



11. Let's switch gears and add these new files to git repo so our git ls-files is still in order.

  $ git add spec/ lib/
  $ git ls-files
  # Verify output

12. Now, re-run the spec.



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.



• Edit the spec/quickbooks_ruby_base_spec.rb file to require the spec_helper.rb.



13. Re-run the spec.



14. To add color to the spec edit spec/spec_helper.rb like so.

Good place to stop for Part 1

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

https://netdna.bootstrapcdn.com/font-awesome/3.2.1/css/font-awesome