Update README.md on directory layout

README.md

@@ -1,3 +1,62 @@
 # software-stack-plumbing
 
-Collection of scripts, etc, to make HLRS software stack work. 
+Collection of scripts, etc, to make HLRS software stack work. 
+
+
+## Notes on software stack at HLRS
+
+Environment variables:
+
+- `HLRS_OPT_PREFIX`: start of hpcoft managed subdirectory
+  - Set by HPCN
+  - Non-public
+  - Example: `HLRS_OPT_PREFIX=/opt/hlrs`
+- `HLRS_SOFTWARE_STACK_PREFIX`: start of software stack as described in this document
+  - Set by this hpcoft
+  - Non-public
+  - Example: `HLRS_SOFTWARE_STACK_PREFIX=$HLRS_OPT_PREFIX/release`
+- `HLRS_SOFTWARE_STACK_RELEASE_VERSION`: label of a currently active release
+  - Set by hpcoft
+  - Public
+  - Example: `HLRS_SOFTWARE_STACK_RELEASE_VERSION=24.1`
+- `HLRS_SOFTWARE_STACK_RELEASE_ROOT` : start of subdirectory of currently active release
+  - Set by hpcoft
+  - Public
+  - Should contain all software, modules, data, etc., to use a release
+  - Defined by: `HLRS_SOFTWARE_STACK_RELEASE_ROOT=${HLRS_SOFTWARE_STACK_PREFIX}/${HLRS_SOFTWARE_STACK_RELEASE_VERSION}`
+- `HLRS_SOFTWARE_STACK_HLRS_SPACK_ROOT` : start of subdirectory for all-things-spack of currently active release
+  - Set by hpcoft
+  - Non-public
+  - Install spack in `SPACK_ROOT=${HLRS_SOFTWARE_STACK_HLRS_SPACK_ROOT}/spack`
+  - Example: `HLRS_SOFTWARE_STACK_HLRS_SPACK_ROOT=${HLRS_SOFTWARE_STACK_RELEASE_ROOT}/hlrs-spack`
+- `HLRS_SOFTWARE_STACK_SPACK_INSTALL_TREE` : spack install tree of of currently active release.
+  - Set by hpcoft
+  - Public
+  - This can be used for hpcoft/users to chain/upstream to HLRS Spack installation.
+  - Defined by: `HLRS_SOFTWARE_STACK_SPACK_INSTALL_TREE=${HLRS_SOFTWARE_STACK_RELEASE_ROOT}/opt-spack`
+
+
+Directory layout:
+
+```text
+${HLRS_SOFTWARE_STACK_RELEASE_ROOT}/
+├── opt-non-spack/
+│ ├── modulefiles
+│ └── ...
+├── opt-spack (${HLRS_SOFTWARE_STACK_SPACK_INSTALL_TREE})/
+│ ├── modulefiles
+│ └── ...
+├── hlrs-spack (${HLRS_SOFTWARE_STACK_HLRS_SPACK_ROOT})/
+│ ├── spack (${SPACK_ROOT})
+│ ├── config-hlrs
+│ ├── config-user
+│ ├── repos
+│ ├── environments
+│ └── ...
+└── hlrs-plumbing
+  ├── scripts
+  ├── envs
+  ├── ci-cd  
+  └── ...
+```
+

envs/00_base_prefix.env

@@ -0,0 +1,6 @@
+# this file is meant to be source'd
+#
+# sets HLRS opt directory 
+# to HLRS_OPT_PREFIX__USER or default
+HLRS_OPT_PREFIX=${HLRS_OPT_PREFIX__USER:-/opt/hlrs}
+

envs/01_release_root.env

@@ -0,0 +1,18 @@
+# this file is meant to be source'd
+#
+
+# need HLRS_OPT_PREFIX
+if [ -z "${HLRS_OPT_PREFIX}" ]; then
+  echo "ERROR: need environment variable HLRS_OPT_DIR"
+else
+
+  HLRS_SOFTWARE_STACK_PREFIX=${HLRS_OPT_PREFIX}/release
+  
+  HLRS_SOFTWARE_STACK_RELEASE_VERSION=${HLRS_SOFTWARE_STACK_RELEASE_VERSION__USER:-24.1}
+  HLRS_SOFTWARE_STACK_RELEASE_ROOT=${HLRS_SOFTWARE_STACK_PREFIX}/${HLRS_SOFTWARE_STACK_RELEASE_VERSION}
+
+  unset HLRS_SOFTWARE_STACK_PREFIX 
+
+  export HLRS_SOFTWARE_STACK_RELEASE_VERSION HLRS_SOFTWARE_STACK_RELEASE_ROOT
+fi
+

envs/01_release_root_23.1.0.env

@@ -0,0 +1,19 @@
+# this file is meant to be source'd
+#
+
+# need HLRS_OPT_PREFIX
+if [ -z "${HLRS_OPT_PREFIX}" ]; then
+  echo "ERROR: need environment variable HLRS_OPT_DIR"
+else
+
+  HLRS_SOFTWARE_STACK_PREFIX=${HLRS_OPT_PREFIX}/spack/release
+  
+  HLRS_SOFTWARE_STACK_RELEASE_VERSION=23.1.0
+  HLRS_SOFTWARE_STACK_RELEASE_ROOT=${HLRS_SOFTWARE_STACK_PREFIX}/${HLRS_SOFTWARE_STACK_RELEASE_VERSION}
+
+  unset HLRS_SOFTWARE_STACK_PREFIX 
+  
+  export HLRS_SOFTWARE_STACK_RELEASE_VERSION HLRS_SOFTWARE_STACK_RELEASE_ROOT
+
+fi
+

envs/02_hlrs_spack_root.env

@@ -0,0 +1,16 @@
+# this file is meant to be source'd
+#
+
+# need HLRS_SOFTWARE_STACK_RELEASE_ROOT
+if [ -z "${HLRS_SOFTWARE_STACK_RELEASE_ROOT}" ]; then
+  echo "ERROR: need environment variable HLRS_SOFTWARE_STACK_RELEASE_ROOT"
+else
+
+  HLRS_SOFTWARE_STACK_HLRS_SPACK_ROOT=${HLRS_SOFTWARE_STACK_RELEASE_ROOT}/hlrs-spack
+  # the following must be a directory containing a subdir named .spack-db/
+  HLRS_SOFTWARE_STACK_SPACK_INSTALL_TREE=${HLRS_SOFTWARE_STACK_RELEASE_ROOT}/opt-spack
+
+  export HLRS_SOFTWARE_STACK_HLRS_SPACK_ROOT HLRS_SOFTWARE_STACK_SPACK_INSTALL_TREE
+
+fi
+

envs/02_hlrs_spack_root_23.1.0.env

@@ -0,0 +1,16 @@
+# this file is meant to be source'd
+#
+
+# need HLRS_SOFTWARE_STACK_RELEASE_ROOT
+if [ -z "${HLRS_SOFTWARE_STACK_RELEASE_ROOT}" ]; then
+  echo "ERROR: need environment variable HLRS_SOFTWARE_STACK_RELEASE_ROOT"
+else
+
+  HLRS_SOFTWARE_STACK_HLRS_SPACK_ROOT=${HLRS_SOFTWARE_STACK_RELEASE_ROOT}
+  # the following must be a directory containing a subdir named .spack-db/
+  HLRS_SOFTWARE_STACK_SPACK_INSTALL_TREE=${HLRS_SOFTWARE_STACK_RELEASE_ROOT}/optional
+
+  export HLRS_SOFTWARE_STACK_HLRS_SPACK_ROOT HLRS_SOFTWARE_STACK_SPACK_INSTALL_TREE
+
+fi
+

envs/xx_fake_spack_localscratch.env

@@ -0,0 +1,17 @@
+# this file is meant to be source'd
+#
+# this loads environemt for a fake HLRS spack release, in /localscratch
+# 
+
+HLRS_OPT_PREFIX__USER=/localscratch/${UID}
+
+# need release version 
+if [ -z "${HLRS_SOFTWARE_STACK_RELEASE_VERSION__USER}" ]; then
+  echo "ERROR: need environment variable HLRS_SOFTWARE_STACK_RELEASE_VERSION__USER"
+else
+
+  source 00_base_prefix.env
+  source 01_release_root.env
+  source 02_hlrs_spack_root.env
+
+fi

envs/xx_hlrs_spack_23.1.0.env

@@ -0,0 +1,9 @@
+# this file is meant to be source'd
+#
+# this loads environemt for a fake HLRS spack release, in /localscratch
+# 
+
+source 00_base_prefix.env
+source 01_release_root_23.1.0.env
+source 02_hlrs_spack_root_23.1.0.env
+

envs/xx_unload_env.env

@@ -0,0 +1,9 @@
+# this file is meant to be source'd
+#
+# this unloads all varaibles related to HLRS software stack
+# 
+
+unset HLRS_SOFTWARE_STACK_HLRS_SPACK_ROOT
+unset HLRS_SOFTWARE_STACK_SPACK_INSTALL_TREE
+unset HLRS_SOFTWARE_STACK_RELEASE_VERSION
+unset HLRS_SOFTWARE_STACK_RELEASE_ROOT

scripts/xx_checkout_repo.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+#
+# This scripts checks out from the repo
+#
+# Input arguments:
+#   - repo:          url to repo in git format
+#   - release_tag:   tag/branch/commit in repo
+#   - release_dir:
+#   - destination:   checkout into directory <release_dir>/<destination>  
+#
+# Environment variables: $TMPDIR must be set
+# 
+
+_VERBOSITY=1
+
+if [[ "$#" -ne 4 ]]; then
+  echo "Syntax: $0 repo release_tag release_dir destination"
+  echo "Checkout tag <release_tag> from repo <repo> into path <release_dir>/<destination>."
+fi 
+
+echo "TODO: check for $TMPDIR"
+
+arg_repo=$1
+arg_tag=$2
+arg_dir=$3
+arg_destination=$4
+
+log () {
+    local msg=$1
+    if [[ -n $_VERBOSITY ]]; then 
+        echo $msg
+    fi
+}
+
+# check repository name for plausibility
+check_repo () {
+    echo $1
+}
+
+# modify tag by stripping "hlrs-release-" prefix
+canonize_tag () {
+    echo ${1##hlrs-release-}
+}
+
+# create and prepare destination directory
+# or return existing directory
+create_dir () {
+    local dir=$1
+    local rc
+
+    if [[ -d $dir ]]; then
+        rc=$dir
+    else
+        mkdir -p $dir
+        chmod g=u $dir
+        rc=$dir
+    fi
+    echo $rc
+}
+
+# create an empty new directory and prepare destination directory
+create_or_fail_dir () {
+    local dir=$1
+    local rc
+
+    if [[ -d $dir ]]; then
+        rc=""
+    else
+        rc=$(create_dir $dir)
+    fi
+    echo $rc
+}
+
+checkout_git () {
+    local repo=$1
+    local tag=$2
+    local dir=$3
+
+    pushd $dir
+    git clone --depth=1 --single-branch --branch=$tag -c feature.manyFiles=true $repo .
+    popd
+
+}
+
+repo=$(check_repo $arg_repo)
+release_tag=$(canonize_tag $arg_tag)
+destination_dir=$(create_or_fail_dir $arg_dir/$arg_destination)
+if [[ -z $destination_dir ]]; then
+    log "Covardly refusing to overwrite existing directory $arg_dir/$arg_destination."
+else
+    log "Checking out Spack from $repo at tag $release_tag into directory $destination_dir"
+    checkout_git $repo $release_tag $destination_dir
+fi

scripts/xx_populate_release_directory.sh

@@ -0,0 +1,107 @@
+#!/bin/bash
+#
+# Populates directory <base_prefix>/release/<release_tag> with the release tagged as <release_tag>.
+#
+# Input arguments:
+#   - release_tag:   tag/branch/commit in repo
+#   - base_prefix:   prefix to base directory for softweare installation; e.g. /opt/hlrs
+#
+# Environment variables: $TMPDIR must be set
+#
+#
+# Release directory structure:
+# ${HLRS_SOFTWARE_STACK_RELEASE_ROOT}/
+# ├── opt-non-spack/
+# │ ├── modulefiles
+# │ └── ...
+# ├── opt-spack (${HLRS_SOFTWARE_STACK_SPACK_INSTALL_TREE})/
+# │ ├── modulefiles
+# │ └── ...
+# ├── hlrs-spack (${HLRS_SOFTWARE_STACK_HLRS_SPACK_ROOT})/
+# │ ├── spack (${SPACK_ROOT})
+# │ ├── config-hlrs
+# │ ├── config-user
+# │ ├── repos
+# │ ├── environments
+# │ └── ...
+# └── hlrs-plumbing
+#   ├── scripts
+#   ├── envs
+#   ├── ci-cd
+#   └── ...
+#
+
+_VERBOSITY=1
+
+if [[ "$#" -ne 2 ]]; then
+  echo "Syntax: $0 release_tag base_prefix"
+  echo "Populates directory <base_prefix>/release/<release_tag> with the release tagged as <release_tag>."
+  # TODO: exit with error code
+fi
+
+echo "TODO: check for $TMPDIR"
+
+arg_tag=$1
+arg_prefix=$2
+
+log () {
+    local msg=$1
+    if [[ -n $_VERBOSITY ]]; then 
+        echo $msg
+    fi
+}
+
+# modify tag by stripping "hlrs-release-" prefix
+canonize_tag () {
+    echo ${1##hlrs-release-}
+}
+
+# create and prepare destination directory
+# or return existing directory
+create_dir () {
+    local dir=$1
+    local rc
+
+    if [[ -d $dir ]]; then
+        rc=$dir
+    else
+        mkdir -p $dir
+        chmod g=u $dir
+        rc=$dir
+    fi
+    echo $rc
+}
+
+
+# process input arguments
+HLRS_SOFTWARE_STACK_RELEASE_VERSION__USER=$(canonize_tag $arg_tag)
+HLRS_OPT_PREFIX__USER=$(create_dir $arg_prefix)
+
+# Define various repo locations
+_HLRS_SPACK_REPO=file://$HOME/spack-test/dummy_repo/spack-v0.21.2.git
+_HLRS_SPACK_PLUMBING_REPO=file://$HOME/spack-test/dummy_repo/hawk-spack-env.git
+_HLRS_SPACK_CONFIG_REPO=
+
+# bootstrap environment variables 
+# (using [bash process substitution](https://tldp.org/LDP/abs/html/process-sub.html))
+source <(curl $_HLRS_SPACK_PLUMBING_REPO/envs/00_base_prefix.env)
+source <(curl $_HLRS_SPACK_PLUMBING_REPO/envs/01_release_root.env)
+source <(curl $_HLRS_SPACK_PLUMBING_REPO/envs/02_hlrs_spack_root.env)
+
+# setup plumbing directory
+curl $_HLRS_SPACK_PLUMBING_REPO/scripts/xx_checkout_repo.sh | \
+  bash -s -- $_HLRS_SPACK_PLUMBING_REPO \
+  $HLRS_SOFTWARE_STACK_RELEASE_VERSION $HLRS_SOFTWARE_STACK_RELEASE_ROOT hlrs-plumbing
+_HLRS_PLUMBING_DIR=$HLRS_SOFTWARE_STACK_RELEASE_ROOT/hlrs-plumbing
+
+# setup hlrs-spack directory
+mkdir -p $HLRS_SOFTWARE_STACK_HLRS_SPACK_ROOT
+# TODO: checkout repo as soon as available; in the meantime do
+# setup hlrs-config directory
+ln -s spack/config-hlrs $HLRS_SOFTWARE_STACK_HLRS_SPACK_ROOT/config-hlrs
+# setup $SPACK_ROOT directory
+$_HLRS_PLUMBING_DIR/scripts/xx_checkout_repo.sh $_HLRS_SPACK_REPO \
+  $HLRS_SOFTWARE_STACK_RELEASE_VERSION $HLRS_SOFTWARE_STACK_HLRS_SPACK_ROOT spack
+
+# setup opt-non-spack 
+# TODO