environments: update for pearc25

Author: cmelone

outputs/environments.sh

@@ -91,7 +91,7 @@ example --tee environments/env-swap-1      "spack env activate myproject"
 spack env activate myproject
 example environments/env-swap-1      "spack find"
 
-example environments/config-get-1    "spack config get"
+example environments/config-edit-1   'cat "$(spack location -e)/spack.yaml"'
 
 # The file is edited by hand here
 # We mock that by using `spack config add`

tutorial_environments.rst

@@ -167,38 +167,6 @@ Let's now confirm the contents of the environment using ``spack find``:
 
 We can see that the roots and all their dependencies have been installed.
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Creating an environment incrementally
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-We can also add and install specs to an environment incrementally. For example:
-
-.. code-block:: console
-
-   $ spack install --add tcl
-   $ spack install --add trilinos
-
-If we create environments incrementally, Spack ensures that already installed roots are not re-concretized.
-So, adding specs to an environment at a later point in time will not cause existing packages to rebuild.
-
-.. note::
-
-   Incrementally creating an environment may give us different package
-   versions from an environment created all at once.
-   We'll cover this later in the tutorial after we've discussed different
-   concretization strategies.
-
-   Further, there are two other advantages of concretizing and installing an
-   environment all at once:
-
-
-   * If you have a number of specs that can be installed together,
-     adding them first and installing them together enables them to
-     share dependencies and reduces total installation time.
-
-   * You can launch all builds in parallel by taking advantage of Spack's
-     `install-level build parallelism <https://spack.readthedocs.io/en/latest/packaging_guide.html#install-level-build-parallelism>`_.
-
 ^^^^^^^^^^^^^^
 Using Packages
 ^^^^^^^^^^^^^^
@@ -299,9 +267,14 @@ In this section, we'll learn how to enforce that all the packages in our environ
 
 We can customize the selection of the ``mpi`` provider using `concretization preferences <https://spack.readthedocs.io/en/latest/build_settings.html#concretization-preferences>`_ to change the behavior of the concretizer.
 
-Let's start by examining our environment's configuration using ``spack config get``:
+.. note::
+
+   Before proceeding, make sure your ``EDITOR`` environment variable
+   is set to the path of your preferred text editor.
+
+Let's start by examining our environment's configuration using ``spack config edit``:
 
-.. literalinclude:: outputs/environments/config-get-1.out
+.. literalinclude:: outputs/environments/config-edit-1.out
    :emphasize-lines: 8-13
 
 The output shows the special ``spack.yaml`` configuration file that Spack uses to store environment configurations.
@@ -331,14 +304,9 @@ The ``concretizer:unify:true`` setting controls how Spack resolves dependencies
 Editing environment configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. note::
+Let's edit ``spack.yaml`` to *require* ``mpich`` as our ``mpi`` provider.
 
-   Before proceeding, make sure your ``EDITOR`` environment variable
-   is set to the path of your preferred text editor.
-
-Let's edit ``spack.yaml`` to *require* ``mpich`` as our ``mpi`` provider using ``spack config edit``.
-
-You should now have the above file open in your editor.
+You should have the above file open in your editor.
 Change it to include the ``packages:mpi:require`` entry below:
 
 .. code-block:: yaml
@@ -388,10 +356,23 @@ Let's run ``spack concretize --force`` (or ``-f`` in short) to make Spack re-con
 
 All the specs are now concrete **and** ready to be installed with ``mpich`` as the MPI implementation.
 
-Re-concretization is sometimes also necessary when creating an environment *incrementally* with unification enabled.
-Spack makes sure that already concretized specs in the environment are not modified when adding something new.
 
-Adding and installing specs one by one leads to greedy concretization.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Creating an environment incrementally
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We can also add and install specs to an environment incrementally. For example:
+
+.. code-block:: console
+
+   $ spack install --add python
+   $ spack install --add py-numpy@1.20
+
+If we create environments incrementally, Spack ensures that already installed roots are not re-concretized.
+So, adding specs to an environment at a later point in time will not cause existing packages to rebuild.
+
+Adding and installing specs incrementally leads to greedy concretization, meaning that the environment may concain different package versions compared to an environment created all at once.
+
 When you first install ``python`` in an environment, Spack will pick a recent version for it.
 If you then add ``py-numpy``, it may be in conflict with the ``python`` version already installed, and fail to concretize:
 
@@ -403,6 +384,16 @@ The solution is to re-concretize the environment as a whole, which causes ``pyth
 .. literalinclude:: outputs/environments/incremental-2.out
    :language: console
 
+.. note::
+   There are advantages to concretizing and installing an environment all at once:
+
+   * If you have a number of specs that can be installed together,
+     adding them first and installing them together enables them to
+     share dependencies and reduces total installation time.
+
+   * You can launch all builds in parallel by taking advantage of Spack's
+     `install-level build parallelism <https://spack.readthedocs.io/en/latest/packaging_guide.html#install-level-build-parallelism>`_.
+
 ------------------------
 Building in environments
 ------------------------