how to make a ruby gem - austin on rails, january 2014

How to Make a Ruby Gem

Clare Glinka

1

Who is this talk for?•Me, a few months ago

•Someone who is:

•new to Rails

•new to Ruby

•new to programming

2

What is a gem?

• Container that hold widely-reusable code.

• Code that is useable in many different contexts.

3

Tools to help with making gems:•Bundler•Jeweler•gemcutter•others!

4

Building a Gem <that generates cheesey adventure plots>

with Bundler

5

Step 0.5: $ gem install bundler

6

Step 1: $ bundle gem adventure

7

=> create adventure/Gemfile create adventure/Rakefile create adventure/LICENSE.txt create adventure/README.md create adventure/.gitignore create adventure/adventure.gemspec create adventure/lib/adventure.rb create adventure/lib/adventure/version.rbInitializing git repo in /Users/me/code/adventure

8

Gem structureadventure├── Gemfile├── Rakefile├── LICENSE.txt├── README.md├──.gitignore├── adventure.gemspec└── lib ├── adventure.rb └── adventure └── version.rb

9

Step 3: Finish .gemspec

10

adventure├── Gemfile├── Rakefile├── LICENSE.txt├── README.md├──.gitignore├── adventure.gemspec└── lib ├── adventure.rb └── adventure └── version.rb

11

adventure.gemspeclib = File.expand_path('../lib', __FILE__)$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)require 'adventure/version'

Gem::Specification.new do |spec| spec.name = "adventure" spec.version = Adventure::VERSION spec.authors = ["Clare Glinka"] spec.email = ["[email protected]"] spec.summary = %q{TODO: Write a short summary. Required.} spec.description = %q{TODO: Write a longer description. Optional.} spec.homepage = "" spec.license = "MIT"

spec.files = `git ls-files`.split($/) spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) } spec.test_files = spec.files.grep(%r{^(test|spec|features)/}) spec.require_paths = ["lib"]

spec.add_development_dependency "bundler", "~> 1.4" spec.add_development_dependency "rake"end

12

Required specs•name•version•summary•require_paths•files•rubygems_version

13

spec.name

14

# coding: utf-8lib = File.expand_path('../lib', __FILE__)$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)require 'adventure/version'




15

spec.version

16





17


18

module Adventure VERSION = "0.0.1"end

lib/adventure/version.rb

19

Versioning• Use semantic versioning.

• 0 . 0 . X - bugfixs

• 0 . X . 0- additional functionality that is backward compatible.

• X . 0 . 0- additional functionality that breaks backwards compatibility.

20

Version constraints• ~> 1.2

- all versions before 2 . 0

• ~> 1 . 3 . 5

- all versions before 1. 4 . 0

21

spec.summary

22





23


Gem::Specification.new do |spec| spec.name = "adventure" spec.version = Adventure::VERSION spec.authors = ["Clare Glinka"] spec.email = ["[email protected]"] spec.summary = "Adventure plot generator" spec.description = "" spec.homepage = "" spec.license = "MIT"



24

spec.require_paths

25





26

Protect the load path!$ pry

[1] pry(main)> $LOAD_PATH

=> ["/rbenv/versions/2.0.0-p353/lib/ruby/gems/2.0.0/gems/coderay-1.1.0/lib", "/rbenv/versions/2.0.0-p353/lib/ruby/gems/2.0.0/gems/slop-3.4.7/lib", "/rbenv/versions/2.0.0-p353/lib/ruby/gems/2.0.0/gems/method_source-0.8.2/lib", "/rbenv/versions/2.0.0-p353/lib/ruby/gems/2.0.0/gems/pry-0.9.12.4/lib", "/rbenv/versions/2.0.0-p353/lib/ruby/site_ruby/2.0.0", "/rbenv/versions/2.0.0-p353/lib/ruby/site_ruby/2.0.0/x86_64-darwin13.0.0", "/rbenv/versions/2.0.0-p353/lib/ruby/site_ruby", "/rbenv/versions/2.0.0-p353/lib/ruby/vendor_ruby/2.0.0", "/rbenv/versions/2.0.0-p353/lib/ruby/vendor_ruby/2.0.0/x86_64-darwin13.0.0", "/rbenv/versions/2.0.0-p353/lib/ruby/vendor_ruby", "/rbenv/versions/2.0.0-p353/lib/ruby/2.0.0", "/rbenv/versions/2.0.0-p353/lib/ruby/2.0.0/x86_64-darwin13.0.0"]

27

Protect the load path![2] pry(main)> require 'adventure'=> true

[3] pry(main)> $LOAD_PATH=> ["/rbenv/versions/2.0.0-p353/lib/ruby/gems/2.0.0/gems/coderay-1.1.0/lib", "/rbenv/versions/2.0.0-p353/lib/ruby/gems/2.0.0/gems/slop-3.4.7/lib", "/rbenv/versions/2.0.0-p353/lib/ruby/gems/2.0.0/gems/method_source-0.8.2/lib", "/rbenv/versions/2.0.0-p353/lib/ruby/gems/2.0.0/gems/pry-0.9.12.4/lib", "/rbenv/versions/2.0.0-p353/lib/ruby/gems/2.0.0/gems/adventure-0.0.1/lib", "/rbenv/versions/2.0.0-p353/lib/ruby/site_ruby/2.0.0", "/rbenv/versions/2.0.0-p353/lib/ruby/site_ruby/2.0.0/x86_64-darwin13.0.0", "/rbenv/versions/2.0.0-p353/lib/ruby/site_ruby", "/rbenv/versions/2.0.0-p353/lib/ruby/vendor_ruby/2.0.0", "/rbenv/versions/2.0.0-p353/lib/ruby/vendor_ruby/2.0.0/x86_64-darwin13.0.0", "/rbenv/versions/2.0.0-p353/lib/ruby/vendor_ruby", "/rbenv/versions/2.0.0-p353/lib/ruby/2.0.0", "/rbenv/versions/2.0.0-p353/lib/ruby/2.0.0/x86_64-darwin13.0.0"]

28


29

spec.files

30





31

$ git ls-files

.gitignoreGemfileLICENSE.txtREADME.mdRakefileadventure.gemspeclib/adventure.rblib/adventure/version.rb

32

$ pry

[1] pry(main)> `git ls-‐files`=> ".gitignore\nGemfile\nLICENSE.txt\nREADME.md\nRakefile\nadventure.gemspec\nlib/adventure.rb\nlib/adventure/version.rb\n"[2] pry(main)> `git ls-‐files`.split($\)=> [".gitignore", "Gemfile", "LICENSE.txt", "README.md", "Rakefile", "adventure.gemspec", "lib/adventure.rb", "lib/adventure/version.rb"]

33

$ pry

[1] pry(main)> `git ls-‐files`=> ".gitignore\nGemfile\nLICENSE.txt\nREADME.md\nRakefile\nadventure.gemspec\nlib/adventure.rb\nlib/adventure/version.rb\n"[2] pry(main)> `git ls-‐files`.split($\)=> [".gitignore", "Gemfile", "LICENSE.txt", "README.md", "Rakefile", "adventure.gemspec", "lib/adventure.rb", "lib/adventure/version.rb"]

34



spec.files = [".gitignore", "Gemfile", "LICENSE.txt", "README.md", "Rakefile", "adventure.gemspec", "lib/adventure.rb", "lib/adventure/version.rb"] spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) } spec.test_files = spec.files.grep(%r{^(test|spec|features)/}) spec.require_paths = ["lib"]


35





36



spec.files = Dir.glob(‘**/*’) spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) } spec.test_files = spec.files.grep(%r{^(test|spec|features)/}) spec.require_paths = ["lib"]


37

$ pry

[1] pry(main)> Dir.glob('**/**')=> ["adventure.gemspec", "Gemfile", "lib", "lib/adventure", "lib/adventure/random.txt", "lib/adventure/version.rb", "lib/adventure.rb", "LICENSE.txt", "Rakefile", "README.md"]

38

spec.rubygems_version

39

Other Specs:•authors•email•homepage• license•executables•test_files•add_development_dependency•add_dependency

40

spec.authorsspec.email

spec.homepage

41





42


Gem::Specification.new do |spec| spec.name = "adventure" spec.version = Adventure::VERSION spec.authors = ["Clare Glinka"] spec.email = ["[email protected]"] spec.summary = "Adventure plot generator" spec.description = "" spec.homepage = "http://www.github.com/cglinka/adventure" spec.license = "MIT"



43

spec.license

44


Gem::Specification.new do |spec| spec.name = "adventure" spec.version = Adventure::VERSION spec.authors = ["Clare Glinka"] spec.email = ["[email protected]"] spec.summary = "Adventure plot generator" spec.description = "" spec.homepage = "http://www.github.com/cglinka/adventure" spec.license = "MIT"



45


46

spec.executablesspec.test_files

47


Gem::Specification.new do |spec| spec.name = "adventure" spec.version = Adventure::VERSION spec.authors = ["Clare Glinka"] spec.email = ["[email protected]"] spec.summary = "Adventure plot generator" spec.description = "" spec.homepage = "http://github.com/cglinka/adventure" spec.license = "MIT"



48

Step 4: Write some code!

49


50

require "adventure/version"

module Adventure # Your code goes here...end

51

“There is a disgruntled shopkeeper with a secret past and a grad student with a knack for cooking.

They fight crime!”

Desired output:

52


module Adventure class Plot def make_plot characters = ["a clever dragon", "a ruthless detective", "a disgruntled shopkeeper", "an aging cowboy", "a grad student", "a mystical lizard"] with = ["nothing left to loose", "a secret past", "an enchanted sword", "a grudge", "a knack for cooking"] who = ["likes kebabs", "organizes poetry nights", "is a world-‐famous cyclist", "lived in a circus"]

"There is #{characters.sample} with #{with.sample} and #{characters.sample} who #{who.sample}. They fight crime!" end endend

53

Step 5: build and install the gem

54

$ gem build adventure.gemspec

WARNING: no description specified Successfully built RubyGem Name: adventure Version: 0.0.1 File: adventure-0.0.1.gem

55

adventure├── Gemfile├── Rakefile├── LICENSE.txt├── README.md├──.gitignore├── adventure.gemspec├── adventure-0.0.1.gem└── lib ├── adventure.rb └── adventure └── version.rb

56

$ gem install adventure-0.0.1.gem

Successfully installed adventure-0.0.11 gem installed

57

$ pry

[1] pry(main)> require 'adventure'=> true[2] pry(main)> plot = Adventure::Plot.new=> #<Adventure::Plot:0x007fe2a4106498>[3] pry(main)> plot.make_plot=> "There is a grad student with a knack for cooking and a ruthless detective who likes kebabs. They fight crime!"

58

The easier way... Rake tasks!

59





60


61

source 'https://rubygems.org'

# Specify your gem's dependencies in adventure.gemspecgemspec

Gemfile

62

Rakefile

require "bundler/gem_tasks"

63

$ rake -‐T

rake build # Build adventure-‐0.0.1.gem into the pkg directory.rake install # Build and install adventure-‐0.0.1.gem into system gems.rake release # Create tag v0.0.1 and build and push adventure-‐0.0.1.gem to Rubygems

64

$ rake build

adventure 0.0.1 built to pkg/adventure-‐0.0.1.gem.

65

$ rake install

adventure 0.0.1 built to pkg/adventure-‐0.0.1.gem.adventure (0.0.1) installed.

66

adventure├── Gemfile├── Rakefile├── LICENSE.txt├── README.md├──.gitignore├── adventure.gemspec├── pkg│ └── adventure-0.0.1.gem└── lib ├── adventure.rb └── adventure └── version.rb

67

Step 6: Release the gem!

68

$ rake release

70

And if everything has gone terribly wrong...

$ gem yank

*** Use with caution71

No More Hardcoding!

72

adventure.json{ "characters": [ "a clever dragon", "a ruthless detective", "a disgruntled shopkeeper", "an aging cowboy", "a grad student", "a mystical lizard" ], "with": [ "nothing left to loose", "a secret past", "an enchanted sword", "a grudge", "a knack for cooking" ], "who": [ "likes kebabs", "organizes poetry nights", "is a world-‐famous cyclist", "lived in a circus" ]}

73

spec.add_dependency

74




spec.add_dependency "json"


75

$ bundle install

Resolving dependencies...Using bundler (1.5.2)Using json (1.7.7)Using rake (0.9.6)Using adventure (0.0.1) from source at .Your bundle is complete!

76


module Adventure class Plot def make_plot characters = ["a clever dragon", "a ruthless detective", "a disgruntled shopkeeper", "an aging cowboy", "a grad student", "a mystical lizard"] with = ["nothing left to loose", "a secret past", "an enchanted sword", "a grudge", "a knack for cooking"] who = ["likes kebabs", "organizes poetry nights", "is a world-‐famous cyclist", "lived in a circus"]


77

require "adventure/version"require "json"

module Adventure class Plot def make_plot(plotdevice) plotholes = JSON.load(File.new(plotdevice))

characters = plotholes["characters"] with = plotholes["with"] who = plotholes["who"]


lib/adventure.rb

78

$ rake install


79



80



81

$ rake install


82

$ pry

[1] pry(main)> require 'adventure'=> true[2] pry(main)> plot = Adventure::Plot.new=> #<Adventure::Plot:0x007fc079139e80>[3] pry(main)> plot.make_plot('adventure.json')=> "There is a clever dragon with a secret past and a clever dragon who is a world-‐famous cyclist. They fight crime!"

83

Set Up Testing with <RSpec>

84




spec.add_dependency "json" spec.add_development_dependency "bundler", "~> 1.4" spec.add_development_dependencyependency "rake" spec.add_development_dependencyependency "rspec"end

85

$ rspec --init

create spec/spec_helper.rb create .rspec

86

adventure├── Gemfile├── Rakefile├── LICENSE.txt├── README.md├── .gitignore├── .rspec├── adventure.gemspec├── pkg├── lib└── spec └── spec_helper.rb

87

spec/spec_helper.rb

# This file was generated by the `rspec -‐-‐init` command. Conventionally, all# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.# Require this file using `require "spec_helper"` to ensure that it is only# loaded once.## See http://rubydoc.info/gems/rspec-‐core/RSpec/Core/ConfigurationRSpec.configure do |config| config.treat_symbols_as_metadata_keys_with_true_values = true config.run_all_when_everything_filtered = true config.filter_run :focus

# Run specs in random order to surface order dependencies. If you find an # order dependency and want to debug it, you can fix the order by providing # the seed, which is printed after each run. # -‐-‐seed 1234 config.order = 'random'end

88

spec/spec_helper.rbrequire 'adventure'

# This file was generated by the `rspec -‐-‐init` command. Conventionally, all# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.# Require this file using `require "spec_helper"` to ensure that it is only# loaded once.## See http://rubydoc.info/gems/rspec-‐core/RSpec/Core/ConfigurationRSpec.configure do |config| config.treat_symbols_as_metadata_keys_with_true_values = true config.run_all_when_everything_filtered = true config.filter_run :focus

# Run specs in random order to surface order dependencies. If you find an # order dependency and want to debug it, you can fix the order by providing # the seed, which is printed after each run. # -‐-‐seed 1234 config.order = 'random'end

89

adventure├── Gemfile├── Rakefile├── LICENSE.txt├── README.md├── .gitignore├── .rspec├── adventure.gemspec├── pkg├── lib└── spec ├── spec_adventure.rb └── spec_helper.rb

90

spec/adventure_spec.rb

require 'spec_helper'

describe Adventure::Plot do describe "#make_plot" do it "does something" do

end endend

91

$ bundle exec rspec

Run options: include {:focus=>true}

All examples were filtered out; ignoring {:focus=>true}.

Finished in 0.00052 seconds1 example, 0 failures

Randomized with seed 38431

92

Rakefile

require "bundler/gem_tasks"require "rspec/core/rake_task"

RSpec::Core::RakeTask.new('spec')

93

Rakefile

require "bundler/gem_tasks"require "rspec/core/rake_task"

RSpec::Core::RakeTask.new('spec')

94

$ rake spec

Run options: include {:focus=>true}

All examples were filtered out; ignoring {:focus=>true}.

Finished in 0.00052 seconds1 example, 0 failures

Randomized with seed 38431

95

Resources

guides.rubygems.org

link to slides @ClareGlinka_

97

how to make a ruby gem - austin on rails, january 2014

Technology

files spec

executables spec

adventure adventure

rbmodule adventure version

git lsfiles

version summary

gemspec lib

f file