Publishing and Versioning a Rubygem

In the last two tutorials we've built a gem and added tests and documentation. We're going carry on working with the same gem, first publishing it on Rubygems.org and GitHub, and then finishing it off by adding an executable.

Publishing on Rubygems.org

If you've been following along, you should already have a listless-0.0.1.gem package sitting on your computer and ready for upload to rubygems.org.

You'll need to sign up for an account if you don't already have one, keeping a note of your username and password.

You'll also need to download and store your personal API key from the site before you can upload. Run the following command, remembering to add your own username and entering the password you signed up with.

$ curl -u username https://rubygems.org/api/v1/api_key.yaml > ~/.gem/credentials
Enter host password for user 'alexedwards':

Once that's done, actually publishing the gem is surprisingly simple – just run gem push on the package.

$ gem push listless-0.1.0.gem
Pushing gem to https://rubygems.org...
Successfully registered gem: listless (0.0.1)

Publishing on GitHub

If you're a GitHub user, it can also be a nice idea to publish the gem source code (not the .gem file this time) on there. That makes it possible for people to use the gem straight from the git repository like so:

gem 'listless', :git => 'git://github.com/alexedwards/listless.git'

Adding an Executable

Next we're going to create a simple executable, so that the functionality in our Gem can be used directly from a terminal.

In this instance we're going to a make a listless executable, which takes a comma-separated values string as an argument and turns it into a HTML list. Sure, it's a trivial and not-very-useful example, but hopefully it illustrates the important steps nicely enough 😊

Go to the root of the Gem directory and create a bin/listless file, then set the permissions so that it's executable.

$ mkdir bin
$ touch bin/listless
$ chmod 755 bin/listless

The complete structure of our Gem should now look like this.

$ tree
.
├── bin
│   └── listless
├── Gemfile
├── lib
│   ├── listless
│   │   └── version.rb
│   └── listless.rb
├── LICENSE.txt
├── listless-0.1.0.gem
├── listless.gemspec
├── Rakefile
├── README.md
└── spec
    └── listless_spec.rb

Open the bin/listless file and add the following code.

#!/usr/bin/env ruby
require 'listless'

array = ARGV[0].split(',')
puts Listless.ul(array)

The first line of the file (called a hashbang line) tells the shell what program to execute the file with (in this case, Ruby). The rest of the file is plain Ruby code.

We'll install the executable properly in a moment, but for now let's quickly check it works with the following command:

$ ruby -Ilib ./bin/listless "foo,bar,baz"
<ul><li>foo</li><li>bar</li><li>baz</li></ul>

As an aside, if you take a look at the listless.gemspec file you'll notice a gem.executables line, piggybacking on our Git repository again. If this wasn't already there, then we'd have needed to add the path to the executable manually.

$ git add .
$ git commit -m 'add: executable for converting CSV strings'

Increment version

Now is a good time to increment the version number. I recommend following the semantic versioning guidelines, which are generally used by the Ruby community when it comes to updating gems.

Let's bump our version from 0.0.1 to 0.1.0 by editing the lib/listless/version file.

module Listless
  VERSION = "0.1.0"
end

Again, remember to commit the change.

$ git commit -a -m 'bump version'

Install the executable

Lastly rebuild and reinstall the gem on your local machine.

$ gem build listless.gemspec
Successfully built RubyGem
Name: listless
Version: 0.1.0
File: listless-0.1.0.gem
$ sudo gem install --local listless-0.1.0.gem

In the process of installing the new version of our gem, the executable should have been stored on your system path and the listless command should now be available. Let's give it a try.

$ listless "foo,bar,baz"
<ul><li>foo</li><li>bar</li><li>baz</li></ul>

Wrapup and Source Code

You can find the full source code for this gem on GitHub.