Go back to the main page

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

 

 


Code from screencast and tutorial is available on Github.

Part 4 of the Gem creation tutorial that follows the conception of a real Gem.

In the last episode, Part 3, I finished wiring up the oauth_client and create_service_for methods. In this final installment, I will complete and publish the Gem, quickbooks-ruby-base.

  1. Up until this point I haven't run all the specs just individual ones. Before I move on I run the entire test suite with a bundle exec rake command.
    2. All 6 specs are green.
    I am now going to test the Gem in a real-world environment by including it into a QuickBooks/Rails project.
  2. In another tmux window I switch to a sample QuickBooks/Rails app, minimulcasts.
    3.   $ cd ~/www/labs/minimulcasts
  3. I add quickbooks-ruby-base to the Gemfile, pointing it to the local path.
    4. The path should be an absolute path.
  4. I run bundle install.
    5.   $ bundle install
  5. I edit config/initializers/quickbooks.rb to add the Gem's persistent configuration settings.
    6. I don't need to configure the oauth_consumer as the Gem's default is $qb_oauth_consumer for that setting.
  6. After saving config/initializers/quickbooks.rb I enter the rails console
    7. I hit an error undefined method 'service' running through some sample commands.
  7. This was because I forgot to expose 'service'. I go back to the Gem code (lib/quickbooks/base.rb) and add it.
    8. Saving the file I go back to the rails console.
  8. Within the existing rails console I have to reload the Gem changes I made to base.rb. To do that without stopping and restarting the rails console I do the following:
    9. I use the vim :!echo %:p command to get the full path of the file I changed.
    I copy the output in tmux.
    Back in the current rails console, I load the full path to base.rb.
  9. I get another error but at least the 'service' method is working.
    10. The new error is an: IntuitRequestException.

    Hey Minimul, you forgot to add a test for the attr_reader :service code you added!

    Minimul says —

    No, I already tested it in the console. The attr_reader is Ruby core code and I don't need to test it formally. The console test gives me enough confidence to move on. See Part 3 for more on my test philosophy.

    I receive this error at the 8:40 mark in the screencast.
  10. Upon further investigation, the Intuit App. API key and secret are not getting set.
    11. Hmm, perhaps the configuration code is not working?
  11. The problem is not within the Quickbooks::Base configuration code but the bash shell env values are not available in the tmux window that I am running rails console.
    12. These two constants are the ones not being populated.
    The fix is to run source ~/.profile, which will inject my environmental variables from ~/.profile into my current bash shell. Restart the rails console and all is well.
  12. With that is it time to work on the README.

    13. Hey Minimul, where is the inline documentation for RDoc or YARD support?

    Minimul says —

    I normally don't find RDoc-like docs useful and consequently don't read them much. Perhaps, if this Gem becomes widely used would I go back and add inline documentation/comments but for now I don't want yet another "weight" preventing me from releasing the Gem. A good README is essential so I am going to focus my efforts there.

    The README section starts roughly at the 11:55 mark in the screencast.
  13. The bundle gem command gives me a boilerplate README to get going.
  14. To aid me in writing a great README I leverage the fantastic Ruby Gem, github-markdown-preview
    15. I run github-markdown-preview README.md and then copy the file:// location returned.
    Next, I paste the file:// url into a new browser window and Whalla! A Github-flavored preview.

    Do I have to restart github-markdown-preview each time I make a change?

    No, just refresh the file:// url and the README modifications will display.

    Using github-markdown-preview section starts at the 14:01 mark in the screencast.
  15. After completing the README I am ready to push to Github.
    16. First I make a new repo.
    I fill in the new repo screen but do not add a README, .gitignore, or license as those are already created by the bundle gem command in Part 1.
    After doing git status I git add(aliased as ga in the figure) files that need to constitute the Gem.
    Make the initial commit.
    To finalize, I do a git remote and git push commands.
  16. The final step is to publish to Rubygems.org
    17. Gem publishing starts at the 21:25 mark in the screencast.
  17. I sign in.
    18. ...and follow the directions under the "Share" section.
    Published!
  18. I search over at Rubygems to verify.
    19. Live at Rubygems.org!

That concludes the "Create a Ruby Gem. Real World, play by play." series.

Wow, that four-part tutorial clocked in at a little over 1.5 hours of video content (~95 minutes). I sincerely hope it aids and encourages you to contribute and distribute your knowledge through creating a Ruby Gem. Here are the other installments:

  • Pushed on 05/08/2014 by Christian