From Fedora Project Wiki


This page is outdated and is only retained for historical reference
It is now contained in the Ruby guidelines


Packaging Ruby Gems

Ruby Gems are Ruby's own packaging format. Most Ruby libraries and tools are distributed as Gems, and it is often not straightforward to package Gems as normal RPM's. Gems also contain a lot of the same metadata that RPM's need, making fairly smooth interoperation between RPM and Gems possible. This guideline ensures that Gems are packaged as RPM's in a way that ensures (1) that such RPM's fit cleanly with the rest of the distribution and (2) make it possible for the end user to satisfy dependencies of a Gem by installing the appropriate RPM-packaged Gem.

Both RPM's and Gems use similar terminology --- there's specfiles, package names, dependencies etc. for both. To keep confusion to a minimum, whenever the term from the Gem world is meant, it is explicitly called the 'Gem specification'. An unqualified 'package' in the following always means an RPM.

Guideline

  • Packages that contain Ruby Gems must be called rubygem-%{gemname} where gemname is the name from the Gem's specification.
  • The Source of the package must be the full URL to the released Gem archive; the version of the package must be the Gem's version
  • The package must have a Requires and a BuildRequires on rubygems
  • The package must provide rubygem(%{gemname}) where gemname is the name from the Gem's specification. For every dependency on a Gem named gemdep, the package must contain a Requires on rubygem(%{gemdep}) with the same version constraints as the Gem
  • The %prep and %build sections of the specfile should be empty.
  • The Gem must be installed into %{gemdir} defined as
%define gemdir %(ruby -rubygems -e 'puts Gem::dir' 2>/dev/null)

The install should be performed with the command

gem install --local --install-dir %{buildroot}%{gemdir} --force %{SOURCE0}
  • The package must own the following files and directories:
%{gemdir}/gems/%{gemname}-%{version}/
%{gemdir}/cache/%{gemname}-%{version}.gem
%{gemdir}/specifications/%{gemname}-%{version}.gemspec
  • Architecture-specific content must not be installed into %{gemdir}
  • If the Gem only contains pure Ruby code, it must be marked as BuildArch: noarch. If the Gem contains binary content (e.g., for a database driver), it must be marked as architecture specific, and all architecture specific content must be moved from the %{gemdir} to the %{ruby_sitearch} directory defined in during %install

Packaging for Gem and non-Gem use

If the same Ruby library is to be packaged for use as a Gem and as a straight Ruby library without Gem support, it must be packaged as a Gem first. To make it available to code that does not use Ruby Gems, a subpackage called ruby-%{gemname} must be created in the rubygem-%{gemname} package such that

  • The subpackage must require rubygem(%gemname) = %version
  • The subpackage must provide ruby(LIBRARY) = %version where LIBRARY is the same name used in
  • All the toplevel library files of the Gem must be symlinked into ruby_sitelib.
  • The subpackage must own these symbolic links.

As an example, for activesupport, the rubygem-activesupport package would have a subpackge ruby-activesupport:

%package -n ruby-activesupport
...
Requires: rubygem(activesupport) = %version
Provides: ruby(active_support) = %version  # The underscore is intentional, not a typo
...
%files -n ruby-activesupport
%{ruby_sitelib}/active_support
%{ruby_sitelib}/active_support.rb

Tips for Packagers

Gems carry a lot of metadata; Gem2Spec is a tool to generate an initial specfile and/or source RPM from a Gem. The generated specfile still needs some hand-editing, but conforms to 90% with this guideline.