Future EAPI/Version syntax changes

From Gentoo Wiki
Jump to:navigation Jump to:search
The syntax used in examples on this page is just an example and is subject to change. Please debate on the concepts, not on the syntax of examples.


bug #598627

Replace the current:

[<operator>] <cat/pkg> [-<version>] [:<slot>] ...
^^^^^^^^^^^^           ^^^^^^^^^^^^


<cat/pkg> [:<slot>] [<operator> <version>]


Old syntax New syntax Notes
dev-foo/bar dev-foo/bar (unchanged)
dev-foo/bar:4 dev-foo/bar:4 (unchanged)
>=dev-foo/bar-4.1 dev-foo/bar>=4.1
>dev-foo/bar-4.1:4 dev-foo/bar:4>4.1
=dev-foo/bar-11 dev-foo/bar==11 (or =, TBD)


  • more readable,
  • easier to edit,
  • easier to validate,
  • easier to split package name from version,
  • better ground for version ranges,
  • in the future, this will allow us to dump restriction on package names not being confusing with versions.


  • Collides with slot operators:
Old syntax New syntax
=dev-foo/bar-4.1:4= dev-foo/bar:4===4.1
>dev-foo/bar-4.1:= dev-foo/bar:=>4.1

Version ranges

bug #4315

Problems to solve

A. Range dependencies vs slotting

Sometimes it is necessary to restrict acceptable versions of a package to a range. This is frequently accomplished using the following syntax:


If the package is slotted, this dependency can actually cause PM to install two versions of the package in different slots, neither of them matching the intended range, e.g. 1.2 (satisfies <1.5) and 1.6 (satisfies >=1.3). For simple slotting, appending correct slot (e.g. :0) fixes that. For fully slotted packages, any-of dependencies are used instead:

|| (


  • verbosity, inconvenience,
  • any-of dep makes it impossible to use :=.

B. Excluding single package versions

Sometimes it is necessary to exclude one or a few versions from a wide range, e.g. due to a bug or temporary incompatibility. This is either achieved using:

|| (
  ( <dev-foo/bar-1.5 >=dev-foo/bar-1.3.2 )
  ( <dev-foo/bar-1.3 >=dev-foo/bar-1.1 )



The former form has the disadvantages of any-of group, the latter of blockers.

Slot-binding dependency groups

The least-change solution to the problem is to introduce an additional dependency group type that forces all conditions in it to be enforced on the same slot:

&& (


  • minimal syntax change,
  • possibility to enforce many different conditions on the matched package without the need to repeat the range (e.g. different sets of USE flags).


  • still verbose, package name repeated needlessly,
  • adding a group requires determining interaction with other groups,
  • solves only problem A.

Arithmetic version ranges

The idea is to use arithmetic notion of ranges:



  • limited to few operators by design,
  • we will probably have to support inclusive and exclusive ranges -- weird syntax,
  • solves only problem A.

Multiple version operator approach

Multiple operator conjunction

Support specifying multiple version restrictions. All of the restrictions must match (i.e. logical AND).



  • solves only problem A,
  • syntax without additional braces looks confusing with slot op :=, e.g. dev-foo/bar:===4.0.

Multiple operator conjunction or disjunction

This is the Exherbo approach. The restriction can be either AND-ed or OR-ed (but not both).



  • expressing two disjoint ranges requires multiple != exclusions,
  • the proposed syntax uses infix operators while most of logic uses prefix (i.e. || ( ... )) (pointed out by [User:Ulm]).

Full-blown logic

Alternatively, we can support AND, OR and nesting.



  • added complexity.

Version suffixes and upper/lower bound problem

Negative suffixes

Versions can be followed by zero or more suffixes, of which _pre, _alpha, _beta and _rc are negative, that is represent version evaluating lower than the preceding version components. It is a cause of somewhat common mistakes.

For example:


matches 1.5_rc1. And:


both do not match 1.5_rc1.

It can be somewhat reasonably solved via appending _alpha suffix (the lowest negative suffix supported):


but see below.

Upper/lower bound

The PMS version syntax has infinite range and precision. There are no formal restrictions on values, lengths or count of version components. The suffixes can be used to infinitely construct versions lower or higher than the base version.

In other words, for each version X, one can always construct a lower version X_pre (X_alpha, X_beta, X_rc) and a newer version X_p. Therefore, it is impossible to fully reliably restrict version, including any possible suffixes. For example:


will still match 1.5_alpha_alpha_rc.

_alpha_alpha is used here and throughout the document as a highly unlikely suffix combination, that evaluates lower to _alpha_pre that could possibly appear on snapshots preceding an alpha release.

Possible solution: explicit lower bound suffix

A possible solution is to include an additional suffix that can not be used in package versions, and always evaluates lower to any possible suffix. Example:


that will match any combination of 1.5_alpha_alpha_alpha...

For completeness, a _max suffix may be considered as well:


However, it is unclear if it should be limited to outgrowing suffixes only (i.e. >_p999999..._p999999....), or also additional version components.

Revision-related operators

Existing: ~ operator

Current status

The existing ~ operator can be used to depend on a specific version of package while allowing for Gentoo-specific revisions to differ.


is equivalent to range:

<dev-foo/bar-1.4.2_p    # smallest next valid version


  • non-symmetry (~ is modification of =, but no variants for <, <=... are provided),
  • inability to further restrict allowed revisions (i.e. v1.4.2, r2+).

Alternative: version ranges

We can possibly replace the ~ operator with explicit version ranges:



  • decreased readability,
  • suffers from the lower-bound problem (_p_pre < _p).

Alternative: regular operators matching only versions, explicit suffixes for revisions

As an additional alternative, it has been considered that we could change the regular version operators <, <=, =, >=, > to match on versions only, ignoring revision. This would make it more in line with upstream dependency specifications. Explicit revision suffix would be necessary to match revisions.

For example:

dev-foo/bar==1.4.0        # version 1.4.0, any revision
dev-foo/bar==1.4.0-r0     # version 1.4.0, r0
dev-foo/bar>1.4.0         # version >1.4.0 (but not a revision of 1.4.0)
dev-foo/bar>1.4.0-r0      # version >1.4.0 or 1.4.0 with r>0
dev-foo/bar<=1.4.0        # version <=1.4.0, including any revision of 1.4.0
dev-foo/bar<=1.4.0-r0     # version <1.4.0, or 1.4.0-r0


  • no new operators,
  • solves end-of-rev-range problem (below) as well.


  • change of behavior on existing operators -- likely to cause confusion and mayhem,
  • different behavior of operator depending on whether revision is specified or not -- even more confusion,
  • still a bit of redundancy (<X <=> <X-r0 and >=X <=> >=X-r0) but less irritating due to no new ops.

Alternative: regular operators matching only versions, additional ops for revisions

The alternative variant of the above, with revision matching explicitly requiring special operators.

dev-foo/bar==1.4.0        # version 1.4.0, any revision
dev-foo/bar===1.4.0-r0    # version 1.4.0, r0
dev-foo/bar>1.4.0         # version >1.4.0 (but not a revision of 1.4.0)
dev-foo/bar>==1.4.0-r1    # version >1.4.0 or 1.4.0 with r>1
dev-foo/bar<=1.4.0        # version <=1.4.0, including any revision of 1.4.0
dev-foo/bar<==1.4.0-r0    # version <1.4.0, or 1.4.0-r0


  • solves end-of-rev-range problem,
  • -r becomes prohibited with normal operators, so it'll more likely blow up verbosely than silently misbehave,
  • proposed weird syntax limits new ops to ===, >== and <== since revisions are integers and so > and >= is pretty much redundant.


  • change of behavior on existing operators -- likely to cause confusion and mayhem,
  • may look kinda weird with additional = switching between version and revision precision,
  • intentional lack of > and < for revisions might get someone confused, trying >= and <= to achieve the same behavior.

Missing: end-of-rev-range operators


Currently we lack a way to express -r9999... that would match all possible revisions of the package. It could be useful with > and < (>= and <= would be equivalent, since the max value is not limited) operators:

>dev-foo/bar-1.4-r9999...      # matches 1.4_p, 1.4.0, 1.5...
<=dev-foo/bar-1.4-r9999...     # matches ~1.4 or less


  • kinda ugly,
  • revision value is not limited and some developers already use 8-digit revisions (dates).

Using next valid version

Alternatively, we can use the next valid version:



  • no extra syntax necessary,
  • always matches all revisions.


  • still ugly-ish,
  • to strictly match any crazy variant possible, we would be always be adding _p e.g. ~1.4_p -> >=1.4_p_p,
  • suffers from the lower bound problem.

Range representation

The <= variant can be represented using range conjunction.


The > variant would require negation of ~:



  • requires only ~ and !~.


  • kinda awkward.

Additional operators

bug #563270

This could be accomplished via adding special >~ and <=~ operators, with ~ indicating match versions without considering revisions:

>~dev-foo/bar-1.4              # version >1.4
<=~dev-foo/bar-1.4             # version <=1.4

(the >=~ and <~ would logically be equivalent to >= and <)


  • may be a bit confusing: >~1.4 looks like it starts with -r0 but it actually does not cover -r9999...,
  • (1.4-r3 <=~ 1.4 <=~ 1.4-r1) is true [but that probably shouldn't be considered since we are comparing versions],
  • ruby uses ~> for another purpose,
  • redundancy or non-symmetry: we can add >=~ and <~ ops, or reduce both to >~ and <~ (in both cases additional confusion possible).

Explicit -rMAX

Alternatively, a special -r value can be added to indicate a value larger than any valid revision.



  • clearly readable.


  • additional magic value that is not valid in versions.

Regular operators matching versions only

Alternative full ~ replacements that solve this problem:

Missing: revision ranges


Sometimes it may be useful to combine ~ with restricting on specific revision range. For example, when upstream requires a specific version and we require a specific revision due to Gentoo fixes. For example:


Additional operators (GLSA solution)

bug #598523

Gentoo GLSAs already specify four additional operators for this specific purpose: rlt, rle, rge, rgt:

<vulnerable range="rle">1.19</vulnerable>
<unaffected range="rge">4.5.2-r5</unaffected>
<unaffected range="rgt">4.4.12</unaffected>

It is unnecessary to include four operators, since in all cases the previous/next revision value is predictable. For symmetry, rle and rge can included:

dev-foo/bar RGE 1.4-r2  # 1.4-r2 .. 1.4-r9999...
dev-foo/bar RLE 1.4-r6  # 1.4 .. 1.4-r6

(note: I didn't have any idea for a fancy symbol for it)


  • additional operators for a seemingly rare case,
  • does not cover non-lower/upper-bound revision ranges (i.e. -r4 .. -r7).

Solution using version ranges

The canonical solution using other operators:



  • no new operators needed.

Component-wide prefix comparison

Existing: =...* operator

Current status

The existing = operator can be used with * wildcard on the end of the version to indicate component-wide prefix comparison.


is equivalent to range:

>=dev-foo/bar-1_alpha_alpha... # this can go on to infinity
<dev-foo/bar-2         # next valid value of the last version component


  • non-symmetry (<, <=... do not support * variants),
  • often confused with wildcard,
  • sometimes confused not to match _pre, _rc... suffixes.

Alternative using version ranges

Alternatively, the same can be expressed using:


or, if matching _alpha_alpha is not desired:



  • more flexible


  • suffers from the lower bound problem.

Missing: <=, >= prefix-wide comparisons


It is sometimes useful to depend on a range of versions starting at the lower or upper bound of a specific prefix. For example:

>=dev-foo/bar-1.4_alpha_alpha   # all 1.4* and newer
<dev-foo/bar-1.5        # all 1.4* and older

The former case suffers from the lower-bound problem, while the latter requires figuring out the correct next version.

Prefix-wise comparison operators

bug #598521

For symmetry, * support could be added to other operators to indicate prefix-wide comparisons, e.g.:

<dev-foo/bar-1.4*      # <=> <dev-foo/bar-1.4_alpha...
<=dev-foo/bar-1.4*     # <=> <=dev-foo/bar-1.4_p....
>=dev-foo/bar-1.4*     # <=> >=dev-foo/bar-1.4_alpha...
>dev-foo/bar-1.4*      # <=> >dev-foo/bar-1.4_p...

This means that the specific comparison is applied to all version components up to the specified part. Or speaking otherwise, it is a union of versions matching =dev-foo/bar-1.4* and </<=/>=/>dev-foo/bar-1.4.


  • solves lower and upper bound problem.


  • potentially confusing,
  • (1.4.2 <= 1.4* <= 1.4.1) is true [but we should be considering prefixes only anyway].

Alternative: version ranges with =...*

The same can be expressed using conjunctive and disjunctive version ranges combined with the =...* and !=...* operator:

dev-foo/bar[>=1.4|==1.4*]     # ==1.4* adds 1.4_alpha...
dev-foo/bar[<=1.4|==1.4*]     # ==1.4* adds 1.4_p...
dev-foo/bar[>1.4&!=1.4*]     # !=1.4* removes 1.4_p...
dev-foo/bar[<1.4&!=1.4*]     # !=1.4* removes 1.4_alpha...


  • more obvious when reading.


  • less obvious to write correctly.

Alternative: version ranges with implicit/explicit lower bound

The more obvious solution is to explicitly use lower (or upper) bound:



  • we're back to lower/upper bound problem.

Missing: prefix match sub-ranges


Sometimes it is necessary to restrict version to a specific prefix, and further restrict the minimal subversion, e.g.:


Ruby ~> operator

Ruby (and Exherbo) use ~> operator for this specific case. It is equivalent to >= on the specified version combined with prefix matching of the version stripped of the last component. For example:


indicates that the version needs to be at least 1.4.2 but in 1.4* range.


  • non-symmetric (is there a use case for < variant?),
  • collides with current meaning of ~,
  • unclear wrt different kinds of versions (letters, suffixes, negative suffixes...).

Alternative: version ranges

Again, this can be implemented using version ranges: