summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatthew LeGendre <legendre1@llnl.gov>2016-03-09 16:11:53 -0800
committerMatthew LeGendre <legendre1@llnl.gov>2016-03-09 16:11:53 -0800
commit1f06dd40f7e65252568da23e9758bf5af02833eb (patch)
treea095826c4205bbc44a00720f51932d81388f4277
parenta384ad5b1270140d71110e46d39144a0f0e9081e (diff)
downloadspack-1f06dd40f7e65252568da23e9758bf5af02833eb.tar.gz
spack-1f06dd40f7e65252568da23e9758bf5af02833eb.tar.bz2
spack-1f06dd40f7e65252568da23e9758bf5af02833eb.tar.xz
spack-1f06dd40f7e65252568da23e9758bf5af02833eb.zip
Update documentation for new packages.yaml config format.
-rw-r--r--lib/spack/docs/packaging_guide.rst41
-rw-r--r--lib/spack/docs/site_configuration.rst61
2 files changed, 49 insertions, 53 deletions
diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst
index f368d0a4fa..ef9fd89b62 100644
--- a/lib/spack/docs/packaging_guide.rst
+++ b/lib/spack/docs/packaging_guide.rst
@@ -1561,50 +1561,49 @@ be concretized on their system. For example, one user may prefer packages
built with OpenMPI and the Intel compiler. Another user may prefer
packages be built with MVAPICH and GCC.
-Spack's ``preferred`` configuration can be used to set defaults for sites or users.
-Spack uses this configuration to make decisions about which compilers, package
-versions, depends_on, and variants it should prefer during concretization.
+Spack can be configurated 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.
-The preferred configuration can be controlled by editing the
-``~/.spack/preferred.yaml`` file for user configuations, or the
-
-Here's an example preferred.yaml file:
+Here's an example packages.yaml file that sets preferred packages:
.. code-block:: sh
- preferred:
+ packages:
dyninst:
- compiler: gcc@4.9
+ compiler: [gcc@4.9]
variants: +debug
gperftools:
- version: 2.2, 2.4, 2.3
+ version: [2.2, 2.4, 2.3]
all:
- compiler: gcc@4.4.7, gcc@4.6:, intel, clang, pgi
- providers:
- mpi: mvapich, mpich, openmpi
+ 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 dyninst 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 Dyninst, which perfers gcc 4.9).
+its MPI and gcc 4.4.7 (except for Dyninst, which overrides this by perfering 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 preferred.yaml file begin with the string ``preferred:`` and
-each subsequent entry is indented underneath it. The next layer contains
-package names or the special string ``all`` (which applies to
-every package). Underneath each package name is
+Each packages.yaml file begin 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 prefered over
-latter entries.
+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 latter, then Spack will install version 2.4
+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
@@ -1612,7 +1611,7 @@ 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 ``providers`` section differs slightly from other
+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.
diff --git a/lib/spack/docs/site_configuration.rst b/lib/spack/docs/site_configuration.rst
index a7211a9d95..ebf0437106 100644
--- a/lib/spack/docs/site_configuration.rst
+++ b/lib/spack/docs/site_configuration.rst
@@ -56,44 +56,43 @@ directory is.
External Packages
~~~~~~~~~~~~~~~~~~~~~
-It's possible for Spack to use certain externally-installed
-packages rather than always rebuilding packages. This may be desirable
+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::
+directory. Here's an example of an external configuration:
.. code-block:: yaml
- packages:
- - openmpi@1.4.3%gcc@4.4.7=chaos_5_x86_64_ib:
- path: /opt/openmpi-1.4.3
- - openmpi@1.4.3%gcc@4.4.7=chaos_5_x86_64_ib+debug:
- path: /opt/openmpi-1.4.3-debug
- - openmpi@1.6.5%intel@10.1=chaos_5_x86_64_ib:
- path: /opt/openmpi-1.6.5-intel
+ packages:
+ openmpi:
+ paths:
+ openmpi@1.4.3%gcc@4.4.7=chaos_5_x86_64_ib: /opt/openmpi-1.4.3
+ openmpi@1.4.3%gcc@4.4.7=chaos_5_x86_64_ib+debug: /opt/openmpi-1.4.3-debug
+ openmpi@1.6.5%intel@10.1=chaos_5_x86_64_ib: /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 OpenMPI.
If Spack is asked to build a package that uses one of these MPIs as a
-dependency, it link the package to the pre-installed OpenMPI in
-the given directory.
-
-Each ``packages.yaml`` should begin with a ``packages:`` token, followed
-by a list of package specs. Specs in the ``packages.yaml`` have at most
-one ``path`` tag, which specifies the top-level directory where the
-spec is installed.
-
-Each spec should be as well-defined as reasonably possible. If a
+dependency, it will use the the pre-installed OpenMPI in
+the given directory. This example also specifies that Spack should never
+build its own OpenMPI via the ``nobuild: True`` option.
+
+Each ``packages.yaml`` begins with a ``packages:`` token, followed
+by a list of package names. To specify externals, add a ``paths``
+token under the package name, which lists externals in a
+``spec : /path`` 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.
-All package versions and compilers listed in ``packages.yaml`` should
+Each package version and compilers listed in an external should
have entries in Spack's packages and compiler configuration, even
-the package and compiler may not actually be used.
+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
@@ -103,27 +102,25 @@ 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::
+be:
.. code-block:: yaml
packages:
- - openmpi:
- nobuild: True
- - openmpi@1.4.3%gcc@4.4.7=chaos_5_x86_64_ib:
- path: /opt/openmpi-1.4.3
- - openmpi@1.4.3%gcc@4.4.7=chaos_5_x86_64_ib+debug:
- path: /opt/openmpi-1.4.3-debug
- - openmpi@1.6.5%intel@10.1=chaos_5_x86_64_ib:
- path: /opt/openmpi-1.6.5-intel
+ openmpi:
+ paths:
+ openmpi@1.4.3%gcc@4.4.7=chaos_5_x86_64_ib: /opt/openmpi-1.4.3
+ openmpi@1.4.3%gcc@4.4.7=chaos_5_x86_64_ib+debug: /opt/openmpi-1.4.3-debug
+ openmpi@1.6.5%intel@10.1=chaos_5_x86_64_ib: /opt/openmpi-1.6.5-intel
+ nobuild: True
The addition of the ``nobuild`` 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 ``path``, ``nobuild`` is specified as a property under
-a spec and will prevent building of anything that satisfies that spec.
+a package name.
The ``nobuild`` does not need to be paired with external packages.
-It could also be used alone to forbid versions of packages that may be
+It could also be used alone to forbid packages that may be
buggy or otherwise undesirable.