From 795918aa47b3d4cac13714c0a6bafdbdce719dc1 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Wed, 18 Nov 2026 11:38:31 +0100 Subject: [PATCH] docs: when EasyBuild alone is enough, and which tools call eb-stack Name the EasyBuild options that cover one recipe or one list (try-*, inject-checksums, robot with dry-run or missing-modules, easystack, from-pr), then what eb-stack adds and which stackhands tool calls each verb: stack admit (eb-pipeline), stack arch (eessi-arch-guard), stack gap --site (eb-keep-logs usage), ledger (eb-staged-rebuild). --- README.md | 24 +++++++++++++++----- changelog.d/+when-easybuild-is-enough.doc.md | 1 + docs/source/conf.py | 13 +++++++---- 3 files changed, 28 insertions(+), 10 deletions(-) create mode 100644 changelog.d/+when-easybuild-is-enough.doc.md diff --git a/README.md b/README.md index ab49a7e8..a98d4191 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,18 @@ A plan is not a build. `package plan` and `package bump` can establish only **resolves**. `campaign run` owns **builds** and **binary-verified**. -The GitHub release and the crates.io package are 0.7.4 and carry every command here. +The GitHub release and the crates.io package are 0.7.4 and carry every command here except those the changelog lists as unreleased. + +## When EasyBuild alone is enough + +For one recipe, or one build list on one machine, EasyBuild has the tools: `eb --try-software-version` and `--try-update-deps` for a bump, `--inject-checksums` for its checksums, `--robot` with `--dry-run` or `--missing-modules` for what a list would build, and `--easystack` or `--from-pr` for the list itself. EESSI builds its stack that way, through easystack files and its bot. + +eb-stack is for what those leave to a site: +- recipes from conda-forge, Spack, PyPI, CRAN, Cargo, LuaRocks and Raku turned into easyconfigs, with a CycloneDX SBOM and a Resolvo lock per variant; +- a whole stack solved under a version policy against the stack it replaces (`stack solve`), and a build list split into shards with disjoint dependency closures that build in parallel (`stack shard`); +- builds admitted under a scratch inode quota (`stack admit`), which [eb-pipeline](https://github.com/stackhands/eb-pipeline) calls before each shard; +- which loaded modules exist for another CPU target (`stack arch`), which [eessi-arch-guard](https://github.com/stackhands/eessi-arch-guard) asks before a job is queued, and which used software the next stack lacks (`stack gap --site`), from [eb-keep-logs](https://github.com/stackhands/eb-keep-logs) `usage --active`; +- an append-only ledger of what was built and published (`ledger`), which [eb-staged-rebuild](https://github.com/stackhands/eb-staged-rebuild) appends to. The [glossary](docs/orgmode/reference/glossary.org) defines closure, generation, baseline, and reachability. The longer path is the [tutorial](docs/orgmode/tutorial.org). @@ -498,11 +509,12 @@ eb-stack is one of the [stackhands](https://github.com/stackhands) tools for bui | Tool | Job | Docs | |---|---|---| -| **eb-stack** | Solve, shard and plan an EasyBuild build list; admit builds under a scratch inode budget | [docs](https://eb-stack.rgoswami.me/) | -| [eb-staged-rebuild](https://github.com/stackhands/eb-staged-rebuild) | Rebuild an installation in a staged tree and swap it in, so running jobs keep their paths | [docs](https://stackhands.github.io/eb-staged-rebuild/) | -| [eessi-arch-guard](https://github.com/stackhands/eessi-arch-guard) | Reload EESSI in a Slurm task that inherited it for another CPU or GPU | [docs](https://stackhands.github.io/eessi-arch-guard/) | -| [eb-local](https://github.com/stackhands/eb-local) | Install software with EasyBuild on top of EESSI into a directory a user or project owns | [docs](https://stackhands.github.io/eb-local/) | -| [eb-keep-logs](https://github.com/stackhands/eb-keep-logs) | Keep a failed build's EasyBuild log and command output; rotate a pipeline's log tree | [docs](https://stackhands.github.io/eb-keep-logs/) | +| **eb-stack** | Turn conda-forge, Spack, PyPI, CRAN and Cargo recipes into easyconfigs; solve, shard and plan an EasyBuild build list | [docs](https://eb-stack.rgoswami.me/) | +| [eb-staged-rebuild](https://github.com/stackhands/eb-staged-rebuild) | Rebuild an installation beside the live one and swap it in, for a stack outside CernVM-FS that jobs read during the rebuild | [docs](https://stackhands.github.io/eb-staged-rebuild/) | +| [eessi-arch-guard](https://github.com/stackhands/eessi-arch-guard) | Reload EESSI in a Slurm task that inherited a stack loaded for another CPU or GPU, as srun from a login shell does | [docs](https://stackhands.github.io/eessi-arch-guard/) | +| [eb-local](https://github.com/stackhands/eb-local) | Build on EESSI-extend inside a Slurm job's node-local disk, compile your own code with RPATH, list and uninstall per CPU target | [docs](https://stackhands.github.io/eb-local/) | +| [eb-keep-logs](https://github.com/stackhands/eb-keep-logs) | Keep a failed EasyBuild command's own output, which --tmp-logdir does not; rotate a pipeline's log tree | [docs](https://stackhands.github.io/eb-keep-logs/) | +| [eb-pipeline](https://github.com/stackhands/eb-pipeline) | Drive a site's EasyBuild builds from one site file, through eb-stack, eb-staged-rebuild and eb-keep-logs | [docs](https://stackhands.github.io/eb-pipeline/) | | [rfc9162](https://github.com/stackhands/rfc9162) | Append-only Merkle logs hashed as RFC 9162, with tiled storage and signed checkpoints | [docs](https://stackhands.github.io/rfc9162/) | | [zig-common](https://github.com/stackhands/zig-common) | The shared Zig library under the Zig tools: system calls, checked files, child processes | [docs](https://stackhands.github.io/zig-common/) | diff --git a/changelog.d/+when-easybuild-is-enough.doc.md b/changelog.d/+when-easybuild-is-enough.doc.md new file mode 100644 index 00000000..2d056002 --- /dev/null +++ b/changelog.d/+when-easybuild-is-enough.doc.md @@ -0,0 +1 @@ +The README says when EasyBuild alone is enough, and which stackhands tool calls each `stack` and `ledger` verb. diff --git a/docs/source/conf.py b/docs/source/conf.py index 4040197f..478c727e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -115,22 +115,27 @@ { "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", + "summary": "Rebuild an installation beside the live one and swap it in, for a stack outside CernVM-FS that jobs read during the rebuild", }, { "title": "eessi-arch-guard", "url": "https://stackhands.github.io/eessi-arch-guard/", - "summary": "Reload EESSI in a Slurm task that inherited it for another CPU or GPU", + "summary": "Reload EESSI in a Slurm task that inherited a stack loaded for another CPU or GPU, as srun from a login shell does", }, { "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", + "summary": "Build on EESSI-extend inside a Slurm job's node-local disk, compile your own code with RPATH, list and uninstall per CPU target", }, { "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", + "summary": "Keep a failed EasyBuild command's own output, which --tmp-logdir does not; rotate a pipeline's log tree", + }, + { + "title": "eb-pipeline", + "url": "https://stackhands.github.io/eb-pipeline/", + "summary": "Drive a site's EasyBuild builds from one site file, through eb-stack, eb-staged-rebuild and eb-keep-logs", }, { "title": "rfc9162",