diff --git a/.github/dependabot.yml b/.github/dependabot.yml index fb2bce8..db69680 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -8,11 +8,3 @@ updates: dependencies: patterns: - "*" - - package-ecosystem: pip - directory: /docs - schedule: - interval: monthly - groups: - docs: - patterns: - - "*" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3a437db..6bec1dd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -65,6 +65,7 @@ jobs: run: TOOL_BIN="$PWD/zig-out/bin/eessi-arch-guard" python -m unittest discover -s tests -v docs: + # The scripts behind the documented output; docs.yml builds the site. runs-on: ubuntu-22.04 timeout-minutes: 30 steps: @@ -74,10 +75,6 @@ jobs: - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 with: python-version: "3.12" - - name: build documentation - run: | - python -m pip install -r docs/requirements.txt - make -C docs html - name: run documentation examples run: | python docs/examples/walkthrough.py mismatch @@ -93,6 +90,7 @@ jobs: python docs/examples/failure_cases.py verbose python docs/examples/failure_cases.py bad-timeout python docs/examples/shell_demo.py + python docs/examples/strict_workspace.py python docs/examples/accelerator.py mismatch python docs/examples/accelerator.py missing-module bash docs/examples/check_install.sh diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..0dacef1 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,64 @@ +# Build the documentation the way `pixi run -e docs docbld` does: Org export, +# API pages from the code, Sphinx with warnings and unresolved references as +# errors, the Zig autodoc site, and the internal link check. External links +# are checked in their own step. On main the site is published to +# https://stackhands.github.io/eessi-arch-guard/. +name: docs + +on: + push: + branches: [main] + pull_request: + workflow_dispatch: + schedule: + # Weekly, so a link that went dead elsewhere is noticed. + - cron: "17 5 * * 1" + +permissions: + contents: read + +concurrency: + group: docs-${{ github.ref }} + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: prefix-dev/setup-pixi@9936258fee697aff89b3fed6ca1f80a382ef694e # v0.11.3 + with: + environments: docs + cache: true + locked: true + + - name: Build + run: pixi run -e docs docbld + env: + DOCS_SOURCE_REF: ${{ github.sha }} + + - name: External links + run: pixi run -e docs linkcheck + env: + GITHUB_TOKEN: ${{ github.token }} + + - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 + with: + path: docs/build/html + + deploy: + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + needs: build + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - id: deployment + uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1 diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml deleted file mode 100644 index 1e112f5..0000000 --- a/.github/workflows/pages.yml +++ /dev/null @@ -1,36 +0,0 @@ -name: pages -# Publish the Sphinx site to https://stackhands.github.io/eessi-arch-guard/ -# from main. The docs job in ci.yml builds and checks it on every push. -on: - push: - branches: [main] -permissions: - contents: read -concurrency: - group: pages - cancel-in-progress: true -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v7 - - uses: actions/setup-python@v7 - with: - python-version: "3.12" - - run: python -m pip install -r docs/requirements.txt - - run: make -C docs html SPHINXOPTS="-W" - - uses: actions/upload-pages-artifact@v5 - with: - path: docs/_build/html - deploy: - needs: build - runs-on: ubuntu-latest - permissions: - pages: write - id-token: write - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - steps: - - id: deployment - uses: actions/deploy-pages@v5 diff --git a/.gitignore b/.gitignore index 71c5571..e50ab7b 100644 --- a/.gitignore +++ b/.gitignore @@ -6,8 +6,21 @@ dist/ build/ .ruff_cache/ .venv/ -docs/_build/ docs/examples/_work/ src/eessi-arch-guard.conf .zig-cache/ zig-out/ +zig-pkg/ + +# Documentation build (docs-plan template): generated, never committed. +/docs/build/ +/docs/source/**/*.rst +/docs/source/reference/api/ +/docs/source/**/*.png +/docs/source/**/*.svg +/docs/source/**/*.jpg +/docs/source/**/*.webp +!/docs/source/_static/** +/docs/**/__pycache__/ +/.pixi/ +/.lycheecache diff --git a/CHANGELOG.md b/CHANGELOG.md index fffbba7..b6ad06d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +# Changelog + + + ## [0.2.0] - 2026-11-14 ### Features diff --git a/COMPAT.md b/COMPAT.md index 6951de1..645b7a4 100644 --- a/COMPAT.md +++ b/COMPAT.md @@ -24,7 +24,7 @@ Slurm runs the file as `TaskProlog` with no arguments, so the argument-less path | later duplicate | `--chain` and `--timeout`: last occurrence wins. Booleans are idempotent. | n/a | n/a | L1700-1709 | | strict detection in wrapper | `main` sets the global strict flag by exact membership `"--strict" in argv` over the raw argv, independent of `parse_args`. `--chain --strict` therefore leaves `args.strict` False but the strict workspace policy True. | n/a | n/a | L1812 | | outer-handler shell detection | `main`'s exception handler picks the stderr/stdout channel with `"--shell" in argv` (raw membership). | n/a | n/a | L1816 | -| `--timeout` numeric grammar | `float(text)`: accepts leading/trailing whitespace, `+`, exponents, `_` digit separators, `inf`, `nan` (the last two rejected afterwards). Accepted only when finite-comparable, `value > 0` and `value <= threading.TIMEOUT_MAX` (9223372036.0 on this platform). | n/a | Rejected value gives the `--timeout is not a positive number...` warning. | L1513-1521, L118 | +| `--timeout` numeric grammar | `float(text)`: accepts leading/trailing whitespace, `+`, exponents, `_` digit separators, `inf`, `nan` (the last two rejected afterwards). Accepted only when finite-comparable, `value > 0` and `value <= threading.TIMEOUT_MAX` (9223372036.0 on this platform). A value above 2147483.647 is accepted, but the Python guard then fails every decision that runs a command (see Unintended differences). | n/a | Rejected value gives the `--timeout is not a positive number...` warning. | L1513-1521, L118 | | help text exact | See section 5 row "HELP". | n/a | n/a | L141-154 | ## 2. Exit codes @@ -187,15 +187,15 @@ All values come from `os.environ` copied at L1751 unless a row says the helper r | Path | Direction | Format / rules | Trust checks | Lines | |---|---|---|---|---| | `/etc/eessi-arch-guard.conf` | read | first candidate | see next row | L1619 | -| `/eessi-arch-guard.conf` | read | second candidate, used only if the first does not `os.path.exists` (a dangling symlink counts as absent). The first existing candidate wins even if untrusted: no fall-through. | `lstat`: symlink rejected; non-regular rejected; `st_uid != 0` rejected; `st_mode & 0o022` rejected. Only the file itself is checked (not parent directories, not `S_ISUID`). | L1616-1637, L1553-1566 | +| `/eessi-arch-guard.conf` | read | second candidate, used only if the first does not `os.path.exists` (a dangling symlink counts as absent). The first existing candidate wins even if untrusted: no fall-through. `script` is `__file__`: the path Python ran the file by, symlinks not resolved, or the module's path in `site-packages` for the console script `pip` installs; the Zig build differs when started through `PATH` (see Unintended differences). | `lstat`: symlink rejected; non-regular rejected; `st_uid != 0` rejected; `st_mode & 0o022` rejected. Only the file itself is checked (not parent directories, not `S_ISUID`). | L1616-1637, L1553-1566 | | config grammar | `blob.splitlines()` on bytes (`\n`, `\r`, `\r\n`); each line `strip()`ped (ASCII whitespace); skip if empty, starts with `#`, or has no `=`; split on the first `=`; key and value stripped; key must be valid UTF-8 and non-empty (otherwise skipped silently); a non-UTF-8 value is decoded `utf-8`/`surrogateescape` and its key is added to the "bad" list (warning, key kept); duplicate keys: last wins; no inline comments, quotes or continuation; no size cap (whole file read). Recognised keys: `chain` (empty counts as unset), `timeout`. Unknown keys ignored. | n/a | L1569-1597, L1604-1607 | | `chain` validity | value must start with `/`, contain no `\n \r \0`, be a regular file (`isfile`), and `os.access(X_OK)`. No owner/mode check on the chain executable. | n/a | L1610-1613 | | `/proc/cpuinfo` or `$EESSI_PROC_CPUINFO` | read | Up to 16 MiB (`_CPUINFO_READ_MAX = 16 * 1024 * 1024`), decoded UTF-8 `replace`; every line matching `(?im)^flags[ \t]*:[ \t]*(.*)$` is split on whitespace; the effective flag set is the intersection over all such lines; no match or unreadable: empty set (then every WAITPKG march is rejected). No trust check. | none | L636-658, L710 | | `/eessi_archdetect.sh` | executed (through `bash`) | `os.path.isfile` (follows symlinks); executable bit not required. | none | L689-691, L736-738 | | `/software///software` | stat | `os.path.isdir`; first candidate in archdetect order that exists. | none | L713-718 | | Cache directory | open | Non-strict: `$TMPDIR` if non-empty, `safe_absolute` and a directory, else `/tmp` if a directory, else no cache. Strict: `restore_work_base(env)` (below), else no cache. Opened `O_RDONLY\|O_DIRECTORY\|O_CLOEXEC` (a symlinked directory is followed; no owner/mode check on the directory). | n/a | L1235-1246, L1313, L1374, L1428 | -| Cache file `/.eessi-arch-guard......` | read, write | `name = ".eessi-arch-guard.%s.%s.%s.%s.%s.%s" % (os.getuid(), _safe_component(nodename), _safe_component(job), _safe_component(step), "shell" if shell else "prolog", digest)`; never deleted; `digest` = first 16 hex of SHA-256 over `"\0".join(env.get(k, "") for k in KEY_FIELDS)` UTF-8 with `surrogateescape`; `_safe_component`: kept if it matches `^[A-Za-z0-9._-]{1,64}$`, else first 16 hex of SHA-256 of the text; `nodename` is `os.uname().nodename`; no cache when `SLURM_JOB_ID` is empty. Content: JSON `{"v": 1, "kind": ..., "message": ..., "detail": ..., "changes": {...}}` (that key order, `ensure_ascii=True`, default separators) plus `\n`. | Read: opened relative to the dir fd with `O_RDONLY\|O_NOFOLLOW\|O_NONBLOCK\|O_CLOEXEC`; fstat must be a regular file, `st_uid == getuid()`, `st_nlink == 1`, `mode & 0o077 == 0`; at most 8 MiB read in one `os.read`; JSON must be a dict with `v == 1`, `message` null or a string without `\n \r \0`, `detail` null or string, `kind` in `skip/noop/reloaded/failed`, `changes` a dict whose keys are strings matching `ENV_NAME_RE` and not `_never_cache`, and whose values are `None` or strings that pass `value_emit_ok` with `multiline=shell`. Any failure: treated as no cache (silently). | L1249-1271, L1224-1226, L1312-1352, L1297-1309, L1362-1371 | -| Cache write | write | Temp file `....tmp` created `O_WRONLY\|O_CREAT\|O_EXCL\|O_NOFOLLOW\|O_CLOEXEC` mode `0600` in the same directory, `fchmod 0600`, then `os.replace` onto the cache name; `OSError` is discarded (temp unlinked); other `BaseException` unlinks the temp and re-raises. Every outcome kind is cached, except that `timeout`/`terminated` outcomes are produced outside `cached_decide` and never reach `_write_cache`. The cache key does not include the shell/prolog mode. | n/a | L1362-1398, L1453-1460 | +| Cache file `/.eessi-arch-guard......` | read, write | `name = ".eessi-arch-guard.%s.%s.%s.%s.%s.%s" % (os.getuid(), _safe_component(nodename), _safe_component(job), _safe_component(step), "shell" if shell else "prolog", digest)`; never deleted; `digest` = first 16 hex of SHA-256 over `"\0".join([env.get(k, "") for k in KEY_FIELDS] + [task_scope_key(env), gpu_scope_key(env)])` UTF-8 with `surrogateescape`; `task_scope_key` is the processors the task may run on (the intersection of its affinity, its cgroup's `cpuset.cpus.effective` and the Slurm bind list) in ascending order joined by `,`, `-` when the intersection is empty, and empty when none of the three can be read; `gpu_scope_key` is `NAME=value` for each of `CUDA_VISIBLE_DEVICES`, `ROCR_VISIBLE_DEVICES`, `GPU_DEVICE_ORDINAL`, `SLURM_STEP_GPUS`, `SLURM_GPUS_ON_NODE` that is set, in that order, joined by `\0`; `_safe_component`: kept if it matches `^[A-Za-z0-9._-]{1,64}$`, else first 16 hex of SHA-256 of the text; `nodename` is `os.uname().nodename`; no cache when `SLURM_JOB_ID` is empty. Content: JSON `{"v": 1, "kind": ..., "message": ..., "detail": ..., "changes": {...}}` (that key order, `ensure_ascii=True`, default separators) plus `\n`. | Read: opened relative to the dir fd with `O_RDONLY\|O_NOFOLLOW\|O_NONBLOCK\|O_CLOEXEC`; fstat must be a regular file, `st_uid == getuid()`, `st_nlink == 1`, `mode & 0o077 == 0`; at most 8 MiB read in one `os.read`; JSON must be a dict with `v == 1`, `message` null or a string without `\n \r \0`, `detail` null or string, `kind` in `skip/noop/reloaded/failed`, `changes` a dict whose keys are strings matching `ENV_NAME_RE` and not `_never_cache`, and whose values are `None` or strings that pass `value_emit_ok` with `multiline=shell`. Any failure: treated as no cache (silently). | L1249-1271, L1224-1226, L1312-1352, L1297-1309, L1362-1371 | +| Cache write | write | Temp file `....tmp` created `O_WRONLY\|O_CREAT\|O_EXCL\|O_NOFOLLOW\|O_CLOEXEC` mode `0600` in the same directory, `fchmod 0600`, then `os.replace` onto the cache name; `OSError` is discarded (temp unlinked); other `BaseException` unlinks the temp and re-raises. Every outcome kind is cached, except that `timeout`/`terminated` outcomes are produced outside `cached_decide` and never reach `_write_cache`. The digest does not include the output mode; the `` part of the name does. | n/a | L1362-1398, L1453-1460 | | Lock file `.lock` | open, `flock` | Opened `O_RDWR\|O_CREAT\|O_NOFOLLOW\|O_NONBLOCK\|O_CLOEXEC`, mode `0600`, relative to the dir fd; never deleted; must pass the same owned-private-regular-file test (else the decision runs without cache); `flock(LOCK_EX)`; under a deadline, `LOCK_EX\|LOCK_NB` polled every `0.05` s. | `_owned_private_file` | L1433-1446, L1279-1294, L1401-1413 | | Strict/explicit workspace base (`restore_work_base`) | stat | Order: `EESSI_ARCH_GUARD_WORKDIR` (must be private or `ValueError`); `TMPDIR` if private; if strict: `$XDG_STATE_HOME/eessi-arch-guard` (default `$HOME/.local/state/eessi-arch-guard`) if private, else `ValueError("strict mode needs an existing private job or state workspace")`; non-strict: `TMPDIR` if `safe_absolute` and a directory, else `tempfile.gettempdir()`. Never created or chmodded. | `_private_directory`: `safe_absolute`; `os.open(O_RDONLY\|O_DIRECTORY\|O_NOFOLLOW\|O_CLOEXEC)`; `st_uid == getuid()`; `mode & 0o077 == 0`; returns `realpath`. | L785-824 | | Restore work directory | create, remove | `tempfile.mkdtemp(prefix="eessi-arch-guard-", dir=base)` (0700); becomes the helper's `HOME`, `TMPDIR`, `EESSI_ARCH_GUARD_WORKDIR`; removed with `rmtree(ignore_errors=True)` in `finally`. | none beyond the base | L978-988, L1025-1026 | @@ -248,7 +248,7 @@ All values come from `os.environ` copied at L1751 unless a row says the helper r | Item | Behaviour | Lines | |---|---|---| | Decision deadline | One `time.monotonic()` deadline of `DEFAULT_TIMEOUT = 60.0` s (or `--timeout`/config) covers: the lock wait, both archdetect runs, the restore helper. Checked at `decide` entry, before a cache miss decides, in the lock poll loop, and around each child. | L115, L455-472, L1074-1075, L1450-1451, L1401-1413 | -| Deadline expiry | `_Deadline` (a `BaseException` subclass, not caught by `except Exception`) is raised; `limited_decide` reads the cache once (no lock, silently ignoring a miss; an `OSError` from that read would escape to the generic handler) and returns it, else a failed outcome token `timeout`. Not cached. | L444-446, L1489-1501 | +| Deadline expiry | `_Deadline` (a `BaseException` subclass, not caught by `except Exception`) is raised; `limited_decide` reads the cache once (no lock, silently ignoring a miss; an `OSError` from that read would escape to the generic handler) and returns it, else a failed outcome token `timeout`. Not cached. The Zig build treats that `OSError` as a miss (see Unintended differences). | L444-446, L1489-1501 | | SIGTERM | Handler installed only for the duration of `limited_decide` (`signal.signal(SIGTERM, ...)`) and restored in `finally`. It sets `terminated`, and unless `committing`, `os.killpg(child_pgid, SIGKILL)`. `_Terminated` is raised at the next `check()` or after the child returns; result is a failed outcome token `terminated`. Not cached. | L452-498, L1483-1510, L1502-1507 | | SIGTERM and child creation | `SIGTERM` is blocked with `pthread_sigmask` around `Popen` so the handler always knows the child's process group; then unblocked. If `terminated` was set meanwhile, the child group is killed before waiting. | L494-498, L559-580 | | Commit window | While the cache write runs, `committing` is True: `check()` returns early, the handler does not kill, and a signal arriving then does not discard the finished decision. | L467-468, L486-487, L1453-1460 | @@ -311,11 +311,11 @@ All tests live under `eessi-arch-guard/tests/`. `harness.py` L14-18 supports `TO | Item | Detail | Lines | |---|---|---| -| VERBOSE wording | Docs say "skip and match reasons"; code writes only `outcome.detail` (skip, noop, and the restore error on failures). | L1798-1799 | +| VERBOSE wording | The 0.2.0 manual said "skip and match reasons"; code writes only `outcome.detail` (skip, noop, and the restore error on failures). | L1798-1799 | | Dead code | Unreachable branch L292-293. | as listed | | `render_bytes` dry run | The decision runs `render_bytes` itself (prolog mode) to detect over-long lines; a cached outcome is not re-checked, so an over-long cached line raises `ValueError` in `_main` and becomes an emergency skip (exit 0, or 78 under strict). | L1211-1220, L1788-1794 | -| `TIMEOUT_MAX` is platform-dependent | `threading.TIMEOUT_MAX` is 9223372036.0 here; the number appears in warning text. | L118, L1535, L1544 | -| Not determined | The behaviour of the real `eessi_archdetect.sh` (only the stub in `tests/stubs/` was read); behaviour of real Lmod output; the docs for tutorial/howto pages under `docs/howto`, `docs/tutorial`, `docs/topics/{concepts,design,detection}.md` were not read line by line. | n/a | +| `TIMEOUT_MAX` is platform-dependent | `threading.TIMEOUT_MAX` is 9223372036.0 here; the number appears in warning text. It is not the largest timeout that works: above 2147483.647 the decision fails (see Unintended differences). | L118, L1535, L1544 | +| Not determined | The behaviour of the real `eessi_archdetect.sh` (only the stub in `tests/stubs/` was read); behaviour of real Lmod output; the tutorial, how-to and topic pages of the Markdown manual that `docs/orgmode/` replaced were not read line by line. | n/a | ## Where the Zig build differs on purpose @@ -336,3 +336,20 @@ The rows above describe the Python guard at 0.2.0. The Zig build in `zig/` keeps | a timeout written with non-ASCII digits, such as `5` | accepted, as `float()` takes any Unicode decimal digit | refused with the timeout warning; the default is kept | | a cache file with a leading-zero number, NaN, Infinity, or nesting deeper than 32 | `NaN` and `Infinity` accepted, the rest refused | all refused, and the decision is made again | | a cpuinfo line whose name is `flags` only under Unicode case folding (`flagſ`) | a flags line | not a flags line | + +## Unintended differences + +The two builds differ here without meaning to, and no row above allows it. In the first three rows the Zig build departs from the rows above, which makes each a bug in the Zig build; in the last, the Python guard fails where the rows above have it decide, a bug in the Python guard. Each was seen with Python 3.12.3 and the Zig build at 0.2.0. + +| case | Python guard | Zig build | +|---|---|---| +| started through `PATH` by a symbolic link whose target is in another directory, as `eval "$(eessi-arch-guard --shell)"` can be | reads `eessi-arch-guard.conf` beside the link | reads `eessi-arch-guard.conf` beside the link's target, as `/proc/self/exe` names it; started by an absolute or relative path, it reads beside the link, as the Python guard does. In `--shell` mode only the `timeout` setting applies. Slurm starts a `TaskProlog` by its absolute path, so the prolog is not affected. | +| the deadline passes and the cache directory cannot be opened for the late cache read, as when `TMPDIR` lost its permissions during the decision | the `OSError` reaches the outer handler: `print eessi-arch-guard: skipped, PermissionError: [Errno 13] Permission denied: 'DIR'`, no `EESSI_ARCH_GUARD_FAILED` | treated as a cache miss: `export EESSI_ARCH_GUARD_FAILED=->timeout` and `print eessi-arch-guard: decision exceeded the time limit; environment left as it was` | +| a `--restore` request whose `env` holds a value that is not a string; the guard's own requests hold only strings | takes `str()` of any JSON value: `null` is `None`, `true` is `True`, a number as Python prints it (`1E5` is `100000.0`), a list or object as Python's repr; `NaN` and `Infinity` are accepted | `null`, `true` and `false` as the Python guard, a number as the JSON writes it, a list or object refused with `restore request is malformed`; `NaN` and `Infinity` refused with exit 1 and `eessi-arch-guard: restore failed: the request is not JSON` | +| a `--timeout` or configured `timeout` above 2147483.647 seconds, which the timeout check accepts | every decision that runs a command ends in `print eessi-arch-guard: skipped, OverflowError: timeout is too large`, exit 0, 78 with `--strict`, the environment unchanged: `subprocess` passes the time left to `poll()`, whose limit is 2147483647 milliseconds | decides under that deadline | + +## Bugs both builds share + +| case | both builds | +|---|---| +| `--chain --strict` | `--chain` takes `--strict` as its path and refuses it with `eessi-arch-guard: --chain is not an absolute executable`, so the run is not strict: a failed decision, and an unexpected exception in the decision, exit 0. The rest of the program reads `--strict` from the raw argv: the restore and the cache use the strict workspace, so without a private `TMPDIR` or state directory a reload fails with `restore failed (restore workspace unavailable: strict mode needs an existing private job or state workspace)`; the helper gets `--strict`; and an error the decision's handler does not catch (in the Zig build: out of memory, a panic, a crash signal) exits 78. | diff --git a/DESIGN.md b/DESIGN.md index ab3f019..235dcb2 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -10,17 +10,17 @@ A Slurm **TaskProlog** is still the place that can fix the environment. It is th The program: -1. Decides, in Python, whether this node is the target the loaded modules were built for. CPU detection is `eessi_archdetect.sh -a cpupath` and then the first candidate that has `/software///software`. Accelerator detection is `eessi_archdetect.sh accelpath`, compared raw with `EESSI_ACCEL_SUBDIR`. The `ccNN` → `ccN0` fallback stays inside the EESSI module, which is what a reload is for. -2. On a mismatch, restores modules in a helper: the same file, exec'd as `python3 -I --restore`, with a process environment that contains only `PATH`, `HOME`, `LANG`, `LC_ALL`, and `TMPDIR`. The task environment is data on stdin, not the helper's process environment. Module names are argv to `LMOD_CMD`, after a whitelist check. Bash is started as `bash --noprofile --norc` and only after `BASH_ENV`, `ENV`, `SHELLOPTS`, `BASHOPTS`, `BASH_XTRACEFD`, and `PS4` have been removed. Its stdout is `env -0`, not a shell script the prolog will print. -3. Emits the **delta** of that restore, and only lines Slurm can apply safely. Names match `^[A-Za-z_][A-Za-z0-9_]*$`. In the default (prolog) mode, values must not contain CR, LF, or NUL. A value that cannot be carried aborts the whole restore: the task keeps the environment it arrived with, and the prolog sets `EESSI_ARCH_GUARD_FAILED`. Prompt variables (`PS1`, `PS2`, `PS3`, `PROMPT_COMMAND`) are the exception: an unsafe new value is left unchanged instead of failing the restore. `SLURM_*`, `BASH_FUNC_*`, `TMPDIR`, `BASH_ENV`, and shell bookkeeping (`_`, `SHLVL`, `PWD`, `OLDPWD`, `SHELLOPTS`, `BASHOPTS`) are never emitted. -4. Refuses module names that fail `^[A-Za-z0-9_][A-Za-z0-9._+-]*(/[A-Za-z0-9_][A-Za-z0-9._+-]*)+$` (length at most 256). The EESSI entry must be exactly one `EESSI/` name. A bad name is a failed restore, not a string interpolated into a shell. -5. Fails loud, and still exits 0. A missing software directory, a broken archdetect, an unusable `LMOD_CMD`, an unsafe name, or a module that will not load sets `EESSI_ARCH_GUARD_FAILED` and prints one line. `EESSI_ARCH_GUARD=0` is the opt-out (silent). `EESSI_ARCH_GUARD_MISSING=ignore` is the narrower opt-out for a node that has no EESSI software directory. Exit 0 is required: on current Slurm master, a non-zero TaskProlog status is `_exit(status)` and the task never runs. Loud means the user and the environment can see the failure. It does not mean killing the task. -6. `--shell` prints `export`/`unset` with `shlex.quote` on stdout, for `eval "$(eessi-arch-guard --shell)"`. The human message goes to stderr, so command substitution does not capture it and does not need an `echo` inside the eval. Prolog mode uses Slurm's `print` line, which master writes to the task's stdout. Those channels differ because Slurm has no stderr form of `print`. -7. One deadline covers the lock wait, both archdetect runs, and the restore helper. The default is 60 seconds (`DEFAULT_TIMEOUT`), Slurm's `DEFAULT_UNKILLABLE_TIMEOUT`. `--timeout SEC` overrides a `timeout = SEC` line in the root-owned config. `SEC` is a positive number of seconds at most CPython's `TIMEOUT_MAX` (`threading.TIMEOUT_MAX`); anything else keeps the default and warns. The children run in their own sessions. `SIGTERM` is held until the child process group is known, then released. At the deadline or on `SIGTERM` the guard SIGKILLs that group, sets `EESSI_ARCH_GUARD_FAILED` to `->timeout` or `->terminated`, exits 0, and does not cache that failure. After the kill the guard still waits up to `POST_KILL_WAIT_SECONDS` for the pipe to close. A result already in the cache is returned unchanged. A decision that has finished is still the result if the signal arrives while it is published. +1. Decides, in Python, whether this node is the target the loaded modules were built for. CPU detection is `eessi_archdetect.sh -a cpupath` on the processors the task may run on (the intersection of its affinity, its cpuset and the Slurm bind list) and then the first candidate that has `/software///software`. Accelerator detection is `eessi_archdetect.sh accelpath`, compared raw with `EESSI_ACCEL_SUBDIR`. The `ccNN` → `ccN0` fallback stays inside the EESSI module, which is what a reload is for. +2. On a mismatch, restores modules in a helper: the same file, exec'd as `python3 -I -X utf8 --restore` (with `--strict` added when the guard has it), with a process environment that contains only `PATH`, `LANG`, `LC_ALL`, `HOME`, `TMPDIR`, and `EESSI_ARCH_GUARD_WORKDIR`; the last three name one new private directory in the restore workspace. The task environment is data on stdin, not the helper's process environment. Module names are argv to `LMOD_CMD`, after a whitelist check. Bash is started as `bash --noprofile --norc` and only after `BASH_ENV`, `ENV`, `SHELLOPTS`, `BASHOPTS`, `BASH_XTRACEFD`, and `PS4` have been removed. Its stdout is `env -0`, not a shell script the prolog will print. +3. Emits the **delta** of that restore, and only lines Slurm can apply safely. Names match `^[A-Za-z_][A-Za-z0-9_]*$`. In the default (prolog) mode, values must not contain CR, LF, or NUL, and no line, newline included, may pass the 4094 bytes Slurm 17.11 reads. A value that cannot be carried aborts the whole restore: the task keeps the environment it arrived with, and the prolog sets `EESSI_ARCH_GUARD_FAILED`. Prompt variables (`PS1`, `PS2`, `PS3`, `PROMPT_COMMAND`) are the exception: an unsafe new value is left unchanged instead of failing the restore. `SLURM_*`, `BASH_FUNC_*`, `TMPDIR`, `BASH_ENV`, and shell bookkeeping (`_`, `SHLVL`, `PWD`, `OLDPWD`, `SHELLOPTS`, `BASHOPTS`) are never emitted. +4. Refuses module names that fail `^[A-Za-z0-9_][A-Za-z0-9._+-]*(/[A-Za-z0-9_][A-Za-z0-9._+-]*)+$` (length at most 256), except a four-digit year such as `2026`, which matches `^[0-9]{4}$`. The EESSI entry must be exactly one `EESSI/` name. A bad name is a failed restore, not a string interpolated into a shell. +5. Fails loud, and still exits 0. A missing software directory, a broken archdetect, an unusable `LMOD_CMD`, an unsafe name, or a module that will not load sets `EESSI_ARCH_GUARD_FAILED` and prints one line. `EESSI_ARCH_GUARD=0` is the opt-out (silent). `EESSI_ARCH_GUARD_MISSING=ignore` is the narrower opt-out for a node that has no EESSI software directory. Exit 0 is required: on current Slurm master, a non-zero TaskProlog status is `_exit(status)` and the task never runs. Loud means the user and the environment can see the failure. It does not mean killing the task. `--strict` is for a user's job wrapper that wants a status: a failed decision or an unexpected exception exits 78 instead. Slurm starts a TaskProlog with no arguments, so a site prolog keeps exit 0. +6. `--shell` prints `export`/`unset` with `shlex.quote` on stdout, for `eval "$(eessi-arch-guard --shell)"`. The human message goes to stderr, so command substitution does not capture it and does not need an `echo` inside the eval. Prolog mode uses Slurm's `print` line, which master writes to the task's stdout, and only local task 0 (`SLURM_LOCALID` unset or `0`) writes it, so a step with many tasks on a node shows it once. Those channels differ because Slurm has no stderr form of `print`. +7. One deadline covers the lock wait, both archdetect runs, and the restore helper. The default is 60 seconds (`DEFAULT_TIMEOUT`), Slurm's `DEFAULT_UNKILLABLE_TIMEOUT`. `--timeout SEC` overrides a `timeout = SEC` line in the root-owned config. `SEC` is a positive number of seconds at most CPython's `TIMEOUT_MAX` (`threading.TIMEOUT_MAX`); anything else keeps the default and warns. Above 2147483.647 seconds the Python guard accepts the value but fails every decision that runs a command, a bug COMPAT.md lists with the unintended differences. The children run in their own sessions. `SIGTERM` is held until the child process group is known, then released. At the deadline or on `SIGTERM` the guard SIGKILLs that group, sets `EESSI_ARCH_GUARD_FAILED` to `->timeout` or `->terminated`, exits 0 (78 with `--strict`), and does not cache that failure. After the kill the guard still waits up to `POST_KILL_WAIT_SECONDS` for the pipe to close. A result already in the cache is returned unchanged. A decision that has finished is still the result if the signal arrives while it is published. The helper command is `python3 -I -X utf8`. Each name and value crosses as one Latin-1 character per environment byte, and `-X utf8` turns that text back into those bytes for Lmod. -One decision is cached per uid, node, job, and step, under `TMPDIR` if that directory exists and otherwise `/tmp`. The cache key is the one from the original design: `EESSI_SOFTWARE_SUBDIR`, `EESSI_ACCEL_SUBDIR`, `LOADEDMODULES`, `MODULEPATH`, `EESSI_INIT_PREFIX`, `EESSI_PROC_CPUINFO`, `PATH`. `EESSI_ARCH_GUARD` is not part of the key. Adding it would change the contract; two tasks in one step that differ only by that variable share a result. The cache file is mode `0600`, created with `O_NOFOLLOW` and `O_EXCL`, and published with `rename`. The lock file is opened the same way. A symlink is not followed. If the cache cannot be used safely, the task computes its own result and does not write through the link. +One decision is cached per uid, node, job, step, and output mode (prolog or `--shell`), under `TMPDIR` if that is a safe absolute directory and otherwise `/tmp`. With `--strict` the cache is in the private restore workspace instead (`EESSI_ARCH_GUARD_WORKDIR`, a private `TMPDIR`, or `eessi-arch-guard` under `XDG_STATE_HOME` or `~/.local/state`), and without one nothing is cached. The cache key is the one from the original design, `EESSI_SOFTWARE_SUBDIR`, `EESSI_ACCEL_SUBDIR`, `LOADEDMODULES`, `MODULEPATH`, `EESSI_INIT_PREFIX`, `EESSI_PROC_CPUINFO`, `PATH`, plus the processors the task may run on and the GPU variables `CUDA_VISIBLE_DEVICES`, `ROCR_VISIBLE_DEVICES`, `GPU_DEVICE_ORDINAL`, `SLURM_STEP_GPUS`, and `SLURM_GPUS_ON_NODE`, so two tasks of one step on different processors or GPUs do not share a result. `EESSI_ARCH_GUARD` is not part of the key. Adding it would change the contract; two tasks in one step that differ only by that variable share a result. The cache file is mode `0600`, created with `O_NOFOLLOW` and `O_EXCL`, and published with `rename`. The lock file is opened the same way. A symlink is not followed. A cache or lock file is trusted only when the open file is a regular file owned by the caller, with one link and no group or other permission bits. If the cache cannot be used safely, the task computes its own result and does not write through the link. Chaining does not trust the job environment. Slurm execs a TaskProlog with no arguments, so a user cannot pass `--chain`. A site either wraps the existing prolog, or writes `chain = /absolute/path` in `/etc/eessi-arch-guard.conf` (or a file of that name beside the program). The file is used only when it is a regular file, owned by root, and not writable by group or others. Symlinks are ignored. Each key is decoded on its own. A value that is not UTF-8 is kept with surrogateescape, and the other keys still apply. `--chain PATH` exists for a root-owned wrapper and for tests. @@ -93,16 +93,16 @@ These were rejected before this repo existed. The new information does not reviv | Module name fails the grammar | Loud failure. Restore is not started. | | A module has no build for this target | Loud failure. Nothing from the restore is applied. When one load of all the modules fails, they are loaded again one call each, in order, so a module from a tree an earlier module adds (EESSI-extend and the user's installations) still loads, and the message names every module that fails rather than the first Lmod error. The list stops after 32. | | A changed variable cannot be expressed as a prolog line | Loud failure. No partial delta. | -| Any unexpected exception | One skip line, exit 0. | -| The decision is still running at the deadline | `->timeout`, the waited-on process group is SIGKILLed, exit 0, nothing cached. | -| `SIGTERM` during the decision | `->terminated`, the same kill, exit 0, nothing cached. | +| Any unexpected exception | One skip line, exit 0 (78 with `--strict`). | +| The decision is still running at the deadline | `->timeout`, the waited-on process group is SIGKILLed, exit 0 (78 with `--strict`), nothing cached. | +| `SIGTERM` during the decision | `->terminated`, the same kill, exit 0 (78 with `--strict`), nothing cached. | | Chained prolog exits non-zero | That status is returned and this program does not restore. Slurm will kill the task, which is what that prolog already did. | `EESSI_ARCH_GUARD_RELOADED` is `was->now`. When the accelerator differs, each side is ` ` or ` no accel`. `EESSI_ARCH_GUARD_FAILED` uses the same shape, with a fixed token (`no-software-dir`, `archdetect-failed`, `unsafe-module-name`, `unsafe-environment`, `lmod-unavailable`, `restore-failed`, `timeout`, `terminated`) when there is no selected target. ## Install shape -Runtime dependency is Python 3.9+ standard library, executed as `python3 -I`. The TaskProlog target is the single file `src/eessi_arch_guard.py` (shebang `#!/usr/bin/python3 -I`). `pyproject.toml` packages that module for a login-node `--shell` install. The generated console script does not pass `-I`; the prolog should be the file itself. +Runtime dependency is Python 3.9+ standard library, executed as `python3 -I`. The TaskProlog target is the single file `src/eessi_arch_guard.py` (shebang `#!/usr/bin/python3 -I`). `pyproject.toml` packages that module for a login-node `--shell` install. The generated console script does not pass `-I`; the prolog should be the file itself. The Zig build in `zig/` is a static binary with the same interface, whose restore helper is the binary itself with `--restore`; COMPAT.md lists where it differs. The Python file stays the default. ## Intel A100 CPU subdirectory diff --git a/README.md b/README.md index f7d4803..703d700 100644 --- a/README.md +++ b/README.md @@ -9,14 +9,13 @@ eessi-arch-guard is a Slurm TaskProlog that reloads an EESSI module stack when the task runs on a CPU or GPU other than the target recorded at `module load`. The EESSI module chooses that target once. Lmod keeps the recorded `MODULEPATH` and the `EBROOT*` paths until the stack is purged and loaded again. The prolog does that purge and load on the compute node, before `execve`, and prints the environment delta for `slurmstepd` to apply. -Documentation: , a Sphinx site built from `docs/`: a tutorial, how-to guides, topics, and a reference, including the generated Python API. +Documentation: , built from the Org pages in `docs/orgmode/`: a tutorial, how-to guides, explanation, and a reference, including the API generated from the Python and Zig code. ```console -python3 -m pip install -r docs/requirements.txt -make -C docs html +pixi run -e docs docbld ``` -The HTML is written to `docs/_build/html`. +The HTML is written to `docs/build/html`. `docs/orgmode/contributing.org` says how to write a page. ## Install the prolog diff --git a/build.zig b/build.zig index 71bf5a0..5b58cd2 100644 --- a/build.zig +++ b/build.zig @@ -1,6 +1,8 @@ const std = @import("std"); const zon = @import("build.zig.zon"); +/// The static binary, stripped unless built for debugging, with the +/// commit -Dcommit names; and the steps docs, test and suite. pub fn build(b: *std.Build) void { const target = b.standardTargetOptions(.{ .default_target = .{ .abi = .musl, .cpu_model = .baseline } }); const optimize = b.standardOptimizeOption(.{ .preferred_optimize_mode = .ReleaseSafe }); @@ -27,6 +29,17 @@ pub fn build(b: *std.Build) void { const exe = b.addExecutable(.{ .name = "eessi-arch-guard", .root_module = mod, .linkage = .static }); b.installArtifact(exe); + // The Zig autodoc site, into /docs (pixi task autodoc). A compile + // of its own: asking the installed one for docs would add -femit-docs to + // every build of the binary. + const doc_exe = b.addExecutable(.{ .name = "eessi-arch-guard", .root_module = mod }); + const docs = b.addInstallDirectory(.{ + .source_dir = doc_exe.getEmittedDocs(), + .install_dir = .prefix, + .install_subdir = "docs", + }); + b.step("docs", "Generate the API reference").dependOn(&docs.step); + const unit = b.addTest(.{ .root_module = mod }); const test_step = b.step("test", "Run the Zig unit tests"); test_step.dependOn(&b.addRunArtifact(unit).step); diff --git a/changelog.d/+absolute-path.doc.md b/changelog.d/+absolute-path.doc.md new file mode 100644 index 0000000..376134e --- /dev/null +++ b/changelog.d/+absolute-path.doc.md @@ -0,0 +1 @@ +The environment variables page says what it means by an absolute path, as both builds check it: one that starts with `/`, has no `..` part, and holds no newline, carriage return or NUL. A `TMPDIR` with a `..` part is not used, and an `EESSI_PREFIX` or `EESSI_INIT_PREFIX` with one ends in `archdetect-failed`, which the page did not say. diff --git a/changelog.d/+compat-design-paths.doc.md b/changelog.d/+compat-design-paths.doc.md new file mode 100644 index 0000000..7f1bce1 --- /dev/null +++ b/changelog.d/+compat-design-paths.doc.md @@ -0,0 +1 @@ +COMPAT.md says that the second configuration file is looked for beside `__file__`, which for the console script `pip` installs is the module in `site-packages`. DESIGN.md lists the helper's environment so that its last three variables are the ones that name the helper's private directory, as the text says. diff --git a/changelog.d/+compat-unintended.doc.md b/changelog.d/+compat-unintended.doc.md new file mode 100644 index 0000000..3e26b7d --- /dev/null +++ b/changelog.d/+compat-unintended.doc.md @@ -0,0 +1 @@ +COMPAT.md lists the differences between the builds that are bugs, not choices: the Zig build reads the config beside a symlink's target when started through `PATH`, reports a timeout where the Python guard skips after a failed cache read at the deadline, and handles `--restore` values that are not strings differently; the Python guard fails every decision that runs a command when the timeout is above 2147483.647 seconds; and in both, `--chain --strict` is not strict. The cache row names everything the digest covers, the task's processors and visible GPUs included. diff --git a/changelog.d/+design-current.doc.md b/changelog.d/+design-current.doc.md new file mode 100644 index 0000000..2b0592c --- /dev/null +++ b/changelog.d/+design-current.doc.md @@ -0,0 +1 @@ +`DESIGN.md` says what the guard does now: detection on the task's processors, the full helper command and environment, the 4094-byte prolog line, four-digit year modules, exit 78 under `--strict`, the cache per output mode with the task's processors and GPUs in its key and the strict workspace, the cache trust rule, the prolog line from local task 0 only, and the Zig build beside the Python file. diff --git a/changelog.d/+doc-comments.doc.md b/changelog.d/+doc-comments.doc.md new file mode 100644 index 0000000..471c4b1 --- /dev/null +++ b/changelog.d/+doc-comments.doc.md @@ -0,0 +1 @@ +Every `pub` declaration of the Zig build, and every public function, class and method of `src/eessi_arch_guard.py`, has a doc comment or docstring, whose first sentence is the summary the API pages list. The comment on `eessiModule` in `zig/text.zig` writes its pattern as code, so its API page shows `^EESSI/$` instead of passing `` through as an HTML tag. diff --git a/changelog.d/+docs-pages.doc.md b/changelog.d/+docs-pages.doc.md new file mode 100644 index 0000000..0772bfa --- /dev/null +++ b/changelog.d/+docs-pages.doc.md @@ -0,0 +1 @@ +The site has the rest of its pages. How-to guides configure the guard, use it without changing the site TaskProlog, run it in a batch script, run a program you built yourself on more than one node type, and correct a failed reload. Explanation pages say why a task prolog runs the reload, and why the guard prints prolog lines or shell lines and shares one decision per step. Reference pages describe the command, the configuration file, the environment variables, the messages and markers, and the CPU flags. Their transcripts come from the scripts in `docs/examples/` and from runs of the guard. diff --git a/changelog.d/+docs-site.doc.md b/changelog.d/+docs-site.doc.md new file mode 100644 index 0000000..880a5df --- /dev/null +++ b/changelog.d/+docs-site.doc.md @@ -0,0 +1 @@ +The documentation site is built from Org pages in `docs/orgmode/` with Sphinx, in four parts: the tutorial "See the guard reload EESSI for another CPU", how-to guides, explanation and reference. The API pages are generated from the doc comments of `zig/main.zig` and the files it imports and from the docstrings of `src/eessi_arch_guard.py`, and `zig build docs` installs the Zig autodoc site. `pixi run -e docs docbld` builds it as CI does and fails on a warning, an unresolved name or a dead internal link; `pixi run -e docs linkcheck` checks the external links. The `docs` workflow publishes the site to GitHub Pages; the Markdown pages, `docs/requirements.txt` and `pages.yml` are gone, and `CHANGELOG.md` has the marker under which `towncrier build` adds a release. diff --git a/changelog.d/+strict-example.doc.md b/changelog.d/+strict-example.doc.md new file mode 100644 index 0000000..81b57a3 --- /dev/null +++ b/changelog.d/+strict-example.doc.md @@ -0,0 +1 @@ +`docs/examples/strict_workspace.py` prints the `--strict --shell` failure that "Run the guard in a batch script" quotes, then checks that the reload runs once `~/.local/state/eessi-arch-guard` exists. The page shows its command, and CI's docs job runs it with the other examples, so every output block in the documentation comes from a script in the repository. diff --git a/changelog.d/+zig-entry-points.doc.md b/changelog.d/+zig-entry-points.doc.md new file mode 100644 index 0000000..d5b04d8 --- /dev/null +++ b/changelog.d/+zig-entry-points.doc.md @@ -0,0 +1 @@ +`build.zig` and `docs/tools/zig_api.zig`, which writes the Zig API pages, have a doc comment on their `pub` functions, `build` and `main`, like every other `pub` declaration in the repository. diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 9bb64f8..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,12 +0,0 @@ -# Build the HTML documentation. Install docs/requirements.txt first. -SPHINXOPTS = -W --keep-going -SOURCEDIR = . -BUILDDIR = _build - -.PHONY: html clean - -html: - python3 -m sphinx $(SPHINXOPTS) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" - -clean: - rm -rf "$(BUILDDIR)" diff --git a/docs/_static/custom.css b/docs/_static/custom.css deleted file mode 100644 index ae0f3b5..0000000 --- a/docs/_static/custom.css +++ /dev/null @@ -1,6 +0,0 @@ -article figure img, -article figure svg { - max-width: 100%; - height: auto; - background: #fff; -} diff --git a/docs/_templates/.gitkeep b/docs/_templates/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 4fd7245..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,113 +0,0 @@ -"""Sphinx configuration for the eessi-arch-guard documentation.""" - -from __future__ import annotations - -import os -import sys - -sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir, "src"))) - -import eessi_arch_guard - -project = "eessi-arch-guard" -author = "eessi-arch-guard developers" -copyright = "(c) eessi-arch-guard developers" -version = eessi_arch_guard.__version__ -release = version - -extensions = [ - "myst_parser", - "sphinx.ext.autodoc", - "sphinx.ext.intersphinx", - "sphinx.ext.viewcode", - "sphinx_design", -] - -myst_enable_extensions = [ - "colon_fence", - "deflist", - "substitution", -] -myst_heading_anchors = 3 -myst_substitutions = {"version": release} - -autosummary_generate = False -autodoc_member_order = "bysource" -autodoc_default_options = { - "members": True, - "undoc-members": True, -} -autoclass_content = "class" - -intersphinx_mapping = { - "python": ("https://docs.python.org/3", None), -} - -templates_path = ["_templates"] -exclude_patterns = ["_build", "examples", "Thumbs.db", ".DS_Store"] -html_static_path = ["_static"] -html_css_files = ["custom.css"] -html_theme = "shibuya" -html_title = "eessi-arch-guard" -html_short_title = "eessi-arch-guard" -html_favicon = "_static/favicon.svg" -html_baseurl = "https://stackhands.github.io/eessi-arch-guard/" -html_theme_options = { - "github_url": "https://github.com/stackhands/eessi-arch-guard", - "accent_color": "teal", - "dark_code": True, - "globaltoc_expand_depth": 1, - "light_logo": "_static/logo-light.svg", - "dark_logo": "_static/logo-dark.svg", - "nav_links": [ - {"title": "Tutorial", "url": "tutorial/index"}, - {"title": "How-to", "url": "howto/index"}, - {"title": "Reference", "url": "reference/index"}, - # stackhands:begin (generated by stackhands/.github branding/sync.py) - { - "title": "stackhands", - "children": [ - { - "title": "eb-stack", - "url": "https://eb-stack.rgoswami.me/", - "summary": "Solve, shard and plan an EasyBuild build list; admit builds under a scratch inode budget", - }, - { - "title": "eb-staged-rebuild", - "url": "https://stackhands.github.io/eb-staged-rebuild/", - "summary": "Rebuild an installation in a staged tree and swap it in, so running jobs keep their paths", - }, - { - "title": "eb-local", - "url": "https://stackhands.github.io/eb-local/", - "summary": "Install software with EasyBuild on top of EESSI into a directory a user or project owns", - }, - { - "title": "eb-keep-logs", - "url": "https://stackhands.github.io/eb-keep-logs/", - "summary": "Keep a failed build's EasyBuild log and command output; rotate a pipeline's log tree", - }, - { - "title": "rfc9162", - "url": "https://stackhands.github.io/rfc9162/", - "summary": "Append-only Merkle logs hashed as RFC 9162, with tiled storage and signed checkpoints", - }, - { - "title": "zig-common", - "url": "https://stackhands.github.io/zig-common/", - "summary": "The shared Zig library under the Zig tools: system calls, checked files, child processes", - }, - ], - }, - # stackhands:end - ], -} -html_context = { - "source_type": "github", - "source_user": "stackhands", - "source_repo": "eessi-arch-guard", - "source_version": "main", - "source_docs_path": "/docs/", -} -html_show_sourcelink = True -html_show_copyright = True diff --git a/docs/development.md b/docs/development.md deleted file mode 100644 index 5acdbfe..0000000 --- a/docs/development.md +++ /dev/null @@ -1,37 +0,0 @@ -# Development - -The suite uses the standard library and the stubs under `tests/`. Those stubs stand in for the prefix, archdetect, and `nvidia-smi`. `tests/test_real_lmod.py` runs one reload through `/usr/share/lmod/lmod/libexec/lmod` when that file exists and is skipped otherwise. - -```console -$ python3 -m pip install ruff -$ ruff check src tests -$ python3 -m unittest discover -s tests -v -``` - -On this machine `ruff check src tests docs/examples` exits 0, and the suite reports `OK (skipped=1)` because the Lmod libexec path is absent. - -`python3 tests/measure_noop.py` prints the host, the Python version, and cold, warm, and baseline percentile timings for a same-target run. The numbers belong to the machine that runs it. - -Build the HTML documentation from a virtualenv that has `docs/requirements.txt` installed: - -```console -$ python3 -m pip install -r docs/requirements.txt -$ make -C docs html -``` - -`make -C docs html` runs `python3 -m sphinx -W --keep-going -b html docs docs/_build/html` via the Makefile, and treats warnings as errors. The pages are written to `docs/_build/html`. - -The documentation examples assert the lines quoted in the tutorial and the how-tos: - -```console -$ python3 docs/examples/walkthrough.py mismatch -$ python3 docs/examples/walkthrough.py again -$ python3 docs/examples/walkthrough.py clean -$ python3 docs/examples/failure_cases.py no-software-dir -$ python3 docs/examples/shell_demo.py -$ python3 docs/examples/accelerator.py mismatch -$ bash docs/examples/check_install.sh -$ bash docs/examples/check_config.sh -``` - -`check_install.sh` and `check_config.sh` use `sudo -n`. The install script refuses to replace an existing `/usr/local/sbin/eessi-arch-guard`. diff --git a/docs/examples/strict_workspace.py b/docs/examples/strict_workspace.py new file mode 100755 index 0000000..ad8b7c5 --- /dev/null +++ b/docs/examples/strict_workspace.py @@ -0,0 +1,53 @@ +#!/usr/bin/env python3 +"""Run ``--strict --shell`` with no private workspace, then with one. + +``$PREFIX`` in the transcript stands for the temporary prefix. Only the +first run is printed. The second creates ``~/.local/state/eessi-arch-guard`` +with mode 700, as the batch-script guide does, and checks that the reload +then runs. +""" + +from __future__ import annotations + +import os +import sys +import tempfile + +import support + + +def main() -> int: + site, env = support.cpu_site() + try: + for name in ("TMPDIR", "XDG_STATE_HOME", "EESSI_ARCH_GUARD_WORKDIR"): + env.pop(name, None) + home = tempfile.mkdtemp(prefix="home-", dir=site.root) + os.chmod(home, 0o755) + env["HOME"] = home + # /tmp is shared, so --strict does not take it as a workspace. + env["TMPDIR"] = "/tmp" + proc = support.run(env, ("--strict", "--shell")) + print("case: strict-no-workspace") + print("command: python3 -I src/eessi_arch_guard.py --strict --shell") + support.show(proc, site.root) + if proc.returncode != 78 or "->restore-failed'" not in proc.stdout: + print("--strict did not fail the reload with exit 78", file=sys.stderr) + return 1 + if "strict mode needs an existing private job or state workspace" not in proc.stderr: + print("cause missing from stderr", file=sys.stderr) + return 1 + state = os.path.join(home, ".local", "state", "eessi-arch-guard") + os.makedirs(state) + os.chmod(state, 0o700) + proc = support.run(env, ("--strict", "--shell")) + if proc.returncode != 0 or "EESSI_ARCH_GUARD_RELOADED=" not in proc.stdout: + print("the state workspace did not let the reload run", file=sys.stderr) + sys.stderr.write(proc.stderr) + return 1 + return 0 + finally: + site.close() + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/docs/export.el b/docs/export.el new file mode 100644 index 0000000..3253546 --- /dev/null +++ b/docs/export.el @@ -0,0 +1,208 @@ +;;; export.el --- Publish docs/orgmode to docs/source -*- lexical-binding: t; -*- + +;; Run from docs/: emacs -Q --batch --load export.el +;; +;; Every .org page under orgmode/ becomes a .rst page under source/ at the +;; same path; images are copied beside them. A page that fails to export +;; fails the run. +;; +;; ox-rst is GPL-2+ and is not stored in the tree. The pinned upstream +;; commit is fetched into a cache outside it ($STACKHANDS_OX_RST_CACHE, else +;; $XDG_CACHE_HOME/stackhands-docs/ox-rst//), its sha256 checked, and +;; that file loaded. +;; +;; Org 9.7 stores the text of ~code~ and =verbatim= as a deferred value, +;; which ox-rst passes to replace-regexp-in-string; deferred values are +;; resolved on the parse tree before any transcoder runs. +;; +;; Links between pages are written as Org file links and come out as :doc: +;; roles. These link types write the other Sphinx roles: +;; +;; [[zig:zig_common.proc.run]] :zig:obj:`zig_common.proc.run` +;; [[autodoc:zig_common.proc]] :zig:autodoc:`zig_common.proc` +;; [[autodoc:/][Zig autodoc]] the autodoc site's front page +;; [[py:eessi_arch_guard.decide]] :py:obj:`eessi_arch_guard.decide` +;; [[rust:struct:eb_stack::Plan]] :rust:struct:`eb_stack::Plan` +;; [[site:eb-local:howto/index]] :external+eb-local:doc:`howto/index` +;; [[man:bwrap(1)]] :manpage:`bwrap(1)` +;; [[term:EESSI]] :term:`EESSI` +;; +;; A description, [[zig:zig_common.proc.run][run]], becomes the link text. + +(require 'org) +(require 'ox-publish) + +(defconst stackhands-ox-rst-revision + "b73eff187eebac24b457688bfd27f09eff434860") +(defconst stackhands-ox-rst-sha256 + "17ac300861f22e62166785a8ac1b97d32bb8a131ee5ba1b7a9db8977b07e7ede") +(defconst stackhands-ox-rst-url + (concat "https://raw.githubusercontent.com/msnoigrs/ox-rst/" + stackhands-ox-rst-revision + "/ox-rst.el")) + +(defvar stackhands-export-failures nil + "Alist of (file . message) for pages that failed to publish.") + +(defun stackhands-export-fail (format-string &rest args) + "Print FORMAT-STRING with ARGS and exit non-zero." + (apply #'message format-string args) + (kill-emacs 1)) + +(defun stackhands-ox-rst-cache-file () + "Absolute path of the pinned ox-rst source, outside the repository." + (expand-file-name + (concat stackhands-ox-rst-revision "/ox-rst.el") + (or (getenv "STACKHANDS_OX_RST_CACHE") + (expand-file-name + "stackhands-docs/ox-rst" + (or (getenv "XDG_CACHE_HOME") + (expand-file-name ".cache" + (or (getenv "HOME") + temporary-file-directory))))))) + +(defun stackhands-file-sha256 (file) + "Return the sha256 hex digest of FILE." + (with-temp-buffer + (set-buffer-multibyte nil) + (insert-file-contents-literally file) + (secure-hash 'sha256 (current-buffer)))) + +(defun stackhands-fetch-ox-rst (dest) + "Download the pinned ox-rst to DEST, or exit non-zero." + (let ((part (concat dest ".partial"))) + (make-directory (file-name-directory dest) t) + (when (file-exists-p part) + (delete-file part)) + (message "export: fetching ox-rst %s" stackhands-ox-rst-revision) + (let ((status (call-process "curl" nil nil nil + "-fsSL" "--retry" "3" "--retry-delay" "1" + "-o" part stackhands-ox-rst-url))) + (unless (and (eq status 0) (file-readable-p part)) + (when (file-exists-p part) + (delete-file part)) + (stackhands-export-fail "export failed: could not fetch %s (curl exited %s)" + stackhands-ox-rst-url status))) + (let ((got (stackhands-file-sha256 part))) + (unless (string= got stackhands-ox-rst-sha256) + (delete-file part) + (stackhands-export-fail "export failed: ox-rst checksum mismatch (expected %s, got %s)" + stackhands-ox-rst-sha256 got))) + (rename-file part dest t))) + +(let ((dest (stackhands-ox-rst-cache-file))) + (unless (and (file-readable-p dest) + (string= (stackhands-file-sha256 dest) stackhands-ox-rst-sha256)) + (stackhands-fetch-ox-rst dest)) + ;; NOSUFFIX, so a stale ox-rst.elc beside it is never loaded. + (load dest nil nil t)) + +(message "export: Org %s; ox-rst %s" (org-version) stackhands-ox-rst-revision) + +;; Source blocks are shown, never run. +(setq org-export-use-babel nil) +;; x86_64 and EESSI_USER_INSTALL are names, not subscripts; only _{...} and +;; ^{...} are. +(setq org-export-with-sub-superscripts '{}) + +(defun stackhands-resolve-deferred (tree _backend _info) + "Replace deferred properties in TREE with their values." + (when (fboundp 'org-element-properties-resolve) + (org-element-map tree t + (lambda (node) + (unless (stringp node) + (org-element-properties-resolve node t))))) + tree) + +(add-to-list 'org-export-filter-parse-tree-functions #'stackhands-resolve-deferred) + +;; ox-rst writes a link to another Org page as a link to its .rst file, and +;; leaves a link to a generated .md page as it is; Sphinx needs a :doc: role +;; to reach either rendered page. +(defun stackhands-doc-link-filter (text backend _info) + (if (org-export-derived-backend-p backend 'rst) + (replace-regexp-in-string + "`\\([^`]+\\) <\\([^>:]+\\)\\.\\(rst\\|md\\)>`_" + ":doc:`\\1 <\\2>`" + text) + text)) + +(add-to-list 'org-export-filter-link-functions #'stackhands-doc-link-filter) + +(defun stackhands-role (role target desc) + "The Sphinx ROLE for TARGET, with DESC as its text when given." + (if (and desc (not (string-empty-p desc)) (not (string= desc target))) + (format ":%s:`%s <%s>`" role desc target) + (format ":%s:`%s`" role target))) + +(defun stackhands-define-role-link (type role-fn) + "Make Org links of TYPE export to the role ROLE-FN returns for their path." + (org-link-set-parameters + type + :export (lambda (path desc backend &optional _info) + (if (org-export-derived-backend-p backend 'rst) + (let ((role-target (funcall role-fn path))) + (stackhands-role (car role-target) (cdr role-target) desc)) + (or desc path))))) + +(stackhands-define-role-link "zig" (lambda (path) (cons "zig:obj" path))) +(stackhands-define-role-link "autodoc" (lambda (path) (cons "zig:autodoc" path))) +(stackhands-define-role-link "py" (lambda (path) (cons "py:obj" path))) +(stackhands-define-role-link "man" (lambda (path) (cons "manpage" path))) +(stackhands-define-role-link "term" (lambda (path) (cons "term" path))) +;; A heading on another page, by the CUSTOM_ID ox-rst writes as its label. +(stackhands-define-role-link "ref" (lambda (path) (cons "ref" path))) +(stackhands-define-role-link + "rust" (lambda (path) + ;; rust:struct:a::B names the role; rust:anyhow::Error does not. + (if (string-match "\\`\\([a-z]+\\):\\([^:].*\\)\\'" path) + (cons (concat "rust:" (match-string 1 path)) (match-string 2 path)) + (cons "rust:any" path)))) +(stackhands-define-role-link + "site" (lambda (path) + (unless (string-match "\\`\\([^:]+\\):\\(.+\\)\\'" path) + (error "site link needs SITE:PAGE, got %s" path)) + (cons (format "external+%s:doc" (match-string 1 path)) (match-string 2 path)))) + +(setq org-publish-project-alist + '(("sphinx-rst" + :base-directory "./orgmode/" + :base-extension "org" + :publishing-directory "./source/" + :publishing-function org-rst-publish-to-rst + :recursive t + :headline-levels 4 + :with-toc nil + :section-numbers nil) + ("sphinx-images" + :base-directory "./orgmode/" + :base-extension "svg\\|png\\|jpg\\|jpeg\\|webp" + :publishing-directory "./source/" + :publishing-function org-publish-attachment + :recursive t) + ("sphinx" :components ("sphinx-rst" "sphinx-images")))) + +(defun stackhands-publish-file (orig filename &optional project no-cache) + "Call ORIG to publish FILENAME, recording a failure instead of stopping." + (condition-case err + (funcall orig filename project no-cache) + (error + (let ((msg (error-message-string err))) + (message "export failed: %s: %s" filename msg) + (push (cons filename msg) stackhands-export-failures) + nil)))) + +(advice-add 'org-publish-file :around #'stackhands-publish-file) + +;; Every .rst under source/ is an export, so one whose page was renamed or +;; deleted would otherwise stay in the build. +(dolist (stale (directory-files-recursively "./source/" "\\.rst\\'")) + (delete-file stale)) + +(org-publish "sphinx" t) + +(when stackhands-export-failures + (message "export: %d page(s) failed" (length stackhands-export-failures)) + (dolist (fail (nreverse stackhands-export-failures)) + (message "export failed: %s: %s" (car fail) (cdr fail))) + (kill-emacs 1)) diff --git a/docs/howto/configure.md b/docs/howto/configure.md deleted file mode 100644 index d5fcea3..0000000 --- a/docs/howto/configure.md +++ /dev/null @@ -1,137 +0,0 @@ -# Configure the guard - -Slurm execs the TaskProlog with no arguments, so a job cannot pass `--chain` or `--timeout`. A site sets them in a root-owned config file, or in a wrapper that the site owns. `--chain` on the command line is the same hook for that wrapper and for tests. - -## Which file is read - -`/etc/eessi-arch-guard.conf` is read first. A file named `eessi-arch-guard.conf` beside the program is read only when `/etc` has none. The file has to be a regular file, owned by root, and not writable by group or others. Symlinks are ignored. A file that exists and fails those checks is unused, and one warning goes to stderr. - -`docs/examples/check_config.sh` copies the prolog into a temporary directory, writes each config below beside that copy, and deletes the directory on exit. `$WORK` in the transcript is that directory. - -A config owned by the user who runs the prolog is ignored: - -```text -case: user-owned -exit: 0 ---- stdout --- -(empty) ---- stderr --- -eessi-arch-guard: config ignored: $WORK/eessi-arch-guard.conf is not owned by root and is ignored -``` - -A symlink at the config path is ignored even when the target is root-owned and mode `644`: - -```text -case: symlink -exit: 0 ---- stdout --- -(empty) ---- stderr --- -eessi-arch-guard: config ignored: $WORK/eessi-arch-guard.conf is a symlink and is ignored -``` - -A root-owned file with group write (`mode 664`) is ignored: - -```text -case: group-writable -exit: 0 ---- stdout --- -(empty) ---- stderr --- -eessi-arch-guard: config ignored: $WORK/eessi-arch-guard.conf is writable by group or others and is ignored -``` - -## Keys - -``` -# /etc/eessi-arch-guard.conf -chain = /etc/slurm/task_prolog.site -timeout = 60 -``` - -`chain` is an absolute path of an executable. It runs first, as the user, with the task environment. Its stdout is forwarded. Its stderr is forwarded as raw bytes. A non-zero status is returned and this program does not restore modules. Slurm then kills the task, which is what that prolog already did. - -`timeout` is a positive number of seconds, at most `threading.TIMEOUT_MAX`. It bounds the lock wait, both archdetect runs, and the restore helper. The default is 60 seconds, Slurm's `DEFAULT_UNKILLABLE_TIMEOUT` in `src/common/read_config.h`. `--timeout` overrides the config line. The same limit applies with `--shell` and with `--chain`. An unusable value keeps the default and writes a warning. See [the CLI](../reference/cli.md). - -Each setting is decoded on its own. A value that is not UTF-8 is kept with surrogateescape, and the other keys still apply. A non-UTF-8 byte in a comment leaves `chain` and `timeout` in force. - -A root-owned config whose first line is a comment containing the byte `0xff`, with `chain` pointing at a script that prints `export SITE_PROLOG=1` and `timeout = 15`, forwards the chain and stays silent on stderr: - -```text -case: root-owned-chain -comment_has_0xff: yes -exit: 0 ---- stdout --- -export SITE_PROLOG=1 ---- stderr --- -(empty) -``` - -A non-UTF-8 value on another key is kept, and `chain` still runs: - -```text -case: non-utf8-value -exit: 0 ---- stdout --- -export SITE_PROLOG=1 ---- stderr --- -eessi-arch-guard: config value kept with its original bytes: other -``` - -`timeout = 0` is rejected. The chain still runs, because it is started before the timeout value is checked, and the decision then uses 60 seconds: - -```text -case: bad-timeout -exit: 0 ---- stdout --- -export SITE_PROLOG=1 ---- stderr --- -eessi-arch-guard: config timeout is not a positive number of seconds at most 9223372036.0 -``` - -A chain that exits 7 is the prolog status. Stdout stays empty when that script writes only to stderr, and the guard does not continue into module restore: - -```text -case: chain-fails -exit: 7 ---- stdout --- -(empty) ---- stderr --- -fail-prolog -``` - -## Wrapper - -Use a wrapper when the existing prolog has to remain the `TaskProlog` path. In POSIX sh, an `if` whose then-branch is skipped has status 0, so `if site; then exec guard; fi; exit $?` reports success when the site prolog failed. Test the site prolog with `|| exit $?` and exec the guard only after that: - -```sh -#!/bin/sh -/etc/slurm/task_prolog.site || exit $? -exec /usr/bin/python3 -I /usr/local/sbin/eessi-arch-guard -``` - -The example runs that shape against a site script that prints `export FROM_SITE=1`. The guard then runs with no EESSI stack loaded, so it adds no further lines: - -```text -case: wrapper -command: $WORK/wrapper/wrapper.sh -exit: 0 ---- stdout --- -export FROM_SITE=1 ---- stderr --- -(empty) -``` - -When the site script exits 9, the wrapper exits 9 and the guard is not exec'd: - -```text -case: wrapper-site-fails -command: $WORK/wrapper-fails/wrapper.sh -exit: 9 ---- stdout --- -(empty) ---- stderr --- -site-failed -``` - -Which path a site should chain is unanswered here. The [design topic](../topics/design.md) lists it with the other open site questions. diff --git a/docs/howto/hand_builds.md b/docs/howto/hand_builds.md deleted file mode 100644 index 18cbb2d..0000000 --- a/docs/howto/hand_builds.md +++ /dev/null @@ -1,43 +0,0 @@ -# Run a program you built yourself on more than one node type - -The guard reloads modules. It cannot change a program you compiled. A program linked against EESSI libraries records their directories as `DT_RPATH`, and those directories name the CPU target of the node it was linked on. A binary linked on zen4 loads zen4 libraries on every node, and can stop with an illegal instruction on zen2, whatever the guard has fixed in the environment. Build flags such as `-march=native` tie the program's own code to the build node as well. - -So build once per node type and pick the build on the node that runs it. - -## Build into a directory that names the target - -Build inside an allocation on each node type, with EESSI loaded there: - -```bash -salloc -p -n 4 -t 00:30:00 -module load EESSI/2026.06 GSL/2.8-GCC-15.2.0 buildenv/default-foss-2026.1 -p="$HOME/opt/prog/$EESSI_SOFTWARE_SUBDIR" -mkdir -p "$p/bin" -gcc -O2 prog.c -lgsl -lgslcblas -o "$p/bin/prog" -readelf -d "$p/bin/prog" | grep RPATH # directories under .../software/linux// -``` - -The build environment loads last so its compiler wrappers record a run path for every loaded library, and the program runs without `LD_LIBRARY_PATH`. [eb-local](https://github.com/stackhands/eb-local) does the same with `eval "$(eb-local dev GSL/2.8-GCC-15.2.0)"`, exports `EB_LOCAL_DEV_PREFIX` as such a directory, and `eb-local check` reports run paths into another target's tree. - -## Pick the build on the node - -`EESSI_SOFTWARE_SUBDIR` has to expand in the task, after the guard has run on the task's node. In the batch script it holds the batch node's target: - -```bash -srun "$HOME/opt/prog/$EESSI_SOFTWARE_SUBDIR/bin/prog" # wrong: expanded on the batch node -srun bash -c 'exec "$HOME/opt/prog/$EESSI_SOFTWARE_SUBDIR/bin/prog"' # expanded in each task -``` - -The single quotes keep the batch shell from expanding the path. With the guard as the site's `TaskProlog` or as `SLURM_TASK_PROLOG` ([Use the guard without changing the site TaskProlog](user_task_prolog.md)), each task's `EESSI_SOFTWARE_SUBDIR` names its own node, so a job across node types runs the matching build on each. - -Without a task prolog, run the [shell mode](shell_batch.md) in the task: - -```bash -srun bash -c 'eval "$(eessi-arch-guard --shell)" && exec "$HOME/opt/prog/$EESSI_SOFTWARE_SUBDIR/bin/prog"' -``` - -To fail fast on a node type you have not built for: - -```bash -srun bash -c 'p="$HOME/opt/prog/$EESSI_SOFTWARE_SUBDIR/bin/prog"; [ -x "$p" ] || { echo "no build for $EESSI_SOFTWARE_SUBDIR" >&2; exit 1; }; exec "$p"' -``` diff --git a/docs/howto/index.md b/docs/howto/index.md deleted file mode 100644 index c7b5af5..0000000 --- a/docs/howto/index.md +++ /dev/null @@ -1,14 +0,0 @@ -# How-to guides - -Procedures for a user who sees a guard message, and for an admin installing the prolog. - -```{toctree} -:maxdepth: 1 - -read_failure -shell_batch -user_task_prolog -hand_builds -install_prolog -configure -``` diff --git a/docs/howto/install_prolog.md b/docs/howto/install_prolog.md deleted file mode 100644 index c86ee78..0000000 --- a/docs/howto/install_prolog.md +++ /dev/null @@ -1,49 +0,0 @@ -# Install the TaskProlog - -Install the single file on the prolog host and point Slurm at it. The file's shebang is `#!/usr/bin/python3 -I`. Runtime dependencies are Python 3.9 or newer and the standard library. Platform notes are in [Installation](../intro/installation.md). - -From a checkout of this repository: - -```bash -sudo install -m 755 src/eessi_arch_guard.py /usr/local/sbin/eessi-arch-guard -``` - -In `slurm.conf`: - -``` -TaskProlog=/usr/local/sbin/eessi-arch-guard -``` - -`docs/examples/check_install.sh` copies the file to that path, prints the shebang and the version, installs a throwaway virtualenv, and deletes both so the script can be run again. It refuses to replace an existing `/usr/local/sbin/eessi-arch-guard`. On this machine the prolog half of the transcript is: - -```text -+ sudo install -m 755 src/eessi_arch_guard.py /usr/local/sbin/eessi-arch-guard -+ head -n 1 /usr/local/sbin/eessi-arch-guard -#!/usr/bin/python3 -I -+ /usr/local/sbin/eessi-arch-guard --version -0.2.0 -``` - -Leave the file in place on a production host. The script removes it only so the example is repeatable. - -## Login-node console script - -The same script then creates a virtualenv, runs `pip install .`, and checks the generated console script: - -```text -+ python3 -m venv -+ /bin/python -m pip install . -+ /bin/python -c 'import importlib.metadata; print(importlib.metadata.version("eessi-arch-guard"))' -0.2.0 -console: /bin/eessi-arch-guard -console import: from eessi_arch_guard import main -console -I flag: absent -+ /bin/eessi-arch-guard --version -0.2.0 -``` - -The console script is the right binary for [`--shell`](shell_batch.md) on a login node. It is started without `-I`. `TaskProlog` stays on the installed file, whose shebang passes `-I`. - -## After the copy - -Add the `TaskProlog` line, or chain this file from the prolog the site already runs. Both arrangements are in [Configure the guard](configure.md). Slurm reads `TaskProlog` with no arguments, so flags such as `--chain` and `--timeout` come from the config file or from a wrapper the site owns. diff --git a/docs/howto/read_failure.md b/docs/howto/read_failure.md deleted file mode 100644 index 1aa4f85..0000000 --- a/docs/howto/read_failure.md +++ /dev/null @@ -1,181 +0,0 @@ -# Correct a guard message - -On a mismatch the guard exports the reloaded environment and one `print` line, as in the [tutorial](../tutorial/index.md). On a failure it still exits 0. It exports `EESSI_ARCH_GUARD_FAILED` and prints one line. Every other variable stays as the task arrived with it. Slurm would kill the task if this program exited non-zero, so a failure is reported in the environment and the task still starts. - -The token after `->` is the case to correct. The full list is the [failure reference](../reference/failures.md). The examples below run the real guard against the stubs in `tests/`. `$PREFIX` is the temporary prefix. - -## No software directory - -The CPU walk found candidates and none of them has `prefix/software///software`. - -```console -$ python3 docs/examples/failure_cases.py no-software-dir -``` - -```text -case: no-software-dir -command: python3 -I src/eessi_arch_guard.py -exit: 0 ---- stdout --- -export EESSI_ARCH_GUARD_FAILED=x86_64/amd/zen4->no-software-dir -print eessi-arch-guard: no EESSI software directory for this node under $PREFIX/prefix (candidates x86_64/amd/zen2 x86_64/generic); modules were loaded for x86_64/amd/zen4; environment left as it was ---- stderr --- -(empty) -``` - -Mount or install a software tree for one of the candidates in the message. The loaded stack stays in place until that directory exists. - -A node that is expected to have no EESSI tree can set `EESSI_ARCH_GUARD_MISSING=ignore`. The same inputs then produce an empty transcript: - -```console -$ python3 docs/examples/failure_cases.py ignore-missing -case: ignore-missing -command: python3 -I src/eessi_arch_guard.py -exit: 0 ---- stdout --- -(empty) ---- stderr --- -(empty) -``` - -## A module has no build for this target - -The node has a software directory, and one of the loaded modules has no file on the reloaded `MODULEPATH`. The message names each missing module, and stops after 32. A module that appears only once an earlier one is loaded, such as one from the installation tree EESSI-extend adds, is loaded after that module and is not reported. - -```console -$ python3 docs/examples/failure_cases.py missing-module -``` - -```text -case: missing-module -command: python3 -I src/eessi_arch_guard.py -exit: 0 ---- stdout --- -export EESSI_ARCH_GUARD_FAILED=x86_64/amd/zen4->x86_64/amd/zen2 -print eessi-arch-guard: this node is x86_64/amd/zen2, the modules were loaded for x86_64/amd/zen4; not available for this target: R/4.4.2; environment left as it was ---- stderr --- -(empty) -``` - -Here `EESSI_ARCH_GUARD_FAILED` is `loaded-target->node-target`, because a target was selected and the reload then failed. Load a version that exists for the node, or unload the named module before submitting. The same shape is used when the accelerator changes and the module exists only on the old GPU tree; see [Detection and matching](../topics/detection.md). - -## archdetect failed - -`eessi_archdetect.sh` is missing, exits non-zero, prints an empty cpupath, or prints a candidate the guard rejects as unsafe. Accelerator stdout that is non-empty and fails the subdirectory grammar is the same token. - -```console -$ python3 docs/examples/failure_cases.py archdetect -``` - -```text -case: archdetect -command: python3 -I src/eessi_arch_guard.py -exit: 0 ---- stdout --- -export EESSI_ARCH_GUARD_FAILED=x86_64/amd/zen4->archdetect-failed -print eessi-arch-guard: archdetect failed (archdetect forced failure); environment left as it was ---- stderr --- -(empty) -``` - -The parenthetical text is the first line of the script's stderr, or a fixed reason such as `cpupath output is not a single line`. Restore `EESSI_INIT_PREFIX/eessi_archdetect.sh`. `EESSI_PREFIX` and `EESSI_INIT_PREFIX` have to be absolute. `EESSI_OS_TYPE` has to be a relative subdirectory with no empty, `.`, or `..` segment. - -## LMOD_CMD is missing - -The targets differ, and `LMOD_CMD` is missing or not executable. The restore never starts. - -```console -$ python3 docs/examples/failure_cases.py lmod -``` - -```text -case: lmod -command: python3 -I src/eessi_arch_guard.py -exit: 0 ---- stdout --- -export EESSI_ARCH_GUARD_FAILED=x86_64/amd/zen4->lmod-unavailable -print eessi-arch-guard: LMOD_CMD is missing or not executable; this node is x86_64/amd/zen2, the modules were loaded for x86_64/amd/zen4; environment left as it was ---- stderr --- -(empty) -``` - -Point `LMOD_CMD` at the Lmod executable the EESSI module normally exports. - -## The restore could not run - -The targets differ, and the restore stopped before Lmod answered: there is no private directory for its temporary files, or the restore helper did not start or gave no usable reply. The parenthetical text is the cause. - -```console -$ python3 docs/examples/failure_cases.py workspace -``` - -```text -case: workspace -command: python3 -I src/eessi_arch_guard.py -exit: 0 ---- stdout --- -export EESSI_ARCH_GUARD_FAILED=x86_64/amd/zen4->restore-failed -print eessi-arch-guard: restore failed (restore workspace unavailable: EESSI_ARCH_GUARD_WORKDIR is not an existing private owned directory); environment left as it was ---- stderr --- -(empty) -``` - -A set `EESSI_ARCH_GUARD_WORKDIR` has to be an existing directory owned by the job's user, with no group or other permission bits (`chmod 700`). Unset, a private `TMPDIR` is used. Under `--strict`, with neither, the guard needs `$XDG_STATE_HOME/eessi-arch-guard`, by default `~/.local/state/eessi-arch-guard`; create it once with `mkdir -p -m 700 ~/.local/state/eessi-arch-guard`. - -## Turn the guard off - -`EESSI_ARCH_GUARD=0` in the submitting environment skips the decision with no output, including on a mismatch: - -```console -$ python3 docs/examples/failure_cases.py opt-out -case: opt-out -command: python3 -I src/eessi_arch_guard.py -exit: 0 ---- stdout --- -(empty) ---- stderr --- -(empty) -``` - -Put the variable in the environment that Slurm copies. An `EESSI_ARCH_GUARD` value that is already set is the one the task receives: on Slurm 23.11.4, with `EESSI_ARCH_GUARD=1` in the shell, `srun --export=ALL,EESSI_ARCH_GUARD=0` gave the task `1`, and the guard reloaded. - -`EESSI_SOFTWARE_SUBDIR_OVERRIDE` or `EESSI_ARCHDETECT_OPTIONS_OVERRIDE` also skips the whole decision: detection is pinned. `EESSI_ACCELERATOR_TARGET_OVERRIDE` skips only the accelerator comparison. The CPU walk still runs. - -## See why a run was silent - -`EESSI_ARCH_GUARD_VERBOSE=1` sends the skip or match reason to stderr. A matching node prints: - -```console -$ python3 docs/examples/failure_cases.py verbose -case: verbose -command: python3 -I src/eessi_arch_guard.py -exit: 0 ---- stdout --- -(empty) ---- stderr --- -target already matches this node -``` - -Slurm discards a TaskProlog's stderr, so under the prolog the reason never reaches the job. A task whose prolog stayed silent still has the environment the prolog saw; run the guard by hand there: - -```console -$ EESSI_ARCH_GUARD=0 EESSI_ARCH_GUARD_VERBOSE=1 srun -n1 eessi-arch-guard -EESSI_ARCH_GUARD=0 -``` - -## The decision ran out of time - -`--timeout 0` is rejected. The guard warns, keeps the default of 60 seconds, and exits 0: - -```console -$ python3 docs/examples/failure_cases.py bad-timeout -case: bad-timeout -command: python3 -I src/eessi_arch_guard.py --timeout 0 -exit: 0 ---- stdout --- -(empty) ---- stderr --- -eessi-arch-guard: --timeout is not a positive number of seconds at most 9223372036.0 -``` - -A decision that is still running at the deadline sets `EESSI_ARCH_GUARD_FAILED` to a value ending in `->timeout`, kills the process group it is waiting on, and exits 0. That result is not cached. Raise `timeout` in the [config file](configure.md), or pass `--timeout SEC` from a wrapper. `SEC` has to be greater than 0 and at most `threading.TIMEOUT_MAX` (the number in the warning). `SIGTERM` during the decision uses the token `->terminated` and the same kill. diff --git a/docs/howto/shell_batch.md b/docs/howto/shell_batch.md deleted file mode 100644 index 7a576e9..0000000 --- a/docs/howto/shell_batch.md +++ /dev/null @@ -1,59 +0,0 @@ -# Run the guard from a batch script - -Use this when the site has not installed the TaskProlog. For `srun` steps, see [Use the guard without changing the site TaskProlog](user_task_prolog.md). At the top of the batch script: - -```bash -eval "$(eessi-arch-guard --shell)" -``` - -Stdout is `export` and `unset` with values quoted for bash. The human message goes to stderr, so the command substitution captures only the assignments. - -`docs/examples/shell_demo.py` builds the same zen4-loaded, zen2-node stack as the [tutorial](../tutorial/index.md), runs `--shell`, and evals the stdout in `bash --noprofile --norc`. - -```console -$ python3 docs/examples/shell_demo.py -``` - -```text -case: shell -command: python3 -I src/eessi_arch_guard.py --shell -exit: 0 ---- stdout --- -export EBROOTR=$PREFIX/prefix/software/linux/x86_64/amd/zen2/software/R/4.4.2 -export EESSI_ACCEL_SUBDIR='' -export EESSI_ARCH_GUARD_RELOADED='x86_64/amd/zen4->x86_64/amd/zen2' -export EESSI_SOFTWARE_SUBDIR=x86_64/amd/zen2 -export MODULEPATH=$PREFIX/prefix/software/linux/x86_64/amd/zen2/modules/all -export PATH=$PREFIX/prefix/software/linux/x86_64/amd/zen2/software/R/4.4.2/bin:$PREFIX/prefix/software/linux/x86_64/amd/zen2/bin:$PREFIX/bin:/usr/bin:/bin -export _LMFILES_='' -export _ModuleTable001_=table-for-x86_64-amd-zen2 ---- stderr --- -eessi-arch-guard: reloaded modules for x86_64/amd/zen2 (loaded for x86_64/amd/zen4) ---- eval --- -x86_64/amd/zen2 -x86_64/amd/zen4->x86_64/amd/zen2 -``` - -The `eval` block is what the shell sees after applying stdout. `EESSI_SOFTWARE_SUBDIR` is the node, and `EESSI_ARCH_GUARD_RELOADED` records the change. There is no `print` line: that directive belongs to the prolog protocol. - -This eval fixes the shell that runs it. `srun ./a.out` from that shell inherits the corrected environment only when the `srun` is started after the eval and the export reaches the step. A bare exec that never passed through the shell still has the submitting environment. The [TaskProlog install](install_prolog.md) is the path that runs before `execve`. - -## Refuse a failed restore before the payload - -An opt-in job wrapper can use strict status instead of interpreting stderr: - -```bash -if delta="$(/usr/bin/python3 -I /absolute/path/eessi_arch_guard.py --strict --shell)"; then - eval "$delta" -else - exit "$?" -fi -``` - -The source path names the installed guard file. The native Python interpreter starts before any inherited EESSI Python. A nonzero guard status prevents the payload from running. This does not alter the configured site TaskProlog. - -`--strict` also needs a private workspace for the restore: a directory owned by the job's user with no group or other permission bits. The guard takes `EESSI_ARCH_GUARD_WORKDIR` when it is set, then `TMPDIR` when that is private (a per-job directory with mode 700 is; a shared `/tmp` is not), then `$XDG_STATE_HOME/eessi-arch-guard`, by default `~/.local/state/eessi-arch-guard`. It creates none of them. Without one, a node that needs a reload fails the decision and the wrapper exits 78 before the payload. Create the state directory once: - -```bash -mkdir -p -m 700 ~/.local/state/eessi-arch-guard -``` diff --git a/docs/howto/user_task_prolog.md b/docs/howto/user_task_prolog.md deleted file mode 100644 index a916aa3..0000000 --- a/docs/howto/user_task_prolog.md +++ /dev/null @@ -1,51 +0,0 @@ -# Use the guard without changing the site TaskProlog - -Use this when the site runs its own `TaskProlog` and you cannot, or should not, change `slurm.conf`. -Slurm has a second, per-job task prolog for exactly this, and it runs after the site's. - -## For `srun` steps - -`srun --task-prolog=PATH` runs `PATH` just before each task starts, after any `TaskProlog` from `slurm.conf`. -The environment variable `SLURM_TASK_PROLOG` is the same option, so a module or a wrapper can set it once for every `srun` that follows: - -```bash -export SLURM_TASK_PROLOG=/path/to/eessi_arch_guard.py -srun -p ./a.out -``` - -Give the full path from `/`; the file must be executable and readable on the compute node. -The file's own shebang, `#!/usr/bin/python3 -I`, starts it. - -## For the batch script itself - -`sbatch` has no task prolog option, and `SLURM_TASK_PROLOG` covers `srun` steps only. -The commands in a batch script run in the batch step, which gets a site `TaskProlog` from `slurm.conf` but no per-job prolog (checked on Slurm 23.11.4). -At the top of the script, use the [shell mode](shell_batch.md): - -```bash -eval "$(/usr/bin/python3 -I /path/to/eessi_arch_guard.py --shell)" -``` - -`srun` steps started after that line inherit the corrected environment, and with `SLURM_TASK_PROLOG` set they are checked again on their own nodes. - -## What a wrong tree looks like, and the fix - -Measured on a Slurm 26.05.5 cluster with EESSI 2026.06 and `GSL/2.8-GCC-15.2.0` loaded on a zen2 login node, then run on a zen4 node: - -| How the task started | `EESSI_SOFTWARE_SUBDIR` in the task | GSL tree | -|---|---|---| -| `srun` on a zen4 partition, no guard | `x86_64/amd/zen2` | zen2 | -| `srun` on a zen4 partition with `SLURM_TASK_PROLOG` | `x86_64/amd/zen4` | zen4 | -| `sbatch --export=ALL`, batch step, no guard | `x86_64/amd/zen2` | zen2 | -| same batch step after the `--shell` line | `x86_64/amd/zen4` | zen4 | - -The guard's stderr line in the fixed cases was `eessi-arch-guard: reloaded modules for x86_64/amd/zen4 (loaded for x86_64/amd/zen2)`, and `EESSI_ARCH_GUARD_RELOADED` read `x86_64/amd/zen2->x86_64/amd/zen4`. - -A plain `sbatch` without `--export=ALL` does not carry the login environment on that site, so the job loads EESSI on its own node and needs no guard. -The wrong tree comes from `--export=ALL` and from `srun` run in a shell that already loaded EESSI. - -## Limits - -- A job's own `--task-prolog` replaces `SLURM_TASK_PROLOG`: the job runs its own prolog and not the guard. -- The per-job prolog does not run for the batch step; the `--shell` line covers it. -- Once the site installs the [TaskProlog](install_prolog.md), the per-job prolog is redundant: the guard then finds the stack already matches and does nothing. diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 99648e7..0000000 --- a/docs/index.md +++ /dev/null @@ -1,77 +0,0 @@ -# eessi-arch-guard - -```{image} _static/logo-light.svg -:alt: eessi-arch-guard -:width: 420px -:class: light-only -``` - -```{image} _static/logo-dark.svg -:alt: eessi-arch-guard -:width: 420px -:class: dark-only -``` - -eessi-arch-guard is a Slurm TaskProlog that reloads an EESSI module stack when the task runs on a CPU or GPU other than the target recorded at `module load`. The EESSI module chooses that target once. Lmod keeps the recorded `MODULEPATH` and the `EBROOT*` paths until the stack is purged and loaded again. The prolog does that purge and load on the compute node, before `execve`, and prints the environment delta for `slurmstepd` to apply. - -Version {{ version }}. - -## Why - -A job submitted from a login node carries that node's EESSI paths. Slurm delivers the same environment to the allocated node. A binary from the login-node tree then executes on a different microarchitecture: the process can die with `SIGILL`, take a slow generic path, or open a GPU tree that is absent on the node. Running `module load EESSI/` again runs the EESSI module's own detection a second time, but Lmod then marks every other loaded module inactive. - -The prolog is the step that still has the task environment and the executing node's view of the CPU and the GPU. A batch script can purge and reload in the shell. `srun ./a.out` starts the binary directly, so the corrected variables have to be in the environment before `execve`. - -::::{grid} 1 2 2 2 -:gutter: 2 - -:::{grid-item-card} Installation -:link: intro/installation -:link-type: doc - -Python 3.9 or newer on the prolog host, and a virtual environment on a login node. -::: - -:::{grid-item-card} Tutorial -:link: tutorial/index -:link-type: doc - -Reload one stack that was loaded for a different CPU, and read the prolog lines. -::: - -:::{grid-item-card} How-to guides -:link: howto/index -:link-type: doc - -Install the TaskProlog, write its config file, and correct a failed reload. -::: - -:::{grid-item-card} Topics -:link: topics/index -:link-type: doc - -How detection, the waitpkg check, and the reload fit together. -::: - -:::{grid-item-card} Reference -:link: reference/index -:link-type: doc - -CLI, environment variables, config keys, failure tokens, and the Python API. -::: -:::: - -```{toctree} -:hidden: -:maxdepth: 2 -:caption: Documentation - -intro/index -tutorial/index -howto/index -topics/index -reference/index -development -``` - -Copyright (c) eessi-arch-guard developers diff --git a/docs/intro/index.md b/docs/intro/index.md deleted file mode 100644 index 7eca103..0000000 --- a/docs/intro/index.md +++ /dev/null @@ -1,16 +0,0 @@ -# Getting started - -The documentation is split the way the [Diataxis framework](https://diataxis.fr/) describes. - -* The [tutorial](../tutorial/index.md) is one path. It reloads a stack from a checkout, with no Slurm daemon and no EESSI mount. -* The [how-to guides](../howto/index.md) are procedures: install the prolog, configure it, run it from a batch script, and correct a failure. -* The [topics](../topics/index.md) explain detection, matching, and the reload. -* The [reference](../reference/index.md) lists the CLI, the variables, the config keys, the failure tokens, and the generated Python API. - -A new user runs the tutorial. A site admin continues with [installation](installation.md) and the [install](../howto/install_prolog.md) and [config](../howto/configure.md) how-tos. Someone who already sees a `print` line starts at [correct a guard message](../howto/read_failure.md). - -```{toctree} -:maxdepth: 1 - -installation -``` diff --git a/docs/intro/installation.md b/docs/intro/installation.md deleted file mode 100644 index 51dd5f2..0000000 --- a/docs/intro/installation.md +++ /dev/null @@ -1,44 +0,0 @@ -# Installation - -The TaskProlog runs on the compute node. That host is Linux, with Python 3.9 or newer and the standard library. The program is started as `python3 -I`. `requires-python` in `pyproject.toml` is `>=3.9`. - -The test workflow runs the suite on Python 3.9 and 3.12. Its comment records that a Rocky 9 prolog host runs Python 3.9. On Ubuntu and Debian the `python3` package provides the interpreter. This checkout reports: - -```console -$ python3 --version -Python 3.12.3 -``` - -## From a git checkout - -The prolog target is the file `src/eessi_arch_guard.py`. Its first line is `#!/usr/bin/python3 -I`. Copy that file to an absolute path and name it in `slurm.conf`: - -``` -TaskProlog=/usr/local/sbin/eessi-arch-guard -``` - -The steps, the shebang check, and a virtualenv install are in [Install the TaskProlog](../howto/install_prolog.md). `docs/examples/check_install.sh` performs them and then removes the copy so the script can be run again. - -## Login node - -`pip install` of this repository installs a console script named `eessi-arch-guard`. That script imports `eessi_arch_guard.main` and is started without `-I`. Use it for `eessi-arch-guard --shell` on a login node. Point `TaskProlog` at the file itself. - -```console -$ python3 -m venv .venv -$ .venv/bin/python -m pip install . -$ .venv/bin/eessi-arch-guard --version -0.2.0 -``` - -`docs/examples/check_install.sh` runs that sequence with the virtualenv under `/tmp`. The script's transcript on this machine ends with: - -```text -console import: from eessi_arch_guard import main -console -I flag: absent -+ /bin/eessi-arch-guard --version -0.2.0 -``` - -## What the host has to provide - -`PATH` must contain `python3` and `bash`. The loaded EESSI environment supplies `EESSI_INIT_PREFIX/eessi_archdetect.sh` and `LMOD_CMD`. The guard reads CPU flags from `EESSI_PROC_CPUINFO` when that variable is set, and from `/proc/cpuinfo` otherwise. Accelerator detection is whatever `eessi_archdetect.sh accelpath` prints; the EESSI script uses `nvidia-smi` for NVIDIA GPUs. diff --git a/docs/orgmode/changelog.org b/docs/orgmode/changelog.org new file mode 100644 index 0000000..157f055 --- /dev/null +++ b/docs/orgmode/changelog.org @@ -0,0 +1,10 @@ +#+TITLE: Changelog +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil + +# CHANGELOG.md at the top of the repository is the one changelog; this page +# shows it. + +#+begin_export rst +.. include:: ../../CHANGELOG.md + :parser: myst_parser.sphinx_ +#+end_export diff --git a/docs/orgmode/contributing.org b/docs/orgmode/contributing.org new file mode 100644 index 0000000..3d892e3 --- /dev/null +++ b/docs/orgmode/contributing.org @@ -0,0 +1,79 @@ +#+TITLE: Contributing +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Contributing + +Changes come as pull requests to [[https://github.com/stackhands/eessi-arch-guard][stackhands/eessi-arch-guard]]. +A change to behaviour changes the page that describes it in the same pull request. + +** Record the change + +Every change adds a news fragment, =changelog.d/+SLUG.TYPE.md=, with a short slug for the change and one of the types the =[tool.towncrier]= table of =pyproject.toml= configures: + +| Type | Section of the release notes | +|-----------+------------------------------| +| =feature= | Features | +| =bugfix= | Bugfixes | +| =doc= | Docs | + +A fragment is one paragraph in the present tense that names the commands, options and files it is about in backticks, as the entries in the [[file:changelog.org][changelog]] do. +With [[https://towncrier.readthedocs.io][towncrier]] installed, =towncrier build --draft --version 0.2.1= shows the release notes the fragments make. +The release commit gathers them into =CHANGELOG.md=; [[https://github.com/stackhands/eessi-arch-guard/blob/main/RELEASING.md][RELEASING.md]] has the rest of a release. + +** Run the tests + +With Python 3.9 or newer, from the top of the repository: + +#+begin_src bash +python3 -m unittest discover -s tests +#+end_src + +This runs the suite against the Python guard, =src/eessi_arch_guard.py=. +With Zig 0.17.1, =zig build test= runs the unit tests of the Zig build, and =zig build suite= builds the binary and runs the same suite against it. +A deliberate difference between the two builds has its row in =COMPAT.md=, which [[file:reference/compatibility.org][Compatibility]] shows. +CI also runs =ruff check src tests= and =zig fmt --check build.zig build.zig.zon zig=. + +** Build the documentation + +The documentation toolchain is pinned in =pixi.lock=: Emacs, Sphinx, lychee, and the tools that read the code. +With [[https://pixi.sh][pixi]] installed, from the top of the repository: + +#+begin_src bash +pixi run -e docs docbld +#+end_src + +The site is in =docs/build/html/=; open =docs/build/html/index.html=. +The build fails on any Sphinx warning, any cross-reference that does not resolve, any internal link or anchor that does not exist, and, outside the changelog, any name of a real site's machines or paths. +The first build needs the network, to fetch the other stackhands sites' inventories; later builds reuse them for 30 days. + +External links are checked separately, as they need the network: + +#+begin_src bash +pixi run -e docs linkcheck +#+end_src + +=pixi run -e docs docdel= removes everything the build generated. + +** Where things are + +| Path | What it holds | +|----------------------------+----------------------------------------------------| +| =docs/orgmode/= | the pages, in Org: edit these | +| =docs/export.el= | the Org to reStructuredText export | +| =docs/source/conf.py= | the Sphinx configuration | +| =docs/source/_ext/= | the Sphinx domain for Zig declarations | +| =docs/tools/zig_api.zig= | writes the Zig API pages from the doc comments | +| =docs/tools/check_site.py= | checks internal links, anchors and forbidden names | + +The =.rst= files under =docs/source/= and everything under =docs/source/reference/api/= are generated and not committed. + +** Write a page + +A page belongs to exactly one quadrant: a tutorial teaches by doing, a how-to guide gets one task done, an explanation says why, and a reference page lists what there is. +Start from the skeleton for its quadrant in =docs-kit/skeletons/= of [[https://github.com/stackhands/.github][stackhands/.github]], add it to the =toctree= of the quadrant's =index.org=, and follow =docs-kit/STYLE.md= there. +Examples use the neutral example site (=example.org=, =/opt/site=, =/home/alice=), never a real one. + +API documentation is written in the code, and the first sentence of each comment is the summary shown in lists. +In Zig it is a =///= comment above each =pub= declaration and a =//!= comment at the top of each file. +In Python it is the docstring of each public module, class and function. diff --git a/docs/orgmode/explanation/design.org b/docs/orgmode/explanation/design.org new file mode 100644 index 0000000..162ada8 --- /dev/null +++ b/docs/orgmode/explanation/design.org @@ -0,0 +1,106 @@ +#+TITLE: Why a task prolog runs the reload +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Why a task prolog runs the reload + +Why does eessi-arch-guard reload the modules of the European Environment for Scientific Software Installations (EESSI) in a Slurm =TaskProlog=, through a helper process, and why does a reload that fails still let the task start? + +** The problem + +A task's program is chosen before any code of the user's runs. +A batch script can purge and load its modules again, but only for its own shell, and =srun ./a.out= starts the program with no shell at all. +The one place that runs on the compute node, as the job's user, with the task's environment, before the program starts, and for the batch step as well, is the =TaskProlog=. +Nothing earlier in the job knows both the node's CPU and the GPUs the task's cgroup lets it see. + +A =TaskProlog= talks to Slurm through text on its stdout, which =slurmstepd= reads line by line: + +- =export NAME=value= sets a variable to the text after the equals sign as it is: =$= and backticks mean nothing there, and a newline starts the next line, so a value holding a newline can add a directive of its own; +- =unset NAME= removes a variable, and =print TEXT= writes a line to the task's output; +- a status other than 0 ends the task, after Slurm has applied the lines read so far. + +The first version of the guard ran the reload in a shell and printed that shell's whole environment as =export= lines. +That shape is where the bugs reviewed in it came from: + +- =bash --noprofile --norc= still runs the file =BASH_ENV= names before its command, as bash 5.2.21 does, and adds that file's output to its own; +- a module name with a newline in it, passed on unquoted, became a second directive; +- a node without a software directory gave an empty result, and the job kept the binaries of the other node without a word; +- a value with a newline was left out while the others were exported, so =MODULEPATH= could move and =_ModuleTable*= or =PS1= stay behind; +- an error while printing could exit with a status other than 0, which ends the task; +- the cache file took the process's umask, and its lock file was opened through a symbolic link. + +** How eessi-arch-guard handles it + +The guard keeps the =TaskProlog= and changes what runs in it. + +*** What Slurm does with the prolog + +These were read in =src/slurmd/slurmstepd/task.c= on Slurm's =master= branch, and seen with Slurm 23.11.4 started by hand in one virtual machine, where the prolog ran for an =srun= step and for a batch step: + +- =exec_task= starts the =TaskProlog= for the batch step too; its checks of =!step->batch= concern the switch plugin and MPI. +- The prolog runs with =SLURM_SCRIPT_CONTEXT=prolog_task=. +- A status other than 0 is acted on after the output is parsed: the exports of a failing prolog are applied, and the task is ended all the same. +- =_make_tmpdir= runs after the prologs, and for local task 0 only, so a per-job =TMPDIR= may not exist yet when the guard runs. + The guard never exports =TMPDIR=, which would change the directory Slurm creates, and keeps its cache in =/tmp= when =TMPDIR= does not exist yet. + +*** A helper does the reload + +The reload runs in a second process: the same file, started again by the same Python with =-I -X utf8 FILE --restore=, or the Zig binary started again with =--restore=. +Its environment holds only =PATH=/usr/bin:/bin=, =LANG=C=, =LC_ALL=C=, and =HOME=, =TMPDIR= and =EESSI_ARCH_GUARD_WORKDIR=, which name a new private directory. +The task's environment reaches it as data on stdin, each byte as one Latin-1 character, and =-X utf8= turns that text back into the same bytes for Lmod, so a path that is not UTF-8 stays the path Lmod opens. +The module names go to =LMOD_CMD= as arguments, after they pass the check in [[file:../reference/environment.org][Environment variables]], never as text in a shell command. +Its shell is =bash --noprofile --norc=, started without =BASH_ENV=, =ENV=, =SHELLOPTS=, =BASHOPTS=, =BASH_XTRACEFD= and =PS4=, and it reports the environment it ends with as =env -0=, never as text the prolog prints. +[[py:eessi_arch_guard.call_restore]] starts the helper, and [[py:eessi_arch_guard.restore_main]] is the helper. + +*** The prolog prints the difference + +The guard compares the environment the helper ends with to the task's, and prints only the names whose values changed, apart from the names it never touches. +Every value has to fit a prolog line; one that does not fails the whole reload, so the task never gets half of the new environment. +[[file:output-modes.org][Prolog lines and shell lines]] describes those rules, and [[py:eessi_arch_guard.environment_delta]] computes the difference. + +*** A failure is loud, and the task still starts + +A reload that cannot be made sets =EESSI_ARCH_GUARD_FAILED=, prints one line that says why, and exits 0. +A status other than 0 would end the task, and a job that would have run on the wrong tree runs, with the failure visible in its output and its environment. +=--strict= is for a wrapper of the user's that wants a status: with it, a failed decision exits 78. +Slurm starts a =TaskProlog= without arguments, so as the site's prolog the guard always exits 0 after a failed reload. + +The site's own prolog, when it has one, runs before the guard. +Slurm gives a =TaskProlog= no arguments and the job controls the environment, so the guard takes that prolog only from a file owned by root, or from a wrapper the site writes, as in [[file:../howto/configure.org][Configure the guard]]. + +** What was considered and turned down + +- /Printing the reload shell's whole environment./ + That was the first version, and each bug above came from it. + A helper whose output is data, and a list of names to leave alone, rule out those kinds of bug; mending each one inside a loop that prints a shell's output leaves the next parser bug on the same path. +- /Setting a flag and letting the job reload./ + A flag does nothing for a program =srun= starts without a shell. + =--shell= stays for a user whose site has not installed the prolog, with the same gap as any shell wrapper. +- /Printing only the paths./ + Modules set =EBROOT*=, =EBVERSION*= and names of their own, so rewriting the paths the guard knows of leaves part of the environment on the other node's tree. +- /A link per node in the CernVM File System (CVMFS) that points at the node's tree./ + Module roots and the run paths in binaries name the target in full, as =init/modules/EESSI/2023.06.lua= at software-layer-scripts =26441ca= shows, so the task would still open the other node's files. +- /Checking again inside the module file of EESSI./ + The module file runs when a =module= command loads it, and nothing loads it in a task before the program starts. +- /An Lmod hook./ + A hook runs for =module= commands, which a program started directly never calls, and it would run on every load for a check needed once per task. +- /A file that bash reads at startup./ + =BASH_ENV= misses a program =srun= starts without bash, runs for every bash, and is already Lmod's; the guard removes it from the helper and does not use it. +- /Not exporting the environment into jobs at all./ + =--export=NONE= as the site's default takes away the environment that job scripts are written against. + It stays as advice for a single command. +- /A SPANK plugin, or other code inside Slurm./ + The guard is one file a site can run from the =TaskProlog= it already has. + +** Limits + +- The behaviour of Slurm above was read in the public source and seen with Slurm 23.11.4; a site's own version may differ. +- The cost on a node that runs a task on every core with a node-local =TMPDIR= is not measured; =python3 tests/measure_noop.py= prints the time of a run that changes nothing on the machine where it runs. +- =--shell= changes only the shell that evaluates it, and the programs that shell starts afterwards. +- After a failed reload the task runs with the environment it was submitted with, unless a wrapper uses =--strict=. + +** Further reading + +- [[file:how-it-decides.org][How the guard decides]], for the detection and the comparison. +- [[file:output-modes.org][Prolog lines and shell lines]], for what the guard prints and how a step shares one decision. +- [[https://github.com/stackhands/eessi-arch-guard/blob/main/DESIGN.md][DESIGN.md]], the maintainers' record of the design. diff --git a/docs/orgmode/explanation/figures/reload.dot b/docs/orgmode/explanation/figures/reload.dot new file mode 100644 index 0000000..468b8a7 --- /dev/null +++ b/docs/orgmode/explanation/figures/reload.dot @@ -0,0 +1,25 @@ +// From module load on the login node to the task's first instruction. +digraph reload { + graph [bgcolor="white", rankdir=TB, nodesep=0.5, ranksep=0.4, fontname="Helvetica"]; + node [shape=box, style="rounded,filled", fillcolor="#f4f4f4", color="#555555", fontname="Helvetica", fontsize=11]; + edge [color="#555555", fontname="Helvetica", fontsize=10]; + + load [label="login1: module load EESSI/2026.06 Example/1.0-GCCcore-15.2.0\nEESSI's detection runs once and picks x86_64/amd/zen4.\nEESSI_SOFTWARE_SUBDIR, MODULEPATH and EBROOTEXAMPLE\nnow name the zen4 tree."]; + submit [label="sbatch: Slurm copies that environment into the job"]; + prolog [label="An older node, before the task's program starts:\nslurmstepd runs the TaskProlog, eessi-arch-guard,\nas the user, with the task's environment"]; + compare [shape=diamond, label="Is this node's target\nthe one recorded at load?", fillcolor="#ffffff"]; + same [label="Same target:\nprints nothing"]; + helper [label="Another target: a helper runs, with Lmod,\nmodule --force purge\nmodule load EESSI/2026.06\nmodule load Example/1.0-GCCcore-15.2.0"]; + delta [label="The prolog prints the difference\nas export and unset lines, and a print line"]; + failed [label="The reload could not be made safely:\nEESSI_ARCH_GUARD_FAILED and a print line;\nevery other variable stays as it was"]; + start [label="slurmstepd applies the lines, then starts the program"]; + + load -> submit -> prolog -> compare; + compare -> same [label=" yes"]; + compare -> helper [label=" no"]; + helper -> delta [label=" it loaded"]; + helper -> failed [label=" it did not"]; + same -> start; + delta -> start; + failed -> start [label=" exit 0; 78 with --strict"]; +} diff --git a/docs/orgmode/explanation/figures/reload.svg b/docs/orgmode/explanation/figures/reload.svg new file mode 100644 index 0000000..3be446d --- /dev/null +++ b/docs/orgmode/explanation/figures/reload.svg @@ -0,0 +1,145 @@ + + + + + + +reload + + + +load + +login1: module load EESSI/2026.06 Example/1.0-GCCcore-15.2.0 +EESSI's detection runs once and picks x86_64/amd/zen4. +EESSI_SOFTWARE_SUBDIR, MODULEPATH and EBROOTEXAMPLE +now name the zen4 tree. + + + +submit + +sbatch: Slurm copies that environment into the job + + + +load->submit + + + + + +prolog + +An older node, before the task's program starts: +slurmstepd runs the TaskProlog, eessi-arch-guard, +as the user, with the task's environment + + + +submit->prolog + + + + + +compare + +Is this node's target +the one recorded at load? + + + +prolog->compare + + + + + +same + +Same target: +prints nothing + + + +compare->same + + + yes + + + +helper + +Another target: a helper runs, with Lmod, +module --force purge +module load EESSI/2026.06 +module load Example/1.0-GCCcore-15.2.0 + + + +compare->helper + + + no + + + +start + +slurmstepd applies the lines, then starts the program + + + +same->start + + + + + +delta + +The prolog prints the difference +as export and unset lines, and a print line + + + +helper->delta + + + it loaded + + + +failed + +The reload could not be made safely: +EESSI_ARCH_GUARD_FAILED and a print line; +every other variable stays as it was + + + +helper->failed + + + it did not + + + +delta->start + + + + + +failed->start + + + exit 0; 78 with --strict + + + diff --git a/docs/orgmode/explanation/figures/render.sh b/docs/orgmode/explanation/figures/render.sh new file mode 100644 index 0000000..18a145a --- /dev/null +++ b/docs/orgmode/explanation/figures/render.sh @@ -0,0 +1,9 @@ +#!/bin/bash +# Render each Graphviz drawing here to the SVG committed beside it. The docs +# build never runs Graphviz; run this by hand after changing a .dot file: +# pixi exec --spec graphviz bash docs/orgmode/explanation/figures/render.sh +set -euo pipefail +cd "$(dirname -- "$0")" +for dot in *.dot; do + dot -Tsvg "$dot" -o "${dot%.dot}.svg" +done diff --git a/docs/orgmode/explanation/figures/targets.dot b/docs/orgmode/explanation/figures/targets.dot new file mode 100644 index 0000000..112a466 --- /dev/null +++ b/docs/orgmode/explanation/figures/targets.dot @@ -0,0 +1,28 @@ +// How the guard finds this node's CPU and accelerator targets. +digraph targets { + graph [bgcolor="white", rankdir=TB, nodesep=0.6, ranksep=0.35, fontname="Helvetica", compound=true]; + node [shape=box, style="rounded,filled", fillcolor="#f4f4f4", color="#555555", fontname="Helvetica", fontsize=11]; + edge [color="#555555", fontname="Helvetica", fontsize=10]; + + subgraph cluster_cpu { + label="CPU"; fontsize=12; color="#999999"; style="rounded"; + cpupath [label="eessi_archdetect.sh -a cpupath\non the processors the task may use:\none line of candidates, best first"]; + waitpkg [label="Drop a candidate whose -march needs waitpkg\nwhen a kept processor lacks the flag"]; + walk [label="Keep the first candidate that has\n$EESSI_PREFIX/software/$EESSI_OS_TYPE//software"]; + cpu_cmp [label="Compare with EESSI_SOFTWARE_SUBDIR"]; + cpupath -> waitpkg -> walk -> cpu_cmp; + } + + subgraph cluster_accel { + label="Accelerator"; fontsize=12; color="#999999"; style="rounded"; + accelpath [label="eessi_archdetect.sh accelpath,\nwhich sees the GPUs visible to the task"]; + none [label="A nonzero status or empty output\nmeans no accelerator, the empty string"]; + shape_ok [label="Any other output must be one line,\naccel/nvidia/ccN or accel/amd/gfxN"]; + acc_cmp [label="Compare with EESSI_ACCEL_SUBDIR"]; + accelpath -> none -> shape_ok -> acc_cmp; + } + + match [label="Both equal: a match", fillcolor="#ffffff"]; + cpu_cmp -> match; + acc_cmp -> match; +} diff --git a/docs/orgmode/explanation/figures/targets.svg b/docs/orgmode/explanation/figures/targets.svg new file mode 100644 index 0000000..8fbc6a8 --- /dev/null +++ b/docs/orgmode/explanation/figures/targets.svg @@ -0,0 +1,132 @@ + + + + + + +targets + + +cluster_cpu + +CPU + + +cluster_accel + +Accelerator + + + +cpupath + +eessi_archdetect.sh -a cpupath +on the processors the task may use: +one line of candidates, best first + + + +waitpkg + +Drop a candidate whose -march needs waitpkg +when a kept processor lacks the flag + + + +cpupath->waitpkg + + + + + +walk + +Keep the first candidate that has +$EESSI_PREFIX/software/$EESSI_OS_TYPE/<candidate>/software + + + +waitpkg->walk + + + + + +cpu_cmp + +Compare with EESSI_SOFTWARE_SUBDIR + + + +walk->cpu_cmp + + + + + +match + +Both equal: a match + + + +cpu_cmp->match + + + + + +accelpath + +eessi_archdetect.sh accelpath, +which sees the GPUs visible to the task + + + +none + +A nonzero status or empty output +means no accelerator, the empty string + + + +accelpath->none + + + + + +shape_ok + +Any other output must be one line, +accel/nvidia/ccN or accel/amd/gfxN + + + +none->shape_ok + + + + + +acc_cmp + +Compare with EESSI_ACCEL_SUBDIR + + + +shape_ok->acc_cmp + + + + + +acc_cmp->match + + + + + diff --git a/docs/orgmode/explanation/how-it-decides.org b/docs/orgmode/explanation/how-it-decides.org new file mode 100644 index 0000000..16a6667 --- /dev/null +++ b/docs/orgmode/explanation/how-it-decides.org @@ -0,0 +1,108 @@ +#+TITLE: How the guard decides +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* How the guard decides + +How does eessi-arch-guard tell that a task runs on a node its modules were not loaded for, and what does it change then? + +** The problem + +The module of the European Environment for Scientific Software Installations (EESSI) picks a CPU target once, when it is loaded, and an accelerator target the same way. +On =login1=, a zen4 machine, =module load EESSI/2026.06 Example/1.0-GCCcore-15.2.0= sets =EESSI_SOFTWARE_SUBDIR= to =x86_64/amd/zen4=, puts the zen4 module tree on =MODULEPATH=, and lets the =Example= module point =EBROOTEXAMPLE= and =PATH= into the zen4 software tree. +Slurm copies that environment into every job submitted from there. +A task that lands on a zen2 node then runs the zen4 build: it can stop with an illegal instruction, take a slower generic path, or look for a GPU tree the node does not have. + +Loading the =EESSI= module again inside the job runs its detection again and moves =MODULEPATH= to the zen2 tree, but Lmod then marks every other loaded module inactive, as seen with Lmod 9.4.5. +=module reload=, an unload and load, and =module swap= leave them inactive too. +The sequence that changes the whole stack is: list the loaded modules, =module --force purge=, =module load EESSI/2026.06= by its full name, then load the others in the same order. +A batch script could run that sequence, but =srun ./a.out= starts no shell to run it in. + +** How eessi-arch-guard handles it + +eessi-arch-guard runs that sequence in the one place every task passes through before its program starts: the Slurm =TaskProlog=. +=slurmstepd= runs it on the compute node, as the job's user, with the task's environment, for the batch step as for every other step. +What the prolog prints on stdout, Slurm applies to the task's environment: an =export NAME=value= line sets a variable, =unset NAME= removes one, and =print TEXT= writes a line to the task's output. + +#+CAPTION: From module load on the login node to the task's first instruction. +#+ATTR_RST: :alt module load on login1 records the zen4 target; Slurm copies the environment into the job; on an older node slurmstepd runs eessi-arch-guard before the program; if the node's target is the recorded one it prints nothing; otherwise a helper purges and loads the same modules with Lmod, and the prolog prints the difference, or, when the reload cannot be made, a failure marker and a message; slurmstepd applies the lines and starts the program +[[file:figures/reload.svg]] + +The /loaded target/ is what the EESSI module recorded: =EESSI_SOFTWARE_SUBDIR= for the CPU and =EESSI_ACCEL_SUBDIR= for the accelerator, which is empty when there is none. +This node's target is what EESSI's own detection script, =eessi_archdetect.sh= from the loaded version, says about the processors and GPUs the task can use. +The guard names no target itself, so it follows the trees a site has and the detection EESSI ships. + +#+CAPTION: How the guard finds this node's CPU and accelerator targets. +#+ATTR_RST: :alt CPU: cpupath on the task's processors gives candidates; a candidate whose march needs waitpkg is dropped when the flag is missing; the first candidate with a software directory is kept and compared with EESSI_SOFTWARE_SUBDIR. Accelerator: accelpath; a nonzero status or empty output means none; other output must be one accel subdirectory, compared with EESSI_ACCEL_SUBDIR. Both equal is a match +[[file:figures/targets.svg]] + +*** This node's CPU + +=eessi_archdetect.sh -a cpupath= prints one line of candidate subdirectories, best first, separated by colons, such as =x86_64/amd/zen4:x86_64/amd/zen3:x86_64/amd/zen2:x86_64/generic=. +The script reads =/proc/cpuinfo=, or the file =EESSI_PROC_CPUINFO= names, and judges by the last processor listed there. +A cgroup cpuset, the affinity mask or a Slurm CPU binding can keep a task off that processor, so the guard first works out which processors the task may run on: the intersection of its affinity mask, the =cpuset.cpus.effective= of its cgroup, and =SLURM_CPU_BIND_LIST= or =SLURM_CPU_BIND=. +When that leaves fewer processors than the file lists, or processors that differ, the script is given one processor record whose flags are the ones every kept processor has. + +The guard then drops a candidate whose compiler target needs a flag that a kept processor lacks. +It checks one flag, =waitpkg=: EESSI's detection does not ask for it, but GCC's =-march= for =sapphirerapids= and twelve other Intel targets uses it, so a virtual machine that hides the flag is offered binaries that stop with an illegal instruction. + +Of the candidates left, the first that has a software directory, =$EESSI_PREFIX/software/$EESSI_OS_TYPE//software=, is this node's CPU target. +When the waitpkg rule removed the candidate that the EESSI module's own walk would choose, the reload pins the module to the guard's choice with =EESSI_SOFTWARE_SUBDIR_OVERRIDE=. +[[file:../reference/cpu-flags.org][CPU flags]] lists the targets the rule covers. +[[py:eessi_arch_guard.probe_cpu]] and [[zig:eessi-arch-guard.guard.probeCpu]] make this choice in the two builds. + +*** This node's accelerator + +=eessi_archdetect.sh accelpath= prints the accelerator subdirectory for the GPUs the task can see, such as =accel/nvidia/cc90= on =gpu003=. +A nonzero exit status or empty output means no accelerator, which the EESSI module records as an empty =EESSI_ACCEL_SUBDIR=. +The guard compares the string as it is printed. +The fallback from a compute capability such as =cc86= to the directory of its major version, =cc80=, stays in the EESSI module, which runs it during the reload. +[[py:eessi_arch_guard.probe_accel]] and [[zig:eessi-arch-guard.guard.probeAccel]] run the detection. + +*** Match, reload or failure + +The node matches when its CPU target is =EESSI_SOFTWARE_SUBDIR= and its accelerator is =EESSI_ACCEL_SUBDIR=; the guard then prints nothing. +It also prints nothing when EESSI is not loaded, when =EESSI_ARCH_GUARD=0= turns it off, and when the user pinned the detection with =EESSI_SOFTWARE_SUBDIR_OVERRIDE= or =EESSI_ARCHDETECT_OPTIONS_OVERRIDE=. +=EESSI_ACCELERATOR_TARGET_OVERRIDE= leaves the accelerator out of the comparison. + +Otherwise a helper process runs the sequence above with the =LMOD_CMD= of the task's environment: =module --force purge=, a load of the =EESSI= module by its full name, then one load of the other modules in the order =LOADEDMODULES= lists them. +When that last load fails, the helper loads them again one call each, so that a module from a tree that an earlier module adds still loads, and the message names every module that has no build for this node. +The prolog prints the difference between the task's environment and the one the helper ends with, and sets =EESSI_ARCH_GUARD_RELOADED=. + +A reload that cannot be made, or made safely, changes nothing but =EESSI_ARCH_GUARD_FAILED=, and the =print= line says why. +The prolog exits 0 in that case too, because Slurm kills a task whose =TaskProlog= exits nonzero: a job that would have run on the wrong tree still runs. +With =--strict=, a failed decision exits 78 instead. +[[py:eessi_arch_guard.decide]] and [[zig:eessi-arch-guard.guard.decide]] make the whole decision. + +** What was considered and turned down + +- /Naming targets in the guard./ + An Intel node with NVIDIA A100 GPUs could be =x86_64/intel/icelake= or =x86_64/intel/skylake_avx512=, and a name baked into the program would be wrong on the other kind of node and on every AMD node. + The guard takes the first candidate the detection offers that the site has installed. +- /Loading only the EESSI module again./ + It moves =MODULEPATH= and leaves every other module inactive. +- /Editing the module path and the list of loaded modules in place./ + The modules set paths of their own, such as =EBROOTEXAMPLE=, and only running the modulefiles again sets them for the new tree. +- /Letting the detection script judge the whole machine./ + =eessi_archdetect.sh= would describe the last processor in =/proc/cpuinfo=, which the task may never run on. +- /Doing the accelerator fallback in the guard./ + The module already does it when it is loaded, from the string the detection printed. +- /A job prolog, which Slurm runs as root once per job./ + It does not run in the task's environment, and it sees GPUs that the task's cgroup hides. + +** Limits + +- The guard follows =eessi_archdetect.sh=: a wrong answer from the script is a wrong target for the guard too. +- Of the flags a target's =-march= uses beyond the ones the detection checks, only =waitpkg= is checked. +- A module with no build for the node's target stops the reload, and the task runs with the environment it was submitted with. +- Programs built with =-march=native= on a login node, and virtual environments with compiled wheels, are outside the module tree, and the guard does not change them. +- To turn the guard off, =EESSI_ARCH_GUARD=0= has to be in the environment the job is submitted with. + On Slurm 23.11.4, =srun --export=ALL,EESSI_ARCH_GUARD=0= gave a task =1= when =EESSI_ARCH_GUARD=1= was already set. + +** Further reading + +- [[file:../tutorials/first-guarded-job.org][See the guard reload EESSI for another CPU]] shows a reload and a failure. +- [[file:design.org][Why a task prolog runs the reload]] covers the prolog, the helper and the failure policy. +- [[file:output-modes.org][Prolog lines and shell lines]] covers what the guard prints, and how the tasks of a step share one decision. +- [[file:../reference/compatibility.org][Compatibility]] lists every input and output of the decision, as the Zig build keeps them. +- [[https://github.com/stackhands/eessi-arch-guard/blob/main/DESIGN.md][DESIGN.md]] is the maintainers' record of the design and of what was rejected. diff --git a/docs/orgmode/explanation/index.org b/docs/orgmode/explanation/index.org new file mode 100644 index 0000000..3eab401 --- /dev/null +++ b/docs/orgmode/explanation/index.org @@ -0,0 +1,17 @@ +#+TITLE: Explanation +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Explanation + +These pages say why eessi-arch-guard works the way it does: the model behind it, the choices made and the ones turned down. +Nothing here is a step to follow. + +#+begin_export rst +.. toctree:: + :maxdepth: 1 + + how-it-decides + design + output-modes +#+end_export diff --git a/docs/orgmode/explanation/output-modes.org b/docs/orgmode/explanation/output-modes.org new file mode 100644 index 0000000..386abe6 --- /dev/null +++ b/docs/orgmode/explanation/output-modes.org @@ -0,0 +1,100 @@ +#+TITLE: Prolog lines and shell lines +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Prolog lines and shell lines + +Why does eessi-arch-guard print Slurm's prolog lines by default and shell commands with =--shell=, and why do the tasks of a job step on one node share a single decision? + +** The problem + +The guard hands a reload to two readers. +As a =TaskProlog=, its stdout goes to =slurmstepd=, which applies =export NAME=value=, =unset NAME= and =print TEXT= lines and knows no quoting: the value runs to the end of the line, and a newline starts the next directive. +Slurm 17.11 reads each line with =fgets(buf, sizeof(buf) - 1)= into =char buf[4096]=, so a longer line is split, and its rest is read as a line of its own. +=print= writes to the task's output, and Slurm has no directive for stderr. +In a batch script, the reader is =bash=, through =eval=, which needs quoting and does not want the message in the text it evaluates. + +A step with many tasks on one node runs the prolog once per task. +Each run would start =eessi_archdetect.sh= for the CPU and for the accelerator and, on a mismatch, a reload through Lmod, and tasks that decided apart could end up with different environments. + +** How eessi-arch-guard handles it + +The decision is the same in both modes, and only the lines that carry it differ. +[[py:eessi_arch_guard.decide]] makes the decision, and [[py:eessi_arch_guard.cached_decide]] shares it. + +*** Prolog lines + +Each line on stdout is =export NAME=value=, =unset NAME= or =print TEXT=, and the names match =^[A-Za-z_][A-Za-z0-9_]*$=. +A value may not hold a carriage return, a newline or a NUL byte, and no line, its newline included, may pass 4094 bytes. +A changed value that breaks either rule fails the whole reload with =unsafe-environment=, and the task keeps the environment it arrived with, because half of a reload is a stack that is neither the old one nor the new one. +New values of =PS1=, =PS2=, =PS3= and =PROMPT_COMMAND= are the exception: such a value is left out, and the rest of the reload is applied. + +The message is one =print= line, at most 500 characters, with control characters turned into spaces. +Only the task whose =SLURM_LOCALID= is =0=, or unset, prints it, so a step with many tasks on a node shows it once; the other tasks get the same =export= and =unset= lines without it. +A batch script that reads its own stdout sees that line too. +A line that cannot be written is dropped, and the guard still exits 0. + +*** Shell lines + +With =--shell=, stdout holds =export NAME=VALUE= with the value quoted for the shell, and =unset NAME=, for =eval "$(eessi-arch-guard --shell)"=. +The message goes to stderr, so the command substitution leaves it out, and the =eval= needs no =echo= to show it. +A value with a newline can be quoted, so =--shell= carries reloads that a prolog line cannot; a NUL byte still fails the reload. +There is no =print= line, and every task writes the message. +[[file:../howto/use-in-a-batch-script.org][Run the guard in a batch script]] shows the output. + +*** One decision per step and node + +With =SLURM_JOB_ID= set, the first task of a step on a node makes the decision and stores it, and the others wait for it and read it. +The file is named + +#+begin_example +.eessi-arch-guard.UID.NODE.JOB.STEP.MODE.DIGEST +#+end_example + +where =STEP= is =SLURM_STEP_ID=, or =batch= without it, and =MODE= is =prolog= or =shell=, because a value with a newline reloads in one mode and fails in the other. +=DIGEST= covers the inputs of the decision: =EESSI_SOFTWARE_SUBDIR=, =EESSI_ACCEL_SUBDIR=, =LOADEDMODULES=, =MODULEPATH=, =EESSI_INIT_PREFIX=, =EESSI_PROC_CPUINFO=, =PATH=, the processors the task may run on, and the GPU variables =CUDA_VISIBLE_DEVICES=, =ROCR_VISIBLE_DEVICES=, =GPU_DEVICE_ORDINAL=, =SLURM_STEP_GPUS= and =SLURM_GPUS_ON_NODE=. +Two tasks of one step on different processors or GPUs therefore decide apart. +[[file:../reference/cli.org][The eessi-arch-guard command]] lists where the file is kept. + +The directory is one other users can write to, such as =/tmp=, so the guard opens the file and its lock without following a symbolic link, and trusts each only when it is a regular file of the user's, with one link and no permission bits for group or others. +It writes the decision to a new file and renames it into place. +A file that fails those checks makes the task decide on its own and write nothing through it. +A stored decision that changes a name the guard never prints, or a name that starts with =LD_=, is not reused either. + +A timeout, a =SIGTERM= and an unexpected exception are not stored, so the next task tries again. + +*** One deadline + +One deadline, 60 seconds by default, covers the wait for the lock, both runs of =eessi_archdetect.sh= and the reload; 60 seconds is Slurm's =DEFAULT_UNKILLABLE_TIMEOUT=. +Each command the guard starts runs in a session of its own. +At the deadline, or on =SIGTERM=, the guard kills that process group with =SIGKILL=, sets =EESSI_ARCH_GUARD_FAILED= to a value ending in =->timeout= or =->terminated=, and exits 0. +After the kill, the Python guard waits up to 5 seconds for the pipe to close and up to 5 seconds twice more for the process, 15 seconds in all at most. +A decision that has finished when the signal comes is still the result, and is still stored. + +** What was considered and turned down + +- /Writing the message to stderr in prolog mode./ + Slurm does not pass a =TaskProlog='s stderr to the task, so the user would not see it. +- /Leaving out only the values a line cannot carry./ + The first version did that, and =MODULEPATH= could move while =_ModuleTable*= or =PS1= stayed behind. +- /Exporting the task's temporary directory./ + =slurmstepd= creates =TMPDIR= after the prologs, and an export would change the directory it creates. +- /One stored decision for both modes./ + A reload that =--shell= can carry may fail as prolog lines. +- /Making the opt-out part of the stored decision's key./ + =EESSI_ARCH_GUARD= is not part of =DIGEST=, and the key was kept as it was first designed; two tasks of a step that differ only in that variable share a result. + +** Limits + +- Nothing removes the stored decision or its lock, the same name with =.lock= added, when the step or the job ends. + A per-job =TMPDIR= that Slurm removes takes them with it; in =/tmp= they stay until the node is cleaned. +- The lock is =flock= on a file in that directory, and the guard assumes it works there. +- A decision whose reload changes an =LD_= variable is decided again by every task. +- A child process that leaves its process group is out of reach of the kill at the deadline. +- In prolog mode, tasks other than local task 0 carry no message; the marker variables are their record. + +** Further reading + +- [[file:design.org][Why a task prolog runs the reload]] +- [[file:../reference/failures.org][Messages and markers]] +- [[file:../reference/compatibility.org][Compatibility]], which lists every line, file and limit as the Zig build keeps them. diff --git a/docs/orgmode/howto/configure.org b/docs/orgmode/howto/configure.org new file mode 100644 index 0000000..4bcdbd5 --- /dev/null +++ b/docs/orgmode/howto/configure.org @@ -0,0 +1,126 @@ +#+TITLE: Configure the guard +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Configure the guard + +Configure the guard when the compute nodes already run a =TaskProlog= of their own, or when its decision needs more or less than 60 seconds. +Slurm starts a =TaskProlog= with no arguments, so these settings come from a configuration file owned by root, or from a wrapper the site owns. + +** Before you start + +- The guard installed on the compute nodes, as in [[file:install-the-prolog.org][Install the prolog]]. +- Root on the compute nodes, or on the image they boot. +- The path of the site's existing task prolog, if there is one; this guide uses =/etc/slurm/task_prolog.site=, which prints =export SITE_PROLOG=1=. + +** Steps + +1. Choose where the settings go: + + | Choice | Use it when | + |------------------------+--------------------------------------------------------------------------------------| + | The configuration file | The guard can be the =TaskProlog= in =slurm.conf=, and runs the site's prolog first. | + | A wrapper | The =TaskProlog= has to stay a script of the site's, which runs the guard last. | + +2. For the configuration file, write =/etc/eessi-arch-guard.conf= on every compute node, owned by root and writable by no one else: + + #+begin_src bash + printf '%s\n' 'chain = /etc/slurm/task_prolog.site' 'timeout = 60' | sudo tee /etc/eessi-arch-guard.conf + sudo chown root:root /etc/eessi-arch-guard.conf + sudo chmod 644 /etc/eessi-arch-guard.conf + #+end_src + + =chain= runs first, as the job's user, with the task's environment; what it prints comes before the guard's lines, and when it exits with a status other than 0, the guard exits with that status and does not decide. + =timeout= is the limit of the decision in seconds. + [[file:../reference/configuration.org][The configuration file]] describes both keys. + +3. For a wrapper instead, write a file =task-prolog= that runs the site's prolog, stops on its failure, and then starts the guard: + + #+begin_src sh + #!/bin/sh + /etc/slurm/task_prolog.site || exit $? + exec /usr/bin/python3 -I /usr/local/sbin/eessi-arch-guard + #+end_src + + Keep the =|| exit $?=: in =if site; then exec guard; fi=, an =if= whose test fails has status 0, so a failed site prolog would look like success. + A wrapper can pass =--timeout SEC= to the guard as well. + Install it on every compute node, and set =TaskProlog=/usr/local/sbin/task-prolog= in =slurm.conf=: + + #+begin_src bash + sudo install -m 755 task-prolog /usr/local/sbin/task-prolog + #+end_src + +** Check that it worked + +Run the prolog as Slurm would, with no arguments, in an environment that holds only =PATH=, and print its exit status: + +#+begin_src bash +env -i PATH=/usr/bin:/bin /usr/local/sbin/eessi-arch-guard +echo "exit $?" +#+end_src + +#+begin_example +export SITE_PROLOG=1 +exit 0 +#+end_example + +The site's prolog ran, and the guard printed nothing else and no warning: with the module environment of the European Environment for Scientific Software Installations (EESSI) not loaded, it has nothing to do. +For a wrapper, run =/usr/local/sbin/task-prolog= the same way. + +=docs/examples/check_config.sh= in the repository runs each case of this guide on a copy of the guard in a temporary directory, =$WORK= in its output, with =sudo= for the files owned by root. +For a configuration file whose first line is a comment holding the byte =0xff=, and which sets =chain= and =timeout = 15=, it shows: + +#+begin_example +case: root-owned-chain +comment_has_0xff: yes +exit: 0 +--- stdout --- +export SITE_PROLOG=1 +--- stderr --- +(empty) +#+end_example + +For a wrapper whose site prolog prints =export FROM_SITE=1=: + +#+begin_example +case: wrapper +command: $WORK/wrapper/wrapper.sh +exit: 0 +--- stdout --- +export FROM_SITE=1 +--- stderr --- +(empty) +#+end_example + +and when that site prolog writes =site-failed= to stderr and exits 9, the wrapper exits 9 without starting the guard: + +#+begin_example +case: wrapper-site-fails +command: $WORK/wrapper-fails/wrapper.sh +exit: 9 +--- stdout --- +(empty) +--- stderr --- +site-failed +#+end_example + +** If it fails + +| Message | Cause | What to do | +|--------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------| +| =eessi-arch-guard: config ignored: /etc/eessi-arch-guard.conf is not owned by root and is ignored= | The file belongs to another user. | =sudo chown root:root /etc/eessi-arch-guard.conf= | +| =eessi-arch-guard: config ignored: /etc/eessi-arch-guard.conf is writable by group or others and is ignored= | The mode has a group or other write bit, such as 664. | =sudo chmod 644 /etc/eessi-arch-guard.conf= | +| =eessi-arch-guard: config ignored: /etc/eessi-arch-guard.conf is a symlink and is ignored= | The path is a symbolic link, even to a file owned by root. | Put the file itself at the path. | +| =eessi-arch-guard: config chain is not an absolute executable: /etc/slurm/task_prolog.site= | The =chain= path is relative, missing, or not executable. | Give the absolute path, and =sudo chmod 755= the script. | +| =eessi-arch-guard: config timeout is not a positive number of seconds at most 9223372036.0= | =timeout= is 0, negative, or not a number; the guard uses 60 seconds and goes on. | Write a number of seconds greater than 0. | +| =eessi-arch-guard: config value kept with its original bytes: KEY= | The value of =KEY= is not UTF-8; it is kept as it is, and the other keys apply. | Write the value in UTF-8. | +| =eessi-arch-guard: skipped, OverflowError: timeout is too large= in the output of every job that loads EESSI | =timeout= is above 2147483.647, which the Python guard accepts and cannot wait for, a bug listed in [[file:../reference/compatibility.org][Compatibility]]. | Write a smaller =timeout=. | +| The task does not start, with the site prolog's message | The site prolog exited with a status other than 0, which the guard returns, so Slurm ends the task. | Correct the site prolog: without the guard, Slurm would end the task the same way. | + +The warnings go to stderr, which Slurm discards for a =TaskProlog=, so run the check above after every change. + +** Related + +- [[file:../reference/configuration.org][The configuration file]] +- [[file:install-the-prolog.org][Install the prolog]] +- [[file:read-a-failure.org][Correct a failed reload]], for the messages of the decision itself diff --git a/docs/orgmode/howto/hand-built-software.org b/docs/orgmode/howto/hand-built-software.org new file mode 100644 index 0000000..47a76ee --- /dev/null +++ b/docs/orgmode/howto/hand-built-software.org @@ -0,0 +1,77 @@ +#+TITLE: Run a program you built yourself on more than one node type +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Run a program you built yourself on more than one node type + +Use this when a program you compiled against modules of the European Environment for Scientific Software Installations (EESSI) runs on more than one CPU type. +The guard reloads modules; it cannot change a program that is already linked. +A program linked against EESSI libraries records their directories as its run path, and those directories name the CPU target of the node it was linked on, so a binary linked on zen4 loads zen4 libraries on every node and can stop with an illegal instruction on zen2. +Build once per node type, and pick the build on the node that runs it. + +** Before you start + +- The guard as the site's =TaskProlog=, or as your own, as in [[file:use-as-a-user-task-prolog.org][Use the guard without changing the site TaskProlog]]. +- The source of your program; this guide uses =prog.c=, which links GSL. + +** Steps + +1. On each node type, in an allocation there, load EESSI and the build environment, and build into a directory named after the target: + + #+begin_src bash + salloc -p cpu -w node017 -n 4 -t 00:30:00 + module load EESSI/2026.06 GSL/2.8-GCC-15.2.0 buildenv/default-foss-2026.1 + p="$HOME/opt/prog/$EESSI_SOFTWARE_SUBDIR" + mkdir -p "$p/bin" + gcc -O2 prog.c -lgsl -lgslcblas -o "$p/bin/prog" + #+end_src + + =buildenv= loads last, so its compiler wrappers record a run path for every loaded library, and the program runs without =LD_LIBRARY_PATH=. + Leave out =-march=native=, which ties the program's own code to the build node as well. + [[https://github.com/stackhands/eb-local][eb-local]] sets up the same build environment with =eval "$(eb-local dev GSL/2.8-GCC-15.2.0)"=. + Repeat the step on a zen2 node. + +2. In the batch script, start the program through a shell in each task, with single quotes, so that =EESSI_SOFTWARE_SUBDIR= expands after the guard has run on that task's node: + + #+begin_src bash + srun bash -c 'exec "$HOME/opt/prog/$EESSI_SOFTWARE_SUBDIR/bin/prog"' + #+end_src + + =srun "$HOME/opt/prog/$EESSI_SOFTWARE_SUBDIR/bin/prog"= expands on the batch node and starts its build on every node. + +3. Without the guard as a task prolog, run its shell mode in the task first: + + #+begin_src bash + srun bash -c 'eval "$(/usr/bin/python3 -I /usr/local/sbin/eessi-arch-guard --shell)" && exec "$HOME/opt/prog/$EESSI_SOFTWARE_SUBDIR/bin/prog"' + #+end_src + +4. To stop at once on a node type with no build: + + #+begin_src bash + srun bash -c 'p="$HOME/opt/prog/$EESSI_SOFTWARE_SUBDIR/bin/prog"; [ -x "$p" ] || { echo "no build for $EESSI_SOFTWARE_SUBDIR" >&2; exit 1; }; exec "$p"' + #+end_src + +** Check that it worked + +The run path of each build names its own target: + +#+begin_src bash +readelf -d "$HOME/opt/prog/x86_64/amd/zen4/bin/prog" | grep -E 'RPATH|RUNPATH' +#+end_src + +Every directory in it lies under =.../software/linux/x86_64/amd/zen4/=, and those of the zen2 build under =.../software/linux/x86_64/amd/zen2/=. +In a job across both node types, each task runs the build of its own node; =srun bash -c 'echo "$(hostname) $EESSI_SOFTWARE_SUBDIR"'= shows the target each task chose. + +** If it fails + +| Message or symptom | Cause | What to do | +|----------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------| +| =Illegal instruction= on one node type | The task ran a build for another target: the path expanded on the batch node, or the build used =-march=native= or was linked on the wrong node. | Quote the path as in step 2, and rebuild on that node type. | +| =no build for x86_64/amd/zen2= | Step 4 found no build for the node. | Build on that node type, as in step 1. | +| The run path names another target | The build ran where EESSI had been loaded for another node. | Load EESSI inside the allocation, or rely on the guard there, and rebuild. | + +** Related + +- [[file:use-as-a-user-task-prolog.org][Use the guard without changing the site TaskProlog]] +- [[file:use-in-a-batch-script.org][Run the guard in a batch script]] +- [[file:../explanation/design.org][Why the guard works the way it does]] diff --git a/docs/orgmode/howto/index.org b/docs/orgmode/howto/index.org new file mode 100644 index 0000000..cc6cf1b --- /dev/null +++ b/docs/orgmode/howto/index.org @@ -0,0 +1,20 @@ +#+TITLE: How-to guides +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* How-to guides + +Each guide gets one task done for a reader who already knows what they want. +The title names the task. + +#+begin_export rst +.. toctree:: + :maxdepth: 1 + + install-the-prolog + configure + use-as-a-user-task-prolog + use-in-a-batch-script + hand-built-software + read-a-failure +#+end_export diff --git a/docs/orgmode/howto/install-the-prolog.org b/docs/orgmode/howto/install-the-prolog.org new file mode 100644 index 0000000..c841c28 --- /dev/null +++ b/docs/orgmode/howto/install-the-prolog.org @@ -0,0 +1,115 @@ +#+TITLE: Install the prolog +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Install the prolog + +Install eessi-arch-guard as the Slurm =TaskProlog= of a cluster whose compute nodes have more than one CPU or GPU type. +After that, a task that inherits the European Environment for Scientific Software Installations (EESSI) loaded for another type gets it loaded again for its own node, before its program starts, and every other task is left as it is. + +** Before you start + +- Root on the compute nodes, or on the image they boot, and on =slurm.conf=. +- =/usr/bin/python3=, Python 3.9 or newer, and =bash= on every compute node. + The guard needs nothing outside Python's standard library. +- EESSI on the compute nodes, as on the login nodes. + The guard runs the =eessi_archdetect.sh= of the loaded EESSI version and the Lmod named by =LMOD_CMD= in the task's environment. +- No =TaskProlog= in =slurm.conf= yet; with one, the guard runs it first, as in [[file:configure.org][Configure the guard]]. +- A checkout of the repository: + + #+begin_src bash + git clone https://github.com/stackhands/eessi-arch-guard.git + cd eessi-arch-guard + #+end_src + +** Steps + +1. Copy the guard to the same path on every compute node, owned by root and executable: + + #+begin_src bash + sudo install -m 755 src/eessi_arch_guard.py /usr/local/sbin/eessi-arch-guard + #+end_src + +2. Check that the copy starts Python in isolated mode, and that it runs: + + #+begin_src bash + head -n 1 /usr/local/sbin/eessi-arch-guard + /usr/local/sbin/eessi-arch-guard --version + #+end_src + + #+begin_example + #!/usr/bin/python3 -I + 0.2.0 + #+end_example + + =-I= makes Python ignore =PYTHONPATH= and the other =PYTHON= variables, the user's site packages and the directory the file is in. + The prolog runs as the job's user, with the job's environment, so none of those may change which code it runs. +3. Name the copy in =slurm.conf=: + + #+begin_example + TaskProlog=/usr/local/sbin/eessi-arch-guard + #+end_example + + Then have =slurmd= on every node read the changed file, as for any other =slurm.conf= change. + Slurm starts a task prolog with no arguments, so the guard runs with its defaults. +4. If users run =eessi-arch-guard --shell= on the login nodes, install the package there too, for example into a virtual environment: + + #+begin_src bash + sudo python3 -m venv /opt/site/software/eessi-arch-guard + sudo /opt/site/software/eessi-arch-guard/bin/python -m pip install . + /opt/site/software/eessi-arch-guard/bin/eessi-arch-guard --version + #+end_src + + #+begin_example + 0.2.0 + #+end_example + + The command this installs starts Python without =-I=. + It serves =--shell=; the =TaskProlog= stays the file from step 1. + +** Check that it worked + +Run the copy the way =slurmstepd= runs it, with no arguments, in an environment without EESSI: + +#+begin_src bash +env -i PATH=/usr/bin:/bin /usr/local/sbin/eessi-arch-guard; echo "exit $?" +env -i PATH=/usr/bin:/bin EESSI_ARCH_GUARD_VERBOSE=1 /usr/local/sbin/eessi-arch-guard; echo "exit $?" +#+end_src + +#+begin_example +exit 0 +EESSI is not loaded +exit 0 +#+end_example + +Without EESSI there is nothing to compare, so the guard prints nothing and exits 0. +=EESSI_ARCH_GUARD_VERBOSE=1= makes it say why on stderr. + +In a job whose task runs on the node type EESSI was loaded on, the guard prints nothing. +On a node of another type, the task's output starts with a line such as + +#+begin_example +eessi-arch-guard: reloaded modules for x86_64/amd/zen2 (loaded for x86_64/amd/zen4) +#+end_example + +and =EESSI_ARCH_GUARD_RELOADED= in the task's environment holds the same pair, =x86_64/amd/zen4->x86_64/amd/zen2=. +Only local task 0 of each node prints the line; every task gets the variable. + +** If it fails + +| Message | Cause | What to do | +|------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------| +| =/usr/local/sbin/eessi-arch-guard: cannot execute: required file not found=, run by hand | The node has no =/usr/bin/python3=; every task on it fails to start. | Install Python 3.9 or newer there, or remove the =TaskProlog= line until then. | +| =/usr/local/sbin/eessi-arch-guard: Permission denied=, run by hand | The copy is not executable; every task on the node fails to start. | Install it again with =-m 755=. | +| No line and no =EESSI_ARCH_GUARD_RELOADED= in a task that ran on another node type | =slurmd= has not read the changed =slurm.conf=, or the submitting environment has =EESSI_ARCH_GUARD=0=. | Check =scontrol show config= for =TaskProlog=, and the job's environment. | +| =eessi-arch-guard: ... environment left as it was= | A reload was needed and could not be made. | The rest of the line names the cause, and [[file:read-a-failure.org][Correct a failed reload]] the correction; the task ran with the environment it was submitted with. | + +** Related + +- [[file:configure.org][Configure the guard]], to run the site's own prolog first or change the time limit +- [[file:read-a-failure.org][Correct a failed reload]] +- [[file:use-in-a-batch-script.org][Run the guard in a batch script]], for the =--shell= install of step 4 +- [[file:../tutorials/first-guarded-job.org][See the guard reload EESSI for another CPU]] +- [[file:../explanation/how-it-decides.org][How the guard decides]] +- [[file:../reference/cli.org][The eessi-arch-guard command]] +- [[file:../reference/compatibility.org][Compatibility]], for the static Zig build of the guard, which is not the default prolog yet diff --git a/docs/orgmode/howto/read-a-failure.org b/docs/orgmode/howto/read-a-failure.org new file mode 100644 index 0000000..a419194 --- /dev/null +++ b/docs/orgmode/howto/read-a-failure.org @@ -0,0 +1,219 @@ +#+TITLE: Correct a failed reload +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Correct a failed reload + +Use this when a job's output has a line from the guard that ends in =environment left as it was=, or when a task has =EESSI_ARCH_GUARD_FAILED= set. +The guard could not load the modules of the European Environment for Scientific Software Installations (EESSI) for the node; the task started with the environment it was submitted with, which was loaded for another node. + +** Before you start + +- The job's output, or a shell in an allocation on a node where the failure happens. +- The modules you load before you submit, with their full names, as =module list= shows them. + +** Steps + +1. Read the marker in a task on the node: + + #+begin_src bash + srun -p cpu -w node017 -n 1 printenv EESSI_ARCH_GUARD_FAILED + #+end_src + + It reads =WAS->NOW=: the target the modules were loaded for, and after =->= either the node's target or a word for the failure. + The line in the job's output, from the first task on each node, says the same in words. + +2. Find what comes after =->= in this table, and make the correction: + + | After =->= | What happened | Correction | + |----------------------+----------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | the node's target | A loaded module has no build for this node's target, or Lmod could not load it. | Load a version that exists for the node, or unload the module the message names, before you submit. | + | =no-software-dir= | None of the targets the detection offered has a software tree on this node. | Ask the site to mount or install a tree for one of the candidates in the message; a node meant to have none can set =EESSI_ARCH_GUARD_MISSING=ignore=. | + | =archdetect-failed= | =eessi_archdetect.sh= is missing, failed, or printed something the guard refuses. | Check =EESSI_INIT_PREFIX/eessi_archdetect.sh=; =EESSI_PREFIX= and =EESSI_INIT_PREFIX= have to be absolute, and =EESSI_OS_TYPE= relative without =.= or =..= parts. | + | =lmod-unavailable= | =LMOD_CMD= is missing or not executable on the node. | Check that the file =LMOD_CMD= names exists on the node; it comes from the shell where EESSI was loaded, so ask the site when the node lacks it. | + | =unsafe-module-name= | A name in =LOADEDMODULES= fails the check of module names. | Unload that module, and load it under a name of the form =NAME/VERSION=. | + | =restore-failed= | The reload could not run, or did not end on this node's target; the message gives the cause. | For a workspace message, point =EESSI_ARCH_GUARD_WORKDIR= at a directory of yours with mode 700, or unset it; the other causes are in the reference below. | + | =unsafe-environment= | The reload changes a variable in a way a prolog line cannot carry. | Run the guard with =--shell= in the job, as in [[file:use-in-a-batch-script.org][Run the guard in a batch script]], or unload the module that sets that value. | + | =timeout= | The decision was still running at the deadline. | Ask the site to raise =timeout= in the configuration file. | + | =terminated= | Slurm or the system sent =SIGTERM= during the decision. | Submit again. | + + [[file:../reference/failures.org][Messages and markers]] has every message and every cause. + +3. Submit the job again from a shell with the corrected modules loaded. + +=docs/examples/failure_cases.py= in the repository runs each case against the stand-ins for EESSI and Lmod of the test suite, with the modules loaded for zen4 and a node that is zen2; =$PREFIX= is its temporary directory. +A module with no build for zen2: + +#+begin_src bash +python3 docs/examples/failure_cases.py missing-module +#+end_src + +#+begin_example +case: missing-module +command: python3 -I src/eessi_arch_guard.py +exit: 0 +--- stdout --- +export EESSI_ARCH_GUARD_FAILED=x86_64/amd/zen4->x86_64/amd/zen2 +print eessi-arch-guard: this node is x86_64/amd/zen2, the modules were loaded for x86_64/amd/zen4; not available for this target: R/4.4.2; environment left as it was +--- stderr --- +(empty) +#+end_example + +A node with no software tree for any candidate: + +#+begin_src bash +python3 docs/examples/failure_cases.py no-software-dir +#+end_src + +#+begin_example +case: no-software-dir +command: python3 -I src/eessi_arch_guard.py +exit: 0 +--- stdout --- +export EESSI_ARCH_GUARD_FAILED=x86_64/amd/zen4->no-software-dir +print eessi-arch-guard: no EESSI software directory for this node under $PREFIX/prefix (candidates x86_64/amd/zen2 x86_64/generic); modules were loaded for x86_64/amd/zen4; environment left as it was +--- stderr --- +(empty) +#+end_example + +The same with =EESSI_ARCH_GUARD_MISSING=ignore= prints nothing: + +#+begin_src bash +python3 docs/examples/failure_cases.py ignore-missing +#+end_src + +#+begin_example +case: ignore-missing +command: python3 -I src/eessi_arch_guard.py +exit: 0 +--- stdout --- +(empty) +--- stderr --- +(empty) +#+end_example + +=eessi_archdetect.sh= failing, with the first line it wrote to stderr in the parentheses: + +#+begin_src bash +python3 docs/examples/failure_cases.py archdetect +#+end_src + +#+begin_example +case: archdetect +command: python3 -I src/eessi_arch_guard.py +exit: 0 +--- stdout --- +export EESSI_ARCH_GUARD_FAILED=x86_64/amd/zen4->archdetect-failed +print eessi-arch-guard: archdetect failed (archdetect forced failure); environment left as it was +--- stderr --- +(empty) +#+end_example + +No usable =LMOD_CMD=: + +#+begin_src bash +python3 docs/examples/failure_cases.py lmod +#+end_src + +#+begin_example +case: lmod +command: python3 -I src/eessi_arch_guard.py +exit: 0 +--- stdout --- +export EESSI_ARCH_GUARD_FAILED=x86_64/amd/zen4->lmod-unavailable +print eessi-arch-guard: LMOD_CMD is missing or not executable; this node is x86_64/amd/zen2, the modules were loaded for x86_64/amd/zen4; environment left as it was +--- stderr --- +(empty) +#+end_example + +An =EESSI_ARCH_GUARD_WORKDIR= that is not a private directory of the user's: + +#+begin_src bash +python3 docs/examples/failure_cases.py workspace +#+end_src + +#+begin_example +case: workspace +command: python3 -I src/eessi_arch_guard.py +exit: 0 +--- stdout --- +export EESSI_ARCH_GUARD_FAILED=x86_64/amd/zen4->restore-failed +print eessi-arch-guard: restore failed (restore workspace unavailable: EESSI_ARCH_GUARD_WORKDIR is not an existing private owned directory); environment left as it was +--- stderr --- +(empty) +#+end_example + +** Check that it worked + +Run the step again and print both markers: + +#+begin_src bash +srun -p cpu -w node017 -n 1 printenv EESSI_SOFTWARE_SUBDIR EESSI_ARCH_GUARD_RELOADED EESSI_ARCH_GUARD_FAILED +#+end_src + +The first line is the node's target, and =EESSI_ARCH_GUARD_FAILED= prints nothing: a reload unsets it. +=EESSI_ARCH_GUARD_RELOADED= is set when the guard reloaded, and unset when the modules were already loaded for the node. + +** If it fails + +| Message or symptom | Cause | What to do | +|----------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------| +| No message and no marker, and the task runs another node's build | The guard did nothing: EESSI was not loaded, the detection was pinned with an override, or =EESSI_ARCH_GUARD=0= was set. | Run the step with =EESSI_ARCH_GUARD_VERBOSE=1=, below, to see which. | +| =EESSI_ARCH_GUARD=0= in the task although the command set =1= | =srun --export=ALL,EESSI_ARCH_GUARD=0= does not replace a value that is already set, as seen with Slurm 23.11.4. | Set or unset the variable in the shell you submit from. | +| =eessi-arch-guard: --timeout is not a positive number of seconds at most 9223372036.0= | A wrapper passed =--timeout= with 0, a negative number or text; the guard keeps 60 seconds. | Pass a number of seconds greater than 0. | + +=EESSI_ARCH_GUARD_VERBOSE=1= writes to stderr why the guard did nothing. +Slurm does not pass a =TaskProlog='s stderr on, so run the guard by hand in the task. +On a node that matches: + +#+begin_src bash +python3 docs/examples/failure_cases.py verbose +#+end_src + +#+begin_example +case: verbose +command: python3 -I src/eessi_arch_guard.py +exit: 0 +--- stdout --- +(empty) +--- stderr --- +target already matches this node +#+end_example + +With =EESSI_ARCH_GUARD=0=, the guard prints nothing at all, also on a mismatch: + +#+begin_src bash +python3 docs/examples/failure_cases.py opt-out +#+end_src + +#+begin_example +case: opt-out +command: python3 -I src/eessi_arch_guard.py +exit: 0 +--- stdout --- +(empty) +--- stderr --- +(empty) +#+end_example + +=--timeout 0= is refused with a warning, and the guard keeps 60 seconds: + +#+begin_src bash +python3 docs/examples/failure_cases.py bad-timeout +#+end_src + +#+begin_example +case: bad-timeout +command: python3 -I src/eessi_arch_guard.py --timeout 0 +exit: 0 +--- stdout --- +(empty) +--- stderr --- +eessi-arch-guard: --timeout is not a positive number of seconds at most 9223372036.0 +#+end_example + +** Related + +- [[file:../reference/failures.org][Messages and markers]] +- [[file:../reference/environment.org][Environment variables]] +- [[file:configure.org][Configure the guard]], for the time limit diff --git a/docs/orgmode/howto/use-as-a-user-task-prolog.org b/docs/orgmode/howto/use-as-a-user-task-prolog.org new file mode 100644 index 0000000..96446a5 --- /dev/null +++ b/docs/orgmode/howto/use-as-a-user-task-prolog.org @@ -0,0 +1,85 @@ +#+TITLE: Use the guard without changing the site TaskProlog +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Use the guard without changing the site TaskProlog + +Use this when your jobs run on more than one CPU type and the site has not installed the guard as its =TaskProlog=, which you cannot change. +Slurm runs a second task prolog for each job step that asks for one, after the site's, and the guard can be that prolog for your own jobs. + +** Before you start + +- The module environment of the European Environment for Scientific Software Installations (EESSI) loaded where you submit, as for any job that inherits it. +- A copy of =src/eessi_arch_guard.py= from the repository, and a home directory the compute nodes mount. + +** Steps + +1. Put the guard where every compute node can run it: + + #+begin_src bash + mkdir -p ~/bin + install -m 755 src/eessi_arch_guard.py ~/bin/eessi-arch-guard + #+end_src + + Its first line, =#!/usr/bin/python3 -I=, starts it with the system's Python, whatever Python a loaded module provides. + +2. Name it as the task prolog of every =srun= that follows, with its full path: + + #+begin_src bash + export SLURM_TASK_PROLOG="$HOME/bin/eessi-arch-guard" + #+end_src + + =SLURM_TASK_PROLOG= is the variable form of =srun --task-prolog=PATH=. + Slurm runs it before each task starts, after any =TaskProlog= of =slurm.conf=. + +3. Start the job step: + + #+begin_src bash + srun -p cpu -w node017 ./a.out + #+end_src + +4. In a batch script, add this line at the top as well, because =sbatch= has no task prolog and =SLURM_TASK_PROLOG= covers only =srun= steps: + + #+begin_src bash + eval "$(/usr/bin/python3 -I "$HOME/bin/eessi-arch-guard" --shell)" + #+end_src + + The commands of a batch script run in the batch step, which gets the site's =TaskProlog= but no per-job prolog, as seen with Slurm 23.11.4. + [[file:use-in-a-batch-script.org][Run the guard in a batch script]] describes that line. + +** Check that it worked + +Print the target and the guard's marker from a task on the other CPU type: + +#+begin_src bash +srun -p cpu -w node017 -n 1 printenv EESSI_SOFTWARE_SUBDIR EESSI_ARCH_GUARD_RELOADED +#+end_src + +The first line names the node's target, and the second records the change, from the target of the node where you loaded the modules to the node's. +On a Slurm 26.05.5 cluster with EESSI 2026.06 and =GSL/2.8-GCC-15.2.0= loaded on a zen2 login node, tasks on a zen4 node got these targets: + +| How the task started | =EESSI_SOFTWARE_SUBDIR= in the task | GSL tree | +|----------------------------------------------+-------------------------------------+----------| +| =srun= on zen4, no guard | =x86_64/amd/zen2= | zen2 | +| =srun= on zen4, with =SLURM_TASK_PROLOG= | =x86_64/amd/zen4= | zen4 | +| =sbatch --export=ALL=, batch step, no guard | =x86_64/amd/zen2= | zen2 | +| the same batch step after the =--shell= line | =x86_64/amd/zen4= | zen4 | + +In the two cases with the guard, it wrote =eessi-arch-guard: reloaded modules for x86_64/amd/zen4 (loaded for x86_64/amd/zen2)=, and =EESSI_ARCH_GUARD_RELOADED= read =x86_64/amd/zen2->x86_64/amd/zen4=. +A plain =sbatch=, without =--export=ALL=, did not carry the login environment on that cluster: the job loaded EESSI on its own node and needed no guard. + +** If it fails + +| Message or symptom | Cause | What to do | +|-------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------| +| =EESSI_SOFTWARE_SUBDIR= names the login node's target, and =EESSI_ARCH_GUARD_RELOADED= is unset | Slurm did not run the guard: =SLURM_TASK_PROLOG= was not exported before =srun=, its path is not absolute or not executable on the node, or the =srun= line has a =--task-prolog= of its own, which replaces it. | Export the variable with the full path, check =ls -l ~/bin/eessi-arch-guard= on the node, and drop the other =--task-prolog=. | +| The same, with =EESSI_ARCH_GUARD=0= in your environment | The guard is off. | =unset EESSI_ARCH_GUARD= before you submit. | +| =EESSI_ARCH_GUARD_FAILED= is set | The guard ran and could not load the modules for the node. | [[file:read-a-failure.org][Correct a failed reload]]. | + +Once the site installs the guard as its =TaskProlog=, your copy finds the modules already loaded for the node and does nothing. + +** Related + +- [[file:use-in-a-batch-script.org][Run the guard in a batch script]] +- [[file:install-the-prolog.org][Install the prolog]], for the site's administrators +- [[file:hand-built-software.org][Run a program you built yourself on more than one node type]] diff --git a/docs/orgmode/howto/use-in-a-batch-script.org b/docs/orgmode/howto/use-in-a-batch-script.org new file mode 100644 index 0000000..82bf821 --- /dev/null +++ b/docs/orgmode/howto/use-in-a-batch-script.org @@ -0,0 +1,125 @@ +#+TITLE: Run the guard in a batch script +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Run the guard in a batch script + +Use this when a batch job inherits modules loaded on a node of another CPU type and the site has not installed the guard as its =TaskProlog=. +The guard's shell mode prints the reload as =export= and =unset= lines, which the batch script applies to itself. + +** Before you start + +- The guard on the compute nodes: installed by the site at =/usr/local/sbin/eessi-arch-guard=, or your own copy, as in step 1 of [[file:use-as-a-user-task-prolog.org][Use the guard without changing the site TaskProlog]]. +- A batch script for =bash=. + +** Steps + +1. Put this line at the top of the batch script, after the =#SBATCH= lines and before the first command that uses a module: + + #+begin_src bash + eval "$(/usr/bin/python3 -I /usr/local/sbin/eessi-arch-guard --shell)" + #+end_src + + =/usr/bin/python3 -I= starts the guard with the system's Python, not one a loaded module put first on =PATH=. + The guard's message goes to stderr, so the command substitution captures only the assignments. + +2. Start the job steps after that line, so that they inherit the corrected environment: + + #+begin_src bash + srun ./a.out + #+end_src + + The =eval= changes only the shell that runs it, so a step gets the corrected environment when this shell starts it after that line, and not with =srun --export=NONE=. + +3. To stop the job when the guard cannot load the modules for the node, use =--strict= and test its status instead: + + #+begin_src bash + if delta="$(/usr/bin/python3 -I /usr/local/sbin/eessi-arch-guard --strict --shell)"; then + eval "$delta" + else + exit "$?" + fi + #+end_src + + With =--strict=, the guard exits 78 after a failed reload, and the script exits with that status before the payload runs. + +4. For =--strict=, create a private workspace once, because the guard does not create one: + + #+begin_src bash + mkdir -p -m 700 ~/.local/state/eessi-arch-guard + #+end_src + + The guard takes =EESSI_ARCH_GUARD_WORKDIR= when it is set, then =TMPDIR= when it is private, then =eessi-arch-guard= under =XDG_STATE_HOME= or =~/.local/state=. + A per-job =TMPDIR= of mode 700 is private; a shared =/tmp= is not. + +** Check that it worked + +=docs/examples/shell_demo.py= in the repository builds a small stack loaded for zen4 on a node it presents as zen2, runs =--shell=, and applies the output in =bash --noprofile --norc=. +=$PREFIX= stands for its temporary directory. + +#+begin_src bash +python3 docs/examples/shell_demo.py +#+end_src + +#+begin_example +case: shell +command: python3 -I src/eessi_arch_guard.py --shell +exit: 0 +--- stdout --- +export EBROOTR=$PREFIX/prefix/software/linux/x86_64/amd/zen2/software/R/4.4.2 +export EESSI_ACCEL_SUBDIR='' +export EESSI_ARCH_GUARD_RELOADED='x86_64/amd/zen4->x86_64/amd/zen2' +export EESSI_SOFTWARE_SUBDIR=x86_64/amd/zen2 +export MODULEPATH=$PREFIX/prefix/software/linux/x86_64/amd/zen2/modules/all +export PATH=$PREFIX/prefix/software/linux/x86_64/amd/zen2/software/R/4.4.2/bin:$PREFIX/prefix/software/linux/x86_64/amd/zen2/bin:$PREFIX/bin:/usr/bin:/bin +export _LMFILES_='' +export _ModuleTable001_=table-for-x86_64-amd-zen2 +--- stderr --- +eessi-arch-guard: reloaded modules for x86_64/amd/zen2 (loaded for x86_64/amd/zen4) +--- eval --- +x86_64/amd/zen2 +x86_64/amd/zen4->x86_64/amd/zen2 +#+end_example + +The lines after =--- eval ---= are =EESSI_SOFTWARE_SUBDIR= and =EESSI_ARCH_GUARD_RELOADED= in the shell after the =eval=: the node's target, and the change from the target the modules were loaded for. +There is no =print= line, which belongs to the =TaskProlog= protocol. +In your job, the same check is + +#+begin_src bash +printenv EESSI_SOFTWARE_SUBDIR EESSI_ARCH_GUARD_RELOADED +#+end_src + +after the =eval= line, and the second variable is unset when the modules already matched the node. + +** If it fails + +With =--strict= and no private workspace, on the same stack, the guard exits 78 and prints the marker of the failure. +=docs/examples/strict_workspace.py= shows it, and then checks that the reload runs once the workspace of step 4 exists: + +#+begin_src bash +python3 docs/examples/strict_workspace.py +#+end_src + +#+begin_example +case: strict-no-workspace +command: python3 -I src/eessi_arch_guard.py --strict --shell +exit: 78 +--- stdout --- +export EESSI_ARCH_GUARD_FAILED='x86_64/amd/zen4->restore-failed' +--- stderr --- +eessi-arch-guard: restore failed (restore workspace unavailable: strict mode needs an existing private job or state workspace); environment left as it was +#+end_example + +| Message | Cause | What to do | +|---------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+--------------------------------------------------------------| +| =eessi-arch-guard: restore failed (restore workspace unavailable: strict mode needs an existing private job or state workspace); environment left as it was= | =--strict= found no private workspace. | Create one, as in step 4. | +| =eessi-arch-guard: restore failed (restore workspace unavailable: EESSI_ARCH_GUARD_WORKDIR is not an existing private owned directory); environment left as it was= | =EESSI_ARCH_GUARD_WORKDIR= names a directory that is missing, not yours, or open to group or others. | Point it at a directory of yours with mode 700, or unset it. | +| =eessi-arch-guard: this node is NOW, the modules were loaded for WAS; not available for this target: NAMES; environment left as it was= | A loaded module has no build for this node's target. | [[file:read-a-failure.org][Correct a failed reload]]. | + +Every message of the guard is listed in [[file:../reference/failures.org][Messages and markers]]. + +** Related + +- [[file:use-as-a-user-task-prolog.org][Use the guard without changing the site TaskProlog]], for =srun= steps +- [[file:../explanation/output-modes.org][Prolog lines and shell lines]] +- [[file:../reference/cli.org][The eessi-arch-guard command]] diff --git a/docs/orgmode/index.org b/docs/orgmode/index.org new file mode 100644 index 0000000..60c2921 --- /dev/null +++ b/docs/orgmode/index.org @@ -0,0 +1,54 @@ +#+TITLE: eessi-arch-guard +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* eessi-arch-guard + +eessi-arch-guard is a Slurm =TaskProlog= that reloads a module stack of the European Environment for Scientific Software Installations (EESSI) when the task runs on a CPU or GPU other than the target recorded at =module load=. +The EESSI module picks that target once, on the machine where it is loaded, and Slurm copies the choice into every job submitted from there. +On the compute node, before the task's program starts, the guard asks EESSI's own detection which target fits the processors and GPUs the task can use; when that is another target, it loads the same modules again for this node and hands the changed environment to Slurm. +A task on a node of the recorded type is left as it is, and a reload that cannot be made changes nothing and says why. +The prolog is one Python file that needs only the standard library; a static Zig build of the same program is in the repository too. + +New here? +[[file:tutorials/first-guarded-job.org][See the guard reload EESSI for another CPU]] runs the guard on one Linux machine, against a stand-in for EESSI loaded for another CPU, and ends with a reload, a run that changes nothing, and a reload that fails safely. + +| You want to | Read | +|-----------------------------------+--------------------------------------------| +| learn by doing, start to finish | [[file:tutorials/index.org][Tutorials]] | +| get one task done | [[file:howto/index.org][How-to guides]] | +| understand why it works this way | [[file:explanation/index.org][Explanation]] | +| look up a command, file or API | [[file:reference/index.org][Reference]] | + +#+begin_export rst +.. toctree:: + :hidden: + :caption: Tutorials + + tutorials/index + +.. toctree:: + :hidden: + :caption: How-to guides + + howto/index + +.. toctree:: + :hidden: + :caption: Explanation + + explanation/index + +.. toctree:: + :hidden: + :caption: Reference + + reference/index + +.. toctree:: + :hidden: + :caption: Project + + contributing + changelog +#+end_export diff --git a/docs/orgmode/reference/api.org b/docs/orgmode/reference/api.org new file mode 100644 index 0000000..16ed337 --- /dev/null +++ b/docs/orgmode/reference/api.org @@ -0,0 +1,27 @@ +#+TITLE: API +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* API + +The API pages are generated from the code on every build, so they match the commit the site was built from. +A declaration's doc comment is its description. + +- [[file:api/zig/index.md][Zig API]]: every =pub= declaration, one page per source file, read with the compiler's own parser by =docs/tools/zig_api.zig=, each linked to its source line at that commit. +- [[autodoc:/][Zig autodoc]]: the same declarations in the browser =zig build docs= makes, with search and source views. + +#+begin_export rst +.. toctree:: + :hidden: + + api/zig/index +#+end_export +The Python API covers every public module, class and function, read from the source by sphinx-autoapi without importing it: + +#+begin_export rst +.. toctree:: + :glob: + :maxdepth: 1 + + api/python/*/index +#+end_export diff --git a/docs/orgmode/reference/cli.org b/docs/orgmode/reference/cli.org new file mode 100644 index 0000000..628b62d --- /dev/null +++ b/docs/orgmode/reference/cli.org @@ -0,0 +1,126 @@ +#+TITLE: The eessi-arch-guard command +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* The eessi-arch-guard command + +=eessi-arch-guard= checks whether the module environment of the European Environment for Scientific Software Installations (EESSI) in a Slurm task was loaded for the task's CPU and accelerator, and prints what loads it again for them. +This page describes the Python guard, =src/eessi_arch_guard.py=; the Zig build behaves the same, except as [[file:compatibility.org][Compatibility]] lists. + +** Synopsis + +#+begin_example +eessi-arch-guard [--shell] [--strict] [--chain PATH] [--timeout SEC] [--restore] [-h|--help] [--version] +#+end_example + +=eessi-arch-guard --help= prints: + +#+begin_example +usage: eessi-arch-guard [--shell] [--strict] [--chain PATH] [--timeout SEC] + [--restore] [-h|--help] [--version] + +Slurm TaskProlog: when the loaded EESSI CPU or accelerator target is not this +node's, print export/unset lines for the reloaded module environment. +--shell prints bash for: eval "$(eessi-arch-guard --shell)" +--strict returns 78 on a failed decision or an unexpected exception. +--chain PATH runs an existing task prolog first. Slurm does not pass arguments, +so a site sets this in a wrapper or in a root-owned eessi-arch-guard.conf. +--timeout SEC bounds the decision. The default is 60 seconds. +--restore reads a JSON restore request on stdin and writes the JSON result. +-h, --help print this text. --version prints the version. +#+end_example + +** Arguments + +=eessi-arch-guard= takes no arguments other than the options below, and skips any argument that is not one of them. +Slurm starts a =TaskProlog= with no arguments at all. + +** Options + +| Option | Meaning | +|----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =--shell= | Print bash instead of prolog lines: =export NAME=VALUE= with the value quoted for bash, and =unset NAME=, for =eval "$(eessi-arch-guard --shell)"=. Messages go to stderr. No chained prolog runs. | +| =--strict= | Exit 78 when the decision fails or an unexpected exception interrupts it. The restore and the cache use a private workspace, which must exist (see [[file:environment.org][Environment variables]]), and the restore helper gets =--strict= too. | +| =--chain PATH=, =--chain=PATH= | Run =PATH= first, in prolog mode only, as described under Exit status. =PATH= must be absolute, free of newline, carriage return and NUL, a regular file and executable; otherwise =eessi-arch-guard: --chain is not an absolute executable= goes to stderr and nothing is chained. A value given here, even an empty or a refused one, replaces the =chain= of the configuration file. | +| =--timeout SEC=, =--timeout=SEC= | The time limit of the decision in seconds, replacing the =timeout= of the configuration file; the default is 60. =SEC= is read as a floating-point number, and must be greater than 0 and at most 9223372036.0, Python's =threading.TIMEOUT_MAX=; otherwise =eessi-arch-guard: --timeout is not a positive number of seconds at most 9223372036.0= goes to stderr and the earlier value stays. Above 2147483.647 the Python guard fails every decision that runs a command, a bug [[file:compatibility.org][Compatibility]] lists. | +| =--restore= | Run as the restore helper: read one JSON request on stdin and write one JSON reply on stdout. The guard starts itself this way; a site or a user has no use for it. | +| =-h=, =--help= | Print the usage text above on stdout and exit 0. | +| =--version= | Print the version on stdout and exit 0. | + +- =--restore= comes first, then =--help=, then =--version=; any of them replaces the decision. +- The value of =--chain= and =--timeout= is the next argument, whatever it is, and empty when there is none. + An option given twice takes its last value. +- =--chain --strict= takes =--strict= as the path, a bug [[file:compatibility.org][Compatibility]] lists under the bugs both builds share. + +** Environment + +The decision reads the task's environment: the variables the =EESSI= module sets, the Slurm task's, and the guard's own controls. +[[file:environment.org][Environment variables]] lists each one. + +** Exit status + +| Status | Meaning | +|--------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 0 | Every run that is not one of the cases below, a failed decision without =--strict= included: the task starts. | +| 78 | =--strict=, and the decision failed or an unexpected exception interrupted it. | +| 1 | =--restore= could not read its request or answer it, with =eessi-arch-guard: restore failed: TEXT= on stderr. | +| N | The chained prolog exited with the status N other than 0, or a signal ended it, which counts as 1. Its stdout is written, and the guard does not decide. Slurm then kills the task, as it would without the guard. | + +** Files + +| File | Use | +|---------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =/etc/eessi-arch-guard.conf= | The configuration file; [[file:configuration.org][The configuration file]] describes it. | +| =eessi-arch-guard.conf= beside the program | The configuration file when =/etc/eessi-arch-guard.conf= does not exist. | +| =EESSI_INIT_PREFIX/eessi_archdetect.sh= | Run with =bash --noprofile --norc=, as =eessi_archdetect.sh -a cpupath= and, unless =EESSI_ACCELERATOR_TARGET_OVERRIDE= is set, as =eessi_archdetect.sh accelpath=. | +| =EESSI_PROC_CPUINFO=, or =/proc/cpuinfo= | Read for the processors and their flags. When the task may run on fewer processors than the file lists, =eessi_archdetect.sh= reads a copy limited to them instead, =eessi-arch-guard-cpu-XXXXXXXX= in the temporary directory, which is removed after the run. | +| =/proc/self/cgroup=, =cpuset.cpus.effective= under =/sys/fs/cgroup= | Read for the processors of the task's cgroup. | +| =.eessi-arch-guard.UID.NODE.JOB.STEP.MODE.DIGEST= | The decision of a job step, kept so that the other tasks of the step on the node read it instead of deciding again; mode 0600. It is in =TMPDIR= when that is a directory whose path starts with =/= and has no =..= part, otherwise in =/tmp=, and in the private workspace with =--strict=. =MODE= is =prolog= or =shell=. Without =SLURM_JOB_ID= there is none. | +| the same name with =.lock= added | The lock the tasks of the step take before they read or write the decision. | +| =eessi-arch-guard-XXXXXXXX= in the restore workspace | The restore helper's private directory, its =HOME= and =TMPDIR=, removed when the helper ends. | + +The guard removes neither the decision nor its lock. +A per-job =TMPDIR= takes them with it at the end of the job; in =/tmp= they stay until the node is cleaned. + +*** Standard output + +In prolog mode, stdout holds, in this order: + +1. what the chained prolog printed, with a newline added when its last line has none; +2. one =export NAME=VALUE= or =unset NAME= line for each variable that changes, sorted by name; +3. one =print MESSAGE= line, from the task whose =SLURM_LOCALID= is =0= or unset. + +Slurm applies the =export= and =unset= lines to the task's environment and writes the message to the task's output. +No line is longer than 4094 bytes, the newline included. +With =--shell=, stdout holds only the =export= and =unset= lines, and the message goes to stderr. +[[file:failures.org][Messages and markers]] lists the messages. + +*** Standard error + +Warnings about the configuration file and the time limit, then whatever the chained prolog wrote to its stderr, unchanged. +With =--shell=, the message. +With =EESSI_ARCH_GUARD_VERBOSE=1=, the reason the guard did nothing, or the error of a failed reload. +Slurm discards a =TaskProlog='s stderr. + +*** --version + +The Python guard prints its version: + +#+begin_example +0.2.0 +#+end_example + +The Zig build follows it with its target, build mode, Zig version and the commit given to =zig build= with =-Dcommit=, or =unknown= without it. +Built with =zig build -Drelease=true -Dtarget=x86_64-linux-musl -Dcommit=a418152=: + +#+begin_example +0.2.0 (x86_64-linux-musl, safe, zig 0.17.1, a418152) +#+end_example + +** See also + +- [[file:../tutorials/first-guarded-job.org][See the guard reload EESSI for another CPU]] +- [[file:../howto/install-the-prolog.org][Install the prolog]], [[file:../howto/configure.org][Configure the guard]] and [[file:../howto/use-in-a-batch-script.org][Run the guard in a batch script]] +- [[file:../explanation/output-modes.org][Prolog lines and shell lines]] +- [[file:configuration.org][The configuration file]], [[file:environment.org][Environment variables]] and [[file:failures.org][Messages and markers]] +- [[py:eessi_arch_guard.parse_args]] and [[py:eessi_arch_guard.main]], and the [[file:api.org][API]] of both builds. diff --git a/docs/orgmode/reference/compatibility.org b/docs/orgmode/reference/compatibility.org new file mode 100644 index 0000000..914279a --- /dev/null +++ b/docs/orgmode/reference/compatibility.org @@ -0,0 +1,9 @@ +#+TITLE: Compatibility +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil + +# COMPAT.md at the top of the repository is the one record; this page shows it. + +#+begin_export rst +.. include:: ../../../COMPAT.md + :parser: myst_parser.sphinx_ +#+end_export diff --git a/docs/orgmode/reference/configuration.org b/docs/orgmode/reference/configuration.org new file mode 100644 index 0000000..73ca4e6 --- /dev/null +++ b/docs/orgmode/reference/configuration.org @@ -0,0 +1,59 @@ +#+TITLE: The configuration file +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* The configuration file + +=eessi-arch-guard.conf= holds the settings a site gives the guard, which Slurm starts with no arguments. + +** Where it is read + +| Path | When | +|---------------------------------------------------------+--------------------------------------------------------| +| =/etc/eessi-arch-guard.conf= | First. | +| =eessi-arch-guard.conf= in the directory of the program | Only when =/etc/eessi-arch-guard.conf= does not exist. | + +- The directory of the program is that of the path Python ran the file by, without following a symbolic link; a guard installed with =pip= reads the one beside the module in =site-packages=. + The Zig build differs when it is started through =PATH= by a symbolic link, as [[file:compatibility.org][Compatibility]] lists. +- A symbolic link at =/etc/eessi-arch-guard.conf= that points nowhere counts as no file. +- The first file that exists is the only one read, even when it is ignored. + +A file is used only when it is: + +| Check | Message on stderr when it fails | +|---------------------------------+----------------------------------------------------------------------------------------| +| not a symbolic link | =eessi-arch-guard: config ignored: PATH is a symlink and is ignored= | +| a regular file | =eessi-arch-guard: config ignored: PATH is not a regular file and is ignored= | +| owned by root | =eessi-arch-guard: config ignored: PATH is not owned by root and is ignored= | +| not writable by group or others | =eessi-arch-guard: config ignored: PATH is writable by group or others and is ignored= | +| readable | =eessi-arch-guard: config ignored: ERROR= | + +An ignored file is a warning, not a failure: the guard goes on with the defaults and exits as it would without the file. + +** Format + +#+begin_example +# /etc/eessi-arch-guard.conf +chain = /etc/slurm/task_prolog.site +timeout = 60 +#+end_example + +- A line is =KEY = VALUE=, split at the first ===; spaces around the key and the value are removed. +- A line that is empty, starts with =#= after its spaces, or has no === is skipped. +- A key that is not UTF-8 is skipped. + A value that is not UTF-8 is kept as the bytes it holds, the other keys still apply, and =eessi-arch-guard: config value kept with its original bytes: KEY= goes to stderr. +- A key given twice takes its last value. + Keys other than the two below are read and not used. + +** Keys + +| Key | Default | Meaning | +|-----------+---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =chain= | none | The absolute path of an executable that runs first, as the job's user, with the task's environment and no arguments, in prolog mode only. Its stdout comes before the guard's lines, its stderr goes to stderr unchanged, and a status other than 0 is the guard's exit status, with no decision. A path that is not absolute, holds a newline, carriage return or NUL, or is not an executable regular file gives =eessi-arch-guard: config chain is not an absolute executable: PATH= on stderr, and nothing is chained. An empty value is no chain. =--chain= replaces it. | +| =timeout= | =60= | The time limit of the decision in seconds, for prolog mode and =--shell= alike: a number greater than 0 and at most 9223372036.0. Another value gives =eessi-arch-guard: config timeout is not a positive number of seconds at most 9223372036.0= on stderr and keeps 60. Above 2147483.647 the Python guard fails every decision that runs a command, a bug [[file:compatibility.org][Compatibility]] lists. =--timeout= replaces it. | + +** See also + +- [[file:../howto/configure.org][Configure the guard]], with the transcripts of each case +- [[file:cli.org][The eessi-arch-guard command]] +- [[py:eessi_arch_guard.site_config]] and [[py:eessi_arch_guard.parse_config_bytes]] diff --git a/docs/orgmode/reference/cpu-flags.org b/docs/orgmode/reference/cpu-flags.org new file mode 100644 index 0000000..b1a3bbd --- /dev/null +++ b/docs/orgmode/reference/cpu-flags.org @@ -0,0 +1,55 @@ +#+TITLE: CPU flags +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* CPU flags + +The processor flags each x86_64 target of the European Environment for Scientific Software Installations (EESSI) needs, and which of them =eessi_archdetect.sh= and eessi-arch-guard check. + +** The waitpkg check + +=eessi_archdetect.sh= gives a CPU a target when the CPU has the flags of that target's line in =eessi_arch_x86.spec=. +The guard drops a candidate whose last path part, with =-= read as =_=, is one of these, when a processor the task may run on lacks =waitpkg=: + +#+begin_example +alderlake arrowlake arrowlake_s clearwaterforest diamondrapids grandridge graniterapids +graniterapids_d novalake pantherlake sapphirerapids sierraforest tremont +#+end_example + +- They are the GCC =-march= targets whose instruction set includes =PTA_WAITPKG= in =gcc/config/i386/i386.h=: those of GCC 15.2.0, and =novalake= from GCC 16. +- The flags are those of the =flags= lines of =/proc/cpuinfo=, or of =EESSI_PROC_CPUINFO=, limited to the processors the task may run on; a flag counts only when every one of them has it. + When the file cannot be read, no processor has the flag. +- No other flag is checked beyond the specification. + +** Flags the specification leaves unchecked + +GCC's =-march= for a target uses more flags than its specification line asks for. +A CPU that lacks one of the others still gets that target, =waitpkg= aside. +The lists name each target's flags under GCC 15.2.0 by their =/proc/cpuinfo= names; where those differ from GCC's, =pni= is SSE3, =abm= is LZCNT, =bmi1= is BMI, =pclmulqdq= is PCLMUL, =rdrand= is RDRND, =3dnowprefetch= is PREFETCHW and =sha_ni= is SHA. +=avx512vbmi= and =avx512ifma= have no underscore. +=PTA_64BIT=, =PTA_NO_SAHF= and =PTA_EVEX512= have no flag in =/proc/cpuinfo= and are left out, as is =avx10_1=, which =graniterapids= gains after GCC 15.2.0. + +- =icelake= is compared with =-march=icelake-server=. +- =graniterapids= has no specification line of its own: =eessi_archdetect.sh= turns a =sapphirerapids= match into =graniterapids= for a CPU of family 6, model 173 or 174, so the flags checked are those of =sapphirerapids=. +- =graniterapids-d= has no specification line; its one flag beyond =graniterapids= is =amx_complex=. +- =alderlake=, =tremont=, =sierraforest=, =grandridge=, =arrowlake=, =arrowlake-s=, =clearwaterforest=, =pantherlake=, =diamondrapids= and =novalake= have no specification line, and =eessi_archdetect.sh= does not choose them from flags. + When a candidate names one of them, the guard checks =waitpkg= and none of its other flags. + +| Target | =-march= | Specification flags | Other flags of the =-march= | +|-------------------+-------------------+-----------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =haswell= | =haswell= | =avx2 fma= | abm, avx, bmi1, bmi2, cx16, f16c, fsgsbase, fxsr, hle, mmx, movbe, pclmulqdq, pni, popcnt, rdrand, sse, sse2, sse4_1, sse4_2, ssse3, xsave, xsaveopt | +| =skylake_avx512= | =skylake-avx512= | =avx2 fma avx512f avx512bw avx512cd avx512dq avx512vl= | 3dnowprefetch, abm, adx, aes, avx, bmi1, bmi2, clflushopt, clwb, cx16, f16c, fsgsbase, fxsr, hle, mmx, movbe, pclmulqdq, pku, pni, popcnt, rdrand, rdseed, sgx, sse, sse2, sse4_1, sse4_2, ssse3, xsave, xsavec, xsaveopt, xsaves | +| =cascadelake= | =cascadelake= | those of =skylake_avx512= and =avx512_vnni= | 3dnowprefetch, abm, adx, aes, avx, bmi1, bmi2, clflushopt, clwb, cx16, f16c, fsgsbase, fxsr, hle, mmx, movbe, pclmulqdq, pku, pni, popcnt, rdrand, rdseed, sgx, sse, sse2, sse4_1, sse4_2, ssse3, xsave, xsavec, xsaveopt, xsaves | +| =icelake= | =icelake-server= | those of =cascadelake= and =avx512_vbmi2= | 3dnowprefetch, abm, adx, aes, avx, avx512_bitalg, avx512_vpopcntdq, avx512ifma, avx512vbmi, bmi1, bmi2, clflushopt, clwb, cx16, f16c, fsgsbase, fxsr, gfni, hle, mmx, movbe, pclmulqdq, pconfig, pku, pni, popcnt, rdpid, rdrand, rdseed, sgx, sha_ni, sse, sse2, sse4_1, sse4_2, ssse3, vaes, vpclmulqdq, wbnoinvd, xsave, xsavec, xsaveopt, xsaves | +| =sapphirerapids= | =sapphirerapids= | =avx2 fma avx512f avx512bw avx512cd avx512dq avx512vl avx512_bf16 amx_tile= | 3dnowprefetch, abm, adx, aes, amx_bf16, amx_int8, avx, avx512_bitalg, avx512_fp16, avx512_vbmi2, avx512_vnni, avx512_vpopcntdq, avx512ifma, avx512vbmi, avx_vnni, bmi1, bmi2, cldemote, clflushopt, clwb, cx16, enqcmd, f16c, fsgsbase, fxsr, gfni, hle, mmx, movbe, movdir64b, movdiri, pclmulqdq, pconfig, pku, pni, popcnt, ptwrite, rdpid, rdrand, rdseed, serialize, sgx, sha_ni, sse, sse2, sse4_1, sse4_2, ssse3, tsxldtrk, uintr, vaes, vpclmulqdq, waitpkg, wbnoinvd, xsave, xsavec, xsaveopt, xsaves | +| =graniterapids= | =graniterapids= | those of =sapphirerapids= | 3dnowprefetch, abm, adx, aes, amx_bf16, amx_fp16, amx_int8, avx, avx512_bitalg, avx512_fp16, avx512_vbmi2, avx512_vnni, avx512_vpopcntdq, avx512ifma, avx512vbmi, avx_vnni, bmi1, bmi2, cldemote, clflushopt, clwb, cx16, enqcmd, f16c, fsgsbase, fxsr, gfni, hle, mmx, movbe, movdir64b, movdiri, pclmulqdq, pconfig, pku, pni, popcnt, prefetchi, ptwrite, rdpid, rdrand, rdseed, serialize, sgx, sha_ni, sse, sse2, sse4_1, sse4_2, ssse3, tsxldtrk, uintr, vaes, vpclmulqdq, waitpkg, wbnoinvd, xsave, xsavec, xsaveopt, xsaves | +| =graniterapids-d= | =graniterapids-d= | none | those of =graniterapids=, and amx_complex | +| =zen2= | =znver2= | =avx2 fma= | 3dnowprefetch, abm, adx, aes, avx, bmi1, bmi2, clflushopt, clwb, clzero, cx16, f16c, fsgsbase, fxsr, mmx, movbe, mwaitx, pclmulqdq, pni, popcnt, rdpid, rdrand, rdseed, sha_ni, sse, sse2, sse4_1, sse4_2, sse4a, ssse3, wbnoinvd, xsave, xsavec, xsaveopt, xsaves | +| =zen3= | =znver3= | those of =zen2= and =vaes= | 3dnowprefetch, abm, adx, aes, avx, bmi1, bmi2, clflushopt, clwb, clzero, cx16, f16c, fsgsbase, fxsr, mmx, movbe, mwaitx, pclmulqdq, pku, pni, popcnt, rdpid, rdrand, rdseed, sha_ni, sse, sse2, sse4_1, sse4_2, sse4a, ssse3, vpclmulqdq, wbnoinvd, xsave, xsavec, xsaveopt, xsaves | +| =zen4= | =znver4= | those of =zen3= and =avx512f avx512ifma= | 3dnowprefetch, abm, adx, aes, avx, avx512_bf16, avx512_bitalg, avx512_vbmi2, avx512_vnni, avx512_vpopcntdq, avx512bw, avx512cd, avx512dq, avx512vbmi, avx512vl, bmi1, bmi2, clflushopt, clwb, clzero, cx16, f16c, fsgsbase, fxsr, gfni, mmx, movbe, mwaitx, pclmulqdq, pku, pni, popcnt, rdpid, rdrand, rdseed, sha_ni, sse, sse2, sse4_1, sse4_2, sse4a, ssse3, vpclmulqdq, wbnoinvd, xsave, xsavec, xsaveopt, xsaves | +| =zen5= | =znver5= | those of =zen4= and =avx512_vp2intersect avx_vnni movdiri= | 3dnowprefetch, abm, adx, aes, avx, avx512_bf16, avx512_bitalg, avx512_vbmi2, avx512_vnni, avx512_vpopcntdq, avx512bw, avx512cd, avx512dq, avx512vbmi, avx512vl, bmi1, bmi2, clflushopt, clwb, clzero, cx16, f16c, fsgsbase, fxsr, gfni, mmx, movbe, movdir64b, mwaitx, pclmulqdq, pku, pni, popcnt, prefetchi, rdpid, rdrand, rdseed, sha_ni, sse, sse2, sse4_1, sse4_2, sse4a, ssse3, vpclmulqdq, wbnoinvd, xsave, xsavec, xsaveopt, xsaves | + +** See also + +- [[file:../explanation/how-it-decides.org][How the guard decides]] +- [[py:eessi_arch_guard.WAITPKG_MARCHES]], [[py:eessi_arch_guard.candidate_supports_cpu]] and [[py:eessi_arch_guard.read_cpu_flags]] diff --git a/docs/orgmode/reference/environment.org b/docs/orgmode/reference/environment.org new file mode 100644 index 0000000..c6a3948 --- /dev/null +++ b/docs/orgmode/reference/environment.org @@ -0,0 +1,111 @@ +#+TITLE: Environment variables +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Environment variables + +The variables eessi-arch-guard reads from the task's environment and the ones it sets there. +The module of the European Environment for Scientific Software Installations (EESSI) sets most of those it reads, and Slurm the rest. + +** Read from the task + +| Variable | Use | +|---------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =EESSI_SOFTWARE_SUBDIR= | The CPU target the modules were loaded for, such as =x86_64/amd/zen4=. Unset or empty, EESSI is not loaded, and the guard does nothing. | +| =EESSI_ACCEL_SUBDIR= | The accelerator target the modules were loaded for, such as =accel/nvidia/cc90=; unset or empty is none. | +| =EESSI_PREFIX= | The EESSI version's prefix; must be an absolute path. A CPU candidate counts when =$EESSI_PREFIX/software/$EESSI_OS_TYPE/CANDIDATE/software= is a directory. | +| =EESSI_OS_TYPE= | The operating system part of that path, such as =linux=; must be a relative path with no empty, =.= or =..= part. | +| =EESSI_INIT_PREFIX= | The directory of =eessi_archdetect.sh=; must be an absolute path. | +| =EESSI_PROC_CPUINFO= | The file =eessi_archdetect.sh= reads instead of =/proc/cpuinfo=. The guard limits it to the task's processors too, when it has =processor= lines. | +| =SLURM_CPU_BIND_LIST= | The processors Slurm binds the task to: a mask such as =0x2=, a list such as =0-3,8=, or a list of names such as =cpu[0-3]=. A list of node names is not a processor list and is skipped. | +| =SLURM_CPU_BIND= | Used when =SLURM_CPU_BIND_LIST= is unset: the text after its last =:= is read as the bind list, as in =quiet,mask_cpu:0x2=. | +| =LOADEDMODULES= | The loaded modules, separated by =:=; the reload loads them again in this order. Exactly one must be =EESSI/VERSION=, and each must be a valid module name, as described below. | +| =MODULEPATH= | Part of the key of the stored decision; the reload sets it anew. | +| =PATH= | Part of the key of the stored decision. =eessi_archdetect.sh= runs with it; the restore helper does not, it runs with =/usr/bin:/bin=. | +| =LMOD_CMD= | The Lmod executable the reload runs; needed only when the targets differ. | +| =EESSI_ARCHDETECT_OPTIONS= | Kept for the =module --force purge= of a reload that pins the CPU target, since the =EESSI= module's unload uses it to find the tree to remove, and dropped from the loads after it. | +| =SLURM_JOB_ID= | Part of the name of the stored decision. Unset, nothing is stored, and each task decides for itself. | +| =SLURM_STEP_ID= | Part of the name of the stored decision; =batch= when unset. | +| =SLURM_LOCALID= | Only the task for which it is =0= or unset prints the =print= line. | +| =CUDA_VISIBLE_DEVICES=, =ROCR_VISIBLE_DEVICES=, =GPU_DEVICE_ORDINAL=, =SLURM_STEP_GPUS=, =SLURM_GPUS_ON_NODE= | Part of the key of the stored decision, so that tasks that see other GPUs do not share it. | +| =TMPDIR= | Where the decision is stored when it is an absolute directory, and the restore workspace when it is private: a directory of the job's user with no group or other permission bits. Never set by the guard: =slurmstepd= creates it after the prolog. | +| =XDG_STATE_HOME=, =HOME= | With =--strict=, the restore workspace can be =$XDG_STATE_HOME/eessi-arch-guard=, or =$HOME/.local/state/eessi-arch-guard= when =XDG_STATE_HOME= is unset or empty. | +| =EESSI_ARCH_GUARD_FAILED= | A successful reload removes it. | +| =BASH_ENV=, =ENV=, =SHELLOPTS=, =BASHOPTS=, =BASH_XTRACEFD=, =PS4= | Removed from the environment of every =bash= the guard starts, so no startup file or trace runs in it. | + +On this page an absolute path starts with =/=, has no =..= part, and holds no newline, carriage return or NUL. + +** Controls + +| Variable | Effect | +|-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =EESSI_ARCH_GUARD=0= | The guard does nothing. It has to be set in the environment the job is submitted from: on Slurm 23.11.4, =srun --export=ALL,EESSI_ARCH_GUARD=0= left a value of =1= that was already set. Any other value leaves the guard on. | +| =EESSI_ARCH_GUARD_MISSING=ignore= | When no CPU candidate has a software directory, the guard does nothing instead of failing. | +| =EESSI_ARCH_GUARD_VERBOSE=1= | The guard writes to stderr why it did nothing, or the error of a failed reload. Slurm discards a =TaskProlog='s stderr; run the guard by hand in the task to read it. | +| =EESSI_SOFTWARE_SUBDIR_OVERRIDE= | Set when the guard starts, the guard does nothing: the CPU target is pinned. A reload that pins the target sets it, as described in [[file:../explanation/how-it-decides.org][How the guard decides]]. | +| =EESSI_ARCHDETECT_OPTIONS_OVERRIDE= | Set, the guard does nothing: the detection is pinned. | +| =EESSI_ACCELERATOR_TARGET_OVERRIDE= | Set, the guard does not compare the accelerator and does not run =eessi_archdetect.sh accelpath=; it still compares the CPU. | +| =EESSI_ARCH_GUARD_WORKDIR= | The restore workspace: an existing directory of the job's user with no group or other permission bits. Set to anything else, every reload fails with =restore-failed=. | + +An override that is set but empty counts as unset. + +The restore workspace is the first of these that applies; the guard creates none of them and changes the mode of none: + +1. =EESSI_ARCH_GUARD_WORKDIR=, when it is set; +2. =TMPDIR=, when it is private; +3. with =--strict=, =eessi-arch-guard= under =XDG_STATE_HOME= or =~/.local/state=, when it exists and is private, and otherwise none, so the reload fails; +4. without =--strict=, =TMPDIR= when it is an absolute directory, and otherwise the system's temporary directory. + +In the workspace the guard creates one private directory per reload, =eessi-arch-guard-XXXXXXXX=, and removes it afterwards. + +** Set by the guard + +| Variable | Value | +|-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =EESSI_ARCH_GUARD_RELOADED= | After a reload, =WAS->NOW=: the target the modules were loaded for and the one they are loaded for now. When the accelerators differ, each side is =CPU ACCEL= or =CPU no accel=. | +| =EESSI_ARCH_GUARD_FAILED= | After a failed reload, =WAS->NOW=, or =WAS->TOKEN= when there is no target to name; [[file:failures.org][Messages and markers]] lists the tokens. | +| every variable the reload changes | Its new value, or removed, except the names below. | + +The guard never sets or removes these names, whatever the reload does to them: + +- =_=, =SHLVL=, =PWD=, =OLDPWD=, =TMPDIR=, =BASH_ENV=, =ENV=, =SHELLOPTS=, =BASHOPTS=, =BASH_XTRACEFD=, =PS4=, =BASH_ARGC=, =BASH_ARGV=, =BASH_LINENO=, =BASH_SOURCE=, =BASH_VERSINFO=, =BASH_VERSION=, =DIRSTACK=, =EPOCHREALTIME=, =EPOCHSECONDS=, =FUNCNAME=, =GROUPS=, =HOSTNAME=, =HOSTTYPE=, =IFS=, =MACHTYPE=, =OPTERR=, =OPTIND=, =OSTYPE=, =PIPESTATUS=, =PPID= +- any name that starts with =SLURM_= or =BASH_FUNC_= + +A changed variable whose name does not match =^[A-Za-z_][A-Za-z0-9_]*$=, or whose value holds a NUL byte, or, in prolog mode, a newline or carriage return, fails the whole reload with =unsafe-environment=. +=PS1=, =PS2=, =PS3= and =PROMPT_COMMAND= are the exception: such a new value is left out, and the rest of the reload is applied. + +** Module names + +Each name in =LOADEDMODULES= must be at most 256 characters long and match + +#+begin_example +^[A-Za-z0-9_][A-Za-z0-9._+-]*(/[A-Za-z0-9_][A-Za-z0-9._+-]*)+$ +#+end_example + +or be a year of four digits, such as =2026=, which matches =^[0-9]{4}$=. +A name with no =/= is refused otherwise. +The =EESSI= entry must match =^EESSI/[A-Za-z0-9_][A-Za-z0-9._+-]*$= and be the only name that starts with =EESSI/=. +A name that fails is =unsafe-module-name=; a list with no such =EESSI= entry, or two, is =restore-failed=. + +** Accelerator targets + +A status other than 0 from =eessi_archdetect.sh accelpath=, or empty output, means no accelerator, as the =EESSI= module records it. +Other output, without the white space around it, must match + +#+begin_example +^accel/(?:nvidia/cc[0-9]+|amd/gfx[0-9a-f]+)$ +#+end_example + +and output that does not fails with =archdetect-failed=. + +** The restore helper's environment + +The helper starts with only =PATH=/usr/bin:/bin=, =LANG=C=, =LC_ALL=C=, and =HOME=, =TMPDIR= and =EESSI_ARCH_GUARD_WORKDIR=, which all name its private directory. +The task's environment reaches it as data in its request. + +** See also + +- [[file:cli.org][The eessi-arch-guard command]] +- [[file:failures.org][Messages and markers]] +- [[file:../explanation/how-it-decides.org][How the guard decides]] and [[file:../explanation/output-modes.org][Prolog lines and shell lines]] +- [[py:eessi_arch_guard.environment_delta]], [[py:eessi_arch_guard.module_name_ok]], [[py:eessi_arch_guard.restore_work_base]] and [[py:eessi_arch_guard.task_cpu_ids]] diff --git a/docs/orgmode/reference/failures.org b/docs/orgmode/reference/failures.org new file mode 100644 index 0000000..4a74cfd --- /dev/null +++ b/docs/orgmode/reference/failures.org @@ -0,0 +1,101 @@ +#+TITLE: Messages and markers +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Messages and markers + +What eessi-arch-guard reports in each case: the marker it sets in the task's environment, the message it prints and its exit status. + +** Outcomes + +| Case | =EESSI_ARCH_GUARD_FAILED= | Output | +|--------------------------------------------------------------------------------------------------+---------------------------+--------------------------------------------------------------------------------------------------------------------------| +| =EESSI_ARCH_GUARD=0= | unchanged | Nothing. | +| =EESSI_SOFTWARE_SUBDIR= unset or empty | unchanged | Nothing: the module environment of the European Environment for Scientific Software Installations (EESSI) is not loaded. | +| =EESSI_SOFTWARE_SUBDIR_OVERRIDE= or =EESSI_ARCHDETECT_OPTIONS_OVERRIDE= set | unchanged | Nothing: the detection is pinned. | +| The node's CPU and accelerator targets are the loaded ones | unchanged | Nothing. With =EESSI_ACCELERATOR_TARGET_OVERRIDE= set, only the CPU is compared. | +| The modules were loaded again | removed | The reload's changes, =EESSI_ARCH_GUARD_RELOADED=WAS->NOW=, and the reload message. | +| No CPU candidate has a software directory | =WAS->no-software-dir= | Its message; nothing with =EESSI_ARCH_GUARD_MISSING=ignore=. | +| =eessi_archdetect.sh= cannot be run, fails for the CPU, or prints something that is not a target | =WAS->archdetect-failed= | Its message. | +| A name in =LOADEDMODULES= is not a valid module name | =WAS->unsafe-module-name= | Its message. | +| =LOADEDMODULES= is empty, or has no single =EESSI/VERSION= entry | =WAS->restore-failed= | Its message. | +| =LMOD_CMD= is not an executable | =WAS->lmod-unavailable= | Its message. | +| The reload could not run, or Lmod's result is not the node's target | =WAS->restore-failed= | Its message, with the cause. | +| A module does not load for the node's target | =WAS->NOW= | Its message, with the modules that did not load. | +| A changed variable cannot be carried | =WAS->unsafe-environment= | Its message. | +| The time limit passed | =SUBDIR->timeout= | Its message. The command the decision was waiting for is killed. | +| =SIGTERM= arrived during the decision | =SUBDIR->terminated= | Its message, after the same kill. | +| An unexpected exception | unchanged | A skip line. | + +- =WAS= and =NOW= are the target the modules were loaded for and the node's target, each =EESSI_SOFTWARE_SUBDIR= alone, or =CPU ACCEL= or =CPU no accel= when the accelerators differ. + =SUBDIR= is =EESSI_SOFTWARE_SUBDIR= alone. + A side that is empty or holds a line break reads =unrecognized=. +- A failure changes nothing else in the environment. +- The exit status is 0 in every case, and 78 with =--strict= for a failure, a time limit, a =SIGTERM= and an unexpected exception. +- With =SLURM_JOB_ID= set, the outcome is stored for the other tasks of the step on the node, except a timeout, a =SIGTERM= and an unexpected exception. + +** Messages + +In prolog mode the message is a =print= line, which Slurm writes to the task's output, from the task whose =SLURM_LOCALID= is =0= or unset; with =--shell= it goes to stderr. +It is one line of at most 500 characters, without control characters. + +| Message | Marker | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------| +| =eessi-arch-guard: reloaded modules for NOW (loaded for WAS)= | =EESSI_ARCH_GUARD_RELOADED=WAS->NOW= | +| =eessi-arch-guard: no EESSI software directory for this node under PREFIX (candidates CANDIDATES); modules were loaded for WAS; environment left as it was= | =no-software-dir= | +| =eessi-arch-guard: archdetect failed (REASON); environment left as it was= | =archdetect-failed= | +| =eessi-arch-guard: a loaded module name is not safe to pass to Lmod; environment left as it was= | =unsafe-module-name= | +| =eessi-arch-guard: the loaded module list has no single EESSI/ entry; environment left as it was= | =restore-failed= | +| =eessi-arch-guard: LMOD_CMD is missing or not executable; this node is NOW, the modules were loaded for WAS; environment left as it was= | =lmod-unavailable= | +| =eessi-arch-guard: restore failed (CAUSE); environment left as it was= | =restore-failed= | +| =eessi-arch-guard: reload did not select this node's CPU target; environment left as it was=, and the same with =accelerator target=, =load the EESSI module= or =load NAME= | =restore-failed= | +| =eessi-arch-guard: this node is NOW, the modules were loaded for WAS; not available for this target: NAMES; environment left as it was= | =WAS->NOW= | +| =eessi-arch-guard: this node is NOW, the modules were loaded for WAS; module load failed; environment left as it was= | =WAS->NOW= | +| =eessi-arch-guard: reload produced a value this output mode cannot carry; environment left as it was= | =unsafe-environment= | +| =eessi-arch-guard: reload produced a prolog line past the Slurm 17.11 read; environment left as it was= | =unsafe-environment= | +| =eessi-arch-guard: decision exceeded the time limit; environment left as it was= | =timeout= | +| =eessi-arch-guard: decision was terminated; environment left as it was= | =terminated= | +| =eessi-arch-guard: skipped, EXCEPTION: TEXT= | none | + +- =CANDIDATES= are the candidates =eessi_archdetect.sh= printed, separated by spaces. +- =NAMES= are the modules that did not load, separated by spaces, followed by =(stopped after 32)= when the guard stopped at 32 of a longer list. + =module load failed= stands in for them when Lmod failed without naming one. + +=REASON= is one of: + +- =EESSI_PREFIX, EESSI_OS_TYPE, or EESSI_INIT_PREFIX is missing or unsafe= +- =eessi_archdetect.sh is not available= +- =could not run archdetect: ERROR= +- the first line =eessi_archdetect.sh -a cpupath= wrote to stderr when it failed, or =exit N= when it wrote none +- =cpupath output is not a single line=, =cpupath returned no candidates=, =cpupath returned an unsafe candidate= +- =accelpath output is not an accelerator subdirectory= + +=CAUSE= is one of: + +- =restore workspace unavailable: EESSI_ARCH_GUARD_WORKDIR is not an existing private owned directory= +- =restore workspace unavailable: strict mode needs an existing private job or state workspace= +- =restore workspace unavailable: ERROR=, when its private directory cannot be created +- =could not start restore helper: ERROR= +- the helper's error on stderr, or =restore helper failed= when it wrote none +- =restore helper returned invalid output=, =restore helper returned no environment= + +** Reasons on stderr + +With =EESSI_ARCH_GUARD_VERBOSE=1=, the guard writes the reason it did nothing to stderr, or the error of a reload whose modules did not load: + +| Reason | Case | +|-------------------------------------------------------------------------------------+--------------------------------------------------------------| +| =EESSI_ARCH_GUARD=0= | The guard is off. | +| =EESSI is not loaded= | =EESSI_SOFTWARE_SUBDIR= is unset or empty. | +| =EESSI_SOFTWARE_SUBDIR_OVERRIDE is set=, =EESSI_ARCHDETECT_OPTIONS_OVERRIDE is set= | The detection is pinned. | +| =no EESSI software directory (ignored)= | =EESSI_ARCH_GUARD_MISSING=ignore= and no software directory. | +| =target already matches this node= | The targets are the loaded ones. | +| Lmod's error | A module did not load. | + +The warnings about the configuration file and the time limit are listed with [[file:configuration.org][The configuration file]] and [[file:cli.org][The eessi-arch-guard command]]. + +** See also + +- [[file:../howto/read-a-failure.org][Correct a failed reload]], with the transcript of each case +- [[file:environment.org][Environment variables]] +- [[py:eessi_arch_guard.decide]] and [[py:eessi_arch_guard.Outcome]] diff --git a/docs/orgmode/reference/index.org b/docs/orgmode/reference/index.org new file mode 100644 index 0000000..4fcc2e4 --- /dev/null +++ b/docs/orgmode/reference/index.org @@ -0,0 +1,21 @@ +#+TITLE: Reference +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Reference + +Descriptions of what there is: commands, options, files, environment variables, exit codes and the API. +Each page states facts in the order the thing itself has them. + +#+begin_export rst +.. toctree:: + :maxdepth: 1 + + cli + configuration + environment + failures + cpu-flags + compatibility + api +#+end_export diff --git a/docs/orgmode/tutorials/first-guarded-job.org b/docs/orgmode/tutorials/first-guarded-job.org new file mode 100644 index 0000000..91026d0 --- /dev/null +++ b/docs/orgmode/tutorials/first-guarded-job.org @@ -0,0 +1,162 @@ +#+TITLE: See the guard reload EESSI for another CPU +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* See the guard reload EESSI for another CPU + +By the end of this tutorial you will have watched eessi-arch-guard find a module environment that was loaded for another CPU, load it again for the CPU it runs on, and stay silent once the two agree. +You will also have seen what it does when a module has no build for that CPU. +Everything runs on one Linux machine, as an ordinary user, from a checkout of the repository. +A small stand-in for the European Environment for Scientific Software Installations (EESSI), the one the repository's tests use, takes the place of the real software stack, so you need no cluster, no Slurm and no EESSI. + +** What you will need + +- A Linux machine with =git=, =bash= and Python 3.9 or newer: + + #+begin_src bash + python3 --version + #+end_src + + #+begin_example + Python 3.12.3 + #+end_example + +** Get the guard + +Clone the repository and check out the commit this tutorial was checked with: + +#+begin_src bash +git clone https://github.com/stackhands/eessi-arch-guard.git +cd eessi-arch-guard +git checkout a418152 +#+end_src + +The guard is the single Python file =src/eessi_arch_guard.py=. +Ask it for its version: + +#+begin_src bash +python3 src/eessi_arch_guard.py --version +#+end_src + +#+begin_example +0.2.0 +#+end_example + +** Run it on a stack loaded for another CPU + +=docs/examples/walkthrough.py= sets up the stand-in and runs the guard the way Slurm runs a task prolog: with no arguments, and with the environment the task would start with. +The stand-in holds software for two CPU types, =x86_64/amd/zen4= and =x86_64/amd/zen2=. +The environment has the =EESSI= module and =R/4.4.2= loaded for zen4, as =module load= leaves them on a zen4 login node. +The stand-in for EESSI's CPU detection says that this machine is a zen2: + +#+begin_src bash +python3 docs/examples/walkthrough.py mismatch +#+end_src + +#+begin_example +case: mismatch +loaded: x86_64/amd/zen4 +node cpuinfo: zen2 +command: python3 -I src/eessi_arch_guard.py +exit: 0 +--- stdout --- +export EBROOTR=$PREFIX/prefix/software/linux/x86_64/amd/zen2/software/R/4.4.2 +export EESSI_ACCEL_SUBDIR= +export EESSI_ARCH_GUARD_RELOADED=x86_64/amd/zen4->x86_64/amd/zen2 +export EESSI_SOFTWARE_SUBDIR=x86_64/amd/zen2 +export MODULEPATH=$PREFIX/prefix/software/linux/x86_64/amd/zen2/modules/all +export PATH=$PREFIX/prefix/software/linux/x86_64/amd/zen2/software/R/4.4.2/bin:$PREFIX/prefix/software/linux/x86_64/amd/zen2/bin:$PREFIX/bin:/usr/bin:/bin +export _LMFILES_= +export _ModuleTable001_=table-for-x86_64-amd-zen2 +print eessi-arch-guard: reloaded modules for x86_64/amd/zen2 (loaded for x86_64/amd/zen4) +--- stderr --- +(empty) +#+end_example + +=$PREFIX= stands for the stand-in's directory, which the script creates under =docs/examples/_work=. +The lines under =--- stdout ---= are what the guard printed, and they are written for Slurm: + +- The =print= line is a message. + In a job, Slurm writes it to the task's output. +- Each =export= line sets one variable in the task's environment before the task starts. + =EESSI_SOFTWARE_SUBDIR=, =MODULEPATH=, =EBROOTR= and =PATH= now name the zen2 tree. +- =EESSI_ARCH_GUARD_RELOADED= records the change, from the target the modules were loaded for to the one they are loaded for now. + +The guard printed only the variables that changed. +It exited with status 0, so Slurm would go on to start the task. + +** Run it again on the corrected environment + +=again= applies those =export= lines to the environment, the way Slurm applies them before it starts the task, and runs the guard on the result: + +#+begin_src bash +python3 docs/examples/walkthrough.py again +#+end_src + +#+begin_example +case: again +command: python3 -I src/eessi_arch_guard.py +exit: 0 +--- stdout --- +(empty) +--- stderr --- +(empty) +#+end_example + +The modules are now loaded for the CPU the guard detects, and when the two agree it prints nothing. + +** Watch a reload that cannot be made + +Run the guard on a stand-in where =R/4.4.2= exists only for zen4, again on a zen2: + +#+begin_src bash +python3 docs/examples/failure_cases.py missing-module +#+end_src + +#+begin_example +case: missing-module +command: python3 -I src/eessi_arch_guard.py +exit: 0 +--- stdout --- +export EESSI_ARCH_GUARD_FAILED=x86_64/amd/zen4->x86_64/amd/zen2 +print eessi-arch-guard: this node is x86_64/amd/zen2, the modules were loaded for x86_64/amd/zen4; not available for this target: R/4.4.2; environment left as it was +--- stderr --- +(empty) +#+end_example + +The message names the module that has no build for this CPU. +Nothing else in the environment changed: a task gets the whole reload or none of it. +=EESSI_ARCH_GUARD_FAILED= records which change was needed, and the exit status is still 0, so the task would start with the environment it was submitted with. + +** Clean up + +Remove the stand-in: + +#+begin_src bash +python3 docs/examples/walkthrough.py clean +#+end_src + +#+begin_example +case: clean +removed: docs/examples/_work +#+end_example + +** What just happened + +1. Loading the =EESSI= module chose a CPU target once, on the machine where it was loaded, and recorded it in =EESSI_SOFTWARE_SUBDIR=. + Every module loaded after it put paths from that target's tree into the environment. +2. The guard asked EESSI's own detection, =eessi_archdetect.sh=, which target this machine is, and found zen2 where zen4 was recorded. +3. It loaded the same modules again for zen2 in a separate process, with the Lmod that =LMOD_CMD= names, here the stand-in's, and printed the difference as lines Slurm applies before the task starts. +4. On the second run the recorded target and the detected one agreed, so it printed nothing. +5. When a module had no build for zen2, it changed nothing, set =EESSI_ARCH_GUARD_FAILED= and said which module was missing. + +[[file:../explanation/how-it-decides.org][How the guard decides]] gives the reasons for each step. + +** Next steps + +- [[file:../howto/install-the-prolog.org][Install the prolog]] on a cluster. +- [[file:../howto/read-a-failure.org][Correct a failed reload]], for each message the guard can print. +- [[file:../explanation/how-it-decides.org][How the guard decides]] what a node's target is. +- [[file:../reference/cli.org][The eessi-arch-guard command]], for every option. + +Checked with Python 3.12.3 and eessi-arch-guard at commit a418152 on 2026-11-16. diff --git a/docs/orgmode/tutorials/index.org b/docs/orgmode/tutorials/index.org new file mode 100644 index 0000000..bd8fb88 --- /dev/null +++ b/docs/orgmode/tutorials/index.org @@ -0,0 +1,15 @@ +#+TITLE: Tutorials +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Tutorials + +A tutorial is a lesson: follow it from the top on a machine like the one it names and it ends with something working. +It explains only what the next step needs; [[file:../explanation/index.org][Explanation]] has the reasons. + +#+begin_export rst +.. toctree:: + :maxdepth: 1 + + first-guarded-job +#+end_export diff --git a/docs/reference/api.md b/docs/reference/api.md deleted file mode 100644 index 25ffca2..0000000 --- a/docs/reference/api.md +++ /dev/null @@ -1,11 +0,0 @@ -# Python API - -The module is `eessi_arch_guard`. The TaskProlog and the console script both call {py:func}`eessi_arch_guard.main`. {py:func}`eessi_arch_guard.decide` compares one environment. {py:func}`eessi_arch_guard.limited_decide` applies the deadline. {py:func}`eessi_arch_guard.probe_cpu` and {py:func}`eessi_arch_guard.probe_accel` read the node. - -The page below is generated from the module. Names that start with an underscore are omitted. - -```{eval-rst} -.. automodule:: eessi_arch_guard - :members: - :undoc-members: -``` diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md deleted file mode 100644 index 922f663..0000000 --- a/docs/reference/changelog.md +++ /dev/null @@ -1,4 +0,0 @@ -# Changelog - -```{include} ../../CHANGELOG.md -``` diff --git a/docs/reference/cli.md b/docs/reference/cli.md deleted file mode 100644 index e4046bc..0000000 --- a/docs/reference/cli.md +++ /dev/null @@ -1,47 +0,0 @@ -# Command line - -```text -eessi-arch-guard [--shell] [--strict] [--chain PATH] [--timeout SEC] [--restore] [-h|--help] [--version] -``` - -`python3 src/eessi_arch_guard.py --help` prints: - -```text -usage: eessi-arch-guard [--shell] [--strict] [--chain PATH] [--timeout SEC] - [--restore] [-h|--help] [--version] - -Slurm TaskProlog: when the loaded EESSI CPU or accelerator target is not this -node's, print export/unset lines for the reloaded module environment. ---shell prints bash for: eval "$(eessi-arch-guard --shell)" ---strict returns 78 on a failed decision or an unexpected exception. ---chain PATH runs an existing task prolog first. Slurm does not pass arguments, -so a site sets this in a wrapper or in a root-owned eessi-arch-guard.conf. ---timeout SEC bounds the decision. The default is 60 seconds. ---restore reads a JSON restore request on stdin and writes the JSON result. --h, --help print this text. --version prints the version. -``` - -`python3 src/eessi_arch_guard.py --version` prints `0.2.0`. - -| Flag | Effect | -| --- | --- | -| `--shell` | Bash assignments on stdout, message on stderr. See [Run the guard from a batch script](../howto/shell_batch.md). | -| `--chain PATH` | Run this absolute executable first. A user job cannot pass it; Slurm supplies no arguments. See [Configure the guard](../howto/configure.md). | -| `--chain=PATH` | Same as `--chain PATH`. | -| `--timeout SEC` | Deadline in seconds. Overrides the config `timeout` key. `SEC` has to be greater than 0 and at most `threading.TIMEOUT_MAX`. Any other value is ignored, a warning goes to stderr, and the default of 60 is used. | -| `--timeout=SEC` | Same as `--timeout SEC`. | -| `--restore` | Helper mode. Read one JSON request on stdin and write one JSON object on stdout. The prolog execs this itself. | -| `-h`, `--help` | Print the usage text and exit 0. | -| `--version` | Print the version and exit 0. The Zig build follows it with its target, build mode, Zig version and the commit given with `-Dcommit` (`unknown` without it), in parentheses. | - -Flags other than these are skipped. The process exits 0 unless `--strict` is given and the decision fails or raises (exit 78, see below), a chained prolog exits non-zero, or `--restore` hits an exception (that path exits 1 and writes the reason to stderr). Without `--strict`, the TaskProlog path catches exceptions and exits 0. - -`--restore` is the helper described in [Concepts](../topics/concepts.md). The JSON request has keys `v` (1), `env`, `eessi`, `modules`, `lmod`, and `pin`: the CPU subdirectory the loads after the purge are pinned to, or empty. Names and values are the Latin-1 wire form from {py:func}`eessi_arch_guard.to_wire`. - -## Strict user job and step status - -`--strict` returns 78 when the decision fails or an unexpected exception interrupts it. -The same flag works with `--shell` and with task-prolog output. -A successful reload, a same-target no-op or an intentional skip returns zero. -A chained prolog failure retains its own nonzero status. -Without `--strict`, the default site TaskProlog keeps its fail-open decision policy. diff --git a/docs/reference/config.md b/docs/reference/config.md deleted file mode 100644 index e3b1f04..0000000 --- a/docs/reference/config.md +++ /dev/null @@ -1,19 +0,0 @@ -# Config file - -| Item | Value | -| --- | --- | -| First path | `/etc/eessi-arch-guard.conf` | -| Second path | `eessi-arch-guard.conf` beside the program, read only when the first path does not exist | -| Owner | root (`st_uid` 0) | -| Type | regular file | -| Mode | group-write and other-write bits clear (`mode & 0o022 == 0`) | -| Symlink | ignored | - -| Key | Meaning | -| --- | --- | -| `chain` | Absolute path of an executable. Run first. Non-zero status is returned unchanged. | -| `timeout` | Positive seconds, at most `threading.TIMEOUT_MAX`. Default 60. Overridden by `--timeout`. | - -Lines are `key = value`. Blank lines and lines whose first non-space byte is `#` are comments. A line with no `=` is skipped. Keys and values are stripped. A key that is not valid UTF-8 is skipped. A value that is not valid UTF-8 is stored with surrogateescape, and stderr receives `eessi-arch-guard: config value kept with its original bytes: `. - -The procedure and the transcripts are [Configure the guard](../howto/configure.md). diff --git a/docs/reference/cpu_flags.md b/docs/reference/cpu_flags.md deleted file mode 100644 index e5a4fc8..0000000 --- a/docs/reference/cpu_flags.md +++ /dev/null @@ -1,29 +0,0 @@ -# CPU flags - -archdetect's x86 spec (`eessi_arch_x86.spec`) requires the flags that separate one EESSI target from the previous one. GCC `-march` for that same target enables a larger set. A flag in the march set and absent from the spec is unchecked: a CPU can miss it and still be given that directory. The guard adds one check on top of that spec, `waitpkg`, for the marches in [Detection and matching](../topics/detection.md). Every other name below stays unchecked. - -The names are `/proc/cpuinfo` flags. Where the spelling differs, `pni` is SSE3, `abm` is LZCNT, `bmi1` is BMI, `pclmulqdq` is PCLMUL, `rdrand` is RDRND, `3dnowprefetch` is PREFETCHW, and `sha_ni` is SHA. `avx512vbmi` and `avx512ifma` have no underscore. `PTA_64BIT`, `PTA_NO_SAHF`, and `PTA_EVEX512` are compiler-internal and have no cpuinfo flag, so this page leaves them out. The lists are GCC 15.2.0 `gcc/config/i386/i386.h`. Trunk's `graniterapids` also adds `PTA_AVX10_1` (`avx10_1`). This page leaves that flag out. archdetect leaves it unchecked. `novalake` is in the guard's waitpkg set and has no march list here. - -`icelake` is compared with `-march=icelake-server`. `graniterapids` shares the Sapphire Rapids spec flags: archdetect upgrades a Sapphire Rapids flag match when the CPU is family 6 model 173 or 174. `graniterapids-d` has no archdetect spec line; its extra flag over `graniterapids` is `amx_complex`. `alderlake`, `tremont`, `sierraforest`, `grandridge`, `arrowlake`, `arrowlake-s`, `clearwaterforest`, `pantherlake`, `diamondrapids`, and `novalake` have no spec line. archdetect selects them only when a candidate string already names them. The guard still requires `waitpkg` on that leaf and leaves the rest of the march unchecked. - -haswell (`-march=haswell`; spec `avx2 fma`): abm, avx, bmi1, bmi2, cx16, f16c, fsgsbase, fxsr, hle, mmx, movbe, pclmulqdq, pni, popcnt, rdrand, sse, sse2, sse4_1, sse4_2, ssse3, xsave, xsaveopt. - -skylake_avx512 (`-march=skylake-avx512`; spec `avx2 fma avx512f avx512bw avx512cd avx512dq avx512vl`): 3dnowprefetch, abm, adx, aes, avx, bmi1, bmi2, clflushopt, clwb, cx16, f16c, fsgsbase, fxsr, hle, mmx, movbe, pclmulqdq, pku, pni, popcnt, rdrand, rdseed, sgx, sse, sse2, sse4_1, sse4_2, ssse3, xsave, xsavec, xsaveopt, xsaves. - -cascadelake (`-march=cascadelake`; spec adds `avx512_vnni`): 3dnowprefetch, abm, adx, aes, avx, bmi1, bmi2, clflushopt, clwb, cx16, f16c, fsgsbase, fxsr, hle, mmx, movbe, pclmulqdq, pku, pni, popcnt, rdrand, rdseed, sgx, sse, sse2, sse4_1, sse4_2, ssse3, xsave, xsavec, xsaveopt, xsaves. - -icelake (`-march=icelake-server`; spec adds `avx512_vbmi2`): 3dnowprefetch, abm, adx, aes, avx, avx512_bitalg, avx512_vpopcntdq, avx512ifma, avx512vbmi, bmi1, bmi2, clflushopt, clwb, cx16, f16c, fsgsbase, fxsr, gfni, hle, mmx, movbe, pclmulqdq, pconfig, pku, pni, popcnt, rdpid, rdrand, rdseed, sgx, sha_ni, sse, sse2, sse4_1, sse4_2, ssse3, vaes, vpclmulqdq, wbnoinvd, xsave, xsavec, xsaveopt, xsaves. - -sapphirerapids (`-march=sapphirerapids`; spec `avx2 fma avx512f avx512bw avx512cd avx512dq avx512vl avx512_bf16 amx_tile`): 3dnowprefetch, abm, adx, aes, amx_bf16, amx_int8, avx, avx512_bitalg, avx512_fp16, avx512_vbmi2, avx512_vnni, avx512_vpopcntdq, avx512ifma, avx512vbmi, avx_vnni, bmi1, bmi2, cldemote, clflushopt, clwb, cx16, enqcmd, f16c, fsgsbase, fxsr, gfni, hle, mmx, movbe, movdir64b, movdiri, pclmulqdq, pconfig, pku, pni, popcnt, ptwrite, rdpid, rdrand, rdseed, serialize, sgx, sha_ni, sse, sse2, sse4_1, sse4_2, ssse3, tsxldtrk, uintr, vaes, vpclmulqdq, waitpkg, wbnoinvd, xsave, xsavec, xsaveopt, xsaves. - -graniterapids (`-march=graniterapids`; same spec flags as sapphirerapids): 3dnowprefetch, abm, adx, aes, amx_bf16, amx_fp16, amx_int8, avx, avx512_bitalg, avx512_fp16, avx512_vbmi2, avx512_vnni, avx512_vpopcntdq, avx512ifma, avx512vbmi, avx_vnni, bmi1, bmi2, cldemote, clflushopt, clwb, cx16, enqcmd, f16c, fsgsbase, fxsr, gfni, hle, mmx, movbe, movdir64b, movdiri, pclmulqdq, pconfig, pku, pni, popcnt, prefetchi, ptwrite, rdpid, rdrand, rdseed, serialize, sgx, sha_ni, sse, sse2, sse4_1, sse4_2, ssse3, tsxldtrk, uintr, vaes, vpclmulqdq, waitpkg, wbnoinvd, xsave, xsavec, xsaveopt, xsaves. - -graniterapids-d (`-march=graniterapids-d`; no spec line): the graniterapids list, plus amx_complex. - -zen2 (`-march=znver2`; spec `avx2 fma`): 3dnowprefetch, abm, adx, aes, avx, bmi1, bmi2, clflushopt, clwb, clzero, cx16, f16c, fsgsbase, fxsr, mmx, movbe, mwaitx, pclmulqdq, pni, popcnt, rdpid, rdrand, rdseed, sha_ni, sse, sse2, sse4_1, sse4_2, sse4a, ssse3, wbnoinvd, xsave, xsavec, xsaveopt, xsaves. - -zen3 (`-march=znver3`; spec adds `vaes`): 3dnowprefetch, abm, adx, aes, avx, bmi1, bmi2, clflushopt, clwb, clzero, cx16, f16c, fsgsbase, fxsr, mmx, movbe, mwaitx, pclmulqdq, pku, pni, popcnt, rdpid, rdrand, rdseed, sha_ni, sse, sse2, sse4_1, sse4_2, sse4a, ssse3, vpclmulqdq, wbnoinvd, xsave, xsavec, xsaveopt, xsaves. - -zen4 (`-march=znver4`; spec adds `avx512f avx512ifma`): 3dnowprefetch, abm, adx, aes, avx, avx512_bf16, avx512_bitalg, avx512_vbmi2, avx512_vnni, avx512_vpopcntdq, avx512bw, avx512cd, avx512dq, avx512vbmi, avx512vl, bmi1, bmi2, clflushopt, clwb, clzero, cx16, f16c, fsgsbase, fxsr, gfni, mmx, movbe, mwaitx, pclmulqdq, pku, pni, popcnt, rdpid, rdrand, rdseed, sha_ni, sse, sse2, sse4_1, sse4_2, sse4a, ssse3, vpclmulqdq, wbnoinvd, xsave, xsavec, xsaveopt, xsaves. - -zen5 (`-march=znver5`; spec adds `avx512_vp2intersect avx_vnni movdiri`): 3dnowprefetch, abm, adx, aes, avx, avx512_bf16, avx512_bitalg, avx512_vbmi2, avx512_vnni, avx512_vpopcntdq, avx512bw, avx512cd, avx512dq, avx512vbmi, avx512vl, bmi1, bmi2, clflushopt, clwb, clzero, cx16, f16c, fsgsbase, fxsr, gfni, mmx, movbe, movdir64b, mwaitx, pclmulqdq, pku, pni, popcnt, prefetchi, rdpid, rdrand, rdseed, sha_ni, sse, sse2, sse4_1, sse4_2, sse4a, ssse3, vpclmulqdq, wbnoinvd, xsave, xsavec, xsaveopt, xsaves. diff --git a/docs/reference/environment.md b/docs/reference/environment.md deleted file mode 100644 index ec5e618..0000000 --- a/docs/reference/environment.md +++ /dev/null @@ -1,69 +0,0 @@ -# Environment - -## Read from the task - -| Variable | Role | -| --- | --- | -| `EESSI_SOFTWARE_SUBDIR` | CPU target recorded at load. Unset means EESSI is not loaded, and the guard returns silently. | -| `EESSI_ACCEL_SUBDIR` | Accelerator subdirectory recorded at load. Empty means no accelerator. | -| `EESSI_PREFIX` | Absolute EESSI prefix. The software walk is `/software///software`. | -| `EESSI_OS_TYPE` | Relative OS subdirectory. An absolute path fails the check. | -| `EESSI_INIT_PREFIX` | Absolute directory that contains `eessi_archdetect.sh`. | -| `EESSI_VERSION` | Exported by the EESSI module. The reload name is the `EESSI/` entry in `LOADEDMODULES`. | -| `EESSI_PROC_CPUINFO` | CPU info file. Unset selects `/proc/cpuinfo`. A file with `processor` lines is scoped to the task's cpuset, affinity, and Slurm bind list before archdetect reads it. | -| `SLURM_CPU_BIND_LIST` | CPUs this task will be bound to: a hex mask, a `0-3,8` list, or a `cpu[0-3]` hostlist. Unset falls through to `SLURM_CPU_BIND`. A node hostlist is ignored. | -| `SLURM_CPU_BIND` | Used when `SLURM_CPU_BIND_LIST` is unset. The text after the last colon is parsed as the bind list (`quiet,mask_cpu:0x2`). | -| `EESSI_ARCHDETECT_OPTIONS` | Kept for the purge of a waitpkg-fallback reload, which removes the loaded tree by it, then dropped so it cannot outrank the pin. | -| `LOADEDMODULES` | Colon-separated module names. Exactly one must match `EESSI/`. | -| `MODULEPATH` | Part of the cache key. The reload replaces it. | -| `LMOD_CMD` | Executable Lmod. Required once the targets differ. | -| `PATH` | Part of the cache key. The helper sees `/usr/bin:/bin` only. | -| `SLURM_JOB_ID` | Required for the cache file. Unset means every task computes its own result. | -| `SLURM_STEP_ID` | Cache component. Unset is stored as `batch`. | -| `SLURM_LOCALID` | `0` or unset receives the `print` line, a skip line included. | -| `TMPDIR` | Cache directory when it is absolute and exists. In strict mode it must be private and owned by the invoking user, or an existing configured private state directory is selected. Omitted from the delta. | - -## Controls - -| Variable | Effect | -| --- | --- | -| `EESSI_ARCH_GUARD=0` | Silent opt-out. Place it in the submitting environment. | -| `EESSI_ARCH_GUARD_MISSING=ignore` | Silent when no candidate has a software directory. | -| `EESSI_ARCH_GUARD_VERBOSE=1` | Skip and match reasons go to stderr. Slurm discards a TaskProlog's stderr; run the guard by hand inside a task to read them. | -| `EESSI_SOFTWARE_SUBDIR_OVERRIDE` | Set on entry: skip detection. Set by a waitpkg fallback during the reload. | -| `EESSI_ARCHDETECT_OPTIONS_OVERRIDE` | Set on entry: skip detection. | -| `EESSI_ACCELERATOR_TARGET_OVERRIDE` | Skip the accelerator comparison. The CPU walk still runs. | -| `EESSI_ARCH_GUARD_WORKDIR` | Existing private directory owned by the invoking user for restore temporaries. The parent creates a private child and removes that child. The configured base is never created or chmodded. | - -## Written by the guard - -| Variable | Value | -| --- | --- | -| `EESSI_ARCH_GUARD_RELOADED` | `was->now` after an applied reload. | -| `EESSI_ARCH_GUARD_FAILED` | `was->token` or `was->now` on a loud failure. Cleared with `unset` after a later success. | - -Plus the restore delta: every changed name that passes the prolog rules. See [What the guard emits](../topics/output.md). - -## Module names - -A loaded name has to match: - -```text -^[A-Za-z0-9_][A-Za-z0-9._+-]*(/[A-Za-z0-9_][A-Za-z0-9._+-]*)+$ -``` - -or be a four-digit ASCII year alias such as `2026`, and be at most 256 characters. Ordinary unversioned package names remain rejected. The EESSI entry has to match `^EESSI/$` and appear once. Anything else is `->unsafe-module-name` (a name that fails the grammar) or `->restore-failed` (the list has no single `EESSI/` entry). The restore does not start. - -Prolog names match `^[A-Za-z_][A-Za-z0-9_]*$`. - -## Accelerator stdout - -```text -^accel/(?:nvidia/cc[0-9]+|amd/gfx[0-9a-f]+)$ -``` - -## Helper process environment - -`PATH=/usr/bin:/bin`, `LANG=C`, `LC_ALL=C`, and `HOME`, `TMPDIR` and `EESSI_ARCH_GUARD_WORKDIR` naming the fresh private helper directory. The task environment travels in the JSON body. - -The configured work directory takes priority over `TMPDIR`. Strict mode accepts only an existing private owned directory, with fallback to an existing `eessi-arch-guard` directory below `XDG_STATE_HOME` or `HOME/.local/state`. It refuses when none is available; it does not create those base directories or use the system temporary fallback. Default TaskProlog mode retains the standard temporary-directory fallback when the scheduler has not created `TMPDIR`. diff --git a/docs/reference/failures.md b/docs/reference/failures.md deleted file mode 100644 index ad9b6f3..0000000 --- a/docs/reference/failures.md +++ /dev/null @@ -1,28 +0,0 @@ -# Failure tokens - -The prolog exits 0 in every row. A chained prolog's non-zero status is the exception: it is returned as-is and the guard does not restore modules. - -| Situation | `EESSI_ARCH_GUARD_FAILED` | Output | -| --- | --- | --- | -| `EESSI_SOFTWARE_SUBDIR` unset | unset | Silent. EESSI is not loaded. | -| `EESSI_ARCH_GUARD=0` | unset | Silent opt-out. | -| `EESSI_SOFTWARE_SUBDIR_OVERRIDE` or `EESSI_ARCHDETECT_OPTIONS_OVERRIDE` set | unset | Silent. Detection is pinned. | -| `EESSI_ACCELERATOR_TARGET_OVERRIDE` set | depends on the CPU | Accelerator is not compared. | -| Same CPU and accelerator | unset | Silent. No exports. | -| No software directory for any candidate | `->no-software-dir` | One `print` line naming the prefix and the candidates. `EESSI_ARCH_GUARD_MISSING=ignore` restores the silence. | -| archdetect missing, non-zero, empty, or unsafe | `->archdetect-failed` | One `print` line. Unsafe accel stdout is this failure. | -| `waitpkg` missing on a march that includes it | unset on success | That candidate is skipped. The next installed candidate is loaded, and `EESSI_SOFTWARE_SUBDIR_OVERRIDE` is set to it. | -| A loaded name fails the grammar | `->unsafe-module-name` | Restore does not start. | -| The list has no single `EESSI/` | `->restore-failed` | Restore does not start. | -| `LMOD_CMD` missing or not executable | `->lmod-unavailable` | Restore does not start. | -| A module has no build for this target | `->` | One `print` line naming the missing modules, up to 32. Nothing from the restore is applied. | -| The restore cannot run: no private workspace, or the helper does not start or gives no usable reply | `->restore-failed` | One `print` line, `restore failed ()`. Nothing from the restore is applied. | -| A changed value cannot be a prolog line | `->unsafe-environment` | No partial delta. | -| Unexpected exception | unchanged, plus a skip line | One `print` line from local task 0, or one stderr line with `--shell`; exit 0. | -| Deadline exhausted | `->timeout` | The waited-on process group is killed. The result is not cached. | -| `SIGTERM` during the decision | `->terminated` | The same kill. The result is not cached. | -| `EESSI_ARCH_GUARD_VERBOSE=1` | unchanged | Skip and match reasons go to stderr. | - -`` is `EESSI_SOFTWARE_SUBDIR`, or ` ` / ` no accel` once both sides are known. `` on the deadline rows is `EESSI_SOFTWARE_SUBDIR` alone. - -How to act on a line is [Correct a guard message](../howto/read_failure.md). diff --git a/docs/reference/index.md b/docs/reference/index.md deleted file mode 100644 index 1e00acf..0000000 --- a/docs/reference/index.md +++ /dev/null @@ -1,15 +0,0 @@ -# Reference - -The CLI, the environment, the config file, the failure tokens, the CPU flag lists, the generated Python API, and the changelog. - -```{toctree} -:maxdepth: 1 - -cli -environment -config -failures -cpu_flags -api -changelog -``` diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index d9d8144..0000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,35 +0,0 @@ -accessible-pygments==0.0.5 -alabaster==1.0.0 -babel==2.18.0 -beautifulsoup4==4.15.0 -certifi==2026.10.23 -charset-normalizer==3.5.2 -docutils==0.21.2 -idna==3.20 -imagesize==2.0.1 -Jinja2==3.1.6 -markdown-it-py==4.2.0 -MarkupSafe==3.0.4 -mdit-py-plugins==0.6.1 -mdurl==0.1.2 -myst-parser==5.1.0 -packaging==26.3 -pygments-styles==0.3.0 -Pygments==2.21.0 -PyYAML==6.0.3 -requests==2.34.2 -roman-numerals-py==4.1.0 -roman-numerals==4.1.0 -shibuya==2025.12.13 -snowballstemmer==3.1.1 -soupsieve==4.1 -Sphinx==8.2.3 -sphinx_design==0.7.0 -sphinxcontrib-applehelp==2.0.0 -sphinxcontrib-devhelp==2.0.0 -sphinxcontrib-htmlhelp==2.1.0 -sphinxcontrib-jsmath==2.0.0 -sphinxcontrib-qthelp==2.0.0 -sphinxcontrib-serializinghtml==2.0.0 -typing_extensions==4.16.0 -urllib3==2.8.0 diff --git a/docs/source/_ext/zig_domain.py b/docs/source/_ext/zig_domain.py new file mode 100644 index 0000000..3b2f143 --- /dev/null +++ b/docs/source/_ext/zig_domain.py @@ -0,0 +1,280 @@ +"""A Sphinx domain for Zig declarations. + +docs/tools/zig_api.zig writes one ``zig:`` directive per public declaration:: + + :::{zig:function} zig_common.proc.run + :signature: pub fn run(gpa: Allocator, argv: []const []const u8, ...) Error!Result + :source: https://github.com/stackhands/zig-common/blob//src/proc.zig#L120 + + The doc comment, as Markdown. + ::: + +The argument is the fully qualified name; it is the HTML anchor and the +key for cross-references and for the objects.inv inventory, so other +stackhands sites reach it through intersphinx. Roles: ``zig:mod``, +``zig:type``, ``zig:fn``, ``zig:const``, ``zig:var``, ``zig:field``, +``zig:err``, and ``zig:obj`` for any kind. A target matches a full name, or +failing that a unique dotted suffix (``proc.run``); ``~`` before the target +shows only its last part. ``zig:autodoc`` links into the autodoc site at +``zig_autodoc_root``, which every directive also links to. +""" + +from __future__ import annotations + +import posixpath +import re +from typing import Any, ClassVar, Iterable + +from docutils import nodes +from docutils.nodes import Element, Node +from docutils.parsers.rst import directives +from sphinx import addnodes +from sphinx.addnodes import desc_signature, pending_xref +from sphinx.application import Sphinx +from sphinx.builders import Builder +from sphinx.directives import ObjectDescription +from sphinx.domains import Domain, ObjType +from sphinx.environment import BuildEnvironment +from sphinx.roles import XRefRole +from sphinx.util import logging +from sphinx.util.docutils import SphinxRole +from sphinx.util.nodes import make_refnode, split_explicit_title + +logger = logging.getLogger(__name__) + +LABELS = { + "module": "module", + "type": "type", + "errorset": "error set", + "function": "function", + "constant": "constant", + "variable": "variable", + "field": "field", + "error": "error", +} + + +def autodoc_href(env: BuildEnvironment, fqn: str) -> str | None: + """The autodoc URL of *fqn*, relative to the page being read.""" + root = env.config.zig_autodoc_root + if not root: + return None + up = posixpath.relpath(".", posixpath.dirname(env.docname) or ".") + base = posixpath.normpath(posixpath.join(up, root)) + "/" + fqn = fqn.strip("/") + return base + ("#" + fqn if fqn else "") + + +def link(text: str, href: str, cls: str) -> nodes.reference: + ref = nodes.reference("", "", internal=False, refuri=href, classes=[cls]) + ref += nodes.inline(text, text) + return ref + + +class ZigObject(ObjectDescription[str]): + """One declaration; its argument is the fully qualified name.""" + + has_content = True + required_arguments = 1 + final_argument_whitespace = False + option_spec: ClassVar[dict[str, Any]] = { + "signature": directives.unchanged, + "source": directives.unchanged, + "file": directives.unchanged, + "no-autodoc": directives.flag, + "no-index": directives.flag, + "no-index-entry": directives.flag, + "no-contents-entry": directives.flag, + } + + def handle_signature(self, sig: str, signode: desc_signature) -> str: + fqn = sig.strip() + short = fqn.rsplit(".", 1)[-1] + text = self.options.get("signature") or ("module " + fqn if self.objtype == "module" else short) + signode["fullname"] = fqn + match = re.search(r"(? None: + # The page title of a module named like a slug ("eb-local") already + # owns the bare id. Sphinx writes anchors into href attributes + # unescaped, so a quote or space would cut the link short. + anchor = re.sub(r"[^\w.\-]", "-", name) + if self.objtype == "module": + anchor = "module-" + anchor + signode["ids"].append(anchor) + self.state.document.note_explicit_target(signode) + domain: ZigDomain = self.env.domains["zig"] # type: ignore[assignment] + domain.note_object(name, self.objtype, anchor, location=signode) + if "no-index-entry" not in self.options: + label = LABELS[self.objtype] + self.indexnode["entries"].append(("single", f"{name} (Zig {label})", anchor, "", None)) + + def _object_hierarchy_parts(self, sig_node: desc_signature) -> tuple[str, ...]: + if self.objtype == "module" or "fullname" not in sig_node: + return () + return tuple(sig_node["fullname"].split(".")) + + def _toc_entry_name(self, sig_node: desc_signature) -> str: + parts = sig_node.get("_toc_parts") + if not parts: + return "" + parens = "()" if self.objtype == "function" and self.config.add_function_parentheses else "" + show = self.config.toc_object_entries_show_parents + if show == "all": + return ".".join(parts) + parens + return parts[-1] + parens + + +class ZigXRefRole(XRefRole): + def process_link( + self, env: BuildEnvironment, refnode: Element, has_explicit_title: bool, title: str, target: str + ) -> tuple[str, str]: + target = target.lstrip("~") + if not has_explicit_title: + title = title.lstrip(".") + if title.startswith("~"): + title = title[1:].rsplit(".", 1)[-1] + return title, target.lstrip(".") + + +class ZigAutodocRole(SphinxRole): + """``:zig:autodoc:`zig_common.proc```, or ``:zig:autodoc:`text ``` for the front page.""" + + def run(self) -> tuple[list[Node], list[nodes.system_message]]: + explicit, title, target = split_explicit_title(self.text) + target = target.strip() + href = autodoc_href(self.env, target) + if href is None: + return [nodes.Text(title)], [] + return [link(title if explicit else (target or "Zig autodoc"), href, "zig-autodoc-link")], [] + + +class ZigDomain(Domain): + name = "zig" + label = "Zig" + object_types: ClassVar[dict[str, ObjType]] = { + "module": ObjType("module", "mod", "obj"), + "type": ObjType("type", "type", "obj"), + "errorset": ObjType("error set", "err", "type", "obj"), + "function": ObjType("function", "fn", "func", "obj"), + "constant": ObjType("constant", "const", "obj"), + "variable": ObjType("variable", "var", "obj"), + "field": ObjType("field", "field", "obj"), + "error": ObjType("error", "err", "obj"), + } + directives: ClassVar[dict[str, type[ObjectDescription]]] = {k: ZigObject for k in object_types} + roles: ClassVar[dict[str, Any]] = { + **{r: ZigXRefRole() for r in ("mod", "type", "err", "fn", "func", "const", "var", "field", "obj")}, + "autodoc": ZigAutodocRole(), + } + initial_data: ClassVar[dict[str, Any]] = {"objects": {}} + data_version = 1 + + @property + def objects(self) -> dict[str, tuple[str, str, str]]: + """Full name -> (docname, anchor, object type).""" + return self.data.setdefault("objects", {}) + + def note_object(self, fqn: str, objtype: str, anchor: str, location: Any = None) -> None: + if fqn in self.objects: + other = self.objects[fqn][0] + logger.warning("duplicate Zig object %s, also in %s", fqn, other, location=location, type="zig", subtype="duplicate") + self.objects[fqn] = (self.env.docname, anchor, objtype) + + def clear_doc(self, docname: str) -> None: + for fqn, (doc, _anchor, _objtype) in list(self.objects.items()): + if doc == docname: + del self.objects[fqn] + + def merge_domaindata(self, docnames: Iterable[str], otherdata: dict[str, Any]) -> None: + for fqn, entry in otherdata["objects"].items(): + if entry[0] in docnames: + self.objects[fqn] = entry + + def find(self, target: str, objtypes: Iterable[str] | None) -> list[tuple[str, tuple[str, str, str]]]: + wanted = set(objtypes) if objtypes is not None else None + + def ok(entry: tuple[str, str, str]) -> bool: + return wanted is None or entry[2] in wanted + + entry = self.objects.get(target) + if entry is not None and ok(entry): + return [(target, entry)] + suffix = "." + target + return [(fqn, e) for fqn, e in self.objects.items() if fqn.endswith(suffix) and ok(e)] + + def resolve_xref( + self, + env: BuildEnvironment, + fromdocname: str, + builder: Builder, + typ: str, + target: str, + node: pending_xref, + contnode: Element, + ) -> nodes.reference | None: + matches = self.find(target, self.objtypes_for_role(typ)) + if not matches: + return None + if len(matches) > 1: + logger.warning( + "more than one Zig object matches %r: %s", + target, + ", ".join(sorted(m[0] for m in matches)), + location=node, + type="ref", + subtype="zig", + ) + fqn, (docname, anchor, _objtype) = matches[0] + return make_refnode(builder, fromdocname, docname, anchor, contnode, fqn) + + def resolve_any_xref( + self, + env: BuildEnvironment, + fromdocname: str, + builder: Builder, + target: str, + node: pending_xref, + contnode: Element, + ) -> list[tuple[str, nodes.reference]]: + results = [] + for fqn, (docname, anchor, objtype) in self.find(target, None): + role = self.role_for_objtype(objtype) or "obj" + results.append((f"zig:{role}", make_refnode(builder, fromdocname, docname, anchor, contnode, fqn))) + return results + + def get_objects(self) -> Iterable[tuple[str, str, str, str, str, int]]: + for fqn, (docname, anchor, objtype) in self.objects.items(): + yield fqn, fqn, objtype, docname, anchor, 1 + + def get_full_qualified_name(self, node: Element) -> str | None: + return node.get("reftarget") + + +def setup(app: Sphinx) -> dict[str, Any]: + app.add_config_value("zig_autodoc_root", "", "env", types=frozenset({str})) + app.add_domain(ZigDomain) + return {"version": "1", "env_version": 1, "parallel_read_safe": True, "parallel_write_safe": True} diff --git a/docs/_static/favicon.svg b/docs/source/_static/favicon.svg similarity index 100% rename from docs/_static/favicon.svg rename to docs/source/_static/favicon.svg diff --git a/docs/_static/logo-dark.svg b/docs/source/_static/logo-dark.svg similarity index 100% rename from docs/_static/logo-dark.svg rename to docs/source/_static/logo-dark.svg diff --git a/docs/_static/logo-light.svg b/docs/source/_static/logo-light.svg similarity index 100% rename from docs/_static/logo-light.svg rename to docs/source/_static/logo-light.svg diff --git a/docs/_static/mark-dark.svg b/docs/source/_static/mark-dark.svg similarity index 100% rename from docs/_static/mark-dark.svg rename to docs/source/_static/mark-dark.svg diff --git a/docs/_static/mark.svg b/docs/source/_static/mark.svg similarity index 100% rename from docs/_static/mark.svg rename to docs/source/_static/mark.svg diff --git a/docs/source/_static/stackhands.css b/docs/source/_static/stackhands.css new file mode 100644 index 0000000..9573490 --- /dev/null +++ b/docs/source/_static/stackhands.css @@ -0,0 +1,23 @@ +/* Zig API pages: keep long signatures readable and the links to source + and autodoc out of the way. */ +dl.zig > dt.sig { + flex-wrap: wrap; + row-gap: 0.25rem; +} + +dl.zig > dt.sig .zig-sig-rest { + white-space: pre-wrap; +} + +dl.zig > dt.sig .zig-source-link, +dl.zig > dt.sig .zig-autodoc-link { + margin-left: 0.75rem; + font-family: var(--sy-f-text, inherit); + font-size: 0.8em; + font-weight: normal; +} + +dl.zig.field > dt.sig, +dl.zig.error > dt.sig { + font-size: 0.95em; +} diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..25c1ac0 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,254 @@ +"""Sphinx configuration for the eessi-arch-guard documentation. + +The pages are Org files under docs/orgmode/, exported here as reStructuredText +by docs/export.el. The API reference under reference/api/ is generated from +the code. Neither is committed: `pixi run -e docs docbld` makes both. +""" + +import os +import re +import sys + +from docutils import nodes + +_here = os.path.dirname(os.path.abspath(__file__)) +_repo = os.path.abspath(os.path.join(_here, "..", "..")) +sys.path.insert(0, os.path.join(_here, "_ext")) + +project = "eessi-arch-guard" +author = "stackhands developers" +copyright = "stackhands developers" + + +def _release(): + """The version the build files declare: build.zig.zon, pyproject.toml or Cargo.toml.""" + for name, pattern in ( + ("build.zig.zon", r'^\s*\.version\s*=\s*"([^"]+)"'), + ("pyproject.toml", r'^version\s*=\s*"([^"]+)"'), + ("Cargo.toml", r'^version\s*=\s*"([^"]+)"'), + ): + path = os.path.join(_repo, name) + if os.path.isfile(path): + found = re.search(pattern, open(path, encoding="utf-8").read(), re.M) + if found: + return found.group(1) + return "" + + +release = version = _release() + +extensions = [ + "myst_parser", + "sphinx.ext.intersphinx", + "sphinx_copybutton", + "sphinx_design", + "sphinx_sitemap", + "zig_domain", +] + +# Generated API pages are MyST Markdown, as doc comments are Markdown; the +# exported Org pages are reStructuredText. +source_suffix = {".rst": "restructuredtext", ".md": "markdown"} +myst_enable_extensions = ["colon_fence", "deflist", "fieldlist"] +exclude_patterns = [] +templates_path = ["_templates"] + +# Every cross-reference must resolve: sphinx-build runs with -W -n. +nitpicky = True +nitpick_ignore = [] +manpages_url = "https://man7.org/linux/man-pages/man{section}/{page}.{section}.html" +# Doc comments and docstrings name flags in plain text: --strict stays two +# hyphens. +smartquotes_action = "qe" + +# -- API reference ----------------------------------------------------------- +# Zig: docs/tools/zig_api.zig writes reference/api/zig/ (pixi task mkapi), and +# `zig build docs` puts the autodoc site at api/ (pixi task autodoc). +zig_autodoc_root = "api/" + +# Python: sphinx-autoapi reads the packages listed here, without importing +# them, into reference/api/python/. +PYTHON_PACKAGES = ["src"] +if PYTHON_PACKAGES: + extensions.append("autoapi.extension") + autoapi_type = "python" + autoapi_dirs = [os.path.join(_repo, p) for p in PYTHON_PACKAGES] + autoapi_root = "reference/api/python" + autoapi_add_toctree_entry = False + autoapi_keep_files = False + autoapi_member_order = "groupwise" + # undoc-members: a module or class without a docstring is still listed, + # so the reference is complete and the gap shows. + autoapi_options = [ + "members", + "undoc-members", + "show-inheritance", + "show-module-summary", + "special-members", + "imported-members", + ] + autoapi_ignore = ["*/tests/*", "*/test_*.py", "*/conftest.py"] + +# Rust: sphinx-rustdocgen reads each crate listed here (crate name: its +# directory) into reference/api/rust//, for sphinxcontrib-rust. +RUST_CRATES = {} +if RUST_CRATES: + extensions.append("sphinxcontrib_rust") + rust_crates = {name: os.path.join(_repo, path) for name, path in RUST_CRATES.items()} + rust_doc_dir = os.path.join(_here, "reference", "api", "rust") + # Doc comments are Markdown, read by myst_parser. + rust_rustdoc_fmt = "md" + rust_generate_mode = "always" + # A rustdoc link to an item named like its module ([`gap`] in gap) also + # matches that module's page; MyST links the page, which lists the item. + suppress_warnings = ["myst.xref_ambiguous"] + # A type from std, core or another crate has no page here; a name in + # these crates that does not resolve still fails the build. + nitpick_ignore_regex = [ + (r"rust:.*", r"(?!(?:%s)(?:::|$)).*" % "|".join(RUST_CRATES)), + ("myst", r"\w+(?:::\w+)+"), + ] + +# -- Links to other sites ---------------------------------------------------- +# A link to another stackhands site resolves through that site's objects.inv, +# so a page or API name that does not exist there fails the build. A local +# build keeps the inventories it fetched for 30 days and works offline in +# that time; CI starts clean and always fetches them. +# stackhands-intersphinx:begin (written by docs-plan/template/apply.py) +intersphinx_mapping = { + "eb-staged-rebuild": ("https://stackhands.github.io/eb-staged-rebuild/", None), + "eb-local": ("https://stackhands.github.io/eb-local/", None), + "eb-keep-logs": ("https://stackhands.github.io/eb-keep-logs/", None), + "zig-common": ("https://stackhands.github.io/zig-common/", None), +} +# stackhands-intersphinx:end +intersphinx_mapping["python"] = ("https://docs.python.org/3", None) +intersphinx_cache_limit = 30 +intersphinx_timeout = 30 + +# -- HTML ---------------------------------------------------------------------- +html_theme = "shibuya" +html_title = "eessi-arch-guard" +html_baseurl = "https://stackhands.github.io/eessi-arch-guard/" +html_static_path = ["_static"] +html_css_files = ["stackhands.css"] +# The logos come from stackhands/.github branding (apply.py copies them). +_logos = { + name: "_static/" + name + for name in ("favicon.svg", "logo-light.svg", "logo-dark.svg") + if os.path.isfile(os.path.join(_here, "_static", name)) +} +html_favicon = _logos.get("favicon.svg") +html_copy_source = False +html_show_sourcelink = False +sitemap_url_scheme = "{link}" + +html_context = { + "source_type": "github", + "source_user": "stackhands", + "source_repo": "eessi-arch-guard", + "source_version": "main", + "source_docs_path": "/docs/orgmode/", +} + +html_theme_options = { + "github_url": "https://github.com/stackhands/eessi-arch-guard", + "accent_color": "teal", + "dark_code": True, + # Its "Copy page" menu links chat services, which check_site.py rejects. + "show_ai_links": False, + "globaltoc_expand_depth": 1, + "nav_links": [ + {"title": "Tutorial", "url": "tutorials/index"}, + {"title": "How-to", "url": "howto/index"}, + {"title": "Explanation", "url": "explanation/index"}, + {"title": "Reference", "url": "reference/index"}, + # stackhands:begin (generated by stackhands/.github branding/sync.py) + { + "title": "stackhands", + "children": [ + { + "title": "eb-stack", + "url": "https://eb-stack.rgoswami.me/", + "summary": "Solve, shard and plan an EasyBuild build list; admit builds under a scratch inode budget", + }, + { + "title": "eb-pipeline", + "url": "https://github.com/stackhands/eb-pipeline#readme", + "summary": "Drive an EasyBuild pipeline from one per-site TOML file, calling the other tools as subprocesses", + }, + { + "title": "eb-staged-rebuild", + "url": "https://stackhands.github.io/eb-staged-rebuild/", + "summary": "Rebuild an installation in a staged tree and swap it in, so running jobs keep their paths", + }, + { + "title": "eb-local", + "url": "https://stackhands.github.io/eb-local/", + "summary": "Install software with EasyBuild on top of EESSI into a directory a user or project owns", + }, + { + "title": "eb-keep-logs", + "url": "https://stackhands.github.io/eb-keep-logs/", + "summary": "Keep a failed build's EasyBuild log and command output; rotate a pipeline's log tree", + }, + { + "title": "rfc9162", + "url": "https://stackhands.github.io/rfc9162/", + "summary": "Append-only Merkle logs hashed as RFC 9162, with tiled storage and signed checkpoints", + }, + { + "title": "zig-common", + "url": "https://stackhands.github.io/zig-common/", + "summary": "The shared Zig library under the Zig tools: system calls, checked files, child processes", + }, + ], + }, + # stackhands:end + ], +} +if "logo-light.svg" in _logos and "logo-dark.svg" in _logos: + html_theme_options["light_logo"] = _logos["logo-light.svg"] + html_theme_options["dark_logo"] = _logos["logo-dark.svg"] + +html_sidebars = { + "**": [ + "sidebars/localtoc.html", + "sidebars/repo-stats.html", + "sidebars/edit-this-page.html", + ], +} + + +def _edit_link(app, pagename, templatename, context, doctree): + """Point "edit this page" at the Org source; generated pages have none.""" + if pagename.startswith("reference/api/"): + context["page_source_suffix"] = None + else: + context["page_source_suffix"] = ".org" + + +def _unlink_rust_paths(app, doctree, docname): + """A rustdoc link to an item outside these crates stays as code, unlinked.""" + if not docname.startswith("reference/api/rust/"): + return + for ref in list(doctree.findall(nodes.reference)): + if re.fullmatch(r"\w+(?:::\w+)+", ref.get("refid", "")): + ref.replace_self(ref.children) + + +def setup(app): + app.connect("html-page-context", _edit_link) + if RUST_CRATES: + app.connect("doctree-resolved", _unlink_rust_paths) + if "local_setup" in globals(): + globals()["local_setup"](app) + + +# -- This repository ----------------------------------------------------------- +# apply.py rewrites everything above and keeps what is between these markers: +# the place for settings only this repository has, such as the Rust crates +# for sphinxcontrib-rust or a nitpick_ignore entry. Event hooks go in a +# function local_setup(app), which setup() calls. +# local:begin +# local:end diff --git a/docs/tools/check_site.py b/docs/tools/check_site.py new file mode 100644 index 0000000..d5cebc2 --- /dev/null +++ b/docs/tools/check_site.py @@ -0,0 +1,177 @@ +#!/usr/bin/env python3 +"""Check a built site: internal links, anchors and forbidden names. + + python docs/tools/check_site.py docs/build/html [--sources docs/orgmode] + [--forbid REGEX]... [--no-default-forbid] [--exempt PAGE]... + +Every relative href and src in every HTML page must name a file in the site, +and a #fragment on a page Sphinx made must name an id on that page. Under +api/, the Zig autodoc site, only files are checked: its anchors are made by +script. External links are lychee's job (pixi task linkcheck). + +A page may not link to a generated .rst file (the edit links go to the Org +sources), and no page's text or link targets, and no Org source, may carry +a forbidden pattern: by default the names and paths of one real site, as +the pages describe a neutral example site, and links to AI chat services. +--exempt names a built page, such as changelog.html, that records history: +its text and link targets are not checked for forbidden names, but its +links must still resolve. + +Exit status: 0 when clean, 1 when anything is wrong, 2 on a usage error. +""" + +import argparse +import html.parser +import os +import re +import sys +import urllib.parse + +# The repositories' CI greps the whole tree for these names, this file +# included, so each keeps one letter in a class or escapes its dot: the +# pattern matches the name, and its own text does not. +DEFAULT_FORBID = [ + r"snelli[u]s", + r"sne[l]-", + r"surf\.nl", + r"surfsar[a]", + r"/gp[f]s/", + r"/project[s]/0", + r"rg\.terra", + r"scratch-shar[e]d", + r"scratch-nod[e]", + r"eblocalinstal[l]", + r"chatgpt\.com", + r"claude\.ai", + r"perplexity\.ai", +] + +SCRIPTED_ANCHORS = ("api/",) + + +class Page(html.parser.HTMLParser): + def __init__(self): + super().__init__(convert_charrefs=True) + self.ids = set() + self.links = [] + self.text = [] + self._skip = 0 + + def handle_starttag(self, tag, attrs): + attrs = dict(attrs) + for key in ("id", "name"): + if attrs.get(key) and (key == "id" or tag == "a"): + self.ids.add(attrs[key]) + for key in ("href", "src"): + value = attrs.get(key) + if value is not None and not (tag == "link" and attrs.get("rel") in ("preconnect", "dns-prefetch")): + self.links.append((value, self.getpos()[0])) + if tag in ("script", "style"): + self._skip += 1 + + def handle_endtag(self, tag): + if tag in ("script", "style") and self._skip: + self._skip -= 1 + + def handle_data(self, data): + if not self._skip: + self.text.append(data) + + +def parse(path): + page = Page() + with open(path, encoding="utf-8", errors="replace") as handle: + page.feed(handle.read()) + return page + + +def check_site(root, forbid, exempt=()): + errors = [] + pages = {} + for dirpath, _dirs, files in os.walk(root): + for name in files: + if name.endswith(".html"): + path = os.path.join(dirpath, name) + pages[os.path.relpath(path, root)] = parse(path) + + for rel, page in sorted(pages.items()): + scripted = rel.startswith(SCRIPTED_ANCHORS) + for href, line in page.links: + where = f"{rel}:{line}" + if re.search(r"\.rst(?:[?#]|$)", href.split("?")[0]): + errors.append(f"{where}: link to a generated .rst file: {href}") + parts = urllib.parse.urlsplit(href) + if parts.scheme or href.startswith("//") or href.startswith(("mailto:", "data:", "javascript:")): + continue + target_rel = rel if not parts.path else os.path.normpath( + os.path.join(os.path.dirname(rel), urllib.parse.unquote(parts.path)) + ) + if target_rel.startswith(".."): + errors.append(f"{where}: link leaves the site: {href}") + continue + target = os.path.join(root, target_rel) + if os.path.isdir(target): + target_rel = os.path.join(target_rel, "index.html") + target = os.path.join(root, target_rel) + if not os.path.isfile(target): + errors.append(f"{where}: no such file: {href}") + continue + fragment = urllib.parse.unquote(parts.fragment) + if not fragment or scripted or target_rel.startswith(SCRIPTED_ANCHORS): + continue + target_page = pages.get(os.path.normpath(target_rel)) + if target_page is not None and fragment not in target_page.ids: + errors.append(f"{where}: no anchor #{fragment} in {target_rel}") + if not scripted and rel not in exempt: + text = " ".join(page.text) + for pattern in forbid: + found = pattern.search(text) + if found: + errors.append(f"{rel}: forbidden text {found.group(0)!r} (pattern {pattern.pattern})") + for href, line in page.links: + if pattern.search(href): + errors.append(f"{rel}:{line}: forbidden link {href} (pattern {pattern.pattern})") + return errors, len(pages) + + +def check_sources(roots, forbid): + errors = [] + for top in roots: + for dirpath, _dirs, files in os.walk(top): + for name in sorted(files): + if not name.endswith((".org", ".md", ".rst", ".py", ".el")): + continue + path = os.path.join(dirpath, name) + with open(path, encoding="utf-8", errors="replace") as handle: + for number, line in enumerate(handle, 1): + for pattern in forbid: + found = pattern.search(line) + if found: + errors.append(f"{path}:{number}: forbidden text {found.group(0)!r}") + return errors + + +def main(argv): + parser = argparse.ArgumentParser(description=__doc__.split("\n", 1)[0]) + parser.add_argument("site", help="the built HTML directory") + parser.add_argument("--sources", action="append", default=[], help="a source tree to scan for forbidden text") + parser.add_argument("--forbid", action="append", default=[], help="another forbidden regular expression") + parser.add_argument("--no-default-forbid", action="store_true", help="drop the default forbidden patterns") + parser.add_argument("--exempt", action="append", default=[], metavar="PAGE", + help="a built page, relative to the site, whose text is not checked for forbidden names") + args = parser.parse_args(argv) + if not os.path.isfile(os.path.join(args.site, "index.html")): + print(f"check_site: no index.html in {args.site}", file=sys.stderr) + return 2 + patterns = ([] if args.no_default_forbid else DEFAULT_FORBID) + args.forbid + forbid = [re.compile(p, re.I) for p in patterns] + errors, count = check_site(args.site, forbid, set(args.exempt)) + errors += check_sources(args.sources, forbid) + for error in errors: + print(error) + print(f"check_site: {count} pages, {len(errors)} problem(s)", file=sys.stderr) + return 1 if errors else 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/docs/tools/zig_api.zig b/docs/tools/zig_api.zig new file mode 100644 index 0000000..d4a6a7a --- /dev/null +++ b/docs/tools/zig_api.zig @@ -0,0 +1,617 @@ +//! Write the API reference of a Zig module as MyST pages for Sphinx. +//! +//! zig run docs/tools/zig_api.zig -- --module NAME --root FILE --out DIR +//! [--source-url URL] [--title TEXT] [--follow-private-imports] +//! +//! The parser is std.zig.Ast, the one the compiler uses. From the root file +//! it follows every `@import("x.zig")` bound to a `pub` declaration (and to +//! any declaration with --follow-private-imports, which an executable needs: +//! its files are rarely imported as `pub`). Each file becomes one page, +//! `.md`, holding its `//!` comment and one `zig:` directive +//! per `pub` declaration, with its `///` comment as the body. Fields of a +//! container and the `pub` declarations inside it are nested under it. A +//! file imported along several paths takes the shortest of `pub` imports, +//! or of any imports when there is none. `index.md` lists the pages. An import of another package, such as +//! `@import("zig_common")`, is not followed; intersphinx links to that +//! package's own site. +//! +//! `{ref}` in the source URL becomes $DOCS_SOURCE_REF, else $GITHUB_SHA, +//! else `main`, so a page built in CI links to the commit it was built from. +//! DIR is emptied first: it holds only generated pages. +const std = @import("std"); +const Ast = std.zig.Ast; +const Allocator = std.mem.Allocator; +const Io = std.Io; +const Writer = std.Io.Writer; + +const usage = + \\usage: zig_api --module NAME --root FILE --out DIR [--source-url URL] + \\ [--title TEXT] [--follow-private-imports] + \\ +; + +const Options = struct { + module: []const u8 = "", + root: []const u8 = "", + out: []const u8 = "", + source_url: []const u8 = "", + title: []const u8 = "", + follow_private: bool = false, +}; + +const Kind = enum { + module, + type, + errorset, + function, + constant, + variable, + + fn directive(k: Kind) []const u8 { + return switch (k) { + .module => "zig:module", + .type => "zig:type", + .errorset => "zig:errorset", + .function => "zig:function", + .constant => "zig:constant", + .variable => "zig:variable", + }; + } + + fn heading(k: Kind) []const u8 { + return switch (k) { + .module => "Modules", + .type => "Types", + .errorset => "Error sets", + .function => "Functions", + .constant => "Constants", + .variable => "Variables", + }; + } +}; + +/// One file to document: the dotted name it is published under and its path. +const Page = struct { + fqn: []const u8, + path: []const u8, + summary: []const u8 = "", + /// Reached from the root through `pub` imports alone, so the autodoc + /// site, which shows only those, has its declarations. + public: bool = false, +}; + +const Ctx = struct { + gpa: Allocator, + io: Io, + opts: Options, + pages: std.ArrayList(Page) = .empty, + seen: std.StringHashMapUnmanaged(void) = .empty, +}; + +fn fail(comptime fmt: []const u8, args: anytype) noreturn { + std.debug.print("zig_api: " ++ fmt ++ "\n", args); + std.process.exit(2); +} + +/// Read the options, empty the --out directory, and write there one page +/// per file reached from --root, and the index. +pub fn main(init: std.process.Init) !void { + const arena = init.arena.allocator(); + const args = try init.minimal.args.toSlice(arena); + var opts: Options = .{}; + var i: usize = 1; + while (i < args.len) : (i += 1) { + const a = args[i]; + if (std.mem.eql(u8, a, "--follow-private-imports")) { + opts.follow_private = true; + continue; + } + if (std.mem.eql(u8, a, "-h") or std.mem.eql(u8, a, "--help")) { + std.debug.print("{s}", .{usage}); + return; + } + if (i + 1 >= args.len) fail("{s} needs a value\n{s}", .{ a, usage }); + const v = args[i + 1]; + i += 1; + if (std.mem.eql(u8, a, "--module")) { + opts.module = v; + } else if (std.mem.eql(u8, a, "--root")) { + opts.root = v; + } else if (std.mem.eql(u8, a, "--out")) { + opts.out = v; + } else if (std.mem.eql(u8, a, "--source-url")) { + opts.source_url = v; + } else if (std.mem.eql(u8, a, "--title")) { + opts.title = v; + } else { + fail("unknown option {s}\n{s}", .{ a, usage }); + } + } + if (opts.module.len == 0 or opts.root.len == 0 or opts.out.len == 0) fail("{s}", .{usage}); + const ref = init.environ_map.get("DOCS_SOURCE_REF") orelse init.environ_map.get("GITHUB_SHA") orelse "main"; + opts.source_url = try std.mem.replaceOwned(u8, arena, opts.source_url, "{ref}", ref); + + var ctx: Ctx = .{ .gpa = arena, .io = init.io, .opts = opts }; + try Io.Dir.cwd().deleteTree(init.io, opts.out); + try Io.Dir.cwd().createDirPath(init.io, opts.out); + try collect(&ctx); + for (ctx.pages.items) |*page| try writePage(&ctx, page); + try writeIndex(&ctx); +} + +fn readSource(ctx: *Ctx, path: []const u8) ![:0]const u8 { + return Io.Dir.cwd().readFileAllocOptions(ctx.io, path, ctx.gpa, .limited(64 << 20), .of(u8), 0) catch |err| + fail("cannot read {s}: {s}", .{ path, @errorName(err) }); +} + +fn parse(ctx: *Ctx, path: []const u8) !Ast { + const source = try readSource(ctx, path); + const tree = try Ast.parse(ctx.gpa, source, .{}); + if (tree.errors.len != 0) { + const e = tree.errors[0]; + const loc = tree.tokenLocation(0, e.token); + fail("{s}:{d}:{d}: does not parse ({s})", .{ path, loc.line + 1, loc.column + 1, @tagName(e.tag) }); + } + return tree; +} + +/// Find the files to document, breadth first, so each gets its shortest +/// name: through `pub` imports when it has one, which is the name the +/// autodoc knows, else through any import. +fn collect(ctx: *Ctx) !void { + try addPage(ctx, ctx.opts.module, ctx.opts.root, true); + try walk(ctx, true); + if (ctx.opts.follow_private) try walk(ctx, false); +} + +/// Add the files imported by the pages found so far, and by the pages +/// added meanwhile: by `pub` declarations of public pages, or by any +/// declaration of any page. +fn walk(ctx: *Ctx, public: bool) !void { + var i: usize = 0; + while (i < ctx.pages.items.len) : (i += 1) { + const page = ctx.pages.items[i]; + if (public and !page.public) continue; + var tree = try parse(ctx, page.path); + for (tree.rootDecls()) |decl| { + const vd = tree.fullVarDecl(decl) orelse continue; + if (public and vd.visib_token == null) continue; + const target = importPath(&tree, vd) orelse continue; + const name = tree.tokenSlice(vd.ast.mut_token + 1); + const fqn = try std.fmt.allocPrint(ctx.gpa, "{s}.{s}", .{ page.fqn, name }); + try addPage(ctx, fqn, try importedFile(ctx, page.path, target), public); + } + } +} + +fn addPage(ctx: *Ctx, fqn: []const u8, path: []const u8, public: bool) !void { + const gop = try ctx.seen.getOrPut(ctx.gpa, path); + if (gop.found_existing) return; + var tree = try parse(ctx, path); + try ctx.pages.append(ctx.gpa, .{ + .fqn = fqn, + .path = path, + .summary = try firstSentence(ctx.gpa, try containerDoc(ctx.gpa, &tree)), + .public = public, + }); +} + +/// The path of the file that `@import(target)` in the file `from` names. +fn importedFile(ctx: *Ctx, from: []const u8, target: []const u8) ![]const u8 { + return std.fs.path.join(ctx.gpa, &.{ std.fs.path.dirname(from) orelse ".", target }); +} + +/// The dotted name of the page for the file `@import(target)` in the file +/// `from` names; another path to that file may have given it its name. +fn pageOf(ctx: *Ctx, from: []const u8, target: []const u8) ![]const u8 { + const path = try importedFile(ctx, from, target); + for (ctx.pages.items) |page| { + if (std.mem.eql(u8, page.path, path)) return page.fqn; + } + fail("{s} imports {s}, which has no page", .{ from, path }); +} + +/// The file a declaration `@import`s, when it names a `.zig` file. +fn importPath(tree: *const Ast, vd: Ast.full.VarDecl) ?[]const u8 { + const init_node = vd.ast.init_node.unwrap() orelse return null; + switch (tree.nodeTag(init_node)) { + .builtin_call_two, .builtin_call_two_comma, .builtin_call, .builtin_call_comma => {}, + else => return null, + } + if (!std.mem.eql(u8, tree.tokenSlice(tree.nodeMainToken(init_node)), "@import")) return null; + var buf: [2]Ast.Node.Index = undefined; + const params = tree.builtinCallParams(&buf, init_node) orelse return null; + if (params.len != 1 or tree.nodeTag(params[0]) != .string_literal) return null; + const lit = tree.tokenSlice(tree.nodeMainToken(params[0])); + if (lit.len < 2) return null; + const name = lit[1 .. lit.len - 1]; + if (!std.mem.endsWith(u8, name, ".zig")) return null; + return name; +} + +/// The `//!` lines at the top of a file, without the marker. +fn containerDoc(gpa: Allocator, tree: *const Ast) ![]const u8 { + var out: Writer.Allocating = .init(gpa); + var tok: Ast.TokenIndex = 0; + while (tok < tree.tokens.len and tree.tokenTag(tok) == .container_doc_comment) : (tok += 1) { + try out.writer.print("{s}\n", .{stripMarker(tree.tokenSlice(tok))}); + } + return out.written(); +} + +/// The `///` lines directly above the token, without the marker. +fn docComment(gpa: Allocator, tree: *const Ast, first: Ast.TokenIndex) ![]const u8 { + var start = first; + while (start > 0 and tree.tokenTag(start - 1) == .doc_comment) start -= 1; + var out: Writer.Allocating = .init(gpa); + var tok = start; + while (tok < first) : (tok += 1) { + try out.writer.print("{s}\n", .{stripMarker(tree.tokenSlice(tok))}); + } + return out.written(); +} + +/// The name an identifier token spells: `@"rename-fallback"` is +/// rename-fallback. Anchors and cross-references use this form; the +/// signature keeps the source's. +fn identName(token: []const u8) []const u8 { + if (token.len >= 3 and std.mem.startsWith(u8, token, "@\"") and token[token.len - 1] == '"') + return token[2 .. token.len - 1]; + return token; +} + +fn stripMarker(line: []const u8) []const u8 { + var s = line[3..]; + if (s.len > 0 and s[0] == ' ') s = s[1..]; + return std.mem.trimEnd(u8, s, " \t\r"); +} + +fn firstSentence(gpa: Allocator, doc: []const u8) ![]const u8 { + const para_end = std.mem.indexOf(u8, doc, "\n\n") orelse doc.len; + const para = try collapse(gpa, doc[0..para_end]); + var i: usize = 0; + while (i + 1 < para.len) : (i += 1) { + if (para[i] == '.' and para[i + 1] == ' ') return para[0 .. i + 1]; + } + return para; +} + +/// Source text with every run of whitespace, newlines included, made one space. +fn collapse(gpa: Allocator, text: []const u8) ![]const u8 { + var out: std.ArrayList(u8) = .empty; + var space = false; + for (text) |c| { + if (std.ascii.isWhitespace(c)) { + space = out.items.len > 0; + continue; + } + if (space) try out.append(gpa, ' '); + space = false; + // zig fmt leaves a comma before a closing bracket on a wrapped list. + if ((c == ')' or c == '}' or c == ']') and out.items.len > 1 and + out.items[out.items.len - 1] == ' ' and out.items[out.items.len - 2] == ',') + { + out.items.len -= 2; + } + try out.append(gpa, c); + } + return out.items; +} + +fn tokenText(tree: *const Ast, first: Ast.TokenIndex, last: Ast.TokenIndex) []const u8 { + const start = tree.tokenStart(first); + const end = tree.tokenStart(last) + tree.tokenSlice(last).len; + return tree.source[start..end]; +} + +fn lineOf(tree: *const Ast, tok: Ast.TokenIndex) usize { + return tree.tokenLocation(0, tok).line + 1; +} + +const Member = struct { + kind: Kind, + name: []const u8, + signature: []const u8, + doc: []const u8, + line: usize, + /// For a container: its node, to document fields and nested declarations. + container: ?Ast.Node.Index = null, + /// For an error set: its node, to list the error names. + errors: ?Ast.Node.Index = null, + /// For an imported file: the `@import` operand, such as "proc.zig". + import: []const u8 = "", +}; + +fn isContainer(tree: *const Ast, node: Ast.Node.Index) bool { + return switch (tree.nodeTag(node)) { + .container_decl, + .container_decl_trailing, + .container_decl_arg, + .container_decl_arg_trailing, + .container_decl_two, + .container_decl_two_trailing, + .tagged_union, + .tagged_union_trailing, + .tagged_union_enum_tag, + .tagged_union_enum_tag_trailing, + .tagged_union_two, + .tagged_union_two_trailing, + => true, + else => false, + }; +} + +fn isTypeName(name: []const u8) bool { + return name.len > 0 and std.ascii.isUpper(name[0]) or std.mem.endsWith(u8, name, "_t"); +} + +/// The declarations of one container worth a directive: `pub` ones, plus +/// every field. Returns them in source order. +fn members(ctx: *Ctx, tree: *const Ast, decls: []const Ast.Node.Index, fields: *std.ArrayList(Member)) !std.ArrayList(Member) { + var list: std.ArrayList(Member) = .empty; + const gpa = ctx.gpa; + for (decls) |decl| { + switch (tree.nodeTag(decl)) { + .container_field_init, .container_field_align, .container_field => { + var cf = tree.fullContainerField(decl).?; + cf.convertToNonTupleLike(tree); + if (cf.ast.tuple_like) continue; + const first = cf.firstToken(); + try fields.append(gpa, .{ + .kind = .constant, + .name = identName(tree.tokenSlice(cf.ast.main_token)), + .signature = try collapse(gpa, tokenText(tree, first, tree.lastToken(decl))), + .doc = try docComment(gpa, tree, first), + .line = lineOf(tree, first), + }); + }, + .fn_decl, .fn_proto, .fn_proto_multi, .fn_proto_one, .fn_proto_simple => { + var buf: [1]Ast.Node.Index = undefined; + const fp = tree.fullFnProto(&buf, decl).?; + if (fp.visib_token == null) continue; + const name_tok = fp.name_token orelse continue; + const proto = if (tree.nodeTag(decl) == .fn_decl) tree.nodeData(decl).node_and_node[0] else decl; + try list.append(gpa, .{ + .kind = .function, + .name = identName(tree.tokenSlice(name_tok)), + .signature = try collapse(gpa, tokenText(tree, fp.firstToken(), tree.lastToken(proto))), + .doc = try docComment(gpa, tree, fp.firstToken()), + .line = lineOf(tree, fp.firstToken()), + }); + }, + .global_var_decl, .local_var_decl, .simple_var_decl, .aligned_var_decl => { + const vd = tree.fullVarDecl(decl).?; + if (vd.visib_token == null) continue; + const name = identName(tree.tokenSlice(vd.ast.mut_token + 1)); + const first = vd.firstToken(); + var m: Member = .{ + .kind = if (tree.tokenTag(vd.ast.mut_token) == .keyword_var) .variable else .constant, + .name = name, + .signature = "", + .doc = try docComment(gpa, tree, first), + .line = lineOf(tree, first), + }; + const init_node = vd.ast.init_node.unwrap(); + const head_end: Ast.TokenIndex = if (init_node) |n| tree.firstToken(n) - 1 else tree.lastToken(decl); + const head = try collapse(gpa, tokenText(tree, first, head_end)); + if (init_node) |n| { + if (importPath(tree, vd)) |target| { + m.kind = .module; + m.import = target; + m.signature = try collapse(gpa, tokenText(tree, first, tree.lastToken(n))); + } else if (m.kind == .constant and isContainer(tree, n)) { + var cbuf: [2]Ast.Node.Index = undefined; + const cd = tree.fullContainerDecl(&cbuf, n).?; + const lbrace = brace: { + var t = cd.ast.main_token; + while (tree.tokenTag(t) != .l_brace) t += 1; + break :brace t; + }; + m.kind = .type; + m.container = n; + m.signature = try std.fmt.allocPrint(gpa, "{s} {s}", .{ head, try collapse(gpa, tokenText(tree, tree.firstToken(n), lbrace - 1)) }); + } else if (m.kind == .constant and (tree.nodeTag(n) == .error_set_decl or tree.nodeTag(n) == .merge_error_sets)) { + m.kind = .errorset; + m.errors = n; + m.signature = try std.fmt.allocPrint(gpa, "{s} {s}", .{ head, if (tree.nodeTag(n) == .error_set_decl) "error{...}" else try collapse(gpa, tree.getNodeSource(n)) }); + } else { + const value = try collapse(gpa, tree.getNodeSource(n)); + if (m.kind == .constant and isTypeName(name)) m.kind = .type; + m.signature = if (value.len <= 72 and std.mem.indexOfScalar(u8, value, '{') == null) + try std.fmt.allocPrint(gpa, "{s} {s}", .{ head, value }) + else + try std.fmt.allocPrint(gpa, "{s} ...", .{head}); + } + } else { + m.signature = head; + } + try list.append(gpa, m); + }, + else => {}, + } + } + return list; +} + +fn writePage(ctx: *Ctx, page: *Page) !void { + const gpa = ctx.gpa; + var tree = try parse(ctx, page.path); + var out: Writer.Allocating = .init(gpa); + const w = &out.writer; + + try w.print("# {s}\n\n", .{page.fqn}); + try w.print("::::{{zig:module}} {s}\n:file: {s}\n", .{ page.fqn, page.path }); + if (ctx.opts.source_url.len > 0) try w.print(":source: {s}{s}\n", .{ ctx.opts.source_url, page.path }); + if (!page.public) try w.writeAll(":no-autodoc:\n"); + try w.writeAll("\n"); + try writeDoc(w, try containerDoc(gpa, &tree)); + try w.writeAll("::::\n\n"); + + var fields: std.ArrayList(Member) = .empty; + const list = try members(ctx, &tree, tree.rootDecls(), &fields); + inline for (.{ Kind.module, Kind.type, Kind.errorset, Kind.function, Kind.constant, Kind.variable }) |kind| { + var any = false; + for (list.items) |m| { + if (m.kind != kind) continue; + if (!any) try w.print("## {s}\n\n", .{kind.heading()}); + any = true; + if (kind == .module) { + // The imported file's own page declares the module. + const target = try pageOf(ctx, page.path, m.import); + try w.print("- {{zig:mod}}`{s}`: ", .{target}); + try writeProse(w, summaryOf(ctx, target)); + try w.writeAll("\n"); + } else { + try writeMember(ctx, w, &tree, page, page.fqn, m); + } + } + if (kind == .module and any) try w.writeAll("\n"); + } + + const name = try std.fmt.allocPrint(gpa, "{s}.md", .{page.fqn}); + var dir = try Io.Dir.cwd().openDir(ctx.io, ctx.opts.out, .{}); + defer dir.close(ctx.io); + try dir.writeFile(ctx.io, .{ .sub_path = name, .data = out.written() }); +} + +fn summaryOf(ctx: *Ctx, fqn: []const u8) []const u8 { + for (ctx.pages.items) |page| { + if (std.mem.eql(u8, page.fqn, fqn)) return page.summary; + } + return ""; +} + +/// Colons for a directive that holds `depth` levels of nested directives. +fn fence(gpa: Allocator, depth: usize) ![]const u8 { + const f = try gpa.alloc(u8, 3 + depth); + @memset(f, ':'); + return f; +} + +fn nesting(ctx: *Ctx, tree: *const Ast, m: Member) !usize { + const n = m.container orelse return if (m.errors != null) 1 else 0; + var cbuf: [2]Ast.Node.Index = undefined; + const cd = tree.fullContainerDecl(&cbuf, n).?; + var fields: std.ArrayList(Member) = .empty; + const inner = try members(ctx, tree, cd.ast.members, &fields); + var deepest: usize = if (fields.items.len > 0) 1 else 0; + for (inner.items) |child| deepest = @max(deepest, 1 + try nesting(ctx, tree, child)); + return deepest; +} + +fn writeMember(ctx: *Ctx, w: *Writer, tree: *const Ast, page: *const Page, parent: []const u8, m: Member) !void { + const gpa = ctx.gpa; + const fqn = try std.fmt.allocPrint(gpa, "{s}.{s}", .{ parent, m.name }); + const colons = try fence(gpa, try nesting(ctx, tree, m)); + try w.print("{s}{{{s}}} {s}\n", .{ colons, m.kind.directive(), fqn }); + try w.print(":signature: {s}\n", .{m.signature}); + if (ctx.opts.source_url.len > 0) try w.print(":source: {s}{s}#L{d}\n", .{ ctx.opts.source_url, page.path, m.line }); + if (!page.public) try w.writeAll(":no-autodoc:\n"); + try w.writeAll("\n"); + try writeDoc(w, m.doc); + + if (m.errors) |n| try writeErrors(ctx, w, tree, n, fqn); + if (m.container) |n| { + var cbuf: [2]Ast.Node.Index = undefined; + const cd = tree.fullContainerDecl(&cbuf, n).?; + var fields: std.ArrayList(Member) = .empty; + const inner = try members(ctx, tree, cd.ast.members, &fields); + for (fields.items) |f| { + try w.print(":::{{zig:field}} {s}.{s}\n:signature: {s}\n", .{ fqn, f.name, f.signature }); + if (ctx.opts.source_url.len > 0) try w.print(":source: {s}{s}#L{d}\n", .{ ctx.opts.source_url, page.path, f.line }); + try w.writeAll("\n"); + try writeDoc(w, f.doc); + try w.writeAll(":::\n\n"); + } + for (inner.items) |child| try writeMember(ctx, w, tree, page, fqn, child); + } + try w.print("{s}\n\n", .{colons}); +} + +/// Each name of an `error{...}` set, with its `///` comment. +fn writeErrors(ctx: *Ctx, w: *Writer, tree: *const Ast, node: Ast.Node.Index, fqn: []const u8) !void { + if (tree.nodeTag(node) != .error_set_decl) return; + const lbrace, const rbrace = tree.nodeData(node).token_and_token; + var tok = lbrace + 1; + while (tok < rbrace) : (tok += 1) { + if (tree.tokenTag(tok) != .identifier) continue; + try w.print(":::{{zig:error}} {s}.{s}\n:signature: error.{s}\n\n", .{ fqn, identName(tree.tokenSlice(tok)), tree.tokenSlice(tok) }); + try writeDoc(w, try docComment(ctx.gpa, tree, tok)); + try w.writeAll(":::\n\n"); + } +} + +/// A doc comment as MyST: Markdown already, except that a heading cannot sit +/// inside a directive, so it becomes a bold line. +fn writeDoc(w: *Writer, doc: []const u8) !void { + if (std.mem.trim(u8, doc, " \n").len == 0) return; + var lines = std.mem.splitScalar(u8, std.mem.trimEnd(u8, doc, "\n"), '\n'); + var in_code = false; + while (lines.next()) |line| { + if (std.mem.startsWith(u8, std.mem.trimStart(u8, line, " "), "```")) { + in_code = !in_code; + try w.print("{s}\n", .{line}); + continue; + } + if (in_code) { + try w.print("{s}\n", .{line}); + } else if (std.mem.startsWith(u8, line, "#")) { + const text = std.mem.trim(u8, std.mem.trimStart(u8, line, "#"), " "); + try w.writeAll("**"); + try writeProse(w, text); + try w.writeAll("**\n"); + } else { + try writeProse(w, line); + try w.writeAll("\n"); + } + } + try w.writeAll("\n"); +} + +/// One line of doc comment prose, with the syntax MyST adds to Markdown, and +/// Zig's autodoc does not have, escaped outside code spans: a footnote +/// reference `[^x]` (a regular expression's negated class) and a `%` comment +/// line. +fn writeProse(w: *Writer, line: []const u8) !void { + return writeEscaped(w, line, false); +} + +/// writeProse for a table cell, where a pipe ends the cell, inside a code +/// span too. +fn writeCell(w: *Writer, text: []const u8) !void { + return writeEscaped(w, text, true); +} + +fn writeEscaped(w: *Writer, line: []const u8, cell: bool) !void { + const indent = line.len - std.mem.trimStart(u8, line, " ").len; + var in_span = false; + for (line, 0..) |c, i| { + if (c == '`') in_span = !in_span; + const footnote = !in_span and c == '[' and i + 1 < line.len and line[i + 1] == '^'; + const comment = i == indent and c == '%'; + if (footnote or comment or (cell and c == '|')) try w.writeByte('\\'); + try w.writeByte(c); + } +} + +fn writeIndex(ctx: *Ctx) !void { + var out: Writer.Allocating = .init(ctx.gpa); + const w = &out.writer; + const title = if (ctx.opts.title.len > 0) ctx.opts.title else "Zig API"; + try w.print("# {s}\n\n", .{title}); + try w.print("Generated from the doc comments of `{s}` by `docs/tools/zig_api.zig`.\n", .{ctx.opts.module}); + try w.writeAll("Each page is one source file; the `pub` declarations are grouped by kind in source order.\n"); + try w.writeAll("Every declaration links to its source line and, where the {zig:autodoc}`Zig autodoc ` build has it, to the same declaration there.\n"); + try w.writeAll("\n| Module | Summary |\n|---|---|\n"); + for (ctx.pages.items) |page| { + try w.print("| {{zig:mod}}`{s}` | ", .{page.fqn}); + try writeCell(w, page.summary); + try w.writeAll(" |\n"); + } + try w.writeAll("\n```{toctree}\n:hidden:\n:maxdepth: 1\n\n"); + for (ctx.pages.items) |page| try w.print("{s}\n", .{page.fqn}); + try w.writeAll("```\n"); + var dir = try Io.Dir.cwd().openDir(ctx.io, ctx.opts.out, .{}); + defer dir.close(ctx.io); + try dir.writeFile(ctx.io, .{ .sub_path = "index.md", .data = out.written() }); +} diff --git a/docs/topics/concepts.md b/docs/topics/concepts.md deleted file mode 100644 index 916892e..0000000 --- a/docs/topics/concepts.md +++ /dev/null @@ -1,18 +0,0 @@ -# Concepts - -The EESSI module picks a CPU target once, at load time, and an accelerator target the same way. Both are written into `MODULEPATH` and into the paths later modules export. Slurm sends that environment to the job. A task that lands on another CPU or GPU then runs the submitting machine's binaries. - -`module load EESSI/` inside the job runs the EESSI module again, with its own detection, and moves `MODULEPATH` to the tree that detection picks. The other loaded modules stay recorded for the old tree, and Lmod marks them inactive. `module reload`, unload/load, and swap leave the other modules inactive too. The sequence that changes the stack is: list `LOADEDMODULES`, `module --force purge`, `module load EESSI/` by that full name, then load the other names in the same order. - -```{figure} concepts.svg -:alt: Submit host, TaskProlog, and the match or reload branches -:width: 100% - -The prolog compares the loaded target with the node, then either returns or reloads. -``` - -The comparison is local to the task. CPU flags come from `EESSI_PROC_CPUINFO` or `/proc/cpuinfo`, limited to the processors in the task's cpuset, affinity mask, and Slurm CPU bind list. The accelerator string comes from `eessi_archdetect.sh accelpath`, which sees the GPUs visible to the task. A job prolog runs outside the task cgroup, so a GPU hidden from the task is still visible there. The TaskProlog runs as the user, with the task environment, before `execve`. - -On a mismatch the prolog runs a helper, `python3 -I -X utf8 --restore`, whose stdin is a JSON request carrying the task environment. The helper's own process environment is `PATH`, `HOME`, `LANG`, `LC_ALL`, `TMPDIR`, and `EESSI_ARCH_GUARD_WORKDIR`. Module names are arguments to `LMOD_CMD` after a grammar check. Bash inside the helper is `bash --noprofile --norc`, with `BASH_ENV`, `ENV`, `SHELLOPTS`, `BASHOPTS`, `BASH_XTRACEFD`, and `PS4` removed, and its last command is `env -0`. The prolog prints the delta of that environment: `export` and `unset` lines Slurm can apply, plus one `print` line for local task 0. - -The [detection](detection.md) topic is the CPU and accelerator walk. [What the guard emits](output.md) is the delta, the cache, and the deadline. [Design](design.md) records why this shape was kept. diff --git a/docs/topics/concepts.svg b/docs/topics/concepts.svg deleted file mode 100644 index 330de1a..0000000 --- a/docs/topics/concepts.svg +++ /dev/null @@ -1,48 +0,0 @@ - - - - - Submit host - module load EESSI/version runs eessi_archdetect.sh once. - The module records EESSI_SOFTWARE_SUBDIR, EESSI_ACCEL_SUBDIR, - MODULEPATH, and the EBROOT* paths of every loaded module. - - - Slurm copies that environment into the task - - TaskProlog on the compute node - CPU: eessi_archdetect.sh -a cpupath, then the first installed candidate - whose march still has waitpkg when that march requires the flag. - Accelerator: eessi_archdetect.sh accelpath, compared with - EESSI_ACCEL_SUBDIR. A non-zero accelpath means no accelerator. - - - - - - Targets match - The CPU directory and the accelerator - string are the ones already loaded. - The prolog prints no export lines. - The process exits 0. - - Targets differ - python3 -I -X utf8 file --restore - module --force purge - module load EESSI/version - module load of the other names, in order - The prolog prints export and unset lines. - slurmstepd applies them, then execve. - - A chained prolog that exits non-zero becomes the TaskProlog status. - Every other path exits 0. A loud failure still lets the task start. - diff --git a/docs/topics/design.md b/docs/topics/design.md deleted file mode 100644 index e40e992..0000000 --- a/docs/topics/design.md +++ /dev/null @@ -1,44 +0,0 @@ -# Design - -The repository file `DESIGN.md` is the design record. This page is the part a user or an admin needs in order to see why the prolog prints a delta. - -## What runs - -1. Decide, in Python, whether this node is the target the loaded modules were built for. The CPU and accelerator walks are [Detection and matching](detection.md). -2. On a mismatch, restore modules in a helper: the same file, exec'd as `python3 -I -X utf8 --restore`. The task environment is JSON on stdin. Each name and value crosses as one Latin-1 character per environment byte, and `-X utf8` turns that text back into those bytes for Lmod, so a prefix that is not valid UTF-8 is the same path Lmod opens. -3. Emit the delta, and only lines Slurm can apply. The rules are [What the guard emits](output.md). -4. Refuse module names that fail the grammar in the [environment reference](../reference/environment.md). The loaded list has to contain exactly one `EESSI/` name. A bad name is a failed restore. -5. Fail loud, and still exit 0. A missing software directory, a broken archdetect, an unusable `LMOD_CMD`, an unsafe name, or a module that will not load sets `EESSI_ARCH_GUARD_FAILED` and prints one line. Exit 0 is required: on current Slurm master, a non-zero TaskProlog status is `_exit(status)` and the task never runs. - -## What was checked in Slurm - -Checked on Slurm `master` `src/slurmd/slurmstepd/task.c` (public source) and, separately, on Ubuntu's slurm-wlm 23.11.4 started by hand in one VM. That VM did run this prolog for both an `srun` step and a batch step. The site's Slurm version is not known here; see Out of scope, below. Master behaving this way is evidence about the public source. - -* `exec_task` calls the configured TaskProlog with no `!step->batch` guard. The batch step is included. The `!step->batch` checks in that function are for the switch plugin and MPI. -* The prolog is started with `SLURM_SCRIPT_CONTEXT=prolog_task`. -* The value after `=` in an `export` line is passed to `setenv` as literal text. `$` and backticks are not shell syntax there. A newline is a new command. -* A non-zero wait status is returned after that parse, and `exec_task` then exits. Exports from a failing prolog are applied, and the task still dies. This program returns non-zero only when a chained prolog did. -* `_make_tmpdir` runs after the prologs, and only for local task 0. A per-job `TMPDIR` may not exist yet. The cache falls back to `/tmp`. The prolog omits `TMPDIR` from the delta. - -`srun --export=ALL,X=y` leaves an `X` already in the environment in place: on Slurm 23.11.4, with `EESSI_ARCH_GUARD=1` set, `--export=ALL,EESSI_ARCH_GUARD=0` gave the task `1`. Opt-out belongs in the submitting environment. - -## Closed alternatives - -| Approach | What happens | -| --- | --- | -| CVMFS variant symlink per node | Module roots and `DT_RPATH` are absolute per target. The task opens the submitting node's files. Confirmed from `init/modules/EESSI/2023.06.lua` at software-layer-scripts `26441ca`. | -| Re-check inside the EESSI module file | The file runs when a `module` command loads it, and nothing loads it in a task before `execve`. Loading it again re-runs it, but the other loaded modules go inactive. | -| Lmod hook on every `module` command | The hook runs for module commands. A bare exec never calls one. It would also run on every load for a check that happens once per task. | -| `BASH_ENV` as the carrier | A bare `srun` of a binary never sources it. Lmod already uses `BASH_ENV`. The reload shell removes it. | -| `--export=NONE` as a site default | Job scripts lose the environment they were written against. A user can still pass it on one command. | -| Job prolog | The script runs as root, once per job, outside the task cgroup. A GPU the cgroup hides from the task is visible there. | -| SPANK or a site C plugin | The guard is one Python file a site can chain from the TaskProlog it already runs. | -| Rewrite `LOADEDMODULES` and `MODULEPATH` in place | Inactive modules stay inactive until the modulefiles run. The purge-and-load sequence is what re-runs them. | - -Re-emitting the child shell's whole environment was the earlier mechanism. It is how the reviewed bugs happen: `bash --noprofile --norc` still sources `BASH_ENV` (confirmed on bash 5.2.21); an unchecked module name can smuggle a second prolog directive; a missing software directory returned an empty result; a newline in one value dropped that key and kept the others; a write error could exit non-zero; the cache followed a symlink. The helper plus the whitelist is the path that closes those classes. - -## Out of scope - -Unanswered here: whether a site already has a TaskProlog, which Slurm version it runs, the cost on a node that runs a task on every core with node-local `TMPDIR`, and a real cross-target job on production nodes. Those measurements are absent from this repository. - -Binaries built with `-march=native` on a login node, virtualenvs with compiled wheels from that node, and a module that has no build for the target stay as they are. The guard reports the missing module and leaves the environment unchanged. `python3 tests/measure_noop.py` prints a same-target timing on the machine where it is run. Treat that timing as a reading from that machine. diff --git a/docs/topics/detection.md b/docs/topics/detection.md deleted file mode 100644 index b17d6c6..0000000 --- a/docs/topics/detection.md +++ /dev/null @@ -1,106 +0,0 @@ -# Detection and matching - -CPU selection stays inside `eessi_archdetect.sh -a cpupath` plus a directory walk. Subdirectory names come from that script's stdout and from the directories that are mounted. An Intel node with A100 GPUs gets whichever candidate has a software directory. Naming `x86_64/intel/icelake` or `x86_64/intel/skylake_avx512` inside the program would pick the wrong tree on the other of those nodes, and on every AMD node. - -```{figure} detection.svg -:alt: CPU candidate walk beside the accelerator comparison, and the waitpkg pin -:width: 100% - -cpupath is filtered for waitpkg, then the first installed directory wins. accelpath is compared as a string. -``` - -The examples call the stub `tests/stubs/eessi_archdetect.sh`. It implements the argv contract the guard uses, `[-a] cpupath` or `accelpath`. The EESSI script is the one under `EESSI_INIT_PREFIX` on a real node. - -## Requirements before archdetect runs - -`EESSI_PREFIX` and `EESSI_INIT_PREFIX` have to be absolute paths with no `..` segment and no CR, LF, or NUL. `EESSI_OS_TYPE` has to be a relative subdirectory: no empty segment, no `.` or `..`, and each segment matching `[A-Za-z0-9_.+-]+`. A value that fails these checks is an archdetect failure, and the script is not started. - -The script path is `/eessi_archdetect.sh`. It is run as `bash --noprofile --norc`. - -## CPU - -cpupath must print one line, at most 65536 bytes, with no NUL and no character below ASCII 32. The line is split on `:`. Empty fields are dropped. Each candidate has to pass the same relative-subdirectory check. - -The guard then reads CPU flags. The path is `EESSI_PROC_CPUINFO` when that variable is set, otherwise `/proc/cpuinfo`. Every `flags` line is parsed. The set used for the decision is the intersection: one logical CPU missing a flag removes it. The read stops at 16 MiB. - -## The processors the task may run on - -`/proc/cpuinfo` lists every online processor. A cgroup cpuset, the affinity mask, or a Slurm bind can keep the task off some of them. archdetect reads the last processor in the file, so an unbound read can name a microarchitecture the task will never execute. - -Before archdetect runs, the guard intersects three sets, skipping any it cannot read: - -* `sched_getaffinity` of this process -* `cpuset.cpus.effective` of this cgroup, walking up to the ancestor that has one -* `SLURM_CPU_BIND_LIST`, or the value after the last colon of `SLURM_CPU_BIND` when the list is unset - -The bind text is a hex mask (`0x2`), a CPU list (`0-3,8`), or a hostlist whose name is empty or `cpu` (`cpu[0-3,8]`, `[1]`). A node hostlist such as `nid[00001-00002]` is not a CPU list and is ignored. A mask with a bit at or past 4096 is ignored rather than applied in part. - -When the file has `processor` lines and the intersection is a narrower set, or the kept processors do not share one vendor, model, and flag set, archdetect is given one record. Its flags, features, and isa tokens are the intersection of the kept processors. The vendor and model are kept only when every kept processor has the same value, so a Granite Rapids model number is not applied to a mix. A file with no `processor` line, such as an `lscpu` snapshot or a test `eessi_arch_matches` line, is read as it stands. The caller-supplied `EESSI_PROC_CPUINFO` is scoped the same way. - -(detection-waitpkg)= -## The waitpkg check - -archdetect's x86 spec requires the flags that separate one EESSI target from the previous one. GCC `-march` for that target enables a larger set. `waitpkg` (`tpause`, `umwait`, `umonitor`) is in the march mask and absent from the spec, so a virtual machine that hides the flag is still offered `sapphirerapids`. A binary built with that march then dies with `SIGILL`. - -The guard drops a candidate whose leaf is one of these marches when `waitpkg` is missing from the intersection. The leaf spells `-` as `_`. The set is GCC 16 `gcc/config/i386/i386.h` on branch `releases/gcc-16`: the marches GCC 15.2.0 carried, plus `novalake`. `znver6`, the other new mask in that header, has no `WAITPKG`. - -`alderlake`, `arrowlake`, `arrowlake-s`, `clearwaterforest`, `diamondrapids`, `grandridge`, `graniterapids`, `graniterapids-d`, `novalake`, `pantherlake`, `sapphirerapids`, `sierraforest`, `tremont`. - -The other march flags stay unchecked. They are listed in [CPU flags](../reference/cpu_flags.md). - -## The installed directory - -The walk keeps the first remaining candidate for which this path is a directory: - -```text -/software///software -``` - -That directory is the CPU target. When no candidate has a directory, the result is `->no-software-dir` unless `EESSI_ARCH_GUARD_MISSING=ignore`. See [Correct a guard message](../howto/read_failure.md). - -archdetect's own consumer, the EESSI module, walks the unfiltered list. When the directory that survives the waitpkg filter is further down the list than the directory the unfiltered walk would install, the reload sets `EESSI_SOFTWARE_SUBDIR_OVERRIDE` to the filtered directory and removes `EESSI_ARCHDETECT_OPTIONS` for the loads after the purge. A login-node value of `EESSI_ARCHDETECT_OPTIONS` would outrank the pin inside the module. The module's archdetect wrapper then exports `EESSI_ARCHDETECT_OPTIONS` as that one subdirectory. The purge itself runs with the task's value: the module's unload works out from it which tree to take off `MODULEPATH`, and without it Lmod only warns and leaves the loaded tree behind the pinned one. - -If the user already set `EESSI_SOFTWARE_SUBDIR_OVERRIDE` or `EESSI_ARCHDETECT_OPTIONS_OVERRIDE`, the guard skips detection entirely. The pin is the user's. - -## Accelerator - -`eessi_archdetect.sh accelpath` is compared as a raw string with `EESSI_ACCEL_SUBDIR`. - -* A non-zero status is "no accelerator". Exit 2 (no `nvidia-smi`) and exit 3 (`nvidia-smi` failed) are the EESSI script's no-GPU paths. The EESSI wrapper stores that as an empty `EESSI_ACCEL_SUBDIR`. -* Empty stdout on a zero status is "no accelerator". -* Stdout has to match `accel/nvidia/cc` plus digits, or `accel/amd/gfx` plus hexadecimal digits. Any other stdout, including a second line, is `->archdetect-failed`. An A100 is `accel/nvidia/cc80` only when the script prints that string. - -The `ccNN` to `ccN0` directory fallback stays inside the EESSI module. The guard compares the string the script printed. - -`EESSI_ACCELERATOR_TARGET_OVERRIDE` skips this comparison. The CPU walk still runs, and the loaded accelerator value is kept. - -## What a match is - -The CPU target equals `EESSI_SOFTWARE_SUBDIR`, and, when the accelerator is being compared, the accelpath result equals `EESSI_ACCEL_SUBDIR`. Both sides empty counts as a match. The prolog then prints nothing. - -When the accelerator differs, the reload label is ` ` or ` no accel` on each side. The [tutorial](../tutorial/index.md) is the CPU-only case: zen4 loaded, zen2 detected, label `x86_64/amd/zen4->x86_64/amd/zen2`. - -## A GPU that changed - -`docs/examples/accelerator.py mismatch` keeps the CPU at zen4, loads `accel/nvidia/cc90`, and points the stub `nvidia-smi` at compute capability 12.0. `CUDA/12.6.0` exists on both accelerator trees, so the reload completes: - -```text -export EESSI_ACCEL_SUBDIR=accel/nvidia/cc120 -export EESSI_ARCH_GUARD_RELOADED=x86_64/amd/zen4 accel/nvidia/cc90->x86_64/amd/zen4 accel/nvidia/cc120 -print eessi-arch-guard: reloaded modules for x86_64/amd/zen4 accel/nvidia/cc120 (loaded for x86_64/amd/zen4 accel/nvidia/cc90) -``` - -`MODULEPATH` in that run gains the `cc120` modules directory ahead of the zen4 CPU modules. The full transcript also rewrites `PATH` under `$PREFIX`. - -When `CUDA/12.6.0` exists only on `cc90`, the same node prints a failure and leaves the loaded accelerator in place: - -```console -$ python3 docs/examples/accelerator.py missing-module -``` - -```text -export EESSI_ARCH_GUARD_FAILED=x86_64/amd/zen4 accel/nvidia/cc90->x86_64/amd/zen4 accel/nvidia/cc120 -print eessi-arch-guard: this node is x86_64/amd/zen4 accel/nvidia/cc120, the modules were loaded for x86_64/amd/zen4 accel/nvidia/cc90; not available for this target: CUDA/12.6.0; environment left as it was -``` - -Load a CUDA build that exists for `cc120`, or drop `CUDA/12.6.0` from the submitting environment. diff --git a/docs/topics/detection.svg b/docs/topics/detection.svg deleted file mode 100644 index 32e7592..0000000 --- a/docs/topics/detection.svg +++ /dev/null @@ -1,43 +0,0 @@ - - - - - CPU walk - 1. eessi_archdetect.sh -a cpupath - One line. Candidates are separated by colons. - 2. Drop a waitpkg march - when the flag is missing from the - intersection of every flags line. - 3. Walk what remains - Keep the first candidate whose - software directory exists: - prefix/software/os/candidate/software - 4. Compare with the loaded value - EESSI_SOFTWARE_SUBDIR equal to that - directory means the CPU matches. - A cpupath error stops the decision. - No installed directory is a loud failure. - - Accelerator - 1. eessi_archdetect.sh accelpath - 2. A non-zero status, or empty stdout, - means no accelerator. - 3. Stdout must be one subdirectory: - accel/nvidia/ccN or accel/amd/gfx... - 4. Compare that string with - EESSI_ACCEL_SUBDIR. - Anything else on stdout is a failure. - - Waitpkg fallback - When the installed directory on the - unfiltered list needs a missing flag, - the reload sets - EESSI_SOFTWARE_SUBDIR_OVERRIDE - and drops EESSI_ARCHDETECT_OPTIONS. - diff --git a/docs/topics/index.md b/docs/topics/index.md deleted file mode 100644 index 4d65489..0000000 --- a/docs/topics/index.md +++ /dev/null @@ -1,12 +0,0 @@ -# Topics - -Background on how the guard decides, what it prints, and why the mechanism is a TaskProlog plus a checked delta. - -```{toctree} -:maxdepth: 1 - -concepts -detection -output -design -``` diff --git a/docs/topics/output.md b/docs/topics/output.md deleted file mode 100644 index ec35ffe..0000000 --- a/docs/topics/output.md +++ /dev/null @@ -1,63 +0,0 @@ -# What the guard emits - -Prolog mode and `--shell` carry the same decision. The bytes on stdout differ, and the human message uses a different stream, because Slurm has a `print` directive and no stderr form of it. - -## Prolog mode - -Stdout is a series of lines. Each line is `export NAME=value`, `unset NAME`, or `print message`. Names match `^[A-Za-z_][A-Za-z0-9_]*$`. Values must not contain CR, LF, or NUL. A value that cannot be carried aborts the whole restore: the task keeps the environment it arrived with, and the prolog sets `EESSI_ARCH_GUARD_FAILED` to a token ending in `->unsafe-environment`. - -`PS1`, `PS2`, `PS3`, and `PROMPT_COMMAND` are the exception. An unsafe new value for one of those names is left unchanged, and the rest of the delta is still emitted. - -Each line stays within 4094 bytes (`PROLOG_LINE_MAX`). That is the Slurm 17.11 read in `src/slurmd/slurmstepd/task.c`: `fgets(buf, sizeof(buf) - 1)` on `char buf[4096]`. A trim of a message stops on a character boundary. Export values keep the bytes they already had. A failed write is dropped and the process still exits 0. - -The `print` line is emitted when `SLURM_LOCALID` is `0` or unset. Slurm writes it to the task's stdout. A batch script that reads its own stdout will see that line. Other local ranks get the `export` and `unset` lines and no `print` line. - -## Shell mode - -`--shell` prints `export NAME=` and `unset NAME` on stdout, for `eval "$(eessi-arch-guard --shell)"`. The message goes to stderr. The [batch-script how-to](../howto/shell_batch.md) runs that eval. - -## Variables the delta never includes - -These names are omitted from the delta. `TMPDIR` is created by `slurmstepd` after the prolog; exporting it would change the directory Slurm creates. - -`_`, `SHLVL`, `PWD`, `OLDPWD`, `TMPDIR`, `BASH_ENV`, `ENV`, `SHELLOPTS`, `BASHOPTS`, `BASH_XTRACEFD`, `PS4`, `BASH_ARGC`, `BASH_ARGV`, `BASH_LINENO`, `BASH_SOURCE`, `BASH_VERSINFO`, `BASH_VERSION`, `DIRSTACK`, `EPOCHREALTIME`, `EPOCHSECONDS`, `FUNCNAME`, `GROUPS`, `HOSTNAME`, `HOSTTYPE`, `IFS`, `MACHTYPE`, `OPTERR`, `OPTIND`, `OSTYPE`, `PIPESTATUS`, `PPID`. - -Any name starting with `BASH_FUNC_` or `SLURM_` is omitted as well. - -## Markers - -`EESSI_ARCH_GUARD_RELOADED` is `was->now` after a reload that was applied. When the accelerator differs, each side is ` ` or ` no accel`. - -`EESSI_ARCH_GUARD_FAILED` uses the same shape. The token after `->` is fixed when there is no selected target, or when the restore could not run: `no-software-dir`, `archdetect-failed`, `unsafe-module-name`, `unsafe-environment`, `lmod-unavailable`, `restore-failed`, `timeout`, `terminated`. When a target was selected and Lmod refused the load, both sides are the target labels. A successful reload clears a previous `EESSI_ARCH_GUARD_FAILED` by emitting `unset` for it. - -`EESSI_ARCH_GUARD_VERBOSE=1` writes the skip or match reason to stderr. The reason strings are the `detail` field of the decision, for example `target already matches this node`. - -## One decision per step - -Within one job step the first task on a node computes the result and the others read it. The cache file is mode `0600` under `TMPDIR` when that directory exists and is absolute, otherwise under `/tmp`. The name is: - -```text -.eessi-arch-guard...... -``` - -`` is `SLURM_STEP_ID`, or `batch` when that variable is unset. `` is `prolog` or `shell`. The decision depends on the output mode: a value with a newline can be carried by `--shell` and not by a prolog line. A batch script that runs `--shell` after the task prolog therefore computes its own result. There is no cache file when `SLURM_JOB_ID` is unset. ``, ``, and `` are used as-is when they match `^[A-Za-z0-9._-]{1,64}$`; otherwise each is a 16-character SHA-256 prefix. `` is the first 16 hex characters of the SHA-256 of these values joined by NUL: - -`EESSI_SOFTWARE_SUBDIR`, `EESSI_ACCEL_SUBDIR`, `LOADEDMODULES`, `MODULEPATH`, `EESSI_INIT_PREFIX`, `EESSI_PROC_CPUINFO`, `PATH`, the task's allowed processors, and the accelerator visibility. - -The allowed processors are the same intersection the detection uses, written as sorted decimal ids separated by commas. An empty intersection is `-`. No information is an empty field. Accelerator visibility is the values of `CUDA_VISIBLE_DEVICES`, `ROCR_VISIBLE_DEVICES`, `GPU_DEVICE_ORDINAL`, `SLURM_STEP_GPUS`, and `SLURM_GPUS_ON_NODE` that are set, each as `NAME=value` and joined by NUL. Two tasks in one step that do not share a cpuset or a GPU therefore do not share a cache entry. - -`EESSI_ARCH_GUARD` is omitted from the key. Two tasks in one step that differ only by that variable share a result. - -The cache file and the lock are opened with `O_NOFOLLOW`. A symlink at either path is not followed. The cache file is created with `O_EXCL` and published with `rename`. `flock` is assumed to work on the directory. The lock wait shares the decision's deadline. A result already in the cache is returned as stored, including when the wait used the whole deadline. If the cache cannot be used safely, the task computes its own result and does not write through the link. - -A timeout or `SIGTERM` is not written to the cache. A decision that has finished is still published if `SIGTERM` arrives while the file is written. - -Nothing removes the cache file or its lock, the same name plus `.lock`, when the step or the job ends. One pair stays for each user, node, job, step, output mode and key. A per-job `TMPDIR` removed at the end of the job takes them with it; under `/tmp` they stay until the node is cleaned. - -## Deadline - -One deadline covers the lock wait, both archdetect runs, and the restore helper. The default is 60 seconds. Children run in their own sessions. `SIGTERM` is held until the child process group is known, then released. At the deadline, or on `SIGTERM`, the guard sends `SIGKILL` to that group. A child that leaves the group is outside this kill. After the kill the guard still waits up to 5 seconds (`POST_KILL_WAIT_SECONDS`) for the pipe to close, and may wait that long in `communicate` and twice more in `wait`, so the worst case after the kill is 15 seconds. - -The parent removes the helper's work directory when the helper exits, including when the deadline kills it. - -An unexpected exception becomes one skip line (`eessi-arch-guard: skipped, ...`) and exit 0. In prolog mode that line is a `print` directive, and like the message it comes only from the task whose `SLURM_LOCALID` is `0` or unset. In `--shell` it goes to stderr. diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md deleted file mode 100644 index 4293bc6..0000000 --- a/docs/tutorial/index.md +++ /dev/null @@ -1,73 +0,0 @@ -# Reload a mismatched stack - -This tutorial runs the guard from a checkout. The prefix, `eessi_archdetect.sh`, and `LMOD_CMD` are the stubs in `tests/`. The guard itself is `src/eessi_arch_guard.py`. You need Python 3.9 or newer and `bash`. - -The loaded stack is EESSI 2025.06 plus `R/4.4.2`, recorded for `x86_64/amd/zen4`. The fake cpuinfo is a zen2 node, and both CPU trees exist in the prefix. `$PREFIX` in the transcript is the temporary directory the script created. - -## Check the version - -```console -$ python3 src/eessi_arch_guard.py --version -0.2.0 -``` - -## Run the guard on the mismatched stack - -```console -$ python3 docs/examples/walkthrough.py mismatch -``` - -The script prints: - -```text -case: mismatch -loaded: x86_64/amd/zen4 -node cpuinfo: zen2 -command: python3 -I src/eessi_arch_guard.py -exit: 0 ---- stdout --- -export EBROOTR=$PREFIX/prefix/software/linux/x86_64/amd/zen2/software/R/4.4.2 -export EESSI_ACCEL_SUBDIR= -export EESSI_ARCH_GUARD_RELOADED=x86_64/amd/zen4->x86_64/amd/zen2 -export EESSI_SOFTWARE_SUBDIR=x86_64/amd/zen2 -export MODULEPATH=$PREFIX/prefix/software/linux/x86_64/amd/zen2/modules/all -export PATH=$PREFIX/prefix/software/linux/x86_64/amd/zen2/software/R/4.4.2/bin:$PREFIX/prefix/software/linux/x86_64/amd/zen2/bin:$PREFIX/bin:/usr/bin:/bin -export _LMFILES_= -export _ModuleTable001_=table-for-x86_64-amd-zen2 -print eessi-arch-guard: reloaded modules for x86_64/amd/zen2 (loaded for x86_64/amd/zen4) ---- stderr --- -(empty) -``` - -Stdout is the TaskProlog protocol. `export` lines are the environment delta. The `print` line is the message `slurmstepd` writes to the task's stdout when `SLURM_LOCALID` is 0 or unset. `EESSI_ARCH_GUARD_RELOADED` is `was->now`. `EBROOTR` and `MODULEPATH` now point at the zen2 tree. The process exits 0, so Slurm continues with the task. - -How the CPU walk chooses zen2 is covered in [Detection and matching](../topics/detection.md). - -## Run it again on the corrected environment - -The example applies those `export` lines the way `tests/slurm_model.py` reads a TaskProlog, then runs the guard on the result. - -```console -$ python3 docs/examples/walkthrough.py again -case: again -command: python3 -I src/eessi_arch_guard.py -exit: 0 ---- stdout --- -(empty) ---- stderr --- -(empty) -``` - -The loaded subdirectory is the node the second run detects. A match prints nothing. - -Remove the temporary prefix when you are done: - -```console -$ python3 docs/examples/walkthrough.py clean -case: clean -removed: docs/examples/_work -``` - -## Where to go next - -A real job shows the same `print` line. The paths in that line use the site prefix. When the line says the environment was left as it was, follow [Correct a guard message](../howto/read_failure.md). A site that has yet to install the prolog can run the same decision from a batch script with [`--shell`](../howto/shell_batch.md). diff --git a/lychee.toml b/lychee.toml new file mode 100644 index 0000000..dc89792 --- /dev/null +++ b/lychee.toml @@ -0,0 +1,31 @@ +# External links in the built site (pixi run -e docs linkcheck). Internal +# links and anchors are checked offline by docs/tools/check_site.py. +max_retries = 3 +retry_wait_time = 2 +timeout = 20 +max_concurrency = 16 +accept = ["200..=299", "429"] +include_fragments = "none" +cache = true +max_cache_age = "1d" +no_progress = true + +exclude_path = [ + # The Zig autodoc site links only within itself. + "docs/build/html/api/", +] + +exclude = [ + # This site: every page names its published URL as canonical, and a new + # page is not published until this build deploys. check_site.py checks the + # site's own links. + '^https://stackhands\.github\.io/eessi\-arch\-guard/', + # Source links name the commit being built, which a pull request build + # may not have pushed anywhere yet; check_site.py checks the pages. + '^https://github\.com/stackhands/[^/]+/(blob|edit|tree)/', + # A Cloudflare challenge answers automated clients with 403. + '^https://eb-stack\.rgoswami\.me/', + # The repository's own, each with its reason; apply.py keeps this block. + # local:begin + # local:end +] diff --git a/pixi.lock b/pixi.lock new file mode 100644 index 0000000..7081eae --- /dev/null +++ b/pixi.lock @@ -0,0 +1,3859 @@ +version: 7 +platforms: +- name: linux-64 + virtual-packages: + - __unix=0 + - __linux=4.18 + - __glibc=2.28 + - __archspec=0=x86_64 +- name: osx-arm64 + virtual-packages: + - __unix=0 + - __osx=13.0 + - __archspec=0=m1 +environments: + default: + channels: + - url: https://conda.anaconda.org/conda-forge/ + packages: {} + docs: + channels: + - url: https://conda.anaconda.org/conda-forge/ + packages: + linux-64: + - conda: https://conda.anaconda.org/conda-forge/linux-64/_openmp_mutex-4.5-20_gnu.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/astroid-4.3.4-py313hd5f5364_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/at-spi2-atk-2.38.0-h0630a04_3.tar.bz2 + - conda: https://conda.anaconda.org/conda-forge/linux-64/at-spi2-core-2.40.3-h0630a04_0.tar.bz2 + - conda: https://conda.anaconda.org/conda-forge/linux-64/atk-1.0-2.38.0-hc5c8e38_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/binutils-2.46.1-default_h4852527_103.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/binutils_impl_linux-64-2.46.1-default_hfdba357_103.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/bzip2-1.0.8-hda65f42_10.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/c-ares-1.34.9-hebe6cf0_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/cairo-1.18.6-h3c89d7e_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/charset-normalizer-3.5.2-h1114479_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/curl-8.23.0-ha042cf0_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/dbus-1.16.2-he8c428d_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/emacs-30.2-hda76a9e_6.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/epoxy-1.5.10-hb03c661_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/fontconfig-2.18.3-h4db4eae_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/freetype-2.14.3-ha770c72_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/fribidi-1.0.18-h7cc23a3_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/gdk-pixbuf-2.44.8-h68053f1_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/giflib-6.1.3-hebe6cf0_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/glib-tools-2.90.1-h876c321_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/gmp-6.3.0-hfd2156b_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/gnutls-3.8.13-h18acefa_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/graphite2-1.3.15-h54a6638_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/gtk3-3.24.52-ha5ea40c_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/harfbuzz-15.0.0-ha770c72_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/hicolor-icon-theme-0.17-hfc2019e_4.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/icu-78.3-py310h44b86e0_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/keyutils-1.6.3-h7cc23a3_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/krb5-1.22.2-hbc21106_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/ld_impl_linux-64-2.46.1-default_hbd61a6d_103.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/lerc-4.3.0-he78707d_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libclang-cpp22.1-22.1.8-default_h0acdd01_11.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libcups-2.3.3-h7a8fb5f_6.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libcurl-8.23.0-ha042cf0_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libdeflate-1.26-h351257e_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libdrm-2.4.129-h7cc23a3_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libedit-3.1.20260512-pl5321h373387f_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libegl-1.7.0-ha4b6fd6_5.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libegl-devel-1.7.0-ha4b6fd6_5.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libev-4.33-h280c20c_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libexpat-2.9.0-hd2095e1_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libffi-3.7.0-h81df57d_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libfreetype-2.14.3-ha770c72_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libfreetype6-2.14.3-h5e6c136_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libgcc-16.2.0-ha9f2e26_7.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libgcc-ng-16.2.0-h69a702a_7.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libgl-1.7.0-ha4b6fd6_5.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libgl-devel-1.7.0-ha4b6fd6_5.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libglib-2.90.1-hb382ddc_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libglvnd-1.7.0-ha4b6fd6_5.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libglx-1.7.0-ha4b6fd6_5.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libglx-devel-1.7.0-ha4b6fd6_5.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libgomp-16.2.0-he0feb66_7.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libharfbuzz-15.0.0-h23af247_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libharfbuzz-devel-15.0.0-h23af247_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libiconv-1.18-h0cb94f2_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libidn2-2.3.8-hfac485b_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libjpeg-turbo-3.2.1-h7cc23a3_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libllvm22-22.1.8-h474f4eb_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/liblzma-5.8.3-hb03c661_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libmpdec-4.0.0-hb03c661_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libnghttp2-1.71.0-hc5e5977_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libpango-1.58.2-hce4e988_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libpango-devel-1.58.2-h317d9d0_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libpciaccess-0.19-hb03c661_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libpng-1.6.59-h922cc85_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libpsl-0.23.1-hd9e3e90_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libpython-3.13.18-hd51c5da_100_cp313.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/librsvg-2.62.4-ha427ee3_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libsqlite-3.54.1-h13e7031_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libssh2-1.11.1-h6154650_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libstdcxx-16.2.0-h934c35e_7.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libtasn1-4.21.0-h7cc23a3_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libtiff-4.7.2-h6d37cbf_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libtree-sitter-0.25.9-h280c20c_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libunistring-0.9.10-h7f98852_0.tar.bz2 + - conda: https://conda.anaconda.org/conda-forge/linux-64/libuuid-2.42.4-hcfc3c73_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libwebp-base-1.6.0-hd42ef1d_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libxcb-1.17.0-hb83e432_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libxkbcommon-1.13.2-h59c2f34_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libxml2-16-2.15.4-hf3af7cc_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libxml2-2.15.4-h7df9aa5_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/libzlib-1.3.2-h25fd6f3_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/lychee-0.24.2-h39d0f39_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/markupsafe-3.0.4-py313h2af15c8_5.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/mpc-1.4.1-ha2cb11d_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/mpfr-4.2.2-ha2cb11d_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/ncurses-6.6-hdb14827_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/nettle-3.10.1-h5ef0d04_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/openssl-3.6.5-h781a0a9_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/p11-kit-0.26.5-h8d769aa_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/pango-1.58.2-h2f58602_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/pcre2-10.49-h8b3dc9c_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/pixman-0.46.4-h54a6638_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/pthread-stubs-0.4-h7cc23a3_1004.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/python-3.13.18-hf47f18c_100_cp313.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/pyyaml-6.0.3-py313h45b8176_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/readline-8.3-hd6e31c0_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/tk-8.6.13-noxft_h1df4ec4_4.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/wayland-1.26.0-hc1c935e_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xkeyboard-config-2.48-hebe6cf0_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libice-1.1.2-h280c20c_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libsm-1.2.6-h0d788c3_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libx11-1.8.14-hb83e432_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxau-1.0.12-h7cc23a3_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxcomposite-0.4.7-hb03c661_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxcursor-1.2.3-h7cc23a3_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxdamage-1.1.6-hb9d3cd8_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxdmcp-1.1.5-h7cc23a3_2.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxext-1.3.7-h7cc23a3_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxfixes-6.0.2-h7cc23a3_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxi-1.8.4-h7cc23a3_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxinerama-1.1.6-hd2095e1_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxrandr-1.5.5-h7cc23a3_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxrender-0.9.13-h7cc23a3_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxtst-1.2.6-h7cc23a3_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxxf86vm-1.1.7-h7cc23a3_1.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-xorgproto-2025.1-hebe6cf0_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/yaml-0.2.5-hebe6cf0_3.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/zig-0.17.1-89c0722_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/zig_impl_linux-64-0.17.1-0addc32_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/zig_linux-64-0.17.1-fa519dd_0.conda + - conda: https://conda.anaconda.org/conda-forge/linux-64/zstd-1.5.7-hb78ec9c_7.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/_python_abi3_support-1.0-hd8ed1ab_3.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/adwaita-icon-theme-51.0-unix_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/alabaster-1.0.0-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/babel-2.18.0-pyhcf101f3_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/ca-certificates-2026.10.23-hbd8a1cb_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/certifi-2026.10.23-pyhd8ed1ab_3.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/colorama-0.4.6-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/cpython-3.13.18-py313hd8ed1ab_100.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/docutils-0.22.4-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/font-ttf-dejavu-sans-mono-2.37-hab24e00_0.tar.bz2 + - conda: https://conda.anaconda.org/conda-forge/noarch/font-ttf-inconsolata-3.000-h77eed37_0.tar.bz2 + - conda: https://conda.anaconda.org/conda-forge/noarch/font-ttf-source-code-pro-2.038-h77eed37_0.tar.bz2 + - conda: https://conda.anaconda.org/conda-forge/noarch/font-ttf-ubuntu-0.83-h77eed37_4.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/fonts-conda-ecosystem-1-0.tar.bz2 + - conda: https://conda.anaconda.org/conda-forge/noarch/fonts-conda-forge-1-hc364b38_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/idna-3.20-pyh5ded981_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/imagesize-2.0.1-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/jinja2-3.1.6-pyhcf101f3_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/kernel-headers_linux-64-4.18.0-he073ed8_9.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/libgcc-devel_linux-64-15.3.0-h2b852eb_107.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/libstdcxx-devel_linux-64-15.3.0-hb2c5482_107.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/markdown-it-py-4.3.0-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/mdit-py-plugins-0.7.0-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/mdurl-0.1.2-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/myst-parser-5.2.0-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/packaging-26.3-pyhc364b38_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/pygments-2.21.0-pyhcf101f3_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/pygments-styles-0.3.0-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/python-gil-3.13.18-h4df99d1_100.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/python_abi-3.13-9_cp313.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/requests-2.34.2-pyhcf101f3_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/roman-numerals-4.1.0-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/shibuya-2026.7.12-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/snowballstemmer-3.1.1-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-9.2.0-pyhc364b38_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-autoapi-3.9.0-pyh5ded981_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-copybutton-0.5.2-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-design-0.8.0-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-last-updated-by-git-0.3.8-pyhe01879c_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-sitemap-2.9.0-pyhcf101f3_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-applehelp-2.0.0-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-devhelp-2.0.0-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-htmlhelp-2.1.0-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-jsmath-2.0.0-pyh5ded981_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-qthelp-2.0.0-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-serializinghtml-2.0.0-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sysroot_linux-64-2.28-h4ee821c_9.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/tzdata-2026e-h5d301ff_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/urllib3-2.8.0-pyh5ded981_1.conda + osx-arm64: + - conda: https://conda.anaconda.org/conda-forge/noarch/alabaster-1.0.0-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/babel-2.18.0-pyhcf101f3_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/ca-certificates-2026.10.23-hbd8a1cb_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/certifi-2026.10.23-pyhd8ed1ab_3.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/charset-normalizer-3.5.1-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/colorama-0.4.6-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/docutils-0.22.4-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/font-ttf-dejavu-sans-mono-2.37-hab24e00_0.tar.bz2 + - conda: https://conda.anaconda.org/conda-forge/noarch/font-ttf-inconsolata-3.000-h77eed37_0.tar.bz2 + - conda: https://conda.anaconda.org/conda-forge/noarch/font-ttf-source-code-pro-2.038-h77eed37_0.tar.bz2 + - conda: https://conda.anaconda.org/conda-forge/noarch/font-ttf-ubuntu-0.83-h77eed37_4.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/fonts-conda-ecosystem-1-0.tar.bz2 + - conda: https://conda.anaconda.org/conda-forge/noarch/fonts-conda-forge-1-hc364b38_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/idna-3.20-pyh5ded981_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/imagesize-2.0.1-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/jinja2-3.1.6-pyhcf101f3_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/markdown-it-py-4.3.0-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/mdit-py-plugins-0.7.0-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/mdurl-0.1.2-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/myst-parser-5.2.0-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/packaging-26.3-pyhc364b38_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/pygments-2.21.0-pyhcf101f3_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/pygments-styles-0.3.0-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/python_abi-3.13-9_cp313.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/requests-2.34.2-pyhcf101f3_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/roman-numerals-4.1.0-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/shibuya-2026.7.12-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/snowballstemmer-3.1.1-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-9.2.0-pyhc364b38_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-autoapi-3.9.0-pyh5ded981_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-copybutton-0.5.2-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-design-0.8.0-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-last-updated-by-git-0.3.8-pyhe01879c_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-sitemap-2.9.0-pyhcf101f3_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-applehelp-2.0.0-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-devhelp-2.0.0-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-htmlhelp-2.1.0-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-jsmath-2.0.0-pyh5ded981_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-qthelp-2.0.0-pyhd8ed1ab_1.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-serializinghtml-2.0.0-pyhd8ed1ab_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/tzdata-2026e-h5d301ff_0.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/urllib3-2.8.0-pyh5ded981_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/astroid-4.3.4-py313h6ee819a_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/bzip2-1.0.8-h4e30115_10.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/c-ares-1.34.9-h74c22ad_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/cairo-1.18.6-h580cee5_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/curl-8.23.0-h6651222_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/dbus-1.16.2-hf049998_2.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/emacs-30.2-ha2f6bed_6.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/fontconfig-2.18.3-h81aa574_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/freetype-2.14.3-hce30654_2.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/fribidi-1.0.18-hb001647_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/gdk-pixbuf-2.44.8-h5867e2c_2.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/giflib-6.1.3-h74c22ad_2.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/gmp-6.3.0-hf5e55b1_3.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/gnutls-3.8.13-hfe86254_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/graphite2-1.3.15-h784d473_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/icu-78.3-py310h579977c_2.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/krb5-1.22.2-h34f8a20_2.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/lerc-4.3.0-h0699d0c_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libasprintf-0.25.1-hae62183_2.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libclang-cpp22.1-22.1.8-default_h79071a4_11.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libcurl-8.23.0-h6651222_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libcxx-22.1.8-h55c6f16_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libdeflate-1.26-h72bfca4_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libedit-3.1.20260512-pl5321h26f1114_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libev-4.33-h1a92334_3.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libexpat-2.9.0-h6111c0a_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libffi-3.7.0-h47dc5ef_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libfreetype-2.14.3-hce30654_2.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libfreetype6-2.14.3-h2ed5691_2.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libgettextpo-0.25.1-hae62183_2.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libglib-2.90.0-hccd281b_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libharfbuzz-15.0.0-hcda0f7c_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libharfbuzz-devel-15.0.0-hcda0f7c_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libiconv-1.18-he4c29f2_3.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libidn2-2.3.8-ha90df94_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libintl-0.25.1-hae62183_2.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libjpeg-turbo-3.2.1-hb001647_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libllvm22-22.1.8-h759d1ac_3.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/liblzma-5.8.3-h8088a28_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libmpdec-4.0.0-h84a0fba_2.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libnghttp2-1.71.0-h29223de_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libpango-1.58.2-hc2ac4f2_3.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libpango-devel-1.58.2-haa2d88b_3.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libpng-1.6.59-hf5e6511_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libpsl-0.23.1-hdb0c161_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libpython-3.13.18-h0af5753_100_cp313.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/librsvg-2.62.4-hc8ac265_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libsqlite-3.54.1-hca69786_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libssh2-1.11.1-hbf2880b_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libtasn1-4.21.0-hb001647_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libtiff-4.7.2-h87d37ca_2.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libtree-sitter-0.25.9-he530434_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libunistring-0.9.10-h3422bc3_0.tar.bz2 + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libwebp-base-1.6.0-h202fb40_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libxml2-16-2.15.4-heb56d2d_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libxml2-2.15.4-h550178d_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libzlib-1.3.2-h8088a28_3.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/lychee-0.24.2-h9d00c72_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/markupsafe-3.0.4-py313h0984dbd_5.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/ncurses-6.6-he64c551_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/nettle-3.10.1-hfc803ee_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/openssl-3.6.5-h55eecbc_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/p11-kit-0.26.5-h329a732_2.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/pango-1.58.2-hc6efcc1_3.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/pcre2-10.47-he63d830_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/pixman-0.46.4-h784d473_3.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/python-3.13.18-hb59dee6_100_cp313.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/pyyaml-6.0.3-py313h5c85ca1_3.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/readline-8.3-h8b90a29_1.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/tk-8.6.13-hbeba79b_4.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/yaml-0.2.5-h74c22ad_3.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/zig-0.17.1-0ccaba2_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/zig_impl_osx-arm64-0.17.1-8405819_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/zig_osx-arm64-0.17.1-a676bd3_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/zstd-1.5.7-hf451053_7.conda +packages: +- conda: https://conda.anaconda.org/conda-forge/linux-64/_openmp_mutex-4.5-20_gnu.conda + build_number: 20 + sha256: 1dd3fffd892081df9726d7eb7e0dea6198962ba775bd88842135a4ddb4deb3c9 + md5: a9f577daf3de00bca7c3c76c0ecbd1de + depends: + - __glibc >=2.17,<3.0.a0 + - libgomp >=7.5.0 + constrains: + - openmp_impl <0.0a0 + license: BSD-3-Clause + license_family: BSD + run_exports: + strong: + - _openmp_mutex >=4.5 + size: 28948 + timestamp: 1770939786096 +- conda: https://conda.anaconda.org/conda-forge/linux-64/astroid-4.3.4-py313hd5f5364_0.conda + sha256: 771ff3b8e696eddcae366aec29fa141de8f86c775829bdc4a7b2178e9ef63a0f + md5: 07762eaac3a9abec3df4a843ea7b1137 + depends: + - python + - python_abi 3.13.* *_cp313 + license: LGPL-2.1-only + run_exports: {} + size: 577483 + timestamp: 1791464581441 +- conda: https://conda.anaconda.org/conda-forge/linux-64/at-spi2-atk-2.38.0-h0630a04_3.tar.bz2 + sha256: 26ab9386e80bf196e51ebe005da77d57decf6d989b4f34d96130560bc133479c + md5: 6b889f174df1e0f816276ae69281af4d + depends: + - at-spi2-core >=2.40.0,<2.41.0a0 + - atk-1.0 >=2.36.0 + - dbus >=1.13.6,<2.0a0 + - libgcc-ng >=9.3.0 + - libglib >=2.68.1,<3.0a0 + license: LGPL-2.1-or-later + license_family: LGPL + run_exports: + weak: + - at-spi2-atk >=2.38.0,<3.0a0 + size: 339899 + timestamp: 1619122953439 +- conda: https://conda.anaconda.org/conda-forge/linux-64/at-spi2-core-2.40.3-h0630a04_0.tar.bz2 + sha256: c4f9b66bd94c40d8f1ce1fad2d8b46534bdefda0c86e3337b28f6c25779f258d + md5: 8cb2fc4cd6cc63f1369cfa318f581cc3 + depends: + - dbus >=1.13.6,<2.0a0 + - libgcc-ng >=9.3.0 + - libglib >=2.68.3,<3.0a0 + - xorg-libx11 + - xorg-libxi + - xorg-libxtst + license: LGPL-2.1-or-later + license_family: LGPL + run_exports: + weak: + - at-spi2-core >=2.40.3,<2.41.0a0 + size: 658390 + timestamp: 1625848454791 +- conda: https://conda.anaconda.org/conda-forge/linux-64/atk-1.0-2.38.0-hc5c8e38_3.conda + sha256: 0a46bb5d2b830bafbc087e03e6dcfbe2bb0ed5367f7eb0f2ac30d814c90eb273 + md5: 0025e3fcf41f95f2d101a5314c203cd7 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - libglib >=2.90.1,<3.0a0 + - libzlib >=1.3.2,<2.0a0 + constrains: + - atk-1.0 2.38.0 + license: LGPL-2.0-or-later + license_family: LGPL + run_exports: + weak: + - atk-1.0 >=2.38.0 + size: 184172 + timestamp: 1794581195451 +- conda: https://conda.anaconda.org/conda-forge/linux-64/binutils-2.46.1-default_h4852527_103.conda + sha256: 1198587b78b20fa00ee397d4ea1bdb5098b08100c08ad7b3e6d10912cd487466 + md5: 3624cc8224aec1c58079dad844d354a2 + depends: + - binutils_impl_linux-64 >=2.46.1,<2.46.2.0a0 + license: GPL-3.0-only + license_family: GPL + run_exports: {} + size: 35373 + timestamp: 1791565504227 +- conda: https://conda.anaconda.org/conda-forge/linux-64/binutils_impl_linux-64-2.46.1-default_hfdba357_103.conda + sha256: 98f9ddc6dc5d56a824b7eaea5bab6ad4bb47642288fc70d6b1b4024ac39d5595 + md5: e86f9dc615d7533c5be8b15b3a1dee8d + depends: + - ld_impl_linux-64 2.46.1 default_hbd61a6d_103 + - sysroot_linux-64 + - zstd >=1.5.7,<1.6.0a0 + license: GPL-3.0-only + license_family: GPL + run_exports: {} + size: 3706604 + timestamp: 1791565481839 +- conda: https://conda.anaconda.org/conda-forge/linux-64/bzip2-1.0.8-hda65f42_10.conda + sha256: 1a0d382c515ebf55f8ee1f38c8b81bc95af5c2acc42ad53b66bc5df932032f96 + md5: e675fabcf81499adc7edf58124fb1e01 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=14 + license: bzip2-1.0.6 + license_family: BSD + run_exports: + weak: + - bzip2 >=1.0.8,<2.0a0 + size: 257808 + timestamp: 1785906269155 +- conda: https://conda.anaconda.org/conda-forge/linux-64/c-ares-1.34.9-hebe6cf0_0.conda + sha256: bd95dd25b80b5c4faf5349542377bf89b2794e23d0f7aa7f1c431e4f3b633f3c + md5: 78b505af04bf7a87ca957ef0cb5946f5 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + license: MIT + license_family: MIT + run_exports: + weak: + - c-ares >=1.34.9,<2.0a0 + size: 233759 + timestamp: 1792507024648 +- conda: https://conda.anaconda.org/conda-forge/linux-64/cairo-1.18.6-h3c89d7e_0.conda + sha256: 5d0efc6f9981468aca72897460d9b2d17b74dff72787f20a9d2330e214064515 + md5: 7920701f9abcb488411495742cf365a7 + depends: + - __glibc >=2.17,<3.0.a0 + - fontconfig >=2.18.3,<3.0a0 + - fonts-conda-ecosystem + - icu >=78.3,<79.0a0 + - libexpat >=2.8.1,<3.0a0 + - libfreetype >=2.14.3 + - libfreetype6 >=2.14.3 + - libgcc >=15 + - libglib >=2.90.0,<3.0a0 + - libpng >=1.6.58,<1.7.0a0 + - libstdcxx >=15 + - libxcb >=1.17.0,<2.0a0 + - libzlib >=1.3.2,<2.0a0 + - pixman >=0.46.4,<1.0a0 + - xorg-libice >=1.1.2,<2.0a0 + - xorg-libsm >=1.2.6,<2.0a0 + - xorg-libx11 >=1.8.13,<2.0a0 + - xorg-libxext >=1.3.7,<2.0a0 + - xorg-libxrender >=0.9.12,<0.10.0a0 + license: LGPL-2.1-only or MPL-1.1 + run_exports: + weak: + - cairo >=1.18.6,<2.0a0 + size: 1007110 + timestamp: 1790045358757 +- conda: https://conda.anaconda.org/conda-forge/linux-64/charset-normalizer-3.5.2-h1114479_0.conda + noarch: python + sha256: e4f04b45d68716fcc47c808aeacbf165f6f295fb91bd20b91aa38942b8d2cdc6 + md5: 78d5c6112c9320a1a797935cecfec7c2 + depends: + - python + - libgcc >=15 + - __glibc >=2.17,<3.0.a0 + - _python_abi3_support 1.* + - cpython >=3.9 + license: MIT + license_family: MIT + run_exports: {} + size: 217200 + timestamp: 1790766086110 +- conda: https://conda.anaconda.org/conda-forge/linux-64/curl-8.23.0-ha042cf0_0.conda + sha256: c34fd476d8ad5eede00a3742f33bf52400e01b35bc2777ab2306d6fc21121949 + md5: ae85b19bbac7336f4efc4802c351effa + depends: + - __glibc >=2.17,<3.0.a0 + - krb5 >=1.22.2,<1.23.0a0 + - libcurl 8.23.0 ha042cf0_0 + - libgcc >=15 + - libpsl >=0.23.1,<0.24.0a0 + - libssh2 >=1.11.1,<2.0a0 + - libzlib >=1.3.2,<2.0a0 + - openssl >=3.5.9,<4.0a0 + - zstd >=1.5.7,<1.6.0a0 + license: curl + license_family: MIT + run_exports: {} + size: 197652 + timestamp: 1791990906207 +- conda: https://conda.anaconda.org/conda-forge/linux-64/dbus-1.16.2-he8c428d_2.conda + sha256: 87a0a42d4ccc527597eff3234509dfb03e0d9bf67d5e2b6fc758e2ef389d8abe + md5: a6eb37b51be1a9a654dc3a8aca039b1a + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - libstdcxx >=15 + - libexpat >=2.8.1,<3.0a0 + - libzlib >=1.3.2,<2.0a0 + - libglib >=2.88.3,<3.0a0 + license: AFL-2.1 OR GPL-2.0-or-later + run_exports: + weak: + - dbus >=1.16.2,<2.0a0 + size: 449564 + timestamp: 1788197922783 +- conda: https://conda.anaconda.org/conda-forge/linux-64/emacs-30.2-hda76a9e_6.conda + sha256: 41085b883c2395030f0612c888897926bb11309a969c7fff4fde14ed0237de79 + md5: c89a80eb5ab4bcf59096bbc5c87c4e39 + depends: + - binutils + - __glibc >=2.17,<3.0.a0 + - libstdcxx >=15 + - libgcc >=15 + - xorg-libxext >=1.3.7,<2.0a0 + - libpng >=1.6.58,<1.7.0a0 + - giflib >=6.1.3,<6.2.0a0 + - zstd >=1.5.7,<1.6.0a0 + - libsqlite >=3.53.4,<4.0a0 + - gmp >=6.3.0,<7.0a0 + - libglib >=2.88.3,<3.0a0 + - fontconfig >=2.18.3,<3.0a0 + - fonts-conda-ecosystem + - xorg-libx11 >=1.8.13,<2.0a0 + - libwebp-base >=1.6.0,<2.0a0 + - xorg-libsm >=1.2.6,<2.0a0 + - libtree-sitter >=0.25.9,<0.26.0a0 + - cairo >=1.18.4,<2.0a0 + - xorg-libxrandr >=1.5.5,<2.0a0 + - xorg-libice >=1.1.2,<2.0a0 + - xorg-libxfixes >=6.0.2,<7.0a0 + - xorg-libxcomposite >=0.4.7,<1.0a0 + - libxml2 + - libxml2-16 >=2.14.6 + - gtk3 >=3.24.52,<4.0a0 + - adwaita-icon-theme + - libjpeg-turbo >=3.2.0,<4.0a0 + - libharfbuzz >=14.3.0 + - libiconv >=1.18,<2.0a0 + - libzlib >=1.3.2,<2.0a0 + - libfreetype >=2.14.3 + - libfreetype6 >=2.14.3 + - ncurses >=6.6,<7.0a0 + - librsvg >=2.62.3,<3.0a0 + - xorg-libxi >=1.8.3,<2.0a0 + - xorg-libxrender >=0.9.12,<0.10.0a0 + - mpfr >=4.2.2,<5.0a0 + - libxcb >=1.17.0,<2.0a0 + - gdk-pixbuf >=2.44.8,<3.0a0 + - libtiff >=4.7.2,<4.8.0a0 + - gnutls >=3.8.11,<3.9.0a0 + - pango >=1.58.2,<2.0a0 + - xorg-libxinerama >=1.1.6,<1.2.0a0 + - dbus >=1.16.2,<2.0a0 + - libexpat >=2.8.1,<3.0a0 + - mpc >=1.4.0,<2.0a0 + license: GPL-3.0-only + license_family: GPL + run_exports: {} + size: 73507511 + timestamp: 1786884762437 +- conda: https://conda.anaconda.org/conda-forge/linux-64/epoxy-1.5.10-hb03c661_2.conda + sha256: a5b51e491fec22bcc1765f5b2c8fff8a97428e9a5a7ee6730095fb9d091b0747 + md5: 057083b06ccf1c2778344b6dabace38b + depends: + - __glibc >=2.17,<3.0.a0 + - libdrm >=2.4.125,<2.5.0a0 + - libegl >=1.7.0,<2.0a0 + - libegl-devel + - libgcc >=14 + - libgl >=1.7.0,<2.0a0 + - libgl-devel + - libglx >=1.7.0,<2.0a0 + - libglx-devel + - xorg-libx11 >=1.8.12,<2.0a0 + - xorg-libxdamage >=1.1.6,<2.0a0 + - xorg-libxext >=1.3.6,<2.0a0 + - xorg-libxfixes >=6.0.1,<7.0a0 + - xorg-libxxf86vm >=1.1.6,<2.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - epoxy >=1.5.10,<1.6.0a0 + size: 411735 + timestamp: 1758743520805 +- conda: https://conda.anaconda.org/conda-forge/linux-64/fontconfig-2.18.3-h4db4eae_2.conda + sha256: 49d5b86a00d441d23e6351a6371429fea311538e2aa8b855e61c4d3dbe3e8762 + md5: 2385ef6446d1a75b26a681449a6e32a7 + depends: + - __glibc >=2.17,<3.0.a0 + - libexpat >=2.9.0,<3.0a0 + - libfreetype >=2.14.3 + - libfreetype6 >=2.14.3 + - libgcc >=15 + - libuuid >=2.42.4,<3.0a0 + - libzlib >=1.3.2,<2.0a0 + license: MIT + run_exports: + weak: + - fontconfig >=2.18.3,<3.0a0 + - fonts-conda-ecosystem + size: 296751 + timestamp: 1794699581275 +- conda: https://conda.anaconda.org/conda-forge/linux-64/freetype-2.14.3-ha770c72_2.conda + sha256: 612a8e0c1a6ecae23da54d81ef395f6ebb5c8e4468ec2611593ebce75876a4e0 + md5: 2d0ea23b23603e07ca47f23f949f67b6 + depends: + - libfreetype 2.14.3 ha770c72_2 + - libfreetype6 2.14.3 h5e6c136_2 + license: GPL-2.0-only OR FTL + run_exports: + weak: + - libfreetype >=2.14.3 + - libfreetype6 >=2.14.3 + size: 175239 + timestamp: 1786641011029 +- conda: https://conda.anaconda.org/conda-forge/linux-64/fribidi-1.0.18-h7cc23a3_0.conda + sha256: 6cabdf62dad4973ef0fe8b0d80c4b5b5d76ac9249da91f26f663cb44acdcc6a1 + md5: a14a9f11f543b9a5c03ae6a5c2245b0a + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + license: LGPL-2.1-or-later + run_exports: + weak: + - fribidi >=1.0.18,<2.0a0 + size: 64767 + timestamp: 1793323486599 +- conda: https://conda.anaconda.org/conda-forge/linux-64/gdk-pixbuf-2.44.8-h68053f1_2.conda + sha256: 32f3ebd1871cb6ac7eac36c78c410860f38e8d252d5857a80f6abfcb79c7e0ff + md5: d7bd6ccfc58eb6796bd6bba85878fc0e + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - libglib >=2.88.3,<3.0a0 + - libjpeg-turbo >=3.2.0,<4.0a0 + - liblzma >=5.8.3,<6.0a0 + - libpng >=1.6.58,<1.7.0a0 + - libtiff >=4.7.2,<4.8.0a0 + license: LGPL-2.1-or-later + license_family: LGPL + run_exports: + weak: + - gdk-pixbuf >=2.44.8,<3.0a0 + size: 581961 + timestamp: 1788490424411 +- conda: https://conda.anaconda.org/conda-forge/linux-64/giflib-6.1.3-hebe6cf0_2.conda + sha256: 917c3a622c3870f822d25a882f1856e757d91e31a3dd52a499849a392ca865d2 + md5: 07bdd65afe03df3fb5dbcaa8257c64a3 + depends: + - libgcc >=15 + - __glibc >=2.17,<3.0.a0 + license: MIT + license_family: MIT + run_exports: + weak: + - giflib >=6.1.3,<6.2.0a0 + size: 86117 + timestamp: 1788948683783 +- conda: https://conda.anaconda.org/conda-forge/linux-64/glib-tools-2.90.1-h876c321_3.conda + sha256: 6f7be2f6545fe3f2e2c62428021623e489daa98ca0d9dbcd9d3fc5297de3bc8b + md5: f68c210114fbae3b35e07a9f1a230972 + depends: + - libglib ==2.90.1 hb382ddc_3 + - libffi + - libgcc >=15 + - __glibc >=2.17,<3.0.a0 + license: LGPL-2.1-or-later + run_exports: {} + size: 238585 + timestamp: 1794580555960 +- conda: https://conda.anaconda.org/conda-forge/linux-64/gmp-6.3.0-hfd2156b_3.conda + sha256: f36c336efc874f346a53a9011f67e997f9faac505562cc18c13b6d399cfe61c7 + md5: 576e32739f323438bf69ab006c21be7b + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=14 + - libstdcxx >=14 + license: GPL-2.0-or-later OR LGPL-3.0-or-later + run_exports: + weak: + - gmp >=6.3.0,<7.0a0 + size: 493498 + timestamp: 1786629164954 +- conda: https://conda.anaconda.org/conda-forge/linux-64/gnutls-3.8.13-h18acefa_0.conda + sha256: dbdbb714064914281c755650bc54e1855412e7e2f4c99ad171b5123ed704b2b1 + md5: 7c3de21891993e89aabdadaa603ed835 + depends: + - __glibc >=2.17,<3.0.a0 + - gmp >=6.3.0,<7.0a0 + - libgcc >=14 + - libidn2 >=2,<3.0a0 + - libstdcxx >=14 + - libtasn1 >=4.21.0,<5.0a0 + - nettle >=3.10.1,<3.11.0a0 + - p11-kit >=0.26.2,<0.27.0a0 + license: LGPL-2.1-or-later + license_family: LGPL + run_exports: + weak: + - gnutls >=3.8.13,<3.9.0a0 + size: 2054535 + timestamp: 1778044634746 +- conda: https://conda.anaconda.org/conda-forge/linux-64/graphite2-1.3.15-h54a6638_1.conda + sha256: 7fa3b6a9c081fa3e545573152a788d061a0a0ba57df7251cc0f4f75225fc93e7 + md5: f9fe2984587fa8235a6af6004760cd18 + depends: + - __glibc >=2.17,<3.0.a0 + - libstdcxx >=14 + - libgcc >=14 + license: LGPL-2.0-or-later + license_family: LGPL + run_exports: + weak: + - graphite2 >=1.3.15,<2.0a0 + size: 102835 + timestamp: 1786118485753 +- conda: https://conda.anaconda.org/conda-forge/linux-64/gtk3-3.24.52-ha5ea40c_0.conda + sha256: c6bb4f06331bcb0a566d84e0f0fad7af4b9035a03b13e2d5ecfaf13be57e6e10 + md5: bcaea22d85999a4f17918acfab877e61 + depends: + - __glibc >=2.17,<3.0.a0 + - at-spi2-atk >=2.38.0,<3.0a0 + - atk-1.0 >=2.38.0 + - cairo >=1.18.4,<2.0a0 + - epoxy >=1.5.10,<1.6.0a0 + - fontconfig >=2.17.1,<3.0a0 + - fonts-conda-ecosystem + - fribidi >=1.0.16,<2.0a0 + - gdk-pixbuf >=2.44.5,<3.0a0 + - glib-tools + - harfbuzz >=13.2.1 + - hicolor-icon-theme + - libcups >=2.3.3,<2.4.0a0 + - libcups >=2.3.3,<3.0a0 + - libexpat >=2.7.4,<3.0a0 + - libfreetype >=2.14.2 + - libfreetype6 >=2.14.2 + - libgcc >=14 + - libglib >=2.86.4,<3.0a0 + - liblzma >=5.8.2,<6.0a0 + - libxkbcommon >=1.13.1,<2.0a0 + - libzlib >=1.3.2,<2.0a0 + - pango >=1.56.4,<2.0a0 + - wayland >=1.25.0,<2.0a0 + - xorg-libx11 >=1.8.13,<2.0a0 + - xorg-libxcomposite >=0.4.7,<1.0a0 + - xorg-libxcursor >=1.2.3,<2.0a0 + - xorg-libxdamage >=1.1.6,<2.0a0 + - xorg-libxext >=1.3.7,<2.0a0 + - xorg-libxfixes >=6.0.2,<7.0a0 + - xorg-libxi >=1.8.2,<2.0a0 + - xorg-libxinerama >=1.1.6,<1.2.0a0 + - xorg-libxrandr >=1.5.5,<2.0a0 + - xorg-libxrender >=0.9.12,<0.10.0a0 + license: LGPL-2.0-or-later + license_family: LGPL + run_exports: + weak: + - gtk3 >=3.24.52,<4.0a0 + - adwaita-icon-theme + size: 5939083 + timestamp: 1774288645605 +- conda: https://conda.anaconda.org/conda-forge/linux-64/harfbuzz-15.0.0-ha770c72_0.conda + sha256: 66e49a0888ad60b69766c8a82a4c5b8be0000b1b0d595710ffaba079fd717e5e + md5: 3bb1373c9a1ca102437ca168e5282cc0 + depends: + - libharfbuzz-devel 15.0.0 h23af247_0 + license: MIT + license_family: MIT + run_exports: + weak: + - libharfbuzz >=15.0.0 + size: 11075 + timestamp: 1792769341313 +- conda: https://conda.anaconda.org/conda-forge/linux-64/hicolor-icon-theme-0.17-hfc2019e_4.conda + sha256: 3eadfa497feb83b48e115383468d756b0637bdd3db7c93d8880c3a68e5f63c68 + md5: bd55e24a51101bcdc51e2c7c8850b333 + license: GPL-2.0-or-later + license_family: GPL + run_exports: {} + size: 15246 + timestamp: 1794120683401 +- conda: https://conda.anaconda.org/conda-forge/linux-64/icu-78.3-py310h44b86e0_2.conda + sha256: 9f07834f0c546ab14d885ce0366285f61f44e326c0edd1fc63b8294e113ae432 + md5: 72a381cbad04f24b1c2a43ef707f45b4 + depends: + - __glibc >=2.17,<3.0.a0 + - libstdcxx >=14 + - libgcc >=14 + license: MIT + license_family: MIT + run_exports: + weak: + - icu >=78.3,<79.0a0 + size: 14459115 + timestamp: 1786545741408 +- conda: https://conda.anaconda.org/conda-forge/linux-64/keyutils-1.6.3-h7cc23a3_1.conda + sha256: dd053c96dcb0dcfd59422aefea9d2fe937a190167f34fba7893ec1e10a7e8963 + md5: ba55d1b89fd7775e67de8291029b4059 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + license: LGPL-2.1-or-later + run_exports: + weak: + - keyutils >=1.6.3,<2.0a0 + size: 135295 + timestamp: 1786739238128 +- conda: https://conda.anaconda.org/conda-forge/linux-64/krb5-1.22.2-hbc21106_2.conda + sha256: 2a5c38c85e63df84c4e69ee71439841ce570d259ae3060627bb9a49a938d66f4 + md5: 53318d715316929a574f83591308b1f8 + depends: + - __glibc >=2.17,<3.0.a0 + - keyutils >=1.6.3,<2.0a0 + - libedit >=3.1.20250104,<3.2.0a0 + - libedit >=3.1.20250104,<4.0a0 + - libgcc >=15 + - libstdcxx >=15 + - openssl >=3.5.7,<4.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - krb5 >=1.22.2,<1.23.0a0 + size: 1394333 + timestamp: 1786762112514 +- conda: https://conda.anaconda.org/conda-forge/linux-64/ld_impl_linux-64-2.46.1-default_hbd61a6d_103.conda + sha256: 901649b1edbe841fd4ee7e2d491a05184ed540eb01cdae506872f344babc1d28 + md5: 2362c70e7e79827c32db35547d9c179b + depends: + - __glibc >=2.17,<3.0.a0 + - zstd >=1.5.7,<1.6.0a0 + constrains: + - binutils_impl_linux-64 2.46.1 + license: GPL-3.0-only + license_family: GPL + run_exports: {} + size: 742109 + timestamp: 1791565468810 +- conda: https://conda.anaconda.org/conda-forge/linux-64/lerc-4.3.0-he78707d_0.conda + sha256: 467aa52e9ba7a438f17944909e1904399eab863778ab501cf271e30cfa4bc6f3 + md5: 78908f9592dbe2cebd57082bf8c57000 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - libstdcxx >=15 + license: Apache-2.0 + license_family: Apache + run_exports: + weak: + - lerc >=4.3.0,<5.0a0 + size: 269911 + timestamp: 1793411350746 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libclang-cpp22.1-22.1.8-default_h0acdd01_11.conda + sha256: e7a3df524a2900677c460e8cd1407db8aabadc3d19e6a713a58a4f29b1d4bef7 + md5: eccc111e6808c3aa5dd458a448c597e6 + depends: + - __glibc >=2.17,<3.0.a0 + - libstdcxx >=15 + - libgcc >=15 + - libxml2 + - libxml2-16 >=2.15.4 + - zstd >=1.5.7,<1.6.0a0 + - libzlib >=1.3.2,<2.0a0 + - libllvm22 >=22.1.8,<22.2.0a0 + license: Apache-2.0 WITH LLVM-exception + license_family: APACHE + run_exports: + weak: + - libclang-cpp22.1 >=22.1.8,<22.2.0a0 + size: 24529645 + timestamp: 1791934037580 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libcups-2.3.3-h7a8fb5f_6.conda + sha256: 205c4f19550f3647832ec44e35e6d93c8c206782bdd620c1d7cf66237580ff9c + md5: 49c553b47ff679a6a1e9fc80b9c5a2d4 + depends: + - __glibc >=2.17,<3.0.a0 + - krb5 >=1.22.2,<1.23.0a0 + - libgcc >=14 + - libstdcxx >=14 + - libzlib >=1.3.1,<2.0a0 + license: Apache-2.0 + license_family: Apache + run_exports: + weak: + - libcups >=2.3.3,<2.4.0a0 + size: 4518030 + timestamp: 1770902209173 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libcurl-8.23.0-ha042cf0_0.conda + sha256: d2db14d80efb4f2e76e76561c633f1767f7543987f2bcb54a067a9d264d432ab + md5: 0ad16151226df493aed967f0efce0e80 + depends: + - __glibc >=2.17,<3.0.a0 + - krb5 >=1.22.2,<1.23.0a0 + - libgcc >=15 + - libnghttp2 >=1.68.1,<2.0a0 + - libpsl >=0.23.1,<0.24.0a0 + - libssh2 >=1.11.1,<2.0a0 + - libzlib >=1.3.2,<2.0a0 + - openssl >=3.5.9,<4.0a0 + - zstd >=1.5.7,<1.6.0a0 + license: curl + license_family: MIT + run_exports: + weak: + - libcurl >=8.23.0,<9.0a0 + size: 505683 + timestamp: 1791990900844 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libdeflate-1.26-h351257e_0.conda + sha256: f437f68abb1fa1dededd082a0c2800bec40495e01cf9ec46f4e693e34d60b644 + md5: d0c17fc12939a990f0865b7a14b49cfe + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + license: MIT + license_family: MIT + run_exports: + weak: + - libdeflate >=1.26,<1.27.0a0 + size: 74338 + timestamp: 1787442593524 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libdrm-2.4.129-h7cc23a3_0.conda + sha256: ea46b0ca0fa16af1f8b329b740e6cd8b4577c5378fa8717b28a885f70668633d + md5: 64cc91512b6278c315349dc13c53f680 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - libpciaccess >=0.19,<0.20.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - libdrm >=2.4.129,<2.5.0a0 + size: 313461 + timestamp: 1786684701973 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libedit-3.1.20260512-pl5321h373387f_0.conda + sha256: 45301f14f4eb66da57cfaf2d265f3eeee73f8b07e99614ee3afc5b26eea91126 + md5: 27dbd7e2984b8fe48e069379636ccfdd + depends: + - ncurses + - __glibc >=2.17,<3.0.a0 + - libgcc >=14 + - ncurses >=6.6,<7.0a0 + license: BSD-2-Clause + license_family: BSD + run_exports: + weak: + - libedit >=3.1.20260512,<3.2.0a0 + size: 135877 + timestamp: 1791327370514 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libegl-1.7.0-ha4b6fd6_5.conda + sha256: 13d3fde9c1dcf254968cc70652222a43f25d04e69555ccf855553110e753288e + md5: 3a1b41c4591a0a1734382af3e2b8bc08 + depends: + - __glibc >=2.17,<3.0.a0 + - libglvnd 1.7.0 ha4b6fd6_5 + license: LicenseRef-libglvnd + run_exports: {} + size: 46694 + timestamp: 1787310030923 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libegl-devel-1.7.0-ha4b6fd6_5.conda + sha256: fd2794bbcff7e692fb476c17886702702893d074071d429217bad7cfb072abfd + md5: 577800fc8c9d8b7d9727246bbfde704e + depends: + - __glibc >=2.17,<3.0.a0 + - libegl 1.7.0 ha4b6fd6_5 + - libgl-devel 1.7.0 ha4b6fd6_5 + - xorg-libx11 + license: LicenseRef-libglvnd + run_exports: + weak: + - libegl >=1.7.0,<2.0a0 + size: 31242 + timestamp: 1787310065866 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libev-4.33-h280c20c_3.conda + sha256: e4418f68d01a6307c4431b585c71b584f40189877364e542ee87deb777f5e85b + md5: 7bc31538d6e3fb349e897353969237ec + depends: + - libgcc >=14 + - __glibc >=2.17,<3.0.a0 + license: BSD-2-Clause OR GPL-2.0-or-later + license_family: GPL + run_exports: + weak: + - libev >=4.33,<4.34.0a0 + size: 43220 + timestamp: 1785917328200 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libexpat-2.9.0-hd2095e1_0.conda + sha256: 7b930a8b6bc6553cb754b4977a11f9c862c719a652fc2d128d89270992ce8beb + md5: 317ecabe4a58b3068c7958dc5eb89e43 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + constrains: + - expat 2.9.0.* + license: MIT + license_family: MIT + run_exports: {} + size: 78894 + timestamp: 1793054221966 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libffi-3.7.0-h81df57d_1.conda + sha256: c8c7583ef063bc3c430f1d48298e5ad24f796a35c22ed5b14183325825a61106 + md5: 6525a0b06aa4fd390795f0740636a9dd + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + license: MIT + license_family: MIT + run_exports: + weak: + - libffi >=3.7.0,<3.8.0a0 + size: 68004 + timestamp: 1787753412298 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libfreetype-2.14.3-ha770c72_2.conda + sha256: fb12ecb46c30d18d928c0e8fc346ab13b5f6fc8a9cacae4f2f4bb188782586f5 + md5: f8054e759d0ddddaf34a5c8fedc900a1 + depends: + - libfreetype6 >=2.14.3 + license: GPL-2.0-only OR FTL + run_exports: {} + size: 8407 + timestamp: 1786641007099 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libfreetype6-2.14.3-h5e6c136_2.conda + sha256: ec607dd5445dd17ff6bf8b7fe6832e5504c226dd91d3aaea7ba83569808b0ce4 + md5: b72a266a9317036fd0464cb98b027cd0 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - libpng >=1.6.58,<1.7.0a0 + - libzlib >=1.3.2,<2.0a0 + constrains: + - freetype >=2.14.3 + license: GPL-2.0-only OR FTL + run_exports: {} + size: 387671 + timestamp: 1786641006460 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libgcc-16.2.0-ha9f2e26_7.conda + sha256: e031634c3a928f9594eba868bc46ef5230d6571a364a0c63215b06c4563bfcea + md5: 735629b400b70eeab21a2ba8f5b1c2ce + depends: + - __glibc >=2.17,<3.0.a0 + - _openmp_mutex >=4.5 + constrains: + - libgcc-ng ==16.2.0=*_7 + - libgomp 16.2.0 he0feb66_7 + license: GPL-3.0-only WITH GCC-exception-3.1 + license_family: GPL + run_exports: {} + size: 1058444 + timestamp: 1790303109576 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libgcc-ng-16.2.0-h69a702a_7.conda + sha256: 03b54d7008de080a17cc2174b0e4acd6d06e1c981b2eb19846f46d8f59966034 + md5: 2005515ac9340f816fb2ac7e83afe553 + depends: + - libgcc 16.2.0 ha9f2e26_7 + license: GPL-3.0-only WITH GCC-exception-3.1 + license_family: GPL + run_exports: + strong: + - libgcc + size: 28616 + timestamp: 1790303114248 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libgl-1.7.0-ha4b6fd6_5.conda + sha256: 7b2e7e31e8a4f5a01c45ecadcd8aa68c8f733b035240bc7ba9881835ef4bf7b4 + md5: 81141db127a106eb5a91df69a29c9918 + depends: + - __glibc >=2.17,<3.0.a0 + - libglvnd 1.7.0 ha4b6fd6_5 + - libglx 1.7.0 ha4b6fd6_5 + license: LicenseRef-libglvnd + run_exports: {} + size: 131988 + timestamp: 1787310049847 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libgl-devel-1.7.0-ha4b6fd6_5.conda + sha256: 3bebdbeb3ce451287794dddd5cc4d7f4970aac200b2fb797f0d17ac727a71cb7 + md5: f5f7fc038c611a25b22758c0a40d25c9 + depends: + - __glibc >=2.17,<3.0.a0 + - libgl 1.7.0 ha4b6fd6_5 + - libglx-devel 1.7.0 ha4b6fd6_5 + license: LicenseRef-libglvnd + run_exports: + weak: + - libgl >=1.7.0,<2.0a0 + size: 116212 + timestamp: 1787310061570 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libglib-2.90.1-hb382ddc_3.conda + sha256: ff0405851f6e95c2b350eb11c505cb5b13c9aca1fe2b854499286b64c78249d8 + md5: e84cb2c1d7ef14f65b92d854b0545ff5 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - pcre2 >=10.49,<10.50.0a0 + - libffi >=3.7.0,<3.8.0a0 + - libiconv >=1.18,<2.0a0 + - libzlib >=1.3.2,<2.0a0 + constrains: + - glib >2.66 + license: LGPL-2.1-or-later + run_exports: + weak: + - libglib >=2.90.1,<3.0a0 + size: 4856026 + timestamp: 1794580555960 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libglvnd-1.7.0-ha4b6fd6_5.conda + sha256: 6eb77601a44b78c4631d886d54ef54f321c2bdc69fdefc4065a1e0491f030c76 + md5: cfcf11edcfd4acf0094771a9c3b8587f + depends: + - __glibc >=2.17,<3.0.a0 + license: LicenseRef-libglvnd + run_exports: {} + size: 133827 + timestamp: 1787310026653 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libglx-1.7.0-ha4b6fd6_5.conda + sha256: d1f0d51aea6bcc5d915969cbed32e72a8ed6a95931b87357ef8d0866573688c4 + md5: 614e10aae180f87b84f0d1ca8ceb7d9e + depends: + - __glibc >=2.17,<3.0.a0 + - libglvnd 1.7.0 ha4b6fd6_5 + - xorg-libx11 >=1.8.13,<2.0a0 + license: LicenseRef-libglvnd + run_exports: {} + size: 79834 + timestamp: 1787310042550 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libglx-devel-1.7.0-ha4b6fd6_5.conda + sha256: aff3841e3404d78e1887fef988ca4842930c577399d566fa0980808756b1df51 + md5: fb00b4fb800f2d431303a5c1625ef9d0 + depends: + - __glibc >=2.17,<3.0.a0 + - libglx 1.7.0 ha4b6fd6_5 + - xorg-libx11 >=1.8.13,<2.0a0 + - xorg-xorgproto + license: LicenseRef-libglvnd + run_exports: + weak: + - libglx >=1.7.0,<2.0a0 + size: 27698 + timestamp: 1787310053582 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libgomp-16.2.0-he0feb66_7.conda + sha256: 92a0bb350c7be6a4eedcb4e111c60aefd176018e6b1c009a6e025dbe9bbcd758 + md5: d904c7ddd95e026254b4b80808ee9e12 + depends: + - __glibc >=2.17,<3.0.a0 + license: GPL-3.0-only WITH GCC-exception-3.1 + license_family: GPL + run_exports: + strong: + - _openmp_mutex >=4.5 + size: 640566 + timestamp: 1790303046034 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libharfbuzz-15.0.0-h23af247_0.conda + sha256: d3190aedc31b449627ba5bdb8423a62fd234623ab99959c0a5a580e4d6ef6420 + md5: f8beff45d7ea8bea3c6675a7ef568337 + depends: + - __glibc >=2.17,<3.0.a0 + - cairo >=1.18.6,<2.0a0 + - graphite2 >=1.3.15,<2.0a0 + - icu >=78.3,<79.0a0 + - libfreetype >=2.14.3 + - libfreetype6 >=2.14.3 + - libgcc >=15 + - libglib >=2.90.0,<3.0a0 + - libpng >=1.6.59,<1.7.0a0 + - libstdcxx >=15 + - libzlib >=1.3.2,<2.0a0 + license: MIT + license_family: MIT + run_exports: {} + size: 1628948 + timestamp: 1792769313795 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libharfbuzz-devel-15.0.0-h23af247_0.conda + sha256: 1409a10889a683a95eff4eac5bd2f99631f40c3ef51f7fbd139a90cc3bc36862 + md5: 0ca7e3876bc01ee2c0d3c1e3b0217cc4 + depends: + - __glibc >=2.17,<3.0.a0 + - cairo >=1.18.6,<2.0a0 + - freetype + - graphite2 >=1.3.15,<2.0a0 + - icu >=78.3,<79.0a0 + - libfreetype >=2.14.3 + - libfreetype6 >=2.14.3 + - libgcc >=15 + - libglib >=2.90.0,<3.0a0 + - libharfbuzz 15.0.0 h23af247_0 + - libpng >=1.6.59,<1.7.0a0 + - libstdcxx >=15 + - libzlib >=1.3.2,<2.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - libharfbuzz >=15.0.0 + size: 2464838 + timestamp: 1792769333155 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libiconv-1.18-h0cb94f2_3.conda + sha256: f943117edb9cd4d9c61cc972eee5a34291dc55ea7a6e9e38da104995841cbcb6 + md5: f92233bf33e24a25668bb2119e2c51f9 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + license: LGPL-2.1-only + run_exports: + weak: + - libiconv >=1.18,<2.0a0 + size: 789471 + timestamp: 1787033836207 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libidn2-2.3.8-hfac485b_1.conda + sha256: cc38c900b9a20fe75e61cbb594e749c57a06d96510722f5ddfa309682062b065 + md5: 842a81de672ddcf476337c8bde3cad33 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=14 + - libunistring >=0,<1.0a0 + license: LGPL-2.0-only + license_family: LGPL + run_exports: + weak: + - libidn2 >=2,<3.0a0 + size: 139036 + timestamp: 1760385590993 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libjpeg-turbo-3.2.1-h7cc23a3_0.conda + sha256: 2f7d092a3212884825c43814575225fde8a9190611bc0e38c55e0dae45e329ac + md5: 5fd2b2218f7c28c71e95738a4fffaf78 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + constrains: + - jpeg <0.0.0a + license: IJG AND BSD-3-Clause AND Zlib + run_exports: + weak: + - libjpeg-turbo >=3.2.1,<4.0a0 + size: 653905 + timestamp: 1793157024388 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libllvm22-22.1.8-h474f4eb_3.conda + sha256: 135b8b9bfed6a20cdbda657ddb4584d483203eb0e4c29e448a60d4bcc762f391 + md5: c927dba789a253045c0089cb25af44ac + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - libstdcxx >=15 + - libxml2 + - libxml2-16 >=2.15.4 + - libzlib >=1.3.2,<2.0a0 + - zstd >=1.5.7,<1.6.0a0 + license: Apache-2.0 WITH LLVM-exception + license_family: Apache + run_exports: + weak: + - libllvm22 >=22.1.8,<22.2.0a0 + size: 44629067 + timestamp: 1790110003063 +- conda: https://conda.anaconda.org/conda-forge/linux-64/liblzma-5.8.3-hb03c661_1.conda + sha256: 9787df8c22a59c9a70d3e5a10db9ad663485e75e9ccc3f09bd092cb7b95e0dab + md5: 1390b7c5ac0b1d8e447bc5efa6d3c8c2 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=14 + constrains: + - xz 5.8.3.* + license: 0BSD + run_exports: + weak: + - liblzma >=5.8.3,<6.0a0 + size: 112995 + timestamp: 1786348617826 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libmpdec-4.0.0-hb03c661_2.conda + sha256: 46820b4a835e175940ae20bec00fdddaff804cda27a1408ab1b95e77a2196437 + md5: fcfed1dc5053eb1901b66e7b1fc32588 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=14 + license: BSD-2-Clause + license_family: BSD + run_exports: {} + size: 92759 + timestamp: 1786650399772 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libnghttp2-1.71.0-hc5e5977_0.conda + sha256: a4386712ad6d5bc18943b198407c39e2f8ae2fa9c6418bb37bba96f1d382f109 + md5: 726df214814a8b06135a6a674bc54589 + depends: + - libev >=4.33,<5.0a0 + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - libstdcxx >=15 + - libev >=4.33,<4.34.0a0 + - c-ares >=1.34.9,<2.0a0 + - libzlib >=1.3.2,<2.0a0 + - openssl >=3.5.9,<4.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - libnghttp2 >=1.71.0,<2.0a0 + size: 822778 + timestamp: 1793628201366 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libpango-1.58.2-hce4e988_3.conda + sha256: 251dfa10f843dfb14ccc8c33d7ec0f18ac75f51be119100f65468a046b1b33ce + md5: d1ad1c07f3ae04176c0b218d7fe3be9b + depends: + - libgcc >=15 + - __glibc >=2.17,<3.0.a0 + - libfreetype >=2.14.3 + - libfreetype6 >=2.14.3 + - fontconfig >=2.18.3,<3.0a0 + - fonts-conda-ecosystem + - cairo >=1.18.6,<2.0a0 + - fribidi >=1.0.17,<2.0a0 + - libglib >=2.90.0,<3.0a0 + - libharfbuzz >=14.6.0 + license: LGPL-2.1-or-later + run_exports: {} + size: 343535 + timestamp: 1792050659391 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libpango-devel-1.58.2-h317d9d0_3.conda + sha256: 75df9cf6e8c8b94648beaa8c7bf0d3c1efd7c3e0ebfb26529e415185a065c2a3 + md5: 8f2e0739636fe033c7324130121ab11c + depends: + - libpango ==1.58.2 hce4e988_3 + - freetype + - libharfbuzz-devel + - libgcc >=15 + - __glibc >=2.17,<3.0.a0 + - libfreetype >=2.14.3 + - libfreetype6 >=2.14.3 + - fontconfig >=2.18.3,<3.0a0 + - fonts-conda-ecosystem + - cairo >=1.18.6,<2.0a0 + - fribidi >=1.0.17,<2.0a0 + - libglib >=2.90.0,<3.0a0 + - libharfbuzz >=14.6.0 + license: LGPL-2.1-or-later + run_exports: + weak: + - libpango >=1.58.2,<2.0a0 + size: 211407 + timestamp: 1792050659391 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libpciaccess-0.19-hb03c661_1.conda + sha256: addc80c69d362a9e6c40305c493139a8e9ee504b2f45a6687dbdaa9da3c6183c + md5: 35fa2b34bbced424e6976d30f5fde576 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=14 + license: MIT + license_family: MIT + run_exports: + weak: + - libpciaccess >=0.19,<0.20.0a0 + size: 30070 + timestamp: 1785971678815 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libpng-1.6.59-h922cc85_0.conda + sha256: c7381be8ef713501f6cd2f5ad473e401f2edeaec3c46788296b8dbf0de165e15 + md5: 8c9caf742a485ac688ffa88bbadbf0be + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - libzlib >=1.3.2,<2.0a0 + license: zlib-acknowledgement + run_exports: + weak: + - libpng >=1.6.59,<1.7.0a0 + size: 316872 + timestamp: 1790805159503 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libpsl-0.23.1-hd9e3e90_1.conda + sha256: 09e8effdc89bc5d021349318d32b85594f5b8d8e3ab8f90a85b81f8fe695a566 + md5: 77be60417aa572afcb48cbe0f967401d + depends: + - libstdcxx >=15 + - libgcc >=15 + - __glibc >=2.17,<3.0.a0 + - icu >=78.3,<79.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - libpsl >=0.23.1,<0.24.0a0 + size: 72519 + timestamp: 1786970753847 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libpython-3.13.18-hd51c5da_100_cp313.conda + build_number: 100 + sha256: 8fb44e69c90a7cb942a6388fae4c7493dbebbae3c9e11cc34d1c464256dc3af1 + md5: eb85e5c7b22eb523e07fa1140b91b9ef + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + license: Python-2.0 + run_exports: + weak: + - libpython >=3.13,<4.0a0 + size: 9721079 + timestamp: 1793015613296 +- conda: https://conda.anaconda.org/conda-forge/linux-64/librsvg-2.62.4-ha427ee3_0.conda + sha256: b8036adad17ceddcef416790131492fd236d34c64a0b2754934903087fa84279 + md5: f9bda2728debbde4c641bd1af103c623 + depends: + - libgcc >=15 + - __glibc >=2.17,<3.0.a0 + - libglib >=2.90.0,<3.0a0 + - pango >=1.58.2,<2.0a0 + - fontconfig >=2.18.3,<3.0a0 + - fonts-conda-ecosystem + - libxml2-16 >=2.15.4 + - cairo >=1.18.6,<2.0a0 + - libharfbuzz >=14.5.0 + - gdk-pixbuf >=2.44.8,<3.0a0 + constrains: + - __glibc >=2.17 + license: LGPL-2.1-or-later + run_exports: + weak: + - librsvg >=2.62.4,<3.0a0 + size: 4692221 + timestamp: 1790276295756 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libsqlite-3.54.1-h13e7031_0.conda + sha256: 07b3c98282022f05781122d073f84e944bfb4299946e8457ece3ce6c384ff78e + md5: 8f15f0ec9b69344df5c3bb5cce1751a1 + depends: + - __glibc >=2.17,<3.0.a0 + - icu >=78.3,<79.0a0 + - libgcc >=15 + - libzlib >=1.3.2,<2.0a0 + license: blessing + run_exports: + weak: + - libsqlite >=3.54.1,<4.0a0 + size: 983668 + timestamp: 1792175587601 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libssh2-1.11.1-h6154650_1.conda + sha256: 7e463000fa1cba3f3a6597b776f6ab301d425a96e3bc20d0d9d76a3b9f237aa3 + md5: 5c526561e1d2a2e071941174eae84557 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=14 + - libzlib >=1.3.2,<2.0a0 + - openssl >=3.5.7,<4.0a0 + license: BSD-3-Clause + license_family: BSD + run_exports: + weak: + - libssh2 >=1.11.1,<2.0a0 + size: 306045 + timestamp: 1786713107897 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libstdcxx-16.2.0-h934c35e_7.conda + sha256: fa7018298629fc429971fffd6ecba3d27a7b02e4e890d6a93ea01ffebe8cb745 + md5: 9b6707e0caca917fa6ea9ee473f37a5d + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc 16.2.0 ha9f2e26_7 + constrains: + - libstdcxx-ng ==16.2.0=*_7 + license: GPL-3.0-only WITH GCC-exception-3.1 + license_family: GPL + run_exports: {} + size: 6615436 + timestamp: 1790303132935 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libtasn1-4.21.0-h7cc23a3_1.conda + sha256: 8db5fe4b5ca8e9f35622d3903e9dcdb28e4e289fcdba3212ee48c9be9dca91f5 + md5: efe26e97b4c332d0c8b2ae6306747133 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + license: LGPL-2.1-or-later + run_exports: + weak: + - libtasn1 >=4.21.0,<5.0a0 + size: 118904 + timestamp: 1793068469782 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libtiff-4.7.2-h6d37cbf_2.conda + sha256: 3406eed96ee929309ecd3937308d5a81302f4ca2eddd30e832071cbe9121a6c7 + md5: 18023fe8fbec4f031ca88444572590e4 + depends: + - __glibc >=2.17,<3.0.a0 + - lerc >=4.3.0,<5.0a0 + - libdeflate >=1.26,<1.27.0a0 + - libgcc >=15 + - libjpeg-turbo >=3.2.1,<4.0a0 + - liblzma >=5.8.3,<6.0a0 + - libstdcxx >=15 + - libwebp-base >=1.6.0,<2.0a0 + - libzlib >=1.3.2,<2.0a0 + - zstd >=1.5.7,<1.6.0a0 + license: HPND + run_exports: + weak: + - libtiff >=4.7.2,<4.8.0a0 + size: 459656 + timestamp: 1794045728051 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libtree-sitter-0.25.9-h280c20c_0.conda + sha256: de4133900552a22fb1d8f5de690b15f784d2bbd7cdd967ad282bd34c965124bf + md5: a9a506002eda117e7cd473305c825f1a + depends: + - libgcc >=14 + - __glibc >=2.17,<3.0.a0 + license: MIT + license_family: MIT + run_exports: + weak: + - libtree-sitter >=0.25.9,<0.26.0a0 + size: 205332 + timestamp: 1757201839815 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libunistring-0.9.10-h7f98852_0.tar.bz2 + sha256: e88c45505921db29c08df3439ddb7f771bbff35f95e7d3103bf365d5d6ce2a6d + md5: 7245a044b4a1980ed83196176b78b73a + depends: + - libgcc-ng >=9.3.0 + license: GPL-3.0-only OR LGPL-3.0-only + run_exports: + weak: + - libunistring >=0,<1.0a0 + size: 1433436 + timestamp: 1626955018689 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libuuid-2.42.4-hcfc3c73_1.conda + sha256: 0e2e8f2daa9306e67f046e31092d637431d8cf0a26c407ab22401d108c2d4631 + md5: d852293faea3c04a6e896b908b43aded + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + license: BSD-3-Clause + license_family: BSD + run_exports: + weak: + - libuuid >=2.42.4,<3.0a0 + size: 36134 + timestamp: 1793891599274 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libwebp-base-1.6.0-hd42ef1d_1.conda + sha256: 8415001414f488c85b72b9d8cc2071dfb3981a47bc3c8eb56ef91a57d12eae7f + md5: 9332b53d0ea93c5d39e33be03a0c611a + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=14 + constrains: + - libwebp 1.6.0 + license: BSD-3-Clause + license_family: BSD + run_exports: + weak: + - libwebp-base >=1.6.0,<2.0a0 + size: 428430 + timestamp: 1785954557217 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libxcb-1.17.0-hb83e432_3.conda + sha256: 38021f35547021762c04860d1c9f2d3186b83e090e5f1773216045de06cf10cc + md5: 661d9e1392a1b672d19d76df3a1feb07 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - pthread-stubs + - xorg-libxau >=1.0.12,<2.0a0 + - xorg-libxdmcp >=1.1.5,<2.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - libxcb >=1.17.0,<2.0a0 + size: 398900 + timestamp: 1794246094531 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libxkbcommon-1.13.2-h59c2f34_2.conda + sha256: 156fdf41b9f3efc54c077b5b8570b810a87800b978c12348c27ec6e0ddc20359 + md5: b85ed11539022fbbf4e63117692179ec + depends: + - xkeyboard-config + - libgcc >=15 + - libstdcxx >=15 + - __glibc >=2.17,<3.0.a0 + - libxml2 + - libxml2-16 >=2.15.4 + - xorg-libxau >=1.0.12,<2.0a0 + - libxcb >=1.17.0,<2.0a0 + license: MIT AND MIT-open-group AND HPND AND HPND-sell-variant AND ISC + run_exports: + weak: + - libxkbcommon >=1.13.2,<2.0a0 + size: 945345 + timestamp: 1792810173656 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libxml2-16-2.15.4-hf3af7cc_1.conda + sha256: d1906463070c21f3215cd5de93164f31c44d5bac6ae9b5d8f5adf42b1e304039 + md5: 046d9eada488e1a1657c80b55c23da52 + depends: + - __glibc >=2.17,<3.0.a0 + - icu >=78.3,<79.0a0 + - libgcc >=15 + - libiconv >=1.18,<2.0a0 + - liblzma >=5.8.3,<6.0a0 + - libzlib >=1.3.2,<2.0a0 + constrains: + - libxml2 2.15.4 + license: MIT + license_family: MIT + run_exports: {} + size: 569062 + timestamp: 1791465631497 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libxml2-2.15.4-h7df9aa5_1.conda + sha256: 8c32be9e8720bc413d2b4267517459d7d71fad4a5f398a2aa8319b6d7b8a00e6 + md5: 51e5162f95bd6840f6b2b3169125fff5 + depends: + - __glibc >=2.17,<3.0.a0 + - icu >=78.3,<79.0a0 + - libgcc >=15 + - libiconv >=1.18,<2.0a0 + - liblzma >=5.8.3,<6.0a0 + - libxml2-16 2.15.4 hf3af7cc_1 + - libzlib >=1.3.2,<2.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - libxml2 + - libxml2-16 >=2.15.4 + size: 46570 + timestamp: 1791465635923 +- conda: https://conda.anaconda.org/conda-forge/linux-64/libzlib-1.3.2-h25fd6f3_3.conda + sha256: eb8a0db0aa570124f7d2a93d7c7f596e3390df5e047818d873baad32985fc736 + md5: 0de0122d9570a8ab637c6b73db268389 + depends: + - __glibc >=2.17,<3.0.a0 + constrains: + - zlib 1.3.2 *_3 + license: Zlib + license_family: Other + run_exports: + weak: + - libzlib >=1.3.2,<2.0a0 + size: 63713 + timestamp: 1785362952714 +- conda: https://conda.anaconda.org/conda-forge/linux-64/lychee-0.24.2-h39d0f39_1.conda + sha256: 59a5afe396a93269ddc4b67262412f0cb707d1294393944d461b2f29164ab5dc + md5: 81747139d7e9fba97af275d1c8f7fe0a + depends: + - libgcc >=15 + - __glibc >=2.17,<3.0.a0 + constrains: + - __glibc >=2.17 + license: Apache-2.0 OR MIT + run_exports: {} + size: 5760830 + timestamp: 1791278254472 +- conda: https://conda.anaconda.org/conda-forge/linux-64/markupsafe-3.0.4-py313h2af15c8_5.conda + sha256: def2a3d0cda3f815b569d5224ef65200555164136cdd3acba30c07321ecfeff6 + md5: eae8eb68bfde138aab698e02a6a19809 + depends: + - python + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - python_abi 3.13.* *_cp313 + constrains: + - jinja2 >=3.0.0 + license: BSD-3-Clause + run_exports: {} + size: 27791 + timestamp: 1794823807688 +- conda: https://conda.anaconda.org/conda-forge/linux-64/mpc-1.4.1-ha2cb11d_0.conda + sha256: ab81712f560a055277a23435b17c113e4aa8b2b15d31042dbc959e236cc5c528 + md5: 8ca4b2b9325e2d22aaf7639aaa5369a1 + depends: + - __glibc >=2.17,<3.0.a0 + - gmp >=6.3.0,<7.0a0 + - libgcc >=15 + - mpfr >=4.2.2,<5.0a0 + license: LGPL-3.0-or-later + run_exports: + weak: + - mpc >=1.4.1,<2.0a0 + size: 101262 + timestamp: 1794641220776 +- conda: https://conda.anaconda.org/conda-forge/linux-64/mpfr-4.2.2-ha2cb11d_1.conda + sha256: 0be79ef2ee536e0c5d3ddb4a52bbae9f26d08560623299f33db2f4c4a17c525a + md5: 7dcc10f6c0bc3596d5519a710a84dfd4 + depends: + - __glibc >=2.17,<3.0.a0 + - gmp >=6.3.0,<7.0a0 + - libgcc >=15 + license: LGPL-3.0-only + license_family: LGPL + run_exports: + weak: + - mpfr >=4.2.2,<5.0a0 + size: 730409 + timestamp: 1787236218159 +- conda: https://conda.anaconda.org/conda-forge/linux-64/ncurses-6.6-hdb14827_1.conda + sha256: 5d46557214ed184381dafe835b7c94a474a1c3b307a08a250b1ea4779b44ffb3 + md5: ee6c0cd80a60961a1f48aa3e0b91f986 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=14 + license: X11 AND BSD-3-Clause + run_exports: + weak: + - ncurses >=6.6,<7.0a0 + size: 911196 + timestamp: 1786355078102 +- conda: https://conda.anaconda.org/conda-forge/linux-64/nettle-3.10.1-h5ef0d04_1.conda + sha256: 9f08df8a8d6660c4c5d8c810da2da2a5b099cd00ca30e1174be6d8df27a82120 + md5: 7b8f8d1226c95f61a51436a657c84770 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=14 + - gmp >=6.3.0,<7.0a0 + license: GPL-2.0-or-later OR LGPL-3.0-or-later + run_exports: + weak: + - nettle >=3.10.1,<3.11.0a0 + size: 1052171 + timestamp: 1787065085312 +- conda: https://conda.anaconda.org/conda-forge/linux-64/openssl-3.6.5-h781a0a9_0.conda + sha256: 9c1533f1cf784f0e250919c0c9762d0b0e6bc727a79290ffb7cea1ceca1d038c + md5: 5a51a2ea653f120240b1a9bf76e0aae9 + depends: + - __glibc >=2.17,<3.0.a0 + - ca-certificates + - libgcc >=15 + license: Apache-2.0 + license_family: Apache + run_exports: + weak: + - openssl >=3.6.5,<4.0a0 + size: 3195299 + timestamp: 1791098052301 +- conda: https://conda.anaconda.org/conda-forge/linux-64/p11-kit-0.26.5-h8d769aa_2.conda + sha256: 16bcb050de08f5423b0e898dea9eb08a66ff93c1b347233137ffc17b2ec7e66c + md5: aeb4e6fe52e15c22f44f73476510c005 + depends: + - __glibc >=2.17,<3.0.a0 + - libffi >=3.7.0,<3.8.0a0 + - libgcc >=15 + - libtasn1 >=4.21.0,<5.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - p11-kit >=0.26.5,<0.27.0a0 + size: 3945183 + timestamp: 1788196153960 +- conda: https://conda.anaconda.org/conda-forge/linux-64/pango-1.58.2-h2f58602_3.conda + sha256: 255c7311441dddee7858279b799156387a6719d3a114dce861cbf379f6fb9d6e + md5: 4a1bbf999cdcdcf3ca1bfd819259f795 + depends: + - libpango-devel ==1.58.2 h317d9d0_3 + license: LGPL-2.1-or-later + run_exports: + weak: + - libpango >=1.58.2,<2.0a0 + size: 15014 + timestamp: 1792050659391 +- conda: https://conda.anaconda.org/conda-forge/linux-64/pcre2-10.49-h8b3dc9c_0.conda + sha256: 63784a2dd0231cf8944b31a781b4ebab48954a94cd455d13585874370e46b658 + md5: db724d35be3a1c7b6cd49b7a03de4027 + depends: + - __glibc >=2.17,<3.0.a0 + - bzip2 >=1.0.8,<2.0a0 + - libgcc >=15 + - libzlib >=1.3.2,<2.0a0 + license: BSD-3-Clause + license_family: BSD + run_exports: + weak: + - pcre2 >=10.49,<10.50.0a0 + size: 1234818 + timestamp: 1793902484896 +- conda: https://conda.anaconda.org/conda-forge/linux-64/pixman-0.46.4-h54a6638_3.conda + sha256: 829d8288764282de5a9f7b9169acb75cc7dc0b6c3fe2535cfe87dea3436bbc5d + md5: 0ee5bb30034b081a1386c1e2c98ab0a7 + depends: + - libstdcxx >=14 + - libgcc >=14 + - __glibc >=2.17,<3.0.a0 + license: MIT + license_family: MIT + run_exports: + weak: + - pixman >=0.46.4,<1.0a0 + size: 376704 + timestamp: 1786106621354 +- conda: https://conda.anaconda.org/conda-forge/linux-64/pthread-stubs-0.4-h7cc23a3_1004.conda + sha256: 4a44fd00ea73b79ca2c89b0727b9ccf61c506ead71e67a9abfa4c590042b5a4a + md5: bb66b610707b811e3c65181a6431e7a8 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + license: MIT + license_family: MIT + run_exports: {} + size: 9630 + timestamp: 1788381877753 +- conda: https://conda.anaconda.org/conda-forge/linux-64/python-3.13.18-hf47f18c_100_cp313.conda + build_number: 100 + sha256: 8c20b663f2da07fee96f5406651854727a18d173e84735b71136cf06d7032b47 + md5: 8a8f008a3e3ae6e4eb6e149d639ab43e + depends: + - __glibc >=2.17,<3.0.a0 + - bzip2 >=1.0.8,<2.0a0 + - ld_impl_linux-64 >=2.36.1 + - libexpat >=2.8.5,<3.0a0 + - libffi >=3.7.0,<3.8.0a0 + - libgcc >=15 + - liblzma >=5.8.3,<6.0a0 + - libmpdec >=4.0.0,<5.0a0 + - libpython 3.13.18 hd51c5da_100_cp313 + - libsqlite >=3.54.1,<4.0a0 + - libuuid >=2.42.4,<3.0a0 + - libzlib >=1.3.2,<2.0a0 + - ncurses >=6.6,<7.0a0 + - openssl >=3.5.9,<4.0a0 + - python_abi 3.13.* *_cp313 + - readline >=8.3,<9.0a0 + - tk >=8.6.13,<8.7.0a0 + - tzdata + license: Python-2.0 + run_exports: + weak: + - python_abi 3.13.* *_cp313 + noarch: + - python + size: 24309726 + timestamp: 1793015646233 + python_site_packages_path: lib/python3.13/site-packages +- conda: https://conda.anaconda.org/conda-forge/linux-64/pyyaml-6.0.3-py313h45b8176_3.conda + sha256: 3e90c35deffbc80fe714ddfc28201589604f6b1144593a78d28929be899b1b60 + md5: b53b2182e0df385ce82e39a38a4a7b05 + depends: + - python + - yaml + - libgcc >=15 + - __glibc >=2.17,<3.0.a0 + - yaml >=0.2.5,<0.3.0a0 + - python_abi 3.13.* *_cp313 + license: MIT + license_family: MIT + run_exports: {} + size: 226628 + timestamp: 1793655133957 +- conda: https://conda.anaconda.org/conda-forge/linux-64/readline-8.3-hd6e31c0_1.conda + sha256: 01b3fe073a66e321970d09e04b388708f8cbdca5cdfbfcb7c9eeb470ad10383d + md5: 69c01c781e7c8190bbdaf79e3848c5ca + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - ncurses >=6.6,<7.0a0 + license: GPL-3.0-only + license_family: GPL + run_exports: + weak: + - readline >=8.3,<9.0a0 + size: 348899 + timestamp: 1787033801506 +- conda: https://conda.anaconda.org/conda-forge/linux-64/tk-8.6.13-noxft_h1df4ec4_4.conda + build_number: 104 + sha256: a1a241d172c1ccab067ba245206dd048bc3c2d1b84504b53c9468e99adfc16a1 + md5: 676a2f9b1c4fcf57b70aa5c65f6c60d0 + depends: + - libgcc >=15 + - __glibc >=2.17,<3.0.a0 + - libzlib >=1.3.2,<2.0a0 + constrains: + - xorg-libx11 >=1.8.13,<2.0a0 + license: TCL + run_exports: + weak: + - tk >=8.6.13,<8.7.0a0 + size: 3566806 + timestamp: 1787272857910 +- conda: https://conda.anaconda.org/conda-forge/linux-64/wayland-1.26.0-hc1c935e_2.conda + sha256: df65b987979e6d7f88e756494da5a230d4f2d08d17437d04eecd35559c3a04e4 + md5: 88a47e22b53e50865b1cabe2eb648352 + depends: + - __glibc >=2.17,<3.0.a0 + - libexpat >=2.8.1,<3.0a0 + - libffi >=3.7.0,<3.8.0a0 + - libgcc >=15 + - libstdcxx >=15 + license: MIT + license_family: MIT + run_exports: + weak: + - wayland >=1.26.0,<2.0a0 + size: 340058 + timestamp: 1787793849093 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xkeyboard-config-2.48-hebe6cf0_1.conda + sha256: 5d803109509756b39e018b780746ed4210cff640eb428fd58fa6c64c9c15ae6b + md5: 1d0383de55470a551d61ccdc225c0d88 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - xorg-libx11 >=1.8.14,<2.0a0 + license: MIT + license_family: MIT + run_exports: {} + size: 441638 + timestamp: 1792698743043 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libice-1.1.2-h280c20c_0.conda + sha256: 49b532d1df875c6749d9078b56a76f3f5db49a5abe0ca620b593ed474ef0ebf1 + md5: 85c9442aec283b4e464fa9ecc484a2f3 + depends: + - libgcc >=14 + - __glibc >=2.17,<3.0.a0 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libice >=1.1.2,<2.0a0 + size: 62517 + timestamp: 1786474410404 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libsm-1.2.6-h0d788c3_1.conda + sha256: ef907caee0665cf3b0f775602cc50e388e3bade8ce22ecade0873ff26604b2fd + md5: aa7459ed9ad086ba11dda843d764b33d + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=14 + - xorg-libice >=1.1.2,<2.0a0 + - libuuid >=2.42.2,<3.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libsm >=1.2.6,<2.0a0 + size: 30739 + timestamp: 1786545374265 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libx11-1.8.14-hb83e432_0.conda + sha256: 1815dc9900bf3a4678caeb343bccbbc74cd5e5a5ff3f6e0a2c01c5e19cd9d30b + md5: e7752792cb214013a34e265cc0838352 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - libxcb >=1.17.0,<2.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libx11 >=1.8.14,<2.0a0 + size: 846774 + timestamp: 1792545407029 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxau-1.0.12-h7cc23a3_2.conda + sha256: 3ec065b94554dc48a4ca582a960a5484bc166b26e83ce0954653e08d17e8bd53 + md5: da33efee1a93603d92e06d4a2b68def6 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libxau >=1.0.12,<2.0a0 + size: 18793 + timestamp: 1788960512381 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxcomposite-0.4.7-hb03c661_0.conda + sha256: 048c103000af9541c919deef03ae7c5e9c570ffb4024b42ecb58dbde402e373a + md5: f2ba4192d38b6cef2bb2c25029071d90 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=14 + - xorg-libx11 >=1.8.12,<2.0a0 + - xorg-libxfixes >=6.0.2,<7.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libxcomposite >=0.4.7,<1.0a0 + size: 14415 + timestamp: 1770044404696 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxcursor-1.2.3-h7cc23a3_1.conda + sha256: 5a819cd8d06656559349175be63bab398947e9755fe54692fab1bfab5385211a + md5: 6115d96e6728a7518358314701a27f75 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - xorg-libx11 >=1.8.14,<2.0a0 + - xorg-libxfixes >=6.0.2,<7.0a0 + - xorg-libxrender >=0.9.13,<0.10.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libxcursor >=1.2.3,<2.0a0 + size: 34792 + timestamp: 1793235593597 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxdamage-1.1.6-hb9d3cd8_0.conda + sha256: 43b9772fd6582bf401846642c4635c47a9b0e36ca08116b3ec3df36ab96e0ec0 + md5: b5fcc7172d22516e1f965490e65e33a4 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=13 + - xorg-libx11 >=1.8.10,<2.0a0 + - xorg-libxext >=1.3.6,<2.0a0 + - xorg-libxfixes >=6.0.1,<7.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libxdamage >=1.1.6,<2.0a0 + size: 13217 + timestamp: 1727891438799 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxdmcp-1.1.5-h7cc23a3_2.conda + sha256: 8a095df9bc1d2e50f2504ce8858a047ae29ea634aad6cc0b43298c63361da6d9 + md5: eabfc45786244de252090cf8d55128a8 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libxdmcp >=1.1.5,<2.0a0 + size: 22606 + timestamp: 1789676943335 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxext-1.3.7-h7cc23a3_1.conda + sha256: aa9bbe8b278aacc194e280ff5037f9f9a1f2c5b33ed97de8e7f01cfbe90dda43 + md5: e5b6b28536b81b3f4cb20db4668a4642 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - xorg-libx11 >=1.8.13,<2.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libxext >=1.3.7,<2.0a0 + size: 53124 + timestamp: 1787100841900 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxfixes-6.0.2-h7cc23a3_1.conda + sha256: aec84f554fc897bf4085c7bc8b8f0740e4c224e13bca3cc51c93e7699d56f83a + md5: 09132e874fe0e1f5e4492b0b6b904b6e + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - xorg-libx11 >=1.8.13,<2.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libxfixes >=6.0.2,<7.0a0 + size: 21440 + timestamp: 1787248059682 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxi-1.8.4-h7cc23a3_0.conda + sha256: bb12543188be23b6e16e478d8b550d4e60bb52dc9c6f0667a5c865ceb3e7a881 + md5: 4ae02f09591c09bbe61a2b675d799ce5 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - xorg-libx11 >=1.8.13,<2.0a0 + - xorg-libxext >=1.3.7,<2.0a0 + - xorg-libxfixes >=6.0.2,<7.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libxi >=1.8.4,<2.0a0 + size: 49659 + timestamp: 1792543111146 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxinerama-1.1.6-hd2095e1_1.conda + sha256: 4bd09fade2b2ca9f69cd6c5211f7fb172b81a43697aa1f009cab48eec5a233bf + md5: ff48e795cb92fc74087c7e818d4dcff1 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - libstdcxx >=15 + - xorg-libx11 >=1.8.14,<2.0a0 + - xorg-libxext >=1.3.7,<2.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libxinerama >=1.1.6,<1.2.0a0 + size: 16227 + timestamp: 1794185243418 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxrandr-1.5.5-h7cc23a3_1.conda + sha256: 05a7f25d7f7f5cd32b27a019233ece97167fd8ade255bc13a0e49e53387f4c30 + md5: 798a8c9d171859a022e1cb89e7d0eb10 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - xorg-libx11 >=1.8.13,<2.0a0 + - xorg-libxext >=1.3.7,<2.0a0 + - xorg-libxrender >=0.9.12,<0.10.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libxrandr >=1.5.5,<2.0a0 + size: 31106 + timestamp: 1787246614086 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxrender-0.9.13-h7cc23a3_0.conda + sha256: 008d610d6ec1d021ad678024afd5dcf534ff84d9c1e9d2877ff36d112c89896f + md5: 7249ce52789c3680e889e7335a2e1c3e + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - xorg-libx11 >=1.8.13,<2.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libxrender >=0.9.13,<0.10.0a0 + size: 34604 + timestamp: 1792530399214 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxtst-1.2.6-h7cc23a3_0.conda + sha256: 9d8e7a2db860da3f362284650b447a96688b834bdb3122707b04bae512a1a178 + md5: 05e756ed9e8b2358591d47f6b8939db4 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - xorg-libx11 >=1.8.13,<2.0a0 + - xorg-libxext >=1.3.7,<2.0a0 + - xorg-libxi >=1.8.3,<2.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libxtst >=1.2.6,<2.0a0 + size: 34918 + timestamp: 1792204941937 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-libxxf86vm-1.1.7-h7cc23a3_1.conda + sha256: 264ddaeba8de4fe17fb25d10c6f6c2aac5d8d41d8883a0976dae59b528ef9520 + md5: ac05771f924d124349ef9cc3140e9876 + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + - xorg-libx11 >=1.8.14,<2.0a0 + - xorg-libxext >=1.3.7,<2.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - xorg-libxxf86vm >=1.1.7,<2.0a0 + size: 20109 + timestamp: 1794184632365 +- conda: https://conda.anaconda.org/conda-forge/linux-64/xorg-xorgproto-2025.1-hebe6cf0_3.conda + sha256: 8e9c7ca4fcfe9f0c300e4aa853b79c25411fc4e470decfe8f909b74f60dfb6dd + md5: c3d0a6f03ba3aa312777b41b20a71ec0 + depends: + - libgcc >=15 + - __glibc >=2.17,<3.0.a0 + license: MIT + license_family: MIT + run_exports: {} + size: 596340 + timestamp: 1788874111132 +- conda: https://conda.anaconda.org/conda-forge/linux-64/yaml-0.2.5-hebe6cf0_3.conda + sha256: d164dfa75ecd538f6fd68765defcc06aa875bc697b9b215362d79a2a73125dd0 + md5: e741576fb8f89821ac7c1c537322a33d + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=15 + license: MIT + license_family: MIT + run_exports: + weak: + - yaml >=0.2.5,<0.3.0a0 + size: 84936 + timestamp: 1787228426393 +- conda: https://conda.anaconda.org/conda-forge/linux-64/zig-0.17.1-89c0722_0.conda + sha256: 36fe7fd9960cca013e843798706fa21f93ebb9839527334c7b43bc77b0592193 + md5: 7ba9f63b0c91252ef787d6a574a11c15 + depends: + - zig_linux-64 ==0.17.1 fa519dd_0 + - libstdcxx >=15 + - libgcc >=15 + license: MIT AND Apache-2.0 WITH LLVM-exception AND Apache-2.0 AND LGPL-2.1-or-later AND BSD-2-Clause AND BSD-3-Clause AND ZPL-2.1 AND LicenseRef-Public-Domain + run_exports: + weak: + - zig >=0.17.1,<0.17.2.0a0 + size: 230408 + timestamp: 1794496954055 +- conda: https://conda.anaconda.org/conda-forge/linux-64/zig_impl_linux-64-0.17.1-0addc32_0.conda + sha256: a059082ebd358256c76914c0ecf061b23a79cf705be9f877f3f3e7bcbab13ab3 + md5: d6666c72896f39a252c28a5fd57d929e + depends: + - libstdcxx >=15 + - libgcc >=15 + - __glibc >=2.17,<3.0.a0 + - libclang-cpp22.1 >=22.1.8,<22.2.0a0 + - libllvm22 >=22.1.8,<22.2.0a0 + - libxml2 + - libzlib >=1.3.2,<2.0a0 + - zstd >=1.5.7,<1.6.0a0 + license: MIT AND Apache-2.0 WITH LLVM-exception AND Apache-2.0 AND LGPL-2.1-or-later AND BSD-2-Clause AND BSD-3-Clause AND ZPL-2.1 AND LicenseRef-Public-Domain + run_exports: {} + size: 77529577 + timestamp: 1794496954055 +- conda: https://conda.anaconda.org/conda-forge/linux-64/zig_linux-64-0.17.1-fa519dd_0.conda + sha256: 69801f7b6201bab75250a094b6af4ae6e5457f40e6bce6ef66f0788d43397b1e + md5: b3c1277859f37ea8acf2aec28dc29016 + depends: + - zig_impl_linux-64 ==0.17.1 0addc32_0 + - libstdcxx-devel_linux-64 15.* + - libgcc-devel_linux-64 15.* + - __glibc >=2.17,<3.0.a0 + license: MIT AND Apache-2.0 WITH LLVM-exception AND Apache-2.0 AND LGPL-2.1-or-later AND BSD-2-Clause AND BSD-3-Clause AND ZPL-2.1 AND LicenseRef-Public-Domain + run_exports: + strong: + - libstdcxx >=15 + - libgcc >=15 + size: 362660 + timestamp: 1794496954055 +- conda: https://conda.anaconda.org/conda-forge/linux-64/zstd-1.5.7-hb78ec9c_7.conda + sha256: 47d682b9f6d6ec9eb1a6e6c3e75ea6273e899e78fb7fc59f81d39745009fbc60 + md5: aa459086047c0e5e27023ab19f8cb86a + depends: + - __glibc >=2.17,<3.0.a0 + - libzlib >=1.3.2,<2.0a0 + license: BSD-3-Clause + license_family: BSD + run_exports: + weak: + - zstd >=1.5.7,<1.6.0a0 + size: 601301 + timestamp: 1786599621503 +- conda: https://conda.anaconda.org/conda-forge/noarch/_python_abi3_support-1.0-hd8ed1ab_3.conda + sha256: 2a7204314663eeda5dec482a956f0e2eaf289bd5b9953eaaaad0e81aa64638f2 + md5: 3845f3d75991bae0fb90884662f4327c + depends: + - cpython + - python-gil + license: MIT + license_family: MIT + run_exports: {} + size: 8144 + timestamp: 1784221492234 +- conda: https://conda.anaconda.org/conda-forge/noarch/adwaita-icon-theme-51.0-unix_0.conda + sha256: def01b148aa54d4de29b7d4bf58d941c8699582201db14cf78c6c89fa1666434 + md5: 6f62266fb2bfc35a5071cfa1d6ffdcc9 + depends: + - __unix + - hicolor-icon-theme + - librsvg + license: LGPL-3.0-or-later OR CC-BY-SA-3.0 + run_exports: {} + size: 687517 + timestamp: 1790100765464 +- conda: https://conda.anaconda.org/conda-forge/noarch/alabaster-1.0.0-pyhd8ed1ab_1.conda + sha256: 6c4456a138919dae9edd3ac1a74b6fbe5fd66c05675f54df2f8ab8c8d0cc6cea + md5: 1fd9696649f65fd6611fcdb4ffec738a + depends: + - python >=3.10 + license: BSD-3-Clause + license_family: BSD + run_exports: {} + size: 18684 + timestamp: 1733750512696 +- conda: https://conda.anaconda.org/conda-forge/noarch/babel-2.18.0-pyhcf101f3_1.conda + sha256: a14a9ad02101aab25570543a59c5193043b73dc311a25650134ed9e6cb691770 + md5: f1976ce927373500cc19d3c0b2c85177 + depends: + - python >=3.10 + - python + constrains: + - pytz >=2015.7 + license: BSD-3-Clause + license_family: BSD + run_exports: {} + size: 7684321 + timestamp: 1772555330347 +- conda: https://conda.anaconda.org/conda-forge/noarch/ca-certificates-2026.10.23-hbd8a1cb_0.conda + sha256: 95619b9c1184be7175392eeb0ee7eeb5ccf25d280951f4225f2d62e725790be3 + md5: 3fd02989038a1e1cee627c14c2d73f29 + depends: + - __unix + license: ISC + run_exports: {} + size: 130057 + timestamp: 1792772446739 +- conda: https://conda.anaconda.org/conda-forge/noarch/certifi-2026.10.23-pyhd8ed1ab_3.conda + sha256: e17d21d2f133cae8eede0eef5a8acfa076b1999d00f11e714e1d18c2c8fd02c6 + md5: 6e761a5c8fd92be3a9fec46ade31b481 + depends: + - ca-certificates >=2026.10.23 + - python >=3.10 + license: ISC + run_exports: {} + size: 13539 + timestamp: 1793720135524 +- conda: https://conda.anaconda.org/conda-forge/noarch/charset-normalizer-3.5.1-pyhd8ed1ab_0.conda + sha256: cb60ef3e0631c8bacb4f7057196dee4496091a22baa3bb4b9bccb12c7e1c921b + md5: e0ac3accc64e23e40969d660e5f58ac8 + depends: + - python >=3.10 + license: MIT + license_family: MIT + run_exports: {} + size: 64487 + timestamp: 1786835648298 +- conda: https://conda.anaconda.org/conda-forge/noarch/colorama-0.4.6-pyhd8ed1ab_1.conda + sha256: ab29d57dc70786c1269633ba3dff20288b81664d3ff8d21af995742e2bb03287 + md5: 962b9857ee8e7018c22f2776ffa0b2d7 + depends: + - python >=3.9 + license: BSD-3-Clause + license_family: BSD + run_exports: {} + size: 27011 + timestamp: 1733218222191 +- conda: https://conda.anaconda.org/conda-forge/noarch/cpython-3.13.18-py313hd8ed1ab_100.conda + noarch: generic + sha256: 283ec2ea28bb5f6de4bb74abebca67b984d95879eef436a13b5635396328e082 + md5: 7ffd95656f21420f6c2d0655e3735656 + depends: + - python >=3.13,<3.14.0a0 + - python_abi * *_cp313 + license: Python-2.0 + run_exports: {} + size: 50090 + timestamp: 1793014423191 +- conda: https://conda.anaconda.org/conda-forge/noarch/docutils-0.22.4-pyhd8ed1ab_0.conda + sha256: 0d605569a77350fb681f9ed8d357cc71649b59a304099dc9d09fbeec5e84a65e + md5: d6bd3cd217e62bbd7efe67ff224cd667 + depends: + - python >=3.10 + license: CC-PDDC AND BSD-3-Clause AND BSD-2-Clause AND ZPL-2.1 + run_exports: {} + size: 438002 + timestamp: 1766092633160 +- conda: https://conda.anaconda.org/conda-forge/noarch/font-ttf-dejavu-sans-mono-2.37-hab24e00_0.tar.bz2 + sha256: 58d7f40d2940dd0a8aa28651239adbf5613254df0f75789919c4e6762054403b + md5: 0c96522c6bdaed4b1566d11387caaf45 + license: BSD-3-Clause + license_family: BSD + run_exports: {} + size: 397370 + timestamp: 1566932522327 +- conda: https://conda.anaconda.org/conda-forge/noarch/font-ttf-inconsolata-3.000-h77eed37_0.tar.bz2 + sha256: c52a29fdac682c20d252facc50f01e7c2e7ceac52aa9817aaf0bb83f7559ec5c + md5: 34893075a5c9e55cdafac56607368fc6 + license: OFL-1.1 + license_family: Other + run_exports: {} + size: 96530 + timestamp: 1620479909603 +- conda: https://conda.anaconda.org/conda-forge/noarch/font-ttf-source-code-pro-2.038-h77eed37_0.tar.bz2 + sha256: 00925c8c055a2275614b4d983e1df637245e19058d79fc7dd1a93b8d9fb4b139 + md5: 4d59c254e01d9cde7957100457e2d5fb + license: OFL-1.1 + license_family: Other + run_exports: {} + size: 700814 + timestamp: 1620479612257 +- conda: https://conda.anaconda.org/conda-forge/noarch/font-ttf-ubuntu-0.83-h77eed37_4.conda + sha256: a7384ac883b1acf492fd1aef27431f0f1a647bbb8b5709a1bfab11b0a765f5e5 + md5: 1df978a6efeb98fa80b96f2860b9b280 + license: Ubuntu-font-1.0 + license_family: Other + run_exports: {} + size: 1619009 + timestamp: 1794346192807 +- conda: https://conda.anaconda.org/conda-forge/noarch/fonts-conda-ecosystem-1-0.tar.bz2 + sha256: a997f2f1921bb9c9d76e6fa2f6b408b7fa549edd349a77639c9fe7a23ea93e61 + md5: fee5683a3f04bd15cbd8318b096a27ab + depends: + - fonts-conda-forge + license: BSD-3-Clause + license_family: BSD + run_exports: {} + size: 3667 + timestamp: 1566974674465 +- conda: https://conda.anaconda.org/conda-forge/noarch/fonts-conda-forge-1-hc364b38_1.conda + sha256: 54eea8469786bc2291cc40bca5f46438d3e062a399e8f53f013b6a9f50e98333 + md5: a7970cd949a077b7cb9696379d338681 + depends: + - font-ttf-ubuntu + - font-ttf-inconsolata + - font-ttf-dejavu-sans-mono + - font-ttf-source-code-pro + license: BSD-3-Clause + license_family: BSD + run_exports: {} + size: 4059 + timestamp: 1762351264405 +- conda: https://conda.anaconda.org/conda-forge/noarch/idna-3.20-pyh5ded981_0.conda + sha256: e044b1ec829e2e24f971fa3f3408eb26f1db836e521a58f08b0fd9a03fee47be + md5: ee73be987f9de9ea5c2fdaeefa7b6491 + depends: + - python >=3.11 + - python + license: BSD-3-Clause + license_family: BSD + run_exports: {} + size: 178572 + timestamp: 1790020377150 +- conda: https://conda.anaconda.org/conda-forge/noarch/imagesize-2.0.1-pyhd8ed1ab_0.conda + sha256: 4e787f9ccc31053ccea56d98ecd284a4f788988a3f9c4627db72fdd0b127529b + md5: ebc56022e4ef7e74a829be94c53797ca + depends: + - python >=3.10 + license: MIT + license_family: MIT + run_exports: {} + size: 21467 + timestamp: 1787649248672 +- conda: https://conda.anaconda.org/conda-forge/noarch/jinja2-3.1.6-pyhcf101f3_1.conda + sha256: fc9ca7348a4f25fed2079f2153ecdcf5f9cf2a0bc36c4172420ca09e1849df7b + md5: 04558c96691bed63104678757beb4f8d + depends: + - markupsafe >=2.0 + - python >=3.10 + - python + license: BSD-3-Clause + license_family: BSD + run_exports: {} + size: 120685 + timestamp: 1764517220861 +- conda: https://conda.anaconda.org/conda-forge/noarch/kernel-headers_linux-64-4.18.0-he073ed8_9.conda + sha256: 41557eeadf641de6aeae49486cef30d02a6912d8da98585d687894afd65b356a + md5: 86d9cba083cd041bfbf242a01a7a1999 + constrains: + - sysroot_linux-64 ==2.28 + license: LGPL-2.0-or-later AND LGPL-2.0-or-later WITH exceptions AND GPL-2.0-or-later + license_family: GPL + run_exports: {} + size: 1278712 + timestamp: 1765578681495 +- conda: https://conda.anaconda.org/conda-forge/noarch/libgcc-devel_linux-64-15.3.0-h2b852eb_107.conda + sha256: 5200a1402eb3c3e9b0e4ba38b3cf163be136d020a15477fb86ce6e754d3ae515 + md5: 057ab488a4da13485caa3b672df9824a + depends: + - __unix + license: GPL-3.0-only WITH GCC-exception-3.1 + license_family: GPL + run_exports: {} + size: 3085843 + timestamp: 1790302578256 +- conda: https://conda.anaconda.org/conda-forge/noarch/libstdcxx-devel_linux-64-15.3.0-hb2c5482_107.conda + sha256: 4b2d94a9abf2feedea354e4256756c5dc255b84080e7faed9a324a101cf20e74 + md5: edce245dade1c29f691983796b4b8414 + depends: + - __unix + license: GPL-3.0-only WITH GCC-exception-3.1 + license_family: GPL + run_exports: {} + size: 20673146 + timestamp: 1790302599776 +- conda: https://conda.anaconda.org/conda-forge/noarch/markdown-it-py-4.3.0-pyhd8ed1ab_0.conda + sha256: 4ccea503ad204bba76b8911fce9245488456bf31249fc6e3d95c072602dc1143 + md5: 975dce37a9e7d56c4f56981666578b07 + depends: + - mdurl >=0.1,<1 + - python >=3.10 + license: MIT + license_family: MIT + run_exports: {} + size: 74305 + timestamp: 1794422554733 +- conda: https://conda.anaconda.org/conda-forge/noarch/mdit-py-plugins-0.7.0-pyhd8ed1ab_0.conda + sha256: 9757a597362961195f6bf0cb93b77ed41814f8461fb99e5728a676193d676b1a + md5: b3f1ff606285e87cb76017e004d3b463 + depends: + - markdown-it-py >=3.0.0,<5.0.0 + - python >=3.10 + license: MIT + license_family: MIT + run_exports: {} + size: 56027 + timestamp: 1794422336457 +- conda: https://conda.anaconda.org/conda-forge/noarch/mdurl-0.1.2-pyhd8ed1ab_1.conda + sha256: 78c1bbe1723449c52b7a9df1af2ee5f005209f67e40b6e1d3c7619127c43b1c7 + md5: 592132998493b3ff25fd7479396e8351 + depends: + - python >=3.9 + license: MIT + license_family: MIT + run_exports: {} + size: 14465 + timestamp: 1733255681319 +- conda: https://conda.anaconda.org/conda-forge/noarch/myst-parser-5.2.0-pyhd8ed1ab_0.conda + sha256: a1d937b0705e31496ed97866b7f714b3926b76b4ca111475a68675cc4bde2020 + md5: ec615efa256902ded31b2dd69d011d1b + depends: + - docutils >=0.20,<0.24 + - jinja2 + - markdown-it-py >=4.2.0,<5 + - mdit-py-plugins >=0.7.0,<1 + - python >=3.11 + - pyyaml + - sphinx >=8,<10 + license: MIT + license_family: MIT + run_exports: {} + size: 90015 + timestamp: 1794425517871 +- conda: https://conda.anaconda.org/conda-forge/noarch/packaging-26.3-pyhc364b38_0.conda + sha256: c432626b16768b8dab228bfb706f7060c2d462a21c516d240f68f2f902b5a044 + md5: 936687ed80f295a1f5dbcf8bd34c252c + depends: + - python >=3.9 + - python + license: Apache-2.0 + license_family: APACHE + run_exports: {} + size: 116363 + timestamp: 1785888127370 +- conda: https://conda.anaconda.org/conda-forge/noarch/pygments-2.21.0-pyhcf101f3_0.conda + sha256: f5f015ff1bc3e1b7fc08eee096b1865234189ae0b82bebdb86a5369116e42fa0 + md5: 2882dee445dfa45b0c5afce3ffb7730a + depends: + - python >=3.10 + - python + license: BSD-2-Clause + license_family: BSD + run_exports: {} + size: 959376 + timestamp: 1786995678795 +- conda: https://conda.anaconda.org/conda-forge/noarch/pygments-styles-0.3.0-pyhd8ed1ab_0.conda + sha256: 451e28671386bc66ecd6fdd999aa8a62502596760cb77e4226ad298edef0a76a + md5: 7bcc971fbb4ef305d6953ce95c6179b7 + depends: + - pygments + - python >=3.10 + license: BSD-3-Clause + license_family: BSD + run_exports: {} + size: 21902 + timestamp: 1762266264143 +- conda: https://conda.anaconda.org/conda-forge/noarch/python-gil-3.13.18-h4df99d1_100.conda + sha256: 5fcdc5f22a5d6354230e3757347165f4ddcdcc04fd523b361b59a0d679cd6c91 + md5: 9c939d47ea820fdf3cdbc9582188bb70 + depends: + - cpython 3.13.18.* + - python_abi * *_cp313 + license: Python-2.0 + run_exports: {} + size: 50086 + timestamp: 1793014429956 +- conda: https://conda.anaconda.org/conda-forge/noarch/python_abi-3.13-9_cp313.conda + build_number: 9 + sha256: 9dc0cb6a20ebc7e9bcd8c6868f2bec083c114b0ba20b7118405c036533d5c522 + md5: c5abc97af551bc12d71305852392f75c + constrains: + - python 3.13.* *_cp313 + license: BSD-3-Clause + license_family: BSD + run_exports: {} + size: 6769 + timestamp: 1788302828005 +- conda: https://conda.anaconda.org/conda-forge/noarch/requests-2.34.2-pyhcf101f3_0.conda + sha256: 1715246b19c9f85ee022933b4845f2fc14ac9184981b7b7d9b728bec8e9588da + md5: 4a85203c1d80c1059086ae860836ffb9 + depends: + - python >=3.10 + - certifi >=2023.5.7 + - charset-normalizer >=2,<4 + - idna >=2.5,<4 + - urllib3 >=1.26,<3 + - python + constrains: + - chardet >=3.0.2,<8 + license: Apache-2.0 + license_family: APACHE + run_exports: {} + size: 68709 + timestamp: 1778851103479 +- conda: https://conda.anaconda.org/conda-forge/noarch/roman-numerals-4.1.0-pyhd8ed1ab_0.conda + sha256: 30f3c04fcfb64c44d821d392a4a0b8915650dbd900c8befc20ade8fde8ec6aa2 + md5: 0dc48b4b570931adc8641e55c6c17fe4 + depends: + - python >=3.10 + license: 0BSD OR CC0-1.0 + run_exports: {} + size: 13814 + timestamp: 1766003022813 +- conda: https://conda.anaconda.org/conda-forge/noarch/shibuya-2026.7.12-pyhd8ed1ab_0.conda + sha256: acbbe4fff1f88e9988fc934311845b72ffca5e0f074cd7a9f31c045cb32781d4 + md5: d9011d5b8d6cb55b2bad3d76aa6fa710 + depends: + - pygments-styles + - python >=3.10 + - sphinx + license: BSD-3-Clause + license_family: BSD + run_exports: {} + size: 87339 + timestamp: 1783799362860 +- conda: https://conda.anaconda.org/conda-forge/noarch/snowballstemmer-3.1.1-pyhd8ed1ab_0.conda + sha256: ad89284ea94821c20ff87e64b948e4afc690cf5202d14c009355b0594cf23aea + md5: 46b6abe31482f6bca064b965696ae807 + depends: + - python >=3.10 + license: BSD-3-Clause + license_family: BSD + run_exports: {} + size: 74456 + timestamp: 1780468201547 +- conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-9.2.0-pyhc364b38_0.conda + sha256: 43c6100fbd2980786c0d3dd3cc76906200597a5d6d83995cc0b8e5afbce00c71 + md5: c1dbc9be69a349a057de3ab17160c887 + depends: + - python >=3.13 + - alabaster >=0.7.14 + - babel >=2.13 + - docutils >=0.21,<0.23 + - imagesize >=1.3 + - jinja2 >=3.1 + - packaging >=23.0 + - pygments >=2.17 + - requests >=2.30.0 + - roman-numerals >=1.0.0 + - snowballstemmer >=2.2 + - sphinxcontrib-applehelp >=1.0.7 + - sphinxcontrib-devhelp >=1.0.6 + - sphinxcontrib-htmlhelp >=2.0.6 + - sphinxcontrib-jsmath >=1.0.1 + - sphinxcontrib-qthelp >=1.0.6 + - sphinxcontrib-serializinghtml >=1.1.9 + - colorama >=0.4.6 + - python + license: BSD-2-Clause + license_family: BSD + run_exports: {} + size: 1588783 + timestamp: 1792587728747 +- conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-autoapi-3.9.0-pyh5ded981_0.conda + sha256: 093453d2c50bf7de814f65e62c5568d7d0d1118473eebb7d2ea0e0d095ac4b94 + md5: cdd46294d340a6847af94f2790518752 + depends: + - python >=3.11 + - astroid >=3.0 + - jinja2 + - pyyaml + - sphinx >=7.4.0 + - python + license: MIT + license_family: MIT + run_exports: {} + size: 37103 + timestamp: 1793487424258 +- conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-copybutton-0.5.2-pyhd8ed1ab_1.conda + sha256: 8cd892e49cb4d00501bc4439fb0c73ca44905f01a65b2b7fa05ba0e8f3924f19 + md5: bf22cb9c439572760316ce0748af3713 + depends: + - python >=3.9 + - sphinx >=1.8 + license: MIT + license_family: MIT + run_exports: {} + size: 17893 + timestamp: 1734573117732 +- conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-design-0.8.0-pyhd8ed1ab_0.conda + sha256: 80ad3e0f137df6a7f6380de78c71e911d551f69ffa856043aa53cce289c13f0f + md5: 6a9ef411fc8221580ee1bbd023edee81 + depends: + - python >=3.11 + - sphinx >=7.2,<10 + license: MIT + license_family: MIT + run_exports: {} + size: 1054687 + timestamp: 1794431986619 +- conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-last-updated-by-git-0.3.8-pyhe01879c_0.conda + sha256: f761670b793dcc10a4a2d855de163d9dfd4016636ef093fb3e3d83ac25ed6e97 + md5: 405a232fb900fc631d2f1b5cdf01dea9 + depends: + - python >=3.9 + - sphinx >=1.8 + - python + license: BSD-2-Clause + license_family: BSD + run_exports: {} + size: 17546 + timestamp: 1750694360605 +- conda: https://conda.anaconda.org/conda-forge/noarch/sphinx-sitemap-2.9.0-pyhcf101f3_0.conda + sha256: 1be6289124207256df5dfbfe6ff0a652e313ac5c3e50560c9e510afa76eb702b + md5: 3baeff262222dc87e978a68702bc5797 + depends: + - python >=3.10 + - sphinx-last-updated-by-git + - python + license: MIT + license_family: MIT + run_exports: {} + size: 13441 + timestamp: 1759753011102 +- conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-applehelp-2.0.0-pyhd8ed1ab_1.conda + sha256: d7433a344a9ad32a680b881c81b0034bc61618d12c39dd6e3309abeffa9577ba + md5: 16e3f039c0aa6446513e94ab18a8784b + depends: + - python >=3.9 + - sphinx >=5 + license: BSD-2-Clause + license_family: BSD + run_exports: {} + size: 29752 + timestamp: 1733754216334 +- conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-devhelp-2.0.0-pyhd8ed1ab_1.conda + sha256: 55d5076005d20b84b20bee7844e686b7e60eb9f683af04492e598a622b12d53d + md5: 910f28a05c178feba832f842155cbfff + depends: + - python >=3.9 + - sphinx >=5 + license: BSD-2-Clause + license_family: BSD + run_exports: {} + size: 24536 + timestamp: 1733754232002 +- conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-htmlhelp-2.1.0-pyhd8ed1ab_1.conda + sha256: c1492c0262ccf16694bdcd3bb62aa4627878ea8782d5cd3876614ffeb62b3996 + md5: e9fb3fe8a5b758b4aff187d434f94f03 + depends: + - python >=3.9 + - sphinx >=5 + license: BSD-2-Clause + license_family: BSD + run_exports: {} + size: 32895 + timestamp: 1733754385092 +- conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-jsmath-2.0.0-pyh5ded981_0.conda + sha256: 59cedf5b1c202005f3af3c276e3fb1c7806bb7dbff476f8f8d46abcade227aed + md5: 7e9e28f90ddccdafa9e16a0541841bc4 + depends: + - python >=3.11 + - python + license: BSD-2-Clause + license_family: BSD + run_exports: {} + size: 25630 + timestamp: 1792589772735 +- conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-qthelp-2.0.0-pyhd8ed1ab_1.conda + sha256: c664fefae4acdb5fae973bdde25836faf451f41d04342b64a358f9a7753c92ca + md5: 00534ebcc0375929b45c3039b5ba7636 + depends: + - python >=3.9 + - sphinx >=5 + license: BSD-2-Clause + license_family: BSD + run_exports: {} + size: 26959 + timestamp: 1733753505008 +- conda: https://conda.anaconda.org/conda-forge/noarch/sphinxcontrib-serializinghtml-2.0.0-pyhd8ed1ab_0.conda + sha256: 20b49741065fd7d3fabf98caf6d19b6436badb06b6d41f66b58f1fc2b52f37a1 + md5: f77df1fcf9af03b7287342638befca77 + depends: + - python >=3.10 + - sphinx >=5 + license: BSD-2-Clause + license_family: BSD + run_exports: {} + size: 30640 + timestamp: 1781260357443 +- conda: https://conda.anaconda.org/conda-forge/noarch/sysroot_linux-64-2.28-h4ee821c_9.conda + sha256: c47299fe37aebb0fcf674b3be588e67e4afb86225be4b0d452c7eb75c086b851 + md5: 13dc3adbc692664cd3beabd216434749 + depends: + - __glibc >=2.28 + - kernel-headers_linux-64 4.18.0 he073ed8_9 + - tzdata + license: LGPL-2.0-or-later AND LGPL-2.0-or-later WITH exceptions AND GPL-2.0-or-later + license_family: GPL + run_exports: + strong: + - __glibc >=2.28,<3.0.a0 + size: 24008591 + timestamp: 1765578833462 +- conda: https://conda.anaconda.org/conda-forge/noarch/tzdata-2026e-h5d301ff_0.conda + sha256: 2b7ca858879f183ce2dcc65b300f48a0133d5430550f35b23d80d405a0788dbf + md5: abccc3810d2b97e570dee487f2b46e38 + license: LicenseRef-Public-Domain + run_exports: {} + size: 119208 + timestamp: 1792758382821 +- conda: https://conda.anaconda.org/conda-forge/noarch/urllib3-2.8.0-pyh5ded981_1.conda + sha256: f892d267de12e031d887b90ea44718358f3558c052dfbac45b10b6cd4cee6705 + md5: 8ce0b6bfc873bf2c25b083dd5ee29489 + depends: + - python >=3.11 + - python + license: MIT + license_family: MIT + run_exports: {} + size: 113282 + timestamp: 1794575230703 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/astroid-4.3.4-py313h6ee819a_0.conda + sha256: 2fbc671a15170292020d2d12d2a9c0f98479639c4e34a82a1c7fbc19a8b22166 + md5: df0851b9d0c7dfda3acf6a1acc8396e8 + depends: + - python + - python_abi 3.13.* *_cp313 + license: LGPL-2.1-only + run_exports: {} + size: 576673 + timestamp: 1791464588433 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/bzip2-1.0.8-h4e30115_10.conda + sha256: 8ec22f0ba25cbfc2e64d70cf29459eccd7ffdf6436f6a6ff15bbfef799f7d4f6 + md5: b50612e7d190b8061ab4e7dc119cf4d5 + depends: + - __osx >=11.0 + license: bzip2-1.0.6 + license_family: BSD + run_exports: + weak: + - bzip2 >=1.0.8,<2.0a0 + size: 124965 + timestamp: 1785906749812 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/c-ares-1.34.9-h74c22ad_0.conda + sha256: 74b52d784b3576643da3aea1240a4120c1f25ee057f14ae5a89e8a7b3fb2e69f + md5: 84dac5da92970cdde9789fcbfe63cb3a + depends: + - __osx >=11.0 + license: MIT + license_family: MIT + run_exports: + weak: + - c-ares >=1.34.9,<2.0a0 + size: 201979 + timestamp: 1792507050139 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/cairo-1.18.6-h580cee5_0.conda + sha256: 32ad9b731d0b4c6dd82061201206164b07bd695bc695e5eb3addc0087ed54cca + md5: 0d25672f63cd1c9b08653a0becfbf31a + depends: + - __osx >=11.0 + - fontconfig >=2.18.3,<3.0a0 + - fonts-conda-ecosystem + - icu >=78.3,<79.0a0 + - libcxx >=21 + - libexpat >=2.8.1,<3.0a0 + - libfreetype >=2.14.3 + - libfreetype6 >=2.14.3 + - libglib >=2.90.0,<3.0a0 + - libpng >=1.6.58,<1.7.0a0 + - libzlib >=1.3.2,<2.0a0 + - pixman >=0.46.4,<1.0a0 + license: LGPL-2.1-only or MPL-1.1 + run_exports: + weak: + - cairo >=1.18.6,<2.0a0 + size: 844614 + timestamp: 1790045326889 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/curl-8.23.0-h6651222_0.conda + sha256: c9628a012fba18552ef02a8a2b46db48153d10b9209c57bdec0a33afcdc508a5 + md5: de96eb952f8c91d2b5161eb55f9a24f0 + depends: + - __osx >=11.0 + - krb5 >=1.22.2,<1.23.0a0 + - libcurl 8.23.0 h6651222_0 + - libpsl >=0.23.1,<0.24.0a0 + - libssh2 >=1.11.1,<2.0a0 + - libzlib >=1.3.2,<2.0a0 + - openssl >=3.5.9,<4.0a0 + - zstd >=1.5.7,<1.6.0a0 + license: curl + license_family: MIT + run_exports: {} + size: 183387 + timestamp: 1792014031633 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/dbus-1.16.2-hf049998_2.conda + sha256: 60e265d5ac83198f1d13a43ab5cd2de097b10b460a5ad0764ed62af875b4ecdc + md5: a199888312b83a5c5e2d2880919eb1f2 + depends: + - __osx >=11.0 + - libcxx >=21 + - libglib >=2.88.3,<3.0a0 + - libexpat >=2.8.1,<3.0a0 + - libzlib >=1.3.2,<2.0a0 + license: AFL-2.1 OR GPL-2.0-or-later + run_exports: + weak: + - dbus >=1.16.2,<2.0a0 + size: 398252 + timestamp: 1788197996006 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/emacs-30.2-ha2f6bed_6.conda + sha256: 4b31cfee001921ffa2342d85c6e19f45b9c4de984a1ff35c892c7ad0cd08c723 + md5: 5615ed71fb7ccbfe82475d322d6213b8 + depends: + - dbus + - __osx >=11.0 + - gnutls >=3.8.11,<3.9.0a0 + - libtree-sitter >=0.25.9,<0.26.0a0 + - libsqlite >=3.53.4,<4.0a0 + - libwebp-base >=1.6.0,<2.0a0 + - libjpeg-turbo >=3.2.0,<4.0a0 + - gmp >=6.3.0,<7.0a0 + - ncurses >=6.6,<7.0a0 + - librsvg >=2.62.3,<3.0a0 + - libzlib >=1.3.2,<2.0a0 + - libxml2 + - libxml2-16 >=2.14.6 + - libpng >=1.6.58,<1.7.0a0 + - libtiff >=4.7.2,<4.8.0a0 + - gdk-pixbuf >=2.44.8,<3.0a0 + - dbus >=1.16.2,<2.0a0 + - giflib >=6.1.3,<6.2.0a0 + - libglib >=2.88.3,<3.0a0 + - libexpat >=2.8.1,<3.0a0 + license: GPL-3.0-only + license_family: GPL + run_exports: {} + size: 53125036 + timestamp: 1786884731551 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/fontconfig-2.18.3-h81aa574_1.conda + sha256: 004570d35fb0eff73ce3ae49b209a47622d0c2e580dd0dc4c61d59626b386a09 + md5: 8ac8cc3fe744b484de4387703134d8b2 + depends: + - __osx >=11.0 + - libexpat >=2.8.1,<3.0a0 + - libfreetype >=2.14.3 + - libfreetype6 >=2.14.3 + - libintl >=0.25.1,<1.0a0 + - libzlib >=1.3.2,<2.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - fontconfig >=2.18.3,<3.0a0 + - fonts-conda-ecosystem + size: 265659 + timestamp: 1786667932256 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/freetype-2.14.3-hce30654_2.conda + sha256: 90681f1d0658cb2fd49a074f644eb4774272499290487a4bebb1c4df01d6997b + md5: 2f4cc7dc2e6622591735c49dda1b92aa + depends: + - libfreetype 2.14.3 hce30654_2 + - libfreetype6 2.14.3 h2ed5691_2 + license: GPL-2.0-only OR FTL + run_exports: + weak: + - libfreetype >=2.14.3 + - libfreetype6 >=2.14.3 + size: 175388 + timestamp: 1786641016583 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/fribidi-1.0.18-hb001647_0.conda + sha256: 0eb7cf0378cfd45c4729e2eedd896bc1fab01872d1ed204d6ea8bbf853a0138d + md5: 08fef45968356b6a9093c19f05d2364e + depends: + - __osx >=11.0 + license: LGPL-2.1-or-later + run_exports: + weak: + - fribidi >=1.0.18,<2.0a0 + size: 64404 + timestamp: 1793323489033 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/gdk-pixbuf-2.44.8-h5867e2c_2.conda + sha256: 96dcac22eaea2f24b9c92e8be078c3e39058829aa4db2a8103c1a4e85f8925ed + md5: 3a84786e0c929f4a05d08c07be5ec9b3 + depends: + - __osx >=11.0 + - libglib >=2.88.3,<3.0a0 + - libintl >=0.25.1,<1.0a0 + - libjpeg-turbo >=3.2.0,<4.0a0 + - liblzma >=5.8.3,<6.0a0 + - libpng >=1.6.58,<1.7.0a0 + - libtiff >=4.7.2,<4.8.0a0 + license: LGPL-2.1-or-later + license_family: LGPL + run_exports: + weak: + - gdk-pixbuf >=2.44.8,<3.0a0 + size: 552802 + timestamp: 1788490405006 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/giflib-6.1.3-h74c22ad_2.conda + sha256: 36a1605ea258ea805fd5a0f23f07ce3febcf4ac041d1ea99d0b31902b79f4358 + md5: edc562dcbe5872664817e64575aa325f + depends: + - __osx >=11.0 + license: MIT + license_family: MIT + run_exports: + weak: + - giflib >=6.1.3,<6.2.0a0 + size: 82055 + timestamp: 1788948759889 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/gmp-6.3.0-hf5e55b1_3.conda + sha256: 980cb1bbc3656d6f923d44297a2c4ab75f20482b8930c70537fd7f1ef2378894 + md5: bbfa5bd261b68536ddcda39e03d3407f + depends: + - libcxx >=19 + - __osx >=11.0 + license: GPL-2.0-or-later OR LGPL-3.0-or-later + run_exports: + weak: + - gmp >=6.3.0,<7.0a0 + size: 399307 + timestamp: 1786629210135 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/gnutls-3.8.13-hfe86254_0.conda + sha256: d36222db9e35788af78b6f41f66dc702d20b18375a9059c81ee074ea4c63d72a + md5: 9fafe1b7ed7d1264dc032e55227e2529 + depends: + - __osx >=11.0 + - gmp >=6.3.0,<7.0a0 + - libasprintf >=0.25.1,<1.0a0 + - libcxx >=19 + - libgettextpo >=0.25.1,<1.0a0 + - libidn2 >=2,<3.0a0 + - libintl >=0.25.1,<1.0a0 + - libtasn1 >=4.21.0,<5.0a0 + - nettle >=3.10.1,<3.11.0a0 + - p11-kit >=0.26.2,<0.27.0a0 + license: LGPL-2.1-or-later + license_family: LGPL + run_exports: + weak: + - gnutls >=3.8.13,<3.9.0a0 + size: 1906035 + timestamp: 1778045117683 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/graphite2-1.3.15-h784d473_1.conda + sha256: 471f34a187fdb4f2df33e26f2e471b16c239a5b277903f643d9c3a8c9a9f44ec + md5: 0c7b78d9ffff4f5a6ca28d346f734d8f + depends: + - libcxx >=19 + - __osx >=11.0 + license: LGPL-2.0-or-later + license_family: LGPL + run_exports: + weak: + - graphite2 >=1.3.15,<2.0a0 + size: 86493 + timestamp: 1786118637573 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/icu-78.3-py310h579977c_2.conda + sha256: 6cdb5dee54c72e56ab189fb3ad33cb28533553d42590e7e831160248f4416a43 + md5: a5efc0b42bb8b42e97d0a29ae3e3c187 + depends: + - __osx >=11.0 + license: MIT + license_family: MIT + run_exports: + weak: + - icu >=78.3,<79.0a0 + size: 14070242 + timestamp: 1786545847761 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/krb5-1.22.2-h34f8a20_2.conda + sha256: aaea1d42b07769920db2af7471ece9399d2613448863da64ad8272998db5db34 + md5: 15235dd10450d67bc25ccafd5b46d2bc + depends: + - __osx >=11.0 + - libcxx >=21 + - libedit >=3.1.20250104,<3.2.0a0 + - libedit >=3.1.20250104,<4.0a0 + - openssl >=3.5.7,<4.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - krb5 >=1.22.2,<1.23.0a0 + size: 1165740 + timestamp: 1786762145768 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/lerc-4.3.0-h0699d0c_0.conda + sha256: 93b1189cf3e47b93fe613dc08213cf22b892650097e8df77519e50f9301e9f62 + md5: b0a537a2f2650404b5fe49f46db50c9d + depends: + - __osx >=11.0 + - libcxx >=21 + license: Apache-2.0 + license_family: Apache + run_exports: + weak: + - lerc >=4.3.0,<5.0a0 + size: 188293 + timestamp: 1793411290334 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libasprintf-0.25.1-hae62183_2.conda + sha256: af6e0e598ace7cdac145daec66c39916016ebcd4d960246b5e90c4247e47be52 + md5: fa3b4ff4b5cbde3a77824949f5d0b1ef + depends: + - __osx >=11.0 + - libcxx >=21 + license: LGPL-2.1-or-later + run_exports: + weak: + - libasprintf >=0.25.1,<1.0a0 + size: 52487 + timestamp: 1790118662123 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libclang-cpp22.1-22.1.8-default_h79071a4_11.conda + sha256: f5e3e35d9a855636a09cd872ea16e195bdd32171ecee295a417f1b7ac2c50a6b + md5: 1eae4048550ca47885ed2bdf6b139aa4 + depends: + - libcxx >=22.1.8 + - __osx >=11.0 + - libzlib >=1.3.2,<2.0a0 + - zstd >=1.5.7,<1.6.0a0 + - libxml2 + - libxml2-16 >=2.15.4 + - libllvm22 >=22.1.8,<22.2.0a0 + license: Apache-2.0 WITH LLVM-exception + license_family: APACHE + run_exports: + weak: + - libclang-cpp22.1 >=22.1.8,<22.2.0a0 + size: 15941660 + timestamp: 1791933888154 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libcurl-8.23.0-h6651222_0.conda + sha256: d9f60525b665e50da15c84fcb4e74e6b1f0a56ea4c89a02d4258f23c3fe1f02c + md5: b955db4c41b9820eba0aa2c9a3c74a37 + depends: + - __osx >=11.0 + - krb5 >=1.22.2,<1.23.0a0 + - libnghttp2 >=1.68.1,<2.0a0 + - libpsl >=0.23.1,<0.24.0a0 + - libssh2 >=1.11.1,<2.0a0 + - libzlib >=1.3.2,<2.0a0 + - openssl >=3.5.9,<4.0a0 + - zstd >=1.5.7,<1.6.0a0 + license: curl + license_family: MIT + run_exports: + weak: + - libcurl >=8.23.0,<9.0a0 + size: 425637 + timestamp: 1792014025908 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libcxx-22.1.8-h55c6f16_0.conda + sha256: a2e7abab5add9750fab064c024394de48e49f97631c605ad5db5c8ac3fc769ef + md5: 89f76a2a21a3ec3ec983b5eb237c4113 + depends: + - __osx >=11.0 + license: Apache-2.0 WITH LLVM-exception + license_family: Apache + run_exports: {} + size: 569349 + timestamp: 1781670209146 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libdeflate-1.26-h72bfca4_0.conda + sha256: f9c75ef67dbcc8e3c255d37e32948550bc8aa6752102c181686630b9ede96b8d + md5: 3f49c4c4ebcdb9fa285e5c73441063c1 + depends: + - __osx >=11.0 + license: MIT + license_family: MIT + run_exports: + weak: + - libdeflate >=1.26,<1.27.0a0 + size: 55312 + timestamp: 1787442891411 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libedit-3.1.20260512-pl5321h26f1114_0.conda + sha256: 5692a969e49b200c7874d1e869d281753361980b2ecfe9191b571d7e550f8b92 + md5: ef2ab2462744ec6ba3a54c34dcc6a06e + depends: + - ncurses + - __osx >=11.0 + - ncurses >=6.6,<7.0a0 + license: BSD-2-Clause + license_family: BSD + run_exports: + weak: + - libedit >=3.1.20260512,<3.2.0a0 + size: 108512 + timestamp: 1791327440683 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libev-4.33-h1a92334_3.conda + sha256: c0100064506ae8abb432c5a506d474f10af2cf48c33d62bc221fb28b6d6ff6ac + md5: 19e86c8a6a47e92bb2e70ca12e758c5c + depends: + - __osx >=11.0 + license: BSD-2-Clause OR GPL-2.0-or-later + license_family: GPL + run_exports: + weak: + - libev >=4.33,<4.34.0a0 + size: 39991 + timestamp: 1785917376956 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libexpat-2.9.0-h6111c0a_0.conda + sha256: b155c524118f751ad8b1c823397bab8b7f715f7e3ca10479925867a7e23e7e9d + md5: f85a1fda9a2758a7aef2a7787d9c0203 + depends: + - __osx >=11.0 + constrains: + - expat 2.9.0.* + license: MIT + license_family: MIT + run_exports: {} + size: 69681 + timestamp: 1793054210049 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libffi-3.7.0-h47dc5ef_1.conda + sha256: 2783389a7b9dda04c62cc54c6bbeb03dd3cef24b3fc642715d02a3fa19464a9a + md5: 216bbcc23c11e9695b3db4a8771d76eb + depends: + - __osx >=11.0 + license: MIT + license_family: MIT + run_exports: + weak: + - libffi >=3.7.0,<3.8.0a0 + size: 43637 + timestamp: 1787753403688 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libfreetype-2.14.3-hce30654_2.conda + sha256: 19ce8bd320414cb6b9889ecbf48a3ded848b0d1068b76ff6bea099bd7387d6f3 + md5: ee1fc5bba400ff0cae27fbf141a1ae0c + depends: + - libfreetype6 >=2.14.3 + license: GPL-2.0-only OR FTL + run_exports: {} + size: 8367 + timestamp: 1786641013393 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libfreetype6-2.14.3-h2ed5691_2.conda + sha256: d9b203d6484ad491b5b5f33d49a9d7a91189d776a9adae53d2b63af18ec11e6a + md5: 881cfb44ea02cc9849f612725a959660 + depends: + - __osx >=11.0 + - libpng >=1.6.58,<1.7.0a0 + - libzlib >=1.3.2,<2.0a0 + constrains: + - freetype >=2.14.3 + license: GPL-2.0-only OR FTL + run_exports: {} + size: 340923 + timestamp: 1786641012794 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libgettextpo-0.25.1-hae62183_2.conda + sha256: ea81b8992214e8c4cd289ba4b9092004aa941ddb12900a32cfbc28be6d3156ff + md5: 93e3f213a8e3fa21fb7b1407d6a4cd44 + depends: + - __osx >=11.0 + - libiconv >=1.18,<2.0a0 + - libintl 0.25.1 hae62183_2 + license: GPL-3.0-or-later + license_family: GPL + run_exports: + weak: + - libgettextpo >=0.25.1,<1.0a0 + size: 182332 + timestamp: 1790118703147 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libglib-2.90.0-hccd281b_0.conda + sha256: 4ec64c476881b31f211842952f192208a3af0925a596da227f4d97fb9a63e0ac + md5: 8f63a5f35547d0c6d819830ebe0d3245 + depends: + - __osx >=11.0 + - libintl >=0.25.1,<1.0a0 + - libzlib >=1.3.2,<2.0a0 + - libffi >=3.7.0,<3.8.0a0 + - libiconv >=1.18,<2.0a0 + - pcre2 >=10.47,<10.48.0a0 + constrains: + - glib >2.66 + license: LGPL-2.1-or-later + run_exports: + weak: + - libglib >=2.90.0,<3.0a0 + size: 4489939 + timestamp: 1789478088421 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libharfbuzz-15.0.0-hcda0f7c_0.conda + sha256: 1cf7900cfd17b60a8e3f76a31ca95140deca4781899e290b499b6caad82058b2 + md5: 2bf1803b0f15fa26d9f22ce8364d16df + depends: + - __osx >=11.0 + - cairo >=1.18.6,<2.0a0 + - graphite2 >=1.3.15,<2.0a0 + - icu >=78.3,<79.0a0 + - libcxx >=21 + - libfreetype >=2.14.3 + - libfreetype6 >=2.14.3 + - libglib >=2.90.0,<3.0a0 + - libpng >=1.6.59,<1.7.0a0 + - libzlib >=1.3.2,<2.0a0 + license: MIT + license_family: MIT + run_exports: {} + size: 1146987 + timestamp: 1792769126357 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libharfbuzz-devel-15.0.0-hcda0f7c_0.conda + sha256: 764b95c1630e66f7eebca2f75ab3dd2cb039aa1d007d00c763e122cd29564a8a + md5: 14a65f11238f07714323d65bc2c9034f + depends: + - __osx >=11.0 + - cairo >=1.18.6,<2.0a0 + - freetype + - graphite2 >=1.3.15,<2.0a0 + - icu >=78.3,<79.0a0 + - libcxx >=21 + - libfreetype >=2.14.3 + - libfreetype6 >=2.14.3 + - libglib >=2.90.0,<3.0a0 + - libharfbuzz 15.0.0 hcda0f7c_0 + - libpng >=1.6.59,<1.7.0a0 + - libzlib >=1.3.2,<2.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - libharfbuzz >=15.0.0 + size: 1673578 + timestamp: 1792769143858 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libiconv-1.18-he4c29f2_3.conda + sha256: 689a14968267f2f97c07112fca5636e7d756036b9aee969911267c20bd3eea1f + md5: 17f4744c0873e9f77ac9b5cd0a27c187 + depends: + - __osx >=11.0 + license: LGPL-2.1-only + run_exports: + weak: + - libiconv >=1.18,<2.0a0 + size: 750816 + timestamp: 1787033961086 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libidn2-2.3.8-ha90df94_1.conda + sha256: 6d9d2db2c8a645f63073553e9497ea266507c940de42800f2f0faddbf00149cd + md5: d4b2e2dd2a1a1e2df8b4a3f05034beb4 + depends: + - __osx >=11.0 + - libintl >=0.25.1,<1.0a0 + - libunistring >=0,<1.0a0 + license: LGPL-2.0-only + license_family: LGPL + run_exports: + weak: + - libidn2 >=2,<3.0a0 + size: 145706 + timestamp: 1760385907428 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libintl-0.25.1-hae62183_2.conda + sha256: b43c6645e668f86d04d5c06d6dc17efe921bbd9244be4b77946d56fb950a3fcc + md5: a3a4193101bc5427e6cf8be81d5eeddf + depends: + - __osx >=11.0 + - libiconv >=1.18,<2.0a0 + license: LGPL-2.1-or-later + run_exports: + weak: + - libintl >=0.25.1,<1.0a0 + size: 90024 + timestamp: 1790118675563 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libjpeg-turbo-3.2.1-hb001647_0.conda + sha256: 957469c69b3b9c9e6ae48dc1267c5c9dfe0db9e1aefa5fa9abf9798224aa23c9 + md5: d420b10837f3b64259b1febf263b5f7a + depends: + - __osx >=11.0 + constrains: + - jpeg <0.0.0a + license: IJG AND BSD-3-Clause AND Zlib + run_exports: + weak: + - libjpeg-turbo >=3.2.1,<4.0a0 + size: 555606 + timestamp: 1793156969006 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libllvm22-22.1.8-h759d1ac_3.conda + sha256: 70d7bbba65233fec41fb2294e81351d81b8d7e21206113135604fed4dd7fdcf6 + md5: 3b912a5fea164495d16d3edc64242f3a + depends: + - __osx >=11.0 + - libcxx >=21 + - libxml2 + - libxml2-16 >=2.15.4 + - libzlib >=1.3.2,<2.0a0 + - zstd >=1.5.7,<1.6.0a0 + license: Apache-2.0 WITH LLVM-exception + license_family: Apache + run_exports: + weak: + - libllvm22 >=22.1.8,<22.2.0a0 + size: 30242555 + timestamp: 1790103714094 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/liblzma-5.8.3-h8088a28_1.conda + sha256: 23d0630046a3e8b164d8f80f2b74ed2605af2e7050ab9913018056402fae4311 + md5: 8ab10323068b107661a4b9a4af84f3b5 + depends: + - __osx >=11.0 + constrains: + - xz 5.8.3.* + license: 0BSD + run_exports: + weak: + - liblzma >=5.8.3,<6.0a0 + size: 91720 + timestamp: 1786348695846 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libmpdec-4.0.0-h84a0fba_2.conda + sha256: 04cc136c5a956a73aa14e0a160b5822b0b29714e67b299fa1b1fd16dbcba5366 + md5: ff33a4dbd93abc8a798cc4e0e7c8136d + depends: + - __osx >=11.0 + license: BSD-2-Clause + license_family: BSD + run_exports: {} + size: 73289 + timestamp: 1786651074391 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libnghttp2-1.71.0-h29223de_0.conda + sha256: d533256cdb91c676b106728e8437a5d96e9c02dc6a99b948f1b04b04a92620c2 + md5: a8f77fc66cd70f2c883764a318fa2f26 + depends: + - libev >=4.33,<5.0a0 + - __osx >=11.0 + - libcxx >=21 + - c-ares >=1.34.9,<2.0a0 + - libev >=4.33,<4.34.0a0 + - openssl >=3.5.9,<4.0a0 + - libzlib >=1.3.2,<2.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - libnghttp2 >=1.71.0,<2.0a0 + size: 671516 + timestamp: 1793628217888 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libpango-1.58.2-hc2ac4f2_3.conda + sha256: 90118019ce64d713888abbe41a15be9e5885bdc8d5d4f84480e615299d2b5a01 + md5: 1261a045589c8d98219cbd258b71ea95 + depends: + - __osx >=11.0 + - fribidi >=1.0.17,<2.0a0 + - libglib >=2.90.0,<3.0a0 + - libharfbuzz >=14.6.0 + - cairo >=1.18.6,<2.0a0 + - libfreetype >=2.14.3 + - libfreetype6 >=2.14.3 + - fontconfig >=2.18.3,<3.0a0 + - fonts-conda-ecosystem + license: LGPL-2.1-or-later + run_exports: {} + size: 308102 + timestamp: 1792050658787 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libpango-devel-1.58.2-haa2d88b_3.conda + sha256: 2434b8c792ce63ba089da94a21acb25ec45430a053d5cbe537d18f18771b27a7 + md5: 4bac42499647d2567ef309b6193d63f6 + depends: + - libpango ==1.58.2 hc2ac4f2_3 + - freetype + - libharfbuzz-devel + - __osx >=11.0 + - fribidi >=1.0.17,<2.0a0 + - libglib >=2.90.0,<3.0a0 + - libharfbuzz >=14.6.0 + - cairo >=1.18.6,<2.0a0 + - libfreetype >=2.14.3 + - libfreetype6 >=2.14.3 + - fontconfig >=2.18.3,<3.0a0 + - fonts-conda-ecosystem + license: LGPL-2.1-or-later + run_exports: + weak: + - libpango >=1.58.2,<2.0a0 + size: 213942 + timestamp: 1792050658787 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libpng-1.6.59-hf5e6511_0.conda + sha256: 4de4dc4cb7432c328c1eaf4f7cc9c6b48c073eab1e9c6723d4533e6d57e7d595 + md5: 4f99571d5354c39f2621b8b6e3a9afa3 + depends: + - __osx >=11.0 + - libzlib >=1.3.2,<2.0a0 + license: zlib-acknowledgement + run_exports: + weak: + - libpng >=1.6.59,<1.7.0a0 + size: 290299 + timestamp: 1790805167385 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libpsl-0.23.1-hdb0c161_1.conda + sha256: c8c3153df39abedf3413483f672151ad70f1adb0c06c192bdf7ec432c3616b07 + md5: 5d270f716a2b4bc13df9af8612071b17 + depends: + - __osx >=11.0 + - libcxx >=21 + - icu >=78.3,<79.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - libpsl >=0.23.1,<0.24.0a0 + size: 72673 + timestamp: 1786970928205 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libpython-3.13.18-h0af5753_100_cp313.conda + build_number: 100 + sha256: 2ccf200438a519589d86acb96c75822f7ba6f6a9e654d1da355521cec4adfac3 + md5: 57bd17817c81cfe8d491e328dcb59a43 + depends: + - __osx >=11.0 + license: Python-2.0 + run_exports: + weak: + - libpython >=3.13,<4.0a0 + size: 1823071 + timestamp: 1793014722078 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/librsvg-2.62.4-hc8ac265_0.conda + sha256: 3bd54de0136907782249a0d5797744ecac5bbd77026f5f2712dd62390c5c9f77 + md5: 878c79beee628e3b683ddc9094aaad1e + depends: + - __osx >=11.0 + - pango >=1.58.2,<2.0a0 + - libglib >=2.90.0,<3.0a0 + - fontconfig >=2.18.3,<3.0a0 + - fonts-conda-ecosystem + - libxml2-16 >=2.15.4 + - gdk-pixbuf >=2.44.8,<3.0a0 + - libharfbuzz >=14.5.0 + - cairo >=1.18.6,<2.0a0 + constrains: + - __osx >=11.0 + license: LGPL-2.1-or-later + run_exports: + weak: + - librsvg >=2.62.4,<3.0a0 + size: 3888310 + timestamp: 1790276358897 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libsqlite-3.54.1-hca69786_0.conda + sha256: 998cd122027b2523f2f25807b1d476b82a168489d16b1430fd848a9a6b606a80 + md5: b3fc67af56dfdf7c9ee7d8fdae21f654 + depends: + - __osx >=11.0 + - icu >=78.3,<79.0a0 + - libzlib >=1.3.2,<2.0a0 + license: blessing + run_exports: + weak: + - libsqlite >=3.54.1,<4.0a0 + size: 953427 + timestamp: 1792175622950 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libssh2-1.11.1-hbf2880b_1.conda + sha256: a056e518c3d2d09fbb1778cea80c0c95338fb24adf1a817bbf90fb484850a304 + md5: d957a8eda98c49b073e8dcfd677c127a + depends: + - libzlib >=1.3.2,<2.0a0 + - openssl >=3.5.7,<4.0a0 + license: BSD-3-Clause + license_family: BSD + run_exports: + weak: + - libssh2 >=1.11.1,<2.0a0 + size: 280492 + timestamp: 1786714226814 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libtasn1-4.21.0-hb001647_1.conda + sha256: a18d0abb7414e4caba4043c3b9e7f981b62b016ed6f203437d7232b175ba2e67 + md5: c298706579b4d8ac9af0df9557fdebae + depends: + - __osx >=11.0 + license: LGPL-2.1-or-later + run_exports: + weak: + - libtasn1 >=4.21.0,<5.0a0 + size: 117547 + timestamp: 1793068747771 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libtiff-4.7.2-h87d37ca_2.conda + sha256: 3c1cf481a60ed8598093641b3a41ee1a7bb78413029ec566a238927504e941bd + md5: ac0e529ed6020472c12f740602e58ab5 + depends: + - __osx >=11.0 + - lerc >=4.3.0,<5.0a0 + - libcxx >=21 + - libdeflate >=1.26,<1.27.0a0 + - libjpeg-turbo >=3.2.1,<4.0a0 + - liblzma >=5.8.3,<6.0a0 + - libwebp-base >=1.6.0,<2.0a0 + - libzlib >=1.3.2,<2.0a0 + - zstd >=1.5.7,<1.6.0a0 + license: HPND + run_exports: + weak: + - libtiff >=4.7.2,<4.8.0a0 + size: 380333 + timestamp: 1794045696512 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libtree-sitter-0.25.9-he530434_0.conda + sha256: 439049f9222d51c0747d004a324cf97dc66138eff9f449627007f7acd4fad971 + md5: 805b557db147781ba60665802414d3e8 + depends: + - __osx >=11.0 + license: MIT + license_family: MIT + run_exports: + weak: + - libtree-sitter >=0.25.9,<0.26.0a0 + size: 207080 + timestamp: 1757201895620 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libunistring-0.9.10-h3422bc3_0.tar.bz2 + sha256: a1afe12ab199f82f339eae83405d293d197f2485d45346a709703bc7e8299949 + md5: d88e77a4861e20bd96bde6628ee7a5ae + license: GPL-3.0-only OR LGPL-3.0-only + run_exports: + weak: + - libunistring >=0,<1.0a0 + size: 1577561 + timestamp: 1626955172521 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libwebp-base-1.6.0-h202fb40_1.conda + sha256: 0ff54650d470c7e54cbeffdd53a8c063e055a7bcf784388c0385ce5c4741b0f4 + md5: 168a13e329259710b28277abc1395b8e + depends: + - __osx >=11.0 + constrains: + - libwebp 1.6.0 + license: BSD-3-Clause + license_family: BSD + run_exports: + weak: + - libwebp-base >=1.6.0,<2.0a0 + size: 294522 + timestamp: 1785955350410 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libxml2-16-2.15.4-heb56d2d_1.conda + sha256: 1acd4dd49c6f54440dc172ab469d0e2c7c3c02de5b1f21158a233eb585ec3c38 + md5: ef82ce9c5e6a0bb8bc9cb0e6935f18ca + depends: + - __osx >=11.0 + - icu >=78.3,<79.0a0 + - libiconv >=1.18,<2.0a0 + - liblzma >=5.8.3,<6.0a0 + - libzlib >=1.3.2,<2.0a0 + constrains: + - libxml2 2.15.4 + license: MIT + license_family: MIT + run_exports: {} + size: 469239 + timestamp: 1791465646245 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libxml2-2.15.4-h550178d_1.conda + sha256: f333b4c6c823ea317aeb0b817520ae3ba2fb16277923d848f5f2aee2049198e5 + md5: 5881b9ab679553078d590db82d7e57b3 + depends: + - __osx >=11.0 + - icu >=78.3,<79.0a0 + - libiconv >=1.18,<2.0a0 + - liblzma >=5.8.3,<6.0a0 + - libxml2-16 2.15.4 heb56d2d_1 + - libzlib >=1.3.2,<2.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - libxml2 + - libxml2-16 >=2.15.4 + size: 41382 + timestamp: 1791465651969 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/libzlib-1.3.2-h8088a28_3.conda + sha256: a18fa5d5bac452401459f966cf0d872224e8080c4ff93c77e168d43ab42ef9d7 + md5: f39288f0ea63ae962e1a2e4f355a0d75 + depends: + - __osx >=11.0 + constrains: + - zlib 1.3.2 *_3 + license: Zlib + license_family: Other + run_exports: + weak: + - libzlib >=1.3.2,<2.0a0 + size: 47822 + timestamp: 1785277049190 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/lychee-0.24.2-h9d00c72_1.conda + sha256: 9c35bbfe243d26c07a21375cfb863f376991e4dd6de3d6bfb147569c60d65cf0 + md5: 1ec074eabe183deb5a7e65fb9e776c3e + depends: + - __osx >=11.0 + constrains: + - __osx >=11.0 + license: Apache-2.0 OR MIT + run_exports: {} + size: 5351911 + timestamp: 1791278249049 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/markupsafe-3.0.4-py313h0984dbd_5.conda + sha256: c996dadcd7c6f0df9ade4e019cf0858761039a62c9dde312475e0822468af8d9 + md5: 4a83df2cb081468887b1ba02de0736a2 + depends: + - python + - __osx >=11.0 + - python_abi 3.13.* *_cp313 + constrains: + - jinja2 >=3.0.0 + license: BSD-3-Clause + run_exports: {} + size: 28227 + timestamp: 1794823823453 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/ncurses-6.6-he64c551_1.conda + sha256: 7024a48c8c0d0114ed4ab53c76bf9275d50e91ba7cea367a9aead638d3c29c68 + md5: 3dfa0d0316dc246cd44937a557de4501 + depends: + - __osx >=11.0 + license: X11 AND BSD-3-Clause + run_exports: + weak: + - ncurses >=6.6,<7.0a0 + size: 804298 + timestamp: 1786355189145 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/nettle-3.10.1-hfc803ee_1.conda + sha256: f57e68f8e7e3197340fa6edc6cc66afd6015f1dc52850a7c2ab20cec66b766d0 + md5: b0229aa5ed12f2d0f33ac3e88a63e1db + depends: + - __osx >=11.0 + - gmp >=6.3.0,<7.0a0 + license: GPL-2.0-or-later OR LGPL-3.0-or-later + run_exports: + weak: + - nettle >=3.10.1,<3.11.0a0 + size: 456749 + timestamp: 1787065337321 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/openssl-3.6.5-h55eecbc_0.conda + sha256: 44fbc526456571a9fb8fa18157f6f269d4d4bd40eef20183a93b9c9296f94497 + md5: 45d9179cdf6e53d88aec034246f0dad6 + depends: + - __osx >=11.0 + - ca-certificates + license: Apache-2.0 + license_family: Apache + run_exports: + weak: + - openssl >=3.6.5,<4.0a0 + size: 3111573 + timestamp: 1791097959641 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/p11-kit-0.26.5-h329a732_2.conda + sha256: ba17447c428db9e0a7c74067e30ef7c9aab29835d69676dad3076e62ae9f8763 + md5: b6dc8c0520f47b73a42dec38794bad8c + depends: + - __osx >=11.0 + - libffi >=3.7.0,<3.8.0a0 + - libtasn1 >=4.21.0,<5.0a0 + license: MIT + license_family: MIT + run_exports: + weak: + - p11-kit >=0.26.5,<0.27.0a0 + size: 800354 + timestamp: 1788196674456 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/pango-1.58.2-hc6efcc1_3.conda + sha256: 4206a8d179dbc2ae070d7c5ed148b73ccf5ec8a962f428e2645527bad9c016de + md5: 17bb0626b5ac18be2c28e65b6d949e3a + depends: + - libpango-devel ==1.58.2 haa2d88b_3 + license: LGPL-2.1-or-later + run_exports: + weak: + - libpango >=1.58.2,<2.0a0 + size: 15035 + timestamp: 1792050658787 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/pcre2-10.47-he63d830_1.conda + sha256: f8c415329b542e1fca1ff2917b80e687c18302dfa0353530668b90cb225b494f + md5: 5ab90033816cbe4097e8a297e5179f67 + depends: + - __osx >=11.0 + - bzip2 >=1.0.8,<2.0a0 + - libzlib >=1.3.2,<2.0a0 + license: BSD-3-Clause + license_family: BSD + run_exports: + weak: + - pcre2 >=10.47,<10.48.0a0 + size: 851704 + timestamp: 1787294559157 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/pixman-0.46.4-h784d473_3.conda + sha256: 4779cd57231ce2e96fac643fcbdd4a6f51a57986264545445574e9c4acf526d3 + md5: 9a99c0b60efe41c194d01c182d000733 + depends: + - __osx >=11.0 + - libcxx >=19 + license: MIT + license_family: MIT + run_exports: + weak: + - pixman >=0.46.4,<1.0a0 + size: 198717 + timestamp: 1786106922508 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/python-3.13.18-hb59dee6_100_cp313.conda + build_number: 100 + sha256: ca7809f986ebd644a418bd52e3bfa1ece8979441917c08e47d341b9e818c652b + md5: fe33fb185e1b63c33394512bccf8807f + depends: + - __osx >=11.0 + - bzip2 >=1.0.8,<2.0a0 + - libexpat >=2.8.5,<3.0a0 + - libffi >=3.7.0,<3.8.0a0 + - liblzma >=5.8.3,<6.0a0 + - libmpdec >=4.0.0,<5.0a0 + - libpython 3.13.18 h0af5753_100_cp313 + - libsqlite >=3.54.1,<4.0a0 + - libzlib >=1.3.2,<2.0a0 + - ncurses >=6.6,<7.0a0 + - openssl >=3.5.9,<4.0a0 + - python_abi 3.13.* *_cp313 + - readline >=8.3,<9.0a0 + - tk >=8.6.13,<8.7.0a0 + - tzdata + license: Python-2.0 + run_exports: + weak: + - python_abi 3.13.* *_cp313 + noarch: + - python + size: 11971526 + timestamp: 1793014757271 + python_site_packages_path: lib/python3.13/site-packages +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/pyyaml-6.0.3-py313h5c85ca1_3.conda + sha256: a5c89aa6d093077b4569c5f33182c93ca7de4fe8536d2ce27a5bec6a407f0ecc + md5: bd7d78d5a001b042e7520cbd724b21a5 + depends: + - python + - yaml + - __osx >=11.0 + - python_abi 3.13.* *_cp313 + - yaml >=0.2.5,<0.3.0a0 + license: MIT + license_family: MIT + run_exports: {} + size: 204613 + timestamp: 1793655118128 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/readline-8.3-h8b90a29_1.conda + sha256: d6782b430e6dce4fe8c7ac118cd988d5a193eb4a7f60741edfaede58016b6110 + md5: 9347fd56a002e6b58946831d48fe62f6 + depends: + - __osx >=11.0 + - ncurses >=6.6,<7.0a0 + license: GPL-3.0-only + license_family: GPL + run_exports: + weak: + - readline >=8.3,<9.0a0 + size: 314395 + timestamp: 1787033878899 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/tk-8.6.13-hbeba79b_4.conda + sha256: 857d89087ae7f2c328cf256728affcb7343031a148b4af847334d248a9cf564c + md5: 90a01bf394d1c594e0eb9258f967d828 + depends: + - __osx >=11.0 + - libzlib >=1.3.2,<2.0a0 + license: TCL + run_exports: + weak: + - tk >=8.6.13,<8.7.0a0 + size: 3342183 + timestamp: 1787272852357 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/yaml-0.2.5-h74c22ad_3.conda + sha256: 3e78c43207502418fc5fb2317bbbefe5df8b6fc1051d90bdcd1c881c76bb4193 + md5: 31cf6dcc138abe673c9440cd6fe6c6fe + depends: + - __osx >=11.0 + license: MIT + license_family: MIT + run_exports: + weak: + - yaml >=0.2.5,<0.3.0a0 + size: 77530 + timestamp: 1787228556857 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/zig-0.17.1-0ccaba2_0.conda + sha256: b79e9a60a36a4001178fe43eb454e74d67266f5ff0828e5581e455e41d8634f7 + md5: 515c9a0205dc70ea68d556fd361a2c69 + depends: + - zig_osx-arm64 ==0.17.1 a676bd3_0 + - libcxx >=22 + license: MIT AND Apache-2.0 WITH LLVM-exception AND Apache-2.0 AND LGPL-2.1-or-later AND BSD-2-Clause AND BSD-3-Clause AND ZPL-2.1 AND LicenseRef-Public-Domain + run_exports: + weak: + - zig >=0.17.1,<0.17.2.0a0 + size: 229303 + timestamp: 1794496879060 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/zig_impl_osx-arm64-0.17.1-8405819_0.conda + sha256: a5cf38eef3105506af4a1488c5cee42e182e8c47bfa56228899cd30dc9c7ee1f + md5: aa771c478390ba34eb22842cdc320334 + depends: + - libcxx 22.* + - libcxx >=22 + - __osx >=11.0 + - libxml2 + - libxml2-16 >=2.15.4 + - zstd >=1.5.7,<1.6.0a0 + - libllvm22 >=22.1.8,<22.2.0a0 + - libzlib >=1.3.2,<2.0a0 + - libclang-cpp22.1 >=22.1.8,<22.2.0a0 + license: MIT AND Apache-2.0 WITH LLVM-exception AND Apache-2.0 AND LGPL-2.1-or-later AND BSD-2-Clause AND BSD-3-Clause AND ZPL-2.1 AND LicenseRef-Public-Domain + run_exports: {} + size: 76882981 + timestamp: 1794496879060 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/zig_osx-arm64-0.17.1-a676bd3_0.conda + sha256: f65739411083e5b9d486bf73af89f1f9dc49032b3135690fbd2dabd49e0bb672 + md5: 74a14e85555a80674578bfa6b77b93cf + depends: + - zig_impl_osx-arm64 ==0.17.1 8405819_0 + license: MIT AND Apache-2.0 WITH LLVM-exception AND Apache-2.0 AND LGPL-2.1-or-later AND BSD-2-Clause AND BSD-3-Clause AND ZPL-2.1 AND LicenseRef-Public-Domain + run_exports: + strong: + - libcxx >=22 + size: 335709 + timestamp: 1794496879060 +- conda: https://conda.anaconda.org/conda-forge/osx-arm64/zstd-1.5.7-hf451053_7.conda + sha256: da867f5092eb0cb746d353694f0098031fd9817a4ce7d5743121209ae0f406ca + md5: 4ec2684c73812cc2c3d78379384a39cc + depends: + - __osx >=11.0 + - libzlib >=1.3.2,<2.0a0 + license: BSD-3-Clause + license_family: BSD + run_exports: + weak: + - zstd >=1.5.7,<1.6.0a0 + size: 433687 + timestamp: 1786599629846 diff --git a/pixi.toml b/pixi.toml new file mode 100644 index 0000000..b3577c4 --- /dev/null +++ b/pixi.toml @@ -0,0 +1,42 @@ +# The documentation toolchain, pinned by pixi.lock. `pixi run -e docs docbld` +# builds docs/build/html the way CI does; docs/orgmode/contributing.org has +# the steps. In a repository that already has a pixi.toml, copy the +# [feature.docs.*] tables and the docs environment into it. +[workspace] +name = "eessi-arch-guard" +channels = ["conda-forge"] +platforms = ["linux-64", "osx-arm64"] + +[feature.docs.dependencies] +python = "3.13.*" +emacs = "30.*" +curl = "*" +lychee = "*" +zig = "0.17.1.*" +sphinx = "9.*" +myst-parser = "*" +shibuya = "*" +sphinx-copybutton = "*" +sphinx-design = "*" +sphinx-sitemap = "*" +sphinx-autoapi = "*" + +[feature.docs.tasks] +# Org pages to reStructuredText, docs/orgmode -> docs/source. +mkrst = { cmd = "emacs -Q --batch --load export.el", cwd = "docs" } +# API pages from the code, into docs/source/reference/api/. +mkapi = { cmd = "zig run docs/tools/zig_api.zig -- --module eessi-arch-guard --root zig/main.zig --out docs/source/reference/api/zig --source-url 'https://github.com/stackhands/eessi-arch-guard/blob/{ref}/' --title 'Zig API' --follow-private-imports" } +sphinxbld = { cmd = "sphinx-build -W -n --keep-going -d docs/build/doctrees -b html docs/source docs/build/html", depends-on = ["mkrst", "mkapi"] } +# The Zig autodoc site, served beside the Sphinx pages at api/. +autodoc = { cmd = "zig build docs --prefix docs/build/autodoc && rm -rf docs/build/html/api && cp -r docs/build/autodoc/docs docs/build/html/api", depends-on = ["sphinxbld"] } +# Every internal link and anchor resolves, and no page names a site. The +# changelog may name what a release removed; its links are still checked. +doccheck = { cmd = "python docs/tools/check_site.py docs/build/html --sources docs/orgmode --exempt changelog.html", depends-on = ["autodoc"] } +docbld = { depends-on = ["doccheck"] } +# External links; needs the network, so CI runs it as its own step. +linkcheck = { cmd = "lychee --config lychee.toml --no-progress 'docs/build/html/**/*.html'" } +# Generated files are the ignored ones under docs/source (see .gitignore). +docdel = { cmd = "rm -rf docs/build && git clean -fdX docs/source" } + +[environments] +docs = { features = ["docs"], no-default-feature = true } diff --git a/src/eessi_arch_guard.py b/src/eessi_arch_guard.py index bcebf7f..7ab7f4a 100755 --- a/src/eessi_arch_guard.py +++ b/src/eessi_arch_guard.py @@ -250,12 +250,14 @@ def safe_rel_subdir(value: str) -> bool: def safe_absolute(path: str) -> bool: + """Absolute path: starts with ``/``, no newline, CR or NUL, no ``..`` segment.""" if not path or not path.startswith("/") or any(c in path for c in "\n\r\0"): return False return all(part != ".." for part in path.split("/")) def strip_startup(env: Mapping[str, str]) -> Dict[str, str]: + """A copy of ``env`` without STARTUP_VARS, which make bash read a file or trace.""" child = dict(env) for key in STARTUP_VARS: child.pop(key, None) @@ -263,6 +265,11 @@ def strip_startup(env: Mapping[str, str]) -> Dict[str, str]: def value_emit_ok(value: str, multiline: bool) -> bool: + """Whether a value can be published. + + A NUL byte never can; a newline or carriage return only when + ``multiline`` is true, for the quoted values of the shell output. + """ if "\0" in value: return False if not multiline and ("\n" in value or "\r" in value): @@ -390,6 +397,11 @@ def render_bytes( def parse_loaded_modules(env: Mapping[str, str]) -> LoadedModules: + """The EESSI module and the other modules of LOADEDMODULES, in order. + + The error token is set instead when the list is empty, holds a name that + is not safe to pass to Lmod, or has no single ``EESSI/`` entry. + """ raw = env.get("LOADEDMODULES", "") names = [part for part in raw.split(":") if part] if not names: @@ -404,6 +416,11 @@ def parse_loaded_modules(env: Mapping[str, str]) -> LoadedModules: def parse_cpu_line(stdout: str) -> Optional[List[str]]: + """The colon-separated candidates of the one line ``cpupath`` prints. + + None when the output holds a NUL or another control character, is longer + than MAX_ARCH_STDOUT, or is not exactly one non-empty line. + """ if "\0" in stdout or len(stdout) > MAX_ARCH_STDOUT: return None parts = [line for line in stdout.splitlines() if line != ""] @@ -427,6 +444,7 @@ class DecisionLimit: """One deadline for the lock, both archdetect runs, and the restore helper.""" def __init__(self, seconds: float) -> None: + """Start the deadline ``seconds`` from now; ``install`` takes SIGTERM.""" self.seconds = seconds self.deadline = time.monotonic() + seconds self.child_pgid: Optional[int] = None @@ -435,9 +453,15 @@ def __init__(self, seconds: float) -> None: self._previous = None def remaining(self) -> float: + """Seconds left before the deadline; zero or less once it has passed.""" return self.deadline - time.monotonic() def check(self) -> None: + """Stop the decision after a SIGTERM or once no time is left. + + Raises ``_Terminated`` or ``_Deadline``; neither while ``committing``, + when the result is being written to the cache. + """ if self.committing: return if self.terminated: @@ -446,9 +470,11 @@ def check(self) -> None: raise _Deadline() def install(self) -> None: + """Handle SIGTERM: note it and kill the running command's process group.""" self._previous = signal.signal(signal.SIGTERM, self._handle) def restore(self) -> None: + """Put back the SIGTERM handler ``install`` replaced.""" if self._previous is not None: signal.signal(signal.SIGTERM, self._previous) self._previous = None @@ -466,9 +492,11 @@ def _handle(self, _signum: int, _frame: object) -> None: return def hold_signals(self) -> None: + """Block SIGTERM while a command starts, until ``child_pgid`` names it.""" signal.pthread_sigmask(signal.SIG_BLOCK, {signal.SIGTERM}) def release_signals(self) -> None: + """Unblock SIGTERM; one that arrived while it was held is handled now.""" signal.pthread_sigmask(signal.SIG_UNBLOCK, {signal.SIGTERM}) @@ -913,6 +941,7 @@ def _prepare_cpuinfo(env: Mapping[str, str]) -> Tuple[str, Optional[str], Mappin def march_of(candidate: str) -> str: + """The compiler target of a CPU subdirectory: its last segment, ``-`` as ``_``.""" leaf = candidate.rsplit("/", 1)[-1] return leaf.replace("-", "_") @@ -1017,6 +1046,11 @@ def probe_accel(env: Mapping[str, str]) -> AccelProbe: def lmod_invocable(path: str) -> bool: + """Whether LMOD_CMD can be run as given. + + Not empty, not an option, no line break or NUL, and a regular file this + user may execute. + """ if not path or path.startswith("-") or any(c in path for c in "\n\r\0"): return False return os.path.isfile(path) and os.access(path, os.X_OK) @@ -1091,6 +1125,12 @@ def restore_work_base(env: Mapping[str, str]) -> str: def source_exports( module_env: Mapping[str, str], script: bytes ) -> Tuple[Optional[Dict[str, str]], str]: + """Run the shell code Lmod printed and return the environment it leaves. + + The code runs in bash from ``module_env``, without STARTUP_VARS, from a + private directory under the restore workspace. Returns None and the + error when it fails. + """ base = restore_work_base(os.environ) tmp = tempfile.mkdtemp(prefix="eessi-arch-guard-", dir=base) try: @@ -1117,6 +1157,10 @@ def source_exports( def run_lmod( module_env: Mapping[str, str], lmod_cmd: str, args: Sequence[str] ) -> subprocess.CompletedProcess: + """Run ``$LMOD_CMD bash ARGS`` from ``module_env`` without STARTUP_VARS. + + Its stdout is the shell code that makes the change. + """ return subprocess.run( [lmod_cmd, "bash", *args], capture_output=True, @@ -1128,6 +1172,11 @@ def run_lmod( def apply_lmod( module_env: Mapping[str, str], lmod_cmd: str, args: Sequence[str] ) -> Tuple[Optional[Dict[str, str]], str]: + """The environment after one Lmod command, such as ``load R/4.4.2``. + + Returns None and Lmod's stderr when the command fails, or None and the + error when its shell code does. + """ proc = run_lmod(module_env, lmod_cmd, args) if proc.returncode != 0: return None, proc.stderr.decode("utf-8", "replace") @@ -1241,6 +1290,10 @@ def do_restore(payload: Mapping[str, object]) -> Dict[str, object]: def restore_main() -> int: + """The ``--restore`` helper: a JSON request on stdin, the JSON result on stdout. + + Returns 0; on an error it writes the reason to stderr and returns 1. + """ try: payload = json.loads(sys.stdin.buffer.read().decode("utf-8")) sys.stdout.write(json.dumps(do_restore(payload))) @@ -1253,6 +1306,12 @@ def restore_main() -> int: def call_restore( env: Mapping[str, str], eessi: str, modules: Sequence[str], pin: str = "" ) -> RestoreResult: + """Reload ``eessi`` and ``modules`` through the restore helper. + + The helper is this file again with ``--restore``, run in a new private + workspace with a clean environment. ``pin`` is the CPU subdirectory the + loads after the purge are pinned to, empty for none. + """ payload = { "v": 1, "env": _wire_map(env), @@ -1532,6 +1591,11 @@ def gpu_scope_key(env: Mapping[str, str]) -> str: def cache_digest(env: Mapping[str, str]) -> str: + """The cache key in a cache file's name: 16 hex digits of a SHA-256. + + The hash covers the KEY_FIELDS values, the task's processors and its + visible GPUs, joined by NUL bytes. + """ parts = [env.get(key, "") for key in KEY_FIELDS] parts.append(task_scope_key(env)) parts.append(gpu_scope_key(env)) @@ -1546,6 +1610,11 @@ def _safe_component(text: str) -> str: def cache_directory(env: Mapping[str, str]) -> Optional[str]: + """The directory for the decision cache, or None for no cache. + + With ``--strict`` it is the private restore workspace; otherwise TMPDIR + when it is a safe absolute directory, else ``/tmp``. + """ if _STRICT_MODE: try: return restore_work_base(env) @@ -1733,6 +1802,12 @@ def cached_decide( accel_probe=probe_accel, restore=call_restore, ) -> Outcome: + """``decide`` once per job step, node, user, output mode and cache key. + + The first task takes the lock and writes its outcome; the others wait for + the lock and read it. Without SLURM_JOB_ID, or without a usable cache + directory or lock file, every task decides on its own. + """ path = cache_file_path(env, shell) if path is None or not hasattr(os, "O_NOFOLLOW"): return decide(env, shell, cpu_probe, accel_probe, restore) @@ -1880,6 +1955,7 @@ def _config_untrusted(path: str) -> Optional[str]: def parse_config(text: str) -> Dict[str, str]: + """The settings of a configuration file given as text, as ``parse_config_bytes`` reads them.""" settings, _bad = parse_config_bytes(text.encode("utf-8")) return settings @@ -1911,6 +1987,7 @@ def parse_config_bytes(blob: bytes) -> Tuple[Dict[str, str], Tuple[str, ...]]: def config_chain(settings: Optional[Mapping[str, str]]) -> Optional[str]: + """The ``chain`` setting, or None when it is unset or empty.""" if not settings: return None return settings.get("chain") or None @@ -1947,6 +2024,11 @@ def site_config(script_path: str) -> Tuple[Optional[Dict[str, str]], Optional[st def run_chain(path: str, env: Mapping[str, str]) -> Tuple[int, bytes, bytes]: + """Run the chained prolog with no arguments and ``env``. + + Returns its exit status, 1 when a signal ended it, its stdout and its + stderr. + """ proc = subprocess.run( [path], stdout=subprocess.PIPE, diff --git a/zig/envmap.zig b/zig/envmap.zig index 78db6e8..f714e34 100644 --- a/zig/envmap.zig +++ b/zig/envmap.zig @@ -26,6 +26,8 @@ pub fn fromEnvp(arena: Allocator, envp: common.proc.Envp) Allocator.Error!Map { return m; } +/// A copy of `m` allocated in `arena`; the names and values it points to are +/// shared, not copied. pub fn clone(arena: Allocator, m: Map) Allocator.Error!Map { return m.clone(arena); } @@ -94,6 +96,9 @@ fn eqlOpt(a: ?[]const u8, b: ?[]const u8) bool { return std.mem.eql(u8, a.?, b.?); } +/// Why `render` refuses a delta: a name that is not a variable name, a prolog +/// value with a newline, carriage return or NUL byte, or a prolog line longer +/// than `text.prolog_line_max`. pub const RenderError = Allocator.Error || error{ UnsafeName, UnsafeValue, LineTooLong }; /// The ValueError text the Python guard raised for each refusal. diff --git a/zig/guard.zig b/zig/guard.zig index bb31719..b1f6d82 100644 --- a/zig/guard.zig +++ b/zig/guard.zig @@ -20,12 +20,16 @@ const empty: []const u8 = ""; const Map = envmap.Map; const Changes = envmap.Changes; +/// DIAGNOSE_LIMIT: the most failed modules the one-call-each load collects +/// before it stops; the message then says "(stopped after 32)". pub const diagnose_limit = 32; const max_arch_stdout = 65536; const cpuinfo_read_max = 16 * 1024 * 1024; const cache_read_max = 8 * 1024 * 1024; const lock_poll_ms = 50; +/// The variables whose values, with the task's processors and visible GPUs, +/// make up the digest in a cache file's name. pub const key_fields = [_][]const u8{ "EESSI_SOFTWARE_SUBDIR", "EESSI_ACCEL_SUBDIR", "LOADEDMODULES", "MODULEPATH", "EESSI_INIT_PREFIX", "EESSI_PROC_CPUINFO", "PATH", @@ -37,17 +41,31 @@ const waitpkg_marches = [_][]const u8{ "sapphirerapids", "sierraforest", "tremont", }; +/// What a decision came to. pub const Kind = enum { + /// Nothing was compared: EESSI is not loaded, the guard is turned off, + /// the detection is pinned, or EESSI_ARCH_GUARD_MISSING=ignore covers a + /// node with no software directory. skip, + /// The node's targets are the loaded ones. noop, + /// The modules were loaded again for this node. reloaded, + /// A reload was needed and could not be made; only + /// EESSI_ARCH_GUARD_FAILED changes. failed, }; +/// A decision's result, as the cache stores it. pub const Outcome = struct { + /// The variables to set, or to unset where the value is null. changes: Changes = .empty, + /// The message: a print line in the prolog output, a line on stderr with + /// --shell. message: ?[]const u8 = null, + /// What the decision came to. kind: Kind, + /// The reason EESSI_ARCH_GUARD_VERBOSE=1 writes to stderr. detail: ?[]const u8 = null, }; @@ -62,17 +80,27 @@ pub var os_failure: []const u8 = ""; // ---- the deadline and SIGTERM ------------------------------------------ +/// DecisionLimit: the deadline of one decision and the SIGTERM it may get. pub const Limit = struct { + /// The `nowMs` reading at which the decision stops. deadline_ms: i64, + /// Set by the SIGTERM handler. terminated: std.atomic.Value(bool) = .init(false), + /// Set while a finished decision is written to the cache, which neither + /// the deadline nor SIGTERM interrupts. committing: std.atomic.Value(bool) = .init(false), + /// The process group of the command the decision is running, 0 for none. child_pgid: std.atomic.Value(i32) = .init(0), + /// The SIGTERM action to put back when the decision ends. previous: linux.Sigaction = undefined, + /// Milliseconds left before the deadline; zero or less once it passed. pub fn remainingMs(l: *const Limit) i64 { return l.deadline_ms - nowMs(); } + /// error.Terminated after a SIGTERM, error.Deadline once no time is + /// left; neither while the result is being written to the cache. pub fn check(l: *const Limit) Stop!void { if (l.committing.load(.seq_cst)) return; if (l.terminated.load(.seq_cst)) return error.Terminated; @@ -107,6 +135,7 @@ fn removeLimit(l: *Limit) void { active_limit = null; } +/// The monotonic clock in milliseconds, as Python's time.monotonic() counts. pub fn nowMs() i64 { var ts: linux.timespec = undefined; _ = linux.clock_gettime(.MONOTONIC, &ts); @@ -115,22 +144,35 @@ pub fn nowMs() i64 { // ---- context ----------------------------------------------------------- +/// What every step of a decision needs. pub const Ctx = struct { + /// Holds everything the decision allocates; freed when the program ends. arena: Allocator, + /// The task's environment. env: Map, + /// --strict is on the command line: the restore and the cache use only a + /// private workspace. strict: bool, /// Absolute path of this program, for the restore helper. self_exe: []const u8, + /// The deadline while `limitedDecide` runs; null otherwise, as in the + /// restore helper, which its parent's deadline covers. limit: ?*Limit = null, }; // ---- running programs ---------------------------------------------------- +/// Why a command gave no result: the decision stopped, the command could not +/// be started, or something no message was written for. pub const RunError = Stop || error{ CannotRun, Unexpected }; +/// A command that ran to the end. pub const Ran = struct { + /// The exit status, or 128 plus the signal that ended it. code: u32, + /// What the command wrote to stdout; more than 64 MiB is an error. stdout: []const u8, + /// What the command wrote to stderr; more than 1 MiB is an error. stderr: []const u8, }; @@ -211,17 +253,31 @@ fn runBash(c: *Ctx, args: []const []const u8, env: Map, why: *[]const u8) RunErr // ---- probes ------------------------------------------------------------ +/// What `probeCpu` found. pub const CpuProbe = struct { + /// `ok`: a target was found; `none`: no candidate has a software + /// directory; `error`: the detection could not be run or read. status: enum { ok, none, @"error" }, + /// This node's CPU target, set when the status is `ok`. target: []const u8 = "", + /// The detection's candidates, best first, without those the waitpkg rule + /// drops. candidates: []const []const u8 = &.{}, + /// Why the status is `error`. err: []const u8 = "", + /// The target again when the waitpkg rule changed the choice, for the + /// reload to pin with EESSI_SOFTWARE_SUBDIR_OVERRIDE; empty otherwise. override: []const u8 = "", }; +/// What `probeAccel` found. pub const AccelProbe = struct { + /// `ok`: an accelerator subdirectory; `none`: no accelerator; `error`: + /// the detection could not be run or printed something else. status: enum { ok, none, @"error" }, + /// The accelerator subdirectory, such as accel/nvidia/cc90. subdir: []const u8 = "", + /// Why the status is `error`. err: []const u8 = "", }; @@ -739,6 +795,11 @@ fn prepareCpuinfo(c: *Ctx, env: Map) PreparedCpu { return .{ .path = tmp, .cleanup = tmp, .child = child }; } +/// probe_cpu: this node's CPU target. Runs `eessi_archdetect.sh -a cpupath` +/// from EESSI_INIT_PREFIX on the processors the task may use, drops the +/// candidates whose -march needs waitpkg when a kept processor lacks it, and +/// takes the first candidate with a directory +/// `$EESSI_PREFIX/software/$EESSI_OS_TYPE//software`. pub fn probeCpu(c: *Ctx, env: Map) Stop!CpuProbe { const prefix = env.get("EESSI_PREFIX") orelse empty; const os_type = env.get("EESSI_OS_TYPE") orelse empty; @@ -788,6 +849,9 @@ fn installed(c: *Ctx, prefix: []const u8, os_type: []const u8, items: []const [] return ""; } +/// probe_accel: this node's accelerator subdirectory from +/// `eessi_archdetect.sh accelpath`. A nonzero exit or empty output is no +/// accelerator; other output must be one accel/nvidia/ccN or accel/amd/gfxN. pub fn probeAccel(c: *Ctx, env: Map) Stop!AccelProbe { const init = env.get("EESSI_INIT_PREFIX") orelse empty; if (!text.safeAbsolute(init)) return .{ .status = .@"error", .err = "EESSI_INIT_PREFIX is missing or unsafe" }; @@ -806,6 +870,8 @@ pub fn probeAccel(c: *Ctx, env: Map) Stop!AccelProbe { return .{ .status = .ok, .subdir = out }; } +/// lmod_invocable: whether LMOD_CMD can be run as given: not empty, not an +/// option, no line break or NUL, and a regular file this user may execute. pub fn lmodInvocable(path: []const u8) bool { if (path.len == 0 or path[0] == '-' or text.hasLineBreakOrNul(path)) return false; if (!isFile(path)) return false; @@ -829,6 +895,7 @@ fn privateDirectory(c: *Ctx, path: []const u8) ?[]const u8 { return c.arena.dupe(u8, real) catch null; } +/// No directory the restore may work in; the reason is in `why`. pub const WorkError = error{Unavailable}; /// restore_work_base: EESSI_ARCH_GUARD_WORKDIR when set (must be private), @@ -912,9 +979,13 @@ fn rmtree(c: *Ctx, p: []const u8) void { /// RestoreResult. `ran` is false when the restore stopped before Lmod could /// answer: no workspace, no helper, or no usable reply from it. pub const Restore = struct { + /// The helper loaded every module. ok: bool, + /// The environment after the loads, when `ok`. env: ?Map = null, + /// The modules the helper names as not loading for this node. missing: []const []const u8 = &.{}, + /// The first line of the helper's error, or why the restore did not run. err: []const u8 = "", ran: bool = true, }; @@ -1303,6 +1374,10 @@ fn nonEmpty(env: Map, k: []const u8) bool { return (env.get(k) orelse empty).len > 0; } +/// decide: compare the loaded targets with this node's and, when they +/// differ, reload the modules through the restore helper and return the +/// delta. `shell` selects the --shell output, whose values may span lines. +/// Returns error.Deadline or error.Terminated when the limit stops it. pub fn decide(c: *Ctx, env: Map, shell: bool) Stop!Outcome { if (c.limit) |l| try l.check(); if (std.mem.eql(u8, env.get("EESSI_ARCH_GUARD") orelse empty, "0")) @@ -1612,6 +1687,10 @@ test "a flock error other than would-block is an OSError, not a wait" { try std.testing.expectEqualStrings("[Errno 9] Bad file descriptor", os_failure); } +/// cached_decide: `decide`, once per job step, node, user, output mode and +/// cache key. The first task takes the lock and writes its outcome; the +/// others wait for the lock and read it. Without SLURM_JOB_ID, or without a +/// usable cache directory or lock file, every task decides on its own. pub fn cachedDecide(c: *Ctx, env: Map, shell: bool) Stop!Outcome { const p = cachePath(c, env, shell) orelse return decide(c, env, shell); const dirfd = fsx.openDir(fsx.cwd, p.dir, true) catch return decide(c, env, shell); diff --git a/zig/main.zig b/zig/main.zig index 0bb6a9a..c8b033d 100644 --- a/zig/main.zig +++ b/zig/main.zig @@ -18,6 +18,8 @@ const cli = common.cli; const Allocator = std.mem.Allocator; const empty: []const u8 = ""; +/// The version `--version` prints first, `.version` of build.zig.zon. The +/// Python guard's `__version__` and pyproject.toml name the same one. pub const version = build_options.version; const tool = "eessi-arch-guard"; /// The Python guard's bare version, then this build (COMPAT.md). @@ -104,6 +106,9 @@ pub fn oom() noreturn { emergencyExit("MemoryError", "out of memory"); } +/// A panic is an uncaught exception to the Python guard: the skip line +/// "eessi-arch-guard: skipped, panic: MESSAGE", then exit 0, or 78 with +/// --strict, so the task still starts. pub const panic = std.debug.FullPanic(struct { fn f(msg: []const u8, _: ?usize) noreturn { emergencyExit("panic", msg); @@ -503,6 +508,10 @@ fn realMain(arena: Allocator, argv0: []const u8, argv: []const []const u8, envp: return 0; } +/// Run the command line and return the exit status. Before anything can +/// fail it notes whether this is local task 0 and whether --shell and +/// --strict were given, and installs the crash handlers, so that a crash +/// prints the skip line where that run would print it. pub fn main(init: std.process.Init.Minimal) u8 { emergency_announce = localTaskZero(init.environ.block.slice.ptr); var arena_state = std.heap.ArenaAllocator.init(std.heap.page_allocator); diff --git a/zig/text.zig b/zig/text.zig index da8353d..ab4b739 100644 --- a/zig/text.zig +++ b/zig/text.zig @@ -9,15 +9,30 @@ const Allocator = std.mem.Allocator; // Python's text handling, shared with the other tools through zig-common. const pytext = common.pytext; +/// One character of a byte string as Python's UTF-8 decoder sees it: its +/// code point, or null for a byte that is not valid UTF-8, and its length. pub const Char = pytext.Char; +/// The next character of a byte string; an invalid byte is a character of +/// its own, as surrogateescape decodes it. pub const nextChar = pytext.nextChar; +/// bytes.decode("utf-8", "replace"): each ill-formed run becomes one U+FFFD. pub const decodeReplace = pytext.decodeReplace; +/// str.isspace for the characters str.strip() removes. pub const pyWhitespace = pytext.pyWhitespace; +/// str.strip(): the bytes without leading and trailing Unicode whitespace. pub const pyStrip = pytext.pyStrip; +/// str.split() with no separator: the runs between Unicode whitespace. pub const pySplit = pytext.pySplit; +/// shlex.quote: the value as it is when a shell reads it as one word, +/// single-quoted otherwise. pub const shellQuote = pytext.shellQuote; +/// MAX_MODULE_NAME: the longest module name the guard loads, in bytes. pub const max_module_name = 256; +/// PROLOG_LINE_MAX: the longest line, newline included, the guard prints for +/// slurmstepd. Slurm 17.11 reads 4094 bytes of a TaskProlog line and the +/// rest as a line of its own, which a longer value could turn into another +/// directive. pub const prolog_line_max = 4094; fn isAlnumU(c: u8) bool { @@ -55,7 +70,7 @@ fn allDigits(s: []const u8) bool { return s.len > 0; } -/// EESSI_MODULE_RE: ^EESSI/$ +/// EESSI_MODULE_RE: `^EESSI/$` pub fn eessiModule(s: []const u8) bool { return std.mem.startsWith(u8, s, "EESSI/") and modSegment(s["EESSI/".len..]); } @@ -93,6 +108,7 @@ pub fn safeAbsolute(s: []const u8) bool { return true; } +/// Whether `s` holds a newline, a carriage return or a NUL byte. pub fn hasLineBreakOrNul(s: []const u8) bool { return std.mem.findAny(u8, s, "\n\r\x00") != null; } @@ -104,6 +120,9 @@ pub fn safeComponent(s: []const u8) bool { return true; } +/// value_emit_ok: whether a value can be published. A NUL byte never can; a +/// newline or carriage return only when `multiline` is set, for the quoted +/// values of the shell output. pub fn valueEmitOk(v: []const u8, multiline: bool) bool { if (std.mem.findScalar(u8, v, 0) != null) return false; if (!multiline and std.mem.findAny(u8, v, "\n\r") != null) return false; @@ -120,9 +139,16 @@ const never_emit = [_][]const u8{ "PPID", }; +/// SOFT_DROP: the prompt variables a delta leaves out when their value cannot +/// be published. Any other such value stops the reload; a prompt with a +/// newline in it must not. pub const soft_drop = [_][]const u8{ "PS1", "PS2", "PS3", "PROMPT_COMMAND" }; +/// STARTUP_VARS: the variables that make bash read a file or trace, which +/// `envmap.stripStartup` removes from the environment of the shells the +/// guard starts. pub const startup_vars = [_][]const u8{ "BASH_ENV", "ENV", "SHELLOPTS", "BASHOPTS", "BASH_XTRACEFD", "PS4" }; +/// Whether `s` is one of the strings in `list`. pub fn inList(list: []const []const u8, s: []const u8) bool { for (list) |x| if (std.mem.eql(u8, x, s)) return true; return false;