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

Basic File Structure for Ruby Gem

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.

nat20.rb

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
• email
• homepage
• license= or licenses=
• metadata

Once you’ve got your gemspec file built, you can create your gem and test it out locally!

nat20.gemspec

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.gem
Successfully 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.

1. 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: true
source "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!

nat20_spec.rb

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!

RubyGems.org | your community gem host

nat20 | RubyGems.org | your community gem host

johneckert/nat20