Navigation: Debian/Ruby Extras / Dear Upstream Developers Language: en WikiLink: Dear Upstream Developers

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.

Don’t distribute only as a gem.

RubyGems is nice for people who aren’t using another packaging system, but it makes it hard to package your application for our distribution. Please distribute your software as a .tgz (or .tar.gz) too.

Don’t depend on RubyGems

Make sure you are using require, not require_gem, to allow users to use your library without using RubyGems.

Use setup.rb

TODO: explain differences between setup.rb, extconf.rb, and install.rb.

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

Don’t 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, consider using #!/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.

References