summaryrefslogtreecommitdiff
path: root/lib
diff options
context:
space:
mode:
authorTodd Gamblin <tgamblin@llnl.gov>2018-11-12 05:18:38 -0600
committerTodd Gamblin <tgamblin@llnl.gov>2018-11-12 05:57:08 -0600
commitf92349ff8ca2acb340a480aebeff85528715cc7b (patch)
treeee1dee6dab12a91b9fcf9f24ecf8605462403c63 /lib
parenta1676ab012bf92b1736b0029841e49b88b6f23a0 (diff)
downloadspack-f92349ff8ca2acb340a480aebeff85528715cc7b.tar.gz
spack-f92349ff8ca2acb340a480aebeff85528715cc7b.tar.bz2
spack-f92349ff8ca2acb340a480aebeff85528715cc7b.tar.xz
spack-f92349ff8ca2acb340a480aebeff85528715cc7b.zip
docs: add environments tutorial
- tutorial goes through three sections: - installing and uninstalling environments - dealing with many specs - spack.yaml and spack.lock and workflows
Diffstat (limited to 'lib')
-rw-r--r--lib/spack/docs/tutorial.rst10
-rw-r--r--lib/spack/docs/tutorial_environments.rst815
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.