diff options
author | Massimiliano Culpo <massimiliano.culpo@gmail.com> | 2022-03-18 10:41:27 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-03-18 10:41:27 +0100 |
commit | 2fa495154ee8afe33a863c57ba0f9584d2324fd6 (patch) | |
tree | 8639719c1f9450ee666d794cec4d709945426da8 /lib/spack/docs/environments.rst | |
parent | 0ce8b9d3983acaf2469b3b10af8bd1b72798026b (diff) | |
download | spack-2fa495154ee8afe33a863c57ba0f9584d2324fd6.tar.gz spack-2fa495154ee8afe33a863c57ba0f9584d2324fd6.tar.bz2 spack-2fa495154ee8afe33a863c57ba0f9584d2324fd6.tar.xz spack-2fa495154ee8afe33a863c57ba0f9584d2324fd6.zip |
Split the workflow section and remove outdated advices (#29344)
This PR removes a few outdated sections from the "Basics" part of the
documentation. It also makes a few topic under the environment section
more prominent by removing an unneeded spack.yaml subsection and
promoting everything under it.
Diffstat (limited to 'lib/spack/docs/environments.rst')
-rw-r--r-- | lib/spack/docs/environments.rst | 123 |
1 files changed, 75 insertions, 48 deletions
diff --git a/lib/spack/docs/environments.rst b/lib/spack/docs/environments.rst index 4e4a75b88c..b18648006e 100644 --- a/lib/spack/docs/environments.rst +++ b/lib/spack/docs/environments.rst @@ -384,18 +384,11 @@ Sourcing that file in Bash will make the environment available to the user; and can be included in ``.bashrc`` files, etc. The ``loads`` file may also be copied out of the environment, renamed, etc. ----------- -spack.yaml ----------- - -Spack environments can be customized at finer granularity by editing -the ``spack.yaml`` manifest file directly. - .. _environment-configuration: -^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------ Configuring Environments -^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------ A variety of Spack behaviors are changed through Spack configuration files, covered in more detail in the :ref:`configuration` @@ -417,9 +410,9 @@ environment can be specified by ``env:NAME`` (to affect environment ``foo``, set ``--scope env:foo``). These commands will automatically manipulate configuration inline in the ``spack.yaml`` file. -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ Inline configurations -""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^ Inline Environment-scope configuration is done using the same yaml format as standard Spack configuration scopes, covered in the @@ -440,9 +433,9 @@ a ``packages.yaml`` file) could contain: This configuration sets the default compiler for all packages to ``intel``. -""""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^^^ Included configurations -""""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^^^ Spack environments allow an ``include`` heading in their yaml schema. This heading pulls in external configuration files and applies @@ -462,9 +455,9 @@ to make small changes to an individual Environment. Included configs listed earlier will have higher precedence, as the included configs are applied in reverse order. -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------- Manually Editing the Specs List -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------- The list of abstract/root specs in the Environment is maintained in the ``spack.yaml`` manifest under the heading ``specs``. @@ -482,9 +475,9 @@ Appending to this list in the yaml is identical to using the ``spack add`` command from the command line. However, there is more power available from the yaml file. -""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^ Spec concretization -""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^ Specs can be concretized separately or together, as already explained in :ref:`environments_concretization`. The behavior active @@ -510,9 +503,9 @@ which can currently take either one of the two allowed values ``together`` or `` the environment remains consistent. When instead the specs are concretized separately only the new specs will be re-concretized after any addition. -""""""""""""" +^^^^^^^^^^^^^ Spec Matrices -""""""""""""" +^^^^^^^^^^^^^ Entries in the ``specs`` list can be individual abstract specs or a spec matrix. @@ -572,9 +565,9 @@ This allows one to create toolchains out of combinations of constraints and apply them somewhat indiscriminately to packages, without regard for the applicability of the constraint. -"""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^ Spec List References -"""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^ The last type of possible entry in the specs list is a reference. @@ -674,9 +667,9 @@ The valid variables for a ``when`` clause are: #. ``hostname``. The hostname of the system (if ``hostname`` is an executable in the user's PATH). -"""""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^^^^ SpecLists as Constraints -"""""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^^^^ Dependencies and compilers in Spack can be both packages in an environment and constraints on other packages. References to SpecLists @@ -708,33 +701,32 @@ For example, the following environment has three root packages: This allows for a much-needed reduction in redundancy between packages and constraints. -^^^^^^^^^^^^^^^^^^^^^^^^^ -Environment-managed Views -^^^^^^^^^^^^^^^^^^^^^^^^^ +---------------- +Filesystem Views +---------------- -Spack Environments can define filesystem views of their software, -which are maintained as packages and can be installed and uninstalled from -the Environment. Filesystem views provide an access point for packages -from the filesystem for users who want to access those packages -directly. For more information on filesystem views, see the section -:ref:`filesystem-views`. - -Spack Environment managed views are updated every time the environment -is written out to the lock file ``spack.lock``, so the concrete -environment and the view are always compatible. +Spack Environments can define filesystem views, which provide a direct access point +for software similar to the directory hierarchy that might exist under ``/usr/local``. +Filesystem views are updated every time the environment is written out to the lock +file ``spack.lock``, so the concrete environment and the view are always compatible. +The files of the view's installed packages are brought into the view by symbolic or +hard links, referencing the original Spack installation, or by copy. .. _configuring_environment_views: -""""""""""""""""""""""""""""" -Configuring environment views -""""""""""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Configuration in ``spack.yaml`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Spack Environment manifest file has a top-level keyword -``view``. Each entry under that heading is a view descriptor, headed -by a name. The view descriptor contains the root of the view, and +``view``. Each entry under that heading is a **view descriptor**, headed +by a name. Any number of views may be defined under the ``view`` heading. +The view descriptor contains the root of the view, and optionally the projections for the view, ``select`` and ``exclude`` lists for the view and link information via ``link`` and -``link_type``. For example, in the following manifest +``link_type``. + +For example, in the following manifest file snippet we define a view named ``mpis``, rooted at ``/path/to/view`` in which all projections use the package name, version, and compiler name to determine the path for a given @@ -759,8 +751,7 @@ directories. link: all link_type: symlink -For more information on using view projections, see the section on -:ref:`adding_projections_to_views`. The default for the ``select`` and +The default for the ``select`` and ``exclude`` values is to select everything and exclude nothing. The default projection is the default view projection (``{}``). The ``link`` attribute allows the following values: @@ -780,8 +771,6 @@ of ``hardlink`` or ``copy``. when the environment is not activated, and linked libraries will be located *outside* of the view thanks to rpaths. -Any number of views may be defined under the ``view`` heading in a -Spack Environment. There are two shorthands for environments with a single view. If the environment at ``/path/to/env`` has a single view, with a root at @@ -847,9 +836,47 @@ regenerate`` will regenerate the views for the environment. This will apply any updates in the environment configuration that have not yet been applied. -"""""""""""""""""""""""""""" +.. _view_projections: + +"""""""""""""""" +View Projections +"""""""""""""""" +The default projection into a view is to link every package into the +root of the view. The projections attribute is a mapping of partial specs to +spec format strings, defined by the :meth:`~spack.spec.Spec.format` +function, as shown in the example below: + +.. code-block:: yaml + + projections: + zlib: {name}-{version} + ^mpi: {name}-{version}/{^mpi.name}-{^mpi.version}-{compiler.name}-{compiler.version} + all: {name}-{version}/{compiler.name}-{compiler.version} + +The entries in the projections configuration file must all be either +specs or the keyword ``all``. For each spec, the projection used will +be the first non-``all`` entry that the spec satisfies, or ``all`` if +there is an entry for ``all`` and no other entry is satisfied by the +spec. Where the keyword ``all`` appears in the file does not +matter. + +Given the example above, the spec ``zlib@1.2.8`` +will be linked into ``/my/view/zlib-1.2.8/``, the spec +``hdf5@1.8.10+mpi %gcc@4.9.3 ^mvapich2@2.2`` will be linked into +``/my/view/hdf5-1.8.10/mvapich2-2.2-gcc-4.9.3``, and the spec +``hdf5@1.8.10~mpi %gcc@4.9.3`` will be linked into +``/my/view/hdf5-1.8.10/gcc-4.9.3``. + +If the keyword ``all`` does not appear in the projections +configuration file, any spec that does not satisfy any entry in the +file will be linked into the root of the view as in a single-prefix +view. Any entries that appear below the keyword ``all`` in the +projections configuration file will not be used, as all specs will use +the projection under ``all`` before reaching those entries. + +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Activating environment views -"""""""""""""""""""""""""""" +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``spack env activate`` command will put the default view for the environment into the user's path, in addition to activating the |