Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!

Bug 353624

Summary: Corrections and updates for EAPI 4
Product: Documentation Reporter: Ulrich Müller <ulm>
Component: DevmanualAssignee: Gentoo Quality Assurance Team <qa>
Status: RESOLVED FIXED    
Severity: normal CC: darkside
Priority: High    
Version: unspecified   
Hardware: All   
OS: Linux   
Whiteboard:
Package list:
Runtime testing required: ---
Attachments: 0001-docompress-Update-description.patch
0002-AA-and-KV-Refer-to-the-variables-not-their-value.patch
0003-EAPI-4-Describe-REPLACING_VERSIONS-and-REPLACED_BY_V.patch
0004-EAPI-4-Describe-MERGE_TYPE.patch
0001-EAPI-4-Describe-REQUIRED_USE-bug-353624.patch

Description Ulrich Müller gentoo-dev 2011-02-03 16:22:48 UTC
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.
Comment 1 Ulrich Müller gentoo-dev 2011-02-03 16:23:32 UTC
Created attachment 261421 [details, diff]
0001-docompress-Update-description.patch
Comment 2 Ulrich Müller gentoo-dev 2011-02-03 16:23:49 UTC
Created attachment 261422 [details, diff]
0002-AA-and-KV-Refer-to-the-variables-not-their-value.patch
Comment 3 Ulrich Müller gentoo-dev 2011-02-03 16:24:08 UTC
Created attachment 261423 [details, diff]
0003-EAPI-4-Describe-REPLACING_VERSIONS-and-REPLACED_BY_V.patch
Comment 4 Ulrich Müller gentoo-dev 2011-02-03 16:24:22 UTC
Created attachment 261425 [details, diff]
0004-EAPI-4-Describe-MERGE_TYPE.patch
Comment 5 Jeremy Olexa (darkside) (RETIRED) archtester gentoo-dev Security 2011-02-03 16:34:43 UTC
Thank you! pushed.
Comment 6 Vlastimil Babka (Caster) (RETIRED) gentoo-dev 2011-02-03 16:52:45 UTC
Since this bug is about EAPI 4 in general, let's reopen it for REQUIRED_USE ?
Comment 7 Ulrich Müller gentoo-dev 2011-02-04 12:24:34 UTC
(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?
Comment 8 Ulrich Müller gentoo-dev 2011-02-20 15:25:35 UTC
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.
Comment 9 Ulrich Müller gentoo-dev 2011-03-03 08:07:18 UTC
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.
Comment 10 Jeremy Olexa (darkside) (RETIRED) archtester gentoo-dev Security 2011-03-30 14:18:34 UTC
(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?
Comment 11 Ulrich Müller gentoo-dev 2011-03-30 22:48:10 UTC
(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.)