Skip to content

Commit c71f4b7

Browse files
SilentSegfaultSilentSegfault
committed
Add instructions for # newSPACKDevArea Configuration Guide
1 parent 8d36e76 commit c71f4b7

9 files changed

Lines changed: 445 additions & 0 deletions

‎develop-sbndaq-with-spack/docs/configuration_file_03.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Configuration Guide for **newSPACKDevArea.sh**
2+
3+
This document explains the configuration options available in the `newSPACKDevArea.env` file, which is used to set up Spack-based SBNDAQ development environments.
4+
5+
## Basic Configuration
6+
7+
| Option | Description |
8+
|--------|-------------|
9+
| `DEVNAME` | The developer's initials or short name (4-5 chars, all **UPPER** case) who owns this development environment. Example: `DEVNAME=ALICE` |
10+
11+
## SBNDAQ Suite Configuration
12+
13+
| Option | Description |
14+
|--------|-------------|
15+
| `DAQ_PKG_NAME` | The name of the DAQ software suite package (`sbndaq-suite` or `artdaq-suite`). Example: `DAQ_PKG_NAME=sbndaq-suite` |
16+
| `DAQ_PKG_VERSIONS` | Specifies the versions of the DAQ software suite to be used. Format: `version:qualifier:compiler:standard`. Multiple versions can be specified with a comma separator. Example: `migration_artdaqv3_13_02:s132:gcc13.1.0:c++20` |
17+
| `DAQ_PKG_SBNENV` | Specifies the SBN environment. Examples: `DAQ_PKG_SBNENV=sbn-fd` or `DAQ_PKG_SBNENV=sbn-nd` |
18+
| `DAQ_PKG_CHECKOUT_PACKAGES` | Lists packages to be checked out from github, with their respective branches. Format: `package@branch`. Multiple packages can be specified with commas. Example: `sbndaq@upgrade_gcc13.1.0,sbndaq-artdaq@upgrade_gcc13.1.0` |
19+
20+
## Spack Configuration
21+
22+
| Option | Description |
23+
|--------|-------------|
24+
| `SPACK_SOFTWARE_BASE` | Base directory for all Spack-related software. Example: `/daq/software` |
25+
| `SPACK_DIR` | Location of the Spack installation. Usually defined as `${SPACK_SOFTWARE_BASE}/spack_packages/spack` |
26+
| `SPACK_VERSION` | Version of Spack being used. Example: `v1.0.1.sbnd` |
27+
| `SPACK_MIRROR_BASE` | Location of Spack binary package mirrors. Usually defined as `${SPACK_SOFTWARE_BASE}/spack_mirrors/${DAQ_PKG_NAME}` |
28+
| `SPACK_DAQ_AREAS` | Directory where SBNDAQ development areas will be created. Example: `${HOME}/DAQ_SPACK_DevAreas` |
29+
| `SPACK_PACKAGES_TOP` | Top-level directory for installed Spack packages. Example: `${SPACK_SOFTWARE_BASE}/spack_packages` |
30+
| `SPACK_USE_USER_CONFIG` | Enables the use of user-specific Spack configuration. Set to `true` or `false` |
31+
32+
## Build Options
33+
34+
| Option | Description |
35+
|--------|-------------|
36+
| `RUN_BUILD` | Enables the automatic build process when setting up the environment. Set to `true` or `false` |
37+
| `BUILD_THREADS` | Number of parallel build threads to use. Example: `8` |
38+
| `DEBUG_BUILD` | Enables or disables debug information in the build. Set to `true` or `false` |
39+
| `ENABLE_TESTS` | Enables or disables building and running tests. Set to `true` or `false` |
40+
| `ENABLE_GIT_PUSH` | Allows changes to be pushed back to the git repositories. Set to `true` or `false` |
41+
42+
## Access Control
43+
44+
| Option | Description |
45+
|--------|-------------|
46+
| `ALLOW_HOSTS` | Restricts execution to specific host machines. Multiple hosts can be specified with commas. Example: `vm-60,vm-51` |
47+
| `ALLOW_USERS` | Restricts execution to specific users. Multiple users can be specified with commas. Example: `artdaq,icarus,sbnd` |
48+
49+
## Example Configuration
50+
51+
```bash
52+
DEVNAME=ALICE
53+
# DAQ suite configuration
54+
DAQ_PKG_NAME=sbndaq-suite
55+
DAQ_PKG_VERSIONS=migration_artdaqv3_13_02:s132:gcc13.1.0:c++20,migration_artdaqv3_13_02:s131:gcc13.1.0:c++20
56+
DAQ_PKG_SBNENV=sbn-fd,sbn-nd
57+
DAQ_PKG_CHECKOUT_PACKAGES=sbndaq@upgrade_gcc13.1.0,sbndaq-artdaq@upgrade_gcc13.1.0,sbndaq-artdaq-core@upgrade_gcc13.1.0
58+
59+
# Spack configuration
60+
SPACK_SOFTWARE_BASE=/daq/software
61+
SPACK_DIR=${SPACK_SOFTWARE_BASE}/spack_packages/spack
62+
SPACK_VERSION=v1.0.1.sbnd
63+
SPACK_MIRROR_BASE=${SPACK_SOFTWARE_BASE}/spack_mirrors/${DAQ_PKG_NAME}
64+
SPACK_DAQ_AREAS=${HOME}/DAQ_SPACK_DevAreas
65+
SPACK_PACKAGES_TOP=${SPACK_SOFTWARE_BASE}/spack_packages
66+
SPACK_USE_USER_CONFIG=true
67+
68+
# Build options
69+
RUN_BUILD=true
70+
BUILD_THREADS=8
71+
DEBUG_BUILD=false
72+
ENABLE_TESTS=false
73+
ENABLE_GIT_PUSH=true
74+
ALLOW_HOSTS=vm-60,vm-51
75+
ALLOW_USERS=artdaq,icarus,sbnd
76+
```

‎develop-sbndaq-with-spack/docs/directory_structure_04.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
## Spack project directory structure
2+
3+
The SBNDDAQ project structure is designed to accommodate two OS variants (AL9/SL7), a use case not fully supported by single-OS Spack environments. Key directories are shared outside environment directories, requiring the specific Spack-activation approach.
4+
5+
The structure follows the [SBNDAQ](https://sbnsoftware.github.io/sbn_online_wiki/sbndaq_Wiki) development workflow using [Spack](https://spack.readthedocs.io/en/latest/index.html):
6+
7+
**Core Environment**: The `./almalinux9-gcc13.1.0-c++20-s132` directory contains the [Spack environment](https://spack.readthedocs.io/en/latest/environments.html) configuration files (`spack.yaml`, `spack.lock`) targeting AlmaLinux 9 with GCC 13.1.0 and the C++20 standard.
8+
9+
**Configuration Management**: The `./spack` directory contains a custom repository (`./spack-repos/mpd`) for developing SBNDAQ using [MPD](https://github.com/FNALssi/spack-mpd).
10+
11+
**Development Sources**: The `./srcs` directory contains sources of SBNDAQ packages (`sbndaq`, `sbndaq-artdaq`, `sbndaq-artdaq-core`, `wibtools`), all on the `feature/upgrade_gcc13.1.0` branch, enabling simultaneous development across the entire SBNDAQ software stack.
12+
13+
**Build Infrastructure**: The setup installed 170 packages, creating binary caches in `./spack_mirrors` for faster rebuilds and `./spack_packages` for installations with placeholder paths to handle long directory names.
14+
15+
**Integration**: The `./DAQInterface` symlink provides direct access to the SBNDAQ RunControl startup scripts, while the `.pkgs.txt` files document the complete Spack dependency tree.
16+
17+
### Example of the project structure that supports two OSes
18+
19+
```bash
20+
─────────────────────────────────────────────────────────────────────────────────────────
21+
$ pwd
22+
${HOME}/DAQ_SPACK_DevAreas/DAQ_2025-06-03_EFG2_migration_artdaqv3_13_02
23+
24+
$ exa --tree --level 2
25+
├── almalinux9-gcc13.1.0-c++20-s132
26+
│ ├── spack.lock
27+
│ └── spack.yaml
28+
├── scientific7-gcc13.1.0-c++20-s132
29+
│ ├── spack.lock
30+
│ └── spack.yaml
31+
├── DAQInterface -> ./srcs/sbndaq/sbn-fd/DAQInterface2
32+
├── sbndaq-suite-migration_artdaqv3_13_02-almalinux9-gcc13.1.0-c++20-s132.pkgs.txt
33+
├── sbndaq-suite-migration_artdaqv3_13_02-scientific7-gcc13.1.0-c++20-s132.pkgs.txt
34+
├── spack
35+
│ ├── config.yaml
36+
│ ├── linux
37+
│ └── repos.yaml
38+
├── spack-repos
39+
│ └── mpd
40+
├── spack_mirrors
41+
│ └── sbndaq-suite
42+
├── spack_packages
43+
│ ├── __spack_path_placeholder__
44+
│ └── bin
45+
└── srcs
46+
├── sbndaq
47+
├── sbndaq-artdaq
48+
├── sbndaq-artdaq-core
49+
└── wibtools
50+
─────────────────────────────────────────────────────────────────────────────────────────
51+
```

‎develop-sbndaq-with-spack/docs/initial_setup_02.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
## Automated development area setup with **newSPACKDevArea.sh**
2+
3+
The [Spack Development Tutorial](https://sbnsoftware.github.io/sbn_online_wiki/Spack-Development-Tutorial.html) guides you through setting up a development environment using Spack. It is still applicable today and can be used for developing SBNDAQ in a single OS variant for development purposes.
4+
5+
The instructions from the tutorial were used to create an automated script called `newSPACKDevArea.sh`. This script automates the setup of an SBNDAQ development area, supporting both AlmaLinux 9 (AL9) and Scientific Linux 7 (SL7). The script uses Spack software available through the shared installation at `/daq/software/spack_packages/spack/v1.0.1.sbnd`, which helps minimize the need for rebuilding approximately 200 dependent packages, a process that can take up to 8 hours.
6+
7+
The script workflow includes the following steps: it creates a directory structure supporting both operating systems, adds Spack configuration files with overrides for install location and the upstream Spack repository, downloads SBNDAQ source code into the `./srcs` directory, and executes a build and installation process. If the build and installation are successful, it then creates tarballs of each SBNDAQ subproject and copies them into the Spack build cache directory.
8+
9+
The script uses a configuration file named `newSPACKDevArea.env`, which is in the [env](https://github.com/env-lang/env/blob/main/env.md) format. Apart from specifying the directory location where the development area should be created, it includes a list of SBNDAQ packages to be checked out from Git into `./srcs` and build options such as the s-qualifier, GCC version, and C++ standard to use. It's a good practice to review this file prior to running the `newSPACKDevArea.sh` script.
10+
11+
The `newSPACKDevArea.sh` script accepts the following options:
12+
13+
```bash
14+
Options:
15+
--dev-name NAME Set developer name for directory naming (default: XYZ)
16+
--default-version VER Set specific version instead of latest available
17+
--non-interactive Run without user prompts (default: false)
18+
-h, --help Display this help message and exit
19+
```
20+
21+
Users can also override the name of the development area by setting the `MY_SPACK_PROJECT` environment variable, so the script will use it instead of creating a new one. If the area pointed to by `MY_SPACK_PROJECT` exists, the `newSPACKDevArea.sh` script will not override the configuration files and sources and will proceed to building, installation, and creating Spack build caches.

‎develop-sbndaq-with-spack/docs/project_rationale_01.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
## Rationale
2+
3+
This project departs from the conventional Spack development use case, which typically involves a single OS variant for development and execution. For SBNDDAQ, this is not feasible. Hardware/software dependencies necessitate the use of two Linux OS variants: AlmaLinux 9 (AL9) and Scientific Linux 7 (SL7). As of 06/25, Spack environments are limited to a single OS variant. Consequently, two Spack environments are required to support the SBNDDAQ use case: one for AL9 and one for SL7. Managing two such environments necessitates synchronizing settings, which is impractical. This project addresses this challenge. While retaining the two-environment concept, the project structure is designed to place the `srcs`, `spack_packages`, `spack_mirrors`, `spack-repos`, and `DAQInterface` directories outside the individual Spack environment directories. These shared directories are located one level above the respective Spack environment directories. This approach allows sharing all files between the two environments, with the exception of environment-specific configurations. During runtime, a helper script executes `cd my-$(os-name.sh)-env && spack env activate .` to activate the OS-specific environment.
4+
5+
### Example of the project structure that supports two OSes
6+
7+
```bash
8+
─────────────────────────────────────────────────────────────────────────────────────────
9+
│ # Two OS-specific environments
10+
├── almalinux9-gcc13.1.0-c++20-s132 # AlmaLinux 9 (AL9)
11+
├── scientific7-gcc13.1.0-c++20-s132 # Scientific Linux 7
12+
│ # Shared sources and project configuration files
13+
├── DAQInterface -> ./srcs/sbndaq/sbn-fd/DAQInterface2
14+
├── spack
15+
├── spack-repos
16+
├── spack_mirrors
17+
├── spack_packages
18+
└── srcs
19+
─────────────────────────────────────────────────────────────────────────────────────────
20+
```

‎develop-sbndaq-with-spack/docs/setup_project_05.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
## Follow these steps to activate (setup) your SBNDAQ project area.
2+
3+
The SBNDDAQ project structure is designed to accommodate two OS variants (AL9/SL7), a use case not fully supported by single-OS Spack environments. Key directories are shared outside environment directories, requiring this specific activation approach.
4+
5+
The bash script below sets up the environment necessary for activating a specific Spack project related to your SBNDAQ work. It begins by setting and exporting the name of the Spack project you wish to use and designates your development area within the home directory. It then sources a specified Spack setup script, temporarily disables local Spack configuration, and sets a user configuration path. Finally, it navigates to the designated OS-specific development directory and activates the Spack environment located there.
6+
7+
### Example of Bash commands to activate the OS-specific environment
8+
9+
```bash
10+
─────────────────────────────────────────────────────────────────────────────────────────
11+
export MY_SPACK_PROJECT=DAQ_2025-06-03_EFG2_migration_artdaqv3_13_02
12+
13+
## Activate your Spack project area
14+
export MY_SPACK_DEV_AREA=${HOME}/DAQ_SPACK_DevAreas/${MY_SPACK_PROJECT}
15+
export SPACK_DISABLE_LOCAL_CONFIG=true
16+
source /daq/software/spack_packages/spack/v1.0.1.sbnd/setup-env.sh
17+
unset SPACK_DISABLE_LOCAL_CONFIG
18+
export SPACK_USER_CONFIG_PATH=${MY_SPACK_DEV_AREA}/spack
19+
cd ${MY_SPACK_DEV_AREA}/$(spack arch -o)-gcc13.1.0-c++20-s132
20+
spack env activate --prompt .
21+
─────────────────────────────────────────────────────────────────────────────────────────
22+
```

‎develop-sbndaq-with-spack/docs/spack_mirrors_08.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
## **spack_mirrors** directory listing
2+
3+
This is a Spack build cache mirror containing precompiled binary packages for the SBNDAQ software suite's artDAQ v3.13.02 migration. It stores `.spack` binary files and `.spec.json` metadata for the AlmaLinux 9 x86_64 architecture using the GCC 13.1.0 compiler.
4+
5+
```bash
6+
───────────────────────────────────────────────────────────────────────────────────────────────────
7+
$ pwd
8+
${HOME}/DAQ_SPACK_DevAreas/DAQ_2025-06-03_EFG2_migration_artdaqv3_13_02/spack_mirrors
9+
10+
$ exa --tree --level 7
11+
└── sbndaq-suite
12+
└── migration_artdaqv3_13_02
13+
└── build_cache
14+
├── index.json
15+
├── index.json.hash
16+
├── linux-almalinux9-x86_64_v2
17+
│ └── gcc-13.1.0
18+
│ ├── sbndaq-artdaq-core-migration
19+
│ │ └── linux-almalinux9-x86_64_v2-gcc-13.1.0-sbndaq-artdaq-core-migration-3uizsxwd4j
20+
│ ├── sbndaq-artdaq-migration
21+
│ │ └── linux-...3.1.0-sbndaq-artdaq-migration-jqsa5jy2wc4lirrgmtwnes7ben6htjge.spack
22+
│ ├── sbndaq-migration
23+
│ │ └── linux-almalinux9-x8...sbndaq-migration-4pqf6pn33ukjsirb4pho2bzcp66uvl7u.spack
24+
│ ├── sbndaq-suite-migration_artdaqv3_13_02
25+
│ │ └── linux-almalinux9-x86_64_v2-gcc-13.1.0-sbndaq-suite-...qvb2bt7j7gcozgjkw.spack
26+
│ └── wibtools-migration
27+
│ └── linux-almalinux9-x86_64_v2-gcc-13.1.0-wibtools-migration-lc...zhcnooufd.spack
28+
├── linux-almalinux9-x86_64_v2-gcc-13.1.0-sbndaq-artdaq-core-migration...rh3ysud.spec.json
29+
├── linux-almalinux9-x86_64_v2-gcc-13.1.0-sbndaq-artdaq-migration-jqsa5jy...tjge.spec.json
30+
├── linux-almalinux9-x86_64_v2-gcc-13.1.0-sbndaq-migration-4pqf6pn33ukjsi...vl7u.spec.json
31+
├── linux-almalinux9-x86_64_v2-gcc-13.1.0-sbndaq-suite-migration_artdaqv3_1...kw.spec.json
32+
└── linux-almalinux9-x86_64_v2-gcc-13.1.0-wibtools-migration-lcv3efcitbmz5m...fd.spec.json
33+
───────────────────────────────────────────────────────────────────────────────────────────────────
34+
```

‎develop-sbndaq-with-spack/examples/example_config_yaml.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
## The **config.yaml** file allows users to tailor Spack by setting system-specific preferences, including installation prefixes.
2+
3+
```txt
4+
───────┬─────────────────────────────────────────────────────────────────────────────────
5+
│ File: config.yaml
6+
───────┼─────────────────────────────────────────────────────────────────────────────────
7+
1 │ config:
8+
2 │ install_tree:
9+
3 │ root: /home/artdaq/DAQ_SPACK_DevAreas/DAQ_2..._artdaqv3_13_02/spack_packages
10+
4 │ padded_length: 255
11+
───────┴─────────────────────────────────────────────────────────────────────────────────
12+
```

‎develop-sbndaq-with-spack/examples/example_repos_yaml.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
## **repos.yaml** is a configuration file that lists the locations of package repositories. These repositories contain the package recipes.
2+
3+
``` txt
4+
───────┬─────────────────────────────────────────────────────────────────────────────────
5+
│ File: repos.yaml
6+
───────┼─────────────────────────────────────────────────────────────────────────────────
7+
1 │ repos:
8+
2 │ - /home/artdaq/DAQ_SPACK_DevAreas/DAQ_2025-06-..._artdaqv3_13_02/spack-repos/mpd
9+
3 │ - /daq/software/spack_packages/spack/v1.0.1.sbnd/spack-repos/sbn-spack
10+
4 │ - /daq/software/spack_packages/spack/v1.0.1.sbnd/spack-repos/artdaq-spack
11+
5 │ - /daq/software/spack_packages/spack/v1.0.1.sbnd/spack-repos/fnal_art
12+
6 │ - /daq/software/spack_packages/spack/v1.0.1.sbnd/spack-repos/scd_recipes
13+
───────┴─────────────────────────────────────────────────────────────────────────────────
14+
```

0 commit comments

Comments
 (0)