Most of the packaging work can be simplified using the Ruby Package Tools. The tools are contained in the ruby-pkg-tools package, available in Debian. It contains the following:
A file (pkg-ruby-extras.team) containing the names and email addresses of all team members.
A CDBS class (ruby-setup-rb.mk) that is usable to create Debian packages from Ruby upstream libraries and apps that use setup.rb as their installer.
A CDBS rule (uploaders.mk) to perform a substitution on build-time, filling in the Uploaders field with the team members. NB: this rule has been deprecated, do not use.
- In the future: dh-make-ruby stuff to automatically Debianize a source tree.
A file (pkg-ruby-extras.sources) which contains a list of upstream sources, which versions are where to get. The file is used by the pkg-ruby-get-sources for locating and retrieving upstream sources for packages to be built that are checked out from the Subversion repository. However, the preferred way to retrieve upstream sources is by using a debian/watch file. You should only add your package to pkg-ruby-extras.sources if you cannot use a watch file.
The Team Member List
A list of team members of the Debian Ruby Extras Maintainers is kept in /usr/share/ruby-pkg-tools/pkg-ruby-extras.team. If you have joined the team, this file must be updated. Please refer to Joining the Team for more information about updating this file. The list is mostly used by the uploaders rule.
N.B: Double check that you haven’t forgotten a comma when adding yourself!
The CDBS Classes
The tools includes two CDBS classes, ruby-setup-rb.mk and ruby-extconf-rb.mk, for automating the building of a package for upstream source that uses install.rb, setup.rb or extconf.rb as builder/installer. The classes try to create a package that adheres to the Debian/Ruby policy (draft version) and takes a lot of common standard and often the same work out of your hands.
A common debian/rules file for setup.rb using this ruby-setup-rb class would look like this:
# # CDBS file to build the Foo Ruby package. include /usr/share/cdbs/1/rules/debhelper.mk include /usr/share/ruby-pkg-tools/1/class/ruby-setup-rb.mk
libbreakpoint-ruby is an example of a setup.rb based Debian package.
For extconf.rb it would look like this:
# # CDBS file to build the Foo Ruby package. include /usr/share/cdbs/1/rules/debhelper.mk include /usr/share/ruby-pkg-tools/1/class/ruby-extconf-rb.mk
You can have a look at libgpgme-ruby to see how an extconf.rb based package can be built.
Note that it is still possible to configure and override the behaviour of the class and debhelper. No control is lost. For more information about how to use the class, see the CDBS HOWTO.
N.B. When using either of these classes, don’t forget to add
- “debhelper” and “cdbs” to the Build-Depends field
- “ruby-pkg-tools” to the Build-Depends(possibly Build-Depends-Indep) field
The Uploaders Rule
Some time ago, we used to write the name of all the members of the team in the Uploaders control field. This has been argued against here. Please, do not use uploaders.mk anymore. Uploaders should only be people who made significant changes to the package.
Retrieving Upstream Sources
Since after much discussion it was decided not to put all the upstream sources of every package into the Subversion repository, a tool was added to this package to help retrieving it. This tool, pkg-ruby-get-sources is described below; it can use either the pkg-ruby-extras.sources information file or (preferably) the package’s debian/watch file.
A basic usage scenario for pkg-ruby-get-sources is to do a checkout, get the upstream source and build:
$ cd Debian/packages $ svn co svn+ssh://svn.debian.org/svn/pkg-ruby-extras/packages/libfoo-ruby [...] $ cd libfoo-ruby/trunk $ mkdir ../tarballs $ pkg-ruby-get-sources [100%] http://somesite/path/to/foo-ruby-0.1.tar.gz $ ls ../tarballs libfoo-ruby_0.1.orig.tar.gz $ svn-buildpackage [...]
Note that pkg-ruby-get-sources retrieves the tarball and takes care of the naming of the file locally so that it suits the Debian source package name. For example see above where foo-ruby-0.1.tar.gz is automatically renamed to libfoo-ruby_0.1.orig.tar.gz.
Where does it find upstream sources?
There are two ways to find the upstream sources:
- # Using the package’s watch file. This is the preferred method.
# Using the pkg-ruby-extras.sources file, described below. This should only be used for packages where watch files are not a solution.
This is by far the best way to do, as other tools from debian also use the information stored in this file (see for instance QA pages for developers).
The principle is simple: if the software you package provides a web page with a link to source tarballs, all you need to do is provide the location of this page along with a regular expression matching the link to the tarball. For a standard Rubyforge package, the watchfile would look like
version=3 http://rubyforge.org/frs/?group_id=701 .*tioga-([\d.-]*)\.t.*
To check the contents of this file, run
$ uscan --report
Look at the uscan manual page for more information.
Registering sources using the pkg-ruby-extras.sources file
Retrieve from Subversion:
and edit it. This file follows the YAML format.
For adding a new package libfoo-ruby version 0.1, append:
libfoo-ruby: "0.1": http://somesite/path/to/foo-ruby-0.1.tar.gz</pre>
For adding a new upstream version 0.2 for libfoo-ruby, append to the previous lines:
pkg-ruby-get-sources allows for selecting different sources files (--sources) instead of using the one that comes with ruby-pkg-tools by default, so you can use your own. It also can list all available sources (--list-available) or download to a different target directory (--target-directory).