• Read more about Polishing Rubies (Part 4): Writing Library Code

This post is a part of Polishing Rubies, an end-to-end guide to Ruby open source development.

« Back to Part 3: Tools for Testing

Can you believe it? It's actually time to start writing the code for your gem! Now, in this part of the guide you'll be more "on your own" than up to this point. I don't know what kind of open source library you're writing, whether it's an extension to an existing library, a simple utility, or a complex, sprawling project that will change the face of development forever. What I do know, however, is that there are some common things that you may want to do that have community best practices attached.

File Structure, Naming, and Requirement

While it may not seem vital, how you name your files and where you put them can be a critical component of your library's ease of use for developers. This is particularly true because on a GitHub repository page one can simply press t and start typing a filename, then look at the code for that file by pressing return. This is the way that many people will try to take a quick peek at the internals of your gem, so by creating sane, easily guessable filenames you are making it simple for others to read your code.

In general, you will have one class per file and one folder per module namespace, so for instance:

• MyGem becomes lib/my-gem.rb (this is a special case, see part 2)
• MyGem::Widget becomes lib/my_gem/widget.rb
• MyGem::Widgets::FooBar becomes lib/my_gem/widgets/foo_bar.rb

There are, however, a few corner cases in which each class may not have its own file. One is a private class that is meant to be used only internally and only in the scope of another class. Another are the exception classes for your library. We will cover exception classes in the next section.

When a developer wants to use your library, they should be able to do so (in almost all cases) by making a single require statement that is identical to the gem name. That means that in the root file you need to make any additional require statements necessary for your gem to function. So if I have a MyGem module, a MyGem::Widget class, and a MyGem::Widgets::FooBar class, the lib/my-gem.rb file in my gem might look like this:

require 'external_library' # require any external dependencies  module MyGem # it is best to declare the base module at the top end  require 'my_gem/version' # created by Bundler require 'my_gem/widget' require 'my_gem/widgets/foo_bar' 

By requiring all of the files necessary for your gem to run in the base file you make it easier for developers to use your library. Some gems, however, may be made up of multiple parts that could be used independently of each other. ActiveSupport, for example, provides a large number of useful utilities that, while they function together, can also function separately.

If I add require 'active_support' to my code I load all of ActiveSupport. While this may be what I want in some cases (like inside a Rails application) in other cases I may just want a specific piece of ActiveSupport. Luckily, ActiveSupport is designed to handle this well. If I, for instance, add require 'active_support/core_ext' I will only be loading the Ruby core extensions that are a part of ActiveSupport.

How can you make this work in your library? It's quite simple: your base file should, when required, require all the other parts of your library. However, each part of your library should, at its top, require any other parts or external dependencies so that it may be included without the user having previously required the base file. Let's take a look at an example:

# in lib/my-gem.rb  require 'my_gem/widget' require 'my_gem/widgets/foo_bar' reuqire 'my_gem/widgets/baz'  # in lib/my_gem/widget.rb  require 'external_library'  module MyGem   class Widget   end end  # in lib/my_gem/widgets/foo_bar  require 'my_gem/widget'  module MyGem   module Widgets     class FooBar < MyGem::Widget     end   end end 

Each of the files in the above example can be required independently, giving developers the flexibility to use only a subset of your library's functionality if needed. Remember that require statements will only load the code from a file once, so it is safe to require the same file multiple times.

Exception Classes

As a library author you are creating a black box: you tell developers how to send messages to the box, the box sends messages back, but a well-designed library does not expose internal implementation details to its end users. In service of creating a properly bounded library, your application should only raise errors that you allow it to raise.

Sometimes you will be able to use existing error classes. For instance, if you might raise an ArgumentError if invalid parameters are passed to a method in your library or a NotImplementedError if you are building some kind of abstract interface. Many times, however, you will want to create one or more custom exception classes to provide insight into what happened when things go wrong.

Exception classes usually end up in one of two places in a library: either in the base file (lib/my-gem.rb) or, if there are more than one or two error classes, all together in a file such as lib/my_gem/errors.rb. It is entirely possible to create a custom exception class in a single line:

module MyGem   class Error < StandardError; end end 

This allows you to raise out an error that can be caught by users of your library when exceptions occur:

raise MyGem::Error, "This is the error message." 

If you wish to create more than one custom exception class, it is a good practice to have a single base MyGem::Error class and several subclasses underneath it. This way, users of your library can rescue from any exception it might generate simply with rescue MyGem::Error.

One other thing you might want to do is store some additional information along with an error; for instance, in an API client library if you receive a non-success status code you may want to include the HTTP response so that more information can be obtained:

module MyGem   class Error < StandardError; end   class ResponseError < MyGem::Error     attr_reader :response      def initialize(response, message)       @response = response       super(message)     end   end end  # Elsewhere...  raise MyGem::ResponseError.new(response, "Invalid response from HTTP client.") 

Because you are providing library code you will usually want to wrap any internal exceptional scenarios with your own exception class. For instance, if there is a method that you call from another library that will sometimes raise exceptions, you should rescue from those exception classes and wrap it into your own:

module MyGem   class SomeClass     def some_method       ExternalLibrary.dangerous_method_call     rescue ExternalLibrary::Error => e       raise MyGem::Error, "Some dangerous method call didn't work."     end   end end 

Proper exception handling makes your library well-encapsulated and easy to use and also helps your users to report issues when they occur.

Library Configuration

Oftentimes in a library there is various "root-level" configuration that may need to be performed. There are lots of different ways to handle such configuration (including a number of gems that you can depend upon to do the heavy-lifting) but, with a little bit of elbow grease, you can write your own configuration class that is robust without being cumbersome.

To begin, let's create a new file lib/my_gem/configuration.rb that will contain our configuration class. Now let's fill it up:

module MyGem   class Configuration     attr_accessor :option1, :option2      def initialize(config = {})       config.each_pair do |key, value|         self.send("#{key}=", value)       end     end   end end 

This gets us started with two configuration options (:option1 and :option2) and can be used like so:

config = MyGem::Configuration.new(option1: 'foo', option2: 'bar') config.option1 # => 'foo' config.option1 = 'baz' config.option1 # => 'baz' 

As you can see, this gives us the beginnings of what we might want from library configuration: there are a few different options, we can read and write each option individually and we can also initialize their values with a hash. So what might we want next? Well, it's usually best to explicitly define default options we might have:

module MyGem   class Configuration     DEFAULT_CONFIGURATION = {       option1: 'foo',        option2: nil     }      attr_accessor :option1, :option2      def initialize(attributes = {})       DEFAULT_CONFIGURATION.merge(attributes).each_pair do |attribute, value|         self.send("#{attribute}=", value)       end     end   end end 

That was easy enough: our default options are set as a constant beneath our Configuration class, and we then merge in the options that are passed to the constructor to bootstrap our configuration. Note also that in this example :option2 is defaulted to nil. Each option should be given an explicit default value so that developers who are reading your code know all of the options that are available.

Next up we will make our Configuration class friendly to people who want to use block-style declarative configuration:

module MyGem   class Configuration     DEFAULT_CONFIGURATION = {       option1: 'foo',        option2: nil     }      attr_accessor :option1, :option2      def initialize(attributes = {}, &block)       configure(DEFAULT_CONFIGURATION.merge(attributes), &block)     end      def configure(attributes = {})       attributes.each_pair do |attribute, value|         self.send("#{attribute}=", value)       end        yield self if block_given?        self     end   end end 

As you can see we've added a #configure method that takes a hash and sets configuration values or takes a block and yields itself. We also added block-yielding capabilities to the constructor. This allows us to set configuration like so:

c = MyGem::Configuration.new do |config|   config.option1 = 'baz' end  c.option1 # => 'baz'  c.configure do |config|   config.option1 = 'wonk' end  c.option1 # => 'wonk' 

Look familiar? Many gems utilize this block-yielding method of configuration; it's a community pattern and one that is nice and easy to implement. Now that we've built a simple configuration class, we need to hook it into our root module. So let's open up lib/my_gem.rb and add the following:

module MyGem   def self.config     @config ||= Configuration.new   end    def self.configure(attributes = {}, &block)     config.configure attributes, &block   end end 

By memoizing an instance of the configuration class at MyGem.config, we have a single persistent configuration object for our gem. We can now configure our library exactly like many others:

MyGem.configure do |config|   config.option1 = 'bar' end  MyGem.config.option1 # => 'bar' 

Because we support both block-yielding and hashes, we also make it easy for people to use, for instance, a YAML configuration file and pass the relevant configuration in that way.

Keep it Clean

The most important aspect of writing library code is just to write the best code you can write! Every best practice and code style that you've heard of is doubly important when you're writing code meant to be read and used by an entire community of developers. That being said, no library ever ships with perfect code. It's often better to do your best and get something out the door than to hold off and hold off while you tweak things ad infinitum. You can always fix it in the next version!

• Read more about Polishing Rubies (Part 3): Tools for Testing

This post is a part of Polishing Rubies, an end-to-end guide to Ruby open source development.

« Back to Part 2: Creating a Gem

A good toolchain is important for any development project. It makes the lives of developers easier by abstracting away or automating repetitive tasks. You should always spend some time at the outset of a project making sure you're using all of the best tools available. On an open source project this is 10 times more important.

Instead of building a toolchain that will be used by your company or small team, you're building a toolchain that will potentially be used by dozens, hundreds, or even thousands of other developers. An annoyance that costs five minutes, multiplied by all those developers, equals hours and hours of lost potential productivity. Now that we've bootstrapped the directory structure of our gem, it's time to get our toolchain up and running so that development for you (and all of your contributors some day) is as painless and fast as possible.

Test Setup

Having tests for your gem is fundamentally important. If you have no tests, you have no way to vet incoming pull requests, check for regressions between versions, or really have any control over the quality of your project. Luckily, the Ruby community has a strong testing culture so there are great tools to use and widespread adoption of testing practices.

I'm going to walk through how to set your gem up for testing via RSpec. In general the Ruby community nearly universally uses either RSpec or the built-in Test::Unit as its framework of choice. I would love to cover Test::Unit as well, but I don't have enough of a grasp on best practices to be able to tell you how to do that here. If you would like to contribute such a section to this guide, by all means please fork it on GitHub and I'll be happy to update the content.

The first step to using RSpec in your tests is to add it to your project's gemspec:

gem.add_development_dependency 'rspec', '~> 2.9' 

This tells RubyGems that RSpec is a necessary library for developers who are going to try to contribute to your gem. Once you've added the dependency, run bundle to update your dependencies with Bundler. Note that because Bundler is capable of reading dependencies from a gemspec you don't need to manually specify them in your Gemfile.

With RSpec, it's a good practice to specify the most recent minor version (the second number in the MAJOR.MINOR.PATCH versioning system) for your dependency. This way if RSpec updates to a new major version that breaks existing functionality, you can review any breakages and fix them with a new release of your gem rather than having unstable tests in the wild.

Now that you have RSpec in your project's bundle, you should run bundle exec rspec --init. This is a simple generator that will bootstrap your project's RSpec setup. The output should look something like this:

create   spec/spec_helper.rb create   .rspec 

The .rspec file is an options file that lets you specify the default command-line options (such as output format and color) that will be used by RSpec's runner in your project. If you've written tests before, you should be familiar with spec/spec_helper.rb as a central place to bootstrap your test suite and add any dependent library requires, etc.

Because we're writing a gem we will want to set up our spec_helper.rb file to work with our gem's structure. Alter the file to look like this:

$:.unshift File.dirname(__FILE__) + '/../lib' require 'my-gem'  RSpec.configure do |config|   config.treat_symbols_as_metadata_keys_with_true_values = true   config.run_all_when_everything_filtered = true   config.filter_run :focus end 

The first line adds our gem's lib directory to Ruby's load path. This means that when we say something like require 'some-file' Ruby will automatically look in our gem's lib directory to see if that file exists. The second line, require 'my-gem', is the same line that your end users will type when they want to start using your gem. This allows us to write tests from the perspective of someone who has installed the gem and required it, either manually or automatically through a tool like Bundler.

Now that we have our spec_helper all set up, let's go ahead and create our first spec. Create a file spec/my_gem_spec.rb (replace my_gem with your gem's name) and put this in it:

require 'spec_helper'  describe MyGem do   it 'requires additional testing' end 

Now simply run the rspec command in your project's root directory. You should see output that looks like this:

Run options: include {:focus=>true}  All examples were filtered out; ignoring {:focus=>true} *  Pending:   MyGem requires additional testing     # Not yet implemented     # ./spec/my_gem_spec.rb:4  Finished in 0.00015 seconds 1 example, 0 failures, 1 pending 

Congratulations! You've got your gem's test suite up and running.

Testing With Rake

Another standard practice amongst all Ruby projects (apps and gems alike) is to make it possible to run the tests for a project via a Rake task. This is remarkably easy; all you need to do is open up the Rakefile in your project's directory and add the following to the bottom of your Rakefile:

require 'rspec/core/rake_task' RSpec::Core::RakeTask.new task :default => :spec 

This does two things: first, it creates a new RSpec rake task that, by default, can be run by typing rake spec at your project's root. Second, we assign the :default task to be :spec. This means that in your project's root you can simply run rake and all of the tests for your project will run. This is a convention in the Ruby community and a good practice for all projects.

To verify everything we've done we can simply run rake -T which is a command to list the available Rake tasks. You should see something like this:

rake build    # Build my-gem-0.0.1.gem into the pkg directory rake install  # Build and install my-gem-0.0.1.gem into system gems rake release  # Create tag v0.0.1 and build and push my-gem-0.0.1.gem to Ru... rake spec     # Run RSpec code examples 

As you can see, we have four tasks available. Three of them are provided to us by Bundler for packaging and releasing our gem, and one of them is provided by RSpec for testing our gem.

Autotesting With Guard

Guard is a gem that allows you to observe your project's files for change and perform actions based on that change. The first thing you will need to do is add Guard (and its helpers for Bundler and RSpec) to the end of your Gemfile:

gem 'guard' gem 'guard-rspec' gem 'guard-bundler' 

Note that, differently from RSpec, I prefer to add Guard and its related gems to my project's Gemfile, not its gemspec. This choice comes down to personal preference, but while RSpec is required for someone to do development on my gem, Guard is really more of a nice to have and so I relax the dependency somewhat. The effect is the same for contributors: simply running bundle in the project's directory will install all of the dependencies from the gemspec and the Gemfile. Speaking of which, you should now run bundle in your project root to install Guard if it isn't already.

Now we need to initialize Guard and configure it for our project. Luckily, Guard comes with its own command line helpers:

guard init guard init bundler guard init rspec 

Guard works similarly to Bundler and Rake by creating a Guardfile in your project's root directory. These commands automatically add example configuration for each guard type to the Guardfile (after guard init creates the file to begin with). While I'm going to tell you explicitly what to put in your Guardfile, the init commands can really help jog your memory if you're trying to do it from scratch. Let's modify our Guardfile to look like this:

guard 'bundler' do   watch('Gemfile')   watch(/^.+.gemspec/) end  guard 'rspec', :version => 2 do   watch(%r{^spec/.+_spec.rb$})   watch(%r{^lib/(.+).rb$})     { |m| "spec/#{m[1]}_spec.rb" }   watch('spec/spec_helper.rb')  { "spec" } end 

Guard works by watching certain files in your project and then performing actions when those files change. The first guard tells us to watch for the Gemfile and the gemspec to change, and re-bundle the application when that happens. The second guard tells us to watch all of our RSpec test files, our spec_helper, and the corresponding library files for each of our RSpec tests. This means that when you change a file, Guard can automatically re-run the tests for that specific file only.

Now that your Guardfile is properly configured, you can just run bundle exec guard from your project's root directory. This will get Guard up and running and you will now automatically run tests and re-bundle as you build your gem. Running Guard makes the development feedback loop as tight and automatic as possible.

Continuous Integration

Continuous Integration is the process of automatically running the tests for a project when new code is pushed to the central repository. Luckily, a team of developers has built Travis CI that provides free continuous integration for open source projects of all types.

Why do you need continuous integration for an open source project?

• Travis allows you to test your code across multiple versions of Ruby. Even if you don't personally develop on older versions of Ruby or alternative implementations such as JRuby or Rubinius, Travis can run your tests on these Rubies and notify you of any build failures.
• Travis gives you the confidence to merge pull requests from the web. If someone submits a pull request you can merge it into your repository knowing that if it breaks your test build Travis will let you know. In the future, Travis will even support testing pull requests before you merge them.

In addition to the benefits provided by Travis is it exceptionally easy to implement. Here's how:

1. Go to http://travis-ci.org and sign in with your GitHub account. Travis needs access to your GitHub info to be able to set up the automatic build process for each repository.
2. Hover over your name once logged in and go to your profile. This lists out your open source repositories; from here you can simply "switch on" CI for each project.
3. Set up a .travis.yml file in your project.

We haven't yet created a GitHub repository for our project, so steps 1 and 2 will actually come a bit later. However, we can set up the configuration file so that when we're ready to push to GitHub we will get continuous integration immediately. To set up Travis for your project you need to create one more configuration file in your repository. Make a file called .travis.yml (the leading dot is not a typo) and add this to it:

rvm:   - 1.9.3   - 1.9.2   - jruby   - rbx script: "bundle exec rake" 

As you can see, the configuration is very straightforward. The rvm key allows us to specify the different versions of Ruby we want to test against. The script key tells Travis what command to run for the build. Any command that exits with a non-zero status code (a Unix standard for a command that had errors) will automatically fail the build in Travis. In our case we're going to run bundle exec rake which, as explained above, has been aliased to running our RSpec tests via Rake.

Once you've added your Travis configuration file, it's time to create another commit:

git add . git commit -m "Adds RSpec, Rake testing, Guard, and Travis." 

All right! Now we've not only created a gem but we've added robust tools for testing that will give us and other contributors the power to develop quickly and in a test-driven manner. We've also set up continuous integration to let us test against many different versions of Ruby, even if we don't have them installed! We're well on our way to building a gem. Stay tuned for the next installment!

Continue to Part 4: Writing Library Code »

• Read more about Polishing Rubies (Part 2): Creating A Gem

This post is a part of Polishing Rubies, an end-to-end guide to Ruby open source development.

« Back to Part 1: Introduction

Creating Your Gem

Eureka! You've thought of a new idea for an open source library. Perhaps you already have some code tucked away in your application that you're extracting into a library, or perhaps you're starting from scratch. Either way, your next step is going to be setting up a gem folder to which you can then add code, tests, and documentation. As we saw previously, RubyGems are simply folders that follow certain patterns. You can build one from scratch quite easily, but luckily we have some tools that make it even easier.

A Gem By Any Other Name...

Of course when you create your gem you're going to have to have something to call it. Naming may not seem very important as a first step, but the gem name ends up in folder names, file names, and Ruby code, so you usually want to come up with a name first. So how do you pick one?

Developers have created RubyGems with an incredibly wide range of names, from the straightforward to the absurd, from the clever to the downright crass. Depending on what you're building, however, there might be a convention to follow in your name. Here is an incomplete list of gem naming conventions:

• Your gem's name should be all lowercase with dash delimiters between words. Typically, the root module or class for your gem should be inferrable by class-casing your gem name. For example, if I wanted to call my library "Awesome Sauce" the gem name would be awesome-sauce and the root class/module would be AwesomeSauce.
• If you are building a gem that adapts an existing library (such as a C library for parsing JSON) the common pattern is simply to name your gem libraryname-ruby (e.g. yajl-ruby for the YAJL JSON library).
• If you are building a library that adapts another library for a framework (such as RSpec testing for Rails), the convention is to name it libraryname-rails (e.g. rspec-rails).
• Some libraries are somewhat like frameworks in their own right and allow for an open "constellation" of associated gems. These will usually suggest a naming pattern, but the common one is frameworkname-libraryname (for example, the Facebook strategy gem for the OmniAuth authentication framework is called omniauth-facebook).
• If you are building a Ruby library to access, for example, a specific service's web API, the gem is usually just named after the service (though in some cases follows the service-ruby pattern). You should be pretty confident about your long-term maintenance of a gem like this, as you will be claiming that gem name for all eternity. It would be unfortunate if the twitter gem fell into disrepair and was no longer a good way to access Twitter's API.

Ultimately a gem name is a lot like a brand name. Whether it's fair or not, a bad gem name can damage the popularity and success of a library just like a good one can make it more memorable and successful. When in doubt, try to include a keyword from your problem domain in the gem name (for example "auth" for an authentication library or "test" for a test framework). Avoid hard-to-spell words and elaborate metaphors (the typhoeus library has always been particularly hard to remember). Keep it short and simple, but ultimately, it's your library, and if you want to name it something funny or clever that's entirely your prerogative.

Before you settle on a name, you will need to make sure that it isn't already taken. The simplest way to do this is simply to visit http://rubygems.org/gems/{YOUR_GEM_NAME} in your browser. If you see a page that says "Page not found." then that gem is available.

Tooling Up

Polishing Rubies is meant to be a guide that is both pragmatic and encourages best practices. To that end, whenever possible we will not be "doing it from scratch." When you're building an open source library you're building for multiple audiences: yourself, end users, and contributors. Using the right tools is important for all of the audiences, but is most important to encourage contribution.

When it comes to making contributors happy, you want to be using a toolchain that is as comfortable as possible to make it extremely easy for someone to check out your code and start working with it. We'll cover that a bit more later on.

Here a quick list of the tools that we'll be using throughout this guide to help us make a gem that follows community best practices:

• GitHub: where you will be hosting the source code, issue reporting and wiki documentation for your gem
• Bundler: directory bootstrapping, dependency, and release management
• Travis: free, amazing continuous integration for open source projects
• Guard: development process automation tool
• RSpec: our test framework (my personal choice, but the built-in Test::Unit libraries included with Ruby are a perfectly acceptable alternative)
• Rubydoc.info: automatic documentation generation for RubyGems. Always a handy place to link from your project's README
• Gemnasium: tracks dependencies to make sure your library is always compatible with the latest versions of the libraries you use

We'll talk about the use of each of these tools as needed throughout the guide, but this can serve as a handy reference to the things that most (if not all) gems will eventually end up using. Right now we're only going to worry about using Bundler.

Spinning Up a Gem

All right, now that all of the introductory material is out of the way, it's time to actually spin up your gem. This guide will be written assuming that you are using a POSIX-based shell system (such as Mac OS X or Linux) and that you have already installed Ruby 1.9.2 or later on your machine.

First make sure that you have Bundler installed on your system. Bundler contains a command-line helper called bundle gem that automatically generates a basic gem skeleton for us. To install Bundler you need to run this command in a terminal window:

gem install bundler 

Once you've installed Bundler, you should change directories to the location that you want to create your gem folder (for me, that location is ~/code/gems). Once there you will create the gem like so:

bundle gem my-gem 

Where my-gem is your gem's name. Note that if you are building a command line tool you should add the -b flag to this command (bundle gem my-gem -b). You should see output that looks something like this:

      create  my-gem/Gemfile       create  my-gem/Rakefile       create  my-gem/.gitignore       create  my-gem/my-gem.gemspec       create  my-gem/lib/my-gem.rb       create  my-gem/lib/my-gem/version.rb Initializating git repo in /Users/mbleigh/code/gems/my-gem 

Bundler has just generated a skeleton for your gem. You should recognize many of the files from our earlier discussion of the general structure of a gem. Some of the nice things that Bundler has done for us include:

• .gitignore: There are certain files that you will not want to have to your git repository. Bundler automatically excludes the most common of these.
• version.rb: Bundler creates my-gem/lib/my-gem/version.rb automatically. This file is used as a single place to track the current version of your library. By default, Bundler sets the version to 0.0.1.
• Rakefile: The Rakefile created by Bundler is already set up with Bundler's gem helpers. These helpers allow you to release a new version of your gem (including creating a release tag in git and pushing the compiled gem to rubygems.org) with a single command.

Now that we've used Bundler to help us build our basic directory structure, we need to dig in and do a little housekeeping before we're ready to set up our development toolchain and start working.

Gemspec: Metadata for Your Library

Bundler has automatically created the gemspec file that serves as a manifest of metadata about your gem. However, you will need to edit this file to add specific information before your gem will be properly set up. Your gemspec should look something like this:

# -*- encoding: utf-8 -*- require File.expand_path('../lib/my-gem/version', __FILE__)  Gem::Specification.new do |gem|   gem.authors       = ["Michael Bleigh"]   gem.email         = ["michael@intridea.com"]   gem.description   = %q{TODO: Write a gem description}   gem.summary       = %q{TODO: Write a gem summary}   gem.homepage      = ""    gem.executables   = `git ls-files -- bin/*`.split("n").map{ |f| File.basename(f) }   gem.files         = `git ls-files`.split("n")   gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("n")   gem.name          = "my-gem"   gem.require_paths = ["lib"]   gem.version       = My::Gem::VERSION end 

Most of these fields are fairly straightforward. Authors lets you provide one or more names of the authors of the library, email is the contact email for each of the authors. The executables, files, and test_files fields each represent lists of files to include in the packaged gem. When a gem is built, only these files will be included. By default Bundler uses some handy command-line magic with git to programmatically determine the file lists. For most circumstances, you shouldn't need to change these lines.

At this point you need to make a few changes to this file to follow best practices:

1. gem.description: you should write a single-sentence description of your gem in this field. Note that %q{} is an alternative way to declare a string in Ruby. Bundler uses this by default so that you can use double and single quotes within the description without needing to escape them. Your maximum length should be no more than around 140 characters (like a tweet!).
2. gem.summary: you can just copy and paste the gem description into this field for now.
3. gem.homepage: this should generally be set to the location of your repo on GitHub unless you have created a specific website for your library.

The last step of your initial setup is to ensure that the constant and folder names generated by Bundler matches the constant and folder names you want to use for your library. Sometimes Bundler gets this right, and sometimes it doesn't. For example, in the above gemspec the referenced version is My::Gem::VERSION when I would actually want it to be MyGem::VERSION. To change this, I need to modify the constant in three places:

1. The version reference in the gemspec
2. The lib/my-gem.rb file
3. The lib/my-gem/version.rb file

Unless your library is going to be very small, you will usually want your base constant (for example MyGem) to be a module, not a class. This allows you to easily namespace all of the different classes and components of your gem in a simple and sane way.

Underscores and Dashes

RubyGems have an unfortunate conflict of common patterns: gem names are almost always delimited with dashes while folder and file names are almost always delimited with underscores. This is partially to make for inferrable mappings from file names to class names (a pattern that is actively utilized by Rails to automatically load constants based on their file names). So if I have a constant called MyGem::VERSION it should be located in lib/my_gem/version.rb even though my gem's name is my-gem.

When Bundler generates your gem (if you have dashes in the name) it creates a folder inside the lib directory of the same name. I would recommend modifying this to use underscores in place of dashes. To do this, you will need to do the following:

1. Rename the directory (e.g. mv lib/my-gem lib/my_gem).
2. Alter the first line require in lib/my-gem.rb to use the underscored directory name.
3. Alter the require in the gemspec file to use the underscored directory name.

If all of this weren't confusing enough, there is another pattern in Ruby that the only file that should be added to the root load path (the first level of your gem's lib) should be named identically to the gem. So lib/my-gem.rb is the one and only place that you should allow dashes in your filenames.

Following such needlessly complicated naming schemes may feel like a waste of time, but it most certainly isn't. By following the community conventions you:

1. Make your library easier to "guess" how to use because developers can use common idioms to which they have become accustomed.
2. Make your library auto-requireable by Bundler (which looks for the my-gem.rb file and requires it automatically in frameworks such as Rails)
3. Make your library easier for contributors to join by providing familiar patterns and locations for code

Library Dependencies

As with a man, no gem is an island (well, ok, very few gems are islands). Nearly all gems are going to have dependencies upon other libraries that they require in order to function. These dependencies are explicitly declared in the gemspec so that when a gem is installed, all of the gems that are needed to run that gem can automatically be installed with it.

There are two types of gem dependencies, runtime dependencies and development dependencies. Runtime dependencies are libraries that your gem needs in order to function. For example, if you built a Rails extension, you would need to add Rails to the runtime dependencies of your project. Development dependencies, on the other hand, are gems that are only needed by people who are going to contribute to the code of the gem. Gems are, by default, installed only with the runtime dependencies. This avoids cluttering up an environment with development dependencies if they aren't needed.

Adding dependencies to your gemspec is extremely simple; all you need to do is add a line to the file for each dependency:

# -*- encoding: utf-8 -*- require File.expand_path('../lib/my-gem/version', __FILE__)  Gem::Specification.new do |gem|   # ...    gem.add_dependency 'rails'   gem.add_development_dependency 'rspec', '~> 2.7' end 

In addition to specifying the gem name of a dependency, you can also specify a version of the gem to get even more specific. Versioning is an important topic and one that we will cover later. For now, it's OK if you just add your dependencies without specifying the version. RubyGems will default to the latest version if no specific version is required.

Now you've created the basic structure of your gem. You understand the gemspec manifest file, a little bit about the structure of the app, and the somewhat-confusing-but-it-makes-sense-eventually-trust-me file naming conventions for Ruby libraries. You've also hopefully added the gem dependencies that you already know about (don't worry, you can always add more later). There's only one more thing to do: commit your code! It's great to have your first commit at this point because you haven't actually added any specific code and this serves as a baseline. So git add . and git commit -m "Initial Import" and you're on your way to building a first-class Ruby library!

Next time, we'll get our new gem set up with all of the bells and whistles you need to make open source development hum.

• Read more about Polishing Rubies: A Guide to Ruby Open Source Development (Part 1)

Welcome to the inaugural post of Polishing Rubies! In this blog post series I will be walking through the process of building and maintaining open source libraries in Ruby from the ground up.

The What and Why of Gems

Building an open source library can be a daunting task if you've never done it before. How should I structure the project? What do I need to include in terms of documentation? What tools can I use to make my library friendly for others to contribute?

We'll get to all of that. But before we do, I think it's worthwhile to examine the RubyGems system, how it works, and what exactly makes up a gem. Once you understand all of that, the idea of creating a gem will be neither confusing nor mysterious but rather just another tool in your arsenal to be used to help make your projects cleaner, more modular, as well as to help you contribute to the open source community.

This post series assumes that you have already installed Ruby on your development machine. You can visit the Ruby language download page if you need help getting started with Ruby.

RubyGems: A Package Management System for Ruby

All programming languages have support for libraries. Libraries are collections of reusable code that are usually grouped around a common purpose. There can be libraries for just about anything, from advanced processing of strings to higher level math functions to entire encapsulated applications.

While all programming languages have libraries, not all programming languages have a system to deliver those libraries as simple and elegant as RubyGems. RubyGems is an internet-aware package management system that allows for the download and installation of new libraries through the simple gem install command. RubyGems is a part of the Ruby programming language. If you have Ruby (version 1.9.2 or later), you have RubyGems.

Bundler: Tracking Your Project's RubyGems

A companion tool to RubyGems that has become indispensable for Ruby development is Bundler. Bundler is a way to manage all of the various gem dependencies for a Ruby project simply and in a single place. Bundler is itself a RubyGem and can be installed at a command line with gem install bundler.

With Bundler you can specify all of the dependencies of your application (the libraries that your application needs to function) in a single manifest file called a Gemfile. Bundler will automatically find compatible versions of the libraries you specify, and you can additionally include libraries that are checked out via git or are local to your filesystem.

Bundler is not mandatory for creating RubyGems, but it provides extremely helpful tools for library authors to automate certain processes. You will learn more about using Bundler when we create our first gem.

So What is A Gem, Anyway?

A RubyGem is essentially a specially structured folder that contains the source code, description, documentation, and tests of a Ruby library. Gems can sometimes contain command-line executables as well. The file structure of a Ruby usually looks like this:

   my-gem   ??? bin           ?   ??? my-gem    ??? lib           ?   ??? my-gem.rb    ?   ??? my-gem       ?       ??? version.rb   ??? spec (or test)   ?   ??? spec_helper.rb    ?   ??? my-gem_spec.rb   ??? my-gem.gemspec   ??? Gemfile      ??? Rakefile  

Let's go through the different parts individually to make sure we know what they all are:

• bin: This directory will contain any command-line executables that a gem has defined. For instance, the Bundler gem contains a bundler executable in this directory.
• lib: This directory houses all of your library code. The convention is that you should only define a single file at the "root" level of your lib directory. That file should be named exactly the same as your gem. All other files should go into a subdirectory in the lib directory named after your gem (the lib/my-gem directory in the example above).
• spec or test: This directory houses all of the automated tests for your gem. Nearly all open source gems have automated tests as testing ensures both maximum quality and maximum reliability for code that is being worked on by many parties such as an open source project.
• my-gem.gemspec: Every gem needs a gemspec file that is effectively all of the metadata that RubyGems needs to know about your library. We will dig into the gemspec in a later post.
• Gemfile: This is the manifest file used by Bundler to keep track of the project's dependencies. This is primarily present to make it easy for other developers to check out and work on the source code of a library.
• Rakefile: Rake is a library that allows developers to define simple "tasks" that can be performed via the rake command at the command line. Most gems have rake tasks for running specs, generating documentation, and performing release-time chores.

And really, that's pretty much it! If you're feeling a little bit overwhelmed by this list, don't worry: we will cover the needs and uses of each of these files in depth as we build our gem throughout this series. I just wanted to give you a clear overview up front of what really goes into a gem. Remember: a gem is just a folder that follows some conventions and rules, nothing more.

Why Would I Want To Create A Gem?

So now you know what a gem is but you may be wondering: why would I want to create an open source gem? There are many, many reasons why individuals and companies alike build open source projects, but here are some common benefits of open source development:

1. By encapsulating reusable code in a packaged library, you are able to reuse that code in multiple applications without rewriting the same thing over and over.
2. Individuals who release open source libraries build a reputation in the community. Most of the "well-known" Ruby developers became so by giving back to the community in the form of useful open source libraries.
3. Companies who promote open source development are more likely to attract the very best programmers, as the very best programmers in the Ruby communities tend to be deeply involved in the open source community.
4. When you release open source libraries, other people do some of the work for you! When the community can fix bugs and make improvements to common libraries it helps everyone get more done faster.

Again, there are far too many reasons to list here as to why you might want to release open source libraries. You might find some more answers in Intridea's own Open Source Citizenry blog post series.

In my next post I'll be covering the creation of the basic structure of a gem as well as getting it well-situated for automated testing, documentation, and other common needs. If you have any questions, comments, inaccuracies, or suggestions please do comment below or fork this post on GitHub. I want this to be a clear and accurate guide that can serve as a great starting point for anyone who wants to get involved in the Ruby open source world. Until next time, keep polishing those gems!

Continue to Part 2: Creating Your Gem »