From: Ian Jackson Date: Sun, 11 Aug 1996 12:25:44 +0000 (+0100) Subject: dpkg (1.3.4) experimental; urgency=low X-Git-Url: https://err.no/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=152af05e53a8fd863575eea9c3ff733bb02694b1;p=dpkg dpkg (1.3.4) experimental; urgency=low * Removed debugging output from dpkg-source -x. Oops. * Removed section on source package permissions from policy manual - dpkg-source now sorts these out. -- Ian Jackson Sun, 11 Aug 1996 13:25:44 +0100 --- diff --git a/debian/changelog b/debian/changelog index 547ebc47..e2ee9440 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,11 @@ +dpkg (1.3.4) experimental; urgency=low + + * Removed debugging output from dpkg-source -x. Oops. + * Removed section on source package permissions from policy manual - + dpkg-source now sorts these out. + + -- Ian Jackson Sun, 11 Aug 1996 13:25:44 +0100 + dpkg (1.3.3) experimental; urgency=low * Programmers' & policy manuals in source tree; HTML in /usr/doc/dpkg. diff --git a/doc/policy.sgml b/doc/policy.sgml index e15c9394..9517a326 100644 --- a/doc/policy.sgml +++ b/doc/policy.sgml @@ -1099,22 +1099,6 @@ including most loops and conditionals you must include a separate Permissions -

- -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). -

- -In summary: data files may be How to become a Debian developer Before you start work diff --git a/doc/policy.sgml.orig b/doc/policy.sgml.orig new file mode 100644 index 00000000..e15c9394 --- /dev/null +++ b/doc/policy.sgml.orig @@ -0,0 +1,1222 @@ + + + + + + +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> diff --git a/scripts/dpkg-source.pl b/scripts/dpkg-source.pl index ac729910..d96993c7 100644 --- a/scripts/dpkg-source.pl +++ b/scripts/dpkg-source.pl @@ -548,7 +548,6 @@ if ($opmode eq 'build') { &internerr("unknown object \`$fn' after extract (mode ". sprintf("0%o",$mode).")"); } -printf STDERR "mode %07o newmode %07o %s\n",$mode,$newmode,$fn; next if ($mode & 07777) == $newmode; chmod($newmode,$fn) || &syserr(sprintf("cannot change mode of \`%s' to 0%o from 0%o",