These guidelines are for RHEL 4, 5, and 6 and Fedora 16 and earlier. Fedora 17 introduced new ruby packages and new ruby guidelines that improve upon these in several ways. Please use those for Fedora 17 and beyond.
All current versions of Fedora now contain
rubygems-devel, so it is possible to carefully use the macros in these guidelines and the newer macros in the new ruby guidelines along with conditionalization to have a consistent spec file for all current versions of Fedora.Each Ruby package must indicate the Ruby ABI version it depends on with a line like
Requires: ruby(abi) = 1.8
Ruby packages must require ruby at build time with a BuildRequires: ruby, and may indicate the minimal ruby version they need for building.
Naming Guidelines
These naming guidelines only apply to ruby packages whose main purpose is providing a Ruby library; packages that mainly provide user-level tools that happen to be written in Ruby do not need to follow these naming guidelines, and should follow the general NamingGuidelines instead.
The name of a ruby extension/library package must be of the form ruby-UPSTREAM. If the upstream name UPSTREAM contains ruby, that should be dropped from the name. For example, the SQLite database driver for ruby is called sqlite3-ruby. The corresponding Fedora package should be called ruby-sqlite3, and not ruby-sqlite3-ruby.
A ruby extension/library package must indicate what it provides with a Provides: ruby(LIBRARY) = VERSION declaration in the spec file. The string LIBRARY should be the same as what is used in the require statement in a Ruby script that uses the library. The VERSION should be the upstream version of the library, as long as upstream follows a sane versioning scheme. For example, a Ruby script using the SQLite database driver will include it with require 'sqlite3'. The specfile for the corresponding Fedora package must contain a line Provides: ruby(sqlite3) = 1.1.0, assuming the package contains version 1.1.0 of the library.
Build Architecture and File Placement
The following only affects the files that the package installs into %{_libdir}/ruby, i.e., Ruby library files. All other files in a Ruby package must adhere to the general Fedora Extras packaging conventions.
Pure Ruby packages
Pure Ruby packages must be built as noarch packages.
The Ruby library files in a pure Ruby package must be placed into Config::CONFIG["sitelibdir"] . The specfile must get that path using
%{!?ruby_sitelib: %global ruby_sitelib %(ruby -rrbconfig -e 'puts Config::CONFIG["sitelibdir"] ')}
For packages with binary content, e.g., database drivers or any other Ruby bindings to C libraries, the package must be architecture specific.
The binary files in a Ruby package with binary content must be placed into Config::CONFIG["sitearchdir"] . The Ruby files in such a package should be placed into that directory, too. The specfile must get that path using
%{!?ruby_sitearch: %global ruby_sitearch %(ruby -rrbconfig -e 'puts Config::CONFIG["sitearchdir"] ')}
For packages which create C shared libraries using extconf.rb
export CONFIGURE_ARGS="--with-cflags='%{optflags}'"
should be used to pass CFLAGS to Makefile correctly.
This also applies to Ruby Gems.
Ruby Gems
Ruby Gems 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 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.
- Packages that contain Ruby Gems must be called
rubygem-%{gemname}wheregemnameis the name from the Gem's specification. - The
Sourceof 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
Requiresand aBuildRequiresonrubygems - The package must provide
rubygem(%{gemname})wheregemnameis the name from the Gem's specification. For every dependency on a Gem namedgemdep, the package must contain aRequiresonrubygem(%{gemdep})with the same version constraints as the Gem - The
%prepand%buildsections of the specfile should be empty. - The Gem must be installed into
%{gemdir}defined as
%global 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%{ruby_sitearch}directory] during%install
Ruby Gem with extension libraries written in C
When a Ruby Gem contains extension libraries written in C,
- First,
%prepstage must contain%setup -q -c -Tto create the directory where C libraries are compiled. - Then at %build stage the Ruby Gem must be installed under the directory created at %prep stage to get C libraries compiled under there.
- When
gem installis used to install Gem file, using-Voption is recommend to check ifCFLAGSis correctly honored. - Finally at
%installstage the whole tree under the directory created at %prep stage should be copied (not moved) to under%{buildroot}%{gemdir}.- When all tree under the directory created at %prep stage is moved to under
%{buildroot},find_debuginfo.shwill complain that the corresponding source files are missing.
- When all tree under the directory created at %prep stage is moved to under
- Installed C codes (usually under
%{geminstdir}/etc) may be removed even ifgem contents %{gemname}reports that installed C codes should be found there.
Note
The current guideline
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 %{ruby_sitearch} directory] during %install
must still apply.
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) = %versionwhere LIBRARY is the same as in the [#ruby_naming general Ruby guideline] above. - 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; gem2rpm 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.