commit: 571dd5d10072e7ce6b7126187be454d8891aff16
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Wed Jun 5 13:42:31 2024 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Jul 5 19:59:05 2024 +0000
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=571dd5d1
function-reference/version-functions: New chapter
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
ebuild-writing/variables/text.xml | 20 +--
function-reference/text.xml | 1 +
function-reference/version-functions/text.xml | 219 ++++++++++++++++++++++++++
general-concepts/portage-cache/text.xml | 6 +-
4 files changed, 229 insertions(+), 17 deletions(-)
diff --git a/ebuild-writing/variables/text.xml
b/ebuild-writing/variables/text.xml
index 97e5995..06c92bf 100644
--- a/ebuild-writing/variables/text.xml
+++ b/ebuild-writing/variables/text.xml
@@ -767,14 +767,11 @@ expecting a tarball named <c>Foo-1.2-3b.tar.bz2</c>.
Rather than hard coding the
it is preferable to make <c>MY_PN</c>, <c>MY_PV</c> and <c>MY_P</c> variables
and use those to define the
upstream naming.
EAPI=7 debuted a new set of functions, ver_cut, ver_rs and ver_test.
-These were backported into older EAPIs with the <c>eapi7-ver</c> eclass.
The easy way of redefining the version, which should be used unless you are
sure
you know what you are doing, is to use these functions:
</p>
<codesample lang="ebuild">
-inherit eapi7-ver
-
MY_PN="Foo"
# Replace the second period separator in PV with -
MY_PV=$(ver_rs 2 '-')
@@ -787,24 +784,21 @@ switches to a format like <c>Foo-1.3-4.5.tar.bz2</c>
(yes, this really happens).
</p>
<p>
-It is also possible to use bash substitution to achieve the same effect (this
is
-how eapi7-ver works internally), but this is complicated, error prone and hard
-to read.
+It is also possible to use bash substitution to achieve the same effect, but
+this is complicated, error-prone and hard to read.
</p>
<p>
Some ebuilds use calls to <c>sed</c>, <c>awk</c> and / or <c>cut</c> to do
this.
This must <e>not</e> be done for any new code and should be fixed to use
-built-in version manipulation commands (for EAPI 7 or later), Bash
substitution,
-or in older EAPIs before 7, <c>eapi7-ver</c>. Global scope non-Bash code is
-<e>strongly</e> discouraged.
+the built-in version manipulation commands or Bash substitution. Global scope
+non-Bash code is <e>strongly</e> discouraged.
</p>
<p>
-The ver_ functions are used extract particular components
-from a version string. See <c>man eapi7-ver.eclass</c> and the eclass source
code
-for further documentation and examples. A brief summary of the functions
-follows.
+The <c>ver_</c> functions are used extract particular components from a version
+string. See <uri link="::function-reference/version-functions/"/> for further
+documentation and examples. A brief summary of the functions follows.
</p>
<table>
diff --git a/function-reference/text.xml b/function-reference/text.xml
index d8e844f..efabc3d 100644
--- a/function-reference/text.xml
+++ b/function-reference/text.xml
@@ -23,5 +23,6 @@ The following functions are available for use in ebuilds:
<include href="message-functions/"/>
<include href="query-functions/"/>
<include href="sandbox-functions/"/>
+<include href="version-functions/"/>
</guide>
diff --git a/function-reference/version-functions/text.xml
b/function-reference/version-functions/text.xml
new file mode 100644
index 0000000..bf05ccc
--- /dev/null
+++ b/function-reference/version-functions/text.xml
@@ -0,0 +1,219 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<guide self="function-reference/version-functions/">
+<chapter>
+<title>Version functions reference</title>
+<body>
+
+<p>
+EAPI 7 introduced three commands for common version number operations:
+</p>
+
+<ul>
+ <li><c>ver_cut</c> obtains substrings of a version string</li>
+ <li><c>ver_rs</c> replaces separators in a version string</li>
+ <li><c>ver_test</c> compares two versions</li>
+</ul>
+</body>
+
+<section>
+<title>Version strings</title>
+<body>
+
+<p>
+The functions support arbitrary version strings consisting of version
+components interspersed with (possibly empty) version separators.
+</p>
+
+<p>
+A version component can either consist purely of digits (<c>[0-9]+</c>) or
+purely of uppercase and lowercase letters (<c>[A-Za-z]+</c>). A version
+separator is either a string of any other characters (<c>[^A-Za-z0-9]+</c>),
+or it occurs at the transition between a sequence of letters and a sequence
+of digits, or vice versa. In the latter case, the version separator is an
+empty string.
+</p>
+
+<p>
+The version is processed left-to-right, and each successive component is
+assigned numbers starting with 1. The components are either split on version
+separators or on boundaries between digits and letters (in which case the
+separator between the components is empty). Version separators are assigned
+numbers starting with 1 for the separator between 1st and 2nd components.
+As a special case, if the version string starts with a separator, it is
+assigned index 0.
+</p>
+
+<p>
+Examples:
+</p>
+
+<table>
+ <tr>
+ <th>Type</th>
+ <th>s</th>
+ <th>c</th>
+ <th>s</th>
+ <th>c</th>
+ <th>s</th>
+ <th>c</th>
+ <th>s</th>
+ <th>c</th>
+ <th>s</th>
+ <th>c</th>
+ </tr>
+ <tr>
+ <th>Index</th>
+ <th>0</th>
+ <th>1</th>
+ <th>1</th>
+ <th>2</th>
+ <th>2</th>
+ <th>3</th>
+ <th>3</th>
+ <th>4</th>
+ <th>4</th>
+ <th>5</th>
+ </tr>
+ <tr>
+ <ti><c>1.2.3</c></ti>
+ <ti/>
+ <ti><c>1</c></ti>
+ <ti><c>.</c></ti>
+ <ti><c>2</c></ti>
+ <ti><c>.</c></ti>
+ <ti><c>3</c></ti>
+ <ti/>
+ <ti/>
+ <ti/>
+ <ti/>
+ </tr>
+ <tr>
+ <ti><c>1.2b_alpha4</c></ti>
+ <ti/>
+ <ti><c>1</c></ti>
+ <ti><c>.</c></ti>
+ <ti><c>2</c></ti>
+ <ti/>
+ <ti><c>b</c></ti>
+ <ti><c>_</c></ti>
+ <ti><c>alpha</c></ti>
+ <ti/>
+ <ti><c>4</c></ti>
+ </tr>
+ <tr>
+ <ti><c>.11.</c></ti>
+ <ti><c>.</c></ti>
+ <ti><c>11</c></ti>
+ <ti><c>.</c></ti>
+ <ti/>
+ <ti/>
+ <ti/>
+ <ti/>
+ <ti/>
+ <ti/>
+ <ti/>
+ </tr>
+</table>
+
+</body>
+</section>
+
+<section>
+<title>Ranges</title>
+<body>
+
+<p>
+A range can be specified as <e>m</e> for the <e>m</e>th version component,
+<e>m-</e> for all components starting with <e>m</e>th, or <e>m-n</e>
+for components starting at <e>m</e>th and ending at <e>n</e>th (inclusive).
+If the range spans outside the version string, it is silently truncated.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Functions</title>
+<body>
+
+<table>
+ <tr>
+ <th>
+ Function
+ </th>
+ <th>
+ Usage
+ </th>
+ <th>
+ Description
+ </th>
+ </tr>
+ <tr>
+ <ti>
+ <c>ver_cut</c>
+ </ti>
+ <ti>
+ <e>range</e> [<e>version</e>]
+ </ti>
+ <ti>
+ <p>
+ Print the substring of the version string containing components defined
+ by the <e>range</e> and the version separators between them. Processes
+ <e>version</e> if specified, <c>${PV}</c> otherwise.
+ </p>
+ <p>
+ See the introductory section for the syntax of versions and ranges.
+ </p>
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ <c>ver_rs</c>
+ </ti>
+ <ti>
+ <e>range repl</e> [<e>range repl</e>...] [<e>version</e>]
+ </ti>
+ <ti>
+ <p>
+ Print the version string after substituting the specified version
+ separators at <e>range</e> with <e>repl</e> (string). Multiple
+ <e>range repl</e> pairs can be specified. Processes <e>version</e>
+ if specified, <c>${PV}</c> otherwise.
+ </p>
+ <p>
+ See the introductory section for the syntax of versions and ranges.
+ </p>
+ </ti>
+ </tr>
+ <tr>
+ <ti>
+ <c>ver_test</c>
+ </ti>
+ <ti>
+ [<e>v1</e>] <e>op v2</e>
+ </ti>
+ <ti>
+ <p>
+ Check if the relation <e>v1 op v2</e> is true. If <e>v1</e> is not
+ specified, default to <c>${PVR}</c>. <e>op</e> can be <c>-gt</c>,
+ <c>-ge</c>, <c>-eq</c>, <c>-ne</c>, <c>-le</c>, or <c>-lt</c>.
+ The operators have their usual meaning as in test(1), i.e. the comparison
+ is true if <e>v1</e> is greater-than, greater-than-or-equal, equal,
+ not-equal, less-than-or-equal, or less-than <e>v2</e>.
+ </p>
+ <p>
+ Both versions <e>v1</e> and <e>v2</e> must conform to the
+ <uri link="https://projects.gentoo.org/pms/8/pms.html#x1-250003.2";>
+ PMS version syntax</uri> (with optional revision parts), and the
+ comparison is performed according to the
+ <uri link="https://projects.gentoo.org/pms/8/pms.html#x1-260003.3";>
+ algorithm specified in the PMS</uri>.
+ </p>
+ </ti>
+ </tr>
+</table>
+
+</body>
+</section>
+</chapter>
+</guide>
diff --git a/general-concepts/portage-cache/text.xml
b/general-concepts/portage-cache/text.xml
index 2b40d26..ad2b391 100644
--- a/general-concepts/portage-cache/text.xml
+++ b/general-concepts/portage-cache/text.xml
@@ -30,13 +30,11 @@ fi
</codesample>
<p>
-However, the following is legal, since <c>eapi7-ver.eclass</c> works upon
-<c>PV</c>, <c>PV</c>, and <c>PN</c> are both static:
+However, the following is legal, since the <c>ver_test</c> function works upon
+<c>PV</c>, and the <c>PV</c> and <c>PN</c> variables are both static:
</p>
<codesample lang="ebuild">
-inherit eapi7-ver
-
if ver_test -ge 7.0 ; then
IUSE="${IUSE} tcltk mzscheme"
DEPEND="${DEPEND}
