Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Becoming a Ruby Gemcutter

Becoming a Ruby Gemcutter

Welcome to the world of Ruby: where the gems are deep, rough, and rarely documented! No need to fear though, in this presentation you'll learn what a RubyGem is, how they're used in Rails and Ruby applications, and of course, how to make your own. You'll see just how easy it is to share your code with others in the Ruby universe, and why creating packages is a joy instead of a burden thanks to the tools and ecosystem of RubyGems.

Given at CodeMash 2012. http://codemash.org

Nick Quaranto

January 12, 2012
Tweet

More Decks by Nick Quaranto

Other Decks in Programming

Transcript

  1. BECOMING
    A
    RUBY
    GEMCUTTER

    View Slide

  2. i’m @qrush
    this is @qrush’s dog

    View Slide

  3. @
    i live here

    View Slide

  4. i work at 37signals

    View Slide

  5. OMG FIRST
    CODEMASH!!!

    View Slide

  6. RUBY
    i mostly write

    View Slide

  7. RUBY
    RAILS
    i mostly write
    with

    View Slide

  8. RUBY
    GEMS
    i mostly write
    inside of

    View Slide

  9. RAILS
    GEMS
    in fact,
    is made of

    View Slide

  10. GEMS
    EASY
    and
    are

    View Slide

  11. EASY!

    View Slide

  12. YOU
    MUST
    BE
    THIS
    CODER
    TO
    RIDE
    THE
    TALK
    KNOW A BIT
    OF RUBY
    LOVE YOUR
    CODE
    WILLING TO
    LEARN!

    View Slide

  13. COVERING:
    WHAT?
    HOW?
    WHY?

    View Slide

  14. GEMS
    GEMS
    GEMS
    GEMS
    GEMS

    View Slide

  15. GEMS contain a
    packaged Ruby
    library or
    application.

    View Slide

  16. RUBYGEMS
    helps you
    download, install,
    and manipulate
    gems.

    View Slide

  17. RUBYGEMS
    gives you the gem
    command

    View Slide

  18. RUBYGEMS.ORG
    is a community
    repository of gems
    available for use.

    View Slide

  19. RUBYGEMS
    CLIENT
    RUBYGEMS.ORG

    View Slide

  20. RUBYGEMS
    CLIENT
    RUBYGEMS.ORG

    View Slide

  21. RUBYGEMS
    CLIENT
    RUBYGEMS.ORG
    .gem
    .gem

    View Slide

  22. http://rubygems.org/pages/download

    View Slide

  23. GEM
    WHAT’S IN A

    View Slide

  24. Docs Code Gemspec

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  29. .GEM RAILS
    ?

    View Slide

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

    View Slide

  31. RubyGems manages
    your $LOAD_PATH

    View Slide

  32. % 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",
    "."]

    View Slide

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

    View Slide

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

    View Slide

  35. RubyGems overrides
    Kernel#require
    RubyGems puts bin/
    and lib/ on your
    $LOAD_PATH

    View Slide

  36. RubyGems manages
    your external
    Ruby code.

    View Slide

  37. The Gemspec holds
    metadata & info
    about the gem

    View Slide

  38. % cat freewill.gemspec
    Gem::Specification.new do |s|
    s.name = 'freewill'
    s.version = '1.0.0'
    s.date = '2012-01-03'
    s.summary = "Freewill!"
    s.description = "I will choose Freewill!"
    s.authors = ["Nick Quaranto"]
    s.email = '[email protected]'
    s.homepage = 'http://example.com'
    s.files = ["lib/freewill.rb"]
    end

    View Slide

  39. A .gem is just a
    tarball of tarballs

    View Slide

  40. % gem fetch rake
    Downloaded rake-0.8.7
    % tar zxvf rake-0.8.7.gem
    x data.tar.gz
    x metadata.gz

    View Slide

  41. A GEM IS A TARBALL
    WITHIN A TARBALL

    View Slide

  42. WHY CAN’T I USE
    MY LINUX PACKAGE
    MANAGER THEN

    View Slide

  43. View Slide

  44. LOL, WHAT’S A TARBALL

    View Slide

  45. WHY?
    WHY?
    WHY?
    ?
    WH
    W
    HY?

    View Slide

  46. Why did you make a RubyGem?

    View Slide

  47. REUSE

    View Slide

  48. INVENTION

    View Slide

  49. AUTOMATION

    View Slide

  50. IMPROVEMENT

    View Slide

  51. FIX HUGE
    PROBLEMS

    View Slide

  52. GOOD LUCK
    WITH THAT

    View Slide

  53. NO
    REALLY
    WHY
    SHOULD
    I
    BOTHER
    WITH
    THIS,
    I’M
    BUSY!
    REUSE YOUR
    CODE
    EASY TO
    INSTALL
    EASY TO
    SHARE

    View Slide

  54. GEM!
    MAKE
    YOUR OWN!

    View Slide

  55. FIRST GEM
    EXECUTABLE
    TESTING
    DOCS

    View Slide

  56. FIRST GEM
    EXECUTABLE
    TESTING
    DOCS

    View Slide

  57. % tree
    .
    !"" hola.gemspec
    #"" lib
    #"" hola.rb

    View Slide

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

    View Slide

  59. require ‘hola’
    % tree
    .
    !"" hola.gemspec
    #"" lib
    #"" hola.rb

    View Slide

  60. % cat hola.gemspec
    Gem::Specification.new do |s|
    s.name = 'hola'
    s.version = '0.0.0'
    s.date = '2011-01-03'
    s.summary = "Hola!"
    s.description = "A simple hello world gem"
    s.authors = ["Nick Quaranto"]
    s.email = '[email protected]'
    s.files = ["lib/hola.rb"]
    s.homepage =
    'http://rubygems.org/gems/hola'
    end

    View Slide

  61. build
    install
    push

    View Slide

  62. build
    install
    push
    LOCAL
    REMOTE

    View Slide

  63. % 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

    View Slide

  64. SHIP IT!

    View Slide

  65. OOPS.
    bad push?

    View Slide

  66. Try your gem out
    before pushing!

    View Slide

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

    View Slide

  68. At least run your
    tests first!
    ...You wrote
    tests, right?

    View Slide

  69. SHIP IT!

    View Slide

  70. % 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: [email protected]
    Password:
    Signed in.
    Pushing gem to RubyGems.org...
    Successfully registered gem: hola (0.0.0)

    View Slide

  71. REMOTE
    LOCAL install
    build
    push
    list -r install

    View Slide

  72. % gem list -r hola
    *** REMOTE GEMS ***
    hola (0.0.0)
    % gem install hola
    Successfully installed hola-0.0.0
    1 gem installed

    View Slide

  73. FIRST GEM
    EXECUTABLE
    TESTING
    DOCS

    View Slide

  74. gems are awesome
    command line
    tools

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  78. % cat bin/hola
    #!/usr/bin/env ruby
    require 'hola'
    puts Hola.hi(ARGV[0])
    (shə-băng')

    View Slide

  79. % cat bin/hola
    #!/usr/bin/env ruby
    require 'hola'
    puts Hola.hi(ARGV[0])
    “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')

    View Slide

  80. % cat bin/hola
    #!/usr/bin/env ruby
    require 'hola'
    puts Hola.hi(ARGV[0])
    (shə-băng')
    “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

    View Slide

  81. % ruby -Ilib ./bin/hola
    Hello world!
    % ruby -Ilib ./bin/hola CodeMash
    Hello CodeMash!

    View Slide

  82. % ruby -Ilib ./bin/hola
    Hello world!
    % ruby -Ilib ./bin/hola CodeMash
    Hello CodeMash!
    $LOAD_PATH.unshift(“lib”)

    View Slide

  83. % hola
    Hello world!
    % hola CodeMash
    Hello CodeMash!

    View Slide

  84. % head -4 hola.gemspec
    Gem::Specification.new do |s|
    s.name = 'hola'
    s.version = '0.0.1'
    s.executables << 'hola'

    View Slide

  85. FIRST GEM
    EXECUTABLE
    TESTING
    DOCS

    View Slide

  86. outsource your
    automation
    and
    framework

    View Slide

  87. automation framework

    View Slide

  88. automation framework
    rake
    thor

    View Slide

  89. automation framework
    rake
    thor
    Test::Unit rspec
    bacon context
    matchy shoulda
    riot testy shindo
    zebra lemon dfect
    cucumber steak

    View Slide

  90. Test your gem.
    Use whatever.
    Please test it.

    View Slide

  91. You will be tested:
    http://test.rubygems.org

    View Slide

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

    View Slide

  93. % 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

    View Slide

  94. % 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

    View Slide

  95. FIRST GEM
    EXECUTABLE
    TESTING
    DOCS

    View Slide

  96. Meh.

    View Slide

  97. push gem
    webhook
    tweet on
    @rubygems

    View Slide

  98. push gem
    webhook
    tweet on
    @rubygems
    ON
    EVERY
    PUSH

    View Slide

  99. push gem
    webhook
    tweet on
    @rubygems
    ON
    EVERY
    PUSH
    ~200+
    TIMES
    DAILY

    View Slide

  100. Say hi, your
    gem will!

    View Slide

  101. guides inline

    View Slide

  102. guides inline
    nokogiri
    yard

    View Slide

  103. guides inline
    nokogiri
    yard
    rails
    datamapper

    View Slide

  104. # 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

    View Slide

  105. Learn how to
    document your
    code:
    http://yardoc.org

    View Slide

  106. 10TIPS
    AWESOME
    FOR MAKING
    YOUR GEM

    View Slide

  107. Write a
    README.
    1.

    View Slide

  108. WHAT
    SHOULD
    GO
    IN
    A
    README
    WHAT IT IS
    INSTALL
    INSTRUCTIONS
    HOW TO
    USE IT

    View Slide

  109. Use a
    LICENSE
    2.

    View Slide

  110. Code with no LICENSE
    is COPYRIGHTED.

    View Slide

  111. Pick a license BEFORE
    pushing your gem.

    View Slide

  112. Name your
    gem
    properly.
    3.

    View Slide

  113. DO NOT CALL IT:
    [rR].*
    rials
    cheezburger
    kitty
    dicks

    View Slide

  114. Have a memorable
    name, not a stupid one.

    View Slide

  115. Have a
    sane
    versioning
    scheme.
    4.

    View Slide

  116. http://www.flickr.com/photos/ioerror/3014911710/lightbox/

    View Slide

  117. 3
    3.1
    3.141
    3.1415
    3.14159
    3.141592
    3.14159256

    View Slide

  118. http://semver.org
    Semantic Versioning

    View Slide

  119. 1.2.3
    MAJOR.MINOR.PATCH

    View Slide

  120. 0.0.X
    PATCH
    implementation details
    small bug fixes

    View Slide

  121. 0.X.0
    MINOR
    backwards compatible
    API changes

    View Slide

  122. X.0.0
    MAJOR
    backwards incompatible
    API changes

    View Slide

  123. Have one
    top-level
    file
    5.

    View Slide

  124. .
    #"" lib
    !"" foo.rb
    #"" set.rb

    View Slide

  125. .
    #"" lib
    !"" foo.rb
    #"" set.rb
    require ‘set’

    View Slide

  126. .
    #"" lib
    !"" foo.rb
    #"" set.rb
    require ‘set’

    View Slide

  127. .
    #"" lib
    !"" foo
    % #"" set.rb
    #"" foo.rb
    require ‘foo/set’

    View Slide

  128. Don’t mess
    with
    $LOAD_PATH
    6.

    View Slide

  129. .
    #"" lib
    !"" hola
    % #"" translator.rb
    #"" hola.rb

    View Slide

  130. .
    #"" lib
    !"" hola
    % #"" translator.rb
    #"" hola.rb
    BAD:
    require File.join(File.dirname(
    __FILE__), "hola", "translator")

    View Slide

  131. .
    #"" lib
    !"" hola
    % #"" translator.rb
    #"" hola.rb
    WORSE:
    $LOAD_PATH.unshift "lib/hola"
    require "translator"

    View Slide

  132. .
    #"" lib
    !"" hola
    % #"" translator.rb
    #"" hola.rb
    GOOD:
    require "hola/translator"

    View Slide

  133. Specify
    dependencies
    7.

    View Slide

  134. http://www.slideshare.net/copiousfreetime/gemology

    View Slide

  135. runtime development

    View Slide

  136. runtime development
    what your
    gem needs
    to work

    View Slide

  137. runtime development
    what your
    gem needs
    to work
    what your
    tests need
    to work

    View Slide

  138. Gem::Specification.new do |s|
    s.name = "hola"
    s.version = "2.0.0"
    s.add_runtime_dependency(
    "daemons", [">= 1.1.0"])
    s.add_development_dependency(
    "rspec", ["= 2.2.0"])

    View Slide

  139. Be pessimistic
    (with dependencies)
    8.

    View Slide

  140. Gem::Specification.new do |s|
    s.name = "hola"
    s.version = "2.0.0"
    s.add_runtime_dependency(
    "thor", [">= 0.14.5"])
    s.add_development_dependency(
    "rspec", ["= 2.2.0"])
    Only this one works for me!
    EXACT

    View Slide

  141. Gem::Specification.new do |s|
    s.name = "hola"
    s.version = "2.0.0"
    s.add_runtime_dependency(
    "thor", [">= 0.14.5"])
    s.add_development_dependency(
    "rspec", ["= 2.2.0"])
    It will always work!
    OPTIMISTIC

    View Slide

  142. Avoid >=

    View Slide

  143. Gem::Specification.new do |s|
    s.name = "hola"
    s.version = "2.0.0"
    s.add_runtime_dependency(
    "thor", [">= 0.14.5", "< 1.0.0"])
    s.add_development_dependency(
    "rspec", ["= 2.2.0"])
    Lock to a range instead
    PESSIMISTIC

    View Slide

  144. Gem::Specification.new do |s|
    s.name = "hola"
    s.version = "2.0.0"
    s.add_runtime_dependency(
    "thor", ["~> 0.14"])
    s.add_development_dependency(
    "rspec", ["= 2.2.0"])
    Use the twiddle-wakka!
    PESSIMISTIC

    View Slide

  145. Cut
    prereleases
    9.

    View Slide

  146. % head -4 hola.gemspec
    Gem::Specification.new do |s|
    s.name = 'hola'
    s.version = '1.0.0.pre'

    View Slide

  147. % head -4 hola.gemspec
    Gem::Specification.new do |s|
    s.name = 'hola'
    s.version = '1.0.0.pre'
    ANY LETTER(S)

    View Slide

  148. % gem install hola --pre
    Fetching: hola-1.0.0.pre.gem (100%)
    Successfully installed hola-1.0.0.pre
    1 gem installed

    View Slide

  149. Build on
    Travis-CI
    10.

    View Slide

  150. No configuration,
    totally free CI.
    http://travis-ci.org

    View Slide

  151. View Slide

  152. GO PUSH A GEM
    TODAY

    View Slide

  153. GO PUSH A GEM
    TODAY
    @qrush Thanks!

    View Slide