Differences between revisions 24 and 25
Revision 24 as of 2008-06-29 11:06:03
Size: 12047
Comment: Again corrected
Revision 25 as of 2008-07-21 15:02:21
Size: 12395
Editor: ?JoeSmith
Comment: Created non-stub text for HardCoded Paths section.
Deletions are marked like this. Additions are marked like this.
Line 37: Line 37:
(our config files are in {{{/etc}}} and our manual pages in {{{/usr/share/man}}}. Other people use {{{/usr/local/etc}}} and {{{/usr/local/man}}}. Please make configurable without patching) Debian's Policy requires that Debian packages follow the [javascript:void(0);/*1216652202996*/ FHS ]with respect to package file locations. It should also be noted that Debian packages are not installed into /usr/local. Thus Debian config files are found in /etc, and manual pages in /usr/share/man. If your program normally installs these to a different location please be sure to provide a mechanism to change the locations without patching the source. Use of environment variables for this purpose is recommended.
Line 88: Line 88:
Please help us in supporting architectures for which the native code compiler (`ocamlopt`) is not available. Practically this mean to support in your build tool (makefile or corresponding) one of the following 2 behaviors: Please help us in supporting architectures for which the native code compiler ({{{ocamlopt}}}) is not available. Practically this mean to support in your build tool (makefile or corresponding) one of the following 2 behaviors:
Line 91: Line 91:
 2. provide different make targets (or corresponding tool invocations) to build and install bytecode stuff vs native code stuff. Usual names for that are: `all` vs `opt` (to build bytecode/native code stuff) and `install` vs `install-opt`
 1. provide different make targets (or corresponding tool invocations) to build and install bytecode stuff vs native code stuff. Usual names for that are: {{{all}}} vs {{{opt}}} (to build bytecode/native code stuff) and {{{install}}} vs {{{install-opt}}}
Line 94: Line 93:
Line 97: Line 95:
 * http``://packages.qa.debian.org/''package'' where package is the name of the package in Debian ; this page is a portal to all kind of information. You can subscribe to Package Tracking System (PTS) to be mailed when there is a new release or when a user report a new bug.
 * http``://bugs.debian.org/''package'' where package is the name of the package in Debian ; this page will list all bugs that have been reported by Debian users. Feel free to help to solve them, propose patch or fix them upstream.
Line 100: Line 96:
 * http{{{}}}://packages.qa.debian.org/''package'' where package is the name of the package in Debian ; this page is a portal to all kind of information. You can subscribe to Package Tracking System (PTS) to be mailed when there is a new release or when a user report a new bug.
 * http{{{}}}://bugs.debian.org/''package'' where package is the name of the package in Debian ; this page will list all bugs that have been reported by Debian users. Feel free to help to solve them, propose patch or fix them upstream.
Line 112: Line 110:
(viewing autobuilder logs) (more info: ["GettingPorted"]) (viewing autobuilder logs) (more info: GettingPorted)

This page is aimed at developers whose software is packaged for Debian. It attempts to document what we do to your software, what we do for you and what you can do to help us.

See also "Distribution-friendly projects" by Diego Pettenò - [http://lwn.net/Articles/274763/ part 1], [http://lwn.net/Articles/277132/ part 2], [http://lwn.net/Articles/279130/ part 3].

Getting Packaged

(the initial version of a package)

Pristine Upstream Source

The source code archive should only contain source code, never any files that are created for the specific system during compilation. We recognize that it is fairly common to ship lexer and parser code or compiled documentation as part of the source package so administrators building from source do not need to install the build tools, however we need to rebuild all generated files to make sure that they can really be built from source, so please include methods to regenerate these files.

It appears that the "rebuild everything" rule is applied inconsequently, for example, most packages do not rebuild the files generated by autoconf and automake. This is due to historical reasons mainly, since these tools broke often during automatic builds.

Please do not include other packages that are also shipped separately inside your source archive, or if you do, please make sure that these can be reliably ignored. If a security issue is found in other included packages, it is far easier to rebuild one package than to scan the entire archive for all copies of this code and patch them individually (this happened for zlib, for example).

(why we'd like to have a single .tar.gz archive from you, at least for the time being)

Many upstream code sources tend to include a rough /debian directory among source files to ease bleeding-edge package compilation and installation on debian (and derived) systems; while this is a good effort, it would be better to leave it out of the final tarball as it can interfere with debian's own packaging effort. Keeping it only in your VCS repository is usually a much saner default.

License

The ["DFSGLicenses"] page has a lot of information about the various licenses currently found in Debian.

  • Please do not write your own license text if you can at all avoid it. Depending on your wishes, the [:DFSGLicenses#gpl:GPL], [:DFSGLicenses#lgpl:LGPL] or a [:DFSGLicenses#3clause-bsd:BSD-style] license will most likely be appropriate, and it is far easier to tell whether something is allowed if we can look at past discussions of the same text.
  • There is usually no need for different "types" of files to have different licenses. It really complicates matters as all the license terms need to be followed at the same time, and if two are incompatible, we cannot distribute the package at all.
  • Please document copyright attribution in each file, and add statements placing the code under the chosen license to the copyright holders. Email addresses or company contacts for copyright holders should be listed either in the individual files, or in a file called "AUTHORS"

  • Include the full text of all licenses used in the top-level directory.
    • If more than one license is in use in the package, a file "COPYING" that lists files and their licenses, and individual files "GPL" "LGPL" with the unmodified license text would be ideal.

    • Packages with a single license can simplify this by using the full license text as the "COPYING" file.

Releases and Versions

When you've reached a point in development of your software where you feel like everything generally works and you've fixed a variety of bugs or implemented some interesting new features, please make a distribution with a version number. This doesn't mean that you have to keep supporting that version afterward if you're short of resources as long as you make that clear. But please don't develop only in a version control repository and with snapshots, or do releases only as tags. It makes it much more difficult to grab a stable point that you think generally works. It's frustrating to try to find something that will probably work for most general users and keep getting snapshots in the middle of some known transition or partial development.

Each time you make a new release, please give it a new version number that's larger than the previous version number. (This sounds obvious, but it's amazing how often this doesn't happen.) If anything changes, please give the new release a new version number. Even if what changed was fixing an obvious mistake or accident and the previous version wasn't usable, please give the new release a new version number.

Version numbers are only useful if they increase every time something changes. There are an infinite number. You won't run out. For most users, it's more useful to know for certain that version numbers always increase and everyone with something with a given version number has the same code than it is to be sure that particular version numbers have a significant psychological meaning or meet past plans about what would go into which version.

Hardcoded Paths

Debian's Policy requires that Debian packages follow the [javascript:void(0);/*1216652202996*/ FHS ]with respect to package file locations. It should also be noted that Debian packages are not installed into /usr/local. Thus Debian config files are found in /etc, and manual pages in /usr/share/man. If your program normally installs these to a different location please be sure to provide a mechanism to change the locations without patching the source. Use of environment variables for this purpose is recommended.

Your Build System

General Considerations

No Downloads

You should never assume that Internet access is available during building. Debian is often installed from CDs or DVDs in places without connectivity, where those packages could not be rebuilt.

Out-of-Tree Builds

(if your software can be built in different ways, we need to build all of them in different directories)

Cleaning the Tree

(if out-of-tree works, we can rm -rf the build tree, otherwise we need clean targets that remove anything that can be automatically rebuilt, including generated source)

Including a file in your distribution and then modifying it as part of the build is confusing and leads to spurious differences that appear to be Debian-local modifications unless the packager takes special care. Files of this type should instead be generated from a template with a different file name, the way that Autoconf handles config.h, generated from config.h.in, and the generated file removed in your clean or distclean target and not included in the distribution.

Installation

Please honor the DESTDIR environment variable or make variable and use its contents as a prefix in front of all installation paths. (Supporting changing prefix at make install time without changing any of the paths built into the software is also good practice, but not strictly necessary if DESTDIR is used.) Automake's make distcheck will verify that your package supports this, as well as out-of-tree builds and other best practices, so if you're using Automake, that's a nice check to do before a release.

After running make, running make install should not rebuild any files and in particular shouldn't encode any new paths. Otherwise, it's very hard to install the software in a temporary staging area without including the paths to the staging area in the final software (which in the case of RPATH can even be a security concern).

Assume that none of the directories into which you're installing files may not already exist and create them if necessary using mkdir -p (possibly via the $(MKDIR_P) macro provided by Autoconf and Automake), install -d, installdirs, or some similar technique.

Autoconf and Automake

If you use config.guess and config.sub, please make a habit of always copying the latest versions from ftp.gnu.org or some other source (such as /usr/share/misc on a Debian system with autotools-dev installed) into your package when you release. If you use autoreconf, it can do this for you automatically provided that you keep your local system version up to date. Most of your users may not care about the changes, but Debian often does, since Debian supports a wide variety of architectures.

(we like it, but keep it fresh :) )

Make

(we sort of like it)

Some make variables are reserved to the user, and the [http://www.gnu.org/software/libtool/manual/automake/User-Variables.html#User-Variables Automake manual] and the [http://www.gnu.org/prep/standards/standards.html#Command-Variables GNU coding standards] advise to never use them for switches that are required for proper compilation of the package. When a Debian binary package is built, environment variables such as CFLAGS and CXXFLAGS are set by dpkg-buildpackage and may override the corresponding variables in the Makefile. We therefore strongly recommend to follow the above advice.

(others that build programs)

Java

As it happens way too often: please do not ship any prebuilt class or jar files or any other generated files without accomanying source code and do not download such files during the build process. Please document each dependency and in particular: where can its source code be obtained.

Apache ant is a very popular build tool for Java code and it is easy to use for Debian packaging, too.

Perl

Please use one of the standard Perl build systems, either Module::Build or ExtUtils::MakeMaker, and please try not to modify it in too many odd ways. That helps greatly in preparing packages.

Please remember that builds need to be done unattended and provide some mechanism to set defaults or bypass any prompts with known answers.

(we like stuff from CPAN, why?) (plugins => see above)

Here is a link to the debian-perl group's internal policy regarding perl packages in debian [http://pkg-perl.alioth.debian.org/policy.html pkg-perl policy].

Python

(they have a standard way of packaging too) (plugins => see above)

OCaml

Please help us in supporting architectures for which the native code compiler (ocamlopt) is not available. Practically this mean to support in your build tool (makefile or corresponding) one of the following 2 behaviors:

  1. automatically detect whether ocamlopt is available or not, build native code objects/executables only if this is the case, install native code executables only if they have been built
  2. provide different make targets (or corresponding tool invocations) to build and install bytecode stuff vs native code stuff. Usual names for that are: all vs opt (to build bytecode/native code stuff) and install vs install-opt

(other languages with their own deployment tools)

Got Packaged

If your package got packaged, congratulations. We hope that you will get new users. There is some resources that you may want to be aware of:

  • http://packages.qa.debian.org/package where package is the name of the package in Debian ; this page is a portal to all kind of information. You can subscribe to Package Tracking System (PTS) to be mailed when there is a new release or when a user report a new bug.

  • http://bugs.debian.org/package where package is the name of the package in Debian ; this page will list all bugs that have been reported by Debian users. Feel free to help to solve them, propose patch or fix them upstream.

Note that subscription to PTS is recommended but optional. The maintainer will forward you bugs that need your help or your interest.

Getting Branched

(why we maintain ancient versions in stable) (what to do if you think we shouldn't do this)

Getting Upgraded

(converting old system wide data) (converting old user data)

Getting Patched

(we need your help in understanding your package) (please add unit tests even for functionality you believe is trivial so we can see if a patch breaks something)

Getting Ported

(viewing autobuilder logs) (more info: GettingPorted)