Source package guidelines
Here are the revised guidelines for constructing Debian source
packages. They may change _very slightly_ in the near future, as I
just received a few good points from Dan, but the main requirements
will still hold. I'm heading out-of-town in a few minutes, and I
wanted to mail the guidelines before I left.
This is also available at tempest.ecn.purdue.edu.
Ian Murdock <imurdock@gnu.ai.mit.edu>
Debian source package guidelines
Ian Murdock <imurdock@gnu.ai.mit.edu>
Revision: Thu Apr 7 22:02:24 EST 1994
===============================================================================
This document describes the steps that must be taken in the
preparation of a Debian source package. All submissions to be
included in the Debian distribution and all packages wishing to be
considered for Debian `contrib' availability _must_ follow the
guidelines and standards listed in this document.
* Considerations
There is one _very_ important consideration to make before proceeding:
do you, the packager, understand the copyright of the package that you
wish to submit? PLEASE study the copyright of your submission VERY
CAREFULLY and UNDERSTAND IT before proceeding!
Ensure that distribution is possible in binary and source form without
restrictions on modification, redistribution and for-profit use of the
package. All submissions to be included in the distribution proper
_must_ be free of such restrictions or they cannot be included.
Submissions for `contrib' availability, however, may be allowed to
deviate from this requirement; we want the maximum amount of software
to be available in `dpkg' format for Debian users, so in certain
circumstances it will be allowable to have ``shareware'' and other
non-free software optionally available as `contrib' packages. It is
important to note that these packages will be _optional_ additions to
the Debian system and that the Debian system itself will remain
completely free of such packages.
When in doubt, send mail to me (see above for address). Be prepared
to provide me with the copyright. Software covered by the GPL, public
domain software and BSD-like copyrights are safe; be wary of the
phrases ``commercial use prohibited'' and ``distribution restricted''.
ALL package submissions _must_ be accompanied by a verbatim copy of
its copyright (with the exception of packages covered by the GPL,
packages with BSD-like copyrights and public domain software; simply
indicate which is appropriate).
===============================================================================
Configuring the source package and building the binary package
--------------------------------------------------------------
* The `install' target of the source package should be all that is
necessary for the user to build the binary package that is shipped as
part of the Debian system. Ensure that _all_ necessary installation
work is done by the Makefile. The package maintainer should _not_
have to manually change permissions, `gzip' files, etc. after the
package has been installed. Ensure that all binaries are installed in
the proper locations and with the correct permissions and ownerships.
Ensure that any appropriate documentation is installed along with any
appropriate examples and that man pages and Info documents are
installed.
In essence, strive for a source package that will generate the
equivalent binary package with a simple `make install' (and a
`./configure', if appropriate; see below) and nothing more.
* Edit the *.in files in packages where `configure' scripts are used
and generate the Makefile, etc. from them rather than editing the
generated files directly. This allows the user to reconfigure the
package if necessary. Do _not_ simply configure the package and edit
the generated Makefile! This makes it impossible for someone else to
reconfigure the package.
* The location of installed files _must_ follow the Linux Filesystem
Standard. The latest version of this document can be found alongside
this Debian source package guidelines. Specific questions about
following the standard can be addressed to Daniel Quinlan
<quinlan@spectrum.cs.bucknell.edu>.
* All directories should be mode 755, with the exception of special
``system'' directories that need to be another mode. The ownership of
the directory should be consistent with its mode; if a directory is
mode 775, then it should be owned by the group that needs write access
to it. Use common sense in assigning permissions and ownerships to
directories, and make sure that what is done is secure if it is
``non-standard''.
* In general, normal binaries should be mode 755 and owned by
root.bin. If there is a good reason to use a different mode or
ownership, then feel free to do so, but do try to be as consistent as
possible with the rest of the system.
* setuid/setgid binaries should be mode 4711/2711 and owned by the
appropriate user/group. For security reasons, please do not make
setuid/setgid binaries mode 4755/2755.
* Library files should be installed with the appropriate
permissions/ownerships, depending on what the package needs to
function correctly.
* Manual pages should be mode 444 and owned by root.man. The nroff
source must be installed. There is no need to install a pre-formatted
cat page.
* Info documents should be mode 444 and `gzipped' when installed.
* Any other documentation that comes with the package should be
installed at the discretion of the package maintainer. Text
documentation should be mode 444, `gzipped' and installed to /usr/doc.
If a subdirectory of /usr/doc is warranted, then please feel free to
create one. Please do not install large text or PostScript
documentation to /usr/doc; however, please do upload such
documentation _separately_ so that it can be made available via FTP
with the distribution in a `doc' directory. If a user has the need
for the documentation they can easily get it from there.
* Any example files (for example, sample configuration files) should
be placed in /usr/doc/examples. If the file is normally a hidden
file, such as `.emacs', then please call it `dot.emacs' to avoid
confusion.
* All symbolic links should be relative, not absolute. Absolute
links, in general, cause problems when a filesystem is not mounted
where it ``normally'' resides (for example, when mounted via NFS). In
certain cases, however, relative links may also cause similar problems
(for example, if /usr is mounted on /foo/bar, and /foo/bar/spool is a
link to ../spool it will not find it); in this case, feel free to use
absolute links, but they should be used only when necessary. I have
generally made links into /etc and /var absolute and all other links
relative. There may be other cases in which absolute links are
necessary.
Therefore, in the Makefile, do not do (even though it is easier):
install: all
[...]
ln -fs /usr/bin/gcc /usr/bin/cc
[...]
Instead, do:
install: all
[...]
( cd /usr/bin ; ln -fs gcc cc )
[...]
Please do not create symbolic links in the manual page directories;
use hard links instead.
* At least the following Makefile variables should be used:
CC = gcc
CFLAGS = -O2
LDFLAGS = -s (and -N, if appropriate; see below)
All installed binaries should be stripped. `-N' should only be used
on binaries that are very small (less than 8K with the `-N' option,
roughly) and are not likely to have multiple instances in memory. Do
not use `-N' on daemons, no matter how small they are.
It is up to the package maintainer to decide what compilation options
are best for the package. Certain binaries (such as computational-
intensive programs) may function better with certain flags; feel free
to use them.
* Please document your changes so that future package maintainers know
what has been changed. Record your changes for Debian in a file
called `README.Debian', and include relevant information such as your
name, electronic mail address, date, etc. If changes to the source
code are made, then please use a `define'. If it is a change required
to compile or function under Linux in general, then use `LINUX'; if it
is a cosmetic or functional change, then use `DEBIAN'.
* Archive the source package using `tar'. Use `gzip -9' to compress
it. Source packages should be named in the form:
<package>-<version>.tar.gz
Example: `fileutils-3.9.tar.gz'
* Make a context diff against the original package:
# diff --context --recursive foo-1.0.orig/ foo-1.0/
Context diffs should compressed with `gzip -9' and be named in the
form:
<package>-<version>.debian.diff.gz
Example: `fileutils-3.9.debian.diff.gz'
* Comments or questions about the guidelines outlined in this document
can be address to Ian Murdock <imurdock@gnu.ai.mit.edu>.
Reply to: