Revision as of 09:17, 19 February 2013

It has been requested that this page be deleted.
This draft obsolete

Note that this is a Draft

Mission Statement

This should actually go end up on the Ruby SIG page or something:

To make Fedora the best and most suitable mid-stream operating system or Linux distribution to develop Ruby applications, and to make EPEL the best repository for production systems.

This may or may not include:

• Being able to provide a parallel stack for Ruby developers
  • Failing that, providing more then one single version of Ruby (despite whether we are actually able to provide parallel stacks or easy enough ways to switch between stacks)
• Providing consistent Ruby and Ruby Gem packages
• Be as efficient as possible for package maintainers building packages for different versions of Ruby
  • Failing that, be as good an upstream for custom downstream packages (e.g. easy to rebuild given different Ruby specific parameters).

Build System / Buildroot Macros

The following RPM macros are available on the build system, through the ruby package -which ships /etc/rpm/macros.ruby:

We may, in the future, move the actual ruby code and libraries outside of the ruby package, and instead provide ruby-1.8.6, ruby-1.9.1 packages containing the actual Ruby code and libraries.

• The ruby package itself would then require the version specific ruby package that is the default ruby stack for Fedora, thus providing a path from a user performing a yum install ruby to having a complete ruby stack available on the system.

See also: Ruby_SIG:Draft_Package_Guidelines/Example_Ruby_Macros_File

Package Ruby ABI/API Requirements

• Each Ruby package shipping binary code must indicate the Ruby ABI version it depends on with a line like:

Requires: ruby(abi) = 1.8

• Each Ruby package shipping architecture independent code must indicate the Ruby API version it depends on with a line like:

Requires: ruby(api) = 1.8

• Ruby packages with binary code and noarch code must require both ruby(abi) and ruby(api).

In case the Ruby ABI or API version required is completely neutral (e.g. the package works no matter what Ruby API of ABI version is used) use:

Requires: ruby(abi) = %{rubyabi_mm}
Requires: ruby(api) = %{rubyapi_mm}

The %{rubyabi_mm} and %{rubyabi_mm} RPM macros are provided through /etc/rpm/macros.ruby, shipped with the ruby package. It results in the full ruby Major.Minor.Teeny version available in the build root to be used as the API/ABI requirement.

Ruby packages must require ruby at build time with a BuildRequires: ruby, and may indicate the minimal ruby version they need for building.

Rationale

The Ruby package is considered unstable even in between teeny versions. The API in Ruby 1.8.6 to datestrf() for example is different from the API in Ruby 1.8.5. While most packages are compatible with most 1.8 series, the Ruby requirement may look like:

Requires: ruby(api) = 1.8

As is provided by ruby-1.8.5, ruby-1.8.6 as well as ruby-1.8.7, but not ruby-1.9.1 or ruby-1.9.2. Should a package, for some reason, be compatible with only the Ruby ABI in a specific Major.Minor.Teeny version, then such can be required through the RPM. This allows for a (future) parallel installable stack as well.

If a package really doesn't care about the Ruby version, as would be the case for many Ruby gems, then simply requiring:

Requires: ruby(api)

should suffice. Whatever is installed will be used, and so the files should go in the version independent path (%{ruby_vendorlib})

However, considering binary packages, they should be recompiled for each Major.Minor.Teeny version of Ruby, hence, inherently, requiring:

Requires: ruby(abi) = %{rubyabi}

resulting in a requirement on either ruby 1.8.5, 1.8.6, 1.8.7, 1.8.7-ee, 1.9.1 or 1.9.2. However, there may be cases where binary packages are in fact compatible with more then one ruby(abi) version without the need for a specific compile against one single Major.Minor.Teeny ruby version. In such cases, one may put in a requirement like:

Requires: ruby(abi) = %{rubyabi_mm}

Ruby Search Path

$ ruby -e 'puts $:'

should result in:

/usr/local/lib{,64}/ruby/X.Y.Z/
/usr/local/lib{,64}/ruby/X.Y/
/usr/local/lib{,64}/ruby/
/usr/local/share/ruby/X.Y.Z/
/usr/local/share/ruby/X.Y/
/usr/local/share/ruby/
/usr/lib{,64}/ruby/X.Y.Z/
/usr/lib{,64}/ruby/X.Y/
/usr/lib{,64}/ruby/
/usr/share/ruby/X.Y.Z/
/usr/share/ruby/X.Y/
/usr/share/ruby/

This provides the most appropriate search path for the following features:

• Allow the site specific Ruby directories to be used for gems and custom installations (e.g. /usr/local/),
  • per Major.Minor.Teeny Ruby version for custom code depending on one or the other Major.Minor.Teeny specific set of code,
  • per Major.Minor Ruby version for custom code depending on one or the other Major.Minor specific set of code,
  • Ruby version independent custom code.
• Allow the Ruby packages in Fedora to depend on specific versions of Ruby,
  • per Major.Minor.Teeny Ruby version dependent code shipped by Fedora Project,
  • per Major.Minor Ruby version dependent code shipped by Fedora Project,
  • Ruby version independent code shipped by Fedora Project.

Site Specific Directories
Note that site-specific directories (e.g. the /usr/local/ directories) should not be used by Fedora packages, but may be used by downstream, custom packages.

 %gemdir

The %gemdir macro should be set to %{ruby_vendorlib} for packages compatible with all versions of Ruby available to a Fedora system.

For gems compatible with all versions in one or the other X.Y series, %gemdir should be set to %{ruby_vendorlib_XY}. Potentially, one may install one gem more then once.

Package Naming Guidelines

Ruby Packages

Ruby packages, or packages for which, essentially, ruby-lang.org is upstream, should be named:

ruby-X.Y.Z

with the exception of the ruby package itself, which is basically an empty package requiring the version specific package to represent the default stack on Fedora.

For Ruby libraries, the name should be:

ruby-%{rubyabi}-[name]-%{version}

Examples

We'll take the current version of ruby-ldap as an example;

1. The package is compiled against the Ruby libraries,
2. should thus be recompiled for all Ruby versions,
3. thus results in as many binary packages as we ship Ruby versions,
4. thus is dependent on a Major.Minor.Teeny version of Ruby,

Take a look at Ruby_SIG:Draft_Package_Guidelines/Example_Ruby_Lib_Spec to see what a .spec might look like.

Ruby Gem Packages

Ruby Gem packages should be named like:

ruby-[version-]gem-%{gemname}

Where [version-] is either;

• the full Major.Minor.Teeny version of the Ruby ABI/API the gem depends on,
• the Major.Minor version of the Ruby API/ABI the gem depends on,
• "", representing that the package is compatible with "whatever version" of Ruby.

Ruby Stack Switching Mechanisms

• RVM
• Alternatives
• Environments