Docs/Packaging guide: Add BundlePackage (#39691)
* Docs/Packaging guide: Add BundlePackage * Adjusted version ordering note to reflect convention.
This commit is contained in:
parent
8ec1657136
commit
007f02e06a
@ -9,9 +9,32 @@
|
|||||||
Bundle
|
Bundle
|
||||||
------
|
------
|
||||||
|
|
||||||
``BundlePackage`` represents a set of packages that are expected to work well
|
``BundlePackage`` represents a set of packages that are expected to work
|
||||||
together, such as a collection of commonly used software libraries. The
|
well together, such as a collection of commonly used software libraries.
|
||||||
associated software is specified as bundle dependencies.
|
The associated software is specified as dependencies.
|
||||||
|
|
||||||
|
If it makes sense, variants, conflicts, and requirements can be added to
|
||||||
|
the package. :ref:`Variants <variants>` ensure that common build options
|
||||||
|
are consistent across the packages supporting them. :ref:`Conflicts
|
||||||
|
and requirements <packaging_conflicts>` prevent attempts to build with known
|
||||||
|
bugs or limitations.
|
||||||
|
|
||||||
|
For example, if ``MyBundlePackage`` is known to only build on ``linux``,
|
||||||
|
it could use the ``require`` directive as follows:
|
||||||
|
|
||||||
|
.. code-block:: python
|
||||||
|
|
||||||
|
require("platform=linux", msg="MyBundlePackage only builds on linux")
|
||||||
|
|
||||||
|
Spack has a number of built-in bundle packages, such as:
|
||||||
|
|
||||||
|
* `AmdAocl <https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/amd-aocl/package.py>`_
|
||||||
|
* `EcpProxyApps <https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/ecp-proxy-apps/package.py>`_
|
||||||
|
* `Libc <https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/libc/package.py>`_
|
||||||
|
* `Xsdk <https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/xsdk/package.py>`_
|
||||||
|
|
||||||
|
where ``Xsdk`` also inherits from ``CudaPackage`` and ``RocmPackage`` and
|
||||||
|
``Libc`` is a virtual bundle package for the C standard library.
|
||||||
|
|
||||||
|
|
||||||
^^^^^^^^
|
^^^^^^^^
|
||||||
|
@ -363,6 +363,42 @@ one of these::
|
|||||||
If Spack finds none of these variables set, it will look for ``vim``, ``vi``, ``emacs``,
|
If Spack finds none of these variables set, it will look for ``vim``, ``vi``, ``emacs``,
|
||||||
``nano``, and ``notepad``, in that order.
|
``nano``, and ``notepad``, in that order.
|
||||||
|
|
||||||
|
^^^^^^^^^^^^^^^^^
|
||||||
|
Bundling software
|
||||||
|
^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
If you have a collection of software expected to work well together with
|
||||||
|
no source code of its own, you can create a :ref:`BundlePackage <bundlepackage>`.
|
||||||
|
Examples where bundle packages can be useful include defining suites of
|
||||||
|
applications (e.g, `EcpProxyApps
|
||||||
|
<https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/ecp-proxy-apps/package.py>`_), commonly used libraries
|
||||||
|
(e.g., `AmdAocl <https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/amd-aocl/package.py>`_),
|
||||||
|
and software development kits (e.g., `EcpDataVisSdk <https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/ecp-data-vis-sdk/package.py>`_).
|
||||||
|
|
||||||
|
These versioned packages primarily consist of dependencies on the associated
|
||||||
|
software packages. They can include :ref:`variants <variants>` to ensure
|
||||||
|
common build options are consistently applied to dependencies. Known build
|
||||||
|
failures, such as not building on a platform or when certain compilers or
|
||||||
|
variants are used, can be flagged with :ref:`conflicts <packaging_conflicts>`.
|
||||||
|
Build requirements, such as only building with specific compilers, can similarly
|
||||||
|
be flagged with :ref:`requires <packaging_conflicts>`.
|
||||||
|
|
||||||
|
The ``spack create --template bundle`` command will create a skeleton
|
||||||
|
``BundlePackage`` ``package.py`` for you:
|
||||||
|
|
||||||
|
.. code-block:: console
|
||||||
|
|
||||||
|
$ spack create --template bundle --name coolsdk
|
||||||
|
|
||||||
|
Now you can fill in the basic package documentation, version(s), and software
|
||||||
|
package dependencies along with any other relevant customizations.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Remember that bundle packages have no software of their own so there
|
||||||
|
is nothing to download.
|
||||||
|
|
||||||
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
Non-downloadable software
|
Non-downloadable software
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
@ -610,7 +646,16 @@ add a line like this in the package class:
|
|||||||
version("8.2.0", md5="1c9f62f0778697a09d36121ead88e08e")
|
version("8.2.0", md5="1c9f62f0778697a09d36121ead88e08e")
|
||||||
version("8.1.2", md5="d47dd09ed7ae6e7fd6f9a816d7f5fdf6")
|
version("8.1.2", md5="d47dd09ed7ae6e7fd6f9a816d7f5fdf6")
|
||||||
|
|
||||||
Versions should be listed in descending order, from newest to oldest.
|
.. note::
|
||||||
|
|
||||||
|
By convention, we list versions in descending order, from newest to oldest.
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
:ref:`Bundle packages <bundlepackage>` do not have source code so
|
||||||
|
there is nothing to fetch. Consequently, their version directives
|
||||||
|
consist solely of the version name (e.g., ``version("202309")``).
|
||||||
|
|
||||||
|
|
||||||
^^^^^^^^^^^^^
|
^^^^^^^^^^^^^
|
||||||
Date Versions
|
Date Versions
|
||||||
@ -2678,7 +2723,7 @@ Conflicts and requirements
|
|||||||
--------------------------
|
--------------------------
|
||||||
|
|
||||||
Sometimes packages have known bugs, or limitations, that would prevent them
|
Sometimes packages have known bugs, or limitations, that would prevent them
|
||||||
to build e.g. against other dependencies or with certain compilers. Spack
|
from building e.g. against other dependencies or with certain compilers. Spack
|
||||||
makes it possible to express such constraints with the ``conflicts`` directive.
|
makes it possible to express such constraints with the ``conflicts`` directive.
|
||||||
|
|
||||||
Adding the following to a package:
|
Adding the following to a package:
|
||||||
|
Loading…
Reference in New Issue
Block a user