ebuild-environment.tex: Clarify visibility of top-level variablesHEADmaster

This came up in https://github.com/pkgcore/pkgcore/issues/470.
Given the following ebuild snippet:

   var1="test"
   declare -- var2="test"
   declare -A var3=([key1]="value1")
   declare -a var4=(1 2 3)

   src_unpack() {
       declare -p var1 var2 var3 var4
   }

With Portage, all four variables are visible in src_unpack, while with
Pkgcore or Paludis only var1 is visible. OTOH, if the definitions are
moved from the ebuild to the top level of an eclass, then var{2,3,4}
will also lose their visibility for Portage.

Considering that:
- Implementation in package managers differs,
- Portage is inconsistent for ebuilds and eclasses,
- developers shouldn't have to remember different rules for ebuild
  and eclass top-level code,

it seems best to clarify that visibility is unspecified and that
ebuilds must not rely on any specific behaviour.

Signed-off-by: Ulrich Müller <ulm@gentoo.org>

1 files changed, 6 insertions, 0 deletions

diff --git a/ebuild-environment.tex b/ebuild-environment.tex
index 06e197d..2691a8e 100644
--- a/ebuild-environment.tex
+++ b/ebuild-environment.tex
@@ -12,6 +12,12 @@ functions executed as part of a later uninstall.
 \note{\t{pkg_pretend} is \emph{not} part of the normal call sequence, and does not take part in
 environment saving.}
 
+The visibility of variables defined at the top level of an ebuild or eclass is unspecified.
+Depending on the implementation, such variables may behave as if evaluated in global scope or as if
+evaluated within a function body; ebuilds must not rely upon either behaviour. Consequently, at the
+top level, the \t{local} builtin may not be used, and the \t{declare} builtin may only be used with
+the \t{-g} option when defining variables.
+
 Variables that were exported must remain exported in later functions; variables with default
 visibility may retain default visibility or be exported. Variables with special meanings to the
 package manager are excluded from this rule.