[SV 65359] doc/make.texi: Describe invalid export variable names

diff --git a/doc/make.texi b/doc/make.texi
index ba1545f661de622f3260668300e576fb8375eb2a..5efae41cbaa13dd117c9d2af8e3ccf92fbcca0cc 100644 (file)
--- a/doc/make.texi
+++ b/doc/make.texi
@@ -4974,6 +4974,15 @@ In both of these forms, the arguments to @code{export} and
 @code{unexport} are expanded, and so could be variables or functions
 which expand to a (list of) variable names to be (un)exported.
 
+GNU Make will add any variable you export to the environment of all child
+processes.  However, be aware that some child processes themselves will not
+accept all types of variables.  For example, many modern shells will clean the
+incoming environment by removing or hiding any environment variable whose name
+is invalid for the shell (e.g., alphanumeric plus underscore).  There is
+nothing GNU Make can do about the behavior of these child processes: if you
+want your makefile to be maximally portable you should choose simple variable
+names for all exported variables.
+
 As a convenience, you can define a variable and export it at the same
 time by doing:
 
@@ -5036,15 +5045,10 @@ This tells @code{make} that variables which are not explicitly mentioned in an
 @code{export} or @code{unexport} directive should be exported.  Any variable
 given in an @code{unexport} directive will still @emph{not} be exported.
 
-@findex .EXPORT_ALL_VARIABLES@r{, compatibility}
-@cindex compatibility in exporting
-The behavior elicited by an @code{export} directive by itself was the default
-in older versions of GNU @code{make}.  If your makefiles depend on this
-behavior and you want to be compatible with old versions of @code{make}, you
-can add the special target @code{.EXPORT_ALL_VARIABLES} to your makefile
-instead of using the @code{export} directive.  This will be ignored by old
-@code{make}s, while the @code{export} directive will cause a syntax
-error.
+@findex .EXPORT_ALL_VARIABLES
+Another way to export variables by default is to add the special target
+@code{.EXPORT_ALL_VARIABLES} to your makefile.  This will be ignored by other
+variants of @code{make}.
 
 When using @code{export} by itself or @code{.EXPORT_ALL_VARIABLES} to export
 variables by default, only variables whose names consist solely of
@@ -5059,6 +5063,13 @@ names which are not exportable by default.  However, a better solution is to
 @emph{not} use this ``export by default'' facility at all, and instead
 explicitly @code{export} the relevant variables by name.
 
+Be aware that exporting all variables can have serious performance impacts,
+especially for recursive variables used in conjunction with the @code{shell}
+function.  We recommend you avoid this and instead export only the specific
+variables needed to run your commands.  If you do need to export all
+variables, use simple variable assignment wherever possible, especially when
+invoking the @code{shell} function.
+
 You can use @code{unexport} by itself to tell @code{make} @emph{not} to export
 variables by default.  Since this is the default behavior, you would only need
 to do this if @code{export} had been used by itself earlier (in an included