Add REQUIRED_USE docs from Brian Harring's GLEP draft.

1 files changed, 94 insertions, 0 deletions

diff --git a/doc/package/ebuild/eapi/4.docbook b/doc/package/ebuild/eapi/4.docbook
index 34fab506a..8d7942b47 100644
--- a/doc/package/ebuild/eapi/4.docbook
+++ b/doc/package/ebuild/eapi/4.docbook
@@ -15,4 +15,98 @@ The dodoc helper now has a -r option which enables recursion.
 </para>
 </section>
 </section>
+<section id='package-ebuild-eapi-4_pre1-metadata'>
+<title>Metadata</title>
+<section id='package-ebuild-eapi-4_pre1-metadata-required-use'>
+<title>REQUIRED_USE</title>
+<para>
+This new REQUIRED_USE metadata key is used to specify what USE flag combinations are disallowed for a specific pkg.
+</para>
+<section id='package-ebuild-eapi-4_pre1-metadata-required-use-motivation'>
+<title>Motivation</title>
+<para>
+It's a semi common occurence that an ebuild may need to state that they disallow USE flags in specific combinations- either mysql or sqlite for example, but not both.
+</para>
+<para>
+Existing solutions rely on checking the the USE configuration in pkg_setup which is non-optimal due to pkg_setup being ran potentially hours after the initial emerge -p invocation.
+</para>
+<para>
+Current versions of EAPI4 support a phase hook pkg_pretend that is intended to move pre-build checks to just after resolution. It has been proposed that pkg_pretend should continue the tradition of adhoc shell code validating the USE state- this too is non optimal for the following reasons-
+</para>
+<orderedlist>
+<listitem>
+<para>
+The only way to find out if the USE state is disallowed is to run the code
+</para>
+</listitem>
+<listitem>
+<para>
+The common implementation of this can result in an iterative process where the user hits a USE constraint, fixs it, reruns the emerge invocation only to find that there is another constraint still violated for the ebuild, thus requiring them to fix it, rerun emerge, etc.
+</para>
+</listitem>
+<listitem>
+<para>
+For a package manager to classify the error, the only option it has is to try and parse adhoc output written by an ebuild dev. This effectively disallows package manager options for providing a more informative error message. A simple example would be if the package manager wanted to integrate in the flag descriptions from use.desc/use.local.desc; this would be effectively impossible.
+</para>
+</listitem>
+<listitem>
+<para>
+Fundamentally these constraints are data, yet they're being encoded as executable code- this effectively blocks the possibility of doing a wide variety of QA/tree scans. For example it blocks the possibility of sanely scanning for USE flag induced hard dependency cycles, because the tools in question cannot get that info out of adhoc shell code.
+More importantly if the manager cannot know what the allowed USE states are for the ebuild in question, this eliminates the possibility of ever sanely breaking dependency cycles caused by USE flags.
+</para>
+</listitem>
+</orderedlist>
+<para>
+Just as .sh scripts are considered a poor archival form due to their opaqueness, pkg_setup and pkg_pretend aren't a proper solution for this. pkg_pretend in particular makes the situation slightly worse due to ebuild devs being expected to convert their ebuilds to the pkg_pretend form when using EAPI4. In doing so they'll have to do work w/out the gains REQUIRED_USE provides and have to repeat the same conversion work when REQUIRED_USE lands in a later EAPI.
+</para>
+</section>
+<section id='package-ebuild-eapi-4_pre1-metadata-required-use-specification'>
+<title>Specification</title>
+<para>
+Essentially REQUIRED_USE is proposed to be an analog of DEPENDS style syntax- a list of assertions that must be met for this USE configuration to be valid for this ebuild. For example, to state "if build is set, python must be unset":
+</para>
+<para>
+REQUIRED_USE="build? ( !python )"
+</para>
+<para>
+To state "either mysql or sqlite must be set, but not both":
+</para>
+<para>
+REQUIRED_USE="mysql? ( !sqlite ) !mysql? ( sqlite )"
+</para>
+<para>
+Note that the mysql/sqlite relationship is that of an Exclusive OR (XOR). While an XOR can be formed from existing syntax, it's suggested that a specific operator be added for this case using ^^. Reformatting the "mysql or sqlite, but not both" with XOR results in:
+</para>
+<para>
+REQUIRED_USE="^^ ( mysql sqlite )"
+</para>
+<para>
+Like any block operator, this can be combined with other constraints. For example if the user has flipped on the client flag, one gui must be choosen:
+</para>
+<para>
+REQUIRED_USE="client? ( ^^ ( gtk qt motif ) )"
+</para>
+<para>
+If the pkg is implemented sanely and requires at least one gui, but can support multiple it would be:
+</para>
+<para>
+REQUIRED_USE="client? ( || ( gtk qt motif ) )"
+</para>
+<para>
+Because ARCH is integrated into the USE space, this also allows for specifying corner cases like "at least one gui must be specified, but on mips only one gui can be specified":
+</para>
+<para>
+REQUIRED_USE="client? ( !mips? ( || (  gtk qt motif ) ) mips? ( ^^ ( gtk qt motif ) ) )"
+</para>
+<para>
+Please note that the AND operator is of course supported- if to enable client you must choose at least one gui and enable the python bindings the syntax would be:
+</para>
+<para>
+REQUIRED_USE="client? ( python || ( gtk qt motif x11 ) )"</para>
+<para>
+Finally, please note that this new metadata key can be set by eclasses, and the inherit implementation should protect the eclass set value just the same as how eclass defined DEPEND is protected.
+</para>
+</section>
+</section>
+</section>
 </section>