Merging upstream version 1.22.5.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 62 insertions, 10 deletions

diff --git a/man/dpkg-buildflags.pod b/man/dpkg-buildflags.pod
index 6673a65..7b31238 100644
--- a/man/dpkg-buildflags.pod
+++ b/man/dpkg-buildflags.pod
@@ -239,10 +239,8 @@ Print the features enabled for a given area (since dpkg 1.16.2).
 If the feature is handled (even if only on some architectures) as a
 builtin default by the compiler, then a B<Builtin> field is printed
 (since dpkg 1.21.14).
-The only currently recognized
-areas on Debian and derivatives are B<future>, B<qa>, B<reproducible>,
-B<sanitize> and B<hardening>, see the B<FEATURE AREAS>
-section for more details.
+See the L</FEATURE AREAS> section for more details about the currently
+recognized areas.
 Exits with 0 if the area is known otherwise exits with 1.
 
 The output is in RFC822 format, with one section per feature.
@@ -401,20 +399,51 @@ to support other languages).
 
 =head1 FEATURE AREAS
 
+Feature areas are currently vendor specific,
+and the ones described below are only recognized on Debian and derivatives.
+
 Each area feature can be enabled and disabled in the B<DEB_BUILD_OPTIONS>
 and B<DEB_BUILD_MAINT_OPTIONS> environment variable's area value with the
 ‘B<+>’ and ‘B<->’ modifier.
+Following the general syntax of these variables
+(described in L<dpkg-buildpackage(1)>),
+multiple feature areas can be specified separated by spaces,
+where each get feature specifiers as mandatory parameters after an
+equal sign (‘B<=>’).
+The feature specifiers are comma-separated and parsed from left to right,
+where the settings within the same feature specifier override previous ones,
+even if the feature specifiers are split across multiple space-separated
+feature area settings for the same area.
+
 For example, to enable the B<hardening> “pie” feature and disable the
 “fortify” feature you can do this in B<debian/rules>:
 
-    export DEB_BUILD_MAINT_OPTIONS=hardening=+pie,-fortify
+    export DEB_BUILD_MAINT_OPTIONS = hardening=+pie,-fortify
 
 The special feature B<all> (valid in any area) can be used to enable or
 disable all area features at the same time.
 Thus disabling everything in the B<hardening> area and enabling only
 “format” and “fortify” can be achieved with:
 
-    export DEB_BUILD_MAINT_OPTIONS=hardening=-all,+format,+fortify
+    export DEB_BUILD_MAINT_OPTIONS = hardening=-all,+format,+fortify
+
+Multiple feature areas can be set:
+
+    export DEB_BUILD_MAINT_OPTIONS = hardening=+pie abi=+lfs
+
+The override behavior applies as much to the B<all> special feature,
+as to specific features,
+which should allow for composition.
+Thus to enable “lfs” in the B<abi> area, and only “pie” and “fortify”
+in the B<hardening> area, but “format” only when CONDITION is defined,
+this could be done with:
+
+    export DEB_BUILD_MAINT_OPTIONS = hardening=-all,+pie,+format abi=+lfs
+    …
+    DEB_BUILD_MAINT_OPTIONS += hardening=+fortify
+    ifdef CONDITION
+    DEB_BUILD_MAINT_OPTIONS += hardening=-format
+    endif
 
 =head2 abi
 
@@ -436,10 +465,33 @@ feature in the B<future> feature area.
 
 =item B<time64>
 
-This setting (since dpkg 1.22.0; disabled by default) enables 64-bit time_t
-support on 32-bit architectures where their ABI does not include it by
-default, by adding B<-D_TIME_BITS=64> to B<CPPFLAGS>.
-This setting automatically enables the B<lfs> feature as it requires it.
+This setting (since dpkg 1.22.0; enabled by default except for i386,
+hurd-i386 and kfreebsd-i386 since dpkg 1.22.5) enables 64-bit time_t support
+on 32-bit architectures where their ABI does not include it by default,
+by adding B<-D_TIME_BITS=64> to B<CPPFLAGS>.
+This setting automatically enables the B<lfs> feature from the B<abi>
+feature area,
+and the B<bug-implicit-func> feature from the B<qa> feature area
+as it requires them.
+
+If the setting is enabled explicitly then it gets enabled on all
+architectures including i386 but not hurd-i386 nor kfreebsd-i386
+(where the kernel does not have time64 interfaces),
+ignoring the binary backwards compatibility default.
+
+It is also enabled by default by gcc on the
+armel,
+armhf,
+hppa,
+m68k,
+mips,
+mipsel,
+powerpc
+and
+sh4
+Debian architectures,
+where disabling the feature will add instead
+B<-U_LARGEFILE_SOURCE -U_FILE_OFFSET_BITS -U_TIME_BITS> to B<CPPFLAGS>.
 
 =back