4.7. RubyGems packages

This section explains what RubyGems packages are, and how to re-package them into RPM.

4.7.1. What RubyGems are

Ruby is a dynamic, interpreted, reflective, object-oriented, general-purpose programming language.

Programs written in Ruby are typically packaged using the RubyGems project, which provides a specific Ruby packaging format.

Packages created by RubyGems are called gems, and they can be re-packaged into RPM as well.


This documentation refers to terms related to the RubyGems concept with the gem prefix, for example .gemspec is used for the gem specification, and terms related to RPM are unqualified.

4.7.2. How RubyGems relate to RPM

RubyGems represent Ruby’s own packaging format. However, RubyGems contain metadata similar to those needed by RPM, which enables the conversion from RubyGems to RPM.

According to Ruby Packaging Guidelines, it is possible to re-package RubyGems packages into RPM in this way:

  • Such RPMs fit with the rest of the distribution.
  • End users are able to satisfy dependencies of a gem by installing the appropriate RPM-packaged gem.

RubyGems use similar terminology as RPM, such as SPEC files, package names, dependencies and other items.

To fit into the rest of RHEL RPM distribution, packages created by RubyGems must follow the conventions listed below:

  • Names of gems must follow this pattern:

  • To implement a shebang line, the following string must be used:


4.7.3. Creating RPM packages from RubyGems packages

To create a source RPM for a RubyGems package, the following files are needed:

  • A gem file
  • An RPM SPEC file

The following sections describe how to create RPM packages from packages created by RubyGems. RubyGems SPEC file conventions

A RubyGems SPEC file must meet the following conventions:

  • Contain a definition of %{gem_name}, which 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.
  • Contain the BuildRequires: a directive defined as follows to be able to pull in the macros needed to build.

  • Not contain any RubyGems Requires or Provides, because those are autogenerated.
  • Not contain the BuildRequires: directive defined as follows, unless you want to explicitly specify Ruby version compatibility:

    Requires: ruby(release)

    The automatically generated dependency on RubyGems (Requires: ruby(rubygems)) is sufficient. RubyGems macros

The following table lists macros useful for packages created by RubyGems. These macros are provided by the rubygems-devel packages.

Tableau 4.4. RubyGems' macros

Macro nameExtended pathUtilisation



Top directory for the gem structure.



Directory with the actual content of the gem.



The library directory of the gem.



The cached gem.



The gem specification file.



The RDoc documentation of the gem.



The directory for gem extension. RubyGems SPEC file example

This section provides an example SPEC file for building gems together with an explanation of its particular sections.

An example RubyGems SPEC file

%setup -q -n  %{gem_name}-%{version}

# Modify the gemspec if necessary
# Also apply patches to code if necessary
%patch0 -p1

# Create the gem as gem install only works on a gem file
gem build ../%{gem_name}-%{version}.gemspec

# %%gem_install compiles any C extensions and installs the gem into ./%%gem_dir
# by default, so that we can move it into the buildroot in %%install

mkdir -p %{buildroot}%{gem_dir}
cp -a ./%{gem_dir}/* %{buildroot}%{gem_dir}/

# If there were programs installed:
mkdir -p %{buildroot}%{_bindir}
cp -a ./%{_bindir}/* %{buildroot}%{_bindir}

# If there are C extensions, copy them to the extdir.
mkdir -p %{buildroot}%{gem_extdir_mri}
cp -a .%{gem_extdir_mri}/{gem.build_complete,*.so} %{buildroot}%{gem_extdir_mri}/

The following table explains the specifics of particular items in a RubyGems SPEC file:

Tableau 4.5. RubyGems' SPEC directives specifics

SPEC directiveRubyGems specifics


RPM can directly unpack gem archives, so you can run the gem unpack comamnd to extract the source from the gem. The %setup -n %{gem_name}-%{version} macro provides the directory into which the gem has been unpacked. At the same directory level, the %{gem_name}-%{version}.gemspec file is automatically created, which can be used to rebuild the gem later, to modify the .gemspec, or to apply patches to the code.


This directive includes commands or series of commands for building the software into machine code. The %gem_install macro operates only on gem archives, and the gem is recreated with the next gem build. The gem file that is created is then used by %gem_install to build and install the code into the temporary directory, which is ./%{gem_dir} by default. The %gem_install macro both builds and installs the code in one step. Before being installed, the built sources are placed into a temporary directory that is created automatically.

The %gem_install macro accepts two additional options: -n <gem_file>, which allows to override gem used for installation, and -d <install_dir>, which might override the gem installation destination; using this option is not recommended.

The %gem_install macro must not be used to install into the %{buildroot}.


The installation is performed into the %{buildroot} hierarchy. You can create the directories that you need and then copy what was installed in the temporary directories into the %{buildroot} hierarchy. If this gem creates shared objects, they are moved into the architecture-specific %{gem_extdir_mri} path.

Ressources supplémentaires Converting RubyGems packages to RPM SPEC files with gem2rpm

The gem2rpm utility converts RubyGems packages to RPM SPEC files.

Les sections suivantes décrivent comment :

  • Install the gem2rpm utility
  • Display all gem2rpm options
  • Use gem2rpm to covert RubyGems packages to RPM SPEC files
  • Edit gem2rpm templates Installing gem2rpm

The following procedure describes how to install the gem2rpm utility.


$ gem install gem2rpm Displaying all options of gem2rpm

The following procedure describes how to display all options of the gem2rpm utility.


  • To see all options of gem2rpm, run:

    gem2rpm --help Using gem2rpm to covert RubyGems packages to RPM SPEC files

The following procedure describes how to use the gem2rpm utility to covert RubyGems packages to RPM SPEC files.


  • Download a gem in its latest version, and generate the RPM SPEC file for this gem:

    $ gem2rpm --fetch <gem_name> > <gem_name>.spec

The described procedure creates an RPM SPEC file based on the information provided in the gem’s metadata. However, the gem misses some important information that is usually provided in RPMs, such as the license and the changelog. The generated SPEC file thus needs to be edited. gem2rpm templates

The gem2rpm template is a standard Embedded Ruby (ERB) file, which includes variables listed in the following table.

Tableau 4.6. Variables in the gem2rpm template



The Gem::Package variable for the gem.


The Gem::Specification variable for the gem (the same as format.spec).


The Gem2Rpm::Configuration variable that can redefine default macros or rules used in spec template helpers.


The Gem2Rpm::RpmDependencyList variable providing a list of package runtime dependencies.


The Gem2Rpm::RpmDependencyList variable providing a list of package development dependencies.


The Gem2Rpm::TestSuite variable providing a list of test frameworks allowing their execution.


The Gem2Rpm::RpmFileList variable providing an unfiltered list of files in a package.


The Gem2Rpm::RpmFileList variable providing a list of files suitable for the main package.


The Gem2Rpm::RpmFileList variable providing a list of files suitable for the -doc subpackage.


The Gem::Format variable for the gem. Note that this variable is now deprecated. Listing available gem2rpm templates

Use the following procedure describes to list all available gem2rpm templates.


  • To see all available templates, run:

    $ gem2rpm --templates Editing gem2rpm templates

You can edit the template from which the RPM SPEC file is generated instead of editing the generated SPEC file.

Use the following procedure to edit the gem2rpm templates.


  1. Save the default template:

    $ gem2rpm -T > rubygem-<gem_name>.spec.template
  2. Edit the template as needed.
  3. Generate the SPEC file using the edited template:

    $ gem2rpm -t rubygem-<gem_name>.spec.template <gem_name>-<latest_version.gem > <gem_name>-GEM.spec

You can now build an RPM package using the edited template as described in Building RPMs.