Add first working version of enzo

Source spack-env.sh to execute spack bootstrap. Then source
spack-env.sh again to get module functionality.

.coveragerc

@@ -0,0 +1,36 @@
+# -*- conf -*-
+# .coveragerc to control coverage.py
+[run]
+parallel = True
+concurrency = multiprocessing
+branch = True
+source = lib
+omit =
+     lib/spack/spack/test/*
+     lib/spack/env/*
+     lib/spack/docs/*
+     lib/spack/external/*
+
+[report]
+# Regexes for lines to exclude from consideration
+exclude_lines =
+    # Have to re-enable the standard pragma
+    pragma: no cover
+
+    # Don't complain about missing debug-only code:
+    def __repr__
+    if self\.debug
+
+    # Don't complain if tests don't hit defensive assertion code:
+    raise AssertionError
+    raise NotImplementedError
+
+    # Don't complain if non-runnable code isn't run:
+    if 0:
+    if False:
+    if __name__ == .__main__.:
+
+ignore_errors = True
+
+[html]
+directory = htmlcov

.flake8

@@ -0,0 +1,26 @@
+# -*- conf -*-
+# flake8 settings for Spack.
+#
+# Below we describe which flake8 checks Spack ignores and what the
+# rationale is.
+#
+# Let people line things up nicely:
+# - E129: visually indented line with same indent as next logical line
+# - E221: multiple spaces before operator
+# - E241: multiple spaces after ','
+# - E272: multiple spaces before keyword
+#
+# Let people use terse Python features:
+# - E731 : lambda expressions
+#
+# Spack allows wildcard imports:
+# - F403: disable wildcard import
+#
+# These are required to get the package.py files to test clean.
+# - F405: `name` may be undefined, or undefined from star imports: `module`
+# - F821: undefined name `name` (needed for cmake, configure, etc.)
+# - F999: syntax error in doctest
+#
+[flake8]
+ignore = E129,E221,E241,E272,E731,F403,F405,F821,F999
+max-line-length = 79

.gitignore

@@ -1,8 +1,24 @@
+/db
 /var/spack/stage
+/var/spack/cache
+/var/spack/repos/*/index.yaml
+/var/spack/repos/*/lock
 *.pyc
-/opt/
+/opt
 *~
 .DS_Store
 .idea
+/etc/spack/licenses
+/etc/spack/*.yaml
 /etc/spackconfig
 /share/spack/dotkit
+/share/spack/modules
+/share/spack/lmod
+/TAGS
+*.swp
+/htmlcov
+.coverage
+#*
+.#*
+/.cache
+/bin/spackc

.mailmap

@@ -0,0 +1,56 @@
+Abhinav Bhatele       <bhatele@llnl.gov>                Abhinav Bhatele         <bhatele@gmail.com>
+Adam Moody            <moody20@llnl.gov>                Adam T. Moody           <moody20@llnl.gov>
+Alfredo Gimenez       <gimenez1@llnl.gov>               Alfredo Gimenez         <alfredo.gimenez@gmail.com>
+Alfredo Gimenez       <gimenez1@llnl.gov>               Alfredo Adolfo Gimenez  <alfredo.gimenez@gmail.com>
+Andrew Williams       <williamsa89@cardiff.ac.uk>       Andrew Williams         <andrew@alshain.org.uk>
+Ben Boeckel           <ben.boeckel@kitware.com>         Ben Boeckel             <mathstuf@gmail.com>
+Ben Boeckel           <ben.boeckel@kitware.com>         Ben Boeckel             <mathstuf@users.noreply.github.com>
+Benedikt Hegner       <hegner@cern.ch>                  Benedikt Hegner         <benedikt.hegner@cern.ch>
+Brett Viren           <bv@bnl.gov>                      Brett Viren             <brett.viren@gmail.com>
+David Boehme          <boehme3@llnl.gov>                David Boehme            <boehme3@sierra324.llnl.gov>
+David Boehme          <boehme3@llnl.gov>                David Boehme            <boehme3@sierra648.llnl.gov>
+David Poliakoff       <poliakoff1@llnl.gov>             David Poliakoff         <david.poliakoff@gmail.com>
+Dhanannjay Deo        <dhanannjay.deo@kitware.com>      Dhanannjay 'Djay' Deo   <dhanannjay.deo@kitware.com>
+Elizabeth Fischer     <elizabeth.fischer@columbia.edu>  Elizabeth F             <elizabeth.fischer@columbia.edu>
+Elizabeth Fischer     <elizabeth.fischer@columbia.edu>  Elizabeth F             <rpf2116@columbia.edu>
+Elizabeth Fischer     <elizabeth.fischer@columbia.edu>  Elizabeth Fischer       <rpf2116@columbia.edu>
+Elizabeth Fischer     <elizabeth.fischer@columbia.edu>  citibeth                <rpf2116@columbia.edu>
+Geoffrey Oxberry      <oxberry1@llnl.gov>               Geoffrey Oxberry        <goxberry@gmail.com>
+Glenn Johnson         <glenn-johnson@uiowa.edu>         Glenn Johnson           <gjohnson@argon-ohpc.hpc.uiowa.edu>
+Glenn Johnson         <glenn-johnson@uiowa.edu>         Glenn Johnson           <glennpj@gmail.com>
+Gregory Becker        <becker33@llnl.gov>               Gregory Becker          <becker33.llnl.gov>
+Gregory Becker        <becker33@llnl.gov>               becker33                <becker33.llnl.gov>
+Gregory Becker        <becker33@llnl.gov>               becker33                <becker33@llnl.gov>
+Gregory L. Lee        <lee218@llnl.gov>                 Greg Lee                <lee218@llnl.gov>
+Gregory L. Lee        <lee218@llnl.gov>                 Gregory L. Lee          <lee218@cab687.llnl.gov>
+Gregory L. Lee        <lee218@llnl.gov>                 Gregory L. Lee          <lee218@cab690.llnl.gov>
+Gregory L. Lee        <lee218@llnl.gov>                 Gregory L. Lee          <lee218@catalyst159.llnl.gov>
+Gregory L. Lee        <lee218@llnl.gov>                 Gregory L. Lee          <lee218@surface86.llnl.gov>
+Gregory L. Lee        <lee218@llnl.gov>                 Gregory Lee             <lee218@llnl.gov>
+Ian Lee               <lee1001@llnl.gov>                Ian Lee                 <IanLee1521@gmail.com>
+James Wynne III       <wynnejr@ornl.gov>                James Riley Wynne III   <wynnejr@ornl.gov>
+James Wynne III       <wynnejr@ornl.gov>                James Wynne III         <wynnejr@gpujake.com>
+Joachim Protze        <protze@rz.rwth-aachen.de>        jprotze                 <protze@rz.rwth-aachen.de>
+Kelly (KT) Thompson   <kgt@lanl.gov>                                            <kellyt@MENE.localdomain>
+Kelly (KT) Thompson   <kgt@lanl.gov>                    Kelly Thompson          <KineticTheory@users.noreply.github.com>
+Kevin Brandstatter    <kjbrandstatter@gmail.com>        Kevin Brandstatter      <kbrandst@hawk.iit.edu>
+Luc Jaulmes           <luc.jaulmes@bsc.es>              Luc Jaulmes             <jaulmes1@llnl.gov>
+Mario Melara          <maamelara@gmail.com>             Mario Melara            <mamelara@genepool1.nersc.gov>
+Mark Miller           <miller86@llnl.gov>               miller86                <miller86@llnl.gov>
+Massimiliano Culpo    <massimiliano.culpo@epfl.ch>      Massimiliano Culpo      <massimiliano.culpo@googlemail.com>
+Massimiliano Culpo    <massimiliano.culpo@epfl.ch>      alalazo                 <massimiliano.culpo@googlemail.com>
+Mayeul d'Avezac       <m.davezac@ucl.ac.uk>             Mayeul d'Avezac         <mdavezac@gmail.com>
+Mitchell Devlin       <mitchell.r.devlin@gmail.com>     Mitchell Devlin         <devlin@blogin4.lcrc.anl.gov>
+Nicolas Richart       <nicolas.richart@epfl.ch>         Nicolas                 <nrichart@users.noreply.github.com>
+Nicolas Richart       <nicolas.richart@epfl.ch>         Nicolas Richart         <nrichart@users.noreply.github.com>
+Peter Scheibel        <scheibel1@llnl.gov>              scheibelp               <scheibel1@llnl.gov>
+Robert D. French      <frenchrd@ornl.gov>               Robert D. French        <robert@robertdfrench.me>
+Robert D. French      <frenchrd@ornl.gov>               Robert.French           <frenchrd@ornl.gov>
+Robert D. French      <frenchrd@ornl.gov>               robertdfrench           <frenchrd@ornl.gov>
+Saravan Pantham       <saravan.pantham@gmail.com>       Saravan Pantham         <pantham1@surface86.llnl.gov>
+Stephen Herbein       <sherbein@udel.edu>               Stephen Herbein         <stephen272@gmail.com>
+Todd Gamblin          <tgamblin@llnl.gov>               George Todd Gamblin     <gamblin2@llnl.gov>
+Todd Gamblin          <tgamblin@llnl.gov>               Todd Gamblin            <gamblin2@llnl.gov>
+Tom Scogland          <tscogland@llnl.gov>              Tom Scogland            <scogland1@llnl.gov>
+Tom Scogland          <tscogland@llnl.gov>              Tom Scogland            <tom.scogland@gmail.com>
+Tzanio Kolev          <tzanio@llnl.gov>                 Tzanio                  <tzanio@llnl.gov>

.travis.yml

@@ -0,0 +1,91 @@
+#=============================================================================
+# Project settings
+#=============================================================================
+language: python
+
+# Only build master and develop on push; do not build every branch.
+branches:
+  only:
+    - master
+    - develop
+
+#=============================================================================
+# Build matrix
+#=============================================================================
+python:
+  - 2.6
+  - 2.7
+
+env:
+  - TEST_SUITE=unit
+  - TEST_SUITE=flake8
+  - TEST_SUITE=doc
+
+matrix:
+  # Flake8 and Sphinx no longer support Python 2.6, and one run is enough.
+  exclude:
+  - python: 2.6
+    env: TEST_SUITE=flake8
+  - python: 2.6
+    env: TEST_SUITE=doc
+  # Explicitly include an OS X build with homebrew's python.
+  # Works around Python issues on Travis for OSX, described here:
+  # http://blog.fizyk.net.pl/blog/running-python-tests-on-traviss-osx-workers.html
+  include:
+  - os: osx
+    language: generic
+    env: TEST_SUITE=unit
+
+#=============================================================================
+# Environment
+#=============================================================================
+# Use new Travis infrastructure (Docker can't sudo yet)
+sudo: false
+
+# Docs need graphviz to build
+addons:
+  apt:
+    packages:
+      - gfortran
+      - graphviz
+      - libyaml-dev
+
+# Work around Travis's lack of support for Python on OSX
+before_install:
+  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then brew update; fi
+  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then brew ls --versions python > /dev/null || brew install python; fi
+  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then brew ls --versions gcc    > /dev/null || brew install gcc;    fi
+  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then virtualenv venv; fi
+  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then source venv/bin/activate; fi
+
+# Install various dependencies
+install:
+  - pip install --upgrade coveralls
+  - pip install --upgrade flake8
+  - pip install --upgrade sphinx
+  - pip install --upgrade mercurial
+
+before_script:
+  # Need this for the git tests to succeed.
+  - git config --global user.email "spack@example.com"
+  - git config --global user.name "Test User"
+
+  # Need this to be able to compute the list of changed files
+  - git fetch origin develop:develop
+
+#=============================================================================
+# Building
+#=============================================================================
+script: share/spack/qa/run-$TEST_SUITE-tests
+
+after_success:
+  - if [[ $TEST_SUITE == unit && $TRAVIS_PYTHON_VERSION == 2.7 && $TRAVIS_OS_NAME == "linux" ]]; then coveralls; fi
+
+#=============================================================================
+# Notifications
+#=============================================================================
+notifications:
+  email:
+    recipients: tgamblin@llnl.gov
+    on_success: change
+    on_failure: always

LICENSE

@@ -1,76 +1,82 @@
-Copyright (c) 2013, Lawrence Livermore National Security, LLC.
+########################################################################
+GNU LESSER GENERAL PUBLIC LICENSE (Lesser GPL)
+Version 2.1, February 1999
+########################################################################
+Copyright (c) 2013-2016, Lawrence Livermore National Security, LLC.
 Produced at the Lawrence Livermore National Laboratory.
 
 This file is part of Spack.
-Written by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
+Created by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
 LLNL-CODE-647188
 
-For details, see https://scalability-llnl.github.io/spack
+For details, see https://github.com/llnl/spack
 
 This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License (as published by
-the Free Software Foundation) version 2.1 dated February 1999.
+it under the terms of the GNU Lesser General Public License (as
+published by the Free Software Foundation) version 2.1, February 1999.
 
 This program is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
-conditions of the GNU General Public License for more details.
+conditions of the GNU Lesser General Public License for more details.
 
-You should have received a copy of the GNU Lesser General Public License
-along with this program; if not, write to the Free Software Foundation,
-Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+You should have received a copy of the GNU Lesser General Public
+License along with this program; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 
-OUR NOTICE AND TERMS AND CONDITIONS OF THE GNU GENERAL PUBLIC LICENSE
+########################################################################
+LLNL NOTICE AND TERMS AND CONDITIONS OF THE GNU LGPL
 
-Our Preamble Notice
+LLNL Preamble Notice
 
-A. This notice is required to be provided under our contract with the
-U.S. Department of Energy (DOE). This work was produced at the
-Lawrence Livermore National Laboratory under Contract
-No. DE-AC52-07NA27344 with the DOE.
+A. This notice is required to be provided under LLNL's contract with
+   the U.S. Department of Energy (DOE). This work was produced at the
+   Lawrence Livermore National Laboratory under Contract
+   No. DE-AC52-07NA27344 with the DOE.
 
 B. Neither the United States Government nor Lawrence Livermore
-National Security, LLC nor any of their employees, makes any warranty,
-express or implied, or assumes any liability or responsibility for the
-accuracy, completeness, or usefulness of any information, apparatus,
-product, or process disclosed, or represents that its use would not
-infringe privately-owned rights.
+   National Security, LLC nor any of their employees, makes any
+   warranty, express or implied, or assumes any liability or
+   responsibility for the accuracy, completeness, or usefulness of any
+   information, apparatus, product, or process disclosed, or
+   represents that its use would not infringe privately-owned rights.
 
 C. Also, reference herein to any specific commercial products,
-process, or services by trade name, trademark, manufacturer or
-otherwise does not necessarily constitute or imply its endorsement,
-recommendation, or favoring by the United States Government or
-Lawrence Livermore National Security, LLC. The views and opinions of
-authors expressed herein do not necessarily state or reflect those of
-the United States Government or Lawrence Livermore National Security,
-LLC, and shall not be used for advertising or product endorsement
-purposes.
+   process, or services by trade name, trademark, manufacturer or
+   otherwise does not necessarily constitute or imply its endorsement,
+   recommendation, or favoring by the United States Government or
+   Lawrence Livermore National Security, LLC. The views and opinions
+   of authors expressed herein do not necessarily state or reflect
+   those of the United States Government or Lawrence Livermore
+   National Security, LLC, and shall not be used for advertising or
+   product endorsement purposes.
 
 The precise terms and conditions for copying, distribution and
 modification follows.
 
-GNU Lesser GPL terms and Conditions for Copying, Distribution, and
-Modification
+########################################################################
+GNU LESSER GENERAL PUBLIC LICENSE
+TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
 
 0. This License Agreement applies to any software library or other
 program which contains a notice placed by the copyright holder or
 other authorized party saying it may be distributed under the terms of
-this Lesser General Public License (also called “this License”). Each
-licensee is addressed as “you”.
+this Lesser General Public License (also called "this License"). Each
+licensee is addressed as "you".
 
-A “library” means a collection of software functions and/or data
+A "library" means a collection of software functions and/or data
 prepared so as to be conveniently linked with application programs
 (which use some of those functions and data) to form executables.
 
-The “Library”, below, refers to any such software library or work
-which has been distributed under these terms. A “work based on the
-Library” means either the Library or any derivative work under
+The "Library", below, refers to any such software library or work
+which has been distributed under these terms. A "work based on the
+Library" means either the Library or any derivative work under
 copyright law: that is to say, a work containing the Library or a
 portion of it, either verbatim or with modifications and/or translated
 straightforwardly into another language. (Hereinafter, translation is
-included without limitation in the term “modification”.)
+included without limitation in the term "modification".)
 
-“Source code” for a work means the preferred form of the work for
+"Source code" for a work means the preferred form of the work for
 making modifications to it. For a library, complete source code means
 all the source code for all modules it contains, plus any associated
 interface definition files, plus the scripts used to control
@@ -83,7 +89,7 @@ covered only if its contents constitute a work based on the Library
 it). Whether that is true depends on what the Library does and what
 the program that uses the Library does.
 
-1. You may copy and distribute verbatim copies of the Library’s
+1. You may copy and distribute verbatim copies of the Library's
 complete source code as you receive it, in any medium, provided that
 you conspicuously and appropriately publish on each copy an
 appropriate copyright notice and disclaimer of warranty; keep intact
@@ -170,17 +176,17 @@ source along with the object code.
 
 5. A program that contains no derivative of any portion of the
 Library, but is designed to work with the Library by being compiled or
-linked with it, is called a “work that uses the Library”. Such a work,
+linked with it, is called a "work that uses the Library". Such a work,
 in isolation, is not a derivative work of the Library, and therefore
 falls outside the scope of this License.
 
-However, linking a “work that uses the Library” with the Library
+However, linking a "work that uses the Library" with the Library
 creates an executable that is a derivative of the Library (because it
-contains portions of the Library), rather than a “work that uses the
-library”. The executable is therefore covered by this License. Section
+contains portions of the Library), rather than a "work that uses the
+library". The executable is therefore covered by this License. Section
 6 states terms for distribution of such executables.
 
-When a “work that uses the Library” uses material from a header file
+When a "work that uses the Library" uses material from a header file
 that is part of the Library, the object code for the work may be a
 derivative work of the Library even though the source code is
 not. Whether this is true is especially significant if the work can be
@@ -200,10 +206,10 @@ distribute the object code for the work under the terms of Section
 whether or not they are linked directly with the Library itself.
 
 6. As an exception to the Sections above, you may also combine or link
-a “work that uses the Library” with the Library to produce a work
+a "work that uses the Library" with the Library to produce a work
 containing portions of the Library, and distribute that work under
 terms of your choice, provided that the terms permit modification of
-the work for the customer’s own use and reverse engineering for
+the work for the customer's own use and reverse engineering for
 debugging such modifications.
 
 You must give prominent notice with each copy of the work that the
@@ -218,7 +224,7 @@ a) Accompany the work with the complete corresponding machine-readable
 source code for the Library including whatever changes were used in
 the work (which must be distributed under Sections 1 and 2 above);
 and, if the work is an executable liked with the Library, with the
-complete machine-readable “work that uses the Library”, as object code
+complete machine-readable "work that uses the Library", as object code
 and/or source code, so that the user can modify the Library and then
 relink to produce a modified executable containing the modified
 Library. (It is understood that the user who changes the contents of
@@ -227,7 +233,7 @@ recompile the application to use the modified definitions.)
 
 b) Use a suitable shared library mechanism for linking with the
 Library. A suitable mechanism is one that (1) uses at run time a copy
-of the library already present on the user’s computer system, rather
+of the library already present on the user's computer system, rather
 than copying library functions into the executable, and (2) will
 operate properly with a modified version of the library, if the user
 installs one, as long as the modified version is interface- compatible
@@ -245,8 +251,8 @@ specified materials from the same place.
 e) Verify that the user has already received a copy of these materials
 or that you have already sent this user a copy.
 
-For an executable, the required form of the “work that uses the
-Library” must include any data and utility programs needed for
+For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
 reproducing the executable from it. However, as a special exception,
 the materials to be distributed need not include anything that is
 normally distributed (in either source or binary form) with the major
@@ -296,7 +302,7 @@ the Library or works based on it.
 Library), the recipient automatically receives a license from the
 original licensor to copy, distribute, link with or modify the Library
 subject to these terms and conditions. You may not impose any further
-restrictions on the recipients’ exercise of the rights granted
+restrictions on the recipients' exercise of the rights granted
 herein. You are not responsible for enforcing compliance by third
 parties with this License.
 
@@ -347,7 +353,7 @@ differ in detail to address new problems or concerns.
 
 Each version is given a distinguishing version number. If the Library
 specifies a version number of this License which applies to it and
-“any later version”, you have the option of following the terms and
+"any later version", you have the option of following the terms and
 conditions either of that version or of any later version published by
 the Free Software Foundation. If the Library does not specify a
 license version number, you may choose any version ever published by
@@ -367,7 +373,7 @@ NO WARRANTY
 1 BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
 FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
-PARTIES PROVIDE THE LIBRARY “AS IS” WITHOUT WARRANTY OF ANY KIND,
+PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND,
 EITHER EXPRESSED OR IMPLIED INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE

README.md

@@ -1,5 +1,8 @@
-Spack
-===========
+![image](share/spack/logo/spack-logo-text-64.png "Spack")
+============
+
+[![Build Status](https://travis-ci.org/LLNL/spack.svg?branch=develop)](https://travis-ci.org/LLNL/spack)
+[![Coverage Status](https://coveralls.io/repos/github/LLNL/spack/badge.svg?branch=develop)](https://coveralls.io/github/LLNL/spack?branch=develop)
 
 Spack is a package management tool designed to support multiple
 versions and configurations of software on a wide variety of platforms
@@ -13,26 +16,87 @@ can coexist on the same system.
 Most importantly, Spack is simple. It offers a simple spec syntax so
 that users can specify versions and configuration options
 concisely. Spack is also simple for package authors: package files are
-writtin in pure Python, and specs allow package authors to write a
+written in pure Python, and specs allow package authors to write a
 single build script for many different builds of the same package.
 
 See the
-[Feature Overview](http://scalability-llnl.github.io/spack/features.html)
+[Feature Overview](http://spack.readthedocs.io/en/latest/features.html)
 for examples and highlights.
 
 To install spack and install your first package:
 
-    $ git clone git@github.com:scalability-llnl/spack.git
+    $ git clone https://github.com/llnl/spack.git
     $ cd spack/bin
     $ ./spack install libelf
 
 Documentation
 ----------------
 
-[Full documentation](http://scalability-llnl.github.io/spack)
-for Spack is also available.
+[**Full documentation**](http://spack.readthedocs.io/) for Spack is
+the first place to look.
+
+We've also got a [**Spack 101 Tutorial**](http://spack.readthedocs.io/en/latest/tutorial_sc16.html),
+so you can learn Spack yourself, or teach users at your own site.
+
+See also:
+  * [Technical paper](http://www.computer.org/csdl/proceedings/sc/2015/3723/00/2807623.pdf) and
+    [slides](https://tgamblin.github.io/files/Gamblin-Spack-SC15-Talk.pdf) on Spack's design and implementation.
+  * [Short presentation](https://tgamblin.github.io/files/Gamblin-Spack-Lightning-Talk-BOF-SC15.pdf) from the *Getting Scientific Software Installed* BOF session at Supercomputing 2015.
+
+
+Get Involved!
+------------------------
+
+Spack is an open source project.  Questions, discussion, and
+contributions are welcome. Contributions can be anything from new
+packages to bugfixes, or even new core features.
+
+### Mailing list
+
+If you are interested in contributing to spack, the first step is to
+join the mailing list.  We're using a Google Group for this, and you
+can join it here:
+
+  * [Spack Google Group](https://groups.google.com/d/forum/spack)
+
+### Contributions
+
+Contributing to Spack is relatively easy.  Just send us a
+[pull request](https://help.github.com/articles/using-pull-requests/).
+When you send your request, make ``develop`` the destination branch on the
+[Spack repository](https://github.com/LLNL/spack).
+
+Your PR must pass Spack's unit tests and documentation tests, and must be
+[PEP 8](https://www.python.org/dev/peps/pep-0008/) compliant.
+We enforce these guidelines with [Travis CI](https://travis-ci.org/LLNL/spack).
+To run these tests locally, and for helpful tips on git, see our
+[Contribution Guide](http://spack.readthedocs.io/en/latest/contribution_guide.html).
+
+Spack uses a rough approximation of the [Git
+Flow](http://nvie.com/posts/a-successful-git-branching-model/)
+branching model.  The ``develop`` branch contains the latest
+contributions, and ``master`` is always tagged and points to the
+latest stable release.
+
 
 Authors
 ----------------
-Spack was written by Todd Gamblin, tgamblin@llnl.gov.
-LLNL-CODE-647188
+Many thanks go to Spack's [contributors](https://github.com/llnl/spack/graphs/contributors).
+
+Spack was originally written by Todd Gamblin, tgamblin@llnl.gov.
+
+### Citing Spack
+
+If you are referencing Spack in a publication, please cite the following paper:
+
+ * Todd Gamblin, Matthew P. LeGendre, Michael R. Collette, Gregory L. Lee,
+   Adam Moody, Bronis R. de Supinski, and W. Scott Futral.
+   [**The Spack Package Manager: Bringing Order to HPC Software Chaos**](http://www.computer.org/csdl/proceedings/sc/2015/3723/00/2807623.pdf).
+   In *Supercomputing 2015 (SC’15)*, Austin, Texas, November 15-20 2015. LLNL-CONF-669890.
+
+Release
+----------------
+Spack is released under an LGPL license.  For more details see the
+LICENSE file.
+
+``LLNL-CODE-647188``

bin/sbang

@@ -0,0 +1,123 @@
+#!/bin/bash
+##############################################################################
+# Copyright (c) 2013-2016, Lawrence Livermore National Security, LLC.
+# Produced at the Lawrence Livermore National Laboratory.
+#
+# This file is part of Spack.
+# Created by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
+# LLNL-CODE-647188
+#
+# For details, see https://github.com/llnl/spack
+# Please also see the LICENSE file for our notice and the LGPL.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License (as
+# published by the Free Software Foundation) version 2.1, February 1999.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
+# conditions of the GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+##############################################################################
+#
+# `sbang`: Run scripts with long shebang lines.
+#
+# Many operating systems limit the length of shebang lines, making it
+# hard to use interpreters that are deep in the directory hierarchy.
+# `sbang` can run such scripts, either as a shebang interpreter, or
+# directly on the command line.
+#
+# Usage
+# -----------------------------
+# Suppose you have a script, long-shebang.sh, like this:
+#
+#     1    #!/very/long/path/to/some/interpreter
+#     2
+#     3    echo "success!"
+#
+# Invoking this script will result in an error on some OS's.  On
+# Linux, you get this:
+#
+#     $ ./long-shebang.sh
+#     -bash: ./long: /very/long/path/to/some/interp: bad interpreter:
+#            No such file or directory
+#
+# On Mac OS X, the system simply assumes the interpreter is the shell
+# and tries to run with it, which is likely not what you want.
+#
+#
+# `sbang` on the command line
+# -----------------------------
+# You can use `sbang` in two ways.  The first is to use it directly,
+# from the command line, like this:
+#
+#     $ sbang ./long-shebang.sh
+#     success!
+#
+#
+# `sbang` as the interpreter
+# -----------------------------
+# You can also use `sbang` *as* the interpreter for your script. Put
+# `#!/bin/bash /path/to/sbang` on line 1, and move the original
+# shebang to line 2 of the script:
+#
+#     1    #!/bin/bash /path/to/sbang
+#     2    #!/long/path/to/real/interpreter with arguments
+#     3
+#     4    echo "success!"
+#
+#     $ ./long-shebang.sh
+#     success!
+#
+# On Linux, you could shorten line 1 to `#!/path/to/sbang`, but other
+# operating systems like Mac OS X require the interpreter to be a
+# binary, so it's best to use `sbang` as a `bash` argument.
+# Obviously, for this to work, `sbang` needs to have a short enough
+# path that *it* will run without hitting OS limits.
+#
+# For Lua, scripts the second line can't start with #!, as # is not
+# the comment character in lua (even though lua ignores #! on the
+# *first* line of a script).  So, instrument a lua script like this,
+# using -- instead of # on the second line:
+#
+#     1    #!/bin/bash /path/to/sbang
+#     2    --!/long/path/to/lua with arguments
+#     3
+#     4    print "success!"
+#
+# How it works
+# -----------------------------
+# `sbang` is a very simple bash script. It looks at the first two
+# lines of a script argument and runs the last line starting with
+# `#!`, with the script as an argument. It also forwards arguments.
+#
+
+# First argument is the script we want to actually run.
+script="$1"
+
+# Search the first two lines of script for interpreters.
+lines=0
+while read line && ((lines < 2)) ; do
+    if [[ "$line" = '#!'* ]]; then
+        interpreter="${line#\#!}"
+    elif [[ "$line" = '--!'*lua* ]]; then
+        interpreter="${line#--!}"
+    fi
+    lines=$((lines+1))
+done < "$script"
+
+# Invoke any interpreter found, or raise an error if none was found.
+if [[ -n "$interpreter" ]]; then
+    if [[ "${interpreter##*/}" = "perl" ]]; then
+        exec $interpreter -x "$@"
+    else
+        exec $interpreter "$@"
+    fi
+else
+    echo "error: sbang found no interpreter in $script"
+    exit 1
+fi

bin/spack

@@ -1,34 +1,37 @@
 #!/usr/bin/env python
+# flake8: noqa
 ##############################################################################
-# Copyright (c) 2013, Lawrence Livermore National Security, LLC.
+# Copyright (c) 2013-2016, Lawrence Livermore National Security, LLC.
 # Produced at the Lawrence Livermore National Laboratory.
 #
 # This file is part of Spack.
-# Written by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
+# Created by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
 # LLNL-CODE-647188
 #
-# For details, see https://scalability-llnl.github.io/spack
+# For details, see https://github.com/llnl/spack
 # Please also see the LICENSE file for our notice and the LGPL.
 #
 # This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License (as published by
-# the Free Software Foundation) version 2.1 dated February 1999.
+# it under the terms of the GNU Lesser General Public License (as
+# published by the Free Software Foundation) version 2.1, February 1999.
 #
 # This program is distributed in the hope that it will be useful, but
 # WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
-# conditions of the GNU General Public License for more details.
+# conditions of the GNU Lesser General Public License for more details.
 #
-# You should have received a copy of the GNU Lesser General Public License
-# along with this program; if not, write to the Free Software Foundation,
-# Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+# You should have received a copy of the GNU Lesser General Public
+# 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 sys
-if not sys.version_info[:2] >= (2,7):
-    sys.exit("Spack requires Python 2.7.  Version was %s." % sys.version_info)
+if (sys.version_info[0] > 2) or (sys.version_info[:2] < (2, 6)):
+    v_info = sys.version_info[:3]
+    sys.exit("Spack requires Python 2.6 or 2.7. "
+             "This is Python %d.%d.%d." % v_info)
 
 import os
-import argparse
+import inspect
 
 # Find spack's location and its prefix.
 SPACK_FILE = os.path.realpath(os.path.expanduser(__file__))
@@ -39,6 +42,34 @@ SPACK_PREFIX = os.path.dirname(os.path.dirname(SPACK_FILE))
 SPACK_LIB_PATH = os.path.join(SPACK_PREFIX, "lib", "spack")
 sys.path.insert(0, SPACK_LIB_PATH)
 
+# Add external libs
+SPACK_EXTERNAL_LIBS = os.path.join(SPACK_LIB_PATH, "external")
+sys.path.insert(0, SPACK_EXTERNAL_LIBS)
+
+# Quick and dirty check to clean orphaned .pyc files left over from
+# previous revisions.  These files were present in earlier versions of
+# Spack, were removed, but shadow system modules that Spack still
+# imports.  If we leave them, Spack will fail in mysterious ways.
+# TODO: more elegant solution for orphaned pyc files.
+orphaned_pyc_files = [
+    os.path.join(SPACK_EXTERNAL_LIBS, 'functools.pyc'),
+    os.path.join(SPACK_EXTERNAL_LIBS, 'ordereddict.pyc'),
+    os.path.join(SPACK_LIB_PATH, 'spack', 'platforms', 'cray_xc.pyc'),
+    os.path.join(SPACK_LIB_PATH, 'spack', 'cmd', 'package-list.pyc'),
+    os.path.join(SPACK_LIB_PATH, 'spack', 'cmd', 'test-install.pyc'),
+    os.path.join(SPACK_LIB_PATH, 'spack', 'cmd', 'url-parse.pyc'),
+    os.path.join(SPACK_LIB_PATH, 'spack', 'test', 'yaml.pyc')
+]
+
+for pyc_file in orphaned_pyc_files:
+    if not os.path.exists(pyc_file):
+        continue
+    try:
+        os.remove(pyc_file)
+    except OSError as e:
+        print ("WARNING: Spack may fail mysteriously. "
+               "Couldn't remove orphaned .pyc file: %s" % pyc_file)
+
 # If there is no working directory, use the spack prefix.
 try:
     working_dir = os.getcwd()
@@ -49,61 +80,133 @@ except OSError:
 # clean up the scope and start using spack package instead.
 del SPACK_FILE, SPACK_PREFIX, SPACK_LIB_PATH
 import llnl.util.tty as tty
+from llnl.util.tty.color import *
 import spack
 from spack.error import SpackError
+import argparse
 
 # Command parsing
 parser = argparse.ArgumentParser(
-    description='Spack: the Supercomputing PACKage Manager.')
+    formatter_class=argparse.RawTextHelpFormatter,
+    description="Spack: the Supercomputing PACKage Manager." + colorize("""
+
+spec expressions:
+  PACKAGE [CONSTRAINTS]
+
+    CONSTRAINTS:
+      @c{@version}
+      @g{%compiler  @compiler_version}
+      @B{+variant}
+      @r{-variant} or @r{~variant}
+      @m{=architecture}
+      [^DEPENDENCY [CONSTRAINTS] ...]"""))
+
+parser.add_argument('-d', '--debug', action='store_true',
+                    help="Write out debug logs during compile")
+parser.add_argument('-D', '--pdb', action='store_true',
+                    help="Run spack under the pdb debugger")
+parser.add_argument('-k', '--insecure', action='store_true',
+                    help="Do not check ssl certificates when downloading.")
+parser.add_argument('-m', '--mock', action='store_true',
+                    help="Use mock packages instead of real ones.")
+parser.add_argument('-p', '--profile', action='store_true',
+                    help="Profile execution using cProfile.")
+parser.add_argument('-v', '--verbose', action='store_true',
+                    help="Print additional output during builds")
+parser.add_argument('-s', '--stacktrace', action='store_true',
+                    help="Add stacktrace information to all printed statements")
 parser.add_argument('-V', '--version', action='version',
                     version="%s" % spack.spack_version)
-parser.add_argument('-v', '--verbose', action='store_true', dest='verbose',
-                    help="Print additional output during builds")
-parser.add_argument('-d', '--debug', action='store_true', dest='debug',
-                    help="Write out debug logs during compile")
-parser.add_argument('-k', '--insecure', action='store_true', dest='insecure',
-                    help="Do not check ssl certificates when downloading archives.")
-parser.add_argument('-m', '--mock', action='store_true', dest='mock',
-                    help="Use mock packages instead of real ones.")
 
 # each command module implements a parser() function, to which we pass its
 # subparser for setup.
 subparsers = parser.add_subparsers(metavar='SUBCOMMAND', dest="command")
 
+
 import spack.cmd
 for cmd in spack.cmd.commands:
     module = spack.cmd.get_module(cmd)
-    subparser = subparsers.add_parser(cmd, help=module.description)
+    cmd_name = cmd.replace('_', '-')
+    subparser = subparsers.add_parser(cmd_name, help=module.description)
     module.setup_parser(subparser)
-args = parser.parse_args()
 
-# Set up environment based on args.
-tty.set_verbose(args.verbose)
-tty.set_debug(args.debug)
-spack.debug = args.debug
 
-spack.spack_working_dir = working_dir
-if args.mock:
-    from spack.packages import PackageDB
-    spack.db = PackageDB(spack.mock_packages_path)
+def _main(args, unknown_args):
+    # Set up environment based on args.
+    tty.set_verbose(args.verbose)
+    tty.set_debug(args.debug)
+    tty.set_stacktrace(args.stacktrace)
+    spack.debug = args.debug
 
-# If the user asked for it, don't check ssl certs.
-if args.insecure:
-    tty.warn("You asked for --insecure, which does not check SSL certificates.")
-    spack.curl.add_default_arg('-k')
-
-# Try to load the particular command asked for and run it
-command = spack.cmd.get_command(args.command)
-try:
-    command(parser, args)
-except SpackError, e:
     if spack.debug:
-        # In debug mode, raise with a full stack trace.
-        raise
-    elif e.long_message:
-        tty.die(e.message, e.long_message)
-    else:
-        tty.die(e.message)
+        import spack.util.debug as debug
+        debug.register_interrupt_handler()
 
-except KeyboardInterrupt:
-    tty.die("Keyboard interrupt.")
+    # Run any available pre-run hooks
+    spack.hooks.pre_run()
+
+    spack.spack_working_dir = working_dir
+    if args.mock:
+        from spack.repository import RepoPath
+        spack.repo.swap(RepoPath(spack.mock_packages_path))
+
+    # If the user asked for it, don't check ssl certs.
+    if args.insecure:
+        tty.warn("You asked for --insecure. Will NOT check SSL certificates.")
+        spack.insecure = True
+
+    # Try to load the particular command asked for and run it
+    command = spack.cmd.get_command(args.command.replace('-', '_'))
+
+    # Allow commands to inject an optional argument and get unknown args
+    # if they want to handle them.
+    info = dict(inspect.getmembers(command))
+    varnames = info['__code__'].co_varnames
+    argcount = info['__code__'].co_argcount
+
+    # Actually execute the command
+    try:
+        if argcount == 3 and varnames[2] == 'unknown_args':
+            return_val = command(parser, args, unknown_args)
+        else:
+            if unknown_args:
+                tty.die('unrecognized arguments: %s' % ' '.join(unknown_args))
+            return_val = command(parser, args)
+    except SpackError as e:
+        e.die()
+    except KeyboardInterrupt:
+        sys.stderr.write('\n')
+        tty.die("Keyboard interrupt.")
+
+    # Allow commands to return values if they want to exit with some other code.
+    if return_val is None:
+        sys.exit(0)
+    elif isinstance(return_val, int):
+        sys.exit(return_val)
+    else:
+        tty.die("Bad return value from command %s: %s"
+                % (args.command, return_val))
+
+
+def main(args):
+    # Just print help and exit if run with no arguments at all
+    if len(args) == 1:
+        parser.print_help()
+        sys.exit(1)
+
+    # actually parse the args.
+    args, unknown = parser.parse_known_args()
+
+    if args.profile:
+        import cProfile
+        cProfile.runctx('_main(args, unknown)', globals(), locals(),
+                        sort='time')
+    elif args.pdb:
+        import pdb
+        pdb.runctx('_main(args, unknown)', globals(), locals())
+    else:
+        _main(args, unknown)
+
+
+if __name__ == '__main__':
+    main(sys.argv)

bin/spack-python

@@ -1,27 +1,27 @@
 #!/bin/sh
 ##############################################################################
-# Copyright (c) 2013, Lawrence Livermore National Security, LLC.
+# Copyright (c) 2013-2016, Lawrence Livermore National Security, LLC.
 # Produced at the Lawrence Livermore National Laboratory.
 #
 # This file is part of Spack.
-# Written by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
+# Created by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
 # LLNL-CODE-647188
 #
-# For details, see https://scalability-llnl.github.io/spack
+# For details, see https://github.com/llnl/spack
 # Please also see the LICENSE file for our notice and the LGPL.
 #
 # This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License (as published by
-# the Free Software Foundation) version 2.1 dated February 1999.
+# it under the terms of the GNU Lesser General Public License (as
+# published by the Free Software Foundation) version 2.1, February 1999.
 #
 # This program is distributed in the hope that it will be useful, but
 # WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
-# conditions of the GNU General Public License for more details.
+# conditions of the GNU Lesser General Public License for more details.
 #
-# You should have received a copy of the GNU Lesser General Public License
-# along with this program; if not, write to the Free Software Foundation,
-# Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 ##############################################################################
 #
 # spack-python

etc/spack/defaults/config.yaml

@@ -0,0 +1,68 @@
+# -------------------------------------------------------------------------
+# This is the default spack configuration file.
+#
+# Settings here are versioned with Spack and are intended to provide
+# sensible defaults out of the box. Spack maintainers should edit this
+# file to keep it current.
+#
+# Users can override these settings by editing the following files.
+#
+# Per-spack-instance settings (overrides defaults):
+#   $SPACK_ROOT/etc/spack/config.yaml
+#
+# Per-user settings (overrides default and site settings):
+#   ~/.spack/config.yaml
+# -------------------------------------------------------------------------
+config:
+  # This is the path to the root of the Spack install tree.
+  # You can use $spack here to refer to the root of the spack instance.
+  install_tree: $spack/opt/spack
+
+
+  # Locations where different types of modules should be installed.
+  module_roots:
+    tcl:    $spack/share/spack/modules
+    lmod:   $spack/share/spack/lmod
+    dotkit: $spack/share/spack/dotkit
+
+
+  # Temporary locations Spack can try to use for builds.
+  #
+  # Spack will use the first one it finds that exists and is writable.
+  # You can use $tempdir to refer to the system default temp directory
+  # (as returned by tempfile.gettempdir()).
+  #
+  # A value of $spack/var/spack/stage indicates that Spack should run
+  # builds directly inside its install directory without staging them in
+  # temporary space.
+  #
+  # The build stage can be purged with `spack purge --stage`.
+  build_stage:
+    - $tempdir
+    - /nfs/tmp2/$user
+    - $spack/var/spack/stage
+
+
+  # Cache directory already downloaded source tarballs and archived
+  # repositories. This can be purged with `spack purge --downloads`.
+  source_cache: $spack/var/spack/cache
+
+
+  # Cache directory for miscellaneous files, like the package index.
+  # This can be purged with `spack purge --misc-cache`
+  misc_cache: ~/.spack/cache
+
+
+  # If this is false, tools like curl that use SSL will not verify
+  # certifiates. (e.g., curl will use use the -k option)
+  verify_ssl: true
+
+
+  # If set to true, Spack will always check checksums after downloading
+  # archives. If false, Spack skips the checksum step.
+  checksum: true
+
+
+  # If set to true, `spack install` and friends will NOT clean
+  # potentially harmful variables from the build environment. Use wisely.
+  dirty: false

etc/spack/defaults/darwin/packages.yaml

@@ -0,0 +1,18 @@
+# -------------------------------------------------------------------------
+# This file controls default concretization preferences for Spack.
+#
+# Settings here are versioned with Spack and are intended to provide
+# sensible defaults out of the box. Spack maintainers should edit this
+# file to keep it current.
+#
+# Users can override these settings by editing the following files.
+#
+# Per-spack-instance settings (overrides defaults):
+#   $SPACK_ROOT/etc/spack/packages.yaml
+#
+# Per-user settings (overrides default and site settings):
+#   ~/.spack/packages.yaml
+# -------------------------------------------------------------------------
+packages:
+  all:
+    compiler: [clang, gcc, intel]

etc/spack/defaults/modules.yaml

@@ -0,0 +1,42 @@
+# -------------------------------------------------------------------------
+# This is the default configuration for Spack's module file generation.
+#
+# Settings here are versioned with Spack and are intended to provide
+# sensible defaults out of the box. Spack maintainers should edit this
+# file to keep it current.
+#
+# Users can override these settings by editing the following files.
+#
+# Per-spack-instance settings (overrides defaults):
+#   $SPACK_ROOT/etc/spack/modules.yaml
+#
+# Per-user settings (overrides default and site settings):
+#   ~/.spack/modules.yaml
+# -------------------------------------------------------------------------
+modules:
+  enable:
+    - tcl
+    - dotkit
+  prefix_inspections:
+    bin:
+      - PATH
+    man:
+      - MANPATH
+    share/man:
+      - MANPATH
+    share/aclocal:
+      - ACLOCAL_PATH
+    lib:
+      - LIBRARY_PATH
+      - LD_LIBRARY_PATH
+    lib64:
+      - LIBRARY_PATH
+      - LD_LIBRARY_PATH
+    include:
+      - CPATH
+    lib/pkgconfig:
+      - PKG_CONFIG_PATH
+    lib64/pkgconfig:
+      - PKG_CONFIG_PATH
+    '':
+      - CMAKE_PREFIX_PATH

etc/spack/defaults/packages.yaml

@@ -0,0 +1,23 @@
+# -------------------------------------------------------------------------
+# This file controls default concretization preferences for Spack.
+#
+# Settings here are versioned with Spack and are intended to provide
+# sensible defaults out of the box. Spack maintainers should edit this
+# file to keep it current.
+#
+# Users can override these settings by editing the following files.
+#
+# Per-spack-instance settings (overrides defaults):
+#   $SPACK_ROOT/etc/spack/packages.yaml
+#
+# Per-user settings (overrides default and site settings):
+#   ~/.spack/packages.yaml
+# -------------------------------------------------------------------------
+packages:
+  all:
+    compiler: [gcc, intel, pgi, clang, xl, nag]
+    providers:
+      mpi: [openmpi, mpich]
+      blas: [openblas]
+      lapack: [openblas]
+      pil: [py-pillow]

etc/spack/defaults/repos.yaml

@@ -0,0 +1,14 @@
+# -------------------------------------------------------------------------
+# This is the default spack repository configuration. It includes the
+# builtin spack package repository.
+#
+# Users can override these settings by editing the following files.
+#
+# Per-spack-instance settings (overrides defaults):
+#   $SPACK_ROOT/etc/spack/repos.yaml
+#
+# Per-user settings (overrides default and site settings):
+#   ~/.spack/repos.yaml
+# -------------------------------------------------------------------------
+repos:
+  - $spack/var/spack/repos/builtin

lib/spack/docs/.gitignore

@@ -1,2 +1,5 @@
+package_list.rst
+command_index.rst
 spack*.rst
+modules.rst
 _build

lib/spack/docs/Makefile

@@ -2,12 +2,13 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+SPHINXOPTS    = -E
+JOBS          ?= $(shell python -c 'import multiprocessing; print multiprocessing.cpu_count()')
+SPHINXBUILD   = sphinx-build -j $(JOBS)
 PAPER         =
 BUILDDIR      = _build
 
-export PYTHONPATH = ../../spack
+export PYTHONPATH := ../../spack:$(PYTHONPATH)
 APIDOC_FILES  = spack*.rst
 
 # Internal variables.
@@ -36,12 +37,25 @@ gh-pages: _build/html
 	touch .nojekyll && \
 	git init && \
 	git add . && \
-	git commit -m "Initial commit" && \
+	git commit -m "Spack Documentation" && \
+	git push -f $$root master:gh-pages && \
+	rm -rf .git
+
+# This version makes gh-pages into a single page that redirects
+# to spack.readthedocs.io
+gh-pages-redirect:
+	root="$$(git rev-parse --show-toplevel)" && \
+	cd _gh_pages_redirect && \
+	rm -rf .git && \
+	git init && \
+	git add . && \
+	git commit -m "Spack Documentation" && \
 	git push -f $$root master:gh-pages && \
 	rm -rf .git
 
 upload:
 	rsync -avz --rsh=ssh --delete _build/html/ cab:/usr/global/web-pages/lc/www/adept/docs/spack
+	git push -f github gh-pages
 
 apidoc:
 	sphinx-apidoc -T -o . $(PYTHONPATH)/spack
@@ -69,9 +83,10 @@ help:
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
+	-rm -f package_list.rst command_index.rst modules.rst
 	-rm -rf $(BUILDDIR)/* $(APIDOC_FILES)
 
-html: apidoc
+html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

lib/spack/docs/_gh_pages_redirect/index.html

@@ -0,0 +1,10 @@
+<html>
+  <head>
+    <meta http-equiv="refresh" content="0; url=http://spack.readthedocs.io/" />
+  </head>
+  <body>
+    <p>
+      This page has moved to <a href="http://spack.readthedocs.io/">http://spack.readthedocs.io/</a>
+    </p>
+  </body>
+</html>

lib/spack/docs/_themes/sphinx_rtd_theme/__init__.py

@@ -5,7 +5,7 @@
 """
 import os
 
-VERSION = (0, 1, 5)
+VERSION = (0, 1, 8)
 
 __version__ = ".".join(str(v) for v in VERSION)
 __version_full__ = __version__

lib/spack/docs/_themes/sphinx_rtd_theme/breadcrumbs.html

@@ -1,15 +1,23 @@
-<ul class="wy-breadcrumbs">
-  <li><a href="{{ pathto(master_doc) }}">Docs</a> &raquo;</li>
-  <li><a href="">{{ title }}</a></li>
-    <li class="wy-breadcrumbs-aside">
-      {% if display_github %}
-        <a href="https://github.com/{{ github_user }}/{{ github_repo }}/blob/{{ github_version }}{{ conf_py_path }}{{ pagename }}.rst" class="icon icon-github"> Edit on GitHub</a>
-      {% elif display_bitbucket %}
-        <a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}.rst'" class="icon icon-bitbucket"> Edit on Bitbucket</a>
-      {% elif show_source and has_source and sourcename %}
-        <a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow"> View page source</a>
-      {% endif %}
-    </li>
-</ul>
-<hr/>
-
+<div role="navigation" aria-label="breadcrumbs navigation">
+  <ul class="wy-breadcrumbs">
+    <li><a href="{{ pathto(master_doc) }}">Docs</a> &raquo;</li>
+      {% for doc in parents %}
+          <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</li>
+      {% endfor %}
+    <li>{{ title }}</li>
+      <li class="wy-breadcrumbs-aside">
+        {% if pagename != "search" %}
+          {% if display_github %}
+            <a href="https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/blob/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ source_suffix }}" class="fa fa-github"> Edit on GitHub</a>
+          {% elif display_bitbucket %}
+            <a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}/src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}{{ source_suffix }}" class="fa fa-bitbucket"> Edit on Bitbucket</a>
+          {% elif show_source and source_url_prefix %}
+            <a href="{{ source_url_prefix }}{{ pagename }}{{ source_suffix }}">View page source</a>
+          {% elif show_source and has_source and sourcename %}
+            <a href="{{ pathto('_sources/' + sourcename, true)|e }}" rel="nofollow"> View page source</a>
+          {% endif %}
+        {% endif %}
+      </li>
+  </ul>
+  <hr/>
+</div>

lib/spack/docs/_themes/sphinx_rtd_theme/footer.html

@@ -1,28 +1,40 @@
 <footer>
   {% if next or prev %}
-    <div class="rst-footer-buttons">
+    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
       {% if next %}
-        <a href="{{ next.link|e }}" class="btn btn-neutral float-right" title="{{ next.title|striptags|e }}"/>Next <span class="icon icon-circle-arrow-right"></span></a>
+        <a href="{{ next.link|e }}" class="btn btn-neutral float-right" title="{{ next.title|striptags|e }}" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
       {% endif %}
       {% if prev %}
-        <a href="{{ prev.link|e }}" class="btn btn-neutral" title="{{ prev.title|striptags|e }}"><span class="icon icon-circle-arrow-left"></span> Previous</a>
+        <a href="{{ prev.link|e }}" class="btn btn-neutral" title="{{ prev.title|striptags|e }}" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
       {% endif %}
     </div>
   {% endif %}
 
   <hr/>
 
-  <p>
-    &copy; Copyright 2013,
-    <a href="https://scalability.llnl.gov/">Lawrence Livermore National Laboratory</a>.
-    <br/>
-    Written by Todd Gamblin, <a href="mailto:tgamblin@llnl.gov">tgamblin@llnl.gov</a>, LLNL-CODE-647188
-    <br/>
+  <div role="contentinfo">
+    <p>
+    {%- if show_copyright %}
+      {%- if hasdoc('copyright') %}
+        {% trans path=pathto('copyright'), copyright=copyright|e %}&copy; <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}
+      {%- else %}
+        {% trans copyright=copyright|e %}&copy; Copyright {{ copyright }}.{% endtrans %}
+      {%- endif %}
+    {%- endif %}
 
-  {%- if last_updated %}
-    {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
+    <br/>
+    Written by Todd Gamblin (<a href="mailto:tgamblin@llnl.gov">tgamblin@llnl.gov</a>) and
+    many contributors. LLNL-CODE-647188.
+
+    {%- if last_updated %}
+      <br/>
+      {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
+    {%- endif %}
+    </p>
+  </div>
+
+  {%- if show_sphinx %}
+  {% trans %}Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>{% endtrans %}.
   {%- endif %}
-  &nbsp;&nbsp;
-  {% trans %}<br/><a href="https://www.github.com/snide/sphinx_rtd_theme">Sphinx theme</a> provided by <a href="http://readthedocs.org">Read the Docs</a>{% endtrans %}
-  </p>
+
 </footer>

lib/spack/docs/_themes/sphinx_rtd_theme/layout.html

@@ -12,6 +12,7 @@
 <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
 <head>
   <meta charset="utf-8">
+  {{ metatags }}
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   {% block htmltitle %}
   <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
@@ -23,40 +24,28 @@
   {% endif %}
 
   {# CSS #}
-  <link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
 
-  {# JS #}
+  {# OPENSEARCH #}
   {% if not embedded %}
-
-    <script type="text/javascript">
-      var DOCUMENTATION_OPTIONS = {
-        URL_ROOT:'{{ url_root }}',
-        VERSION:'{{ release|e }}',
-        COLLAPSE_INDEX:false,
-        FILE_SUFFIX:'{{ '' if no_search_suffix else file_suffix }}',
-        HAS_SOURCE:  {{ has_source|lower }}
-      };
-    </script>
-    {%- for scriptfile in script_files %}
-      <script type="text/javascript" src="{{ pathto(scriptfile, 1) }}"></script>
-    {%- endfor %}
-
     {% if use_opensearch %}
       <link rel="search" type="application/opensearchdescription+xml" title="{% trans docstitle=docstitle|e %}Search within {{ docstitle }}{% endtrans %}" href="{{ pathto('_static/opensearch.xml', 1) }}"/>
     {% endif %}
 
   {% endif %}
 
-  {# RTD hosts these file themselves, so just load on non RTD builds #}
+  {# RTD hosts this file, so just load on non RTD builds #}
   {% if not READTHEDOCS %}
     <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
-    <script type="text/javascript" src="_static/js/theme.js"></script>
   {% endif %}
 
   {% for cssfile in css_files %}
     <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
   {% endfor %}
 
+  {% for cssfile in extra_css_files %}
+    <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
+  {% endfor %}
+
   {%- block linktags %}
     {%- if hasdoc('about') %}
         <link rel="author" title="{{ _('About these documents') }}"
@@ -85,29 +74,47 @@
   {%- endblock %}
   {%- block extrahead %} {% endblock %}
 
-  <script src="//cdnjs.cloudflare.com/ajax/libs/modernizr/2.6.2/modernizr.min.js"></script>
+  {# Keep modernizr in head - http://modernizr.com/docs/#installing #}
+  <script src="_static/js/modernizr.min.js"></script>
 
 </head>
 
-<body class="wy-body-for-nav">
+<body class="wy-body-for-nav" role="document">
 
   <div class="wy-grid-for-nav">
 
     {# SIDE NAV, TOGGLES ON MOBILE #}
     <nav data-toggle="wy-nav-shift" class="wy-nav-side">
       <div class="wy-side-nav-search">
-        <a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }}</a>
+        {% block sidebartitle %}
+
+        {% if logo and theme_logo_only %}
+          <a href="{{ pathto(master_doc) }}">
+        {% else %}
+          <a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }}
+        {% endif %}
+
+        {% if logo %}
+          {# Not strictly valid HTML, but it's the only way to display/scale it properly, without weird scripting or heaps of work #}
+          <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" />
+        {% endif %}
+        </a>
+
         {% include "searchbox.html" %}
+
+        {% endblock %}
       </div>
 
-      <div class="wy-menu wy-menu-vertical" data-spy="affix">
-        {% set toctree = toctree(maxdepth=2, collapse=False, includehidden=True) %}
-        {% if toctree %}
-            {{ toctree }}
-        {% else %}
-            <!-- Local TOC -->
-            <div class="local-toc">{{ toc }}</div>
-        {% endif %}
+      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
+        {% block menu %}
+          {% set toctree = toctree(maxdepth=4, collapse=False, includehidden=True) %}
+          {% if toctree %}
+              {{ toctree }}
+          {% else %}
+              <!-- Local TOC -->
+              <div class="local-toc">{{ toc }}</div>
+          {% endif %}
+        {% endblock %}
       </div>
       &nbsp;
     </nav>
@@ -115,8 +122,8 @@
     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
 
       {# MOBILE NAV, TRIGGLES SIDE NAV ON TOGGLE #}
-      <nav class="wy-nav-top">
-        <i data-toggle="wy-nav-top" class="icon icon-reorder"></i>
+      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
+        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
         <a href="{{ pathto(master_doc) }}">{{ project }}</a>
       </nav>
 
@@ -125,7 +132,9 @@
       <div class="wy-nav-content">
         <div class="rst-content">
           {% include "breadcrumbs.html" %}
-          {% block body %}{% endblock %}
+          <div role="main" class="document">
+            {% block body %}{% endblock %}
+          </div>
           {% include "footer.html" %}
         </div>
       </div>
@@ -134,5 +143,39 @@
 
   </div>
   {% include "versions.html" %}
+
+  {% if not embedded %}
+
+    <script type="text/javascript">
+        var DOCUMENTATION_OPTIONS = {
+            URL_ROOT:'{{ url_root }}',
+            VERSION:'{{ release|e }}',
+            COLLAPSE_INDEX:false,
+            FILE_SUFFIX:'{{ '' if no_search_suffix else file_suffix }}',
+            HAS_SOURCE:  {{ has_source|lower }}
+        };
+    </script>
+    {%- for scriptfile in script_files %}
+      <script type="text/javascript" src="{{ pathto(scriptfile, 1) }}"></script>
+    {%- endfor %}
+
+  {% endif %}
+
+  {# RTD hosts this file, so just load on non RTD builds #}
+  {% if not READTHEDOCS %}
+    <script type="text/javascript" src="{{ pathto('_static/js/theme.js', 1) }}"></script>
+  {% endif %}
+
+  {# STICKY NAVIGATION #}
+  {% if theme_sticky_navigation %}
+  <script type="text/javascript">
+      jQuery(function () {
+          SphinxRtdTheme.StickyNav.enable();
+      });
+  </script>
+  {% endif %}
+
+  {%- block footer %} {% endblock %}
+
 </body>
 </html>

lib/spack/docs/_themes/sphinx_rtd_theme/search.html

@@ -10,7 +10,7 @@
 {%- extends "layout.html" %}
 {% set title = _('Search') %}
 {% set script_files = script_files + ['_static/searchtools.js'] %}
-{% block extrahead %}
+{% block footer %}
   <script type="text/javascript">
     jQuery(function() { Search.loadIndex("{{ pathto('searchindex.js', 1) }}"); });
   </script>

lib/spack/docs/_themes/sphinx_rtd_theme/searchbox.html

@@ -1,5 +1,9 @@
-<form id ="rtd-search-form" class="wy-form" action="{{ pathto('search') }}" method="get">
-  <input type="text" name="q" placeholder="Search docs" />
-  <input type="hidden" name="check_keywords" value="yes" />
-  <input type="hidden" name="area" value="default" />
-</form>
+{%- if builder != 'singlehtml' %}
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="{{ pathto('search') }}" method="get">
+    <input type="text" name="q" placeholder="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+{%- endif %}

lib/spack/docs/_themes/sphinx_rtd_theme/static/css/badge_only.css

@@ -1 +1,2 @@
-.font-smooth,.icon:before{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:before,.clearfix:after{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:fontawesome-webfont;font-weight:normal;font-style:normal;src:url("../font/fontawesome_webfont.eot");src:url("../font/fontawesome_webfont.eot?#iefix") format("embedded-opentype"),url("../font/fontawesome_webfont.woff") format("woff"),url("../font/fontawesome_webfont.ttf") format("truetype"),url("../font/fontawesome_webfont.svg#fontawesome-webfont") format("svg")}.icon:before{display:inline-block;font-family:fontawesome-webfont;font-style:normal;font-weight:normal;line-height:1;text-decoration:inherit}a .icon{display:inline-block;text-decoration:inherit}li .icon{display:inline-block}li .icon-large:before,li .icon-large:before{width:1.875em}ul.icons{list-style-type:none;margin-left:2em;text-indent:-0.8em}ul.icons li .icon{width:0.8em}ul.icons li .icon-large:before,ul.icons li .icon-large:before{vertical-align:baseline}.icon-book:before{content:"\f02d"}.icon-caret-down:before{content:"\f0d7"}.icon-caret-up:before{content:"\f0d8"}.icon-caret-left:before{content:"\f0d9"}.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;border-top:solid 10px #343131;font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60;*zoom:1}.rst-versions .rst-current-version:before,.rst-versions .rst-current-version:after{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-versions .rst-current-version .icon{color:#fcfcfc}.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:gray;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:solid 1px #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px}.rst-versions.rst-badge .icon-book{float:none}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge .rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width: 768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}img{width:100%;height:auto}}
+.fa:before{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:before,.clearfix:after{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-weight:normal;font-style:normal;src:url("../font/fontawesome_webfont.eot");src:url("../font/fontawesome_webfont.eot?#iefix") format("embedded-opentype"),url("../font/fontawesome_webfont.woff") format("woff"),url("../font/fontawesome_webfont.ttf") format("truetype"),url("../font/fontawesome_webfont.svg#FontAwesome") format("svg")}.fa:before{display:inline-block;font-family:FontAwesome;font-style:normal;font-weight:normal;line-height:1;text-decoration:inherit}a .fa{display:inline-block;text-decoration:inherit}li .fa{display:inline-block}li .fa-large:before,li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-0.8em}ul.fas li .fa{width:0.8em}ul.fas li .fa-large:before,ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before{content:""}.icon-book:before{content:""}.fa-caret-down:before{content:""}.icon-caret-down:before{content:""}.fa-caret-up:before{content:""}.icon-caret-up:before{content:""}.fa-caret-left:before{content:""}.icon-caret-left:before{content:""}.fa-caret-right:before{content:""}.icon-caret-right:before{content:""}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;border-top:solid 10px #343131;font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;z-index:400}.rst-versions a{color:#2980B9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27AE60;*zoom:1}.rst-versions .rst-current-version:before,.rst-versions .rst-current-version:after{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book{float:left}.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#E74C3C;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#F1C40F;color:#000}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:gray;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:solid 1px #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px}.rst-versions.rst-badge .icon-book{float:none}.rst-versions.rst-badge .fa-book{float:none}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book{float:left}.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge .rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width: 768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}img{width:100%;height:auto}}
+/*# sourceMappingURL=badge_only.css.map */

lib/spack/docs/_themes/sphinx_rtd_theme/static/css/badge_only.css.map

@@ -0,0 +1,7 @@
+{
+"version": 3,
+"mappings": "CAyDA,SAAY,EACV,qBAAsB,EAAE,UAAW,EAqDrC,QAAS,EARP,IAAK,EAAE,AAAC,EACR,+BAAS,EAEP,MAAO,EAAE,IAAK,EACd,MAAO,EAAE,CAAE,EACb,cAAO,EACL,IAAK,EAAE,GAAI,EC1Gb,SAkBC,EAjBC,UAAW,ECFJ,UAAW,EDGlB,UAAW,EAHqC,KAAM,EAItD,SAAU,EAJsD,KAAM,EAapE,EAAG,EAAE,qCAAwB,EAC7B,EAAG,EAAE,0PAAyE,ECZpF,SAAU,EACR,MAAO,EAAE,WAAY,EACrB,UAAW,EAAE,UAAW,EACxB,SAAU,EAAE,KAAM,EAClB,UAAW,EAAE,KAAM,EACnB,UAAW,EAAE,AAAC,EACd,cAAe,EAAE,MAAO,EAG1B,IAAK,EACH,MAAO,EAAE,WAAY,EACrB,cAAe,EAAE,MAAO,EAIxB,KAAG,EACD,MAAO,EAAE,WAAY,EACvB,sCAAiB,EAGf,IAAK,EAAE,MAAY,EAEvB,KAAM,EACJ,cAAe,EAAE,GAAI,EACrB,UAAW,EAAE,EAAG,EAChB,UAAW,EAAE,KAAM,EAEjB,YAAG,EACD,IAAK,EAAE,IAAI,EACb,oDAAiB,EAGf,aAAc,EAAE,OAAQ,EAG9B,cAAe,EACb,MAAO,EAAE,EAAO,EAElB,gBAAiB,EACf,MAAO,EAAE,EAAO,EAElB,oBAAqB,EACnB,MAAO,EAAE,EAAO,EAElB,sBAAuB,EACrB,MAAO,EAAE,EAAO,EAElB,kBAAmB,EACjB,MAAO,EAAE,EAAO,EAElB,oBAAqB,EACnB,MAAO,EAAE,EAAO,EAElB,oBAAqB,EACnB,MAAO,EAAE,EAAO,EAElB,sBAAuB,EACrB,MAAO,EAAE,EAAO,EAElB,qBAAsB,EACpB,MAAO,EAAE,EAAO,EAElB,uBAAwB,EACtB,MAAO,EAAE,EAAO,ECnElB,YAAa,EACX,OAAQ,EAAE,IAAK,EACf,KAAM,EAAE,AAAC,EACT,GAAI,EAAE,AAAC,EACP,IAAK,EC6E+B,IAAK,ED5EzC,IAAK,ECE+B,MAAyB,EDD7D,SAAU,EAAE,MAAkC,EAC9C,SAAU,EAAE,iBAAiC,EAC7C,UAAW,EEAyB,sDAAM,EFC1C,MAAO,EC+E6B,EAAG,ED9EvC,cAAC,EACC,IAAK,ECqE6B,MAAW,EDpE7C,cAAe,EAAE,GAAI,EACvB,6BAAgB,EACd,MAAO,EAAE,GAAI,EACf,iCAAoB,EAClB,MAAO,EAAE,GAAqB,EAC9B,eAAgB,EAAE,MAAkC,EACpD,MAAO,EAAE,IAAK,EACd,SAAU,EAAE,IAAK,EACjB,QAAS,EAAE,EAAG,EACd,KAAM,EAAE,MAAO,EACf,IAAK,ECiD6B,MAAM,EJgC1C,IAAK,EAAE,AAAC,EACR,iFAAS,EAEP,MAAO,EAAE,IAAK,EACd,MAAO,EAAE,CAAE,EACb,uCAAO,EACL,IAAK,EAAE,GAAI,EGrFX,qCAAG,EACD,IAAK,EClB2B,MAAyB,EDmB3D,0CAAQ,EACN,IAAK,EAAE,GAAI,EACb,4CAAU,EACR,IAAK,EAAE,GAAI,EACb,iDAAiB,EACf,eAAgB,ECQgB,MAAI,EDPpC,IAAK,EC0B2B,GAAM,EDzBxC,wDAAwB,EACtB,eAAgB,ECXgB,MAAO,EDYvC,IAAK,ECzB2B,GAAI,ED0BxC,yCAA8B,EAC5B,MAAO,EAAE,IAAK,EAChB,gCAAmB,EACjB,QAAS,EAAE,EAAG,EACd,MAAO,EAAE,GAAqB,EAC9B,IAAK,ECE6B,GAAwB,EDD1D,MAAO,EAAE,GAAI,EACb,mCAAE,EACA,MAAO,EAAE,IAAK,EACd,KAAM,EAAE,EAAG,EACX,KAAM,EAAE,AAAC,EACT,KAAM,EAAE,KAAM,EACd,MAAO,EAAE,AAAC,EACV,SAAU,EAAE,gBAA6C,EAC3D,mCAAE,EACA,MAAO,EAAE,WAAY,EACrB,KAAM,EAAE,AAAC,EACT,qCAAC,EACC,MAAO,EAAE,WAAY,EACrB,MAAO,EAAE,EAAqB,EAC9B,IAAK,ECjDyB,MAAyB,EDkD7D,sBAAW,EACT,IAAK,EAAE,GAAI,EACX,KAAM,EAAE,GAAI,EACZ,IAAK,EAAE,GAAI,EACX,GAAI,EAAE,GAAI,EACV,KAAM,EAAE,GAAI,EACZ,QAAS,ECkByB,IAAK,EDjBvC,iCAAU,EACR,IAAK,EAAE,GAAI,EACb,+BAAQ,EACN,IAAK,EAAE,GAAI,EACb,oDAA+B,EAC7B,SAAU,EAAE,IAAK,EACjB,6DAAQ,EACN,IAAK,EAAE,GAAI,EACb,+DAAU,EACR,IAAK,EAAE,GAAI,EACf,2CAAoB,EAClB,IAAK,EAAE,GAAI,EACX,KAAM,EAAE,GAAI,EACZ,UAAW,EAAE,GAAI,EACjB,MAAO,EAAE,IAAuB,EAChC,MAAO,EAAE,IAAK,EACd,SAAU,EAAE,KAAM,EGhDpB,mCAAsB,EHmDxB,YAAa,EACX,IAAK,EAAE,EAAG,EACV,MAAO,EAAE,GAAI,EACb,kBAAO,EACL,MAAO,EAAE,IAAK,EAClB,EAAG,EACD,IAAK,EAAE,GAAI,EACX,KAAM,EAAE,GAAI",
+"sources": ["../../../bower_components/wyrm/sass/wyrm_core/_mixin.sass","../../../bower_components/bourbon/dist/css3/_font-face.scss","../../../sass/_theme_badge_fa.sass","../../../sass/_theme_badge.sass","../../../bower_components/wyrm/sass/wyrm_core/_wy_variables.sass","../../../sass/_theme_variables.sass","../../../bower_components/neat/app/assets/stylesheets/grid/_media.scss"],
+"names": [],
+"file": "badge_only.css"
+}

lib/spack/docs/_themes/sphinx_rtd_theme/static/fonts/fontawesome-webfont.svg

@@ -280,8 +280,8 @@
 <glyph unicode="&#xf113;" horiz-adv-x="1664" d="M640 320q0 -40 -12.5 -82t-43 -76t-72.5 -34t-72.5 34t-43 76t-12.5 82t12.5 82t43 76t72.5 34t72.5 -34t43 -76t12.5 -82zM1280 320q0 -40 -12.5 -82t-43 -76t-72.5 -34t-72.5 34t-43 76t-12.5 82t12.5 82t43 76t72.5 34t72.5 -34t43 -76t12.5 -82zM1440 320 q0 120 -69 204t-187 84q-41 0 -195 -21q-71 -11 -157 -11t-157 11q-152 21 -195 21q-118 0 -187 -84t-69 -204q0 -88 32 -153.5t81 -103t122 -60t140 -29.5t149 -7h168q82 0 149 7t140 29.5t122 60t81 103t32 153.5zM1664 496q0 -207 -61 -331q-38 -77 -105.5 -133t-141 -86 t-170 -47.5t-171.5 -22t-167 -4.5q-78 0 -142 3t-147.5 12.5t-152.5 30t-137 51.5t-121 81t-86 115q-62 123 -62 331q0 237 136 396q-27 82 -27 170q0 116 51 218q108 0 190 -39.5t189 -123.5q147 35 309 35q148 0 280 -32q105 82 187 121t189 39q51 -102 51 -218 q0 -87 -27 -168q136 -160 136 -398z" />
 <glyph unicode="&#xf114;" horiz-adv-x="1664" d="M1536 224v704q0 40 -28 68t-68 28h-704q-40 0 -68 28t-28 68v64q0 40 -28 68t-68 28h-320q-40 0 -68 -28t-28 -68v-960q0 -40 28 -68t68 -28h1216q40 0 68 28t28 68zM1664 928v-704q0 -92 -66 -158t-158 -66h-1216q-92 0 -158 66t-66 158v960q0 92 66 158t158 66h320 q92 0 158 -66t66 -158v-32h672q92 0 158 -66t66 -158z" />
 <glyph unicode="&#xf115;" horiz-adv-x="1920" d="M1781 605q0 35 -53 35h-1088q-40 0 -85.5 -21.5t-71.5 -52.5l-294 -363q-18 -24 -18 -40q0 -35 53 -35h1088q40 0 86 22t71 53l294 363q18 22 18 39zM640 768h768v160q0 40 -28 68t-68 28h-576q-40 0 -68 28t-28 68v64q0 40 -28 68t-68 28h-320q-40 0 -68 -28t-28 -68 v-853l256 315q44 53 116 87.5t140 34.5zM1909 605q0 -62 -46 -120l-295 -363q-43 -53 -116 -87.5t-140 -34.5h-1088q-92 0 -158 66t-66 158v960q0 92 66 158t158 66h320q92 0 158 -66t66 -158v-32h544q92 0 158 -66t66 -158v-160h192q54 0 99 -24.5t67 -70.5q15 -32 15 -68z " />
-<glyph unicode="&#xf116;" horiz-adv-x="1152" d="M896 608v-64q0 -14 -9 -23t-23 -9h-224v-224q0 -14 -9 -23t-23 -9h-64q-14 0 -23 9t-9 23v224h-224q-14 0 -23 9t-9 23v64q0 14 9 23t23 9h224v224q0 14 9 23t23 9h64q14 0 23 -9t9 -23v-224h224q14 0 23 -9t9 -23zM1024 224v704q0 40 -28 68t-68 28h-704q-40 0 -68 -28 t-28 -68v-704q0 -40 28 -68t68 -28h704q40 0 68 28t28 68zM1152 928v-704q0 -92 -65.5 -158t-158.5 -66h-704q-93 0 -158.5 66t-65.5 158v704q0 93 65.5 158.5t158.5 65.5h704q93 0 158.5 -65.5t65.5 -158.5z" />
-<glyph unicode="&#xf117;" horiz-adv-x="1152" d="M928 1152q93 0 158.5 -65.5t65.5 -158.5v-704q0 -92 -65.5 -158t-158.5 -66h-704q-93 0 -158.5 66t-65.5 158v704q0 93 65.5 158.5t158.5 65.5h704zM1024 224v704q0 40 -28 68t-68 28h-704q-40 0 -68 -28t-28 -68v-704q0 -40 28 -68t68 -28h704q40 0 68 28t28 68z M864 640q14 0 23 -9t9 -23v-64q0 -14 -9 -23t-23 -9h-576q-14 0 -23 9t-9 23v64q0 14 9 23t23 9h576z" />
+<glyph unicode="&#xf116;" horiz-adv-x="1792" />
+<glyph unicode="&#xf117;" horiz-adv-x="1792" />
 <glyph unicode="&#xf118;" d="M1134 461q-37 -121 -138 -195t-228 -74t-228 74t-138 195q-8 25 4 48.5t38 31.5q25 8 48.5 -4t31.5 -38q25 -80 92.5 -129.5t151.5 -49.5t151.5 49.5t92.5 129.5q8 26 32 38t49 4t37 -31.5t4 -48.5zM640 896q0 -53 -37.5 -90.5t-90.5 -37.5t-90.5 37.5t-37.5 90.5 t37.5 90.5t90.5 37.5t90.5 -37.5t37.5 -90.5zM1152 896q0 -53 -37.5 -90.5t-90.5 -37.5t-90.5 37.5t-37.5 90.5t37.5 90.5t90.5 37.5t90.5 -37.5t37.5 -90.5zM1408 640q0 130 -51 248.5t-136.5 204t-204 136.5t-248.5 51t-248.5 -51t-204 -136.5t-136.5 -204t-51 -248.5 t51 -248.5t136.5 -204t204 -136.5t248.5 -51t248.5 51t204 136.5t136.5 204t51 248.5zM1536 640q0 -209 -103 -385.5t-279.5 -279.5t-385.5 -103t-385.5 103t-279.5 279.5t-103 385.5t103 385.5t279.5 279.5t385.5 103t385.5 -103t279.5 -279.5t103 -385.5z" />
 <glyph unicode="&#xf119;" d="M1134 307q8 -25 -4 -48.5t-37 -31.5t-49 4t-32 38q-25 80 -92.5 129.5t-151.5 49.5t-151.5 -49.5t-92.5 -129.5q-8 -26 -31.5 -38t-48.5 -4q-26 8 -38 31.5t-4 48.5q37 121 138 195t228 74t228 -74t138 -195zM640 896q0 -53 -37.5 -90.5t-90.5 -37.5t-90.5 37.5 t-37.5 90.5t37.5 90.5t90.5 37.5t90.5 -37.5t37.5 -90.5zM1152 896q0 -53 -37.5 -90.5t-90.5 -37.5t-90.5 37.5t-37.5 90.5t37.5 90.5t90.5 37.5t90.5 -37.5t37.5 -90.5zM1408 640q0 130 -51 248.5t-136.5 204t-204 136.5t-248.5 51t-248.5 -51t-204 -136.5t-136.5 -204 t-51 -248.5t51 -248.5t136.5 -204t204 -136.5t248.5 -51t248.5 51t204 136.5t136.5 204t51 248.5zM1536 640q0 -209 -103 -385.5t-279.5 -279.5t-385.5 -103t-385.5 103t-279.5 279.5t-103 385.5t103 385.5t279.5 279.5t385.5 103t385.5 -103t279.5 -279.5t103 -385.5z" />
 <glyph unicode="&#xf11a;" d="M1152 448q0 -26 -19 -45t-45 -19h-640q-26 0 -45 19t-19 45t19 45t45 19h640q26 0 45 -19t19 -45zM640 896q0 -53 -37.5 -90.5t-90.5 -37.5t-90.5 37.5t-37.5 90.5t37.5 90.5t90.5 37.5t90.5 -37.5t37.5 -90.5zM1152 896q0 -53 -37.5 -90.5t-90.5 -37.5t-90.5 37.5 t-37.5 90.5t37.5 90.5t90.5 37.5t90.5 -37.5t37.5 -90.5zM1408 640q0 130 -51 248.5t-136.5 204t-204 136.5t-248.5 51t-248.5 -51t-204 -136.5t-136.5 -204t-51 -248.5t51 -248.5t136.5 -204t204 -136.5t248.5 -51t248.5 51t204 136.5t136.5 204t51 248.5zM1536 640 q0 -209 -103 -385.5t-279.5 -279.5t-385.5 -103t-385.5 103t-279.5 279.5t-103 385.5t103 385.5t279.5 279.5t385.5 103t385.5 -103t279.5 -279.5t103 -385.5z" />
@@ -310,7 +310,7 @@
 <glyph unicode="&#xf133;" horiz-adv-x="1664" d="M128 -128h1408v1024h-1408v-1024zM512 1088v288q0 14 -9 23t-23 9h-64q-14 0 -23 -9t-9 -23v-288q0 -14 9 -23t23 -9h64q14 0 23 9t9 23zM1280 1088v288q0 14 -9 23t-23 9h-64q-14 0 -23 -9t-9 -23v-288q0 -14 9 -23t23 -9h64q14 0 23 9t9 23zM1664 1152v-1280 q0 -52 -38 -90t-90 -38h-1408q-52 0 -90 38t-38 90v1280q0 52 38 90t90 38h128v96q0 66 47 113t113 47h64q66 0 113 -47t47 -113v-96h384v96q0 66 47 113t113 47h64q66 0 113 -47t47 -113v-96h128q52 0 90 -38t38 -90z" />
 <glyph unicode="&#xf134;" horiz-adv-x="1408" d="M512 1344q0 26 -19 45t-45 19t-45 -19t-19 -45t19 -45t45 -19t45 19t19 45zM1408 1376v-320q0 -16 -12 -25q-8 -7 -20 -7q-4 0 -7 1l-448 96q-11 2 -18 11t-7 20h-256v-102q111 -23 183.5 -111t72.5 -203v-800q0 -26 -19 -45t-45 -19h-512q-26 0 -45 19t-19 45v800 q0 106 62.5 190.5t161.5 114.5v111h-32q-59 0 -115 -23.5t-91.5 -53t-66 -66.5t-40.5 -53.5t-14 -24.5q-17 -35 -57 -35q-16 0 -29 7q-23 12 -31.5 37t3.5 49q5 10 14.5 26t37.5 53.5t60.5 70t85 67t108.5 52.5q-25 42 -25 86q0 66 47 113t113 47t113 -47t47 -113 q0 -33 -14 -64h302q0 11 7 20t18 11l448 96q3 1 7 1q12 0 20 -7q12 -9 12 -25z" />
 <glyph unicode="&#xf135;" horiz-adv-x="1664" d="M1440 1088q0 40 -28 68t-68 28t-68 -28t-28 -68t28 -68t68 -28t68 28t28 68zM1664 1376q0 -249 -75.5 -430.5t-253.5 -360.5q-81 -80 -195 -176l-20 -379q-2 -16 -16 -26l-384 -224q-7 -4 -16 -4q-12 0 -23 9l-64 64q-13 14 -8 32l85 276l-281 281l-276 -85q-3 -1 -9 -1 q-14 0 -23 9l-64 64q-17 19 -5 39l224 384q10 14 26 16l379 20q96 114 176 195q188 187 358 258t431 71q14 0 24 -9.5t10 -22.5z" />
-<glyph unicode="&#xf136;" horiz-adv-x="1792" d="M1708 881l-188 -881h-304l181 849q4 21 1 43q-4 20 -16 35q-10 14 -28 24q-18 9 -40 9h-197l-205 -960h-303l204 960h-304l-205 -960h-304l272 1280h1139q157 0 245 -118q86 -116 52 -281z" />
+<glyph unicode="&#xf136;" horiz-adv-x="1792" d="M1745 763l-164 -763h-334l178 832q13 56 -15 88q-27 33 -83 33h-169l-204 -953h-334l204 953h-286l-204 -953h-334l204 953l-153 327h1276q101 0 189.5 -40.5t147.5 -113.5q60 -73 81 -168.5t0 -194.5z" />
 <glyph unicode="&#xf137;" d="M909 141l102 102q19 19 19 45t-19 45l-307 307l307 307q19 19 19 45t-19 45l-102 102q-19 19 -45 19t-45 -19l-454 -454q-19 -19 -19 -45t19 -45l454 -454q19 -19 45 -19t45 19zM1536 640q0 -209 -103 -385.5t-279.5 -279.5t-385.5 -103t-385.5 103t-279.5 279.5 t-103 385.5t103 385.5t279.5 279.5t385.5 103t385.5 -103t279.5 -279.5t103 -385.5z" />
 <glyph unicode="&#xf138;" d="M717 141l454 454q19 19 19 45t-19 45l-454 454q-19 19 -45 19t-45 -19l-102 -102q-19 -19 -19 -45t19 -45l307 -307l-307 -307q-19 -19 -19 -45t19 -45l102 -102q19 -19 45 -19t45 19zM1536 640q0 -209 -103 -385.5t-279.5 -279.5t-385.5 -103t-385.5 103t-279.5 279.5 t-103 385.5t103 385.5t279.5 279.5t385.5 103t385.5 -103t279.5 -279.5t103 -385.5z" />
 <glyph unicode="&#xf139;" d="M1165 397l102 102q19 19 19 45t-19 45l-454 454q-19 19 -45 19t-45 -19l-454 -454q-19 -19 -19 -45t19 -45l102 -102q19 -19 45 -19t45 19l307 307l307 -307q19 -19 45 -19t45 19zM1536 640q0 -209 -103 -385.5t-279.5 -279.5t-385.5 -103t-385.5 103t-279.5 279.5 t-103 385.5t103 385.5t279.5 279.5t385.5 103t385.5 -103t279.5 -279.5t103 -385.5z" />
@@ -342,7 +342,7 @@
 <glyph unicode="&#xf155;" horiz-adv-x="1024" d="M978 351q0 -153 -99.5 -263.5t-258.5 -136.5v-175q0 -14 -9 -23t-23 -9h-135q-13 0 -22.5 9.5t-9.5 22.5v175q-66 9 -127.5 31t-101.5 44.5t-74 48t-46.5 37.5t-17.5 18q-17 21 -2 41l103 135q7 10 23 12q15 2 24 -9l2 -2q113 -99 243 -125q37 -8 74 -8q81 0 142.5 43 t61.5 122q0 28 -15 53t-33.5 42t-58.5 37.5t-66 32t-80 32.5q-39 16 -61.5 25t-61.5 26.5t-62.5 31t-56.5 35.5t-53.5 42.5t-43.5 49t-35.5 58t-21 66.5t-8.5 78q0 138 98 242t255 134v180q0 13 9.5 22.5t22.5 9.5h135q14 0 23 -9t9 -23v-176q57 -6 110.5 -23t87 -33.5 t63.5 -37.5t39 -29t15 -14q17 -18 5 -38l-81 -146q-8 -15 -23 -16q-14 -3 -27 7q-3 3 -14.5 12t-39 26.5t-58.5 32t-74.5 26t-85.5 11.5q-95 0 -155 -43t-60 -111q0 -26 8.5 -48t29.5 -41.5t39.5 -33t56 -31t60.5 -27t70 -27.5q53 -20 81 -31.5t76 -35t75.5 -42.5t62 -50 t53 -63.5t31.5 -76.5t13 -94z" />
 <glyph unicode="&#xf156;" horiz-adv-x="898" d="M898 1066v-102q0 -14 -9 -23t-23 -9h-168q-23 -144 -129 -234t-276 -110q167 -178 459 -536q14 -16 4 -34q-8 -18 -29 -18h-195q-16 0 -25 12q-306 367 -498 571q-9 9 -9 22v127q0 13 9.5 22.5t22.5 9.5h112q132 0 212.5 43t102.5 125h-427q-14 0 -23 9t-9 23v102 q0 14 9 23t23 9h413q-57 113 -268 113h-145q-13 0 -22.5 9.5t-9.5 22.5v133q0 14 9 23t23 9h832q14 0 23 -9t9 -23v-102q0 -14 -9 -23t-23 -9h-233q47 -61 64 -144h171q14 0 23 -9t9 -23z" />
 <glyph unicode="&#xf157;" horiz-adv-x="1027" d="M603 0h-172q-13 0 -22.5 9t-9.5 23v330h-288q-13 0 -22.5 9t-9.5 23v103q0 13 9.5 22.5t22.5 9.5h288v85h-288q-13 0 -22.5 9t-9.5 23v104q0 13 9.5 22.5t22.5 9.5h214l-321 578q-8 16 0 32q10 16 28 16h194q19 0 29 -18l215 -425q19 -38 56 -125q10 24 30.5 68t27.5 61 l191 420q8 19 29 19h191q17 0 27 -16q9 -14 1 -31l-313 -579h215q13 0 22.5 -9.5t9.5 -22.5v-104q0 -14 -9.5 -23t-22.5 -9h-290v-85h290q13 0 22.5 -9.5t9.5 -22.5v-103q0 -14 -9.5 -23t-22.5 -9h-290v-330q0 -13 -9.5 -22.5t-22.5 -9.5z" />
-<glyph unicode="&#xf158;" horiz-adv-x="1664" d="M1664 352v-32q0 -132 -94 -226t-226 -94h-128q-132 0 -226 94t-94 226v480h-224q-2 -102 -14.5 -190.5t-30.5 -156t-48.5 -126.5t-57 -99.5t-67.5 -77.5t-69.5 -58.5t-74 -44t-69 -32t-65.5 -25.5q-4 -2 -32 -13q-8 -2 -12 -2q-22 0 -30 20l-71 178q-5 13 0 25t17 17 q7 3 20 7.5t18 6.5q31 12 46.5 18.5t44.5 20t45.5 26t42 32.5t40.5 42.5t34.5 53.5t30.5 68.5t22.5 83.5t17 103t6.5 123h-256q-14 0 -23 9t-9 23v160q0 14 9 23t23 9h1216q14 0 23 -9t9 -23v-160q0 -14 -9 -23t-23 -9h-224v-512q0 -26 19 -45t45 -19h128q26 0 45 19t19 45 v64q0 14 9 23t23 9h192q14 0 23 -9t9 -23zM1280 1376v-160q0 -14 -9 -23t-23 -9h-960q-14 0 -23 9t-9 23v160q0 14 9 23t23 9h960q14 0 23 -9t9 -23z" />
+<glyph unicode="&#xf158;" horiz-adv-x="1280" d="M1043 971q0 100 -65 162t-171 62h-320v-448h320q106 0 171 62t65 162zM1280 971q0 -193 -126.5 -315t-326.5 -122h-340v-118h505q14 0 23 -9t9 -23v-128q0 -14 -9 -23t-23 -9h-505v-192q0 -14 -9.5 -23t-22.5 -9h-167q-14 0 -23 9t-9 23v192h-224q-14 0 -23 9t-9 23v128 q0 14 9 23t23 9h224v118h-224q-14 0 -23 9t-9 23v149q0 13 9 22.5t23 9.5h224v629q0 14 9 23t23 9h539q200 0 326.5 -122t126.5 -315z" />
 <glyph unicode="&#xf159;" horiz-adv-x="1792" d="M514 341l81 299h-159l75 -300q1 -1 1 -3t1 -3q0 1 0.5 3.5t0.5 3.5zM630 768l35 128h-292l32 -128h225zM822 768h139l-35 128h-70zM1271 340l78 300h-162l81 -299q0 -1 0.5 -3.5t1.5 -3.5q0 1 0.5 3t0.5 3zM1382 768l33 128h-297l34 -128h230zM1792 736v-64q0 -14 -9 -23 t-23 -9h-213l-164 -616q-7 -24 -31 -24h-159q-24 0 -31 24l-166 616h-209l-167 -616q-7 -24 -31 -24h-159q-11 0 -19.5 7t-10.5 17l-160 616h-208q-14 0 -23 9t-9 23v64q0 14 9 23t23 9h175l-33 128h-142q-14 0 -23 9t-9 23v64q0 14 9 23t23 9h109l-89 344q-5 15 5 28 q10 12 26 12h137q26 0 31 -24l90 -360h359l97 360q7 24 31 24h126q24 0 31 -24l98 -360h365l93 360q5 24 31 24h137q16 0 26 -12q10 -13 5 -28l-91 -344h111q14 0 23 -9t9 -23v-64q0 -14 -9 -23t-23 -9h-145l-34 -128h179q14 0 23 -9t9 -23z" />
 <glyph unicode="&#xf15a;" horiz-adv-x="1280" d="M1167 896q18 -182 -131 -258q117 -28 175 -103t45 -214q-7 -71 -32.5 -125t-64.5 -89t-97 -58.5t-121.5 -34.5t-145.5 -15v-255h-154v251q-80 0 -122 1v-252h-154v255q-18 0 -54 0.5t-55 0.5h-200l31 183h111q50 0 58 51v402h16q-6 1 -16 1v287q-13 68 -89 68h-111v164 l212 -1q64 0 97 1v252h154v-247q82 2 122 2v245h154v-252q79 -7 140 -22.5t113 -45t82.5 -78t36.5 -114.5zM952 351q0 36 -15 64t-37 46t-57.5 30.5t-65.5 18.5t-74 9t-69 3t-64.5 -1t-47.5 -1v-338q8 0 37 -0.5t48 -0.5t53 1.5t58.5 4t57 8.5t55.5 14t47.5 21t39.5 30 t24.5 40t9.5 51zM881 827q0 33 -12.5 58.5t-30.5 42t-48 28t-55 16.5t-61.5 8t-58 2.5t-54 -1t-39.5 -0.5v-307q5 0 34.5 -0.5t46.5 0t50 2t55 5.5t51.5 11t48.5 18.5t37 27t27 38.5t9 51z" />
 <glyph unicode="&#xf15b;" horiz-adv-x="1280" d="M1280 768v-800q0 -40 -28 -68t-68 -28h-1088q-40 0 -68 28t-28 68v1344q0 40 28 68t68 28h544v-544q0 -40 28 -68t68 -28h544zM1277 896h-509v509q82 -15 132 -65l312 -312q50 -50 65 -132z" />
@@ -390,10 +390,25 @@
 <glyph unicode="&#xf188;" horiz-adv-x="1664" d="M1632 576q0 -26 -19 -45t-45 -19h-224q0 -171 -67 -290l208 -209q19 -19 19 -45t-19 -45q-18 -19 -45 -19t-45 19l-198 197q-5 -5 -15 -13t-42 -28.5t-65 -36.5t-82 -29t-97 -13v896h-128v-896q-51 0 -101.5 13.5t-87 33t-66 39t-43.5 32.5l-15 14l-183 -207 q-20 -21 -48 -21q-24 0 -43 16q-19 18 -20.5 44.5t15.5 46.5l202 227q-58 114 -58 274h-224q-26 0 -45 19t-19 45t19 45t45 19h224v294l-173 173q-19 19 -19 45t19 45t45 19t45 -19l173 -173h844l173 173q19 19 45 19t45 -19t19 -45t-19 -45l-173 -173v-294h224q26 0 45 -19 t19 -45zM1152 1152h-640q0 133 93.5 226.5t226.5 93.5t226.5 -93.5t93.5 -226.5z" />
 <glyph unicode="&#xf189;" horiz-adv-x="1920" d="M1917 1016q23 -64 -150 -294q-24 -32 -65 -85q-78 -100 -90 -131q-17 -41 14 -81q17 -21 81 -82h1l1 -1l1 -1l2 -2q141 -131 191 -221q3 -5 6.5 -12.5t7 -26.5t-0.5 -34t-25 -27.5t-59 -12.5l-256 -4q-24 -5 -56 5t-52 22l-20 12q-30 21 -70 64t-68.5 77.5t-61 58 t-56.5 15.5q-3 -1 -8 -3.5t-17 -14.5t-21.5 -29.5t-17 -52t-6.5 -77.5q0 -15 -3.5 -27.5t-7.5 -18.5l-4 -5q-18 -19 -53 -22h-115q-71 -4 -146 16.5t-131.5 53t-103 66t-70.5 57.5l-25 24q-10 10 -27.5 30t-71.5 91t-106 151t-122.5 211t-130.5 272q-6 16 -6 27t3 16l4 6 q15 19 57 19l274 2q12 -2 23 -6.5t16 -8.5l5 -3q16 -11 24 -32q20 -50 46 -103.5t41 -81.5l16 -29q29 -60 56 -104t48.5 -68.5t41.5 -38.5t34 -14t27 5q2 1 5 5t12 22t13.5 47t9.5 81t0 125q-2 40 -9 73t-14 46l-6 12q-25 34 -85 43q-13 2 5 24q17 19 38 30q53 26 239 24 q82 -1 135 -13q20 -5 33.5 -13.5t20.5 -24t10.5 -32t3.5 -45.5t-1 -55t-2.5 -70.5t-1.5 -82.5q0 -11 -1 -42t-0.5 -48t3.5 -40.5t11.5 -39t22.5 -24.5q8 -2 17 -4t26 11t38 34.5t52 67t68 107.5q60 104 107 225q4 10 10 17.5t11 10.5l4 3l5 2.5t13 3t20 0.5l288 2 q39 5 64 -2.5t31 -16.5z" />
 <glyph unicode="&#xf18a;" horiz-adv-x="1792" d="M675 252q21 34 11 69t-45 50q-34 14 -73 1t-60 -46q-22 -34 -13 -68.5t43 -50.5t74.5 -2.5t62.5 47.5zM769 373q8 13 3.5 26.5t-17.5 18.5q-14 5 -28.5 -0.5t-21.5 -18.5q-17 -31 13 -45q14 -5 29 0.5t22 18.5zM943 266q-45 -102 -158 -150t-224 -12 q-107 34 -147.5 126.5t6.5 187.5q47 93 151.5 139t210.5 19q111 -29 158.5 -119.5t2.5 -190.5zM1255 426q-9 96 -89 170t-208.5 109t-274.5 21q-223 -23 -369.5 -141.5t-132.5 -264.5q9 -96 89 -170t208.5 -109t274.5 -21q223 23 369.5 141.5t132.5 264.5zM1563 422 q0 -68 -37 -139.5t-109 -137t-168.5 -117.5t-226 -83t-270.5 -31t-275 33.5t-240.5 93t-171.5 151t-65 199.5q0 115 69.5 245t197.5 258q169 169 341.5 236t246.5 -7q65 -64 20 -209q-4 -14 -1 -20t10 -7t14.5 0.5t13.5 3.5l6 2q139 59 246 59t153 -61q45 -63 0 -178 q-2 -13 -4.5 -20t4.5 -12.5t12 -7.5t17 -6q57 -18 103 -47t80 -81.5t34 -116.5zM1489 1046q42 -47 54.5 -108.5t-6.5 -117.5q-8 -23 -29.5 -34t-44.5 -4q-23 8 -34 29.5t-4 44.5q20 63 -24 111t-107 35q-24 -5 -45 8t-25 37q-5 24 8 44.5t37 25.5q60 13 119 -5.5t101 -65.5z M1670 1209q87 -96 112.5 -222.5t-13.5 -241.5q-9 -27 -34 -40t-52 -4t-40 34t-5 52q28 82 10 172t-80 158q-62 69 -148 95.5t-173 8.5q-28 -6 -52 9.5t-30 43.5t9.5 51.5t43.5 29.5q123 26 244 -11.5t208 -134.5z" />
-<glyph unicode="&#xf18b;" horiz-adv-x="1920" d="M805 163q-122 -67 -261 -67q-141 0 -261 67q98 61 167 149t94 191q25 -103 94 -191t167 -149zM453 1176v-344q0 -179 -89.5 -326t-234.5 -217q-129 152 -129 351q0 200 129.5 352t323.5 184zM958 991q-128 -152 -128 -351q0 -201 128 -351q-145 70 -234.5 218t-89.5 328 v341q196 -33 324 -185zM1638 163q-122 -67 -261 -67q-141 0 -261 67q98 61 167 149t94 191q25 -103 94 -191t167 -149zM1286 1176v-344q0 -179 -91 -326t-237 -217v0q133 154 133 351q0 195 -133 351q129 151 328 185zM1920 640q0 -201 -129 -351q-145 70 -234.5 218 t-89.5 328v341q194 -32 323.5 -184t129.5 -352z" />
-<glyph unicode="&#xf18c;" horiz-adv-x="1792" />
-<glyph unicode="&#xf18d;" horiz-adv-x="1792" />
-<glyph unicode="&#xf18e;" horiz-adv-x="1792" />
+<glyph unicode="&#xf18b;" d="M1133 -34q-171 -94 -368 -94q-196 0 -367 94q138 87 235.5 211t131.5 268q35 -144 132.5 -268t235.5 -211zM638 1394v-485q0 -252 -126.5 -459.5t-330.5 -306.5q-181 215 -181 495q0 187 83.5 349.5t229.5 269.5t325 137zM1536 638q0 -280 -181 -495 q-204 99 -330.5 306.5t-126.5 459.5v485q179 -30 325 -137t229.5 -269.5t83.5 -349.5z" />
+<glyph unicode="&#xf18c;" horiz-adv-x="1408" d="M1402 433q-32 -80 -76 -138t-91 -88.5t-99 -46.5t-101.5 -14.5t-96.5 8.5t-86.5 22t-69.5 27.5t-46 22.5l-17 10q-113 -228 -289.5 -359.5t-384.5 -132.5q-19 0 -32 13t-13 32t13 31.5t32 12.5q173 1 322.5 107.5t251.5 294.5q-36 -14 -72 -23t-83 -13t-91 2.5t-93 28.5 t-92 59t-84.5 100t-74.5 146q114 47 214 57t167.5 -7.5t124.5 -56.5t88.5 -77t56.5 -82q53 131 79 291q-7 -1 -18 -2.5t-46.5 -2.5t-69.5 0.5t-81.5 10t-88.5 23t-84 42.5t-75 65t-54.5 94.5t-28.5 127.5q70 28 133.5 36.5t112.5 -1t92 -30t73.5 -50t56 -61t42 -63t27.5 -56 t16 -39.5l4 -16q12 122 12 195q-8 6 -21.5 16t-49 44.5t-63.5 71.5t-54 93t-33 112.5t12 127t70 138.5q73 -25 127.5 -61.5t84.5 -76.5t48 -85t20.5 -89t-0.5 -85.5t-13 -76.5t-19 -62t-17 -42l-7 -15q1 -5 1 -50.5t-1 -71.5q3 7 10 18.5t30.5 43t50.5 58t71 55.5t91.5 44.5 t112 14.5t132.5 -24q-2 -78 -21.5 -141.5t-50 -104.5t-69.5 -71.5t-81.5 -45.5t-84.5 -24t-80 -9.5t-67.5 1t-46.5 4.5l-17 3q-23 -147 -73 -283q6 7 18 18.5t49.5 41t77.5 52.5t99.5 42t117.5 20t129 -23.5t137 -77.5z" />
+<glyph unicode="&#xf18d;" horiz-adv-x="1280" d="M1259 283v-66q0 -85 -57.5 -144.5t-138.5 -59.5h-57l-260 -269v269h-529q-81 0 -138.5 59.5t-57.5 144.5v66h1238zM1259 609v-255h-1238v255h1238zM1259 937v-255h-1238v255h1238zM1259 1077v-67h-1238v67q0 84 57.5 143.5t138.5 59.5h846q81 0 138.5 -59.5t57.5 -143.5z " />
+<glyph unicode="&#xf18e;" d="M1152 640q0 -14 -9 -23l-320 -320q-9 -9 -23 -9q-13 0 -22.5 9.5t-9.5 22.5v192h-352q-13 0 -22.5 9.5t-9.5 22.5v192q0 13 9.5 22.5t22.5 9.5h352v192q0 14 9 23t23 9q12 0 24 -10l319 -319q9 -9 9 -23zM1312 640q0 148 -73 273t-198 198t-273 73t-273 -73t-198 -198 t-73 -273t73 -273t198 -198t273 -73t273 73t198 198t73 273zM1536 640q0 -209 -103 -385.5t-279.5 -279.5t-385.5 -103t-385.5 103t-279.5 279.5t-103 385.5t103 385.5t279.5 279.5t385.5 103t385.5 -103t279.5 -279.5t103 -385.5z" />
+<glyph unicode="&#xf190;" d="M1152 736v-192q0 -13 -9.5 -22.5t-22.5 -9.5h-352v-192q0 -14 -9 -23t-23 -9q-12 0 -24 10l-319 319q-9 9 -9 23t9 23l320 320q9 9 23 9q13 0 22.5 -9.5t9.5 -22.5v-192h352q13 0 22.5 -9.5t9.5 -22.5zM1312 640q0 148 -73 273t-198 198t-273 73t-273 -73t-198 -198 t-73 -273t73 -273t198 -198t273 -73t273 73t198 198t73 273zM1536 640q0 -209 -103 -385.5t-279.5 -279.5t-385.5 -103t-385.5 103t-279.5 279.5t-103 385.5t103 385.5t279.5 279.5t385.5 103t385.5 -103t279.5 -279.5t103 -385.5z" />
+<glyph unicode="&#xf191;" d="M1024 960v-640q0 -26 -19 -45t-45 -19q-20 0 -37 12l-448 320q-27 19 -27 52t27 52l448 320q17 12 37 12q26 0 45 -19t19 -45zM1280 160v960q0 13 -9.5 22.5t-22.5 9.5h-960q-13 0 -22.5 -9.5t-9.5 -22.5v-960q0 -13 9.5 -22.5t22.5 -9.5h960q13 0 22.5 9.5t9.5 22.5z M1536 1120v-960q0 -119 -84.5 -203.5t-203.5 -84.5h-960q-119 0 -203.5 84.5t-84.5 203.5v960q0 119 84.5 203.5t203.5 84.5h960q119 0 203.5 -84.5t84.5 -203.5z" />
+<glyph unicode="&#xf192;" d="M1024 640q0 -106 -75 -181t-181 -75t-181 75t-75 181t75 181t181 75t181 -75t75 -181zM768 1184q-148 0 -273 -73t-198 -198t-73 -273t73 -273t198 -198t273 -73t273 73t198 198t73 273t-73 273t-198 198t-273 73zM1536 640q0 -209 -103 -385.5t-279.5 -279.5 t-385.5 -103t-385.5 103t-279.5 279.5t-103 385.5t103 385.5t279.5 279.5t385.5 103t385.5 -103t279.5 -279.5t103 -385.5z" />
+<glyph unicode="&#xf193;" horiz-adv-x="1664" d="M1023 349l102 -204q-58 -179 -210 -290t-339 -111q-156 0 -288.5 77.5t-210 210t-77.5 288.5q0 181 104.5 330t274.5 211l17 -131q-122 -54 -195 -165.5t-73 -244.5q0 -185 131.5 -316.5t316.5 -131.5q126 0 232.5 65t165 175.5t49.5 236.5zM1571 249l58 -114l-256 -128 q-13 -7 -29 -7q-40 0 -57 35l-239 477h-472q-24 0 -42.5 16.5t-21.5 40.5l-96 779q-2 16 6 42q14 51 57 82.5t97 31.5q66 0 113 -47t47 -113q0 -69 -52 -117.5t-120 -41.5l37 -289h423v-128h-407l16 -128h455q40 0 57 -35l228 -455z" />
+<glyph unicode="&#xf194;" d="M1254 899q16 85 -21 132q-52 65 -187 45q-17 -3 -41 -12.5t-57.5 -30.5t-64.5 -48.5t-59.5 -70t-44.5 -91.5q80 7 113.5 -16t26.5 -99q-5 -52 -52 -143q-43 -78 -71 -99q-44 -32 -87 14q-23 24 -37.5 64.5t-19 73t-10 84t-8.5 71.5q-23 129 -34 164q-12 37 -35.5 69 t-50.5 40q-57 16 -127 -25q-54 -32 -136.5 -106t-122.5 -102v-7q16 -8 25.5 -26t21.5 -20q21 -3 54.5 8.5t58 10.5t41.5 -30q11 -18 18.5 -38.5t15 -48t12.5 -40.5q17 -46 53 -187q36 -146 57 -197q42 -99 103 -125q43 -12 85 -1.5t76 31.5q131 77 250 237 q104 139 172.5 292.5t82.5 226.5zM1536 1120v-960q0 -119 -84.5 -203.5t-203.5 -84.5h-960q-119 0 -203.5 84.5t-84.5 203.5v960q0 119 84.5 203.5t203.5 84.5h960q119 0 203.5 -84.5t84.5 -203.5z" />
+<glyph unicode="&#xf195;" horiz-adv-x="1152" d="M1152 704q0 -191 -94.5 -353t-256.5 -256.5t-353 -94.5h-160q-14 0 -23 9t-9 23v611l-215 -66q-3 -1 -9 -1q-10 0 -19 6q-13 10 -13 26v128q0 23 23 31l233 71v93l-215 -66q-3 -1 -9 -1q-10 0 -19 6q-13 10 -13 26v128q0 23 23 31l233 71v250q0 14 9 23t23 9h160 q14 0 23 -9t9 -23v-181l375 116q15 5 28 -5t13 -26v-128q0 -23 -23 -31l-393 -121v-93l375 116q15 5 28 -5t13 -26v-128q0 -23 -23 -31l-393 -121v-487q188 13 318 151t130 328q0 14 9 23t23 9h160q14 0 23 -9t9 -23z" />
+<glyph unicode="&#xf196;" horiz-adv-x="1408" d="M1152 736v-64q0 -14 -9 -23t-23 -9h-352v-352q0 -14 -9 -23t-23 -9h-64q-14 0 -23 9t-9 23v352h-352q-14 0 -23 9t-9 23v64q0 14 9 23t23 9h352v352q0 14 9 23t23 9h64q14 0 23 -9t9 -23v-352h352q14 0 23 -9t9 -23zM1280 288v832q0 66 -47 113t-113 47h-832 q-66 0 -113 -47t-47 -113v-832q0 -66 47 -113t113 -47h832q66 0 113 47t47 113zM1408 1120v-832q0 -119 -84.5 -203.5t-203.5 -84.5h-832q-119 0 -203.5 84.5t-84.5 203.5v832q0 119 84.5 203.5t203.5 84.5h832q119 0 203.5 -84.5t84.5 -203.5z" />
+<glyph unicode="&#xf197;" horiz-adv-x="1792" />
+<glyph unicode="&#xf198;" horiz-adv-x="1792" />
+<glyph unicode="&#xf199;" horiz-adv-x="1792" />
+<glyph unicode="&#xf19a;" horiz-adv-x="1792" />
+<glyph unicode="&#xf19b;" horiz-adv-x="1792" />
+<glyph unicode="&#xf19c;" horiz-adv-x="1792" />
+<glyph unicode="&#xf19d;" horiz-adv-x="1792" />
+<glyph unicode="&#xf19e;" horiz-adv-x="1792" />
 <glyph unicode="&#xf500;" horiz-adv-x="1792" />
 </font>
 </defs></svg> 

lib/spack/docs/_themes/sphinx_rtd_theme/static/js/theme.js

@@ -1,16 +1,113 @@
-$( document ).ready(function() {
-  // Shift nav in mobile when clicking the menu.
-  $("[data-toggle='wy-nav-top']").click(function() {
-    $("[data-toggle='wy-nav-shift']").toggleClass("shift");
-    $("[data-toggle='rst-versions']").toggleClass("shift");
-  });
-  // Close menu when you click a link.
-  $(".wy-menu-vertical .current ul li a").click(function() {
-    $("[data-toggle='wy-nav-shift']").removeClass("shift");
-    $("[data-toggle='rst-versions']").toggleClass("shift");
-  });
-  $("[data-toggle='rst-current-version']").click(function() {
-    $("[data-toggle='rst-versions']").toggleClass("shift-up");
-  });
-  $("table.docutils:not(.field-list").wrap("<div class='wy-table-responsive'></div>");
+function toggleCurrent (elem) {
+    var parent_li = elem.closest('li');
+    parent_li.siblings('li.current').removeClass('current');
+    parent_li.siblings().find('li.current').removeClass('current');
+    parent_li.find('> ul li.current').removeClass('current');
+    parent_li.toggleClass('current');
+}
+
+$(document).ready(function() {
+    // Shift nav in mobile when clicking the menu.
+    $(document).on('click', "[data-toggle='wy-nav-top']", function() {
+        $("[data-toggle='wy-nav-shift']").toggleClass("shift");
+        $("[data-toggle='rst-versions']").toggleClass("shift");
+    });
+    // Nav menu link click operations
+    $(document).on('click', ".wy-menu-vertical .current ul li a", function() {
+        var target = $(this);
+        // Close menu when you click a link.
+        $("[data-toggle='wy-nav-shift']").removeClass("shift");
+        $("[data-toggle='rst-versions']").toggleClass("shift");
+        // Handle dynamic display of l3 and l4 nav lists
+        toggleCurrent(target);
+        if (typeof(window.SphinxRtdTheme) != 'undefined') {
+            window.SphinxRtdTheme.StickyNav.hashChange();
+        }
+    });
+    $(document).on('click', "[data-toggle='rst-current-version']", function() {
+        $("[data-toggle='rst-versions']").toggleClass("shift-up");
+    });
+    // Make tables responsive
+    $("table.docutils:not(.field-list)").wrap("<div class='wy-table-responsive'></div>");
+
+    // Add expand links to all parents of nested ul
+    $('.wy-menu-vertical ul').siblings('a').each(function () {
+        var link = $(this);
+            expand = $('<span class="toctree-expand"></span>');
+        expand.on('click', function (ev) {
+            toggleCurrent(link);
+            ev.stopPropagation();
+            return false;
+        });
+        link.prepend(expand);
+    });
 });
+
+// Sphinx theme state
+window.SphinxRtdTheme = (function (jquery) {
+    var stickyNav = (function () {
+        var navBar,
+            win,
+            winScroll = false,
+            linkScroll = false,
+            winPosition = 0,
+            enable = function () {
+                init();
+                reset();
+                win.on('hashchange', reset);
+
+                // Set scrolling
+                win.on('scroll', function () {
+                    if (!linkScroll) {
+                        winScroll = true;
+                    }
+                });
+                setInterval(function () {
+                    if (winScroll) {
+                        winScroll = false;
+                        var newWinPosition = win.scrollTop(),
+                            navPosition = navBar.scrollTop(),
+                            newNavPosition = navPosition + (newWinPosition - winPosition);
+                        navBar.scrollTop(newNavPosition);
+                        winPosition = newWinPosition;
+                    }
+                }, 25);
+            },
+            init = function () {
+                navBar = jquery('nav.wy-nav-side:first');
+                win = jquery(window);
+            },
+            reset = function () {
+                // Get anchor from URL and open up nested nav
+                var anchor = encodeURI(window.location.hash);
+                if (anchor) {
+                    try {
+                        var link = $('.wy-menu-vertical')
+                            .find('[href="' + anchor + '"]');
+                        $('.wy-menu-vertical li.toctree-l1 li.current')
+                            .removeClass('current');
+                        link.closest('li.toctree-l2').addClass('current');
+                        link.closest('li.toctree-l3').addClass('current');
+                        link.closest('li.toctree-l4').addClass('current');
+                    }
+                    catch (err) {
+                        console.log("Error expanding nav for anchor", err);
+                    }
+                }
+            },
+            hashChange = function () {
+                linkScroll = true;
+                win.one('hashchange', function () {
+                    linkScroll = false;
+                });
+            };
+        jquery(init);
+        return {
+            enable: enable,
+            hashChange: hashChange
+        };
+    }());
+    return {
+        StickyNav: stickyNav
+    };
+}($));

lib/spack/docs/_themes/sphinx_rtd_theme/theme.conf

@@ -5,3 +5,5 @@ stylesheet = css/theme.css
 [options]
 typekit_id = hiw1hhg
 analytics_id = 
+sticky_navigation = False
+logo_only =

lib/spack/docs/_themes/sphinx_rtd_theme/versions.html

@@ -1,10 +1,10 @@
 {% if READTHEDOCS %}
 {# Add rst-badge after rst-versions for small badge style. #}
-  <div class="rst-versions" data-toggle="rst-versions">
+  <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
     <span class="rst-current-version" data-toggle="rst-current-version">
-      <span class="icon icon-book"> Read the Docs</span>
-      v: {{ current_version }} 
-      <span class="icon icon-caret-down"></span>
+      <span class="fa fa-book"> Read the Docs</span>
+      v: {{ current_version }}
+      <span class="fa fa-caret-down"></span>
     </span>
     <div class="rst-other-versions">
       <dl>

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.

lib/spack/docs/command_index.in

@@ -0,0 +1,9 @@
+=============
+Command Index
+=============
+
+This is an alphabetical list of commands with links to the places they
+appear in the documentation.
+
+.. hlist::
+   :columns: 3

lib/spack/docs/conf.py

@@ -1,26 +1,27 @@
+# flake8: noqa
 ##############################################################################
-# Copyright (c) 2013, Lawrence Livermore National Security, LLC.
+# Copyright (c) 2013-2016, Lawrence Livermore National Security, LLC.
 # Produced at the Lawrence Livermore National Laboratory.
 #
 # This file is part of Spack.
-# Written by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
+# Created by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
 # LLNL-CODE-647188
 #
-# For details, see https://scalability-llnl.github.io/spack
+# For details, see https://github.com/llnl/spack
 # Please also see the LICENSE file for our notice and the LGPL.
 #
 # This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License (as published by
-# the Free Software Foundation) version 2.1 dated February 1999.
+# it under the terms of the GNU Lesser General Public License (as
+# published by the Free Software Foundation) version 2.1, February 1999.
 #
 # This program is distributed in the hope that it will be useful, but
 # WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
-# conditions of the GNU General Public License for more details.
+# conditions of the GNU Lesser General Public License for more details.
 #
-# You should have received a copy of the GNU Lesser General Public License
-# along with this program; if not, write to the Free Software Foundation,
-# Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 ##############################################################################
 # -*- coding: utf-8 -*-
 #
@@ -35,22 +36,87 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys
+import os
+import re
+import shutil
+import subprocess
+from glob import glob
+from sphinx.apidoc import main as sphinx_apidoc
+
+# -- Spack customizations -----------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('exts'))
+sys.path.insert(0, os.path.abspath('../external'))
+sys.path.append(os.path.abspath('..'))
 
 # Add the Spack bin directory to the path so that we can use its output in docs.
-os.environ['SPACK_ROOT'] = '../../..'
-os.environ['PATH'] += os.pathsep + '$SPACK_ROOT/bin'
+spack_root = '../../..'
+os.environ['SPACK_ROOT'] = spack_root
+os.environ['PATH'] += '%s%s/bin' % (os.pathsep, spack_root)
+
+# Get the spack version for use in the docs
+spack_version =  subprocess.Popen(
+    [spack_root + '/bin/spack', '-V'],
+    stderr=subprocess.PIPE).communicate()[1].strip().split('.')
 
 # Set an environment variable so that colify will print output like it would to
 # a terminal.
-os.environ['COLIFY_TTY'] = 'true'
-os.environ['COLUMNS']    = '80'
-os.environ['LINES']      = '25'
+os.environ['COLIFY_SIZE'] = '25x120'
+
+#
+# Generate package list using spack command
+#
+with open('package_list.rst', 'w') as plist_file:
+    subprocess.Popen(
+        [spack_root + '/bin/spack', 'list', '--format=rst'], stdout=plist_file)
+
+#
+# Find all the `cmd-spack-*` references and add them to a command index
+#
+command_names = []
+for filename in glob('*rst'):
+    with open(filename) as f:
+        for line in f:
+            match = re.match('.. _(cmd-spack-.*):', line)
+            if match:
+                command_names.append(match.group(1).strip())
+
+shutil.copy('command_index.in', 'command_index.rst')
+with open('command_index.rst', 'a') as index:
+    index.write('\n')
+    for cmd in sorted(command_names):
+        index.write('   * :ref:`%s`\n' % cmd)
+
+
+# Run sphinx-apidoc
+sphinx_apidoc(['-T', '-o', '.', '../spack'])
+os.remove('modules.rst')
+
+#
+# Exclude everything in spack.__all__ from indexing.  All of these
+# symbols are imported from elsewhere in spack; their inclusion in
+# __all__ simply allows package authors to use `from spack import *`.
+# Excluding them ensures they're only documented in their "real" module.
+#
+# This also avoids issues where some of these symbols shadow core spack
+# modules.  Sphinx will complain about duplicate docs when this happens.
+#
+import fileinput, spack
+handling_spack = False
+for line in fileinput.input('spack.rst', inplace=1):
+    if handling_spack:
+        if not line.startswith('    :noindex:'):
+            print '    :noindex: %s' % ' '.join(spack.__all__)
+        handling_spack = False
+
+    if line.startswith('.. automodule::'):
+        handling_spack = (line == '.. automodule:: spack\n')
+
+    print line,
 
 # Enable todo items
 todo_include_todos = True
@@ -83,23 +149,23 @@
 source_suffix = '.rst'
 
 # The encoding of source files.
-#source_encoding = 'utf-8-sig'
+source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
 project = u'Spack'
-copyright = u'2013, Lawrence Livermore National Laboratory'
+copyright = u'2013-2015, Lawrence Livermore National Laboratory.'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '1.0'
+version = '.'.join(spack_version[:2])
 # The full version, including alpha/beta/rc tags.
-release = '1.0'
+release = '.'.join(spack_version[:2])
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -145,7 +211,7 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = []
+html_theme_options = { 'logo_only' : True }
 
 # Add any paths that contain custom themes here, relative to this directory.
 html_theme_path = ["_themes"]
@@ -159,12 +225,12 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = '../../../share/spack/logo/spack-logo-white-text-48.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-#html_favicon = None
+html_favicon = '../../../share/spack/logo/favicon.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -199,7 +265,7 @@
 #html_show_sourcelink = True
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
+#html_show_sphinx = False
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
 #html_show_copyright = True

lib/spack/docs/config_yaml.rst

@@ -0,0 +1,149 @@
+.. _config-yaml:
+
+====================================
+Basic settings in ``config.yaml``
+====================================
+
+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.

lib/spack/docs/configuration.rst

@@ -0,0 +1,253 @@
+.. _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>`
+* :ref:`repos.yaml <repositories>`
+
+-------------------------
+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
+
+   config:
+     install_tree: $spack/opt/spack
+     module_roots:
+       lmod:   $spack/share/spack/lmod
+     build_stage:
+       - $tempdir
+       - /nfs/tmp2/$user
+
+**site** scope:
+
+.. code-block:: yaml
+
+   config:
+     install_tree: /some/other/directory
+
+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:
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+Overriding entire sections
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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
+
+Spack will ignore all lower-precedence configuration under the
+``config::`` section:
+
+.. code-block:: console
+
+   $ spack config get config
+   config:
+     install_tree: /some/other/directory
+
+^^^^^^^^^^^^^^^^^^^^^^
+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:
+
+**defaults**
+
+.. code-block:: yaml
+
+   build_stage:
+     - $tempdir
+     - /nfs/tmp2/$user
+
+Suppose the user configuration adds its *own* list of ``build_stage``
+paths:
+
+**user**
+
+.. code-block:: yaml
+
+   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
+   $ _

lib/spack/docs/contribution_guide.rst

@@ -0,0 +1,522 @@
+.. _contribution-guide:
+
+==================
+Contribution Guide
+==================
+
+This guide is intended for developers or administrators who want to
+contribute a new package, feature, or bugfix to Spack.
+It assumes that you have at least some familiarity with Git VCS and Github.
+The guide will show a few examples of contributing workflows and discuss
+the granularity of pull-requests (PRs). It will also discuss the tests your
+PR must pass in order to be accepted into Spack.
+
+First, what is a PR? Quoting `Bitbucket's tutorials <https://www.atlassian.com/git/tutorials/making-a-pull-request/>`_:
+
+  Pull requests are a mechanism for a developer to notify team members that
+  they have **completed a feature**. The pull request is more than just a
+  notification—it’s a dedicated forum for discussing the proposed feature.
+
+Important is **completed feature**. The changes one proposes in a PR should
+correspond to one feature/bugfix/extension/etc. One can create PRs with
+changes relevant to different ideas, however reviewing such PRs becomes tedious
+and error prone. If possible, try to follow the **one-PR-one-package/feature** rule.
+
+Spack uses a rough approximation of the `Git Flow <http://nvie.com/posts/a-successful-git-branching-model/>`_
+branching model. The develop branch contains the latest contributions, and
+master is always tagged and points to the latest stable release. Therefore, when
+you send your request, make ``develop`` the destination branch on the
+`Spack repository <https://github.com/LLNL/spack>`_.
+
+----------------------
+Continuous Integration
+----------------------
+
+Spack uses `Travis CI <https://travis-ci.org/LLNL/spack>`_ for Continuous Integration
+testing. This means that every time you submit a pull request, a series of tests will
+be run to make sure you didn't accidentally introduce any bugs into Spack. Your PR
+will not be accepted until it passes all of these tests. While you can certainly wait
+for the results of these tests after submitting a PR, we recommend that you run them
+locally to speed up the review process.
+
+If you take a look in ``$SPACK_ROOT/.travis.yml``, you'll notice that we test
+against Python 2.6 and 2.7. We currently perform 3 types of tests:
+
+^^^^^^^^^^
+Unit Tests
+^^^^^^^^^^
+
+Unit tests ensure that core Spack features like fetching or spec resolution are
+working as expected. If your PR only adds new packages or modifies existing ones,
+there's very little chance that your changes could cause the unit tests to fail.
+However, if you make changes to Spack's core libraries, you should run the unit
+tests to make sure you didn't break anything.
+
+Since they test things like fetching from VCS repos, the unit tests require
+`git <https://git-scm.com/>`_, `mercurial <https://www.mercurial-scm.org/>`_,
+and `subversion <https://subversion.apache.org/>`_ to run. Make sure these are
+installed on your system and can be found in your ``PATH``. All of these can be
+installed with Spack or with your system package manager.
+
+To run *all* of the unit tests, use:
+
+.. code-block:: console
+
+   $ spack test
+
+These tests may take several minutes to complete. If you know you are only
+modifying a single Spack feature, you can run a single unit test at a time:
+
+.. code-block:: console
+
+   $ spack test architecture
+
+This allows you to develop iteratively: make a change, test that change, make
+another change, test that change, etc. To get a list of all available unit
+tests, run:
+
+.. command-output:: spack test --collect-only
+
+Unit tests are crucial to making sure bugs aren't introduced into Spack. If you
+are modifying core Spack libraries or adding new functionality, please consider
+adding new unit tests or strengthening existing tests.
+
+.. note::
+
+   There is also a ``run-unit-tests`` script in ``share/spack/qa`` that
+   runs the unit tests. Afterwards, it reports back to Coverage with the
+   percentage of Spack that is covered by unit tests. This script is
+   designed for Travis CI. If you want to run the unit tests yourself, we
+   suggest you use ``spack test``.
+
+^^^^^^^^^^^^
+Flake8 Tests
+^^^^^^^^^^^^
+
+Spack uses `Flake8 <http://flake8.pycqa.org/en/latest/>`_ to test for
+`PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_ conformance. PEP 8 is
+a series of style guides for Python that provide suggestions for everything
+from variable naming to indentation. In order to limit the number of PRs that
+were mostly style changes, we decided to enforce PEP 8 conformance. Your PR
+needs to comply with PEP 8 in order to be accepted.
+
+Testing for PEP 8 compliance is easy. Simply run the ``spack flake8``
+command:
+
+.. code-block:: console
+
+   $ spack flake8
+
+``spack flake8`` has a couple advantages over running ``flake8`` by hand:
+
+#. It only tests files that you have modified since branching off of
+   ``develop``.
+
+#. It works regardless of what directory you are in.
+
+#. It automatically adds approved exemptions from the ``flake8``
+   checks. For example, URLs are often longer than 80 characters, so we
+   exempt them from line length checks. We also exempt lines that start
+   with "homepage", "url", "version", "variant", "depends_on", and
+   "extends" in ``package.py`` files.
+
+More approved flake8 exemptions can be found
+`here <https://github.com/LLNL/spack/blob/develop/.flake8>`_.
+
+If all is well, you'll see something like this:
+
+.. code-block:: console
+
+   $ run-flake8-tests
+   Dependencies found.
+   =======================================================
+   flake8: running flake8 code checks on spack.
+
+   Modified files:
+
+     var/spack/repos/builtin/packages/hdf5/package.py
+     var/spack/repos/builtin/packages/hdf/package.py
+     var/spack/repos/builtin/packages/netcdf/package.py
+   =======================================================
+   Flake8 checks were clean.
+
+However, if you aren't compliant with PEP 8, flake8 will complain:
+
+.. code-block:: console
+
+   var/spack/repos/builtin/packages/netcdf/package.py:26: [F401] 'os' imported but unused
+   var/spack/repos/builtin/packages/netcdf/package.py:61: [E303] too many blank lines (2)
+   var/spack/repos/builtin/packages/netcdf/package.py:106: [E501] line too long (92 > 79 characters)
+   Flake8 found errors.
+
+Most of the error messages are straightforward, but if you don't understand what
+they mean, just ask questions about them when you submit your PR. The line numbers
+will change if you add or delete lines, so simply run ``run-flake8-tests`` again
+to update them.
+
+.. tip::
+
+   Try fixing flake8 errors in reverse order. This eliminates the need for
+   multiple runs of ``flake8`` just to re-compute line numbers and makes it
+   much easier to fix errors directly off of the Travis output.
+
+.. warning::
+
+   Flake8 requires setuptools in order to run. If you installed ``py-flake8``
+   with Spack, make sure to add ``py-setuptools`` to your ``PYTHONPATH``.
+   Otherwise, you will get an error message like:
+
+   .. code-block:: console
+
+      Traceback (most recent call last):
+        File: "/usr/bin/flake8", line 5, in <module>
+          from pkg_resources import load_entry_point
+      ImportError: No module named pkg_resources
+
+^^^^^^^^^^^^^^^^^^^
+Documentation Tests
+^^^^^^^^^^^^^^^^^^^
+
+Spack uses `Sphinx <http://www.sphinx-doc.org/en/stable/>`_ to build its
+documentation. In order to prevent things like broken links and missing imports,
+we added documentation tests that build the documentation and fail if there
+are any warning or error messages.
+
+Building the documentation requires several dependencies, all of which can be
+installed with Spack:
+
+* sphinx
+* graphviz
+* git
+* mercurial
+* subversion
+
+.. warning::
+
+   Sphinx has `several required dependencies <https://github.com/LLNL/spack/blob/develop/var/spack/repos/builtin/packages/py-sphinx/package.py>`_.
+   If you installed ``py-sphinx`` with Spack, make sure to add all of these
+   dependencies to your ``PYTHONPATH``. The easiest way to do this is to run
+   ``spack activate py-sphinx`` so that all of the dependencies are symlinked
+   to a central location. If you see an error message like:
+
+   .. code-block:: console
+
+      Traceback (most recent call last):
+        File: "/usr/bin/flake8", line 5, in <module>
+          from pkg_resources import load_entry_point
+      ImportError: No module named pkg_resources
+
+   that means Sphinx couldn't find setuptools in your ``PYTHONPATH``.
+
+Once all of the dependencies are installed, you can try building the documentation:
+
+.. code-block:: console
+
+   $ cd "$SPACK_ROOT/lib/spack/docs"
+   $ make clean
+   $ make
+
+If you see any warning or error messages, you will have to correct those before
+your PR is accepted.
+
+.. note::
+
+   There is also a ``run-doc-tests`` script in the Quality Assurance directory.
+   The only difference between running this script and running ``make`` by hand
+   is that the script will exit immediately if it encounters an error or warning.
+   This is necessary for Travis CI. If you made a lot of documentation tests, it
+   is much quicker to run ``make`` by hand so that you can see all of the warnings
+   at once.
+
+If you are editing the documentation, you should obviously be running the
+documentation tests. But even if you are simply adding a new package, your
+changes could cause the documentation tests to fail:
+
+.. code-block:: console
+
+   package_list.rst:8745: WARNING: Block quote ends without a blank line; unexpected unindent.
+
+At first, this error message will mean nothing to you, since you didn't edit
+that file. Until you look at line 8745 of the file in question:
+
+.. code-block:: rst
+
+   Description:
+      NetCDF is a set of software libraries and self-describing, machine-
+     independent data formats that support the creation, access, and sharing
+     of array-oriented scientific data.
+
+Our documentation includes :ref:`a list of all Spack packages <package-list>`.
+If you add a new package, its docstring is added to this page. The problem in
+this case was that the docstring looked like:
+
+.. code-block:: python
+
+   class Netcdf(Package):
+       """
+       NetCDF is a set of software libraries and self-describing,
+       machine-independent data formats that support the creation,
+       access, and sharing of array-oriented scientific data.
+       """
+
+Docstrings cannot start with a newline character, or else Sphinx will complain.
+Instead, they should look like:
+
+.. code-block:: python
+
+   class Netcdf(Package):
+       """NetCDF is a set of software libraries and self-describing,
+       machine-independent data formats that support the creation,
+       access, and sharing of array-oriented scientific data."""
+
+Documentation changes can result in much more obfuscated warning messages.
+If you don't understand what they mean, feel free to ask when you submit
+your PR.
+
+-------------
+Git Workflows
+-------------
+
+Spack is still in the beta stages of development. Most of our users run off of
+the develop branch, and fixes and new features are constantly being merged. So
+how do you keep up-to-date with upstream while maintaining your own local
+differences and contributing PRs to Spack?
+
+^^^^^^^^^
+Branching
+^^^^^^^^^
+
+The easiest way to contribute a pull request is to make all of your changes on
+new branches. Make sure your ``develop`` is up-to-date and create a new branch
+off of it:
+
+.. code-block:: console
+
+   $ git checkout develop
+   $ git pull upstream develop
+   $ git branch <descriptive_branch_name>
+   $ git checkout <descriptive_branch_name>
+
+Here we assume that the local ``develop`` branch tracks the upstream develop
+branch of Spack. This is not a requirement and you could also do the same with
+remote branches. But for some it is more convenient to have a local branch that
+tracks upstream.
+
+Normally we prefer that commits pertaining to a package ``<package-name>`` have
+a message ``<package-name>: descriptive message``. It is important to add
+descriptive message so that others, who might be looking at your changes later
+(in a year or maybe two), would understand the rationale behind them.
+
+Now, you can make your changes while keeping the ``develop`` branch pure.
+Edit a few files and commit them by running:
+
+.. code-block:: console
+
+   $ git add <files_to_be_part_of_the_commit>
+   $ git commit --message <descriptive_message_of_this_particular_commit>
+
+Next, push it to your remote fork and create a PR:
+
+.. code-block:: console
+
+   $ git push origin <descriptive_branch_name> --set-upstream
+
+GitHub provides a `tutorial <https://help.github.com/articles/about-pull-requests/>`_
+on how to file a pull request. When you send the request, make ``develop`` the
+destination branch.
+
+If you need this change immediately and don't have time to wait for your PR to
+be merged, you can always work on this branch. But if you have multiple PRs,
+another option is to maintain a Frankenstein branch that combines all of your
+other branches:
+
+.. code-block:: console
+
+   $ git co develop
+   $ git branch <your_modified_develop_branch>
+   $ git checkout <your_modified_develop_branch>
+   $ git merge <descriptive_branch_name>
+
+This can be done with each new PR you submit. Just make sure to keep this local
+branch up-to-date with upstream ``develop`` too.
+
+^^^^^^^^^^^^^^
+Cherry-Picking
+^^^^^^^^^^^^^^
+
+What if you made some changes to your local modified develop branch and already
+committed them, but later decided to contribute them to Spack? You can use
+cherry-picking to create a new branch with only these commits.
+
+First, check out your local modified develop branch:
+
+.. code-block:: console
+
+   $ git checkout <your_modified_develop_branch>
+
+Now, get the hashes of the commits you want from the output of:
+
+.. code-block:: console
+
+   $ git log
+
+Next, create a new branch off of upstream ``develop`` and copy the commits
+that you want in your PR:
+
+.. code-block:: console
+
+   $ git checkout develop
+   $ git pull upstream develop
+   $ git branch <descriptive_branch_name>
+   $ git checkout <descriptive_branch_name>
+   $ git cherry-pick <hash>
+   $ git push origin <descriptive_branch_name> --set-upstream
+
+Now you can create a PR from the web-interface of GitHub. The net result is as
+follows:
+
+#. You patched your local version of Spack and can use it further.
+#. You "cherry-picked" these changes in a stand-alone branch and submitted it
+   as a PR upstream.
+
+Should you have several commits to contribute, you could follow the same
+procedure by getting hashes of all of them and cherry-picking to the PR branch.
+
+.. note::
+
+   It is important that whenever you change something that might be of
+   importance upstream, create a pull request as soon as possible. Do not wait
+   for weeks/months to do this, because:
+
+   #. you might forget why you modified certain files
+   #. it could get difficult to isolate this change into a stand-alone clean PR.
+
+^^^^^^^^
+Rebasing
+^^^^^^^^
+
+Other developers are constantly making contributions to Spack, possibly on the
+same files that your PR changed. If their PR is merged before yours, it can
+create a merge conflict. This means that your PR can no longer be automatically
+merged without a chance of breaking your changes. In this case, you will be
+asked to rebase on top of the latest upstream ``develop``.
+
+First, make sure your develop branch is up-to-date:
+
+.. code-block:: console
+
+   $ git checkout develop
+   $ git pull upstream develop
+
+Now, we need to switch to the branch you submitted for your PR and rebase it
+on top of develop:
+
+.. code-block:: console
+
+   $ git checkout <descriptive_branch_name>
+   $ git rebase develop
+
+Git will likely ask you to resolve conflicts. Edit the file that it says can't
+be merged automatically and resolve the conflict. Then, run:
+
+.. code-block:: console
+
+   $ git add <file_that_could_not_be_merged>
+   $ git rebase --continue
+
+You may have to repeat this process multiple times until all conflicts are resolved.
+Once this is done, simply force push your rebased branch to your remote fork:
+
+.. code-block:: console
+
+   $ git push --force origin <descriptive_branch_name>
+
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Rebasing with cherry-pick
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can also perform a rebase using ``cherry-pick``. First, create a temporary
+backup branch:
+
+.. code-block:: console
+
+   $ git checkout <descriptive_branch_name>
+   $ git branch tmp
+
+If anything goes wrong, you can always go back to your ``tmp`` branch.
+Now, look at the logs and save the hashes of any commits you would like to keep:
+
+.. code-block:: console
+
+   $ git log
+
+Next, go back to the original branch and reset it to ``develop``.
+Before doing so, make sure that you local ``develop`` branch is up-to-date
+with upstream:
+
+.. code-block:: console
+
+   $ git checkout develop
+   $ git pull upstream develop
+   $ git checkout <descriptive_branch_name>
+   $ git reset --hard develop
+
+Now you can cherry-pick relevant commits:
+
+.. code-block:: console
+
+   $ git cherry-pick <hash1>
+   $ git cherry-pick <hash2>
+
+Push the modified branch to your fork:
+
+.. code-block:: console
+
+   $ git push --force origin <descriptive_branch_name>
+
+If everything looks good, delete the backup branch:
+
+.. code-block:: console
+
+   $ git branch --delete --force tmp
+
+^^^^^^^^^^^^^^^^^^
+Re-writing History
+^^^^^^^^^^^^^^^^^^
+
+Sometimes you may end up on a branch that has diverged so much from develop
+that it cannot easily be rebased. If the current commits history is more of
+an experimental nature and only the net result is important, you may rewrite
+the history.
+
+First, merge upstream ``develop`` and reset you branch to it. On the branch
+in question, run:
+
+.. code-block:: console
+
+   $ git merge develop
+   $ git reset develop
+
+At this point your branch will point to the same commit as develop and
+thereby the two are indistinguishable. However, all the files that were
+previously modified will stay as such. In other words, you do not lose the
+changes you made. Changes can be reviewed by looking at diffs:
+
+.. code-block:: console
+
+   $ git status
+   $ git diff
+
+The next step is to rewrite the history by adding files and creating commits:
+
+.. code-block:: console
+
+   $ git add <files_to_be_part_of_commit>
+   $ git commit --message <descriptive_message>
+
+After all changed files are committed, you can push the branch to your fork
+and create a PR:
+
+.. code-block:: console
+
+   $ git push origin --set-upstream

lib/spack/docs/developer_guide.rst

@@ -1,27 +1,29 @@
 .. _developer_guide:
 
+===============
 Developer Guide
-=====================
+===============
 
 This guide is intended for people who want to work on Spack itself.
-If you just want to develop pacakges, see the :ref:`packaging-guide`.
+If you just want to develop packages, see the :ref:`packaging-guide`.
 
 It is assumed that you've read the :ref:`basic-usage` and
 :ref:`packaging-guide` sections, and that you're familiar with the
 concepts discussed there.  If you're not, we recommend reading those
 first.
 
+--------
 Overview
------------------------
+--------
 
 Spack is designed with three separate roles in mind:
 
-   #. **Users**, who need to install software *without* knowing all the
-      details about how it is built.
-   #. **Packagers** who know how a particular software package is
-      built and encode this information in package files.
-   #. **Developers** who work on Spack, add new features, and try to
-      make the jobs of packagers and users easier.
+#. **Users**, who need to install software *without* knowing all the
+   details about how it is built.
+#. **Packagers** who know how a particular software package is
+   built and encode this information in package files.
+#. **Developers** who work on Spack, add new features, and try to
+   make the jobs of packagers and users easier.
 
 Users could be end users installing software in their home directory,
 or administrators installing software to a shared directory on a
@@ -41,20 +43,20 @@ specification.
 
 This gets us to the two key concepts in Spack's software design:
 
-   #. **Specs**: expressions for describing builds of software, and
-   #. **Packages**: Python modules that build software according to a
-      spec.
+#. **Specs**: expressions for describing builds of software, and
+#. **Packages**: Python modules that build software according to a
+   spec.
 
 A package is a template for building particular software, and a spec
 as a descriptor for one or more instances of that template.  Users
 express the configuration they want using a spec, and a package turns
 the spec into a complete build.
 
-The obvious difficulty with this design is that users underspecify
+The obvious difficulty with this design is that users under-specify
 what they want.  To build a software package, the package object needs
 a *complete* specification.  In Spack, if a spec describes only one
 instance of a package, then we say it is **concrete**.  If a spec
-could describes many instances, (i.e. it is underspecified in one way
+could describes many instances, (i.e. it is under-specified in one way
 or another), then we say it is **abstract**.
 
 Spack's job is to take an *abstract* spec from the user, find a
@@ -63,73 +65,87 @@ building the software off to the package object.  The rest of this
 document describes all the pieces that come together to make that
 happen.
 
-
+-------------------
 Directory Structure
--------------------------
+-------------------
 
 So that you can familiarize yourself with the project, we'll start
-with a high level view of Spack's directory structure::
+with a high level view of Spack's directory structure:
 
-  spack/                  <- installation root
-     bin/
-        spack             <- main spack executable
-     var/
-        spack/            <- build & stage directories
-     opt/
-        spack/            <- packages are installed here
-     lib/
-        spack/
-           docs/          <- source for this documentation
-           env/           <- compiler wrappers for build environment
+.. code-block:: none
 
-           spack/         <- spack module; contains Python code
-              cmd/        <- each file in here is a spack subcommand
-              compilers/  <- compiler description files
-              packages/   <- each file in here is a spack package
-              test/       <- unit test modules
-              util/       <- common code
+   spack/                  <- installation root
+      bin/
+         spack             <- main spack executable
+
+      etc/
+         spack/            <- Spack config files.
+                              Can be overridden by files in ~/.spack.
+
+      var/
+         spack/            <- build & stage directories
+             repos/            <- contains package repositories
+                builtin/       <- pkg repository that comes with Spack
+                   repo.yaml   <- descriptor for the builtin repository
+                   packages/   <- directories under here contain packages
+             cache/        <- saves resources downloaded during installs
+
+      opt/
+         spack/            <- packages are installed here
+
+      lib/
+         spack/
+            docs/          <- source for this documentation
+            env/           <- compiler wrappers for build environment
+
+            external/      <- external libs included in Spack distro
+            llnl/          <- some general-use libraries
+
+            spack/         <- spack module; contains Python code
+               cmd/        <- each file in here is a spack subcommand
+               compilers/  <- compiler description files
+               test/       <- unit test modules
+               util/       <- common code
 
 Spack is designed so that it could live within a `standard UNIX
 directory hierarchy <http://linux.die.net/man/7/hier>`_, so ``lib``,
 ``var``, and ``opt`` all contain a ``spack`` subdirectory in case
-Spack is installed alongside other software.  Most of the insteresting
-parts of Spack live in ``lib/spack``.  Files under ``var`` are created
-as needed, so there is no ``var`` directory when you initially clone
-Spack from the repository.
+Spack is installed alongside other software.  Most of the interesting
+parts of Spack live in ``lib/spack``.
 
 Spack has *one* directory layout and there is no install process.
-version and the source code.  Most Python programs don't look like
-this (they use distutils, ``setup.py``, etc.) but we wanted to make
-Spack *very* easy to use.  The simple layout spares users from the
-need to install Spack into a Python environment.  Many users don't
-have write access to a Python installation, and installing an entire
-new instance of Python to bootstrap Spack would be very complicated.
+Most Python programs don't look like this (they use distutils, ``setup.py``,
+etc.) but we wanted to make Spack *very* easy to use.  The simple layout
+spares users from the need to install Spack into a Python environment.
+Many users don't have write access to a Python installation, and installing
+an entire new instance of Python to bootstrap Spack would be very complicated.
 Users should not have to install install a big, complicated package to
 use the thing that's supposed to spare them from the details of big,
 complicated packages.  The end result is that Spack works out of the
 box: clone it and add ``bin`` to your PATH and you're ready to go.
 
-
+--------------
 Code Structure
--------------------------
+--------------
 
 This section gives an overview of the various Python modules in Spack,
 grouped by functionality.
 
+^^^^^^^^^^^^^^^^^^^^^^^
 Package-related modules
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
 
 :mod:`spack.package`
   Contains the :class:`Package <spack.package.Package>` class, which
   is the superclass for all packages in Spack.  Methods on ``Package``
   implement all phases of the :ref:`package lifecycle
-  <pacakge-lifecycle>` and manage the build process.
+  <package-lifecycle>` and manage the build process.
 
 :mod:`spack.packages`
   Contains all of the packages in Spack and methods for managing them.
   Functions like :func:`packages.get <spack.packages.get>` and
   :func:`class_name_for_package_name
-  <packages.class_name_for_package_name>` handle mapping packge module
+  <packages.class_name_for_package_name>` handle mapping package module
   names to class names and dynamically instantiating packages by name
   from module files.
 
@@ -144,9 +160,9 @@ Package-related modules
   decorator, which allows :ref:`multimethods <multimethods>` in
   packages.
 
-
+^^^^^^^^^^^^^^^^^^^^
 Spec-related modules
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^
 
 :mod:`spack.spec`
   Contains :class:`Spec <spack.spec.Spec>` and :class:`SpecParser
@@ -194,9 +210,9 @@ Spec-related modules
      Not yet implemented.  Should eventually have architecture
      descriptions for cross-compiling.
 
-
+^^^^^^^^^^^^^^^^^
 Build environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^
 
 :mod:`spack.stage`
   Handles creating temporary directories for builds.
@@ -210,15 +226,17 @@ Build environment
   Create more implementations of this to change the hierarchy and
   naming scheme in ``$spack_prefix/opt``
 
+^^^^^^^^^^^^^^^^^
 Spack Subcommands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^
 
 :mod:`spack.cmd`
   Each module in this package implements a Spack subcommand.  See
   :ref:`writing commands <writing-commands>` for details.
 
+^^^^^^^^^^
 Unit tests
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^
 
 :mod:`spack.test`
   Implements Spack's test suite.  Add a module and put its name in
@@ -228,78 +246,100 @@ Unit tests
   This is a fake package hierarchy used to mock up packages for
   Spack's test suite.
 
+^^^^^^^^^^^^^
 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
--------------------------
+------------
 
+---------------
 Package objects
--------------------------
-
-
-Most spack commands
-look something like this:
-
-   #. Parse an abstract spec (or specs) from the command line,
-   #. *Normalize* the spec based on information in package files,
-   #. *Concretize* the spec according to some customizable policies,
-   #. Instantiate a package based on the spec, and
-   #. Call methods (e.g., ``install()``) on the package object.
+---------------
 
+Most spack commands look something like this:
 
+#. Parse an abstract spec (or specs) from the command line,
+#. *Normalize* the spec based on information in package files,
+#. *Concretize* the spec according to some customizable policies,
+#. Instantiate a package based on the spec, and
+#. Call methods (e.g., ``install()``) on the package object.
 
 The information in Package files is used at all stages in this
 process.
 
+Conceptually, packages are overloaded.  They contain:
 
-Conceptually, packages are overloaded.  They contain
-
+-------------
 Stage objects
--------------------------
+-------------
 
 .. _writing-commands:
 
+----------------
 Writing commands
--------------------------
+----------------
 
+----------
 Unit tests
--------------------------
+----------
 
+------------
 Unit testing
--------------------------
-
+------------
 
+------------------
 Developer commands
--------------------------
+------------------
 
+^^^^^^^^^^^^^
 ``spack doc``
-~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
+^^^^^^^^^^^^^^
 ``spack test``
-~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^
+
+---------
+Profiling
+---------
+
+Spack has some limited built-in support for profiling, and can report
+statistics using standard Python timing tools.  To use this feature,
+supply ``--profile`` to Spack on the command line, before any subcommands.
+
+.. _spack-p:
+
+^^^^^^^^^^^^^^^^^^^
+``spack --profile``
+^^^^^^^^^^^^^^^^^^^
+
+``spack --profile`` output looks like this:
+
+.. command-output:: spack --profile graph dyninst
+   :ellipsis: 25
+
+The bottom of the output shows the top most time consuming functions,
+slowest on top.  The profiling support is from Python's built-in tool,
+`cProfile
+<https://docs.python.org/2/library/profile.html#module-cProfile>`_.

lib/spack/docs/exts/sphinxcontrib/__init__.py

@@ -1,27 +1,3 @@
-##############################################################################
-# Copyright (c) 2013, Lawrence Livermore National Security, LLC.
-# Produced at the Lawrence Livermore National Laboratory.
-#
-# This file is part of Spack.
-# Written by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
-# LLNL-CODE-647188
-#
-# For details, see https://scalability-llnl.github.io/spack
-# Please also see the LICENSE file for our notice and the LGPL.
-#
-# This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License (as published by
-# the Free Software Foundation) version 2.1 dated February 1999.
-#
-# This program is distributed in the hope that it will be useful, but
-# WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
-# conditions of the GNU General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with this program; if not, write to the Free Software Foundation,
-# Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-##############################################################################
 # -*- coding: utf-8 -*-
 """
     sphinxcontrib

lib/spack/docs/exts/sphinxcontrib/programoutput.py

@@ -1,27 +1,3 @@
-##############################################################################
-# Copyright (c) 2013, Lawrence Livermore National Security, LLC.
-# Produced at the Lawrence Livermore National Laboratory.
-#
-# This file is part of Spack.
-# Written by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
-# LLNL-CODE-647188
-#
-# For details, see https://scalability-llnl.github.io/spack
-# Please also see the LICENSE file for our notice and the LGPL.
-#
-# This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License (as published by
-# the Free Software Foundation) version 2.1 dated February 1999.
-#
-# This program is distributed in the hope that it will be useful, but
-# WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
-# conditions of the GNU General Public License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with this program; if not, write to the Free Software Foundation,
-# Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-##############################################################################
 # -*- coding: utf-8 -*-
 # Copyright (c) 2010, 2011, 2012, Sebastian Wiesner <lunaryorn@gmail.com>
 # All rights reserved.

lib/spack/docs/features.rst

@@ -1,29 +1,32 @@
+================
 Feature Overview
-==================
+================
 
 This is a high-level overview of features that make Spack different
 from other `package managers
 <http://en.wikipedia.org/wiki/Package_management_system>`_ and `port
 systems <http://en.wikipedia.org/wiki/Ports_collection>`_.
 
+---------------------------
 Simple package installation
-----------------------------
+---------------------------
 
 Installing the default version of a package is simple. This will install
 the latest version of the ``mpileaks`` package and all of its dependencies:
 
-.. code-block:: sh
+.. code-block:: console
 
    $ spack install mpileaks
 
+--------------------------------
 Custom versions & configurations
--------------------------------------------
+--------------------------------
 
 Spack allows installation to be customized.  Users can specify the
 version, build compiler, compile-time options, and cross-compile
 platform, all on the command line.
 
-.. code-block:: sh
+.. code-block:: console
 
    # Install a particular version by appending @
    $ spack install mpileaks@1.1.2
@@ -31,46 +34,55 @@ platform, all on the command line.
    # Specify a compiler (and its version), with %
    $ spack install mpileaks@1.1.2 %gcc@4.7.3
 
-   # Add special compile-time options with +
+   # Add special compile-time options by name
+   $ spack install mpileaks@1.1.2 %gcc@4.7.3 debug=True
+
+   # Add special boolean compile-time options with +
    $ spack install mpileaks@1.1.2 %gcc@4.7.3 +debug
 
-   # Cross-compile for a different architecture with =
-   $ spack install mpileaks@1.1.2 =bgqos_0
+   # Add compiler flags using the conventional names
+   $ spack install mpileaks@1.1.2 %gcc@4.7.3 cppflags="-O3 -floop-block"
 
-Users can specify as many or few options as they care about.  Spack
-will fill in the unspecified values with sensible defaults.
+   # Cross-compile for a different architecture with arch=
+   $ spack install mpileaks@1.1.2 arch=bgqos_0
 
+Users can specify as many or few options as they care about. Spack
+will fill in the unspecified values with sensible defaults. The two listed
+syntaxes for variants are identical when the value is boolean.
 
+----------------------
 Customize dependencies
--------------------------------------
+----------------------
 
 Spack allows *dependencies* of a particular installation to be
 customized extensively.  Suppose that ``mpileaks`` depends indirectly
 on ``libelf`` and ``libdwarf``.  Using ``^``, users can add custom
 configurations for the dependencies:
 
-.. code-block:: sh
+.. code-block:: console
 
    # Install mpileaks and link it with specific versions of libelf and libdwarf
    $ spack install mpileaks@1.1.2 %gcc@4.7.3 +debug ^libelf@0.8.12 ^libdwarf@20130729+debug
 
-
+------------------------
 Non-destructive installs
--------------------------------------
+------------------------
 
 Spack installs every unique package/dependency configuration into its
 own prefix, so new installs will not break existing ones.
 
+-------------------------------
 Packages can peacefully coexist
--------------------------------------
+-------------------------------
 
 Spack avoids library misconfiguration by using ``RPATH`` to link
 dependencies.  When a user links a library or runs a program, it is
 tied to the dependencies it was built with, so there is no need to
 manipulate ``LD_LIBRARY_PATH`` at runtime.
 
+-------------------------
 Creating packages is easy
--------------------------------------
+-------------------------
 
 To create a new packages, all Spack needs is a URL for the source
 archive.  The ``spack create`` command will create a boilerplate
@@ -79,7 +91,7 @@ in pure Python.
 
 For example, this command:
 
-.. code-block:: sh
+.. code-block:: console
 
    $ spack create http://www.mr511.de/software/libelf-0.8.13.tar.gz
 
@@ -89,21 +101,31 @@ creates a simple python file:
 
    from spack import *
 
+
    class Libelf(Package):
-       homepage = "http://www.example.com/"
+       """FIXME: Put a proper description of your package here."""
+
+       # FIXME: Add a proper url for your package's homepage here.
+       homepage = "http://www.example.com"
        url      = "http://www.mr511.de/software/libelf-0.8.13.tar.gz"
 
-       versions = { '0.8.13' : '4136d7b4c04df68b686570afa26988ac' }
+       version('0.8.13', '4136d7b4c04df68b686570afa26988ac')
 
-       def install(self, prefix):
-           configure("--prefix=%s" % prefix)
+       # FIXME: Add dependencies if required.
+       # depends_on('foo')
+
+       def install(self, spec, prefix):
+           # FIXME: Modify the configure line to suit your build system here.
+           configure('--prefix={0}'.format(prefix))
+
+           # FIXME: Add logic to build and install here.
            make()
-           make("install")
+           make('install')
 
 It doesn't take much python coding to get from there to a working
 package:
 
-.. literalinclude:: ../../../var/spack/packages/libelf/package.py
+.. literalinclude:: ../../../var/spack/repos/builtin/packages/libelf/package.py
    :lines: 25-
 
 Spack also provides wrapper functions around common commands like

lib/spack/docs/index.rst

@@ -3,8 +3,9 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+===================
 Spack Documentation
-=================================
+===================
 
 Spack is a package management tool designed to support multiple
 versions and configurations of software on a wide variety of platforms
@@ -18,38 +19,58 @@ configurations can coexist on the same system.
 Most importantly, Spack is *simple*.  It offers a simple *spec* syntax
 so that users can specify versions and configuration options
 concisely.  Spack is also simple for package authors: package files
-are writtin in pure Python, and specs allow package authors to write a
-single build script for many different builds of the same package.
+are written in pure Python, and specs allow package authors to
+maintain a single file for many different builds of the same package.
 
 See the :doc:`features` for examples and highlights.
 
 Get spack from the `github repository
-<https://github.com/scalability-llnl/spack>`_ and install your first
+<https://github.com/llnl/spack>`_ and install your first
 package:
 
-.. code-block:: sh
+.. code-block:: console
 
-   $ git clone git@github.com:scalability-llnl/spack.git
+   $ git clone https://github.com/llnl/spack.git
    $ cd spack/bin
    $ ./spack install libelf
 
 If you're new to spack and want to start using it, see :doc:`getting_started`,
 or refer to the full manual below.
 
-Table of Contents
----------------------
 
 .. toctree::
    :maxdepth: 2
+   :caption: Basics
 
    features
    getting_started
    basic_usage
+   workflows
+   tutorial_sc16
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reference
+
+   configuration
+   config_yaml
+   build_settings
+   mirrors
+   module_file_support
+   repositories
+   command_index
+   package_list
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contributing
+
+   contribution_guide
    packaging_guide
-   site_configuration
    developer_guide
    API Docs <spack>
 
+==================
 Indices and tables
 ==================
 

lib/spack/docs/mirrors.rst

@@ -0,0 +1,245 @@
+.. _mirrors:
+
+=======
+Mirrors
+=======
+
+Some sites may not have access to the internet for fetching packages.
+These sites will need a local repository of tarballs from which they
+can get their files.  Spack has support for this with *mirrors*.  A
+mirror is a URL that points to a directory, either on the local
+filesystem or on some server, containing tarballs for all of Spack's
+packages.
+
+Here's an example of a mirror's directory structure:
+
+.. code-block:: none
+
+   mirror/
+       cmake/
+           cmake-2.8.10.2.tar.gz
+       dyninst/
+           dyninst-8.1.1.tgz
+           dyninst-8.1.2.tgz
+       libdwarf/
+           libdwarf-20130126.tar.gz
+           libdwarf-20130207.tar.gz
+           libdwarf-20130729.tar.gz
+       libelf/
+           libelf-0.8.12.tar.gz
+           libelf-0.8.13.tar.gz
+       libunwind/
+           libunwind-1.1.tar.gz
+       mpich/
+           mpich-3.0.4.tar.gz
+       mvapich2/
+           mvapich2-1.9.tgz
+
+The structure is very simple.  There is a top-level directory.  The
+second level directories are named after packages, and the third level
+contains tarballs for each package, named after each package.
+
+.. note::
+
+   Archives are **not** named exactly the way they were in the package's fetch
+   URL.  They have the form ``<name>-<version>.<extension>``, where
+   ``<name>`` is Spack's name for the package, ``<version>`` is the
+   version of the tarball, and ``<extension>`` is whatever format the
+   package's fetch URL contains.
+
+   In order to make mirror creation reasonably fast, we copy the
+   tarball in its original format to the mirror directory, but we do
+   not standardize on a particular compression algorithm, because this
+   would potentially require expanding and re-compressing each archive.
+
+.. _cmd-spack-mirror:
+
+----------------
+``spack mirror``
+----------------
+
+Mirrors are managed with the ``spack mirror`` command.  The help for
+``spack mirror`` looks like this:
+
+.. command-output:: spack help mirror
+
+The ``create`` command actually builds a mirror by fetching all of its
+packages from the internet and checksumming them.
+
+The other three commands are for managing mirror configuration.  They
+control the URL(s) from which Spack downloads its packages.
+
+.. _spack-mirror-create:
+
+-----------------------
+``spack mirror create``
+-----------------------
+
+You can create a mirror using the ``spack mirror create`` command, assuming
+you're on a machine where you can access the internet.
+
+The command will iterate through all of Spack's packages and download
+the safe ones into a directory structure like the one above.  Here is
+what it looks like:
+
+.. code-block:: console
+
+   $ spack mirror create libelf libdwarf
+   ==> Created new mirror in spack-mirror-2014-06-24
+   ==> Trying to fetch from http://www.mr511.de/software/libelf-0.8.13.tar.gz
+   ##########################################################                81.6%
+   ==> Checksum passed for libelf@0.8.13
+   ==> Added libelf@0.8.13
+   ==> Trying to fetch from http://www.mr511.de/software/libelf-0.8.12.tar.gz
+   ######################################################################    98.6%
+   ==> Checksum passed for libelf@0.8.12
+   ==> Added libelf@0.8.12
+   ==> Trying to fetch from http://www.prevanders.net/libdwarf-20130207.tar.gz
+   ######################################################################    97.3%
+   ==> Checksum passed for libdwarf@20130207
+   ==> Added libdwarf@20130207
+   ==> Trying to fetch from http://www.prevanders.net/libdwarf-20130126.tar.gz
+   ########################################################                  78.9%
+   ==> Checksum passed for libdwarf@20130126
+   ==> Added libdwarf@20130126
+   ==> Trying to fetch from http://www.prevanders.net/libdwarf-20130729.tar.gz
+   #############################################################             84.7%
+   ==> Added libdwarf@20130729
+   ==> Added spack-mirror-2014-06-24/libdwarf/libdwarf-20130729.tar.gz to mirror
+   ==> Added python@2.7.8.
+   ==> Successfully updated mirror in spack-mirror-2015-02-24.
+     Archive stats:
+       0    already present
+       5    added
+       0    failed to fetch.
+
+Once this is done, you can tar up the ``spack-mirror-2014-06-24`` directory and
+copy it over to the machine you want it hosted on.
+
+^^^^^^^^^^^^^^^^^^^
+Custom package sets
+^^^^^^^^^^^^^^^^^^^
+
+Normally, ``spack mirror create`` downloads all the archives it has
+checksums for.  If you want to only create a mirror for a subset of
+packages, you can do that by supplying a list of package specs on the
+command line after ``spack mirror create``.  For example, this
+command:
+
+.. code-block:: console
+
+   $ spack mirror create libelf@0.8.12: boost@1.44:
+
+Will create a mirror for libelf versions greater than or equal to
+0.8.12 and boost versions greater than or equal to 1.44.
+
+^^^^^^^^^^^^
+Mirror files
+^^^^^^^^^^^^
+
+If you have a *very* large number of packages you want to mirror, you
+can supply a file with specs in it, one per line:
+
+.. code-block:: console
+
+   $ cat specs.txt
+   libdwarf
+   libelf@0.8.12:
+   boost@1.44:
+   boost@1.39.0
+   ...
+   $ spack mirror create --file specs.txt
+   ...
+
+This is useful if there is a specific suite of software managed by
+your site.
+
+.. _spack-mirror-add:
+
+--------------------
+``spack mirror add``
+--------------------
+
+Once you have a mirror, you need to let spack know about it.  This is
+relatively simple.  First, figure out the URL for the mirror.  If it's
+a file, you can use a file URL like this one:
+
+.. code-block:: none
+
+   file://~/spack-mirror-2014-06-24
+
+That points to the directory on the local filesystem.  If it were on a
+web server, you could use a URL like this one:
+
+https://example.com/some/web-hosted/directory/spack-mirror-2014-06-24
+
+Spack will use the URL as the root for all of the packages it fetches.
+You can tell your Spack installation to use that mirror like this:
+
+.. code-block:: console
+
+   $ spack mirror add local_filesystem file://~/spack-mirror-2014-06-24
+
+Each mirror has a name so that you can refer to it again later.
+
+.. _spack-mirror-list:
+
+---------------------
+``spack mirror list``
+---------------------
+
+To see all the mirrors Spack knows about, run ``spack mirror list``:
+
+.. code-block:: console
+
+   $ spack mirror list
+   local_filesystem    file://~/spack-mirror-2014-06-24
+
+.. _spack-mirror-remove:
+
+-----------------------
+``spack mirror remove``
+-----------------------
+
+To remove a mirror by name, run:
+
+.. code-block:: console
+
+   $ spack mirror remove local_filesystem
+   $ spack mirror list
+   ==> No mirrors configured.
+
+-----------------
+Mirror precedence
+-----------------
+
+Adding a mirror really adds a line in ``~/.spack/mirrors.yaml``:
+
+.. code-block:: yaml
+
+   mirrors:
+     local_filesystem: file://~/spack-mirror-2014-06-24
+     remote_server: https://example.com/some/web-hosted/directory/spack-mirror-2014-06-24
+
+If you want to change the order in which mirrors are searched for
+packages, you can edit this file and reorder the sections.  Spack will
+search the topmost mirror first and the bottom-most mirror last.
+
+.. _caching:
+
+-------------------
+Local Default Cache
+-------------------
+
+Spack caches resources that are downloaded as part of installs. The cache is
+a valid spack mirror: it uses the same directory structure and naming scheme
+as other Spack mirrors (so it can be copied anywhere and referenced with a URL
+like other mirrors). The mirror is maintained locally (within the Spack
+installation directory) at :file:`var/spack/cache/`. It is always enabled (and
+is always searched first when attempting to retrieve files for an installation)
+but can be cleared with :ref:`purge <cmd-spack-purge>`; the cache directory can also
+be deleted manually without issue.
+
+Caching includes retrieved tarball archives and source control repositories, but
+only resources with an associated digest or commit ID (e.g. a revision number
+for SVN) will be cached.

lib/spack/docs/module_file_support.rst

@@ -0,0 +1,682 @@
+.. _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
+programmers on their development machines. To support this common practice
+Spack provides integration with `Environment Modules
+<http://modules.sourceforge.net/>`_ ,  `LMod
+<http://lmod.readthedocs.io/en/latest/>`_ and `Dotkit <https://computing.llnl.gov/?set=jobs&page=dotkit>`_ by:
+
+* generating module files after a successful installation
+* providing commands that can leverage the spec syntax to manipulate modules
+
+In the following you will see how to activate shell support for commands in Spack
+that requires it, and discover what benefits this may bring with respect to deal
+directly with automatically generated module files.
+
+.. note::
+
+   If your machine does not already have a module system installed,
+   we advise you to use either Environment Modules or LMod. See :ref:`InstallEnvironmentModules`
+   for more details.
+
+.. _shell-support:
+
+-------------
+Shell support
+-------------
+
+You can enable shell support by sourcing the appropriate setup file
+in the ``$SPACK_ROOT/share/spack`` directory.
+For ``bash`` or ``ksh`` users:
+
+.. code-block:: console
+
+   $ . ${SPACK_ROOT}/share/spack/setup-env.sh
+
+For ``csh`` and ``tcsh`` instead:
+
+.. code-block:: console
+
+   $ source $SPACK_ROOT/share/spack/setup-env.csh
+
+
+.. note::
+  You can put the source line in your ``.bashrc`` or ``.cshrc`` to
+  have Spack's shell support available on the command line at any login.
+
+
+----------------------------
+Using module files via Spack
+----------------------------
+
+If you have shell support enabled you should be able to run either
+``module avail`` or ``use -l spack`` to see what module/dotkit files have
+been installed.  Here is sample output of those programs, showing lots
+of installed packages.
+
+.. code-block:: console
+
+   $ module avail
+
+   ------- ~/spack/share/spack/modules/linux-debian7-x86_64 --------
+   adept-utils@1.0%gcc@4.4.7-5adef8da   libelf@0.8.13%gcc@4.4.7
+   automaded@1.0%gcc@4.4.7-d9691bb0     libelf@0.8.13%intel@15.0.0
+   boost@1.55.0%gcc@4.4.7               mpc@1.0.2%gcc@4.4.7-559607f5
+   callpath@1.0.1%gcc@4.4.7-5dce4318    mpfr@3.1.2%gcc@4.4.7
+   dyninst@8.1.2%gcc@4.4.7-b040c20e     mpich@3.0.4%gcc@4.4.7
+   gcc@4.9.1%gcc@4.4.7-93ab98c5         mpich@3.0.4%gcc@4.9.0
+   gmp@6.0.0a%gcc@4.4.7                 mrnet@4.1.0%gcc@4.4.7-72b7881d
+   graphlib@2.0.0%gcc@4.4.7             netgauge@2.4.6%gcc@4.9.0-27912b7b
+   launchmon@1.0.1%gcc@4.4.7            stat@2.1.0%gcc@4.4.7-51101207
+   libNBC@1.1.1%gcc@4.9.0-27912b7b      sundials@2.5.0%gcc@4.9.0-27912b7b
+   libdwarf@20130729%gcc@4.4.7-b52fac98
+
+.. code-block:: console
+
+   $ use -l spack
+
+   spack ----------
+     adept-utils@1.0%gcc@4.4.7-5adef8da - adept-utils @1.0
+     automaded@1.0%gcc@4.4.7-d9691bb0 - automaded @1.0
+     boost@1.55.0%gcc@4.4.7 - boost @1.55.0
+     callpath@1.0.1%gcc@4.4.7-5dce4318 - callpath @1.0.1
+     dyninst@8.1.2%gcc@4.4.7-b040c20e - dyninst @8.1.2
+     gmp@6.0.0a%gcc@4.4.7 - gmp @6.0.0a
+     libNBC@1.1.1%gcc@4.9.0-27912b7b - libNBC @1.1.1
+     libdwarf@20130729%gcc@4.4.7-b52fac98 - libdwarf @20130729
+     libelf@0.8.13%gcc@4.4.7 - libelf @0.8.13
+     libelf@0.8.13%intel@15.0.0 - libelf @0.8.13
+     mpc@1.0.2%gcc@4.4.7-559607f5 - mpc @1.0.2
+     mpfr@3.1.2%gcc@4.4.7 - mpfr @3.1.2
+     mpich@3.0.4%gcc@4.4.7 - mpich @3.0.4
+     mpich@3.0.4%gcc@4.9.0 - mpich @3.0.4
+     netgauge@2.4.6%gcc@4.9.0-27912b7b - netgauge @2.4.6
+     sundials@2.5.0%gcc@4.9.0-27912b7b - sundials @2.5.0
+
+The names here should look familiar, they're the same ones from
+``spack find``.  You *can* use the names here directly.  For example,
+you could type either of these commands to load the callpath module:
+
+.. code-block:: console
+
+   $ use callpath@1.0.1%gcc@4.4.7-5dce4318
+
+.. code-block:: console
+
+   $ 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:
+
+=========================  ==========================
+Environment Modules        Dotkit
+=========================  ==========================
+``spack load <spec>``      ``spack use <spec>``
+``spack unload <spec>``    ``spack unuse <spec>``
+=========================  ==========================
+
+And you can use the same shortened names you use everywhere else in
+Spack.  For example, this will add the ``mpich`` package built with
+``gcc`` to your path:
+
+.. code-block:: console
+
+   $ spack install mpich %gcc@4.4.7
+
+   # ... wait for install ...
+
+   $ spack use mpich %gcc@4.4.7
+   Prepending: mpich@3.0.4%gcc@4.4.7 (ok)
+   $ which mpicc
+   ~/spack/opt/linux-debian7-x86_64/gcc@4.4.7/mpich@3.0.4/bin/mpicc
+
+Or, similarly with modules, you could type:
+
+.. code-block:: console
+
+   $ spack load mpich %gcc@4.4.7
+
+These commands will add appropriate directories to your ``PATH``,
+``MANPATH``, ``CPATH``, and ``LD_LIBRARY_PATH``.  When you no longer
+want to use a package, you can type unload or unuse similarly:
+
+.. code-block:: console
+
+   $ spack unload mpich %gcc@4.4.7  # modules
+   $ spack unuse  mpich %gcc@4.4.7  # dotkit
+
+.. note::
+
+   These ``use``, ``unuse``, ``load``, and ``unload`` subcommands are
+   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:
+
+.. code-block:: console
+
+   $ spack load libelf
+   ==> Error: Multiple matches for spec libelf.  Choose one:
+   libelf@0.8.13%gcc@4.4.7 arch=linux-debian7-x86_64
+   libelf@0.8.13%intel@15.0.0 arch=linux-debian7-x86_64
+
+You can either type the ``spack load`` command again with a fully
+qualified argument, or you can add just enough extra constraints to
+identify one package.  For example, above, the key differentiator is
+that one ``libelf`` is built with the Intel compiler, while the other
+used ``gcc``.  You could therefore just type:
+
+.. code-block:: console
+
+   $ spack load libelf %intel
+
+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
+because Spack builds binaries with RPATH support.  However, not all
+packages use RPATH to find their dependencies: this can be true in
+particular for Python extensions, which are currently *not* built with
+RPATH.
+
+Scripts to load modules recursively may be made with the command:
+
+.. code-block:: console
+
+    $ spack module loads --dependencies <spec>
+
+An equivalent alternative is:
+
+.. code-block :: console
+
+    $ source <( spack module loads --dependencies <spec> )
+
+.. warning::
+
+    The ``spack load`` command does not currently accept the
+    ``--dependencies`` flag.  Use ``spack module loads`` instead, for
+    now.
+
+.. See #1662
+
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Module Commands for Shell Scripts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Although Spack is flexible, the ``module`` command is much faster.
+This could become an issue when emitting a series of ``spack load``
+commands inside a shell script.  By adding the ``--shell`` flag,
+``spack module find`` may also be used to generate code that can be
+cut-and-pasted into a shell script.  For example:
+
+.. code-block:: console
+
+    $ spack module loads --dependencies py-numpy git
+    # bzip2@1.0.6%gcc@4.9.3=linux-x86_64
+    module load bzip2-1.0.6-gcc-4.9.3-ktnrhkrmbbtlvnagfatrarzjojmkvzsx
+    # ncurses@6.0%gcc@4.9.3=linux-x86_64
+    module load ncurses-6.0-gcc-4.9.3-kaazyneh3bjkfnalunchyqtygoe2mncv
+    # zlib@1.2.8%gcc@4.9.3=linux-x86_64
+    module load zlib-1.2.8-gcc-4.9.3-v3ufwaahjnviyvgjcelo36nywx2ufj7z
+    # sqlite@3.8.5%gcc@4.9.3=linux-x86_64
+    module load sqlite-3.8.5-gcc-4.9.3-a3eediswgd5f3rmto7g3szoew5nhehbr
+    # readline@6.3%gcc@4.9.3=linux-x86_64
+    module load readline-6.3-gcc-4.9.3-se6r3lsycrwxyhreg4lqirp6xixxejh3
+    # python@3.5.1%gcc@4.9.3=linux-x86_64
+    module load python-3.5.1-gcc-4.9.3-5q5rsrtjld4u6jiicuvtnx52m7tfhegi
+    # py-setuptools@20.5%gcc@4.9.3=linux-x86_64
+    module load py-setuptools-20.5-gcc-4.9.3-4qr2suj6p6glepnedmwhl4f62x64wxw2
+    # py-nose@1.3.7%gcc@4.9.3=linux-x86_64
+    module load py-nose-1.3.7-gcc-4.9.3-pwhtjw2dvdvfzjwuuztkzr7b4l6zepli
+    # openblas@0.2.17%gcc@4.9.3+shared=linux-x86_64
+    module load openblas-0.2.17-gcc-4.9.3-pw6rmlom7apfsnjtzfttyayzc7nx5e7y
+    # py-numpy@1.11.0%gcc@4.9.3+blas+lapack=linux-x86_64
+    module load py-numpy-1.11.0-gcc-4.9.3-mulodttw5pcyjufva4htsktwty4qd52r
+    # curl@7.47.1%gcc@4.9.3=linux-x86_64
+    module load curl-7.47.1-gcc-4.9.3-ohz3fwsepm3b462p5lnaquv7op7naqbi
+    # autoconf@2.69%gcc@4.9.3=linux-x86_64
+    module load autoconf-2.69-gcc-4.9.3-bkibjqhgqm5e3o423ogfv2y3o6h2uoq4
+    # cmake@3.5.0%gcc@4.9.3~doc+ncurses+openssl~qt=linux-x86_64
+    module load cmake-3.5.0-gcc-4.9.3-x7xnsklmgwla3ubfgzppamtbqk5rwn7t
+    # expat@2.1.0%gcc@4.9.3=linux-x86_64
+    module load expat-2.1.0-gcc-4.9.3-6pkz2ucnk2e62imwakejjvbv6egncppd
+    # git@2.8.0-rc2%gcc@4.9.3+curl+expat=linux-x86_64
+    module load git-2.8.0-rc2-gcc-4.9.3-3bib4hqtnv5xjjoq5ugt3inblt4xrgkd
+
+The script may be further edited by removing unnecessary modules.
+
+
+^^^^^^^^^^^^^^^
+Module Prefixes
+^^^^^^^^^^^^^^^
+
+On some systems, modules are automatically prefixed with a certain
+string; ``spack module loads`` needs to know about that prefix when it
+issues ``module load`` commands.  Add the ``--prefix`` option to your
+``spack module loads`` commands if this is necessary.
+
+For example, consider the following on one system:
+
+.. code-block:: console
+
+    $ module avail
+    linux-SuSE11-x86_64/antlr-2.7.7-gcc-5.3.0-bdpl46y
+
+    $ spack module loads antlr    # WRONG!
+    # antlr@2.7.7%gcc@5.3.0~csharp+cxx~java~python arch=linux-SuSE11-x86_64
+    module load antlr-2.7.7-gcc-5.3.0-bdpl46y
+
+    $ spack module loads --prefix linux-SuSE11-x86_64/ antlr
+    # 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
+
+----------------------------
+Auto-generating Module Files
+----------------------------
+
+Module files are generated by post-install hooks after the successful
+installation of a package. The following table summarizes the essential
+information associated with the different file formats
+that can be generated by Spack:
+
+  +-----------------------------+--------------------+-------------------------------+----------------------+
+  |                             | **Hook name**      |  **Default root directory**   | **Compatible tools** |
+  +=============================+====================+===============================+======================+
+  |  **Dotkit**                 | ``dotkit``         |   share/spack/dotkit          |  DotKit              |
+  +-----------------------------+--------------------+-------------------------------+----------------------+
+  |  **TCL - Non-Hierarchical** | ``tcl``            |  share/spack/modules          | Env. Modules/LMod    |
+  +-----------------------------+--------------------+-------------------------------+----------------------+
+  |  **Lua - Hierarchical**     | ``lmod``           |   share/spack/lmod            | LMod                 |
+  +-----------------------------+--------------------+-------------------------------+----------------------+
+
+
+Though Spack ships with sensible defaults for the generation of module files,
+one can customize many aspects of it to accommodate package or site specific needs.
+These customizations are enabled by either:
+
+ 1. overriding certain callback APIs in the Python packages
+ 2. writing specific rules in the ``modules.yaml`` configuration file
+
+The former method fits best cases that are site independent, e.g. injecting variables
+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.
+
+^^^^^^^^^^^^^^^^^^^^
+``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:
+
+.. code-block:: python
+
+   def setup_environment(self, spack_env, run_env):
+       """Set up the compile and runtime environments for a package."""
+       pass
+
+and can alter the content of *the same package where it is overridden*
+by adding actions to ``run_env``. The second method is:
+
+.. code-block:: python
+
+   def setup_dependent_environment(self, spack_env, run_env, dependent_spec):
+       """Set up the environment of packages that depend on this one"""
+       pass
+
+and has similar effects on module file of dependees. Even in this case
+``run_env`` must be filled with the desired list of environment modifications.
+
+.. note::
+ The ``r`` package and callback APIs
+  A typical example in which overriding both methods prove to be useful
+  is given by the ``r`` package. This package installs libraries and headers
+  in non-standard locations and it is possible to prepend the appropriate directory
+  to the corresponding environment variables:
+
+  ================== =================================
+   LIBRARY_PATH       ``self.prefix/rlib/R/lib``
+   LD_LIBRARY_PATH    ``self.prefix/rlib/R/lib``
+   CPATH              ``self.prefix/rlib/R/include``
+  ================== =================================
+
+  with the following snippet:
+
+  .. literalinclude:: ../../../var/spack/repos/builtin/packages/r/package.py
+     :pyobject: R.setup_environment
+
+  The ``r`` package also knows which environment variable should be modified
+  to make language extensions provided by other packages available, and modifies
+  it appropriately in the override of the second method:
+
+  .. literalinclude:: ../../../var/spack/repos/builtin/packages/r/package.py
+     :lines: 128-129,146-151
+
+.. _modules-yaml:
+
+---------------------------------
+Configuration in ``modules.yaml``
+---------------------------------
+
+The name of the configuration file that controls module generation behavior
+is ``modules.yaml``. The default configuration:
+
+.. literalinclude:: ../../../etc/spack/defaults/modules.yaml
+   :language: yaml
+
+activates generation for ``tcl`` and ``dotkit`` module files and inspects
+the installation folder of each package for the presence of a set of subdirectories
+(``bin``, ``man``, ``share/man``, etc.). If any is found its full path is prepended
+to the environment variables listed below the folder name.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Activation of other systems
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Any other module file generator shipped with Spack can be activated adding it to the
+list under the ``enable`` key in the module file. Currently the only generator that
+is not activated by default is ``lmod``, which produces hierarchical lua module files.
+For each module system that can be enabled a finer configuration is possible.
+
+Directives that are aimed at driving the generation of a particular type of module files
+should be listed under a top level key that corresponds to the generator being
+customized:
+
+.. code-block:: yaml
+
+   modules:
+     enable:
+       - tcl
+       - dotkit
+       - lmod
+     tcl:
+       # contains environment modules specific customizations
+     dotkit:
+       # contains dotkit specific customizations
+     lmod:
+       # contains lmod specific customizations
+
+All these module sections allow for both:
+
+1. global directives that usually affect the whole layout of modules or the naming scheme
+2. directives that affect only a set of packages and modify their content
+
+For the latter point in particular it is possible to use anonymous specs
+to select an appropriate set of packages on which the modifications should be applied.
+
+.. _anonymous_specs:
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Selection by anonymous specs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The procedure to select packages using anonymous specs is a natural
+extension of using them to install packages, the only difference being
+that specs in this case **are not required to have a root package**.
+Consider for instance this snippet:
+
+.. code-block:: yaml
+
+   modules:
+     tcl:
+       # The keyword `all` selects every package
+       all:
+         environment:
+           set:
+             BAR: 'bar'
+       # This anonymous spec selects any package that
+       # depends on openmpi. The double colon at the
+       # end clears the set of rules that matched so far.
+       ^openmpi::
+         environment:
+           set:
+             BAR: 'baz'
+       # Selects any zlib package
+       zlib:
+         environment:
+           prepend_path:
+             LD_LIBRARY_PATH: 'foo'
+       # Selects zlib compiled with gcc@4.8
+       zlib%gcc@4.8:
+         environment:
+           unset:
+           - FOOBAR
+
+During module file generation, the configuration above will instruct
+Spack to set the environment variable ``BAR=bar`` for every module,
+unless the associated spec satisfies ``^openmpi`` in which case ``BAR=baz``.
+In addition in any spec that satisfies ``zlib`` the value ``foo`` will be
+prepended to ``LD_LIBRARY_PATH`` and in any spec that satisfies ``zlib%gcc@4.8``
+the variable ``FOOBAR`` will be unset.
+
+.. note::
+   Order does matter
+     The modifications associated with the ``all`` keyword are always evaluated
+     first, no matter where they appear in the configuration file. All the other
+     spec constraints are instead evaluated top to bottom.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Blacklist or whitelist the generation of specific module files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Anonymous specs are also used to prevent module files from being written or
+to force them to be written. A common case for that at HPC centers is to hide
+from users all of the software that needs to be built with system compilers.
+Suppose for instance to have ``gcc@4.4.7`` provided by your system. Then
+with a configuration file like this one:
+
+.. code-block:: yaml
+
+   modules:
+     tcl:
+       whitelist: ['gcc', 'llvm']  # Whitelist will have precedence over blacklist
+       blacklist: ['%gcc@4.4.7']   # Assuming gcc@4.4.7 is the system compiler
+
+you will skip the generation of module files for any package that
+is compiled with ``gcc@4.4.7``, with the exception of any ``gcc``
+or any ``llvm`` installation.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Customize the naming scheme
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The names of environment modules generated by spack are not always easy to
+fully comprehend due to the long hash in the name. There are two module
+configuration options to help with that. The first is a global setting to
+adjust the hash length. It can be set anywhere from 0 to 32 and has a default
+length of 7. This is the representation of the hash in the module file name and
+does not affect the size of the package hash. Be aware that the smaller the
+hash length the more likely naming conflicts will occur. The following snippet
+shows how to set hash length in the module file names:
+
+.. code-block:: yaml
+
+   modules:
+     tcl:
+       hash_length: 7
+
+To help make module names more readable, and to help alleviate name conflicts
+with a short hash, one can use the ``suffixes`` option in the modules
+configuration file. This option will add strings to modules that match a spec.
+For instance, the following config options,
+
+.. code-block:: yaml
+
+   modules:
+     tcl:
+       all:
+         suffixes:
+           ^python@2.7.12: 'python-2.7.12'
+           ^openblas: 'openblas'
+
+will add a ``python-2.7.12`` version string to any packages compiled with
+python matching the spec, ``python@2.7.12``. This is useful to know which
+version of python a set of python extensions is associated with. Likewise, the
+``openblas`` string is attached to any program that has openblas in the spec,
+most likely via the ``+blas`` variant specification.
+
+.. note::
+   TCL module files
+     A modification that is specific to ``tcl`` module files is the possibility
+     to change the naming scheme of modules.
+
+     .. code-block:: yaml
+
+       modules:
+         tcl:
+           naming_scheme: '${PACKAGE}/${VERSION}-${COMPILERNAME}-${COMPILERVER}'
+           all:
+             conflict: ['${PACKAGE}', 'intel/14.0.1']
+
+     will create module files that will conflict with ``intel/14.0.1`` and with the
+     base directory of the same module, effectively preventing the possibility to
+     load two or more versions of the same software at the same time. The tokens
+     that are available for use in this directive are the same understood by
+     the ``Spec.format`` method.
+
+
+.. note::
+   LMod hierarchical module files
+     When ``lmod`` is activated Spack will generate a set of hierarchical lua module
+     files that are understood by LMod. The generated hierarchy always contains the
+     three layers ``Core`` / ``Compiler`` / ``MPI`` but can be further extended to
+     any other virtual dependency present in Spack. A case that could be useful in
+     practice is for instance:
+
+     .. code-block:: yaml
+
+       modules:
+         enable:
+           - lmod
+         lmod:
+           core_compilers: ['gcc@4.8']
+           hierarchical_scheme: ['lapack']
+
+     that will generate a hierarchy in which the ``lapack`` layer is treated as the ``mpi``
+     one. This allows a site to build the same libraries or applications against different
+     implementations of ``mpi`` and ``lapack``, and let LMod switch safely from one to the
+     other.
+
+.. warning::
+  Deep hierarchies and ``lmod spider``
+   For hierarchies that are deeper than three layers ``lmod spider`` may have some issues.
+   See `this discussion on the LMod project <https://github.com/TACC/Lmod/issues/114>`_.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Filter out environment modifications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Modifications to certain environment variables in module files are generated by
+default, for instance by prefix inspections in the default configuration file.
+There are cases though where some of these modifications are unwanted.
+Suppose you need to avoid having ``CPATH`` and ``LIBRARY_PATH``
+modified by your ``dotkit`` modules:
+
+.. code-block:: yaml
+
+   modules:
+     dotkit:
+       all:
+         filter:
+           # Exclude changes to any of these variables
+           environment_blacklist: ['CPATH', 'LIBRARY_PATH']
+
+The configuration above will generate dotkit module files that will not contain
+modifications to either ``CPATH`` or ``LIBRARY_PATH`` and environment module
+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``:
+
+.. code-block:: yaml
+
+   modules:
+     tcl:
+       ^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``.
+
+.. 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``
+     statement instead of automatically loading other modules.
+
+------------------------
+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
+a tool to ease the burden of their maintenance in production environments.
+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``:
+
+.. command-output:: spack module refresh --help
+
+A set of packages can be selected using anonymous specs for the optional
+``constraint`` positional argument. The argument ``--module-type`` identifies
+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``:
+
+.. 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.

lib/spack/docs/repositories.rst

@@ -0,0 +1,456 @@
+.. _repositories:
+
+=============================
+Package Repositories
+=============================
+
+Spack comes with over 1,000 built-in package recipes in
+``var/spack/repos/builtin/``.  This is a **package repository** -- a
+directory that Spack searches when it needs to find a package by name.
+You may need to maintain packages for restricted, proprietary or
+experimental software separately from the built-in repository. Spack
+allows you to configure local repositories using either the
+``repos.yaml`` or the ``spack repo`` command.
+
+A package repository a directory structured like this::
+
+  repo/
+      repo.yaml
+      packages/
+          hdf5/
+              package.py
+          mpich/
+              package.py
+              mpich-1.9-bugfix.patch
+          trilinos/
+              package.py
+          ...
+
+The top-level ``repo.yaml`` file contains configuration metadata for the
+repository, and the ``packages`` directory contains subdirectories for
+each package in the repository.  Each package directory contains a
+``package.py`` file and any patches or other files needed to build the
+package.
+
+Package repositories allow you to:
+
+1. Maintain your own packages separately from Spack;
+
+2. Share your packages (e.g. by hosting them in a shared file system),
+   without committing them to the built-in Spack package repository; and
+
+3. Override built-in Spack packages with your own implementation.
+
+Packages in a separate repository can also *depend on* built-in Spack
+packages.  So, you can leverage existing recipes without re-implementing
+them in your own repository.
+
+---------------------
+``repos.yaml``
+---------------------
+
+Spack uses the ``repos.yaml`` file in ``~/.spack`` (and :ref:`elsewhere
+<configuration>`) to find repositories. Note that the ``repos.yaml``
+configuration file is distinct from the ``repo.yaml`` file in each
+repository.  For more on the YAML format, and on how configuration file
+precedence works in Spack, see :ref:`configuration <configuration>`.
+
+The default ``etc/spack/defaults/repos.yaml`` file looks like this:
+
+.. code-block:: yaml
+
+  repos:
+  - $spack/var/spack/repos/builtin
+
+The file starts with ``repos:`` and contains a single ordered list of
+paths to repositories. Each path is on a separate line starting with
+``-``.  You can add a repository by inserting another path into the list:
+
+.. code-block:: yaml
+
+  repos:
+  - /opt/local-repo
+  - $spack/var/spack/repos/builtin
+
+When Spack interprets a spec, e.g. ``mpich`` in ``spack install mpich``,
+it searches these repositories in order (first to last) to resolve each
+package name.  In this example, Spack will look for the following
+packages and use the first valid file:
+
+1. ``/opt/local-repo/packages/mpich/package.py``
+2. ``$spack/var/spack/repos/builtin/packages/mpich/package.py``
+
+.. note::
+
+  Currently, Spack can only use repositories in the file system. We plan
+  to eventually support URLs in ``repos.yaml``, so that you can easily
+  point to remote package repositories, but that is not yet implemented.
+
+---------------------
+Namespaces
+---------------------
+
+Every repository in Spack has an associated **namespace** defined in its
+top-level ``repo.yaml`` file.  If you look at
+``var/spack/repos/builtin/repo.yaml`` in the built-in repository, you'll
+see that its namespace is ``builtin``:
+
+.. code-block:: console
+
+  $ cat var/spack/repos/builtin/repo.yaml
+  repo:
+    namespace: builtin
+
+Spack records the repository namespace of each installed package.  For
+example, if you install the ``mpich`` package from the ``builtin`` repo,
+Spack records its fully qualified name as ``builtin.mpich``.  This
+accomplishes two things:
+
+1. You can have packages with the same name from different namespaces
+   installed at once.
+
+1. You can easily determine which repository a package came from after it
+   is installed (more :ref:`below <namespace-example>`).
+
+.. note::
+
+   It may seem redundant for a repository to have both a namespace and a
+   path, but repository *paths* may change over time, or, as mentioned
+   above, a locally hosted repository path may eventually be hosted at
+   some remote URL.
+
+   Namespaces are designed to allow *package authors* to associate a
+   unique identifier with their packages, so that the package can be
+   identified even if the repository moves. This is why the namespace is
+   determined by the ``repo.yaml`` file in the repository rather than the
+   local ``repos.yaml`` configuration: the *repository maintainer* sets
+   the name.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Uniqueness
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You should choose a namespace that uniquely identifies your package
+repository.  For example, if you make a repository for packages written
+by your organization, you could use your organization's name.  You can
+also nest namespaces using periods, so you could identify a repository by
+a sub-organization.  For example, LLNL might use a namespace for its
+internal repositories like ``llnl``. Packages from the Physical & Life
+Sciences directorate (PLS) might use the ``llnl.pls`` namespace, and
+packages created by the Computation directorate might use ``llnl.comp``.
+
+Spack cannot ensure that every repository is named uniquely, but it will
+prevent you from registering two repositories with the same namespace at
+the same time.  If you try to add a repository that has the same name as
+an existing one, e.g. ``builtin``, Spack will print a warning message.
+
+.. _namespace-example:
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Namespace example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Suppose that LLNL maintains its own version of ``mpich``, separate from
+Spack's built-in ``mpich`` package, and suppose you've installed both
+LLNL's and Spack's ``mpich`` packages.  If you just use ``spack find``,
+you won't see a difference between these two packages:
+
+.. code-block:: console
+
+  $ spack find
+  ==> 2 installed packages.
+  -- linux-rhel6-x86_64 / gcc@4.4.7 -------------
+  mpich@3.2  mpich@3.2
+
+However, if you use ``spack find -N``, Spack will display the packages
+with their namespaces:
+
+.. code-block:: console
+
+  $ spack find -N
+  ==> 2 installed packages.
+  -- linux-rhel6-x86_64 / gcc@4.4.7 -------------
+  builtin.mpich@3.2  llnl.comp.mpich@3.2
+
+Now you know which one is LLNL's special version, and which one is the
+built-in Spack package.  As you might guess, packages that are identical
+except for their namespace will still have different hashes:
+
+.. code-block:: console
+
+  $ spack find -lN
+  ==> 2 installed packages.
+  -- linux-rhel6-x86_64 / gcc@4.4.7 -------------
+  c35p3gc builtin.mpich@3.2  itoqmox llnl.comp.mpich@3.2
+
+All Spack commands that take a package :ref:`spec <sec-specs>` can also
+accept a fully qualified spec with a namespace.  This means you can use
+the namespace to be more specific when designating, e.g., which package
+you want to uninstall:
+
+.. code-block:: console
+
+  spack uninstall llnl.comp.mpich
+
+----------------------------
+Overriding built-in packages
+----------------------------
+
+Spack's search semantics mean that you can make your own implementation
+of a built-in Spack package (like ``mpich``), put it in a repository, and
+use it to override the built-in package.  As long as the repository
+containing your ``mpich`` is earlier any other in ``repos.yaml``, any
+built-in package that depends on ``mpich`` will be use the one in your
+repository.
+
+Suppose you have three repositories: the builtin Spack repo
+(``builtin``), a shared repo for your institution (e.g., ``llnl``), and a
+repo containing your own prototype packages (``proto``).  Suppose they
+contain packages as follows:
+
+  +--------------+------------------------------------+-----------------------------+
+  | Namespace    | Path to repo                       | Packages                    |
+  +==============+====================================+=============================+
+  | ``proto``    | ``~/proto``                        | ``mpich``                   |
+  +--------------+------------------------------------+-----------------------------+
+  | ``llnl``     | ``/usr/local/llnl``                | ``hdf5``                    |
+  +--------------+------------------------------------+-----------------------------+
+  | ``builtin``  | ``$spack/var/spack/repos/builtin`` | ``mpich``, ``hdf5``, others |
+  +--------------+------------------------------------+-----------------------------+
+
+Suppose that ``hdf5`` depends on ``mpich``.  You can override the
+built-in ``hdf5`` by adding the ``llnl`` repo to ``repos.yaml``:
+
+.. code-block:: yaml
+
+   repos:
+   - /usr/local/llnl
+   - $spack/var/spack/repos/builtin
+
+``spack install hdf5`` will install ``llnl.hdf5 ^builtin.mpich``.
+
+If, instead, ``repos.yaml`` looks like this:
+
+.. code-block:: yaml
+
+   repos:
+   - ~/proto
+   - /usr/local/llnl
+   - $spack/var/spack/repos/builtin
+
+``spack install hdf5`` will install ``llnl.hdf5 ^proto.mpich``.
+
+Any unqualified package name will be resolved by searching ``repos.yaml``
+from the first entry to the last.  You can force a particular
+repository's package by using a fully qualified name.  For example, if
+your ``repos.yaml`` is as above, and you want ``builtin.mpich`` instead
+of ``proto.mpich``, you can write::
+
+  spack install hdf5 ^builtin.mpich
+
+which will install ``llnl.hdf5 ^builtin.mpich``.
+
+Similarly, you can force the ``builtin.hdf5`` like this::
+
+  spack install builtin.hdf5 ^builtin.mpich
+
+This will not search ``repos.yaml`` at all, as the ``builtin`` repo is
+specified in both cases.  It will install ``builtin.hdf5
+^builtin.mpich``.
+
+If you want to see which repositories will be used in a build *before*
+you install it, you can use ``spack spec -N``:
+
+.. code-block:: console
+
+   $ spack spec -N hdf5
+   Input spec
+   --------------------------------
+   hdf5
+
+   Normalized
+   --------------------------------
+   hdf5
+       ^zlib@1.1.2:
+
+   Concretized
+   --------------------------------
+   builtin.hdf5@1.10.0-patch1%clang@7.0.2-apple+cxx~debug+fortran+mpi+shared~szip~threadsafe arch=darwin-elcapitan-x86_64
+       ^builtin.openmpi@2.0.1%clang@7.0.2-apple~mxm~pmi~psm~psm2~slurm~sqlite3~thread_multiple~tm~verbs+vt arch=darwin-elcapitan-x86_64
+           ^builtin.hwloc@1.11.4%clang@7.0.2-apple arch=darwin-elcapitan-x86_64
+               ^builtin.libpciaccess@0.13.4%clang@7.0.2-apple arch=darwin-elcapitan-x86_64
+                   ^builtin.libtool@2.4.6%clang@7.0.2-apple arch=darwin-elcapitan-x86_64
+                       ^builtin.m4@1.4.17%clang@7.0.2-apple+sigsegv arch=darwin-elcapitan-x86_64
+                           ^builtin.libsigsegv@2.10%clang@7.0.2-apple arch=darwin-elcapitan-x86_64
+                   ^builtin.pkg-config@0.29.1%clang@7.0.2-apple+internal_glib arch=darwin-elcapitan-x86_64
+                   ^builtin.util-macros@1.19.0%clang@7.0.2-apple arch=darwin-elcapitan-x86_64
+       ^builtin.zlib@1.2.8%clang@7.0.2-apple+pic arch=darwin-elcapitan-x86_64
+
+.. warning::
+
+   You *can* use a fully qualified package name in a ``depends_on``
+   directive in a ``package.py`` file, like so::
+
+       depends_on('proto.hdf5')
+
+   This is *not* recommended, as it makes it very difficult for
+   multiple repos to be composed and shared.  A ``package.py`` like this
+   will fail if the ``proto`` repository is not registered in
+   ``repos.yaml``.
+
+.. _cmd-spack-repo:
+
+--------------------------
+``spack repo``
+--------------------------
+
+Spack's :ref:`configuration system <configuration>` allows repository
+settings to come from ``repos.yaml`` files in many locations.  If you
+want to see the repositories registered as a result of all configuration
+files, use ``spack repo list``.
+
+^^^^^^^^^^^^^^^^^^^
+``spack repo list``
+^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: console
+
+  $ spack repo list
+  ==> 2 package repositories.
+  myrepo     ~/myrepo
+  builtin    ~/spack/var/spack/repos/builtin
+
+Each repository is listed with its associated namespace.  To get the raw,
+merged YAML from all configuration files, use ``spack config get repos``:
+
+.. code-block:: console
+
+   $ spack config get repos
+   repos:srepos:
+   - ~/myrepo
+   - $spack/var/spack/repos/builtin
+
+mNote that, unlike ``spack repo list``, this does not include the
+namespace, which is read from each repo's ``repo.yaml``.
+
+^^^^^^^^^^^^^^^^^^^^^
+``spack repo create``
+^^^^^^^^^^^^^^^^^^^^^
+
+To make your own repository, you don't need to construct a directory
+yourself; you can use the ``spack repo create`` command.
+
+.. code-block:: console
+
+  $ spack repo create myrepo
+  ==> Created repo with namespace 'myrepo'.
+  ==> To register it with spack, run this command:
+    spack repo add ~/myrepo
+
+  $ ls myrepo
+  packages/  repo.yaml
+
+  $ cat myrepo/repo.yaml
+  repo:
+    namespace: 'myrepo'
+
+By default, the namespace of a new repo matches its directory's name.
+You can supply a custom namespace with a second argument, e.g.:
+
+.. code-block:: console
+
+  $ spack repo create myrepo llnl.comp
+  ==> Created repo with namespace 'llnl.comp'.
+  ==> To register it with spack, run this command:
+    spack repo add ~/myrepo
+
+  $ cat myrepo/repo.yaml
+  repo:
+    namespace: 'llnl.comp'
+
+^^^^^^^^^^^^^^^^^^
+``spack repo add``
+^^^^^^^^^^^^^^^^^^
+
+Once your repository is created, you can register it with Spack with
+``spack repo add``:
+
+.. code-block:: console
+
+   $ spack repo add ./myrepo
+   ==> Added repo with namespace 'llnl.comp'.
+
+   $ spack repo list
+   ==> 2 package repositories.
+   llnl.comp    ~/myrepo
+   builtin      ~/spack/var/spack/repos/builtin
+
+This simply adds the repo to your ``repos.yaml`` file.
+
+Once a repository is registered like this, you should be able to see its
+packages' names in the output of ``spack list``, and you should be able
+to build them using ``spack install <name>`` as you would with any
+built-in package.
+
+^^^^^^^^^^^^^^^^^^^^^
+``spack repo remove``
+^^^^^^^^^^^^^^^^^^^^^
+
+You can remove an already-registered repository with ``spack repo rm``.
+This will work whether you pass the repository's namespace *or* its
+path.
+
+By namespace:
+
+.. code-block:: console
+
+  $ spack repo rm llnl.comp
+  ==> Removed repository ~/myrepo with namespace 'llnl.comp'.
+
+  $ spack repo list
+  ==> 1 package repository.
+  builtin    ~/spack/var/spack/repos/builtin
+
+By path:
+
+.. code-block:: console
+
+  $ spack repo rm ~/myrepo
+  ==> Removed repository ~/myrepo
+
+  $ spack repo list
+  ==> 1 package repository.
+  builtin    ~/spack/var/spack/repos/builtin
+
+--------------------------------
+Repo namespaces and Python
+--------------------------------
+
+You may have noticed that namespace notation for repositories is similar
+to the notation for namespaces in Python.  As it turns out, you *can*
+treat Spack repositories like Python packages; this is how they are
+implemented.
+
+You could, for example, extend a ``builtin`` package in your own
+repository:
+
+.. code-block:: python
+
+   from spack.pkg.builtin.mpich import Mpich
+
+   class MyPackage(Mpich):
+       ...
+
+Spack repo namespaces are actually Python namespaces tacked on under
+``spack.pkg``.  The search semantics of ``repos.yaml`` are actually
+implemented using Python's built-in `sys.path
+<https://docs.python.org/2/library/sys.html#sys.path>`_ search.  The
+:py:mod:`spack.repository` module implements a custom `Python importer
+<https://docs.python.org/2/library/imp.html>`_.
+
+.. warning::
+
+   The mechanism for extending packages is not yet extensively tested,
+   and extending packages across repositories imposes inter-repo
+   dependencies, which may be hard to manage.  Use this feature at your
+   own risk, but let us know if you have a use case for it.

lib/spack/docs/site_configuration.rst

@@ -1,329 +0,0 @@
-.. _site-configuration:
-
-Site-specific configuration
-===================================
-
-.. _mirrors:
-
-Mirrors
-----------------------------
-
-Some sites may not have access to the internet for fetching packages.
-These sites will need a local repository of tarballs from which they
-can get their files.  Spack has support for this with *mirrors*.  A
-mirror is a URL that points to a directory, either on the local
-filesystem or on some server, containing tarballs for all of Spack's
-packages.
-
-Here's an example of a mirror's directory structure::
-
-    mirror/
-        cmake/
-            cmake-2.8.10.2.tar.gz
-        dyninst/
-            DyninstAPI-8.1.1.tgz
-            DyninstAPI-8.1.2.tgz
-        libdwarf/
-            libdwarf-20130126.tar.gz
-            libdwarf-20130207.tar.gz
-            libdwarf-20130729.tar.gz
-        libelf/
-            libelf-0.8.12.tar.gz
-            libelf-0.8.13.tar.gz
-        libunwind/
-            libunwind-1.1.tar.gz
-        mpich/
-            mpich-3.0.4.tar.gz
-        mvapich2/
-        mvapich2-1.9.tgz
-
-The structure is very simple.  There is a top-level directory.  The
-second level directories are named after packages, and the third level
-contains tarballs for each package, named as they were in the
-package's fetch URL.
-
-``spack mirror``
-~~~~~~~~~~~~~~~~~~~~~~~
-
-Mirrors are managed with the ``spack mirror`` command.  The help for
-``spack mirror`` looks like this::
-
-    $ spack mirror -h
-    usage: spack mirror [-h] SUBCOMMAND ...
-
-    positional arguments:
-      SUBCOMMAND
-        create           Create a directory to be used as a spack mirror, and fill
-                         it with package archives.
-        add              Add a mirror to Spack.
-        remove           Remove a mirror by name.
-        list             Print out available mirrors to the console.
-
-    optional arguments:
-      -h, --help         show this help message and exit
-
-The ``create`` command actually builds a mirror by fetching all of its
-packages from the internet and checksumming them.
-
-The other three commands are for managing mirror configuration.  They
-control the URL(s) from which Spack downloads its packages.
-
-
-``spack mirror create``
-~~~~~~~~~~~~~~~~~~~~~~~
-
-You can create a mirror using the ``spack mirror create`` command, assuming
-you're on a machine where you can access the internet.
-
-The command will iterate through all of Spack's packages and download
-the safe ones into a directory structure like the one above.  Here is
-what it looks like:
-
-
-.. code-block:: bash
-
-   $ spack mirror create libelf libdwarf
-   ==> Created new mirror in spack-mirror-2014-06-24
-   ==> Trying to fetch from http://www.mr511.de/software/libelf-0.8.13.tar.gz
-   ##########################################################                81.6%
-   ==> Checksum passed for libelf@0.8.13
-   ==> Added spack-mirror-2014-06-24/libelf/libelf-0.8.13.tar.gz to mirror
-   ==> Trying to fetch from http://www.mr511.de/software/libelf-0.8.12.tar.gz
-   ######################################################################    98.6%
-   ==> Checksum passed for libelf@0.8.12
-   ==> Added spack-mirror-2014-06-24/libelf/libelf-0.8.12.tar.gz to mirror
-   ==> Trying to fetch from http://www.prevanders.net/libdwarf-20130207.tar.gz
-   ######################################################################    97.3%
-   ==> Checksum passed for libdwarf@20130207
-   ==> Added spack-mirror-2014-06-24/libdwarf/libdwarf-20130207.tar.gz to mirror
-   ==> Trying to fetch from http://www.prevanders.net/libdwarf-20130126.tar.gz
-   ########################################################                  78.9%
-   ==> Checksum passed for libdwarf@20130126
-   ==> Added spack-mirror-2014-06-24/libdwarf/libdwarf-20130126.tar.gz to mirror
-   ==> Trying to fetch from http://www.prevanders.net/libdwarf-20130729.tar.gz
-   #############################################################             84.7%
-   ==> Checksum passed for libdwarf@20130729
-   ==> Added spack-mirror-2014-06-24/libdwarf/libdwarf-20130729.tar.gz to mirror
-
-Once this is done, you can tar up the ``spack-mirror-2014-06-24`` directory and
-copy it over to the machine you want it hosted on.
-
-Custom package sets
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Normally, ``spack mirror create`` downloads all the archives it has
-checksums for.  If you want to only create a mirror for a subset of
-packages, you can do that by supplying a list of package specs on the
-command line after ``spack mirror create``.  For example, this
-command::
-
-    $ spack mirror create libelf@0.8.12: boost@1.44:
-
-Will create a mirror for libelf versions greater than or equal to
-0.8.12 and boost versions greater than or equal to 1.44.
-
-Mirror files
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you have a *very* large number of packages you want to mirror, you
-can supply a file with specs in it, one per line::
-
-   $ cat specs.txt
-   libdwarf
-   libelf@0.8.12:
-   boost@1.44:
-   boost@1.39.0
-   ...
-   $ spack mirror create -f specs.txt
-   ...
-
-This is useful if there is a specific suite of software managed by
-your site.
-
-
-``spack mirror add``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Once you have a mirrror, you need to let spack know about it.  This is
-relatively simple.  First, figure out the URL for the mirror.  If it's
-a file, you can use a file URL like this one::
-
-    file:///Users/gamblin2/spack-mirror-2014-06-24
-
-That points to the directory on the local filesystem.  If it were on a
-web server, you could use a URL like this one:
-
-    https://example.com/some/web-hosted/directory/spack-mirror-2014-06-24
-
-Spack will use the URL as the root for all of the packages it fetches.
-You can tell your Spack installation to use that mirror like this:
-
-.. code-block:: bash
-
-   $ spack mirror add local_filesystem file:///Users/gamblin2/spack-mirror-2014-06-24
-
-Each mirror has a name so that you can refer to it again later.
-
-``spack mirror list``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you want to see all the mirrors Spack knows about you can run ``spack mirror list``::
-
-   $ spack mirror list
-   local_filesystem    file:///Users/gamblin2/spack-mirror-2014-06-24
-
-``spack mirror remove``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-And, if you want to remove a mirror, just remove it by name::
-
-   $ spack mirror remove local_filesystem
-   $ spack mirror list
-   ==> No mirrors configured.
-
-Mirror precedence
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Adding a mirror really just adds a section in ``~/.spackconfig``::
-
-   [mirror "local_filesystem"]
-       url = file:///Users/gamblin2/spack-mirror-2014-06-24
-   [mirror "remote_server"]
-       url = https://example.com/some/web-hosted/directory/spack-mirror-2014-06-24
-
-If you want to change the order in which mirrors are searched for
-packages, you can edit this file and reorder the sections.  Spack will
-search the topmost mirror first and the bottom-most mirror last.
-
-
-.. _temp-space:
-
-Temporary space
-----------------------------
-
-.. warning:: Temporary space configuration will be moved to configuration files.
-   The intructions here are old and refer to ``__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.
-
-
-.. _concretization-policies:
-
-Concretization policies
-----------------------------
-
-When a user asks for a package like ``mpileaks`` to be installed,
-Spack has to make decisions like what version should be installed,
-what compiler to use, and how its dependencies should be configured.
-This process is called *concretization*, and it's covered in detail in
-:ref:`its own section <abstract-and-concrete>`.
-
-The default concretization policies are in the
-:py:mod:`spack.concretize` module, specifically in the
-:py:class:`spack.concretize.DefaultConcretizer` class.  These are the
-important methods used in the concretization process:
-
-* :py:meth:`concretize_version(self, spec) <spack.concretize.DefaultConcretizer.concretize_version>`
-* :py:meth:`concretize_architecture(self, spec) <spack.concretize.DefaultConcretizer.concretize_architecture>`
-* :py:meth:`concretize_compiler(self, spec) <spack.concretize.DefaultConcretizer.concretize_compiler>`
-* :py:meth:`choose_provider(self, spec, providers) <spack.concretize.DefaultConcretizer.choose_provider>`
-
-The first three take a :py:class:`Spec <spack.spec.Spec>` object and
-modify it by adding constraints for the version.  For example, if the
-input spec had a version range like `1.0:5.0.3`, then the
-``concretize_version`` method should set the spec's version to a
-*single* version in that range.  Likewise, ``concretize_architecture``
-selects an architecture when the input spec does not have one, and
-``concretize_compiler`` needs to set both a concrete compiler and a
-concrete compiler version.
-
-``choose_provider()`` affects how concrete implementations are chosen
-based on a virtual dependency spec.  The input spec is some virtual
-dependency and the ``providers`` index is a :py:class:`ProviderIndex
-<spack.packages.ProviderIndex>` object.  The ``ProviderIndex`` maps
-the virtual spec to specs for possible implementations, and
-``choose_provider()`` should simply choose one of these.  The
-``concretize_*`` methods will be called on the chosen implementation
-later, so there is no need to fully concretize the spec when returning
-it.
-
-The ``DefaultConcretizer`` is intendend to provide sensible defaults
-for each policy, but there are certain choices that it can't know
-about.  For example, one site might prefer ``OpenMPI`` over ``MPICH``,
-or another might prefer an old version of some packages.  These types
-of special cases can be integrated with custom concretizers.
-
-Writing a custom concretizer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To write your own concretizer, you need only subclass
-``DefaultConcretizer`` and override the methods you want to change.
-For example, you might write a class like this to change *only* the
-``concretize_version()`` behavior:
-
-.. code-block:: python
-
-   from spack.concretize import DefaultConcretizer
-
-   class MyConcretizer(DefaultConcretizer):
-       def concretize_version(self, spec):
-           # implement custom logic here.
-
-Once you have written your custom concretizer, you can make Spack use
-it by editing ``globals.py``.  Find this part of the file:
-
-.. code-block:: python
-
-   #
-   # This controls how things are concretized in spack.
-   # Replace it with a subclass if you want different
-   # policies.
-   #
-   concretizer = DefaultConcretizer()
-
-Set concretizer to *your own* class instead of the default:
-
-.. code-block:: python
-
-   concretizer = MyConcretizer()
-
-The next time you run Spack, your changes should take effect.

lib/spack/docs/tutorial/examples/0.package.py

@@ -0,0 +1,63 @@
+##############################################################################
+# Copyright (c) 2013-2016, Lawrence Livermore National Security, LLC.
+# Produced at the Lawrence Livermore National Laboratory.
+#
+# This file is part of Spack.
+# Created by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
+# LLNL-CODE-647188
+#
+# For details, see https://github.com/llnl/spack
+# Please also see the LICENSE file for our notice and the LGPL.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License (as
+# published by the Free Software Foundation) version 2.1, February 1999.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
+# conditions of the GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+##############################################################################
+#
+# This is a template package file for Spack.  We've put "FIXME"
+# next to all the things you'll want to change. Once you've handled
+# them, you can save this file and test your package like this:
+#
+#     spack install mpileaks
+#
+# You can edit this file again by typing:
+#
+#     spack edit mpileaks
+#
+# See the Spack documentation for more information on packaging.
+# If you submit this package back to Spack as a pull request,
+# please first remove this boilerplate and all FIXME comments.
+#
+from spack import *
+
+
+class Mpileaks(AutotoolsPackage):
+    """FIXME: Put a proper description of your package here."""
+
+    # FIXME: Add a proper url for your package's homepage here.
+    homepage = "http://www.example.com"
+    url      = "https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
+
+    version('1.0', '8838c574b39202a57d7c2d68692718aa')
+
+    # FIXME: Add dependencies if required.
+    # depends_on('m4', type='build')
+    # depends_on('autoconf', type='build')
+    # depends_on('automake', type='build')
+    # depends_on('libtool', type='build')
+    # depends_on('foo')
+
+    def configure_args(self):
+        # FIXME: Add arguments other than --prefix
+        # FIXME: If not needed delete the function
+        args = []
+        return args

lib/spack/docs/tutorial/examples/1.package.py

@@ -0,0 +1,48 @@
+##############################################################################
+# Copyright (c) 2013-2016, Lawrence Livermore National Security, LLC.
+# Produced at the Lawrence Livermore National Laboratory.
+#
+# This file is part of Spack.
+# Created by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
+# LLNL-CODE-647188
+#
+# For details, see https://github.com/llnl/spack
+# Please also see the LICENSE file for our notice and the LGPL.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License (as
+# published by the Free Software Foundation) version 2.1, February 1999.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
+# conditions of the GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+##############################################################################
+from spack import *
+
+
+class Mpileaks(AutotoolsPackage):
+    """Tool to detect and report MPI objects like MPI_Requests and
+    MPI_Datatypes."""
+
+    homepage = "https://github.com/hpc/mpileaks"
+    url      = "https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
+
+    version('1.0', '8838c574b39202a57d7c2d68692718aa')
+
+    # FIXME: Add dependencies if required.
+    # depends_on('m4', type='build')
+    # depends_on('autoconf', type='build')
+    # depends_on('automake', type='build')
+    # depends_on('libtool', type='build')
+    # depends_on('foo')
+
+    def configure_args(self):
+        # FIXME: Add arguments other than --prefix
+        # FIXME: If not needed delete the function
+        args = []
+        return args

lib/spack/docs/tutorial/examples/2.package.py

@@ -0,0 +1,45 @@
+##############################################################################
+# Copyright (c) 2013-2016, Lawrence Livermore National Security, LLC.
+# Produced at the Lawrence Livermore National Laboratory.
+#
+# This file is part of Spack.
+# Created by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
+# LLNL-CODE-647188
+#
+# For details, see https://github.com/llnl/spack
+# Please also see the LICENSE file for our notice and the LGPL.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License (as
+# published by the Free Software Foundation) version 2.1, February 1999.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
+# conditions of the GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+##############################################################################
+from spack import *
+
+
+class Mpileaks(AutotoolsPackage):
+    """Tool to detect and report MPI objects like MPI_Requests and
+    MPI_Datatypes."""
+
+    homepage = "https://github.com/hpc/mpileaks"
+    url      = "https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
+
+    version('1.0', '8838c574b39202a57d7c2d68692718aa')
+
+    depends_on('mpi')
+    depends_on('adept-utils')
+    depends_on('callpath')
+
+    def configure_args(self):
+        # FIXME: Add arguments other than --prefix
+        # FIXME: If not needed delete the function
+        args = []
+        return args

lib/spack/docs/tutorial/examples/3.package.py

@@ -0,0 +1,43 @@
+##############################################################################
+# Copyright (c) 2013-2016, Lawrence Livermore National Security, LLC.
+# Produced at the Lawrence Livermore National Laboratory.
+#
+# This file is part of Spack.
+# Created by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
+# LLNL-CODE-647188
+#
+# For details, see https://github.com/llnl/spack
+# Please also see the LICENSE file for our notice and the LGPL.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License (as
+# published by the Free Software Foundation) version 2.1, February 1999.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
+# conditions of the GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+##############################################################################
+from spack import *
+
+
+class Mpileaks(AutotoolsPackage):
+    """Tool to detect and report MPI objects like MPI_Requests and
+    MPI_Datatypes."""
+    homepage = "https://github.com/hpc/mpileaks"
+    url      = "https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
+
+    version('1.0', '8838c574b39202a57d7c2d68692718aa')
+
+    depends_on('mpi')
+    depends_on('adept-utils')
+    depends_on('callpath')
+
+    def configure_args(self):
+        args = ['--with-adept-utils=%s' % self.spec['adept-utils'].prefix,
+                '--with-callpath=%s' % self.spec['callpath'].prefix]
+        return args

lib/spack/docs/tutorial/examples/4.package.py

@@ -0,0 +1,50 @@
+##############################################################################
+# Copyright (c) 2013-2016, Lawrence Livermore National Security, LLC.
+# Produced at the Lawrence Livermore National Laboratory.
+#
+# This file is part of Spack.
+# Created by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
+# LLNL-CODE-647188
+#
+# For details, see https://github.com/llnl/spack
+# Please also see the LICENSE file for our notice and the LGPL.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License (as
+# published by the Free Software Foundation) version 2.1, February 1999.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
+# conditions of the GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+##############################################################################
+from spack import *
+
+
+class Mpileaks(AutotoolsPackage):
+    """Tool to detect and report MPI objects like MPI_Requests and
+    MPI_Datatypes."""
+
+    homepage = "https://github.com/hpc/mpileaks"
+    url      = "https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
+
+    version('1.0', '8838c574b39202a57d7c2d68692718aa')
+
+    variant('stackstart', default=0, description='Specify the number of stack frames to truncate.')
+
+    depends_on('mpi')
+    depends_on('adept-utils')
+    depends_on('callpath')
+
+    def configure_args(self):
+        args = ['--with-adept-utils=%s' % self.spec['adept-utils'].prefix,
+                '--with-callpath=%s' % self.spec['callpath'].prefix]
+        stackstart = int(self.spec.variants['stackstart'].value)
+        if stackstart:
+            args.extend(['--with-stack-start-c=%s' % stackstart,
+                         '--with-stack-start-fortran=%s' % stackstart])
+        return args

lib/spack/docs/tutorial_sc16.rst

@@ -0,0 +1,48 @@
+.. _spack-101:
+
+=============================
+Tutorial: Spack 101
+=============================
+
+This is a 3-hour introduction to Spack with lectures and live demos.  It
+was presented as a tutorial at `Supercomputing 2016
+<http://sc16.supercomputing.org>`_.  You can use these materials to teach
+a course on Spack at your own site, or you can just skip ahead and read
+the live demo scripts to see how Spack is used in practice.
+
+.. _sc16-slides:
+
+.. rubric:: Slides
+
+.. figure:: tutorial/sc16-tutorial-slide-preview.png
+   :target: http://llnl.github.io/spack/files/Spack-SC16-Tutorial.pdf
+   :height: 72px
+   :align: left
+   :alt: Slide Preview
+
+`Download Slides <http://llnl.github.io/spack/files/Spack-SC16-Tutorial.pdf>`_.
+
+**Full citation:** Todd Gamblin, Massimiliano Culpo, Gregory Becker, Matt
+Legendre, Greg Lee, Elizabeth Fischer, and Benedikt Hegner.
+`Managing HPC Software Complexity with Spack
+<http://sc16.supercomputing.org/presentation/?id=tut166&sess=sess209>`_.
+Tutorial presented at Supercomputing 2016. November 13, 2016, Salt Lake
+City, UT, USA.
+
+.. _sc16-live-demos:
+
+.. rubric:: Live Demos
+
+These scripts will take you step-by-step through basic Spack tasks.  They
+correspond to sections in the slides above.
+
+  1. :ref:`basics-tutorial`
+  2. :ref:`packaging-tutorial`
+  3. :ref:`modules-tutorial`
+
+Full contents:
+
+.. toctree::
+   tutorial_sc16_spack_basics
+   tutorial_sc16_packaging
+   tutorial_sc16_modules

lib/spack/docs/tutorial_sc16_modules.rst

@@ -0,0 +1,982 @@
+.. _modules-tutorial:
+
+=============================
+Module Configuration Tutorial
+=============================
+
+This tutorial will guide you through the customization of both
+content and naming of module files generated by Spack.
+
+Starting from the default Spack settings you will add an increasing
+number of directives to the ``modules.yaml`` configuration file to
+satisfy a number of constraints that mimic those that you may encounter
+in a typical production environment at HPC sites.
+
+Even though the focus will be for the most part on customizing
+TCL non-hierarchical module files, everything
+you'll see applies also to other kinds of module files generated by Spack.
+
+The generation of Lua hierarchical
+module files will be addressed at the end of the tutorial,
+and you'll see that with minor modifications
+to an existing ``modules.yaml`` written for TCL
+non-hierarchical  modules you'll get almost
+for free the possibility to try a hierarchical layout.
+
+Let's start!
+
+.. _module_file_tutorial_prerequisites:
+
+-------------
+Prerequisites
+-------------
+
+Before proceeding further ensure:
+
+- you have LMod or Environment Modules available
+- have :ref:`shell support <shell-support>` activated in Spack
+
+If you need to install Lmod or Environment module you can refer
+to the documentation :ref:`here <InstallEnvironmentModules>`.
+
+
+^^^^^^^^^^^^^^^^^^
+Add a new compiler
+^^^^^^^^^^^^^^^^^^
+
+Spack automatically scans the environment to search for available
+compilers on first use. On a Ubuntu 14.04 a fresh clone will show
+something like this:
+
+.. code-block:: console
+
+  $ uname -a
+  Linux nuvolari 4.4.0-45-generic #66~14.04.1-Ubuntu SMP Wed Oct 19 15:05:38 UTC 2016 x86_64 x86_64 x86_64 GNU/Linux
+
+  $ spack compilers
+  ==> Available compilers
+  -- gcc ----------------------------------------------------------
+  gcc@4.8
+
+For the purpose of building a limited set of packages with some features
+that will help showcasing the capabilities of
+module customization the first thing we need is to build a new compiler:
+
+.. code-block:: console
+
+  $ spack install gcc@6.2.0
+  # ...
+  # Wait a long time
+  # ...
+
+Then we can use shell support for modules to add it to the list of known compilers:
+
+.. code-block:: console
+
+  # The name of the generated module may vary
+  $ module load gcc-6.2.0-gcc-4.8-twd5nqg
+
+  $ spack compiler add
+  ==> Added 1 new compiler to ~/.spack/linux/compilers.yaml
+      gcc@6.2.0
+
+  $ spack compilers
+  ==> Available compilers
+  -- gcc ----------------------------------------------------------
+  gcc@6.2.0  gcc@4.8
+
+Note that the final 7 digits hash at the end of the generated module may vary depending
+on architecture or package version.
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Build software that will be used in the tutorial
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Next you should install a few modules that will be used in the tutorial:
+
+.. code-block:: console
+
+  $ spack install netlib-scalapack ^openmpi ^openblas
+  # ...
+
+The packages you need to install are:
+
+- ``netlib-scalapack ^openmpi ^openblas``
+- ``netlib-scalapack ^mpich ^openblas``
+- ``netlib-scalapack ^openmpi ^netlib-lapack``
+- ``netlib-scalapack ^mpich ^netlib-lapack``
+- ``py-scipy ^openblas``
+
+In the end your environment should look something like:
+
+.. code-block:: console
+
+  $ module avail
+
+  ------------------------------------------------------------------------ ~/spack/share/spack/modules/linux-Ubuntu14-x86_64 ------------------------------------------------------------------------
+     binutils-2.27-gcc-4.8-dz3xevw         libpciaccess-0.13.4-gcc-6.2.0-eo2siet      lzo-2.09-gcc-6.2.0-jcngz72                  netlib-scalapack-2.0.2-gcc-6.2.0-wnimqhw    python-2.7.12-gcc-6.2.0-qu7rc5p
+     bzip2-1.0.6-gcc-6.2.0-csoc2mq         libsigsegv-2.10-gcc-4.8-avb6azw            m4-1.4.17-gcc-4.8-iggewke                   netlib-scalapack-2.0.2-gcc-6.2.0-wojunhq    sqlite-3.8.5-gcc-6.2.0-td3zfe7
+     cmake-3.5.2-gcc-6.2.0-6poypqg         libsigsegv-2.10-gcc-6.2.0-g3qpmbi          m4-1.4.17-gcc-6.2.0-lhgqa6s                 nettle-3.2-gcc-6.2.0-djdthlh                tcl-8.6.5-gcc-4.8-atddxu7
+     curl-7.50.3-gcc-6.2.0-2ffacqm         libtool-2.4.6-gcc-6.2.0-kiepac6            mpc-1.0.3-gcc-4.8-lylv7lk                   openblas-0.2.19-gcc-6.2.0-js33umc           util-macros-1.19.0-gcc-6.2.0-uoukuqk
+     expat-2.2.0-gcc-6.2.0-bxqnjar         libxml2-2.9.4-gcc-6.2.0-3k4ykbe            mpfr-3.1.4-gcc-4.8-bldfx3w                  openmpi-2.0.1-gcc-6.2.0-s3qbtby             xz-5.2.2-gcc-6.2.0-t5lk6in
+     gcc-6.2.0-gcc-4.8-twd5nqg             lmod-6.4.5-gcc-4.8-7v7bh7b                 mpich-3.2-gcc-6.2.0-5n5xoep                 openssl-1.0.2j-gcc-6.2.0-hibnfda            zlib-1.2.8-gcc-4.8-bds4ies
+     gmp-6.1.1-gcc-4.8-uq52e2n             lua-5.3.2-gcc-4.8-xozf2hx                  ncurses-6.0-gcc-4.8-u62fit4                 pkg-config-0.29.1-gcc-6.2.0-rslsgcs         zlib-1.2.8-gcc-6.2.0-asydrba
+     gmp-6.1.1-gcc-6.2.0-3cfh3hi           lua-luafilesystem-1_6_3-gcc-4.8-sbzejlz    ncurses-6.0-gcc-6.2.0-7tb426s               py-nose-1.3.7-gcc-6.2.0-4gl5c42
+     hwloc-1.11.4-gcc-6.2.0-3ostwel        lua-luaposix-33.4.0-gcc-4.8-xf7y2p5        netlib-lapack-3.6.1-gcc-6.2.0-mirer2l       py-numpy-1.11.1-gcc-6.2.0-i3rpk4e
+     isl-0.14-gcc-4.8-cq73t5m              lz4-131-gcc-6.2.0-cagoem4                  netlib-scalapack-2.0.2-gcc-6.2.0-6bqlxqy    py-scipy-0.18.1-gcc-6.2.0-e6uljfi
+     libarchive-3.2.1-gcc-6.2.0-2b54aos    lzma-4.32.7-gcc-6.2.0-sfmeynw              netlib-scalapack-2.0.2-gcc-6.2.0-hpqb3dp    py-setuptools-25.2.0-gcc-6.2.0-hkqauaa
+
+------------------------------------------------
+Filter unwanted modifications to the environment
+------------------------------------------------
+
+The non-hierarchical TCL module files that have been generated so far
+follow the default rules for module generation, which are given
+:ref:`here <modules-yaml>` in the reference part of the manual. Taking a
+look at the ``gcc`` module you'll see something like:
+
+.. code-block:: console
+
+  $ module show gcc-6.2.0-gcc-4.8-twd5nqg
+  ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+     ~/spack/share/spack/modules/linux-Ubuntu14-x86_64/gcc-6.2.0-gcc-4.8-twd5nqg:
+  ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+  whatis("gcc @6.2.0 ")
+  prepend_path("PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/bin")
+  prepend_path("CMAKE_PREFIX_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/")
+  prepend_path("MANPATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/share/man")
+  prepend_path("PKG_CONFIG_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64/pkgconfig")
+  prepend_path("LIBRARY_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64")
+  prepend_path("LD_LIBRARY_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64")
+  prepend_path("CPATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/include")
+  help([[The GNU Compiler Collection includes front ends for C, C++, Objective-C,
+  Fortran, and Java.
+  ]])
+
+As expected, a few environment variables representing paths will be modified
+by the modules according to the default prefix inspection rules.
+
+Consider now the case that your site has decided that e.g. ``CPATH`` and
+``LIBRARY_PATH`` modifications should not be present in module files. What you can
+do to abide by the rules is to create a configuration file ``~/.spack/modules.yaml``
+with the following content:
+
+.. code-block:: yaml
+
+  modules:
+    tcl:
+      all:
+        filter:
+          environment_blacklist: ['CPATH', 'LIBRARY_PATH']
+
+Next you should regenerate all the module files:
+
+.. code-block:: console
+
+  $ spack module refresh --module-type tcl
+  ==> You are about to regenerate tcl module files for:
+
+  -- linux-Ubuntu14-x86_64 / gcc@4.8 ------------------------------
+  dz3xevw binutils@2.27  uq52e2n gmp@6.1.1  avb6azw libsigsegv@2.10  xozf2hx lua@5.3.2                xf7y2p5 lua-luaposix@33.4.0  lylv7lk mpc@1.0.3   u62fit4 ncurses@6.0  bds4ies zlib@1.2.8
+  twd5nqg gcc@6.2.0      cq73t5m isl@0.14   7v7bh7b lmod@6.4.5       sbzejlz lua-luafilesystem@1_6_3  iggewke m4@1.4.17            bldfx3w mpfr@3.1.4  atddxu7 tcl@8.6.5
+
+  ...
+
+  ==> Do you want to proceed ? [y/n]
+  y
+  ==> Regenerating tcl module files
+
+If you take a look now at the module for ``gcc`` you'll see that the unwanted
+paths have disappeared:
+
+.. code-block:: console
+
+  $ module show gcc-6.2.0-gcc-4.8-twd5nqg
+  ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+     ~/spack/share/spack/modules/linux-Ubuntu14-x86_64/gcc-6.2.0-gcc-4.8-twd5nqg:
+  ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+  whatis("gcc @6.2.0 ")
+  prepend_path("PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/bin")
+  prepend_path("CMAKE_PREFIX_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/")
+  prepend_path("MANPATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/share/man")
+  prepend_path("PKG_CONFIG_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64/pkgconfig")
+  prepend_path("LD_LIBRARY_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64")
+  help([[The GNU Compiler Collection includes front ends for C, C++, Objective-C,
+  Fortran, and Java.
+  ]])
+
+----------------------------------------------
+Prevent some module files from being generated
+----------------------------------------------
+
+Another common request at many sites is to avoid exposing software that
+is only needed as an intermediate step when building a newer stack.
+Let's try to prevent the generation of
+module files for anything that is compiled with ``gcc@4.8`` (the OS provided compiler).
+
+To do this you should add a ``blacklist`` keyword to the configuration file:
+
+.. code-block:: yaml
+  :emphasize-lines: 3,4
+
+  modules:
+    tcl:
+      blacklist:
+        -  '%gcc@4.8'
+      all:
+        filter:
+          environment_blacklist: ['CPATH', 'LIBRARY_PATH']
+
+and regenerate the module files:
+
+.. code-block:: console
+
+  $ spack module refresh --module-type tcl --delete-tree
+  ==> You are about to regenerate tcl module files for:
+
+  -- linux-Ubuntu14-x86_64 / gcc@4.8 ------------------------------
+  dz3xevw binutils@2.27  uq52e2n gmp@6.1.1  avb6azw libsigsegv@2.10  xozf2hx lua@5.3.2                xf7y2p5 lua-luaposix@33.4.0  lylv7lk mpc@1.0.3   u62fit4 ncurses@6.0  bds4ies zlib@1.2.8
+  twd5nqg gcc@6.2.0      cq73t5m isl@0.14   7v7bh7b lmod@6.4.5       sbzejlz lua-luafilesystem@1_6_3  iggewke m4@1.4.17            bldfx3w mpfr@3.1.4  atddxu7 tcl@8.6.5
+
+  -- linux-Ubuntu14-x86_64 / gcc@6.2.0 ----------------------------
+  csoc2mq bzip2@1.0.6   2b54aos libarchive@3.2.1     sfmeynw lzma@4.32.7          wnimqhw netlib-scalapack@2.0.2  s3qbtby openmpi@2.0.1      hkqauaa py-setuptools@25.2.0
+  6poypqg cmake@3.5.2   eo2siet libpciaccess@0.13.4  jcngz72 lzo@2.09             6bqlxqy netlib-scalapack@2.0.2  hibnfda openssl@1.0.2j     qu7rc5p python@2.7.12
+  2ffacqm curl@7.50.3   g3qpmbi libsigsegv@2.10      lhgqa6s m4@1.4.17            wojunhq netlib-scalapack@2.0.2  rslsgcs pkg-config@0.29.1  td3zfe7 sqlite@3.8.5
+  bxqnjar expat@2.2.0   kiepac6 libtool@2.4.6        5n5xoep mpich@3.2            hpqb3dp netlib-scalapack@2.0.2  4gl5c42 py-nose@1.3.7      uoukuqk util-macros@1.19.0
+  3cfh3hi gmp@6.1.1     3k4ykbe libxml2@2.9.4        7tb426s ncurses@6.0          djdthlh nettle@3.2              i3rpk4e py-numpy@1.11.1    t5lk6in xz@5.2.2
+  3ostwel hwloc@1.11.4  cagoem4 lz4@131              mirer2l netlib-lapack@3.6.1  js33umc openblas@0.2.19         e6uljfi py-scipy@0.18.1    asydrba zlib@1.2.8
+
+  ==> Do you want to proceed ? [y/n]
+  y
+
+  $ module avail
+
+  ------------------------------------------------------------------------ ~/spack/share/spack/modules/linux-Ubuntu14-x86_64 ------------------------------------------------------------------------
+     bzip2-1.0.6-gcc-6.2.0-csoc2mq            libsigsegv-2.10-gcc-6.2.0-g3qpmbi    ncurses-6.0-gcc-6.2.0-7tb426s               openmpi-2.0.1-gcc-6.2.0-s3qbtby           sqlite-3.8.5-gcc-6.2.0-td3zfe7
+     cmake-3.5.2-gcc-6.2.0-6poypqg            libtool-2.4.6-gcc-6.2.0-kiepac6      netlib-lapack-3.6.1-gcc-6.2.0-mirer2l       openssl-1.0.2j-gcc-6.2.0-hibnfda          util-macros-1.19.0-gcc-6.2.0-uoukuqk
+     curl-7.50.3-gcc-6.2.0-2ffacqm            libxml2-2.9.4-gcc-6.2.0-3k4ykbe      netlib-scalapack-2.0.2-gcc-6.2.0-6bqlxqy    pkg-config-0.29.1-gcc-6.2.0-rslsgcs       xz-5.2.2-gcc-6.2.0-t5lk6in
+     expat-2.2.0-gcc-6.2.0-bxqnjar            lz4-131-gcc-6.2.0-cagoem4            netlib-scalapack-2.0.2-gcc-6.2.0-hpqb3dp    py-nose-1.3.7-gcc-6.2.0-4gl5c42           zlib-1.2.8-gcc-6.2.0-asydrba
+     gmp-6.1.1-gcc-6.2.0-3cfh3hi              lzma-4.32.7-gcc-6.2.0-sfmeynw        netlib-scalapack-2.0.2-gcc-6.2.0-wnimqhw    py-numpy-1.11.1-gcc-6.2.0-i3rpk4e
+     hwloc-1.11.4-gcc-6.2.0-3ostwel           lzo-2.09-gcc-6.2.0-jcngz72           netlib-scalapack-2.0.2-gcc-6.2.0-wojunhq    py-scipy-0.18.1-gcc-6.2.0-e6uljfi
+     libarchive-3.2.1-gcc-6.2.0-2b54aos       m4-1.4.17-gcc-6.2.0-lhgqa6s          nettle-3.2-gcc-6.2.0-djdthlh                py-setuptools-25.2.0-gcc-6.2.0-hkqauaa
+     libpciaccess-0.13.4-gcc-6.2.0-eo2siet    mpich-3.2-gcc-6.2.0-5n5xoep          openblas-0.2.19-gcc-6.2.0-js33umc           python-2.7.12-gcc-6.2.0-qu7rc5p
+
+This time it is convenient to pass the option ``--delete-tree`` to the command that
+regenerates the module files to instruct it to delete the existing tree and regenerate
+a new one instead of overwriting the files in the existing directory.
+
+If you pay careful attention you'll see though that we went too far in blacklisting modules:
+the module for ``gcc@6.2.0`` disappeared as it was bootstrapped with ``gcc@4.8``. To specify
+exceptions to the blacklist rules you can use ``whitelist``:
+
+.. code-block:: yaml
+  :emphasize-lines: 3,4
+
+  modules:
+    tcl:
+      whitelist:
+        -  gcc
+      blacklist:
+        -  '%gcc@4.8'
+      all:
+        filter:
+          environment_blacklist: ['CPATH', 'LIBRARY_PATH']
+
+``whitelist`` rules always have precedence over ``blacklist`` rules. If you regenerate the modules again:
+
+.. code-block:: console
+
+  $ spack module refresh --module-type tcl -y
+
+you'll see that now the module for ``gcc@6.2.0`` has reappeared:
+
+.. code-block:: console
+
+  $ module avail gcc-6.2.0-gcc-4.8-twd5nqg
+
+  ------------------------------------------------------------------------ ~/spack/share/spack/modules/linux-Ubuntu14-x86_64 ------------------------------------------------------------------------
+     gcc-6.2.0-gcc-4.8-twd5nqg
+
+-------------------------
+Change module file naming
+-------------------------
+
+The next step in making  module files more user-friendly is to
+improve their naming scheme.
+To reduce the length of the hash or remove it altogether you can
+use the ``hash_length`` keyword in the configuration file:
+
+.. TODO: give reasons to remove hashes if they are not evident enough?
+
+.. code-block:: yaml
+  :emphasize-lines: 3
+
+  modules:
+    tcl:
+      hash_length: 0
+      whitelist:
+        -  gcc
+      blacklist:
+        -  '%gcc@4.8'
+      all:
+        filter:
+          environment_blacklist: ['CPATH', 'LIBRARY_PATH']
+
+If you try to regenerate the module files now you will get an error:
+
+.. code-block:: console
+
+  $ spack module refresh --module-type tcl --delete-tree -y
+  ==> Error: Name clashes detected in module files:
+
+  file : ~/spack/share/spack/modules/linux-Ubuntu14-x86_64/netlib-scalapack-2.0.2-gcc-6.2.0
+  spec : netlib-scalapack@2.0.2%gcc@6.2.0~fpic+shared arch=linux-Ubuntu14-x86_64
+  spec : netlib-scalapack@2.0.2%gcc@6.2.0~fpic+shared arch=linux-Ubuntu14-x86_64
+  spec : netlib-scalapack@2.0.2%gcc@6.2.0~fpic+shared arch=linux-Ubuntu14-x86_64
+  spec : netlib-scalapack@2.0.2%gcc@6.2.0~fpic+shared arch=linux-Ubuntu14-x86_64
+
+  ==> Error: Operation aborted
+
+.. note::
+  We try to check for errors upfront!
+   In Spack we check for errors upfront whenever possible, so don't worry about your module files:
+   as a name clash was detected nothing has been changed on disk.
+
+The problem here is that without
+the hashes the four different flavors of ``netlib-scalapack`` map to the same module file
+name. We have the possibility to add suffixes to differentiate them:
+
+.. code-block:: yaml
+ :emphasize-lines: 9-11,14-17
+
+  modules:
+    tcl:
+      hash_length: 0
+      whitelist:
+        -  gcc
+      blacklist:
+        -  '%gcc@4.8'
+      all:
+        suffixes:
+          '^openblas': openblas
+          '^netlib-lapack': netlib
+        filter:
+          environment_blacklist: ['CPATH', 'LIBRARY_PATH']
+      netlib-scalapack:
+        suffixes:
+          '^openmpi': openmpi
+          '^mpich': mpich
+
+As you can see it is possible to specify rules that applies only to a
+restricted set of packages using :ref:`anonymous specs <anonymous_specs>`.
+Regenerating module files now we obtain:
+
+.. code-block:: console
+
+  $ spack module refresh --module-type tcl --delete-tree -y
+  ==> Regenerating tcl module files
+  $ module avail
+
+  ------------------------------------------------------------------------ ~/spack/share/spack/modules/linux-Ubuntu14-x86_64 ------------------------------------------------------------------------
+     bzip2-1.0.6-gcc-6.2.0         libpciaccess-0.13.4-gcc-6.2.0    mpich-3.2-gcc-6.2.0                                  openblas-0.2.19-gcc-6.2.0             python-2.7.12-gcc-6.2.0
+     cmake-3.5.2-gcc-6.2.0         libsigsegv-2.10-gcc-6.2.0        ncurses-6.0-gcc-6.2.0                                openmpi-2.0.1-gcc-6.2.0               sqlite-3.8.5-gcc-6.2.0
+     curl-7.50.3-gcc-6.2.0         libtool-2.4.6-gcc-6.2.0          netlib-lapack-3.6.1-gcc-6.2.0                        openssl-1.0.2j-gcc-6.2.0              util-macros-1.19.0-gcc-6.2.0
+     expat-2.2.0-gcc-6.2.0         libxml2-2.9.4-gcc-6.2.0          netlib-scalapack-2.0.2-gcc-6.2.0-netlib-mpich        pkg-config-0.29.1-gcc-6.2.0           xz-5.2.2-gcc-6.2.0
+     gcc-6.2.0-gcc-4.8             lz4-131-gcc-6.2.0                netlib-scalapack-2.0.2-gcc-6.2.0-netlib-openmpi      py-nose-1.3.7-gcc-6.2.0               zlib-1.2.8-gcc-6.2.0
+     gmp-6.1.1-gcc-6.2.0           lzma-4.32.7-gcc-6.2.0            netlib-scalapack-2.0.2-gcc-6.2.0-openblas-mpich      py-numpy-1.11.1-gcc-6.2.0-openblas
+     hwloc-1.11.4-gcc-6.2.0        lzo-2.09-gcc-6.2.0               netlib-scalapack-2.0.2-gcc-6.2.0-openblas-openmpi    py-scipy-0.18.1-gcc-6.2.0-openblas
+     libarchive-3.2.1-gcc-6.2.0    m4-1.4.17-gcc-6.2.0              nettle-3.2-gcc-6.2.0                                 py-setuptools-25.2.0-gcc-6.2.0
+
+Finally we can set a ``naming_scheme`` to prevent users from loading
+modules that refer to different flavors of the same library/application:
+
+.. code-block:: yaml
+  :emphasize-lines: 4,10,11
+
+  modules:
+    tcl:
+      hash_length: 0
+      naming_scheme: '${PACKAGE}/${VERSION}-${COMPILERNAME}-${COMPILERVER}'
+      whitelist:
+        -  gcc
+      blacklist:
+        -  '%gcc@4.8'
+      all:
+        conflict:
+          - '${PACKAGE}'
+        suffixes:
+          '^openblas': openblas
+          '^netlib-lapack': netlib
+        filter:
+          environment_blacklist: ['CPATH', 'LIBRARY_PATH']
+      netlib-scalapack:
+        suffixes:
+          '^openmpi': openmpi
+          '^mpich': mpich
+
+The final result should look like:
+
+.. code-block:: console
+
+  $ module avail
+
+  ------------------------------------------------------------------------ ~/spack/share/spack/modules/linux-Ubuntu14-x86_64 ------------------------------------------------------------------------
+     bzip2/1.0.6-gcc-6.2.0         libpciaccess/0.13.4-gcc-6.2.0    mpich/3.2-gcc-6.2.0                                      openblas/0.2.19-gcc-6.2.0             python/2.7.12-gcc-6.2.0
+     cmake/3.5.2-gcc-6.2.0         libsigsegv/2.10-gcc-6.2.0        ncurses/6.0-gcc-6.2.0                                    openmpi/2.0.1-gcc-6.2.0               sqlite/3.8.5-gcc-6.2.0
+     curl/7.50.3-gcc-6.2.0         libtool/2.4.6-gcc-6.2.0          netlib-lapack/3.6.1-gcc-6.2.0                            openssl/1.0.2j-gcc-6.2.0              util-macros/1.19.0-gcc-6.2.0
+     expat/2.2.0-gcc-6.2.0         libxml2/2.9.4-gcc-6.2.0          netlib-scalapack/2.0.2-gcc-6.2.0-netlib-mpich            pkg-config/0.29.1-gcc-6.2.0           xz/5.2.2-gcc-6.2.0
+     gcc/6.2.0-gcc-4.8             lz4/131-gcc-6.2.0                netlib-scalapack/2.0.2-gcc-6.2.0-netlib-openmpi          py-nose/1.3.7-gcc-6.2.0               zlib/1.2.8-gcc-6.2.0
+     gmp/6.1.1-gcc-6.2.0           lzma/4.32.7-gcc-6.2.0            netlib-scalapack/2.0.2-gcc-6.2.0-openblas-mpich          py-numpy/1.11.1-gcc-6.2.0-openblas
+     hwloc/1.11.4-gcc-6.2.0        lzo/2.09-gcc-6.2.0               netlib-scalapack/2.0.2-gcc-6.2.0-openblas-openmpi (D)    py-scipy/0.18.1-gcc-6.2.0-openblas
+     libarchive/3.2.1-gcc-6.2.0    m4/1.4.17-gcc-6.2.0              nettle/3.2-gcc-6.2.0                                     py-setuptools/25.2.0-gcc-6.2.0
+
+.. note::
+  TCL specific directive
+    The directives ``naming_scheme`` and ``conflict`` are TCL specific and do not apply
+    to the ``dotkit`` or ``lmod`` sections in the configuration file.
+
+------------------------------------
+Add custom environment modifications
+------------------------------------
+
+At many sites it is customary to set an environment variable in a
+package's module file that points to the folder in which the package
+is installed. You can achieve this with Spack by adding an
+``environment`` directive to the configuration file:
+
+.. code-block:: yaml
+  :emphasize-lines: 17-19
+
+  modules:
+    tcl:
+      hash_length: 0
+      naming_scheme: '${PACKAGE}/${VERSION}-${COMPILERNAME}-${COMPILERVER}'
+      whitelist:
+        -  gcc
+      blacklist:
+        -  '%gcc@4.8'
+      all:
+        conflict:
+          - '${PACKAGE}'
+        suffixes:
+          '^openblas': openblas
+          '^netlib-lapack': netlib
+        filter:
+          environment_blacklist: ['CPATH', 'LIBRARY_PATH']
+        environment:
+          set:
+            '${PACKAGE}_ROOT': '${PREFIX}'
+      netlib-scalapack:
+        suffixes:
+          '^openmpi': openmpi
+          '^mpich': mpich
+
+There are many variable tokens available to use in the ``environment``
+and ``naming_scheme`` directives, such as ``${PACKAGE}``,
+``${VERSION}``, etc. (see the :meth:`~spack.spec.Spec.format` API
+documentation for the complete list).
+
+Regenerating the module files should result in something like:
+
+.. code-block:: console
+  :emphasize-lines: 14
+
+  $ spack module refresh -y --module-type tcl
+  ==> Regenerating tcl module files
+
+  $ module show gcc
+  ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+     ~/spack/share/spack/modules/linux-Ubuntu14-x86_64/gcc/6.2.0-gcc-4.8:
+  ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+  whatis("gcc @6.2.0 ")
+  prepend_path("PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/bin")
+  prepend_path("CMAKE_PREFIX_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/")
+  prepend_path("MANPATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/share/man")
+  prepend_path("PKG_CONFIG_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64/pkgconfig")
+  prepend_path("LD_LIBRARY_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64")
+  setenv("GCC_ROOT","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u")
+  conflict("gcc")
+  help([[The GNU Compiler Collection includes front ends for C, C++, Objective-C,
+  Fortran, and Java.
+  ]])
+
+As you see the ``gcc`` module has the environment variable ``GCC_ROOT`` set.
+
+Sometimes it's also useful to apply environment modifications selectively and target
+only certain packages. You can, for instance set the common variables ``CC``, ``CXX``,
+etc. in the ``gcc`` module file and apply other custom modifications to the
+``openmpi`` modules as follows:
+
+.. code-block:: yaml
+  :emphasize-lines: 20-32
+
+  modules:
+    tcl:
+      hash_length: 0
+      naming_scheme: '${PACKAGE}/${VERSION}-${COMPILERNAME}-${COMPILERVER}'
+      whitelist:
+        - gcc
+      blacklist:
+        - '%gcc@4.8'
+      all:
+        conflict:
+          - '${PACKAGE}'
+        suffixes:
+          '^openblas': openblas
+          '^netlib-lapack': netlib
+        filter:
+          environment_blacklist: ['CPATH', 'LIBRARY_PATH']
+        environment:
+          set:
+            '${PACKAGE}_ROOT': '${PREFIX}'
+      gcc:
+        environment:
+          set:
+            CC: gcc
+            CXX: g++
+            FC: gfortran
+            F90: gfortran
+            F77: gfortran
+      openmpi:
+        environment:
+          set:
+            SLURM_MPI_TYPE: pmi2
+            OMPI_MCA_btl_openib_warn_default_gid_prefix: '0'
+      netlib-scalapack:
+        suffixes:
+          '^openmpi': openmpi
+          '^mpich': mpich
+
+This time we will be more selective and regenerate only the ``gcc`` and
+``openmpi`` module files:
+
+.. code-block:: console
+
+  $ spack module refresh -y --module-type tcl gcc
+  ==> Regenerating tcl module files
+
+  $ spack module refresh -y --module-type tcl openmpi
+  ==> Regenerating tcl module files
+
+  $ module show gcc
+  ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+     ~/spack/share/spack/modules/linux-Ubuntu14-x86_64/gcc/6.2.0-gcc-4.8:
+  ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+  whatis("gcc @6.2.0 ")
+  prepend_path("PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/bin")
+  prepend_path("CMAKE_PREFIX_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/")
+  prepend_path("MANPATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/share/man")
+  prepend_path("PKG_CONFIG_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64/pkgconfig")
+  prepend_path("LD_LIBRARY_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u/lib64")
+  setenv("GCC_ROOT","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-4.8/gcc-6.2.0-twd5nqg33hrrssqclcfi5k42eccwxz5u")
+  setenv("CC","gcc")
+  setenv("CXX","g++")
+  setenv("F90","gfortran")
+  setenv("FC","gfortran")
+  setenv("F77","gfortran")
+  conflict("gcc")
+  help([[The GNU Compiler Collection includes front ends for C, C++, Objective-C,
+  Fortran, and Java.
+  ]])
+
+  $ module show openmpi
+  ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+     ~/spack/share/spack/modules/linux-Ubuntu14-x86_64/openmpi/2.0.1-gcc-6.2.0:
+  ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+  whatis("openmpi @2.0.1 ")
+  prepend_path("PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/openmpi-2.0.1-s3qbtbyh3y5y4gkchmhcuak7th44l53w/bin")
+  prepend_path("CMAKE_PREFIX_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/openmpi-2.0.1-s3qbtbyh3y5y4gkchmhcuak7th44l53w/")
+  prepend_path("LD_LIBRARY_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/openmpi-2.0.1-s3qbtbyh3y5y4gkchmhcuak7th44l53w/lib")
+  prepend_path("PKG_CONFIG_PATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/openmpi-2.0.1-s3qbtbyh3y5y4gkchmhcuak7th44l53w/lib/pkgconfig")
+  prepend_path("MANPATH","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/openmpi-2.0.1-s3qbtbyh3y5y4gkchmhcuak7th44l53w/share/man")
+  setenv("SLURM_MPI_TYPE","pmi2")
+  setenv("OMPI_MCA_BTL_OPENIB_WARN_DEFAULT_GID_PREFIX","0")
+  setenv("OPENMPI_ROOT","~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/openmpi-2.0.1-s3qbtbyh3y5y4gkchmhcuak7th44l53w")
+  conflict("openmpi")
+  help([[The Open MPI Project is an open source Message Passing Interface
+  implementation that is developed and maintained by a consortium of
+  academic, research, and industry partners. Open MPI is therefore able to
+  combine the expertise, technologies, and resources from all across the
+  High Performance Computing community in order to build the best MPI
+  library available. Open MPI offers advantages for system and software
+  vendors, application developers and computer science researchers.
+  ]])
+
+
+---------------------
+Autoload dependencies
+---------------------
+
+Spack can also generate module files that contain code to load the
+dependencies automatically. You can, for instance generate python
+modules that load their dependencies by adding the ``autoload``
+directive and assigning it the value ``direct``:
+
+.. code-block:: yaml
+  :emphasize-lines: 37,38
+
+  modules:
+    tcl:
+      hash_length: 0
+      naming_scheme: '${PACKAGE}/${VERSION}-${COMPILERNAME}-${COMPILERVER}'
+      whitelist:
+        - gcc
+      blacklist:
+        - '%gcc@4.8'
+      all:
+        conflict:
+          - '${PACKAGE}'
+        suffixes:
+          '^openblas': openblas
+          '^netlib-lapack': netlib
+        filter:
+          environment_blacklist: ['CPATH', 'LIBRARY_PATH']
+        environment:
+          set:
+            '${PACKAGE}_ROOT': '${PREFIX}'
+      gcc:
+        environment:
+          set:
+            CC: gcc
+            CXX: g++
+            FC: gfortran
+            F90: gfortran
+            F77: gfortran
+      openmpi:
+        environment:
+          set:
+            SLURM_MPI_TYPE: pmi2
+            OMPI_MCA_btl_openib_warn_default_gid_prefix: '0'
+      netlib-scalapack:
+        suffixes:
+          '^openmpi': openmpi
+          '^mpich': mpich
+      ^python:
+        autoload:  'direct'
+
+and regenerating the module files for every package that depends on ``python``:
+
+.. code-block:: console
+
+  $ spack module refresh -y --module-type tcl ^python
+  ==> Regenerating tcl module files
+
+Now the ``py-scipy`` module will be:
+
+.. code-block:: tcl
+
+  #%Module1.0
+  ## Module file created by spack (https://github.com/LLNL/spack) on 2016-11-02 20:53:21.283547
+  ##
+  ## py-scipy@0.18.1%gcc@6.2.0 arch=linux-Ubuntu14-x86_64-e6uljfi
+  ##
+  module-whatis "py-scipy @0.18.1"
+
+  proc ModulesHelp { } {
+  puts stderr "SciPy (pronounced "Sigh Pie") is a Scientific Library for Python. It"
+  puts stderr "provides many user-friendly and efficient numerical routines such as"
+  puts stderr "routines for numerical integration and optimization."
+  }
+
+  if ![ is-loaded python/2.7.12-gcc-6.2.0 ] {
+      puts stderr "Autoloading python/2.7.12-gcc-6.2.0"
+      module load python/2.7.12-gcc-6.2.0
+  }
+
+  if ![ is-loaded openblas/0.2.19-gcc-6.2.0 ] {
+      puts stderr "Autoloading openblas/0.2.19-gcc-6.2.0"
+      module load openblas/0.2.19-gcc-6.2.0
+  }
+
+  if ![ is-loaded py-numpy/1.11.1-gcc-6.2.0-openblas ] {
+      puts stderr "Autoloading py-numpy/1.11.1-gcc-6.2.0-openblas"
+      module load py-numpy/1.11.1-gcc-6.2.0-openblas
+  }
+
+  prepend-path CMAKE_PREFIX_PATH "~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/py-scipy-0.18.1-e6uljfiffgym4xvj6wveevqxfqnfb3gh/"
+  prepend-path LD_LIBRARY_PATH "~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/py-scipy-0.18.1-e6uljfiffgym4xvj6wveevqxfqnfb3gh/lib"
+  prepend-path PYTHONPATH "~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/py-scipy-0.18.1-e6uljfiffgym4xvj6wveevqxfqnfb3gh/lib/python2.7/site-packages"
+  setenv PY_SCIPY_ROOT "~/spack/opt/spack/linux-Ubuntu14-x86_64/gcc-6.2.0/py-scipy-0.18.1-e6uljfiffgym4xvj6wveevqxfqnfb3gh"
+  conflict py-scipy
+
+and will contain code to autoload all the dependencies:
+
+.. code-block:: console
+
+  $ module load py-scipy
+  Autoloading python/2.7.12-gcc-6.2.0
+  Autoloading openblas/0.2.19-gcc-6.2.0
+  Autoloading py-numpy/1.11.1-gcc-6.2.0-openblas
+
+-----------------------------
+Lua hierarchical module files
+-----------------------------
+
+In the final part of this tutorial you will modify ``modules.yaml`` to generate
+Lua hierarchical module files. You will see that most of the directives used before
+are also valid in the ``lmod`` context.
+
+^^^^^^^^^^^^^^^^^
+Core/Compiler/MPI
+^^^^^^^^^^^^^^^^^
+
+.. warning::
+  Only LMod supports Lua hierarchical module files
+    For this part of the tutorial you need to be using LMod to
+    manage your environment.
+
+The most common hierarchy is the so called ``Core/Compiler/MPI``. To have an idea
+how a hierarchy is organized you may refer to the
+`Lmod guide <https://www.tacc.utexas.edu/research-development/tacc-projects/lmod/user-guide/module-hierarchy>`_.
+Since ``lmod`` is not enabled by default, you need to add it to the list of
+enabled module file generators. The other things you need to do are:
+
+- change the ``tcl`` tag to ``lmod``
+- remove ``tcl`` specific directives (``naming_scheme`` and ``conflict``)
+- set which compilers are considered ``core``
+- remove the ``mpi`` related suffixes (as they will be substituted by hierarchies)
+
+After modifications the configuration file will be:
+
+.. code-block:: yaml
+  :emphasize-lines: 2-6
+
+  modules:
+    enable::
+      - lmod
+    lmod:
+      core_compilers:
+        - 'gcc@4.8'
+      hash_length: 0
+      whitelist:
+        - gcc
+      blacklist:
+        - '%gcc@4.8'
+      all:
+        suffixes:
+          '^openblas': openblas
+          '^netlib-lapack': netlib
+        filter:
+          environment_blacklist: ['CPATH', 'LIBRARY_PATH']
+        environment:
+          set:
+            '${PACKAGE}_ROOT': '${PREFIX}'
+      gcc:
+        environment:
+          set:
+            CC: gcc
+            CXX: g++
+            FC: gfortran
+            F90: gfortran
+            F77: gfortran
+      openmpi:
+        environment:
+          set:
+            SLURM_MPI_TYPE: pmi2
+            OMPI_MCA_btl_openib_warn_default_gid_prefix: '0'
+
+
+.. note::
+  The double colon
+    The double colon after ``enable`` is intentional and it serves the
+    purpose of overriding the default list of enabled generators so
+    that only ``lmod`` will be active (see :ref:`the reference
+    manual <config-overrides>` for a more detailed explanation of
+    config scopes).
+
+The directive ``core_compilers`` accepts a list of compilers : everything built
+using these compilers will create a module in the ``Core`` part of the hierarchy. It is
+common practice to put the OS provided compilers in the list and only build common utilities
+and other compilers in ``Core``.
+
+If you regenerate the module files
+
+.. code-block:: console
+
+  $ spack module refresh --module-type lmod --delete-tree -y
+
+and update ``MODULEPATH`` to point to the ``Core`` folder, and
+list the available modules, you'll see:
+
+.. code-block:: console
+
+  $ module unuse ~/spack/share/spack/modules/linux-Ubuntu14-x86_64
+  $ module use ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/Core
+  $ module avail
+
+  ----------------------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/Core -----------------------------------------------------------------------
+     gcc/6.2.0
+
+The only module visible now is ``gcc``. Loading that you will make
+visible the ``Compiler`` part of the software stack that was built with ``gcc/6.2.0``:
+
+.. code-block:: console
+
+  $ module load gcc
+  $ module avail
+
+  -------------------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/gcc/6.2.0 ---------------------------------------------------------------------
+     binutils/2.27    curl/7.50.3    hwloc/1.11.4           libtool/2.4.6    lzo/2.09       netlib-lapack/3.6.1    openssl/1.0.2j              py-scipy/0.18.1-openblas    util-macros/1.19.0
+     bison/3.0.4      expat/2.2.0    libarchive/3.2.1       libxml2/2.9.4    m4/1.4.17      nettle/3.2             pkg-config/0.29.1           py-setuptools/25.2.0        xz/5.2.2
+     bzip2/1.0.6      flex/2.6.0     libpciaccess/0.13.4    lz4/131          mpich/3.2      openblas/0.2.19        py-nose/1.3.7               python/2.7.12               zlib/1.2.8
+     cmake/3.6.1      gmp/6.1.1      libsigsegv/2.10        lzma/4.32.7      ncurses/6.0    openmpi/2.0.1          py-numpy/1.11.1-openblas    sqlite/3.8.5
+
+  ----------------------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/Core -----------------------------------------------------------------------
+     gcc/6.2.0 (L)
+
+The same holds true for the ``MPI`` part of the stack, that you can enable by loading
+either ``mpich`` or ``openmpi``. The nice features of LMod will become evident
+once you'll try switching among different stacks:
+
+.. code-block:: console
+
+  $ module load mpich
+  $ module avail
+
+  ----------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/mpich/3.2-5n5xoep/gcc/6.2.0 ------------------------------------------------------------
+     netlib-scalapack/2.0.2-netlib    netlib-scalapack/2.0.2-openblas (D)
+
+  -------------------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/gcc/6.2.0 ---------------------------------------------------------------------
+     binutils/2.27    curl/7.50.3    hwloc/1.11.4           libtool/2.4.6    lzo/2.09           netlib-lapack/3.6.1    openssl/1.0.2j              py-scipy/0.18.1-openblas    util-macros/1.19.0
+     bison/3.0.4      expat/2.2.0    libarchive/3.2.1       libxml2/2.9.4    m4/1.4.17          nettle/3.2             pkg-config/0.29.1           py-setuptools/25.2.0        xz/5.2.2
+     bzip2/1.0.6      flex/2.6.0     libpciaccess/0.13.4    lz4/131          mpich/3.2   (L)    openblas/0.2.19        py-nose/1.3.7               python/2.7.12               zlib/1.2.8
+     cmake/3.6.1      gmp/6.1.1      libsigsegv/2.10        lzma/4.32.7      ncurses/6.0        openmpi/2.0.1          py-numpy/1.11.1-openblas    sqlite/3.8.5
+
+  ----------------------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/Core -----------------------------------------------------------------------
+     gcc/6.2.0 (L)
+
+  $ module load openblas netlib-scalapack/2.0.2-openblas
+  $ module list
+
+  Currently Loaded Modules:
+    1) gcc/6.2.0   2) mpich/3.2   3) openblas/0.2.19   4) netlib-scalapack/2.0.2-openblas
+
+  $ module load openmpi
+
+  Lmod is automatically replacing "mpich/3.2" with "openmpi/2.0.1"
+
+
+  Due to MODULEPATH changes the following have been reloaded:
+    1) netlib-scalapack/2.0.2-openblas
+
+This layout is already a great improvement over the usual non-hierarchical layout,
+but it still has an asymmetry: ``LAPACK`` providers are semantically the same as ``MPI``
+providers, but they are still not part of the hierarchy.  We'll see a possible solution
+next.
+
+.. Activate lmod and turn the previous modifications into lmod:
+   Add core compilers
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Extend the hierarchy to other virtual providers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. warning::
+  This is an experimental feature
+    Having a hierarchy deeper than ``Core``/``Compiler``/``MPI`` is an experimental
+    feature, still not fully supported by ``module spider``,
+    see `here <https://github.com/TACC/Lmod/issues/114>`_. Furthermore its use
+    with hierarchies more complex than ``Core``/``Compiler``/``MPI``/``LAPACK``
+    has not been thoroughly tested in production environments.
+
+Spack permits you to generate Lua hierarchical module files where users
+can add an arbitrary list of virtual providers to the triplet
+``Core``/``Compiler``/``MPI``. A configuration file like:
+
+.. code-block:: yaml
+  :emphasize-lines: 7,8
+
+  modules:
+    enable::
+      - lmod
+    lmod:
+      core_compilers:
+        - 'gcc@4.8'
+      hierarchical_scheme:
+        - lapack
+      hash_length: 0
+      whitelist:
+        - gcc
+      blacklist:
+        - '%gcc@4.8'
+        - readline
+      all:
+        filter:
+          environment_blacklist: ['CPATH', 'LIBRARY_PATH']
+        environment:
+          set:
+            '${PACKAGE}_ROOT': '${PREFIX}'
+      gcc:
+        environment:
+          set:
+            CC: gcc
+            CXX: g++
+            FC: gfortran
+            F90: gfortran
+            F77: gfortran
+      openmpi:
+        environment:
+          set:
+            SLURM_MPI_TYPE: pmi2
+            OMPI_MCA_btl_openib_warn_default_gid_prefix: '0'
+
+will add ``lapack`` providers to the mix. After the usual regeneration of module files:
+
+.. code-block:: console
+
+  $ module purge
+  $ spack module refresh --module-type lmod --delete-tree -y
+  ==> Regenerating lmod module files
+
+you will have something like:
+
+.. code-block:: console
+
+  $ module load gcc
+  $ module load openblas
+  $ module load openmpi
+  $ module avail
+
+  --------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/openblas/0.2.19-js33umc/openmpi/2.0.1-s3qbtby/gcc/6.2.0 ----------------------------------------------
+     netlib-scalapack/2.0.2
+
+  -------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/openblas/0.2.19-js33umc/gcc/6.2.0 ---------------------------------------------------------
+     py-numpy/1.11.1    py-scipy/0.18.1
+
+  -------------------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/gcc/6.2.0 ---------------------------------------------------------------------
+     binutils/2.27    curl/7.50.3    hwloc/1.11.4           libtool/2.4.6    lzo/2.09       netlib-lapack/3.6.1        openssl/1.0.2j          python/2.7.12         zlib/1.2.8
+     bison/3.0.4      expat/2.2.0    libarchive/3.2.1       libxml2/2.9.4    m4/1.4.17      nettle/3.2                 pkg-config/0.29.1       sqlite/3.8.5
+     bzip2/1.0.6      flex/2.6.0     libpciaccess/0.13.4    lz4/131          mpich/3.2      openblas/0.2.19     (L)    py-nose/1.3.7           util-macros/1.19.0
+     cmake/3.6.1      gmp/6.1.1      libsigsegv/2.10        lzma/4.32.7      ncurses/6.0    openmpi/2.0.1       (L)    py-setuptools/25.2.0    xz/5.2.2
+
+  ----------------------------------------------------------------------- ~/spack/share/spack/lmod/linux-Ubuntu14-x86_64/Core -----------------------------------------------------------------------
+     gcc/6.2.0 (L)
+
+Now both the ``MPI`` and the ``LAPACK`` providers are handled by LMod as hierarchies:
+
+.. code-block:: console
+
+  $ module load py-numpy netlib-scalapack
+  $ module load mpich
+
+  Lmod is automatically replacing "openmpi/2.0.1" with "mpich/3.2"
+
+
+  Due to MODULEPATH changes the following have been reloaded:
+    1) netlib-scalapack/2.0.2
+
+  $ module load netlib-lapack
+
+  Lmod is automatically replacing "openblas/0.2.19" with "netlib-lapack/3.6.1"
+
+
+  Inactive Modules:
+    1) py-numpy
+
+  Due to MODULEPATH changes the following have been reloaded:
+    1) netlib-scalapack/2.0.2
+
+making the use of tags to differentiate them unnecessary.
+Note that because we only compiled ``py-numpy`` with ``openblas`` the module
+is made inactive when we switch the ``LAPACK`` provider. The user
+environment will now be consistent by design!

lib/spack/docs/tutorial_sc16_packaging.rst

@@ -0,0 +1,462 @@
+.. _packaging-tutorial:
+
+=========================
+Package Creation Tutorial
+=========================
+
+This tutorial will walk you through the steps behind building a simple
+package installation script.  We'll focus building an mpileaks package,
+which is a MPI debugging tool.  By creating a package file we're
+essentially giving Spack a recipe for how to build a particular piece of
+software.  We're describing some of the software's dependencies, where to
+find the package, what commands and options are used to build the package
+from source, and more.  Once we've specified a package's recipe, we can
+ask Spack to build that package in many different ways.
+
+This tutorial assumes you have a basic familiarity with some of the Spack
+commands, and that you have a working version of Spack installed.  If
+not, we suggest looking at Spack's *Getting Started* guide.  This
+tutorial also assumes you have at least a beginner's-level familiarity
+with Python.
+
+Also note that this document is a tutorial.  It can help you get started
+with packaging, but is not intended to be complete.  See Spack's
+:ref:`packaging-guide` for more complete documentation on this topic.
+
+---------------
+Getting Started
+---------------
+
+A few things before we get started:
+
+- We'll refer to the Spack installation location via the environment
+  variable ``SPACK_ROOT``.  You should point ``SPACK_ROOT`` at wherever
+  you have Spack installed.
+- Add ``$SPACK_ROOT/bin`` to your ``PATH`` before you start.
+- Make sure your ``EDITOR`` environment variable is set to some text
+  editor you like.
+- We'll be writing Python code as part of this tutorial.  You can find
+  successive versions of the Python code in
+  ``$SPACK_ROOT/lib/spack/docs/tutorial/examples``.
+
+-------------------------
+Creating the Package File
+-------------------------
+
+Spack comes with a handy command to create a new package: ``spack create``
+
+This command is given the location of a package's source code, downloads
+the code, and sets up some basic packaging infrastructure for you.  The
+mpileaks source code can be found on GitHub, and here's what happens when
+we run ``spack create`` on it:
+
+.. code-block:: console
+
+  $ spack create -f https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz
+  ==> This looks like a URL for mpileaks version 1.0
+  ==> Creating template for package mpileaks
+  ==> Downloading...
+  ==> Fetching https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz
+  ###################################################################################### 100.0%
+
+And Spack should spawn a text editor with this file:
+
+.. literalinclude:: tutorial/examples/0.package.py
+   :language: python
+
+Spack has created this file in
+``$SPACK_ROOT/var/spack/repos/builtin/packages/mpileaks/package.py``.  Take a
+moment to look over the file.  There's a few placeholders that Spack has
+created, which we'll fill in as part of this tutorial:
+
+- We'll document some information about this package in the comments.
+- We'll fill in the dependency list for this package.
+- We'll fill in some of the configuration arguments needed to build this
+  package.
+
+For the moment, exit your editor and let's see what happens when we try
+to build this package:
+
+.. code-block:: console
+
+  $ spack install mpileaks
+  ==> Installing mpileaks
+  ==> Using cached archive: /usr/workspace/wsa/legendre/spack/var/spack/cache/mpileaks/mpileaks-1.0.tar.gz
+  ==> Staging archive: /usr/workspace/wsa/legendre/spack/var/spack/stage/mpileaks-1.0-hufwhwpq5benv3sslie6ryflk5s6nm35/mpileaks-1.0.tar.gz
+  ==> Created stage in /usr/workspace/wsa/legendre/spack/var/spack/stage/mpileaks-1.0-hufwhwpq5benv3sslie6ryflk5s6nm35
+  ==> Ran patch() for mpileaks
+  ==> Building mpileaks [AutotoolsPackage]
+  ==> Executing phase : 'autoreconf'
+  ==> Executing phase : 'configure'
+  ==> Error: ProcessError: Command exited with status 1:
+      './configure' '--prefix=/usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/mpileaks-1.0-hufwhwpq5benv3sslie6ryflk5s6nm35'
+  /usr/workspace/wsa/legendre/spack/lib/spack/spack/build_systems/autotools.py:150, in configure:
+       145      def configure(self, spec, prefix):
+       146          """Runs configure with the arguments specified in `configure_args`
+       147          and an appropriately set prefix
+       148          """
+       149          options = ['--prefix={0}'.format(prefix)] + self.configure_args()
+    >> 150          inspect.getmodule(self).configure(*options)
+
+  See build log for details:
+    /tmp/legendre/spack-stage/spack-stage-8HVzqu/mpileaks-1.0/spack-build.out
+
+This obviously didn't work; we need to fill in the package-specific
+information.  Specifically, Spack didn't try to build any of mpileaks'
+dependencies, nor did it use the proper configure arguments.  Let's start
+fixing things
+
+---------------------
+Package Documentation
+---------------------
+
+We can bring the ``package.py`` file back into our ``EDITOR`` with the
+``spack edit`` command:
+
+.. code-block:: console
+
+  $ spack edit mpileaks
+
+Let's remove some of the ``FIXME`` comments, and add links to the mpileaks
+homepage and document what mpileaks does.  I'm also going to cut out the
+Copyright clause at this point to keep this tutorial document shorter,
+but you shouldn't do that normally.  The results of these changes can be
+found in ``$SPACK_ROOT/lib/spack/docs/tutorial/examples/1.package.py``
+and are below.  Make these changes to your ``package.py``:
+
+.. literalinclude:: tutorial/examples/1.package.py
+   :lines: 25-
+   :language: python
+
+We've filled in the comment that describes what this package does and
+added a link to the web site.  That won't help us build yet, but it will
+allow Spack to provide some documentation on this package to other users:
+
+.. code-block:: console
+
+  $ spack info mpileaks
+  AutotoolsPackage:    mpileaks
+  Homepage:            https://github.com/hpc/mpileaks
+
+  Safe versions:
+      1.0    https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz
+
+  Variants:
+      None
+
+  Installation Phases:
+      autoreconf    configure    build    install
+
+  Build Dependencies:
+      None
+
+  Link Dependencies:
+      None
+
+  Run Dependencies:
+      None
+
+  Virtual Packages:
+      None
+
+  Description:
+      Tool to detect and report MPI objects like MPI_Requests and
+      MPI_Datatypes
+
+As we fill in more information about this package the ``spack info`` command
+will become more informative.  Now let's start making this package build.
+
+------------
+Dependencies
+------------
+
+The mpileaks packages depends on three other package: ``MPI``,
+``adept-utils``, and ``callpath``.  Let's add those via the
+``depends_on`` command in our ``package.py`` (this version is in
+``$SPACK_ROOT/lib/spack/docs/tutorial/examples/2.package.py``):
+
+.. literalinclude:: tutorial/examples/2.package.py
+   :lines: 25-
+   :language: python
+
+Now when we go to build mpileaks, Spack will fetch and build these
+dependencies before building mpileaks.  Note that the mpi dependency is a
+different kind of beast than the adept-utils and callpath dependencies;
+there is no mpi package available in Spack.  Instead mpi is a virtual
+dependency.  Spack may satisfy that dependency by installing packages
+such as ``openmpi`` or ``mvapich``.  See the :ref:`packaging-guide` for more
+information on virtual dependencies.
+
+Now when we try to install this package a lot more happens:
+
+.. code-block:: console
+
+  $ spack install mpileaks
+  ==> Installing mpileaks
+  ==> openmpi is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz
+  ==> callpath is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/callpath-1.0.2-zm4pf3gasgxeibyu2y262suktvaazube
+  ==> adept-utils is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/adept-utils-1.0.1-7p7ezxwtajdglj6cmojy2vybjct4j4jz
+  ==> Using cached archive: /usr/workspace/wsa/legendre/spack/var/spack/cache/mpileaks/mpileaks-1.0.tar.gz
+  ==> Already staged mpileaks-1.0-eum4hmnlt6ovalwjnciaygfb3beja4gk in /usr/workspace/wsa/legendre/spack/var/spack/stage/mpileaks-1.0-eum4hmnlt6ovalwjnciaygfb3beja4gk
+  ==> Already patched mpileaks
+  ==> Building mpileaks [AutotoolsPackage]
+  ==> Executing phase : 'autoreconf'
+  ==> Executing phase : 'configure'
+  ==> Error: ProcessError: Command exited with status 1:
+      './configure' '--prefix=/usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/mpileaks-1.0-eum4hmnlt6ovalwjnciaygfb3beja4gk'
+  /usr/workspace/wsa/legendre/spack/lib/spack/spack/build_systems/autotools.py:150, in configure:
+       145      def configure(self, spec, prefix):
+       146          """Runs configure with the arguments specified in `configure_args`
+       147          and an appropriately set prefix
+       148          """
+       149          options = ['--prefix={0}'.format(prefix)] + self.configure_args()
+    >> 150          inspect.getmodule(self).configure(*options)
+
+  See build log for details:
+    /tmp/legendre/spack-stage/spack-stage-7V5yyk/mpileaks-1.0/spack-build.out
+
+Note that this command may take a while to run and produce more output if
+you don't have an MPI already installed or configured in Spack.
+
+Now Spack has identified and made sure all of our dependencies have been
+built.  It found the ``openmpi`` package that will satisfy our ``mpi``
+dependency, and the ``callpath`` and ``adept-utils`` package to satisfy our
+concrete dependencies.
+
+------------------------
+Debugging Package Builds
+------------------------
+
+Our ``mpileaks`` package is still not building.  It may be obvious to
+many of you that we're still missing the configure options.  But let's
+pretend we're not all intelligent developers and use this opportunity
+spend some time debugging.  We a few options that can tell us about
+what's going wrong:
+
+As per the error message, Spack has given us a ``spack-build.out`` debug log:
+
+.. code-block:: console
+
+  ==> './configure' '--prefix=/usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/mpileaks-1.0-eum4hmnlt6ovalwjnciaygfb3beja4gk'
+  checking metadata... no
+  checking installation directory variables... yes
+  checking for a BSD-compatible install... /usr/bin/install -c
+  checking whether build environment is sane... yes
+  checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
+  checking for gawk... gawk
+  checking whether make sets $(MAKE)... yes
+  checking for gcc... /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc
+  checking for C compiler default output file name... a.out
+  checking whether the C compiler works... yes
+  checking whether we are cross compiling... no
+  checking for suffix of executables...
+  checking for suffix of object files... o
+  checking whether we are using the GNU C compiler... yes
+  checking whether /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc accepts -g... yes
+  checking for /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc option to accept ISO C89... none needed
+  checking for style of include used by make... GNU
+  checking dependency style of /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc... gcc3
+  checking whether /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc and cc understand -c and -o together... yes
+  checking whether we are using the GNU C++ compiler... yes
+  checking whether /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/g++ accepts -g... yes
+  checking dependency style of /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/g++... gcc3
+  checking for /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz/bin/mpicc... /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz/bin/mpicc
+  Checking whether /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz/bin/mpicc responds to '-showme:compile'... yes
+  configure: error: unable to locate ``adept-utils`` installation
+
+This gives us the output from the build, and it's fairly obvious that
+mpileaks isn't finding its ``adept-utils`` package.  Spack has
+automatically added the include and library directories of
+``adept-utils`` to the compiler's search path, but some packages like
+mpileaks can sometimes be picky and still want things spelled out on
+their command line.  But let's continue to pretend we're not brilliant
+developers, and explore some other debugging paths:
+
+We can also enter the build area and try to manually run the build:
+
+.. code-block:: console
+
+  $ spack env mpileaks bash
+  $ spack cd mpileaks
+
+The ``spack env`` command spawned a new shell that contains the same
+environment that Spack used to build the mpileaks package (you can
+substitute bash for your favorite shell).  The ``spack cd`` command
+changed our working dirctory to the last attempted build for mpileaks.
+From here we can manually re-run the build:
+
+.. code-block:: console
+
+  $ ./configure
+  checking metadata... no
+  checking installation directory variables... yes
+  checking for a BSD-compatible install... /usr/bin/install -c
+  checking whether build environment is sane... yes
+  checking for a thread-safe mkdir -p... /usr/bin/mkdir -p
+  checking for gawk... gawk
+  checking whether make sets $(MAKE)... yes
+  checking for gcc... /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc
+  checking for C compiler default output file name... a.out
+  checking whether the C compiler works... yes
+  checking whether we are cross compiling... no
+  checking for suffix of executables...
+  checking for suffix of object files... o
+  checking whether we are using the GNU C compiler... yes
+  checking whether /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc accepts -g... yes
+  checking for /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc option to accept ISO C89... none needed
+  checking for style of include used by make... GNU
+  checking dependency style of /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc... gcc3
+  checking whether /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/gcc and cc understand -c and -o together... yes
+  checking whether we are using the GNU C++ compiler... yes
+  checking whether /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/g++ accepts -g... yes
+  checking dependency style of /usr/workspace/wsa/legendre/spack/lib/spack/env/gcc/g++... gcc3
+  checking for /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz/bin/mpicc... /usr/workspace/wsa  /legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz/bin/mpicc
+  Checking whether /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz/bin/mpicc responds to '-showme:compile'... yes
+  configure: error: unable to locate adept-utils installation
+
+We're seeing the same error, but now we're in a shell where we can run
+the command ourselves and debug as needed.  We could, for example, run
+``./configure --help`` to see what options we can use to specify
+dependencies.
+
+We can use the ``exit`` command to leave the shell spawned by ``spack
+env``.
+
+------------------------------
+Specifying Configure Arguments
+------------------------------
+
+Let's add the configure arguments to the mpileaks' ``package.py``.  This
+version can be found in
+``$SPACK_ROOT/lib/spack/docs/tutorial/examples/3.package.py``:
+
+.. literalinclude:: tutorial/examples/3.package.py
+   :lines: 25-
+   :language: python
+
+This is all we need for working mpileaks!  If we install now we'll see:
+
+.. code-block:: console
+
+  $ spack install mpileaks
+  spack install mpileaks
+  ==> Installing mpileaks
+  ==> openmpi is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz
+  ==> callpath is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/callpath-1.0.2-zm4pf3gasgxeibyu2y262suktvaazube
+  ==> adept-utils is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/adept-utils-1.0.1-7p7ezxwtajdglj6cmojy2vybjct4j4jz
+  ==> Using cached archive: /usr/workspace/wsa/legendre/spack/var/spack/cache/mpileaks/mpileaks-1.0.tar.gz
+  ==> Already staged mpileaks-1.0-eum4hmnlt6ovalwjnciaygfb3beja4gk in /usr/workspace/wsa/legendre/spack/var/spack/stage/mpileaks-1.0-eum4hmnlt6ovalwjnciaygfb3beja4gk
+  ==> Already patched mpileaks
+  ==> Building mpileaks [AutotoolsPackage]
+  ==> Executing phase : 'autoreconf'
+  ==> Executing phase : 'configure'
+  ==> Executing phase : 'build'
+  ==> Executing phase : 'install'
+  ==> Successfully installed mpileaks
+    Fetch: 0.00s.  Build: 14.08s.  Total: 14.08s.
+  [+] /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/mpileaks-1.0-eum4hmnlt6ovalwjnciaygfb3beja4gk
+
+We took a few shortcuts for this package that are worth highlighting.
+Spack automatically detected that mpileaks was an Autotools-based package
+when we ran ``spack create``.  If this had been a CMake-based package we
+would have been filling in a ``cmake_args`` function instead of
+``configure_args``.  If Spack hadn't been able to detect the build
+system, we'd be filling in a generic install method that would manually
+be calling build commands, such as is found in the ``zlib`` package:
+
+.. code-block:: python
+
+    def install(self, spec, prefix):
+        configure('--prefix={0}'.format(prefix))
+        make()
+        make('install')
+
+--------
+Variants
+--------
+
+We have a successful mpileaks build, but let's take some time to improve
+it.  ``mpileaks`` has a build-time option to truncate parts of the stack
+that it walks.  Let's add a variant to allow users to set this when they
+build in Spack.
+
+To do this, we'll add a variant to our package, as per the following (see
+``$SPACK_ROOT/lib/spack/docs/tutorial/examples/4.package.py``):
+
+.. literalinclude:: tutorial/examples/4.package.py
+   :lines: 25-
+   :language: python
+
+We've added the variant ``stackstart``, and given it a default value of
+``0``.  If we install now we can see the stackstart variant added to the
+configure line (output truncated for length):
+
+.. code-block:: console
+
+  $ spack install --verbose mpileaks stackstart=4
+  ==> Installing mpileaks
+  ==> openmpi is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/openmpi-2.0.1-5ee5j34c2y4kb5c3joygrgahidqnwhnz
+  ==> callpath is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/callpath-1.0.2-zm4pf3gasgxeibyu2y262suktvaazube
+  ==> adept-utils is already installed in /usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/adept-utils-1.0.1-7p7ezxwtajdglj6cmojy2vybjct4j4jz
+  ==> Using cached archive: /usr/workspace/wsa/legendre/spack/var/spack/cache/mpileaks/mpileaks-1.0.tar.gz
+  ==> Staging archive: /usr/workspace/wsa/legendre/spack/var/spack/stage/mpileaks-1.0-otqo2opkhan5ksujt6tpmdftydrieig7/mpileaks-1.0.tar.gz
+  ==> Created stage in /usr/workspace/wsa/legendre/spack/var/spack/stage/mpileaks-1.0-otqo2opkhan5ksujt6tpmdftydrieig7
+  ==> Ran patch() for mpileaks
+  ==> Building mpileaks [AutotoolsPackage]
+  ==> Executing phase : 'autoreconf'
+  ==> Executing phase : 'configure'
+  ==> './configure' '--prefix=/usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/mpileaks-1.0-otqo2opkhan5ksujt6tpmdftydrieig7' '--with-adept-utils=/usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/adept-utils-1.0.1-7p7ezxwtajdglj6cmojy2vybjct4j4jz' '--with-callpath=/usr/workspace/wsa/legendre/spack/opt/spack/linux-rhel7-x86_64/gcc-4.9.3/callpath-1.0.2-zm4pf3gasgxeibyu2y262suktvaazube' '--with-stack-start-c=4' '--with-stack-start-fortran=4'
+
+---------------
+The Spec Object
+---------------
+
+This tutorial has glossed over a few important features, which weren't
+too relevant for mpileaks but may be useful for other packages.  There
+were several places we references the ``self.spec`` object.  This is a
+powerful class for querying information about what we're building.  For
+example, you could use the spec to query information about how a
+package's dependencies were built, or what compiler was being used, or
+what version of a package is being installed.  Full documentation can be
+found in the :ref:`packaging-guide`, but here's some quick snippets with
+common queries:
+
+- Am I building ``mpileaks`` version ``1.1`` or greater?
+
+.. code-block:: python
+
+  if self.spec.satisfies('@1.1:'):
+    # Do things needed for 1.1+
+
+- Is ``openmpi`` the MPI I'm building with?
+
+.. code-block:: python
+
+  if self.spec['mpi'].name == 'openmpi':
+    # Do openmpi things
+
+- Am I building with ``gcc`` version less than ``5.0.0``:
+
+.. code-block:: python
+
+  if self.spec.satisfies('%gcc@:5.0.0'):
+    # Add arguments specific to gcc's earlier than 5.0.0
+
+- Am I built with the ``debug`` variant:
+
+.. code-block:: python
+
+  if self.spec.satisfies('+debug'):
+    # Add -g option to configure flags
+
+- Is my ``dyninst`` dependency greater than version ``8.0``?
+
+.. code-block:: python
+
+   if self.spec['dyninst'].satisfies('@8.0:'):
+    # Use newest dyninst options
+
+More examples can be found in the thousands of packages already added to
+Spack in ``$SPACK_ROOT/var/spack/repos/builtin/packages``.
+
+Good Luck!

lib/spack/env/cc

@@ -1,140 +1,362 @@
-#!/usr/bin/env python
-import sys
-if not sys.version_info[:2] >= (2,7):
-    sys.exit("Spack requires Python 2.7.  Version was %s." % sys.version_info)
+#!/bin/bash
+##############################################################################
+# Copyright (c) 2013-2016, Lawrence Livermore National Security, LLC.
+# Produced at the Lawrence Livermore National Laboratory.
+#
+# This file is part of Spack.
+# Created by Todd Gamblin, tgamblin@llnl.gov, All rights reserved.
+# LLNL-CODE-647188
+#
+# For details, see https://github.com/llnl/spack
+# Please also see the LICENSE file for our notice and the LGPL.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License (as
+# published by the Free Software Foundation) version 2.1, February 1999.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the IMPLIED WARRANTY OF
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the terms and
+# conditions of the GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+##############################################################################
+#
+# Spack compiler wrapper script.
+#
+# Compiler commands go through this compiler wrapper in Spack builds.
+# The compiler wrapper is a thin layer around the standard compilers.
+# It enables several key pieces of functionality:
+#
+# 1. It allows Spack to swap compilers into and out of builds easily.
+# 2. It adds several options to the compile line so that spack
+#    packages can find their dependencies at build time and run time:
+#      -I           arguments for dependency /include directories.
+#      -L           arguments for dependency /lib directories.
+#      -Wl,-rpath   arguments for dependency /lib directories.
+#
 
-import os
-import re
-import subprocess
-import argparse
-from contextlib import closing
+# This is an array of environment variables that need to be set before
+# the script runs. They are set by routines in spack.build_environment
+# as part of spack.package.Package.do_install().
+parameters=(
+    SPACK_PREFIX
+    SPACK_ENV_PATH
+    SPACK_DEBUG_LOG_DIR
+    SPACK_COMPILER_SPEC
+    SPACK_CC_RPATH_ARG
+    SPACK_CXX_RPATH_ARG
+    SPACK_F77_RPATH_ARG
+    SPACK_FC_RPATH_ARG
+    SPACK_SHORT_SPEC
+)
 
-# Import spack parameters through the build environment.
-spack_lib = os.environ.get("SPACK_LIB")
-if not spack_lib:
-    print "Spack compiler must be run from spack!"
-    sys.exit(1)
+# The compiler input variables are checked for sanity later:
+#   SPACK_CC, SPACK_CXX, SPACK_F77, SPACK_FC
+# The default compiler flags are passed from these variables:
+#   SPACK_CFLAGS, SPACK_CXXFLAGS, SPACK_FCFLAGS, SPACK_FFLAGS,
+#   SPACK_LDFLAGS, SPACK_LDLIBS
+# Debug env var is optional; set to true for debug logging:
+#   SPACK_DEBUG
+# Test command is used to unit test the compiler script.
+#   SPACK_TEST_COMMAND
+# Dependencies can be empty for pkgs with no deps:
+#   SPACK_DEPENDENCIES
 
-# Grab a minimal set of spack packages
-sys.path.append(spack_lib)
-from spack.compilation import *
-import llnl.util.tty as tty
+# die()
+# Prints a message and exits with error 1.
+function die {
+    echo "$@"
+    exit 1
+}
 
-spack_prefix        = get_env_var("SPACK_PREFIX")
-spack_debug         = get_env_flag("SPACK_DEBUG")
-spack_deps          = get_path("SPACK_DEPENDENCIES")
-spack_env_path      = get_path("SPACK_ENV_PATH")
-spack_debug_log_dir = get_env_var("SPACK_DEBUG_LOG_DIR")
-spack_spec          = get_env_var("SPACK_SPEC")
+for param in ${parameters[@]}; do
+    if [[ -z ${!param} ]]; then
+        die "Spack compiler must be run from Spack! Input '$param' is missing."
+    fi
+done
 
-compiler_spec = get_env_var("SPACK_COMPILER_SPEC")
-spack_cc  = get_env_var("SPACK_CC",  required=False)
-spack_cxx = get_env_var("SPACK_CXX", required=False)
-spack_f77 = get_env_var("SPACK_F77", required=False)
-spack_fc  = get_env_var("SPACK_FC",  required=False)
+# Figure out the type of compiler, the language, and the mode so that
+# the compiler script knows what to do.
+#
+# Possible languages are C, C++, Fortran 77, and Fortran 90.
+# 'command' is set based on the input command to $SPACK_[CC|CXX|F77|F90]
+#
+# 'mode' is set to one of:
+#    vcheck  version check
+#    cpp     preprocess
+#    cc      compile
+#    as      assemble
+#    ld      link
+#    ccld    compile & link
 
-# Figure out what type of operation we're doing
-command = os.path.basename(sys.argv[0])
+command=$(basename "$0")
+comp="CC"
+case "$command" in
+    cpp)
+        mode=cpp
+        ;;
+    cc|c89|c99|gcc|clang|icc|pgcc|xlc)
+        command="$SPACK_CC"
+        language="C"
+        comp="CC"
+        lang_flags=C
+        ;;
+    c++|CC|g++|clang++|icpc|pgc++|xlc++)
+        command="$SPACK_CXX"
+        language="C++"
+        comp="CXX"
+        lang_flags=CXX
+        ;;
+    ftn|f90|fc|f95|gfortran|ifort|pgfortran|xlf90|nagfor)
+        command="$SPACK_FC"
+        language="Fortran 90"
+        comp="FC"
+        lang_flags=F
+        ;;
+    f77|gfortran|ifort|pgfortran|xlf|nagfor|ftn)
+        command="$SPACK_F77"
+        language="Fortran 77"
+        comp="F77"
+        lang_flags=F
+        ;;
+    ld)
+        mode=ld
+        ;;
+    *)
+        die "Unkown compiler: $command"
+        ;;
+esac
 
-cpp, cc, ccld, ld, version_check = range(5)
+# If any of the arguments below are present, then the mode is vcheck.
+# In vcheck mode, nothing is added in terms of extra search paths or
+# libraries.
+if [[ -z $mode ]]; then
+    for arg in "$@"; do
+        if [[ $arg == -v || $arg == -V || $arg == --version || $arg == -dumpversion ]]; then
+            mode=vcheck
+            break
+        fi
+    done
+fi
 
-if command == 'cpp':
-    mode = cpp
-elif command == 'ld':
-    mode = ld
-elif '-E' in sys.argv:
-    mode = cpp
-elif '-c' in sys.argv:
-    mode = cc
-else:
-    mode = ccld
+# Finish setting up the mode.
+if [[ -z $mode ]]; then
+    mode=ccld
+    for arg in "$@"; do
+        if [[ $arg == -E ]]; then
+            mode=cpp
+            break
+        elif [[ $arg == -S ]]; then
+            mode=as
+            break
+        elif [[ $arg == -c ]]; then
+            mode=cc
+            break
+        fi
+    done
+fi
 
+# Set up rpath variable according to language.
+eval rpath=\$SPACK_${comp}_RPATH_ARG
 
-if command in ('cc', 'gcc', 'c89', 'c99', 'clang'):
-    command = spack_cc
-    language = "C"
-elif command in ('c++', 'CC', 'g++', 'clang++'):
-    command = spack_cxx
-    language = "C++"
-elif command in ('f77'):
-    command = spack_f77
-    language = "Fortran 77"
-elif command in ('fc', 'f90', 'f95'):
-    command = spack_fc
-    language = "Fortran 90"
-elif command in ('ld', 'cpp'):
-    pass # leave it the same.  TODO: what's the right thing?
-else:
-    raise Exception("Unknown compiler: %s" % command)
+# Dump the version and exit if we're in testing mode.
+if [[ $SPACK_TEST_COMMAND == dump-mode ]]; then
+    echo "$mode"
+    exit
+fi
 
-if command is None:
-    print "ERROR: Compiler '%s' does not support compiling %s programs." % (
-        compiler_spec, language)
-    sys.exit(1)
+# Check that at least one of the real commands was actually selected,
+# otherwise we don't know what to execute.
+if [[ -z $command ]]; then
+    die "ERROR: Compiler '$SPACK_COMPILER_SPEC' does not support compiling $language programs."
+fi
 
-version_args = ['-V', '-v', '--version', '-dumpversion']
-if any(arg in sys.argv for arg in version_args):
-    mode = version_check
+#
+# Set paths as defined in the 'environment' section of the compiler config
+#   names are stored in SPACK_ENV_TO_SET
+#   values are stored in SPACK_ENV_SET_<varname>
+#
+IFS=':' read -ra env_set_varnames <<< "$SPACK_ENV_TO_SET"
+for varname in "${env_set_varnames[@]}"; do
+    spack_varname="SPACK_ENV_SET_$varname"
+    export $varname=${!spack_varname}
+    unset $spack_varname
+done
 
-# Parse out the includes, libs, etc. so we can adjust them if need be.
-parser = argparse.ArgumentParser(add_help=False)
-parser.add_argument("-I", action='append', default=[], dest='include_path')
-parser.add_argument("-L", action='append', default=[], dest='lib_path')
-parser.add_argument("-l", action='append', default=[], dest='libs')
+#
+# Filter '.' and Spack environment directories out of PATH so that
+# this script doesn't just call itself
+#
+IFS=':' read -ra env_path <<< "$PATH"
+IFS=':' read -ra spack_env_dirs <<< "$SPACK_ENV_PATH"
+spack_env_dirs+=("" ".")
+PATH=""
+for dir in "${env_path[@]}"; do
+    addpath=true
+    for env_dir in "${spack_env_dirs[@]}"; do
+        if [[ $dir == $env_dir ]]; then
+            addpath=false
+            break
+        fi
+    done
+    if $addpath; then
+        PATH="${PATH:+$PATH:}$dir"
+    fi
+done
+export PATH
 
-options, other_args = parser.parse_known_args()
-rpaths, other_args = parse_rpaths(other_args)
+if [[ $mode == vcheck ]]; then
+    exec ${command} "$@"
+fi
 
-# Add dependencies' include and lib paths to our compiler flags.
-def add_if_dir(path_list, directory, index=None):
-    if os.path.isdir(directory):
-        if index is None:
-            path_list.append(directory)
-        else:
-            path_list.insert(index, directory)
+# Darwin's linker has a -r argument that merges object files together.
+# It doesn't work with -rpath.
+# This variable controls whether they are added.
+add_rpaths=true
+if [[ ($mode == ld || $mode == ccld) && "$SPACK_SHORT_SPEC" =~ "darwin" ]]; then
+    for arg in "$@"; do
+        if [[ ($arg == -r && $mode == ld) || ($arg == -Wl,-r && $mode == ccld) ]]; then
+            add_rpaths=false
+            break
+        fi
+    done
+fi
 
-for dep_dir in spack_deps:
-    add_if_dir(options.include_path, os.path.join(dep_dir, "include"))
-    add_if_dir(options.lib_path,     os.path.join(dep_dir, "lib"))
-    add_if_dir(options.lib_path,     os.path.join(dep_dir, "lib64"))
+# Save original command for debug logging
+input_command="$@"
+args=("$@")
 
-# Add our modified arguments to it.
-arguments  = ['-I%s' % path for path in options.include_path]
-arguments += other_args
-arguments += ['-L%s' % path for path in options.lib_path]
-arguments += ['-l%s' % path for path in options.libs]
+# Prepend cppflags, cflags, cxxflags, fcflags, fflags, and ldflags
 
-# Add rpaths to install dir and its dependencies.  We add both lib and lib64
-# here because we don't know which will be created.
-rpaths.extend(options.lib_path)
-rpaths.append('%s/lib'   % spack_prefix)
-rpaths.append('%s/lib64' % spack_prefix)
-if mode == ccld:
-    arguments += ['-Wl,-rpath,%s' % p for p in rpaths]
-elif mode == ld:
-    pairs = [('-rpath', '%s' % p) for p in rpaths]
-    arguments += [item for sublist in pairs for item in sublist]
+# Add ldflags
+case "$mode" in
+    ld|ccld)
+        args=(${SPACK_LDFLAGS[@]} "${args[@]}") ;;
+esac
 
-# Unset some pesky environment variables
-for var in ["LD_LIBRARY_PATH", "LD_RUN_PATH", "DYLD_LIBRARY_PATH"]:
-    if var in os.environ:
-        os.environ.pop(var)
+# Add compiler flags.
+case "$mode" in
+    cc|ccld)
+    # Add c, cxx, fc, and f flags
+        case $lang_flags in
+            C)
+                args=(${SPACK_CFLAGS[@]} "${args[@]}") ;;
+            CXX)
+                args=(${SPACK_CXXFLAGS[@]} "${args[@]}") ;;
+        esac
+        ;;
+esac
 
-# Ensure that the delegated command doesn't just call this script again.
-remove_paths = ['.'] + spack_env_path
-path = [p for p in get_path("PATH") if p not in remove_paths]
-os.environ["PATH"] = ":".join(path)
+# Add cppflags
+case "$mode" in
+    cpp|as|cc|ccld)
+        args=(${SPACK_CPPFLAGS[@]} "${args[@]}") ;;
+esac
 
-full_command = [command] + arguments
+case "$mode" in cc|ccld)
+        # Add fortran flags
+        case $lang_flags in
+            F)
+                args=(${SPACK_FFLAGS[@]} "${args[@]}") ;;
+        esac
+        ;;
+esac
 
-if spack_debug:
-    input_log = os.path.join(spack_debug_log_dir,  'spack-cc-%s.in.log' % spack_spec)
-    output_log = os.path.join(spack_debug_log_dir, 'spack-cc-%s.out.log' % spack_spec)
-    with closing(open(input_log, 'a')) as log:
-        args = [os.path.basename(sys.argv[0])] + sys.argv[1:]
-        log.write("%s\n" % " ".join(arg.replace(' ', r'\ ') for arg in args))
-    with closing(open(output_log, 'a')) as log:
-        log.write("%s\n" % " ".join(full_command))
+# Read spack dependencies from the path environment variable
+IFS=':' read -ra deps <<< "$SPACK_DEPENDENCIES"
+for dep in "${deps[@]}"; do
+    # Prepend include directories
+    if [[ -d $dep/include ]]; then
+        if [[ $mode == cpp || $mode == cc || $mode == as || $mode == ccld ]]; then
+            args=("-I$dep/include" "${args[@]}")
+        fi
+    fi
 
-rcode = subprocess.call(full_command)
-sys.exit(rcode)
+    # Prepend lib and RPATH directories
+    if [[ -d $dep/lib ]]; then
+        if [[ $mode == ccld ]]; then
+            if [[ $SPACK_RPATH_DEPS == *$dep* ]]; then
+                $add_rpaths && args=("$rpath$dep/lib" "${args[@]}")
+            fi
+            if [[ $SPACK_LINK_DEPS == *$dep* ]]; then
+                args=("-L$dep/lib" "${args[@]}")
+            fi
+        elif [[ $mode == ld ]]; then
+            if [[ $SPACK_RPATH_DEPS == *$dep* ]]; then
+                $add_rpaths && args=("-rpath" "$dep/lib" "${args[@]}")
+            fi
+            if [[ $SPACK_LINK_DEPS == *$dep* ]]; then
+                args=("-L$dep/lib" "${args[@]}")
+            fi
+        fi
+    fi
+
+    # Prepend lib64 and RPATH directories
+    if [[ -d $dep/lib64 ]]; then
+        if [[ $mode == ccld ]]; then
+            if [[ $SPACK_RPATH_DEPS == *$dep* ]]; then
+                $add_rpaths && args=("$rpath$dep/lib64" "${args[@]}")
+            fi
+            if [[ $SPACK_LINK_DEPS == *$dep* ]]; then
+                args=("-L$dep/lib64" "${args[@]}")
+            fi
+        elif [[ $mode == ld ]]; then
+            if [[ $SPACK_RPATH_DEPS == *$dep* ]]; then
+                $add_rpaths && args=("-rpath" "$dep/lib64" "${args[@]}")
+            fi
+            if [[ $SPACK_LINK_DEPS == *$dep* ]]; then
+                args=("-L$dep/lib64" "${args[@]}")
+            fi
+        fi
+    fi
+done
+
+# Include all -L's and prefix/whatever dirs in rpath
+if [[ $mode == ccld ]]; then
+    $add_rpaths && args=("$rpath$SPACK_PREFIX/lib64" "${args[@]}")
+    $add_rpaths && args=("$rpath$SPACK_PREFIX/lib"   "${args[@]}")
+elif [[ $mode == ld ]]; then
+    $add_rpaths && args=("-rpath" "$SPACK_PREFIX/lib64" "${args[@]}")
+    $add_rpaths && args=("-rpath" "$SPACK_PREFIX/lib"   "${args[@]}")
+fi
+
+# Set extra RPATHs
+IFS=':' read -ra extra_rpaths <<< "$SPACK_COMPILER_EXTRA_RPATHS"
+for extra_rpath in "${extra_rpaths[@]}"; do
+    if [[ $mode == ccld ]]; then
+        $add_rpaths && args=("$rpath$extra_rpath" "${args[@]}")
+    elif [[ $mode == ld ]]; then
+        $add_rpaths && args=("-rpath" "$extra_rpath" "${args[@]}")
+    fi
+done
+
+# Add SPACK_LDLIBS to args
+case "$mode" in
+    ld|ccld)
+        args=("${args[@]}" ${SPACK_LDLIBS[@]}) ;;
+esac
+
+full_command=("$command" "${args[@]}")
+
+# In test command mode, write out full command for Spack tests.
+if [[ $SPACK_TEST_COMMAND == dump-args ]]; then
+    echo "${full_command[@]}"
+    exit
+elif [[ -n $SPACK_TEST_COMMAND ]]; then
+    die "ERROR: Unknown test command"
+fi
+
+#
+# Write the input and output commands to debug logs if it's asked for.
+#
+if [[ $SPACK_DEBUG == TRUE ]]; then
+    input_log="$SPACK_DEBUG_LOG_DIR/spack-cc-$SPACK_SHORT_SPEC.in.log"
+    output_log="$SPACK_DEBUG_LOG_DIR/spack-cc-$SPACK_SHORT_SPEC.out.log"
+    echo "[$mode] $command $input_command" >> "$input_log"
+    echo "[$mode] ${full_command[@]}" >> "$output_log"
+fi
+
+exec "${full_command[@]}"

lib/spack/env/clang

@@ -1 +0,0 @@
-cc

lib/spack/env/clang++

@@ -1 +0,0 @@
-cc

lib/spack/env/clang/clang

@@ -0,0 +1 @@
+../cc

lib/spack/env/clang/clang++

@@ -0,0 +1 @@
+../cc

lib/spack/env/clang/gfortran

@@ -0,0 +1 @@
+../cc

lib/spack/env/cray/CC

@@ -0,0 +1 @@
+../cc

lib/spack/env/cray/cc

@@ -0,0 +1 @@
+../cc

lib/spack/env/cray/ftn

@@ -0,0 +1 @@
+../cc

lib/spack/env/craype/CC

@@ -0,0 +1 @@
+../cc

lib/spack/env/craype/cc

@@ -0,0 +1 @@
+../cc

lib/spack/env/craype/ftn

@@ -0,0 +1 @@
+../cc

lib/spack/env/g++

@@ -1 +0,0 @@
-cc

lib/spack/env/gcc

@@ -1 +0,0 @@
-cc

lib/spack/env/gcc/g++

@@ -0,0 +1 @@
+../cc

lib/spack/env/gcc/gcc

@@ -0,0 +1 @@
+../cc

lib/spack/env/gcc/gfortran

@@ -0,0 +1 @@
+../cc

lib/spack/env/intel/icc

@@ -0,0 +1 @@
+../cc

lib/spack/env/intel/icpc

@@ -0,0 +1 @@
+../cc

lib/spack/env/intel/ifort

@@ -0,0 +1 @@
+../cc

lib/spack/env/nag/nagfor

@@ -0,0 +1 @@
+../cc

lib/spack/env/pgi/pgc++

@@ -0,0 +1 @@
+../cc

lib/spack/env/pgi/pgcc

@@ -0,0 +1 @@
+../cc

lib/spack/env/pgi/pgfortran

@@ -0,0 +1 @@
+../cc

lib/spack/env/xl/xlc

@@ -0,0 +1 @@
+../cc