X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=policy.sgml;h=5801b9015450cb1a707f64d3b425dc6494b719a4;hb=4d448b710fcdc52be791692c2d9ffb579cfb7d8e;hp=39de67d9d54b084edb34f42730da814300908e1c;hpb=a3a649ad7268e5709cb3a84cd37c7adeba71cf35;p=debian%2Fdebian-policy.git diff --git a/policy.sgml b/policy.sgml index 39de67d..5801b90 100644 --- a/policy.sgml +++ b/policy.sgml @@ -764,10 +764,7 @@ These packages provide a reasonably small but not too limited character-mode system. This is what will be installed 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.

+ else. It doesn't include many large applications.

optional @@ -1116,7 +1113,7 @@ file in their control archive. The config script might be run before the preinst script, and before the package is unpacked or any of its - dependancies or pre-dependancies are satisfied. + dependencies or pre-dependancies are satisfied. Therefore it must work using only the tools present in essential packages.

@@ -1906,63 +1903,64 @@ Package: libc6

The required and optional targets are as follows: - build + build, build-arch (optional), + build-indep (optional)

- This should perform all non-interactive configuration - and compilation of the package. If a package has an - interactive pre-build configuration routine, the - Debianized source package must either be built after - this has taken place (so that the binary package can - be built without rerunning the configuration) or the - configuration routine modified to become - non-interactive. (The latter is preferable if there - are architecture-specific features detected by the - configuration routine.) + The build target should perform all + non-interactive configuration and compilation of the + package. If a package has an interactive pre-build + configuration routine, the Debianized source package + must either be built after this has taken place (so + that the binary package can be built without rerunning + the configuration) or the configuration routine + modified to become non-interactive. (The latter is + preferable if there are architecture-specific features + detected by the configuration routine.)

For some packages, notably ones where the same source tree is compiled in different ways to produce - two binary packages, the build target + two binary packages, the build target does not make much sense. For these packages it is good enough to provide two (or more) targets (build-a and build-b or whatever) for each of the ways of building the package, and a - build target that does nothing. The - binary target will have to build the + build target that does nothing. The + binary target will have to build the package in each of the possible ways and make the binary package out of each.

- The build target must not do anything + The build target must not do anything that might require root privilege.

- The build target may need to run the - clean target first - see below. + The build target may need to run the + clean target first - see below.

When a package has a configuration and build routine which takes a long time, or when the makefiles are - poorly designed, or when build needs to - run clean first, it is a good idea to + poorly designed, or when build needs to + run clean first, it is a good idea to touch build when the build process is complete. This will ensure that if debian/rules build is run again it will not rebuild the whole program.

- Another common way to do this is for build + Another common way to do this is for build to depend on build-stamp and to do nothing else, and for the build-stamp target to do the building and to touch build-stamp on completion. This is especially useful if the build routine creates a file or directory called build; in such a - case, build will need to be listed as + case, build will need to be listed as a phony target (i.e., as a dependency of the .PHONY target). See the documentation of make for more information on phony @@ -1977,37 +1975,35 @@ Package: libc6

- The binary target must be all that is + The binary target must be all that is necessary for the user to build the binary package(s) produced from this source package. All of these targets are required to be non-interactive. It is split into two parts: binary-arch builds the binary packages which are specific to a particular - architecture, and binary-indep builds + architecture, and binary-indep builds those which are not.

-

- binary may be (and commonly is) a target - with no commands which simply depends on - binary-arch and - binary-indep. + binary may be (and commonly is) a target with + no commands which simply depends on + binary-arch and binary-indep.

-

- Each binary-* target should depend on - the build target, above, so that the - package is built if it has not been already. It - should then create the relevant binary package(s), - using dpkg-gencontrol to make their - control files and dpkg-deb to build - them and place them in the parent of the top level - directory. + Both binary-* targets should depend on the + build target, or on the appropriate + build-arch or build-indep target, if + provided, so that the package is built if it has not + been already. It should then create the relevant + binary package(s), using dpkg-gencontrol to + make their control files and dpkg-deb to + build them and place them in the parent of the top + level directory.

- Both the binary-arch and - binary-indep targets must exist. + Both the binary-arch and + binary-indep targets must exist. If one of them has nothing to do (which will always be the case if the source generates only a single binary package, whether architecture-dependent or not), it @@ -2015,7 +2011,7 @@ Package: libc6

- The binary targets must be invoked as + The binary targets must be invoked as root.

The fakeroot package often allows one @@ -2029,29 +2025,29 @@ Package: libc6 clean

- This must undo any effects that the build - and binary targets may have had, except + This must undo any effects that the build + and binary targets may have had, except that it should leave alone any output files created in - the parent directory by a run of a binary + the parent directory by a run of a binary target. This target must be non-interactive.

- If a build file is touched at the end of - the build target, as suggested above, it + If a build file is touched at the end of + the build target, as suggested above, it should be removed as the first action that - clean performs, so that running - build again after an interrupted - clean doesn't think that everything is + clean performs, so that running + build again after an interrupted + clean doesn't think that everything is already done.

- The clean target may need to be - invoked as root if binary has been - invoked since the last clean, or if - build has been invoked as root (since - build may create directories, for + The clean target may need to be + invoked as root if binary has been + invoked since the last clean, or if + build has been invoked as root (since + build may create directories, for example).

@@ -2081,8 +2077,8 @@ Package: libc6

- The build, binary and - clean targets must be invoked with the current + The build, binary and + clean targets must be invoked with the current directory being the package's top-level directory.

@@ -2166,12 +2162,20 @@ Package: libc6 That format is a series of entries like this: package (version) distribution(s); urgency=urgency - + +

[optional blank line(s), stripped]

+ * change details more change details + +

[blank line(s), included in output of dpkg-parsechangelog]

+ * even more change details - - -- maintainer name <email address> date + +

[optional blank line(s), stripped]

+ + -- maintainer name <email + address>[two spaces] date

@@ -2197,12 +2201,12 @@ Package: libc6 currently only one useful keyword, urgency).

- Usual urgency values are low, medium, - high and critical. They have an - effect on how quickly a package will be considered for - inclusion into the testing distribution, and - give an indication of the importance of any fixes - included in this upload. + Recognised urgency values are low, + medium, high and emergency. + They have an effect on how quickly a package will be + considered for inclusion into the testing + distribution, and give an indication of the importance + of any fixes included in this upload.

@@ -2297,7 +2301,7 @@ Package: libc6

The debian/substvars file is usually generated and modified dynamically by debian/rules targets; in - this case it must be removed by the clean + this case it must be removed by the clean target.

@@ -2330,9 +2334,9 @@ Package: libc6 occurs

) should be removed by the - clean target. It may also be wise to + clean target. It may also be wise to ensure a fresh start by emptying or removing it at the - start of the binary target. + start of the binary target.

@@ -2341,7 +2345,7 @@ Package: libc6 .deb file that will be created when dpkg-deb --build is run for that binary package. So for most packages all that needs to be done with this file is to - delete it in the clean target. + delete it in the clean target.

@@ -3753,8 +3757,8 @@ Replaces: mail-transport-agent

In the past, the shared libraries linked to were determined by calling ldd, but now - objdump to do this. The only change this - makes to package building is that + objdump is used to do this. The only + change this makes to package building is that dpkg-shlibdeps must also be run on shared libraries, whereas in the past this was unnecessary. The rest of this footnote explains the advantage that @@ -3769,7 +3773,7 @@ Replaces: mail-transport-agent libraries that are needed by libbar are linked indirectly to foo, and the dynamic linker will load them automatically when it loads - libbar. A package should needs to depend on + libbar. A package should depend on the libraries it directly uses, and the dependencies for those libraries should automatically pull in the other libraries. @@ -3957,7 +3961,7 @@ dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/sbin/* \

Each shlibs file has the same format. Lines - beginning with # are considered to be commments and + beginning with # are considered to be comments and are ignored. Each line is of the form: library-name soname-version-number dependencies ... @@ -4134,15 +4138,20 @@ libbar 1 bar1 (>= 1.0-1)

The location of all installed files and directories must comply with the Filesystem Hierarchy Standard (FHS), - version 2.1. This can be found in the - debian-policy package or on alongside this manual or on . + version 2.1, except where doing so would violate other + terms of Debian Policy. The version of this document + referred here can be found in the debian-policy + package or on + alongside this manual. The + latest version, which may be a more recent version, may + be found on + . Specific questions about following the standard may be asked on the debian-devel mailing list, or - referred to Daniel Quinlan, the FHS coordinator, at - quinlan@pathname.com. + referred to the FHS mailing list (see the + for + more information).

@@ -4544,16 +4553,18 @@ rmdir /usr/local/share/emacs 2>/dev/null || true successfully.

- The /etc/init.d scripts should be treated as - configuration files, either by marking them as - conffiles or managing them correctly in the - maintainer scripts (see ). This is - important since we want to give the local system - administrator the chance to adapt the scripts to the local - system, e.g., to disable a service without de-installing - the package, or to specify some special command line - options when starting a service, while making sure her - changes aren't lost during the next package upgrade. + The /etc/init.d scripts must be treated as + configuration files, either (if they are present in the + package, that is, in the .deb file) by marking them as + conffiles, or, (if they do not exist in the .deb) + by managing them correctly in the maintainer scripts (see + ). This is important since we want + to give the local system administrator the chance to adapt + the scripts to the local system, e.g., to disable a + service without de-installing the package, or to specify + some special command line options when starting a service, + while making sure her changes aren't lost during the next + package upgrade.

@@ -4580,18 +4591,18 @@ test -f program-executed-later-in-script || exit 0 change. As the scripts themselves are frequently conffiles, modifying them requires that the administrator merge in their changes each time the package - is upgraded and the conffile changes. To ease + is upgraded and the conffile changes. To ease the burden on the system administrator, such configurable values should not be placed directly in the script. Instead, they should be placed in a file in - /etc/default, which typically will have thesame + /etc/default, which typically will have the same base name as the init.d script. This extra file should be sourced by the script when the script runs. It must contain only variable settings and comments in POSIX - sh format. It should not be a - conffile, but a configuration file maintained by - the package maintainer scripts. See - for more details. + sh format. It may either be a + conffile or a configuration file maintained by + the package maintainer scripts. See + for more details.

@@ -6023,7 +6034,7 @@ ln -fs ../sbin/sendmail debian/tmp/usr/bin/runq operate sensibly (dotfiles that they do not create themselves automatically, that is) are a bad thing. Furthermore, programs should be configured by the Debian - default installation as behave as closely to the upstream + default installation to behave as closely to the upstream default behaviour as possible.

@@ -6481,19 +6492,19 @@ http://localhost/cgi-bin/cgi-bin-name

HTML documents for a package are stored in - /usr/share/doc/package but should - be accessed via symlinks as - /usr/doc/package -

- for backward compatibility; see -

- + /usr/share/doc/package and can be referred to as http://localhost/doc/package/filename

+

+ The web server should restrict access to the document + tree so that only clients on the same host can read + the documents. If the web server does not support such + access controls, then it should not provide access at + all, or ask about providing access during installation. +

Web Document Root

@@ -7565,13 +7576,22 @@ fi now-deprecated Packaging Manual, version 3.2.1.0. They are the chapters which are likely to be of use to package maintainers and which have not already been included in the - policy document itself. They have not yet been checked to - ensure that they are compatible with the contents of policy, - and if there are any contradictions, the version in the main - policy document takes precedence. The remaining chapters of - the old Packaging Manual have also not been read in detail to - ensure that there are not parts which have been left out. - Both of these will be done in due course. + policy document itself. Most of these sections are very likely + not relevant to policy; they should be treated as + documentation for the packaging system. Please note that these + appendices are included for convenience, and for historical + reasons: they used to be part of policy package, and they have + not yet been incorporated into dpkg documentation. However, + they still have value, and hence they are presented here. +

+

+ They have not yet been checked to ensure that they are + compatible with the contents of policy, and if there are any + contradictions, the version in the main policy document takes + precedence. The remaining chapters of the old Packaging + Manual have also not been read in detail to ensure that there + are not parts which have been left out. Both of these will be + done in due course.

@@ -7747,7 +7767,7 @@ fi To view the copyright file for a package you could use this command: - dpkg --fsys-tarfile filename.deb | tar xof usr/doc/\*copyright | less + dpkg --fsys-tarfile filename.deb | tar xof usr/share/doc/\*copyright | less

@@ -8066,8 +8086,8 @@ fi

dpkg-buildpackage is a script which invokes dpkg-source, the debian/rules - targets clean, build and - binary, dpkg-genchanges and + targets clean, build and + binary, dpkg-genchanges and pgp to build a signed source and binary package upload.

@@ -8283,7 +8303,7 @@ fi

- It is usually invoked from the binary target of + It is usually invoked from the binary target of debian/rules: dpkg-distaddfile filename section priority @@ -8414,40 +8434,70 @@ fi built after this has taken place, so that it can be built without rerunning the configuration.

- + +

+ A package may also provide both of the targets + build-arch and build-indep. The + build-arch target, if provided, should + perform all non-interactive configuration and + compilation required for producing all + architecture-dependant binary packages (those packages + for which the body of the Architecture field + in debian/control is not all). + Similarly, the build-indep target, if + provided, should perform all non-interactive + configuration and compilation required for producing + all architecture-independent binary packages (those + packages for which the body of the + Architecture field in debian/control + is all). The build target should + depend on those of the targets build-arch and + build-indep that are provided in the rules + file. +

+

+ If one or both of the targets build-arch and + build-indep are not provided, then invoking + debian/rules with one of the not-provided + targets as arguments should produce a exit status code + of 2. Usually this is provided automatically by make + if the target is missing. +

+ +

For some packages, notably ones where the same source tree is compiled in different ways to produce - two binary packages, the build target - does not make much sense. For these packages it is - good enough to provide two (or more) targets + two binary packages, the build target does + not make much sense. For these packages it is good + enough to provide two (or more) targets (build-a and build-b or whatever) for each of the ways of building the package, and a - build target that does nothing. The - binary target will have to build the + build target that does nothing. The + binary target will have to build the package in each of the possible ways and make the binary package out of each.

- The build target must not do anything - that might require root privilege. + The targets build, build-arch + and build-indep target must not do + anything that might require root privilege.

- The build target may need to run - clean first - see below. + The build target may need to run + clean first - see below.

-

- When a package has a configuration routine that - takes a long time, or when the makefiles are poorly - designed, or when build needs to run - clean first, it is a good idea to - touch build when the build process is - complete. This will ensure that if debian/rules - build is run again it will not rebuild the - whole program. +

+ When a package has a configuration routine that takes + a long time, or when the makefiles are poorly + designed, or when build needs to run + clean first, it is a good idea to touch + build when the build process is complete. This + will ensure that if debian/rules build is run + again it will not rebuild the whole program.

@@ -8456,18 +8506,18 @@ fi

- The binary target should be all that is + The binary target should be all that is necessary for the user to build the binary package. All these targets are required to be non-interactive. It is split into two parts: - binary-arch builds the packages' output + binary-arch builds the packages' output files which are specific to a particular - architecture, and binary-indep builds + architecture, and binary-indep builds those which are not.

- binary should usually be a target with + binary should usually be a target with no commands which simply depends on binary-arch and binary-indep. @@ -8475,7 +8525,7 @@ fi

Both binary-* targets should depend on - the build target, above, so that the + the build target, above, so that the package is built if it has not been already. It should then create the relevant binary package(s), using dpkg-gencontrol to make their @@ -8499,7 +8549,7 @@ fi

- The binary targets must be invoked as + The binary targets must be invoked as root.

@@ -8509,29 +8559,29 @@ fi

This should undo any effects that the - build and binary targets + build and binary targets may have had, except that it should leave alone any output files created in the parent directory by a - run of binary. This target is required + run of binary. This target is required to be non-interactive.

- If a build file is touched at the end - of the build target, as suggested + If a build file is touched at the end + of the build target, as suggested above, it must be removed as the first thing that - clean does, so that running - build again after an interrupted - clean doesn't think that everything is + clean does, so that running + build again after an interrupted + clean doesn't think that everything is already done.

- The clean target must be invoked as - root if binary has been invoked since - the last clean, or if - build has been invoked as root (since - build may create directories, for + The clean target must be invoked as + root if binary has been invoked since + the last clean, or if + build has been invoked as root (since + build may create directories, for example).

@@ -8562,8 +8612,8 @@ fi

- The build, binary and - clean targets must be invoked with a current + The build, binary and + clean targets must be invoked with a current directory of the package's top-level directory.

@@ -9016,7 +9066,7 @@ fi

The is usually generated and modified dynamically by debian/rules targets; in this case it must be - removed by the clean target. + removed by the clean target.

@@ -9049,9 +9099,9 @@ fi occurs

) should be removed by the - clean target. It may also be wise to + clean target. It may also be wise to ensure a fresh start by emptying or removing it at the - start of the binary target. + start of the binary target.

@@ -9059,7 +9109,7 @@ fi for the .deb file that will be created by dpkg-deb from the control file that it generates, so for most packages all that needs to be done - with this file is to delete it in clean. + with this file is to delete it in clean.

@@ -9076,7 +9126,7 @@ fi

This is the canonical temporary location for the - construction of binary packages by the binary + construction of binary packages by the binary target. The directory tmp serves as the root of the filesystem tree as it is being constructed (for example, by using the package's upstream makefiles install @@ -9094,8 +9144,8 @@ fi

Whatever tmp directories are created and used by - binary must of course be removed by the - clean target.

+ binary must of course be removed by the + clean target.