From: Russ Allbery Date: Sun, 16 Mar 2008 20:43:55 +0000 (+0000) Subject: Add parallel=n and move DEB_BUILD_OPTS section X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=3b477c0255a9eb221a3b4a755059bd94a9eed579;p=debian%2Fdebian-policy.git Add parallel=n and move DEB_BUILD_OPTS section Add the build option parallel=n, requesting a parallel build. Standardize the format of DEB_BUILD_OPTIONS, require tags be whitespace-separated, allow packages to assume non-conflicting tags, and require unknown flags be ignored. Move the section documenting DEB_BUILD_OPTS under the debian/rules section and away from the binaries section, leaving a cross-reference behind. Thanks to Loïc Minier, Peter Samuelson, Robert Millan, and Guillem Jover for wording suggestions. git-archimport-id: rra@debian.org--lenny/debian-policy--devel--3.7--patch-40 --- diff --git a/debian/changelog b/debian/changelog index ac674e9..1b90563 100644 --- a/debian/changelog +++ b/debian/changelog @@ -2,6 +2,12 @@ debian-policy (3.7.4.0) unstable; urgency=low * Bug fix: "[AMENDMENT 11/02/2008] Manual page encoding", thanks to Colin Watson (Closes: #440420). + * Bug fix: "[PROPOSAL] common interface for parallel building in + DEB_BUILD_OPTIONS", thanks to Loïc Minier, Peter Samuelson, and Robert + Millan (Closes: #209008). + * Bug fix: "Please clarify splitting/syntax of DEB_BUILD_OPTIONS", thanks to + Loïc Minier, Peter Samuelson, Robert Millan, and Guillem Jover + (Closes: #430649). * Bug fix: "Documentation for Breaks in dpkg", thanks to Ian Jackson (Closes: #379150). * Bug fix: "support for wrapped Uploaders should now be mandatory" diff --git a/policy.sgml b/policy.sgml index c8087f3..888de5a 100644 --- a/policy.sgml +++ b/policy.sgml @@ -1986,6 +1986,105 @@ or system information; the GNU style variables should be used for that.

+ + + debian/rules and + DEB_BUILD_OPTIONS + +

+ Supporting the standardized environment variable + DEB_BUILD_OPTIONS is recommended. This variable can + contain several flags to change how a package is compiled and + built. Each flag must be in the form flag or + flag=options. If multiple flags are + given, they must be separated by whitespace. + Some packages support any delimiter, but whitespace is the + easiest to parse inside a makefile and avoids ambiguity with + flag values that contain commas. + + flag must start with a lowercase letter + (a-z) and consist only of lowercase letters, + numbers (0-9), and the characters + - and _ (hyphen and underscore). + options must not contain whitespace. The same + tag should not be given multiple times with conflicting + values. Package maintainers may assume that + DEB_BUILD_OPTIONS will not contain conflicting tags. +

+ +

+ The meaning of the following tags has been standardized: + + noopt + + The presence of this tag means that the package should + be compiled with a minimum of optimization. For C + programs, it is best to add -O0 to + CFLAGS (although this is usually the default). + Some programs might fail to build or run at this level + of optimization; it may be necessary to use + -O1, for example. + + nostrip + + This tag means that the debugging symbols should not be + stripped from the binary during installation, so that + debugging information may be included in the package. + + parallel=n + + This tag means that the package should be built using up + to n parallel processes if the package build + system supports this. + Packages built with make can often implement + this by passing the -jn option to + make. + + If the package build system does not support parallel + builds, this string must be ignored. If the package + build system only supports a lower level of concurrency + than n, the package should be built using as + many parallel processes as the package build system + supports. It is up to the package maintainer to decide + whether the package build times are long enough and the + package build system is robust enough to make supporting + parallel builds worthwhile. + + +

+ +

+ Unknown flags must be ignored by debian/rules. +

+ +

+ The following makefile snippet is an example of how one may + implement the build options; you will probably have to + massage this example in order to make it work for your + package. + +CFLAGS = -Wall -g +INSTALL = install +INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644 +INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755 +INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755 +INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755 + +ifneq (,$(filter noopt,$(DEB_BUILD_OPTIONS))) + CFLAGS += -O0 +else + CFLAGS += -O2 +endif +ifeq (,$(filter nostrip,$(DEB_BUILD_OPTIONS))) + INSTALL_PROGRAM += -s +endif +ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS))) + NUMJOBS = $(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS))) + MAKEFLAGS += -j$(NUMJOBS) +endif + +

+ @@ -6597,58 +6696,12 @@ INSTALL = install -s # (or use strip on the files in debian/tmp)

Although binaries in the build tree should be compiled with - debugging information by default, it can often be difficult - to debug programs if they are also subjected to compiler - optimization. For this reason, it is recommended to support - the standardized environment - variable DEB_BUILD_OPTIONS. This variable can - contain several flags to change how a package is compiled - and built. -

- -

- - noopt - - The presence of this string means that the package - should be compiled with a minimum of optimization. - For C programs, it is best to add -O0 - to CFLAGS (although this is usually the - default). Some programs might fail to build or run at - this level of optimization; it may be necessary to - use -O1, for example. - - nostrip - - This string means that the debugging symbols should - not be stripped from the binary during installation, - so that debugging information may be included in the package. - - -

- -

- The following makefile snippet is an example of how one may - implement the build options; you will probably have to - massage this example in order to make it work for your - package. - -CFLAGS = -Wall -g -INSTALL = install -INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644 -INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755 -INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755 -INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755 - -ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS))) -CFLAGS += -O0 -else -CFLAGS += -O2 -endif -ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS))) -INSTALL_PROGRAM += -s -endif - + debugging information by default, it can often be difficult to + debug programs if they are also subjected to compiler + optimization. For this reason, it is recommended to support the + standardized environment variable DEB_BUILD_OPTIONS + (see ). This variable can contain + several flags to change how a package is compiled and built.

diff --git a/upgrading-checklist.html b/upgrading-checklist.html index 5cd0b10..e344403 100644 --- a/upgrading-checklist.html +++ b/upgrading-checklist.html @@ -58,6 +58,13 @@ picking your way through this list. * The base section has been removed. contrib and non-free have been removed from the section list; they are only categories. The base system is now defined by priority. [2.4, 3.7] + * Standardized the format of DEB_BUILD_OPTIONS. Specified permitted + characters for tags, required that tags be whitespace-separated, + allowed packages to assume non-conflicting tags, and required + unknown flags be ignored. [4.9.1, 10.1] + * Added parallel=n to the standardized DEB_BUILD_OPTIONS tags, + indicating that a package should be built using up to n parallel + processes if the package supports it [4.9.1] * Debian packages should not use convience copies of code from other packages unless the included package is explicitly intended to be used that way. [4.13]