RubyGems and You
Josh Nichols technicalpickles.com

Overview
• How ‘require’ works
• Where rubygems fits in
• Creating your own rubygem from scratch
• Creating your own rubygem using jeweler
Josh Nichols technicalpickles.com

Overview
• How ‘require’ works
• Where rubygems fits in
• Creating your own rubygem from scratch
• Creating your own rubygem using jeweler
Josh Nichols technicalpickles.com

require
executes the contents of a file
Josh Nichols technicalpickles.com

# foo.rb
puts \"zomg, so awesome\"
# bar.rb
require 'foo.rb'
$ ruby bar.rb
zomg, so awesome
Josh Nichols technicalpickles.com

require ‘/usr/lib/awesome.rb’
absolute path
Josh Nichols technicalpickles.com

require ‘subdir/foo.rb’
relative path
Josh Nichols technicalpickles.com

require ‘subdir/foo’
can omit the .rb
Josh Nichols technicalpickles.com

$LOAD_PATH
list of directories to look for required files
Josh Nichols technicalpickles.com

require ‘net/http’
$LOAD_PATH includes your ruby install....
this actually lives under a path like:
/usr/local/lib/ruby/1.8/
Josh Nichols technicalpickles.com

require
only will execute a particular path once
Josh Nichols technicalpickles.com

# foo.rb
puts \"zomg, so awesome\"
# bar.rb
require 'foo'
require 'foo'
require './foo'
$ ruby bar.rb
zomg, so awesome
zomg, so awesome
Josh Nichols technicalpickles.com

Dealing with diversity...
• Different environments (mac vs. win. vs. linux)
• People install stuff to random places
• Different versions of libraries
• What do we do?
Josh Nichols technicalpickles.com

MASS HYSTERIA!
Josh Nichols technicalpickles.com

Overview
• How ‘require’ works
• Where rubygems fits in
• Creating your own rubygem from scratch
• Creating your own rubygem using jeweler
Josh Nichols technicalpickles.com

Enter RubyGems
• Handles downloading and installing library
• Manages $LOAD_PATH
• Allows a developer to package & distribute their library
Josh Nichols technicalpickles.com

Installing
• gem install burninator
Josh Nichols technicalpickles.com

Using gems
require 'rubygems'
require 'burninator'
Josh Nichols technicalpickles.com

Using gems in under Rails
# config/environment.rb, or anywhere really
require 'burninator'
Josh Nichols technicalpickles.com

Using gems in under Rails
# config/environment.rb
config.gem 'burninator'
Josh Nichols technicalpickles.com

Using gems in under Rails
# create vendor/gems...
# then 'gem unpack' gems there
# config/environment.rb
Rails::Initializer.run do |config|
config.load_paths += Dir[\"#{RAILS_ROOT}/vendor/gems/**\"].map do |dir|
File.directory?(lib = \"#{dir}/lib\") ? lib : dir
end
end
Josh Nichols technicalpickles.com

Where do gems live?
Josh Nichols technicalpickles.com

• RubyGems already knows about it by default
• Has been the defacto standard for hosting
Josh Nichols technicalpickles.com

• But you need to apply for projects...
• And you need extra tools to publish gems...
Josh Nichols technicalpickles.com

• The new hotness
• Just create a repository and turn on RubyGem support
• Create a Gem::Specification, and push it
Josh Nichols technicalpickles.com

Overview
• How ‘require’ works
• Where rubygems fits in
• Creating your own rubygem from scratch
• Creating your own rubygem using jeweler
Josh Nichols technicalpickles.com

Tools of the trade
• Rake for automation
• Testing framework of choice (we’ll assume test/unit)
• RubyGems
Josh Nichols technicalpickles.com

Directory Layout
|~bin/
| `-cylon_detector
|~lib/
| `-cylon_detector.rb
|~test/
| |-test_cylon_detector.rb
| `-test_helper.rb
|-LICENSE
|-Rakefile
`-README.rdoc
Josh Nichols technicalpickles.com

Rakefile basics
require 'rubygems'
require 'rake'
Josh Nichols technicalpickles.com

Gem::Specification
• Metadata about your gem
• name, files, binaries, homepage, etc, etc
Josh Nichols technicalpickles.com

Rakefile gemspec
spec = Gem::Specification.new do |s|
s.name = 'cylon-detector'
s.version = '0.8.1'
s.authors = ['Josh Nichols']
s.date = '2009-02-03'
s.email = 'josh@technicalpickles.com'
s.files = FileList['{bin,lib}/**']
s.executables = 'cylon_detector'
s.has_rdoc = true
s.summary = 'Detect cylons with ease'
end
Josh Nichols technicalpickles.com

Rakefile gemspec
task :gemspec do
File.open('cylon-detector.gemspec', 'w') do |file|
file.write spec.to_ruby
end
end
Josh Nichols technicalpickles.com

Rakefile package
require 'rake/gempackagetask'
Rake::GemPackageTask.new(spec) do |pkg|
pkg.need_zip = false
pkg.need_tar = false
end
Josh Nichols technicalpickles.com

Rakefile rdoc
require 'rake/rdoctask'
Rake::RDocTask.new do |rdoc|
rdoc.rdoc_dir = 'rdoc'
rdoc.title = 'cylon-detector'
rdoc.options << '--line-numbers' << '--inline-source'
rdoc.rdoc_files.include('README.rdoc')
rdoc.rdoc_files.include('lib/**/*.rb')
end
Josh Nichols technicalpickles.com

Rakefile test
require 'rake/testtask'
Rake::TestTask.new(:test) do |t|
t.test_files = 'test/**/test_*.rb'
t.verbose = false
end
Josh Nichols technicalpickles.com

Rakefile rcov
begin
require 'rcov/rcovtask'
Rcov::RcovTask.new do |t|
t.test_files = 'test/**/test_*.rb'
t.verbose = true
end
rescue LoadError
task :rcov do
abort \"RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov\"
end
end
Josh Nichols technicalpickles.com

Rakefile default
task :default => :test
Josh Nichols technicalpickles.com

bin/cylon_detector
#!/usr/bin/env ruby
$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
require 'cylon_detector'
# detection code here
Josh Nichols technicalpickles.com

lib/cylon_detector.rb
• The entry point into your library
• Require all dependencies (internal and external)
• Design decisions
• generally want to namespace your project
• class or module?
• Do not require rubygems (unless you are interacting
directly with it)
Josh Nichols technicalpickles.com

test/test_helper.rb
• Central location to setup testing environment
require 'rubygems'
require 'test/unit'
$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
$LOAD_PATH.unshift(File.dirname(__FILE__))
require 'cylon_detector'
class Test::Unit::TestCase
end
Josh Nichols technicalpickles.com

test/test_cylon_detector.rb
require File.dirname(__FILE__) + '/test_helper'
class CylonDetectorTest < Test::Unit::TestCase
# tests go here
end
Josh Nichols technicalpickles.com

Workflow
• Hack and commit your code
• ‘rake gemspec’ and commit your gemspec
• push to GitHub
• wait for the gem to build
• rejoice and have some Scotch
Josh Nichols technicalpickles.com

Overview
• How ‘require’ works
• Where rubygems fits in
• Creating your own rubygem from scratch
• Creating your own rubygem using jeweler
Josh Nichols technicalpickles.com

Jeweler
• Handles the grunt work
• Generator
• Skeleton project setup for your test framework of choice
• Starts a git repo setup for GitHub
• Creates the repo on GitHub and enables RubyGem for it
• Rake tasks
• Automate version bumping
• Releasing to GitHub, including tagging the release
Josh Nichols technicalpickles.com

Generator
• Choose between testing frameworks
• Test::Unit
• Shoulda
• RSpec
• Bacon
• Also includes cucumber stories enabled for
Josh Nichols technicalpickles.com

Versioning
• Tracks current version in VERSION.yml
• Rake tasks for bumping the version
• version:bump:patch, version:bump:minor,
version:bump:major
Josh Nichols technicalpickles.com

0.8.5
patch version
API backward-compatible
bug fixes
minor enhancements
Josh Nichols technicalpickles.com

0.8.5
minor version
mostly API backwards compatible
more significant enhancements
Josh Nichols technicalpickles.com

0.8.5
major version
break API as much you want
usually signifies an overhaul
Josh Nichols technicalpickles.com

Releasing
• Updates the gemspec based on the version
• Pushes to GitHub
• Tags the release with the version number
Josh Nichols technicalpickles.com