+++ /dev/null
-<!doctype debiandoc system>
-
-<!--
- Debian Linux package policy manual.
- Copyright (C)1996 Ian Jackson; released under the terms of the GNU
- General Public License, version 2 or (at your option) any later.
- -->
-
-<book>
-
-<title>Debian policy manual
-<author>Ian Jackson <email/ijackson@gnu.ai.mit.edu/
-<version>version 0.1, <date>
-
-<abstract>
-This manual describes the policy requirements which must be satisfied
-for a package to be included in the Debian distribution. This
-includes details of the permissions and ownerships of files in
-packages and other technical requirements as well as information like
-the upload procedure.
-</abstract>
-
-<copyright>Copyright ©1996 Ian Jackson.
-<p>
-
-This manual is free software; you may redistribute it and/or modify it
-under the terms of the GNU General Public License as published by the
-Free Software Foundation; either version 2, or (at your option) any
-later version.
-<p>
-
-This is distributed in the hope that it will be useful, but
-<em>without any warranty</em>; without even the implied warranty of
-merchantability or fitness for a particular purpose. See the GNU
-General Public License for more details.
-<p>
-
-You should have received a copy of the GNU General Public License with
-your Debian GNU/Linux system, in <tt>/usr/doc/copyright/GPL</tt>, or
-with the <prgn/dpkg/ source package as the file <tt>COPYING</tt>. If
-not, write to the Free Software Foundation, Inc., 675 Mass Ave,
-Cambridge, MA 02139, USA.
-
-<toc sect>
-
-<chapt id="scope">Introduction and scope of this manual
-<p>
-
-This manual describes the criteria that a Debian-format package must
-satisfy to be included in the Debian distribution.
-<p>
-
-Much of this information will be useful even when building a package
-which is to be distributed in some other way or is for local use.
-<p>
-
-This manual does <em/not/ describe the technical mechanisms involved
-in package creation, installation and removal. This information can
-be found in the <prgn/dpkg/ programmers' manual and the <prgn/dpkg/ system
-administrators' manual.
-<p>
-
-This document assumes familiarity with these other two manuals.
-<p>
-
-The Debian version of the FSF's GNU <prgn/hello/ program is provided
-as an example for people wishing to create Debian packages.
-<p>
-
-<em>Note that this document is still a draft!</em>
-
-<chapt id="pkgcopyright">Package copyright
-<p>
-
-Please study the copyright of your submission <em/carefully/ and
-understand it before proceeding. If you have doubts or questions,
-please ask.
-<p>
-
-All packages in the Debian distribution proper must be freely useable,
-modifiable and redistributable in both source and binary form. It
-must be possible for anyone to distribute and use modified source code
-and their own own compiled binaries, at least when they do so as part
-of a Debian distribution.
-<p>
-
-Packages whose copyright permission notices (or patent problems) do
-not allow distribution and copying for profit, without restriction on
-the amount charged, or where distribution is restricted according to
-the medium used, or where the distributor must ask any kind of special
-permission of the authors, or with other onerous conditions, may only
-be placed in the semi-supported non-free section of the Debian FTP
-archives. This is important so that CDROM manufacturers can
-distribute Debian without having to check the copyright of each
-package individually, simply by leaving out the contents of the
-non-free area; CDROM distributors are encouraged, though, to check the
-copyrights on programs in non-free individually and include as many as
-they can.
-<p>
-
-Packages whose copyright permission notices (or patent problems) allow
-only distribution of compiled binaries (and thus of which only
-binaries are available), or where the source code which may be
-distributed is not the complete source code required to compile the
-program (ie, the program cannot be compiled using only packages in the
-main Debian distribution), or which depend for their use on non-free
-or contrib packages, or allow free use only for a trial period
-(shareware), or are demonstration programs lacking vital functionality
-(crippleware), or are only installer-packages which require the user
-to supply a separate file to be installed, or which fail to meet some
-other policy requirements, may only be placed in the semi-supported
-contrib section of the Debian FTP archives (unless they need to be in
-non-free - see above).
-<p>
-
-Programs whose authors encourage the user to make donations are fine
-for the main distribution, provided that the authors do not claim that
-not donating is immoral, unethical, illegal or something similar;
-otherwise they must go in contrib (or non-free, if even distribution
-is restricted by such statements).
-<p>
-
-Packages whose copyright permission notices (or patent problems) do
-not allow redistribution even of only binaries, and where no special
-permission has been obtained, cannot placed on the Debian FTP site and
-its mirrors at all.
-<p>
-
-Note that under international copyright law<footnote>This applies in
-the United States, too.</footnote> <em/no/ distribution or modification
-of a work is allowed without an explicit notice saying so. Therefore
-a program without a copyright notice <em/is/ copyrighted and you may
-not do anything to it without risking being sued! Likewise if a
-program has a copyright notice but no statement saying what is
-permitted then nothing is permitted.
-<p>
-
-Many authors are unaware of the problems that restrictive copyrights
-(or lack of copyright notices) can cause for the users of their
-supposedly-free software. It is often worthwhile contacting such
-authors diplomatically to ask them to modify their terms generally, or
-specially for Debian. However, this is a politically difficult thing
-to do and you should ask for advice on <prgn/debian-devel/ first.
-<p>
-
-When in doubt, send mail to <email/debian-devel@lists.debian.org/. Be
-prepared to provide us with the copyright statement. 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'.
-<p>
-
-Every package submission <em/must/ be accompanied by verbatim copy of
-its copyright (with the exceptions of public domain packages and those
-covered by the UCB BSD licence or the GNU GPL or LGPL; in these cases
-simply indicate which is appropriate). This information must be
-included in a file installed by the binary package - see <ref
-id="copyrightfile">.
-
-<chapt id="binarypkg">Contents of the binary package
-
-<sect>Control file requirements
-
-<sect1><tt/Maintainer/ information
-<p>
-
-All packages must have a <tt/Maintainer/ field with the correct name
-and a working email address for the Debian maintainer of the package.
-If one person maintains several packages they should try to avoid
-having different forms of their name and address in different
-<tt/Maintainer/ fields.
-
-<sect1>Dependencies and virtual packages
-<p>
-
-Add a dependency for any shared libraries required by
-dynamically-linked executable binaries in your package. Almost every
-package containing compiled C code should therefore include a
-<tt/Depends/ field which mentions the shared C library required for
-the program to run. For ELF binaries linked against <tt/libc.so.5/
-the relevant package name is <tt/libc5/.
-<p>
-
-All packages must use virtual package names where appropriate, and
-arrange to create new ones if necessary. They must not use virtual
-package names (except privately, amongst a cooperating group of
-packages) unless they have been agreed upon and appear in the list of
-virtual package names.
-<p>
-
-The latest version of the authoritative list of virtual package names
-can be found on <ftpsite>ftp.debian.org</> in
-<ftppath>/debian/doc/package-developer/virtual-package-names-list.text</>
-or your local mirror. The procedure for updating it is described at
-the top of the file.
-
-<sect1><tt/Section/ and <tt/Priority/
-<p>
-
-Decide whether your package can go in <tt/non-free/, <tt/contrib/ or
-the main distribution - see <ref id="pkgcopyright">, and put
-an appropriate value for the distribution in the
-<tt>debian/changelog</> file.
-<p>
-
-The <tt/Priority/ and <tt/Section/ control file fields give
-information for classifying the package in <prgn/dselect/ and say
-which directory to place it in the FTP archive.
-<p>
-
-They are ultimately the responsibility of the distribution
-maintainers; however, you should suggest values for them in your
-<tt/.changes/ information when you upload a package. You do this by
-including appropriate information in the <tt>debian/control</tt> file
-before building the packages.
-<p>
-
-For a list of the currently in-use sections, please see the FTP
-archive. Packages in the non-free and contrib areas should have
-section <tt/non-free/ and <tt/contrib/, respectively.
-
-<sect2><tt/Priority/ values
-<p>
-
-<taglist>
-<tag><tt/required/
-<item>
-<tt/required/ packages are necessary for the proper functioning of the
-system. You must not remove these packages or your system may become
-totally broken and you may probably not even be able to use
-<prgn/dpkg/ to put things back. Systems with only the <tt/required/
-packages are probably unuseable, but they do have enough functionality
-to allow the sysadmin to boot and install more software.
-
-<tag><tt/important/
-<item>
-Important programs, including those which one would expect to find on
-any Unix-like system. If the expectation is that an experienced Unix
-person who found it missing would go `What the F*!@<+ is going on,
-where is <prgn/foo/', it should be in <tt/important/. This is an
-important criterion because we are trying to produce, amongst other
-things, a free Unix. Other packages without which the system will not
-run well or be useable should also be here. This does <em/not/
-include Emacs or X11 or TeX or any other large applications. The
-<tt/important/ packages are just a bare minimum of commonly-expected
-and necessary tools.
-
-<tag><tt/standard/
-<item>
-These packages provide a reasonably small but not too limited
-character-mode system. This is what will install by default if the
-user doesn't select anything else. It doesn't include many large
-applications, but it does include Emacs (this is more of a piece of
-infrastructure than an application) and a reasonable subset of TeX and
-LaTeX (if this is possible without X).
-
-<tag><tt/optional/<footnote>In a sense everything is optional that
-isn't required, but that's not what is meant here.</footnote>
-<item>
-This is all the software that you might reasonably want to install if
-you didn't know what it was or don't have specialised requirements.
-This is a much larger system and includes X11, a full TeX
-distribution, and lots of applications.
-
-<tag><tt/extra/
-<item>
-This contains packages that conflict with others with higher
-priorities, or are only likely to be useful if you already know what
-they are or have specialised requirements.
-
-</taglist>
-<p>
-
-Priority values are not case-sensitive.
-
-<sect2>Base packages
-<p>
-
-Some packages have <tt/Section: base/ and are in the <tt/base/
-subdirectory on the FTP archives. These are the packages that are
-supplied on the base disks. They are the minimum sensible set for
-installing new packages (perhaps via a network).
-<p>
-
-Most of these packages should have <tt/Priority: required/ or at least
-<tt/Priority: important/.
-
-<sect1>The <tt/Essential/ flag
-<p>
-
-The <tt/Essential: yes/ control file field should not be used unless
-removing a package really will completely hose the system; nor should
-it be used for a shared library package - the dependencies will
-prevent its premature removal, and we need to be able to remove it
-when it has been superseded.
-
-<sect1>Including <tt/Priority/ and <tt/Section/ in the <tt/.deb/
-control file
-<p>
-
-If a user installs a package which is not part of the standard
-distribution, or without downloading and updating from a new
-<prgn/Packages/ file, the information about the priority and section
-of a package will be absent, and the <prgn/dselect/ package listing
-will have the package listed under `unclassified'. In order to
-improve this it is permissible to use the <tt/-is/, <tt/-isp/ or
-<tt/-ip/ option to <prgn/dpkg-gencontrol/, so that the <tt/Section/
-and/or <tt/Priority/ is copied into the actual control information in
-the <tt/.deb/ file. However, if you do this you should make sure you
-keep the information up to date so that users are not shown
-conflicting information.
-
-
-<sect1>Formatting of the <tt/Description/ control file field
-<p>
-
-Every Debian package should have an extended description.
-<p>
-
-The description should be written so that it tells the user what they
-need to know to decide whether to install the package. This
-description should not just be copied from the blurb for the program.
-Instructions for configuring or using the package should not be
-included - that is what installation scripts, manpages, Info files and
-<tt>/usr/doc/<var/package/</> are for. Copyright statements and other
-administrivia should not be included - that is what
-<tt>/usr/doc/copyright</> is for.
-<p>
-
-If you wish to include a list in your extended with entries which are
-a line or more each you must indent each entry by one space to make
-sure that it doesn't get wordwrapped. The start of each list entry
-should be marked with an asterisk, followed by a single space. You
-must wrap the list entries yourself to 75 columns, and should start
-continuation lines indented by three spaces so that they line up with
-the start of the text on the first line of each list entry.
-<p>
-
-See the programmers' manual for further requirements and pitfalls.
-
-<sect>Locations of files
-<p>
-
-The location of all installed files and directories must comply fully
-with the Linux File System Standard (FSSTND). The latest version of
-this document can be found alongside this manual or on
-<ftpsite/tsx-11.mit.edu/ in
-<ftppath>/pub/linux/docs/linux-standards/fsstnd/</>. Specific questions
-about following the standard may be asked on <prgn/debian-devel/, or
-referred to Daniel Quinlan, the FSSTND coordinator, at
-<email/quinlan@yggdrasil.com/.
-<p>
-
-<sect1>Manpages
-<p>
-
-You must install manpages in <prgn/nroff/ source form, in appropriate
-places under <tt>/usr/man</tt>. You should only use sections 1 to 9
-(see the FSSTND for more details). You must <em/not/ install a
-preformatted `cat page'.
-<p>
-
-If no manual page is available for a particular program, utility or
-function and this is reported as a bug on debian-bugs, a symbolic link
-from the requested manual page to the <manref name=undocumented
-section=7> manual page should be provided. This symbolic link can be
-created from <tt>debian/rules</> like this:
-<example>
-ln -s ../man7/undocumented.7 \
- debian/tmp/usr/man/man[1-9]/the_requested_manpage.[1-9]
-</example>
-This manpage claims that the lack of a manpage has been reported as a
-bug, so you may only do this if it really has (you can report it
-yourself, if you like). Do not close the bug report until a proper
-manpage is available.
-<p>
-
-You may forward a complaint about a missing manpage to the upstream
-authors, and mark the bug as forwarded in the Debian bug tracking
-system. Even though the GNU Project do not in general consider the
-lack of a manpage to be a bug, we do - if they tell you that they
-don't consider it a bug you should leave the bug in our bug tracking
-system open anyway.
-<p>
-
-Manpages should be installed uncompressed.
-<p>
-
-If one manpage needs to be accesssible via several names it is better
-to use a symbolic link than the <tt/.so/ feature, but there is no need
-to fiddle with the relevant parts of the upstream source to change
-from <tt/.so/ to symlinks - don't do it unless it's easy. Do not
-create hard links in the manual page directories, and do not put
-absolute filenames in <tt/.so/ directives. The filename in a
-<tt/.so/ in a manpage should be relative to the base of the manpage
-tree (usually <tt>/usr/man</tt>).
-
-<sect1>Info documents
-<p>
-
-Info documents should be installed in <tt>/usr/info</tt>. They should
-be compressed with <tt/gzip -9/.
-<p>
-
-Your package must call <prgn/install-info/ to update the Info <tt/dir/
-file, in its post-installation script:
-<example>
-install-info --quiet --section Development Development \
- /usr/info/foobar.info
-</example>
-<p>
-
-It is a good idea to specify a section for the location of your
-program; this is done with the <tt/--section/ switch. To determine
-which section to use, you should use look at <tt>/usr/info/dir</> on
-your system and choose the most relevant (or create a new section if
-none of the current sections are relevant). Note that the
-<tt/--section/ flag takes two arguments; the first is a regular
-expression to match (case-insensitively) against an existing section,
-the second is used when creating a new one.
-<p>
-
-You must remove the entries in the pre-removal script:
-<example>
-install-info --quiet --remove /usr/info/foobar.info
-</example>
-<p>
-
-If <prgn/install-info/ cannot find a description entry in the Info file
-you will have to supply one. See <manref name=install-info section=8>
-for details.
-
-<sect1>Additional documentation
-<p>
-
-Any additional documentation that comes with the package can be
-installed at the discretion of the package maintainer. Text
-documentation should be installed in a directory
-<tt>/usr/doc/<var/package/</tt><footnote>Where <var/package/ is the
-name of the package.</footnote> and compressed with <tt/gzip -9/
-unless it is small.
-<p>
-
-If a package comes with large amounts of documentation which many
-users of the package will not require you should create a separate
-binary package to contain it, so that it does not take up disk space
-on the machines of users who do not need or want it installed.
-<p>
-
-It is often a good idea to put text information files that come with
-the source package in <tt>/usr/doc/<var/package/</> in the binary
-package. However, don't install the instructions for building and
-installing the package, of course!
-
-<sect1>Preferred documentation formats
-<p>
-
-The unification of Debian documentation is being carried out via HTML.
-<p>
-
-If your package comes with extensive documentation in a markup format
-that can be converted to various other formats you should if possible
-ship HTML versions in the binary package, in the directory
-<tt>/usr/doc/<var/package/</> or its subdirectories.
-<p>
-
-Other formats such as PostScript may be provided at your option.
-
-<sect2>Examples
-<p>
-
-Any examples (configurations, source files, whatever), should be
-installed in a directory <tt>/usr/doc/<var/package//examples</tt>.
-These files should not be referenced by any program - they're there
-for the benefit of the system administrator and users, as
-documentation only.
-
-<sect1 id="copyrightfile"><tt>/usr/doc/copyright/<var/package/</tt>
-<p>
-
-This file must contain details of the authorship and copyright of the
-package. It must say where the upstream sources (if any) were
-obtained, and explain briefly what modifications were made in the
-Debian version of the package compared to the upstream one. It must
-name the original authors of the package and the Debian maintainer(s)
-who were involved with its creation.
-<p>
-
-It must contain the full text of the copyright notice and any
-acknowledgements for the program and the licence terms under which the
-program is distributed. If the package is distributed under the GNU
-General Public Licence, the GNU Library General Public Licence, the
-Regents of the University of California at Berkeley (BSD) licence or
-Larry Wall's Artistic Licence please say so instead of including a
-copy of the licence. The files <tt/BSD/, <tt/GPL/, <tt/LGPL/ and
-<tt/Artistic/ are be available in <tt>/usr/doc/copyright</tt> for you
-to refer to. The package's copyright file should not be compressed.
-<p>
-
-Do not use the copyright file as a general <tt/README/ file. If your
-package has such a file it should be installed in
-<tt>/usr/doc/<var/package//README</> or <tt/README.Debian/ or some
-other appropriate place. Do not make links between
-<tt>/usr/doc/<var/package/</> and the <tt/copyright/ directory.
-
-<sect1>Symbolic links
-<p>
-
-Most symbolic links should be relative, not absolute. Absolute links,
-in general, cause problems when a file system is not mounted where it
-"normally" resides (for example, when mounted via NFS).
-<p>
-
-In particular, symlinks from one part of <tt>/usr</tt> to another
-should be relative.
-<p>
-
-In certain cases, however, relative links may cause more problems.
-For example, links into <tt>/etc</tt> and <tt>/var</tt> should be
-absolute.
-<p>
-
-Note that when creating a relative link using <prgn/ln/ it is not
-necessary for the target of the link to exist relative to the working
-directory you're running <prgn/ln/ from; nor is it necessary to change
-directory to the directory where the link is to be made. Simply
-include the string that should appear as the target of the link (this
-will be a pathname relative to the directory in which the link
-resides) as the first argument to <prgn/ln/.
-<p>
-
-For example, in your <prgn/Makefile/ or <tt>debian/rules</>, do things
-like:
-<example>
-ln -fs gcc $(prefix)/bin/cc
-ln -fs gcc debian/tmp/usr/bin/cc
-ln -fs ../sbin/sendmail $(prefix)/bin/runq
-ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq
-</example>
-
-<sect1>Logfiles
-<p>
-
-Logfiles should usually be named
-<tt>/var/log/<var/package/.log</tt>. If you have many logfiles,
-or need a separate directory for permissions reasons
-(<tt>/var/log</tt> is writeable only by <tt/root/), you should usually
-create a directory named <tt>/var/log/<var/package/</tt>.
-<p>
-
-Make sure that any logfiles are rotated occasionally using so that
-they don't grow indefinitely; the best way to do this is to use
-<prgn/savelog/ program in an <tt>/etc/cron.daily</>,
-<tt>/etc/cron.weekly</> or <tt>/etc/cron.monthly</> script.
-<p>
-
-Make sure that any logfiles are removed when the package is purged
-(but not when it is only removed), by checking the argument to the
-postrm script (see the programmer's manual for details).
-
-<sect1><tt>/usr/local</> - for the use of the system administrator
-<p>
-
-As mandated by the FSSTND no package should place any files in
-<tt>/usr/local</>, either by putting them in the filesystem archive to
-be unpacked by <prgn/dpkg/ or by manipulating them in their maintainer
-scripts.
-<p>
-
-Every package that searches a number of directories or files for
-something (for example, looking for shared libraries in <tt>/lib</> or
-<tt>/usr/lib</>) should search an appropriate directory in
-<tt>/usr/local</> too.
-<p>
-
-In order that the system administrator may know where to place
-additional files a package should create an empty directory in the
-appropriate place in <tt>/usr/local</> by supplying it in the
-filesystem archive for unpacking by <prgn/dpkg/. The
-<tt>/usr/local</> directory itself and all the subdirectories created
-by the package should have permissions 2775 (group-writeable and
-set-group-id) and be owned by <tt/root.staff/.
-<p>
-
-In the future it will be possible to tell <prgn/dpkg/ not to unpack
-files matching certain patterns, so that system administrators who do
-not wish these directories in <tt>/usr/local</> do not need to have
-them.
-
-<sect>Permissions and ownerships
-<p>
-
-The rules in this section are guidelines for general use. If
-necessary you may deviate from the details below. However, if you do
-so you must make sure that what is done is secure and you must try to
-be as consistent as possible with the rest of the system. You should
-probably also discuss it on <prgn/debian-devel/ first.
-<p>
-
-Files should be owned by <tt/root.root/, and made writeable only by
-the owner and universally readable (and executable, if appropriate).
-<p>
-
-Directories should be mode 755 or (for group-writability) mode 2775.
-The ownership of the directory should be consistent with its mode -
-if a directory is mode 2775, it should be owned by the group that
-needs write access to it.
-<p>
-
-Setuid and setgid executables should be mode 4755 or 2755
-respectively, and owned by the appropriate user or group. They should
-not be made unreadable (modes like 4711 or 2711 or even 4111); doing
-so achieves no extra security, because anyone can find the binary in
-the freely available Debian package - it is merely inconvenient. For
-the same reason you should not restrict read or execute permissions on
-non-set-id executables.
-<p>
-
-Some setuid programs need to be restricted to particular sets of
-users, using file permissions. In this case they should be owned by
-the uid to which they are set-id, and by the group which should be
-allowed to execute them. They should have mode 4754; there is no
-point in making them unreadable to those users who must not be allowed
-to execute them.
-<p>
-
-Do not arrange that the system administrator can only reconfigure the
-package to correspond to their local security policy by changing the
-permissions on a binary. Ordinary files installed by <prgn/dpkg/ (as
-opposed to conffiles and other similar objects) have their permissions
-reset to the distributed permissions when the package is reinstalled.
-Instead you should consider (for example) creating a group for people
-allowed to use the program(s) and making any setuid executables
-executable only by that group.
-<p>
-
-Shared libraries should be installed executable.
-
-<sect>Configuration files
-<p>
-
-Any configuration files created or used by your package should reside
-in <tt>/etc</tt>. If there are several you should consider creating a
-subdirectory named after your package.
-<p>
-
-It is almost certain that any file in <tt>/etc</tt> that is in your
-package's filesystem archive should be listed in <prgn/dpkg/'s
-<tt/conffiles/ control area file. (See the <prgn/dpkg/ programmers'
-manual).
-
-<sect>Maintainer scripts
-<p>
-
-The package installation scripts should avoid producing output which
-it is unnecessary for the user to see and should rely on <prgn/dpkg/ to
-stave off boredom on the part of a user installing many packages.
-This means, amongst other things, using the <tt/--quiet/ option on
-<prgn/install-info/.
-<p>
-
-Packages should try to minimise the amount of prompting they need to
-do, and they should ensure that the user will only every be asked each
-question once. This means that packages should try to use appropriate
-shared configuration files (such as <tt>/etc/papersize</> and
-<tt>/etc/news/server</>, rather than each prompting for their own
-list of required pieces of information.
-<p>
-
-It also means that an upgrade should not ask the same questions again,
-unless the user has used <tt/dpkg --purge/ to remove the package's
-configuration. The answers to configuration questions should be
-stored in an appropriate place in <tt>/etc</> so that the user can
-modify them, and how this has been done should be documented.
-<p>
-
-If a package has a vitally important piece of information to pass to
-the user (such as "don't run me as I am, you must edit the following
-configuration files first or you risk your system emitting
-badly-formatted messages"), it should display this in the
-<prgn/postinst/ script and prompt the user to hit return to
-acknowledge the message. Copyright messages do not count as vitally
-important (they belong in <tt>/usr/doc/copyright</>); neither do
-instructions on how to use a program (these should be in on line
-documentation, where all the users can see them).
-<p>
-
-Any necessary prompting should almost always be confined to the
-post-installation script, and should be protected with a conditional
-so that unnecssary prompting doesn't happen if a package's
-installation fails and the <prgn/postinst/ is called with
-<tt/abort-upgrade/, <tt/abort-remove/ or <tt/abort-deconfigure/.
-<p>
-
-Errors which occur during the execution of an installation script
-<em/must/ be checked and the installation <em/must not/ continue after
-an error.
-<p>
-
-The section below on scripts in general applies to package maintainer
-scripts too.
-
-<sect>Scripts in general
-<p>
-
-All command scripts, including the package maintainer scripts inside
-the package and used by <prgn/dpkg/, should have a <tt/#!/ line naming
-the shell to be used to interpret them.
-<p>
-
-In the case of Perl scripts this should be <tt>#!/usr/bin/perl</tt>.
-<p>
-
-Shell scripts (<prgn/sh/ and <prgn/bash/) should almost certainly
-start with <tt>set -e</> so that errors are detected. Every script
-<em/must/ use <tt/set -e/ or check the exit status of <em/every/
-command.
-<p>
-
-Perl scripts should check for errors when making any system calls,
-including <tt/open/, <tt/print/, <tt/close/, <tt/rename/ and
-<tt/system/.
-<p>
-
-<prgn/csh/ and <prgn/tcsh/ should be avoided as scripting languages. See
-Csh Programming Considered Harmful, one of the <tt/comp.unix.*/ FAQs.
-If an upstream package comes with <prgn/csh/ scripts then you must make
-sure that they start with <tt>#!/bin/csh</tt> and make your package
-depend on <prgn/csh/.
-<p>
-
-<sect>Compilation options
-<p>
-
-Generally the following compilation parameters should be used:
-<example>
-CC = gcc
-CFLAGS = -O2 -g -Wall # sane warning options vary between programs
-LDFLAGS = # none
-install -s # (or use strip on the files in debian/tmp)
-</example>
-<p>
-
-Note that all installed binaries should be stripped, either by using
-the <tt/-s/ flag to <prgn/install/, or by calling <prgn/strip/ on the
-binaries after they have been copied into <tt>debian/tmp</> but
-before the tree is made into a package.
-<p>
-
-Make sure that you do not link with <tt/-g/, as this makes a.out
-compilers produce huge statically linked binaries. The <tt/-g/ flag
-is useful on compilation so that you have available a full set of
-debugging symbols in your built source tree, in case anyone should
-file a bug report involving (for example) a core dump.
-<p>
-
-The <tt/-N/ flag should not be used. On a.out systems it may have
-been useful for some very small binaries, but for ELF it has no good
-effect.
-<p>
-
-It is up to the package maintainer to decide what compilation options
-are best for the package. Certain binaries (such as
-computationally-intensive programs) may function better with certain
-flags (<tt/-O3/, for example); feel free to use them. Please use good
-judgment here. Don't use flags for the sake of it; only use them if
-there is good reason to do so. Feel free to override the upstream
-author's ideas about which compilation options are best - they are
-often inappropriate for our environment.
-<p>
-
-Please make sure that you use only released versions of shared
-libraries to build your packages; otherwise other users will not be
-able to run your binaries properly. Producing source packages that
-depend on unreleased compilers is also usually a bad idea.
-
-<sect>Shared library packages
-<p>
-
-Packages involving shared libraries should be split up into several
-binary packages.
-<p>
-
-For a straightforward library which has a development environment and
-a runtime kit including just shared libraries you need to create two
-packages: <tt/<var/libraryname/<var/soname//<footnote><var/soname/ is
-the shared object name of the shared library - it's the thing that has
-to match exactly between building an executable and running it for the
-dynamic linker to be able run the program. Usually the <var/soname/
-is the major number of the library.</footnote> and
-<tt/<var/libraryname/<var/soname/-dev/.
-<p>
-
-If you prefer only to support one development version time you may
-name the development package <tt/<var/libraryname/-dev/; otherwise you
-may wish to use <prgn/dpkg/'s conflicts mechanism to ensure that the
-user only installs one development version at a time (after all,
-different development versions are likely to have the same header
-files in them, causing a filename clash if both are installed).
-Typically the development version will also need an exact version
-dependency on the runtime library, to make sure that compilation and
-linking happens correctly.
-<p>
-
-Packages which use the shared library should have a dependency on the
-name of the shared library package,
-<tt/<var/libraryname/<var/soname//. When the <var/soname/ changes you
-can have both versions of the library installed while moving from the
-old library to the new.
-<p>
-
-If your package has some run-time support programs which use the
-shared library you must <em/not/ put them in the shared library
-package. If you do that then you won't be able to install several
-versions of the shared library without getting filename clashes.
-Instead, either create a third package for the runtime binaries (this
-package might typically be named <tt/<var/libraryname/-runtime/ - note
-the absence of the <var/soname/ in the package name) or if the
-development package is small include them in there.
-<p>
-
-If you have several shared libraries built from the same source tree
-you can lump them all togther into a single shared library package,
-provided that you change all their <var/soname/s at once (so that you
-don't get filename clashes if you try to install different versions of
-the combined shared libraries package).
-<p>
-
-Follow the directions in the <prgn/dpkg/ programmers' manual for
-putting the shared library in its package.
-
-<sect>Application configuration files, dotfiles and <tt>/etc/skel</>
-<p>
-
-Files in <tt>/etc/skel</> will automatically be copied into new user
-accounts by <prgn/adduser/. They should not be referenced there by
-any program.
-<p>
-
-Therefore, if a program needs a dotfile to exist in advance in
-<tt/$HOME/ to work sensibly that dotfile should be installed in
-<tt>/etc/skel</> (and listed in conffiles, if it is not generated and
-modified dynamically by the package's installation scripts).
-<p>
-
-However, programs that require dotfiles in order to operate sensibly
-(dotfiles that they do not create themselves automatically, that is)
-are a bad thing, and programs should be configured by the Debian
-default installation as close to normal as possible.
-<p>
-
-Therefore, if a program in a Debian package needs to be configured in
-some way in order to operate sensibly that configuration should be
-done in a site-wide global configuration file elsewhere in
-<tt>/etc</>. Only if the program doesn't support a site-wide default
-configuration and the package maintainer doesn't have time to add it
-should a default per-user file be placed in <tt>/etc/skel</>.
-<p>
-
-<tt>/etc/skel</> should be as empty as we can make it. This is
-particularly true because there is no easy mechanism for ensuring that
-the appropriate dotfiles are copied into the accounts of existing
-users when a package is installed.
-<p>
-
-Ideally the sysadmin should ideally not have to do any configuration
-other than that done (semi-)automatically by the postinst script.
-
-<sect id="mail">Mail processing on Debian systems
-<p>
-
-Debian packages which process electronic mail, whether
-mail-user-agents (MUAs) or mail-transport-agents (MTAs), <em/must/
-make sure that they are compatible with the configuration decisions
-below. Failure to do this may result in lost mail, broken <tt/From:/
-lines, and other serious brain damage!
-<p>
-
-The mail spool is <tt>/var/spool/mail</> and the interface to send a
-mail message is <tt>/usr/sbin/sendmail</> (as per the FSSTND). The
-mail spool is part of the base system and not part of the MTA package.
-<p>
-
-Mailboxes are locked using the <tt/<var/username/.lock/ lockfile
-convention, rather than <prgn/fcntl/, <prgn/flock/ or <prgn/lockf/.
-<p>
-
-Mailboxes are generally 660 <tt/<var/user/.mail/ unless the user has
-chosen otherwise. A MUA may remove a mailbox (unless it has
-nonstandard permissions) in which case the MTA or another MUA must
-recreate it if needed. Mailboxes must be writeable by group mail.
-<p>
-
-The mail spool is 2775 <tt/mail.mail/, and MUA's need to be setgid
-mail to do the locking mentioned above (and obviously need to avoid
-accessing other users' mailboxes using this privilege).
-<p>
-
-<tt>/etc/aliases</> is the source file for the system mail aliases
-(e.g. postmaster, usenet, etc.) - it is the one which the sysadmin
-and postinst scripts may edit. After <tt>/etc/aliases</> is edited
-the program or human editing it must call <prgn/newaliases/. All MTA
-packages should come with a <prgn/newaliases/ program, even if it does
-nothing, but older MTA packages do not do this so programs should not
-fail if <prgn/newaliases/ cannot be found.
-<p>
-
-The convention of writing <tt/forward to <var/address// in the mailbox
-itself is not supported. Use a <tt/.forward/ file instead.
-<p>
-
-The location for the <prgn/rmail/ program used by UUCP for incoming
-mail is <tt>/usr/sbin/rmail</>, as per the FSSTND. Likewise,
-<prgn/rsmtp/, for receiving batch-SMTP-over-UUCP, is in
-<tt>/usr/sbin/rsmtp</> if it is supported.
-<p>
-
-Smail is not using HoneyDanBer UUCP, whose <prgn/uux/ apparently
-accepts <tt/-a/ and <tt/-g/ options.
-<p>
-
-If you need to know what name to use (for example) on outgoing news
-and mail messages which are generated locally, you should use the file
-<tt>/etc/mailname</>. It will contain the portion after the username
-and <tt/@/ (at) sign for email addresses of users on the machine
-(followed by a newline).
-<p>
-
-A package should check for the existence of this file. If it exists
-it should use it without comment.<footnote>An MTA's prompting
-configuration script may wish to prompt the user even if it finds this
-file exists.</footnote> If it does not exist it should prompt the user
-for the value and store it in <tt>/etc/mailname</> as well as using it
-in the package's configuration. The prompt should make it clear that
-the name will not just be used by that package. E.g., in this
-situation the INN package says:
-<example>
-Please enter the `mail name' of your system. This is the hostname
-portion of the address to be shown on outgoing news and mail messages.
-The default is <var/syshostname/, your system's host name.
-Mail name [`<var/syshostname/']:
-</example>
-where <var/syshostname/ is the output of <tt/hostname -fqdn/.
-
-
-<sect>Packages which can use the X shared libraries
-<p>
-
-Some programs can be configured with or without support for X Windows.
-Typically these binaries produced when configured for X will need the
-X shared libraries to run.
-<p>
-
-Such programs should be configured <em/with/ X support, and should
-declare a dependency on <tt/elf-x11r6lib/ (for the X11R6 libraries).
-Users who wish to use the program can install just the relatively
-small <tt/xlib/ package, and do not need to install the whole of X.
-<p>
-
-Do not create two versions (one with X support and one without) of
-your package.
-
-
-<sect>Games
-<p>
-
-The permissions on /var/lib/games are 755 <tt/root.root/.
-<p>
-
-Each game decides on its own security policy.
-<p>
-
-Games which require protected, privileged access to high-score files,
-savegames, &c, must be made set-<em/group/-id (mode 2755) and
-owned by <tt/root.games/, and use files and directories with
-appropriate permissions (770 <tt/root.games/, for example). They must
-<em/not/ be made set-<em/user/-id, as this causes security
-problems.<footnote>If an attacker can subvert any set-user-id game
-they can overwrite the executable of any other, causing other players
-of these cames to run a trojan. With a set-group-id game the attacker
-only gets access to less important game data, and if they can get at
-the other players' accounts at all it will take considerably more
-effort.</footnote>
-<p>
-
-Some packages, for example some fortune cookie programs, are
-configured by the upstream authors to install with their data files or
-other static information made unreadable so that they can only be
-accessed through set-id programs provided. Do not do this in a Debian
-package: anyone can download the <tt/.deb/ file and read the data from
-it, so there is no point making the files unreadable. Not making the
-files unreadable also means that you don't have to make so many
-programs set-id, which reduces the risk of a security hole.
-
-<sect>Allocating package-specific users and groups
-<p>
-
-If you need to create a new user or group for your package there are
-two possibilities. Firstly, you may need to make some files in the
-binary package be owned by this user or group, or you may need to
-compile the user or group id (rather than just the name) into the
-binary (though this latter should be avoided if possible). In this
-case you need a statically allocated id.
-<p>
-
-You must ask for a user or group id from the base system maintainer,
-and must not release the package until you have been allocated one.
-Once you have been allocated one you must make the package depend
-on a version of the base system with the id present in
-<tt>/etc/passwd</tt> or <tt>/etc/group</tt>, or alternatively arrange
-for your package to create the user or group itself with the correct
-id (using <tt/adduser/) in its pre- or post-installation script (the
-latter is to be preferred if it is possible).
-<p>
-
-On the other hand, the program may able to determine the uid or gid
-from the group name at runtime, so that a dynamic id can be used. In
-this case you must choose an appropriate user or group name,
-discussing this on <prgn/debian-devel/ and checking with the base system
-maintainer that it is unique and that they do not wish you to use a
-statically allocated id instead. When this has been checked you must
-arrange for your package to create the user or group if necessary
-using <prgn/adduser/ in the pre- or post-installation script (again, the
-latter is to be preferred if it is possible).
-<p>
-
-Note that changing the numeric value of an id associated with a name
-is very difficult, and involves searching the filesystem for all
-appropriate files. You need to think carefully whether a static or
-dynamic id is required, since changing your mind later will cause
-problems.
-
-<chapt id="sourcepkg">Source package
-
-<sect>Documentation and the <tt/changelog/
-<p>
-
-Document your changes and updates to the source package properly in
-the <tt>debian/changelog</tt> file.
-<p>
-
-A copy of the file which will be installed in
-<tt>/usr/doc/copyright/<var/package/</tt> should be in
-<tt>debian/copyright</tt>.
-<p>
-
-In non-experimental packages you may only use a format for
-<tt>debian/changelog</> which is supported by the most recent released
-version of <prgn/dpkg/. If your format is not supported and there is
-general support for it you should contact the <prgn/dpkg/ maintainer
-to have the parser script for your format included in the <prgn/dpkg/
-package.<footnote>You will need to agree that the parser and its
-manpage may be distributed under the GNU GPL, just as the rest of
-<prgn/dpkg/ is.</footnote>
-
-<sect>Changes to the upstream sources
-<p>
-
-If you need to edit a <prgn/Makefile/ where GNU-style <prgn/configure/
-scripts are used, you should edit the <tt/.in/ files rather than
-editing the <prgn/Makefile/ directly. This allows the user to
-reconfigure the package if necessary. You should <em/not/ configure
-the package and edit the generated <prgn/Makefile/! This makes it
-impossible for someone else to later reconfigure the package.
-<p>
-
-If changes to the source code are made that are generally applicable
-please try to get them included in the upstream version of the package
-by supplying the upstream authors with the changes in whatever form
-they prefer.
-<p>
-
-If you need to configure the package differently for Debian or for
-Linux, and the upstream source doesn't provide a way to configure it
-the way you need to, please add such configuration facilities (for
-example, a new <prgn/autoconf/ test or <tt/#define/) and send the
-patch to the upstream authors, with the default set to the way they
-originally had it. You can then easily override the default in your
-<tt>debian/rules</tt> or wherever is appropriate.
-
-<sect>Error trapping in makefiles
-<p>
-
-When <prgn/make/ invokes a command in a makefile (including your
-package's upstream makefiles and the <tt>debian/rules</>) it does so
-using <tt/sh/. This means that <tt/sh/'s usual bad error handling
-properties apply: if you include a miniature script as one of the
-commands in your makefile you'll find that if you don't do anything
-about it then errors are not detected and <prgn/make/ will blithely
-continue after problems.
-<p>
-
-Every time you put more than one shell command (this includes using a
-loop) in a makefile command you <em/must/ make sure that errors are
-trapped. For simple compound commands, such as changing directory and
-then running a program, using <tt/&&/ rather than semicolon as
-a command separator is sufficient. For more complex commands
-including most loops and conditionals you must include a separate
-<tt/set -e/ command at the start of every makefile command that's
-actually one of these miniature shellscripts.
-
-<sect>Permissions
-<p>
-
-All the files in the source package should be world-readable and
-user-writeable. Directories and executable programs should be
-world-exectuable. None of the files should be world-writeable. The
-files may or may not be group-writeable, and directories may or may
-not be setgid. Pipes should not be world-readable and should be
-either both group readable and writeable or neither (and they should
-not be executable).
-<p>
-
-In summary: data files may be <tt/664/, <tt/644/. Executable files
-may be <tt/775/ or <tt/755/. Directories may be <tt/775/, <tt/755/,
-<tt/2775/ or <tt/2755/. Pipes may be <tt/660/ or <tt/600/.
-
-<chapt id="developer">How to become a Debian developer
-
-<sect>Before you start work
-<p>
-
-So, you've read all the documentation, you understand what everything
-in the <prgn/hello/ example package is for, and you're about to
-Debianise your favourite package. How do you actually become a Debian
-developer so that your work can be incorporated into the Project?
-<p>
-
-Firstly, subscribe to <prgn/debian-devel/ if you haven't already.
-Send the word <tt/subscribe/ in the <em/Subject/ of a mail to
-<email/debian-devel-REQUEST@lists.debian.org/. In case of problems
-contact the list administrator, Anders Chrigstrom <email/ac@netg.se/.
-<p>
-
-You should to subscribe and lurk for a bit before doing any coding,
-and you should post about your intentions to work on something to
-avoid duplicated effort.
-<p>
-
-If you do not have a PGP key yet generate one. You should probably
-read the PGP manual, as it has much important information which is
-critical to its security. Many more security failures are due to
-human error than to software failure or high-powered spy techniques.
-
-<sect>When you have a package to upload
-<p>
-
-When you have your package ready to be uploaded you must send a
-message to the project leader, Bruce Perens <email/bruce@pixar.com/,
-the administrator of <tt/master.debian.org/, Simon Shapiro
-<email/shimon@i-connect.net/, the mailing list administrator, Anders
-Chrigstrom <email/ac@netg.se/ and the <prgn/dpkg/ maintainer, Ian
-Jackson <email/ijackson@gnu.ai.mit.edu/.
-<p>
-
-The message should say what you've done and who you are, and should
-ask for an account on <prgn/master/ and to be subscribed to
-<prgn/debian-private/ (the developers-only mailing list). It should
-contain your PGP key (extracted using <tt/pgp -kxa/) for the database
-of keys which is shipped with <prgn/dpkg/.
-
-When you have your personal account on <prgn/master/ log in and
-transfer the files to
-<tt>/home/Debian/ftp/private/project/Incoming</>. You cannot upload
-to <prgn/Incoming/ on <prgn/master/ using anonymous FTP.
-<p>
-
-You can also upload files to <prgn/Incoming/ via a <prgn/cron/-driven
-upload queue in Europe on <ftpsite/chiark.chu.cam.ac.uk/. For details
-connect to <prgn/chiark/ using anonymous FTP and read
-<ftppath>/pub/debian/private/project/README.how-to-upload</ftppath>.
-
-<sect id="changesfiles">Upload handling - <tt/.changes/ files
-<p>
-
-When a package is uploaded to the Debian FTP archive, it must be
-accompanied by a <tt/.changes/ file which gives directions for its
-handling. This is usually generated by <prgn/dpkg-genchanges/.
-<p>
-
-This file is a control file with the following fields:
-<list compact>
-<item><tt/Format/
-<item><tt/Date/
-<item><tt/Source/
-<item><tt/Binary/
-<item><tt/Architecture/
-<item><tt/Version/
-<item><tt/Distribution/
-<item><tt/Urgency/
-<item><tt/Maintainer/
-<item><tt/Description/
-<item><tt/Changes/
-<item><tt/Files/
-</list>
-<p>
-
-All of them are mandatory for a Debian upload. See the list of
-control fields in the <prgn/dpkg/ programmers' manual for the contents
-of these fields.
-
-
-<chapt id="mailinglists">The Debian mailing lists
-<p>
-
-The mailing list server is at <tt/lists.debian.org/. Mail
-<tt/debian-<var/foo/-REQUEST@lists.debian.org/<footnote>where
-<tt/debian-<var/foo// is the name of the list</footnote> with the word
-<tt/subscribe/ in the Subject to subscribe or <tt/unsubscribe/ to
-unsubscribe.
-<p>
-
-When replying to messages on the mailing list, please do not send a
-carbon copy (<tt/CC/ - this does not mean `courtesy copy') to the
-original poster. Anyone who posts to a mailing list should read it to
-see the responses.
-<p>
-
-As ever on the net, please trim down the quoting of articles you're
-replying to.
-
-</book>
projects / dpkg / commitdiff