Documentation for configuration

15 files changed, 678 insertions, 388 deletions

diff --git a/lib/spack/docs/build_settings.rst b/lib/spack/docs/build_settings.rst
new file mode 100644
index 0000000000..60ff26f26f
--- /dev/null
+++ b/lib/spack/docs/build_settings.rst
@@ -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.
diff --git a/lib/spack/docs/config_yaml.rst b/lib/spack/docs/config_yaml.rst
new file mode 100644
index 0000000000..7b1a89bc8a
--- /dev/null
+++ b/lib/spack/docs/config_yaml.rst
@@ -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.
diff --git a/lib/spack/docs/configuration.rst b/lib/spack/docs/configuration.rst
index 1244a27d2f..48a4686b84 100644
--- a/lib/spack/docs/configuration.rst
+++ b/lib/spack/docs/configuration.rst
@@ -1,234 +1,252 @@
 .. _configuration:
 
-=============
-Configuration
-=============
-
-.. _install-area:
-
-Install options
-----------------------------
-
-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.
-
-.. _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:
+==============================
+Configuration Files in Spack
+==============================
+
+Spack has many configuration files.  Here is a quick list of them, in
+case you want to skip directly to specific docs:
+
+* :ref:`compilers.yaml <compiler-config>`
+* :ref:`config.yaml <config-yaml>`
+* :ref:`mirrors.yaml <mirrors>`
+* :ref:`modules.yaml <modules>`
+* :ref:`packages.yaml <build-settings>`
+
+-------------------------
+YAML Format
+-------------------------
+
+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
+
+   config:
+     install_tree: $spack/opt/spack
+     module_roots:
+       lmod:   $spack/share/spack/lmod
+     build_stage:
+       - $tempdir
+       - /nfs/tmp2/$user
+
+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.
+
+.. _configuration-scopes:
+
+-------------------------
+Configuration Scopes
+-------------------------
+
+Spack pulls configuration data from files in several directories. There
+are three configuration scopes.  From lowest to highest:
+
+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
-
-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:
+   config:
+     install_tree: $spack/opt/spack
+     module_roots:
+       lmod:   $spack/share/spack/lmod
+     build_stage:
+       - $tempdir
+       - /nfs/tmp2/$user
+
+**site** 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: /some/other/directory
 
-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.
+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:
 
-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:: console
+   :emphasize-lines: 3
 
-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.
+   $ spack config get config
+   config:
+     install_tree: /some/other/directory
+     module_roots:
+       lmod:   $spack/share/spack/lmod
+     build_stage:
+       - $tempdir
+       - /nfs/tmp2/$user
+   $ _
 
-.. _system-packages:
+.. _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:
+
+.. code-block:: yaml
+   :emphasize-lines: 1
+
+   config::
+     install_tree: /some/other/directory
 
-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:
+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:
+**defaults**
 
---------------------------
-Concretization Preferences
---------------------------
+.. code-block:: yaml
+
+   build_stage:
+     - $tempdir
+     - /nfs/tmp2/$user
 
-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.
+Suppose the user configuration adds its *own* list of ``build_stage``
+paths:
 
-Here's an example packages.yaml file that sets preferred packages:
+**user**
 
 .. 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.
+   build_stage:
+     - /lustre-scratch/$user
+     - ~/mystage
+
+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
+   $ _
diff --git a/lib/spack/docs/developer_guide.rst b/lib/spack/docs/developer_guide.rst
index 0942fdd9c3..5ddbaf2478 100644
--- a/lib/spack/docs/developer_guide.rst
+++ b/lib/spack/docs/developer_guide.rst
@@ -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.url`
+  URL parsing, for deducing names and versions of packages from
+  tarball URLs.
+
+:mod:`spack.error`
+  :class:`SpackError <spack.error.SpackError>`, the base class for
+  Spack's exception hierarchy.
 
-:mod:`spack.tty`
+:mod:`llnl.util.tty`
   Basic output functions for all of the messages Spack writes to the
   terminal.
 
-:mod:`spack.color`
+:mod:`llnl.util.tty.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`
+:mod:`llnl.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.
-
 ------------
 Spec objects
 ------------
diff --git a/lib/spack/docs/getting_started.rst b/lib/spack/docs/getting_started.rst
index a125af70e4..4bc7629a3a 100644
--- a/lib/spack/docs/getting_started.rst
+++ b/lib/spack/docs/getting_started.rst
@@ -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`.
diff --git a/lib/spack/docs/index.rst b/lib/spack/docs/index.rst
index 026b01b628..3d1bd86c3e 100644
--- a/lib/spack/docs/index.rst
+++ b/lib/spack/docs/index.rst
@@ -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
diff --git a/lib/spack/docs/module_file_support.rst b/lib/spack/docs/module_file_support.rst
index 502152bc73..19a8161477 100644
--- a/lib/spack/docs/module_file_support.rst
+++ b/lib/spack/docs/module_file_support.rst
@@ -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
 
-------------------------
+.. _cmd-spack-module-refresh:
+
+^^^^^^^^^^^^^^^^^^^^^^^^
 ``spack module refresh``
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
-The command that regenerates module files to update their content or their layout
-is ``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.
diff --git a/lib/spack/spack/cmd/build.py b/lib/spack/spack/cmd/build.py
index 1c43acc2b3..703705a32c 100644
--- a/lib/spack/spack/cmd/build.py
+++ b/lib/spack/spack/cmd/build.py
@@ -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 *
diff --git a/lib/spack/spack/config.py b/lib/spack/spack/config.py
index 904195e47e..c47eb68e09 100644
--- a/lib/spack/spack/config.py
+++ b/lib/spack/spack/config.py
@@ -24,129 +24,27 @@
 ##############################################################################
 """This module implements Spack's configuration file handling.
 
-=========================
-Configuration file scopes
-=========================
-
-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):
-
-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.
-
-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).
-
-3. ``user``: User configuration goes in the user's home directory,
-   specifically in ``~/.spack/``.
-
-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.
+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:
+
+  #. ``default``
+  #. ``site``
+  #. ``user``
+
+And corresponding :ref:`per-platform scopes <platform-scopes>`. Important
+functions in this module are:
+
+* :py:func:`get_config`
+* :py:func:`update_config`
+
+``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``.
+
+When read in, Spack validates configurations with jsonschemas.  The
+schemas are in submodules of :py:mod:`spack.schema`.
 
 """
 
@@ -436,7 +334,26 @@ def _merge_yaml(dest, source):
 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()
diff --git a/lib/spack/spack/schema/compilers.py b/lib/spack/spack/schema/compilers.py
index 72aa8e0d8b..1c7894d675 100644
--- a/lib/spack/spack/schema/compilers.py
+++ b/lib/spack/spack/schema/compilers.py
@@ -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 = {
diff --git a/lib/spack/spack/schema/config.py b/lib/spack/spack/schema/config.py
index a8057f303c..31d4b8a8a8 100644
--- a/lib/spack/spack/schema/config.py
+++ b/lib/spack/spack/schema/config.py
@@ -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#',
diff --git a/lib/spack/spack/schema/mirrors.py b/lib/spack/spack/schema/mirrors.py
index ff599b9c7d..9aa3a0f747 100644
--- a/lib/spack/spack/schema/mirrors.py
+++ b/lib/spack/spack/schema/mirrors.py
@@ -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 = {
diff --git a/lib/spack/spack/schema/modules.py b/lib/spack/spack/schema/modules.py
index bdc70c9ef1..2e776635d2 100644
--- a/lib/spack/spack/schema/modules.py
+++ b/lib/spack/spack/schema/modules.py
@@ -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 = {
diff --git a/lib/spack/spack/schema/packages.py b/lib/spack/spack/schema/packages.py
index e19f3f533b..29c62150ef 100644
--- a/lib/spack/spack/schema/packages.py
+++ b/lib/spack/spack/schema/packages.py
@@ -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 = {
diff --git a/lib/spack/spack/schema/repos.py b/lib/spack/spack/schema/repos.py
index 9f01942422..74dcee7cdc 100644
--- a/lib/spack/spack/schema/repos.py
+++ b/lib/spack/spack/schema/repos.py
@@ -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 = {