Guidelines
Guidelines and standards for creating Debian packages
Working version
(Last modified: 15 Mar 1993)
This is a working version of the guidelines and standards for
preparing `dpkg' packages. As you will notice, there are still a few
specifics to be worked out. The standard is, at present, not clear on
several points. These points will be clarified soon (most of them are
waiting for the C version of `dpkg'; we are changing a few specifics
in the new version, which is not yet complete).
This document will eventually be distributed with the source code to
`dpkg', package creation utilities and a sample package.
PLEASE READ THIS AND COMMENT ON IT, BUT DO NOT USE IT TO PACKAGE
ANYTHING YET. IT WILL LIKELY CHANGE WITHIN THE NEXT WEEK.
============================================================================
This document describes the steps that must be taken in the
preparation of a Debian package or a package that attempts to conform
to the Debian `dpkg' format. All submissions to be included in the
Debian distribution proper and all packages 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 in certain circumstances; we want the
maximum amount of software to be available in `dpkg' format for Debian
users, so in some cases 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 them.
When in doubt, ask me. Be prepared to provide me with the copyright.
Software with a BSD-like copyright, software covered by the GPL and
public domain software are safe; be wary of ``distribution
restricted'', ``commercial use prohibited'' and similar phrases.
All package submissions _must_ be accompanied by a _verbatim_ copy of
its copyright (with the exception of BSD, GPL and public domain;
simply indicate which is appropriate).
============================================================================
Configuring the source package and building the binary package
--------------------------------------------------------------
* The following Makefile variables should be used:
CC = gcc
CFLAGS = -O2 -fomit-frame-pointer -m486
LDFLAGS = -s (and -N, if appropriate)
* 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 re-`configure' the
package if necessary.
* The `install' target of the source package should be all that is
necessary for the user to compile and install the binary package.
Ensure that _all_ necessary installation work is done BY THE MAKEFILE.
You should not need 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 properly.
In essence, strive for a source package that will generate the
equivalent binary package with a simple `make install' and nothing
more.
* Location, permissions and ownerships:
[ NOTE: this may change in the near future. ]
Location Permission Ownership
Binaries (normal): */bin, */sbin 0755 root.bin
Binaries (set[gu]id): */bin, */sbin [42]711 <user>.<group>
Text documentation: /usr/doc 444 root.root
Examples: /usr/doc/examples 444 root.root
Info documents: /usr/info 444 root.root
Man pages: /usr/man 444 root.man
* Text documentation and Info documents should be `gzipped' when they
are installed.
* In certain circumstances, subdirectories of /usr/doc may be used if
a package has a great deal of text documentation.
* 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 be compressed with `gzip -9' and be named in the
form:
<package>-<version>.debian.diff.gz
Example: `fileutils-3.9.debian.diff.gz'
============================================================================
Preparing the `dpkg' package
----------------------------
NOTE: Only packages to be included in the distribution proper need to
have a category. If you are packaging something for the distribution,
then please talk to me about placing it in a category.
The following files are used by the `dpkg' utility for installation
and package maintenance. Some of these files are required, and others
are not.
* /var/adm/dpkg/dep/<pkg>.dep
(Not required)
This file describes package dependencies. Please ignore this file for
the moment; the format used in 0.91 doesn't work very well, and we are
currently in the process of working out a different format.
* /var/adm/dpkg/desc/<pkg>.desc
(REQUIRED)
This file provides a brief description of the package. Use this as a
template for creating it:
--8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<--
Package: (Name of the Debian package)
Category: (Package category; see above)
Name: (Complete name of the package)
Version: (Version of the package)
Description: (A brief description of the package)
--8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<---8<--
Example:
----------------------------------------------------------------------------
Package: bc
Category: util
Name: GNU bc
Version: 1.02
Description: An arbitrary precision calculator language
----------------------------------------------------------------------------
* /var/adm/dpkg/inst/<pkg>.inst
(Not required)
This file is a /bin/sh script and is executed, if found, after the
batch processing of packages. It can be used to provide automatic or
user-controlled setup of a package after installation.
For example, this script is used to automatically create the
/usr/bin/emacs symbolic link depending on whether or not the user
installed the Emacs X11 binary:
----------------------------------------------------------------------------
#! /bin/sh
if [ -x /usr/bin/emacs-x11 ]; then
cd /usr/bin
ln -s emacs-x11 emacs
chown root.bin emacs
else
if [ -x /usr/bin/emacs-no-x ]; then
cd /usr/bin
ln -s emacs-no-x emacs
chown root.bin emacs
fi
fi
----------------------------------------------------------------------------
* /var/adm/dpkg/list/<pkg>.list
(REQUIRED)
This file contains a list of all files in the package relative to root
(/). Ensure that the `dpkg' control files are in the list as well as
all files installed with the `make install' of the source package.
Example:
----------------------------------------------------------------------------
/usr/bin/bc
/usr/man/man1/bc.1
/var/adm/dpkg/list/bc.list
/var/adm/dpkg/perm/bc.perm
/var/adm/dpkg/ver/bc.ver
----------------------------------------------------------------------------
* /var/adm/dpkg/ver/<pkg>.ver
(REQUIRED)
This file contains one line and nothing more: the version number string.
Example:
----------------------------------------------------------------------------
0.92 BETA
----------------------------------------------------------------------------
* /var/adm/dpkg/perm/<pkg>.perm
This file contains the `fixperms' control file. It should be created
_last_. Before creating it, ensure that all files are correctly
listed in /var/adm/dpkg/list/<pkg>.list and that the permissions and
ownerships of the files in the package are correct. When this is
done, type the following to generate the perms file:
[ NOTE: I tried this, but it didn't work. This is the first time that
I've tried to do this with fixperms 1.0... Anthony? ]
# fixperms --absolute --force <pkg> /var/adm/dpkg/list/<pkg>.list
============================================================================
Packaging and submission
------------------------
* Once the package has been configured and installed and the
appropriate `dpkg' control files have been constructed, the following
will create the <pkg>.deb file:
# cd /
# cpio --create --verbose < /var/adm/dpkg/list/<pkg>.list | gzip -9 > <pkg>.deb
* Upload the following:
- the source package
- the context diff
- the .deb package
to `sunsite.unc.edu::/pub/Linux/distributions/debian/Incoming'.
All uploads must be accompanied by mail to <imurdock@sunsite.unc.edu>
describing the upload and containing the copyright as requested
earlier.
Reply to: