[gentoo-dev] [PATCH 1/2] app-portage/eclass-manpages: Introduce additional variable classes

[Michał Górny]

Add a few additional variable classes to better emphasize the specifics
of different kinds of variables set for eclasses, and by eclasses.

The change applied, each eclass variable can belong to one of
the following five eclasses:

1. (default) - variable set by ebuild, influences eclass behavior.

2. @PRE-INHERIT - likewise but must be set above the inherit line,
and not modified afterwards.

3. @USER-VARIABLE - variable to be set by user (make.conf), and not
by ebuilds. This mostly involves MAKEOPTS-style variables.

4. @OUTPUT-VARIABLE - variable that is generated and defined by eclass,
and ebuilds can *read* it.

5. @INTERNAL - (existing) internal use variable.
---
 .../eclass-manpages/files/eclass-to-manpage.awk    | 32 ++++++++++++++++++++--
 1 file changed, 29 insertions(+), 3 deletions(-)

diff --git a/app-portage/eclass-manpages/files/eclass-to-manpage.awk b/app-portage/eclass-manpages/files/eclass-to-manpage.awk
index 681a567af043..56847930ff35 100644
--- a/app-portage/eclass-manpages/files/eclass-to-manpage.awk
+++ b/app-portage/eclass-manpages/files/eclass-to-manpage.awk
@@ -37,8 +37,9 @@
 
 # The format of function-specific variables:
 # @VARIABLE: foo
+# [@USER-VARIABLE] (set in make.conf, not ebuilds)
+# [@INTERNAL] (internal eclass use variable)
 # [@DEFAULT-UNSET]
-# [@INTERNAL]
 # [@REQUIRED]
 # @DESCRIPTION:
 # <required; blurb about this variable>
@@ -46,8 +47,11 @@
 
 # The format of eclass variables:
 # @ECLASS-VARIABLE: foo
+# [@PRE-INHERIT] (the variable must be set before inheriting the eclass)
+# [@USER-VARIABLE] (set in make.conf, not ebuilds)
+# [@OUTPUT-VARIABLE] (set by eclass, to be read in ebuilds)
+# [@INTERNAL] (internal eclass use variable)
 # [@DEFAULT-UNSET]
-# [@INTERNAL]
 # [@REQUIRED]
 # @DESCRIPTION:
 # <required; blurb about this variable>
@@ -279,6 +283,11 @@ function _handle_variable() {
 	internal = 0
 	required = 0
 
+	# additional variable classes
+	pre_inherit = 0
+	user_variable = 0
+	output_variable = 0
+
 	# make sure people haven't specified this before (copy & paste error)
 	if (all_vars[var_name])
 		fail(eclass ": duplicate definition found for variable: " var_name)
@@ -297,6 +306,12 @@ function _handle_variable() {
 			internal = 1
 		else if ($2 == "@REQUIRED")
 			required = 1
+		else if ($2 == "@PRE-INHERIT")
+			pre_inherit = 1
+		else if ($2 == "@USER-VARIABLE")
+			user_variable = 1
+		else if ($2 == "@OUTPUT-VARIABLE")
+			output_variable = 1
 		else
 			opts = 0
 	}
@@ -314,7 +329,7 @@ function _handle_variable() {
 		regex = "^[[:space:]]*:[[:space:]]*[$]{" var_name ":?=(.*)}"
 		val = gensub(regex, "\\1", 1, $0)
 		if (val == $0) {
-			if (default_unset + required + internal == 0)
+			if (default_unset + required + internal + output_variable == 0)
 				warn(var_name ": unable to extract default variable content: " $0)
 			val = ""
 		} else if (val !~ /^["']/ && val ~ / /) {
@@ -327,6 +342,17 @@ function _handle_variable() {
 		val = " " op " \\fI" val "\\fR"
 	if (required == 1)
 		val = val " (REQUIRED)"
+	# TODO: group variables using those classes
+	if (pre_inherit == 1)
+		val = val " (SET BEFORE INHERIT)"
+	if (user_variable == 1)
+		val = val " (USER VARIABLE)"
+	if (output_variable == 1)
+		val = val " (GENERATED BY ECLASS)"
+
+	# check for invalid combos
+	if (internal + pre_inherit + user_variable + output_variable > 1)
+		fail(var_name ": multiple variable classes specified")
 
 	if (internal == 1)
 		return ""
-- 
2.13.0.rc1