What is a gem?
Learn what a gem can do for your Ruby applications, and what’s inside of one.
A RubyGem is a software package, commonly called a “gem”. Gems contain a packaged Ruby application or library. The RubyGems software itself allows you to easily download, install, and manipulate gems on your system.
Each gem has a name, version, and platform. For example, the rake gem has a
0.8.7 version. Rake’s platform is
ruby, which means it works on any platform Ruby runs on. Other platforms include
java (like nokogiri) and
mswin32 (like sqlite-ruby).
Gems can be used to extend or modify functionality within a Ruby application. Commonly, they’re used to split out reusable functionality that others can use in their applications as well. Some gems also provide command line utilities to help automate tasks and speed up your work. As of Ruby 1.9.2, RubyGems is included when you install the programming language, so gems are both ubiquitous and extremely useful. If you’re using an earlier version of Ruby, it’s simple to install RubyGems as an addon.
For information on installing or upgrading RubyGems, please visit the RubyGems.org download page.
Structure of a Gem
Gems contain three components:
- Code (including tests and supporting utilities)
Each gem follows the same standard structure of code organization:
% tree freewill freewill/ ├── bin/ │ └── freewill ├── lib/ │ └── freewill.rb ├── test/ │ └── test_freewill.rb ├── README ├── Rakefile └── freewill.gemspec
Here, you can see the major components of a gem:
libdirectory contains the code for the gem
specdirectory contains tests, depending on which test framework the developer uses
- A gem usually has a
Rakefile, which the rake program uses to automate tests, generate code, and perform other tasks.
- This gem also includes an executable file in the
bindirectory, which will be loaded into the user’s
PATHwhen the gem is installed.
- Documentation is usually included in the
READMEand inline with the code. When you install a gem, documentation is generated automatically for you. Most gems include RDoc documentation, but some use YARD docs instead.
- The final piece is the gemspec, which contains information about the gem. The gem’s files, test information, platform, version number and more are all laid out here along with the author’s email and name.
More information on the gemspec file
Building your own gem
RubyGems modifies your Ruby load path, which controls how your Ruby code is found by the
require statement. When you
require a gem, really you’re just placing that gem’s
lib directory onto your
$LOAD_PATH. Let’s try this out in
irb and get some help from the
pretty_print library included with Ruby.
irb will automatically require a library when irb is loaded.
% irb -rpp >> pp $LOAD_PATH [".../lib/ruby/site_ruby/1.9.1", ".../lib/ruby/site_ruby", ".../lib/ruby/vendor_ruby/1.9.1", ".../lib/ruby/vendor_ruby", ".../lib/ruby/1.9.1", "."]
By default you have just a few system directories on the load path and the Ruby standard libraries.To add the awesome_print directories to the load path, you can require its gem:
% irb -rpp >> require 'ap' => true >> pp $LOAD_PATH .../gems/awesome_print-1.0.2/lib"
Note: If you’re using Ruby 1.8, you need to
require 'rubygems' before requiring any gems. This is no longer necessary now that RubyGems is installed with Ruby itself.
Once you’ve required rake, then RubyGems automatically drops its
lib directory on to the
$LOAD_PATH. Some gems also add additional directories, such as
bin, to the load path. These are completely optional and you can have many directories added to the load path by a single gem.
That’s basically it for what’s in a gem. Drop Ruby code into
lib, name a Ruby file the same as your gem (so for freewill,
freewill.rb) and it’s loaded by RubyGems.
lib directory itself normally contains only one
.rb file, and then another folder with the same name as the gem with more code in it. For example:
% tree freewill/ freewill/ ├── lib/ │ ├── freewill/ │ │ ├── core_ext/ │ │ │ ├── array.rb │ │ │ └── string.rb │ │ ├── user.rb │ │ ├── widget.rb │ │ └── ... │ ├── freewill.rb
Your application, your gem’s users, and you 6 months from now need to know who wrote a gem, when, and what it does. The gemspec tells you this information and is your guide to understanding what a gem contains.
Here’s an example of a gemspec file. You can learn more in how to make a gem.
% cat freewill.gemspec Gem::Specification.new do |s| s.name = 'freewill' s.version = '1.0.0' s.date = '2010-04-27' s.summary = "Freewill!" s.description = "I will choose Freewill!" s.authors = ["Nick Quaranto"] s.email = 'email@example.com' s.homepage = 'http://example.com' s.files = ["lib/freewill.rb"] end
For more information on the gemspec, please check out the full Specification Reference which goes over each metadata field in detail.
This guide was adapted from Gonçalo Silva’s original tutorial on docs.rubygems.org and from Gem Sawyer, Modern Day Ruby Warrior.