Bug#1038888: dpkg-buildpackage(1): mention all supported flags for DEB_BUILD_OPTIONS

[Guillem Jover]

Hi!

On Thu, 2023-06-29 at 19:32:04 +0200, Sebastian Kayser wrote:
> even though it's not 100% of what I expected this LGTM. What would you think
> about retaining the link to the Debian Policy?

Yeah, as I mentioned that would be backwards, and while I can recognize
it might seem inconvenient, I'd rather not. Sorry.

Thanks,
Guillem

Bug#1038888: dpkg-buildpackage(1): mention all supported flags for DEB_BUILD_OPTIONS

[Sebastian Kayser]

Hi Guillem,

even though it's not 100% of what I expected this LGTM. What would you 
think about retaining the link to the Debian Policy?


Kind regards

Sebastian

Bug#1038888: dpkg-buildpackage(1): mention all supported flags for DEB_BUILD_OPTIONS

[Guillem Jover]

Hi!

On Thu, 2023-06-22 at 17:35:15 +0200, Sebastian Kayser wrote:
> Package: dpkg-dev
> Version: 1.21.22
> Severity: normal
> Tags: patch
> X-Debbugs-Cc: skay...@tutanota.com

> the man page for dpkg-buildpackage only includes a subset of supported flags
> for DEB_BUILD_OPTIONS and the description for the "nocheck" flags seems to
> be incorrect.

It is only supposed to include those supported or known by dpkg tools,
as the others are defined by distribution specific policies.

> The currently supported, full list of flags is available at 
> 
> https://www.debian.org/doc/debian-policy/ch-source.html#debian-rules-and-deb-build-options
> 
> I've attached an example patch to include the supported flags list in
> dpkg-buildpackage(1).

Thanks for the patch! Although in general this is backwards, the
Debian policy documents the dpkg behavior and not the other way
around. So perhaps something along the lines like the attachment
instead, while probably not what you were looking for, is something
that feels acceptable for inclusion.

Thanks,
Guillem
From dbbb968d8e92f816de9538653ee70d19b08a3681 Mon Sep 17 00:00:00 2001
From: Guillem Jover 
Date: Fri, 23 Jun 2023 01:53:02 +0200
Subject: [PATCH] man: Document known DEB_BUILD_OPTIONS options

Itemize the options for easier reading. Include all the options
supported by dpkg-buildpackage or the dpkg tooling, and mention
which of those debian/rules might act on too.

Closes: #103
---
 man/dpkg-buildpackage.pod | 44 ++-
 1 file changed, 39 insertions(+), 5 deletions(-)

diff --git a/man/dpkg-buildpackage.pod b/man/dpkg-buildpackage.pod
index 3da341992..a28892fe9 100644
--- a/man/dpkg-buildpackage.pod
+++ b/man/dpkg-buildpackage.pod
@@ -740,14 +740,48 @@ Overridden by the B<--sign-keyfile> option.
 
 =item B
 
-If set, it will contain a space-separated list of options that might
-affect the build process in I, and the behavior of some
-dpkg commands.
+If set, it will contain a space-separated list of options that affect
+the behavior of some dpkg commands, and might affect the build process
+in I if the code in there honors them.
 
-With B the B variable will be ignored.
-With BI the parallel jobs will be set to I,
+The following are the options known and supported by dpkg tools, other
+options honored by I might be defined by distribution
+specific policies.
+
+=over
+
+=item BI
+
+The parallel jobs will be set to I,
 overridden by the B<--jobs-try> option.
 
+=item B
+
+The B variable will be ignored in B.
+The I in the packaging is not expected to run test suites
+during the build.
+
+=item B
+
+If I calls B to set up the build flags,
+those will be set to not enable any optimizations.
+
+=item B
+
+The I in the packaging should ensure that objects are not
+stripped from their debugging information. If I includes
+the B make fragment the B make variable will
+respect this option.
+
+=item B
+
+The B<--no-print-directory> flags will be appended to the B
+environment variable.
+The I in the packaging should reduce verbosity, while not
+being completely quiet.
+
+=back
+
 =item B
 
 If set, it will be used as the active build profile(s) for the package
-- 
2.40.1

Bug#1038888: dpkg-buildpackage(1): mention all supported flags for DEB_BUILD_OPTIONS

[Sebastian Kayser]

Package: dpkg-dev
Version: 1.21.22
Severity: normal
Tags: patch
X-Debbugs-Cc: skay...@tutanota.com

Dear Maintainer,

the man page for dpkg-buildpackage only includes a subset of supported flags
for DEB_BUILD_OPTIONS and the description for the "nocheck" flags seems to
be incorrect.

The currently supported, full list of flags is available at 

https://www.debian.org/doc/debian-policy/ch-source.html#debian-rules-and-deb-build-options

I've attached an example patch to include the supported flags list in
dpkg-buildpackage(1).

All the best,

Sebastian


-- Package-specific info:
This system uses merged-usr-via-aliased-dirs, going behind dpkg's
back, breaking its core assumptions. This can cause silent file
overwrites and disappearances, and its general tools misbehavior.
See .

-- System Information:
Debian Release: 12.0
  APT prefers stable-security
  APT policy: (500, 'stable-security'), (500, 'stable')
Architecture: amd64 (x86_64)

Kernel: Linux 6.1.0-9-amd64 (SMP w/1 CPU thread; PREEMPT)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

Versions of packages dpkg-dev depends on:
ii  binutils  2.40-2
ii  bzip2 1.0.8-5+b1
ii  libdpkg-perl  1.21.22
ii  make  4.3-4.1
ii  patch 2.7.6-7
ii  perl  5.36.0-7
ii  tar   1.34+dfsg-1.2
ii  xz-utils  5.4.1-0.2

Versions of packages dpkg-dev recommends:
ii  build-essential  12.9
ii  fakeroot 1.31-1.2
ii  gcc [c-compiler] 4:12.2.0-3
ii  gcc-12 [c-compiler]  12.2.0-14
ii  gnupg2.2.40-1.1
ii  gpgv 2.2.40-1.1
ii  libalgorithm-merge-perl  0.08-5

Versions of packages dpkg-dev suggests:
pn  debian-keyring  

-- no debconf information
>From 4249055007018502b5981ad06b019fd56619ed64 Mon Sep 17 00:00:00 2001
From: skayser 
Date: Thu, 22 Jun 2023 17:31:23 +0200
Subject: [PATCH] dpkg-buildpackage.pod: include full list of DEB_BUILD_OPTIONS

---
 man/dpkg-buildpackage.pod | 43 +++
 1 file changed, 39 insertions(+), 4 deletions(-)

diff --git a/man/dpkg-buildpackage.pod b/man/dpkg-buildpackage.pod
index 3da341992..9abcc4a3a 100644
--- a/man/dpkg-buildpackage.pod
+++ b/man/dpkg-buildpackage.pod
@@ -740,13 +740,48 @@ Overridden by the B<--sign-keyfile> option.
 
 =item B
 
-If set, it will contain a space-separated list of options that might
+If set, it will contain a space-separated list of tags that might
 affect the build process in I, and the behavior of some
 dpkg commands.
 
-With B the B variable will be ignored.
-With BI the parallel jobs will be set to I,
-overridden by the B<--jobs-try> option.
+The meaning of the following tags has been standardized:
+
+=over
+
+=item B
+
+This tag says to not run any build-time test suite provided by the package.
+
+=item B
+
+This tag says to skip any build steps that only generate package
+documentation.
+
+=item B
+
+The presence of this tag means that the package should be compiled with a
+minimum of optimization.
+
+=item B
+
+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 B
+
+This tag means that the package should be built using up to I parallel
+processes if the package build system supports this. Overridable with the
+B<--jobs-try> option.
+
+=item B
+
+This tag means that the package build will be less verbose than default.
+
+=back
+
+See also 
L
 for an extended description as well as an example
+B file that implements these tags.
 
 =item B
 
-- 
2.39.2