From: Manoj Srivastava Date: Thu, 16 Jun 2005 05:11:31 +0000 (+0000) Subject: * Improvements to sections 5.1 and 5.2. X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=70d2593679ad50867a3c1f270ae2a7967422e874;p=debian%2Fdebian-policy.git * Improvements to sections 5.1 and 5.2. Author: jdg Date: 2001/04/18 16:15:14 * Improvements to sections 5.1 and 5.2. * Added a couple of cosmetic phony targets to debian/rules git-archimport-id: srivasta@debian.org--etch/debian-policy--devel--3.0--patch-98 --- diff --git a/debian/rules b/debian/rules index 52161c9..e02d2e9 100755 --- a/debian/rules +++ b/debian/rules @@ -202,7 +202,7 @@ endef source diff: @echo >&2 'source and diff are obsolete - use dpkg-source -b'; false -.PHONY: binary binary-arch binary-indep clean checkroot +.PHONY: configure build binary binary-arch binary-indep clean checkroot #Local variables: #mode: makefile diff --git a/policy.sgml b/policy.sgml index b964aac..c8537a4 100644 --- a/policy.sgml +++ b/policy.sgml @@ -1869,10 +1869,9 @@ Time Stamps

- Maintainers are encouraged to preserve the modification - times of the upstream source files in a package, as far as - is reasonably possible. Even though this is optional, this - is still a good idea. + Maintainers should preserve the modification times of the + upstream source files in a package, as far as is reasonably + possible.

The rationale is that there is some information conveyed @@ -1887,12 +1886,12 @@ debian/rules - the - main building script + main building script

This file must be an executable makefile, and contains the package-specific recipes for compiling the package and - building binary package(s) out of the source. + building binary package(s) from the source.

@@ -1905,7 +1904,7 @@ Since an interactive debian/rules script makes it impossible to auto-compile that package and also makes it hard for other people to reproduce the same binary - package, all required targets MUST be + package, all required targets MUST be non-interactive. At a minimum, required targets are the ones called by dpkg-buildpackage, namely, clean, binary, binary-arch, @@ -1915,17 +1914,21 @@

- The targets which must be present are: + The required and optional targets are as follows: build

- This should perform all non-interactive - configuration and compilation of the package. If a - package has an interactive pre-build configuration - routine, the Debianised source package should be - built after this has taken place, so that it can be - built without rerunning the configuration. + 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.)

@@ -1948,19 +1951,35 @@

- The build target may need to run - clean first - see below. + The build target may need to run the + clean target 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 + 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 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. + build is run again it will not rebuild the whole + program. + +

+ 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 + a phony target (i.e., as a dependency of the + .PHONY target). See the documentation of + make for more information on phony + targets. +

+

@@ -1970,11 +1989,11 @@

The binary target must 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 - files which are specific to a particular + 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 those which are not.

@@ -1987,7 +2006,7 @@

- Both binary-* targets should depend on + 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), @@ -1998,17 +2017,24 @@

- If one of the binary-* targets has - nothing to do (this will be always be the case if - the source generates only a single binary package, - whether architecture-dependent or not) it - must still exist, and must always - succeed. + 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 + must still exist and must always succeed.

The binary targets must be invoked as root. + +

+ The fakeroot package often allows one + to build a package correctly even without being + root. +

+

@@ -2016,19 +2042,18 @@

- 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 binary. This target must be - non-interactive. + 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 + target. This target must be non-interactive.

- If a build file is touched at the end - of the build target, as suggested - above, it should be removed as the first thing that - clean does, so that running + 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 already done. @@ -2071,8 +2096,8 @@

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

@@ -2083,11 +2108,14 @@

- The architecture we build on and build for is determined by - make variables via dpkg-architecture. You can get the Debian - architecture and the GNU style architecture specification - string for the build machine as well as the host - machine. Here is a list of supported make variables: + The architectures we build on and build for are determined + by make variables using + dpkg-architecture. You can determine the + Debian architecture and the GNU style architecture + specification string for the build machine (the machine type + we are building on) as well as for the host machine (the + machine type we are building for). Here is a list of + supported make variables:

DEB_*_ARCH (the Debian architecture)

@@ -2097,25 +2125,23 @@ specification string)

 -

DEB_*_GNU_CPU (the CPU part of DEB_*_GNU_TYPE)

+

DEB_*_GNU_CPU (the CPU part of + DEB_*_GNU_TYPE)

DEB_*_GNU_SYSTEM (the System part of - DEB_*_GNU_TYPE)

+ DEB_*_GNU_TYPE)

-

- -

where * is either BUILD for specification of - the build machine or HOST for specification of the machine - we build for. + the build machine or HOST for specification of the + host machine.

Backward compatibility can be provided in the rules file by setting the needed variables to suitable default - values, please refer to the documentation of - dpkg-architecture for details. + values; please refer to the documentation of + dpkg-architecture for details.