Unpack the mystery behind what’s in a RubyGem.
Structure of a Gem
Each gem has a name, version, and platform. For example, the
rake gem has a
0.8.7 version (from May,
2009). Rake’s platform is
ruby, which means it works on any platform Ruby
Platforms are based on the CPU architecture, operating system type and
sometimes the operating system version. Examples include “x86-mingw32” or
“java”. The platform indicates the gem only works with a ruby built for the
same platform. RubyGems will automatically download the correct version for
your platform. See
gem help platform for full details.
Inside a gems are the following 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.
Your application, your gem’s users, and you 6 months from now will want to know who wrote a gem, when, and what it does. The gemspec contains this information.
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.summary = "Freewill!" s.description = "I will choose Freewill!" s.authors = ["Nick Quaranto"] s.email = 'firstname.lastname@example.org' s.homepage = 'http://example.com/freewill' 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.