[pkgsrc/trunk]: pkgsrc/mk/misc show-all: explain how to show the values of tr...

[rillig <rillig%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/444120505c1a
branches:  trunk
changeset: 443460:444120505c1a
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Mon Dec 14 00:14:48 2020 +0000

description:
show-all: explain how to show the values of tricky variables

In most cases, the output of "bmake show-all" is reliable, but in a few
edge cases there may still be surprises.

diffstat:

 mk/misc/show.mk |  27 ++++++++++++++++++++-------
 1 files changed, 20 insertions(+), 7 deletions(-)

diffs (41 lines):

diff -r 20fa647df2fd -r 444120505c1a mk/misc/show.mk
--- a/mk/misc/show.mk   Sun Dec 13 23:51:20 2020 +0000
+++ b/mk/misc/show.mk   Mon Dec 14 00:14:48 2020 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: show.mk,v 1.26 2020/09/12 21:27:15 rillig Exp $
+# $NetBSD: show.mk,v 1.27 2020/12/14 00:14:48 rillig Exp $
 #
 # This file contains some targets that print information gathered from
 # variables. They do not modify any variables.
@@ -92,12 +92,25 @@
 #      For each of these groups, a specialized target show-all-${group}
 #      is defined, e.g. "show-all-extract" for the "extract" group.
 #
-#      CAVEAT: Some few variable values that are shown here may be
-#      misleading. For example, make(1)'s := operator leaves references
-#      to undefined variables as-is, so they may be resolved later. So
-#      if you want to take a snapshot of the exact value of a variable,
-#      you have to use "snapshot!=printf %s ''${var:q}" instead of
-#      "snapshot:=${var}".
+#      CAVEAT: There are a few extreme edge cases in which the variable
+#      values that are shown here are not 100% correct. The closest you
+#      can get are the following:
+#
+#              * To see the unexpanded definition of a variable while the
+#                Makefile or an included file is parsed, run "bmake -dcpv",
+#                which adds a lot of debug logging.
+#              * To see the unexpanded definition of a variable at the end
+#                of parsing the Makefile, run "bmake -V VARNAME".
+#              * To see the expanded value of a variable while the Makefile
+#                or an included file is parsed, add a line of the form
+#                ".info ${VARNAME}" to that makefile.
+#              * To see the expanded value of a variable at the end of
+#                parsing the Makefile, run "bmake -v VARNAME".
+#
+#      In some cases, the actual value of a variable depends on the targets
+#      that are given on the command line, or whether bmake is run
+#      recursively, or whether a directory inside WRKSRC already exists.
+#      There is nothing the pkgsrc infrastructure can do about this.
 #
 # Keywords: debug show _vargroups
 #