diff options
author | Adam J. Stewart <ajstewart426@gmail.com> | 2016-10-21 09:49:36 -0500 |
---|---|---|
committer | Todd Gamblin <tgamblin@llnl.gov> | 2016-10-21 07:49:36 -0700 |
commit | 52158d9316aabd9c02a719825928607cb5204377 (patch) | |
tree | 88313eb2c64a939e7fe6cc1ee3dd8522b3490824 /lib | |
parent | c513fd72fb0face2fd3504a9df408ff50beb00d3 (diff) | |
download | spack-52158d9316aabd9c02a719825928607cb5204377.tar.gz spack-52158d9316aabd9c02a719825928607cb5204377.tar.bz2 spack-52158d9316aabd9c02a719825928607cb5204377.tar.xz spack-52158d9316aabd9c02a719825928607cb5204377.zip |
Add new Version property to handle joined version numbers (#2062)
* Add new version property to handle joined version numbers
* Add unit test for new joined property
* Add documentation on version.up_to() and version.joined
Diffstat (limited to 'lib')
-rw-r--r-- | lib/spack/docs/packaging_guide.rst | 59 | ||||
-rw-r--r-- | lib/spack/spack/test/versions.py | 1 | ||||
-rw-r--r-- | lib/spack/spack/version.py | 4 |
3 files changed, 47 insertions, 17 deletions
diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst index efd4c459a2..bf5763f4f8 100644 --- a/lib/spack/docs/packaging_guide.rst +++ b/lib/spack/docs/packaging_guide.rst @@ -526,32 +526,57 @@ in the package. For example, Spack is smart enough to download version ``8.2.1.`` of the ``Foo`` package above from ``http://example.com/foo-8.2.1.tar.gz``. -If spack *cannot* extrapolate the URL from the ``url`` field by -default, you can write your own URL generation algorithm in place of -the ``url`` declaration. For example: +If the URL is particularly complicated or changes based on the release, +you can override the default URL generation algorithm by defining your +own ``url_for_version()`` function. For example, the developers of HDF5 +keep changing the archive layout, so the ``url_for_version()`` function +looks like: + +.. literalinclude:: ../../../var/spack/repos/builtin/packages/hdf5/package.py + :pyobject: Hdf5.url_for_version + +With the use of this ``url_for_version()``, Spack knows to download HDF5 ``1.8.16`` +from ``http://www.hdfgroup.org/ftp/HDF5/releases/hdf5-1.8.16/src/hdf5-1.8.16.tar.gz`` +but download HDF5 ``1.10.0`` from ``http://www.hdfgroup.org/ftp/HDF5/releases/hdf5-1.10/hdf5-1.10.0/src/hdf5-1.10.0.tar.gz``. + +You'll notice that HDF5's ``url_for_version()`` function makes use of a special +``Version`` function called ``up_to()``. When you call ``version.up_to(2)`` on a +version like ``1.10.0``, it returns ``1.10``. ``version.up_to(1)`` would return +``1``. This can be very useful for packages that place all ``X.Y.*`` versions in +a single directory and then places all ``X.Y.Z`` versions in a subdirectory. + +There are a few ``Version`` properties you should be aware of. We generally +prefer numeric versions to be separated by dots for uniformity, but not all +tarballs are named that way. For example, ``icu4c`` separates its major and minor +versions with underscores, like ``icu4c-57_1-src.tgz``. The value ``57_1`` can be +obtained with the use of the ``version.underscored`` property. Note that Python +properties don't need parentheses. There are other separator properties as well: + +=================== ====== +Property Result +=================== ====== +version.dotted 1.2.3 +version.dashed 1-2-3 +version.underscored 1_2_3 +version.joined 123 +=================== ====== -.. code-block:: python - :linenos: +.. note:: - class Foo(Package): - version('8.2.1', '4136d7b4c04df68b686570afa26988ac') - ... - def url_for_version(self, version): - return 'http://example.com/version_%s/foo-%s.tar.gz' \ - % (version, version) - ... + Python properties don't need parentheses. ``version.dashed`` is correct. + ``version.dashed()`` is incorrect. -If a URL cannot be derived systematically, you can add an explicit URL -for a particular version: +If a URL cannot be derived systematically, or there is a special URL for one +of its versions, you can add an explicit URL for a particular version: .. code-block:: python version('8.2.1', '4136d7b4c04df68b686570afa26988ac', url='http://example.com/foo-8.2.1-special-version.tar.gz') -For the URL above, you might have to add an explicit URL because the -version can't simply be substituted in the original ``url`` to -construct the new one for ``8.2.1``. +This is common for Python packages that download from PyPi. Since newer +download URLs often contain a unique hash for each version, there is no +way to guess the URL systematically. When you supply a custom URL for a version, Spack uses that URL *verbatim* and does not perform extrapolation. diff --git a/lib/spack/spack/test/versions.py b/lib/spack/spack/test/versions.py index 9b4dc29f35..c1d427783c 100644 --- a/lib/spack/spack/test/versions.py +++ b/lib/spack/spack/test/versions.py @@ -392,6 +392,7 @@ class VersionsTest(unittest.TestCase): self.assertEqual(v.dotted, '1.2.3') self.assertEqual(v.dashed, '1-2-3') self.assertEqual(v.underscored, '1_2_3') + self.assertEqual(v.joined, '123') def test_repr_and_str(self): diff --git a/lib/spack/spack/version.py b/lib/spack/spack/version.py index 67a22f4660..0d68a709e8 100644 --- a/lib/spack/spack/version.py +++ b/lib/spack/spack/version.py @@ -146,6 +146,10 @@ class Version(object): def dashed(self): return '-'.join(str(x) for x in self.version) + @property + def joined(self): + return ''.join(str(x) for x in self.version) + def up_to(self, index): """Return a version string up to the specified component, exclusive. e.g., if this is 10.8.2, self.up_to(2) will return '10.8'. |