Merge pull request #131 from LLNL/task/white238/document_package_repo

Document `spack_packages_path`
LLNL · Mar 13, 2024 · cf91883 · cf91883
2 parents 0a39ce2 + a050b76
commit cf91883
Show file tree

Hide file tree

Showing 13 changed files with 50 additions and 45 deletions.
diff --git a/.ci/test-project/packages/magictestlib/package.py b/.ci/test-project/packages/magictestlib/package.py
@@ -1,5 +1,5 @@
 ###############################################################################
-# Copyright (c) 2014-2022, Lawrence Livermore National Security, LLC.
+# Copyright (c) 2014-2024, Lawrence Livermore National Security, LLC.
 #
 # Produced at the Lawrence Livermore National Laboratory
 #

diff --git a/.ci/test-project/packages/magictestlib_cached/package.py b/.ci/test-project/packages/magictestlib_cached/package.py
@@ -1,5 +1,5 @@
 ###############################################################################
-# Copyright (c) 2014-2022, Lawrence Livermore National Security, LLC.
+# Copyright (c) 2014-2024, Lawrence Livermore National Security, LLC.
 #
 # Produced at the Lawrence Livermore National Laboratory
 #

diff --git a/.ci/test-project/packages/uberenv-magictestlib/package.py b/.ci/test-project/packages/uberenv-magictestlib/package.py
@@ -1,5 +1,5 @@
 ###############################################################################
-# Copyright (c) 2014-2022, Lawrence Livermore National Security, LLC.
+# Copyright (c) 2014-2024, Lawrence Livermore National Security, LLC.
 #
 # Produced at the Lawrence Livermore National Laboratory
 #

diff --git a/.ci/test-project/spack_configs/toss_3_x86_64_ib/spack.yaml b/.ci/test-project/spack_configs/toss_3_x86_64_ib/spack.yaml
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -1,5 +1,5 @@
 ###############################################################################
-# Copyright (c) 2014-2022, Lawrence Livermore National Security, LLC.
+# Copyright (c) 2014-2024, Lawrence Livermore National Security, LLC.
 #
 # Produced at the Lawrence Livermore National Laboratory
 #

diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,24 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/sphinx/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all
+
+# Set requirements required to build your docs
+python:
+  install:
+    - requirements: docs/requirements.txt
diff --git a/LICENSE b/LICENSE
@@ -1,4 +1,4 @@
-Copyright (c) 2014-2023, Lawrence Livermore National Security, LLC.
+Copyright (c) 2014-2024, Lawrence Livermore National Security, LLC.
 
 Produced at the Lawrence Livermore National Laboratory
 

diff --git a/deprecated_uberenv.py b/deprecated_uberenv.py
@@ -1,7 +1,7 @@
 #!/bin/sh
 "exec" "python3" "-u" "-B" "$0" "$@"
 ###############################################################################
-# Copyright (c) 2014-2023, Lawrence Livermore National Security, LLC.
+# Copyright (c) 2014-2024, Lawrence Livermore National Security, LLC.
 #
 # Produced at the Lawrence Livermore National Laboratory
 #

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,3 @@
+docutils
+sphinx==6.2.1
+sphinx-rtd-theme==1.2.2
diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py
@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 #
 ###############################################################################
-# Copyright (c) 2015-2023, Lawrence Livermore National Security, LLC.
+# Copyright (c) 2015-2024, Lawrence Livermore National Security, LLC.
 #
 # Produced at the Lawrence Livermore National Laboratory
 #

diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst
@@ -1,5 +1,5 @@
 .. ############################################################################
-.. # Copyright (c) 2014-2023, Lawrence Livermore National Security, LLC.
+.. # Copyright (c) 2014-2024, Lawrence Livermore National Security, LLC.
 .. #
 .. # Produced at the Lawrence Livermore National Laboratory
 .. #
@@ -221,8 +221,8 @@ Project settings are as follows:
   spack_commit             **None**                   Spack commit to checkout                         **None**
   spack_activate           **None**                   Spack packages to activate                       **None**
   spack_build_mode         ``--spack-build-mode``     Set mode used to build TPLs with Spack           ``dev-build``
-  spack_configs_path       **None**                   Directory with Spack configs to be copied        ``spack_configs``
-  spack_packages_path      **None**                   Directory with Spack packages to be copied       ``packages``
+  spack_configs_path       **None**                   Directory with Spack configs to be autodetected  ``spack_configs``
+  spack_packages_path      **None**                   Directory|List with Package Repos to be added    ``packages``
   spack_concretizer        **None**                   Spack concretizer to use ``original, clingo``    ``original``
   spack_setup_clingo       **None**                   Do not install clingo if set to ``false``        ``true``
   spack_externals          ``--spack-externals``      Space delimited string of packages for Spack to  **None**
@@ -235,12 +235,22 @@ Project settings are as follows:
   vcpkg_ports_path         ``--vcpkg-ports-path``     Folder with vcpkg ports files                    **None**
  ========================= ========================== ================================================ =======================================
 
-If a ``spack_commit`` is present, it supercedes the ``spack_branch`` option, and similarly for ``vcpkg_commit`` and ``vcpkg_branch``.
+If a ``spack_commit`` is present, it supercedes the ``spack_branch`` option, and similarly for ``vcpkg_commit``and ``vcpkg_branch``.
 
 When used as a submodule ``.uberenv_config.json`` should define both ``spack_configs_path`` and ``spack_packages_path``,
 providing Uberenv with the respective location of ``spack_configs`` and ``packages`` directories.
 Note that they cannot sit next to ``uberenv.py``, since by default, the Uberenv repo does not provide them.
 
+``spack_packages_path`` can either be a singular directory or a list of directories. These are relative to the
+location of the ``.uberenv_config.json``. When it is a list, the directories are added from left to right in Spack
+and right-most directories have the highest priority. The built-in Spack package repository is the lowest priority.
+Example:
+
+.. code-block:: json
+
+    "spack_packages_path": "package/repo/higher/than/spacks",
+    "spack_packages_path": ["package/repo/higher/than/spacks", "package/repo/even/higher"],
+
 .. note::
     Uberenv no longer copies all directories that exist under ``spack_packages_path`` to the cloned
     Spack. A ``repo.yaml`` is now required in the previous directory of each packages path instead.

diff --git a/gen_spack_env_script.py b/gen_spack_env_script.py
@@ -1,5 +1,5 @@
 ###############################################################################
-# Copyright (c) 2015-2023, Lawrence Livermore National Security, LLC.
+# Copyright (c) 2015-2024, Lawrence Livermore National Security, LLC.
 #
 # Produced at the Lawrence Livermore National Laboratory
 #

diff --git a/uberenv.py b/uberenv.py
@@ -1,7 +1,7 @@
 #!/bin/sh
 "exec" "python3" "-u" "-B" "$0" "$@"
 ###############################################################################
-# Copyright (c) 2014-2023, Lawrence Livermore National Security, LLC.
+# Copyright (c) 2014-2024, Lawrence Livermore National Security, LLC.
 #
 # Produced at the Lawrence Livermore National Laboratory
 #