commit: 01cb58aae249511d25609883166477c6bbda992d
Author: Brian Evans <grknight <AT> gentoo <DOT> org>
AuthorDate: Fri Sep 14 19:37:33 2018 +0000
Commit: Brian Evans <grknight <AT> gentoo <DOT> org>
CommitDate: Wed Oct 24 12:56:36 2018 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=01cb58aa
Move REQUIRED_USE descripton to variables
Instead of having it split on the EAPI page, this allows it
to grow organically in its own section
Signed-off-by: Brian Evans <grknight <AT> gentoo.org>
ebuild-writing/eapi/text.xml | 39 +--------------------
ebuild-writing/variables/text.xml | 71 +++++++++++++++++++++++++++++++++++++--
2 files changed, 70 insertions(+), 40 deletions(-)
diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml
index 3f60d1a..406a562 100644
--- a/ebuild-writing/eapi/text.xml
+++ b/ebuild-writing/eapi/text.xml
@@ -595,45 +595,8 @@ src_install() {
must be enabled (or disabled if it has an exclamation
mark prefix).
</p>
<p>
- Essentially, <c>REQUIRED_USE</c> is an analogue of
<c>DEPEND</c>
- style syntax. For example, to state that some
combination is
- forbidden, i.e. "if <c>foo</c> is set, <c>bar</c> must
be unset":
+ See <uri
link="::ebuild-writing/variables#REQUIRED_USE"/>
</p>
- <codesample lang="ebuild">
-REQUIRED_USE="foo? ( !bar )"
- </codesample>
- <p>
- To state "if <c>foo</c> is set, then at least one of
<c>bar</c>,
- <c>baz</c>, and <c>quux</c> must be activated":
- </p>
- <codesample lang="ebuild">
-REQUIRED_USE="foo? ( || ( bar baz quux ) )"
- </codesample>
- <p>
- To state "exactly one of <c>foo</c>, <c>bar</c>, or
<c>baz</c> must
- be set, but not several":
- </p>
- <codesample lang="ebuild">
-REQUIRED_USE="^^ ( foo bar baz )"
- </codesample>
- <p>
- Note that the last relationship is that of an Exclusive
OR (XOR).
- While an XOR could be formed from usual <c>DEPEND</c>
syntax, a
- specific <c>^^</c> operator has been added for this
case.
- </p>
- <p>
- Finally, to state "at least one of <c>foo</c>,
<c>bar</c>, or
- <c>baz</c> must be set":
- </p>
- <codesample lang="ebuild">
-REQUIRED_USE="|| ( foo bar baz )"
- </codesample>
-
- <important>
- See section
- <uri
link="::general-concepts/use-flags/#conflicting-use-flags" />
- for when (and when not) to use <c>REQUIRED_USE</c>.
- </important>
</li>
<li>
<p><b>REPLACING_VERSIONS and REPLACED_BY_VERSION</b></p>
diff --git a/ebuild-writing/variables/text.xml
b/ebuild-writing/variables/text.xml
index 39aeb76..811d92a 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -216,8 +216,8 @@ The following variables may or must be defined by every
ebuild.
<ti><c>REQUIRED_USE</c></ti>
<ti>
A list of assertions that must be met by the configuration of
- <c>USE</c> flags to be valid for this ebuild. (Requires
- <uri link="::ebuild-writing/eapi/#eapi=4">EAPI>=4</uri>.)
+ <c>USE</c> flags to be valid for this ebuild. (Requires EAPI>=4.)
+ See <uri link="::ebuild-writing/variables#REQUIRED_USE"/>.
</ti>
</tr>
<tr>
@@ -636,5 +636,72 @@ have no direct correlation with the expected string should
be avoided.
</body>
</section>
+<section>
+<title>REQUIRED_USE</title>
+<body>
+<p>
+The <c>REQUIRED_USE</c> variable contains a list of assertions that must be
+met by the configuration of USE flags to be valid for this ebuild. In order
+to be matched, a USE flag in a terminal element must be enabled
+(or disabled if it has an exclamation mark prefix).
+</p>
+
+<p>
+Essentially, <c>REQUIRED_USE</c> is an analogue of <c>DEPEND</c> style syntax.
+For example, to state that some combination is forbidden, i.e. "if foo is
set, bar must be unset":
+</p>
+
+<codesample lang="ebuild">
+REQUIRED_USE="foo? ( !bar )"
+</codesample>
+<p>
+To state "if foo is set, then at least one of bar, baz, and quux must be
activated":
+</p>
+<codesample lang="ebuild">
+REQUIRED_USE="foo? ( || ( bar baz quux ) )"
+</codesample>
+<p>
+To state "exactly one of foo, bar, or baz must be set, but not several":
+</p>
+<codesample lang="ebuild">
+REQUIRED_USE="^^ ( foo bar baz )"
+</codesample>
+<p>
+Note that the last relationship is that of an Exclusive OR (XOR).
+While an XOR could be formed from usual DEPEND syntax,
+a specific ^^ operator has been added for this case.
+</p>
+<p>
+Finally, to state "at least one of foo, bar, or baz must be set":
+</p>
+<codesample lang="ebuild">
+REQUIRED_USE="|| ( foo bar baz )"
+</codesample>
+<important>
+See section <uri link="::general-concepts/use-flags/#conflicting-use-flags" />
+for when (and when not) to use <c>REQUIRED_USE</c>.
+</important>
+
+<subsection>
+<title>EAPI 5</title>
+<body>
+<p>
+EAPI 5 added an additional case to simplify conflicting USE flags.
+</p>
+<p>
+To state "zero or one of foo, bar, or baz must be set, but not several":
+</p>
+<codesample lang="ebuild">
+REQUIRED_USE="?? ( foo bar baz )"
+</codesample>
+<p>In the previous EAPI, this would be the same as:</p>
+<codesample lang="ebuild">
+REQUIRED_USE="foo? ( !bar !baz ) bar? ( !foo !baz ) baz? ( !foo !bar )"
+</codesample>
+</body>
+</subsection>
+</body>
+</section>
+
</chapter>
</guide>
