Additional edits to environments for readability enhancements

Author: alecbcs

tutorial_environments.rst

@@ -132,14 +132,14 @@ After deactivating, we can see everything installed in this Spack instance:
 Installing packages
 ^^^^^^^^^^^^^^^^^^^
 
-Now that we understand how creation and activation work, let's go back to our ``myproject`` enviornment and *install* a couple of packages, specifically, ``tcl`` and ``trilinos``.
+Now that we understand how creation and activation work, let's go back to our ``myproject`` environment and *install* a couple of packages, specifically, ``tcl`` and ``trilinos``.
 
 Let's try the usual install commands we learned earlier:
 
 .. literalinclude:: outputs/environments/env-fail-install-1.out
    :language: console
 
-Environments are special in that we must *add* specs to the an environment before we can install them. This additional step helps prevent us from accidentally modifying a shared enviornment when installing new software.
+Environments are special in that we must *add* specs to the an environment before we can install them. This additional step helps prevent us from accidentally modifying a shared environment when installing new software.
 
 ``spack add`` allows us to queue up several specs to be installed together.
 Let's try it:
@@ -148,7 +148,7 @@ Let's try it:
    :language: console
 
 Now, ``tcl`` and ``trilinos`` have been registered as **root specs** in our environment. **Root specs** are packages that we've explicitly requested to be installed in an environment.
-They're called **"roots"** because they sit at the top of the dependency graph—when Spack installs these packages, with their respective depenedency packages sitting below them.
+They're called **"roots"** because they sit at the top of the dependency graph—when Spack installs these packages, with their respective dependency packages sitting below them.
 
 Now, let's install:
 
@@ -202,13 +202,21 @@ So, adding specs to an environment at a later point in time will not cause exist
 Using packages
 ^^^^^^^^^^^^^^
 
-Environments provide a convenient way for using installed packages.
-When we run ``spack env activate`` Spack by default prepends packages in the environment to our ``PATH``, ``MANPATH``, and ``CMAKE_PREFIX_PATH`` environment variables.
+Spack environments provide a convenient way to use your installed packages by automatically making them available in your shell environment.
+This is accomplished through a feature called **environment views**.
 
-Let's try it out to get a better sense of how views are constructed and added to our shell environment.
+An environment view is a directory structure mirroring a standard linux root filesystem with directories like ``/bin`` and ``/usr`` that contain symbolic links to all the packages installed in your Spack environment.
+When you activate an environment with ``spack env activate``, Spack automatically:
 
-We just installed ``tcl`` into our ``myproject`` environment. ``Tcl`` includes a shell-like application called ``tclsh``.
-To can see the path to ``tclsh`` let's use ``which``:
+* Prepends the view's ``bin`` directory to your ``PATH`` environment variable
+* Adds the view's ``man`` directory to your ``MANPATH`` for manual pages
+* Updates ``CMAKE_PREFIX_PATH`` to include the view's root directory
+
+This means that executables, libraries, and other files from your environment's packages become immediately accessible from your command line, just as if they were installed system-wide.
+
+Let's explore how views work using the ``tcl`` package we just installed in our ``myproject`` environment. The Tcl package includes a shell-like application called ``tclsh``.
+
+To can see the path to ``tclsh`` let's use the ``which`` command:
 
 .. literalinclude:: outputs/environments/use-tcl-1.out
    :language: console
@@ -225,89 +233,98 @@ We can now run ``tclsh`` just like you would any other program that is in your p
     hello world!
     % exit
 
-^^^^^^^^^^^^^^^^^^^^^
-Uninstalling packages
-^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Uninstalling Packages from Environments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+One of Spack's key features is that you can safely uninstall packages from specific environments without affecting other environments.
+This works because Spack environments only create links to shared package installations—they don't contain the actual package files.
 
-We can uninstall packages from an environment without affecting other environments.
-This is possible since, while Spack shares common installations, environments only link to those installations.
+Let's demonstrate this capability by creating a second environment.
+Imagine we have two projects:
 
-Let's demonstrate this feature by creating another environment.
-Suppose ``myproject`` requires ``trilinos`` but we have another project that has it installed but no longer requires it.
+* ``myproject`` - requires ``trilinos``
+* ``myproject2`` - previously needed ``trilinos`` but no longer requires it
 
-Start by creating a ``myproject2`` environment with the installed packages ``scr`` and ``trilinos``.
+Let's start by creating the ``myproject2`` environment and installing both ``scr`` and ``trilinos``:
 
 .. literalinclude:: outputs/environments/env-create-2.out
    :language: console
 
 
-Now we have two environments.
-The ``myproject`` environment has ``tcl`` and ``trilinos`` while the ``myproject2`` environment has ``scr`` and ``trilinos``.
+Now we have two environments with different package combinations:
 
-Now let's try to uninstall ``trilinos`` from ``myproject2`` and review the contents of the environment:
+* The ``myproject`` environment contains ``tcl`` and ``trilinos``
+* The ``myproject2`` environment contains ``scr`` and ``trilinos``
+
+Now let's attempt to uninstall ``trilinos`` from ``myproject2`` and examine what happens:
 
 .. literalinclude:: outputs/environments/env-uninstall-1.out
    :language: console
 
 
-We can see that ``trilinos`` won't be uninstalled because it is still referenced in another environment managed by Spack.
-If we want to remove it from the roots list, we need to use ``spack remove``:
+Notice that ``trilinos`` won't be uninstalled because it's still referenced in ``myproject``. This safety feature prevents accidental removal of packages that other environments depend on.
+
+Instead, if we want to remove ``trilinos`` from the ``myproject2`` environment (without affecting it in other environments), we need to use ``spack remove``:
 
 .. literalinclude:: outputs/environments/env-remove-1.out
    :language: console
 
-When the spec is first removed, we see that it is no longer a root but is still present in the installed specs.
-Once we reconcretize, the vestigial spec is removed.
-Now, it is no longer a root and will need to be re-added before being installed as part of this environment.
+After running ``spack remove`` we'll see that ``trilinos`` is no longer a root but is still present in the installed specs.
+Reconcretizing the environment, we'll see the vestigial ``trilinos`` and its dependencies will be pruned and will no longer be listed in the environment at all.
 
-We know ``trilinos`` is still needed for the ``myproject`` environment, so let's switch back to confirm that it is still installed in that environment.
+We know ``trilinos`` is still needed for the ``myproject`` environment, so let's switch back to that environment to confirm that it is still installed.
 
 .. literalinclude:: outputs/environments/env-swap-1.out
    :language: console
 
 
 Phew!
-We see that ``myproject`` still has ``trilinos`` as a root spec.
-Spack uses reference counting to ensure that we don't remove ``trilinos`` when it is still needed by ``myproject``.
+We can see that ``myproject`` still has ``trilinos`` as a root spec.
 
 .. note::
 
-   Trilinos would only have been uninstalled by Spack if it were
-   no longer needed by any environments or their package dependencies.
-
-You can also uninstall a package and remove it from the environment in one go with ``spack uninstall --remove trilinos``.
+   You can also uninstall a package and remove it from the environment
+   in one go with ``spack uninstall --remove trilinos``.
 
 -----------------------
 The ``spack.yaml`` file
 -----------------------
 
-An environment is more than just a list of root specs.
-It includes *configuration* settings that affect the way Spack behaves when the environment is activated.
-So far, ``myproject`` relies on configuration defaults that can be overridden.
-Here we'll look at how to add specs and ensure all the packages depending on ``mpi`` build with ``mpich``.
+An environment is more than just a list of root specs -- it includes **configuration settings** that control how Spack behaves when the environment it activated.
+So far, ``myproject`` relies on configuration defaults, but these can be overridden to customize our environment's behavior.
+
+In this section, we'll learn how to enforce that all the packages in our environment depending on ``mpi`` build with ``mpich`` by modifying our configuration.
+
 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 looking at the configuration of our environment using ``spack config get``:
+Let's start by examining our environment's configuration using ``spack config get``:
 
 .. literalinclude:: outputs/environments/config-get-1.out
    :emphasize-lines: 8-13
 
-The output shows the special ``spack.yaml`` configuration file that Spack uses to store the environment configuration.
+The output shows the special ``spack.yaml`` configuration file that Spack uses to store environment configurations.
 
 There are several important parts of this file:
 
-* ``specs:``: the list of specs to install
-* ``view:``: this controls whether the environment has a *view*. You can
-  set it to ``false`` to disable view generation.
-* ``concretizer:unify:``: This controls how the specs in the environment
-  are concretized.
+* ``specs:``: The list of package specs to install in the environment.
+* ``view:``: Controls whether the environment generates a *view* (the
+  directory tree with symlinks to installed packages we discussed earlier).
+* ``concretizer:unify:``: Determines how package specs in the environment are
+  concretized together to reduce duplicated dependencies when possible.
 
-The ``specs`` list should look familiar; these are the specs we've been modifying with ``spack add``.
+The ``specs`` list should look familiar -- these are the package specs we've been modifying previously with ``spack add`` and ``spack install``.
 
-``concretizer:unify:true``, the default, means that they are concretized *together*, so that there is only one version of each package in the environment.
-Other options for ``unify`` are ``false`` and ``when_possible``. ``false`` means that the specs are concretized *independently*, so that there may be multiple versions of the same package in the environment. ``when_possible`` lies between these options.
-In this case, Spack will unify as many packages in the environment, but will not fail if it cannot unify all of them.
+The ``concretizer:unify:true`` setting controls how Spack resolves dependencies across packages specs in an environment:
 
+* ``true`` (default): specs are concretized *together*, ensuring
+  there is only one version of each package in the environment.
+* ``false``: specs are concretized *independently* from each other,
+  potentially allowing multiple versions of the package to appear in the
+  environment twice.
+* ``when_possible``: A middle ground -- Spack attempts to unify dependencies
+  as possible but will backoff to allow duplicates when root specs require
+  incompatible versions of dependencies.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Editing environment configuration