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

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 = 'nick@quaran.to'
    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 = 'nick@quaran.to'
    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: nick@quaran.to
    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