Skip to content

Latest commit

 

History

History
117 lines (96 loc) · 8.92 KB

environment.md

File metadata and controls

117 lines (96 loc) · 8.92 KB

Environment variables

eb-local reads the variables below. The lines eb-local env and eb-local dev print, and a build, set others, listed after them.

Settings

Each of these sets a setting in place of the configuration files, and an option sets it in place of the variable. The configuration files describes each setting, and each value is checked as it is there. An empty variable is ignored, unless the table says what it does.

Variable Setting
EB_LOCAL_PREFIX prefix
EB_LOCAL_PROJECT project
EB_LOCAL_STACK_MODULE stack.module
EB_LOCAL_STACK_EXTEND stack.extend
EB_LOCAL_DEV_BUILDENV dev.buildenv
EB_LOCAL_DEV_BUILDENV_FOR_CUDA dev.buildenv_for.cuda; none empties it
EB_LOCAL_DEV_BUILDENV_FOR_LLVM dev.buildenv_for.llvm; none empties it
EB_LOCAL_DEV_BUILDENV_FOR_INTEL dev.buildenv_for.intel; none empties it
EB_LOCAL_DEV_BUILDENV_FOR_NVHPC dev.buildenv_for.nvhpc; none empties it
EB_LOCAL_DEV_MODULES dev.modules, with blanks between the names; empty, it empties it
EB_LOCAL_BUILD_ALLOCATION_HINT build.allocation_hint; empty, it empties it
EB_LOCAL_BUILD_SECRETS build.secrets, with blanks between the names; empty, a build gets none
EB_LOCAL_BUILD_CLEAR_FOREIGN_PREFIXES build.clear_foreign_prefixes; true or 1 sets it, false or 0 clears it
EB_LOCAL_DOCTOR_CVMFS_PARALLEL doctor.cvmfs_parallel; an integer from 0 to 8. 0 reads no metadata in parallel
EB_LOCAL_CLEAN_TRASH clean.trash
EB_LOCAL_TRASH clean.trash, the 1.x name; EB_LOCAL_CLEAN_TRASH wins over it
EB_LOCAL_CLEAN_LOGS_OLDER_THAN_DAYS clean.logs_older_than_days
EB_LOCAL_NIMVAULT_PROGRAM nimvault.program; empty, it empties it
EB_LOCAL_NIMVAULT_VAULT nimvault.vault; empty, it empties it
EB_LOCAL_SECRET_<NAME> the secret NAME, whose source is the value, as in [secrets]

The site settings, storage.*, build.site_toolchains and build.node_types, have no variable. eb-local config --env prints export lines for the variables that carry the settings in force, after EB_LOCAL_PROFILE='', so that no profile applies beneath them.

Others eb-local reads

Variable What eb-local does with it
EB_LOCAL_PROFILE Names the profile when --profile does not; empty, it selects none.
EB_LOCAL_CONFIG Names a configuration file to read when --config does not.
EB_LOCAL_KEEP_WORK 1 keeps the workspace of a build that succeeds.
EB_LOCAL_LOCK_TIMEOUT_MS Positive integer milliseconds to wait for a busy flock lock before exiting non-zero; default 300000.
EB_LOCAL_EESSI_EXTEND Set, not empty and not 0, it sends every argument to eb, as after eb-local eb --. An eb-stack EESSI target runs eb-local this way.
EB_LOCAL_ENV_STRICT Set, not empty and not 0 or false, env and dev prepend the same CVMFS check as --strict before their load lines.
EB_LOCAL_RPATH_WRAPPERS The wrapper directory an earlier dev put first on PATH; the next dev takes it off.
HOME Stands for ~/ in settings and secret sources, holds the default prefix, and the user file and the wrappers when the XDG_* variable is unset.
XDG_CONFIG_HOME Holds the user file, $XDG_CONFIG_HOME/eb-local/config.toml.
XDG_CACHE_HOME Holds the RPATH wrappers, below $XDG_CACHE_HOME/eb-local.
SLURM_JOB_ID The job a build runs in, whose node-local mount it uses; without it, a build and clean --workspaces stop.
EESSI_USER_INSTALL, EESSI_PROJECT_INSTALL, EESSI_SITE_INSTALL, EESSI_CVMFS_INSTALL Choose where eb-local eb installs. A build clears them, and warns about one left in the shell that is not the one it sets.
EESSI_CVMFS_REPO, EESSI_VERSION Name the EESSI repository (default /cvmfs/software.eessi.io) and version (default 2026.06) for eb, doctor and list. For env and dev they name only the Lmod init file a shell without module sources and the file --strict checks; the stack those lines load is stack.module.
EESSI_SOFTWARE_PATH, EESSI_SITE_SOFTWARE_PATH Checked by eb-local eb to confirm that EESSI-extend selected an install path inside the requested tree.
EESSI_SOFTWARE_SUBDIR, EESSI_ACCELERATOR_TARGET, EESSI_EPREFIX Used by check, check --dev, list, rpath-wrappers and doctor to identify the loaded CPU target, accelerator and compatibility layer.
LMOD_PKG, LMOD_CMD, MODULESHOME, MODULEPATH Checked by doctor and the emitted shell snippets to locate Lmod initialization and verify loaded module trees.
CVMFS_HTTP_PROXY Read by doctor --cvmfs as the active HTTP proxy override over /etc/cvmfs configuration files.
LD_LIBRARY_PATH, LD_PRELOAD, LD_AUDIT A build does not pass them on, and warns; dev warns about LD_LIBRARY_PATH; check looks in LD_LIBRARY_PATH as the loader does.
PATH Where eb-local finds bash, rtrash, nimvault, sbatch and eessi-arch-guard, and the compilers rpath-wrappers wraps.

Set by env and dev

The lines eb-local env prints, in order:

  1. load Lmod when the shell has no module command, and unload EESSI-extend;
  2. unset EESSI_CVMFS_INSTALL, EESSI_SITE_INSTALL, EESSI_USER_INSTALL, EESSI_PROJECT_INSTALL, EESSI_SITE_SOFTWARE_PREFIX, EESSI_SOFTWARE_SUBDIR_OVERRIDE, EESSI_ACCELERATOR_TARGET_OVERRIDE, EESSI_OVERRIDE_GPU_CHECK, EASYBUILD_INSTALLPATH, EASYBUILD_INSTALLPATH_SOFTWARE, EASYBUILD_INSTALLPATH_MODULES and EASYBUILD_PREFIX;
  3. set EESSI_USER_INSTALL to the prefix, or EESSI_PROJECT_INSTALL to the project directory;
  4. set each [eessi] variable;
  5. load the EESSI module; let eessi-arch-guard, when it is on PATH, move it to the CPU target the guard selects; and load the EESSI-extend module when the prefix exists;
  6. with build.site_toolchains, set EESSI_SITE_TOP_LEVEL_TOOLCHAINS_<EESSI version>, with _ for each . of the version, to the toolchains as JSON: [{"name": "intel", "version": "2026.1"}].

The modules set variables of their own.

The lines eb-local dev prints do the same, load the modules and a build environment, and set:

Variable Value
EB_LOCAL_DEV_PREFIX <prefix>/dev/<EESSI version>/<CPU target>, with /<GPU target> after it when EESSI found one
PATH The RPATH wrappers' directory first, when eb-local writes wrappers
EB_LOCAL_RPATH_WRAPPERS The RPATH wrappers' directory, when eb-local writes wrappers
SSL_CERT_FILE, CARGO_HTTP_CAINFO The host's CA bundle, when the host has none at /etc/ssl/certs/ca-certificates.crt and the variable is not set

EESSI's cargo and curl look for the CA bundle at /etc/ssl/certs/ca-certificates.crt. A host that keeps it at /etc/pki/tls/certs/ca-bundle.crt, /etc/ssl/ca-bundle.pem or /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem would leave them without one, so dev names the first of those that is readable.

Set for a build

The script a build runs gets eb-local's environment without the variables env unsets, BASH_ENV, ENV, SHELLOPTS, BASHOPTS, LD_LIBRARY_PATH, LD_PRELOAD and LD_AUDIT. With build.clear_foreign_prefixes or EB_LOCAL_BUILD_CLEAR_FOREIGN_PREFIXES set, it also drops entries of PERL5LIB, PYTHONPATH, R_LIBS*, CMAKE_PREFIX_PATH and PKG_CONFIG_PATH that lie outside the approved prefixes, and unsets a compiler-wrapper variable that resolves outside them. Off, which is the default, a build keeps those variables. The approved prefixes are the EESSI repository, the install prefix, the four EESSI install variables, doctor.approved_prefixes and eb-local's RPATH wrapper directory. eb-local doctor names each foreign entry either way. It sets these, where W is the workspace the build makes in its job's node-local mount:

Variable Value
TMPDIR, TMP, TEMP, EASYBUILD_TMPDIR $W/tmp
EASYBUILD_BUILDPATH $W/build
WORKING_DIR $W/source-index
XDG_CACHE_HOME $W/cache
CARGO_HOME $W/cargo
EASYBUILD_SOURCEPATH <prefix>/.eb-local/sources
EASYBUILD_TMP_LOGDIR <prefix>/.eb-local/logs
LMOD_EXACT_MATCH no

It also sets the install variable, each [eessi] variable and the site toolchains as env does, and loads the EESSI and EESSI-extend modules; after each load it sets the variables above again, whatever the module set. The secrets reach eb's environment only. eb-local --explain prints the script and this environment for one build, without running it.

See also