From start to finish, learn how to package your Ruby code in a gem.
Note: Many people use Bundler to create Gems. You can learn how to do that by reading the “Developing a RubyGem +href="https://bundler.io/v2.3/guides/creating_gem.html">Developing a RubyGem using Bundler” guide on the Bundler website.
* [Introduction](#introduction) @@ -32,11 +32,11 @@ Your first gem -------------- I started with just one Ruby file for my `hola` gem, and the gemspec. -You'll need a new name for yours (maybe `hola_yourusername`) to publish it. Check the Patterns guide for -[basic recommendations](/patterns/#consistent-naming) to follow -when naming a gem. +You'll need a new name for yours (maybe `hola_yourusername`) to publish it. +Check the Patterns guide for [basic recommendations](/patterns/#consistent-naming) +to follow when naming a gem. - % tree + $ tree . ├── hola.gemspec └── lib @@ -44,13 +44,13 @@ when naming a gem. Code for your package is placed within the `lib` directory. The convention is to have *one* Ruby file with the *same* name as your gem, since that gets -loaded when `require 'hola'` is run. That one file is in charge of setting up +loaded when `require "hola"` is run. That one file is in charge of setting up your gem's code and API. -The code inside of `lib/hola.rb` is pretty bare bones. It just makes sure that you -can see some output from the gem: +The code inside of `lib/hola.rb` is pretty bare bones. It just makes sure that +you can see some output from the gem: - % cat lib/hola.rb + $ cat lib/hola.rb class Hola def self.hi puts "Hello world!" @@ -62,64 +62,82 @@ It’s also your interface to [RubyGems.org](https://rubygems.org). All of the information you see on a gem page (like [jekyll](https://rubygems.org/gems/jekyll)’s) comes from the gemspec. - % cat hola.gemspec + $ cat hola.gemspec Gem::Specification.new do |s| - s.name = 'hola' - s.version = '0.0.0' + s.name = "hola" + s.version = "0.0.0" s.summary = "Hola!" s.description = "A simple hello world gem" s.authors = ["Nick Quaranto"] - s.email = 'nick@quaran.to' + s.email = "nick@quaran.to" s.files = ["lib/hola.rb"] s.homepage = - 'https://rubygems.org/gems/hola' - s.license = 'MIT' + "https://rubygems.org/gems/hola" + s.license = "MIT" end > The description member can be much longer than you see in this example. If it > matches `/^== [A-Z]/` then the description will be run through -> [RDoc's markup formatter](https://github.com/rdoc/rdoc) for display on -> the RubyGems web site. Be aware though that other consumers of the data might not -> understand this markup. +> [RDoc's markup formatter](https://github.com/ruby/rdoc) for display on +> the RubyGems web site. Be aware though that other consumers of the data might +> not understand this markup. Look familiar? The gemspec is also Ruby, so you can wrap scripts to generate the file names and bump the version number. There are lots of fields the gemspec can contain. To see them all check out the full -[reference](/specification-reference). +[reference](/specification-reference/). -After you have created a gemspec, you can build a gem from it. Then you can install -the generated gem locally to test it out. +After you have created a gemspec, you can build a gem from it. Then you can +install the generated gem locally to test it out. - % gem build hola.gemspec - Successfully built RubyGem - Name: hola - Version: 0.0.0 - File: hola-0.0.0.gem + $ 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 + $ gem install ./hola-0.0.0.gem Successfully installed hola-0.0.0 + Parsing documentation for hola-0.0.0 + Installing ri documentation for hola-0.0.0 + Done installing documentation for hola after 0 seconds 1 gem installed -Of course, the smoke test isn’t over yet: the final step is to `require` the gem and use it: +Of course, the smoke test isn’t over yet: the final step is to `require` the +gem and use it: - % irb - >> require 'hola' - => true - >> Hola.hi + $ irb + 3.1.2 :001 > require "hola" + => true + 3.1.2 :002 > Hola.hi Hello world! - -> If you're using an earlier Ruby than 1.9.2, you need to start the -> session with `irb -rubygems` or require the rubygems library after -> you launch irb. + => nil Now you can share hola with the rest of the Ruby community. Publishing your -gem out to RubyGems.org only takes one command, provided that you have an account on -the site. To setup your computer with your RubyGems account, you can run below command (where `qrush` should be replaced by your own username): - - $ curl -u qrush https://rubygems.org/api/v1/api_key.yaml > - ~/.gem/credentials; chmod 0600 ~/.gem/credentials - - Enter host password for user 'qrush': +gem out to RubyGems.org only takes one command, provided that you have an +account on the site. To setup your computer with your RubyGems account, you can +run below command (where you should replace with your own Email, Password, and +OTP (if enabled)): + + $ gem signin + Enter your RubyGems.org credentials. + Don't have an account yet? Create one at https://rubygems.org/sign_up + Email: (your-email-address@example.com) + Password: (your password for RubyGems.org) + + API Key name [host-user-20220102030405]: + Please select scopes you want to enable for the API key (y/n) + index_rubygems [y/N]: n + push_rubygem [y/N]: y + yank_rubygem [y/N]: n + add_owner [y/N]: n + remove_owner [y/N]: n + access_webhooks [y/N]: n + show_dashboard [y/N]: n + + You have enabled multi-factor authentication. Please enter OTP code. + Code: 123456 + Signed in with API key: host-user-20220102030405. > If you're having problems with curl, OpenSSL, or certificates, you might want to > simply try entering the above URL in your browser's address bar. Your browser will @@ -128,7 +146,7 @@ the site. To setup your computer with your RubyGems account, you can run below c Once this has been setup, you can push out the gem: - % gem push hola-0.0.0.gem + $ gem push hola-0.0.0.gem Pushing gem to RubyGems.org... Successfully registered gem: hola (0.0.0) @@ -136,14 +154,18 @@ In just a short time (usually less than a minute), your gem will be available fo installation by anyone. You can see it [on the RubyGems.org site](https://rubygems.org/gems/hola) or grab it from any computer with RubyGems installed: - % gem list -r hola + $ gem list -r hola *** REMOTE GEMS *** - hola (0.0.0) + hola (0.1.3) - % gem install hola - Successfully installed hola-0.0.0 + $ gem install hola + Fetching hola-0.1.3.gem + Successfully installed hola-0.1.3 + Parsing documentation for hola-0.1.3 + Installing ri documentation for hola-0.1.3 + Done installing documentation for hola after 0 seconds 1 gem installed It’s really that easy to share code with Ruby and RubyGems. @@ -154,7 +176,7 @@ Requiring more files Having everything in one file doesn't scale well. Let's add some more code to this gem. - % cat lib/hola.rb + $ cat lib/hola.rb class Hola def self.hi(language = "english") translator = Translator.new(language) @@ -183,7 +205,7 @@ loading code for the gem. The other files for a gem are usually placed in a directory of the same name of the gem inside of `lib`. We can split this gem out like so: - % tree + $ tree . ├── hola.gemspec └── lib @@ -195,7 +217,7 @@ The `Translator` is now in `lib/hola`, which can easily be picked up with a `require` statement from `lib/hola.rb`. The code for the `Translator` did not change much: - % cat lib/hola/translator.rb + $ cat lib/hola/translator.rb class Hola::Translator def initialize(language) @language = language @@ -213,7 +235,7 @@ change much: But now the `hola.rb` file has some code to load the `Translator`: - % cat lib/hola.rb + $ cat lib/hola.rb class Hola def self.hi(language = "english") translator = Translator.new(language) @@ -224,23 +246,25 @@ But now the `hola.rb` file has some code to load the `Translator`: require 'hola/translator' > Gotcha: -> For newly created folder/file, do not forget to add one entry in hola.gemspec file, as shown- +> For newly created folder/file, do not forget to add one entry in hola.gemspec +> file, as shown- - % cat hola.gemspec + $ cat hola.gemspec Gem::Specification.new do |s| ... - s.files = ["lib/hola.rb", "lib/hola/translator.rb"] + s.files = ["lib/hola.rb", "lib/hola/translator.rb"] ... end -> without the above change, new folder would not be included into the installed gem. +> without the above change, the new folder would not be included into the +> installed gem. Let's try this out. First, fire up `irb`: - % irb -Ilib -rhola - irb(main):001:0> Hola.hi("english") + $ irb -Ilib -rhola + 3.1.2 :001 > Hola.hi("english") => "hello world" - irb(main):002:0> Hola.hi("spanish") + 3.1.2 :002 > Hola.hi("spanish") => "hola mundo" We need to use a strange command line flag here: `-Ilib`. Usually RubyGems @@ -248,17 +272,17 @@ includes the `lib` directory for you, so end users don't need to worry about configuring their load paths. However, if you're running the code outside of RubyGems, you have to configure things yourself. It's possible to manipulate the `$LOAD_PATH` from within the code itself, but that's considered an -anti-pattern in most cases. There are many more anti-patterns (and good patterns!) -for gems, explained in [this guide](/patterns). +anti-pattern in most cases. There are many more anti-patterns (and good +patterns!) for gems, explained in [this guide](/patterns/). If you've added more files to your gem, make sure to remember to add them to -your gemspec's `files` array before publishing a new gem! For this reason (among others), -many developers automate this with +your gemspec's `files` array before publishing a new gem! For this reason +(among others), many developers automate this with [Hoe](https://github.com/seattlerb/hoe), [Jeweler](https://github.com/technicalpickles/jeweler), [Rake](https://github.com/ruby/rake), -[Bundler](http://railscasts.com/episodes/245-new-gem-with-bundler), or -[just a dynamic gemspec +[lorem](https://github.com/railscasts/245-new-gem-with-bundler/tree/HEAD/lorem), +or [just a dynamic gemspec ](https://github.com/wycats/newgem-template/blob/master/newgem.gemspec). Adding more directories with more code from here is pretty much the same @@ -269,32 +293,33 @@ line. Adding an executable -------------------- -In addition to providing libraries of Ruby code, gems can also expose one or many -executable files to your shell's `PATH`. Probably the best known example of -this is `rake`. Another very useful one is `prettify_json.rb`, included -with the [JSON](https://rubygems.org/gems/json) gem, which formats JSON in a -readable manner (and is included with Ruby 1.9). Here's an example: +In addition to providing libraries of Ruby code, gems can also expose one or +many executable files to your shell's `PATH`. Probably the best known example +of this is `rake`. Another very useful one is `nokogiri` from [Nokogiri +](https://rubygems.org/gems/Nokogiri) gem, which parse HTML/XML documents. +Here's an example: - % curl -s http://jsonip.com/ | \ - prettify_json.rb - { - "ip": "24.60.248.134" - } + $ gem install -N nokogiri + [...] + $ nokogiri https://www.ruby-lang.org/ + Your document is stored in @doc... + 3.1.2 :001 > @doc.title + => "Ruby Programming Language" Adding an executable to a gem is a simple process. You just need to place the file in your gem's `bin` directory, and then add it to the list of executables in the gemspec. Let's add one for the Hola gem. First create the file and make it executable: - % mkdir bin - % touch bin/hola - % chmod a+x bin/hola + $ mkdir bin + $ touch bin/hola + $ chmod a+x bin/hola The executable file itself just needs a [shebang](http://www.catb.org/jargon/html/S/shebang.html) in order to figure out what program to run it with. Here's what Hola's executable looks like: - % cat bin/hola + $ cat bin/hola #!/usr/bin/env ruby require 'hola' @@ -303,20 +328,20 @@ what program to run it with. Here's what Hola's executable looks like: All it's doing is loading up the gem, and passing the first command line argument as the language to say hello with. Here's an example of running it: - % ruby -Ilib ./bin/hola + $ ruby -Ilib ./bin/hola hello world - % ruby -Ilib ./bin/hola spanish + $ ruby -Ilib ./bin/hola spanish hola mundo Finally, to get Hola's executable included when you push the gem, you'll need to add it in the gemspec. - % head -4 hola.gemspec + $ head -4 hola.gemspec Gem::Specification.new do |s| - s.name = 'hola' - s.version = '0.0.1' - s.executables << 'hola' + s.name = "hola" + s.version = "0.0.1" + s.executables << "hola" Push up that new gem, and you'll have your own command line utility published! You can add more executables as well in the `bin` directory if you need to, @@ -339,16 +364,16 @@ when a gem is downloaded. In short: *TEST YOUR GEM!* Please! `Minitest` is Ruby's built-in test framework. There are -[lots](http://www.mikeperham.com/2012/09/25/minitest-ruby-1-9s-test-framework/) of -[tutorials](https://github.com/seattlerb/minitest/blob/master/README.rdoc) for +[lots](https://www.mikeperham.com/2012/09/25/minitest-ruby-1-9s-test-framework/) of +[tutorials](https://github.com/minitest/minitest/blob/master/README.rdoc) for using it online. There are many other test frameworks available for Ruby as -well. [RSpec](http://rspec.info/) is a popular choice. At the end of the day, +well. [RSpec](https://rspec.info/) is a popular choice. At the end of the day, it doesn't matter what you use, just *TEST*! Let's add some tests to Hola. This requires adding a few more files, namely a `Rakefile` and a brand new `test` directory: - % tree + $ tree . ├── Rakefile ├── bin @@ -363,22 +388,22 @@ Let's add some tests to Hola. This requires adding a few more files, namely a The `Rakefile` gives you some simple automation for running tests: - % cat Rakefile - require 'rake/testtask' + $ cat Rakefile + require "rake/testtask" Rake::TestTask.new do |t| - t.libs << 'test' + t.libs << "test" end desc "Run tests" - task :default => :test + task default: :test Now you can run `rake test` or simply just `rake` to run tests. Woot! Here's a basic test file for hola: - % cat test/test_hola.rb - require 'minitest/autorun' - require 'hola' + $ cat test/test_hola.rb + require "minitest/autorun" + require "hola" class HolaTest < Minitest::Test def test_english_hello @@ -399,25 +424,27 @@ a basic test file for hola: Finally, to run the tests: - % rake test - (in /Users/qrush/Dev/ruby/hola) - Loaded suite - Started + $ rake test + Run options: --seed 9351 + + # Running: + ... - Finished in 0.000736 seconds. - 3 tests, 3 assertions, 0 failures, 0 errors, 0 skips + Finished in 0.005645s, 531.4108 runs/s, 531.4108 assertions/s. - Test run options: --seed 15331 + 3 runs, 3 assertions, 0 failures, 0 errors, 0 skips -It's green! Well, depending on your shell colors. For more great examples, the best thing you can do is hunt around -[GitHub](https://github.com/search?q=stars%3A%3E100+forks%3A%3E10&type=Repositories&l=Ruby) and read some code. +It's green! Well, depending on your shell colors. For more great examples, the +best thing you can do is to hunt around [GitHub +](https://github.com/search?q=stars%3A%3E1000+forks%3A%3E100&type=Repositories&l=Ruby) +and read some code. Documenting your code --------------------- By default most gems use RDoc to generate docs. There are plenty of -[great tutorials](http://docs.seattlerb.org/rdoc/RDoc/Markup.html) for learning how +[great tutorials](https://ruby.github.io/rdoc/RDoc/Markup.html) for learning how to mark up your code with RDoc. Here's a simple example: # The main Hola driver @@ -437,11 +464,11 @@ to mark up your code with RDoc. Here's a simple example: end end -Another great option for documentation is [YARD](http://yardoc.org/), since -when you push a gem, [RubyDoc.info](http://rubydoc.info/) generates YARDocs +Another great option for documentation is [YARD](https://yardoc.org/), since +when you push a gem, [RubyDoc.info](https://rubydoc.info/) generates YARDocs automatically from your gem. YARD is backwards compatible with RDoc, and it has a [good -introduction](http://rubydoc.info/docs/yard/file/docs/GettingStarted.md) on +introduction](https://rubydoc.info/gems/yard/file/docs/GettingStarted.md) on what's different and how to use it. Wrapup @@ -454,6 +481,6 @@ gem and the other capabilities of the RubyGems system. Credits ------- -This tutorial was adapted from [Gem Sawyer, Modern Day Ruby -Warrior](http://rubylearning.com/blog/2010/10/06/gem-sawyer-modern-day-ruby-warrior/). +This tutorial was adapted from "Gem Sawyer, Modern Day Ruby +Warrior" <`http://rubylearning.com/blog/2010/10/06/gem-sawyer-modern-day-ruby-warrior/`>. The code for this gem can be found [on GitHub](https://github.com/qrush/hola).