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.

diff --git a/app-portage/eclass-manpages/files/eclass-to-manpage.awk b/app-portage/eclass-manpages/files/eclass-to-manpage.awk
index fe7e9c12d8f59c142b87833733e057b364cf5f69..b2f9afb0fa950f193136448645df30e09d8951b5 100644 (file)
--- 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 ""