Notes

See the source repo for how
the book gets auto-built with "plain" Jekyll - of course - and hosted on GitHub Pages.

Onwards.

1. What is a gem?

Contents

Structure of a Gem

The Gemspec

Unpack the mystery behind what’s in a RubyGem.

Structure of a Gem

Each gem has a name, version, and platform. For example, the
rake gem has a 0.8.7 version (from May,
2009). Rake’s platform is ruby, which means it works on any platform Ruby
runs on.

Platforms are based on the CPU architecture, operating system type and
sometimes the operating system version. Examples include “x86-mingw32” or
“java”. The platform indicates the gem only works with a ruby built for the
same platform. RubyGems will automatically download the correct version for
your platform. See gem help platform for full details.

The test or spec directory contains tests, depending on which test
framework the developer uses

A gem usually has a Rakefile, which the
rake program uses to automate tests,
generate code, and perform other tasks.

This gem also includes an executable file in the
bin directory, which will be loaded into the user’s PATH when the gem is
installed.

Documentation is usually included in the README and inline with the code.
When you install a gem, documentation is generated automatically for you.
Most gems include RDoc documentation,
but some use YARD docs instead.

The final piece is the gemspec, which contains information about the gem.
The gem’s files, test information, platform, version number and more are all
laid out here along with the author’s email and name.

For more information on the gemspec, please check out the full Specification
Reference which goes over each metadata field in
detail.

Credits

This guide was adapted from Gonçalo
Silva’s original tutorial on
docs.rubygems.org and from Gem Sawyer, Modern Day Ruby Warrior.

2. Make your own gem

Contents

Introduction

Your first gem

Requiring more files

Adding an executable

Writing tests

Documenting your code

Wrapup

From start to finish, learn how to package your Ruby code in a gem.

Introduction

Creating and publishing your own gem is simple thanks to the tools baked right
into RubyGems. Let’s make a simple “hello world” gem, and feel free to
play along at home! The code for the gem we’re going to make here is up
on GitHub.

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 to follow
when naming a gem.

% tree
.
├── hola.gemspec
└── lib
└── hola.rb

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
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:

% cat lib/hola.rb
class Hola
def self.hi
puts "Hello world!"
end
end

The gemspec defines what’s in the gem, who made it, and the version of the gem.
It’s also your interface to RubyGems.org. All of the
information you see on a gem page
(like jekyll’s) comes from the gemspec.

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

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.

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

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:

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
ask you to login to RubyGems.org. Enter your username and password. Your browser
will now try to download the file api_key.yaml. Save it in ~/.gem and call it ‘credentials’

This file is getting pretty crowded. Let’s break out the Translator into a
separate file. As mentioned before, the gem’s root file is in charge of
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:

We need to use a strange command line flag here: -Ilib. Usually RubyGems
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.

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
Hoe,
Jeweler,
Rake,
Bundler, or
just a dynamic gemspec
.

Adding more directories with more code from here is pretty much the same
process. Split your Ruby files up when it makes sense! Making a sane order for
your project will help you and your future maintainers from headaches down the
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 gem, which formats JSON in a
readable manner (and is included with Ruby 1.9). Here’s an example:

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

The executable file itself just needs a
shebang in order to figure out
what program to run it with. Here’s what Hola’s executable looks like:

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,
there’s an executables array field on the gemspec.

Note that you should change the gem’s version when pushing up a new release.
For more information on gem versioning, see the Patterns Guide

Writing tests

Testing your gem is extremely important. Not only does it help assure you that
your code works, but it helps others know that your gem does its job. When
evaluating a gem, Ruby developers tend to view a solid test suite (or lack thereof)
as one of the main reasons for trusting that piece of code.

Gems support adding test files into the package itself so tests can be run
when a gem is downloaded.

In short: TEST YOUR GEM! Please!

Test::Unit is Ruby’s built-in test framework. There are
lots of
tutorials for
using it online. There are many other test frameworks available for Ruby as
well. RSpec 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:

Another great option for documentation is YARD, since
when you push a gem, RubyDoc.info generates YARDocs
automatically from your gem. YARD is backwards compatible with RDoc, and it
has a good
introduction on
what’s different and how to use it.

Wrapup

With this basic understanding of building your own RubyGem, we hope you’ll be
on your way to making your own! The next few guides cover patterns in making a
gem and the other capabilities of the RubyGems system.

Creating a gem that uses an extension involves several steps. This guide will
focus on what you should put in your gem specification to make this as easy and
maintainable as possible. The extension in this guide will wrap malloc() and
free() from the C standard library.

Gem layout

Every gem should start with a Rakefile which contains the tasks needed by
developers to work on the gem. The files for the extension should go in the
ext/ directory in a directory matching the extension’s name. For this
example we’ll use “my_malloc” for the name.

Some extensions will be partially written in C and partially written in ruby.
If you are going to support multiple languages, such as C and Java extensions,
you should put the C-specific ruby files under the ext/ directory as well in a
lib/ directory.

When the extension is built the files in ext/my_malloc/lib/ will be installed
into the lib/ directory for you.

extconf.rb

The extconf.rb configures a Makefile that will build your extension based. The
extconf.rb must check for the necessary functions, macros and shared libraries
your extension depends upon. The extconf.rb must exit with an error if any of
these are missing.

Here is an extconf.rb that checks for malloc() and free() and creates a
Makefile that will install the built extension at lib/my_malloc/my_malloc.so:

Now you can build the extension with rake compile and hook the compile task
into other tasks (such as tests).

Setting lib_dir places the shared library in lib/my_malloc/my_malloc.so (or
.bundle or .dll). This allows the top-level file for the gem to be a ruby
file. This allows you to write the parts that are best suited to ruby in ruby.

For example:

class MyMalloc
VERSION = "1.0"
end
require "my_malloc/my_malloc"

Setting the lib_dir also allows you to build a gem that contains pre-built
extensions for multiple versions of ruby. (An extension for Ruby 1.9.3 cannot
be used with an extension for Ruby 2.0.0). lib/my_malloc.rb can pick the
correct shared library to install.

Gem specification

The final step to building the gem is adding the extconf.rb to the extensions
list in the gemspec:

Interfaces to C libraries can be written using ruby and
fiddle (part
of the standard library) or ruby-ffi

4. Name your gem

Contents

Use underscores for multiple words

Use dashes for extensions

Mix underscores and dashes appropriately

Don't use UPPERCASE letters

Our recommendation on the use of “_” and “-“ in your gem’s name.

Here are some examples of our recommendations for naming gems:

Gem name

Require statement

Main class or module

ruby_parser

require 'ruby_parser'

RubyParser

rdoc-data

require 'rdoc/data'

RDoc::Data

net-http-persistent

require 'net/http/persistent'

Net::HTTP::Persistent

net-http-digest_auth

require 'net/http/digest_auth'

Net::HTTP::DigestAuth

The main goal of these recommendations is to give the user some clue about
how to require the files in your gem. Following these conventions also lets
Bundler require your gem with no extra configuration.

If you publish a gem on rubygems.org it may be removed if the name
is objectionable, violates intellectual property or the contents of the gem
meet these criteria. You can report such a gem on the
RubyGems Support site.

Use underscores for multiple words

If a class or module has multiple words, use underscores to separate them. This
matches the file the user will require, making it easier for the user to start
using your gem.

Use dashes for extensions

If you’re adding functionality to another gem, use a dash. This usually
corresponds to a / in the require statement (and therefore your gem’s
directory structure) and a :: in the name of your main class or module.

Mix underscores and dashes appropriately

If your class or module has multiple words and you’re also adding functionality
to another gem, follow both of the rules above. For example,
net-http-digest_auth adds
HTTP digest authentication to net/http.
The user will require 'net/http/digest_auth' to use the extension
(in class Net::HTTP::DigestAuth).

Don’t use UPPERCASE letters

OS X and Windows have case-insensitive filesystems by default. Users may
mistakenly require files from a gem using uppercase letters which will be
non-portable if they move it to a non-windows or OS X system. While this will
mostly be a newbie mistake we don’t need to be confusing them more than
necessary.

Introduction

Now that you’ve created your gem, you’re probably ready
to share it. While it is perfectly reasonable to create private gems solely to
organize the code in large private projects, it’s more common to build gems so
that they can be used by multiple projects. This guide discusses the various
ways that you can share your gem with the world.

Sharing Source Code

The simplest way (from the author’s perspective) to share a gem for other
developers’ use is to distribute it in source code form. If you place the full
source code for your gem on a public git repository (often, though not always,
this means sharing it via GitHub), then other users can
install it with Bundler’s git functionality.

For example, you can install the latest code for the wicked_pdf gem in a
project by including this line in your Gemfile:

gem "wicked_pdf", :git => "git://github.com/mileszs/wicked_pdf.git"

Installing a gem directly from a git repository is a feature of Bundler, not
a feature of RubyGems. Gems installed this way will not show up when you run
gem list.

Serving Your Own Gems

If you want to control who can install a gem, or directly track the activity
surrounding a gem, then you’ll want to set up a private gem server. You can
set up your own gem server or use a commercial
service such as Gemfury.

RubyGems 2.2.0 and newer support the allowed_push_host metadata value to
restrict gem pushes to a single host. If you are publishing private gems you
should set this value to prevent accidental pushes to rubygems.org:

See the Resources guide for an up-to-date listing of options for
private gem servers.

Publishing to RubyGems.org

The simplest way to distribute a gem for public consumption is to use
RubyGems.org. Gems that are published to RubyGems.org
can be installed via the gem install command or through the use of tools such
as Isolate or Bundler.

To begin, you’ll need to create an account on RubyGems.org. Visit the sign
up page and supply an email address that you
control, a handle (username) and a password.

After creating the account, use your email and password when pushing the gem.
(RubyGems saves the credentials in ~/.gem/credentials for you so you only need
to log in once.)

The executable and the primary file in lib are named the same. A developer
can easily jump in and call require 'hola' with no problems.

Naming your gem

Naming your gem is important. Before you pick a name for your gem, do a
quick search on RubyGems.org and
GitHub to see if someone else has taken it. Every
published gem must have a unique name. Be sure to read our naming
recommendations when you’ve found a name you like.

Semantic versioning

A versioning policy is merely a set of simple rules governing how version
numbers are allocated. It can be very simple (e.g. the version number is a
single number starting with 1 and incremented for each successive version), or
it can be really strange (Knuth’s TeX project had version numbers: 3,
3.1, 3.14, 3.141, 3.1415; each successive version added another digit to PI).

The RubyGems team urges gem developers to follow the
Semantic Versioning standard for their gem’s versions. The
RubyGems library itself does not enforce a strict versioning policy, but using
an “irrational” policy will only be a disservice to those in the community who
use your gems.

Suppose you have a ‘stack’ gem that holds a Stack class with both push and
pop functionality. Your CHANGELOG might look like this if you use
semantic versioning:

Version 0.0.1: The initial Stack class is released.

Version 0.0.2: Switched to a linked list implementation because it is
cooler.

Version 0.1.0: Added a depth method.

Version 1.0.0: Added top and made pop return nil (pop used to
return the old top item).

Version 1.1.0: push now returns the value pushed (it used to return
nil).

Version 1.1.1: Fixed a bug in the linked list implementation.

Version 1.1.2: Fixed a bug introduced in the last fix.

Semantic versioning boils down to:

PATCH0.0.x level changes for implementation level detail changes, such
as small bug fixes

MINOR0.x.0 level changes for any backwards compatible API changes,
such as new functionality/features

MAJORx.0.0 level changes for backwards incompatible API changes,
such as changes that will break existing users code if they update

Declaring dependencies

Gems work with other gems. Here are some tips to make sure they’re nice to each
other.

Runtime vs. development

RubyGems provides two main “types” of dependencies: runtime and development.
Runtime dependencies are what your gem needs to work (such as
rails needing
activesupport).

Development dependencies are useful for when someone wants to make
modifications to your gem. When you specify development dependencies, another
developer can run gem install --dev your_gem and RubyGems will grab both sets
of dependencies (runtime and development). Typical development dependencies
include test frameworks and build systems.

Setting dependencies in your gemspec is easy. Just use add_runtime_dependency
and add_development_dependency:

Don’t use gem from within your gem

You may have seen some code like this around to make sure you’re using a
specific version of a gem:

gem "extlib", ">= 1.0.8"
require "extlib"

It’s reasonable for applications that consume gems to use this (though they
could also use a tool like Bundler). Gems themselves
should not do this. They should instead use dependencies in the gemspec so
RubyGems can handle loading the dependency instead of the user.

Pessimistic version constraint

If your gem properly follows semantic versioning with its
versioning scheme, then other Ruby developers can take advantage of this when
choosing a version constraint to lock down your gem in their application.

Let’s say the following releases of a gem exist:

Version 2.1.0 — Baseline

Version 2.2.0 — Introduced some new (backward compatible) features.

Version 2.2.1 — Removed some bugs

Version 2.2.2 — Streamlined your code

Version 2.3.0 — More new features (but still backwards compatible).

Version 3.0.0 — Reworked the interface. Code written to version 2.x might
not work.

Someone who wants to use your gem has determined that version 2.2.0 works with
their software, but version 2.1.0 doesn’t have a feature they need. Adding a
dependency in a gem (or a Gemfile from Bundler) might look like:

The important note to take home here is to be aware others will be using
your gems, so guard yourself from potential bugs/failures in future releases
by using ~> instead of >= if at all possible.

If you’re dealing with a lot of gem dependencies in your application, we
recommend that you take a look into Bundler or
Isolate which do a great job of
managing a complex version manifest for many gems.

If you want to allow prereleases and regular releases use a compound
requirement:

# gemspec
spec.add_runtime_dependency 'library', '>= 2.0.0.a', '< 3'

Using ~> with prerelease versions will restrict you to prerelease versions
only.

Requiring RubyGems

Summary: don’t.

This line…

require 'rubygems'

…should not be necessary in your gem code, since RubyGems is loaded
already when a gem is required. Not having require 'rubygems' in your code
means that the gem can be easily used without needing the RubyGems client to
run.

For more information please check out Ryan
Tomayko’s original
post about the subject.

Loading code

At its core, RubyGems exists to help you manage Ruby’s $LOAD_PATH, which is
how the require statement picks up new code. There’s several things you can
do to make sure you’re loading code the right way.

Respect the global load path

When packaging your gem files, you need to be careful of what is in your lib
directory. Every gem you have installed gets its lib directory appended onto
your $LOAD_PATH. This means any file on the top level of the lib directory
could get required.

For example, let’s say we have a foo gem with the following structure:

.
└── lib
├── foo
│ └── cgi.rb
├── erb.rb
├── foo.rb
└── set.rb

This might seem harmless since your custom erb and set files are within
your gem. However, this is not harmless, anyone who requires this gem will not
be able to bring in the
ERB or
Set classes
provided by Ruby’s standard library.

The best way to get around this is to keep files in a different directory
under lib. The usual convention is to be consistent and put them in the same
folder name as your gem’s name, for example lib/foo/cgi.rb.

Requiring files relative to each other

Gems should not have to use __FILE__ to bring in other Ruby files in your
gem. Code like this is surprisingly common in gems:

When RubyGems activates a gem, it adds your package’s lib folder to the
$LOAD_PATH ready to be required normally by another lib or application. It
is safe to assume you can then require any file in your lib folder.

Prerelease gems

Many gem developers have versions of their gem ready to go out for testing or
“edge” releases before a big gem release. RubyGems supports the concept of
“prerelease” versions, which could be betas, alphas, or anything else that
isn’t ready as a regular release.

Taking advantage of this is easy. All you need is one or more letters in the
gem version. For example, here’s what a prerelease gemspec’s version field
might look like:

Gem::Specification.new do |s|
s.name = "hola"
s.version = "1.0.0.pre"

Other prerelease version numbers might include 2.0.0.rc1, or 1.5.0.beta.3.
It just has to have a letter in it, and you’re set. These gems can then be
installed with the --pre flag, like so:

Credits

A1. Security

How to build and install cryptographically signed gems– and other security concerns.

Security practices are being actively discussed. Check back often.

General

Installing a gem allows that gem’s code to run in the context of your
application. Clearly this has security implications: installing a malicious gem
on a server could ultimately result in that server being completely penetrated
by the gem’s author. Because of this, the security of gem code is a topic of
active discussion within the Ruby community.

RubyGems has had the ability to cryptographically sign
gems since version
0.8.11. This signing works by using the gem cert command to create a key
pair, and then packaging signing data inside the gem itself. The gem install
command optionally lets you set a security policy, and you can verify the
signing key for a gem before you install it.

However, this method of securing gems is not widely used. It requires a number
of manual steps on the part of the developer, and there is no
well-established chain of trust for gem signing keys. Discussion of new
signing models such as X509 and OpenPGP is going on in the rubygems-trust
wiki, the
RubyGems-Developers
list
and in IRC. The goal is to improve
(or replace) the signing system so that it is easy for authors and transparent
for users.

Using Gems

Install with a trust policy.

gem install gemname -P HighSecurity: All dependent gems must be signed
and verified.

gem install gemname -P MediumSecurity: All signed dependent gems must be
verified.

bundle --trust-policy MediumSecurity: Same as above, except Bundler only
recognizes the long --trust-policy flag, not the short -P.

Caveat: Gem certificates are trusted globally, such that adding a
cert.pem for one gem automatically trusts all gems signed by that cert.

Reporting Security vulnerabilities

Reporting a security vulnerability with someone else’s gem

If you spot a security vulnerability in someone else’s gem, then you
first step should be to check whether this is a known vulnerability.
One way is by searching for an advisory on RubySec.

If this looks like a newly discovered vulnerability, then you should
contact the author(s) privately (i.e., not via a pull request or issue on a
public project) explaining the issue, how it can be exploited, and ideally
offering an indication of how it might be fixed.

Reporting a security vulnerability with your own gem

Second, work out what people who depend on your gem should do to resolve the
vulnerability. This may involve releasing a patched version of your gem that
you can recommend they upgrade to.

Finally, you need to tell people about the vulnerability. Currently there
is no single place to broadcast this information but some good places to
start might be to:

Send an email to several lists including ruby-security-ann@googlegroups.com,
rubysec-announce@googlegroups.com, and oss-security@lists.openwall.com
outlining the vulnerability, which versions of your gem it affects, and what
actions those depending on the gem should take. Make sure to use a subject
that includes the gem name, some short summary of the vulnerability, and the
CVE ID if you have one.