From 007f02e06acf22433f3110882ad5d1ec6660ab55 Mon Sep 17 00:00:00 2001 From: Tamara Dahlgren <35777542+tldahlgren@users.noreply.github.com> Date: Thu, 7 Sep 2023 19:45:51 -0700 Subject: Docs/Packaging guide: Add BundlePackage (#39691) * Docs/Packaging guide: Add BundlePackage * Adjusted version ordering note to reflect convention. --- lib/spack/docs/build_systems/bundlepackage.rst | 29 ++++++++++-- lib/spack/docs/packaging_guide.rst | 63 ++++++++++++++++++++++---- 2 files changed, 80 insertions(+), 12 deletions(-) (limited to 'lib') diff --git a/lib/spack/docs/build_systems/bundlepackage.rst b/lib/spack/docs/build_systems/bundlepackage.rst index ca2be81240..323a13d472 100644 --- a/lib/spack/docs/build_systems/bundlepackage.rst +++ b/lib/spack/docs/build_systems/bundlepackage.rst @@ -9,9 +9,32 @@ Bundle ------ -``BundlePackage`` represents a set of packages that are expected to work well -together, such as a collection of commonly used software libraries. The -associated software is specified as bundle dependencies. +``BundlePackage`` represents a set of packages that are expected to work +well together, such as a collection of commonly used software libraries. +The associated software is specified as dependencies. + +If it makes sense, variants, conflicts, and requirements can be added to +the package. :ref:`Variants ` ensure that common build options +are consistent across the packages supporting them. :ref:`Conflicts +and requirements ` 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 `_ +* `EcpProxyApps `_ +* `Libc `_ +* `Xsdk `_ + +where ``Xsdk`` also inherits from ``CudaPackage`` and ``RocmPackage`` and +``Libc`` is a virtual bundle package for the C standard library. ^^^^^^^^ diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst index a568e0f7d2..f433996ec7 100644 --- a/lib/spack/docs/packaging_guide.rst +++ b/lib/spack/docs/packaging_guide.rst @@ -363,6 +363,42 @@ one of these:: If Spack finds none of these variables set, it will look for ``vim``, ``vi``, ``emacs``, ``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 `. +Examples where bundle packages can be useful include defining suites of +applications (e.g, `EcpProxyApps +`_), commonly used libraries +(e.g., `AmdAocl `_), +and software development kits (e.g., `EcpDataVisSdk `_). + +These versioned packages primarily consist of dependencies on the associated +software packages. They can include :ref:`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 `. +Build requirements, such as only building with specific compilers, can similarly +be flagged with :ref:`requires `. + +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 ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -610,7 +646,16 @@ add a line like this in the package class: version("8.2.0", md5="1c9f62f0778697a09d36121ead88e08e") 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 ` 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 @@ -2678,7 +2723,7 @@ Conflicts and requirements -------------------------- 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. Adding the following to a package: @@ -5246,8 +5291,8 @@ Saving build-time files We highly recommend re-using build-time test sources and pared down input files for testing installed software. These files are easier to keep synchronized with software capabilities since they reside - within the software's repository. - + within the software's repository. + If that is not possible, you can add test-related files to the package repository (see :ref:`adding custom files `). It will be important to maintain them so they work across listed or supported @@ -5268,7 +5313,7 @@ where each argument has the following meaning: * ``pkg`` is an instance of the package for the spec under test. * ``srcs`` is a string *or* a list of strings corresponding to the - paths of subdirectories and or files needed for stand-alone testing. + paths of subdirectories and or files needed for stand-alone testing. The paths must be relative to the staged source directory. Contents of subdirectories and files are copied to a special test cache subdirectory @@ -5411,7 +5456,7 @@ Reading expected output from a file The helper function ``get_escaped_text_output`` is available for packages to retrieve and properly format the text from a file that contains the -expected output from running an executable that may contain special +expected output from running an executable that may contain special characters. The signature for ``get_escaped_text_output`` is: @@ -5458,7 +5503,7 @@ source code, the path would be obtained as shown below. db_filename = test_cache_dir.join("packages.db") Alternatively, if the file was copied to the ``share/tests`` subdirectory -as part of the installation process, the test could access the path as +as part of the installation process, the test could access the path as follows: .. code-block:: python @@ -5555,7 +5600,7 @@ Inheriting stand-alone tests Stand-alone tests defined in parent (.e.g., :ref:`build-systems`) and virtual (e.g., :ref:`virtual-dependencies`) packages are executed by packages that inherit from or provide interface implementations for those -packages, respectively. +packages, respectively. The table below summarizes the stand-alone tests that will be executed along with those implemented in the package itself. @@ -5625,7 +5670,7 @@ for ``openmpi``: SKIPPED: test_version_oshcc: oshcc is not installed ... ==> [2023-03-10-16:04:02.215227] Completed testing - ==> [2023-03-10-16:04:02.215597] + ==> [2023-03-10-16:04:02.215597] ======================== SUMMARY: openmpi-4.1.4-ubmrigj ======================== Openmpi::test_bin_mpirun .. PASSED Openmpi::test_bin_ompi_info .. PASSED -- cgit v1.2.3-60-g2f50