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.
Once that's done, actually publishing the gem is surprisingly simple – just run
gem push on the package.
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:
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.
The complete structure of our Gem should now look like this.
bin/listless file and add the following code.
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:
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.
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.1.0 by editing the
Again, remember to commit the change.
Install the executable
Lastly rebuild and reinstall the gem on your local machine.
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.
Wrapup and Source Code
You can find the full source code for this gem on GitHub.