diff options
| -rw-r--r-- | lib/spack/docs/packaging_guide.rst | 56 |
1 files changed, 30 insertions, 26 deletions
diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst index dbf1c83078..e2e3e297fd 100644 --- a/lib/spack/docs/packaging_guide.rst +++ b/lib/spack/docs/packaging_guide.rst @@ -695,20 +695,23 @@ example, ``py-sphinx-rtd-theme@0.1.10a0``. In this case, numbers are always considered to be "newer" than letters. This is for consistency with `RPM <https://bugzilla.redhat.com/show_bug.cgi?id=50977>`_. -Spack versions may also be arbitrary non-numeric strings; any string -here will suffice; for example, ``@develop``, ``@master``, ``@local``. -Versions are compared as follows. First, a version string is split into -multiple fields based on delimiters such as ``.``, ``-`` etc. Then -matching fields are compared using the rules below: +Spack versions may also be arbitrary non-numeric strings, for example +``@develop``, ``@master``, ``@local``. -#. The following develop-like strings are greater (newer) than all - numbers and are ordered as ``develop > main > master > head > trunk``. +The order on versions is defined as follows. A version string is split +into a list of components based on delimiters such as ``.``, ``-`` etc. +Lists are then ordered lexicographically, where components are ordered +as follows: -#. Numbers are all less than the chosen develop-like strings above, - and are sorted numerically. +#. The following special strings are considered larger than any other + numeric or non-numeric version component, and satisfy the following + order between themselves: ``develop > main > master > head > trunk``. -#. All other non-numeric versions are less than numeric versions, and - are sorted alphabetically. +#. Numbers are ordered numerically, are less than special strings, and + larger than other non-numeric components. + +#. All other non-numeric components are less than numeric components, + and are ordered alphabetically. The logic behind this sort order is two-fold: @@ -729,7 +732,7 @@ Version selection When concretizing, many versions might match a user-supplied spec. For example, the spec ``python`` matches all available versions of the package ``python``. Similarly, ``python@3:`` matches all versions of -Python3. Given a set of versions that match a spec, Spack +Python 3 and above. Given a set of versions that match a spec, Spack concretization uses the following priorities to decide which one to use: @@ -2117,7 +2120,7 @@ Version ranges ^^^^^^^^^^^^^^ Although some packages require a specific version for their dependencies, -most can be built with a range of version. For example, if you are +most can be built with a range of versions. For example, if you are writing a package for a legacy Python module that only works with Python 2.4 through 2.6, this would look like: @@ -2126,9 +2129,9 @@ writing a package for a legacy Python module that only works with Python depends_on('python@2.4:2.6') Version ranges in Spack are *inclusive*, so ``2.4:2.6`` means any version -greater than or equal to ``2.4`` and up to and including ``2.6``. If you -want to specify that a package works with any version of Python 3, this -would look like: +greater than or equal to ``2.4`` and up to and including any ``2.6.x``. If +you want to specify that a package works with any version of Python 3 (or +higher), this would look like: .. code-block:: python @@ -2139,29 +2142,30 @@ requires Python 2, you can similarly leave out the lower bound: .. code-block:: python - depends_on('python@:2.9') + depends_on('python@:2') Notice that we didn't use ``@:3``. Version ranges are *inclusive*, so -``@:3`` means "up to and including 3". +``@:3`` means "up to and including any 3.x version". -What if a package can only be built with Python 2.6? You might be +What if a package can only be built with Python 2.7? You might be inclined to use: .. code-block:: python - depends_on('python@2.6') + depends_on('python@2.7') However, this would be wrong. Spack assumes that all version constraints -are absolute, so it would try to install Python at exactly ``2.6``. The -correct way to specify this would be: +are exact, so it would try to install Python not at ``2.7.18``, but +exactly at ``2.7``, which is a non-existent version. The correct way to +specify this would be: .. code-block:: python - depends_on('python@2.6.0:2.6') + depends_on('python@2.7.0:2.7') -A spec can contain multiple version ranges separated by commas. -For example, if you need Boost 1.59.0 or newer, but there are known -issues with 1.64.0, 1.65.0, and 1.66.0, you can say: +A spec can contain a version list of ranges and individual versions +separated by commas. For example, if you need Boost 1.59.0 or newer, +but there are known issues with 1.64.0, 1.65.0, and 1.66.0, you can say: .. code-block:: python |