Cutting Your Own RubyGems

cutting your own RubyGems
R B Y
Nick Quaranto
@qrush nick@thoughtbot.com
Wednesday, May 25, 2011
first, a
P S A
Where have all of
the manuals gone?

http://history.nasa.gov/diagrams/gemini.html
http://history.nasa.gov/diagrams/gemini.html
http://archive.computerhistory.org/resources/text/Apple/Apple.AppleI.1976.102646518.pdf
http://ed-thelen.org/comp-hist/CRAY-1-HardRefMan/CRAY-1-HRM.html
http://guides.rubyonrails.org

http://progit.org

http://guides.sproutcore.org

We need
MORE
manuals!

MAKE
MANUALS
http://guides.rubygems.org

what is a gem?
G E M
Gems contain a
packaged Ruby
application or library.

RubyGems helps you
download, install, and
mani pulate gems.

rubygems.org
rubygems client

rubygems.org
rubygems client
gems

gems,
gemspecs,
indexes
from S3
rubygems.org
rubygems client
gems

.gem

Docs Code Gemspec

% tree freewill
freewill/
|-- bin/
| `-- freewill
|-- lib/
| `-- freewill.rb
|-- test/
| `-- test_freewill.rb
|-- README
|-- Rakefile
`-- freewill.gemspec

???
.gem Rails

Ruby looks on your
$LOAD_PATH when
you call Kernel#require

RubyGems manages
your $LOAD_PATH

% irb -rpp
>> pp $LOAD_PATH
[".../lib/ruby/site_ruby/1.8",
".../lib/ruby/site_ruby",
".../lib/ruby/vendor_ruby/1.8",
".../lib/ruby/vendor_ruby",
".../lib/ruby/1.8",
"."]

% irb -rpp
>> require 'rake'
LoadError: no such file to load --
rake
from (irb):2:in `require'
from (irb):2

>> require 'rubygems'
=> true
>> require 'rake'
=> true
>> pp $LOAD_PATH[0..1]
[".../gems/rake-0.8.7/bin",
".../gems/rake-0.8.7/lib"]

RubyGems overrides
Kernel#require
RubyGems puts bin/ and

lib/ on your $LOAD_PATH

Gemspec holds
metadata & info
about the gem

% cat freewill.gemspec
Gem::Specification.new do |s|
s.name = 'freewill'
s.version = '1.0.0'
s.date = '2010-04-27'
s.summary = "Freewill!"
s.description = "I will choose Freewill!"
s.authors = ["Nick Quaranto"]
s.email = 'nick@quaran.to'
s.homepage = 'http://example.com'
s.files = ["lib/freewill.rb"]
end

A gem is just
a tarball of
tarballs

% gem fetch rake
Downloaded rake-0.8.7
% tar zxvf rake-0.8.7.gem

x data.tar.gz
x metadata.gz

A GEM IS A TARBALL
WITHIN A TARBALL
WHY CAN’T I USE
MY LINUX PACKAGE
MANAGER THEN

LOL, WHAT’S A TARBALL

make your own gem
D Y I
share/modularize code
automate your process
releasing a gem is easy!

first gem

Your gem
needs a name

DO NOT CALL IT:
[rR].*
rials
cheezburger
kitty
dicks
no capitals, please
use underscores for spaces
use dashes for extensions

% tree
.
├── hola.gemspec
└── lib
└── hola.rb

% cat lib/hola.rb
class Hola
def self.hi(msg = "world")
puts "Hello #{msg}!"
end
end

require ‘hola’
% tree
.
├── hola.gemspec
└── lib
└── hola.rb
% cat hola.gemspec
s.name = 'hola'
s.version = '0.0.0'
s.date = '2010-04-28'
s.summary = "Hola!"
s.description = "A simple hello world gem"
s.authors = ["Nick Quaranto"]
s.email = 'nick@quaran.to'
s.files = ["lib/hola.rb"]
s.homepage =
'http://rubygems.org/gems/hola'
end

build
install
push
build
LOCAL
install
push
build
LOCAL
install
REMOTE
push
% gem build hola.gemspec
Successfully built RubyGem
Name: hola
Version: 0.0.0
File: hola-0.0.0.gem
% gem install ./hola-0.0.0.gem

Successfully installed hola-0.0.0
1 gem installed

try your gem out
before pushing!

% irb -rubygems
>> require 'hola'
=> true
>> Hola.hi
Hello world!

require 'ubygems.rb'
% irb -rubygems
>> require 'hola'
=> true
>> Hola.hi
Hello world!

% gem push hola-0.0.0.gem
Enter your RubyGems.org credentials.
Don't have an account yet?
Create one at http://rubygems.org/sign_up
Email: nick@quaran.to
Password:
Signed in.
Pushing gem to RubyGems.org...
Successfully registered gem: hola (0.0.0)

build
LOCAL
install
push
REMOTE
install list -r
% gem list -r hola
*** REMOTE GEMS ***
hola (0.0.0)
% gem install hola

Successfully installed hola-0.0.0
1 gem installed

first gem
executable

gems are like
awesome shell aliases

% curl -s http://jsonip.com/ | \
prettify_json.rb
{
"ip": "24.60.248.134"
}

% mkdir bin
% touch bin/hola
% chmod a+x bin/hola

% cat bin/hola
#!/usr/bin/env ruby
require 'hola'
puts Hola.hi(ARGV[0])

(shə-băng')
% cat bin/hola
#!/usr/bin/env ruby
require 'hola'

(shə-băng')
% cat bin/hola
#!/usr/bin/env ruby
require 'hola'
“Probably derived from “shell bang” under the influence of
American slang “the whole shebang” (everything, the works)”
http://www.retrologic.com/jargon/S/shebang.html
(shə-băng')
% cat bin/hola
#!/usr/bin/env ruby
require 'hola'
“Probably derived from “shell bang” under the influence of
American slang “the whole shebang” (everything, the works)”
http://www.retrologic.com/jargon/S/shebang.html
% ruby -Ilib ./bin/hola
Hello world!
% ruby -Ilib ./bin/hola Baltimore

Hello Baltimore!

$LOAD_PATH.unshift(“lib”)
% ruby -Ilib ./bin/hola

Hello world!
% ruby -Ilib ./bin/hola Baltimore

Hello Baltimore!

% hola
Hello world!
% hola Baltimore
Hello Baltimore!

% head -4 hola.gemspec
s.name = 'hola'
s.version = '0.0.1'
s.executables << 'hola'

first gem
executable
tests

automation framework

rake
thor
Test::Unit rspec
rake bacon context
matchy shoulda
riot testy shindo
thor zebra lemon dfect
cucumber steak
Test your gem.
Use whatever.
Please test it.

http://test.rubygems.org

% cat Rakefile
require 'rake/testtask'
Rake::TestTask.new do |t|
t.libs << 'test'
end
desc "Run tests"

task :default => :test

% cat test/test_hola.rb
require 'test/unit'
require 'hola'
class HolaTest < Test::Unit::TestCase

def test_default_hello
assert_equal "Hello world!",
Hola.hi
end
def test_custom_hello
assert_equal "Hello Boston!",
Hola.hi("Boston")
end
end
% rake test
(in /Users/qrush/Dev/ruby/hola)
Loaded suite
Started
..
Finished in 0.000736 seconds.
2 tests, 2 assertions, 0 failures,

0 errors, 0 skips
Test run options: --seed 15331

first gem
executable
tests
docs
Others will use your gem.
Write about it.

At least have a README!

http://twitter.com/rubygems
guides inline

guides inline
nokogiri
yard
guides inline
nokogiri rails
yard datamapper
# The main Hola driver
class Hola
# Say hi to the world!
#
# Example:
# >> Hola.hi("Buffalo")
# => Hello Buffalo!
#
# Arguments:
# message: (String)
def self.hi(message = "world")

puts "Hello #{message}!"
end
end

http://yardoc.org
patterns
P T N
more files

.
└── lib
├── hola
│ └── translator.rb
└── hola.rb

.
└── lib
├── hola
└── hola.rb
BAD:
require File.join(File.dirname(
__FILE__), "hola", "translator")

.
└── lib
├── hola
└── hola.rb
WORSE:
$LOAD_PATH.unshift "lib/hola"
require "translator"

.
└── lib
├── hola
└── hola.rb
GOOD:
require "hola/translator"

Keep only one
top-level file in lib/

.
└── lib
├── foo
│ └── cgi.rb
├── foo.rb
└── set.rb

.
└── lib
├── foo
├── foo.rb
└── set.rb
require ‘set’
.
└── lib
├── foo
├── foo.rb
└── set.rb
require ‘foo/cgi’
more files
semver

Have a sane
versioning scheme

http://www.flickr.com/photos/ioerror/3014911710/lightbox/
3
3.1
3.14
3.141
3.1415
3.14159
3.141592
3.1415926
http://semver.org

1.2.3
MAJOR.MINOR.PATCH

0.0.x
PATCH
implementation details
small bug fixes
0.x.0
MINOR
backwards compatible
API changes
x.0.0
MAJOR
backwards incompatible
API changes
more files
semver
dependencies

http://www.slideshare.net/copiousfreetime/gemology
Specify your
dependencies

runtime development

runtime development
what your
gem
needs to
work
runtime development
what your what your
gem tests
needs to need to
work work
s.name = "hola"
s.version = "2.0.0"
s.add_runtime_dependency(
"daemons", ["= 1.1.0"])
s.add_development_dependency(
"rspec", [">= 2.2.0"])

Avoid >=

s.name = "hola"
s.version = "2.0.0"
"daemons", ["= 1.1.0"])
"rspec", [">= 2.0.0"])
Exact
This one works for me!
s.name = "hola"
s.version = "2.0.0"
"daemons", ["= 1.1.0"])
"rspec", [">= 2.2.0"])
Optimistic
It will always work!
s.name = "hola"
s.version = "2.0.0"
"daemons", ["= 1.1.0"])
"rspec", [">= 2.2.0", "< 3.0.0"])
Pessimistic
This and future minor releases work
s.name = "hola"
s.version = "2.0.0"
"daemons", ["= 1.1.0"])
"rspec", ["~> 2.2"])
Pessimistic
Use the twiddle-wakka!
releasing a gem
is easy!

have a sane
versioning scheme

MAKE
MANUALS
Thanks for listening!
T H X
http://guides.rubygems.org
Big thanks to:

thoughtbot Nick Quaranto
Jeremy Hinegardner @qrush nick@thoughtbot.com

Cutting Your Own RubyGems

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Cutting Your Own RubyGems

Uploaded by

Copyright:

Available Formats

cutting your own RubyGems

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

RubyGems puts bin/ and

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

% tar zxvf rake-0.8.7.gem

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

% gem install ./hola-0.0.0.gem

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

*** REMOTE GEMS ***

% gem install hola

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

% ruby -Ilib ./bin/hola Baltimore

Wednesday, May 25, 2011

% ruby -Ilib ./bin/hola

% ruby -Ilib ./bin/hola Baltimore

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

Wednesday, May 25, 2011

* REMOTE GEMS *