How To Make A Ruby Gem
Ruby Gems are awesome! They allow us to add little bits of functionality to our projects without having to waste time reinventing the wheel. The great thing about them is that anybody can make one… and here’s how!
Step 1— The Basics
To begin, you will need two things a RubyGems account and an idea of what you want your gem to do.
What makes a good gem? A great place to start is to try to think of anything you find yourself repeatedly implementing in multiple projects.
I decided to make a gem that contained functions for rolling different combinations of dice in the style of tabletop RPGs. It will allow users to phrase the arguments to the dice rolling methods exactly how they would speak them. For example, to roll two six-sided dice, the user will be able to enter '2d6'
as the argument to the dice rolling method. My gem is probably not going to change the world, but it seemed like a decent amount of functionality for a trial run.
Step 2 — Naming
You’ll want to consider how users will access the different methods in your gem. This means developing a good naming structure for the gem itself, your files and your classes.
Gems all have to have unique names, so once you have an idea of what you want to call your gem, it’s a good idea to check RubyGems and make sure that there isn’t already a gem with that name. In my case there are already a bunch of dice rolling gems, so most of the names involving the word dice were taken. I decided to call my gem Nat20, which is again a reference to table top RPGs, and rolling a 20 on a twenty-sided die.
Step 3 —Directory & File Structure
The picture above is the basic file structure for our gem. All we need to get started is a gemspec file and a lib folder to contain the ruby file (or files) with our code in it.
In the case of my silly little gem we just have a nat20.rb file which contains a Nat20 class. The class contains two methods that are accessible by the user and a bunch of private methods for pulling relevant information out of the arguments entered by the user.
Step 4 — Gemspec
The gemspec file is what defines things like the description of the gem, who made it, the version, and other information that gets packaged with the gem. It communicates directly with rubygems.org. The gemspec file is written in Ruby, which is great because it means you can insert code into it to automate certain actions, like changing the version number, release date, or anything else you need to do.
The gemspec also excepts a large variety of attributes. Some of them are required, but many are optional. A full list of attributes is available here.
The required attributes are:
- files
- name
- summary
- version
There is also a list of recommended attributes. These include:
- author= or authors=
- description
- homepage
- license= or licenses=
- metadata
Once you’ve got your gemspec file built, you can create your gem and test it out locally!
Step 5 — Building
At this point, we have everything we need for working gem. Let’s build it!
gem build nat20.gemspec
If it all works as planned you should see something like:
Successfully built RubyGem
Name: nat20
Version: 0.0.0
File: nat20-0.0.0.gem
You should also see a .gem
file in your root directory. Now the gem can be installed locally.
gem install ./nat20-0.0.0.gemSuccessfully installed hola-0.0.0
1 gem installed
With our new gem installed on the local machine, we can start testing.
The next step is to start irb and see if the gem is working.
irb
> require 'nat20'
=> true
> Nat20.roll '2d4+2'
=> 8
Awesome! It seems to be working just fine.
Step 6-Testing
Testing is essential for gems. Not only does it ensure that our gem is working correctly and that it continues to do so, but it let’s other developers know that our gem does what it says it does. So in short, if you want other people to use your gem — Write Tests!!
I decided to use RSpec to write tests for my gem, so I needed to add a few things to get it working.
- We need to add the Rspec gem as a dependency. We do that by adding the following line to the gemfile.
s.add_development_dependency 'rspec', '~> 3.7'
2. Next, we need to create a Rakefile to do that we can create a new file called Rakefile
and put the following code in it, which tells RSpec where to look for the tests:
require 'rspec/core/rake_task'
require 'bundler/gem_tasks'# Default directory to look in is `/spec`
RSpec::Core::RakeTask.new(:spec)task :default => :spec
3. We should also add a Gemfile
that specifies our RSpec dependency which should contain the following:
# frozen_string_literal: truesource "https://rubygems.org"git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }# gem "rails"
gem 'rspec', :require => 'spec'
4. Now, all we need to do is create a spec folder in the root directory of our project and create a test file inside of it. Now we can run bundle install, and our file structure should look like this.
After writing the tests and making sure everything works as expected, we can rebuild our gem using the gem build
command like we did previously and get ready to publish it!
Step 7-Uploading
Now that we have a fully functional gem, it’s time to upload it! To upload the gem to RubyGems, we can use the push command in the terminal.
gem push nat20-0.0.0.gem
You’ll be prompted for your email and password, and once you do that your gem will be registered, and everyone will be able to use your code!