PackagingDrafts/Ruby

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 ABI
Each Ruby package must indicate the Ruby ABI version it depends on with a line like Requires: ruby(abi) = 1.9.1

Naming Guidelines

 * Packages that contain Ruby Gems must be called.


 * The name of a ruby extension/library package must be of the form . If the upstream name   contains , that should be dropped from the name. For example, the SQLite database driver for ruby is called  . The corresponding Fedora package should be called  , and not.


 * 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  and   packages contain macros useful for the respective package types.

Dependencies
Due to having multiple types of libraries (gems and non-gems) there are two ways to specify dependencies.

Requires
If your package uses  or you're packaging a ruby gem that depends on the library in its   (See the section on  building gems for more information) you Must use   so the rpm will pull in the correct ruby library.

If your package just uses  it's always fine to use. If you know that the ruby library is provided as a gem despite using  you may use   instead but this is not required as it forces packagers to know unnecessary details of how another ruby package has been created.

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  to work with the Fedora version of the package (see the section on  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. The string  Must be the same as what is used in the   statement in a Ruby script that uses the library. The  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. The specfile for the corresponding Fedora package must contain a line, assuming the package contains version 1.1.0 of the library.

Gem packages must have two provides: Provides: ruby(RUBYLIBRARY) = VERSION Provides: rubygem(%{gem_name}) = %{version}

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

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.


 * Spec files must contain a definition of, which is the name from the Gem's specification.
 * The  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  to pull in the macros needed to build.

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 %setup -q -T -n %{gem_name}-%{version} gem unpack %{SOURCE0} pushd %{gem_name}-%{version}

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

popd

%build mkdir -p ./%{gem_dir} mkdir -p ./%{_bindir}

gem build %{gem_name}.gemspec export CONFIGURE_ARGS="--with-cflags='%{optflags}'" gem install -V \ --local \ --install-dir ./%{gem_dir} \ --bindir .%{_bindir} \ --force \ --rdoc ../%{gem_name}-%{version}/%{gem_name}-%{version}.gem
 * 1) Create the gem as gem install only works on a gem file
 * 1) gem install compiles any C extensions and installs into a directory

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

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

mkdir -p %{buildroot}%{gem_extdir}/$REQUIRE_PATHS mv %{buildroot}%{gem_instdir}/$REQUIRE_PATHS/shared_object.so %{buildroot}%{gem_extdir}/$REQUIRE_PATHS/
 * 1) If there are C extensions, mv them to the extdir.
 * 2) $REQUIRE_PATHS is taken from the first value of the require_paths field in
 * 3) the gemspec file.  It will typically be either "lib" or "ext".  For instance:
 * 4)  s.require_paths = ["lib"]

%prep
In the  section we first use   to tell rpm what the directory the gem will unpack into. We use the  flag to tell   not to try unpacking the source on its own. Then we explicitly use  to extract the source from the gem and switch into the directory. This is equivalent to the steps that  would take if gem was a recognized archive format.

We then run  to output the metadata from the gem into a file. This  file will be used to rebuild the gem later. If we need to modify the  (for instance, if the version of dependencies is wrong for Fedora or the   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. The first step is to create directories in which to temporarily install the built sources. We do this because the  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. Because  only operates on gem archives, we next recreate the gem with. The gem file that is created can then be used by  to build and install the code into the temporary directory we created earlier.

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

%setup -q -c -T mkdir -p .%{gem_dir} gem install \ -V \ --local \ --install-dir .%{gem_dir} \ --force \ --rdoc \ %{SOURCE0} mkdir -p %{buildroot}%{gem_dir} cp -a .%{gem_dir}/* \ %{buildroot}%{gem_dir}/ mkdir -p %{buildroot}%{_bindir} cp -a .%{_bindir}/* \ %{buildroot}%{_bindir}/ %dir %{gem_instdir} %{gem_libdir} %{gem_spec} %doc %{gem_docdir} %exclude %{gem_cache}
 * The  section should contain the local   similar to this (assuming that the   is  ):
 * If the Gem contains executable files, you must ad  option to the   command.
 * The  section of the specfile should be empty.
 * The  section should then be used to copy the files to appropriate directory structure under , for example:
 * If the Gem contains executable files, you must also add:
 * The Gem must be installed into.
 * The package must own the following files and directories:
 * Since the Gem is installed using RPM, you must exclude the .gem file. This file is used typically with  command to restore the Gem into its original state, but this could be achieved by equivalent RPM command. Exclude the cached Gem like this:
 * If the Gem only contains pure Ruby code, it must be marked as . 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 extensions section in their Gem specification file. Their specfiles have to be slightly adjusted to reflect the presence of binary files. %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} %install mkdir -p %{buildroot}%{gem_dir} mkdir -p %{buildroot}%{gem_extdir}/foo cp -a .%{gem_dir}/* %{buildroot}%{gem_dir}/
 * The %prep section is the same as for pure Ruby Gem, but it must add CONFIGURE_ARGS before the  command:
 * The  option should be used with   to check if   is correctly honored.
 * During the  section all architecture specific content must be moved from the   to the  . Usage of %{gem_extdir} assures that the binary files are placed under the proper directory under   according to FHS.

mv %{buildroot}%{gem_instdir}/foo/shared_object.so %{buildroot}%{gem_extdir}/foo/


 * The Gem package with C extension must own the  directory.
 * Installed C codes (usually under ) may be removed even if   reports that installed C codes should be found there.

Applying Patches
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  command, for example: %prep gem install \ -V \ --local \ --install-dir .%{gem_dir} \ --force \ --rdoc \ %{SOURCE0}

pushd .%{gem_instdir} %patch0 -p1 popd

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: %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

Binary Extension Fails to Build
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:

%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

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.

Non-Gem Packages
Non-Gem Ruby packages must require ruby-devel package at build time with a, 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  (architecture specific) and   (architecture independent), 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  (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  (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

export CONFIGURE_ARGS="--with-cflags='%{optflags}'" should be used to pass  to   correctly. Also, to place the files into the correct folders during build, pass  to   like this: extconf.rb --vendor

Applications
By applications we mean:
 * programmes that provide user-level tools or
 * 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: %global app_root %{_datadir}/%{name} 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): %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 %setup -q -c -T gem unpack -V --target=%{_builddir} %{SOURCE0}

%build

%install mkdir -p %{buildroot}%{app_root} mkdir -p %{buildroot}%{_initddir} mkdir -p %{buildroot}%{_bindir} cp -r %{_builddir}/%{name}-%{version}/* %{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 /sbin/chkconfig --add %{name}
 * 1) This adds the proper /etc/rc*.d links for the script

%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,  is used instead of common   to extract the application and library files. These are then placed under %{_datadir}/%{name}, %{_bindir}, etc. to follow FHS and general packaging guidelines. If additional Fedora specific files (systemd  files, configurations) are required, they should be Source1: deltacloudd-fedora install -m 0755 %{SOURCE1} %{buildroot}%{_bindir}/deltacloudd
 * added via another  tags
 * placed into appropriate locations during  stage

Running test suite
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.

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

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.

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 testrb -Ilib test

Test::UNIT
To run the tests using Test::Unit (you must use ), you can usually use something like testrb2 -Ilib test

Please note that test suite which runs using Test::UNIT can be typically executed also by MiniTest. In that case, please prefer MiniTest.

RSpec
To run the tests using RSpec >= 2 (you must use ), you can usually use something like rspec -Ilib spec

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: Source1: %{name}-%{version}-specs.tgz
 * 1) git clone https://github.com/bebanjo/delorean.git && cd delorean
 * 2) git checkout v1.2.0
 * 3) tar -czf rubygem-delorean-1.2.0-specs.tgz spec/



%check pushd .%{gem_instdir} tar xzf %{SOURCE1} 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.