summaryrefslogtreecommitdiff
path: root/lib
diff options
context:
space:
mode:
Diffstat (limited to 'lib')
-rw-r--r--lib/spack/docs/chain.rst98
-rw-r--r--lib/spack/docs/index.rst1
-rw-r--r--lib/spack/docs/module_file_support.rst3
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
"""""""""""""""""""""