docs: add environments tutorial

- tutorial goes through three sections:
  - installing and uninstalling environments
  - dealing with many specs
  - spack.yaml and spack.lock and workflows

2 files changed, 821 insertions, 4 deletions

diff --git a/lib/spack/docs/tutorial.rst b/lib/spack/docs/tutorial.rst
index c3ddf98cfb..28a5353111 100644
--- a/lib/spack/docs/tutorial.rst
+++ b/lib/spack/docs/tutorial.rst
@@ -43,9 +43,10 @@ correspond to sections in the slides above.
   1. :ref:`basics-tutorial`
   2. :ref:`configs-tutorial`
   3. :ref:`packaging-tutorial`
-  4. :ref:`build-systems-tutorial`
-  5. :ref:`advanced-packaging-tutorial`
-  6. :ref:`modules-tutorial`
+  4. :ref:`environments-tutorial`
+  5. :ref:`modules-tutorial`
+  6. :ref:`build-systems-tutorial`
+  7. :ref:`advanced-packaging-tutorial`
 
 Full contents:
 
@@ -53,6 +54,7 @@ Full contents:
    tutorial_basics
    tutorial_configuration
    tutorial_packaging
+   tutorial_environments
+   tutorial_modules
    tutorial_buildsystems
    tutorial_advanced_packaging
-   tutorial_modules
diff --git a/lib/spack/docs/tutorial_environments.rst b/lib/spack/docs/tutorial_environments.rst
new file mode 100644
index 0000000000..9ad2e9567c
--- /dev/null
+++ b/lib/spack/docs/tutorial_environments.rst
@@ -0,0 +1,815 @@
+.. Copyright 2013-2018 Lawrence Livermore National Security, LLC and other
+   Spack Project Developers. See the top-level COPYRIGHT file for details.
+
+   SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+.. _environments-tutorial:
+
+================================================
+Environments, ``spack.yaml``, and ``spack.lock``
+================================================
+
+We've shown you how to install and remove packages with Spack.  You can
+use :ref:`cmd-spack-install` to install packages,
+:ref:`cmd-spack-uninstall` to remove them, and :ref:`cmd-spack-find` to
+look at and query what is installed.  We've also shown you how to
+customize Spack's installation with configuration files like
+:ref:`packages.yaml <build-settings>`.
+
+If you build a lot of software, or if you work on multiple projects,
+managing everything in one place can be overwhelming. The default ``spack
+find`` output may contain many packages, but you may want to *just* focus
+on packages a particular project.  Moreover, you may want to include
+special configuration with your package groups, e.g., to build all the
+packages in the same group the same way.
+
+Spack **environments** provide a way to handle these problems.
+
+-------------------
+Environment basics
+-------------------
+
+Let's look at the output of ``spack find`` at this point in the tutorial.
+
+.. code-block:: console
+
+   $ bin/spack find
+   ==> 70 installed packages
+   -- linux-ubuntu16.04-x86_64 / clang@3.8.0-2ubuntu4 --------------
+   tcl@8.6.8  zlib@1.2.8  zlib@1.2.11
+
+   -- linux-ubuntu16.04-x86_64 / gcc@4.7 ---------------------------
+   zlib@1.2.11
+
+   -- linux-ubuntu16.04-x86_64 / gcc@5.4.0 -------------------------
+   adept-utils@1.0.1  hdf5@1.10.4          mpc@1.1.0               perl@5.26.2
+   autoconf@2.69      hdf5@1.10.4          mpfr@3.1.6              pkgconf@1.4.2
+   automake@1.16.1    hdf5@1.10.4          mpich@3.2.1             readline@7.0
+   boost@1.68.0       hwloc@1.11.9         mpileaks@1.0            suite-sparse@5.3.0
+   bzip2@1.0.6        hypre@2.15.1         mumps@5.1.1             tar@1.30
+   callpath@1.0.4     hypre@2.15.1         mumps@5.1.1             tcl@8.6.8
+   cmake@3.12.3       isl@0.18             ncurses@6.1             tcl@8.6.8
+   diffutils@3.6      libdwarf@20180129    netcdf@4.6.1            texinfo@6.5
+   dyninst@9.3.2      libiberty@2.31.1     netcdf@4.6.1            trilinos@12.12.1
+   elfutils@0.173     libpciaccess@0.13.5  netlib-scalapack@2.0.2  trilinos@12.12.1
+   findutils@4.6.0    libsigsegv@2.11      netlib-scalapack@2.0.2  util-macros@1.19.1
+   gcc@7.2.0          libtool@2.4.6        numactl@2.0.11          xz@5.2.4
+   gdbm@1.14.1        libxml2@2.9.8        openblas@0.3.3          zlib@1.2.8
+   gettext@0.19.8.1   m4@1.4.18            openmpi@3.1.3           zlib@1.2.8
+   glm@0.9.7.1        matio@1.5.9          openssl@1.0.2o          zlib@1.2.11
+   gmp@6.1.2          matio@1.5.9          parmetis@4.0.3
+   hdf5@1.10.4        metis@5.1.0          parmetis@4.0.3
+
+
+This is a complete, but cluttered view.  There are packages built with
+both ``openmpi`` and ``mpich``, as well as multiple variants of other
+packages, like ``zlib``.  The query mechanism we learned about in ``spack
+find`` can help, but it would be nice if we could start from a clean
+slate without losing what we've already done.
+
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Creating and activating environments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``spack env`` command can help.  Let's create a new environment:
+
+.. code-block:: console
+
+   $ spack env create myproject
+   ==> Created environment 'myproject' in ~/spack/var/spack/environments/myproject
+
+An environment is a virtualized ``spack`` instance that you can use for a
+specific purpose.  You can see the environments we've created so far like this:
+
+.. code-block:: console
+
+   $ spack env list
+   ==> 1 environments
+       myproject
+
+And you can **activate** an environment with ``spack env activate``:
+
+.. code-block:: console
+
+   $ spack env activate myproject
+
+Once you enter an environment, ``spack find`` shows only what is in the
+current environment.  That's nothing, so far:
+
+.. code-block:: console
+
+   $ spack find
+   ==> In environment myproject
+   ==> No root specs
+
+   ==> 0 installed packages
+
+The ``spack find`` output is still *slightly* different.  It tells you
+that you're in the ``myproject`` environment, so that you don't panic
+when you see that there is nothing installed.  It also says that there
+are *no root specs*.  We'll get back to what that means later.
+
+If you *only* want to check what environment you are in, you can use
+``spack env status``:
+
+.. code-block:: console
+
+   $ spack env status
+   ==> In environment myproject
+
+And, if you want to leave this environment and go back to normal Spack,
+you can use ``spack env deactivate``.  We like to use the
+``despacktivate`` alias (which Spack sets up automatically) for short:
+
+.. code-block:: console
+
+   $ despacktivate     # short alias for `spack env deactivate`
+   $ spack env status
+   ==> No active environment
+   $ spack find
+   netcdf@4.6.1            readline@7.0        zlib@1.2.11
+   diffutils@3.6      hdf5@1.10.4       m4@1.4.18            netcdf@4.6.1            suite-sparse@5.3.0
+   dyninst@10.0.0     hwloc@1.11.9      matio@1.5.9          netlib-scalapack@2.0.2  tar@1.30
+   elfutils@0.173     hypre@2.15.1      matio@1.5.9          netlib-scalapack@2.0.2  tcl@8.6.8
+   findutils@4.6.0    hypre@2.15.1      metis@5.1.0          numactl@2.0.11          tcl@8.6.8
+   gcc@7.2.0          intel-tbb@2019    mpc@1.1.0            openblas@0.3.3          texinfo@6.5~
+
+
+^^^^^^^^^^^^^^^^^^^
+Installing packages
+^^^^^^^^^^^^^^^^^^^
+
+Ok, now that we understand how creation and activation work, let's go
+back to ``myproject`` and *install* a few packages:
+
+.. code-block:: console
+
+   $ spack env activate myproject
+   $ spack install tcl
+   ==> tcl is already installed in ~/spack/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/tcl-8.6.8-qhwyccywhx2i6s7ob2gvjrjtj3rnfuqt
+   $ spack install trilinos
+   ==> trilinos is already installed in ~/spack/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/trilinos-12.12.1-rlsruavxqvwk2tgxzxboclbo6ykjf54r
+   $ spack find
+   ==> In environment myproject
+   ==> Root specs
+   tcl  trilinos
+
+   ==> 22 installed packages
+   -- linux-ubuntu16.04-x86_64 / gcc@5.4.0 -------------------------
+   boost@1.68.0  hwloc@1.11.9         matio@1.5.9   netlib-scalapack@2.0.2  parmetis@4.0.3      xz@5.2.4
+   bzip2@1.0.6   hypre@2.15.1         metis@5.1.0   numactl@2.0.11          suite-sparse@5.3.0  zlib@1.2.11
+   glm@0.9.7.1   libpciaccess@0.13.5  mumps@5.1.1   openblas@0.3.3          tcl@8.6.8
+   hdf5@1.10.4   libxml2@2.9.8        netcdf@4.6.1  openmpi@3.1.3           trilinos@12.12.1
+
+We've installed ``tcl`` and ``trilinos`` in our environment, along with
+all of their dependencies.  We call ``tcl`` and ``trilinos`` the
+**roots** because we asked for them explicitly.  The other 20 packages
+listed under "installed packages" are present because they were needed as
+dependencies.  So, these are the roots of the packages' dependency graph.
+
+The "<package> is already installed" messages above are generated because
+we already installed these packages in previous steps of the tutorial,
+and we don't have to rebuild them to put them in an environment.
+
+Now let's create *another* project.  We'll call this one ``myproject2``:
+
+.. code-block:: console
+
+   $ spack env create myproject2
+   ==> Created environment 'myproject2' in ~/spack/var/spack/environments/myproject2
+   $ spack env activate myproject2
+   $ spack install hdf5
+   ==> hdf5 is already installed in ~/spack/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/hdf5-1.10.4-ozyvmhzdew66byarohm4p36ep7wtcuiw
+   $ spack install trilinos
+   ==> trilinos is already installed in ~/spack/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/trilinos-12.12.1-rlsruavxqvwk2tgxzxboclbo6ykjf54r
+   $ spack find
+   ==> In environment myproject2
+   ==> Root specs
+   hdf5  trilinos
+
+   ==> 22 installed packages
+   -- linux-ubuntu16.04-x86_64 / gcc@5.4.0 -------------------------
+   boost@1.68.0  hdf5@1.10.4          libxml2@2.9.8  netcdf@4.6.1            openmpi@3.1.3       xz@5.2.4
+   bzip2@1.0.6   hwloc@1.11.9         matio@1.5.9    netlib-scalapack@2.0.2  parmetis@4.0.3      zlib@1.2.11
+   glm@0.9.7.1   hypre@2.15.1         metis@5.1.0    numactl@2.0.11          suite-sparse@5.3.0
+   hdf5@1.10.4   libpciaccess@0.13.5  mumps@5.1.1    openblas@0.3.3          trilinos@12.12.1
+
+Now we have two environments: one with ``tcl`` and ``trilinos``, and
+another with ``hdf5`` and ``trilinos``.
+
+We can uninstall trilinos from ``myproject2`` as you would expect:
+
+.. code-block:: console
+
+   $ spack uninstall trilinos
+   ==> The following packages will be uninstalled:
+
+       -- linux-ubuntu16.04-x86_64 / gcc@5.4.0 -------------------------
+       rlsruav trilinos@12.12.1%gcc~alloptpkgs+amesos+amesos2+anasazi+aztec+belos+boost build_type=RelWithDebInfo ~cgns~complex~dtk+epetra+epetraext+exodus+explicit_template_instantiation~float+fortran~fortrilinos+gtest+hdf5+hypre+ifpack+ifpack2~intrepid~intrepid2~isorropia+kokkos+metis~minitensor+ml+muelu+mumps~nox~openmp~phalanx~piro~pnetcdf~python~rol~rythmos+sacado~shards+shared~stk+suite-sparse~superlu~superlu-dist~teko~tempus+teuchos+tpetra~x11~xsdkflags~zlib+zoltan+zoltan2
+   ==> Do you want to proceed? [y/N] y
+   $ spack find
+   ==> In environment myproject2
+   ==> Root specs
+   hdf5
+
+   ==> 8 installed packages
+   -- linux-ubuntu16.04-x86_64 / gcc@5.4.0 -------------------------
+   hdf5@1.10.4   libpciaccess@0.13.5  numactl@2.0.11  xz@5.2.4
+   hwloc@1.11.9  libxml2@2.9.8        openmpi@3.1.3   zlib@1.2.11
+
+Now there is only one root spec, ``hdf5``, which requires fewer
+additional dependencies.
+
+However, we still needed ``trilinos`` for the ``myproject`` environment!
+What happened to it?  Let's switch back and see.
+
+.. code-block:: console
+
+   $ despacktivate
+   $ spack env activate myproject
+   $ spack find
+   ==> In environment myproject
+   ==> Root specs
+   tcl  trilinos
+
+   ==> 22 installed packages
+   -- linux-ubuntu16.04-x86_64 / gcc@5.4.0 -------------------------
+   boost@1.68.0  hwloc@1.11.9         matio@1.5.9   netlib-scalapack@2.0.2  parmetis@4.0.3      xz@5.2.4
+   bzip2@1.0.6   hypre@2.15.1         metis@5.1.0   numactl@2.0.11          suite-sparse@5.3.0  zlib@1.2.11
+   glm@0.9.7.1   libpciaccess@0.13.5  mumps@5.1.1   openblas@0.3.3          tcl@8.6.8
+   hdf5@1.10.4   libxml2@2.9.8        netcdf@4.6.1  openmpi@3.1.3           trilinos@12.12.1
+
+
+Spack is smart enough to realize that ``trilinos`` is still present in
+the other environment.  Trilinos won't *actually* be uninstalled unless
+it is no longer needed by any environments or packages.  If it is still
+needed, it is only removed from the environment.
+
+-------------------------------
+Dealing with many specs at once
+-------------------------------
+
+In the above examples, we just used ``install`` and ``uninstall``.  There
+are other ways to deal with groups of packages, as well.
+
+^^^^^^^^^^^^^
+Adding specs
+^^^^^^^^^^^^^
+
+Let's go back to our first ``myproject`` environment and *add* a few specs instead of installing them:
+
+.. code-block:: console
+
+   $ spack add hdf5
+   ==> Adding hdf5 to environment myproject
+   $ spack add gmp
+   ==> Adding mumps to environment myproject
+   $ spack find
+   ==> In environment myproject
+   ==> Root specs
+   gmp  hdf5  tcl  trilinos
+
+   ==> 22 installed packages
+   -- linux-ubuntu16.04-x86_64 / gcc@5.4.0 -------------------------
+   boost@1.68.0  hwloc@1.11.9         matio@1.5.9   netlib-scalapack@2.0.2  parmetis@4.0.3      xz@5.2.4
+   bzip2@1.0.6   hypre@2.15.1         metis@5.1.0   numactl@2.0.11          suite-sparse@5.3.0  zlib@1.2.11
+   glm@0.9.7.1   libpciaccess@0.13.5  mumps@5.1.1   openblas@0.3.3          tcl@8.6.8
+   hdf5@1.10.4   libxml2@2.9.8        netcdf@4.6.1  openmpi@3.1.3           trilinos@12.12.1
+
+Let's take a close look at what happened.  The two packages we added,
+``hdf5`` and ``gmp``, are present, but they're not installed in the
+environment yet.  ``spack add`` just adds *roots* to the environment, but
+it does not automatically install them.
+
+We can install *all* the as-yet uninstalled packages in an environment by
+simply running ``spack install`` with no arguments:
+
+.. code-block:: console
+
+   $ spack install
+   ==> Concretizing hdf5
+   [+]  ozyvmhz  hdf5@1.10.4%gcc@5.4.0~cxx~debug~fortran~hl+mpi+pic+shared~szip~threadsafe arch=linux-ubuntu16.04-x86_64
+   [+]  3njc4q5      ^openmpi@3.1.3%gcc@5.4.0~cuda+cxx_exceptions fabrics= ~java~legacylaunchers~memchecker~pmi schedulers= ~sqlite3~thread_multiple+vt arch=linux-ubuntu16.04-x86_64
+   [+]  43tkw5m          ^hwloc@1.11.9%gcc@5.4.0~cairo~cuda+libxml2+pci+shared arch=linux-ubuntu16.04-x86_64
+   [+]  5urc6tc              ^libpciaccess@0.13.5%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  o2pfwjf                  ^libtool@2.4.6%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  suf5jtc                      ^m4@1.4.18%gcc@5.4.0 patches=3877ab548f88597ab2327a2230ee048d2d07ace1062efe81fc92e91b7f39cd00,c0a408fbffb7255fcc75e26bd8edab116fc81d216bfd18b473668b7739a4158e,fc9b61654a3ba1a8d6cd78ce087e7c96366c290bc8d2c299f09828d793b853c8 +sigsegv arch=linux-ubuntu16.04-x86_64
+   [+]  fypapcp                          ^libsigsegv@2.11%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  fovrh7a                  ^pkgconf@1.4.2%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  milz7fm                  ^util-macros@1.19.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  wpexsph              ^libxml2@2.9.8%gcc@5.4.0~python arch=linux-ubuntu16.04-x86_64
+   [+]  teneqii                  ^xz@5.2.4%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  5nus6kn                  ^zlib@1.2.11%gcc@5.4.0+optimize+pic+shared arch=linux-ubuntu16.04-x86_64
+   [+]  ft463od              ^numactl@2.0.11%gcc@5.4.0 patches=592f30f7f5f757dfc239ad0ffd39a9a048487ad803c26b419e0f96b8cda08c1a arch=linux-ubuntu16.04-x86_64
+   [+]  3sx2gxe                  ^autoconf@2.69%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  ic2kyoa                      ^perl@5.26.2%gcc@5.4.0+cpanm patches=0eac10ed90aeb0459ad8851f88081d439a4e41978e586ec743069e8b059370ac +shared+threads arch=linux-ubuntu16.04-x86_64
+   [+]  q4fpyuo                          ^gdbm@1.14.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  nxhwrg7                              ^readline@7.0%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  3o765ou                                  ^ncurses@6.1%gcc@5.4.0~symlinks~termlib arch=linux-ubuntu16.04-x86_64
+   [+]  rymw7im                  ^automake@1.16.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   ==> Concretizing gmp
+   [+]  qc4qcfz  gmp@6.1.2%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  3sx2gxe      ^autoconf@2.69%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  suf5jtc          ^m4@1.4.18%gcc@5.4.0 patches=3877ab548f88597ab2327a2230ee048d2d07ace1062efe81fc92e91b7f39cd00,c0a408fbffb7255fcc75e26bd8edab116fc81d216bfd18b473668b7739a4158e,fc9b61654a3ba1a8d6cd78ce087e7c96366c290bc8d2c299f09828d793b853c8 +sigsegv arch=linux-ubuntu16.04-x86_64
+   [+]  fypapcp              ^libsigsegv@2.11%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  ic2kyoa          ^perl@5.26.2%gcc@5.4.0+cpanm patches=0eac10ed90aeb0459ad8851f88081d439a4e41978e586ec743069e8b059370ac +shared+threads arch=linux-ubuntu16.04-x86_64
+   [+]  q4fpyuo              ^gdbm@1.14.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  nxhwrg7                  ^readline@7.0%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  3o765ou                      ^ncurses@6.1%gcc@5.4.0~symlinks~termlib arch=linux-ubuntu16.04-x86_64
+   [+]  fovrh7a                          ^pkgconf@1.4.2%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  rymw7im      ^automake@1.16.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  o2pfwjf      ^libtool@2.4.6%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   ==> Installing environment myproject
+   ==> tcl is already installed in ~/spack/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/tcl-8.6.8-qhwyccywhx2i6s7ob2gvjrjtj3rnfuqt
+   ==> trilinos is already installed in ~/spack/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/trilinos-12.12.1-rlsruavxqvwk2tgxzxboclbo6ykjf54r
+   ==> hdf5 is already installed in ~/spack/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/hdf5-1.10.4-ozyvmhzdew66byarohm4p36ep7wtcuiw
+   ==> gmp is already installed in ~/spack/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/gmp-6.1.2-qc4qcfz4monpllc3nqupdo7vwinf73sw
+
+Spack will concretize the new roots, and install everything you added to
+the environment.  Now we can see the installed roots in the output of
+``spack find``:
+
+.. code-block:: console
+
+   $ spack find
+   ==> In environment myproject
+   ==> Root specs
+   gmp  hdf5  tcl  trilinos
+
+   ==> 24 installed packages
+   -- linux-ubuntu16.04-x86_64 / gcc@5.4.0 -------------------------
+   boost@1.68.0  hdf5@1.10.4   libpciaccess@0.13.5  mumps@5.1.1             openblas@0.3.3      tcl@8.6.8
+   bzip2@1.0.6   hdf5@1.10.4   libxml2@2.9.8        netcdf@4.6.1            openmpi@3.1.3       trilinos@12.12.1
+   glm@0.9.7.1   hwloc@1.11.9  matio@1.5.9          netlib-scalapack@2.0.2  parmetis@4.0.3      xz@5.2.4
+   gmp@6.1.2     hypre@2.15.1  metis@5.1.0          numactl@2.0.11          suite-sparse@5.3.0  zlib@1.2.11
+
+We can build whole environments this way, by adding specs and installing
+all at once, or we can install them with the usual ``install`` and
+``uninstall`` portions.  The advantage to doing them all at once is that
+we don't have to write a script outside of Spack to automate this, and we
+can kick off a large build of many packages easily.
+
+^^^^^^^^^^^^^^^^^^^^^
+Configuration
+^^^^^^^^^^^^^^^^^^^^^
+
+So far, ``myproject`` does not have any special configuration associated
+with it.  The specs concretize using Spack's defaults:
+
+.. code-block:: console
+
+   $ spack spec hypre
+   Input spec
+   --------------------------------
+   hypre
+
+   Concretized
+   --------------------------------
+   hypre@2.15.1%gcc@5.4.0~debug~int64+internal-superlu+mpi+shared arch=linux-ubuntu16.04-x86_64
+       ^openblas@0.3.3%gcc@5.4.0 cpu_target= ~ilp64 patches=47cfa7a952ac7b2e4632c73ae199d69fb54490627b66a62c681e21019c4ddc9d,714aea33692304a50bd0ccde42590c176c82ded4a8ac7f06e573dc8071929c33 +pic+shared threads=none ~virtual_machine arch=linux-ubuntu16.04-x86_64
+       ^openmpi@3.1.3%gcc@5.4.0~cuda+cxx_exceptions fabrics= ~java~legacylaunchers~memchecker~pmi schedulers= ~sqlite3~thread_multiple+vt arch=linux-ubuntu16.04-x86_64
+           ^hwloc@1.11.9%gcc@5.4.0~cairo~cuda+libxml2+pci+shared arch=linux-ubuntu16.04-x86_64
+               ^libpciaccess@0.13.5%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+                   ^libtool@2.4.6%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+                       ^m4@1.4.18%gcc@5.4.0 patches=3877ab548f88597ab2327a2230ee048d2d07ace1062efe81fc92e91b7f39cd00,c0a408fbffb7255fcc75e26bd8edab116fc81d216bfd18b473668b7739a4158e,fc9b61654a3ba1a8d6cd78ce087e7c96366c290bc8d2c299f09828d793b853c8 +sigsegv arch=linux-ubuntu16.04-x86_64
+                           ^libsigsegv@2.11%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+                   ^pkgconf@1.4.2%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+                   ^util-macros@1.19.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+               ^libxml2@2.9.8%gcc@5.4.0~python arch=linux-ubuntu16.04-x86_64
+                   ^xz@5.2.4%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+                   ^zlib@1.2.11%gcc@5.4.0+optimize+pic+shared arch=linux-ubuntu16.04-x86_64
+               ^numactl@2.0.11%gcc@5.4.0 patches=592f30f7f5f757dfc239ad0ffd39a9a048487ad803c26b419e0f96b8cda08c1a arch=linux-ubuntu16.04-x86_64
+                   ^autoconf@2.69%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+                       ^perl@5.26.2%gcc@5.4.0+cpanm patches=0eac10ed90aeb0459ad8851f88081d439a4e41978e586ec743069e8b059370ac +shared+threads arch=linux-ubuntu16.04-x86_64
+                           ^gdbm@1.14.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+                               ^readline@7.0%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+                                   ^ncurses@6.1%gcc@5.4.0~symlinks~termlib arch=linux-ubuntu16.04-x86_64
+                   ^automake@1.16.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+
+You may want to add extra configuration to your environment.  You can see
+how your environment is configured using ``spack config get``:
+
+.. code-block:: console
+
+   $ spack config get
+   # This is a Spack Environment file.
+   #
+   # It describes a set of packages to be installed, along with
+   # configuration settings.
+   spack:
+     # add package specs to the `specs` list
+     specs: [tcl, trilinos, hdf5, gmp]
+
+It turns out that this is a special configuration format where Spack
+stores the state for the environment. Currently, the file is just a
+``spack:`` header and a list of ``specs``.  These are the roots.
+
+You can edit this file to add your own custom configuration.  Spack
+provides a shortcut to do that:
+
+.. code-block:: console
+
+   spack config edit
+
+You should now see the same file, and edit it to look like this:
+
+.. code-block:: yaml
+
+   # This is a Spack Environment file.
+   #
+   # It describes a set of packages to be installed, along with
+   # configuration settings.
+   spack:
+     packages:
+       all:
+         providers:
+           mpi: [mpich]
+
+     # add package specs to the `specs` list
+     specs: [tcl, trilinos, hdf5, gmp]
+
+Now if we run ``spack spec`` again in the environment, specs will concretize with ``mpich`` as the MPI implementation:
+
+.. code-block:: console
+
+   $ spack spec hypre
+   Input spec
+   --------------------------------
+   hypre
+
+   Concretized
+   --------------------------------
+   hypre@2.15.1%gcc@5.4.0~debug~int64+internal-superlu+mpi+shared arch=linux-ubuntu16.04-x86_64
+       ^mpich@3.2.1%gcc@5.4.0 device=ch3 +hydra netmod=tcp +pmi+romio~verbs arch=linux-ubuntu16.04-x86_64
+           ^findutils@4.6.0%gcc@5.4.0 patches=84b916c0bf8c51b7e7b28417692f0ad3e7030d1f3c248ba77c42ede5c1c5d11e,bd9e4e5cc280f9753ae14956c4e4aa17fe7a210f55dd6c84aa60b12d106d47a2 arch=linux-ubuntu16.04-x86_64
+               ^autoconf@2.69%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+                   ^m4@1.4.18%gcc@5.4.0 patches=3877ab548f88597ab2327a2230ee048d2d07ace1062efe81fc92e91b7f39cd00,c0a408fbffb7255fcc75e26bd8edab116fc81d216bfd18b473668b7739a4158e,fc9b61654a3ba1a8d6cd78ce087e7c96366c290bc8d2c299f09828d793b853c8 +sigsegv arch=linux-ubuntu16.04-x86_64
+                       ^libsigsegv@2.11%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+                   ^perl@5.26.2%gcc@5.4.0+cpanm patches=0eac10ed90aeb0459ad8851f88081d439a4e41978e586ec743069e8b059370ac +shared+threads arch=linux-ubuntu16.04-x86_64
+                       ^gdbm@1.14.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+                           ^readline@7.0%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+                               ^ncurses@6.1%gcc@5.4.0~symlinks~termlib arch=linux-ubuntu16.04-x86_64
+                                   ^pkgconf@1.4.2%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+               ^automake@1.16.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+               ^libtool@2.4.6%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+               ^texinfo@6.5%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+       ^openblas@0.3.3%gcc@5.4.0 cpu_target= ~ilp64 patches=47cfa7a952ac7b2e4632c73ae199d69fb54490627b66a62c681e21019c4ddc9d,714aea33692304a50bd0ccde42590c176c82ded4a8ac7f06e573dc8071929c33 +pic+shared threads=none ~virtual_machine arch=linux-ubuntu16.04-x86_64
+
+In addition to the ``specs`` section, an environment's configuration can
+contain any of the configuration options from Spack's various config
+sections. You can add custom repositories, a custom install location,
+custom compilers, or custom external packages, in addition to the ``package``
+preferences we show here.
+
+But now we have a problem.  We already installed part of this environment
+with openmpi, but now we want to install it with ``mpich``.
+
+You can run ``spack concretize`` inside of an environment to concretize
+all of its specs.  We can run it here:
+
+.. code-block:: console
+
+   $ spack concretize -f
+   ==> Concretizing tcl
+   [+]  qhwyccy  tcl@8.6.8%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  5nus6kn      ^zlib@1.2.11%gcc@5.4.0+optimize+pic+shared arch=linux-ubuntu16.04-x86_64
+   ==> Concretizing trilinos
+   [+]  kqc52mo  trilinos@12.12.1%gcc@5.4.0~alloptpkgs+amesos+amesos2+anasazi+aztec+belos+boost build_type=RelWithDebInfo ~cgns~complex~dtk+epetra+epetraext+exodus+explicit_template_instantiation~float+fortran~fortrilinos+gtest+hdf5+hypre+ifpack+ifpack2~intrepid~intrepid2~isorropia+kokkos+metis~minitensor+ml+muelu+mumps~nox~openmp~phalanx~piro~pnetcdf~python~rol~rythmos+sacado~shards+shared~stk+suite-sparse~superlu~superlu-dist~teko~tempus+teuchos+tpetra~x11~xsdkflags~zlib+zoltan+zoltan2 arch=linux-ubuntu16.04-x86_64
+   [+]  zbgfxap      ^boost@1.68.0%gcc@5.4.0+atomic+chrono~clanglibcpp cxxstd=default +date_time~debug+exception+filesystem+graph~icu+iostreams+locale+log+math~mpi+multithreaded~numpy patches=2ab6c72d03dec6a4ae20220a9dfd5c8c572c5294252155b85c6874d97c323199 +program_options~python+random+regex+serialization+shared+signals~singlethreaded+system~taggedlayout+test+thread+timer~versionedlayout+wave arch=linux-ubuntu16.04-x86_64
+   [+]  ufczdvs          ^bzip2@1.0.6%gcc@5.4.0+shared arch=linux-ubuntu16.04-x86_64
+   [+]  2rhuivg              ^diffutils@3.6%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  5nus6kn          ^zlib@1.2.11%gcc@5.4.0+optimize+pic+shared arch=linux-ubuntu16.04-x86_64
+   [+]  otafqzh      ^cmake@3.12.3%gcc@5.4.0~doc+ncurses+openssl+ownlibs patches=dd3a40d4d92f6b2158b87d6fb354c277947c776424aa03f6dc8096cf3135f5d0 ~qt arch=linux-ubuntu16.04-x86_64
+   [+]  3o765ou          ^ncurses@6.1%gcc@5.4.0~symlinks~termlib arch=linux-ubuntu16.04-x86_64
+   [+]  fovrh7a              ^pkgconf@1.4.2%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  b4y3w3b          ^openssl@1.0.2o%gcc@5.4.0+systemcerts arch=linux-ubuntu16.04-x86_64
+   [+]  ic2kyoa              ^perl@5.26.2%gcc@5.4.0+cpanm patches=0eac10ed90aeb0459ad8851f88081d439a4e41978e586ec743069e8b059370ac +shared+threads arch=linux-ubuntu16.04-x86_64
+   [+]  q4fpyuo                  ^gdbm@1.14.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  nxhwrg7                      ^readline@7.0%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  jnw622j      ^glm@0.9.7.1%gcc@5.4.0 build_type=RelWithDebInfo arch=linux-ubuntu16.04-x86_64
+   [+]  xxd7syh      ^hdf5@1.10.4%gcc@5.4.0~cxx~debug~fortran+hl+mpi+pic+shared~szip~threadsafe arch=linux-ubuntu16.04-x86_64
+   [+]  p3f7p2r          ^mpich@3.2.1%gcc@5.4.0 device=ch3 +hydra netmod=tcp +pmi+romio~verbs arch=linux-ubuntu16.04-x86_64
+   [+]  d4iajxs              ^findutils@4.6.0%gcc@5.4.0 patches=84b916c0bf8c51b7e7b28417692f0ad3e7030d1f3c248ba77c42ede5c1c5d11e,bd9e4e5cc280f9753ae14956c4e4aa17fe7a210f55dd6c84aa60b12d106d47a2 arch=linux-ubuntu16.04-x86_64
+   [+]  3sx2gxe                  ^autoconf@2.69%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  suf5jtc                      ^m4@1.4.18%gcc@5.4.0 patches=3877ab548f88597ab2327a2230ee048d2d07ace1062efe81fc92e91b7f39cd00,c0a408fbffb7255fcc75e26bd8edab116fc81d216bfd18b473668b7739a4158e,fc9b61654a3ba1a8d6cd78ce087e7c96366c290bc8d2c299f09828d793b853c8 +sigsegv arch=linux-ubuntu16.04-x86_64
+   [+]  fypapcp                          ^libsigsegv@2.11%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  rymw7im                  ^automake@1.16.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  o2pfwjf                  ^libtool@2.4.6%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  zs7a2pc                  ^texinfo@6.5%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  obewuoz      ^hypre@2.15.1%gcc@5.4.0~debug~int64~internal-superlu+mpi+shared arch=linux-ubuntu16.04-x86_64
+   [+]  cyeg2yi          ^openblas@0.3.3%gcc@5.4.0 cpu_target= ~ilp64 patches=47cfa7a952ac7b2e4632c73ae199d69fb54490627b66a62c681e21019c4ddc9d,714aea33692304a50bd0ccde42590c176c82ded4a8ac7f06e573dc8071929c33 +pic+shared threads=none ~virtual_machine arch=linux-ubuntu16.04-x86_64
+   [+]  gvyqldh      ^matio@1.5.9%gcc@5.4.0+hdf5+shared+zlib arch=linux-ubuntu16.04-x86_64
+   [+]  3wnvp4j      ^metis@5.1.0%gcc@5.4.0 build_type=Release ~gdb~int64 patches=4991da938c1d3a1d3dea78e49bbebecba00273f98df2a656e38b83d55b281da1 ~real64+shared arch=linux-ubuntu16.04-x86_64
+   [+]  cumcj5a      ^mumps@5.1.1%gcc@5.4.0+complex+double+float~int64~metis+mpi~parmetis~ptscotch~scotch+shared arch=linux-ubuntu16.04-x86_64
+   [+]  p7iln2p          ^netlib-scalapack@2.0.2%gcc@5.4.0 build_type=RelWithDebInfo ~pic+shared arch=linux-ubuntu16.04-x86_64
+   [+]  wmmx5sg      ^netcdf@4.6.1%gcc@5.4.0~dap~hdf4 maxdims=1024 maxvars=8192 +mpi~parallel-netcdf+shared arch=linux-ubuntu16.04-x86_64
+   [+]  jehtata      ^parmetis@4.0.3%gcc@5.4.0 build_type=RelWithDebInfo ~gdb patches=4f892531eb0a807eb1b82e683a416d3e35154a455274cf9b162fb02054d11a5b,50ed2081bc939269689789942067c58b3e522c269269a430d5d34c00edbc5870,704b84f7c7444d4372cb59cca6e1209df4ef3b033bc4ee3cf50f369bce972a9d +shared arch=linux-ubuntu16.04-x86_64
+   [+]  zaau4ki      ^suite-sparse@5.3.0%gcc@5.4.0~cuda~openmp+pic~tbb arch=linux-ubuntu16.04-x86_64
+   ==> Concretizing hdf5
+    -   zjgyn3w  hdf5@1.10.4%gcc@5.4.0~cxx~debug~fortran~hl+mpi+pic+shared~szip~threadsafe arch=linux-ubuntu16.04-x86_64
+   [+]  p3f7p2r      ^mpich@3.2.1%gcc@5.4.0 device=ch3 +hydra netmod=tcp +pmi+romio~verbs arch=linux-ubuntu16.04-x86_64
+   [+]  d4iajxs          ^findutils@4.6.0%gcc@5.4.0 patches=84b916c0bf8c51b7e7b28417692f0ad3e7030d1f3c248ba77c42ede5c1c5d11e,bd9e4e5cc280f9753ae14956c4e4aa17fe7a210f55dd6c84aa60b12d106d47a2 arch=linux-ubuntu16.04-x86_64
+   [+]  3sx2gxe              ^autoconf@2.69%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  suf5jtc                  ^m4@1.4.18%gcc@5.4.0 patches=3877ab548f88597ab2327a2230ee048d2d07ace1062efe81fc92e91b7f39cd00,c0a408fbffb7255fcc75e26bd8edab116fc81d216bfd18b473668b7739a4158e,fc9b61654a3ba1a8d6cd78ce087e7c96366c290bc8d2c299f09828d793b853c8 +sigsegv arch=linux-ubuntu16.04-x86_64
+   [+]  fypapcp                      ^libsigsegv@2.11%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  ic2kyoa                  ^perl@5.26.2%gcc@5.4.0+cpanm patches=0eac10ed90aeb0459ad8851f88081d439a4e41978e586ec743069e8b059370ac +shared+threads arch=linux-ubuntu16.04-x86_64
+   [+]  q4fpyuo                      ^gdbm@1.14.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  nxhwrg7                          ^readline@7.0%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  3o765ou                              ^ncurses@6.1%gcc@5.4.0~symlinks~termlib arch=linux-ubuntu16.04-x86_64
+   [+]  fovrh7a                                  ^pkgconf@1.4.2%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  rymw7im              ^automake@1.16.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  o2pfwjf              ^libtool@2.4.6%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  zs7a2pc              ^texinfo@6.5%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  5nus6kn      ^zlib@1.2.11%gcc@5.4.0+optimize+pic+shared arch=linux-ubuntu16.04-x86_64
+   ==> Concretizing gmp
+   [+]  qc4qcfz  gmp@6.1.2%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  3sx2gxe      ^autoconf@2.69%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  suf5jtc          ^m4@1.4.18%gcc@5.4.0 patches=3877ab548f88597ab2327a2230ee048d2d07ace1062efe81fc92e91b7f39cd00,c0a408fbffb7255fcc75e26bd8edab116fc81d216bfd18b473668b7739a4158e,fc9b61654a3ba1a8d6cd78ce087e7c96366c290bc8d2c299f09828d793b853c8 +sigsegv arch=linux-ubuntu16.04-x86_64
+   [+]  fypapcp              ^libsigsegv@2.11%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  ic2kyoa          ^perl@5.26.2%gcc@5.4.0+cpanm patches=0eac10ed90aeb0459ad8851f88081d439a4e41978e586ec743069e8b059370ac +shared+threads arch=linux-ubuntu16.04-x86_64
+   [+]  q4fpyuo              ^gdbm@1.14.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  nxhwrg7                  ^readline@7.0%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  3o765ou                      ^ncurses@6.1%gcc@5.4.0~symlinks~termlib arch=linux-ubuntu16.04-x86_64
+   [+]  fovrh7a                          ^pkgconf@1.4.2%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  rymw7im      ^automake@1.16.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  o2pfwjf      ^libtool@2.4.6%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+
+Now, all the specs in the environemnt are concrete and ready to be
+installed wiht ``mpich`` as the MPI immplementation.
+
+Normally, we could just run ``spack config edit``, edit the environment
+configuration, ``spack add`` some specs, and ``install``.
+
+But, when we already have installed packages in the environment, we have
+to force everything in the environment to be re-concretized using ``spack
+concretize -f``.  *Then* we can re-run ``spack install``.
+
+
+-----------------------------------
+``spack.yaml`` and ``spack.lock``
+-----------------------------------
+
+So far we've shown you how to interact with environments from the command
+line, but they also have a file-based interface that can be used by
+developers and admins to manage workflows for projects.
+
+In this section we'll dive a little deeper to see how environments are
+implemented, and how you could use this in your day-to-day development.
+
+^^^^^^^^^^^^^^
+``spack.yaml``
+^^^^^^^^^^^^^^
+
+Earlier, we changed an environment's configuration using ``spack config
+edit``.  We were actually editing a special file called ``spack.yaml``.
+Let's take a look.
+
+We can get directly to the current environment's location using ``spack cd``:
+
+.. code-block:: console
+
+   $ spack cd -e myproject
+   $ pwd
+   ~/spack/var/spack/environments/myproject
+   $ ls
+   spack.lock  spack.yaml
+
+We notice two things here.  First, the environment is just a directory
+inside of ``var/spack/environments`` within the Spack installation.
+Second, it contains two important files: ``spack.yaml`` and
+``spack.lock``.
+
+``spack.yaml`` is the configuration file for environments that we've
+already seen, but it does not *have* to live inside Spack.  If you create
+an environment using ``spack env create``, it is *managed* by
+Spack in the ``var/spack/environments`` directory, and you can refer to
+it by name.
+
+You can actually put a ``spack.yaml`` file *anywhere*, and you can use it
+to bundle an environment, or a list of dependencies to install, with your
+project.  Let's make a simple project:
+
+.. code-block:: console
+
+   $ cd
+   $ mkdir code
+   $ cd code
+   $ spack env create -d .
+   ==> Created environment in ~/code
+
+Here, we made a new directory called *code*, and we used the ``-d``
+option to create an environment in it.
+
+What really happened?
+
+.. code-block:: console
+
+   $ ls
+   spack.yaml
+   $ cat spack.yaml
+   # This is a Spack Environment file.
+   #
+   # It describes a set of packages to be installed, along with
+   # configuration settings.
+   spack:
+     # add package specs to the `specs` list
+     specs: []
+
+Spack just created a ``spack.yaml`` file in the code directory, with an
+empty list of root specs.  Now we have a Spack environment, *in a
+directory*, that we can use to manage dependencies.  Suppose your project
+depends on ``boost``, ``trilinos``, and ``openmpi``.  You can add these
+to your spec list:
+
+.. code-block:: yaml
+
+   # This is a Spack Environment file.
+   #
+   # It describes a set of packages to be installed, along with
+   # configuration settings.
+   spack:
+     # add package specs to the `specs` list
+     specs:
+     - boost
+     - trilinos
+     - openmpi
+
+And now *anyone* who uses the *code* repository can use this format to
+install the project's dependencies.  They need only clone the repository,
+``cd`` into it, and type ``spack install``:
+
+.. code-block:: console
+
+   $ spack install
+   ==> Concretizing boost
+   [+]  zbgfxap  boost@1.68.0%gcc@5.4.0+atomic+chrono~clanglibcpp cxxstd=default +date_time~debug+exception+filesystem+graph~icu+iostreams+locale+log+math~mpi+multithreaded~numpy patches=2ab6c72d03dec6a4ae20220a9dfd5c8c572c5294252155b85c6874d97c323199 +program_options~python+random+regex+serialization+shared+signals~singlethreaded+system~taggedlayout+test+thread+timer~versionedlayout+wave arch=linux-ubuntu16.04-x86_64
+   [+]  ufczdvs      ^bzip2@1.0.6%gcc@5.4.0+shared arch=linux-ubuntu16.04-x86_64
+   [+]  2rhuivg          ^diffutils@3.6%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  5nus6kn      ^zlib@1.2.11%gcc@5.4.0+optimize+pic+shared arch=linux-ubuntu16.04-x86_64
+   ==> Concretizing trilinos
+   [+]  rlsruav  trilinos@12.12.1%gcc@5.4.0~alloptpkgs+amesos+amesos2+anasazi+aztec+belos+boost build_type=RelWithDebInfo ~cgns~complex~dtk+epetra+epetraext+exodus+explicit_template_instantiation~float+fortran~fortrilinos+gtest+hdf5+hypre+ifpack+ifpack2~intrepid~intrepid2~isorropia+kokkos+metis~minitensor+ml+muelu+mumps~nox~openmp~phalanx~piro~pnetcdf~python~rol~rythmos+sacado~shards+shared~stk+suite-sparse~superlu~superlu-dist~teko~tempus+teuchos+tpetra~x11~xsdkflags~zlib+zoltan+zoltan2 arch=linux-ubuntu16.04-x86_64
+   [+]  zbgfxap      ^boost@1.68.0%gcc@5.4.0+atomic+chrono~clanglibcpp cxxstd=default +date_time~debug+exception+filesystem+graph~icu+iostreams+locale+log+math~mpi+multithreaded~numpy patches=2ab6c72d03dec6a4ae20220a9dfd5c8c572c5294252155b85c6874d97c323199 +program_options~python+random+regex+serialization+shared+signals~singlethreaded+system~taggedlayout+test+thread+timer~versionedlayout+wave arch=linux-ubuntu16.04-x86_64
+   [+]  ufczdvs          ^bzip2@1.0.6%gcc@5.4.0+shared arch=linux-ubuntu16.04-x86_64
+   [+]  2rhuivg              ^diffutils@3.6%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  5nus6kn          ^zlib@1.2.11%gcc@5.4.0+optimize+pic+shared arch=linux-ubuntu16.04-x86_64
+   [+]  otafqzh      ^cmake@3.12.3%gcc@5.4.0~doc+ncurses+openssl+ownlibs patches=dd3a40d4d92f6b2158b87d6fb354c277947c776424aa03f6dc8096cf3135f5d0 ~qt arch=linux-ubuntu16.04-x86_64
+   [+]  3o765ou          ^ncurses@6.1%gcc@5.4.0~symlinks~termlib arch=linux-ubuntu16.04-x86_64
+   [+]  fovrh7a              ^pkgconf@1.4.2%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  b4y3w3b          ^openssl@1.0.2o%gcc@5.4.0+systemcerts arch=linux-ubuntu16.04-x86_64
+   [+]  ic2kyoa              ^perl@5.26.2%gcc@5.4.0+cpanm patches=0eac10ed90aeb0459ad8851f88081d439a4e41978e586ec743069e8b059370ac +shared+threads arch=linux-ubuntu16.04-x86_64
+   [+]  q4fpyuo                  ^gdbm@1.14.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  nxhwrg7                      ^readline@7.0%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  jnw622j      ^glm@0.9.7.1%gcc@5.4.0 build_type=RelWithDebInfo arch=linux-ubuntu16.04-x86_64
+   [+]  oqwnui7      ^hdf5@1.10.4%gcc@5.4.0~cxx~debug~fortran+hl+mpi+pic+shared~szip~threadsafe arch=linux-ubuntu16.04-x86_64
+   [+]  3njc4q5          ^openmpi@3.1.3%gcc@5.4.0~cuda+cxx_exceptions fabrics= ~java~legacylaunchers~memchecker~pmi schedulers= ~sqlite3~thread_multiple+vt arch=linux-ubuntu16.04-x86_64
+   [+]  43tkw5m              ^hwloc@1.11.9%gcc@5.4.0~cairo~cuda+libxml2+pci+shared arch=linux-ubuntu16.04-x86_64
+   [+]  5urc6tc                  ^libpciaccess@0.13.5%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  o2pfwjf                      ^libtool@2.4.6%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  suf5jtc                          ^m4@1.4.18%gcc@5.4.0 patches=3877ab548f88597ab2327a2230ee048d2d07ace1062efe81fc92e91b7f39cd00,c0a408fbffb7255fcc75e26bd8edab116fc81d216bfd18b473668b7739a4158e,fc9b61654a3ba1a8d6cd78ce087e7c96366c290bc8d2c299f09828d793b853c8 +sigsegv arch=linux-ubuntu16.04-x86_64
+   [+]  fypapcp                              ^libsigsegv@2.11%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  milz7fm                      ^util-macros@1.19.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  wpexsph                  ^libxml2@2.9.8%gcc@5.4.0~python arch=linux-ubuntu16.04-x86_64
+   [+]  teneqii                      ^xz@5.2.4%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  ft463od                  ^numactl@2.0.11%gcc@5.4.0 patches=592f30f7f5f757dfc239ad0ffd39a9a048487ad803c26b419e0f96b8cda08c1a arch=linux-ubuntu16.04-x86_64
+   [+]  3sx2gxe                      ^autoconf@2.69%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  rymw7im                      ^automake@1.16.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  fshksdp      ^hypre@2.15.1%gcc@5.4.0~debug~int64~internal-superlu+mpi+shared arch=linux-ubuntu16.04-x86_64
+   [+]  cyeg2yi          ^openblas@0.3.3%gcc@5.4.0 cpu_target= ~ilp64 patches=47cfa7a952ac7b2e4632c73ae199d69fb54490627b66a62c681e21019c4ddc9d,714aea33692304a50bd0ccde42590c176c82ded4a8ac7f06e573dc8071929c33 +pic+shared threads=none ~virtual_machine arch=linux-ubuntu16.04-x86_64
+   [+]  lmzdgss      ^matio@1.5.9%gcc@5.4.0+hdf5+shared+zlib arch=linux-ubuntu16.04-x86_64
+   [+]  3wnvp4j      ^metis@5.1.0%gcc@5.4.0 build_type=Release ~gdb~int64 patches=4991da938c1d3a1d3dea78e49bbebecba00273f98df2a656e38b83d55b281da1 ~real64+shared arch=linux-ubuntu16.04-x86_64
+   [+]  acsg2dz      ^mumps@5.1.1%gcc@5.4.0+complex+double+float~int64~metis+mpi~parmetis~ptscotch~scotch+shared arch=linux-ubuntu16.04-x86_64
+   [+]  wotpfwf          ^netlib-scalapack@2.0.2%gcc@5.4.0 build_type=RelWithDebInfo ~pic+shared arch=linux-ubuntu16.04-x86_64
+   [+]  mhm4izp      ^netcdf@4.6.1%gcc@5.4.0~dap~hdf4 maxdims=1024 maxvars=8192 +mpi~parallel-netcdf+shared arch=linux-ubuntu16.04-x86_64
+   [+]  uv6h3sq      ^parmetis@4.0.3%gcc@5.4.0 build_type=RelWithDebInfo ~gdb patches=4f892531eb0a807eb1b82e683a416d3e35154a455274cf9b162fb02054d11a5b,50ed2081bc939269689789942067c58b3e522c269269a430d5d34c00edbc5870,704b84f7c7444d4372cb59cca6e1209df4ef3b033bc4ee3cf50f369bce972a9d +shared arch=linux-ubuntu16.04-x86_64
+   [+]  zaau4ki      ^suite-sparse@5.3.0%gcc@5.4.0~cuda~openmp+pic~tbb arch=linux-ubuntu16.04-x86_64
+   ==> Concretizing openmpi
+   [+]  3njc4q5  openmpi@3.1.3%gcc@5.4.0~cuda+cxx_exceptions fabrics= ~java~legacylaunchers~memchecker~pmi schedulers= ~sqlite3~thread_multiple+vt arch=linux-ubuntu16.04-x86_64
+   [+]  43tkw5m      ^hwloc@1.11.9%gcc@5.4.0~cairo~cuda+libxml2+pci+shared arch=linux-ubuntu16.04-x86_64
+   [+]  5urc6tc          ^libpciaccess@0.13.5%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  o2pfwjf              ^libtool@2.4.6%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  suf5jtc                  ^m4@1.4.18%gcc@5.4.0 patches=3877ab548f88597ab2327a2230ee048d2d07ace1062efe81fc92e91b7f39cd00,c0a408fbffb7255fcc75e26bd8edab116fc81d216bfd18b473668b7739a4158e,fc9b61654a3ba1a8d6cd78ce087e7c96366c290bc8d2c299f09828d793b853c8 +sigsegv arch=linux-ubuntu16.04-x86_64
+   [+]  fypapcp                      ^libsigsegv@2.11%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  fovrh7a              ^pkgconf@1.4.2%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  milz7fm              ^util-macros@1.19.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  wpexsph          ^libxml2@2.9.8%gcc@5.4.0~python arch=linux-ubuntu16.04-x86_64
+   [+]  teneqii              ^xz@5.2.4%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  5nus6kn              ^zlib@1.2.11%gcc@5.4.0+optimize+pic+shared arch=linux-ubuntu16.04-x86_64
+   [+]  ft463od          ^numactl@2.0.11%gcc@5.4.0 patches=592f30f7f5f757dfc239ad0ffd39a9a048487ad803c26b419e0f96b8cda08c1a arch=linux-ubuntu16.04-x86_64
+   [+]  3sx2gxe              ^autoconf@2.69%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  ic2kyoa                  ^perl@5.26.2%gcc@5.4.0+cpanm patches=0eac10ed90aeb0459ad8851f88081d439a4e41978e586ec743069e8b059370ac +shared+threads arch=linux-ubuntu16.04-x86_64
+   [+]  q4fpyuo                      ^gdbm@1.14.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  nxhwrg7                          ^readline@7.0%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   [+]  3o765ou                              ^ncurses@6.1%gcc@5.4.0~symlinks~termlib arch=linux-ubuntu16.04-x86_64
+   [+]  rymw7im              ^automake@1.16.1%gcc@5.4.0 arch=linux-ubuntu16.04-x86_64
+   ==> Installing environment ~/code
+   ==> boost is already installed in ~/spack/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/boost-1.68.0-zbgfxapchxa4awxdwpleubfuznblxzvt
+   ==> trilinos is already installed in ~/spack/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/trilinos-12.12.1-rlsruavxqvwk2tgxzxboclbo6ykjf54r
+   ==> openmpi is already installed in ~/spack/opt/spack/linux-ubuntu16.04-x86_64/gcc-5.4.0/openmpi-3.1.3-3njc4q5pqdpptq6jvqjrezkffwokv2sx
+
+
+Spack concretizes the specs in the ``spack.yaml`` file and installs them.
+
+What happened here?  If you ``cd`` into a directory tha has a
+``spack.yaml`` file in it, Spack considers this directory's environment
+to be activated.  The directory does not have to live within Spack; it
+can be anywhere.
+
+So, from ``~/code``, we can actually manipulate ``spack.yaml`` using
+``spack add`` and ``spack remove`` (just like managed environments):
+
+.. code-block:: console
+
+   $ spack add hdf5@5.5.1
+   ==> Adding hdf5 to environment ~/code
+   $ cat spack.yaml
+   # This is a Spack Environment file.
+   #
+   # It describes a set of packages to be installed, along with
+   # configuration settings.
+   spack:
+     # add package specs to the `specs` list
+     specs:
+     - boost
+     - trilinos
+     - openmpi
+     - hdf5@5.5.1
+
+   $ spack remove hdf5
+   ==> Removing hdf5 from environment ~/code
+   $ cat spack.yaml
+   # This is a Spack Environment file.
+   #
+   # It describes a set of packages to be installed, along with
+   # configuration settings.
+   spack:
+     # add package specs to the `specs` list
+     specs:
+     - boost
+     - trilinos
+     - openmpi
+
+
+^^^^^^^^^^^^^^
+``spack.lock``
+^^^^^^^^^^^^^^
+
+Ok, we've covered managed environments, environments in directories, and
+the last thing we'll cover is ``spack.lock``. You may remember that when
+we ran ``spack install``, Spack concretized all the specs in the
+``spack.yaml`` file and installed them.
+
+Whenever we concretize Specs in an environment, all concrete specs in the
+environment are written out to a ``spack.lock`` file *alongside*
+``spack.yaml``.  The ``spack.lock`` file is not really human-readable
+like the ``spack.yaml`` file.  It is a ``json`` format that contains all
+the information that we need to ``reproduce`` the build of an
+environment:
+
+.. code-block:: console
+
+   $ head spack.lock
+   {
+     "concrete_specs": {
+      "teneqii2xv5u6zl5r6qi3pwurc6pmypz": {
+       "xz": {
+         "version": "5.2.4",
+         "arch": {
+           "platform": "linux",
+           "platform_os": "ubuntu16.04",
+         "target": "x86_64"
+    },
+    ...
+
+``spack.yaml`` and ``spack.lock`` correspond to two fundamental concepts
+in Spack, but for environments:
+
+  * ``spack.yaml`` is the set of *abstract* specs and configuration that
+    you want to install.
+  * ``spack.lock`` is the set of all fully *concretized* specs generated
+    from concretizing ``spack.yaml``
+
+Using either of these, you can recreate an environment that someone else
+built.  ``spack env create`` takes an extra optional argument, which can
+be either a ``spack.yaml`` or a ``spack.lock`` file:
+
+.. code-block:: console
+
+   $ spack env create my-project spack.yaml
+
+   $ spack env create my-project spack.lock
+
+Both of these create a new environment called ``my-project``, but which
+one you choose to use depends on your needs:
+
+  1.  copying the yaml file allows someone else to build your *requirements*,
+      potentially a different way.
+
+  2. copying the lock file allows someone else to rebuild your
+     *installation* exactly as you built it.
+
+The first use case can *re-concretize* the same specs on new platforms in
+order to build, but it will preserve the abstract requirements.  The
+second use case (currently) requires you to be on the same machine, but
+it retains all decisions made during concretization and is faithful to a
+prior install.