| 1 |
commit: 01cb58aae249511d25609883166477c6bbda992d |
| 2 |
Author: Brian Evans <grknight <AT> gentoo <DOT> org> |
| 3 |
AuthorDate: Fri Sep 14 19:37:33 2018 +0000 |
| 4 |
Commit: Brian Evans <grknight <AT> gentoo <DOT> org> |
| 5 |
CommitDate: Wed Oct 24 12:56:36 2018 +0000 |
| 6 |
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=01cb58aa |
| 7 |
|
| 8 |
Move REQUIRED_USE descripton to variables |
| 9 |
|
| 10 |
Instead of having it split on the EAPI page, this allows it |
| 11 |
to grow organically in its own section |
| 12 |
|
| 13 |
Signed-off-by: Brian Evans <grknight <AT> gentoo.org> |
| 14 |
|
| 15 |
ebuild-writing/eapi/text.xml | 39 +-------------------- |
| 16 |
ebuild-writing/variables/text.xml | 71 +++++++++++++++++++++++++++++++++++++-- |
| 17 |
2 files changed, 70 insertions(+), 40 deletions(-) |
| 18 |
|
| 19 |
diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml |
| 20 |
index 3f60d1a..406a562 100644 |
| 21 |
--- a/ebuild-writing/eapi/text.xml |
| 22 |
+++ b/ebuild-writing/eapi/text.xml |
| 23 |
@@ -595,45 +595,8 @@ src_install() { |
| 24 |
must be enabled (or disabled if it has an exclamation mark prefix). |
| 25 |
</p> |
| 26 |
<p> |
| 27 |
- Essentially, <c>REQUIRED_USE</c> is an analogue of <c>DEPEND</c> |
| 28 |
- style syntax. For example, to state that some combination is |
| 29 |
- forbidden, i.e. "if <c>foo</c> is set, <c>bar</c> must be unset": |
| 30 |
+ See <uri link="::ebuild-writing/variables#REQUIRED_USE"/> |
| 31 |
</p> |
| 32 |
- <codesample lang="ebuild"> |
| 33 |
-REQUIRED_USE="foo? ( !bar )" |
| 34 |
- </codesample> |
| 35 |
- <p> |
| 36 |
- To state "if <c>foo</c> is set, then at least one of <c>bar</c>, |
| 37 |
- <c>baz</c>, and <c>quux</c> must be activated": |
| 38 |
- </p> |
| 39 |
- <codesample lang="ebuild"> |
| 40 |
-REQUIRED_USE="foo? ( || ( bar baz quux ) )" |
| 41 |
- </codesample> |
| 42 |
- <p> |
| 43 |
- To state "exactly one of <c>foo</c>, <c>bar</c>, or <c>baz</c> must |
| 44 |
- be set, but not several": |
| 45 |
- </p> |
| 46 |
- <codesample lang="ebuild"> |
| 47 |
-REQUIRED_USE="^^ ( foo bar baz )" |
| 48 |
- </codesample> |
| 49 |
- <p> |
| 50 |
- Note that the last relationship is that of an Exclusive OR (XOR). |
| 51 |
- While an XOR could be formed from usual <c>DEPEND</c> syntax, a |
| 52 |
- specific <c>^^</c> operator has been added for this case. |
| 53 |
- </p> |
| 54 |
- <p> |
| 55 |
- Finally, to state "at least one of <c>foo</c>, <c>bar</c>, or |
| 56 |
- <c>baz</c> must be set": |
| 57 |
- </p> |
| 58 |
- <codesample lang="ebuild"> |
| 59 |
-REQUIRED_USE="|| ( foo bar baz )" |
| 60 |
- </codesample> |
| 61 |
- |
| 62 |
- <important> |
| 63 |
- See section |
| 64 |
- <uri link="::general-concepts/use-flags/#conflicting-use-flags" /> |
| 65 |
- for when (and when not) to use <c>REQUIRED_USE</c>. |
| 66 |
- </important> |
| 67 |
</li> |
| 68 |
<li> |
| 69 |
<p><b>REPLACING_VERSIONS and REPLACED_BY_VERSION</b></p> |
| 70 |
|
| 71 |
diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml |
| 72 |
index 39aeb76..811d92a 100644 |
| 73 |
--- a/ebuild-writing/variables/text.xml |
| 74 |
+++ b/ebuild-writing/variables/text.xml |
| 75 |
@@ -216,8 +216,8 @@ The following variables may or must be defined by every ebuild. |
| 76 |
<ti><c>REQUIRED_USE</c></ti> |
| 77 |
<ti> |
| 78 |
A list of assertions that must be met by the configuration of |
| 79 |
- <c>USE</c> flags to be valid for this ebuild. (Requires |
| 80 |
- <uri link="::ebuild-writing/eapi/#eapi=4">EAPI>=4</uri>.) |
| 81 |
+ <c>USE</c> flags to be valid for this ebuild. (Requires EAPI>=4.) |
| 82 |
+ See <uri link="::ebuild-writing/variables#REQUIRED_USE"/>. |
| 83 |
</ti> |
| 84 |
</tr> |
| 85 |
<tr> |
| 86 |
@@ -636,5 +636,72 @@ have no direct correlation with the expected string should be avoided. |
| 87 |
</body> |
| 88 |
</section> |
| 89 |
|
| 90 |
+<section> |
| 91 |
+<title>REQUIRED_USE</title> |
| 92 |
+<body> |
| 93 |
+<p> |
| 94 |
+The <c>REQUIRED_USE</c> variable contains a list of assertions that must be |
| 95 |
+met by the configuration of USE flags to be valid for this ebuild. In order |
| 96 |
+to be matched, a USE flag in a terminal element must be enabled |
| 97 |
+(or disabled if it has an exclamation mark prefix). |
| 98 |
+</p> |
| 99 |
+ |
| 100 |
+<p> |
| 101 |
+Essentially, <c>REQUIRED_USE</c> is an analogue of <c>DEPEND</c> style syntax. |
| 102 |
+For example, to state that some combination is forbidden, i.e. "if foo is set, bar must be unset": |
| 103 |
+</p> |
| 104 |
+ |
| 105 |
+<codesample lang="ebuild"> |
| 106 |
+REQUIRED_USE="foo? ( !bar )" |
| 107 |
+</codesample> |
| 108 |
+<p> |
| 109 |
+To state "if foo is set, then at least one of bar, baz, and quux must be activated": |
| 110 |
+</p> |
| 111 |
+<codesample lang="ebuild"> |
| 112 |
+REQUIRED_USE="foo? ( || ( bar baz quux ) )" |
| 113 |
+</codesample> |
| 114 |
+<p> |
| 115 |
+To state "exactly one of foo, bar, or baz must be set, but not several": |
| 116 |
+</p> |
| 117 |
+<codesample lang="ebuild"> |
| 118 |
+REQUIRED_USE="^^ ( foo bar baz )" |
| 119 |
+</codesample> |
| 120 |
+<p> |
| 121 |
+Note that the last relationship is that of an Exclusive OR (XOR). |
| 122 |
+While an XOR could be formed from usual DEPEND syntax, |
| 123 |
+a specific ^^ operator has been added for this case. |
| 124 |
+</p> |
| 125 |
+<p> |
| 126 |
+Finally, to state "at least one of foo, bar, or baz must be set": |
| 127 |
+</p> |
| 128 |
+<codesample lang="ebuild"> |
| 129 |
+REQUIRED_USE="|| ( foo bar baz )" |
| 130 |
+</codesample> |
| 131 |
+<important> |
| 132 |
+See section <uri link="::general-concepts/use-flags/#conflicting-use-flags" /> |
| 133 |
+for when (and when not) to use <c>REQUIRED_USE</c>. |
| 134 |
+</important> |
| 135 |
+ |
| 136 |
+<subsection> |
| 137 |
+<title>EAPI 5</title> |
| 138 |
+<body> |
| 139 |
+<p> |
| 140 |
+EAPI 5 added an additional case to simplify conflicting USE flags. |
| 141 |
+</p> |
| 142 |
+<p> |
| 143 |
+To state "zero or one of foo, bar, or baz must be set, but not several": |
| 144 |
+</p> |
| 145 |
+<codesample lang="ebuild"> |
| 146 |
+REQUIRED_USE="?? ( foo bar baz )" |
| 147 |
+</codesample> |
| 148 |
+<p>In the previous EAPI, this would be the same as:</p> |
| 149 |
+<codesample lang="ebuild"> |
| 150 |
+REQUIRED_USE="foo? ( !bar !baz ) bar? ( !foo !baz ) baz? ( !foo !bar )" |
| 151 |
+</codesample> |
| 152 |
+</body> |
| 153 |
+</subsection> |
| 154 |
+</body> |
| 155 |
+</section> |
| 156 |
+ |
| 157 |
</chapter> |
| 158 |
</guide> |
Archives