Update documentation for use on Cray

Updating how to use compilers.yaml on Cray as well as setting up
external packages. Also includes what needs to be set up for usage on
Cray and explains what needs to be done to get Spack properly working.
Also explain the architecture spec and what it does.

1 files changed, 51 insertions, 9 deletions

diff --git a/lib/spack/docs/configuration.rst b/lib/spack/docs/configuration.rst
index a6f876b2aa..b2e81e4334 100644
--- a/lib/spack/docs/configuration.rst
+++ b/lib/spack/docs/configuration.rst
@@ -70,20 +70,31 @@ directory. Here's an example of an external configuration:
    packages:
       openmpi:
          paths:
-            openmpi@1.4.3%gcc@4.4.7 arch=chaos_5_x86_64_ib: /opt/openmpi-1.4.3
-            openmpi@1.4.3%gcc@4.4.7 arch=chaos_5_x86_64_ib+debug: /opt/openmpi-1.4.3-debug
-            openmpi@1.6.5%intel@10.1 arch=chaos_5_x86_64_ib: /opt/openmpi-1.6.5-intel
+            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.
+the given directory. Packages.yaml can also be used to specify modules
+
+Here's an example of an external configuration for cray modules:
+
+.. code-block:: yaml
+  packages:
+      mpich:
+        modules:
+            mpich@7.3.1%gcc@5.2.0 arch=cray_xc-haswell-CNL10: cray-mpich
+            mpich@7.3.1%intel@16.0.0.109 arch=cray_xc-haswell-CNL10: cray-mpich
+
+
 
 Each ``packages.yaml`` begins with a ``packages:`` token, followed
-by a list of package names.  To specify externals, add a ``paths``
+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`` format.  Each spec should be as
+``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
@@ -108,9 +119,9 @@ be:
   packages:
     openmpi:
       paths:
-        openmpi@1.4.3%gcc@4.4.7 arch=chaos_5_x86_64_ib: /opt/openmpi-1.4.3
-        openmpi@1.4.3%gcc@4.4.7 arch=chaos_5_x86_64_ib+debug: /opt/openmpi-1.4.3-debug
-        openmpi@1.6.5%intel@10.1 arch=chaos_5_x86_64_ib: /opt/openmpi-1.6.5-intel
+        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
@@ -118,6 +129,9 @@ 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.
@@ -180,7 +194,35 @@ concretization rules.  A provider lists a value that packages may
 ``depend_on`` (e.g, mpi) and a list of rules for fulfilling that
 dependency.
 
+For Cray users, you can specify the default compiler that Spack will
+concretize too. If you want to use the Cray defaults, then set them
+under all: in packages.yaml. You can also specify concretization preferences
+to cray-mpich. Just set the cray-mpich external module as a preferred package,
+set buildable to False and set the preference of mpi to mpich.
+
+Here is an example of a full packages.yaml used at NERSC
 
+.. code-block:: sh
+   packages:
+    mpich:
+        modules:
+            mpich@7.3.1%gcc@5.2.0 arch=cray_xc-CNL10-ivybridge: cray-mpich
+            mpich@7.3.1%intel@16.0.0.109 arch=cray_xc-SuSE11-ivybridge: cray-mpich
+        buildable: False
+    netcdf:
+        modules:
+            netcdf@4.3.3.1%gcc@5.2.0 arch=cray_xc-CNL10-ivybridge: cray-netcdf
+            netcdf@4.3.3.1%intel@16.0.0.109 arch=cray_xc-CNL10-ivybridge: cray-netcdf
+        buildable: False
+    hdf5:
+        paths:
+            hdf5@1.8.14%gcc@5.2.0 arch=cray_xc-CNL10-ivybridge: cray-hdf5
+            hdf5@1.8.14%intel@16.0.0.109 arch=cray_xc-CNL10-ivybridge: cray-hdf5
+        buildable: False
+    all:
+        compiler: [gcc@5.2.0, intel@16.0.0.109]
+        providers:
+            mpi: [mpich, openmpi, intelmpi]ackages:
 
 Profiling
 ------------------