How to create your own gem

#ruby #gem #bundle

Introduction

In this post, I am going to demonstrate how to create and publish your own ruby gem. I'll create and publish a very simple gem called spell-generator. Additionally, I'll install and use it in my other ruby program.

Create your first gem
What does a gem consist of?
Publish your gem
How to use your gem
More Resources

Create your first gem

You can generate foundations of your gem by running the command below. It will generate basic files and directories that you need to start developing your gem. It is sort of like running rails new command to create a RoR application.

$ bundle gem spell_generator

If you successfully run the command above, it would look like this.

Creating gem 'spell_generator'...
MIT License enabled in config
Code of conduct enabled in config
      create  spell_generator/Gemfile
      create  spell_generator/lib/spell_generator.rb
      create  spell_generator/lib/spell_generator/version.rb
      create  spell_generator/spell_generator.gemspec
      create  spell_generator/Rakefile
      create  spell_generator/README.md
      create  spell_generator/bin/console
      create  spell_generator/bin/setup
      create  spell_generator/.gitignore
      create  spell_generator/.travis.yml
      create  spell_generator/.rspec
      create  spell_generator/spec/spec_helper.rb
      create  spell_generator/spec/spell_generator_spec.rb
      create  spell_generator/LICENSE.txt
      create  spell_generator/CODE_OF_CONDUCT.md
Initializing git repo in /Users/katsuki/Desktop/Ruby/spell_generator
Gem 'spell_generator' was successfully created. For more information on making a RubyGem visit https://bundler.io/guides/creating_gem.html

Naming a gem

The name of a gem is not just a random collection of letters. There is a strict guideline to follow when you name a gem.

every dash(-) represents a structure (folder, module) immersion
every underscore(_) represents a joining in the class name

What does a gem consist of?

Let's briefly go through directories and files that were created by bundle gem command.

lib directory: Code for your gem is placed within this directory.
spec directory: You can write test code for your gem within this directory.
gemspec: The information about the gem is listed here. For instance, information like what’s in the gem, who made it, and the version of the gem.

Let's write some code in your gem

As I mentioned above, code for your gem is placed within lib. It is the convention to have one Ruby file with the same name as your gem under lib since that file gets loaded when require your_gem is run. That file is in charge of setting up your gem's code and API. (If you run bundle gem command, this file with the same name as the gem's name will be automatically generated.)

#spell_generator/lib/spell_generator.rb

require_relative "spell_generator/version.rb"

module SpellGenerator
  SPELL_SET1 = %w(accurate sufficient ugly useful immediate entire healthy hot efficient dramatic)
  SPELL_SET2 = %w(punch kick attack blow smash strike smack cut poke stab)
  class Generator
    def self.generate
      new.generate
    end

    def generate
      "#{SPELL_SET1[rand(0..9)]} #{SPELL_SET2[rand(0..9)]}"
    end
  end
end

Although it is possible to write all the code in this file, having everything in one file does not scale well. So you can add more files to the directory which also has the same name as your gem and is also automatically generated by the bundle gem command.

--lib
 --spell_generator
    - generator.rb
    - spells.rb
- spell_generator.rb

#spell_generator/lib/spell_generator.rb

require_relative "spell_generator/version.rb"
require_relative "spell_generator/generator.rb"

module SpellGenerator
end

#spell_generator/lib/spell_generotor/spells.rb

SPELL_SET1 = %w(accurate sufficient ugly useful immediate entire healthy hot efficient dramatic)
SPELL_SET2 = %w(punch kick attack blow smash strike smack cut poke stab)

#spell_generator/lib/spell_generotor/generator.rb

require_relative 'spells'

class SpellGenerator::Generator
  def self.generate
    new.generate
  end

  def generate
    "#{SPELL_SET1[rand(0..9)]} #{SPELL_SET2[rand(0..9)]}"
  end
end

Publish your gem

You have to modify spec.summary, spec.description, spec.homepage and spec.respond_to? of your gemspec file before you publish your gem. You have to replace the original texts with your own. Your gemspec would look something like this after replacing them.

  spec.name          = "spell_generator"
  spec.version       = SpellGenerator::VERSION
  spec.authors       = ["K-Sato"]
  spec.email         = ["your_email@example.com"]

  spec.summary       = %q{short summary,}
  spec.description   = %q{description}
  spec.homepage      = "https://github.com/K-Sato1995/hola_sato/blob/master/spell_generator.gemspec"
  spec.license       = "MIT"

  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
  # to allow pushing to a single host or delete this section to allow pushing to any host.
  if spec.respond_to?(:metadata)
   spec.metadata["allowed_push_host"] = 'https://rubygems.org'
  else
   raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
  end

Next, you should commit all the files and directories you have created so far and push it to github.

$ git add .
$ git commit -m 'initial commit'
$ git push origin master

Lastly, you can release your gem by running rake commands below.

$ rake build 
$ rake release

How to use your gem

It is really easy to use your gem once your gem in up and running on github. If you want to use your gem on your rails application, you can add the gem to your gemfile and run bundle install.
If you want to use your gem in another ruby file, install the gem on your console and add the lines below in your file.

$ gem install gem-name

require 'rubygems'
require 'gem-name'

For instance, if I want to use the gem I just created in this post, I can do so by installing the gem and adding the lines above in my ruby file.

$ gem install spell_generator

require 'rubygems'
require 'spell_generator'

Class.new(SpellGenerator::Generator).tap do |klass|
  p klass.generate #=> "immediate cut"
  p klass.new.generate #=> "dramatic smack"
end