diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/spack/docs/chain.rst | 98 | ||||
| -rw-r--r-- | lib/spack/docs/index.rst | 1 | ||||
| -rw-r--r-- | lib/spack/docs/module_file_support.rst | 3 |
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 """"""""""""""""""""" |