hlrs-software-stack/spack
7
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Documentation for configuration

Browse source
This commit is contained in:
Todd Gamblin 2016-10-28 16:17:58 -07:00
parent b962622975
commit d155156e32
15 changed files with 664 additions and 374 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

168
lib/spack/docs/build_settings.rst Normal file
View file

@ -0,0 +1,168 @@
.. _build-settings:
======================================
Build customization
======================================
Spack allows you to customize how your software is built through the
``packages.yaml`` file. Using it, you can make Spack prefer particular
implementations of virtual dependencies (e.g., compilers, MPI, or BLAS),
or you can make it prefer to build with particular compilers. You can
also tell Spack to use *external* installations of certain software.
At a high level, the ``packages.yaml`` file is structured like this:
.. code-block:: yaml
packages:
package1:
# settings for package1
package2:
# settings for package2
# ...
all:
# settings that apply to all packages.
So you can either set build preferences *specifically* for one package,
or you can specify that certain settings should apply to all packages.
The types of settings you can customize are described in detail below.
Spack's build defaults are in the default
``etc/spack/defaults/packages.yaml`` file. You can override them in
``~/.spack/packages.yaml`` or ``etc/spack/packages.yaml``. For more
details on how this works, see :ref:`configuration-scopes`
.. _sec-external-packages:
-----------------
External Packages
-----------------
Spack can be configured to use externally-installed
packages rather than building its own packages. This may be desirable
if machines ship with system packages, such as a customized MPI
that should be used instead of Spack building its own MPI.
External packages are configured through the ``packages.yaml`` file found
in a Spack installation's ``etc/spack/`` or a user's ``~/.spack/``
directory. Here's an example of an external configuration:
.. code-block:: yaml
packages:
openmpi:
paths:
openmpi@1.4.3%gcc@4.4.7 arch=linux-x86_64-debian7: /opt/openmpi-1.4.3
openmpi@1.4.3%gcc@4.4.7 arch=linux-x86_64-debian7+debug: /opt/openmpi-1.4.3-debug
openmpi@1.6.5%intel@10.1 arch=linux-x86_64-debian7: /opt/openmpi-1.6.5-intel
This example lists three installations of OpenMPI, one built with gcc,
one built with gcc and debug information, and another built with Intel.
If Spack is asked to build a package that uses one of these MPIs as a
dependency, it will use the the pre-installed OpenMPI in
the given directory. Packages.yaml can also be used to specify modules
Each ``packages.yaml`` begins with a ``packages:`` token, followed
by a list of package names. To specify externals, add a ``paths`` or ``modules``
token under the package name, which lists externals in a
``spec: /path`` or ``spec: module-name`` format. Each spec should be as
well-defined as reasonably possible. If a
package lacks a spec component, such as missing a compiler or
package version, then Spack will guess the missing component based
on its most-favored packages, and it may guess incorrectly.
Each package version and compilers listed in an external should
have entries in Spack's packages and compiler configuration, even
though the package and compiler may not every be built.
The packages configuration can tell Spack to use an external location
for certain package versions, but it does not restrict Spack to using
external packages. In the above example, if an OpenMPI 1.8.4 became
available Spack may choose to start building and linking with that version
rather than continue using the pre-installed OpenMPI versions.
To prevent this, the ``packages.yaml`` configuration also allows packages
to be flagged as non-buildable. The previous example could be modified to
be:
.. code-block:: yaml
packages:
openmpi:
paths:
openmpi@1.4.3%gcc@4.4.7 arch=linux-x86_64-debian7: /opt/openmpi-1.4.3
openmpi@1.4.3%gcc@4.4.7 arch=linux-x86_64-debian7+debug: /opt/openmpi-1.4.3-debug
openmpi@1.6.5%intel@10.1 arch=linux-x86_64-debian7: /opt/openmpi-1.6.5-intel
buildable: False
The addition of the ``buildable`` flag tells Spack that it should never build
its own version of OpenMPI, and it will instead always rely on a pre-built
OpenMPI. Similar to ``paths``, ``buildable`` is specified as a property under
a package name.
If an external module is specified as not buildable, then Spack will load the
external module into the build environment which can be used for linking.
The ``buildable`` does not need to be paired with external packages.
It could also be used alone to forbid packages that may be
buggy or otherwise undesirable.
.. _concretization-preferences:
--------------------------
Concretization Preferences
--------------------------
Spack can be configured to prefer certain compilers, package
versions, depends_on, and variants during concretization.
The preferred configuration can be controlled via the
``~/.spack/packages.yaml`` file for user configuations, or the
``etc/spack/packages.yaml`` site configuration.
Here's an example packages.yaml file that sets preferred packages:
.. code-block:: yaml
packages:
opencv:
compiler: [gcc@4.9]
variants: +debug
gperftools:
version: [2.2, 2.4, 2.3]
all:
compiler: [gcc@4.4.7, gcc@4.6:, intel, clang, pgi]
providers:
mpi: [mvapich, mpich, openmpi]
At a high level, this example is specifying how packages should be
concretized. The opencv package should prefer using gcc 4.9 and
be built with debug options. The gperftools package should prefer version
2.2 over 2.4. Every package on the system should prefer mvapich for
its MPI and gcc 4.4.7 (except for opencv, which overrides this by preferring gcc 4.9).
These options are used to fill in implicit defaults. Any of them can be overwritten
on the command line if explicitly requested.
Each packages.yaml file begins with the string ``packages:`` and
package names are specified on the next level. The special string ``all``
applies settings to each package. Underneath each package name is
one or more components: ``compiler``, ``variants``, ``version``,
or ``providers``. Each component has an ordered list of spec
``constraints``, with earlier entries in the list being preferred over
later entries.
Sometimes a package installation may have constraints that forbid
the first concretization rule, in which case Spack will use the first
legal concretization rule. Going back to the example, if a user
requests gperftools 2.3 or later, then Spack will install version 2.4
as the 2.4 version of gperftools is preferred over 2.3.
An explicit concretization rule in the preferred section will always
take preference over unlisted concretizations. In the above example,
xlc isn't listed in the compiler list. Every listed compiler from
gcc to pgi will thus be preferred over the xlc compiler.
The syntax for the ``provider`` section differs slightly from other
concretization rules. A provider lists a value that packages may
``depend_on`` (e.g, mpi) and a list of rules for fulfilling that
dependency.

149
lib/spack/docs/config_yaml.rst Normal file
View file

@ -0,0 +1,149 @@
.. _config-yaml:
====================================
Basics settings
====================================
Spack's basic configuration options are set in ``config.yaml``. You can
see the default settings by looking at
``etc/spack/defaults/config.yaml``:
.. literalinclude:: ../../../etc/spack/defaults/config.yaml
:language: yaml
These settings can be overridden in ``etc/spack/config.yaml`` or
``~/.spack/config.yaml``. See :ref:`configuration-scopes` for details.
.. _config-file-variables:
------------------------------
Config file variables
------------------------------
You may notice some variables prefixed with ``$`` in the settings above.
Spack understands several variables that can be used in values of
configuration parameters. They are:
* ``$spack``: path to the prefix of this spack installation
* ``$tempdir``: default system temporary directory (as specified in
Python's `tempfile.tempdir
<https://docs.python.org/2/library/tempfile.html#tempfile.tempdir>`_
variable.
* ``$user``: name of the current user
Note that, as with shell variables, you can write these as ``$varname``
or with braces to distinguish the variable from surrounding characters:
``${varname}``.
--------------------
``install_tree``
--------------------
The location where Spack will install packages and their dependencies.
Default is ``$spack/opt/spack``.
--------------------
``module_roots``
--------------------
Controls where Spack installs generated module files. You can customize
the location for each type of module. e.g.:
.. code-block:: yaml
module_roots:
tcl: $spack/share/spack/modules
lmod: $spack/share/spack/lmod
dotkit: $spack/share/spack/dotkit
See :ref:`modules` for details.
--------------------
``build_stage``
--------------------
Spack is designed to run out of a user home directories, and on many
systems the home directory a (slow) network filesystem. On most systems,
building in a temporary filesystem results in faster builds than building
in the home directory. Usually, there is also more space available in
the temporary location than in the home directory. So, Spack tries to
create build stages in temporary space.
By default, Spack's ``build_stage`` is configured like this:
.. code-block:: yaml
build_stage:
- $tempdir
- /nfs/tmp2/$user
- $spack/var/spack/stage
This is an ordered list of paths that Spack should search when trying to
find a temporary directory for the build stage. The list is searched in
order, and Spack will use the first directory to which it has write access.
See :ref:`config-file-variables` for more on ``$tempdir`` and ``$spack``.
When Spack builds a package, it creates a temporary directory within the
``build_stage``, and it creates a symbolic link to that directory in
``$spack/var/spack/stage``. This is used totrack the stage.
After a package is successfully installed, Spack deletes the temporary
directory it used to build. Unsuccessful builds are not deleted, but you
can manually purge them with :ref:`spack purge --stage
<cmd-spack-purge>`.
.. note::
The last item in the list is ``$spack/var/spack/stage``. If this is the
only writable directory in the ``build_stage`` list, Spack will build
*directly* in ``$spack/var/spack/stage`` and will not link to temporary
space.
--------------------
``source_cache``
--------------------
Location to cache downloaded tarballs and repositories. By default these
are stored in ``$spack/var/spack/cache``. These are stored indefinitely
by default. Can be purged with :ref:`spack purge --downloads
<cmd-spack-purge>`.
--------------------
``misc_cache``
--------------------
Temporary directory to store long-lived cache files, such as indices of
packages available in repositories. Defaults to ``~/.spack/cache``. Can
be purged with :ref:`spack purge --misc-cache <cmd-spack-purge>`.
--------------------
``verify_ssl``
--------------------
When set to ``true`` (default) Spack will verify certificates of remote
hosts when making ``ssl`` connections. Set to ``false`` to disable, and
tools like ``curl`` will use their ``--insecure`` options. Disabling
this can expose you to attacks. Use at your own risk.
--------------------
``checksum``
--------------------
When set to ``true``, Spack verifies downloaded source code using a
checksum, and will refuse to build packages that it cannot verify. Set
to ``false`` to disable these checks. Disabling this can expose you to
attacks. Use at your own risk.
--------------------
``dirty``
--------------------
By default, Spack unsets variables in your environment that can change
the way packages build. This includes ``LD_LIBRARY_PATH``, ``CPATH``,
``LIBRARY_PATH``, ``DYLD_LIBRARY_PATH``, and others.
By default, builds are ``clean``, but on some machines, compilers and
other tools may need custom ``LD_LIBRARY_PATH`` setings to run. You can
set ``dirty`` to ``true`` to skip the cleaning step and make all builds
"dirty" by default. Be aware that this will reduce the reproducibility
of builds.

406
lib/spack/docs/configuration.rst
View file

@ -1,234 +1,252 @@
.. _configuration:
=============
Configuration
=============
==============================
Configuration Files in Spack
==============================
.. _install-area:
Spack has many configuration files. Here is a quick list of them, in
case you want to skip directly to specific docs:
Install options
----------------------------
* :ref:`compilers.yaml <compiler-config>`
* :ref:`config.yaml <config-yaml>`
* :ref:`mirrors.yaml <mirrors>`
* :ref:`modules.yaml <modules>`
* :ref:`packages.yaml <build-settings>`
By default, Spack will install software into ``opt/spack``.
To set a custom install directory, the option ``install_tree`` in
``config.yaml`` can be used. This file can be found
in a Spack installation's ``etc/spack/`` or a user's ``~/.spack/``
directory.
-------------------------
YAML Format
-------------------------
.. _temp-space:
---------------
Temporary space
---------------
.. warning::
Temporary space configuration will eventually be moved to
configuration files, but currently these settings are in
``lib/spack/spack/__init__.py``
By default, Spack will try to do all of its building in temporary
space. There are two main reasons for this. First, Spack is designed
to run out of a user's home directory, and on may systems the home
directory is network mounted and potentially not a very fast
filesystem. We create build stages in a temporary directory to avoid
this. Second, many systems impose quotas on home directories, and
``/tmp`` or similar directories often have more available space. This
helps conserve space for installations in users' home directories.
You can customize temporary directories by editing
``lib/spack/spack/__init__.py``. Specifically, find this part of the file:
.. code-block:: python
# Whether to build in tmp space or directly in the stage_path.
# If this is true, then spack will make stage directories in
# a tmp filesystem, and it will symlink them into stage_path.
use_tmp_stage = True
# Locations to use for staging and building, in order of preference
# Use a %u to add a username to the stage paths here, in case this
# is a shared filesystem. Spack will use the first of these paths
# that it can create.
tmp_dirs = ['/nfs/tmp2/%u/spack-stage',
'/var/tmp/%u/spack-stage',
'/tmp/%u/spack-stage']
The ``use_tmp_stage`` variable controls whether Spack builds
**directly** inside the ``var/spack/`` directory. Normally, Spack
will try to find a temporary directory for a build, then it *symlinks*
that temporary directory into ``var/spack/`` so that you can keep
track of what temporary directories Spack is using.
The ``tmp_dirs`` variable is a list of paths Spack should search when
trying to find a temporary directory. They can optionally contain a
``%u``, which will substitute the current user's name into the path.
The list is searched in order, and Spack will create a temporary stage
in the first directory it finds to which it has write access. Add
more elements to the list to indicate where your own site's temporary
directory is.
.. _sec-external_packages:
-----------------
External Packages
-----------------
Spack can be configured to use externally-installed
packages rather than building its own packages. This may be desirable
if machines ship with system packages, such as a customized MPI
that should be used instead of Spack building its own MPI.
External packages are configured through the ``packages.yaml`` file found
in a Spack installation's ``etc/spack/`` or a user's ``~/.spack/``
directory. Here's an example of an external configuration:
Spack configuration files are written in YAML. We chose YAML because
it's human readable, but also versatile in that it supports dictionaries,
lists, and nested sections. For more details on the format, see `yaml.org
<http://yaml.org>`_ and `libyaml <http://pyyaml.org/wiki/LibYAML>`_.
Here is an example ``config.yaml`` file:
.. code-block:: yaml
packages:
openmpi:
paths:
openmpi@1.4.3%gcc@4.4.7 arch=linux-x86_64-debian7: /opt/openmpi-1.4.3
openmpi@1.4.3%gcc@4.4.7 arch=linux-x86_64-debian7+debug: /opt/openmpi-1.4.3-debug
openmpi@1.6.5%intel@10.1 arch=linux-x86_64-debian7: /opt/openmpi-1.6.5-intel
config:
install_tree: $spack/opt/spack
module_roots:
lmod: $spack/share/spack/lmod
build_stage:
- $tempdir
- /nfs/tmp2/$user
This example lists three installations of OpenMPI, one built with gcc,
one built with gcc and debug information, and another built with Intel.
If Spack is asked to build a package that uses one of these MPIs as a
dependency, it will use the the pre-installed OpenMPI in
the given directory. Packages.yaml can also be used to specify modules
Each spack configuration files is nested under a top-level section
corresponding to its name. So, ``config.yaml`` starts with ``config:``,
and ``mirrors.yaml`` starts with ``mirrors:``, etc.
Each ``packages.yaml`` begins with a ``packages:`` token, followed
by a list of package names. To specify externals, add a ``paths`` or ``modules``
token under the package name, which lists externals in a
``spec: /path`` or ``spec: module-name`` format. Each spec should be as
well-defined as reasonably possible. If a
package lacks a spec component, such as missing a compiler or
package version, then Spack will guess the missing component based
on its most-favored packages, and it may guess incorrectly.
.. _configuration-scopes:
Each package version and compilers listed in an external should
have entries in Spack's packages and compiler configuration, even
though the package and compiler may not every be built.
-------------------------
Configuration Scopes
-------------------------
The packages configuration can tell Spack to use an external location
for certain package versions, but it does not restrict Spack to using
external packages. In the above example, if an OpenMPI 1.8.4 became
available Spack may choose to start building and linking with that version
rather than continue using the pre-installed OpenMPI versions.
Spack pulls configuration data from files in several directories. There
are three configuration scopes. From lowest to highest:
To prevent this, the ``packages.yaml`` configuration also allows packages
to be flagged as non-buildable. The previous example could be modified to
be:
1. **defaults**: Stored in ``$(prefix)/etc/spack/defaults/``. These are
the "factory" settings. Users should generally not modify the settings
here, but should override them in other configuration scopes. The
defaults here will change from version to version of Spack.
2. **site**: Stored in ``$(prefix)/etc/spack/``. Settings here affect
only *this instance* of Spack, and they override defaults. The site
scope can can be used for per-project settings (one spack instance per
project) or for site-wide settings on a multi-user machine (e.g., for
a common spack instance).
3. **user**: Stored in the home directory: ``~/.spack/``. These settings
affect all instances of Spack and take the highest precedence.
Each configuration directory may contain several configuration files,
such as ``config.yaml``, ``compilers.yaml``, or ``mirrors.yaml``. When
configurations conflict, settings from higher-precedence scopes override
lower-precedence settings.
Commands that modify scopes (e.g., ``spack compilers``, ``spack repo``,
etc.) take a ``--scope=<name>`` parameter that you can use to control
which scope is modified. By default they modify the highest-precedence
scope.
.. _platform-scopes:
-------------------------
Platform-specific scopes
-------------------------
For each scope above, there can *also* be platform-specific settings.
For example, on Blue Gene/Q machines, Spack needs to know the location of
cross-compilers for the compute nodes. This configuration is in
``etc/spack/defaults/bgq/compilers.yaml``. It will take precedence over
settings in the ``defaults`` scope, but can still be overridden by
settings in ``site``, ``site/bgq``, ``user``, or ``user/bgq``. So, the
full scope precedence is:
1. ``defaults``
2. ``defaults/<platform>``
3. ``site``
4. ``site/<platform>``
5. ``user``
6. ``user/<platform>``
You can get the name to use for ``<platform>`` by running ``spack arch
--platform``.
-------------------------
Scope precedence
-------------------------
When spack queries for configuration parameters, it searches in
higher-precedence scopes first. So, settings in a higher-precedence file
can override those with the same key in a lower-precedence one. For
list-valued settings, Spack *prepends* higher-precedence settings to
lower-precedence settings. Completely ignoring higher-level configuration
options is supported with the ``::`` notation for keys (see
:ref:`config-overrides` below).
^^^^^^^^^^^^^^^^^^^^^^^^
Simple keys
^^^^^^^^^^^^^^^^^^^^^^^^
Let's look at an example of overriding a single key in a Spack file. If
your configurations look like this:
**defaults** scope:
.. code-block:: yaml
packages:
openmpi:
paths:
openmpi@1.4.3%gcc@4.4.7 arch=linux-x86_64-debian7: /opt/openmpi-1.4.3
openmpi@1.4.3%gcc@4.4.7 arch=linux-x86_64-debian7+debug: /opt/openmpi-1.4.3-debug
openmpi@1.6.5%intel@10.1 arch=linux-x86_64-debian7: /opt/openmpi-1.6.5-intel
buildable: False
config:
install_tree: $spack/opt/spack
module_roots:
lmod: $spack/share/spack/lmod
build_stage:
- $tempdir
- /nfs/tmp2/$user
The addition of the ``buildable`` flag tells Spack that it should never build
its own version of OpenMPI, and it will instead always rely on a pre-built
OpenMPI. Similar to ``paths``, ``buildable`` is specified as a property under
a package name.
**site** scope:
If an external module is specified as not buildable, then Spack will load the
external module into the build environment which can be used for linking.
.. code-block:: yaml
The ``buildable`` does not need to be paired with external packages.
It could also be used alone to forbid packages that may be
buggy or otherwise undesirable.
config:
install_tree: /some/other/directory
.. _system-packages:
Spack will only override ``install_tree`` in the ``config`` section, and
will take the site preferences for other settings. You can see the
final, combined configuration with the ``spack config get <configtype>``
command:
.. code-block:: console
:emphasize-lines: 3
$ spack config get config
config:
install_tree: /some/other/directory
module_roots:
lmod: $spack/share/spack/lmod
build_stage:
- $tempdir
- /nfs/tmp2/$user
$ _
.. _config-overrides:
^^^^^^^^^^^^^^^^^^^^^^^^^^
Extracting System Packages
Overriding entire sections
^^^^^^^^^^^^^^^^^^^^^^^^^^
In some cases, using false paths for system packages will not work.
Some builds need to run binaries out of their dependencies, not just
access their libraries: the build needs to know the real location of
the system package.
Above, the site ``config.yaml`` only overrides specific settings in the
default ``config.yaml``. Sometimes, it is useful to *completely*
override lower-precedence settings. To do this, you can use *two* colons
at the end of a key in a configuration file. For example, if the
**site** ``config.yaml`` above looks like this:
In this case, one can create a Spack-like single-package tree by
creating symlinks to the files related to just that package.
Depending on the OS, it is possible to obtain a list of the files in a
single OS-installed package. For example, on RedHat / Fedora:
.. code-block:: yaml
:emphasize-lines: 1
config::
install_tree: /some/other/directory
Spack will ignore all lower-precedence configuration under the
``config::`` section:
.. code-block:: console
$ repoquery --list openssl-devel
...
/usr/lib/libcrypto.so
/usr/lib/libssl.so
/usr/lib/pkgconfig/libcrypto.pc
/usr/lib/pkgconfig/libssl.pc
/usr/lib/pkgconfig/openssl.pc
...
$ spack config get config
config:
install_tree: /some/other/directory
Spack currently does not provide an automated way to create a symlink
tree to these files.
^^^^^^^^^^^^^^^^^^^^^^
List-valued settings
^^^^^^^^^^^^^^^^^^^^^^
Let's revisit the ``config.yaml`` example one more time. The
``build_stage`` setting's value is an ordered list of directories:
.. _concretization-preferences:
--------------------------
Concretization Preferences
--------------------------
Spack can be configured to prefer certain compilers, package
versions, depends_on, and variants during concretization.
The preferred configuration can be controlled via the
``~/.spack/packages.yaml`` file for user configuations, or the
``etc/spack/packages.yaml`` site configuration.
Here's an example packages.yaml file that sets preferred packages:
**defaults**
.. code-block:: yaml
packages:
opencv:
compiler: [gcc@4.9]
variants: +debug
gperftools:
version: [2.2, 2.4, 2.3]
all:
compiler: [gcc@4.4.7, gcc@4.6:, intel, clang, pgi]
providers:
mpi: [mvapich, mpich, openmpi]
build_stage:
- $tempdir
- /nfs/tmp2/$user
At a high level, this example is specifying how packages should be
concretized. The opencv package should prefer using gcc 4.9 and
be built with debug options. The gperftools package should prefer version
2.2 over 2.4. Every package on the system should prefer mvapich for
its MPI and gcc 4.4.7 (except for opencv, which overrides this by preferring gcc 4.9).
These options are used to fill in implicit defaults. Any of them can be overwritten
on the command line if explicitly requested.
Suppose the user configuration adds its *own* list of ``build_stage``
paths:
Each packages.yaml file begins with the string ``packages:`` and
package names are specified on the next level. The special string ``all``
applies settings to each package. Underneath each package name is
one or more components: ``compiler``, ``variants``, ``version``,
or ``providers``. Each component has an ordered list of spec
``constraints``, with earlier entries in the list being preferred over
later entries.
**user**
Sometimes a package installation may have constraints that forbid
the first concretization rule, in which case Spack will use the first
legal concretization rule. Going back to the example, if a user
requests gperftools 2.3 or later, then Spack will install version 2.4
as the 2.4 version of gperftools is preferred over 2.3.
.. code-block:: yaml
An explicit concretization rule in the preferred section will always
take preference over unlisted concretizations. In the above example,
xlc isn't listed in the compiler list. Every listed compiler from
gcc to pgi will thus be preferred over the xlc compiler.
build_stage:
- /lustre-scratch/$user
- ~/mystage
The syntax for the ``provider`` section differs slightly from other
concretization rules. A provider lists a value that packages may
``depend_on`` (e.g, mpi) and a list of rules for fulfilling that
dependency.
Spack will first look at the paths in the site ``config.yaml``, then the
paths in the user's ``~/.spack/config.yaml``. The list in the
higher-precedence scope is *prepended* to the defaults. ``spack config
get config`` shows the result:
.. code-block:: console
:emphasize-lines: 7-10
$ spack config get config
config:
install_tree: /some/other/directory
module_roots:
lmod: $spack/share/spack/lmod
build_stage:
- /lustre-scratch/$user
- ~/mystage
- $tempdir
- /nfs/tmp2/$user
$ _
As in :ref:`config-overrides`, the higher-precedence scope can
*completely* override the lower-precedence scope using `::`. So if the
user config looked like this:
**user**
.. code-block:: yaml
:emphasize-lines: 1
build_stage::
- /lustre-scratch/$user
- ~/mystage
The merged configuration would look like this:
.. code-block:: console
:emphasize-lines: 7-8
$ spack config get config
config:
install_tree: /some/other/directory
module_roots:
lmod: $spack/share/spack/lmod
build_stage:
- /lustre-scratch/$user
- ~/mystage
$ _

27
lib/spack/docs/developer_guide.rst
View file

@ -250,30 +250,25 @@ Unit tests
Other Modules
^^^^^^^^^^^^^
:mod:`spack.globals`
Includes global settings for Spack. the default policy classes for
things like :ref:`temporary space <temp-space>` and
:ref:`concretization <concretization-policies>`.
:mod:`spack.tty`
Basic output functions for all of the messages Spack writes to the
terminal.
:mod:`spack.color`
Implements a color formatting syntax used by ``spack.tty``.
:mod:`spack.url`
URL parsing, for deducing names and versions of packages from
tarball URLs.
:mod:`spack.util`
In this package are a number of utility modules for the rest of
Spack.
:mod:`spack.error`
:class:`SpackError <spack.error.SpackError>`, the base class for
Spack's exception hierarchy.
:mod:`llnl.util.tty`
Basic output functions for all of the messages Spack writes to the
terminal.
:mod:`llnl.util.tty.color`
Implements a color formatting syntax used by ``spack.tty``.
:mod:`llnl.util`
In this package are a number of utility modules for the rest of
Spack.
------------
Spec objects
------------

2
lib/spack/docs/getting_started.rst
View file

@ -1170,4 +1170,4 @@ if we want to build with intel compilers, use version 16.0.0.109. We add a spec
for each compiler type for each cray modules. This ensures that for each
compiler on our system we can use that external module.
For more on external packages check out the section :ref:`sec-external_packages`.
For more on external packages check out the section :ref:`sec-external-packages`.

2
lib/spack/docs/index.rst
View file

@ -52,6 +52,8 @@ or refer to the full manual below.
:caption: Reference Manual
configuration
config_yaml
build_settings
mirrors
module_file_support
package_list

91
lib/spack/docs/module_file_support.rst
View file

@ -1,6 +1,8 @@
===============================
Integration with module systems
===============================
.. _modules:
=====================================
Modules
=====================================
The use of module systems to manage user environment in a controlled way
is a common practice at HPC centers that is often embraced also by individual
@ -106,6 +108,12 @@ you could type either of these commands to load the callpath module:
$ module load callpath@1.0.1%gcc@4.4.7-5dce4318
.. _cmd-spack-load:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``spack load / unload``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Neither of these is particularly pretty, easy to remember, or
easy to type. Luckily, Spack has its own interface for using modules
and dotkits. You can use the same spec syntax you're used to:
@ -153,9 +161,9 @@ want to use a package, you can type unload or unuse similarly:
only available if you have enabled Spack's shell support *and* you
have dotkit or modules installed on your machine.
----------------------
^^^^^^^^^^^^^^^^^^^^^^^^^
Ambiguous module names
----------------------
^^^^^^^^^^^^^^^^^^^^^^^^^
If a spec used with load/unload or use/unuse is ambiguous (i.e. more
than one installed package matches it), then Spack will warn you:
@ -181,9 +189,11 @@ To identify just the one built with the Intel compiler.
.. _extensions:
----------------------
.. _cmd-spack-module-loads:
^^^^^^^^^^^^^^^^^^^^^^
``spack module loads``
----------------------
^^^^^^^^^^^^^^^^^^^^^^
In some cases, it is desirable to load not just a module, but also all
the modules it depends on. This is not required for most modules
@ -284,9 +294,9 @@ For example, consider the following on one system:
# antlr@2.7.7%gcc@5.3.0~csharp+cxx~java~python arch=linux-SuSE11-x86_64
module load linux-SuSE11-x86_64/antlr-2.7.7-gcc-5.3.0-bdpl46y
=======================
Module files generation
=======================
-----------------------------
Auto-generating Module Files
-----------------------------
Module files are generated by post-install hooks after the successful
installation of a package. They are placed in the following directories
@ -314,9 +324,9 @@ The former method fits best cases that are site independent, e.g. injecting vari
from language interpreters into their extensions. The latter instead permits to
fine tune the content, naming and creation of module files to meet site specific conventions.
--------------------------
Overriding ``Package`` API
--------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^
``Package`` file API
^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are two methods that can be overridden in any ``package.py`` to affect the
content of generated module files. The first one is:
@ -364,9 +374,11 @@ and has similar effects on module file of dependees. Even in this case
.. literalinclude:: ../../../var/spack/repos/builtin/packages/R/package.py
:lines: 128-129,146-151
------------------------------
Configuration file for modules
------------------------------
.. _modules-yaml:
----------------------------------
Configuration in ``modules.yaml``
----------------------------------
The name of the configuration file that controls module generation behavior
is ``modules.yaml``. The default configuration:
@ -597,8 +609,9 @@ files that instead will contain these modifications.
Autoload dependencies
^^^^^^^^^^^^^^^^^^^^^
In some cases it can be useful to have module files directly autoload their dependencies.
This may be the case for Python extensions, if not activated using ``spack activate``:
In some cases it can be useful to have module files directly autoload
their dependencies. This may be the case for Python extensions, if not
activated using ``spack activate``:
.. code-block:: yaml
@ -607,20 +620,20 @@ This may be the case for Python extensions, if not activated using ``spack activ
^python:
autoload: 'direct'
The configuration file above will produce module files that will automatically
load their direct dependencies. The allowed values for the ``autoload`` statement
are either ``none``, ``direct`` or ``all``.
The configuration file above will produce module files that will
automatically load their direct dependencies. The allowed values for the
``autoload`` statement are either ``none``, ``direct`` or ``all``.
.. note::
TCL prerequisites
In the ``tcl`` section of the configuration file it is possible to use
the ``prerequisites`` directive that accepts the same values as ``autoload``.
It will produce module files that have a ``prereq``
the ``prerequisites`` directive that accepts the same values as
``autoload``. It will produce module files that have a ``prereq``
statement instead of automatically loading other modules.
========================
Module files maintenance
========================
------------------------
Maintaining Module Files
------------------------
Spack not only provides great flexibility in the generation of module files
and in the customization of both their layout and content, but also ships with
@ -629,12 +642,14 @@ This tool is the ``spack module`` command:
.. command-output:: spack module --help
------------------------
``spack module refresh``
------------------------
.. _cmd-spack-module-refresh:
The command that regenerates module files to update their content or their layout
is ``module refresh``:
^^^^^^^^^^^^^^^^^^^^^^^^
``spack module refresh``
^^^^^^^^^^^^^^^^^^^^^^^^
The command that regenerates module files to update their content or
their layout is ``module refresh``:
.. command-output:: spack module refresh --help
@ -643,9 +658,11 @@ A set of packages can be selected using anonymous specs for the optional
the type of module files to refresh. Optionally the entire tree can be deleted
before regeneration if the change in layout is radical.
-------------------
.. _cmd-spack-module-rm:
^^^^^^^^^^^^^^^^^^^^^^^^
``spack module rm``
-------------------
^^^^^^^^^^^^^^^^^^^^^^^^
If instead what you need is just to delete a few module files, then the right
command is ``module rm``:
@ -653,7 +670,7 @@ command is ``module rm``:
.. command-output:: spack module rm --help
.. note::
We care about your module files!
Every modification done on modules that are already existing will
ask for a confirmation by default. If the command is used in a script it is
possible though to pass the ``-y`` argument, that will skip this safety measure.
We care about your module files! Every modification done on modules
that are already existing will ask for a confirmation by default. If
the command is used in a script it is possible though to pass the
``-y`` argument, that will skip this safety measure.

1
lib/spack/spack/cmd/build.py
View file

@ -22,7 +22,6 @@
# License along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
##############################################################################
import spack.cmd.configure as cfg
from spack import *

155
lib/spack/spack/config.py
View file

@ -24,129 +24,27 @@
##############################################################################
"""This module implements Spack's configuration file handling.
=========================
Configuration file scopes
=========================
This implements Spack's configuration system, which handles merging
multiple scopes with different levels of precedence. See the
documentation on :ref:`configuration-scopes` for details on how Spack's
configuration system behaves. The scopes are:
When Spack runs, it pulls configuration data from several config
directories, each of which contains configuration files. In Spack,
there are three configuration scopes (lowest to highest):
#. ``default``
#. ``site``
#. ``user``
1. ``defaults``: Spack loads default configuration settings from
``$(prefix)/etc/spack/defaults/``. These settings are the "out of the
box" settings Spack will use without site- or user- modification, and
this is where settings that are versioned with Spack should go.
And corresponding :ref:`per-platform scopes <platform-scopes>`. Important
functions in this module are:
2. ``site``: This scope affects only this *instance* of Spack, and
overrides the ``defaults`` scope. Configuration files in
``$(prefix)/etc/spack/`` determine site scope. These can be used for
per-project settings (for users with their own spack instance) or for
site-wide settings (for admins maintaining a common spack instance).
* :py:func:`get_config`
* :py:func:`update_config`
3. ``user``: User configuration goes in the user's home directory,
specifically in ``~/.spack/``.
``get_config`` reads in YAML data for a particular scope and returns
it. Callers can then modify the data and write it back with
``update_config``.
Spack may read configuration files from any of these locations. When
configurations conflict, settings from higher-precedence scopes override
lower-precedence settings.
fCommands that modify scopes (``spack compilers``, ``spack config``,
etc.) take a ``--scope=<name>`` parameter that you can use to control
which scope is modified.
For each scope above, there can *also* be platform-specific
overrides. For example, on Blue Gene/Q machines, Spack needs to know the
location of cross-compilers for the compute nodes. This configuration is
in ``etc/spack/defaults/bgq/compilers.yaml``. It will take precedence
over settings in the ``defaults`` scope, but can still be overridden by
settings in ``site``, ``site/bgq``, ``user``, or ``user/bgq``. So, the
full list of scopes and their precedence is:
1. ``defaults``
2. ``defaults/<platform>``
3. ``site``
4. ``site/<platform>``
5. ``user``
6. ``user/<platform>``
Each configuration directory may contain several configuration files,
such as compilers.yaml or mirrors.yaml.
=========================
Configuration file format
=========================
Configuration files are formatted using YAML syntax. This format is
implemented by libyaml (included with Spack as an external module),
and it's easy to read and versatile.
Config files are structured as trees, like this ``compiler`` section::
compilers:
chaos_5_x86_64_ib:
gcc@4.4.7:
cc: /usr/bin/gcc
cxx: /usr/bin/g++
f77: /usr/bin/gfortran
fc: /usr/bin/gfortran
bgqos_0:
xlc@12.1:
cc: /usr/local/bin/mpixlc
...
In this example, entries like "compilers" and "xlc@12.1" are used to
categorize entries beneath them in the tree. At the root of the tree,
entries like "cc" and "cxx" are specified as name/value pairs.
``config.get_config()`` returns these trees as nested dicts, but it
strips the first level off. So, ``config.get_config('compilers')``
would return something like this for the above example::
{ 'chaos_5_x86_64_ib' :
{ 'gcc@4.4.7' :
{ 'cc' : '/usr/bin/gcc',
'cxx' : '/usr/bin/g++'
'f77' : '/usr/bin/gfortran'
'fc' : '/usr/bin/gfortran' }
}
{ 'bgqos_0' :
{ 'cc' : '/usr/local/bin/mpixlc' } }
Likewise, the ``mirrors.yaml`` file's first line must be ``mirrors:``,
but ``get_config()`` strips that off too.
==========
Precedence
==========
``config.py`` routines attempt to recursively merge configuration
across scopes. So if there are ``compilers.py`` files in both the
site scope and the user scope, ``get_config('compilers')`` will return
merged dictionaries of *all* the compilers available. If a user
compiler conflicts with a site compiler, Spack will overwrite the site
configuration wtih the user configuration. If both the user and site
``mirrors.yaml`` files contain lists of mirrors, then ``get_config()``
will return a concatenated list of mirrors, with the user config items
first.
Sometimes, it is useful to *completely* override a site setting with a
user one. To accomplish this, you can use *two* colons at the end of
a key in a configuration file. For example, this::
compilers::
chaos_5_x86_64_ib:
gcc@4.4.7:
cc: /usr/bin/gcc
cxx: /usr/bin/g++
f77: /usr/bin/gfortran
fc: /usr/bin/gfortran
bgqos_0:
xlc@12.1:
cc: /usr/local/bin/mpixlc
...
Will make Spack take compilers *only* from the user configuration, and
the site configuration will be ignored.
When read in, Spack validates configurations with jsonschemas. The
schemas are in submodules of :py:mod:`spack.schema`.
"""
@ -436,7 +334,26 @@ def they_are(t):
def get_config(section, scope=None):
"""Get configuration settings for a section.
Strips off the top-level section name from the YAML dict.
If ``scope`` is ``None`` or not provided, return the merged contents
of all of Spack's configuration scopes. If ``scope`` is provided,
return only the confiugration as specified in that scope.
This off the top-level name from the YAML section. That is, for a
YAML config file that looks like this::
config:
install_tree: $spack/opt/spack
module_roots:
lmod: $spack/share/spack/lmod
``get_config('config')`` will return::
{ 'install_tree': '$spack/opt/spack',
'module_roots: {
'lmod': '$spack/share/spack/lmod'
}
}
"""
validate_section_name(section)
merged_section = syaml.syaml_dict()

6
lib/spack/spack/schema/compilers.py
View file

@ -22,7 +22,11 @@
# License along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
##############################################################################
"""Schema for compiler configuration files."""
"""Schema for compilers.yaml configuration file.
.. literalinclude:: ../spack/schema/compilers.py
:lines: 32-
"""
schema = {

7
lib/spack/spack/schema/config.py
View file

@ -22,7 +22,12 @@
# License along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
##############################################################################
"""Schema for packages.yaml configuration files."""
"""Schema for config.yaml configuration file.
.. literalinclude:: ../spack/schema/config.py
:lines: 32-
"""
schema = {
'$schema': 'http://json-schema.org/schema#',

6
lib/spack/spack/schema/mirrors.py
View file

@ -22,7 +22,11 @@
# License along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
##############################################################################
"""Schema for mirror configuration files."""
"""Schema for mirrors.yaml configuration file.
.. literalinclude:: ../spack/schema/mirrors.py
:lines: 32-
"""
schema = {

6
lib/spack/spack/schema/modules.py
View file

@ -22,7 +22,11 @@
# License along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
##############################################################################
"""Schema for mirror configuration files."""
"""Schema for modules.yaml configuration file.
.. literalinclude:: ../spack/schema/modules.py
:lines: 32-
"""
schema = {

6
lib/spack/spack/schema/packages.py
View file

@ -22,7 +22,11 @@
# License along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
##############################################################################
"""Schema for packages.yaml configuration files."""
"""Schema for packages.yaml configuration files.
.. literalinclude:: ../spack/schema/packages.py
:lines: 32-
"""
schema = {

6
lib/spack/spack/schema/repos.py
View file

@ -22,7 +22,11 @@
# License along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
##############################################################################
"""Schema for repository configuration files."""
"""Schema for repos.yaml configuration file.
.. literalinclude:: ../spack/schema/repos.py
:lines: 32-
"""
schema = {