Upstream Developers, Be Nice to Distributions (Re)Packagers!
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
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.
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:
- fails if the user doesn’t have rubygems installed
causes manually-installed (or installed with a package manager) libraries to be ignored after RubyGems has been loaded.
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.
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.