[pkgsrc/trunk]: pkgsrc/mk/help mk/help: update information about environment ...

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

details:   https://anonhg.NetBSD.org/pkgsrc/rev/8d183250aa19
branches:  trunk
changeset: 387075:8d183250aa19
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Fri Nov 09 07:03:37 2018 +0000

description:
mk/help: update information about environment variables like MAKE_ENV

diffstat:

 mk/help/env.help |  71 ++++++++++++++++++++++++++++++-------------------------
 1 files changed, 39 insertions(+), 32 deletions(-)

diffs (100 lines):

diff -r 8f3289c510fc -r 8d183250aa19 mk/help/env.help
--- a/mk/help/env.help  Fri Nov 09 06:59:20 2018 +0000
+++ b/mk/help/env.help  Fri Nov 09 07:03:37 2018 +0000
@@ -1,43 +1,50 @@
-# $NetBSD: env.help,v 1.2 2010/09/29 11:40:43 obache Exp $
+# $NetBSD: env.help,v 1.3 2018/11/09 07:03:37 rillig Exp $
 #
 # This file describes the *_ENV variables, where they are defined and
 # where they are used.
 #
-# In general, all environments should be ordered from general to specific
-# ones. That is, first comes the BARRIER_ENV, then the MAKE_ENV, then the
-# MAKE_BUILD_ENV.
-#
-# Additionally, the package should be able to override all settings from
-# the infrastructure. That means that the package-settable variables
-# must appear behind the system-defined ones.
-#
-
-# XXX: I'm missing BARRIER_ENV or something like that.
-
-# XXX: The do-* targets are not run with ALL_ENV (or better:
-# BARRIER_ENV) in effect.
-
-#
-# Common environments.
+# See regress/env-vars.
 #
 
 # PKGSRC_MAKE_ENV
+#      The variables mentioned in this environment are passed to all
+#      recursive calls of the pkgsrc make. From there, they will also
+#      be available to configure files or the Makefiles from inside the
+#      package.
 #
 
+# EXTRACT_ENV
+#      The variables mentioned in this environment are passed to the
+#      default extract command, together with many other environment
+#      variables from the pkgsrc infrastructure.
+#
+#      If a package defines its own extract command, it doesn't have
+#      access to this full environment, but only to the EXTRACT_ENV
+#      part alone.
+
 # ALL_ENV
 #      This is the basic environment for the configure, build and install
-#      phases. It can be overridden by CONFIGURE_ENV and MAKE_ENV.
+#      phases. Definitions from this environment can be overridden by
+#      appending to CONFIGURE_ENV and MAKE_ENV.
 #
 
-#
-# Environments for individual phases.
+# CONFIGURE_ENV
+#      The variables mentioned in this environment are passed to the
+#      default configure commands. They can be overridden by appending
+#      to ALL_ENV.
 #
-
-# EXTRACT_ENV
-
-# CONFIGURE_ENV
+#      If a package defines its own configure commands, these commands
+#      don't have access to this full environment, but only to the
+#      CONFIGURE_ENV part alone.
 
 # MAKE_ENV
+#      The variables mentioned in this environment are passed to the
+#      default build commands. They can be overridden by appending
+#      to ALL_ENV.
+#
+#      If a package defines its own build commands, these commands
+#      don't have access to this full environment, but only to the
+#      MAKE_ENV part alone.
 
 # BSD_MAKE_ENV
 #      This environment can be appended to MAKE_ENV by a package to
@@ -49,13 +56,13 @@
 #
 
 # INSTALL_ENV
-#      This environment is prepended to MAKE_ENV in the install phase.
-#      XXX: Shouldn't this be _ap_pended?
-
+#      The variables mentioned in this environment are passed to the
+#      default install commands. They can be overridden by appending
+#      to ALL_ENV.
 #
-# Other environments.
+#      If a package defines its own build commands, these commands
+#      don't have access to this full environment, but only to the
+#      MAKE_ENV part alone.
+#      This environment is prepended to MAKE_ENV in the install phase.
 #
-
-# INSTALL_SCRIPTS_ENV
-#      TODO
-#
+#      XXX: Shouldn't this be _ap_pended?