Bug#430649: New proposed wording for DEB_BUILD_OPTIONS
Okay, here's a revised proposal to address both Bug#209008 (parallel) and
Bug#430649 (DEB_BUILD_OPTIONS parsing). This proposal does the following:
* Standardizes on space as the separator for DEB_BUILD_OPTIONS. This
only affects what people can pass into debian/rules, not any existing
packages. I think all existing packages use parsing methods that would
work with either, and that's what Policy has previously recommended. I
think the argument that we may want to pass values including commas to
an option is persuasive.
* Adds parallel=n with wording tweaks based on subsequent discussion,
including handling the case where the build system supports some
concurrency but not as much as was requested. Do people still feel
that we need to explicitly say that, in the absence of this option,
packages should be built one process at a time? Note that supporting
DEB_BUILD_OPTS at all is only recommended.
* Moves the whole section about DEB_BUILD_OPTS to a sub-section of the
section on debian/rules and out of the section on binaries, leaving a
pointer behind. There are flags that do things other than affect the
content of binaries, and I think this is a more intuitive place to look
for it.
I left the MAKEFLAGS bit in the example for parallel since that example
clearly says that it's only an example and will need modification for the
needs of a specific package. The way INSTALL is handled in the example
that was already there similarliy won't work for all upstream build
systems.
Comments? Seconds?
--- orig/policy.sgml
+++ mod/policy.sgml
@@ -1987,6 +1987,104 @@
or system information; the GNU style variables should be
used for that.
</p>
+
+ <sect id="debianrules-options">
+ <heading><file>debian/rules</file> and
+ <tt>DEB_BUILD_OPTIONS</tt></heading>
+
+ <p>
+ Supporting the standardized environment variable
+ <tt>DEB_BUILD_OPTIONS</tt> is recommended. This variable can
+ contain several flags to change how a package is compiled and
+ built. Each flag must be in the form <var>flag</var> or
+ <var>flag</var>=<var>options</var>. If multiple flags are
+ given, they must be separated by whitespace.<footnote>
+ Some packages support any delimiter, but whitespace is the
+ easiest to parse inside a makefile and avoids ambiguity with
+ flag values that contain commas.
+ </footnote>
+ <var>flag</var> must consist only of lowercase letters
+ (<tt>a-z</tt>), numbers (<tt>0-9</tt>), and the characters
+ <tt>-</tt> and <tt>_</tt> (hyphen and underscore).
+ <var>options</var> must not contain whitespace. The same
+ tag should not be given multiple times with conflicting
+ values. Package maintainers may assume that
+ <tt>DEB_BUILD_OPTIONS</tt> will not contain conflicting tags.
+ </p>
+
+ <p>
+ The meaning of the following tags has been standardized:
+ <taglist>
+ <tag>noopt</tag>
+ <item>
+ 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 <tt>-O0</tt> to
+ <tt>CFLAGS</tt> (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
+ <tt>-O1</tt>, for example.
+ </item>
+ <tag>nostrip</tag>
+ <item>
+ 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.
+ </item>
+ <tag>parallel=n</tag>
+ <item>
+ This tag means that the package should be built using up
+ to <tt>n</tt> parallel processes if the package build
+ system supports this.<footnote>
+ Packages built with <tt>make</tt> can often implement
+ this by passing the <tt>-j</tt><var>n</var> option to
+ <tt>make</tt>.
+ </footnote>
+ 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 <var>n</var>, 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.
+ </item>
+ </taglist>
+ </p>
+
+ <p>
+ Unknown flags must be ignored by <file>debian/rules</file>.
+ </p>
+
+ <p>
+ 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.
+ <example compact="compact">
+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
+ </example>
+ </p>
+ </sect>
</sect>
<!-- FIXME: section pkg-srcsubstvars is the same as substvars -->
@@ -6439,58 +6537,12 @@
<p>
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 <tt>DEB_BUILD_OPTIONS</tt>. This variable can
- contain several flags to change how a package is compiled
- and built.
- </p>
-
- <p>
- <taglist>
- <tag>noopt</tag>
- <item>
- 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 <tt>-O0</tt>
- to <tt>CFLAGS</tt> (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 <tt>-O1</tt>, for example.
- </item>
- <tag>nostrip</tag>
- <item>
- 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.
- </item>
- </taglist>
- </p>
-
- <p>
- 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.
- <example compact="compact">
-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
- </example>
+ 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 <tt>DEB_BUILD_OPTIONS</tt>
+ (see <ref id="debianrules-options">). This variable can contain
+ several flags to change how a package is compiled and built.
</p>
<p>
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: