From 21a538ce8f4daabc12f542c91e7da5d2d7b870ca Mon Sep 17 00:00:00 2001 From: Paul Smith Date: Sun, 24 Mar 2024 14:05:45 -0400 Subject: [PATCH] [SV 65359] doc/make.texi: Describe invalid export variable names --- doc/make.texi | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/doc/make.texi b/doc/make.texi index ba1545f6..5efae41c 100644 --- 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