Upstream Developers, Be Nice to Distributions (Re)Packagers!

Dear developer,

Your library/application is very good, and we would like to integrate it into our favorite distribution, so many more people would benefit easily from it. However, it would be great if you could make our work as easy as possible by following those guidelines.

Distribute your software as a source code archive

RubyGems is a useful tool for developers, but isn’t ideal for the general distribution of your software (see On Rubygems for more information).

Distribute your software as a .tar.gz archive. .tar.gz is the most widely used archive format on Linux. Using other formats (.tar.bz2, for example) is also acceptable. A .zip file could be provided for Windows users.

Including the version of the software in the name of the archive is also a very good idea.

Use setup.rb

Provide a setup.rb. Use it with its default layout (bin/, lib/, …). Test that your software works when installed using it.

If your library is only a native library, using extconf.rb might be a suitable alternative. However, all extconf use-cases are covered by setup.rb.

Note that install.rb is deprecated, and should not be used.

Remove all references to rubygems in the software you ship

One big issue we have with rubygems is that it is source-intrusive: developers add require 'rubygems' in their code, which:

Do not use: 

begin
   require 'rubygems'
rescue LoadError
end

As this will succeed on systems with rubygems installed.

Instead, make the loading of rubygems conditional, using a global constant that you can easily disable before releasing: 

require 'rubygems' if DEVELOPER_MODE

For the same reason, require_gem must not be used.

Don’t make your Rakefile depend on RubyGems

If you provide a Rakefile, make sure it is usable without ?RubyGems installed. The following example is known to work: 

require 'rake/testtask'
require 'rake/packagetask'
require 'rake/rdoctask'
require 'rake'
require 'find'

# Globals

PKG_NAME = 'yourpackagename'
PKG_VERSION = '0.1'

PKG_FILES = ['ChangeLog', 'README', 'COPYING', 'LICENSE', 'setup.rb', 'Rakefile']
Find.find('lib/', 'data/', 'test/', 'tools/') do |f|
        if FileTest.directory?(f) and f =~ /\.svn/
                Find.prune
        else
                PKG_FILES << f
        end
end

# Tasks

task :default => [:package]

Rake::TestTask.new do |t|
        t.libs << "test"
        t.test_files = FileList['test/tc_*.rb']
end

Rake::RDocTask.new do |rd|
  f = []
  require 'find'
  Find.find('lib/') do |file|
    # Skip hidden files (.svn/ directories and Vim swapfiles)
    if file.split(/\//).last =~ /^\./
      Find.prune
    else
      f << file if not FileTest.directory?(file)
    end
  end
  rd.rdoc_files.include(f)
  rd.options << '--all'
end

Rake::PackageTask.new(PKG_NAME, PKG_VERSION) do |p|
        p.need_tar = true
        p.package_files = PKG_FILES
end

# "Gem" part of the Rakefile
begin
        require 'rake/gempackagetask'

        spec = Gem::Specification.new do |s|
                s.platform = Gem::Platform::RUBY
                s.summary = "Your summary"
                s.name = PKG_NAME
                s.version = PKG_VERSION
                s.requirements << 'none'
                s.require_path = 'lib'
                s.autorequire = 'yourpackagename'
                s.files = PKG_FILES
                s.description = "Your description"
        end

        Rake::GemPackageTask.new(spec) do |pkg|
                pkg.need_zip = true
                pkg.need_tar = true
        end
rescue LoadError
end

Make your tests and examples usable outside of your directory tree

Do not do things like require '../lib/yourpackagename'. Instead, use the following example: 

$:.unshift '../lib'

require 'yourpackagename'

This way, example and test scripts can be moved to other locations, but will still be able to use the global installation of your library. And since ‘../lib’ is added at the beginning of the search patch, you will be able to use the version of your library you are working on during development.

Use a shebang that works everywhere

The Ruby interpreter can be installed in different places. Instead of using #!/usr/bin/ruby or #!/usr/local/bin/ruby, use #!/usr/bin/env ruby.

Provide man pages for your binaries

Some distributions (e.g. Debian) require all executables to have a man page. It would be great if you could provide it yourself.

If possible, maintain a backward-compatible API

Usually, distributions don’t ship several versions of the same libraries. Libraries providing a stable API make this much easier.

Contact information

The Debian pkg-ruby-extras team can be contacted at pkg-ruby-extras-maintainers AT lists.alioth.debian.org. In particular, feel free to send comments or questions about this document, or suggest Ruby libraries that we should package in Debian.