Improve 5/2010 and 6/2010

1 files changed, 165 insertions, 0 deletions

diff --git a/decisions/documents.tex b/decisions/documents.tex
index cc8301b..1cfd6c2 100644
--- a/decisions/documents.tex
+++ b/decisions/documents.tex
@@ -414,3 +414,168 @@ Copyright
 This document has been placed in the public domain.
 
 \end{verbatim}}
+
+
+\section{REQUIRED_USE USE state constraints}
+\label{2010-05-feringb-requireduse}
+
+Source: 
+\url{
+https://web.archive.org/web/20100812050720/http://dev.gentoo.org/~ferringb/requi 
+red-use.html}
+\index{developer!feringb}
+
+\vspace*{1cm}
+
+{\small
+\begin{verbatim}
+GLEP:	61
+Title:	REQUIRED_USE USE state constraints
+Version:	1.1
+Author:	Brian Harring <ferringb at gentoo.org>
+Last-Modified:	2010/04/10 17:03:27
+Status:	Draft
+Type:	Standards Track
+Content-Type:	text/x-rst
+Created:	10-April-2010
+Post-History:	10-April-2010
+
+Abstract
+========
+
+This GLEP proposes the addition of a new metadata key to specify what USE flag 
+combinations are disallowed for a specific pkg.
+
+Motivation
+==========
+
+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.
+
+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.
+
+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-
+
+1. The only way to find out if the USE state is disallowed is to run the code
+2. 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.
+3. 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.
+4. 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.
+5. 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.
+
+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.
+
+It's due to this and a few lesser reasons that EAPI4 is strongly recommended as 
+the target for this functionality.
+
+Specification
+=============
+
+Essentially REQUIRED_USE is proposed to be an analogue 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":
+
+REQUIRED_USE="build? ( !python )"
+
+To state "either mysql or sqlite must be set, but not both":
+
+REQUIRED_USE="mysql? ( !sqlite ) !mysql? ( sqlite )"
+
+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:
+
+REQUIRED_USE="^^ ( mysql sqlite )"
+
+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:
+
+REQUIRED_USE="client? ( ^^ ( gtk qt motif ) )"
+
+If the pkg is implemented sanely and requires at least one gui, but can support 
+multiple it would be:
+
+REQUIRED_USE="client? ( || ( gtk qt motif ) )"
+
+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":
+
+REQUIRED_USE="client? ( !mips? ( || (  gtk qt motif ) ) mips? ( ^^ ( gtk qt 
+motif ) ) )"
+
+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:
+
+REQUIRED_USE="client? ( python || ( gtk qt motif x11 ) )"
+
+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.
+Implementation
+
+Implementing this for EAPI4, currently 'few' (Sebastion Luther) has a working 
+git branch available at [portage-implementation] implementing this 
+functionality.
+
+For getting this implemented in pkgcore, the author of the glep will handle it. 
+As for paludis, presumably they can manage it due to MYOPTIONS existing in 
+exheres already.
+
+Backwards Compatibility
+=======================
+
+EAPI already makes this a non issue for backwards compatibility. Additionally 
+the rsync metadata caches (enumerated flat file format) is designed for key 
+expansion so there is no issue there either.
+
+References
+==========
+
+Original ML proposal: 
+http://archives.gentoo.org/gentoo-dev/msg_b0e868626019f497eba47194c34e5421.xml
+[portage-implementation]	
+http://github.com/few/fews-portage-branch/tree/REQUIRED_USE
+
+Thanks to
+=========
+
+David Leverton, Brian Dolbec, and Jorge Manuel Vicetto for proofreading this and 
+correcting the innumerable typos, run on sentences and general abuse of english 
+the GLEP author is known for.
+
+Additionally, many thanks to Sebastion Luther ('few') for stepping up and 
+writing the portage patch on short notice.
+
+Copyright
+=========
+
+This document has been placed in the public domain.
+\end{verbatim}
+}
+