Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
View | Details | Raw Unified | Return to bug 353624 | Differences between
and this patch

Collapse All | Expand All

(-)a/ebuild-writing/eapi/text.xml (+41 lines)
Lines 556-561 src_install() { Link Here
556
<body>
556
<body>
557
<ul>
557
<ul>
558
	<li>
558
	<li>
559
		<p><b>REQUIRED_USE</b></p>
560
		<p>
561
			The <c>REQUIRED_USE</c> variable contains a list of assertions that
562
			must be met by the configuration of USE flags to be valid for this
563
			ebuild. In order to be matched, a USE flag in a terminal element
564
			must be enabled (or disabled if it has an exclamation mark prefix).
565
		</p>
566
		<p>
567
			Essentially, <c>REQUIRED_USE</c> is an analogue of <c>DEPEND</c>
568
			style syntax. For example, to state that some combination is
569
			forbidden, i.e. "if <c>foo</c> is set, <c>bar</c> must be unset":
570
		</p>
571
		<codesample lang="ebuild">
572
REQUIRED_USE="foo? ( !bar )"
573
		</codesample>
574
		<p>
575
			To state "if <c>foo</c> is set, then at least one of <c>bar</c>,
576
			<c>baz</c>, and <c>quux</c> must be activated":
577
		</p>
578
		<codesample lang="ebuild">
579
REQUIRED_USE="foo? ( || ( bar baz quux ) )"
580
		</codesample>
581
		<p>
582
			To state "exactly one of <c>foo</c>, <c>bar</c>, or <c>baz</c> must
583
			be set, but not several":
584
		</p>
585
		<codesample lang="ebuild">
586
REQUIRED_USE="^^ ( foo bar baz )"
587
		</codesample>
588
		<p>
589
			Note that the last relationship is that of an Exclusive OR (XOR).
590
			While an XOR could be formed from usual <c>DEPEND</c> syntax, a
591
			specific <c>^^</c> operator has been added for this case.
592
		</p>
593
		<important>
594
			See section
595
			<uri link="::general-concepts/use-flags/#conflicting-use-flags" />
596
			for when (and when not) to use <c>REQUIRED_USE</c>.
597
		</important>
598
	</li>
599
	<li>
559
		<p><b>REPLACING_VERSIONS and REPLACED_BY_VERSION</b></p>
600
		<p><b>REPLACING_VERSIONS and REPLACED_BY_VERSION</b></p>
560
		<p>
601
		<p>
561
			The <c>REPLACING_VERSIONS</c> variable contains a
602
			The <c>REPLACING_VERSIONS</c> variable contains a
(-)a/general-concepts/use-flags/text.xml (-1 / +23 lines)
Lines 210-215 src_compile() { Link Here
210
    emake || die "make failed"
210
    emake || die "make failed"
211
}
211
}
212
</codesample>
212
</codesample>
213
214
<p>
215
	In some exceptional cases, above policy would break reverse USE
216
	dependencies. To avoid this, the ebuild can specify allowed USE flag
217
	combinations with <c>REQUIRED_USE</c> (available in EAPI 4). See section
218
	<uri link="::ebuild-writing/eapi/#eapi=&quot;4&quot;" /> for a description
219
	of its syntax.
220
</p>
221
222
<p>
223
	For example, if a package <c>dev-libs/foo</c> can be built with either
224
	<c>USE="a"</c> or <c>USE="b"</c> but not with both, then preferring one of
225
	the flags would break packages that depend on either <c>dev-libs/foo[a]</c>
226
	or <c>dev-libs/foo[b]</c>. Therefore, the ebuild should specify
227
	<c>REQUIRED_USE="a? ( !b )"</c> in this case.
228
</p>
229
230
<note>
231
	In order to avoid forcing users to micro-manage flags too much,
232
	<c>REQUIRED_USE</c> should be used sparingly. Follow the normal policy
233
	whenever it is possible to do a build that will presumably suit the user's
234
	needs.
235
</note>
213
</body>
236
</body>
214
</section>
237
</section>
215
238
216
- 

Return to bug 353624