[gentoo-commits] repo/gentoo:master commit in: app-portage/eclass-manpages/files/

[Michał Górny]

commit:     1a2962517426e51bea4b05b848175d788f44766f
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Fri Apr 28 14:51:12 2017 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Fri Nov 17 16:49:22 2017 +0000
URL:        https://gitweb.gentoo.org/repo/gentoo.git/commit/?id=1a296251

app-portage/eclass-manpages: Introduce additional variable classes

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 fe7e9c12d8f..b2f9afb0fa9 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)
@@ -294,6 +303,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
 	}
@@ -311,7 +326,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 ~ / /) {
@@ -324,6 +339,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 ""