diff --git a/.gitignore b/.gitignore index e39ba11..405bac3 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ __pycache__/ *.py[cod] .venv/ build/ +docs/_build/ .zig-cache/ zig-out/ zig-pkg/ diff --git a/README.md b/README.md index 25b20fe..4237c19 100644 --- a/README.md +++ b/README.md @@ -145,7 +145,7 @@ The build does not pass `LD_LIBRARY_PATH`, `LD_PRELOAD` or `LD_AUDIT` through to `eb-local eb` is the way to run EasyBuild where there is no site file and no Slurm job: inside `eessi_container.sh`, on a laptop with the CernVM File System (CVMFS) mount, or anywhere else the EESSI init can be sourced. It sources that init, loads `EESSI-extend`, and execs `eb`. The module keeps EESSI's hooks, RPATH and compat layer. Host Cargo and CMake wrappers are unset first, and the compat-layer linker is put on `PATH` even when `rustc` is not installed. EasyBuild builds under `$WORKING_DIR/easybuild`, as the module sets it. This command leaves `WORKING_DIR` as you set it; unset, the module uses `/tmp/$USER`, so two users on one node do not share a build directory. -Set at most one install variable before it. A variable that is present and empty counts as set, which is how EESSI-extend reads them. With none set, this command exports nothing and creates nothing. The loaded module then installs under `$HOME/eessi`. Its help text says `$HOME/EESSI`; on EESSI 2026.06 the module uses the lowercase directory, and does not require it to exist before the load. +Set at most one install variable before it. A variable that is present and empty counts as set, which is how EESSI-extend reads them. With none set, this command exports nothing and creates nothing. The loaded module then installs under `$HOME/eessi`. Its help text says `$HOME/EESSI`; on EESSI 2026.06 the module uses the lowercase directory, and does not require it to exist before the load. With more than one set, this command stops with exit 3 and names each one, its value, and what EESSI-extend would do with them. | variable | mode | prefix | process umask | |---|---|---|---| @@ -166,6 +166,21 @@ eb-local eb -- example.eb --robot `--profile`, `--project` and `--config` are not this command's options. The project, site and cvmfs modes are the variables above. A caller that can pass only a program name, and then eb's own arguments, sets `EB_LOCAL_EESSI_EXTEND=1`. Every argument is then eb's, which is how an eb-stack EESSI target runs this command. The 1.x Bash script has no `eb` command. +### Where EESSI-extend installs + +EESSI-extend chooses the install tree as it loads: `DIR/versions/2026.06/software/linux/` for `EESSI_USER_INSTALL=DIR` or `EESSI_PROJECT_INSTALL=DIR`, the same below `$HOME/eessi` with none set, the site tree `$EESSI_SITE_SOFTWARE_PATH` for `EESSI_SITE_INSTALL`, and EESSI's own `$EESSI_SOFTWARE_PATH` for `EESSI_CVMFS_INSTALL`. +With a user and a project variable both set, it loads and makes a private user install, umask 077 and the sticky bit, in the user tree, and puts both module trees on `MODULEPATH`, the user's first; with the site or the cvmfs variable and another, it refuses to load. +So a variable left from an earlier session, by a `.bashrc` that exports `EESSI_USER_INSTALL` or by `eval "$(eb-local env)"` for another prefix, turns a project install typed by hand into one the rest of the project cannot read. + +A build clears every install variable and sets its own, and names each one it cleared from your shell. +`eb-local eb` refuses two or more, and `eb-local doctor` lists every one your shell has; unset the one you did not mean to keep. + +Once EESSI-extend has loaded, a build and `eb-local eb` stop with exit 2, before `eb` runs, unless `EASYBUILD_INSTALLPATH` is in the tree the install variable selects, and whenever `EASYBUILD_INSTALLPATH_SOFTWARE` or `EASYBUILD_INSTALLPATH_MODULES` is set. +A build's tree is `/versions`, which eb-local checked, lists and cleans of secrets. +Three things move the install path: a site Lmod hook that sets one (see the next section), a changed EESSI-extend, and an `EESSI_CVMFS_REPO` with a character such as `-`. EESSI-extend makes a user or project path by replacing `EESSI_CVMFS_REPO` in `$EESSI_SOFTWARE_PATH` with Lua's `string.gsub`, which reads it as a pattern, so a copy of the repository under `/opt/eessi-mirror` leaves the path unchanged and the install would go into the repository's own tree. +Both also say when loading EESSI-extend sets or unsets an install variable, as a site hook does: the variable stays in a shell, and that shell's next load installs elsewhere. +[Where EESSI-extend installs](docs/explanation/install-variables.md) has what each mode and mix of variables did under Lmod. + ### What a build runs `eb-local --explain` prints the script a build runs, and creates and runs nothing. @@ -176,7 +191,7 @@ A build names this command in its first line, as in `eb-local: what this runs: e eb-local --explain GSL-2.8-GCC-15.2.0.eb --robot ``` -The script does what you would type to use EESSI-extend by hand: clear the install variables a login shell may carry, set one of `EESSI_USER_INSTALL` or `EESSI_PROJECT_INSTALL`, load `EESSI/2026.06`, then `EESSI-extend`, which reads that variable as it loads, and run `eb`. +The script does what you would type to use EESSI-extend by hand: clear the install variables a login shell may carry, set one of `EESSI_USER_INSTALL` or `EESSI_PROJECT_INSTALL`, load `EESSI/2026.06`, then `EESSI-extend`, which reads that variable as it loads, check that the install path EESSI-extend set is in `/versions`, and run `eb`. `$W` stands for the workspace a build makes in the allocation's node-local mount. With `W` set to a directory, `bash` runs the printed text as a build runs its script; the checks before it and the cleaning of logs after it are eb-local's own. ## Where things go @@ -188,6 +203,12 @@ The script does what you would type to use EESSI-extend by hand: clear the insta | downloaded source archives | `/.eb-local/sources` | | build logs | `/.eb-local/logs` | +A build needs a Slurm allocation whose node-local directory, `/`, is its own mount, of the configured file system type, owned by you. +Shared parallel-file-system paths, tmpfs, enclosing mounts and symbolic-link aliases are refused before anything is created, and so is an install prefix on shared scratch or node-local storage. +A refusal says what it refused and why, and what the command then did not do; its next line says what to change: a setting, with its value and where it was set as `eb-local config` shows it, or the variable, option or command to use. +`eb-local doctor` says the same on one line. +[Refusals](docs/reference/refusals.md) lists each one. + The default prefix, `$HOME/eessi`, is EESSI-extend's own, so modules installed with `eb-local`, with `eb-local eb` and with EESSI-extend loaded by hand are in one tree, with the same permissions. That is why the default is not `$HOME/.local/eessi`: EESSI-extend, loaded with no install variable set, installs under `$HOME/eessi`, so any other default would split one user's modules into two trees, of which `eb-local env` shows one. Before 3.0 the default was `$HOME/.local/eessi`; where that exists and `$HOME/eessi` does not, eb-local keeps using it and says so. Set `prefix` to choose either for good. @@ -221,15 +242,16 @@ They apply when EESSI-extend is loaded by hand and under `eb-local eb`. An eb-local build puts its own workspace and `.eb-local/sources` back after EESSI-extend loads, so the build uses those, and the two do not conflict. Lmod undoes only what a module file sets, so the hook's values stay set after `module unload EESSI-extend`. -An install path from a hook bypasses eb-local's checks. +An install path from a hook stops eb-local. `EASYBUILD_INSTALLPATH`, `EASYBUILD_INSTALLPATH_SOFTWARE` or `EASYBUILD_INSTALLPATH_MODULES` set in a hook replaces the install path EESSI-extend chose, while the `MODULEPATH` the module set still names its own tree. -In an eb-local build, EasyBuild then installs, and writes its logs, outside the prefix eb-local checked: `eb-local env` and `list` do not show what it installed, and eb-local does not remove secret values from those logs. +EasyBuild would then install, and write its logs, outside the prefix eb-local checked, where `eb-local env` and `list` do not show what it installed and eb-local does not remove secret values from those logs, so a build and `eb-local eb` stop once EESSI-extend has loaded, before `eb` runs. A hook sets no install path. A default install prefix cannot come from a load hook. EESSI-extend reads `EESSI_USER_INSTALL` and the other install variables as its module file runs, and Lmod runs the load hook after that. A hook that sets `EESSI_USER_INSTALL=$HOME/.local/eessi` when no install variable is set is too late for that load, which installs under `$HOME/eessi`. The value stays after `module unload`, so the next load in the same shell installs under `$HOME/.local/eessi`, and which tree a user gets depends on what their shell did before. +A build and `eb-local eb` say so when loading EESSI-extend sets an install variable. A hook for the `EESSI` module itself does not run: that module sets `LMOD_PACKAGE_PATH`, through which Lmod finds EESSI's `SitePackage.lua` and so the site's, and neither is in effect for the command that loads it. So another default goes into the environment before EESSI-extend loads, for example `EESSI_USER_INSTALL` set by a login script in `/etc/profile.d`, and into eb-local's site file as `prefix`, before the file's first table, so that eb-local builds there too: @@ -240,9 +262,6 @@ prefix = "~/.local/eessi" `eb-local doctor` then says that `EESSI_USER_INSTALL` names your prefix. -A build needs a Slurm allocation whose node-local directory, `/`, is its own mount, of the configured file system type, owned by you. -Shared parallel-file-system paths, tmpfs, enclosing mounts and symbolic-link aliases are refused before anything is created. - ## Build for every node type A module is built for the CPU target of the node that built it, so a site with several node types needs one build on each. @@ -350,7 +369,7 @@ dev.modules = ["CUDA/13.3.0"] ``` `eb-local --profile gpu dev` or `EB_LOCAL_PROFILE=gpu` selects a profile; without either, `default_profile` does, from your file if it sets one, else from the site file. -The keys are `default_profile` (outside any profile), `prefix`, `project`, `stack.module`, `stack.extend`, `dev.buildenv`, `dev.buildenv_for.{cuda,llvm,intel,nvhpc}`, `dev.modules`, `build.allocation_hint`, `build.site_toolchains` and `build.node_types` (site file only), `clean.trash` (`auto`, `rtrash` or `none`), `clean.logs_older_than_days`, `nimvault.program`, `nimvault.vault`, `[eessi]` and `[secrets]`; the variables are `EB_LOCAL_PREFIX`, `EB_LOCAL_PROJECT`, `EB_LOCAL_STACK_MODULE`, `EB_LOCAL_STACK_EXTEND`, `EB_LOCAL_DEV_BUILDENV`, `EB_LOCAL_DEV_BUILDENV_FOR_{CUDA,LLVM,INTEL,NVHPC}` (`none` for the RPATH wrappers), `EB_LOCAL_DEV_MODULES`, `EB_LOCAL_BUILD_ALLOCATION_HINT`, `EB_LOCAL_CLEAN_TRASH`, `EB_LOCAL_CLEAN_LOGS_OLDER_THAN_DAYS`, `EB_LOCAL_NIMVAULT_PROGRAM`, `EB_LOCAL_NIMVAULT_VAULT` and `EB_LOCAL_SECRET_`. +The keys are `default_profile` (outside any profile), `prefix`, `project`, `stack.module`, `stack.extend`, `dev.buildenv`, `dev.buildenv_for.{cuda,llvm,intel,nvhpc}`, `dev.modules`, `build.allocation_hint`, `build.secrets`, `build.site_toolchains` and `build.node_types` (site file only), `clean.trash` (`auto`, `rtrash` or `none`), `clean.logs_older_than_days`, `nimvault.program`, `nimvault.vault`, `[eessi]` and `[secrets]`; the variables are `EB_LOCAL_PREFIX`, `EB_LOCAL_PROJECT`, `EB_LOCAL_STACK_MODULE`, `EB_LOCAL_STACK_EXTEND`, `EB_LOCAL_DEV_BUILDENV`, `EB_LOCAL_DEV_BUILDENV_FOR_{CUDA,LLVM,INTEL,NVHPC}` (`none` for the RPATH wrappers), `EB_LOCAL_DEV_MODULES`, `EB_LOCAL_BUILD_ALLOCATION_HINT`, `EB_LOCAL_BUILD_SECRETS`, `EB_LOCAL_CLEAN_TRASH`, `EB_LOCAL_CLEAN_LOGS_OLDER_THAN_DAYS`, `EB_LOCAL_NIMVAULT_PROGRAM`, `EB_LOCAL_NIMVAULT_VAULT` and `EB_LOCAL_SECRET_`. An unknown key, a wrong type, a duplicate key or an unsafe module name is an error naming its file and line, in every profile, selected or not. The site file is the first that exists of `config.toml` beside the program, `/etc/eb-local/config.toml`, and a 1.x `eb-local.conf` beside the program or in `/etc`. @@ -406,7 +425,8 @@ eb-local --profile gpu config --env > eb-local.env # sources only, never value ``` Empty settings are printed too, and `EB_LOCAL_PROFILE` is printed empty, which selects no profile, not even `default_profile`: the lines already hold every setting of the profile in force, and they work where that profile is not defined. -An empty `EB_LOCAL_DEV_MODULES`, `EB_LOCAL_BUILD_ALLOCATION_HINT`, `EB_LOCAL_NIMVAULT_PROGRAM` or `EB_LOCAL_NIMVAULT_VAULT` empties its setting; any other empty `EB_LOCAL_*` variable is ignored. +An empty `EB_LOCAL_DEV_MODULES`, `EB_LOCAL_BUILD_ALLOCATION_HINT`, `EB_LOCAL_BUILD_SECRETS`, `EB_LOCAL_NIMVAULT_PROGRAM` or `EB_LOCAL_NIMVAULT_VAULT` empties its setting; any other empty `EB_LOCAL_*` variable is ignored. +`EB_LOCAL_BUILD_SECRETS` is printed only when `build.secrets` is set, since without it a build gets every secret. `EB_LOCAL_SECRET_` is checked as a `[secrets]` entry is. `[eessi]` settings come out as the `EESSI_*` variables themselves, which reach EESSI as they are. The storage settings and `build.site_toolchains` have no variable: only the site file sets them. A configuration file is used only when it is a regular file, not a symbolic link, not writable by group or others, and owned by root or the program's owner (a site file) or by you (your file); otherwise eb-local stops. @@ -424,9 +444,26 @@ SOURCE_TOKEN = "file:~/.secrets/source-token" # your file, mode 600 MIRROR_PASSWORD = "env:MY_MIRROR_PASSWORD" ``` +A build gets every secret unless `build.secrets` names the ones it gets, and then only those: set it to `[]` in your file and name the secrets in the profile of the builds that need them, or for one build with `EB_LOCAL_BUILD_SECRETS`, names separated by spaces: + +```toml +# ~/.config/eb-local/config.toml +[build] +secrets = [] # no build gets a secret it does not name + +[profile.licensed] +build.secrets = ["LM_LICENSE_FILE"] # eb-local --profile licensed MATLAB-2026a.eb +``` + +```sh +EB_LOCAL_BUILD_SECRETS=SOURCE_TOKEN eb-local Private-1.0-GCC-15.2.0.eb +``` + +A secret a build does not get is not read, so it cannot stop that build. A name no secret has is an error that says where it was set. `eb-local config` shows `build.secrets`, and `eb-local --explain RECIPE` which secrets reach `eb`. [Give a secret only to the builds that need it](docs/howto/scope-secrets.md) has the steps. + - Values are read only for a build, after every other check, and go only into the environment of `eb` and what it runs. - `eb-local config --check` reads each secret and reports `ok` or why not, never the value. -- After the build, the logs written during it (in `.eb-local/logs` and each installation's `easybuild/`) have each value, its base64 form and its percent-encoded form (either hex case) replaced. The usual replacement is ``; a value that those words contain is replaced with `` instead, so the marker does not put the value back. Where one value is a prefix of another, the longer one is removed whole. The log directory is private meanwhile. EasyBuild compresses the copy in an installation (with `bzip2` under EESSI-extend): a log ending in `.bz2`, `.gz`, `.xz` or `.zst` is decompressed and compressed again with `bzip2`, `gzip`, `xz` or `zstd` from `PATH`. A value shorter than 4 bytes, or a log that is too large or too deep to check or that cannot be decompressed, is reported instead, including an installation log nested too deep to reach. A secret reaches every program the build runs. A build stopped with a signal is cleaned up, including those logs, and eb-local then dies from that same signal, so a cancelled job does not continue; a build killed with SIGKILL leaves its logs unchecked. eb-local passes SIGINT, SIGTERM, SIGHUP and SIGQUIT on to EasyBuild, except one from the terminal, such as Ctrl-C, which reaches EasyBuild directly, and cleans the logs only once EasyBuild has exited, so the lines it writes as it stops are cleaned too. An ignored signal, as SIGHUP is under `nohup`, stays ignored. `eb-local eb` passes signals on in the same way. +- After the build, the logs written during it (in `.eb-local/logs` and each installation's `easybuild/`) have each value, its base64 form and its percent-encoded form (either hex case) replaced. The usual replacement is ``; a value that those words contain is replaced with `` instead, so the marker does not put the value back. Where one value is a prefix of another, the longer one is removed whole. The log directory is private meanwhile. EasyBuild compresses the copy in an installation (with `bzip2` under EESSI-extend): a log ending in `.bz2`, `.gz`, `.xz` or `.zst` is decompressed and compressed again with `bzip2`, `gzip`, `xz` or `zstd` from `PATH`. A value shorter than 4 bytes, or a log that is too large or too deep to check or that cannot be decompressed, is reported instead, including an installation log nested too deep to reach. A secret a build gets reaches every program the build runs. A build stopped with a signal is cleaned up, including those logs, and eb-local then dies from that same signal, so a cancelled job does not continue; a build killed with SIGKILL leaves its logs unchecked. eb-local passes SIGINT, SIGTERM, SIGHUP and SIGQUIT on to EasyBuild, except one from the terminal, such as Ctrl-C, which reaches EasyBuild directly, and cleans the logs only once EasyBuild has exited, so the lines it writes as it stops are cleaned too. An ignored signal, as SIGHUP is under `nohup`, stays ignored. `eb-local eb` passes signals on in the same way. - A secret cannot set `PATH`, `LD_*`, `EESSI_*`, `EASYBUILD_*` or another variable the build depends on. - [nimvault](https://github.com/HaoZeke/nimvault) runs with a 30-second deadline; on failure eb-local shows its error output, never what it printed as the value. - nimvault finds its vault from `NIMVAULT_VAULT_REPO` or the current git repository, so a build started inside another repository reads that one. Name the vault, and the program if it is not on `PATH`: @@ -484,6 +521,8 @@ zig build unit && zig build test # the Zig build: unit A change adds a news fragment, `changelog.d/..md` with type `feature`, `bugfix`, `doc`, `removal` or `misc`; `towncrier build --draft --version 2.1.2` shows the release notes it makes. +The documentation is this README and the pages under `docs/`. A page with an Org source in `docs/orgmode/` is written from it, so edit the Org file and run `emacs --batch -Q -l docs/export.el`; `tests/test_docs.py` checks that the two agree where Emacs is installed. `python -m sphinx -W -b html docs docs/_build/html` builds the site, as CI does. + `tests/site/` holds the site acceptance scripts: the development tasks above, and a build inside an allocation, which takes the site's partition and node-local disk feature on its `sbatch` line and finds the allocation's mount from the site file. ## License diff --git a/changelog.d/+build-secrets.feature.md b/changelog.d/+build-secrets.feature.md new file mode 100644 index 0000000..7a73eeb --- /dev/null +++ b/changelog.d/+build-secrets.feature.md @@ -0,0 +1 @@ +`build.secrets`, in a configuration file or a profile, and `EB_LOCAL_BUILD_SECRETS`, for one build, name the secrets a build gets: the build reads only those, so a secret it does not get never reaches `eb`, and one that cannot be read no longer stops it. Without either, every build gets every secret, as before. A name that no secret in force has is an error saying where it was set. `eb-local config` shows the setting, `config --env` carries it, `--explain` says which secrets reach `eb`, and `doctor` says FAIL only for a secret builds get, and otherwise warns. The documentation has a how-to page. diff --git a/changelog.d/+install-path-check.bugfix.md b/changelog.d/+install-path-check.bugfix.md new file mode 100644 index 0000000..136b3a4 --- /dev/null +++ b/changelog.d/+install-path-check.bugfix.md @@ -0,0 +1 @@ +A build and `eb-local eb` check where EESSI-extend will install once it has loaded, and stop with exit 2, before `eb` runs, when `EASYBUILD_INSTALLPATH` is outside the tree the install variable selects, `/versions` for a build, or when `EASYBUILD_INSTALLPATH_SOFTWARE` or `EASYBUILD_INSTALLPATH_MODULES` is set. Before, a site Lmod hook that set an install path, or an `EESSI_CVMFS_REPO` with a character such as `-`, which EESSI-extend matches as a Lua pattern, sent the install and its logs outside the prefix eb-local had checked and cleans of secrets while eb-local said it was installing into that prefix, and `eb-local eb` passed a leftover `EASYBUILD_INSTALLPATH_MODULES` on to EasyBuild, splitting an install between two trees. Both now say when loading EESSI-extend sets or unsets an install variable, as a site load hook does too late for its own load. A build names each install variable it clears from the caller's shell, and the refusal of more than one install variable by `eb-local eb` names each with its value and what EESSI-extend would do with them: with a user and a project variable, a private user install. diff --git a/changelog.d/+install-variables-docs.doc.md b/changelog.d/+install-variables-docs.doc.md new file mode 100644 index 0000000..c2f47bf --- /dev/null +++ b/changelog.d/+install-variables-docs.doc.md @@ -0,0 +1 @@ +The documentation has a page on where EESSI-extend installs under each install variable and each mix of them, as the module did under Lmod, on the trap a variable left from an earlier session sets, and on what eb-local checks. Pages besides the README are written in Org under `docs/orgmode` and exported to the MyST pages Sphinx builds with `emacs --batch -Q -l docs/export.el`, which needs only the Markdown backend Org has; a test checks the committed pages against a fresh export where Emacs is installed. diff --git a/changelog.d/+node-local-refusals.bugfix.md b/changelog.d/+node-local-refusals.bugfix.md new file mode 100644 index 0000000..9fa94a1 --- /dev/null +++ b/changelog.d/+node-local-refusals.bugfix.md @@ -0,0 +1 @@ +The refusals of a build's node-local mount and install prefix, by a build, `eb-local clean` and `eb-local doctor`, now say what was refused and why, what the command then did not do, and, on the next line, what to change: the setting, with its value and where it was set as `eb-local config` shows it, or the variable, option or command. Before, most said only that the allocation's node-local root "must be an owned writable directory" or that paths "must use durable owned storage", without the path, the setting or the reason. A workspace that cannot be made in a mount that passed the checks names the error the kernel gave, and a setting in a 1.x `eb-local.conf` is shown with its own line. The documentation has a page listing each refusal. diff --git a/docs/explanation/install-variables.md b/docs/explanation/install-variables.md new file mode 100644 index 0000000..39cb852 --- /dev/null +++ b/docs/explanation/install-variables.md @@ -0,0 +1,95 @@ + + +# Where EESSI-extend installs + +EESSI-extend chooses the tree EasyBuild installs into when the module loads, from four install variables. +eb-local loads it in two ways: a build sets one variable itself, and `eb-local eb` uses the ones the shell has. +This page says where each variable, and each mix of them, sends an install, why a variable left from an earlier session is a trap, and what eb-local checks. + +The results below come from the EESSI-extend module that EESSI's software-layer-scripts generate (commit `169e720f`), loaded under Lmod 8.6.19 on a stand-in EESSI 2026.06 tree for the CPU target `x86_64/amd/zen4`, with `HOME=/home/alice`. + +## One install variable + +| Set before the load | EESSI-extend installs into | umask, and bit | +|---|---|---| +| `EESSI_USER_INSTALL=DIR` | `DIR/versions/2026.06/software/linux/x86_64/amd/zen4` | 077, sticky | +| `EESSI_PROJECT_INSTALL=DIR` | `DIR/versions/2026.06/software/linux/x86_64/amd/zen4` | 002, setgid | +| `EESSI_SITE_INSTALL` | `$EESSI_SITE_SOFTWARE_PATH`, the site tree in `host_injections` | 022 | +| `EESSI_CVMFS_INSTALL` | `$EESSI_SOFTWARE_PATH`, EESSI's own tree | 022 | +| none | `/home/alice/eessi/versions/2026.06/software/linux/x86_64/amd/zen4` | 077, sticky | + +The module tests each variable with `os.getenv(name) ~= nil`, so a variable that is present and empty counts as set. +A named user or project directory must exist, or the module refuses to load; `$HOME/eessi` need not. +The module puts the tree's `modules/all` first on `MODULEPATH`. + +## Two at once + +| Set before the load | What EESSI-extend does | +|---|---| +| `EESSI_USER_INSTALL` and `EESSI_PROJECT_INSTALL` | loads, installs into the user tree with umask 077 and the sticky bit, and puts both module trees on `MODULEPATH`, the user's first | +| `EESSI_SITE_INSTALL` and a user or project variable | refuses to load | +| `EESSI_CVMFS_INSTALL` and any other | refuses to load | + +The first row is the trap. +A `.bashrc` that exports `EESSI_USER_INSTALL`, or `eval "$(eb-local env)"` run earlier for a user prefix, leaves the variable in the shell. +A project install typed by hand there, `export EESSI_PROJECT_INSTALL=/path/to/project/eessi` and then `module load EESSI-extend`, becomes a private user install that the rest of the project cannot read. +Lmod says nothing about it but a second line, `Configuring for use of EESSI_USER_INSTALL under /home/alice/eessi`, after the project one. + +## What eb-local does with the variables + +A build clears every install variable, sets `EESSI_USER_INSTALL` or `EESSI_PROJECT_INSTALL` to its prefix, and loads EESSI-extend afresh, so what the shell carries does not reach it. +It names each one it cleared: + +```text +eb-local: EESSI_USER_INSTALL=/home/alice/eessi is set in this shell; this build clears it, but EESSI-extend or eb run by hand would use it +``` + +`eb-local eb` uses the variables the shell has, so it refuses two or more, with exit 3, and says what EESSI-extend would do with them: + +```text +eb-local: EESSI_USER_INSTALL=/home/alice/eessi and EESSI_PROJECT_INSTALL=/path/to/project/eessi are both set; EESSI-extend would make a private user install (umask 077) under /home/alice/eessi, not a project install under /path/to/project/eessi. + Unset the one an earlier session left (a shell startup file, or eval "$(eb-local env)" for another prefix): + set at most one of EESSI_USER_INSTALL, EESSI_PROJECT_INSTALL, EESSI_SITE_INSTALL, EESSI_CVMFS_INSTALL; with none set, the module installs under $HOME/eessi +``` + +`eb-local doctor` lists every install variable the shell has, and says which one names your prefix. + +## The install path, once the module has loaded + +EESSI-extend sets `EASYBUILD_INSTALLPATH` to the tree in the first table. +Once it has loaded, a build and `eb-local eb` stop with exit 2, before `eb` runs, unless that path is in the tree the install variable selects. +For a build that tree is `/versions`, which eb-local checked before the build, lists afterwards and cleans of secret values; for `eb-local eb` it is the tree in the first table. +They also stop when `EASYBUILD_INSTALLPATH_SOFTWARE` or `EASYBUILD_INSTALLPATH_MODULES` is set, since EasyBuild would then put the software or the modules somewhere else while `MODULEPATH` names EESSI-extend's tree. + +Three things move the install path: + +- a site Lmod hook that sets one, which the README's [A site Lmod hook](../index.md#a-site-lmod-hook) warns against; +- a changed EESSI-extend; +- an `EESSI_CVMFS_REPO` with a character such as `-`. + +The last is EESSI-extend's own. +It makes a user or project path with `string.gsub(EESSI_SOFTWARE_PATH, EESSI_CVMFS_REPO, DIR)`, and Lua reads the second argument as a pattern, where `-`, `+`, `*`, `?`, `%`, `(`, `)`, `[` and `^` are not themselves. +With a copy of the repository under `/opt/eessi-mirror` the pattern does not match, the path is left as it was, and the install would go into the repository's own tree. +The default, `/cvmfs/software.eessi.io`, has only `.`, which matches itself among the rest. +A build there used to say `installing into /home/alice/eessi (user)` while EasyBuild was given the repository's tree; it now stops: + +```text +eb-local: loading EESSI-extend/2026.06-easybuild set the install path to /opt/eessi-mirror/versions/2026.06/software/linux/x86_64/amd/zen4, outside /home/alice/eessi/versions, the tree eb-local checked; nothing was built. + EESSI_USER_INSTALL did not choose it: a site Lmod hook, a changed EESSI-extend, or a character such as - in EESSI_CVMFS_REPO, which EESSI-extend matches as a Lua pattern, did. See "Where EESSI-extend installs" in the README. +``` + +## A variable set as the module loads + +A site Lmod hook that sets an install variable when EESSI-extend loads runs after the module has read the variables, so the load it runs in installs where it would have anyway. +The value stays in the shell after `module unload`, and the next load installs there. +With a hook that sets `EESSI_USER_INSTALL=/home/alice/.local/eessi` when no install variable is set, the first load in a shell installed under `/home/alice/eessi`, and a second one, after `module unload EESSI-extend`, under `/home/alice/.local/eessi`; `MODULEPATH` then held both trees. + +eb-local cannot tell a variable a hook left in an earlier load from one set on purpose. +It does see a load that sets or unsets one, and says so: + +```text +eb-local: loading EESSI-extend set EESSI_USER_INSTALL=/home/alice/.local/eessi; this install still goes under /home/alice/eessi, but a shell that loads EESSI-extend by hand keeps the change, and its next load installs elsewhere. + A site Lmod hook that sets an install variable acts only on the next load. See "Where EESSI-extend installs" in the README. +``` + +A site that wants another default prefix sets it before EESSI-extend loads, in a login script, and as `prefix` in eb-local's site file, as the README's [A site Lmod hook](../index.md#a-site-lmod-hook) shows. diff --git a/docs/export.el b/docs/export.el new file mode 100644 index 0000000..884b651 --- /dev/null +++ b/docs/export.el @@ -0,0 +1,136 @@ +;;; export.el --- Export docs/orgmode to the MyST pages Sphinx builds -*- lexical-binding: t; -*- + +;; The pages under docs/ that have an Org source are written from it: +;; docs/orgmode/PART/NAME.org becomes docs/PART/NAME.md. Edit the Org +;; file and run, from the repository: +;; +;; emacs --batch -l docs/export.el +;; +;; EB_LOCAL_DOCS_OUT names another directory to write into, which is how +;; the tests compare a fresh export with the committed pages. Only Org's +;; own Markdown backend is used, so any Emacs 29 can run this. + +;;; Code: + +(require 'ox-md) +(require 'subr-x) + +(defconst eb-local-docs-root + (file-name-directory (or load-file-name buffer-file-name)) + "The docs/ directory.") + +(defun eb-local-docs--fence (lang code) + "CODE in a fenced block, tagged LANG when there is one." + (format "```%s\n%s```\n" (or lang "") (org-remove-indentation code))) + +(defun eb-local-docs--src-block (src-block _contents info) + (eb-local-docs--fence (org-element-property :language src-block) + (org-export-format-code-default src-block info))) + +(defun eb-local-docs--example-block (example-block _contents info) + (eb-local-docs--fence "text" (org-export-format-code-default example-block info))) + +(defun eb-local-docs--fixed-width (fixed-width _contents _info) + (eb-local-docs--fence "text" (org-element-property :value fixed-width))) + +(defun eb-local-docs--table-cell (_cell contents _info) + (replace-regexp-in-string "|" "\\\\|" (string-trim (or contents "")))) + +(defun eb-local-docs--table-row (row _contents info) + "A pipe-table row, and the separator after the header, or after the +first row of a table that has none." + (unless (eq (org-element-property :type row) 'rule) + (let* ((cells (org-element-contents row)) + (table (org-export-get-parent-table row)) + (header (or (org-export-table-row-ends-header-p row info) + (and (not (org-export-table-has-header-p table info)) + (= (org-export-table-row-number row info) 0))))) + (concat "| " + (string-join (mapcar (lambda (cell) (org-export-data cell info)) cells) " | ") + " |\n" + (when header + (concat "|" (string-join (make-list (length cells) "---") "|") "|\n")))))) + +(defun eb-local-docs--table (_table contents _info) + "The rows, without the blank lines Org's Markdown puts between elements." + (replace-regexp-in-string "\n\\(?:[ \t]*\n\\)+" "\n" contents)) + +(defun eb-local-docs--item (item contents info) + "A description item as a MyST definition, anything else as Org's Markdown has it." + (let ((tag (org-element-property :tag item))) + (if (not tag) + (org-md-item item contents info) + (format "%s\n: %s\n" (org-export-data tag info) + (replace-regexp-in-string "\n\\(.\\)" "\n \\1" (string-trim (or contents ""))))))) + +(defun eb-local-docs--plain-list (plain-list contents info) + "A description list as definitions with a blank line between them." + (if (eq (org-element-property :type plain-list) 'descriptive) + (mapconcat (lambda (item) (org-export-data item info)) + (org-element-contents plain-list) "\n") + (org-md-plain-list plain-list contents info))) + +(defun eb-local-docs--link (link desc info) + "Org's Markdown link, keeping a #anchor search option on a file link." + (let ((search (org-element-property :search-option link))) + (if (and (string= (org-element-property :type link) "file") + search (string-prefix-p "#" search)) + (let ((path (org-element-property :path link))) + (when (string-suffix-p ".org" path) + (setq path (concat (file-name-sans-extension path) ".md"))) + (format "[%s](%s%s)" (or desc path) path search)) + (org-md-link link desc info)))) + +(defun eb-local-docs--template (contents info) + "The page: where it comes from, its title, then its contents." + (format "\n\n# %s\n\n%s" + (plist-get info :eb-local-source) + (org-export-data (plist-get info :title) info) + contents)) + +(defun eb-local-docs--tidy (text _backend _info) + "One blank line between blocks, and a single newline at the end." + (concat (string-trim (replace-regexp-in-string "\n\\(?:[ \t]*\n\\)\\{2,\\}" "\n\n" text)) "\n")) + +(org-export-define-derived-backend 'eb-local-myst 'md + :translate-alist '((src-block . eb-local-docs--src-block) + (example-block . eb-local-docs--example-block) + (fixed-width . eb-local-docs--fixed-width) + (table . eb-local-docs--table) + (table-row . eb-local-docs--table-row) + (table-cell . eb-local-docs--table-cell) + (item . eb-local-docs--item) + (plain-list . eb-local-docs--plain-list) + (link . eb-local-docs--link) + (template . eb-local-docs--template)) + :filters-alist '((:filter-final-output . eb-local-docs--tidy))) + +(defun eb-local-docs-export (out) + "Write each Org page under docs/orgmode as MyST under OUT." + (let ((src (expand-file-name "orgmode" eb-local-docs-root)) + (org-md-headline-style 'atx) + (org-md-toplevel-hlevel 2) + (org-export-with-toc nil) + (org-export-with-section-numbers nil) + (org-export-with-author nil) + (org-export-with-date nil) + (org-export-with-sub-superscripts '{}) + (org-export-time-stamp-file nil) + (make-backup-files nil)) + (dolist (org (directory-files-recursively src "\\.org\\'")) + (let* ((rel (file-relative-name org src)) + (md (expand-file-name (concat (file-name-sans-extension rel) ".md") out))) + (make-directory (file-name-directory md) t) + (with-temp-buffer + (insert-file-contents org) + (setq default-directory (file-name-directory org)) + (org-mode) + (let ((text (org-export-as 'eb-local-myst nil nil nil + (list :eb-local-source rel)))) + (with-temp-file md (insert text)))) + (message "%s" md))))) + +(when noninteractive + (eb-local-docs-export (or (getenv "EB_LOCAL_DOCS_OUT") eb-local-docs-root))) + +;;; export.el ends here diff --git a/docs/howto/scope-secrets.md b/docs/howto/scope-secrets.md new file mode 100644 index 0000000..cf8830a --- /dev/null +++ b/docs/howto/scope-secrets.md @@ -0,0 +1,65 @@ + + +# Give a secret only to the builds that need it + +Every build gets every secret the configuration defines, unless `build.secrets` names the ones it gets. +A build reads only the secrets it gets, so one it does not get cannot stop it, and its value never reaches `eb` or anything `eb` runs. +These steps keep a licence and a source token away from the builds that do not use them. +The secrets are defined in `[secrets]`, or as `EB_LOCAL_SECRET_` variables, as [Secrets](../index.md#secrets) describes. + +## Give no secret by default + +Set `build.secrets` to an empty list in your file, beside the secrets: + +```toml +# ~/.config/eb-local/config.toml +[build] +secrets = [] + +[secrets] +LM_LICENSE_FILE = "nimvault:licences/flexlm" +SOURCE_TOKEN = "file:~/.secrets/source-token" +``` + +`eb-local config` now shows `build.secrets` as `(none)`, and where it was set. +A site file can set it in the same way for everyone; your file then overrides it. + +## Name the secrets of a kind of build in a profile + +```toml +[profile.licensed] +build.secrets = ["LM_LICENSE_FILE"] +``` + +```sh +eb-local --profile licensed MATLAB-2026a.eb +``` + +The profile's list replaces the one above it; it does not add to it. + +## Name the secrets of one build + +`EB_LOCAL_BUILD_SECRETS` names them, separated by spaces, in place of `build.secrets`; set but empty, it names none: + +```sh +EB_LOCAL_BUILD_SECRETS=SOURCE_TOKEN eb-local Private-1.0-GCC-15.2.0.eb +``` + +The `sbatch` lines that `eb-local --explain` prints for each node type run the build with the environment of the shell that runs them, so export the variable in that shell instead. + +## Check what a build gets + +```sh +eb-local config # build.secrets, and where it was set +eb-local --explain MATLAB-2026a.eb # which secrets reach eb, and which stay out +eb-local doctor # which secrets can be read, and which would stop a build +``` + +A name that no secret in force has stops eb-local, which says where the name was set: + +```text +eb-local: build.secrets [user /home/alice/.config/eb-local/config.toml:2] names TOKEN, but no secret TOKEN is defined: add it to [secrets], or set EB_LOCAL_SECRET_TOKEN=SOURCE +``` + +With a site file, `eb-local doctor` says FAIL for a secret that cannot be read only when builds get it; one they do not get is a warning. +Without `build.secrets` anywhere, `doctor` suggests naming the secrets builds need when one of them cannot be read, since every build would stop there. diff --git a/docs/index.md b/docs/index.md index 1381cf2..b15f95d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,12 +15,15 @@ ```{include} ../README.md :start-after: :end-before: +:relative-docs: docs/ ``` ```{toctree} :hidden: :maxdepth: 1 - +howto/scope-secrets +reference/refusals +explanation/install-variables ``` diff --git a/docs/orgmode/explanation/install-variables.org b/docs/orgmode/explanation/install-variables.org new file mode 100644 index 0000000..f2092e6 --- /dev/null +++ b/docs/orgmode/explanation/install-variables.org @@ -0,0 +1,93 @@ +#+title: Where EESSI-extend installs + +EESSI-extend chooses the tree EasyBuild installs into when the module loads, from four install variables. +eb-local loads it in two ways: a build sets one variable itself, and =eb-local eb= uses the ones the shell has. +This page says where each variable, and each mix of them, sends an install, why a variable left from an earlier session is a trap, and what eb-local checks. + +The results below come from the EESSI-extend module that EESSI's software-layer-scripts generate (commit =169e720f=), loaded under Lmod 8.6.19 on a stand-in EESSI 2026.06 tree for the CPU target =x86_64/amd/zen4=, with =HOME=/home/alice=. + +* One install variable + +| Set before the load | EESSI-extend installs into | umask, and bit | +|-------------------------------+----------------------------------------------------------------+----------------| +| =EESSI_USER_INSTALL=DIR= | =DIR/versions/2026.06/software/linux/x86_64/amd/zen4= | 077, sticky | +| =EESSI_PROJECT_INSTALL=DIR= | =DIR/versions/2026.06/software/linux/x86_64/amd/zen4= | 002, setgid | +| =EESSI_SITE_INSTALL= | =$EESSI_SITE_SOFTWARE_PATH=, the site tree in =host_injections= | 022 | +| =EESSI_CVMFS_INSTALL= | =$EESSI_SOFTWARE_PATH=, EESSI's own tree | 022 | +| none | =/home/alice/eessi/versions/2026.06/software/linux/x86_64/amd/zen4= | 077, sticky | + +The module tests each variable with ~os.getenv(name) ~= nil~, so a variable that is present and empty counts as set. +A named user or project directory must exist, or the module refuses to load; =$HOME/eessi= need not. +The module puts the tree's =modules/all= first on =MODULEPATH=. + +* Two at once + +| Set before the load | What EESSI-extend does | +|-----------------------------------------------------+---------------------------------------------------------------------------------------------------------| +| =EESSI_USER_INSTALL= and =EESSI_PROJECT_INSTALL= | loads, installs into the user tree with umask 077 and the sticky bit, and puts both module trees on =MODULEPATH=, the user's first | +| =EESSI_SITE_INSTALL= and a user or project variable | refuses to load | +| =EESSI_CVMFS_INSTALL= and any other | refuses to load | + +The first row is the trap. +A =.bashrc= that exports =EESSI_USER_INSTALL=, or =eval "$(eb-local env)"= run earlier for a user prefix, leaves the variable in the shell. +A project install typed by hand there, =export EESSI_PROJECT_INSTALL=/path/to/project/eessi= and then =module load EESSI-extend=, becomes a private user install that the rest of the project cannot read. +Lmod says nothing about it but a second line, =Configuring for use of EESSI_USER_INSTALL under /home/alice/eessi=, after the project one. + +* What eb-local does with the variables + +A build clears every install variable, sets =EESSI_USER_INSTALL= or =EESSI_PROJECT_INSTALL= to its prefix, and loads EESSI-extend afresh, so what the shell carries does not reach it. +It names each one it cleared: + +#+begin_example +eb-local: EESSI_USER_INSTALL=/home/alice/eessi is set in this shell; this build clears it, but EESSI-extend or eb run by hand would use it +#+end_example + +=eb-local eb= uses the variables the shell has, so it refuses two or more, with exit 3, and says what EESSI-extend would do with them: + +#+begin_example +eb-local: EESSI_USER_INSTALL=/home/alice/eessi and EESSI_PROJECT_INSTALL=/path/to/project/eessi are both set; EESSI-extend would make a private user install (umask 077) under /home/alice/eessi, not a project install under /path/to/project/eessi. + Unset the one an earlier session left (a shell startup file, or eval "$(eb-local env)" for another prefix): + set at most one of EESSI_USER_INSTALL, EESSI_PROJECT_INSTALL, EESSI_SITE_INSTALL, EESSI_CVMFS_INSTALL; with none set, the module installs under $HOME/eessi +#+end_example + +=eb-local doctor= lists every install variable the shell has, and says which one names your prefix. + +* The install path, once the module has loaded + +EESSI-extend sets =EASYBUILD_INSTALLPATH= to the tree in the first table. +Once it has loaded, a build and =eb-local eb= stop with exit 2, before =eb= runs, unless that path is in the tree the install variable selects. +For a build that tree is =/versions=, which eb-local checked before the build, lists afterwards and cleans of secret values; for =eb-local eb= it is the tree in the first table. +They also stop when =EASYBUILD_INSTALLPATH_SOFTWARE= or =EASYBUILD_INSTALLPATH_MODULES= is set, since EasyBuild would then put the software or the modules somewhere else while =MODULEPATH= names EESSI-extend's tree. + +Three things move the install path: + +- a site Lmod hook that sets one, which the README's [[file:../index.md::#a-site-lmod-hook][A site Lmod hook]] warns against; +- a changed EESSI-extend; +- an =EESSI_CVMFS_REPO= with a character such as =-=. + +The last is EESSI-extend's own. +It makes a user or project path with =string.gsub(EESSI_SOFTWARE_PATH, EESSI_CVMFS_REPO, DIR)=, and Lua reads the second argument as a pattern, where =-=, =+=, =*=, =?=, =%=, =(=, =)=, =[= and =^= are not themselves. +With a copy of the repository under =/opt/eessi-mirror= the pattern does not match, the path is left as it was, and the install would go into the repository's own tree. +The default, =/cvmfs/software.eessi.io=, has only =.=, which matches itself among the rest. +A build there used to say =installing into /home/alice/eessi (user)= while EasyBuild was given the repository's tree; it now stops: + +#+begin_example +eb-local: loading EESSI-extend/2026.06-easybuild set the install path to /opt/eessi-mirror/versions/2026.06/software/linux/x86_64/amd/zen4, outside /home/alice/eessi/versions, the tree eb-local checked; nothing was built. + EESSI_USER_INSTALL did not choose it: a site Lmod hook, a changed EESSI-extend, or a character such as - in EESSI_CVMFS_REPO, which EESSI-extend matches as a Lua pattern, did. See "Where EESSI-extend installs" in the README. +#+end_example + +* A variable set as the module loads + +A site Lmod hook that sets an install variable when EESSI-extend loads runs after the module has read the variables, so the load it runs in installs where it would have anyway. +The value stays in the shell after =module unload=, and the next load installs there. +With a hook that sets =EESSI_USER_INSTALL=/home/alice/.local/eessi= when no install variable is set, the first load in a shell installed under =/home/alice/eessi=, and a second one, after =module unload EESSI-extend=, under =/home/alice/.local/eessi=; =MODULEPATH= then held both trees. + +eb-local cannot tell a variable a hook left in an earlier load from one set on purpose. +It does see a load that sets or unsets one, and says so: + +#+begin_example +eb-local: loading EESSI-extend set EESSI_USER_INSTALL=/home/alice/.local/eessi; this install still goes under /home/alice/eessi, but a shell that loads EESSI-extend by hand keeps the change, and its next load installs elsewhere. + A site Lmod hook that sets an install variable acts only on the next load. See "Where EESSI-extend installs" in the README. +#+end_example + +A site that wants another default prefix sets it before EESSI-extend loads, in a login script, and as =prefix= in eb-local's site file, as the README's [[file:../index.md::#a-site-lmod-hook][A site Lmod hook]] shows. diff --git a/docs/orgmode/howto/scope-secrets.org b/docs/orgmode/howto/scope-secrets.org new file mode 100644 index 0000000..2808141 --- /dev/null +++ b/docs/orgmode/howto/scope-secrets.org @@ -0,0 +1,63 @@ +#+title: Give a secret only to the builds that need it + +Every build gets every secret the configuration defines, unless =build.secrets= names the ones it gets. +A build reads only the secrets it gets, so one it does not get cannot stop it, and its value never reaches =eb= or anything =eb= runs. +These steps keep a licence and a source token away from the builds that do not use them. +The secrets are defined in =[secrets]=, or as =EB_LOCAL_SECRET_= variables, as [[file:../index.md::#secrets][Secrets]] describes. + +* Give no secret by default + +Set =build.secrets= to an empty list in your file, beside the secrets: + +#+begin_src toml +# ~/.config/eb-local/config.toml +[build] +secrets = [] + +[secrets] +LM_LICENSE_FILE = "nimvault:licences/flexlm" +SOURCE_TOKEN = "file:~/.secrets/source-token" +#+end_src + +=eb-local config= now shows =build.secrets= as =(none)=, and where it was set. +A site file can set it in the same way for everyone; your file then overrides it. + +* Name the secrets of a kind of build in a profile + +#+begin_src toml +[profile.licensed] +build.secrets = ["LM_LICENSE_FILE"] +#+end_src + +#+begin_src sh +eb-local --profile licensed MATLAB-2026a.eb +#+end_src + +The profile's list replaces the one above it; it does not add to it. + +* Name the secrets of one build + +=EB_LOCAL_BUILD_SECRETS= names them, separated by spaces, in place of =build.secrets=; set but empty, it names none: + +#+begin_src sh +EB_LOCAL_BUILD_SECRETS=SOURCE_TOKEN eb-local Private-1.0-GCC-15.2.0.eb +#+end_src + +The =sbatch= lines that =eb-local --explain= prints for each node type run the build with the environment of the shell that runs them, so export the variable in that shell instead. + +* Check what a build gets + +#+begin_src sh +eb-local config # build.secrets, and where it was set +eb-local --explain MATLAB-2026a.eb # which secrets reach eb, and which stay out +eb-local doctor # which secrets can be read, and which would stop a build +#+end_src + +A name that no secret in force has stops eb-local, which says where the name was set: + +#+begin_example +eb-local: build.secrets [user /home/alice/.config/eb-local/config.toml:2] names TOKEN, but no secret TOKEN is defined: add it to [secrets], or set EB_LOCAL_SECRET_TOKEN=SOURCE +#+end_example + +With a site file, =eb-local doctor= says FAIL for a secret that cannot be read only when builds get it; one they do not get is a warning. +Without =build.secrets= anywhere, =doctor= suggests naming the secrets builds need when one of them cannot be read, since every build would stop there. diff --git a/docs/orgmode/reference/refusals.org b/docs/orgmode/reference/refusals.org new file mode 100644 index 0000000..d1c1db3 --- /dev/null +++ b/docs/orgmode/reference/refusals.org @@ -0,0 +1,99 @@ +#+title: Refusals + +A build checks where it would work and where it would install, and stops before it makes anything there when either is wrong. +=eb-local clean= checks the trees it would remove from before it removes anything, and =eb-local doctor= reports what a build would refuse. +This page lists each refusal: what it refused, why, and what to change. +The README's [[file:../index.md::#where-things-go][Where things go]] says where each thing goes, and [[file:../explanation/install-variables.org][Where EESSI-extend installs]] has the refusals of =eb-local eb= and of an install path EESSI-extend moves. + +* The form + +A refusal is two lines or more on standard error, and the command exits with status 2: + +#+begin_example +eb-local: WHAT WAS REFUSED, AND WHY; WHAT THE COMMAND DID NOT DO. + WHAT TO CHANGE. +#+end_example + +The first line ends with what the command then did not do: =nothing was built= for a build, =a build would stop here= for =eb-local --explain=, =nothing was removed= for =eb-local clean=, and =doctor checks no further= when =eb-local doctor= cannot tell your user name. +The next line names a setting with its value and, in square brackets, where it was set, as =eb-local config= shows it; or it names the variable, option or command to use. +Where the reason is not plain from the first line, that line starts with it. + +| In brackets | The setting comes from | +|---------------------------------------------------+-----------------------------| +| =default= | eb-local's built-in default | +| =site /etc/eb-local/config.toml:2= | line 2 of the site file | +| =user /home/alice/.config/eb-local/config.toml:2= | line 2 of your file | +| =environment EB_LOCAL_PREFIX= | the variable | +| =option --project= | the option | + +=eb-local doctor= puts a refusal on one line, after =FAIL=, with =builds refuse it= in place of =nothing was built=, and what to change after that: + +#+begin_example +FAIL Slurm job 4242: the node-local mount /local/alice.4242 is on tmpfs, not xfs; builds refuse it. A build's workspace must be on node-local disk, not shared or memory-backed storage; storage.node_local_fstype, xfs [site /etc/eb-local/config.toml:4], names the nodes' file system: set it in the site file if their disks use another, or build in an allocation that has a node-local disk +#+end_example + +A site file that sets a storage setting wrongly, such as a =storage.node_local_mount= without =%j=, stops eb-local as it reads the file, with the file and line. + +* Outside a Slurm job + +A build needs an allocation on the node type that will run the software: + +#+begin_example +eb-local: not inside a Slurm job: SLURM_JOB_ID is unset or empty; nothing was built. + Software is built for the CPU of the node that runs eb-local, so build + inside an allocation on the node type that will run it, for example: + salloc -p cpu -n 16 -t 02:00:00 +#+end_example + +The example is =build.allocation_hint=. +When the site file lists =[build.node_types]=, the same build as a batch job for each type follows. + +=eb-local clean --workspaces= removes only the workspaces of the job it runs in: + +#+begin_example +eb-local: clean --workspaces works only inside the Slurm job that made the workspaces, and SLURM_JOB_ID is unset or empty; nothing was removed. + A build workspace is in its job's node-local mount, which goes when the job ends; run eb-local clean --workspaces inside that job, in its batch script or with srun --jobid=JOBID --overlap. +#+end_example + +* The node-local mount + +A build makes its workspace in the allocation's node-local mount, =/=, with your user name for =%u= and the job id for =%j=. +=eb-local clean --workspaces= removes workspaces only there. +Only the site file sets the =storage= settings. +With the README's site file, =storage.node_local_root= is =/local= and =storage.node_local_mount= is =%u.%j=, so job 4242 of the user =alice= has =/local/alice.4242=. +The checks run in this order, and the first that fails is the refusal: + +- =no site file sets storage.node_local_root= :: Set it in the site file, which =eb-local site install slurm --set node_local_root=DIR= writes, or name a site file that root or this program's owner owns with =--config FILE= or =EB_LOCAL_CONFIG=FILE=. =eb-local eb= needs no site file. +- =cannot tell your user name: /usr/bin/id -un failed with status N= :: eb-local puts it for =%u= in =storage.node_local_mount=: run eb-local where =id -un= prints your user name. +- =SLURM_JOB_ID=ID is not a Slurm job id= :: eb-local finds the job's mount by it: run eb-local inside the allocation, from =salloc=, =srun= or =sbatch=, and leave =SLURM_JOB_ID= as Slurm sets it. +- =the user name "NAME" cannot be part of a path= :: It would be =%u= in =storage.node_local_mount=: run eb-local as a user whose name can. +- =the node-local mount MOUNT does not exist=, =cannot be read=, =is not a directory=, =is too long a path=, =is not writable by you=, =cannot be resolved= :: =storage.node_local_root= and =storage.node_local_mount= name it: build in an allocation that has a node-local disk, or set them in the site file to where Slurm mounts your job's node-local disk. +- =the node-local mount MOUNT is a symbolic link= :: A link could lead a build onto another job's or shared storage, so none is followed: build in an allocation whose node-local mount is a directory of its own. +- =the node-local mount MOUNT is reached through a symbolic link, as PATH= :: The same; set =storage.node_local_root= in the site file to the directory itself, which the next line names. +- =the node-local mount MOUNT belongs to uid N, not to you (uid M)= :: =storage.node_local_mount= names your job's own mount below =storage.node_local_root=: set them in the site file to where Slurm mounts your job's node-local disk. +- =no mount in /proc/self/mountinfo holds the node-local mount MOUNT= :: eb-local reads the mount table to check that the mount is node-local: run it where =/proc= is mounted. +- =the node-local mount MOUNT is on TYPE, not FSTYPE= :: A workspace must be on node-local disk, not shared or memory-backed storage: set =storage.node_local_fstype= in the site file if the nodes' disks use another file system, or build in an allocation that has a node-local disk. +- =the node-local mount MOUNT is not a mount of its own but part of TARGET= :: Each job's workspace must be a mount made for the job, which goes with it; then as for a mount that does not exist. +- =the node-local mount MOUNT is not mounted read-write (OPTIONS)= :: A build writes its workspace there: build in an allocation whose node-local disk is writable, and tell the site. + +Once the checks of the install prefix below pass, and the secrets the build needs are found, the build makes its workspace in the mount. +When it cannot: + +#+begin_example +eb-local: cannot make a build workspace in the node-local mount /local/alice.4242 (NoSpace); nothing was built. + The mount passed eb-local's checks, so it may be full or have changed since; df /local/alice.4242 shows its free space. +#+end_example + +* The install prefix + +Installs, sources and logs must outlive the job, so a build refuses a prefix on shared scratch, any of =storage.shared_scratch=, or below =storage.node_local_root=: + +#+begin_example +eb-local: the install prefix /scratch/alice/eessi [environment EB_LOCAL_PREFIX] is under /scratch, shared scratch in storage.shared_scratch [site /etc/eb-local/config.toml:5]; nothing was built. + Installs, sources and logs must outlive the job and not be on shared scratch; set a prefix on durable storage you own with prefix in your eb-local configuration, EB_LOCAL_PREFIX, or --project DIR for a project. +#+end_example + +It refuses the trees a build writes below the prefix when they lead there or out of the prefix, through a symbolic link: + +- =PREFIX/versions leads to PATH, under TREE=, and the same for =PREFIX/.eb-local= :: Replace the symbolic link with a directory, or set another prefix as above. +- =PREFIX/.eb-local/sources leads to PATH, not to a directory inside the install prefix PREFIX=, and the same for =logs= :: Sources and logs stay in the durable prefix, beside the installs: replace the symbolic link with a directory, or set another prefix as above. =eb-local clean= refuses it too. diff --git a/docs/reference/refusals.md b/docs/reference/refusals.md new file mode 100644 index 0000000..9a3e799 --- /dev/null +++ b/docs/reference/refusals.md @@ -0,0 +1,127 @@ + + +# Refusals + +A build checks where it would work and where it would install, and stops before it makes anything there when either is wrong. +`eb-local clean` checks the trees it would remove from before it removes anything, and `eb-local doctor` reports what a build would refuse. +This page lists each refusal: what it refused, why, and what to change. +The README's [Where things go](../index.md#where-things-go) says where each thing goes, and [Where EESSI-extend installs](../explanation/install-variables.md) has the refusals of `eb-local eb` and of an install path EESSI-extend moves. + +## The form + +A refusal is two lines or more on standard error, and the command exits with status 2: + +```text +eb-local: WHAT WAS REFUSED, AND WHY; WHAT THE COMMAND DID NOT DO. + WHAT TO CHANGE. +``` + +The first line ends with what the command then did not do: `nothing was built` for a build, `a build would stop here` for `eb-local --explain`, `nothing was removed` for `eb-local clean`, and `doctor checks no further` when `eb-local doctor` cannot tell your user name. +The next line names a setting with its value and, in square brackets, where it was set, as `eb-local config` shows it; or it names the variable, option or command to use. +Where the reason is not plain from the first line, that line starts with it. + +| In brackets | The setting comes from | +|---|---| +| `default` | eb-local's built-in default | +| `site /etc/eb-local/config.toml:2` | line 2 of the site file | +| `user /home/alice/.config/eb-local/config.toml:2` | line 2 of your file | +| `environment EB_LOCAL_PREFIX` | the variable | +| `option --project` | the option | + +`eb-local doctor` puts a refusal on one line, after `FAIL`, with `builds refuse it` in place of `nothing was built`, and what to change after that: + +```text +FAIL Slurm job 4242: the node-local mount /local/alice.4242 is on tmpfs, not xfs; builds refuse it. A build's workspace must be on node-local disk, not shared or memory-backed storage; storage.node_local_fstype, xfs [site /etc/eb-local/config.toml:4], names the nodes' file system: set it in the site file if their disks use another, or build in an allocation that has a node-local disk +``` + +A site file that sets a storage setting wrongly, such as a `storage.node_local_mount` without `%j`, stops eb-local as it reads the file, with the file and line. + +## Outside a Slurm job + +A build needs an allocation on the node type that will run the software: + +```text +eb-local: not inside a Slurm job: SLURM_JOB_ID is unset or empty; nothing was built. + Software is built for the CPU of the node that runs eb-local, so build + inside an allocation on the node type that will run it, for example: + salloc -p cpu -n 16 -t 02:00:00 +``` + +The example is `build.allocation_hint`. +When the site file lists `[build.node_types]`, the same build as a batch job for each type follows. + +`eb-local clean --workspaces` removes only the workspaces of the job it runs in: + +```text +eb-local: clean --workspaces works only inside the Slurm job that made the workspaces, and SLURM_JOB_ID is unset or empty; nothing was removed. + A build workspace is in its job's node-local mount, which goes when the job ends; run eb-local clean --workspaces inside that job, in its batch script or with srun --jobid=JOBID --overlap. +``` + +## The node-local mount + +A build makes its workspace in the allocation's node-local mount, `/`, with your user name for `%u` and the job id for `%j`. +`eb-local clean --workspaces` removes workspaces only there. +Only the site file sets the `storage` settings. +With the README's site file, `storage.node_local_root` is `/local` and `storage.node_local_mount` is `%u.%j`, so job 4242 of the user `alice` has `/local/alice.4242`. +The checks run in this order, and the first that fails is the refusal: + +`no site file sets storage.node_local_root` +: Set it in the site file, which `eb-local site install slurm --set node_local_root=DIR` writes, or name a site file that root or this program's owner owns with `--config FILE` or `EB_LOCAL_CONFIG=FILE`. `eb-local eb` needs no site file. + +`cannot tell your user name: /usr/bin/id -un failed with status N` +: eb-local puts it for `%u` in `storage.node_local_mount`: run eb-local where `id -un` prints your user name. + +`SLURM_JOB_ID=ID is not a Slurm job id` +: eb-local finds the job's mount by it: run eb-local inside the allocation, from `salloc`, `srun` or `sbatch`, and leave `SLURM_JOB_ID` as Slurm sets it. + +`the user name "NAME" cannot be part of a path` +: It would be `%u` in `storage.node_local_mount`: run eb-local as a user whose name can. + +`the node-local mount MOUNT does not exist`, `cannot be read`, `is not a directory`, `is too long a path`, `is not writable by you`, `cannot be resolved` +: `storage.node_local_root` and `storage.node_local_mount` name it: build in an allocation that has a node-local disk, or set them in the site file to where Slurm mounts your job's node-local disk. + +`the node-local mount MOUNT is a symbolic link` +: A link could lead a build onto another job's or shared storage, so none is followed: build in an allocation whose node-local mount is a directory of its own. + +`the node-local mount MOUNT is reached through a symbolic link, as PATH` +: The same; set `storage.node_local_root` in the site file to the directory itself, which the next line names. + +`the node-local mount MOUNT belongs to uid N, not to you (uid M)` +: `storage.node_local_mount` names your job's own mount below `storage.node_local_root`: set them in the site file to where Slurm mounts your job's node-local disk. + +`no mount in /proc/self/mountinfo holds the node-local mount MOUNT` +: eb-local reads the mount table to check that the mount is node-local: run it where `/proc` is mounted. + +`the node-local mount MOUNT is on TYPE, not FSTYPE` +: A workspace must be on node-local disk, not shared or memory-backed storage: set `storage.node_local_fstype` in the site file if the nodes' disks use another file system, or build in an allocation that has a node-local disk. + +`the node-local mount MOUNT is not a mount of its own but part of TARGET` +: Each job's workspace must be a mount made for the job, which goes with it; then as for a mount that does not exist. + +`the node-local mount MOUNT is not mounted read-write (OPTIONS)` +: A build writes its workspace there: build in an allocation whose node-local disk is writable, and tell the site. + +Once the checks of the install prefix below pass, and the secrets the build needs are found, the build makes its workspace in the mount. +When it cannot: + +```text +eb-local: cannot make a build workspace in the node-local mount /local/alice.4242 (NoSpace); nothing was built. + The mount passed eb-local's checks, so it may be full or have changed since; df /local/alice.4242 shows its free space. +``` + +## The install prefix + +Installs, sources and logs must outlive the job, so a build refuses a prefix on shared scratch, any of `storage.shared_scratch`, or below `storage.node_local_root`: + +```text +eb-local: the install prefix /scratch/alice/eessi [environment EB_LOCAL_PREFIX] is under /scratch, shared scratch in storage.shared_scratch [site /etc/eb-local/config.toml:5]; nothing was built. + Installs, sources and logs must outlive the job and not be on shared scratch; set a prefix on durable storage you own with prefix in your eb-local configuration, EB_LOCAL_PREFIX, or --project DIR for a project. +``` + +It refuses the trees a build writes below the prefix when they lead there or out of the prefix, through a symbolic link: + +`PREFIX/versions leads to PATH, under TREE`, and the same for `PREFIX/.eb-local` +: Replace the symbolic link with a directory, or set another prefix as above. + +`PREFIX/.eb-local/sources leads to PATH, not to a directory inside the install prefix PREFIX`, and the same for `logs` +: Sources and logs stay in the durable prefix, beside the installs: replace the symbolic link with a directory, or set another prefix as above. `eb-local clean` refuses it too. diff --git a/src/config.zig b/src/config.zig index 354bc11..74cfc73 100644 --- a/src/config.zig +++ b/src/config.zig @@ -105,6 +105,9 @@ pub const Settings = struct { /// one from NIMVAULT_VAULT_REPO or the current directory. nimvault_vault: Setting([]const u8) = .{ .value = "" }, secrets: std.ArrayList(Secret) = .empty, + /// The secrets a build gets, by name. Null, when nothing sets + /// build.secrets, is every secret. + build_secrets: Setting(?[]const []const u8) = .{ .value = null }, eessi: std.ArrayList(EessiVar) = .empty, }; @@ -232,6 +235,22 @@ pub fn validSecretSource(source: []const u8) bool { return false; } +/// Whether a build gets the secret `name`: build.secrets names it, or +/// nothing sets build.secrets. +pub fn buildGets(s: Settings, name: []const u8) bool { + const names = s.build_secrets.value orelse return true; + for (names) |n| if (std.mem.eql(u8, n, name)) return true; + return false; +} + +/// The secrets a build gets, in the order the configuration defines them. +pub fn buildSecrets(a: Allocator, s: Settings) Allocator.Error![]Secret { + var out: std.ArrayList(Secret) = .empty; + errdefer out.deinit(a); + for (s.secrets.items) |sec| if (buildGets(s, sec.name)) try out.append(a, sec); + return out.toOwnedSlice(a); +} + fn validEnvName(name: []const u8) bool { if (name.len == 0 or !(std.ascii.isAlphabetic(name[0]) or name[0] == '_')) return false; for (name) |c| if (!(std.ascii.isAlphanumeric(c) or c == '_')) return false; @@ -411,6 +430,11 @@ const Loader = struct { } l.s.node_types = .{ .value = list.items, .from = try l.where(src, f.line, null) }; l.s.node_types_old_key = if (old) l.s.node_types.from else null; + } else if (std.mem.eql(u8, f.key, "secrets")) { + const v = try l.stringList(src, f, "build.secrets"); + for (v) |name| if (!validSecretName(name)) + return l.fail("{s}:{d}: build.secrets: {s} is not a variable name a secret may set", .{ src.path, f.line, name }); + l.s.build_secrets = .{ .value = v, .from = try l.where(src, f.line, profile) }; } else return l.fail("{s}:{d}: unknown key build.{s}", .{ src.path, f.line, f.key }); } } else if (std.mem.eql(u8, k, "clean")) { @@ -680,6 +704,23 @@ pub fn load( try s.secrets.append(a, .{ .name = name, .source = v, .from = try std.fmt.allocPrint(a, "environment {s}", .{k}) }); } } + // EB_LOCAL_BUILD_SECRETS="NAME ..." names the secrets a build gets; + // empty, it names none. + if (env.get("EB_LOCAL_BUILD_SECRETS")) |v| { + var names: std.ArrayList([]const u8) = .empty; + var it = std.mem.tokenizeAny(u8, v, " \t"); + while (it.next()) |name| { + if (!validSecretName(name)) return l.fail("EB_LOCAL_BUILD_SECRETS: {s} is not a variable name a secret may set", .{name}); + try names.append(a, name); + } + s.build_secrets = .{ .value = names.items, .from = "environment EB_LOCAL_BUILD_SECRETS" }; + } + if (s.build_secrets.value) |names| for (names) |name| { + for (s.secrets.items) |sec| { + if (std.mem.eql(u8, sec.name, name)) break; + } else return l.fail("build.secrets [{s}] names {s}, but no secret {s} is defined: add it to [secrets], or set " ++ + secret_env_prefix ++ "{s}=SOURCE", .{ s.build_secrets.from, name, name, name }); + }; if (cli.prefix) |v| s.prefix = .{ .value = v, .from = "option" }; if (cli.project) |v| s.project = .{ .value = v, .from = "option --project" }; @@ -691,14 +732,18 @@ pub fn load( } /// The 1.x site file: `key = value` lines, parsed, never sourced. Kept so a -/// site's existing eb-local.conf keeps working. +/// site's existing eb-local.conf keeps working. Each setting becomes a +/// dotted TOML key on the line it is on, so that `eb-local config` and the +/// errors name that line. pub fn legacyToToml(a: Allocator, text: []const u8, diag: *Diagnostic) Error![]const u8 { const tables = [_][]const u8{ "storage", "stack", "build", "dev", "clean" }; - var bufs: [tables.len]std.ArrayList(u8) = @splat(.empty); + var out: std.ArrayList(u8) = .empty; + errdefer out.deinit(a); var lines = std.mem.splitScalar(u8, text, '\n'); var n: usize = 0; while (lines.next()) |raw| { n += 1; + if (n > 1) try out.append(a, '\n'); const no_comment = if (std.mem.indexOfScalar(u8, raw, '#')) |i| raw[0..i] else raw; const line = std.mem.trim(u8, no_comment, " \t\r"); if (line.len == 0) continue; @@ -727,30 +772,23 @@ pub fn legacyToToml(a: Allocator, text: []const u8, diag: *Diagnostic) Error![]c diag.message = try std.fmt.allocPrint(a, "line {d}: unknown setting '{s}'", .{ n, key }); return error.Invalid; }; - const buf = &bufs[m.t]; - try buf.appendSlice(a, m.name); - try buf.appendSlice(a, " = "); + try out.print(a, "{s}.{s} = ", .{ tables[m.t], m.name }); if (m.list) { - try buf.append(a, '['); + try out.append(a, '['); var it = std.mem.tokenizeAny(u8, value, " \t"); var first = true; while (it.next()) |p| { - if (!first) try buf.appendSlice(a, ", "); + if (!first) try out.appendSlice(a, ", "); first = false; - try appendQuoted(a, buf, p); + try appendQuoted(a, &out, p); } - try buf.append(a, ']'); + try out.append(a, ']'); } else { - try appendQuoted(a, buf, value); + try appendQuoted(a, &out, value); } - try buf.append(a, '\n'); } - var out: std.ArrayList(u8) = .empty; - for (tables, &bufs) |name, *buf| if (buf.items.len > 0) { - try out.appendSlice(a, try std.fmt.allocPrint(a, "[{s}]\n", .{name})); - try out.appendSlice(a, buf.items); - }; - return out.items; + try out.append(a, '\n'); + return out.toOwnedSlice(a); } fn appendQuoted(a: Allocator, buf: *std.ArrayList(u8), v: []const u8) Allocator.Error!void { @@ -910,10 +948,65 @@ test "refusals" { try r.one(&t, "default_profile = \"nope\"\n", .user, "no profile 'nope'"); try r.one(&t, "[storage]\nnode_local_root = \"relative\"\n", .site, "absolute"); try r.one(&t, "x = 1\nx = 2\n", .user, "c.toml:2"); + try r.one(&t, "[build]\nsecrets = \"TOKEN\"\n", .user, "build.secrets must be an array of strings"); + try r.one(&t, "[build]\nsecrets = [\"PATH\"]\n", .user, "c.toml:2: build.secrets: PATH is not a variable name a secret may set"); + try r.one(&t, "[build]\nsecrets = [\"TOKEN\"]\n", .user, "build.secrets [user c.toml:2] names TOKEN, but no secret TOKEN is defined"); t.env.put("EB_LOCAL_STACK_MODULE", "a b") catch unreachable; try r.one(&t, "", .user, "EB_LOCAL_STACK_MODULE"); } +test "build.secrets names the secrets a build gets" { + var t = Fixture.init(); + defer t.deinit(); + const a = t.arena.allocator(); + const text = + \\[build] + \\secrets = [] + \\[secrets] + \\SOURCE_TOKEN = "env:MY_TOKEN" + \\MIRROR_PASSWORD = "env:MY_MIRROR" + \\[profile.licensed] + \\build.secrets = ["LM_LICENSE_FILE", "SOURCE_TOKEN"] + \\[profile.licensed.secrets] + \\LM_LICENSE_FILE = "nimvault:licences/flexlm" + ; + const sources = [_]Source{.{ .path = "u.toml", .text = text, .layer = .user }}; + + // With nothing setting it, a build gets every secret. + var s = try t.load(&.{.{ .path = "u.toml", .text = user_text, .layer = .user }}, .{ .profile = "group" }); + try std.testing.expect(s.build_secrets.value == null); + try std.testing.expectEqualStrings("default", s.build_secrets.from); + try std.testing.expectEqual(@as(usize, 2), (try buildSecrets(a, s)).len); + + s = try t.load(&sources, .{}); + try std.testing.expectEqualStrings("user u.toml:2", s.build_secrets.from); + try std.testing.expectEqual(@as(usize, 0), (try buildSecrets(a, s)).len); + try std.testing.expect(!buildGets(s, "SOURCE_TOKEN")); + + s = try t.load(&sources, .{ .profile = "licensed" }); + try std.testing.expectEqualStrings("user profile licensed, u.toml:7", s.build_secrets.from); + const got = try buildSecrets(a, s); + try std.testing.expectEqual(@as(usize, 2), got.len); + try std.testing.expectEqualStrings("SOURCE_TOKEN", got[0].name); + try std.testing.expectEqualStrings("LM_LICENSE_FILE", got[1].name); + try std.testing.expect(!buildGets(s, "MIRROR_PASSWORD")); + + try t.env.put("EB_LOCAL_BUILD_SECRETS", " MIRROR_PASSWORD\tSOURCE_TOKEN "); + s = try t.load(&sources, .{ .profile = "licensed" }); + try std.testing.expectEqualStrings("environment EB_LOCAL_BUILD_SECRETS", s.build_secrets.from); + try std.testing.expect(buildGets(s, "MIRROR_PASSWORD") and buildGets(s, "SOURCE_TOKEN") and !buildGets(s, "LM_LICENSE_FILE")); + try t.env.put("EB_LOCAL_BUILD_SECRETS", ""); + s = try t.load(&sources, .{ .profile = "licensed" }); + try std.testing.expectEqual(@as(usize, 0), (try buildSecrets(a, s)).len); + + // Only the profile defines LM_LICENSE_FILE. + try t.env.put("EB_LOCAL_BUILD_SECRETS", "LM_LICENSE_FILE"); + try t.refuse(&sources, "build.secrets [environment EB_LOCAL_BUILD_SECRETS] names LM_LICENSE_FILE, but no secret LM_LICENSE_FILE " ++ + "is defined: add it to [secrets], or set EB_LOCAL_SECRET_LM_LICENSE_FILE=SOURCE"); + try t.env.put("EB_LOCAL_BUILD_SECRETS", "SOURCE_TOKEN LD_PRELOAD"); + try t.refuse(&sources, "EB_LOCAL_BUILD_SECRETS: LD_PRELOAD is not a variable name a secret may set"); +} + test "storage.node_local_mount" { var t = Fixture.init(); defer t.deinit(); @@ -1053,6 +1146,22 @@ test "the 1.x site file" { try std.testing.expectEqual(Trash.none, s.trash.value); try std.testing.expectEqualStrings("stack/mine", s.stack_module.value); try std.testing.expectError(error.Invalid, legacyToToml(a, "source_me = $(touch x)\n", &d)); + + // Each setting is where its own line is, whatever its table and order. + try std.testing.expectEqualStrings("site eb-local.conf:2", s.node_local_root.from); + try std.testing.expectEqualStrings("site eb-local.conf:6", s.allocation_hint.from); + try std.testing.expectEqualStrings("site eb-local.conf:9", s.trash.from); + const reordered = try legacyToToml(a, + \\allocation_hint = salloc -n 16 + \\ + \\# the node-local disk + \\node_local_root = /local # each job's mount is below it + \\node_local_mount = job-%j + , &d); + const r = try t.load(&.{.{ .path = "eb-local.conf", .text = reordered, .layer = .site }}, .{}); + try std.testing.expectEqualStrings("site eb-local.conf:1", r.allocation_hint.from); + try std.testing.expectEqualStrings("site eb-local.conf:4", r.node_local_root.from); + try std.testing.expectEqualStrings("site eb-local.conf:5", r.node_local_mount.from); } test "each node type is where its own line is" { diff --git a/src/extend.zig b/src/extend.zig index d571c21..935969f 100644 --- a/src/extend.zig +++ b/src/extend.zig @@ -24,8 +24,6 @@ pub const Selection = struct { pub const SelectError = error{TooMany}; -pub const too_many = "eb-local: set at most one of EESSI_USER_INSTALL, EESSI_PROJECT_INSTALL, EESSI_SITE_INSTALL, EESSI_CVMFS_INSTALL; with none set, the module installs under $HOME/eessi"; - const Name = struct { name: []const u8, mode: Mode, @@ -71,6 +69,60 @@ pub fn select(env: *const std.process.Environ.Map) SelectError!Selection { return .{ .mode = names[i].mode, .umask = names[i].umask }; } +/// Why `select` refused: each install variable that is set, with its +/// value, and what EESSI-extend does with them. With a project and a user +/// variable it loads and makes a private user install; with a site or a +/// cvmfs one and another it refuses to load. One of them is usually left +/// from an earlier session. +pub fn tooMany(a: Allocator, env: *const std.process.Environ.Map) Allocator.Error![]u8 { + var out: std.ArrayList(u8) = .empty; + errdefer out.deinit(a); + var set: usize = 0; + for (names) |n| { + if (env.get(n.name) != null) set += 1; + } + try out.appendSlice(a, "eb-local: "); + var shown: usize = 0; + for (names) |n| { + const v = env.get(n.name) orelse continue; + if (shown > 0) try out.appendSlice(a, if (shown + 1 == set) " and " else ", "); + try out.print(a, "{s}=", .{n.name}); + try appendQuoted(a, &out, v); + shown += 1; + } + try out.appendSlice(a, if (set == 2) " are both set; " else " are all set; "); + if (env.get("EESSI_CVMFS_INSTALL") != null) { + try out.appendSlice(a, "EESSI-extend refuses to load with EESSI_CVMFS_INSTALL and any other install variable.\n"); + } else if (env.get("EESSI_SITE_INSTALL") != null) { + try out.appendSlice(a, "EESSI-extend refuses to load with EESSI_SITE_INSTALL and a user or project install variable.\n"); + } else { + try out.appendSlice(a, "EESSI-extend would make a private user install (umask 077) under "); + try appendQuoted(a, &out, env.get("EESSI_USER_INSTALL").?); + try out.appendSlice(a, ", not a project install under "); + try appendQuoted(a, &out, env.get("EESSI_PROJECT_INSTALL").?); + try out.appendSlice(a, ".\n"); + } + try out.appendSlice(a, + \\ Unset the one an earlier session left (a shell startup file, or eval "$(eb-local env)" for another prefix): + \\ set at most one of EESSI_USER_INSTALL, EESSI_PROJECT_INSTALL, EESSI_SITE_INSTALL, EESSI_CVMFS_INSTALL; with none set, the module installs under $HOME/eessi + \\ + ); + return out.toOwnedSlice(a); +} + +/// S as one shell word, as eb-local prints values elsewhere. +fn appendQuoted(a: Allocator, out: *std.ArrayList(u8), s: []const u8) Allocator.Error!void { + const safe = s.len > 0 and for (s) |ch| { + if (!(std.ascii.isAlphanumeric(ch) or std.mem.indexOfScalar(u8, "_./:@%+,=-", ch) != null)) break false; + } else true; + if (safe) return out.appendSlice(a, s); + try out.append(a, '\''); + for (s) |ch| { + if (ch == '\'') try out.appendSlice(a, "'\\''") else try out.append(a, ch); + } + try out.append(a, '\''); +} + /// Drop the launcher switch, so a build that itself runs eb-local does not /// enter this mode again. Install variables are left as the caller set them. pub fn apply(env: *std.process.Environ.Map) void { @@ -94,7 +146,10 @@ pub fn initPath(a: Allocator, env: *const std.process.Environ.Map) Allocator.Err /// `pipefail` would exit before the module loads. `WORKING_DIR` is the /// caller's: unset, the module's default is `/tmp/$USER`, one per user, /// where a shared default would leave every other user's build unable to -/// write the first one's directories. +/// write the first one's directories. Once the module has loaded, eb runs +/// only if EASYBUILD_INSTALLPATH is in the tree the install variable +/// selects and no EASYBUILD_INSTALLPATH_SOFTWARE or _MODULES moves part of +/// the install elsewhere. pub const script = \\set -eo pipefail \\unset EB_LOCAL_EESSI_EXTEND || true @@ -137,7 +192,57 @@ pub const script = \\fi \\_arch=$(uname -m) \\export PATH="${EESSI_EPREFIX:-${repo}/versions/${ver}/compat/linux/${_arch}}/usr/bin:${PATH}" + \\# Where the module installs, read before it loads: below the tree a user + \\# or project variable names, $HOME/eessi as Lmod's pathJoin makes it + \\# with none set, the site tree for a site install, the EESSI tree for a + \\# cvmfs one. + \\case $mode in + \\ user) + \\ home=${HOME-} + \\ while [[ $home == *//* ]]; do home=${home//\/\//\/}; done + \\ root=${EESSI_USER_INSTALL:-${home%/}/eessi} from=EESSI_USER_INSTALL ;; + \\ project) root=$EESSI_PROJECT_INSTALL from=EESSI_PROJECT_INSTALL ;; + \\ site) root=${EESSI_SITE_SOFTWARE_PATH:-} from=EESSI_SITE_SOFTWARE_PATH ;; + \\ *) root=${EESSI_SOFTWARE_PATH:-} from=EESSI_SOFTWARE_PATH ;; + \\esac + \\readme='See "Where EESSI-extend installs" in the README.' + \\for v in EASYBUILD_INSTALLPATH_SOFTWARE EASYBUILD_INSTALLPATH_MODULES; do + \\ if [[ -n ${!v+set} ]]; then + \\ echo "eb-local: ${v}=${!v} is set in this shell and would put part of this install outside ${root}; nothing was built." >&2 + \\ echo " Unset it: EasyBuild installs software and modules below the install path EESSI-extend sets. ${readme}" >&2 + \\ exit 2 + \\ fi + \\done + \\installs=(EESSI_USER_INSTALL EESSI_PROJECT_INSTALL EESSI_SITE_INSTALL EESSI_CVMFS_INSTALL) + \\declare -A was + \\for v in "${installs[@]}"; do was[$v]=${!v+set:${!v}}; done \\module load EESSI-extend + \\# An install variable a load hook sets acts only on the next load, so + \\# this install is not moved by it; a shell that keeps it is. + \\for v in "${installs[@]}"; do + \\ [[ ${!v+set:${!v}} == "${was[$v]}" ]] && continue + \\ if [[ -n ${!v+set} ]]; then what="set $v=${!v}"; else what="unset $v"; fi + \\ echo "eb-local: loading EESSI-extend ${what}; this install still goes under ${root}, but a shell that loads EESSI-extend by hand keeps the change, and its next load installs elsewhere." >&2 + \\ echo " A site Lmod hook that sets an install variable acts only on the next load. ${readme}" >&2 + \\done + \\for v in EASYBUILD_INSTALLPATH_SOFTWARE EASYBUILD_INSTALLPATH_MODULES; do + \\ if [[ -n ${!v+set} ]]; then + \\ echo "eb-local: loading EESSI-extend set ${v}=${!v}, which would put part of this install outside ${root}; nothing was built." >&2 + \\ echo " A site Lmod hook or a changed EESSI-extend set it. ${readme}" >&2 + \\ exit 2 + \\ fi + \\done + \\if [[ -z $root ]]; then + \\ echo "eb-local: ${from} is empty or not set, so where a ${mode} install goes cannot be checked; nothing was built." >&2 + \\ echo " The EESSI module that ${init} loads sets it: check that EESSI_CVMFS_REPO and EESSI_VERSION name the EESSI you mean. ${readme}" >&2 + \\ exit 2 + \\fi + \\installpath=${EASYBUILD_INSTALLPATH-} + \\if [[ /$installpath/ == */../* || ( $installpath != "$root" && $installpath != "$root"/* ) ]]; then + \\ echo "eb-local: EESSI-extend set the install path to ${installpath:-nothing}, outside ${root}, where a ${mode} install goes; nothing was built." >&2 + \\ echo " The install variable did not choose it: a site Lmod hook, a changed EESSI-extend, or a character such as - in EESSI_CVMFS_REPO, which EESSI-extend matches as a Lua pattern, did. ${readme}" >&2 + \\ exit 2 + \\fi \\exec eb "$@" ; @@ -272,20 +377,33 @@ const Run = struct { try sys.fchmod(fd, mode); } - /// A repository whose init defines `module` and, on load, the hooks, - /// the EasyBuild umask and the EasyBuild prefix the real module sets. - /// `eb` prints the process umask and then the environment. + /// A repository whose init sets the trees the EESSI module sets and + /// defines `module`, which on load sets the hooks, the EasyBuild umask, + /// the EasyBuild prefix and the install path the real module sets. + /// FAKE_INSTALLPATH replaces that install path, and FAKE_SETS, NAME=VALUE, + /// is set after it is chosen, as a site load hook would; FAKE_NO_SITE_PATH + /// leaves the site tree unset. `eb` prints the process umask and then the + /// environment. fn fake(self: *Run, version: []const u8, eprefix: ?[]const u8) !void { var init_text: std.ArrayList(u8) = .empty; errdefer init_text.deinit(self.arena.allocator()); const a = self.arena.allocator(); try init_text.appendSlice(a, + \\export EESSI_SOFTWARE_PATH="$EESSI_CVMFS_REPO/versions/2026.06/software/linux/x86_64/amd/zen4" + \\[ -n "${FAKE_NO_SITE_PATH:-}" ] || + \\ export EESSI_SITE_SOFTWARE_PATH="$EESSI_CVMFS_REPO/host_injections/2026.06/software/linux/x86_64/amd/zen4" \\module() { \\ if [ "$1" = load ]; then \\ export EASYBUILD_HOOKS=/eessi/init/easybuild/eb_hooks.py \\ export EASYBUILD_RPATH=1 \\ export EASYBUILD_UMASK=from-the-module \\ export EASYBUILD_PREFIX="${WORKING_DIR:-/tmp/$USER}/easybuild" + \\ if [ -n "${EESSI_CVMFS_INSTALL+set}" ]; then installpath=$EESSI_SOFTWARE_PATH + \\ elif [ -n "${EESSI_SITE_INSTALL+set}" ]; then installpath=${EESSI_SITE_SOFTWARE_PATH-} + \\ else installpath="${EESSI_USER_INSTALL:-${EESSI_PROJECT_INSTALL:-$HOME/eessi}}/versions/2026.06/software/linux/x86_64/amd/zen4" + \\ fi + \\ export EASYBUILD_INSTALLPATH="${FAKE_INSTALLPATH:-$installpath}" + \\ [ -z "${FAKE_SETS:-}" ] || export "$FAKE_SETS" \\ fi \\} \\ @@ -307,7 +425,7 @@ const Run = struct { error.TooMany => return .{ .term = .{ .exited = 3 }, .stdout = try a.dupe(u8, ""), - .stderr = try a.dupe(u8, too_many), + .stderr = try tooMany(a, &self.env), }, }; apply(&self.env); @@ -513,6 +631,118 @@ test "two prefixes are refused" { try r.env.put("EESSI_PROJECT_INSTALL", "/y"); const out = try r.launch(&.{}); try testing.expectEqual(@as(u32, 3), out.term.code()); + try testing.expectEqualStrings("", out.stdout); + try testing.expect(std.mem.startsWith(u8, out.stderr, "eb-local: EESSI_USER_INSTALL=/x and EESSI_PROJECT_INSTALL=/y are both set; " ++ + "EESSI-extend would make a private user install (umask 077) under /x, not a project install under /y.\n")); +} + +test "the refusal of several install variables names each and what EESSI-extend does" { + var env = std.process.Environ.Map.init(testing.allocator); + defer env.deinit(); + try put(&env, "EESSI_USER_INSTALL", "/home/alice/eessi"); + try put(&env, "EESSI_SITE_INSTALL", ""); + const site = try tooMany(testing.allocator, &env); + defer testing.allocator.free(site); + try testing.expectEqualStrings( + \\eb-local: EESSI_USER_INSTALL=/home/alice/eessi and EESSI_SITE_INSTALL='' are both set; EESSI-extend refuses to load with EESSI_SITE_INSTALL and a user or project install variable. + \\ Unset the one an earlier session left (a shell startup file, or eval "$(eb-local env)" for another prefix): + \\ set at most one of EESSI_USER_INSTALL, EESSI_PROJECT_INSTALL, EESSI_SITE_INSTALL, EESSI_CVMFS_INSTALL; with none set, the module installs under $HOME/eessi + \\ + , site); + + try put(&env, "EESSI_PROJECT_INSTALL", "/projects/a b"); + try put(&env, "EESSI_CVMFS_INSTALL", "1"); + const all = try tooMany(testing.allocator, &env); + defer testing.allocator.free(all); + try testing.expect(std.mem.startsWith(u8, all, "eb-local: EESSI_USER_INSTALL=/home/alice/eessi, EESSI_PROJECT_INSTALL='/projects/a b', " ++ + "EESSI_SITE_INSTALL='' and EESSI_CVMFS_INSTALL=1 are all set; " ++ + "EESSI-extend refuses to load with EESSI_CVMFS_INSTALL and any other install variable.\n")); +} + +test "an install path outside the selected tree stops eb" { + var r = try Run.init(); + defer r.deinit(); + try r.fake("2026.06", null); + const a = r.arena.allocator(); + const mine = try std.fs.path.join(a, &.{ r.root, "home/mine" }); + try r.env.put("EESSI_USER_INSTALL", mine); + for ([_][]const u8{ "/elsewhere/software", try std.fmt.allocPrint(a, "{s}/../other/versions", .{mine}), try std.fmt.allocPrint(a, "{s}-old/versions", .{mine}) }) |moved| { + try r.env.put("FAKE_INSTALLPATH", moved); + const out = try r.launch(&.{}); + try testing.expectEqual(@as(u32, 2), out.term.code()); + try testing.expectEqualStrings("", out.stdout); + const said = try std.fmt.allocPrint(a, "eb-local: EESSI-extend set the install path to {s}, outside {s}, where a user install goes; nothing was built.\n" ++ + " The install variable did not choose it: a site Lmod hook, a changed EESSI-extend, or a character such as - in EESSI_CVMFS_REPO, " ++ + "which EESSI-extend matches as a Lua pattern, did. See \"Where EESSI-extend installs\" in the README.\n", .{ moved, mine }); + try testing.expectEqualStrings(said, out.stderr); + } + try r.env.put("FAKE_INSTALLPATH", mine); + try ok(try r.launch(&.{})); +} + +test "an EasyBuild install path for software or modules alone stops eb" { + var r = try Run.init(); + defer r.deinit(); + try r.fake("2026.06", null); + try r.env.put("EASYBUILD_INSTALLPATH_MODULES", "/home/alice/old-modules"); + const out = try r.launch(&.{}); + try testing.expectEqual(@as(u32, 2), out.term.code()); + try testing.expectEqualStrings("", out.stdout); + const said = try std.fmt.allocPrint(r.arena.allocator(), "eb-local: EASYBUILD_INSTALLPATH_MODULES=/home/alice/old-modules is set in this shell " ++ + "and would put part of this install outside {s}/home/eessi; nothing was built.\n" ++ + " Unset it: EasyBuild installs software and modules below the install path EESSI-extend sets. " ++ + "See \"Where EESSI-extend installs\" in the README.\n", .{r.root}); + try testing.expectEqualStrings(said, out.stderr); + + _ = r.env.swapRemove("EASYBUILD_INSTALLPATH_MODULES"); + try r.env.put("FAKE_SETS", "EASYBUILD_INSTALLPATH_SOFTWARE=/home/alice/old-software"); + const hooked = try r.launch(&.{}); + try testing.expectEqual(@as(u32, 2), hooked.term.code()); + try testing.expectEqualStrings("", hooked.stdout); + const hook_said = try std.fmt.allocPrint(r.arena.allocator(), "eb-local: loading EESSI-extend set EASYBUILD_INSTALLPATH_SOFTWARE=/home/alice/old-software, " ++ + "which would put part of this install outside {s}/home/eessi; nothing was built.\n" ++ + " A site Lmod hook or a changed EESSI-extend set it. See \"Where EESSI-extend installs\" in the README.\n", .{r.root}); + try testing.expectEqualStrings(hook_said, hooked.stderr); +} + +test "an install variable set as the module loads is reported and does not move the install" { + var r = try Run.init(); + defer r.deinit(); + try r.fake("2026.06", null); + try r.env.put("FAKE_SETS", "EESSI_USER_INSTALL=/home/alice/.local/eessi"); + const out = try r.launch(&.{}); + try ok(out); + const default = try std.fs.path.join(r.arena.allocator(), &.{ r.root, "home/eessi" }); + try testing.expect(std.mem.startsWith(u8, envVar(out.stdout, "EASYBUILD_INSTALLPATH").?, default)); + const said = try std.fmt.allocPrint(r.arena.allocator(), "eb-local: loading EESSI-extend set EESSI_USER_INSTALL=/home/alice/.local/eessi; " ++ + "this install still goes under {s}, but a shell that loads EESSI-extend by hand keeps the change, and its next load installs elsewhere.\n" ++ + " A site Lmod hook that sets an install variable acts only on the next load. See \"Where EESSI-extend installs\" in the README.\n", .{default}); + try testing.expectEqualStrings(said, out.stderr); +} + +test "a site install with no site tree cannot be checked" { + var r = try Run.init(); + defer r.deinit(); + try r.fake("2026.06", null); + try r.env.put("EESSI_SITE_INSTALL", "1"); + try r.env.put("FAKE_NO_SITE_PATH", "1"); + const out = try r.launch(&.{}); + try testing.expectEqual(@as(u32, 2), out.term.code()); + try testing.expect(std.mem.startsWith(u8, out.stderr, "eb-local: EESSI_SITE_SOFTWARE_PATH is empty or not set, so where a site install goes cannot be checked; nothing was built.\n" ++ + " The EESSI module that ")); + try testing.expect(std.mem.endsWith(u8, out.stderr, "/init/lmod/bash loads sets it: check that EESSI_CVMFS_REPO and EESSI_VERSION name the EESSI you mean. " ++ + "See \"Where EESSI-extend installs\" in the README.\n")); +} + +test "the default user tree is $HOME/eessi as Lmod joins it" { + var r = try Run.init(); + defer r.deinit(); + try r.fake("2026.06", null); + const a = r.arena.allocator(); + const home = r.env.get("HOME").?; + try r.env.put("FAKE_INSTALLPATH", try std.fmt.allocPrint(a, "{s}/eessi/versions/2026.06", .{home})); + try r.env.put("HOME", try std.fmt.allocPrint(a, "{s}//", .{home})); + try ok(try r.launch(&.{})); } test "a missing version is reported" { diff --git a/src/main.zig b/src/main.zig index 8fb92c5..4d48829 100644 --- a/src/main.zig +++ b/src/main.zig @@ -34,7 +34,9 @@ const usage_text = \\ At most one of EESSI_USER_INSTALL, EESSI_PROJECT_INSTALL, \\ EESSI_SITE_INSTALL, EESSI_CVMFS_INSTALL may be set, and a \\ present empty value counts as set; with none set, the - \\ module uses $HOME/eessi and nothing is exported + \\ module uses $HOME/eessi and nothing is exported. + \\ eb runs only if the module's install path is in the + \\ tree that variable selects \\ eb-local --explain eb [--] [eb options] \\ the script eb runs, with its arguments; runs nothing \\ eb-local env lines that make your installed modules visible @@ -89,7 +91,8 @@ const usage_text = \\then options. Builds use the allocation's own \\node-local mount; a successful build removes its workspace unless \\EB_LOCAL_KEEP_WORK=1. Secrets reach eb's environment only, and logs - \\written during a build are cleaned of them. + \\written during a build are cleaned of them. A build gets every secret, + \\unless build.secrets or EB_LOCAL_BUILD_SECRETS names the ones it gets. \\ \\--config FILE, or EB_LOCAL_CONFIG=FILE without it, is read in place of the \\site file when root or this program's owner owns it, otherwise in place of @@ -158,11 +161,25 @@ const install_vars = [_][]const u8{ "EASYBUILD_INSTALLPATH_SOFTWARE", "EASYBUILD_INSTALLPATH_MODULES", "EASYBUILD_PREFIX", }; +/// What, left in a shell, sends a later load of EESSI-extend, or eb after +/// it, somewhere else: EESSI-extend sets the other install variables itself. +const leftover_vars = [_][]const u8{ + "EESSI_USER_INSTALL", "EESSI_PROJECT_INSTALL", "EESSI_SITE_INSTALL", "EESSI_CVMFS_INSTALL", + "EASYBUILD_INSTALLPATH_SOFTWARE", "EASYBUILD_INSTALLPATH_MODULES", +}; + const Place = struct { prefix: []const u8, project: bool, }; +/// Whether NAME=VALUE is what `eb-local env` sets for P: its install +/// variable, naming its prefix. +fn ownInstallVar(c: Ctx, p: Place, name: []const u8, value: []const u8) bool { + const mine = if (p.project) "EESSI_PROJECT_INSTALL" else "EESSI_USER_INSTALL"; + return std.mem.eql(u8, name, mine) and std.mem.eql(u8, storage.canonical(c.a, value, c.cwd) catch oom(), p.prefix); +} + fn environmentLines(c: Ctx, s: config.Settings, p: Place) []const u8 { const a = c.a; var out: std.ArrayList(u8) = .empty; @@ -881,6 +898,9 @@ fn cmdConfig(c: Ctx, s: config.Settings, check: bool) u8 { const types = nodeTypes(s); if (types.len == 0) row("build.node_types", "(none)", s.node_types.from); for (types) |t| row(str(a, "build.node_types.{s}", .{t.name}), t.sbatch, t.from); + if (s.build_secrets.value) |names| { + row("build.secrets", if (names.len == 0) "(none)" else std.mem.join(a, " ", names) catch oom(), s.build_secrets.from); + } else row("build.secrets", "(every secret)", s.build_secrets.from); row("clean.trash", @tagName(s.trash.value), s.trash.from); row("clean.logs_older_than_days", str(a, "{d}", .{s.logs_older_than_days.value}), s.logs_older_than_days.from); row("nimvault.program", if (s.nimvault_program.value.len == 0) "(nimvault on PATH)" else s.nimvault_program.value, s.nimvault_program.from); @@ -960,6 +980,7 @@ fn cmdConfigEnv(c: Ctx, s: config.Settings) u8 { line(a, &out, "EB_LOCAL_NIMVAULT_PROGRAM", s.nimvault_program.value); line(a, &out, "EB_LOCAL_NIMVAULT_VAULT", s.nimvault_vault.value); for (s.secrets.items) |sec| line(a, &out, str(a, "{s}{s}", .{ config.secret_env_prefix, sec.name }), sec.source); + if (s.build_secrets.value) |names| line(a, &out, "EB_LOCAL_BUILD_SECRETS", std.mem.join(a, " ", names) catch oom()); // [eessi] settings are environment for EESSI already; they travel as // themselves. An empty one is a profile clearing a site setting; the // clear has to be exported or the site value stays in the job. @@ -1267,12 +1288,16 @@ test "the value eessi-arch-guard --shell gives a variable" { try std.testing.expect(shellExport(a, text, "EESSI_SOFTWARE") == null); } -fn userName(c: Ctx) []const u8 { +/// Your user name, for %u in storage.node_local_mount. `undone` is what the +/// command does not do when there is none. +fn userName(c: Ctx, s: config.Settings, undone: []const u8) []const u8 { // A static binary has no NSS; id(1) asks the system's. const id = (proc.which(c.a, "id", c.env.get("PATH") orelse "/usr/bin:/bin") catch null) orelse "/usr/bin/id"; - const r = proc.run(c.a, id, &.{ id, "-un" }, c.envp, .{ .stdout_limit = 4096, .timeout_ms = 10_000 }) catch - die("cannot determine the allocation user.", .{}); - if (r.term.code() != 0) die("cannot determine the allocation user.", .{}); + const failed = "cannot tell your user name: {s} -un {s}; {s}.\n" ++ + " eb-local puts it for %u in storage.node_local_mount, {s} [{s}]; run eb-local where id -un prints your user name."; + const r = proc.run(c.a, id, &.{ id, "-un" }, c.envp, .{ .stdout_limit = 4096, .timeout_ms = 10_000 }) catch |e| + die(failed, .{ id, str(c.a, "could not run ({s})", .{@errorName(e)}), undone, s.node_local_mount.value, s.node_local_mount.from }); + if (r.term.code() != 0) die(failed, .{ id, str(c.a, "failed with status {d}", .{r.term.code()}), undone, s.node_local_mount.value, s.node_local_mount.from }); return std.mem.trim(u8, r.stdout, " \n"); } @@ -1295,24 +1320,74 @@ fn callerUid(c: Ctx) linux.uid_t { return linux.getuid(); } -fn checkedJobRoot(c: Ctx, s: config.Settings) []const u8 { - if (s.node_local_root.value.len == 0) die("no node-local root is configured; set storage.node_local_root in the site configuration (see the README).", .{}); +fn nodeLocal(s: config.Settings) storage.NodeLocal { + return .{ + .root = s.node_local_root.value, + .root_from = s.node_local_root.from, + .mount = s.node_local_mount.value, + .mount_from = s.node_local_mount.from, + .fstype = s.node_local_fstype.value, + .fstype_from = s.node_local_fstype.from, + }; +} + +/// The allocation's node-local mount. A refusal says what was refused and +/// why, then what to change; `undone` is what the command then did not do. +fn checkedJobRoot(c: Ctx, s: config.Settings, undone: []const u8) []const u8 { + if (s.node_local_root.value.len == 0) + die("no site file sets storage.node_local_root, the directory that holds each job's node-local mount; {s}.\n" ++ + " Set it in the site file, which eb-local site install slurm --set node_local_root=DIR writes, or name a site file " ++ + "that root or this program's owner owns with --config FILE or EB_LOCAL_CONFIG=FILE. eb-local eb needs no site file.", .{undone}); var r: storage.Refusal = .{}; const job_id = c.env.get("SLURM_JOB_ID") orelse ""; - const jr = storage.jobRoot(c.a, s.node_local_root.value, s.node_local_mount.value, s.node_local_fstype.value, job_id, userName(c), mountinfoText(c), callerUid(c), &r) catch |e| switch (e) { - error.Refused => die("{s}", .{r.message}), + const jr = storage.jobRoot(c.a, nodeLocal(s), job_id, userName(c, s, undone), mountinfoText(c), callerUid(c), &r) catch |e| switch (e) { + error.Refused => die("{s}; {s}.\n {s}.", .{ r.message, undone, r.fix }), error.OutOfMemory => oom(), }; return jr.path; } +/// Where the prefix in force was set, as `eb-local config` shows it. +fn prefixFrom(s: config.Settings, p: Place) []const u8 { + return if (p.project) s.project.from else s.prefix.from; +} + +/// What to change when a prefix is refused. +const prefix_fix = "set a prefix on durable storage you own with prefix in your eb-local configuration, EB_LOCAL_PREFIX, or --project DIR for a project"; + +/// Why a prefix is refused when it, or a tree below it, is on refused storage. +const outlive = "Installs, sources and logs must outlive the job and not be on shared scratch"; + +/// A tree a build writes nothing to, with the setting that names it. +const RefusedTree = struct { path: []const u8, what: []const u8 }; + +/// Shared scratch and the node-local root, as configured and, when +/// `resolved`, as the kernel resolves them, so that an alias (a symbolic +/// link to shared scratch) is refused as the tree itself is. +fn refusedTrees(c: Ctx, s: config.Settings, resolved: bool) []const RefusedTree { + const a = c.a; + const scratch = str(a, "shared scratch in storage.shared_scratch [{s}]", .{s.shared_scratch.from}); + const local = str(a, "node-local storage below storage.node_local_root [{s}]", .{s.node_local_root.from}); + var configured: std.ArrayList(RefusedTree) = .empty; + for (s.shared_scratch.value) |r| configured.append(a, .{ .path = r, .what = scratch }) catch oom(); + if (s.node_local_root.value.len > 0) configured.append(a, .{ .path = s.node_local_root.value, .what = local }) catch oom(); + if (!resolved) return configured.items; + var out: std.ArrayList(RefusedTree) = .empty; + for (configured.items) |t| { + out.append(a, t) catch oom(); + out.append(a, .{ .path = storage.canonical(a, t.path, c.cwd) catch oom(), .what = t.what }) catch oom(); + } + return out.items; +} + const Durable = struct { sources: []const u8, logs: []const u8, }; /// Sources and logs live beside the installation, and must stay there. -fn durableDirs(c: Ctx, prefix: []const u8) Durable { +/// `undone` is what the command does not do when one leads elsewhere. +fn durableDirs(c: Ctx, prefix: []const u8, undone: []const u8) Durable { const root = std.fs.path.join(c.a, &.{ prefix, ".eb-local" }) catch oom(); const d: Durable = .{ .sources = std.fs.path.join(c.a, &.{ root, "sources" }) catch oom(), @@ -1321,11 +1396,19 @@ fn durableDirs(c: Ctx, prefix: []const u8) Durable { for ([_][]const u8{ d.sources, d.logs }) |p| { const resolved = storage.canonical(c.a, p, c.cwd) catch oom(); if (!storage.under(resolved, prefix) or std.mem.eql(u8, resolved, prefix)) - die("source and log directories must remain inside the durable prefix.", .{}); + die("{s} leads to {s}, not to a directory inside the install prefix {s}; {s}.\n" ++ + " Sources and logs stay in the durable prefix, beside the installs: replace the symbolic link in {s} with a directory, or " ++ prefix_fix ++ ".", .{ p, resolved, prefix, undone, p }); } return d; } +/// The stop when the checked node-local mount takes no workspace. +fn workspaceFailed(a: Allocator, job_root: []const u8, e: anyerror) noreturn { + if (e == error.OutOfMemory) oom(); + die("cannot make a build workspace in the node-local mount {s} ({s}); nothing was built.\n" ++ + " The mount passed eb-local's checks, so it may be full or have changed since; df {s} shows its free space.", .{ job_root, @errorName(e), q(a, job_root) }); +} + // ---- clean ---------------------------------------------------------------- const CleanOpts = struct { @@ -1436,11 +1519,14 @@ fn cmdClean(c: Ctx, s: config.Settings, o: CleanOpts) u8 { const a = c.a; var job_root: ?[]const u8 = null; if (o.workspaces) { - if (nonEmpty(c.env.get("SLURM_JOB_ID")) == null) die("--workspaces works inside the allocation that made them.", .{}); - job_root = checkedJobRoot(c, s); + if (nonEmpty(c.env.get("SLURM_JOB_ID")) == null) + die("clean --workspaces works only inside the Slurm job that made the workspaces, and SLURM_JOB_ID is unset or empty; nothing was removed.\n" ++ + " A build workspace is in its job's node-local mount, which goes when the job ends; run eb-local clean --workspaces inside that job, " ++ + "in its batch script or with srun --jobid=JOBID --overlap.", .{}); + job_root = checkedJobRoot(c, s, "nothing was removed"); } const p = place(c, s); - const d = durableDirs(c, p.prefix); + const d = durableDirs(c, p.prefix, "nothing was removed"); var trash = s.trash.value; const rtrash = proc.which(a, "rtrash", c.env.get("PATH") orelse "") catch null; switch (trash) { @@ -1575,6 +1661,31 @@ const build_script = "set -eo pipefail\n" ++ (if (build_options.test_ops) test_p \\fi \\module load "$extend" >/dev/null 2>&1 || { echo "eb-local: could not load $extend" >&2; exit 1; } \\restore + \\# EESSI-extend chose the install path as it loaded. eb-local checked the + \\# prefix's versions tree, lists it and cleans its logs of secrets, so an + \\# install path anything else chose stops the build. An install variable + \\# a load hook sets acts only on the next load. + \\readme='See "Where EESSI-extend installs" in the README.' + \\for v in EESSI_USER_INSTALL EESSI_PROJECT_INSTALL EESSI_SITE_INSTALL EESSI_CVMFS_INSTALL; do + \\ if [ "$v" = "$install_var" ]; then want=set:$prefix; else want=; fi + \\ [ "${!v+set:${!v}}" = "$want" ] && continue + \\ if [ -n "${!v+set}" ]; then what="set $v=${!v}"; else what="unset $v"; fi + \\ echo "eb-local: loading $extend $what; this build still installs into $prefix, but a shell that loads EESSI-extend by hand keeps the change, and its next load installs elsewhere." >&2 + \\ echo " A site Lmod hook that sets an install variable acts only on the next load. $readme" >&2 + \\done + \\for v in EASYBUILD_INSTALLPATH_SOFTWARE EASYBUILD_INSTALLPATH_MODULES; do + \\ if [ -n "${!v+set}" ]; then + \\ echo "eb-local: loading $extend set $v=${!v}, which would put part of the install outside $prefix/versions, the tree eb-local checked; nothing was built." >&2 + \\ echo " A site Lmod hook or a changed EESSI-extend set it. $readme" >&2 + \\ exit 2 + \\ fi + \\done + \\installpath=${EASYBUILD_INSTALLPATH-} + \\if [[ $installpath != "$prefix"/versions/?* || /$installpath/ == */../* ]]; then + \\ echo "eb-local: loading $extend set the install path to ${installpath:-nothing}, outside $prefix/versions, the tree eb-local checked; nothing was built." >&2 + \\ echo " $install_var did not choose it: a site Lmod hook, a changed EESSI-extend, or a character such as - in EESSI_CVMFS_REPO, which EESSI-extend matches as a Lua pattern, did. $readme" >&2 + \\ exit 2 + \\fi \\# The hooks of EESSI $EESSI_VERSION accept these toolchains besides foss and lfoss. \\if [ -n "${EB_LOCAL_SITE_TOOLCHAINS:-}" ]; then \\ [ -n "${EESSI_VERSION:-}" ] || { echo "eb-local: $stack set no EESSI_VERSION; cannot apply build.site_toolchains" >&2; exit 1; } @@ -1643,7 +1754,7 @@ fn buildCommand(a: Allocator, c: Ctx, s: config.Settings, p: Place, args: []cons fn explainBuild(c: Ctx, s: config.Settings, g: Global, args: []const []const u8) u8 { const a = c.a; const p = place(c, s); - const d = durableDirs(c, p.prefix); + const d = durableDirs(c, p.prefix, "a build would stop here"); var out: std.ArrayList(u8) = .empty; out.appendSlice(a, "# eb-local --explain: the script a build runs, with its environment and arguments. Nothing was created or run.\n") catch oom(); out.print(a, "# Installs as a {s} install into {s} (prefix from {s}).\n", .{ @@ -1663,7 +1774,11 @@ fn explainBuild(c: Ctx, s: config.Settings, g: Global, args: []const []const u8) for (jobs) |line| out.print(a, "# {s}\n", .{line}) catch oom(); } out.appendSlice(a, "# W is a new workspace eb-local makes in that mount; it is removed after a good build.\n") catch oom(); - for (s.secrets.items) |sec| out.print(a, "# {s} reaches eb's environment from {s}; logs are cleaned of it afterwards.\n", .{ sec.name, sec.source }) catch oom(); + for (s.secrets.items) |sec| { + if (config.buildGets(s, sec.name)) { + out.print(a, "# {s} reaches eb's environment from {s}; logs are cleaned of it afterwards.\n", .{ sec.name, sec.source }) catch oom(); + } else out.print(a, "# {s} stays out of eb's environment and is not read: build.secrets [{s}] does not name it.\n", .{ sec.name, s.build_secrets.from }) catch oom(); + } out.appendSlice(a, "# The script gets this environment without the install variables and") catch oom(); for (shell_startup ++ host_loader) |name| out.print(a, " {s}", .{name}) catch oom(); out.appendSlice(a, ",\n# and with these:\n") catch oom(); @@ -1698,7 +1813,7 @@ fn cmdBuild(c: Ctx, s: config.Settings, g: Global, args: []const []const u8) u8 } if (g.explain) return explainBuild(c, s, g, args); if (nonEmpty(c.env.get("SLURM_JOB_ID")) == null) { - warn("not inside a Slurm job.", .{}); + warn("not inside a Slurm job: SLURM_JOB_ID is unset or empty; nothing was built.", .{}); cli.err(" Software is built for the CPU of the node that runs eb-local, so build\n", .{}); cli.err(" inside an allocation on the node type that will run it{s}\n", .{if (s.allocation_hint.value.len > 0) ", for example:" else ""}); if (s.allocation_hint.value.len > 0) cli.err(" {s}\n", .{s.allocation_hint.value}); @@ -1707,24 +1822,16 @@ fn cmdBuild(c: Ctx, s: config.Settings, g: Global, args: []const []const u8) u8 for (jobs) |line| cli.err(" {s}\n", .{line}); return 2; } - const job_root = checkedJobRoot(c, s); + const job_root = checkedJobRoot(c, s, "nothing was built"); var p = place(c, s); // The process umask EESSI-extend gives the install, as `eb-local eb` // sets it: 002 for a project, so that every member can write the // directories builds share, and 077 for a user. What eb-local makes // there takes it too. _ = linux.syscall1(.umask, buildUmask(p)); - // The refused trees as the kernel resolves them, so an alias (a symbolic - // link to shared scratch) is refused as the tree itself is. - var refused: std.ArrayList([]const u8) = .empty; - for (s.shared_scratch.value) |r| { - refused.append(a, r) catch oom(); - refused.append(a, storage.canonical(a, r, c.cwd) catch oom()) catch oom(); - } - refused.append(a, s.node_local_root.value) catch oom(); - refused.append(a, storage.canonical(a, s.node_local_root.value, c.cwd) catch oom()) catch oom(); - for (refused.items) |r| if (storage.under(p.prefix, r)) - die("installation, source and log paths must use durable owned storage.", .{}); + const refused = refusedTrees(c, s, true); + for (refused) |t| if (storage.under(p.prefix, t.path)) + die("the install prefix {s} [{s}] is under {s}, {s}; nothing was built.\n " ++ outlive ++ "; " ++ prefix_fix ++ ".", .{ p.prefix, prefixFrom(s, p), t.path, t.what }); common.atomic.makedirs(p.prefix) catch die("installation prefix is not writable.", .{}); { var zb: [sys.path_max:0]u8 = undefined; @@ -1734,13 +1841,14 @@ fn cmdBuild(c: Ctx, s: config.Settings, g: Global, args: []const []const u8) u8 var buf: [sys.path_max]u8 = undefined; p.prefix = a.dupe(u8, fsx.realpath(fsx.cwd, p.prefix, &buf) catch die("cannot resolve installation prefix.", .{})) catch oom(); } - const d = durableDirs(c, p.prefix); + const d = durableDirs(c, p.prefix, "nothing was built"); // The trees a build writes below the prefix must not lead onto refused // storage either, through a symbolic link made later. for ([_][]const u8{ "versions", ".eb-local" }) |sub| { - const resolved = storage.canonical(a, std.fs.path.join(a, &.{ p.prefix, sub }) catch oom(), c.cwd) catch oom(); - for (refused.items) |r| if (storage.under(resolved, r)) - die("{s}/{s} leads onto shared or node-local storage; installation, source and log paths must use durable owned storage.", .{ p.prefix, sub }); + const path = std.fs.path.join(a, &.{ p.prefix, sub }) catch oom(); + const resolved = storage.canonical(a, path, c.cwd) catch oom(); + for (refused) |t| if (storage.under(resolved, t.path)) + die("{s} leads to {s}, under {s}, {s}; nothing was built.\n " ++ outlive ++ ": replace the symbolic link in {s} with a directory, or " ++ prefix_fix ++ ".", .{ path, resolved, t.path, t.what, path }); } { @@ -1753,16 +1861,17 @@ fn cmdBuild(c: Ctx, s: config.Settings, g: Global, args: []const []const u8) u8 // Secrets before the workspace and the build, so a missing one stops // the build with nothing but the installation directory made. var failure: secrets.Failure = .{}; - const values = secrets.resolve(a, s.secrets.items, c.env, c.envp, nimvaultOf(s), &failure) catch |e| switch (e) { + const wanted = config.buildSecrets(a, s) catch oom(); + const values = secrets.resolve(a, wanted, c.env, c.envp, nimvaultOf(s), &failure) catch |e| switch (e) { error.Unavailable => die("{s}", .{failure.message}), error.OutOfMemory => oom(), }; for (values) |v| if (v.value.len < secrets.min_redacted_len) warn("secret {s} is shorter than {d} bytes and is not removed from logs", .{ v.name, secrets.min_redacted_len }); - const work = storage.makeWorkspace(a, job_root) catch die("cannot create allocation workspace.", .{}); + const work = storage.makeWorkspace(a, job_root) catch |e| workspaceFailed(a, job_root, e); for ([_][]const u8{ "build", "tmp", "cache", "cargo", "source-index" }) |sub| - common.atomic.makedirs(std.fs.path.join(a, &.{ work, sub }) catch oom()) catch die("cannot create allocation workspace.", .{}); + common.atomic.makedirs(std.fs.path.join(a, &.{ work, sub }) catch oom()) catch |e| workspaceFailed(a, job_root, e); common.atomic.makedirs(d.sources) catch die("cannot create {s}", .{d.sources}); common.atomic.makedirs(d.logs) catch die("cannot create {s}", .{d.logs}); if (values.len > 0) { @@ -1774,6 +1883,10 @@ fn cmdBuild(c: Ctx, s: config.Settings, g: Global, args: []const []const u8) u8 } const started: i64 = nowSecs(); + for (leftover_vars) |v| if (c.env.get(v)) |val| { + if (!ownInstallVar(c, p, v, val)) + warn("{s}={s} is set in this shell; this build clears it, but EESSI-extend or eb run by hand would use it", .{ v, q(a, val) }); + }; var env = c.env.clone(a) catch oom(); for (install_vars) |v| _ = env.swapRemove(v); _ = env.swapRemove("EB_LOCAL_SITE_TOOLCHAINS"); @@ -2040,18 +2153,26 @@ fn cmdDoctor(c: Ctx, s: config.Settings, g: Global) u8 { note(a, &out, "info", "no site file sets storage.node_local_root: `eb-local RECIPE` needs a site file; `eb-local eb` does not. `eb-local site install` writes one beside the program", .{}); } - // A build reads every secret before it starts, so one that cannot be - // read stops every build, whether or not it uses that secret. The - // values are read as a build reads them and never shown. + // A build reads each secret it gets before it starts, so one of those + // that cannot be read stops it, whether or not eb uses it. The values + // are read as a build reads them and never shown. for (s.secrets.items) |sec| { + const gets = config.buildGets(s, sec.name); var f: secrets.Failure = .{}; if (secrets.resolve(a, &.{sec}, c.env, c.envp, nimvaultOf(s), &f)) |values| { if (values[0].value.len < secrets.min_redacted_len) { note(a, &out, "warn", "secret {s} from {s} is shorter than {d} bytes and is not removed from logs", .{ sec.name, sec.source, secrets.min_redacted_len }); - } else note(a, &out, "ok ", "secret {s} can be read from {s}", .{ sec.name, sec.source }); + } else if (gets) { + note(a, &out, "ok ", "secret {s} can be read from {s}", .{ sec.name, sec.source }); + } else note(a, &out, "info", "secret {s} can be read from {s}; builds do not get it, as build.secrets [{s}] does not name it", .{ sec.name, sec.source, s.build_secrets.from }); } else |e| switch (e) { - error.Unavailable => { - note(a, &out, if (site) "FAIL" else "warn", "{s} [{s}]; every build stops there, whether or not it uses {s}", .{ f.message, sec.from, sec.name }); + error.Unavailable => if (!gets) { + note(a, &out, "warn", "{s} [{s}]; builds do not read it, as build.secrets [{s}] does not name it, but one that names it stops there", .{ f.message, sec.from, s.build_secrets.from }); + } else { + if (s.build_secrets.value == null) { + note(a, &out, if (site) "FAIL" else "warn", "{s} [{s}]; every build stops there, whether or not it uses {s}. " ++ + "Name in build.secrets the secrets builds need, or in EB_LOCAL_BUILD_SECRETS those one build needs", .{ f.message, sec.from, sec.name }); + } else note(a, &out, if (site) "FAIL" else "warn", "{s} [{s}]; every build stops there, as build.secrets [{s}] names {s}", .{ f.message, sec.from, s.build_secrets.from, sec.name }); if (site) failed = true; }, error.OutOfMemory => oom(), @@ -2061,11 +2182,8 @@ fn cmdDoctor(c: Ctx, s: config.Settings, g: Global) u8 { // Where installs go. const p = locate(c, s); note(a, &out, "ok ", "installs go to {s}: a {s} install, prefix from {s}", .{ p.prefix, if (p.project) "project" else "user", if (p.project) s.project.from else s.prefix.from }); - var refused: std.ArrayList([]const u8) = .empty; - for (s.shared_scratch.value) |r| refused.append(a, r) catch oom(); - if (s.node_local_root.value.len > 0) refused.append(a, s.node_local_root.value) catch oom(); - for (refused.items) |r| if (r.len > 0 and storage.under(p.prefix, r)) { - note(a, &out, "FAIL", "{s} is under {s}, shared or node-local scratch; builds refuse it. Set prefix to durable storage you own", .{ p.prefix, r }); + for (refusedTrees(c, s, false)) |t| if (t.path.len > 0 and storage.under(p.prefix, t.path)) { + note(a, &out, "FAIL", "the install prefix {s} [{s}] is under {s}, {s}; builds refuse it. " ++ outlive ++ "; " ++ prefix_fix, .{ p.prefix, prefixFrom(s, p), t.path, t.what }); failed = true; }; if (fsx.statAt(fsx.cwd, p.prefix, true)) |st| { @@ -2098,9 +2216,7 @@ fn cmdDoctor(c: Ctx, s: config.Settings, g: Global) u8 { // What this shell carries. var leftovers: usize = 0; for (install_vars) |v| if (c.env.get(v)) |val| { - const own = ((std.mem.eql(u8, v, "EESSI_USER_INSTALL") and !p.project) or (std.mem.eql(u8, v, "EESSI_PROJECT_INSTALL") and p.project)) and - std.mem.eql(u8, storage.canonical(a, val, c.cwd) catch oom(), p.prefix); - if (own) { + if (ownInstallVar(c, p, v, val)) { note(a, &out, "ok ", "{s} names your prefix, as eb-local env sets it", .{v}); continue; } @@ -2134,11 +2250,11 @@ fn cmdDoctor(c: Ctx, s: config.Settings, g: Global) u8 { if (nonEmpty(c.env.get("SLURM_JOB_ID"))) |job| { if (s.node_local_root.value.len > 0) { var r: storage.Refusal = .{}; - if (storage.jobRoot(a, s.node_local_root.value, s.node_local_mount.value, s.node_local_fstype.value, job, userName(c), mountinfoText(c), callerUid(c), &r)) |jr| { + if (storage.jobRoot(a, nodeLocal(s), job, userName(c, s, "doctor checks no further"), mountinfoText(c), callerUid(c), &r)) |jr| { note(a, &out, "ok ", "Slurm job {s}: build space {s}", .{ job, jr.path }); } else |e| switch (e) { error.Refused => { - note(a, &out, "FAIL", "Slurm job {s}: {s}", .{ job, r.message }); + note(a, &out, "FAIL", "Slurm job {s}: {s}; builds refuse it. {s}", .{ job, r.message, r.fix }); failed = true; }, error.OutOfMemory => oom(), @@ -2900,7 +3016,7 @@ fn cmdExtend(c: Ctx, args: []const []const u8) u8 { const eb_args = if (args.len > 0 and std.mem.eql(u8, args[0], "--")) args[1..] else args; const sel = extend.select(c.env) catch |err| switch (err) { error.TooMany => { - cli.err("{s}\n", .{extend.too_many}); + cli.err("{s}", .{extend.tooMany(c.a, c.env) catch oom()}); return 3; }, }; @@ -2919,7 +3035,7 @@ fn explainExtend(c: Ctx, args: []const []const u8) u8 { const eb_args = if (args.len > 0 and std.mem.eql(u8, args[0], "--")) args[1..] else args; const sel = extend.select(c.env) catch |err| switch (err) { error.TooMany => { - cli.err("{s}\n", .{extend.too_many}); + cli.err("{s}", .{extend.tooMany(a, c.env) catch oom()}); return 3; }, }; diff --git a/src/secrets.zig b/src/secrets.zig index 0730afc..f3ff801 100644 --- a/src/secrets.zig +++ b/src/secrets.zig @@ -1,9 +1,10 @@ //! Secrets for a build: each names the variable eb receives and where its -//! value comes from. Values are read for a build, after every other check, -//! and by `config --check` and `doctor`, which say only whether each can be -//! read. They go only into eb's environment and are never printed. A failed -//! read reports why without the value. After the build, logs written during -//! it are scanned and every occurrence of a value is replaced. +//! value comes from. A build reads the ones it gets (config.buildSecrets), +//! after every other check; `config --check` and `doctor` read each one and +//! say only whether it can be read. Values go only into eb's environment +//! and are never printed. A failed read reports why without the value. +//! After the build, logs written during it are scanned and every occurrence +//! of a value is replaced. const std = @import("std"); const linux = std.os.linux; const common = @import("zig_common"); diff --git a/src/storage.zig b/src/storage.zig index 35c5214..552128a 100644 --- a/src/storage.zig +++ b/src/storage.zig @@ -8,14 +8,24 @@ const sys = common.sys; const fsx = common.fsx; const Allocator = std.mem.Allocator; +/// Why a path was refused: in `message`, what was refused and why, as one +/// clause; in `fix`, what changes that, naming the setting, variable or +/// command, and for a setting its value and where it was set. pub const Refusal = struct { message: []const u8 = "", + fix: []const u8 = "", }; pub const Error = error{Refused} || Allocator.Error; -fn refuse(a: Allocator, r: *Refusal, comptime fmt: []const u8, args: anytype) Error { - r.message = try std.fmt.allocPrint(a, fmt, args); +fn refuse(a: Allocator, r: *Refusal, comptime what: []const u8, what_args: anytype, comptime fix: []const u8, fix_args: anytype) Error { + const message = try std.fmt.allocPrint(a, what, what_args); + // Not errdefer: every return is an error, and r keeps the message. + const fixed = std.fmt.allocPrint(a, fix, fix_args) catch |e| { + a.free(message); + return e; + }; + r.* = .{ .message = message, .fix = fixed }; return error.Refused; } @@ -197,6 +207,40 @@ pub const JobRoot = struct { /// the job id. pub const default_mount = "%u.%j"; +/// The site file's node-local settings, each with where it was set, as +/// `eb-local config` shows it. +pub const NodeLocal = struct { + root: []const u8, + root_from: []const u8 = "default", + mount: []const u8 = default_mount, + mount_from: []const u8 = "default", + fstype: []const u8 = "xfs", + fstype_from: []const u8 = "default", +}; + +// What changes a refusal of the job's mount, for Refusal.fix. +const where_fix = "storage.node_local_root, {s} [{s}], and storage.node_local_mount, {s} [{s}], name it; " ++ + "build in an allocation that has a node-local disk, or set them in the site file to where Slurm mounts your job's node-local disk"; +const job_fix = "eb-local finds the job's node-local mount by it; run eb-local inside the allocation, " ++ + "from salloc, srun or sbatch, and leave SLURM_JOB_ID as Slurm sets it"; +const user_fix = "eb-local puts your user name, as id -un prints it, for %u in storage.node_local_mount, {s} [{s}]; " ++ + "run eb-local as a user that has one"; +const pattern_fix = "Set it in the site file to one file name of letters, digits, '.', '_', '-', " ++ + "%u (the user) and %j (the job id), with %j in it"; +const link_fix = "A link could lead a build onto another job's or shared storage, so none is followed; "; +const owner_fix = "storage.node_local_mount, {s} [{s}], names your job's own mount below storage.node_local_root, {s} [{s}], " ++ + "with %u for your user name and %j for the job id; set them in the site file to where Slurm mounts your job's node-local disk"; +const mountinfo_fix = "eb-local reads the mount table to check that the job's mount is node-local; run it where /proc is mounted"; +const fstype_fix = "A build's workspace must be on node-local disk, not shared or memory-backed storage; " ++ + "storage.node_local_fstype, {s} [{s}], names the nodes' file system: set it in the site file if their disks use another, " ++ + "or build in an allocation that has a node-local disk"; +const own_mount_fix = "Each job's workspace must be a mount made for the job, which goes with it; " ++ where_fix; +const rw_fix = "A build writes its workspace there; build in an allocation whose node-local disk is writable, and tell the site"; + +fn whereArgs(nl: NodeLocal) struct { []const u8, []const u8, []const u8, []const u8 } { + return .{ nl.root, nl.root_from, nl.mount, nl.mount_from }; +} + /// A storage.node_local_mount: one file name of letters, digits, '.', '_', /// '-', %u (the user) and %j (the job id). It must hold %j, so that each /// allocation has a mount of its own. @@ -237,44 +281,58 @@ fn mountName(a: Allocator, pattern: []const u8, user: []const u8, job_id: []cons /// The allocation's node-local mount: /, the mount name with /// the user and the job id filled in, an owned, writable, canonical -/// directory that is its own mount of `fstype`. +/// directory that is its own mount of `nl.fstype`. pub fn jobRoot( a: Allocator, - node_local_root: []const u8, - mount: []const u8, - fstype: []const u8, + nl: NodeLocal, job_id: []const u8, user: []const u8, mountinfo: []const u8, uid: linux.uid_t, r: *Refusal, ) Error!JobRoot { - if (job_id.len == 0 or job_id[0] == '0') return refuse(a, r, "invalid Slurm allocation identity.", .{}); - for (job_id) |c| if (!std.ascii.isDigit(c)) return refuse(a, r, "invalid Slurm allocation identity.", .{}); + const job_ok = job_id.len > 0 and job_id[0] != '0' and for (job_id) |c| { + if (!std.ascii.isDigit(c)) break false; + } else true; + if (!job_ok) return refuse(a, r, "SLURM_JOB_ID={s} is not a Slurm job id", .{job_id}, job_fix, .{}); if (user.len == 0 or std.mem.indexOfAny(u8, user, "/\x00") != null or std.mem.eql(u8, user, "..") or std.mem.eql(u8, user, ".")) - return refuse(a, r, "cannot determine the allocation user.", .{}); - if (!validMountPattern(mount)) return refuse(a, r, "storage.node_local_mount is not a mount name.", .{}); - const path = try std.fmt.allocPrint(a, "{s}/{s}", .{ node_local_root, try mountName(a, mount, user, job_id) }); - const st = fsx.statAt(fsx.cwd, path, false) catch - return refuse(a, r, "allocation node-local root must be an owned writable directory.", .{}); - if (!st.isDir()) return refuse(a, r, "allocation node-local root must be an owned writable directory.", .{}); + return refuse(a, r, "the user name \"{s}\" cannot be part of a path", .{user}, user_fix, .{ nl.mount, nl.mount_from }); + if (!validMountPattern(nl.mount)) + return refuse(a, r, "storage.node_local_mount, {s} [{s}], is not a mount name", .{ nl.mount, nl.mount_from }, pattern_fix, .{}); + const path = try std.fmt.allocPrint(a, "{s}/{s}", .{ nl.root, try mountName(a, nl.mount, user, job_id) }); + const st = fsx.statAt(fsx.cwd, path, false) catch |e| return switch (e) { + error.NotFound => refuse(a, r, "the node-local mount {s} does not exist", .{path}, where_fix, whereArgs(nl)), + else => refuse(a, r, "the node-local mount {s} cannot be read ({s})", .{ path, @errorName(e) }, where_fix, whereArgs(nl)), + }; + if (st.isLink()) return refuse(a, r, "the node-local mount {s} is a symbolic link", .{path}, link_fix ++ + "build in an allocation whose node-local mount is a directory of its own", .{}); + if (!st.isDir()) return refuse(a, r, "the node-local mount {s} is not a directory", .{path}, where_fix, whereArgs(nl)); var zb: [sys.path_max:0]u8 = undefined; - const zp = sys.z(&zb, path) catch return refuse(a, r, "allocation node-local root must be an owned writable directory.", .{}); + const zp = sys.z(&zb, path) catch return refuse(a, r, "the node-local mount {s} is too long a path", .{path}, where_fix, whereArgs(nl)); if (linux.errno(linux.faccessat(linux.AT.FDCWD, zp.ptr, linux.W_OK | linux.X_OK, 0)) != .SUCCESS) - return refuse(a, r, "allocation node-local root must be an owned writable directory.", .{}); + return refuse(a, r, "the node-local mount {s} is not writable by you", .{path}, where_fix, whereArgs(nl)); var buf: [sys.path_max]u8 = undefined; - const real = fsx.realpath(fsx.cwd, path, &buf) catch return refuse(a, r, "cannot resolve allocation node-local root.", .{}); - if (!std.mem.eql(u8, real, path)) return refuse(a, r, "allocation node-local root must be canonical.", .{}); - if (st.uid != uid) return refuse(a, r, "allocation node-local root belongs to another user.", .{}); - const m = (try mountOf(a, mountinfo, path)) orelse return refuse(a, r, "cannot inspect allocation mount.", .{}); - if (!std.mem.eql(u8, m.fstype, fstype)) - return refuse(a, r, "allocation node-local root must use {s}, not shared or memory-backed storage.", .{fstype}); - if (!std.mem.eql(u8, m.target, path)) return refuse(a, r, "allocation node-local root must be its own mount.", .{}); + const real = fsx.realpath(fsx.cwd, path, &buf) catch |e| + return refuse(a, r, "the node-local mount {s} cannot be resolved ({s})", .{ path, @errorName(e) }, where_fix, whereArgs(nl)); + if (!std.mem.eql(u8, real, path)) { + var root_buf: [sys.path_max]u8 = undefined; + const real_root = fsx.realpath(fsx.cwd, nl.root, &root_buf) catch nl.root; + return refuse(a, r, "the node-local mount {s} is reached through a symbolic link, as {s}", .{ path, real }, link_fix ++ + "set storage.node_local_root, {s} [{s}], in the site file to the directory itself, {s}", .{ nl.root, nl.root_from, real_root }); + } + if (st.uid != uid) + return refuse(a, r, "the node-local mount {s} belongs to uid {d}, not to you (uid {d})", .{ path, st.uid, uid }, owner_fix, .{ nl.mount, nl.mount_from, nl.root, nl.root_from }); + const m = (try mountOf(a, mountinfo, path)) orelse + return refuse(a, r, "no mount in /proc/self/mountinfo holds the node-local mount {s}", .{path}, mountinfo_fix, .{}); + if (!std.mem.eql(u8, m.fstype, nl.fstype)) + return refuse(a, r, "the node-local mount {s} is on {s}, not {s}", .{ path, m.fstype, nl.fstype }, fstype_fix, .{ nl.fstype, nl.fstype_from }); + if (!std.mem.eql(u8, m.target, path)) + return refuse(a, r, "the node-local mount {s} is not a mount of its own but part of {s}", .{ path, m.target }, own_mount_fix, whereArgs(nl)); var opts = std.mem.tokenizeScalar(u8, m.options, ','); while (opts.next()) |o| { if (std.mem.eql(u8, o, "rw")) return .{ .path = path }; } - return refuse(a, r, "allocation mount is not writable.", .{}); + return refuse(a, r, "the node-local mount {s} is not mounted read-write ({s})", .{ path, m.options }, rw_fix, .{}); } /// A workspace eb-local made: a real directory of the caller named @@ -328,18 +386,16 @@ pub fn makeWorkspace(a: Allocator, job_root: []const u8) (fsx.Error || Allocator for (raw, 0..) |b, i| name[i] = alphabet[b % alphabet.len]; const path = try std.fmt.allocPrint(a, "{s}/eb-local.{s}", .{ job_root, name }); var zb: [sys.path_max:0]u8 = undefined; + const zp = try sys.z(&zb, path); // mkdir applies the process umask. With umask 0777 the directory // would be mode 000 and could not be opened to correct it, so the // umask is cleared for this one call. eb-local is one thread. const previous: linux.mode_t = @intCast(linux.syscall1(.umask, 0)); - const rc = linux.mkdirat(linux.AT.FDCWD, (try sys.z(&zb, path)).ptr, 0o700); - const created = linux.errno(rc); + const rc = linux.mkdirat(linux.AT.FDCWD, zp.ptr, 0o700); _ = linux.syscall1(.umask, previous); - switch (created) { - .SUCCESS => return path, - .EXIST => continue, - else => return error.AccessDenied, - } + if (sys.result(rc)) |made| { + if (made != null) return path; + } else |e| if (e != error.Exists) return e; } return error.Exists; } @@ -459,6 +515,27 @@ test "a workspace is private even when the umask clears every bit" { try testing.expectEqual(@as(u32, 0o700), (try fsx.statAt(fsx.cwd, path, false)).perm()); } +test "a workspace that cannot be made says why, and leaves the umask as it was" { + var arena = std.heap.ArenaAllocator.init(testing.allocator); + defer arena.deinit(); + const a = arena.allocator(); + var cwd_buf: [sys.path_max]u8 = undefined; + const cwd = try fsx.realpath(fsx.cwd, ".", &cwd_buf); + const root = try std.fmt.allocPrint(a, "{s}/.zig-cache/no-ws-{d}", .{ cwd, linux.getpid() }); + try common.atomic.makedirs(root); + defer fsx.deleteTree(a, fsx.cwd, root) catch {}; + const old: linux.mode_t = @intCast(linux.syscall1(.umask, 0o027)); + defer _ = linux.syscall1(.umask, old); + try testing.expectError(error.NotFound, makeWorkspace(a, try std.fmt.allocPrint(a, "{s}/gone", .{root}))); + const file = try std.fmt.allocPrint(a, "{s}/file", .{root}); + sys.close(try sys.openat(fsx.cwd, file, .{ .ACCMODE = .WRONLY, .CREAT = true }, 0o600)); + try testing.expectError(error.NotDir, makeWorkspace(a, file)); + const long = try a.alloc(u8, sys.path_max); + @memset(long, 'x'); + try testing.expectError(error.NameTooLong, makeWorkspace(a, long)); + try testing.expectEqual(@as(usize, 0o027), linux.syscall1(.umask, 0o027)); +} + test "removeTree stays on one device" { var arena = std.heap.ArenaAllocator.init(testing.allocator); defer arena.deinit(); @@ -491,17 +568,75 @@ test "the job mount is refused when another user owns it" { defer fsx.deleteTree(a, fsx.cwd, nodes) catch {}; const info = try std.fmt.allocPrint(a, "1 0 0:1 / / rw - ext4 /dev/x rw\n2 1 0:2 / {s} rw,relatime - xfs /dev/y rw\n", .{job}); var r: Refusal = .{}; - const ok = try jobRoot(a, nodes, default_mount, "xfs", "42", "u", info, linux.getuid(), &r); + const ok = try jobRoot(a, .{ .root = nodes }, "42", "u", info, linux.getuid(), &r); try testing.expectEqualStrings(job, ok.path); - try testing.expectError(error.Refused, jobRoot(a, nodes, default_mount, "xfs", "42", "u", info, linux.getuid() + 1, &r)); - try testing.expect(std.mem.indexOf(u8, r.message, "another user") != null); - try testing.expectError(error.Refused, jobRoot(a, nodes, default_mount, "gpfs", "42", "u", info, linux.getuid(), &r)); - try testing.expectError(error.Refused, jobRoot(a, nodes, default_mount, "xfs", "042", "u", info, linux.getuid(), &r)); - try testing.expectError(error.Refused, jobRoot(a, nodes, "job-%j", "xfs", "42", "u", info, linux.getuid(), &r)); - try testing.expectError(error.Refused, jobRoot(a, nodes, "%u", "xfs", "42", "u", info, linux.getuid(), &r)); + try testing.expectError(error.Refused, jobRoot(a, .{ .root = nodes }, "42", "u", info, linux.getuid() + 1, &r)); + try testing.expectEqualStrings(try std.fmt.allocPrint(a, "the node-local mount {s} belongs to uid {d}, not to you (uid {d})", .{ job, linux.getuid(), linux.getuid() + 1 }), r.message); + try testing.expectError(error.Refused, jobRoot(a, .{ .root = nodes, .fstype = "gpfs" }, "42", "u", info, linux.getuid(), &r)); + try testing.expectError(error.Refused, jobRoot(a, .{ .root = nodes }, "042", "u", info, linux.getuid(), &r)); + try testing.expectError(error.Refused, jobRoot(a, .{ .root = nodes, .mount = "job-%j" }, "42", "u", info, linux.getuid(), &r)); + try testing.expectError(error.Refused, jobRoot(a, .{ .root = nodes, .mount = "%u" }, "42", "u", info, linux.getuid(), &r)); try testing.expect(std.mem.indexOf(u8, r.message, "node_local_mount") != null); } +test "a refused job mount says what, why, and the setting that changes it" { + var arena = std.heap.ArenaAllocator.init(testing.allocator); + defer arena.deinit(); + const a = arena.allocator(); + var cwd_buf: [sys.path_max]u8 = undefined; + const cwd = try fsx.realpath(fsx.cwd, ".", &cwd_buf); + const nodes = try std.fmt.allocPrint(a, "{s}/.zig-cache/refusal-test-{d}", .{ cwd, linux.getpid() }); + const job = try std.fmt.allocPrint(a, "{s}/u.42", .{nodes}); + try common.atomic.makedirs(job); + defer fsx.deleteTree(a, fsx.cwd, nodes) catch {}; + const nl: NodeLocal = .{ .root = nodes, .root_from = "site /etc/eb-local/config.toml:3", .fstype_from = "site /etc/eb-local/config.toml:5" }; + const uid = linux.getuid(); + const table = struct { + fn of(allocator: Allocator, target: []const u8, options: []const u8, fstype: []const u8) ![]const u8 { + return std.fmt.allocPrint(allocator, "1 0 0:1 / / rw - ext4 /dev/x rw\n2 1 0:2 / {s} {s} - {s} /dev/y rw\n", .{ target, options, fstype }); + } + }.of; + var r: Refusal = .{}; + const where = try std.fmt.allocPrint(a, "storage.node_local_root, {s} [site /etc/eb-local/config.toml:3], and storage.node_local_mount, %u.%j [default], name it; " ++ + "build in an allocation that has a node-local disk, or set them in the site file to where Slurm mounts your job's node-local disk", .{nodes}); + + try testing.expectError(error.Refused, jobRoot(a, nl, "43", "u", try table(a, job, "rw", "xfs"), uid, &r)); + try testing.expectEqualStrings(try std.fmt.allocPrint(a, "the node-local mount {s}/u.43 does not exist", .{nodes}), r.message); + try testing.expectEqualStrings(where, r.fix); + + try testing.expectError(error.Refused, jobRoot(a, nl, "42", "u", try table(a, job, "rw", "gpfs"), uid, &r)); + try testing.expectEqualStrings(try std.fmt.allocPrint(a, "the node-local mount {s} is on gpfs, not xfs", .{job}), r.message); + try testing.expect(std.mem.indexOf(u8, r.fix, "storage.node_local_fstype, xfs [site /etc/eb-local/config.toml:5], names the nodes' file system") != null); + + try testing.expectError(error.Refused, jobRoot(a, nl, "42", "u", try table(a, nodes, "rw", "xfs"), uid, &r)); + try testing.expectEqualStrings(try std.fmt.allocPrint(a, "the node-local mount {s} is not a mount of its own but part of {s}", .{ job, nodes }), r.message); + try testing.expect(std.mem.endsWith(u8, r.fix, where)); + + try testing.expectError(error.Refused, jobRoot(a, nl, "42", "u", try table(a, job, "ro,relatime", "xfs"), uid, &r)); + try testing.expectEqualStrings(try std.fmt.allocPrint(a, "the node-local mount {s} is not mounted read-write (ro,relatime)", .{job}), r.message); + + try testing.expectError(error.Refused, jobRoot(a, nl, "4x2", "u", "", uid, &r)); + try testing.expectEqualStrings("SLURM_JOB_ID=4x2 is not a Slurm job id", r.message); + try testing.expect(std.mem.indexOf(u8, r.fix, "run eb-local inside the allocation") != null); + + // A link in the root is named with the directory it leads to; the job's + // own mount as a link is refused without one. + const link = try std.fmt.allocPrint(a, "{s}-link", .{nodes}); + var zt: [sys.path_max:0]u8 = undefined; + var zl: [sys.path_max:0]u8 = undefined; + var zlink_buf: [sys.path_max:0]u8 = undefined; + const zlink = try sys.z(&zlink_buf, link); + _ = linux.symlinkat((try sys.z(&zt, nodes)).ptr, linux.AT.FDCWD, zlink.ptr); + defer _ = linux.unlinkat(linux.AT.FDCWD, zlink.ptr, 0); + try testing.expectError(error.Refused, jobRoot(a, .{ .root = link }, "42", "u", try table(a, job, "rw", "xfs"), uid, &r)); + try testing.expectEqualStrings(try std.fmt.allocPrint(a, "the node-local mount {s}/u.42 is reached through a symbolic link, as {s}", .{ link, job }), r.message); + try testing.expect(std.mem.endsWith(u8, r.fix, try std.fmt.allocPrint(a, "set storage.node_local_root, {s} [default], in the site file to the directory itself, {s}", .{ link, nodes }))); + const alias = try std.fmt.allocPrint(a, "{s}/u.44", .{nodes}); + _ = linux.symlinkat((try sys.z(&zt, job)).ptr, linux.AT.FDCWD, (try sys.z(&zl, alias)).ptr); + try testing.expectError(error.Refused, jobRoot(a, nl, "44", "u", try table(a, alias, "rw", "xfs"), uid, &r)); + try testing.expectEqualStrings(try std.fmt.allocPrint(a, "the node-local mount {s} is a symbolic link", .{alias}), r.message); +} + test "the allocation's mount name" { var arena = std.heap.ArenaAllocator.init(testing.allocator); defer arena.deinit(); diff --git a/tests/test_config_cli.py b/tests/test_config_cli.py index e5cfff3..eeaa200 100644 --- a/tests/test_config_cli.py +++ b/tests/test_config_cli.py @@ -260,6 +260,68 @@ def test_a_missing_secret_stops_the_build_before_anything_is_made(self): self.assertEqual(list(self.job.iterdir()), []) self.assertFalse((self.root / "eb.json").exists()) + def test_a_build_gets_only_the_secrets_build_secrets_names(self): + with open(self.user, "a") as handle: + handle.write('\n[build]\nsecrets = ["SOURCE_TOKEN"]\n') + # OTHER_TOKEN's source is not set, and a build that does not get it + # does not read it. + env = dict(self.env) + del env["MY_OTHER"] + argv, env = binary.command(self.script, ["--config", str(self.site), "recipe.eb"], env) + run = subprocess.run(argv, env=env, cwd=self.root, capture_output=True, text=True) + self.assertEqual(run.returncode, 0, run.stdout + run.stderr) + seen = json.loads((self.root / "eb.json").read_text())["secrets"] + self.assertEqual(seen, {"SOURCE_TOKEN": "file-secret-value", "OTHER_TOKEN": None, "LM_LICENSE_FILE": None}) + text = (self.prefix / ".eb-local" / "logs" / "easybuild-test.log").read_text() + self.assertNotIn("file-secret-value", text) + self.assertIn("", text) + + run = self.run_tool(["--config", str(self.site), "--profile", "licensed", "recipe.eb"], + EB_LOCAL_BUILD_SECRETS="OTHER_TOKEN LM_LICENSE_FILE") + self.assertEqual(run.returncode, 0, run.stdout + run.stderr) + seen = json.loads((self.root / "eb.json").read_text())["secrets"] + self.assertEqual(seen, {"SOURCE_TOKEN": None, "OTHER_TOKEN": "env-secret-value", + "LM_LICENSE_FILE": "27000@licence.example"}) + + run = self.run_tool(["--config", str(self.site), "recipe.eb"], EB_LOCAL_BUILD_SECRETS="") + self.assertEqual(run.returncode, 0, run.stdout + run.stderr) + seen = json.loads((self.root / "eb.json").read_text())["secrets"] + self.assertEqual(seen, {"SOURCE_TOKEN": None, "OTHER_TOKEN": None, "LM_LICENSE_FILE": None}) + self.assertNotIn("removed secret values", run.stdout) + + run = self.run_tool(["--config", str(self.site), "recipe.eb"], EB_LOCAL_BUILD_SECRETS="LM_LICENSE_FILE") + self.assertEqual(run.returncode, 2, run.stdout + run.stderr) + self.assertIn("build.secrets [environment EB_LOCAL_BUILD_SECRETS] names LM_LICENSE_FILE, but no secret " + "LM_LICENSE_FILE is defined: add it to [secrets], or set EB_LOCAL_SECRET_LM_LICENSE_FILE=SOURCE", + run.stderr) + + def test_config_and_explain_say_which_secrets_a_build_gets(self): + run = self.run_tool(["config"]) + self.assertRegex(run.stdout, r"build\.secrets\s+\(every secret\)\s+\[default\]") + run = self.run_tool(["config", "--env"]) + self.assertNotIn("EB_LOCAL_BUILD_SECRETS", run.stdout) + + with open(self.user, "a") as handle: + handle.write('\n[build]\nsecrets = ["SOURCE_TOKEN"]\n\n[profile.none]\nbuild.secrets = []\n') + lines = self.user.read_text().splitlines() + top = lines.index('secrets = ["SOURCE_TOKEN"]') + 1 + run = self.run_tool(["config"]) + self.assertEqual(run.returncode, 0, run.stderr) + self.assertRegex(run.stdout, rf"build\.secrets\s+SOURCE_TOKEN\s+\[user .*config\.toml:{top}\]") + run = self.run_tool(["config", "--profile", "none"]) + self.assertRegex(run.stdout, rf"build\.secrets\s+\(none\)\s+\[user profile none, .*config\.toml:{len(lines)}\]") + run = self.run_tool(["config", "--env", "--profile", "none"]) + self.assertIn("export EB_LOCAL_BUILD_SECRETS=''\n", run.stdout) + run = self.run_tool(["config", "--env"]) + self.assertIn("export EB_LOCAL_BUILD_SECRETS=SOURCE_TOKEN\n", run.stdout) + + run = self.run_tool(["--config", str(self.site), "--explain", "recipe.eb"]) + self.assertEqual(run.returncode, 0, run.stderr) + self.assertIn(f"# SOURCE_TOKEN reaches eb's environment from file:{self.token}; logs are cleaned of it afterwards.\n", + run.stdout) + self.assertIn(f"# OTHER_TOKEN stays out of eb's environment and is not read: build.secrets [user {self.user}:{top}] " + "does not name it.\n", run.stdout) + def test_site_toolchains_reach_the_eessi_hooks(self): text = self.site.read_text() self.assertIn('allocation_hint = "salloc -p cpu -n 16"\n', text) diff --git a/tests/test_docs.py b/tests/test_docs.py new file mode 100644 index 0000000..2d8a57c --- /dev/null +++ b/tests/test_docs.py @@ -0,0 +1,58 @@ +#!/usr/bin/env python3 +"""The pages docs/export.el writes from docs/orgmode. + +Each Org source has its page, in the index's table of contents, and each +written page has its source. Where Emacs is installed, a fresh export +must match the committed pages; another Org than the one that wrote them +may lay a page out differently, and then the comparison is skipped. +""" +import os +from pathlib import Path +import re +import shutil +import subprocess +import tempfile +import unittest + +DOCS = Path(__file__).resolve().parents[1] / "docs" +ORG = DOCS / "orgmode" +GENERATED = "\n"), page) + + def test_each_written_page_has_its_org_source(self): + for page in DOCS.rglob("*.md"): + if "_build" not in page.parts and page.read_text().startswith(GENERATED): + self.assertTrue((ORG / page.relative_to(DOCS).with_suffix(".org")).is_file(), page) + + @unittest.skipUnless(shutil.which("emacs"), "exporting the Org sources needs Emacs") + def test_the_pages_are_what_their_org_sources_export_to(self): + with tempfile.TemporaryDirectory() as out: + run = subprocess.run(["emacs", "--batch", "-Q", "-l", str(DOCS / "export.el")], + env=dict(os.environ, EB_LOCAL_DOCS_OUT=out), capture_output=True, text=True) + self.assertEqual(run.returncode, 0, run.stderr) + stale = [str(rel) for rel in sources() + if (Path(out) / rel.with_suffix(".md")).read_text() != (DOCS / rel.with_suffix(".md")).read_text()] + if stale: + org = subprocess.run(["emacs", "--batch", "-Q", "--eval", "(progn (require 'org) (princ (org-version)))"], + capture_output=True, text=True).stdout + if not org.startswith(WRITTEN_WITH): + self.skipTest(f"Org {org} lays pages out differently from Org {WRITTEN_WITH}x") + self.assertEqual(stale, [], "run: emacs --batch -Q -l docs/export.el") + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_environment.py b/tests/test_environment.py index ed7a9f0..a4f660d 100644 --- a/tests/test_environment.py +++ b/tests/test_environment.py @@ -2,7 +2,9 @@ """Behavioral checks for the environment eb-local selects. The module and eb doubles verify wrapper routing and argument preservation. -They do not establish the destination chosen by a native EESSI extension. +They do not establish the destination chosen by a native EESSI extension; +the EESSI-extend double sets the install path the module would, below the +tree the install variable names. The module double refuses, as Lmod 9.4.5 does, a load that names EESSI-extend while EESSI is not loaded yet; the EESSI load sets the CPU target. The eessi-arch-guard double selects another target, as the guard @@ -41,6 +43,9 @@ export EESSI_SOFTWARE_SUBDIR=x86_64/amd/zen4 export EESSI_ACCELERATOR_TARGET= fi + if [ "$2" = EESSI-extend/2026.06-easybuild ]; then + export EASYBUILD_INSTALLPATH="${EESSI_USER_INSTALL:-${EESSI_PROJECT_INSTALL:-$HOME/eessi}}/versions/2026.06/software/linux/$EESSI_SOFTWARE_SUBDIR" + fi export EASYBUILD_HOOKS=/selected/eessi/eb_hooks.py return 0 fi diff --git a/tests/test_extend_cli.py b/tests/test_extend_cli.py index 26b7542..4b1c74f 100644 --- a/tests/test_extend_cli.py +++ b/tests/test_extend_cli.py @@ -16,9 +16,16 @@ SCRIPT = Path(__file__).resolve().parents[1] / "eb-local" INIT = r''' +export EESSI_SOFTWARE_PATH="$EESSI_CVMFS_REPO/versions/2026.06/software/linux/x86_64/amd/zen4" +export EESSI_SITE_SOFTWARE_PATH="$EESSI_CVMFS_REPO/host_injections/2026.06/software/linux/x86_64/amd/zen4" module() { if [ "$1" = load ]; then export EASYBUILD_PREFIX="${WORKING_DIR:-/tmp/$USER}/easybuild" + if [ -n "${EESSI_CVMFS_INSTALL+set}" ]; then installpath=$EESSI_SOFTWARE_PATH + elif [ -n "${EESSI_SITE_INSTALL+set}" ]; then installpath=$EESSI_SITE_SOFTWARE_PATH + else installpath="${EESSI_USER_INSTALL:-${EESSI_PROJECT_INSTALL:-$HOME/eessi}}/versions/2026.06/software/linux/x86_64/amd/zen4" + fi + export EASYBUILD_INSTALLPATH="${CONTROL_INSTALLPATH:-$installpath}" fi } ''' @@ -129,6 +136,39 @@ def test_at_most_one_install_variable_and_none_is_the_modules_default(self): self.assertIn("set at most one of EESSI_USER_INSTALL", two.stderr) self.assertIn("with none set, the module installs under $HOME/eessi", two.stderr) + def test_a_leftover_user_install_beside_a_project_install_is_named(self): + run = self.run_tool(["eb", "x.eb"], EESSI_USER_INSTALL="/home/alice/eessi", EESSI_PROJECT_INSTALL="/projects/a") + self.assertEqual(run.returncode, 3, run.stdout) + self.assertFalse((self.root / "eb-ran").exists()) + self.assertIn("eb-local: EESSI_USER_INSTALL=/home/alice/eessi and EESSI_PROJECT_INSTALL=/projects/a are both set; " + "EESSI-extend would make a private user install (umask 077) under /home/alice/eessi, " + "not a project install under /projects/a.\n" + " Unset the one an earlier session left", run.stderr) + + def test_eb_stops_when_the_install_path_is_outside_the_selected_tree(self): + mine = self.root / "mine" + run = self.run_tool(["eb", "x.eb"], EESSI_USER_INSTALL=str(mine), CONTROL_INSTALLPATH="/elsewhere/hooktree") + self.assertEqual(run.returncode, 2, run.stdout + run.stderr) + self.assertFalse((self.root / "eb-ran").exists()) + self.assertIn(f"eb-local: EESSI-extend set the install path to /elsewhere/hooktree, outside {mine}, " + "where a user install goes; nothing was built.\n" + " The install variable did not choose it: a site Lmod hook,", run.stderr) + + def test_eb_stops_on_a_leftover_install_path_for_modules(self): + run = self.run_tool(["eb", "x.eb"], EASYBUILD_INSTALLPATH_MODULES="/home/alice/old-modules") + self.assertEqual(run.returncode, 2, run.stdout + run.stderr) + self.assertFalse((self.root / "eb-ran").exists()) + self.assertIn("eb-local: EASYBUILD_INSTALLPATH_MODULES=/home/alice/old-modules is set in this shell and would put " + f"part of this install outside {self.root / 'home' / 'eessi'}; nothing was built.\n Unset it:", + run.stderr) + + def test_site_and_cvmfs_installs_go_into_the_trees_eessi_sets(self): + for name in ("EESSI_SITE_INSTALL", "EESSI_CVMFS_INSTALL"): + with self.subTest(name=name): + run = self.run_tool(["eb", "x.eb"], **{name: "1"}) + self.assertEqual(run.returncode, 0, run.stderr) + self.assertEqual(run.stdout.splitlines()[0], "0022") + def test_explain_with_a_command_it_does_not_explain_is_refused(self): prefix = self.root / "prefix" logs = prefix / ".eb-local" / "logs" diff --git a/tests/test_list_doctor_cli.py b/tests/test_list_doctor_cli.py index d0ba250..6bccc6d 100644 --- a/tests/test_list_doctor_cli.py +++ b/tests/test_list_doctor_cli.py @@ -178,6 +178,23 @@ def test_doctor_asks_eessi_arch_guard_only_in_a_job_with_eessi_loaded(self): self.assertIn("info eessi-arch-guard is not on PATH; builds, env and dev load EESSI for the target EESSI" " detects\n", run.stdout) + def test_doctor_says_what_is_wrong_with_the_node_local_mount_and_what_to_change(self): + run = self.run_tool(["doctor"], CONTROL_FSTYPE="tmpfs") + self.assertEqual(run.returncode, 1, run.stdout) + self.assertIn(f"FAIL Slurm job 123: the node-local mount {self.job} is on tmpfs, not xfs; builds refuse it. " + "A build's workspace must be on node-local disk, not shared or memory-backed storage; " + f"storage.node_local_fstype, xfs [site {self.config}:3], names the nodes' file system", run.stdout) + + def test_doctor_names_where_a_refused_prefix_and_its_storage_were_set(self): + shared = self.root / "shared" / "install" + run = self.run_tool(["doctor"], EB_LOCAL_PREFIX=str(shared)) + self.assertEqual(run.returncode, 1, run.stdout) + self.assertIn(f"FAIL the install prefix {shared} [environment EB_LOCAL_PREFIX] is under {shared.parent}, shared " + f"scratch in storage.shared_scratch [site {self.config}:4]; builds refuse it. Installs, sources and " + "logs must outlive the job and not be on shared scratch; set a prefix on durable storage you own " + "with prefix in your eb-local configuration, EB_LOCAL_PREFIX, or --project DIR for a project\n", + run.stdout) + def test_doctor_fails_on_a_project_directory_others_can_write(self): project = self.root / "durable" / "project" project.mkdir(parents=True) @@ -208,7 +225,8 @@ def test_doctor_fails_on_a_secret_every_build_would_stop_on(self): run = self.run_tool(["doctor"], **secret) self.assertEqual(run.returncode, 1, run.stdout) self.assertIn("FAIL secret MY_LICENCE_KEY: MY_LICENCE_SRC is not set", run.stdout) - self.assertIn("every build stops there, whether or not it uses MY_LICENCE_KEY", run.stdout) + self.assertIn("every build stops there, whether or not it uses MY_LICENCE_KEY. Name in build.secrets the " + "secrets builds need, or in EB_LOCAL_BUILD_SECRETS those one build needs\n", run.stdout) self.assertTrue(run.stdout.rstrip().endswith("Something above says FAIL; builds stop there.")) build = self.run_wrapper(["recipe.eb"], **secret) self.assertEqual(build.returncode, 2, build.stdout + build.stderr) @@ -228,6 +246,27 @@ def test_doctor_fails_on_a_secret_every_build_would_stop_on(self): run = self.without_a_site_file(**secret) self.assertIn("warn secret MY_LICENCE_KEY: MY_LICENCE_SRC is not set", run.stdout) + def test_doctor_fails_only_on_a_secret_builds_get(self): + secret = dict(EB_LOCAL_SECRET_MY_LICENCE_KEY="env:MY_LICENCE_SRC", EB_LOCAL_SECRET_MIRROR_TOKEN="env:MY_MIRROR") + run = self.run_tool(["doctor"], EB_LOCAL_BUILD_SECRETS="MIRROR_TOKEN", MY_MIRROR="mirror-token-value", **secret) + self.assertEqual(run.returncode, 0, run.stdout) + self.assertIn("warn secret MY_LICENCE_KEY: MY_LICENCE_SRC is not set [environment EB_LOCAL_SECRET_MY_LICENCE_KEY]; " + "builds do not read it, as build.secrets [environment EB_LOCAL_BUILD_SECRETS] does not name it, " + "but one that names it stops there\n", run.stdout) + self.assertIn("ok secret MIRROR_TOKEN can be read from env:MY_MIRROR\n", run.stdout) + self.assertTrue(run.stdout.rstrip().endswith("Nothing above stops a build.")) + build = self.run_wrapper(["recipe.eb"], EB_LOCAL_BUILD_SECRETS="MIRROR_TOKEN", MY_MIRROR="mirror-token-value", **secret) + self.assertEqual(build.returncode, 0, build.stdout + build.stderr) + + run = self.run_tool(["doctor"], EB_LOCAL_BUILD_SECRETS="MY_LICENCE_KEY", MY_MIRROR="mirror-token-value", **secret) + self.assertEqual(run.returncode, 1, run.stdout) + self.assertIn("FAIL secret MY_LICENCE_KEY: MY_LICENCE_SRC is not set [environment EB_LOCAL_SECRET_MY_LICENCE_KEY]; " + "every build stops there, as build.secrets [environment EB_LOCAL_BUILD_SECRETS] names MY_LICENCE_KEY\n", + run.stdout) + self.assertIn("info secret MIRROR_TOKEN can be read from env:MY_MIRROR; builds do not get it, as build.secrets " + "[environment EB_LOCAL_BUILD_SECRETS] does not name it\n", run.stdout) + self.assertNotIn("mirror-token-value", run.stdout + run.stderr) + def without_a_site_file(self, **extra): for installed in ("/etc/eb-local/config.toml", "/etc/eb-local.conf"): if Path(installed).exists(): diff --git a/tests/test_storage.py b/tests/test_storage.py index 305b159..ade8e8c 100644 --- a/tests/test_storage.py +++ b/tests/test_storage.py @@ -42,6 +42,13 @@ export EASYBUILD_HOOKS=/selected/hooks.py export TMPDIR=/scratch/module WORKING_DIR=/scratch/module export EASYBUILD_BUILDPATH=/scratch/module + # The install path EESSI-extend sets, or CONTROL_INSTALLPATH; and + # CONTROL_LOAD_SETS, NAME=VALUE, as a site load hook would set it. + case "$2" in + EESSI-extend/*) + export EASYBUILD_INSTALLPATH="${CONTROL_INSTALLPATH:-${EESSI_USER_INSTALL:-${EESSI_PROJECT_INSTALL:-$HOME/eessi}}/versions/2026.06/software/linux/x86_64/amd/zen4}" + [ -z "${CONTROL_LOAD_SETS:-}" ] || export "$CONTROL_LOAD_SETS";; + esac return 0 fi return 99 @@ -365,5 +372,162 @@ def test_install_prefix_cannot_use_job_storage(self): self.assertEqual(list(self.job.iterdir()), []) +@unittest.skipUnless(binary.BIN, "the wording of these refusals is the Zig build's") +class RefusalWording(StorageFixture): + """A refusal says what it refused and why, and what was not done; its next + line says what to change: a setting, with its value and where it was set, + a variable, or a command.""" + + def refusal(self, args=None, **extra): + run = self.run_wrapper(args, **extra) + self.assertEqual(run.returncode, 2, run.stdout + run.stderr) + self.assertEqual(run.stdout, "") + return run.stderr.splitlines() + + def site(self, line): + return f"[site {self.config}:{line}]" + + def test_a_mount_another_user_owns(self): + first, fix = self.refusal(CONTROL_OWNER=str(os.getuid() + 1)) + self.assertEqual(first, f"eb-local: the node-local mount {self.job} belongs to uid {os.getuid()}, " + f"not to you (uid {os.getuid() + 1}); nothing was built.") + self.assertEqual(fix, f" storage.node_local_mount, %u.%j [default], names your job's own mount below " + f"storage.node_local_root, {self.nodes} {self.site(2)}, with %u for your user name and %j " + "for the job id; set them in the site file to where Slurm mounts your job's node-local disk.") + + def test_a_mount_on_another_file_system(self): + first, fix = self.refusal(CONTROL_FSTYPE="tmpfs") + self.assertEqual(first, f"eb-local: the node-local mount {self.job} is on tmpfs, not xfs; nothing was built.") + self.assertIn("not shared or memory-backed storage", fix) + self.assertIn(f"storage.node_local_fstype, xfs {self.site(3)}, names the nodes' file system", fix) + + def test_a_mount_that_is_part_of_another_or_read_only(self): + first, fix = self.refusal(CONTROL_MOUNT_TARGET=str(self.nodes)) + self.assertEqual(first, f"eb-local: the node-local mount {self.job} is not a mount of its own but part of " + f"{self.nodes}; nothing was built.") + self.assertTrue(fix.endswith(f"storage.node_local_root, {self.nodes} {self.site(2)}, and storage.node_local_mount, " + "%u.%j [default], name it; build in an allocation that has a node-local disk, or set them " + "in the site file to where Slurm mounts your job's node-local disk."), fix) + first, fix = self.refusal(CONTROL_MOUNT_OPTIONS="ro,relatime") + self.assertEqual(first, f"eb-local: the node-local mount {self.job} is not mounted read-write (ro,relatime); " + "nothing was built.") + + def test_a_mount_the_site_file_names_that_does_not_exist(self): + write_config(self.config, self.nodes, "node_local_mount = job-%j\n") + first, fix = self.refusal() + self.assertEqual(first, f"eb-local: the node-local mount {self.nodes}/job-123 does not exist; nothing was built.") + self.assertIn(f"storage.node_local_mount, job-%j {self.site(6)}, name it", fix) + + def test_a_mount_reached_through_a_link_names_the_directory_itself(self): + real = self.root / "real-node-mounts" + self.nodes.rename(real) + self.nodes.symlink_to(real, target_is_directory=True) + first, fix = self.refusal() + self.assertEqual(first, f"eb-local: the node-local mount {self.job} is reached through a symbolic link, " + f"as {real / self.job.name}; nothing was built.") + self.assertTrue(fix.endswith(f"set storage.node_local_root, {self.nodes} {self.site(2)}, in the site file " + f"to the directory itself, {real}."), fix) + + def test_no_job_a_job_id_that_is_not_one_and_no_node_local_root(self): + self.assertEqual(self.refusal(SLURM_JOB_ID="")[0], + "eb-local: not inside a Slurm job: SLURM_JOB_ID is unset or empty; nothing was built.") + first, fix = self.refusal(SLURM_JOB_ID="not-a-job") + self.assertEqual(first, "eb-local: SLURM_JOB_ID=not-a-job is not a Slurm job id; nothing was built.") + self.assertIn("run eb-local inside the allocation, from salloc, srun or sbatch", fix) + self.config.write_text("node_local_fstype = xfs\n") + first, fix = self.refusal() + self.assertEqual(first, "eb-local: no site file sets storage.node_local_root, the directory that holds each " + "job's node-local mount; nothing was built.") + self.assertIn("--config FILE or EB_LOCAL_CONFIG=FILE", fix) + + def test_a_prefix_on_shared_scratch_or_in_job_storage_names_where_each_was_set(self): + for prefix, tree, what in ( + (self.root / "shared" / "install", self.root / "shared", + f"shared scratch in storage.shared_scratch {self.site(4)}"), + (self.job / "install", self.nodes, f"node-local storage below storage.node_local_root {self.site(2)}")): + with self.subTest(prefix=prefix): + first, fix = self.refusal(EB_LOCAL_PREFIX=str(prefix)) + self.assertEqual(first, f"eb-local: the install prefix {prefix} [environment EB_LOCAL_PREFIX] is under " + f"{tree}, {what}; nothing was built.") + self.assertEqual(fix, " Installs, sources and logs must outlive the job and not be on shared scratch; " + "set a prefix on durable storage you own with prefix in your eb-local configuration, " + "EB_LOCAL_PREFIX, or --project DIR for a project.") + self.assertFalse(prefix.exists()) + + def test_a_link_that_leads_sources_or_versions_away(self): + (self.prefix / ".eb-local").mkdir(parents=True) + sources = self.prefix / ".eb-local" / "sources" + sources.symlink_to(self.job, target_is_directory=True) + first, fix = self.refusal() + self.assertEqual(first, f"eb-local: {sources} leads to {self.job}, not to a directory inside the install " + f"prefix {self.prefix}; nothing was built.") + self.assertIn(f"Sources and logs stay in the durable prefix, beside the installs: replace the symbolic link " + f"in {sources} with a directory, or set a prefix", fix) + self.assertEqual(self.refusal(["--explain", "recipe.eb"])[0], first.replace("nothing was built", "a build would stop here")) + self.assertEqual(self.refusal(["clean"])[0], first.replace("nothing was built", "nothing was removed")) + sources.unlink() + shared = self.root / "shared" / "versions" + (self.prefix / "versions").symlink_to(shared, target_is_directory=True) + first, fix = self.refusal() + self.assertEqual(first, f"eb-local: {self.prefix}/versions leads to {shared}, under {shared.parent}, shared " + f"scratch in storage.shared_scratch {self.site(4)}; nothing was built.") + self.assertIn(f"replace the symbolic link in {self.prefix}/versions with a directory", fix) + self.assertEqual(list(self.job.iterdir()), []) + + def test_clean_workspaces_says_nothing_was_removed(self): + first, fix = self.refusal(["clean", "--workspaces"], SLURM_JOB_ID="") + self.assertEqual(first, "eb-local: clean --workspaces works only inside the Slurm job that made the workspaces, " + "and SLURM_JOB_ID is unset or empty; nothing was removed.") + self.assertIn("srun --jobid=JOBID --overlap", fix) + first, fix = self.refusal(["clean", "--workspaces"], CONTROL_FSTYPE="tmpfs") + self.assertEqual(first, f"eb-local: the node-local mount {self.job} is on tmpfs, not xfs; nothing was removed.") + + +@unittest.skipUnless(binary.BIN, "checking where EESSI-extend installs is a feature of the Zig build") +class InstallPathChecks(StorageFixture): + """The install path EESSI-extend chose, and install variables left in the shell or set as it loads.""" + + def test_an_install_path_moved_out_of_the_prefix_stops_the_build(self): + for moved in ("/elsewhere/hooktree", f"{self.prefix}/versions/../../elsewhere", + f"{self.prefix}-old/versions/2026.06", f"{self.prefix}/versions"): + with self.subTest(moved=moved): + run = self.run_wrapper(CONTROL_INSTALLPATH=moved) + self.assertEqual(run.returncode, 2, run.stdout + run.stderr) + self.assertFalse((self.root / "eb.json").exists()) + self.assertNotIn("installing into", run.stdout) + self.assertIn(f"eb-local: loading EESSI-extend/2026.06-easybuild set the install path to {moved}, " + f"outside {self.prefix}/versions, the tree eb-local checked; nothing was built.", run.stderr) + + def test_a_load_that_sets_an_install_path_for_modules_stops_the_build(self): + run = self.run_wrapper(CONTROL_LOAD_SETS="EASYBUILD_INSTALLPATH_MODULES=/elsewhere/modules") + self.assertEqual(run.returncode, 2, run.stdout + run.stderr) + self.assertFalse((self.root / "eb.json").exists()) + self.assertIn("eb-local: loading EESSI-extend/2026.06-easybuild set EASYBUILD_INSTALLPATH_MODULES=/elsewhere/modules, " + f"which would put part of the install outside {self.prefix}/versions", run.stderr) + + def test_an_install_variable_set_as_the_module_loads_is_reported_and_does_not_move_the_build(self): + run = self.run_wrapper(CONTROL_LOAD_SETS="EESSI_PROJECT_INSTALL=/projects/a") + self.assertEqual(run.returncode, 0, run.stdout + run.stderr) + self.assertEqual(json.loads((self.root / "eb.json").read_text())["user"], str(self.prefix)) + self.assertIn("eb-local: loading EESSI-extend/2026.06-easybuild set EESSI_PROJECT_INSTALL=/projects/a; " + f"this build still installs into {self.prefix}, but a shell that loads EESSI-extend by hand " + "keeps the change, and its next load installs elsewhere.", run.stderr) + + def test_a_leftover_install_variable_is_cleared_and_reported(self): + run = self.run_wrapper(EESSI_USER_INSTALL="/home/alice/eessi-old", + EASYBUILD_INSTALLPATH_MODULES="/home/alice/modules") + self.assertEqual(run.returncode, 0, run.stdout + run.stderr) + self.assertEqual(json.loads((self.root / "eb.json").read_text())["user"], str(self.prefix)) + self.assertIn("eb-local: EESSI_USER_INSTALL=/home/alice/eessi-old is set in this shell; this build clears it, " + "but EESSI-extend or eb run by hand would use it", run.stderr) + self.assertIn("eb-local: EASYBUILD_INSTALLPATH_MODULES=/home/alice/modules is set in this shell", run.stderr) + + def test_what_eb_local_env_sets_for_this_prefix_is_not_a_leftover(self): + run = self.run_wrapper(EESSI_USER_INSTALL=str(self.prefix), EASYBUILD_PREFIX="/tmp/alice/easybuild", + EASYBUILD_INSTALLPATH=f"{self.prefix}/versions/2026.06/software/linux/x86_64/amd/zen4") + self.assertEqual(run.returncode, 0, run.stdout + run.stderr) + self.assertNotIn("is set in this shell", run.stderr) + + if __name__ == "__main__": unittest.main()