--- /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