Packaging:Ruby

= Ruby 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 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 start with the interpreter it is built for (ruby, jruby, etc) and then the  name.  For example:  . 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.

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 (for instance, ). 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  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  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 gem unpack %{SOURCE0} %setup -q -D -T -n %{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

%build mkdir -p .%{gem_dir}

gem build %{gem_name}.gemspec
 * 1) Create the gem as gem install only works on a gem file

export CONFIGURE_ARGS="--with-cflags='%{optflags}'" gem install -V \ --local \ --install-dir ./%{gem_dir} \ --bindir ./%{_bindir} \ --force \ --rdoc \ %{gem_name}-%{version}.gem
 * 1) gem install compiles any C extensions and installs into a directory
 * 2) We set that to be a local directory so that we can move it into the
 * 3) buildroot in %install

%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) You should replace REQUIRE_PATHS with 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
Since gems aren't an archive format that rpm recognizes, the first thing we have to do is explicitly use  to extract the source from the gem. Then we call  to tell rpm what the directory the gem has unpacked into. The and  flags tell   that we've already unpacked the code

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

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  call in the gemspec and patch it with the corrected version similar to this:

Gem::Specification.new do |s| # [...] - s.add_runtime_dependency(%q, ["~> 2.2.19"]) + s.add_runtime_dependency(%q, [">= 2.3.0"]) # [...] end

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  and   (the actual Ruby library files). All other files in a Ruby package must adhere to the general Fedora 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
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. 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 /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, 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  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 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. 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.

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 ). To run tests using MiniTest you can use something like:

%check testrb -Ilib test

Test::UNIT
To run tests using Test::Unit you must  and use something like this:

%check testrb2 -Ilib test

RSpec
To run tests using RSpec >= 2 you must  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, 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:

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/

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

tar -xzf %{SOURCE1}



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




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