m (Packaging/Ruby moved to Packaging:Ruby: Moving Packaging Pages to Packaging Namespace) |
No edit summary |
||
Line 40: | Line 40: | ||
%{!?ruby_sitearch: %define ruby_sitearch %(ruby -rrbconfig -e 'puts Config::CONFIG["sitearchdir"] ')} | %{!?ruby_sitearch: %define ruby_sitearch %(ruby -rrbconfig -e 'puts Config::CONFIG["sitearchdir"] ')} | ||
</pre> | </pre> | ||
For packages which create C shared libraries using <code>extconf.rb</code> | |||
<pre> | |||
export CONFIGURE_ARGS="--with-cflags='%{optflags}'" | |||
</pre> | |||
'''should''' be used to pass <code>CFLAGS</code> to <code>Makefile</code> correctly. | |||
This also applies to Ruby Gems. | |||
== Ruby Gems == | == Ruby Gems == | ||
Line 68: | Line 75: | ||
* Architecture-specific content '''must not''' be installed into <code>%{gemdir}</code> | * Architecture-specific content '''must not''' be installed into <code>%{gemdir}</code> | ||
* 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, and all architecture specific content '''must''' be moved from the <code>%{gemdir}</code> to the [#ruby_sitearch <code>%{ruby_sitearch}</code> directory] during <code>%install</code> | * 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, and all architecture specific content '''must''' be moved from the <code>%{gemdir}</code> to the [#ruby_sitearch <code>%{ruby_sitearch}</code> directory] during <code>%install</code> | ||
=== Ruby Gem with extension libraries written in C === | |||
When a Ruby Gem contains extension libraries written in C, | |||
* First, <code>%prep</code> stage '''must''' contain <code>%setup -q -c -T</code> to create the directory where C libraries are compiled. | |||
* Then at %build stage the Ruby Gem '''must''' be installed under the directory created at %prep stage to get C libraries compiled under there. | |||
* When <code>gem install</code> is used to install Gem file, using <code>-V</code> option is '''recommend''' to check if <code>CFLAGS</code> is correctly honored. | |||
* Finally at <code>%install</code> stage the whole tree under the directory created at %prep stage '''should''' be '''copied''' (not moved) to under <code>%{buildroot}%{gemdir}</code>. | |||
** When all tree under the directory created at %prep stage is moved to under <code>%{buildroot}</code>, <code>find_debuginfo.sh</code> will complain that the corresponding source files are missing. | |||
* Installed C codes (usually under <code>%{geminstdir}/etc</code>) '''may''' be removed even if <code>gem contents %{gemname}</code> reports that installed C codes should be found there. | |||
==== Note ==== | |||
The current guideline | |||
<pre> | |||
If the Gem contains binary content (e.g., for a database driver), it must be marked | |||
as architecture specific, and all architecture specific content must be moved | |||
from the %{gemdir} to the [#ruby_sitearch %{ruby_sitearch} directory] during %install | |||
</pre> | |||
must still apply. | |||
=== Packaging for Gem and non-Gem use === | === Packaging for Gem and non-Gem use === |
Revision as of 20:42, 20 January 2009
Ruby Packaging Guidelines
Each Ruby package must indicate the Ruby ABI version it depends on with a line like
Requires: ruby(abi) = 1.8
Ruby packages must require ruby at build time with a BuildRequires: ruby
, and may indicate the minimal ruby version they need for building.
Naming Guidelines
These naming guidelines only apply to ruby packages whose main purpose is providing a Ruby library; packages that mainly provide user-level tools that happen to be written in Ruby do not need to follow these naming guidelines, and should follow the general NamingGuidelines instead.
The name of a ruby extension/library package must be of the form ruby-UPSTREAM
. If the upstream name UPSTREAM
contains ruby
, that should be dropped from the name. For example, the SQLite database driver for ruby is called sqlite3-ruby
. The corresponding Fedora package should be called ruby-sqlite3
, and not ruby-sqlite3-ruby
.
A ruby extension/library package must indicate what it provides with a Provides: ruby(LIBRARY) = VERSION
declaration in the spec file. The string LIBRARY
should be the same as what is used in the require
statement in a Ruby script that uses the library. The VERSION
should be the upstream version of the library, as long as upstream follows a sane versioning scheme. For example, a Ruby script using the SQLite database driver will include it with require 'sqlite3'
. The specfile for the corresponding Fedora package must contain a line Provides: ruby(sqlite3) = 1.1.0
, assuming the package contains version 1.1.0 of the library.
Build Architecture and File Placement
The following only affects the files that the package installs into %{_libdir}/ruby
, i.e., Ruby library files. All other files in a Ruby package must adhere to the general Fedora Extras packaging conventions.
Pure Ruby packages
Pure Ruby packages must be built as noarch packages.
The Ruby library files in a pure Ruby package must be placed into Config::CONFIG["sitelibdir"]
. The specfile must get that path using
%{!?ruby_sitelib: %define ruby_sitelib %(ruby -rrbconfig -e 'puts Config::CONFIG["sitelibdir"] ')}
For Fedora Core 3 and earlier releases, it is not possible to build noarch packages; for those releases, all Ruby packages must be architecture-specific, even if they only contain Ruby files. (See bug 184199 for details)
For packages with binary content, e.g., database drivers or any other Ruby bindings to C libraries, the package must be architecture specific.
The binary files in a Ruby package with binary content must be placed into Config::CONFIG["sitearchdir"]
. The Ruby files in such a package should be placed into that directory, too. The specfile must get that path using
%{!?ruby_sitearch: %define ruby_sitearch %(ruby -rrbconfig -e 'puts Config::CONFIG["sitearchdir"] ')}
For packages which create C shared libraries using extconf.rb
export CONFIGURE_ARGS="--with-cflags='%{optflags}'"
should be used to pass CFLAGS
to Makefile
correctly.
This also applies to Ruby Gems.
Ruby Gems
Ruby Gems are Ruby's own packaging format. Gems contain a lot of the same metadata that RPM's need, making fairly smooth interoperation between RPM and Gems possible. This guideline ensures that Gems are packaged as RPM's in a way that ensures (1) that such RPM's fit cleanly with the rest of the distribution and (2) make it possible for the end user to satisfy dependencies of a Gem by installing the appropriate RPM-packaged Gem.
Both RPM's and Gems use similar terminology --- there's specfiles, package names, dependencies etc. for both. To keep confusion to a minimum, whenever the term from the Gem world is meant, it is explicitly called the 'Gem specification'. An unqualified 'package' in the following always means an RPM.
- Packages that contain Ruby Gems must be called
rubygem-%{gemname}
wheregemname
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 have a
Requires
and aBuildRequires
onrubygems
- The package must provide
rubygem(%{gemname})
wheregemname
is the name from the Gem's specification. For every dependency on a Gem namedgemdep
, the package must contain aRequires
onrubygem(%{gemdep})
with the same version constraints as the Gem - The
%prep
and%build
sections of the specfile should be empty. - The Gem must be installed into
%{gemdir}
defined as
%define gemdir %(ruby -rubygems -e 'puts Gem::dir' 2>/dev/null)
The install should be performed with the command
gem install --local --install-dir %{buildroot}%{gemdir} --force %{SOURCE0}
- The package must own the following files and directories:
%{gemdir}/gems/%{gemname}-%{version}/ %{gemdir}/cache/%{gemname}-%{version}.gem %{gemdir}/specifications/%{gemname}-%{version}.gemspec
- Architecture-specific content must not be installed into
%{gemdir}
- If the Gem only contains pure Ruby code, it must be marked as
BuildArch: noarch
. If the Gem contains binary content (e.g., for a database driver), it must be marked as architecture specific, and all architecture specific content must be moved from the%{gemdir}
to the [#ruby_sitearch%{ruby_sitearch}
directory] during%install
Ruby Gem with extension libraries written in C
When a Ruby Gem contains extension libraries written in C,
- First,
%prep
stage must contain%setup -q -c -T
to create the directory where C libraries are compiled. - Then at %build stage the Ruby Gem must be installed under the directory created at %prep stage to get C libraries compiled under there.
- When
gem install
is used to install Gem file, using-V
option is recommend to check ifCFLAGS
is correctly honored. - Finally at
%install
stage the whole tree under the directory created at %prep stage should be copied (not moved) to under%{buildroot}%{gemdir}
.- When all tree under the directory created at %prep stage is moved to under
%{buildroot}
,find_debuginfo.sh
will complain that the corresponding source files are missing.
- When all tree under the directory created at %prep stage is moved to under
- Installed C codes (usually under
%{geminstdir}/etc
) may be removed even ifgem contents %{gemname}
reports that installed C codes should be found there.
Note
The current guideline
If the Gem contains binary content (e.g., for a database driver), it must be marked as architecture specific, and all architecture specific content must be moved from the %{gemdir} to the [#ruby_sitearch %{ruby_sitearch} directory] during %install
must still apply.
Packaging for Gem and non-Gem use
If the same Ruby library is to be packaged for use as a Gem and as a straight Ruby library without Gem support, it must be packaged as a Gem first. To make it available to code that does not use Ruby Gems, a subpackage called ruby-%{gemname}
must be created in the rubygem-%{gemname}
package such that
- The subpackage must require
rubygem(%gemname) = %version
- The subpackage must provide
ruby(LIBRARY) = %version
where LIBRARY is the same as in the [#ruby_naming general Ruby guideline] above. - All the toplevel library files of the Gem must be symlinked into
ruby_sitelib
. - The subpackage must own these symbolic links.
As an example, for activesupport
, the rubygem-activesupport
package would have a subpackge ruby-activesupport
:
%package -n ruby-activesupport ... Requires: rubygem(activesupport) = %version Provides: ruby(active_support) = %version # The underscore is intentional, not a typo ... %files -n ruby-activesupport %{ruby_sitelib}/active_support %{ruby_sitelib}/active_support.rb
Tips for Packagers
Gems carry a lot of metadata; gem2rpm is a tool to generate an initial specfile and/or source RPM from a Gem. The generated specfile still needs some hand-editing, but conforms to 90% with this guideline.