A gem is a simple way to distribute functionality, it can be a small plugin, a Ruby library or sometimes a whole program. Thanks to RubyGems, a gem hosting service, developers have a wide range of gems at their disposal allowing them to easily add functionality to their applications.
But what if there is no gem available that will suit the functionality you need, and you find yourself writing the same code over and over again for different projects? Well, in that case you should consider making your own gem.
It’s considered a good practice to extract a gem out of an existing application, since that way you will have a better understanding of all the requirements as well as how the gem will be used. This blog post will illustrate just that on a real life example, and will take you through the process of creating a slug_converter gem.
Slug converter gem
Source code for slug_converter gem was developed while working on a link shortener application, in order to generate a string consisting of predefined characters, based on a given id number of a link. As it will be described in this blog post, this code was easily extracted from the application into an independent gem that was released on RubyGems.
Although it may seem like a complex task at first, creating a gem is not that difficult, if you have RubyGems and Bundler installed you are good to go. We already know what RubyGems is, and Bundler is a package manager that determines a full set of direct dependencies needed by your application.
Now let’s build a gem!
Creating a gem
First step is to make sure that bundler gem is installed.
once bundler is installed creating a structure for your new gem is easy,
The first time you use bundler to create a gem you will be prompted to answer a couple of questions:
1 2 3 4
Answering these questions will help bundler configure and setup files that are being generated now and in the future. Here we answered yes to first 4 qestions and choose rspec for testing.
$ bundle gem slug_converter command resulted with “slug_converter” directory with essential gem file structure being created, and git repository initialized, assuming that you are using git for version management (as you should).
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
Let’s go through files that bundler generated for us, .gemspec file is the “heart” of your gem so lets start with
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
This file contains metadata about your gem and it can be populated directly, so here you can enter all the data such as name, description, licence… This file also contains information about what files should be packaged in your gem, as well as the load path to include the gem directory when the gem is first loaded. Most of these default settings will work for the majority of gems but you can always edit them if you want different behavior. At the bottom of the file add any gem dependencies that are required.
The version number of the gem is set in
SlugConverter::VERSION constant which is kept in a separate version.rb file, and you can change it there for every new version of your gem.
lib |--slug_converter |--version.rb
A very important part of every gem is the
README file, where you can describe how to install and use the gem, and the
LICENCE file where you can define the terms and conditions under which the gem can be used.
In the lib directory there is a file which has the same name as your gem (recommended), and that file will be loaded when someone requires your gem. If the gem you are writing is simple all the code can be placed in this single file, or in case of more complex gems all the other files from the lib directory are required in this file.
There is also a
Gemfile generated, but this file doesn’t have to be managed directly since all it does is look in
.gemspec for required dependencies and then loads them through bundler. All the dependencies required by the gem should be specified in the
Another file that is generated by the bundler is
Rakefile which just adds some gem tasks from bundler, and we can see those tasks with explanation by running
1 2 3 4
If you are following the principles of Test Driven Development you will probably like to start by writing tests for you gem, for that purpose I would suggest using RSpec. To do that you will need to add rspec as a development dependency to you gemspec file:
As mentioned in the beginning, when running bundle gem for the first time, bundler will asks if you would like to generate test files for your gem and to choose if you want to use rspec or minitest. If you answer with yes, and choose rspec, bundler will generate a spec directory with two files:
|-- spec |-- slug_converter_spec.rb |-- spec_helper.rb
spec_helper.rb file you can reference any test globals or configuration.
Since we are extracting code from an existing application we already have all the tests written so we just need to copy them into the generated
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99
To make rspec rake task available we will setup tasks folder where we’ll place our
rspec.rake file containing only 2 lines:
and then we will import this file in our Rakefile that bundler provided automatically:
And watch your tests fail. :)
Add gem functionality
Now we need to make those test go green. To do that we will again copy the existing code from our application in the main gem file
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78
Now when we run the tests again, they should all pass.
Making your gem configurabile
In order to allow users to set their own alphabet that will be used by the SlugConverter, we needed to make our gem configurabile. To do this we used https://github.com/krautcomputing/gem_config gem.
You will notice this code at the begining of the SlugConverter class:
1 2 3 4 5 6 7 8 9 10 11 12 13 14
this code along with
spec.add_runtime_dependency 'gem_config' added as a dependency in
slug_converter.gemspec file, alows us to make the gem configureabile.
Custom aphabet can than be defined by adding
config/initializers/slug_converter.rb to your application, and defining the alphabet like this:
Releasing your gem
Now that we have the test passing and all the code in place it’s time to make the gem available for everyone to use by releasing it on RubyGems, to do that you will need to have a RubyGems account. If this is the first time you release a gem you will be prompted to enter your RubyGems username and password. You will also need to have your repository setup on Github.
Then with just one comand:
- your code will be pushed to your Github repository,
- your git repository will be tagged with the version number using a name like “v1.0.0”.
- your gem released on RubyGems.