[gentoo-pms] [PATCH] Allocate __* for package manager internals, blacklist it for ebuilds.

[Brian Harring]

To varying degrees, existing PMs use names that aren't prefixed in some
fashion indicating it's an internal- the end result being ebuilds/eclasses
that rely on a PM internal (both bad for alternate PMs, and bad should
that internal change).

Further, the lack of a standardized namespace for the PMs internals means
QA tools must maintain their own lists.  As such, allocate __* for the PM
to use for it's internal functionality and variables.

This currently conflicts with the following in gentoo-x86:

__do_sed_fix
__list_needed_subdirectories
__prepare_module
___ECLASS_ONCE_AUTOTOOLS

All of these are trivial to change.
---
 ebuild-env-vars.tex  | 9 +++++++++
 ebuild-functions.tex | 6 ++++++
 ebuild-vars.tex      | 6 ++++++
 3 files changed, 21 insertions(+)

diff --git a/ebuild-env-vars.tex b/ebuild-env-vars.tex
index 9597e67..1036f6f 100644
--- a/ebuild-env-vars.tex
+++ b/ebuild-env-vars.tex
@@ -1,3 +1,12 @@
+\section{Package Manager Internals}
+\label{sec:package-manager-internal-names}
+
+The package manager, unless stated otherwise in this document, must name all internal variables
+and functions starting with \_\_; the purpose of this is to ensure that no ebuild or eclass
+accidentally relies on a package manager implementation detail.  Variables and functions
+exported by bash, or bash the systems bashrc or profiles are exempt from this requirement; this
+applies strictly to the package managers implementation.
+
 \section{Defined Variables}
 \label{sec:ebuild-env-vars}
 
diff --git a/ebuild-functions.tex b/ebuild-functions.tex
index 9836e33..a50ccdc 100644
--- a/ebuild-functions.tex
+++ b/ebuild-functions.tex
@@ -1,6 +1,12 @@
 \chapter{Ebuild-defined Functions}
 \label{sec:ebuild-functions}
 
+\section{Allowed Names}
+\label{sec:ebuild-function-names}
+
+All ebuild and eclass functions must not start with \_\_; that space is reserved for package
+manager internal functions.
+
 \section{List of Functions}
 \label{sec:functions}
 
diff --git a/ebuild-vars.tex b/ebuild-vars.tex
index 53de53d..dfe71dd 100644
--- a/ebuild-vars.tex
+++ b/ebuild-vars.tex
@@ -8,6 +8,12 @@ If any of these variables are set to invalid values, or if any of the mandatory
 undefined, the package manager's behaviour is undefined; ideally, an error in one ebuild should not
 prevent operations upon other ebuilds or packages.
 
+\section{Allowed Names}
+\label{sec:ebuild-variable-names}
+
+All ebuild and eclass defined variables must not start with \_\_; that namespace is reserved for
+the package managers internals.
+
 \section{Metadata invariance}
 \label{sec:metadata-invariance}
 
-- 
1.7.12