mk/help: update information about environment variables like MAKE_ENV

1 files changed, 38 insertions, 31 deletions

diff --git a/mk/help/env.help b/mk/help/env.help
index c153670e50a..d980deb304a 100644
--- a/mk/help/env.help
+++ b/mk/help/env.help
@@ -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.
+# See regress/env-vars.
 #
-# 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.
+# 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.
 #
 
-# PKGSRC_MAKE_ENV
+# 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.
-#
-
-# EXTRACT_ENV
-
 # CONFIGURE_ENV
+#	The variables mentioned in this environment are passed to the
+#	default configure commands. They can be overridden by appending
+#	to ALL_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?
-
-#
-# Other environments.
+#	The variables mentioned in this environment are passed to the
+#	default install commands. They can be overridden by appending
+#	to ALL_ENV.
 #
-
-# INSTALL_SCRIPTS_ENV
-#	TODO
+#	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.
 #
+#	XXX: Shouldn't this be _ap_pended?