Add documentation for chaining Spack instances (#11152)

Add documentation for the Spack chain feature added in #8772

3 files changed, 102 insertions, 0 deletions

diff --git a/lib/spack/docs/chain.rst b/lib/spack/docs/chain.rst
new file mode 100644
index 0000000000..c76b53a488
--- /dev/null
+++ b/lib/spack/docs/chain.rst
@@ -0,0 +1,98 @@
+.. Copyright 2013-2019 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)
+
+.. chain:
+
+============================
+Chaining Spack Installations
+============================
+
+You can point your Spack installation to another installation to use any
+packages that are installed there. To register the other Spack instance,
+you can add it as an entry to ``config.yaml``:
+
+.. code-block:: yaml
+
+  config:
+    upstreams:
+      spack-instance-1:
+        install_tree: /path/to/other/spack/opt/spack
+      spack-instance-2:
+        install_tree: /path/to/another/spack/opt/spack
+
+``install_tree`` must point to the ``opt/spack`` directory inside of the
+Spack base directory.
+
+Once the upstream Spack instance has been added, ``spack find`` will
+automatically check the upstream instance when querying installed packages,
+and new package installations for the local Spack install will use any
+dependencies that are installed in the upstream instance.
+
+This other instance of Spack has no knowledge of the local Spack instance
+and may not have the same permissions or ownership as the local Spack instance.
+This has the following consequences:
+
+#. Upstream Spack instances are not locked. Therefore it is up to users to
+   make sure that the local instance is not using an upstream instance when it
+   is being modified.
+
+#. Users should not uninstall packages from the upstream instance. Since the
+   upstream instance doesn't know about the local instance, it cannot prevent
+   the uninstallation of packages which the local instance depends on.
+
+Other details about upstream installations:
+
+#. If a package is installed both locally and upstream, the local installation
+   will always be used as a dependency. This can occur if the local Spack
+   installs a package which is not present in the upstream, but later on the
+   upstream Spack instance also installs that package.
+
+#. If an upstream Spack instance registers and installs an external package,
+   the local Spack instance will treat this the same as a Spack-installed
+   package. This feature will only work if the upstream Spack instance
+   includes the upstream functionality (i.e. if its commit is after March
+   27, 2019).
+
+---------------------------------------
+Using Multiple Upstream Spack Instances
+---------------------------------------
+
+A single Spack instance can use multiple upstream Spack installations. Spack
+will search upstream instances in the order you list them in your
+configuration. If your installation refers to instances X and Y, in that order,
+then instance X must list Y as an upstream in its own ``config.yaml``.
+
+-----------------------------------
+Using Modules for Upstream Packages
+-----------------------------------
+
+The local Spack instance does not generate modules for packages which are
+installed upstream. The local Spack instance can be configured to use the
+modules generated by the upstream Spack instance.
+
+There are two requirements to use the modules created by an upstream Spack
+instance: firstly the upstream instance must do a ``spack module tcl refresh``,
+which generates an index file that maps installed packages to their modules;
+secondly, the local Spack instance must add a ``modules`` entry to the
+configuration:
+
+.. code-block:: yaml
+
+  config:
+    upstreams:
+      spack-instance-1:
+        install_tree: /path/to/other/spack/opt/spack
+        modules:
+          tcl: /path/to/other/spack/share/spack/modules
+
+Each time new packages are installed in the upstream Spack instance, the
+upstream Spack maintainer should run ``spack module tcl refresh`` (or the
+corresponding command for the type of module they intend to use).
+
+.. note::
+
+   Spack can generate modules that :ref:`automatically load
+   <autoloading-dependencies>` the modules of dependency packages. Spack cannot
+   currently do this for modules in upstream packages.
diff --git a/lib/spack/docs/index.rst b/lib/spack/docs/index.rst
index 5e4ed764a2..b176835979 100644
--- a/lib/spack/docs/index.rst
+++ b/lib/spack/docs/index.rst
@@ -71,6 +71,7 @@ or refer to the full manual below.
    binary_caches
    command_index
    package_list
+   chain
 
 .. toctree::
    :maxdepth: 2
diff --git a/lib/spack/docs/module_file_support.rst b/lib/spack/docs/module_file_support.rst
index 32e03f546f..31fe902790 100644
--- a/lib/spack/docs/module_file_support.rst
+++ b/lib/spack/docs/module_file_support.rst
@@ -600,6 +600,9 @@ The configuration above will generate dotkit module files that will not contain
 modifications to either ``CPATH`` or ``LIBRARY_PATH`` and environment module
 files that instead will contain these modifications.
 
+
+.. _autoloading-dependencies:
+
 """""""""""""""""""""
 Autoload dependencies
 """""""""""""""""""""