Start with a working setup

.gitlab-ci.yml

@@ -10,19 +10,17 @@ variables:
   SPACK_PARENT_DIR: ${CI_BUILDS_DIR}/llnl-stack-${CI_COMMIT_SHORT_SHA}
   SPACK_PATH: ${CI_BUILDS_DIR}/llnl-stack-${CI_COMMIT_SHORT_SHA}/spack
   #[--create-unique-path]
-  SPACK_REPO: https://github.com/spack/spack.git
-  SPACK_REF: develop
   SPACK_DEBUG: "-d"
-  ENV_NAME: "radiuss"
+  ENV_NAME: ""
 
 # We only do one generation per stage because we found conflicts otherwise
 #[one-generate-per-stage--]
 stages:
-  - get-spack
+  - setup
   - generate-quartz
   - generate-lassen
   - build
-  - rm-spack
+  - clean
 #[--one-generate-per-stage]
 
 .on-quartz:
@@ -31,21 +29,17 @@ stages:
 .on-lassen:
   tags: [shell, lassen]
 
-#[get-spack--]
-get-spack:
-  extends: [.on-quartz]
-  stage: get-spack
-  script:
-    - scripts/get-spack
-#[--get-spack]
-
-#[rm-spack--]
-rm-spack:
-  extends: [.on-quartz]
-  stage: rm-spack
-  script:
-    - scripts/remove-spack
-#[--rm-spack]
-
 include:
-  - .gitlab/generate.yml
+  - local: spack-environments/radiuss/ci-variables.yml
+    rules:
+      - if: '$ENV_NAME == "radiuss"'
+  - local: spack-environments/raja-suite/ci-variables.yml
+    rules:
+      - if: '$ENV_NAME == "raja-suite"'
+  - local: .gitlab/generate.yml
+    rules:
+      - if: '$ENV_NAME =~ /^./'
+    #- spack-environments/${ENV_NAME}/ci-variables.yml
+  - local: .gitlab/no-env-name.yml
+    rules:
+      - if: '$ENV_NAME == ""'

.gitlab/generate.yml

@@ -7,21 +7,22 @@
 #
 # Generate CI pipelines for the package in $ENV_NAME
 
-# To use with each job that has to run when an environment name is provided.
-.has_project_name:
-  rules:
-    - if: '$ENV_NAME == ""'
-      when: never
-    - if: '$CI_JOB_NAME == "rm-spack"'
-      when: always
-    - when: on_success
+#[get-spack--]
+get-spack:
+  extends: [.on-quartz]
+  stage: setup
+  script:
+    - scripts/get-spack
+#[--get-spack]
 
-# To use with each job that has to run when no environment is provided.
-.no_project_name:
-  rules:
-    - if: '$ENV_NAME != ""'
-      when: never
-    - when: on_success
+#[rm-spack--]
+rm-spack:
+  extends: [.on-quartz]
+  stage: clean
+  script:
+    - scripts/remove-spack
+  when: always
+#[--rm-spack]
 
 .generate-pipeline:
   script:
@@ -37,14 +38,13 @@
 
 # quartz
 generate-on-quartz:
-  extends: [.generate-pipeline, .on-quartz, .has_project_name]
+  extends: [.generate-pipeline, .on-quartz]
   stage: generate-quartz
   before_script:
     - scripts/print-variables
 
 #[send-variable-child--]
 build-on-quartz:
-  extends: [.has_project_name]
   stage: build
   variables:
     CHILD_SPACK_PATH: ${SPACK_PATH}
@@ -58,13 +58,12 @@ build-on-quartz:
 
 # lassen
 generate-on-lassen:
-  extends: [.generate-pipeline, .on-lassen, .has_project_name]
+  extends: [.generate-pipeline, .on-lassen]
   stage: generate-lassen
   before_script:
     - scripts/print-variables
 
 build-on-lassen:
-  extends: [.has_project_name]
   stage: build
   variables:
     CHILD_SPACK_PATH: ${SPACK_PATH}
@@ -74,4 +73,3 @@ build-on-lassen:
         job: generate-on-lassen
     strategy: depend
   needs: [generate-on-lassen]
-

.gitlab/no-env-name.yml

@@ -0,0 +1,16 @@
+##############################################################################
+# Copyright (c) 2019-2021, Lawrence Livermore National Security, LLC and
+# RADIUSS project contributors. See the COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: (MIT)
+##############################################################################
+#
+# Run a simple jobs to display instructions when no env name was specified.
+
+no-env-name:
+  extends: [.on-quartz]
+  stage: setup
+  script:
+    - echo "Variable \"ENV_NAME\" was not set."
+    - echo "\"ENV_NAME\" is required and should point to an existing directory in spack-environments."
+    - exit 1

docs/sphinx/add-environment.rst

@@ -0,0 +1,152 @@
+.. ## other RADIUSS Project Developers. See the top-level COPYRIGHT file for
+.. ## details.
+.. ##
+.. ## SPDX-License-Identifier: (MIT)
+
+.. _add-environment:
+
+================================
+Process to add a new environment
+================================
+
+The goal of this project is to be able to build any environment of interest for
+RADIUSS, independently, and in a reproducible manner. We aim in particular at
+building those environments against Spack develop branch to check that RADIUSS
+packages do not get broken by recent changes in Spack.
+
+Pre-requisite
+=============
+
+To be used in CI, we need to  make sure your environment can be built
+completely isolated of any personnal Spack configuration on LC systems.
+All the required configuration needs to be embedded in the environment
+directory.
+
+**Note**
+
+You may use this CI to effectively iterate over builds of an environment to fix
+it. That's part of the purpose of this repo.
+
+Required adds-on
+================
+
+Gitlab section in spack config
+------------------------------
+
+Spack will use the ``gitlab-ci`` section to the ``spack.yaml`` file to
+generate the pipeline for you environment. In particular, this is where we
+map runners to specs. Adding this section should be doable by inspecting
+the existing radiuss environement. Create a Pull Request and ask for help
+if needed.
+
+CI variables
+------------
+
+There are three (3) variables that need to be defined in the CI YAML
+configuration in order to make it work.
+
+* `ENV_NAME`: the name of the environment, which must match one of the
+  directories under `spack_environments`.
+
+* `SPACK_REPO`: the URL where to clone Spack from.
+
+* `SPACK_REF`: the ref to checkout in Spack repo.
+
+The CI is configured to generate a subpipeline using the environment under the
+`spack_environments/<ENV_NAME>`. The two other variables will be retrieved in
+this same directory, but GitLab needs an hint.
+
+First, create a file named `ci-variables.yml` in
+`spack_environments/<ENV_NAME>`. In this file, add the definition of the
+missing variables:
+
+.. code-block:: yaml
+
+  variables:
+    SPACK_REPO: <the url to you spack clone or upstream spack>
+    SPACK_REF: <the ref (branch, tag) to use in checkout in spack>
+
+Then edit the `.gitlab-ci.yml` file to add a conditional inclusion of you ci
+variable file:
+
+.. code-block:: yaml
+
+  include:
+    - local: spack-environments/<env_name>/ci-variables.yml
+      rules:
+        - if: '$ENV_NAME == "<env_name>"'
+    - local: spack-environments/radiuss/ci-variables.yml
+      rules:
+        - if: '$ENV_NAME == "radiuss"'
+
+This simply means that each time the CI runs with `ENV_NAME=<env_name>` it will
+include the appropriate variable file. All you need to do to run your
+environment pipeline is to set your environement name.
+
+Pull Request worflow
+--------------------
+
+We recommend setting your environment name globally in `.gitlab-ci.yml`
+
+Recommended adds-on
+===================
+
+Although you may use radiuss-spack-testing to play solo − even clone it in
+another GitLab repo − we see it as an opportunity to gather various Spack
+environments useful for LLNL.
+
+In particular, we provide a preferred location to create your `install_tree`,
+`mirror` (build-cache) and `store` (for concretizer bootstrap).
+
+.. note::
+
+  The following recommendation applies to those belonging to the RADIUSS
+  group only. We could workaround that using the radiuss service user in
+  the future.
+
+Getting Started configuration
+-----------------------------
+
+As a getting started recommendation, and if you belong to RADIUSS group, we
+recommend creating a directory with you `ENV_NAME` in:
+
+* `/usr/workspace/radiuss/installs/<env_name>`
+* `/usr/workspace/radiuss/mirrors/<env_name>`
+* `/usr/workspace/radiuss/stores/<env_name>`
+
+.. note::
+
+  Immediately addapt the permissions so that the RADIUSS group has write
+  access on those:
+
+.. code-block:: bash
+
+  chmod -R g+rwX /usr/workspace/radiuss/installs/<env_name>
+  chmod -R g+rwX /usr/workspace/radiuss/mirrors/<env_name>
+  chmod -R g+rwX /usr/workspace/radiuss/stores/<env_name>
+
+Then, point your environment configuration to those locations. For install
+tree, use:
+
+.. code-block:: yaml
+
+  config:
+    install_tree:
+      root: /usr/workspace/radiuss/install/radiuss
+      padded_length: 128
+      projections:
+        all: '{architecture}/{compiler.name}-{compiler.version}/{name}-{version}-{hash}'
+
+For the mirror location, use:
+
+.. code-block:: yaml
+
+  mirrors:
+    mirror: file:///usr/workspace/radiuss/mirrors/radiuss
+
+For the store location, use:
+
+.. code-block:: yaml
+
+  bootstrap:
+    root: /usr/workspace/radiuss/store/radiuss

docs/sphinx/index.rst

@@ -62,7 +62,8 @@ Table of Contents
 .. toctree::
    :maxdepth: 2
 
-   general
+   structure
+   add-environment
    spack-pipeline-feature
 
 Indices and tables

docs/sphinx/general.rst → docs/sphinx/structure.rst

@@ -4,7 +4,7 @@
 .. ##
 .. ## SPDX-License-Identifier: (MIT)
 
-.. _general:
+.. _structure:
 
 The goal of this project is to provide a code infrastructure using Spack
 pipeline feature to test on LC machines any Spack environment of interest for

spack-environments/radiuss/ci-variables.yml

@@ -0,0 +1,10 @@
+##############################################################################
+# Copyright (c) 2019-2021, Lawrence Livermore National Security, LLC and
+# RADIUSS project contributors. See the COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: (MIT)
+##############################################################################
+
+variables:
+  SPACK_REPO: https://github.com/spack/spack.git
+  SPACK_REF: develop

spack-environments/raja-suite/ci-variables.yml

@@ -0,0 +1,10 @@
+##############################################################################
+# Copyright (c) 2019-2021, Lawrence Livermore National Security, LLC and
+# RADIUSS project contributors. See the COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: (MIT)
+##############################################################################
+
+variables:
+  SPACK_REPO: https://github.com/spack/spack.git
+  SPACK_REF: develop