dpkg-buildflags(1) documents how maintainers can set
DEB_CFLAGS_MAINT_APPEND and friends, but there's no best-practice example
of how to use them in d/rules. This means that maintainers will write
in whatever format happens to work today, resulting in a risk that when
corner-case behaviour of default.mk etc. changes, as it seems to have
done recently, their d/rules will no longer work as intended.

What I'd ideally like to see is something like this in the EXAMPLES section,
if it's correct (but I'm unsure whether it is):

    #!/usr/bin/make -f

    # Add -Wl,-z,-defs to the linker flags
    export DEB_LDFLAGS_MAINT_APPEND = -Wl,-z,-defs

    include /usr/share/dpkg/default.mk

    # ... the rest of the build description ...

Ideally there would also be an example of how a build flag can be made
to depend on some other fact about the package. For example if I want to
build with -ffloat-store on i386 only, is this correct?

    #!/usr/bin/make -f

    include /usr/share/dpkg/pkg-info.mk

    # Add -ffloat-store to the CFLAGS, but only on i386 CPUs
    ifeq ($(DEB_HOST_ARCH_CPU),i386)
    export DEB_CFLAGS_MAINT_APPEND = -ffloat-store
    endif

    include /usr/share/dpkg/default.mk

    # ... the rest of the build description ...

Questions whose answers are unclear to me:

* Do DEB_*_MAINT_* need to be exported as environment variables, or is it
  sufficient for them to be set as make(1) variables?
* Do DEB_*_MAINT_* need to be set before including buildflags.mk, or
  do they use enough lazy-evaluation that it is sufficient to set them
  anywhere in debian/rules?
* Are there other requirements or interactions that maintainers will
  typically need to take into account?

Thanks,
    smcv

Hi Simon,

On Thu, 1 Aug 2024 10:14:07 +0100 Simon McVittie <smcv@debian.org>  wrote:
 > dpkg-buildflags(1) documents how maintainers can set
 > DEB_CFLAGS_MAINT_APPEND and friends, but there's no best-practice
example
 > of how to use them in d/rules.

An example d/rules assuming debhelper usage (in case it matters) would
be useful indeed, alongside an explanation of when and why we should
use DPKG_EXPORT_BUILDFLAGS.

 > Questions whose answers are unclear to me:
 >
 > * Do DEB_*_MAINT_* need to be exported as environment variables, or
is it
 >   sufficient for them to be set as make(1) variables?

According to the dpkg-buildflags(1) manpage, "The default flags [...]
can be extended/overridden in several ways: [...] dynamically by the
package maintainer with environment variables set via debian/rules (see
section "ENVIRONMENT")". So it seems that make(1) variables are not
enough.

 > * Do DEB_*_MAINT_* need to be set before including buildflags.mk, or
 >   do they use enough lazy-evaluation that it is sufficient to set
them
 >   anywhere in debian/rules?

Also, _when_ should be include buildflags.mk? Is it needed when using
debhelper? Is it there a case where you would *not* want to include it?

 > * Are there other requirements or interactions that maintainers will
 >   typically need to take into account?

As I said above, it'd be also nice to specify what is already implied
by debhelper usage, possibly pointing to its appropriate documentation.