From Fedora Project Wiki
mNo edit summary
 
(53 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Draft}}
{{admon/warning|Different guidelines for packages in EPEL 5| In RHEL 5 a ruby version that does not have all the features needed to support these guidelines exists.  If you're packaging for EPEL 5 you should follow the [[Packaging:Old_Ruby | old ruby guidelines]] instead.}}


{{admon/warning|Different guidelines for older Fedora and RHEL| In RHEL 4, 5, and 6 and Fedora before Fedora 16, a ruby version that does not have all the features needed to support these guidelines exists. If you're packaging for those distributions you should follow the [[Packaging:Old_Ruby | old ruby guidelines]] instead.}}
{{admon/warning|Different Guidelines for Fedora 19/20 and EPEL6/7| In Fedora 19/20 and EPEL 6/7 the Ruby guidelines were slightly different. Some of the macros and practices listed here did not work. Please see this [[https://fedoraproject.org/w/index.php?title=Packaging:Ruby&oldid=363159 earlier version of the guidelines]] if you want your package to work on those versions of Fedora/EPEL}}
 
{{admon/note|JRuby Gems| Although Fedora 19 has fully functioning JRuby integrated with system RubyGems, we have decided to not include the JRuby specific packaging guidelines here, as they need some more work. They will appear here as soon as we feel that we've got everything covered properly. You can contact us on [https://lists.fedoraproject.org/mailman/listinfo/ruby-sig Ruby-SIG mailing list] in case of any questions about the prepared JRuby packaging guidelines.}}


There are three basic categories of ruby packages: [[#RubyGems | ruby gems]], [[#Non-Gem Packages | non-gem ruby packages]], and [[#ruby_applications| applications written in ruby]]. These guidelines contain sections common to all of these as well as sections which apply to each one individually. Be sure to read all the guidelines relevant to the type of ruby package you are building.
There are three basic categories of ruby packages: [[#RubyGems | ruby gems]], [[#Non-Gem Packages | non-gem ruby packages]], and [[#ruby_applications| applications written in ruby]]. These guidelines contain sections common to all of these as well as sections which apply to each one individually. Be sure to read all the guidelines relevant to the type of ruby package you are building.


== Ruby ABI ==


Each Ruby package '''must''' indicate the Ruby ABI version it depends on with a line like
== Ruby Compatibility ==
 
Each Ruby package '''must''' indicate it depends on a Ruby interpreter (this does not apply to [[#RubyGems|ruby gem packages]]). Use ruby(release) virtual requirement to achieve that:
<pre>
<pre>
Requires: ruby(abi) = 1.9.1
Requires: ruby(release)
</pre>
</pre>
If the package requires Ruby of certain version(s), make the requirement versioned like this:
<pre>
Requires: ruby(release) >= 1.9.1
</pre>
{{admon/note|Alternate interpreters| Alternate Ruby interpreters (currently JRuby) also <code>Provide: ruby(release)</code>. This implies, that pure RubyGems packages (these are shared among interpreters) '''should not''' have <code>Requires: ruby</code> or <code>Requires: jruby</code> to have their dependencies satisfied by any of these interpreters.}}
{{admon/warning|Over specified ruby(release) versioning| Please note, that if the  <code>ruby(release)</code> version requirement is too specific, it may cause an unexpected interpreter to be drawn in. E.g. <code>ruby(release) &#61; 1.8</code> will require JRuby package, since it is the only package that provides it.}}
{{Anchor|interpreters_compatibility}}
=== Different Interpreters Compatibility ===
Most of the pure Ruby packages will work on all Ruby interpreters. There are however cases, when the packages use interpreter-specific functions (like <code>fork()</code>) and won't run on other interpreters (JRuby). In this case, the package '''should''' require that interpreter. For example, a package that uses <code>fork</code> should explicitly specify <code>Requires: ruby</code>.
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.
=== Shebang lines ===
On Fedora, <code>/usr/bin/ruby</code> is implemented via [https://github.com/bkabrda/rubypick Rubypick].  Rubypick is a tool similar to RVM or rbenv. It allows choosing interpreter to execute Ruby script. Rubypick routes anything executed via <code>/usr/bin/ruby</code> to <code>/usr/bin/ruby-mri</code> or <code>/usr/bin/jruby</code>. By default, it runs MRI (Matz's Ruby Implementation), but user can explicitly specify the interpreter by using <code>_mri_</code> or <code>_jruby_</code> as a first parameter. For example:
<pre>
ruby _jruby_ jruby_script.rb
gem _mri_ install foo
rails _jruby_ s
</pre>
Using the <code>RUBYPICK</code> environment variable can achieve the same results.  The environment variable can be used to set one interpreter as the global default:
<pre>
export RUBYPICK=_jruby_
ruby jruby_script.rb  # Will use jruby
gem install foo        # Will also use jruby
</pre>
Ruby executables that are known to only run on one Ruby implementation '''should''' use that specific implementation in their shebang - <code>#!/usr/bin/ruby-mri</code> or <code>#!/usr/bin/jruby</code> to ensure that they run using that implementation.  All other code '''should''' use <code>#!/usr/bin/ruby</code>.


{{Anchor|ruby_naming}}
{{Anchor|ruby_naming}}
== Naming Guidelines ==
== Naming Guidelines ==


* Packages that contain Ruby Gems '''must''' be called <code>rubygem-%{gem_name}</code>.
* Packages that contain Ruby Gems '''must''' be called <code>rubygem-%{gem_name}</code>.


* The name of a ruby extension/library package '''must''' be of the form <code>ruby-UPSTREAM</code>. If the upstream name <code>UPSTREAM</code> contains <code>ruby</code>, that '''should''' be dropped from the name. For example, the SQLite database driver for ruby is called <code>sqlite3-ruby</code>. The corresponding Fedora package should be called <code>ruby-sqlite3</code>, and not <code>ruby-sqlite3-ruby</code>.
* The name of a ruby extension/library package '''must''' start with the interpreter it is built for (ruby, jruby, etc) and then the <code>UPSTREAM</code> name.  For example: <code>ruby-UPSTREAM</code>. If the upstream name <code>UPSTREAM</code> contains <code>ruby</code>, that '''should''' be dropped from the name. For example, the SQLite database driver for ruby is called <code>sqlite3-ruby</code>. The corresponding Fedora package should be called <code>ruby-sqlite3</code>, and not <code>ruby-sqlite3-ruby</code>.


* Application packages that mainly provide user-level tools that happen to be written in Ruby '''must''' follow the general [[Packaging/NamingGuidelines|  NamingGuidelines]]  instead.
* Application packages that mainly provide user-level tools that happen to be written in Ruby '''must''' follow the general [[Packaging/NamingGuidelines|  NamingGuidelines]]  instead.
Line 23: Line 60:
== Macros ==
== Macros ==


{{admon/question|Interpreter independence|Related to the below text about interpreter independence.  Move vendorlib/vendorarch to a non-MRI specific location}}
Non-gem ruby packages and ruby gem packages install to certain standard locations.  The <code>ruby-devel</code> and <code>rubygems-devel</code> packages contain macros useful for the respective package types. Alternate ruby interpreters will have equivalent locations (To be added to this table later)
{{admon/warning|Interpreter indendence|The vendordirs are intentionally placed under the MRI Ruby directory, because many libraries and applications use them to install their Ruby bindings - bindings that are meant only for MRI Ruby. Therefore, the vendordirs should stay where they are now.}}
 
 
Non-gem ruby packages and ruby gem packages install to certain standard locations.  The <code>ruby-devel</code> and <code>rubygems-devel</code> packages contain macros useful for the respective package types.


{| border="1" cellpadding="20" cellspacing="0"
{| border="1" cellpadding="20" cellspacing="0"
Line 34: Line 67:
!Usage
!Usage
|-
|-
! colspan="3"|From ruby-devel; intended for non-gem packages
! colspan="3"|From ruby-devel; intended for non-gem packages.
|-
|-
|<code>%{ruby_vendorarchdir}</code>
|<code>%{ruby_vendorarchdir}</code>
Line 78: Line 111:
|The rdoc documentation of the Gem.
|The rdoc documentation of the Gem.
|-
|-
|<code>%{gem_extdir}</code>
|<code>%{gem_extdir_mri}</code>
|%{_libdir}/gems/exts/%{gem_name}-%{version}
|%{_libdir}/gems/ruby/%{gem_name}-%{version}
|The directory for binary Gem extensions.
|The directory for MRI Ruby Gem extensions.
|}
|}


== Dependencies ==
=== Interpreter independence and directory macros ===


Due to having multiple types of libraries (gems and non-gems) there are two ways to specify dependencies.
You may 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 [[#interpreter_compatibility|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.


{{admon/question|Confirm change: rubygems to provide ruby()| Since rubygems now work with plain <code>require</code> the distinction between ruby() and rubygem() doesn't seem as necessary.  I've reworked the requires and provides to tak this into account.  Someone from ruby sig should confirm that this seems sensible.}}
The standard ruby <code>%{vendorlib}</code> directories lack this facilityFor 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.
{{admon/warning|Confirm change: rubygems to provide ruby()|This is not a good move. The ruby() provides should be left to non-gem libraries, that can be required even with the <code>--disable-gems</code> option, while rubygem() provides should be only present for packages, which are only loadable via RubyGems library.}}
 
 
=== Requires ===
If your package uses <code>gem 'rubylibrary'</code> or you're packaging a ruby gem that depends on the library in its <code>.gemspec</code> (See the section on [[#Building gems| building gems]] for more information) you '''Must''' use <code>Requires: rubygem(rubylibrary)</code> so the rpm will pull in the correct ruby library.
 
If your package just uses <code>require 'rubylibrary'</code> it's always fine to use <code>Requires: ruby(rubylibrary)</code>.  If you know that the ruby library is provided as a gem despite using <code>require 'rubylibrary'</code> you may use <code>Requires: rubygem(rubylibrary)</code> instead but this is not required as it forces packagers to know unnecessary details of how another ruby package has been created.
{{admon/warning|Not true in Ruby world|The upstream of the package in Ruby world always uses a specific type of a library. Gems in most cases, sometimes non-gem libraries. But they always need the specific one (again, take <code>--disable-gems</code> into account).}}
 
When packaging rubygems the gem itself carries some dependency information in the "gem specification".  That specification may contain precise versions of dependent gems.  If Fedora has packaged a different version of the gem you may have to adjust the <code>.gemspec</code> to work with the Fedora version of the package (see the section on [[#Building gems| building gems]] for more information).
 
Please ensure that the package works properly with the dependencies specified in the rpm spec file.
 
=== Provides ===
 
Non-gem ruby libraries '''Must''' indicate what they provide with <code>Provides: ruby(RUBYLIBRARY) = VERSION</code>.  The string <code>RUBYLIBRARY</code> '''Must''' be the same as what is used in the <code>require</code> statement in a Ruby script that uses the library.  The <code>VERSION</code> '''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 <code>require 'sqlite3'</code>.  The specfile for the corresponding Fedora package must contain a line <code>Provides: ruby(sqlite3) = 1.1.0</code>, assuming the package contains version 1.1.0 of the library.
 
Gem packages '''must''' have two provides:
<pre>
Provides: ruby(RUBYLIBRARY) = VERSION
Provides: rubygem(%{gem_name}) = %{version}
</pre>
 
This allows people who are packaging something that requires the gem to use either form of the dependency to get the proper package.  Since their package may only have a <code>require 'rubylibrary'</code> in the code, there's no reason for them to have to figure out whether we've packaged it as a gem or a non-gem library.  The <code>rubygem(%{gem_name})</code> form of the dependency allows packages which depend on having the gem metadata to specify that the Fedora package must be packaging a gem form of the library, not a non-gem form of the library.


== Libraries ==
== Libraries ==


These 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 must follow the [[#ruby_applications|ruby applications guidelines]] instead.
These 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 must follow the [[#ruby_applications|ruby applications guidelines]] instead.
{{admon/question|Move text about interpreter independence to here|In Fedora we strive to make rubylibraries run on all versions of the interpreter (ruby, jruby, etc) that we ship.  We may carry patches so that the libraries run on all versions of the interpreter and we install them to interpreter neutral locations.}}


=== RubyGems ===
=== RubyGems ===


[http://www.rubygems.org/ 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 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.
[http://www.rubygems.org/ 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 RPM's in a way that such RPM's fit cleanly with the rest of the distribution and to make it possible for the end user to satisfy dependencies of a Gem by installing the appropriate RPM-packaged Gem.
 
{{admon/question|See above|About moving the next bit of text to the overall libraries portion.}}
 
In Fedora we strive to make rubygems run on all versions of the interpreter (ruby, jruby, etc) that we ship.  We may carry patches so that gems run on all versions of the interpreter and we install them to interpreter neutral locations.


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 refereed to with the word 'Gem' prefixed, eg 'Gem specification' (.gemspec). An unqualified 'package' in the following always means an RPM.
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 refereed to with the word 'Gem' prefixed, eg 'Gem specification' (.gemspec). An unqualified 'package' in the following always means an RPM.


* Spec files '''must''' contain a definition of <code>%{gem_name}</code>, which is the name from the Gem's specification.
* Spec files '''must''' contain a definition of <code>%{gem_name}</code> which is the name from the Gem's specification.
* The <code>Source</code> 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 <code>Source</code> 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''' <code>BuildRequires: rubygems-devel</code> to pull in the macros needed to build.
* The package '''must''' <code>BuildRequires: rubygems-devel</code> to pull in the macros needed to build.
* There '''should''' not be any rubygem <code>Requires</code> nor <code>Provides</code> listed, since those are autogenerated.
* There '''should''' not be <code>Requires: ruby(release)</code>, unless you want to explicitly specify Ruby version compatibility. Automatically generated dependency on RubyGems (<code>Requires: ruby(rubygems)</code>) is enough.
==== Filtering Requires and Provides ====
Runtime requires and provides are automatically generated by RPM's dependency generator. However, it can sometimes throw in additional dependencies contrary to reality. To fix this, the dependency generator needs to be overridden so that the additional dependencies can be filtered out.  See [[Packaging:AutoProvidesAndRequiresFiltering]] for details.


==== Building gems ====
==== Building gems ====
Line 139: Line 148:
<pre>
<pre>
%prep
%prep
%setup -q -T -n  %{gem_name}-%{version}
gem unpack %{SOURCE0}
gem unpack %{SOURCE0}
pushd %{gem_name}-%{version}
%setup -q -D -T -n  %{gem_name}-%{version}


gem spec %{SOURCE0} -l --ruby > %{gem_name}.gemspec
gem spec %{SOURCE0} -l --ruby > %{gem_name}.gemspec
# Modify the gemspec if necessary with a patch or sed
# Modify the gemspec if necessary with a patch or sed
# Also apply patches to code if necessary
# Also apply patches to code if necessary
%patch0 -p1
%patch0 -p1
popd


%build
%build
mkdir -p ./%{gem_dir}
mkdir -p ./%{_bindir}
# Create the gem as gem install only works on a gem file
# Create the gem as gem install only works on a gem file
gem build %{gem_name}.gemspec
gem build %{gem_name}.gemspec
export CONFIGURE_ARGS="--with-cflags='%{optflags}'"
 
# gem install compiles any C extensions and installs into a directory
# %%gem_install compiles any C extensions and installs the gem into ./%%gem_dir
gem install -V \
# by default, so that we can move it into the buildroot in %%install
        --local \
%gem_install
        --install-dir ./%{gem_dir} \
        --bindir .%{_bindir} \
        --force \
        --rdoc
        ../%{gem_name}-%{version}/%{gem_name}-%{version}.gem


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


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


# If there are C extensions, mv them to the extdir.
# If there are C extensions, copy them to the extdir.
# $REQUIRE_PATHS is taken from the first value of the require_paths field in
mkdir -p %{buildroot}%{gem_extdir_mri}
# the gemspec file.  It will typically be either "lib" or "ext".  For instance:
cp -a .%{gem_extdir_mri}/{gem.build_complete,*.so} %{buildroot}%{gem_extdir_mri}/
#  s.require_paths = ["lib"]
mkdir -p %{buildroot}%{gem_extdir}/$REQUIRE_PATHS
mv %{buildroot}%{gem_instdir}/$REQUIRE_PATHS/shared_object.so %{buildroot}%{gem_extdir}/$REQUIRE_PATHS/
</pre>
</pre>


===== %prep =====
===== %prep =====
In the <code>%prep</code> section we first use <code>%setup -n %{gem_name}-%{version}</code> to tell rpm what the directory the gem will unpack into.  We use the <code>-T</code> flag to tell <code>%setup</code> not to try unpacking the source on its own. Then we explicitly use <code>gem unpack</code> to extract the source from the gem and switch into the directory.  This is equivalent to the steps that <code>%setup</code> would take if gem was a recognized archive format.
Since gems aren't an archive format that rpm recognizes, the first thing we have to do is explicitly use <code>gem unpack</code> to extract the source from the gem.  Then we call <code>%setup -n %{gem_name}-%{version}</code> to tell rpm what the directory the gem has unpacked into.  The [http://www.rpm.org/max-rpm/s1-rpm-inside-macros.html#S3-RPM-INSIDE-SETUP-T-OPTION <code>-T</code>] and [http://www.rpm.org/max-rpm/s1-rpm-inside-macros.html#S3-RPM-INSIDE-SETUP-D-OPTION <code>-D</code>] flags tell <code>%setup</code> that we've already unpacked the code


We then run <code>gem spec</code> to output the metadata from the gem into a file.  This <code>.gemspec</code> file will be used to rebuild the gem later.  If we need to modify the <code>.gemspec</code> (for instance, if the version of dependencies is wrong for Fedora or the <code>.gemspec</code> is using old, no longer supported fields) we would do it here.  Patches to the code itself can also be done here.
We then run <code>gem spec</code> to output the metadata from the gem into a file.  This <code>.gemspec</code> file will be used to rebuild the gem later.  If we need to modify the <code>.gemspec</code> (for instance, if the version of dependencies is wrong for Fedora or the <code>.gemspec</code> is using old, no longer supported fields) we would do it here.  Patches to the code itself can also be done here.
{{admon/question|Give examples?|We could give examples of modifying the version of a dependency and of commond fields that might need to be removed here.}}


===== %build =====
===== %build =====
Next we build the gem. The first step is to create directories in which to temporarily install the built sources.  We do this because the <code>gem install</code> command both builds and installs the code in one step so we need to have a temporary directory to place the built sources before installing them in <code>%install</code>.  Because <code>gem install</code> only operates on gem archives, we next recreate the gem with <code>gem build</code>. The gem file that is created can then be used by <code>gem install</code> to build and install the code into the temporary directory we created earlier.
Next we build the gem. Because <code>%gem_install</code> only operates on gem archives, we next recreate the gem with <code>gem build</code>. The gem file that is created is then used by <code>%gem_install</code> to build and install the code into the temporary directory, which is <code>./%{gem_dir}</code> by default. We do this because the <code>%gem_install</code> command both builds and installs the code in one step so we need to have a temporary directory to place the built sources before installing them in <code>%install</code> section.


{{admon/question|Do we want to tell what the arguments to gem install do?| The previous guideline did this only for -V (allows checking that CFLAGS was honored)}}
<code>%gem_install</code> macro accepts two additional options:
;<code>-n <gem_file></code>
:Allows to override gem used for installation. This might get useful for converting legacy spec, so you might specify %{SOURCE0} as a gem for installation.
;<code>-d <install_dir></code>
:Might override the gem installation destination. However we do not suggest to use this option.


===== %install =====
{{admon/note||The %gem_install macro '''must not''' be used to install into the <code>%{buildroot}</code>}}
Here we actually install into the <code>%{buildroot}</code>.  We create the directories that we need and then copy what was installed into the temporary directories into the <code>%{buildroot}</code> hierarchy.  Finally, if this ruby gem creates shared objects the shared objects are moved into the arch specific <code>%{gem_extdir}</code> path.


{{admon/question|Replacement instructions|Replace all of the following build instructions with the one above.  The one above conforms to the standard spec file %prep, %build, and %install sections and allows patching in all instances.}}
{{admon/question|TODO| Continue to merge the below instructions and explanations into this section.}}


{{admon/warning|Following lines summarize the approach suggested by Ruby SIG|Advantages: significantly shorter; obvious to people from Ruby world, who would want to start packaging; effective in 99 % of cases; doesn't include the unnecessary patching of gemspec generated by <code>gem spec</code> command. Recommendation: the only case, when the FPC suggested approach is really needed is when the gem extension fails to build, so leave it as a fallback for these cases (has been needed for one out of cca 250 packages so far).}}
===== %install =====
Here we actually install into the <code>%{buildroot}</code>.  We create the directories that we need and then copy what was installed into the temporary directories into the <code>%{buildroot}</code> hierarchy. Finally, if this ruby gem creates shared objects the shared objects are moved into the arch specific <code>%{gem_extdir_mri}</code> path.


* The <code>%prep</code> section '''should''' contain the local <code>gem install</code> similar to this (assuming that the <code>%{gem_name}-%{version}.gem</code> is <code>SOURCE0</code>):
==== Patching required gem versions ====
<pre>
One common patching need is to change overly strict version requirements in the upstream gemspec. This may be because upstream's gemspec only mentions versions that they've explicitly tested against but we know that a different version will also work or because we know that the packages we ship have applied fixes for problematic behaviour without bumping the version number (for instance, backported fixes). To fix these issues, find the <code>add_runtime_dependency</code> call in the gemspec and patch it with the corrected version similar to this:
%setup -q -c -T
mkdir -p .%{gem_dir}
gem install \
-V \
--local \
        --install-dir .%{gem_dir} \
--force \
--rdoc \
%{SOURCE0}
</pre>
* If the Gem contains executable files, you '''must''' ad <code>--bindir .%{_bindir}</code> option to the <code>gem install</code> command.
* The <code>%build</code> section of the specfile '''should''' be empty.
* The <code>%install</code> section should then be used to copy the files to appropriate directory structure under <code>%{buildroot}</code>, for example:
<pre>
mkdir -p %{buildroot}%{gem_dir}
cp -a .%{gem_dir}/* \
        %{buildroot}%{gem_dir}/
</pre>
* If the Gem contains executable files, you '''must''' also add:
<pre>
mkdir -p %{buildroot}%{_bindir}
cp -a .%{_bindir}/* \
        %{buildroot}%{_bindir}/
</pre>
* The Gem '''must''' be installed into <code>%{gem_dir}</code>.
* The package '''must''' own the following files and directories:
<pre>
%dir %{gem_instdir}
%{gem_libdir}
%{gem_spec}
%doc %{gem_docdir}
</pre>
* Since the Gem is installed using RPM, you '''must''' exclude the .gem file. This file is used typically with <code>gem pristine</code> command to restore the Gem into its original state, but this could be achieved by equivalent RPM command. Exclude the cached Gem like this:
<pre>
%exclude %{gem_cache}
</pre>
* If the Gem only contains pure Ruby code, it '''must''' be marked as <code>BuildArch: noarch</code>. If the Gem contains binary content (e.g., for a database driver), it '''must''' be marked as architecture specific.
 
==== RubyGem with extension libraries written in C ====


Some Ruby Gems may contain extension libraries written in C. These Gems carry an [http://docs.rubygems.org/read/chapter/20#extensions extensions] section in their Gem specification file. Their specfiles have to be slightly adjusted to reflect the presence of binary files.
* The %prep section is the same as for pure Ruby Gem, but it '''must''' add [[#configure_args|CONFIGURE_ARGS]] before the <code>gem install</code> command:
<pre>
%setup -q -c -T
mkdir -p .%{gem_dir}
export CONFIGURE_ARGS="--with-cflags='%{optflags}'"
gem install \
-V \
--local \
        --install-dir .%{gem_dir} \
--force \
--rdoc \
%{SOURCE0}
</pre>
* The <code>-V</code> option '''should''' be used with <code>gem install</code> to check if <code>CFLAGS</code> is correctly honored.
* During the <code>%install</code> section all architecture specific content '''must''' be moved from the <code>%{gem_instdir}</code> to the <code>%{gem_extdir}</code>. Usage of %{gem_extdir} assures that the binary files are placed under the proper directory under <code>/usr</code> according to FHS.
<pre>
<pre>
%install
Gem::Specification.new do |s|
mkdir -p %{buildroot}%{gem_dir}
  # [...]
mkdir -p %{buildroot}%{gem_extdir}/foo
- s.add_runtime_dependency(%q<mail>, ["~> 2.2.19"])
cp -a .%{gem_dir}/* %{buildroot}%{gem_dir}/
+  s.add_runtime_dependency(%q<mail>, [">= 2.3.0"])
 
  # [...]
mv %{buildroot}%{gem_instdir}/foo/shared_object.so %{buildroot}%{gem_extdir}/foo/
end
</pre>
</pre>


{{admon/note|Library placement|Please note the <code>foo</code> subdirectory of <code>%{buildroot}%{gem_extdir}</code>. The <code>foo</code> '''must''' be replaced by first path defined by <code>require_paths</code> in Gem specification. Typically, it is replaced either by <code>lib</code> or <code>ext</code>.}}
{{admon/warning|Be sure to test|Do not simply change versions without testing that the new version works. There are times the upstream is overly strict but there are also times when the version requirement was specified because a specific bug was encountered or the API changed in a minor release.}}
 
* The Gem package with C extension '''must''' own the <code>%{gem_extdir}</code> directory.
* Installed C codes (usually under <code>%{gem_instdir}/ext</code>) '''may''' be removed even if <code>gem contents %{gem_name}</code> reports that installed C codes should be found there.
 
==== Packaging for Gem and non-Gem use ====


{{admon/caution|Packaging for non-Gem use is no longer needed| Originally, rubygem modules were not placed in ruby's library path, so we packaged rubygems for use with both gems and non-gems.  The current <code>rubygem</code> module adds all gems to the ruby library path when it is <code>require</code>'d. So, packagers '''must not''' create non-Gem subpackages of rubygems for new packages. Since the majority of Ruby packages in Fedora are now packaged as installed gems, you may need to use <code>require('rubygem')</code> as early in the program as possible to ensure that these ruby components are properly found.  Packages for ruby gems that currently create a non-gem subpackage should be adapted to stop shipping the non-gem subpackage (with a [[Packaging:Guidelines#Renaming.2FReplacing_Existing_Packages | proper Obsoletes and Provides]] in the main rubygem package).}}
=== Packaging for Gem and non-Gem use ===


==== Applying Patches ====
{{admon/caution|Packaging for non-Gem use is no longer needed| Originally, rubygem modules were not placed in ruby's library path, so we packaged rubygems for use with both gems and non-gems. This allowed code that used <code>require('ARubyModulePackagedAsAGem');</code> to function.  The current <code>rubygem</code> module adds all gems to the ruby library path when it is <code>require</code>'d. So, packagers '''must not''' create non-Gem subpackages of rubygems for new packages. Since the majority of Ruby packages in Fedora are now packaged as installed gems, you may need to patch the code to use <code>require('rubygem')</code> as early in the program as possible to ensure that these ruby components are properly found. Packages for ruby gems that currently create a non-gem subpackage should be adapted to stop shipping the non-gem subpackage (with a [[Packaging:Guidelines#Renaming.2FReplacing_Existing_Packages | proper Obsoletes and Provides]] in the main rubygem package).}}
There are several cases, when you need to apply patch to your gem. The following paragraphs tries to demonstrate how to solve the most basic scenarios.
 
===== Ruby Code =====
 
If you are applying a patch to the Ruby code (which is platform independent), the only thing you need to do is just to apply it in the %prep section after the <code>gem install</code> command, for example:
<pre>
%prep
gem install \
-V \
--local \
        --install-dir .%{gem_dir} \
--force \
--rdoc \
%{SOURCE0}
 
pushd .%{gem_instdir}
%patch0 -p1
popd
</pre>
 
===== Binary Extensions =====
 
Sometimes, although you are able to successfully install the gem, you will later encounter some bug in its binary extension which needs patching. In this case, you first need to use the %patch macro as in the previous example and then you '''must''' recompile the extension in %build section. For example:
<pre>
%prep
export CONFIGURE_ARGS="--with-cflags='%{optflags}'"
gem install \
-V \
--local \
        --install-dir .%{gem_dir} \
--force \
--rdoc \
%{SOURCE0}
 
pushd .%{gem_instdir}
%patch0 -p1
popd
 
%build
pushd .%{gem_instdir}/ext
make %{?_smp_mflags}
popd
</pre>
 
===== Binary Extension Fails to Build =====
 
{{admon/warning|Consider alternative package|If you find out that you need this approach, then probably the gem you are about to package is old and unmaintained. Please consider if there is not some more viable alternative.}}
 
If you are packaging a gem with binary extension, which is not ABI/API compatible with Ruby, the gem installation probably fails during compilation of the extension. In this case, you need to apply patch to fix this issue prior the installation. Unfortunately, there is no easy straight forward way how to achieve it ATM. Nevertheless, you can repack the gem with applied patch in %prep section and later install as always. For example:
 
<pre>
%prep
%setup -q -c -T
pushd ..
gem unpack %{SOURCE0}
 
pushd %{gem_name}-%{version}
gem spec %{SOURCE0} -l --ruby > %{gem_name}.gemspec
 
%patch0 -p1
 
gem build %{gem_name}.gemspec
popd
popd
 
mkdir -p ./%{gem_dir}
export CONFIGURE_ARGS="--with-cflags='%{optflags}'"
gem install --local --install-dir ./%{gem_dir} \
--force ../%{gem_name}-%{version}/%{gem_name}-%{version}.gem
</pre>
 
{{admon/note|Might help you|
Please note that the unpacked gem might already contain:
 
* Gem specification (.gemspec). If you like to use it, you must make sure that it is up-to-date.
* Some upstream authors might have pre-prepared rake task, which can package the gem for you, instead of <code>gem build</code> command.
 
However, for consistency, you '''should''' to stay with the approach demonstrated by example above.}}
 
==== Tips for Packagers ====
 
Gems carry a lot of metadata; [https://github.com/lutter/gem2rpm 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.


=== Non-Gem Packages ===
=== Non-Gem Packages ===
Line 368: Line 222:


==== Build Architecture and File Placement ====
==== Build Architecture and File Placement ====
The following only affects the files that the package installs into <code>%{_libdir}/ruby/vendor_ruby</code> (architecture specific) and <code>%{_datadir}/ruby/vendor_ruby</code> (architecture independent), i.e. Ruby library files. All other files in a Ruby package must adhere to the general Fedora Extras packaging conventions.
The following only affects the files that the package installs into <code>%{ruby_vendorarchdir} </code> and <code>%{ruby_vendorlibdir}</code> (the actual Ruby library files). All other files in a Ruby package must adhere to the general Fedora packaging conventions.




Line 400: Line 254:
== Applications ==
== Applications ==


By applications we mean:
Applications are
* programmes that provide user-level tools or
 
* programs that provide user-level tools or
* web applications, typically built using Rails, Sinatra or similar frameworks.  
* web applications, typically built using Rails, Sinatra or similar frameworks.  


The RPM packages '''must''' obey FHS rules, it means that they should be installed into %{_datadir}. Following macro can help you:
The RPM packages '''must''' obey FHS rules.  They should be installed into <code>%{_datadir}</code>. The following macro can help you:
<pre>
<pre>
%global app_root %{_datadir}/%{name}
%global app_root %{_datadir}/%{name}
</pre>
</pre>
These packages typically have no "Provides" section, since no other libraries or applications depend on them.
These packages typically have no "Provides" section, since no other libraries or applications depend on them.


A good example is the initial specfile of deltacloud-core package (shortened here):
Here's an abbreviated example:
 
<pre>
<pre>
%global app_root %{_datadir}/%{name}
%global app_root %{_datadir}/%{name}
Line 422: Line 279:
URL: http://incubator.apache.org/deltacloud
URL: http://incubator.apache.org/deltacloud
Source0: http://gems.rubyforge.org/gems/%{name}-%{version}.gem
Source0: http://gems.rubyforge.org/gems/%{name}-%{version}.gem
Requires: rubygem(haml)
Requires: rubygem-haml
#...
#...
Requires(post):  chkconfig
Requires(post):  chkconfig
#...
#...
BuildRequires: rubygem(haml)
BuildRequires: rubygem-haml
#...
#...
BuildArch: noarch
BuildArch: noarch
Line 445: Line 302:


%prep
%prep
%setup -q -c -T  
gem unpack -V %{SOURCE0}
gem unpack -V --target=%{_builddir} %{SOURCE0}
%setup -q -D -T -n %{name}-%{version}


%build
%build
Line 454: Line 311:
mkdir -p %{buildroot}%{_initddir}
mkdir -p %{buildroot}%{_initddir}
mkdir -p %{buildroot}%{_bindir}
mkdir -p %{buildroot}%{_bindir}
cp -r %{_builddir}/%{name}-%{version}/* %{buildroot}%{app_root}
cp -r * %{buildroot}%{app_root}
mv %{buildroot}%{app_root}/support/fedora/%{name} %{buildroot}%{_initddir}
mv %{buildroot}%{app_root}/support/fedora/%{name} %{buildroot}%{_initddir}
find %{buildroot}%{app_root}/lib -type f | xargs chmod -x
find %{buildroot}%{app_root}/lib -type f | xargs chmod -x
Line 483: Line 340:
</pre>
</pre>


Note, that although the source is a RubyGem, <code>gem unpack</code> is used instead of common <code>gem install</code> to extract the application and library files. These are then placed under %{_datadir}/%{name}, %{_bindir}, etc. to follow FHS and general packaging guidelines.
Note, that although the source is a RubyGem, we have to install the files manually under %{_datadir}/%{name}, %{_bindir}, etc. to follow FHS and general packaging guidelines. If additional Fedora specific files (systemd <code>.service</code> files, configurations) are required, they '''should''' be
If additional Fedora specific files (systemd <code>.service</code> files, configurations) are required, they '''should''' be
* added via another <code>%SOURCE</code> tags
* added via another <code>%SOURCE</code> tags
<pre>
<pre>
Line 494: Line 350:
</pre>
</pre>


== Running test suite ==
== Running test suites ==


If there is test suite available for the package (even separately, for example not included in the Gem, but available in the upstream repository), you '''should''' run it. The test suite is the only automated tool which could assure basic functionality of package. This is helpful when mass rebuild is required for example. You could skip test suite execution in case when not all build dependencies are met, but this '''must''' be documented in specfile. Nevertheless, the build dependencies should be imported into Fedora as soon as possible.
If there is test suite available for the package (even separately, for example not included in the gem but available in the upstream repository), it '''should''' be run in <code>%check</code>. The test suite is the only automated tool which can assure basic functionality of the package. Running it is especially helpful when mass rebuilds are required. You may skip test suite execution when not all build dependencies are met but this '''must''' be documented in the specfile. The missing build dependencies to enable the test suite should be packaged for Fedora as soon as possible and the test suite re-enabled.


The tests '''should not''' be run using Rake - Rake almost always draws in some unnecessary dependencies like hoe or gemcutter.
The tests '''should not''' be run using Rake - Rake almost always draws in some unnecessary dependencies like hoe or gemcutter.
{{admon/note|Do not ship tests|Normally tests are only run at package buildtime.  They should not be included in the binary rpms that users install on their systems.  You may make an exception for this if the package makes public use of the test suite at runtime (for instance, an application package that has a <code>--selftest</code> command line switch that runs its testsuite.)}}
=== Testing With Different Ruby Implementations ===
To run tests with different Ruby implementation such as JRuby, you need to <code>BuildRequires: jruby</code>. Then use Rubypick's interpreter switching:
<pre>
  ruby _jruby_ -Ilib -e 'Dir.glob "./test/test_*.rb", &method(:require)'
</pre>
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.


=== Testing frameworks usage ===
=== Testing frameworks usage ===


Ruby community provides and supports various testing frameworks. Following paragraphs demonstrates how the test suite can be executed. Please note that the list is not exhaustive.
The Ruby community supports many testing frameworks. The following sections demonstrate how several to execute several of the more common test suites.


==== MiniTest ====
==== MiniTest ====


MiniTest is default testing framework shipped together with Ruby, however unbundled in Fedora (you must use BuildRequires: rubygem(minitest)). To run the tests using MiniTest, you can usually use something like
MiniTest is the default testing framework shipped with Ruby.  It is unbundled in Fedora (you must use <code>BuildRequires: rubygem-minitest</code>). To run tests using MiniTest you can use something like:
 
<pre>
<pre>
testrb -Ilib test
%check
ruby -Ilib -e 'Dir.glob "./test/test_*.rb", &method(:require)'
</pre>
</pre>
The <code>testrb</code> utility is deprecated and is not present in newer Ruby versions. If a gem's tests support Minitest, the <code>testrb</code> utility should not be used during %check. Instead of <code>testrb</code>, users should call <code>ruby</code> directly in the %check section as shown above.
You may need to adjust <code>-Ilib</code> to be <code>-Ilib:test</code>, or you may need to use a slightly different matching pattern for <code>test_*.rb</code>, etc. Packagers are expected to use the right pattern for each gem.


==== Test::UNIT ====
==== Test::UNIT ====


To run the tests using Test::Unit (you must use <code>BuildRequires: rubygem(test-unit)</code>), you can usually use something like
To run tests using Test::Unit you must <code>BuildRequires: rubygem-test-unit-</code> and use something like this:
 
<pre>
<pre>
%check
testrb2 -Ilib test
testrb2 -Ilib test
</pre>
</pre>


{{Template:Note}} Please note that test suite which runs using Test::UNIT can be typically executed also by MiniTest. In that case, please prefer MiniTest.
{{admon/note|| Test suites which run using Test::UNIT can typically also be executed by MiniTest. In that case, please prefer MiniTest.}}


==== RSpec ====
==== RSpec ====


To run the tests using RSpec >= 2 (you must use <code>BuildRequires: rubygem(rspec)</code>), you can usually use something like
To run tests using RSpec >= 2 you must <code>BuildRequires: rubygem-rspec</code> and use something like:
 
<pre>
<pre>
%check
rspec -Ilib spec
rspec -Ilib spec
</pre>
</pre>


=== Test suite not included in package ===


Typical way of getting the tests separately from upstream follows - lets suppose you're packaging rubygem-delorean, version 1.2.0, which is hosted on Git. Tests are not included in the Gem itself, so you need to get them and adjust the specfile accordingly:
=== Test suites not included in the package ===
 
Sometimes you have to get the tests separately from upstream's gem package.  As an example lets suppose you're packaging <code>rubygem-delorean</code>, 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:
 
<pre>
<pre>
# git clone https://github.com/bebanjo/delorean.git && cd delorean
# git clone https://github.com/bebanjo/delorean.git && cd delorean
Line 535: Line 414:
# tar -czf rubygem-delorean-1.2.0-specs.tgz spec/
# tar -czf rubygem-delorean-1.2.0-specs.tgz spec/
Source1: %{name}-%{version}-specs.tgz
Source1: %{name}-%{version}-specs.tgz
# ...
%prep
%setup -q -D -T -n %{gem_name}-%{version}
tar -xzf %{SOURCE1}


# ...
# ...


%check
%check
pushd .%{gem_instdir}
cp -pr spec/ ./%{gem_instdir}
tar xzf %{SOURCE1}
pushd ./%{gem_instdir}
# Run tests
rm -rf spec
popd
popd


Line 546: Line 433:


</pre>
</pre>
* Make sure to include the version of the tests in the source name, so that when updating to new version, rpmbuild will fail because it won't find the proper %SOURCE1 (and this will remind you to update the tests, too).
* Make sure to include the version of the tests in the source name, so that when updating to new version, rpmbuild will fail because it won't find the proper <code>%{SOURCE1}</code> (and this will remind you to update the tests, too).
* Add the commands you used to get the tests into the specfile as comments. This will make it a lot easier the next time you will need to get them.
* Add the commands you used to get the tests into the specfile as comments. This will make it a lot easier the next time you will need to get them.
* Run the tests as you normally would.
* Run the tests as you normally would.


[[Category:Packaging guidelines drafts]]
[[Category:Packaging guidelines drafts]]

Latest revision as of 19:33, 14 October 2016

Different guidelines for packages in EPEL 5
In RHEL 5 a ruby version that does not have all the features needed to support these guidelines exists. If you're packaging for EPEL 5 you should follow the old ruby guidelines instead.
Different Guidelines for Fedora 19/20 and EPEL6/7
In Fedora 19/20 and EPEL 6/7 the Ruby guidelines were slightly different. Some of the macros and practices listed here did not work. Please see this [earlier version of the guidelines] if you want your package to work on those versions of Fedora/EPEL
JRuby Gems
Although Fedora 19 has fully functioning JRuby integrated with system RubyGems, we have decided to not include the JRuby specific packaging guidelines here, as they need some more work. They will appear here as soon as we feel that we've got everything covered properly. You can contact us on Ruby-SIG mailing list in case of any questions about the prepared JRuby packaging guidelines.

There are three basic categories of ruby packages: ruby gems, non-gem ruby packages, and applications written in ruby. These guidelines contain sections common to all of these as well as sections which apply to each one individually. Be sure to read all the guidelines relevant to the type of ruby package you are building.


Ruby Compatibility

Each Ruby package must indicate it depends on a Ruby interpreter (this does not apply to ruby gem packages). Use ruby(release) virtual requirement to achieve that:

Requires: ruby(release)

If the package requires Ruby of certain version(s), make the requirement versioned like this:

Requires: ruby(release) >= 1.9.1
Alternate interpreters
Alternate Ruby interpreters (currently JRuby) also Provide: ruby(release). This implies, that pure RubyGems packages (these are shared among interpreters) should not have Requires: ruby or Requires: jruby to have their dependencies satisfied by any of these interpreters.
Over specified ruby(release) versioning
Please note, that if the ruby(release) version requirement is too specific, it may cause an unexpected interpreter to be drawn in. E.g. ruby(release) = 1.8 will require JRuby package, since it is the only package that provides it.

Different Interpreters Compatibility

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.

Shebang lines

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:

ruby _jruby_ jruby_script.rb
gem _mri_ install foo
rails _jruby_ s

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

export RUBYPICK=_jruby_
ruby jruby_script.rb  # Will use jruby
gem install foo        # Will also use jruby

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.

Naming Guidelines

  • Packages that contain Ruby Gems must be called rubygem-%{gem_name}.
  • The name of a ruby extension/library package must start with the interpreter it is built for (ruby, jruby, etc) and then the UPSTREAM name. For example: 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.
  • Application packages that mainly provide user-level tools that happen to be written in Ruby must follow the general NamingGuidelines instead.

Macros

Non-gem ruby packages and ruby gem packages install to certain standard locations. The ruby-devel and rubygems-devel packages contain macros useful for the respective package types. Alternate ruby interpreters will have equivalent locations (To be added to this table later)

Macro Expanded path Usage
From ruby-devel; intended for non-gem packages.
%{ruby_vendorarchdir} /usr/lib{64}/ruby/vendor_ruby Place for architecture specific (e.g. *.so) files.
%{ruby_vendorlibdir} /usr/share/ruby/vendor_ruby Place for architecture independent (e.g. *.rb) files.
%{ruby_sitearchdir} /usr/local/lib{64}/ruby/site_ruby Place for local architecture specific (e.g. *.so) files.
%{ruby_sitelibdir} /usr/local/share/ruby/site_ruby Place for local architecture independent (e.g. *.rb) files.
From rubygems-devel; intended for gem packages
%{gem_dir} /usr/share/gems Top directory for the Gem structure.
%{gem_instdir} %{gem_dir}/gems/%{gem_name}-%{version} Directory with the actual content of the Gem.
%{gem_libdir} %{gem_instdir}/lib The lib folder of the Gem.
%{gem_cache} %{gem_dir}/cache/%{gem_name}-%{version}.gem The cached Gem.
%{gem_spec} %{gem_dir}/specifications/%{gem_name}-%{version}.gemspec The Gem specification file.
%{gem_docdir} %{gem_dir}/doc/%{gem_name}-%{version} The rdoc documentation of the Gem.
%{gem_extdir_mri} %{_libdir}/gems/ruby/%{gem_name}-%{version} The directory for MRI Ruby Gem extensions.

Interpreter independence and directory macros

You may 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.

Libraries

These 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 must follow the ruby applications guidelines instead.

RubyGems

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 RPM's in a way that such RPM's fit cleanly with the rest of the distribution and to 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 are specfiles, package names, dependencies etc. for both. To keep confusion to a minimum, terms relating to Gem concepts will be explicitly refereed to with the word 'Gem' prefixed, eg 'Gem specification' (.gemspec). An unqualified 'package' in the following always means an RPM.

  • Spec files must 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.
  • The package must BuildRequires: rubygems-devel to pull in the macros needed to build.
  • There should not be any rubygem Requires nor Provides listed, since those are autogenerated.
  • There should not be Requires: ruby(release), unless you want to explicitly specify Ruby version compatibility. Automatically generated dependency on RubyGems (Requires: ruby(rubygems)) is enough.


Filtering Requires and Provides

Runtime requires and provides are automatically generated by RPM's dependency generator. However, it can sometimes throw in additional dependencies contrary to reality. To fix this, the dependency generator needs to be overridden so that the additional dependencies can be filtered out. See Packaging:AutoProvidesAndRequiresFiltering for details.

Building gems

Since gems aren't a standard archive format that rpm knows about and they encapsulate both an archive format and information to build the ruby library building an rpm from a gem looks a little different from other rpms.

A sample spec for building gems would look like this:

%prep
gem unpack %{SOURCE0}
%setup -q -D -T -n  %{gem_name}-%{version}

gem spec %{SOURCE0} -l --ruby > %{gem_name}.gemspec

# Modify the gemspec if necessary with a patch or sed
# Also apply patches to code if necessary
%patch0 -p1

%build
# Create the gem as gem install only works on a gem file
gem build %{gem_name}.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
%gem_install

%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}/
%prep

Since gems aren't an archive format that rpm recognizes, the first thing we have to do is explicitly use gem unpack to extract the source from the gem. Then we call %setup -n %{gem_name}-%{version} to tell rpm what the directory the gem has unpacked into. The -T and -D flags tell %setup that we've already unpacked the code

We then run gem spec to output the metadata from the gem into a file. This .gemspec file will be used to rebuild the gem later. If we need to modify the .gemspec (for instance, if the version of dependencies is wrong for Fedora or the .gemspec is using old, no longer supported fields) we would do it here. Patches to the code itself can also be done here.

%build

Next we build the gem. Because %gem_install only operates on gem archives, we next recreate the gem with 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. We do this because the %gem_install command both builds and installs the code in one step so we need to have a temporary directory to place the built sources before installing them in %install section.

%gem_install macro accepts two additional options:

-n <gem_file>
Allows to override gem used for installation. This might get useful for converting legacy spec, so you might specify %{SOURCE0} as a gem for installation.
-d <install_dir>
Might override the gem installation destination. However we do not suggest to use this option.
The %gem_install macro must not be used to install into the %{buildroot}


%install

Here we actually install into the %{buildroot}. We create the directories that we need and then copy what was installed into the temporary directories into the %{buildroot} hierarchy. Finally, if this ruby gem creates shared objects the shared objects are moved into the arch specific %{gem_extdir_mri} path.

Patching required gem versions

One common patching need is to change overly strict version requirements in the upstream gemspec. This may be because upstream's gemspec only mentions versions that they've explicitly tested against but we know that a different version will also work or because we know that the packages we ship have applied fixes for problematic behaviour without bumping the version number (for instance, backported fixes). To fix these issues, find the add_runtime_dependency call in the gemspec and patch it with the corrected version similar to this:

Gem::Specification.new do |s|
  # [...]
-  s.add_runtime_dependency(%q<mail>, ["~> 2.2.19"])
+  s.add_runtime_dependency(%q<mail>, [">= 2.3.0"])
  # [...]
end
Be sure to test
Do not simply change versions without testing that the new version works. There are times the upstream is overly strict but there are also times when the version requirement was specified because a specific bug was encountered or the API changed in a minor release.

Packaging for Gem and non-Gem use

Packaging for non-Gem use is no longer needed
Originally, rubygem modules were not placed in ruby's library path, so we packaged rubygems for use with both gems and non-gems. This allowed code that used require('ARubyModulePackagedAsAGem'); to function. The current rubygem module adds all gems to the ruby library path when it is require'd. So, packagers must not create non-Gem subpackages of rubygems for new packages. Since the majority of Ruby packages in Fedora are now packaged as installed gems, you may need to patch the code to use require('rubygem') as early in the program as possible to ensure that these ruby components are properly found. Packages for ruby gems that currently create a non-gem subpackage should be adapted to stop shipping the non-gem subpackage (with a proper Obsoletes and Provides in the main rubygem package).

Non-Gem Packages

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.


Build Architecture and File Placement

The following only affects the files that the package installs into %{ruby_vendorarchdir} and %{ruby_vendorlibdir} (the actual Ruby library files). All other files in a Ruby package must adhere to the general Fedora packaging conventions.


Site versus Vendor
Previously, %{ruby_sitelibdir} and %{ruby_sitearchdir} were used. However, as they are meant only for local installations, please use %{ruby_vendorlibdir} and %{ruby_vendorarchdir} instead.

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 %{ruby_vendorlibdir} (or its proper subdirectory). The specfile must use this macro.

Ruby packages with binary content/shared libraries

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 %{ruby_vendorarchdir} (or its proper subdirectory). The Ruby files in such a package should be placed into %{ruby_vendorlibdir}. The specfile must use these macros.

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. Also, to place the files into the correct folders during build, pass --vendor to extconf.rb like this:

extconf.rb --vendor

Applications

Applications are

  • programs that provide user-level tools or
  • web applications, typically built using Rails, Sinatra or similar frameworks.

The RPM packages must obey FHS rules. They should be installed into %{_datadir}. The following macro can help you:

%global app_root %{_datadir}/%{name}

These packages typically have no "Provides" section, since no other libraries or applications depend on them.

Here's an abbreviated example:

%global app_root %{_datadir}/%{name}

Summary: Deltacloud REST API
Name: deltacloud-core
Version: 0.3.0
Release: 3%{?dist}
Group: Development/Languages
License: ASL 2.0 and MIT
URL: http://incubator.apache.org/deltacloud
Source0: http://gems.rubyforge.org/gems/%{name}-%{version}.gem
Requires: rubygem-haml
#...
Requires(post):   chkconfig
#...
BuildRequires: rubygem-haml
#...
BuildArch: noarch

%description
The Deltacloud API is built as a service-based REST API.
You do not directly link a Deltacloud library into your program to use it.
Instead, a client speaks the Deltacloud API over HTTP to a server
which implements the REST interface.

%package doc
Summary: Documentation for %{name}
Group: Documentation
Requires:%{name} = %{version}-%{release}

%description doc
Documentation for %{name}

%prep
gem unpack -V %{SOURCE0}
%setup -q -D -T -n %{name}-%{version}

%build

%install
mkdir -p %{buildroot}%{app_root}
mkdir -p %{buildroot}%{_initddir}
mkdir -p %{buildroot}%{_bindir}
cp -r * %{buildroot}%{app_root}
mv %{buildroot}%{app_root}/support/fedora/%{name} %{buildroot}%{_initddir}
find %{buildroot}%{app_root}/lib -type f | xargs chmod -x
chmod 0755 %{buildroot}%{_initddir}/%{name}
chmod 0755 %{buildroot}%{app_root}/bin/deltacloudd
rm -rf %{buildroot}%{app_root}/support
rdoc --op %{buildroot}%{_defaultdocdir}/%{name}

%post
# This adds the proper /etc/rc*.d links for the script
/sbin/chkconfig --add %{name}

%files
%{_initddir}/%{name}
%{_bindir}/deltacloudd
%dir %{app_root}/
%{app_root}/bin
#...

%files doc
%{_defaultdocdir}/%{name}
%{app_root}/tests
%{app_root}/%{name}.gemspec
%{app_root}/Rakefile

%changelog
#...

Note, that although the source is a RubyGem, we have to install the files manually under %{_datadir}/%{name}, %{_bindir}, etc. to follow FHS and general packaging guidelines. If additional Fedora specific files (systemd .service files, configurations) are required, they should be

  • added via another %SOURCE tags
Source1: deltacloudd-fedora
  • placed into appropriate locations during %install stage
install -m 0755 %{SOURCE1} %{buildroot}%{_bindir}/deltacloudd

Running test suites

If there is test suite available for the package (even separately, for example not included in the gem but available in the upstream repository), it should be run in %check. The test suite is the only automated tool which can assure basic functionality of the package. Running it is especially helpful when mass rebuilds are required. You may skip test suite execution when not all build dependencies are met but this must be documented in the specfile. The missing build dependencies to enable the test suite should be packaged for Fedora as soon as possible and the test suite re-enabled.

The tests should not be run using Rake - Rake almost always draws in some unnecessary dependencies like hoe or gemcutter.

Do not ship tests
Normally tests are only run at package buildtime. They should not be included in the binary rpms that users install on their systems. You may make an exception for this if the package makes public use of the test suite at runtime (for instance, an application package that has a --selftest command line switch that runs its testsuite.)

Testing With Different Ruby Implementations

To run tests with different Ruby implementation such as JRuby, you need to BuildRequires: jruby. Then use Rubypick's interpreter switching:

  ruby _jruby_ -Ilib -e 'Dir.glob "./test/test_*.rb", &method(:require)'

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.

Testing frameworks usage

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

MiniTest

MiniTest is the default testing framework shipped with Ruby. It is unbundled in Fedora (you must use BuildRequires: rubygem-minitest). To run tests using MiniTest you can use something like:

%check
ruby -Ilib -e 'Dir.glob "./test/test_*.rb", &method(:require)'

The testrb utility is deprecated and is not present in newer Ruby versions. If a gem's tests support Minitest, the testrb utility should not be used during %check. Instead of testrb, users should call ruby directly in the %check section as shown above.

You may need to adjust -Ilib to be -Ilib:test, or you may need to use a slightly different matching pattern for test_*.rb, etc. Packagers are expected to use the right pattern for each gem.

Test::UNIT

To run tests using Test::Unit you must BuildRequires: rubygem-test-unit- and use something like this:

%check
testrb2 -Ilib test
Test suites which run using Test::UNIT can typically also be executed by MiniTest. In that case, please prefer MiniTest.

RSpec

To run tests using RSpec >= 2 you must BuildRequires: rubygem-rspec and use something like:

%check
rspec -Ilib spec


Test suites not included in the package

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:

# git clone https://github.com/bebanjo/delorean.git && cd delorean
# git checkout v1.2.0
# tar -czf rubygem-delorean-1.2.0-specs.tgz spec/
Source1: %{name}-%{version}-specs.tgz

# ...
%prep
%setup -q -D -T -n %{gem_name}-%{version}

tar -xzf %{SOURCE1}

# ...

%check
cp -pr spec/ ./%{gem_instdir}
pushd ./%{gem_instdir}
# Run tests
rm -rf spec
popd

# ...

  • Make sure to include the version of the tests in the source name, so that when updating to new version, rpmbuild will fail because it won't find the proper %{SOURCE1} (and this will remind you to update the tests, too).
  • Add the commands you used to get the tests into the specfile as comments. This will make it a lot easier the next time you will need to get them.
  • Run the tests as you normally would.