Differences between revisions 31 and 32
Revision 31 as of 2011-04-18 19:30:07
Size: 10767
Editor: ?VincentFourmond
Comment:
Revision 32 as of 2011-04-18 21:16:07
Size: 9781
Comment:
Deletions are marked like this. Additions are marked like this.
Line 104: Line 104:
 1. VincentFourmond: someone (please, please, not me, not me !) has to step forward and rewrite the Debian Ruby policy -- http://pkg-ruby.alioth.debian.org/ruby-policy.html/ so that it actually reflects the current rules.
Line 115: Line 114:

= How to convert one package ? =

In the simplest case, just dump the current `debian/rule`, replace it by the following `debhelper`-based:

{{{
#!/usr/bin/make -f
%:
 dh $@ --with ruby --buildsystem ruby
}}}

This means you need `debhelper (>= 7), gem2deb` in your build-depends.

You must also add the following stanza in your `debian/control`:

{{{
XS-Ruby-Versions: all
}}}

(VincentFourmond: is this correct ?)

Of course, you'll probably have to tweak this variable (and maybe other things too) if you are building native extensions...

BTW, for now `lintian` complains about this field, we'll have to make it aware of it.

= Lintian =

To ease the transition, it would be good to write appropriate lintian tags, woudln't it ?

This page describes the various changes to Ruby packaging that are planned for Wheezy.

Planned changes

Changes to interpreter packaging

Use alternatives to switch between Ruby implementations

There is a huge demand (see #548917) for using alternatives to switch between Ruby implementations. This would provide a way to mimic what RVM provides in a cleaner way, and will help the Ruby community with moving to 1.9.x or other implementations.

Of course, it is clear that some libraries will not work with Ruby 1.9.x or Rubinius or JRuby. The plan is to do something similar to what is done for Java:

  • Make sure that everything works with Ruby 1.8 (i.e not working is considered a serious bug)
  • Do what we can for other libraries (i.e not working is considered a normal bug), and work with upstream

Each ruby implementation will provide ruby-interpreter. Pure-ruby packages must depend on ruby-interpreter.

Switch to 1.9 as default

Once we use alternatives, it is quite easy to switch to 1.9 as default. However, 1.9 doesn't sound like a reasonable target now, even if it is likely to become one during the wheeze cycle.

Package other interpreters

It would be nice to make progress towards having the same support for Rubinius and JRuby.

  • For JRuby, it is in non-free (see http://packages.qa.debian.org/j/jruby.html) because of some dependencies. We can't depend on it if it stays non-free because it would make all ruby software part of contrib.

  • For Rubinius, there's an ITP (see #591817)

Changes to rubygems packaging

  • Rubygems should install gems to /usr/local/lib/gems/ (with a proper migration plan)
  • Rubygems should install binary wrappers to /usr/local/bin

Changes to third-party libraries and software packaging

Single package for all Ruby versions

For Wheezy, Ruby software must not come in separate packages per Ruby interpreter version, as we did until Squeeze (libfoo-ruby1.8, libfoo-ruby1.9.1 etc). We are going to use a single binary package per source package no matter what. In the case of native extensions, those single binary packages will contain the compiled extensions (*.so) for all supported Ruby versions. This is supported by gem2deb, so you should use it.

Naming of ruby packages

The current libfoo-ruby naming, inspired for perl, is not really great. It would be better to move to the python naming, with ruby-foo. Since all packages will have to be modified anyway to switch to gem2deb (see below), it is the perfect time to do that.

The guidelines are the following:

  • Binary packages must normally be named "ruby-foo". If the package is mainly used as an application (not as a library), then it can be named "foo". Known examples are rails, chef, rubygems, puppet.
  • Source packages must have the same name as the "main" binary package. (our infrastructure is better at handling this case)

Renaming existing packages

Existing packages must be renamed to the new scheme. This renaming must be done using the standard Debian practices (i.e. Debian Developers' Reference, section 5.9.3). In our case, this means:

  • when libfoo-ruby gets renamed to ruby-foo, then ruby-foo must declare Provides: libfoo-ruby, Replaces: libfoo-ruby and Conflicts: libfoo-ruby

  • when libfoo-ruby1.8 gets renamed to ruby-foo, then ruby-foo must declare Provides: libfoo-ruby1.8, Replaces: libfoo-ruby1.8, and Conflicts: libfoo-ruby1.8

  • when libfoo-ruby1.8 and libfoo-ruby1.9.1 are turned into a single pure-Ruby package ruby-foo, then it must declare Provides: libfoo-ruby, libfoo-ruby1.8, libfoo-ruby1.9.1, Replaces: libfoo-ruby, libfoo-ruby1.8, libfoo-ruby1.9.1, and Conflicts: libfoo-ruby, libfoo-ruby1.8, libfoo-ruby1.9.1

  • ruby-foo must also provide transitional binary packages for libfoo-ruby, libfoo-ruby1.8 and libruby1.9.1 (when it's the case). You can use the gen-ruby-trans-pkgs script to generate the proper snippet to be added to your debian/control.

  • note that this is only needed for packages that were already released with Squeeze. New packages must not keep any references to packages named as lib*-ruby.
  • after the renamed package enters the archive, please request the removal of the old package.

    • I guess this is not needed when using transitional packages - according to Renaming_a_Package the old source package will be removed automatically. If that's the case, the above bullet point, as well as this one, can be removed.

Handling of shebangs

  • applications willing to force the use of ruby1.8 should use /usr/bin/ruby1.8 in shebang
  • applications willing to use the selected ruby implementation (whatever it is) should use /usr/bin/ruby

gem2deb currenly forces the use of ruby1.8 (the default ruby version, actually). Patches to make it configurable are welcome.

gem2deb as the preferred packaging tool for ruby software

gem2deb is a replacement for our current cdbs-based packaging suite. It:

  • does almost everything automatically
  • uses dh (much faster)
  • is easier to adapt to our needs, since there's no dependency on an external tool
  • runs the test suite as part of the build, for each ruby implementation (yes, it's possible to override this)
  • uses one binary package per pure-ruby lib, instead of one binary package per ruby implementation

To test it:

git clone git://github.com/ln/gem2deb.git
cd gem2deb
rake install
then, cd to some temporary place, and do:
gem2deb rdiscount # native gem
or:
gem2deb i18n # pure-ruby gem

It serves two goals:

  • it can be used by users to generate .debs from gems locally
  • it generates Debian source package from which we can do the packaging work

Prerequisites for migrations:

  • we need to decide on a workflow for packaging (switch to git?)
  • we need to decide on a migration plan to avoid breaking the archive for too long

Generation of ri and rdoc documentation

We decide not to generate the ri and rdoc documentation, as there are good online services providing it (like rdoc.info). We might change our mind later. :)

How do we proceed?

  1. Upload updated interpreter packages, rubygems, and gem2deb to experimental
  2. Package a dozen of gems in experimental, make necessary improvements to gem2deb & other packages

  3. Finish the discussion on the necessary changes to the pkg-ruby-extras infrastructure (consider switching to git)

Success metrics

  • There are no non-transitional binary packages named lib.*-ruby.* in the archive. No package should Depend or Recommend a package named lib.*-ruby.*.
  • The only packages installing stuff to /usr/lib/ruby/{1.8,1.9.1} are interpreters. Software packaged with gem2deb will install to /usr/lib/ruby/vendor_ruby/
  • Upgrades from squeeze work. ;)

  • The Ruby community stops whining about Debian ;-) (just kidding. that's not really an achievable goal)

Transition status

See http://pkg-ruby-extras.alioth.debian.org/wheezy/

Using Git

Obtaining the master repository

git clone <alioth-username>@git.debian.org:/git/pkg-ruby-extras/pkg-ruby-extras.git

Then, to obtain all the team packages, do:

cd pkg-ruby-extras
mr checkout

To avoid typing your username and your password see this page.

Creating a new git repository

on alioth:

cd /git/pkg-ruby-extras
./setup-repository repository-name 'description of the repository'
Example:
./setup-repository ruby-foo 'Packaging for foo'

Note: please do not leave empty repositories on alioth; only create a repository there just before pushing your package (see below).

Pushing an existing package to git.debian.org

On alioth:

cd /git/pkg-ruby-extras
./setup-repository ruby-feedparser 'Packaging for ruby-feedparser'

On your local machine:

Get a basic .dsc from your package, using:
gem2deb ruby-feedparser-0.7.gem

At this point, please do not make any change to the package generated by gem2deb. It is important to track all the changes in git. Then:

cd where-you-cloned-pkg-ruby-extras.git
./make-mrconfig # will generate the config for your new repo
mr checkout # will clone your new repo
cd ruby-feedparser
git import-dsc --pristine-tar path-to/ruby-feedparser_0.7-1.dsc
git tag -d debian/0.7-1 # because the package is not ready yet
git push --all
git push --tags

Then, make the needed changes to the packaging, and then

git push

After upload, tag the package with

git tag debian/0.7-1

And don't forget to

git push --tags

Known Issues

If mr checkout gives an error like mr: illegal section "[DEFAULT]" in untrusted:

Add .mrconfig path to ~/.mrtrust

If your local username is different from your Alioth username (that's probably the case for non-DD developers with -guest accounts), add the following to your ~/.ssh/config:

Host alioth.debian.org svn.debian.org git.debian.org
User alioth-username

References