Slide 1

Slide 1 text

Nick Quaranto @qrush [email protected] R B Y cutting your own RubyGems Wednesday, May 25, 2011

Slide 2

Slide 2 text

P S A first, a Wednesday, May 25, 2011

Slide 3

Slide 3 text

Where have all of the manuals gone? Wednesday, May 25, 2011

Slide 4

Slide 4 text

http://history.nasa.gov/diagrams/gemini.html Wednesday, May 25, 2011

Slide 5

Slide 5 text

http://history.nasa.gov/diagrams/gemini.html Wednesday, May 25, 2011

Slide 6

Slide 6 text

http://archive.computerhistory.org/resources/text/Apple/Apple.AppleI.1976.102646518.pdf Wednesday, May 25, 2011

Slide 7

Slide 7 text

http://archive.computerhistory.org/resources/text/Apple/Apple.AppleI.1976.102646518.pdf Wednesday, May 25, 2011

Slide 8

Slide 8 text

http://archive.computerhistory.org/resources/text/Apple/Apple.AppleI.1976.102646518.pdf Wednesday, May 25, 2011

Slide 9

Slide 9 text

http://archive.computerhistory.org/resources/text/Apple/Apple.AppleI.1976.102646518.pdf Wednesday, May 25, 2011

Slide 10

Slide 10 text

http://ed-thelen.org/comp-hist/CRAY-1-HardRefMan/CRAY-1-HRM.html Wednesday, May 25, 2011

Slide 11

Slide 11 text

http://ed-thelen.org/comp-hist/CRAY-1-HardRefMan/CRAY-1-HRM.html Wednesday, May 25, 2011

Slide 12

Slide 12 text

http://ed-thelen.org/comp-hist/CRAY-1-HardRefMan/CRAY-1-HRM.html Wednesday, May 25, 2011

Slide 13

Slide 13 text

http://guides.rubyonrails.org Wednesday, May 25, 2011

Slide 14

Slide 14 text

http://progit.org Wednesday, May 25, 2011

Slide 15

Slide 15 text

http://guides.sproutcore.org Wednesday, May 25, 2011

Slide 16

Slide 16 text

We need MORE manuals! Wednesday, May 25, 2011

Slide 17

Slide 17 text

MAKE MANUALS Wednesday, May 25, 2011

Slide 18

Slide 18 text

http://guides.rubygems.org Wednesday, May 25, 2011

Slide 19

Slide 19 text

G E M what is a gem? Wednesday, May 25, 2011

Slide 20

Slide 20 text

Gems contain a packaged Ruby application or library. Wednesday, May 25, 2011

Slide 21

Slide 21 text

RubyGems helps you download, install, and manipulate gems. Wednesday, May 25, 2011

Slide 22

Slide 22 text

rubygems.org rubygems client Wednesday, May 25, 2011

Slide 23

Slide 23 text

rubygems.org rubygems client gems Wednesday, May 25, 2011

Slide 24

Slide 24 text

rubygems.org rubygems client gems, gemspecs, indexes from S3 gems Wednesday, May 25, 2011

Slide 25

Slide 25 text

.gem Wednesday, May 25, 2011

Slide 26

Slide 26 text

Code Gemspec Docs Wednesday, May 25, 2011

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

.gem Rails ??? Wednesday, May 25, 2011

Slide 29

Slide 29 text

Ruby looks on your $LOAD_PATH when you call Kernel#require Wednesday, May 25, 2011

Slide 30

Slide 30 text

RubyGems manages your $LOAD_PATH Wednesday, May 25, 2011

Slide 31

Slide 31 text

% 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", "."] Wednesday, May 25, 2011

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

RubyGems overrides Kernel#require RubyGems puts bin/ and lib/ on your $LOAD_PATH Wednesday, May 25, 2011

Slide 35

Slide 35 text

Gemspec holds metadata & info about the gem Wednesday, May 25, 2011

Slide 36

Slide 36 text

% 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 = '[email protected]' s.homepage = 'http://example.com' s.files = ["lib/freewill.rb"] end Wednesday, May 25, 2011

Slide 37

Slide 37 text

A gem is just a tarball of tarballs Wednesday, May 25, 2011

Slide 38

Slide 38 text

% gem fetch rake Downloaded rake-0.8.7 % tar zxvf rake-0.8.7.gem x data.tar.gz x metadata.gz Wednesday, May 25, 2011

Slide 39

Slide 39 text

A GEM IS A TARBALL WITHIN A TARBALL Wednesday, May 25, 2011

Slide 40

Slide 40 text

WHY CAN’T I USE MY LINUX PACKAGE MANAGER THEN Wednesday, May 25, 2011

Slide 41

Slide 41 text

Wednesday, May 25, 2011

Slide 42

Slide 42 text

LOL, WHAT’S A TARBALL Wednesday, May 25, 2011

Slide 43

Slide 43 text

D Y I make your own gem Wednesday, May 25, 2011

Slide 44

Slide 44 text

share/modularize code automate your process releasing a gem is easy! Wednesday, May 25, 2011

Slide 45

Slide 45 text

first gem Wednesday, May 25, 2011

Slide 46

Slide 46 text

Your gem needs a name Wednesday, May 25, 2011

Slide 47

Slide 47 text

DO NOT CALL IT: [rR].* rials cheezburger kitty dicks Wednesday, May 25, 2011

Slide 48

Slide 48 text

no capitals, please use underscores for spaces use dashes for extensions Wednesday, May 25, 2011

Slide 49

Slide 49 text

% tree . ├── hola.gemspec └── lib └── hola.rb Wednesday, May 25, 2011

Slide 50

Slide 50 text

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

Slide 51

Slide 51 text

require ‘hola’ % tree . ├── hola.gemspec └── lib └── hola.rb Wednesday, May 25, 2011

Slide 52

Slide 52 text

% cat hola.gemspec Gem::Specification.new do |s| 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 = '[email protected]' s.files = ["lib/hola.rb"] s.homepage = 'http://rubygems.org/gems/hola' end Wednesday, May 25, 2011

Slide 53

Slide 53 text

push install build Wednesday, May 25, 2011

Slide 54

Slide 54 text

push install build LOCAL Wednesday, May 25, 2011

Slide 55

Slide 55 text

push install build LOCAL REMOTE Wednesday, May 25, 2011

Slide 56

Slide 56 text

% 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 Wednesday, May 25, 2011

Slide 57

Slide 57 text

Wednesday, May 25, 2011

Slide 58

Slide 58 text

Wednesday, May 25, 2011

Slide 59

Slide 59 text

try your gem out before pushing! Wednesday, May 25, 2011

Slide 60

Slide 60 text

% irb -rubygems >> require 'hola' => true >> Hola.hi Hello world! Wednesday, May 25, 2011

Slide 61

Slide 61 text

% irb -rubygems >> require 'hola' => true >> Hola.hi Hello world! require 'ubygems.rb' Wednesday, May 25, 2011

Slide 62

Slide 62 text

Wednesday, May 25, 2011

Slide 63

Slide 63 text

% 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) Wednesday, May 25, 2011

Slide 64

Slide 64 text

push install build LOCAL REMOTE install list -r Wednesday, May 25, 2011

Slide 65

Slide 65 text

% gem list -r hola *** REMOTE GEMS *** hola (0.0.0) % gem install hola Successfully installed hola-0.0.0 1 gem installed Wednesday, May 25, 2011

Slide 66

Slide 66 text

executable first gem Wednesday, May 25, 2011

Slide 67

Slide 67 text

gems are like awesome shell aliases Wednesday, May 25, 2011

Slide 68

Slide 68 text

% curl -s http://jsonip.com/ | \ prettify_json.rb { "ip": "24.60.248.134" } Wednesday, May 25, 2011

Slide 69

Slide 69 text

% mkdir bin % touch bin/hola % chmod a+x bin/hola Wednesday, May 25, 2011

Slide 70

Slide 70 text

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

Slide 71

Slide 71 text

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

Slide 72

Slide 72 text

% 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') Wednesday, May 25, 2011

Slide 73

Slide 73 text

% 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 Wednesday, May 25, 2011

Slide 74

Slide 74 text

% ruby -Ilib ./bin/hola Hello world! % ruby -Ilib ./bin/hola Baltimore Hello Baltimore! Wednesday, May 25, 2011

Slide 75

Slide 75 text

% ruby -Ilib ./bin/hola Hello world! % ruby -Ilib ./bin/hola Baltimore Hello Baltimore! $LOAD_PATH.unshift(“lib”) Wednesday, May 25, 2011

Slide 76

Slide 76 text

% hola Hello world! % hola Baltimore Hello Baltimore! Wednesday, May 25, 2011

Slide 77

Slide 77 text

% head -4 hola.gemspec Gem::Specification.new do |s| s.name = 'hola' s.version = '0.0.1' s.executables << 'hola' Wednesday, May 25, 2011

Slide 78

Slide 78 text

tests executable first gem Wednesday, May 25, 2011

Slide 79

Slide 79 text

framework automation Wednesday, May 25, 2011

Slide 80

Slide 80 text

framework automation rake thor Wednesday, May 25, 2011

Slide 81

Slide 81 text

framework automation rake thor Test::Unit rspec bacon context matchy shoulda riot testy shindo zebra lemon dfect cucumber steak Wednesday, May 25, 2011

Slide 82

Slide 82 text

Test your gem. Use whatever. Please test it. Wednesday, May 25, 2011

Slide 83

Slide 83 text

http://test.rubygems.org Wednesday, May 25, 2011

Slide 84

Slide 84 text

Wednesday, May 25, 2011

Slide 85

Slide 85 text

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

Slide 86

Slide 86 text

% 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 Wednesday, May 25, 2011

Slide 87

Slide 87 text

% 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 Wednesday, May 25, 2011

Slide 88

Slide 88 text

tests executable first gem docs Wednesday, May 25, 2011

Slide 89

Slide 89 text

Others will use your gem. Write about it. Wednesday, May 25, 2011

Slide 90

Slide 90 text

At least have a README! Wednesday, May 25, 2011

Slide 91

Slide 91 text

http://twitter.com/rubygems Wednesday, May 25, 2011

Slide 92

Slide 92 text

inline guides Wednesday, May 25, 2011

Slide 93

Slide 93 text

inline guides nokogiri yard Wednesday, May 25, 2011

Slide 94

Slide 94 text

inline guides nokogiri yard rails datamapper Wednesday, May 25, 2011

Slide 95

Slide 95 text

# 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 Wednesday, May 25, 2011

Slide 96

Slide 96 text

http://yardoc.org Wednesday, May 25, 2011

Slide 97

Slide 97 text

P T N patterns Wednesday, May 25, 2011

Slide 98

Slide 98 text

more files Wednesday, May 25, 2011

Slide 99

Slide 99 text

. └── lib ├── hola │ └── translator.rb └── hola.rb Wednesday, May 25, 2011

Slide 100

Slide 100 text

. └── lib ├── hola │ └── translator.rb └── hola.rb BAD: require File.join(File.dirname( __FILE__), "hola", "translator") Wednesday, May 25, 2011

Slide 101

Slide 101 text

. └── lib ├── hola │ └── translator.rb └── hola.rb WORSE: $LOAD_PATH.unshift "lib/hola" require "translator" Wednesday, May 25, 2011

Slide 102

Slide 102 text

. └── lib ├── hola │ └── translator.rb └── hola.rb GOOD: require "hola/translator" Wednesday, May 25, 2011

Slide 103

Slide 103 text

Keep only one top-level file in lib/ Wednesday, May 25, 2011

Slide 104

Slide 104 text

. └── lib ├── foo │ └── cgi.rb ├── foo.rb └── set.rb Wednesday, May 25, 2011

Slide 105

Slide 105 text

. └── lib ├── foo │ └── cgi.rb ├── foo.rb └── set.rb require ‘set’ Wednesday, May 25, 2011

Slide 106

Slide 106 text

. └── lib ├── foo │ └── cgi.rb ├── foo.rb └── set.rb require ‘foo/cgi’ Wednesday, May 25, 2011

Slide 107

Slide 107 text

semver more files Wednesday, May 25, 2011

Slide 108

Slide 108 text

Have a sane versioning scheme Wednesday, May 25, 2011

Slide 109

Slide 109 text

http://www.flickr.com/photos/ioerror/3014911710/lightbox/ Wednesday, May 25, 2011

Slide 110

Slide 110 text

3 3.1 3.14 3.141 3.1415 3.14159 3.141592 3.1415926 Wednesday, May 25, 2011

Slide 111

Slide 111 text

http://semver.org Wednesday, May 25, 2011

Slide 112

Slide 112 text

1.2.3 MAJOR.MINOR.PATCH Wednesday, May 25, 2011

Slide 113

Slide 113 text

0.0.x implementation details small bug fixes PATCH Wednesday, May 25, 2011

Slide 114

Slide 114 text

0.x.0 backwards compatible API changes MINOR Wednesday, May 25, 2011

Slide 115

Slide 115 text

x.0.0 backwards incompatible API changes MAJOR Wednesday, May 25, 2011

Slide 116

Slide 116 text

dependencies semver more files Wednesday, May 25, 2011

Slide 117

Slide 117 text

http://www.slideshare.net/copiousfreetime/gemology Wednesday, May 25, 2011

Slide 118

Slide 118 text

Specify your dependencies Wednesday, May 25, 2011

Slide 119

Slide 119 text

development runtime Wednesday, May 25, 2011

Slide 120

Slide 120 text

development runtime what your gem needs to work Wednesday, May 25, 2011

Slide 121

Slide 121 text

development runtime what your gem needs to work what your tests need to work Wednesday, May 25, 2011

Slide 122

Slide 122 text

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"]) Wednesday, May 25, 2011

Slide 123

Slide 123 text

Avoid >= Wednesday, May 25, 2011

Slide 124

Slide 124 text

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.0.0"]) Exact This one works for me! Wednesday, May 25, 2011

Slide 125

Slide 125 text

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"]) Optimistic It will always work! Wednesday, May 25, 2011

Slide 126

Slide 126 text

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", "< 3.0.0"]) Pessimistic This and future minor releases work Wednesday, May 25, 2011

Slide 127

Slide 127 text

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"]) Pessimistic Use the twiddle-wakka! Wednesday, May 25, 2011

Slide 128

Slide 128 text

releasing a gem is easy! Wednesday, May 25, 2011

Slide 129

Slide 129 text

have a sane versioning scheme Wednesday, May 25, 2011

Slide 130

Slide 130 text

MAKE MANUALS Wednesday, May 25, 2011

Slide 131

Slide 131 text

T H X Thanks for listening! Big thanks to: thoughtbot Jeremy Hinegardner Nick Quaranto @qrush [email protected] http://guides.rubygems.org Wednesday, May 25, 2011