How To Work With The Ruby Package Manager RubyGems: Getting Started

Introduction

---

The RubyGems is a tool which manages Ruby application packages’ lifecycle from creation to distribution. If you have ever worked with a Ruby based application, chances are you have used RubyGems to manage dependencies, libraries, or frameworks (e.g. Ruby-on-Rails).

In this DigitalOcean article, we will learn all the important bits and pieces of RubyGems, from the most basic to more advanced features. If you are planning to work with (or use) Ruby in the long run, mastering this tool can translate to a great deal of efficiency for your work.

Glossary

---

1. Package Managers And The RubyGems

---

1. What Is A Package Manager?
2. Application Packages
3. What Is RubyGems?
4. What Is A Gem?

2. RubyGems Gem Package Format

---

1. Gem Information And Format
2. The `*.gemspec` File

3. Getting Started With RubyGems

---

1. Installing Ruby And RubyGems
2. Usage

4. Main RubyGem Operations To Work With Gems

---

1. Finding Installed And Available Gems
2. Searching RubyGems.org For Gems
3. Installing New Gems
4. Finding Outdated Gems
5. Updating Gems
6. Removing / Deleting Gems
7. Reading The Gem Documentation

Package Managers And The RubyGems

---

What Is A Package Manager?

---

In terms of computers, almost everything consists of connections and collections between different programs. The moment you start the machine, a bunch of code gets executed, which in turn loads some others. A pyramid gets built, forming the final platform, allowing you to run the higher-level applications you require (e.g. Ruby!).

As you can see from the above basic portrayal of application execution lifecycle, everything is dependant on others when it comes to programs. And this cycle starts during the development phase.

In order to facilitate the download and installation procedure of libraries that programs depend on, especially nowadays, a set of tools referred to as package managers are heavily used. These tools make it very easy to find, install, and keep track of all other libraries that, as a developer, your programs need.

Application packages which are distributed via these tools are generally simple archives containing programs and metadata. Different package managers exist to manage different programming languages’ dependencies – and they each name their packages differently.

Application Packages

---

Simply put, application packages contain already compiled and ready-to-use software or libraries which others use. They can (and usually do) come with additional files to give information about the package, and despite the importance, only sometimes with a decent usage manual. Once the package manager installs a package, all these elements become accessible inside the environment they are set (e.g. an RVM Gemset).

What Is RubyGems?

---

In the case of Ruby, the default package manager is called the RubyGems. This program has been distributed with the default Ruby interpreter since version 1.9 and helps you with many things from downloading to packaging and distributing Ruby applications – and of course, relevant binaries and libraries. RubyGems is very rich, and probably one of the most mature package management applications that exists. It provides the developers a standard structure, along with a standard format to deal with application collections (packages) called Gems.

What Is A Gem?

---

A Gem is an application package very similar in structure to the generic description we have just given. It can be a collection of code, libraries, list of dependencies and some additional meta-data, defining the package that gets distributed with the RubyGems tool.

The simplest way to start working with programs is to use these bundles when developing Ruby based (or Ruby related) applications. In this tutorial, we are going to learn how to use the RubyGems to work with and handle Gem based packages.

RubyGems Gem Package Format

---

Gem Information And Format

---

As we have mentioned previously, a Gem is a package that contains different sets of components. Each Gem has a version and a basic definition of the platform it was built for.

The Gem directories can contain the following:

• Application code;

• Tests;

• Description of dependencies;

• Binaries;

• Relevant Documentation;

• Information regarding the package (e.g. gemspec).

And they have a basic structure similar to the following:

/[package_name]               # 1
        |__ /bin              # 2
        |__ /lib              # 3
        |__ /test             # 4
        |__ README            # 5
        |__ Rakefile          # 6
        |__ [name].gemspec    # 7

1. [package_name]:
   The main root directory of the Gem package.

2. /bin:
   Location of the executable binaries if the package has any.

3. /lib:
   Directory containing the main Ruby application code (inc. modules).

4. /test:
   Location of test files.

5. Rakefile:
   The Rake-file for libraries which use Rake for builds.

6. [packagename].gemspec:
   *.gemspec file, which has the name of the main directory, contains all package meta-data, e.g. name, version, directories etc.

The gemspec File

---

Pretty much like any application collection that is distributed or shared, Gems also come with a file describing the package, which also tends to contain some very useful additional information.

These gemspec files contain certain required data, such as the package version, maintainer name and platform, with the possibility of some optional attributes such as keys, contact information or additional description.

A gemspec file looks similar to the following example:

Gem::Specification.new do |s|
  s.name        = 'myapp'
  s.version     = '1.5.7'
  s.licenses    = ['Apache']
  s.summary     = "My application package"
  s.description = "Optional, longer description."
  s.authors     = ["Maintaner Name"]
  s.files       = ["path/to/files", "additional/files", ..]
end

Getting Started With RubyGems

---

Installing Ruby And RubyGems

---

If you have not installed Ruby, and thus the RubyGems, you can follow one of the two links below to get it on your platform of choice.

• CentOS / Rhel:
  How To Install Ruby 2.1.0 On CentOS 6.5 Using RVM

• Ubuntu / Debian:
  How To Install Ruby 2.1.0 On Ubuntu 13 With RVM

Usage

---

Working with RubyGems is very easy. Once you install Ruby, the application should be set up in your PATH and you can start using the tool by typing gem inside the terminal emulator (e.g. Terminal for OS X, Putty for Windows etc).

Run gem to see some usage instructions and examples:

gem

# RubyGems is a sophisticated package manager for Ruby.  This is a
# basic help message containing pointers to more information.

# Usage:
#     gem -h/--help
#     gem -v/--version
#     gem command [arguments...] [options...]

As you can see, working with gem consists of chaining a command with arguments and options, e.g.:

gem help commands

# GEM commands are:

# build             Build a gem from a gemspec
# cert              Manage RubyGems certificates and signing settings
# check             Check a gem repository for added or missing files
# ..

Tip: When you run a command like ruby or rake, your operating system searches through a list of directories to find an executable file with that name. This list of directories lives in an environment variable called PATH, with each directory in the list separated by a colon:

/usr/local/bin:/usr/bin:/bin

Directories in PATH are searched from left to right, so a matching executable in a directory at the beginning of the list takes precedence over another one at the end. In this example, the /usr/local/bin directory will be searched first, then /local/bin, then /bin.

When you install Ruby, both the ruby interpreter and the RubyGems’ gem get added to your PATH.

Main RubyGem Operations To Work With Gems

---

Beginning to learn a new programming language also means learning to work with the basic and common related tools, such as the RubyGems for Ruby. Without over-complicating things, let’s see the basic operations that you need to know when getting started with this package management tool.

Usually, the main operations with any package manager can be considered as:

• Finding out what is installed on the system;

• Searching for and discovering new packages;

• Finding out which packages need updating;

• Installing new ones;

• Updating old ones;

• Removing (or deleting) packages;

• Cleaning up what is no longer needed;

• Checking out the documentation.

Let’s see how to perform these operations with RubyGems.

Finding Installed And Available Gems

---

You can think of finding all the currently installed gems as getting a list of their names.

Hence remembering that the list command is what you need for this operation.

Run the following to get a list of installed gems with their versions:

gem list

# ** LOCAL GEMS ***

# actionmailer (4.0.2)
# actionpack (4.0.2)
# activesupport (4.0.2)
# bundler (1.5.3, 1.5.2)
# capistrano (3.1.0)
# coffee-rails (4.0.1)
# coffee-script (2.2.0)
# coffee-script-source (1.7.0, 1.6.3)
# execjs (2.0.2)
# i18n (0.6.9)
# ..

Searching RubyGems.org For Gems

---

If you already know the name of a gem, you can use the search command to look for it.

In return, you will again have a list of gems and their versions.

Run the following to search for a gem by name:

# Usage: gem search [name]
# Example:
gem search rails

# *** REMOTE GEMS ***

# rails (4.0.2)
# rails-3-settings (0.1.1)
# rails-action-args (0.1.1)
# rails-admin (0.0.0)
# .. 

Note: You can use regular expressions with the gem name queried. You can also pass the -d flag to get additional information, e.g.:

gem search rails_utils -d

# *** REMOTE GEMS ***

# rails_utils (2.1.4)
#     Author: Winston Teo
#     Homepage: https://github.com/winston/rails_utils
# 
#     Rails helpers based on opinionated project practices.

Installing New Gems

---

Once you have found a gem you would like to install, you can simply use the install command.

Run the following to install a new gem:

# Usage: [sudo] gem install [name]
# Example:
gem install rails_utils

# Fetching: rails_utils-2.1.4.gem (100%)
# Successfully installed rails_utils-2.1.4
# Parsing documentation for rails_utils-2.1.4
# Installing ri documentation for rails_utils-2.1.4
# Done installing documentation for rails_utils after 0 seconds
# 1 gem installed

Note: When you install a new gem, all the dependencies specified within the gem are also installed so that the gem can actually work.

In order to download a specific version of a gem, use the following:

# Usage: [sudo] gem install [name] -v [version]
# Example:
gem install rails -v 4.0

Finding Outdated Gems

---

In order to find out which gems are outdated (i.e. a newer version exists), you can use the outdated command. This, again, will provide you a list of gems with their currently installed versions (i.e. local gems).

Run the following to find out which gems are outdated:

gem outdated

# builder (3.1.4 < 3.2.2)
# bundler (1.5.2 < 1.5.3)
# coffee-script-source (1.6.3 < 1.7.0)
# jquery-rails (3.0.4 < 3.1.0)

Updating Gems

---

After you see which gems need updating, you can simply do so using the update command.

Run the following to update a gem:

# Usage: [sudo] gem update [name]
# Example:
gem update bundler

# Updating installed gems
# Updating bundler
# Fetching: bundler-1.5.3.gem (100%)
# Successfully installed bundler-1.5.3
# Parsing documentation for bundler-1.5.3
# Installing ri documentation for bundler-1.5.3
# Installing darkfish documentation for bundler-1.5.3
# Done installing documentation for bundler after 6 seconds
# Gems updated: bundler

Removing / Deleting Gems

---

Removing a gem from your local machine is done with the uninstall command, similarly to the install.

Run the following to remove / delete a gem:

# Usage: [sudo] gem uninstall [name]
# Example:
gem uninstall bundler

Alternatively, you can specify a version to remove that one only.

# Usage: [sudo] gem uninstall [name] -v [version]
# Example:
gem uninstall bundler -v 1.0.0

# Successfully uninstalled bundler-1.0.0

Reading The Gem Documentation

---

One of the most handy and important things about gems is that they [should] come with good documentation to allow you to start working with them fast. The simplest way to go with documentation is to run a local server where you will have access to all installed gems’ usage instructions.

Run the following to run a documentation server:

gem server

# Server started at http://0.0.0.0:8808
# Server started at http://[::]:8808

You can now access http://0.0.0.0:8808 using your favourite browser, find the gem you would like to learn more about and read its documentation.

<div class=“author”>Submitted by: <a href=“https://twitter.com/ostezer”>O.S. Tezer</a></div>