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:

   require 'rubygems'
rescue LoadError

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_FILES = ['ChangeLog', 'README', 'COPYING', 'LICENSE', 'setup.rb', 'Rakefile']
Find.find('lib/', 'data/', 'test/', 'tools/') do |f|
        if and f =~ /\.svn/
                PKG_FILES << f

# Tasks

task :default => [:package] do |t|
        t.libs << "test"
        t.test_files = FileList['test/tc_*.rb']
end do |rd|
  f = []
  require 'find'
  Find.find('lib/') do |file|
    # Skip hidden files (.svn/ directories and Vim swapfiles)
    if file.split(/\//).last =~ /^\./
      f << file if not
  rd.options << '--all'
end, PKG_VERSION) do |p|
        p.need_tar = true
        p.package_files = PKG_FILES

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

        spec = do |s|
                s.platform = Gem::Platform::RUBY
                s.summary = "Your summary"
       = 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 do |pkg|
                pkg.need_zip = true
                pkg.need_tar = true
rescue LoadError

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 In particular, feel free to send comments or questions about this document, or suggest Ruby libraries that we should package in Debian.