From 7a873a2e15dbb003aa9974c9019a7ca1821062e7 Mon Sep 17 00:00:00 2001
From: Nicolas Boulenguez <nicolas@debian.org>
Date: Sun, 13 Feb 2022 13:41:26 +0100
Subject: [PATCH 10/10] scripts/mk: improve details in documentation

architecture.mk: give more details
Mention default.mk as an alternative in included scripts.
Improve consistency accross Makefile snippets.
Stop documenting version restrictions older than oldoldstable.
---
 scripts/mk/architecture.mk | 14 +++++++++++---
 scripts/mk/buildflags.mk   | 10 ++++++++--
 scripts/mk/buildopts.mk    |  6 ++----
 scripts/mk/buildtools.mk   |  5 +++--
 scripts/mk/default.mk      |  3 +--
 scripts/mk/pkg-info.mk     |  5 ++---
 scripts/mk/vendor.mk       |  4 ++--
 7 files changed, 29 insertions(+), 18 deletions(-)

diff --git a/scripts/mk/architecture.mk b/scripts/mk/architecture.mk
index 5f03e764d..c654991bd 100644
--- a/scripts/mk/architecture.mk
+++ b/scripts/mk/architecture.mk
@@ -1,6 +1,14 @@
-# This Makefile frament (since dpkg 1.16.1) defines all the DEB_HOST_* and
-# DEB_BUILD_* variables that dpkg-architecture can return. Existing values
-# of those variables are preserved as per policy.
+# debian/rules helper defining dpkg-architecture(1) variables.
+# Include this (or default.mk) if using DEB_{HOST,BUILD,TARGET}_*.
+#
+# These variables are usually computed by dpkg-buildpackage and simply
+# inherited by debian/rules, but need a definition when debian/rules
+# is invoked directly.
+#
+# Each variable may be overridden by the end user (on the debian/rules
+# command line) or by the maintainer (within debian/rules).
+#
+# All values are unconditionally exported.
 
 # Protect against repeated inclusion (via buildtools.mk for example).
 ifndef dpkg-architecture_vars
diff --git a/scripts/mk/buildflags.mk b/scripts/mk/buildflags.mk
index ac74fe656..87a0fba0f 100644
--- a/scripts/mk/buildflags.mk
+++ b/scripts/mk/buildflags.mk
@@ -1,4 +1,5 @@
-# This Makefile fragment (since dpkg 1.16.1) defines the following variables:
+# debian/rules helper defining the dpkg-buildflags(1) variables.
+# Include this (or default.mk) if using:
 #
 #   ASFLAGS: flags for the assembler (since 1.21.0).
 #   CFLAGS: flags for the C compiler.
@@ -13,8 +14,13 @@
 #   LDFLAGS: flags for the linker.
 #
 # You can also export them in the environment by setting
-# DPKG_EXPORT_BUILDFLAGS to a non-empty value.
+# DPKG_EXPORT_BUILDFLAGS.
 #
+# These variables are computed by dpkg-buildflags(1) and should not be
+# directly overridden.  The following setting are exported to
+# dpkg-buildflags.
+#   DEB_BUILD_{OPTIONS,MAINT_OPTIONS,PATH}
+#   DEB_*_MAINT_{APPEND,PREPEND,SET,STRIP}
 
 # Protect against repeated inclusion
 ifndef DPKG_BUILDFLAGS_LIST
diff --git a/scripts/mk/buildopts.mk b/scripts/mk/buildopts.mk
index a8d6f1987..9ebc8e9ac 100644
--- a/scripts/mk/buildopts.mk
+++ b/scripts/mk/buildopts.mk
@@ -1,7 +1,5 @@
-# This Makefile fragment (since dpkg 1.20.1) parses option arguments from
-# DEB_BUILD_OPTIONS, and exposes these as variables.
-#
-# Defines the following variables:
+# debian/rules helper extracting some arguments from DEB_BUILD_OPTIONS.
+# Include this (or default.mk) if using:
 #
 #   DEB_BUILD_OPTION_PARALLEL: the argument for the parallel=N option.
 
diff --git a/scripts/mk/buildtools.mk b/scripts/mk/buildtools.mk
index b4cdbcb40..be08c3915 100644
--- a/scripts/mk/buildtools.mk
+++ b/scripts/mk/buildtools.mk
@@ -1,5 +1,6 @@
-# This Makefile fragment (since dpkg 1.19.0) defines the following variables
-# for host tools:
+# debian/rules helper defining some host and build tools
+# (since dpkg 1.19.0)
+# Include this if using:
 #
 #   AS: assembler (since dpkg 1.19.1).
 #   CPP: C preprocessor.
diff --git a/scripts/mk/default.mk b/scripts/mk/default.mk
index afe5d6876..278a9481c 100644
--- a/scripts/mk/default.mk
+++ b/scripts/mk/default.mk
@@ -1,5 +1,4 @@
-# This Makefile fragment (since dpkg 1.16.1) includes all the Makefile
-# fragments that define variables that can be useful within debian/rules.
+# debian/rules helper including a selection of more specific helpers.
 
 dpkg_datadir := $(dir $(lastword $(MAKEFILE_LIST)))
 include $(dpkg_datadir)architecture.mk
diff --git a/scripts/mk/pkg-info.mk b/scripts/mk/pkg-info.mk
index 7ee3cbd6b..a40116ace 100644
--- a/scripts/mk/pkg-info.mk
+++ b/scripts/mk/pkg-info.mk
@@ -1,5 +1,5 @@
-# This Makefile fragment (since dpkg 1.16.1) defines the following package
-# information variables:
+# debian/rules helper defining some dpkg-parsechangelog(1) variables.
+# Include this (or default.mk) if using:
 #
 #   DEB_SOURCE: source package name.
 #   DEB_VERSION: package's full version (epoch + upstream vers. + revision).
@@ -11,7 +11,6 @@
 #
 #   SOURCE_DATE_EPOCH: source release date as seconds since the epoch, as
 #     specified by <https://reproducible-builds.org/specs/source-date-epoch/>
-#     (since dpkg 1.18.8).
 #     If it is undefined, the date of the latest changelog entry is used.
 #     In both cases, the value is exported.
 
diff --git a/scripts/mk/vendor.mk b/scripts/mk/vendor.mk
index 8f8618880..521d9e0ec 100644
--- a/scripts/mk/vendor.mk
+++ b/scripts/mk/vendor.mk
@@ -1,5 +1,5 @@
-# This Makefile fragment (since dpkg 1.16.1) defines the following
-# vendor-related variables:
+# debian/rules helper defining some dpkg-vendor(1) variables.
+# Include this (or default.mk) if using:
 #
 #   DEB_VENDOR: output of «dpkg-vendor --query Vendor».
 #   DEB_PARENT_VENDOR: output of «dpkg-vendor --query Parent» (can be empty).
-- 
2.30.2

