diff options
| -rw-r--r-- | ebuild-writing/variables/text.xml | 20 | ||||
| -rw-r--r-- | function-reference/text.xml | 1 | ||||
| -rw-r--r-- | function-reference/version-functions/text.xml | 219 | ||||
| -rw-r--r-- | 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} |