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

[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

[gentoo-dev] [PATCH 2/2] python-r1.eclass: Set @ECLASS-VARIABLE classes (example)

[Michał Górny]

---
 eclass/python-r1.eclass | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/eclass/python-r1.eclass b/eclass/python-r1.eclass
index 9f56c6f3877a..866f49071147 100644
--- a/eclass/python-r1.eclass
+++ b/eclass/python-r1.eclass
@@ -55,6 +55,7 @@ inherit multibuild python-utils-r1
 fi
 
 # @ECLASS-VARIABLE: PYTHON_COMPAT
+# @PRE-INHERIT
 # @REQUIRED
 # @DESCRIPTION:
 # This variable contains a list of Python implementations the package
@@ -91,6 +92,7 @@ fi
 # @CODE
 
 # @ECLASS-VARIABLE: PYTHON_REQ_USE
+# @PRE-INHERIT
 # @DEFAULT_UNSET
 # @DESCRIPTION:
 # The list of USEflags required to be enabled on the chosen Python
@@ -111,6 +113,7 @@ fi
 # @CODE
 
 # @ECLASS-VARIABLE: PYTHON_DEPS
+# @OUTPUT-VARIABLE
 # @DESCRIPTION:
 # This is an eclass-generated Python dependency string for all
 # implementations listed in PYTHON_COMPAT.
@@ -130,6 +133,7 @@ fi
 # @CODE
 
 # @ECLASS-VARIABLE: PYTHON_USEDEP
+# @OUTPUT-VARIABLE
 # @DESCRIPTION:
 # This is an eclass-generated USE-dependency string which can be used to
 # depend on another Python package being built for the same Python
@@ -150,6 +154,7 @@ fi
 # @CODE
 
 # @ECLASS-VARIABLE: PYTHON_REQUIRED_USE
+# @OUTPUT-VARIABLE
 # @DESCRIPTION:
 # This is an eclass-generated required-use expression which ensures at
 # least one Python implementation has been enabled.
-- 
2.13.0.rc1

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

[Michael Orlitzky]

On 04/28/2017 10:59 AM, Michał Górny wrote:
> 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:

We did some work to move all of this stuff to the devmanual:

  https://devmanual.gentoo.org/eclass-writing/index.html

The idea being that we shouldn't have to tell people the eclass doc
specification is in the guts of some random awk script.

Can you please also update that page so that it remains authoritative?

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

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 816 bytes --]

On pią, 2017-04-28 at 15:11 -0400, Michael Orlitzky wrote:
> On 04/28/2017 10:59 AM, Michał Górny wrote:
> > 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:
> 
> We did some work to move all of this stuff to the devmanual:
> 
>   https://devmanual.gentoo.org/eclass-writing/index.html
> 
> The idea being that we shouldn't have to tell people the eclass doc
> specification is in the guts of some random awk script.
> 
> Can you please also update that page so that it remains authoritative?
> 

Sure, I'll keep that in mind if the patches get past review.

-- 
Best regards,
Michał Górny

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 963 bytes --]