From 3ac84880e2a57590f66598f6987f7c4c1646988d Mon Sep 17 00:00:00 2001
From: Nicolas Boulenguez <nicolas@debian.org>
Date: Sun, 13 Feb 2022 13:41:26 +0100
Subject: [PATCH 6/6] 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.
---
 scripts/mk/architecture.mk | 15 ++++++++++++---
 scripts/mk/buildflags.mk   | 11 +++++++++--
 scripts/mk/buildopts.mk    |  7 +++----
 scripts/mk/buildtools.mk   |  5 +++--
 scripts/mk/default.mk      |  4 ++--
 scripts/mk/pkg-info.mk     |  5 +++--
 scripts/mk/vendor.mk       |  5 +++--
 7 files changed, 35 insertions(+), 17 deletions(-)

diff --git a/scripts/mk/architecture.mk b/scripts/mk/architecture.mk
index 963293e05..5bf017844 100644
--- a/scripts/mk/architecture.mk
+++ b/scripts/mk/architecture.mk
@@ -1,6 +1,15 @@
-# 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.
+# (since dpkg 1.16.1)
+# 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.
 
 ifndef dpkg_architecture_mk_already_included
 dpkg_architecture_mk_already_included :=
diff --git a/scripts/mk/buildflags.mk b/scripts/mk/buildflags.mk
index 34a66fd01..a51778467 100644
--- a/scripts/mk/buildflags.mk
+++ b/scripts/mk/buildflags.mk
@@ -1,4 +1,6 @@
-# This Makefile fragment (since dpkg 1.16.1) defines the following variables:
+# debian/rules helper defining the dpkg-buildflags(1) variables.
+# (since dpkg 1.16.1)
+# Include this (or default.mk) if using:
 #
 #   ASFLAGS: flags for the assembler (since 1.21.0).
 #   CFLAGS: flags for the C compiler.
@@ -13,8 +15,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}
 
 ifndef dpkg_buildflags_mk_already_included
 dpkg_buildflags_mk_already_included :=
diff --git a/scripts/mk/buildopts.mk b/scripts/mk/buildopts.mk
index c087ad3a4..042bf814a 100644
--- a/scripts/mk/buildopts.mk
+++ b/scripts/mk/buildopts.mk
@@ -1,7 +1,6 @@
-# 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.
+# (since dpkg 1.20.1)
+# 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 ac9809c36..859b21043 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 095128470..0a0b52171 100644
--- a/scripts/mk/default.mk
+++ b/scripts/mk/default.mk
@@ -1,5 +1,5 @@
-# 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.
+# (since dpkg 1.16.1)
 
 dpkg_datadir := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST))))
 include $(dpkg_datadir)/architecture.mk
diff --git a/scripts/mk/pkg-info.mk b/scripts/mk/pkg-info.mk
index 21ed26b36..abc27379d 100644
--- a/scripts/mk/pkg-info.mk
+++ b/scripts/mk/pkg-info.mk
@@ -1,5 +1,6 @@
-# This Makefile fragment (since dpkg 1.16.1) defines the following package
-# information variables:
+# debian/rules helper defining some dpkg-parsechangelog(1) variables.
+# (since 1.16.1)
+# Include this (or default.mk) if using:
 #
 #   DEB_SOURCE: source package name.
 #   DEB_VERSION: package's full version (epoch + upstream vers. + revision).
diff --git a/scripts/mk/vendor.mk b/scripts/mk/vendor.mk
index d6050d965..8669620ea 100644
--- a/scripts/mk/vendor.mk
+++ b/scripts/mk/vendor.mk
@@ -1,5 +1,6 @@
-# This Makefile fragment (since dpkg 1.16.1) defines the following
-# vendor-related variables:
+# debian/rules helper defining some dpkg-vendor(1) variables.
+# (since dpkg 1.16.1)
+# 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

