How to build a Ruby Gem?

What is a Gem?

A gem is essentially a Ruby plugin.

Ruby gems makes life much, much easier. Rather than including third party code directly into your application, you just reference the name (and optionally version) of the gem you want to use in your Gemfile, and then run bundle install.

The bundler will load full set of dependencies needed by your application. The code for gem is still downloaded to your system, but it is kept separate from your application, so you don’t have to maintain it in the source control.

Why a Gem?

One of the most obvious reasons relates to code reuse. If you find yourself implementing the same feature over and over again across projects, there's a good chance that you've found the need for a gem.

Releasing a gem as open-source provides others the opportunity to contribute by adding features, addressing issues that you might have overlooked, and generally making your gem provide an all-around better experience for its users.

Making your Ruby Gem

If you haven't yet, you will need to install bundler gem like this

$ gem install bundler

Next, please follow the steps below:

Step 1: Generate a skeleton for your gem

$ bundle gem <gemname> 

Don't put dashes in your gemname, underscores are ok

My gem name is codec62, so I did

$ bundle gem codec62 

The output I got is

create  codec62/Gemfile
      create  codec62/Rakefile
      create  codec62/LICENSE.txt
      create  codec62/README.md
      create  codec62/.gitignore
      create  codec62/codec62.gemspec
      create  codec62/lib/codec62.rb
      create  codec62/lib/codec62/version.rb
Initializing git repo in /Users/bhargavi/Turing/session4/codec62

Gemfile - track versions of all the dependencies our gem needs
Rakefile - is to make tools for building things
License - is for license, rubiest most fav is MIT license
Readme - it’s a pretty ok read to start with
.gitignore - decent ignore file for git so that we don't check bad things in. Normally, if you were building an app, you'd check this in, but when you're making a gem, you don’t
gemspec - This file specifies all the metadata for our gem
lib/codec62 - is the file that is required when we say require “codec62” in a ruby program
version.rb - has the version of our gem. we'll edit this file when we're about to release a new version of the gem.

Step 2: Setting the test environment

cd into your gem directory and make a test directory and test file to write your tests

$ cd codec62 
$ mkdir test 
$ atom test/codec62_test.rb

I am using atom editor

We will also add these lines to our Rakefile

require "bundler/gem_tasks"

require "rake/testtask"

Rake::TestTask.new do |t|
  t.test_files = FileList['test/*_test.rb']
end

task default: :test

Step 3: TDD for our Gem

Let's write some test in our test/codec62_test.rb file

require "minitest/autorun"
require "minitest/pride"
require "codec62"

class Codec62Test 

Our test will fail because we don't have any code in our lib/codec62.rb

$ rake 

To pass our test we put this code in our lib/codec62.rb

require "codec62/version"

module Codec62
  Message = "This is my gem"
end

$ rake

Run options: --seed 34746
\# Running tests:
.
Fabulous tests in 0.000821s, 1218.0268 tests/s, 1218.0268 assertions/s.
1 tests, 1 assertions, 0 failures, 0 errors, 0 skips

Step 4: Adding an executable

Executables are stored in bin so we make directory bin

mkdir bin

To make it executable we write this code into codec62 file in bin

\#!/usr/bin/env ruby

require 'codec62'

puts Codec62::Message

This is actually a script. We don't add an extension, but we do use a 'shebang' line to tell the shell that this is a Ruby script. We will make this file executable later after intalling our gem.

Step 5: Writing some doc

Being a good programmer documentation is very important. We will add some comments to our lib/codec62.rb and lib/codec62/version.rb

Rdoc will parse these comments to generate documentation.

rdoc lib

Step 6: Push to Github

Before we push to github, let's fix our README.md file and codec62.gemspec. Change all the TODOs with documentation. Then push your work to github.

$ git add .
$ git commit -m "my codec62 gem"
$ git push 

Step 7: Release to RubyGems

Run this command to make your bin file executable

$ chmod +x bin/codec62

and the install your rubygem by running this command

$ rake install 

If you have not updated your TODOs, rake install will not work Your Ruby Gem is still not released to the ruby community and is still private. To release change the version to 1.0.0 in your lib/codec62/version.rb file, then

$ ga .
$ git commit -m "fixed the version"
$ git push
$ rake release

Now your Ruby Gem is published!
Great!!
You can tell the whole world!!

references:
https://howistart.org/posts/ruby/1 Quickleft doc