docs: Add documentation for views in environments

2 files changed, 145 insertions, 3 deletions

diff --git a/lib/spack/docs/environments.rst b/lib/spack/docs/environments.rst
index 2f619bf5d8..aa925de07c 100644
--- a/lib/spack/docs/environments.rst
+++ b/lib/spack/docs/environments.rst
@@ -631,5 +631,147 @@ The valid variables for a ``when`` clause are:
 Environment-managed Views
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Code for Spack Environments is in code review at the
-moment. Documentation will be updated when the code is finalized.
+Spack Environments can define filesystem views of their software,
+which are maintained as packages are installed and uninstalled from
+the Environment. Filesystem views provide an access point for packages
+from the filesystem for users who want to access those packages
+directly. For more information on filesystem views, see the section
+:ref:`filesystem-views`.
+
+Spack Environment managed views are updated every time the environment
+is written out to the lock file ``spack.lock``, so the concrete
+environment and the view are always compatible.
+
+"""""""""""""""""""""""""""""
+Configuring environment views
+"""""""""""""""""""""""""""""
+
+The Spack Environment manifest file has a top-level keyword
+``view``. Each entry under that heading is a view descriptor, headed
+by a name. The view descriptor contains the root of the view, and
+optionally the projections for the view, and ``select`` and
+``exclude`` lists for the view. For example, in the following manifest
+file snipped we define a view named ``mpis``, rooted at
+``/path/to/view`` in which all projections use the package name,
+version, and compiler name to determine the path for a given
+package. This view selects all packages that depend on MPI, and
+excludes those built with the PGI compiler at version 18.5.
+
+.. code-block:: yaml
+
+   spack:
+     ...
+     view:
+       mpis:
+         root: /path/to/view
+         select: [^mpi]
+         exclude: ['%pgi@18.5']
+         projections:
+           all: ${package}/${version}-${compilername}
+
+For more information on using view projections, see the section on
+:ref:`adding_projections_to_views`. The default for the ``select`` and
+``exclude`` values is to select everything and exclude nothing. The
+default projection is the default view projection (``{}``).
+
+Any number of views may be defined under the ``view`` heading in a
+Spack Environment.
+
+There are two shorthands for environments with a single view. If the
+environment at ``/path/to/env`` has a single view, with a root at
+``/path/to/env/.spack-env/view``, with default selection and exclusion
+and the default projection, we can put ``view: True`` in the
+environment manifest. Similarly, if the environment has a view with a
+different root, but default selection, exclusion, and projections, the
+manifest can say ``view: /path/to/view``. These views are
+automatically named ``default``, so that
+
+.. code-block:: yaml
+
+   spack:
+     ...
+     view: True
+
+is equivalent to
+
+.. code-block:: yaml
+
+   spack:
+     ...
+     view:
+       default:
+         root: .spack-env/view
+
+and
+
+.. code-block:: yaml
+
+   spack:
+     ...
+     view: /path/to/view
+
+is equivalent to
+
+.. code-block:: yaml
+
+   spack:
+     ...
+     view:
+       default:
+         root: /path/to/view
+
+By default, Spack environments are configured with ``view: True`` in
+the manifest. Environments can be configured without views using
+``view: False``. For backwards compatibility reasons, environments
+with no ``view`` key are treated the same as ``view: True``.
+
+From the command line, the ``spack env create`` command takes an
+argument ``with-view [PATH]`` that sets the path for a single, default
+view. If no path is specified, the default path is used (``view:
+True``). The argument ``without-view`` can be used to create an
+environment without any view configured.
+
+The ``spack env view`` command can be used to change the manage views
+of an Environment. The subcommand ``spack env view enable`` will add a
+view named ``default`` to an environment. It takes an optional
+argument to specify the path for the new default view. The subcommand
+``spack env view disable`` will remove the view named ``default`` from
+an environment if one exists. The subcommand ``spack env view
+regenerate`` will regenerate the views for the environment. This will
+apply any updates in the environment configuration that have not yet
+been applied.
+
+""""""""""""""""""""""""""""
+Activating environment views
+""""""""""""""""""""""""""""
+
+The ``spack env activate`` command will put the default view for the
+environment into the user's path, in addition to activating the
+environment for Spack commands. The arguments ``-v,--with-view`` and
+``-V,--without-view`` can be used to tune this behavior. The default
+behavior is to activate with the environment view if there is one.
+
+The environment variables affected by the ``spack env activate``
+command and the paths that are used to update them are in the
+following table.
+
+=================== =========
+Variable            Paths
+=================== =========
+PATH                bin
+MANPATH             man, share/man
+ACLOCAL_PATH        share/aclocal
+LD_LIBRARY_PATH     lib, lib64
+LIBRARY_PATH        lib, lib64
+CPATH               include
+PKG_CONFIG_PATH     lib/pkgconfig, lib64/pkgconfig
+CMAKE_PREFIX_PATH   ''
+=================== =========
+
+Each of these paths are appended to the view root, and added to the
+relevant variable if the path exists. For this reason, it is not
+recommended to use non-default projections with the default view of an
+environment.
+
+The ``spack env deactivate`` command will remove the default view of
+the environment from the user's path.
diff --git a/lib/spack/spack/cmd/env.py b/lib/spack/spack/cmd/env.py
index 62e9d4f90c..ce0523bfb9 100644
--- a/lib/spack/spack/cmd/env.py
+++ b/lib/spack/spack/cmd/env.py
@@ -310,7 +310,7 @@ def env_view(args):
 
     if env:
         if args.action == ViewAction.regenerate:
-            env.regenerate_view()
+            env.regenerate_views()
         elif args.action == ViewAction.enable:
             if args.view_path:
                 view_path = args.view_path