Creating a Ruby Gem Cheatsheet

ruby-gem-cheatsheet.md

Creating a Ruby Gem Cheatsheet

Here you are the basics to create a Ruby Gem, with some appendix about interesting use cases. This guide tries to cover the minimum requirements to create a Gem using Ruby conventions. For more information, navigate to this link to see what is a Gem.

Step 0 - Have a good README

Most of Ruby Gems have lack of documentation, usage guides and examples. In order to make the usage comfortable would be important to have a robust guide.

Step 1 - Create bin, lib and test folders

• bin - This folder will be loaded in the system PATH to enable the execution of the files contained within it.
• lib - Container of the Gem code itself.
• test - Holds the unit testing scripts.

Step 2 - Version.rb

Have a file in lib/<gem-name>/version.rb enables reading version from the application and from bundler. This version file is also imported into gemspec file to specify version changes in the gem.

# frozen_string_literal: true

module Gem
  VERSION = '0.1.0'
end

Step 3 - Gemspec file

This file contains all the definition and description of the gem. It is usually named gem-name.gemspec. Detailed section are described below:

# frozen_string_literal: true

# Append the contents of the lib directory into the Ruby Load Path.
lib = File.expand_path('lib', __dir__)
$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)

require '<gem-name>/version'

Gem::Specification.new do |spec|
  spec.name          = 'This is the gem name, used when compiling and publishing it, and it is REQUIRED'
  spec.version       = GEM::VERSION # Imported from lib/<gem-name>/version.rb, this is REQUIRED.
  spec.authors       = ['Authors list... this can come from a lib/<gem-name>/authors.rb']

  spec.summary       = 'Short summary of the gem, it is REQUIRED'
  spec.description   = 'A more detailed summary of the gem'
  spec.homepage      = 'Homepage... if any'
  spec.licenses      = 'MIT or whatever'

  # Files to be included in the gem (REQUIRED), i.e. below way to get files from Git repository.
  spec.files       = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(scripts|test)/}) }
  spec.bindir      = 'bin'         # Executables path.
  spec.executables << 'executable' # Executable file(s).
  spec.require_paths = %w[lib]     # And/Or another path.

  ##
  # Development dependencies
  spec.add_development_dependency 'add dev dependencies in alphabetical order', '~> and its version'
  
  ##
  # Runtime dependencies
  spec.add_runtime_dependency 'The same for runtime ones', '~> 1.2.3'
end

Step 4 - Gemfile

We should create the Gemfile to allow Bundler install Gem dependencies. With the changes done in step 3, the Gemfile will finish as follows:

# frozen_string_literal: true

source 'https://rubygems.org'

gemspec

Step 5 - Include Rubocop.

Install Rubocop as a CLI (as it is recommended) using gem install rubocop. Having this and executing rubocop on the command line will check code agains standard Cops.

To customize Cops, create a .rubocop.yml file and customize there Cops params, as for example:

AllCops:
  TargetRubyVersion: 2.3
Metrics/LineLength:
  Max: 110
Metrics/MethodLength:
  Max: 25
Metrics/AbcSize:
  Max: 30

To have Rubocop integrated as a Linter with Arcanist/Phabricator, create an .arclint file as below:

{
  "linters": {
    "Ruby Rubocop": {
      "type": "rubocop",
      "include": "(\\.rb$)"
    },
     "Ruby ": {
      "type": "ruby",
      "include": "(\\.rb$)"
    }
  }
}

Appendix A - Common Dependencies

List of common development dependencies:

Gem	Website	Usage
Bundler	https://bundler.io/	The gem par excellence for dependency tracking in Ruby
Rake	https://github.com/ruby/rake	This allows to create executable tasks for code, i.e. run unit testing
Minitest	https://github.com/seattlerb/minitest	The standard library to unit test your code in Ruby
Faker	https://github.com/stympy/faker	A good and funny library to generate mock data in Unit Testing