-
Notifications
You must be signed in to change notification settings - Fork 2.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add documentation for chaining Spack instances (#11152)
Add documentation for the Spack chain feature added in #8772
- Loading branch information
Showing
3 changed files
with
102 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters