Ruby Packaging Guidelines

Most of the pure Ruby packages will work on all Ruby interpreters. There are however cases when the packages use interpreter-specific functions (like fork()) and won’t run on other interpreters (JRuby). In this case, the package SHOULD require that interpreter. For example, a package that uses fork SHOULD explicitly specify Requires: ruby. In case of such package, packager SHOULD file a bug to ask upstream to provide support for other interpreter(s). This SHOULD be documented in specfile.

On Fedora, /usr/bin/ruby is implemented via Rubypick. Rubypick is a tool similar to RVM or rbenv. It allows choosing interpreter to execute Ruby script. Rubypick routes anything executed via /usr/bin/ruby to /usr/bin/ruby-mri or /usr/bin/jruby. By default, it runs MRI (Matz’s Ruby Implementation), but user can explicitly specify the interpreter by using _mri_ or _jruby_ as a first parameter. For example:

Using the RUBYPICK environment variable can achieve the same results. The environment variable can be used to set one interpreter as the global default:

Ruby executables that are known to only run on one Ruby implementation SHOULD use that specific implementation in their shebang (#!/usr/bin/ruby-mri or #!/usr/bin/jruby) to ensure that they run using that implementation. All other code SHOULD use #!/usr/bin/ruby.

You might have noticed that the table above has different directories for non-gem libraries on different ruby interpreters but only a single set of directories for rubygem libraries. This is because code written for one ruby interpreter will often run on all ruby interpreters that Fedora ships (ruby, jruby, etc.). However, some code uses methods that are not available on all interpreters (see Different Interpreters Compatibility). Rubygems have a facility to ship different versions of the code in the same gem so that the gem can run on all versions of the interpreter, so we only need to have one common directory for rubygems that all the interpreters can use.

The standard ruby %{vendorlib} directories lack this facility. For this reason, non-gem libraries need to be placed in per-interpreter directories and MUST have a separate subpackage (or package depending on upstream) for each interpreter that they support.

RubyGems are Ruby’s own packaging format. Gems 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 RPMs in a way that such RPMs fit cleanly with the rest of the distribution and makes 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 are specfiles, package names, dependencies, etc. for both. To keep confusion to a minimum, terms relating to Gem concepts will be explicitly referred to with the word "Gem" prefixed, e.g., "Gem specification" (.gemspec). An unqualified "package" in the following always means an RPM.

Non-Gem Ruby packages MUST require ruby-devel package at build time with a BuildRequires: ruby-devel, and MAY indicate the minimal ruby version they need for building.

To run tests with different Ruby implementation such as JRuby, add BuildRequires: jruby. Then use Rubypick’s interpreter switching:

If your package is running unittests for ruby-mri and it is intended to run under alternate interpreters then it needs to run the unittests under all alternate interpreters as well. This is the only method we have to check compatibility of the code under each interpreter. The same rules apply that you can omit this if libraries you need are unavailable for a specific alternate interpreter but you MUST have a comment to explain.

The Ruby community supports many testing frameworks. The following sections demonstrate how several to execute test suites using the more common of them.

Sometimes you have to get the tests separately from upstream’s gem package. As an example lets suppose you’re packaging rubygem-delorean, version 1.2.0, which is hosted on Github. Tests are not included in the Gem itself, so you need to get them and adjust the specfile accordingly: