Here are 4 patches with corrections and updates. Since they all concern EAPI 4, I'm using a single bug for them. 1. Description of docompress is inaccurate in some points. 2. AA and KV have been removed. ${AA} and ${KV} would refer to their values, not to the variables themselves. 3. REPLACING_VERSIONS and REPLACED_BY_VERSION were missing. 4. MERGE_TYPE was missing.
Created attachment 261421 [details, diff] 0001-docompress-Update-description.patch
Created attachment 261422 [details, diff] 0002-AA-and-KV-Refer-to-the-variables-not-their-value.patch
Created attachment 261423 [details, diff] 0003-EAPI-4-Describe-REPLACING_VERSIONS-and-REPLACED_BY_V.patch
Created attachment 261425 [details, diff] 0004-EAPI-4-Describe-MERGE_TYPE.patch
Thank you! pushed.
Since this bug is about EAPI 4 in general, let's reopen it for REQUIRED_USE ?
(In reply to comment #6) > Since this bug is about EAPI 4 in general, let's reopen it for REQUIRED_USE ? The question is what to recommend about its usage. So far, I had the impression that our policy about conflicting USE flags, as described in <http://devmanual.gentoo.org/general-concepts/use-flags/#conflicting-use-flags>, was still valid: | Occasionally, ebuilds will have conflicting USE flags for functionality. | Checking for them and returning an error is not a viable solution. | Instead, you must pick one of the USE flags in conflict to favour and | should alert the user that a particular flag is being used instead. From that, it would follow that REQUIRED_USE should only be used in exceptional cases, where preference of one USE flag is not a viable solution. (To give an example, for Emacs we prefer "gtk" over "Xaw3d" over "motif" for the toolkit used, following above-mentioned policy. However, for the "X" and "aqua" flags, we've decided that preferring one over the other might be too surprising for the user, so we have a REQUIRED_USE="aqua? ( !X )" for them.) So, can someone confirm that this policy is still in place? Or, if not, when and by whom it was changed?
Following the discussion in gentoo-dev (especially Zac's comments), I'd suggest to add the following to the "Conflicting USE Flags" section: | In some exceptional cases, above policy would break reverse USE | dependencies. To avoid this, the ebuild can specify allowed USE flag | combinations with REQUIRED_USE (available in EAPI 4). | | For example, if dev-libs/foo can be built with either USE="a" or USE="b" | but not with both, then preferring one of the flags would break packages | that depend on either dev-libs/foo[a] or dev-libs/foo[b]. Therefore, the | ebuild should specify REQUIRED_USE="a? ( !b )" in this case. | | Note: In order to avoid forcing users to micro-manage flags too much, | REQUIRED_USE should be used sparingly. Follow the normal policy whenever | it's possible to do a build that will presumably suit the user's needs. And to section "EAPI=4": | REQUIRED_USE | | The REQUIRED_USE 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). | | Essentially REQUIRED_USE is an analogue of DEPEND style syntax. For example, | to state that some combination is forbidden, i.e. "if foo is set, bar must | be unset": | | REQUIRED_USE="foo? ( !bar )" | | To state "if foo is set, then at least one of bar, baz, and quux must be | activated": | | REQUIRED_USE="foo? ( || ( bar baz quux ) )" | | To state "exactly one of foo, bar, or baz must be set, but not several": | | REQUIRED_USE="^^ ( foo bar baz )" | | 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. | | See also section "Conflicting USE Flags" for when (and when not) to use | REQUIRED_USE. I can prepare a patch if there are no objections against this wording.
Created attachment 264565 [details, diff] 0001-EAPI-4-Describe-REQUIRED_USE-bug-353624.patch (In reply to comment #8) > I can prepare a patch if there are no objections against this wording. See attachment.
(In reply to comment #9) > Created attachment 264565 [details, diff] > 0001-EAPI-4-Describe-REQUIRED_USE-bug-353624.patch > > (In reply to comment #8) > > I can prepare a patch if there are no objections against this wording. > > See attachment. pushed, thanks! should the bug be closed yet?
(In reply to comment #10) > pushed, thanks! should the bug be closed yet? No open issues from my side, therefore closing. (If required, it can be reopened.)
