Update documentation for new packages.yaml config format.

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.