diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 30fa322..7140aa7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -50,3 +50,30 @@ jobs: - uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 - name: Locked all-targets build run: cargo build --locked --all-targets + + docs: + # The scripts behind the documented output; docs.yml builds the site. + name: documentation examples + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: dtolnay/rust-toolchain@39008827e6b4319a349e9a42dfc90579dd25f1ca # stable + with: + toolchain: stable + - uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + - name: Build + run: cargo build --locked + - name: Run the documentation examples + run: | + bash docs/examples/tutorial.sh + bash docs/examples/cli.sh + bash docs/examples/files.sh + bash docs/examples/templates.sh + bash docs/examples/site-file.sh + bash docs/examples/ci.sh + bash docs/examples/rotation.sh + bash docs/examples/staged.sh + bash docs/examples/select.sh diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..7926565 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,64 @@ +# Build the documentation the way `pixi run -e docs docbld` does: Org export, +# Sphinx with warnings and unresolved references as errors, the rustdoc site +# of the library, and the internal link check. External links are checked in +# their own step. On main the site is published to +# https://stackhands.github.io/eb-pipeline/. +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/.gitignore b/.gitignore index b0eb1e9..af05fe0 100644 --- a/.gitignore +++ b/.gitignore @@ -25,3 +25,16 @@ rustc-ice-*.txt # and can be added to the global gitignore or merged into this file. For a more nuclear # option (not recommended) you can uncomment the following to ignore the entire idea folder. #.idea/ + +# 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/README.md b/README.md index 124090a..4730f05 100644 --- a/README.md +++ b/README.md @@ -1,611 +1,64 @@ # eb-pipeline -A site-neutral EasyBuild pipeline driver. One per-site TOML file describes -targets, scheduler allocations, paths, admission, modules, caches, log handling -and licences. `eb-pipeline` turns that file and a build list into an ordered set -of subprocesses, so a CI system (Jenkins, GitLab CI, a cron job) becomes a thin -caller that passes a list and a target and reads an exit code and a result file. - -The driver composes existing stackhands tools and never links them in: - -| tool | called for | -|---|---| -| [eb-stack](https://github.com/stackhands/eb-stack) | `stack shard` (planning), `stack admit` (inode admission) | -| [eb-keep-logs](https://github.com/stackhands/eb-keep-logs) | `failed` (keep a failed build's logs), `rotate` | -| [eb-staged-rebuild](https://github.com/stackhands/eb-staged-rebuild) | `run`, for lines that rebuild a live install | +A site-neutral EasyBuild pipeline driver. One per-site Tom's Obvious Minimal +Language (TOML) file describes targets, scheduler allocations, paths, +admission, modules, caches, log handling and licences. `eb-pipeline` turns that +file and a build list into an ordered set of subprocesses, so a continuous +integration (CI) system (Jenkins, GitLab CI, a cron job) becomes a thin caller +that passes a list and a target and reads an exit code and a result file. + +It starts [eb-stack](https://github.com/stackhands/eb-stack) for `stack shard` +and `stack admit`, [eb-keep-logs](https://github.com/stackhands/eb-keep-logs) +for `failed` and `rotate`, and +[eb-staged-rebuild](https://github.com/stackhands/eb-staged-rebuild) for `run`, +and never links them in. Nothing about a site lives in this repository: the +templates carry placeholders only, and a test rejects any template value that +looks site-specific. + +## Documentation + +, built from the Org pages in +`docs/orgmode/`: + +- Tutorial: [Run your first build list](docs/orgmode/tutorials/first-build-list.org). +- How-to guides: [install eb-pipeline](docs/orgmode/howto/install.org), + [write a site file for your cluster](docs/orgmode/howto/write-a-site-file.org), + [build a list on every target from continuous integration](docs/orgmode/howto/build-from-ci.org), + [rotate the log tree](docs/orgmode/howto/rotate-logs.org), + [rebuild installed software through eb-staged-rebuild](docs/orgmode/howto/staged-rebuilds.org), + [build some lines of a list on some targets only](docs/orgmode/howto/select-lines.org). +- Explanation: [why one site file drives the build](docs/orgmode/explanation/design.org), + [how a run goes through its phases](docs/orgmode/explanation/phases.org), + [why the rotation takes two locks](docs/orgmode/explanation/log-rotation.org), + [what the targets of a site file share](docs/orgmode/explanation/shared-paths.org). +- Reference: [the eb-pipeline command](docs/orgmode/reference/cli.org), + [the site file](docs/orgmode/reference/site-file.org), + [the plan and result files](docs/orgmode/reference/plan-and-result.org), + [the log tree and its locks](docs/orgmode/reference/log-tree.org), + [the site file templates](docs/orgmode/reference/templates.org), + [environment variables](docs/orgmode/reference/environment.org), + [exit status](docs/orgmode/reference/exit-status.org), and the + [API](docs/orgmode/reference/api.org) of the crate, from rustdoc. + +```console +pixi run -e docs docbld +``` -Nothing about a site lives in this repository. The templates carry placeholders -only, and a test rejects any template value that looks site-specific. +The HTML is written to `docs/build/html`. +[Contributing](docs/orgmode/contributing.org) says how to write a page, run +the tests and record a change. ## Install -Needs Rust 1.90 or newer. +Rust 1.90 or newer, in a checkout: ```bash -cargo install --path . +cargo install --locked --path . --root ~/.local eb-pipeline --version ``` -At run time the driver needs `eb` (through the site's modules) and whichever of -the three tools above the site file enables. - -## Tutorial: plan and dry-run a list on a small cluster - -1. Write the site file from a template. `small-cluster` is Slurm, one CPU - target, no EESSI, no quota, no licences; `eb-pipeline init --list` names the - others. - - ```bash - eb-pipeline init --template small-cluster --out site.toml - ``` - - The paths in it are placeholders under `/opt` and `/scratch`; edit them for - your cluster, or set them from the environment (see - [Configuration](#configuration)). - -2. Check it. `check` exits 0 for a valid file and 2 otherwise. - - ```bash - eb-pipeline check --site site.toml - ``` - - ```text - INFO [check] small-lab: site file is valid - ``` - -3. Write a build list: one easyconfig per line, EasyBuild options after it. - This one builds pigz on GCCcore 15.2.0, the compiler EESSI 2026.06 - provides. - - ```bash - printf 'pigz-2.8-GCCcore-15.2.0.eb\n' > list.txt - ``` - -4. Plan it. `plan` computes everything and executes nothing; the JSON is the - same on every invocation, so it can be diffed. - - ```bash - eb-pipeline plan --site site.toml --list list.txt --target cpu \ - --build-type production --run-id demo --out plan.json - ``` - -5. Run with `--dry-run` to see the commands that `run` would start: - - ```bash - eb-pipeline run --site site.toml --list list.txt --target cpu \ - --build-type production --run-id demo --dry-run - ``` - - Drop `--dry-run` and add `--result result.json` to execute. - -## Subcommands - -| command | purpose | -|---|---| -| `init --template NAME [--out FILE]`, `init --list` | write a starter site file from a built-in template; an existing file is refused | -| `check --site FILE [--lists-dir DIR] [--probe-tools]` | parse and validate; exit 0 or 2 | -| `schema` | print every key with type, default, required flag and meaning | -| `explain --site FILE [--target T] [--build-type B] [--format toml\|json]` | resolved per-target configuration | -| `targets --site FILE [--format text\|json]` | target names in file order, one per line or as a JSON array on one line | -| `plan --site FILE --list LIST --target T --build-type B [--run-id ID] [--log-stamp S] [--shard-plan DIR] [--out FILE.json]` | phases, launch lines, environment, tool calls | -| `run` (arguments of `plan`, plus `--result FILE.json`, `--dry-run`) | execute the plan | - -`eb-pipeline schema` is generated from the same declarations the parser uses, -and a test asserts that every field of every section is documented there. - -Streams: stdout carries `plan`, `explain`, `schema`, `init`, `targets` and `--dry-run` output only. -Events go to stderr, one per line, as `LEVEL [phase] target: message`. The -result JSON goes to `--result`. - -## Configuration - -Configuration lives in two places: the site file, which describes the site, -and the environment, which describes one deployment of it. - -Every command line flag falls back to a variable; a flag given on the command -line wins. - -| flag | variable | -|---|---| -| `--site` | `EB_PIPELINE_SITE` | -| `--list` | `EB_PIPELINE_LIST` | -| `--target` | `EB_PIPELINE_TARGET` | -| `--build-type` | `EB_PIPELINE_BUILD_TYPE` | -| `--run-id` | `EB_PIPELINE_RUN_ID` | -| `--log-stamp` | `EB_PIPELINE_LOG_STAMP` | -| `--lists-dir` | `EB_PIPELINE_LISTS_DIR` | - -`EB_PIPELINE__SECTION__KEY=value` sets one site file value. The name after the -prefix is split on `__` and lowercased. `EB_PIPELINE__FILESYSTEMS__SCRATCH` -sets `filesystems.scratch`; `EB_PIPELINE__SITE__TOOLS__EB_STACK__BIN` sets -`site.tools.eb_stack.bin`. - -The value is read as a TOML value: `true`, `16`, `["/opt/a", "/opt/b"]`. Text -that does not parse as one is taken as a string. Quote a string that looks like -a number: `'"1.0"'`. - -The file plus the overrides go through the same schema as the file alone. An -unknown key or a wrong type is a usage error (exit 2). Overrides apply in name -order, and each one is logged to stderr by key, never by value. Values inside -`[[targets]]` cannot be overridden; they stay in the file. - -```bash -export EB_PIPELINE_SITE=/opt/eb/site.toml -export EB_PIPELINE__FILESYSTEMS__SCRATCH=/scratch/$USER/eb -eb-pipeline explain --target cpu -``` - -## Phases - -`preflight`, `licences`, `shard`, `sources`, `admission`, `build`, `caches`, -`logs`, in that order. An optional section that is absent, or has -`enabled = false`, is skipped and recorded as "not configured" in the plan and -the result. - -With `scheduler.kind = "slurm"`, every command starts as `launch`, -`common_args`, `--job-name=`, then the launch arguments of -its role from `[targets.phases]` or `[phase_defaults]`: `plan` for `stack -shard`, `short` for admission, prefetch and log handling, `build`, `cpu` for -CPU-role units, and `cache`. A role with no arguments launches a bare -`srun --job-name=…`. Inside an allocation srun then starts one task per -allocated task, so give each role a task count; the templates use -`-N 1 --ntasks-per-node=1` for the roles they run. - -- `shard`: `eb-stack stack shard`. The exit code `shards.planner_exit_unsharded` - (default 3) means the planner built the plan unsharded. The list then builds - as one unit. The planner runs inside the module wrapper, so what the - `[modules]` init list sets, EESSI-extend's `EASYBUILD_FILTER_DEPS` for - example, reaches it. `run` leaves out an `installed_modules_dirs` tree that - does not exist yet, such as the site tree before its first install, and logs - a WARN. -- `sources`: `eb --fetch --robot` for every list line, with the - line's options other than `--rebuild*`, then `[sources].extra_args`. A line - whose fetch fails is recorded as failed and is not built. `--fetch` ignores - installed modules, so `--robot` fetches the sources of every dependency, - those EESSI provides included. `--disable-robot` in `extra_args` fetches each - line's own sources only: the driver leaves out its `--robot`, drops a line's - `--robot`, and keeps the paths of a line's `--robot=PATH` at the front of - `--robot-paths` so the easyconfig is still found. -- `admission`: `eb-stack stack admit` before each build unit. Exit 78 retries - with the backoff in `[admission]` (`attempts`, `wait_seconds`, doubling up to - `max_wait_seconds`). The job id comes from the variable named by - `job_id_env` (default `SLURM_JOB_ID`); `run` refuses with 78 before any build - when it is unset or not a positive integer without a leading zero, and `plan` - shows `${SLURM_JOB_ID}`. A unit's footprint is the shard plan's - `inode_footprint`, else `default_footprint`, which `check` requires when - admission is enabled. `unknown_reserve` stays the reserve for live jobs that - have no record. A refusal after the last attempt ends the run with exit - 78 and a message that names the attempt count and the tool's last JSON line. - With `required = true`, a missing `quota_cmd` or `reservations` refuses with 78. - When an admitted unit's builds end, or the run ends first, `run` removes the - job's reservation `/.json` under `lock`, taken as - `lock_kind`. A record another writer has replaced since, such as a - `forecast` or `waiting` one, is kept with a WARN. A job the scheduler kills - leaves its reservation behind, so set `live_jobs_cmd` to print the running - jobs of the build account, for example `squeue -h -t R -u -o %A`. - Without it `stack admit` counts every other job's reservation, and `check` - warns. -- `build`: one `eb` call per list line, started through the scheduler launch - line of the target. A line goes through `eb-staged-rebuild run` only when - all three hold: `[rebuild] staged = true` (a target can override it with - `staged`), the line carries `--rebuild`, `-f` or `--force` as a whole option - (`--force-download` and `--rebuild-from-scratch` do not count), and the module - is installed, meaning `/all//.lua` or a file of - that name without `.lua` exists. Otherwise it is a normal `eb` call. - `software_root` and `modules_root` are per-target keys, defaulting to - `software` and `modules` under the target's `site_prefix`, or under - `filesystems.install_root` when the target sets none; they go to - `eb-staged-rebuild --software` and `--modules` and to the installed check. - Each staged line passes its own `--run-id`: `-` followed by the - easyconfig file name without `.eb`, with `.2`, `.3` appended when a list - repeats a line. eb-staged-rebuild refuses a run id it already holds, so a - staged line runs again under a new `--run-id`. eb-staged-rebuild holds - `/.lock` for the whole of a staged build and publish, and each - staged line passes `--lock-timeout` from `[rebuild] lock_timeout` (default - 600 seconds; 0 refuses at once). A line whose wait runs out is `refused`; its - note and the ERROR line name the lock that another eb-staged-rebuild holds - and, when that is the state root's, say that `lock_timeout` ran out. Without - `[rebuild] state_root`, a module that the line loads can set the state root - in `EB_STAGED_REBUILD_STATE_ROOT`, where eb-pipeline cannot see it, so for a - lock away from the state root eb-pipeline expects, the note says that - `lock_timeout` ran out if that is the state root's lock, and why eb-pipeline - cannot tell. A failed line triggers - `eb-keep-logs failed` when `[logs].keep_failed` is set. - That step runs with `EASYBUILD_OUTPUT_STYLE=basic`, whatever `[scheduler.env]` - sets, so that `eb --last-log` prints the log path on one line. -- `caches`: runs `[caches].command` once for the selected target, after a clean - build, with `EB_PIPELINE_CACHE_*` in the environment. -- `logs`: `eb-keep-logs rotate` on `filesystems.log_root`. `[logs.rotate]` needs - `compress_after_days`, passed as `--compress-after`; `delete_after_days`, - passed as `--delete-after`, must be greater. A run rotates only when no other - run under the log root is live or rotating, and leaves the rotation to - another rotate that holds eb-keep-logs' lock; either way, `logs` is then - `skipped`. [Log rotation](#log-rotation) has the locks behind this, and a - rotation from cron that takes them in the same order. - -### Per-target line selection - -A build list can mark lines for a subset of targets with a per-line option. -`[targets.select]` names the option and this target's token: - -```toml -[targets.select] -option = "--only-targets" # long option that carries the selection -value = "target-a" # this target's token -separator = "," # between tokens in the option's value -when_absent = "all" # "all" plans lines without the option, "none" skips them -strip = false # true removes the option before eb is called -``` - -`option` includes the leading dashes, and a line carries it as `--name=a,b` or -`--name a,b`. A line is planned for the target when the option is absent and -`when_absent = "all"`, or when its value list contains `value`. `plan` and `run` -both apply it, to the whole list or to each shard unit; a unit left without -lines is dropped. With a selector, `run` writes the kept lines, in list order -and with `strip` applied, to `/selected-.list` and passes that -file to `stack shard --build-list`, so deselected lines do not weigh in shard -balancing. `plan` shows the same path in the shard command, under -`selected_list`, and records the kept count under `selected`. A shard plan given -to `plan --shard-plan` must come from that file. `plan` lists the dropped lines -under `deselected`, and the result file does the same, apart from `lines` and -`counts`, so a deselected line never reads as a failure. Without -`[targets.select]` every line is planned. - -### Route contract - -`[targets.route]` wraps the commands of CPU-role units (the CPU prerequisites -that `stack shard` lifts out) in a command. Beyond `kind` and `command`: - -| key | meaning | -|---|---| -| `args` | argument templates after `command`; a `--` follows them and the phase command comes after it | -| `env` | environment of the routed command | -| `runtime_root` | exported as `EB_PIPELINE_ROUTE_RUNTIME_ROOT` | -| `shares_ro`, `shares_rw` | shared paths, exported joined with `:` as `EB_PIPELINE_ROUTE_SHARES_RO` and `_RW` | -| `receipt_digest_env` | name of a variable that holds a digest; `run` refuses with 78 when it is unset or empty and exports the value as `EB_PIPELINE_ROUTE_RECEIPT_DIGEST`; `plan` shows `${NAME}` | -| `phases` | `build` (default) and `sources`: the phases whose CPU-role commands are routed | - -Placeholders in `args` and `env`: `{phase_dir}` (`/`, created -before the command starts), `{log_dir}`, `{work_dir}` (the target's -`filesystems.build_path`), `{target}`, `{phase}`, `{runtime_root}`, -`{shares_ro}`, `{shares_rw}`. Share -entries accept the first three. A route with only `kind` and `command` plans -exactly the 0.1.0 argv. - -### Hardware classes, fetch profile, package environment - -- `[targets.cpu_hardware]` has the shape of `[targets.hardware]` and names the - hardware class of CPU-role units. When it is set, every command exports its - class as `EB_PIPELINE_HW_VENDOR_ID`, `EB_PIPELINE_HW_CPU_FAMILY` and - `EB_PIPELINE_HW_MODEL`: `cpu_hardware` for CPU-role commands, `hardware` for - the rest. Without it nothing is exported. -- `[targets.fetch_profile]` is a free-form table passed to source prefetch - commands as `EB_PIPELINE_FETCH_PROFILE`, serialised as JSON with sorted keys. -- `[targets.package_env.]` adds to `[modules.package_env.]` for that - target; per key the target value wins. - -### Per-target paths - -`{target}` in `[filesystems] build_path`, in the entries of -`[filesystems] source_paths` and in `[rebuild] state_root` expands to the -target's name. `build_path = "/scratch//build/{target}"` gives each -target an `EASYBUILD_BUILDPATH` of its own, which `{work_dir}` follows. -EasyBuild looks for a source in every `source_paths` entry and downloads a -missing one into the first, writing the file in place, so -`source_paths = ["/scratch//sources/{target}", "/opt/eb/sources"]` -gives each target a download directory of its own and still finds the sources -under `/opt/eb/sources`. `state_root = "/opt/eb/{target}/.eb-staged-rebuild"` -gives each target an eb-staged-rebuild state root, and so a lock, of its own. -`plan` and `explain` show the expanded paths. `check` refuses any other -placeholder in those keys, `{target}` in the other `[filesystems]` paths, the -target names `.` and `..`, and a `{target}` state root when two staged targets -share a software root: eb-staged-rebuild locks a live tree through its state -root, so one tree takes one state root. - -### Install paths, cache module, installed module dirs - -- `filesystems.export_install_vars = "split"` exports - `EASYBUILD_INSTALLPATH_SOFTWARE` and `EASYBUILD_INSTALLPATH_MODULES` from the - target's `software_root` and `modules_root` instead of `EASYBUILD_INSTALLPATH`. - `read_only_installdir_value` sets the value of `EASYBUILD_READ_ONLY_INSTALLDIR` - (default `"1"`). -- With `[modules.eessi] site_install = true` and a single install path, - EESSI-extend replaces `EASYBUILD_INSTALLPATH` when it loads: - `$EESSI_SITE_SOFTWARE_PREFIX/versions//software/linux/`, - plus `/` for an NVIDIA target when `EESSI_ACCELERATOR_INSTALL` - is set. `explain` names that path in each target's `install_note`. A target - that takes staged rebuilds must then set `software_root` and `modules_root` - to the `software` and `modules` directories under it; `check` refuses the - site file otherwise. -- A `--rebuild`, `-f` or `--force` line on a staged target whose module file - is missing under `modules_root` builds with plain `eb`. `plan` notes it on - the build command and `run` logs a WARN. -- `[caches] init_module` is the default `EB_PIPELINE_CACHE_INIT_MODULE`; an entry - in `[[caches.targets]]` overrides it. -- `shards.installed_modules_dirs_from_env` names variables whose colon-separated - values are appended to `installed_modules_dirs` when `run` starts. An unset - variable refuses with 78, an empty one adds nothing, and `plan` shows - `${NAME}`. - -Every child writes to `///`. The timestamp -is the UTC time, taken once per run. `--log-stamp` overrides it with a stamp of -the same form, a real UTC date and time; anything else is refused with exit 2. -The `logs` phase runs `eb-keep-logs rotate` with `TZ=UTC`, so a run's age -counts from the UTC midnight of its stamp. `--run-id` is a separate label -recorded in the result. The result JSON records the log path of each line. - -`plan --shard-plan DIR` reads the `plan.json` that `stack shard` wrote in `DIR` -and expands the per-shard admission and build commands. - -`run` builds the units one at a time, each after its own admission: the CPU -prerequisites, then the prelude, then each shard in turn. It has no option to -build one shard alone. The prelude holds the modules that two or more shards -need. A shard list holds lines of the input list only, so a line whose other -dependencies are not installed needs `--robot` to build them. - -Limitation: the licence gate checks configuration only. It confirms that every -required package has a group, a threshold or an exemption; it does not verify -file permissions or group membership on the host. - -### Staged rebuild ledger - -`[rebuild] ledger_config` is the file passed to `eb-staged-rebuild run ---ledger-config`. It names one `target`, which eb-staged-rebuild copies into -every ledger record, so each target that takes staged rebuilds needs a file of -its own: a target's `ledger_config` overrides the one in `[rebuild]`, and -`check` refuses two such targets that resolve to the same file. `explain` shows -the file of each target. - -### Log rotation - -Two `flock` locks in `filesystems.log_root` keep the rotations of the log tree -apart from each other and from the runs that write into it. They hold between -nodes only where the log root's filesystem carries `flock` between them. - -- `.eb-pipeline-rotate.lock` is eb-pipeline's. With `[logs.rotate]`, a run - holds it shared from its start and rotates only when it can take it alone. - While another run under the log root is live or rotating, `logs` is - `skipped` and the rotation is left to a run that ends alone; a run that - starts while another rotates waits for it. -- `.eb-keep-logs-rotate.lock` is eb-keep-logs'. An eb-keep-logs whose `--help` - lists `--lock-timeout` takes this lock alone in `rotate`, from before it lists - the log root until it exits, and waits for it up to `--lock-timeout` seconds, - 600 unless given; 0 does not wait. When the wait runs out, it exits 75 and - has changed nothing. eb-keep-logs never takes eb-pipeline's lock. - -eb-keep-logs' lock keeps two rotates apart, but not a rotate and a run that is -still writing logs on another host, which is what eb-pipeline's lock is for. -eb-keep-logs 0.2.1 takes no lock of its own, and passes over at most the run -that it writes into itself: two rotations at once lose each other's updates to -a run's `.licensed-logs`, and a rotation compresses the logs of a run that is -still writing them once that run's log stamp is a day old in UTC, as it is for -a target that started before midnight. - -Whatever takes both locks takes eb-pipeline's first and eb-keep-logs' second. -A run's rotation does, and so does the cron wrapper below; eb-keep-logs takes -only its own. So nothing waits for eb-pipeline's lock while it holds -eb-keep-logs', and two rotations cannot deadlock. - -`run` passes `--lock-timeout 0`, so that its rotation does not wait for another -rotate: while it rotates, the run holds `.eb-pipeline-rotate.lock` alone, and -every run under the log root that starts meanwhile waits for it. A `rotate` -that exits 75 leaves `logs` `skipped`, with a note that names -`.eb-keep-logs-rotate.lock`, and the rotation to the rotate that holds it. That -rotate lists the log root after taking the lock, so it does this rotation's -work, and a later run that ends alone does what is left. Any other non-zero -exit of `rotate` is `failed`. - -eb-keep-logs 0.2.1 refuses `--lock-timeout` with exit 2, and the builds that -take it print the same version, so `run` passes the option only when -`eb-keep-logs --help` lists it. `run` reads the help where it checks -`min_version`, with the rotation's environment, and only when it rotates. -Without the option, the rotation runs as it does with 0.2.1, and the `logs` -note and an INFO line say why. - -A rotation outside a run, such as one from cron, takes eb-pipeline's lock the -same way with `flock(1)`: - -```bash -TZ=UTC flock -w 3600 -E 75 /opt/eb/logs/.eb-pipeline-rotate.lock \ - eb-keep-logs rotate /opt/eb/logs --compress-after 30 --delete-after 365 -``` - -`flock` waits up to an hour for the live runs under the log root, and a -rotation that holds the lock, to end, then holds the lock alone while `rotate` -runs. When that wait runs out, it exits 75 without starting `rotate`; `rotate` -exits 75 too when another rotate holds its own lock past `--lock-timeout`. -Either way, 75 means that the tree was busy and nothing changed. While the -wrapper holds the lock, a run that starts waits for it. A run can still start -while the wrapper waits, so on a log root that always has a live run the -wrapper gives up after the hour, and the last run to end can take the lock and -rotate before the wrapper does. The wrapper keeps a rotation by eb-keep-logs -0.2.1 apart from runs and their rotations too. `TZ=UTC`, as `run` sets it, counts a run's age from the UTC -midnight of its stamp. - -## Exit codes - -| code | meaning | -|---|---| -| 0 | all requested work completed | -| 1 | work attempted and failed (a build line or a phase); see the result file | -| 2 | usage error, invalid site file, or a tool below its `min_version` | -| 75 | a resource is temporarily unavailable or a step is pending; rerun | -| 78 | refused by a precondition, by admission or by eb-staged-rebuild; lines built before the refusal stay built, see the result file | -| 130 | interrupted by SIGINT, after the running child ended | -| 143 | interrupted by SIGTERM, after the running child ended | - -The process exit code is never a sum of failures; the result file holds the -per-line counts. A signal (130, 143) or a usage error (2) ends the run with -that code. Otherwise, when several conditions apply, the order is 1, 78, 75, 0. - -Sibling tool codes are mapped explicitly: - -| tool | code | driver reading | -|---|---|---| -| eb-stack `stack admit` | 0 / 78 / 1 / 2 | admitted / refused (retry) / failed / usage, exit 2 | -| eb-stack `stack shard` | `shards.planner_exit_unsharded` (default 3) | unsharded, continue | -| eb-staged-rebuild `run` | 2 | refusal there, such as a lock still held when `--lock-timeout` runs out; the line is recorded as `refused` with `translated_from = 2` and the run ends with 78 | -| eb-staged-rebuild `run` | 75 | pending; the line is recorded as `pending`, exit 75 | -| eb-staged-rebuild `run` | other non-zero | failed | -| eb-keep-logs `rotate` | 75 | another rotate holds `/.eb-keep-logs-rotate.lock`, and this one changed nothing; `logs` is recorded as `skipped` and the run's code is unchanged | -| eb-keep-logs `rotate` | other non-zero | `logs` failed, exit 1 | - -SIGTERM and SIGINT are forwarded to the running child. The driver starts no -further child, writes the result file, and exits 143 or 130. - -## Result file - -`phases` holds the phases the run recorded, in pipeline order from `preflight` -to `logs`. A line that ran through eb-staged-rebuild carries a `note` naming -it, whatever its status. - -```json -{ - "kind": "result", - "exit_code": 1, - "sharded": false, - "counts": {"failed": 1, "success": 2}, - "not_configured": ["admission", "shard"], - "admission": [], - "lines": [{"easyconfig": "Foo-1.0-foss-2025a.eb", "status": "failed", "exit_code": 1, "log": "..."}], - "phases": [] -} -``` - -`run` writes the result file unless `--dry-run` is set or an input error stops -it first, such as an invalid site file, an unknown target, an unreadable, empty -or malformed list, or a tool below its `min_version`. Input errors exit 2, or 78 -when the licence gate alone fails, and leave an existing file at the `--result` -path as it was, so read the exit code before the file. - -Line statuses: `success`, `failed`, `refused`, `pending`, `skipped`. Lines that -a target's `[targets.select]` left out appear under `deselected` (`easyconfig` -and `unit`) and in no status count. - -Phase statuses: `ok`, `failed`, `refused`, `skipped`, `not configured`, -`interrupted`, and `unsharded` for `shard`. The `build` phase is `skipped`, -with a note, when admission refused before any line started, and `refused` -when every line that ran was refused. - -## A thin CI caller - -```bash -export EB_PIPELINE_SITE=site.toml EB_PIPELINE_LIST="$LIST" EB_PIPELINE_TARGET="$TARGET" -export EB_PIPELINE_BUILD_TYPE="$BUILD_TYPE" EB_PIPELINE_RUN_ID="$CI_RUN_ID" -eb-pipeline run --result "result-$TARGET.json" -rc=$? -``` - -The caller names no partition, path, licence group or quota command. It maps -`rc` to its own status and archives the result file and the log directory. - -## One job per target - -A run builds one target. To build a list on every target, the caller starts -one `run` per name that `targets` prints, in file order, each after the -previous one has finished: - -```bash -export EB_PIPELINE_SITE=site.toml EB_PIPELINE_LIST="$LIST" EB_PIPELINE_BUILD_TYPE="$BUILD_TYPE" -names=$(eb-pipeline targets) || exit -for t in $names; do - EB_PIPELINE_TARGET=$t EB_PIPELINE_RUN_ID="$CI_RUN_ID-$t" \ - eb-pipeline run --result "result-$t.json" || echo "$t: exit $?" >&2 -done -``` - -An invalid site file exits 2 with nothing on stdout, so no run starts. Each -target needs a run id of its own. `stack shard` writes its plan into -`/`, which has no target in it, and eb-staged-rebuild -refuses a run id it already holds, so targets that share -`[rebuild] state_root` would pass it the same `-`. -The default run id, the log stamp, is the same for two runs that start in the -same second. Logs go to `///`, so targets never -share a log directory. - -Without `{target}` in `[filesystems] build_path`, the targets of a site file -share their EasyBuild build path, so run them one at a time. Every target then -gets one `EASYBUILD_BUILDPATH`, and EasyBuild builds an easyconfig in -`///-`, -with no target in the path. A build removes that directory when it starts and -again after it installs, so two targets that build one easyconfig at once -remove each other's build directory, and the build that loses it fails. -EasyBuild downloads a missing source into the first `source_paths` entry and -writes the file in place, so a target that looks for a source that another -target is still downloading there finds the partial file and fails its -checksum. Staged lines of targets that share `[rebuild] state_root` take one -lock, and eb-staged-rebuild holds it for the whole of a staged build. A second -staged build waits up to `[rebuild] lock_timeout` for it, 600 seconds unless -set, and is `refused` when the first still holds it then, so the run ends with -78 instead of waiting with no deadline. eb-staged-rebuild has not measured that -lock between two build nodes. `EASYBUILD_TMPDIR` is safe to share: each `eb` -makes its own `eb-*` directory under it. So is `log_root`: each run writes -under its own `/`, and with `[logs.rotate]` a run rotates -only when no other run under the log root is live ([Log -rotation](#log-rotation)). - -`targets --format json` prints the names as a JSON array on one line, the form -a CI matrix reads. [examples/ci/github-actions.yml](examples/ci/github-actions.yml) -is a GitHub Actions workflow with one job that prints the array and one build -job per target. It sets `max-parallel: 1`, the safe default, and a target that -fails leaves the others running. Raise `max-parallel` only when no two targets -that build at once share a build directory, a download directory or, with -staged rebuilds, a state root: - -- `{target}` in `build_path` gives each target a build path of its own. A - `build_path` without it is one path for every target, so it needs storage - that no two targets' build nodes share. -- `{target}` in the first `source_paths` entry gives each target a download - directory of its own. -- `{target}` in `state_root` gives each target a state root, and so a lock, of - its own, and so does leaving `state_root` unset: eb-staged-rebuild then keeps - its state in `/.eb-staged-rebuild`, next to each target's - software tree. The staged lines of targets that share a state root take - turns, and one that waits longer than `lock_timeout` is refused. - -[Per-target paths](#per-target-paths) has examples of all three. -`eessi-site.toml` has `{target}` in `build_path` and `state_root`; give its -targets a first source path each before raising `max-parallel`. - -`max-parallel` holds within one run of the workflow, and each dispatch is a -run of its own. The build job's `concurrency` group, `eb-pipeline-`, -lets one dispatch at a time build a target: another dispatch's job for that -target waits until the running one has finished, and -`cancel-in-progress: false` leaves the running build alone. GitHub keeps only -one pending job per group, so a third dispatch replaces the waiting one, which -is cancelled. The group belongs to the repository and has no workflow name in -it, so another workflow in the repository that uses the same group waits as -well. It keeps two dispatches off one target, not off one path: one dispatch -can build a target while another builds a different one. Targets that share a -build directory, a download directory or a state root therefore need one group -for the whole build job, `eb-pipeline` with no target in it, so that one build -job in the repository runs at a time. - -Dependabot updates the action pins in `examples/ci/` along with those in -`.github/workflows/`. - -## Development - -```bash -cargo fmt --all --check -cargo clippy --locked --all-targets -- -D warnings -cargo test --locked -``` - -Set `EB_PIPELINE_LINT_DENY` to a comma-separated list of your own site's names -or paths before `cargo test --test examples` to refuse them in the templates as -well; the repository names none. - -`run` is tested against stub tool binaries written into a temporary directory. -The scenarios: success, a failed line, admission refused after N attempts, -admission admitted on the second attempt, staged-rebuild refusal translation, -and SIGTERM forwarding. - -A change adds a news fragment, `changelog.d/+..md`, with type -`feature`, `bugfix`, `doc`, `removal` or `misc`. -`towncrier build --draft --version X.Y.Z` prints the release notes the -fragments make. A release writes them into `CHANGELOG.md`, as -[RELEASING.md](RELEASING.md) describes. +[Install eb-pipeline](docs/orgmode/howto/install.org) has the release binaries +and what to do when the build fails. ## Licence diff --git a/changelog.d/+api-docs.doc.md b/changelog.d/+api-docs.doc.md new file mode 100644 index 0000000..bb1719d --- /dev/null +++ b/changelog.d/+api-docs.doc.md @@ -0,0 +1 @@ +Every public item of the `eb_pipeline` library has a doc comment, and `pixi run -e docs docbld` fails on one without. The field of a site file key in `eb_pipeline::schema` carries the text `eb-pipeline schema` prints for that key. diff --git a/changelog.d/+ci-howto.doc.md b/changelog.d/+ci-howto.doc.md new file mode 100644 index 0000000..0436481 --- /dev/null +++ b/changelog.d/+ci-howto.doc.md @@ -0,0 +1 @@ +A how-to guide builds a list on every target from continuous integration (CI): the GitHub Actions workflow of `examples/ci/`, with why each target gets its own run id, when to raise `max-parallel` and what the `concurrency` group holds, and a caller script for other CI systems that exits as a run does. diff --git a/changelog.d/+cli-reference.doc.md b/changelog.d/+cli-reference.doc.md new file mode 100644 index 0000000..0027224 --- /dev/null +++ b/changelog.d/+cli-reference.doc.md @@ -0,0 +1 @@ +The reference has a page for the `eb-pipeline` command, with the usage line, options, variables and exit statuses of every subcommand, and a page for the environment variables it reads, the `EB_PIPELINE__SECTION__KEY` site file values and the variables a run sets for the commands it starts. `docs/examples/cli.sh` prints the help texts the page shows. diff --git a/changelog.d/+design-explanation.doc.md b/changelog.d/+design-explanation.doc.md new file mode 100644 index 0000000..1298cd2 --- /dev/null +++ b/changelog.d/+design-explanation.doc.md @@ -0,0 +1 @@ +Explanation pages say why one site file drives the build and the caller stays thin, and how a run goes through its phases and units, what stops it, and how one exit status sums up its lines, with a figure of the phases; the tutorial links them. diff --git a/changelog.d/+docs-site.doc.md b/changelog.d/+docs-site.doc.md new file mode 100644 index 0000000..46100bc --- /dev/null +++ b/changelog.d/+docs-site.doc.md @@ -0,0 +1 @@ +The documentation is a site built from Org pages in `docs/orgmode/`, published at , with the API of the `eb_pipeline` library from `cargo doc` beside it at `api/`. `pixi run -e docs docbld` builds it with the tools `pixi.lock` pins, and fails on a Sphinx or rustdoc warning, an internal link or anchor that does not exist, or the name of a real site. The `docs` workflow builds it for every pull request, checks its external links, also weekly, and publishes it from `main`. diff --git a/changelog.d/+exit-status-reference.doc.md b/changelog.d/+exit-status-reference.doc.md new file mode 100644 index 0000000..cfde6b7 --- /dev/null +++ b/changelog.d/+exit-status-reference.doc.md @@ -0,0 +1 @@ +The reference has a page on exit statuses: what leads to each of 0, 1, 2, 75, 78, 130 and 143, the order in which `run` picks one when several apply, and what a run does with each exit status of `eb`, eb-stack, eb-staged-rebuild, eb-keep-logs and the cache command. diff --git a/changelog.d/+install-howto.doc.md b/changelog.d/+install-howto.doc.md new file mode 100644 index 0000000..35f910c --- /dev/null +++ b/changelog.d/+install-howto.doc.md @@ -0,0 +1 @@ +A how-to guide installs eb-pipeline from the 0.3.0 release, checked against its checksum, or from source with `cargo install --locked`, and says what the release lacks of the code the documentation describes. diff --git a/changelog.d/+log-tree-reference.doc.md b/changelog.d/+log-tree-reference.doc.md new file mode 100644 index 0000000..cd217ab --- /dev/null +++ b/changelog.d/+log-tree-reference.doc.md @@ -0,0 +1 @@ +The reference has a page on the log tree: the files a run writes in its log directory, the files of the log root, and the locks a run takes, with the order in which it takes the two rotation locks. diff --git a/changelog.d/+plan-and-result-reference.doc.md b/changelog.d/+plan-and-result-reference.doc.md new file mode 100644 index 0000000..313ede0 --- /dev/null +++ b/changelog.d/+plan-and-result-reference.doc.md @@ -0,0 +1 @@ +The reference has a page on the plan and result files, with every key of each object, the statuses of a line and of a phase, and a plan and a result from `docs/examples/files.sh`. diff --git a/changelog.d/+reference-commands.doc.md b/changelog.d/+reference-commands.doc.md new file mode 100644 index 0000000..b36e383 --- /dev/null +++ b/changelog.d/+reference-commands.doc.md @@ -0,0 +1 @@ +The commands on the reference pages are in blocks of their own, without a prompt, so that copying a block gives commands that run. diff --git a/changelog.d/+rotate-howto.doc.md b/changelog.d/+rotate-howto.doc.md new file mode 100644 index 0000000..a2964cb --- /dev/null +++ b/changelog.d/+rotate-howto.doc.md @@ -0,0 +1 @@ +A how-to guide rotates the log tree, at the end of each run and from cron under the same lock with `flock`, with the messages of a run that leaves the rotation to another and of a rotation that fails. diff --git a/changelog.d/+rotation-explanation.doc.md b/changelog.d/+rotation-explanation.doc.md new file mode 100644 index 0000000..08b52e4 --- /dev/null +++ b/changelog.d/+rotation-explanation.doc.md @@ -0,0 +1 @@ +An explanation page says why a rotation of the log tree takes eb-pipeline's lock and eb-keep-logs' lock, always in that order, why a run does not wait for another rotate, and what the locks do not cover, with a figure of who takes which lock. diff --git a/changelog.d/+select-howto.doc.md b/changelog.d/+select-howto.doc.md new file mode 100644 index 0000000..ad159c3 --- /dev/null +++ b/changelog.d/+select-howto.doc.md @@ -0,0 +1 @@ +A how-to guide builds some lines of a list on some targets only, with a `[targets.select]` table in each target, and shows what each target plans and runs of the list, `selected-TARGET.list` and the `deselected` lines of the plan and the result. diff --git a/changelog.d/+shared-paths-explanation.doc.md b/changelog.d/+shared-paths-explanation.doc.md new file mode 100644 index 0000000..5b240b4 --- /dev/null +++ b/changelog.d/+shared-paths-explanation.doc.md @@ -0,0 +1 @@ +An explanation page says what the targets of a site file share, what goes wrong when two of them build into one build directory, download directory or state root at once, and when `{target}` in those paths lets them build at the same time. diff --git a/changelog.d/+short-readme.doc.md b/changelog.d/+short-readme.doc.md new file mode 100644 index 0000000..2be2c99 --- /dev/null +++ b/changelog.d/+short-readme.doc.md @@ -0,0 +1 @@ +The README is short and links the pages of the documentation, which now hold its sections, log rotation included. The tests that read the README read those pages instead, and one fails when the `--help` text on the command reference differs from what `eb-pipeline --help` prints. diff --git a/changelog.d/+site-file-howto.doc.md b/changelog.d/+site-file-howto.doc.md new file mode 100644 index 0000000..bc1720e --- /dev/null +++ b/changelog.d/+site-file-howto.doc.md @@ -0,0 +1 @@ +A how-to guide writes a site file for a cluster from the small-cluster template, checks it with `check`, `--lists-dir` and `--probe-tools`, reads it back with `explain` and a dry run, and lists the messages of the common mistakes. diff --git a/changelog.d/+site-file-reference.doc.md b/changelog.d/+site-file-reference.doc.md new file mode 100644 index 0000000..f540e0c --- /dev/null +++ b/changelog.d/+site-file-reference.doc.md @@ -0,0 +1 @@ +The reference has a page on the site file, with a table per section that gives every key its type, default and meaning, and sections on the placeholders, `{target}` in paths, the `[logs]` rotation and the lines that go through `[rebuild]`. `tests/docs.rs` fails when a table and `eb_pipeline::schema::SECTIONS` differ in a key, its order, its type or its default. diff --git a/changelog.d/+staged-howto.doc.md b/changelog.d/+staged-howto.doc.md new file mode 100644 index 0000000..c46c15d --- /dev/null +++ b/changelog.d/+staged-howto.doc.md @@ -0,0 +1 @@ +A how-to guide rebuilds installed software through eb-staged-rebuild: the `[rebuild]` table with a state root per target, the line and module that make a line staged, the run id each staged line passes, and the messages of a refused or pending line and of the site files `check` refuses. diff --git a/changelog.d/+templates-reference.doc.md b/changelog.d/+templates-reference.doc.md new file mode 100644 index 0000000..d2bd28b --- /dev/null +++ b/changelog.d/+templates-reference.doc.md @@ -0,0 +1 @@ +The reference has a page on the site file templates that `eb-pipeline init` writes, with each template in full and what `check` and `targets` say about it. diff --git a/changelog.d/+tutorial-cargo-version.doc.md b/changelog.d/+tutorial-cargo-version.doc.md new file mode 100644 index 0000000..bc6c97c --- /dev/null +++ b/changelog.d/+tutorial-cargo-version.doc.md @@ -0,0 +1 @@ +`docs/examples/tutorial.sh` also runs the `cargo --version` that the tutorial starts with; `RUSTUP_TOOLCHAIN=1.90.0` prints the version the page shows. diff --git a/changelog.d/+tutorial.doc.md b/changelog.d/+tutorial.doc.md new file mode 100644 index 0000000..91de46c --- /dev/null +++ b/changelog.d/+tutorial.doc.md @@ -0,0 +1 @@ +The tutorial, "Run your first build list", installs eb-pipeline from source, writes a site file with the `local` scheduler, runs a build list against a stand-in for `eb`, reads the result file and a line's log, and makes a line fail. `docs/examples/tutorial.sh` runs its commands in order and checks what the page says they print, and the `docs` job of the `ci` workflow runs it. diff --git a/docs/examples/ci.sh b/docs/examples/ci.sh new file mode 100755 index 0000000..34dc919 --- /dev/null +++ b/docs/examples/ci.sh @@ -0,0 +1,54 @@ +#!/bin/bash +# What docs/orgmode/howto/build-from-ci.org shows: the targets of +# build-from-ci/site.toml and the paths each one gets, then +# build-from-ci/build-all.sh run on a copy of that site file with the local +# scheduler, no modules and its paths under $WORK, with the stand-in eb of +# the tutorial, which fails the lines whose easyconfig starts with Broken-. +# shellcheck disable=SC2016 # commands stay quoted as the pages show them +# shellcheck source-path=SCRIPTDIR source=lib.sh +. "$(dirname -- "$0")/lib.sh" + +export WORK=$HOME/ci +mkdir -p "$WORK" +cd "$WORK" +cp "$pages/howto/build-from-ci/site.toml" site.toml + +run 'eb-pipeline targets --site site.toml +eb-pipeline targets --site site.toml --format json' +expect_status 0 +expect_line '["zen2","zen4"]' + +run 'for t in $(eb-pipeline targets --site site.toml); do + eb-pipeline explain --site site.toml --target "$t" | grep -E "BUILDPATH|SOURCEPATH" +done' +expect_status 0 +expect_line 'EASYBUILD_BUILDPATH = "/scratch/alice/build/zen2"' +expect_line 'EASYBUILD_SOURCEPATH = "/scratch/alice/sources/zen4:/opt/site/sources"' + +sed 's/^kind = "slurm"/kind = "local"/' site.toml >broken.toml +sed -i 's/^name = "zen4"/name = "zen2"/' broken.toml +run 'eb-pipeline targets --site broken.toml' +expect_status 2 + +mkdir local +sed -e 's/^kind = "slurm"/kind = "local"/' \ + -e "s#/opt/site#$WORK/site#g" \ + -e "s#/scratch/alice#$WORK/scratch#g" \ + -e 's/^init = \["EasyBuild"\]/init = []/' site.toml >local/site.toml +cp "$pages/howto/build-from-ci/build-all.sh" local/build-all.sh +cd local +# shellcheck source=../orgmode/tutorials/first-build-list/eb.sh +. "$pages/tutorials/first-build-list/eb.sh" +export PATH=$WORK/local/bin:$PATH +printf '%s\n' Example-1.0-GCCcore-15.2.0.eb Broken-1.0-GCCcore-15.2.0.eb >build.list + +run 'bash build-all.sh build.list production 1234; echo "exit $?"' +expect_line 'zen2: exit 1' +expect_line 'exit 1' + +run "grep -H '^ \"exit_code\"' result-*.json" +expect_line 'result-zen4.json: "exit_code": 1,' + +run 'bash build-all.sh missing.list production 1235; echo "exit $?"' +expect_line 'ERROR [main] -: cannot read list missing.list: No such file or directory (os error 2)' +expect_line 'exit 2' diff --git a/docs/examples/cli.sh b/docs/examples/cli.sh new file mode 100755 index 0000000..432512d --- /dev/null +++ b/docs/examples/cli.sh @@ -0,0 +1,28 @@ +#!/bin/bash +# The help texts that docs/orgmode/reference/cli.org shows, and the usage +# line of every command, which its synopsis copies. +# shellcheck source-path=SCRIPTDIR source=lib.sh +. "$(dirname -- "$0")/lib.sh" + +run 'eb-pipeline --help' +expect_status 0 +expect_line 'Usage: eb-pipeline ' + +run 'eb-pipeline --version' +expect_status 0 +expect_line "eb-pipeline $(crate_version)" + +synopsis=( + 'check [OPTIONS] --site ' + 'schema' + 'init [OPTIONS]' + 'explain [OPTIONS] --site ' + 'targets [OPTIONS] --site ' + 'plan [OPTIONS] --site --list --target --build-type ' + 'run [OPTIONS] --site --list --target --build-type ' +) +for usage in "${synopsis[@]}"; do + run "eb-pipeline ${usage%% *} --help" + expect_status 0 + expect_line "Usage: eb-pipeline $usage" +done diff --git a/docs/examples/files.sh b/docs/examples/files.sh new file mode 100755 index 0000000..4d519ef --- /dev/null +++ b/docs/examples/files.sh @@ -0,0 +1,80 @@ +#!/bin/bash +# The plan, the result file and the log tree that +# docs/orgmode/reference/plan-and-result.org and log-tree.org show: a site +# with the local scheduler, kept logs and rotation, run with stand-ins for +# eb and eb-keep-logs that print their arguments. +# shellcheck disable=SC2016 # commands stay quoted as the pages show them +# shellcheck source-path=SCRIPTDIR source=lib.sh +. "$(dirname -- "$0")/lib.sh" + +export WORK=$HOME/files +mkdir -p "$WORK/bin" +cd "$WORK" +cat >bin/eb <<'EOF' +#!/bin/sh +echo "eb $*" +case "$1" in Broken-*) exit 1 ;; esac +EOF +cat >bin/eb-keep-logs <<'EOF' +#!/bin/sh +if [ "$1" = --help ]; then + echo "usage: eb-keep-logs rotate LOG_ROOT --compress-after DAYS [--delete-after DAYS] [--lock-timeout SECONDS]" + exit 0 +fi +echo "eb-keep-logs $*" +EOF +chmod +x bin/eb bin/eb-keep-logs +export PATH=$WORK/bin:$PATH +cat >site.toml <build.list + +args='--site site.toml --list build.list --target cpu --build-type production --run-id nightly --log-stamp 20261117_090000' + +run "eb-pipeline plan $args --out plan.json" +expect_status 0 + +run 'cat plan.json' +expect_line ' "kind": "plan",' + +run "eb-pipeline run $args --result result.json" +expect_status 1 +expect_line 'ERROR [build] cpu: Broken-1.0-GCCcore-15.2.0: failed (exit 1)' + +run 'cat result.json' +expect_line ' "exit_code": 1,' + +run 'find logs | sort' +expect_line 'logs/.eb-pipeline-rotate.lock' +expect_line 'logs/20261117_090000/cpu/Broken-1.0-GCCcore-15.2.0.keep-logs.log' + +run 'cat logs/20261117_090000/cpu/Broken-1.0-GCCcore-15.2.0.keep-logs.log logs/20261117_090000/cpu/rotate.log' +expect_line 'eb-keep-logs rotate $WORK/logs --compress-after 30 --delete-after 365 --lock-timeout 0' diff --git a/docs/examples/install.sh b/docs/examples/install.sh new file mode 100755 index 0000000..fe2b52e --- /dev/null +++ b/docs/examples/install.sh @@ -0,0 +1,78 @@ +#!/bin/bash +# The installs that docs/orgmode/howto/install.org shows: release 0.3.0 from +# GitHub, checked against its checksum, and a build from a clone of this +# checkout with cargo install, then the failures its table lists. +# +# It needs the network and a Rust toolchain of 1.90 or newer, so the docs +# job of the CI workflow does not run it. Pick the toolchain with +# RUSTUP_TOOLCHAIN, as in RUSTUP_TOOLCHAIN=1.90.0 bash docs/examples/install.sh; +# OLD_TOOLCHAIN names one older than 1.90 for the failure, 1.83.0 unless set. +# shellcheck disable=SC2016 # commands stay quoted as the pages show them + +# lib.sh moves HOME and PATH; keep the toolchain of the user who runs this. +cargo=$(command -v cargo) +export RUSTUP_HOME=${RUSTUP_HOME:-$HOME/.rustup} +export CARGO_HOME=${CARGO_HOME:-$HOME/.cargo} +old_toolchain=${OLD_TOOLCHAIN:-1.83.0} +# shellcheck source-path=SCRIPTDIR source=lib.sh +. "$(dirname -- "$0")/lib.sh" + +export WORK=$HOME/install +mkdir -p "$WORK" "$HOME/.local/bin" +cd "$WORK" +# The pages run the eb-pipeline they install, not the one lib.sh links. +rm "$HOME/.cargo/bin/eb-pipeline" +PATH=$HOME/.local/bin:$PATH:$(dirname -- "$cargo") +export PATH + +release=https://github.com/stackhands/eb-pipeline/releases/download/v0.3.0 +archive=eb-pipeline-x86_64-unknown-linux-musl.tar.xz + +run "curl -fsSLO $release/$archive +curl -fsSLO $release/$archive.sha256 +sha256sum -c $archive.sha256" +expect_status 0 +expect_line "$archive: OK" + +run "tar -xJf $archive +ls ${archive%.tar.xz}" +expect_status 0 +expect_line 'eb-pipeline' + +run "install -D -m 755 ${archive%.tar.xz}/eb-pipeline ~/.local/bin/eb-pipeline +command -v eb-pipeline +eb-pipeline --version" +expect_status 0 +expect_line 'eb-pipeline 0.3.0' + +run 'eb-pipeline targets --site site.toml' +expect_status 2 +expect_line "error: unrecognized subcommand 'targets'" + +git clone --quiet "$root" eb-pipeline +cd eb-pipeline + +run 'cargo install --locked --path . --root ~/.local' +expect_status 101 +expect_line 'error: binary `eb-pipeline` already exists in destination' +rm ~/.local/bin/eb-pipeline + +run "cargo +$old_toolchain install --locked --path . --root ~/.local" +expect_status 101 + +run 'cargo install --locked --quiet --path . --root ~/.local +command -v eb-pipeline +eb-pipeline --version' +expect_status 0 +expect_line "eb-pipeline $(crate_version)" + +run 'eb-pipeline targets --help | head -n 1' +expect_status 0 +expect_line 'Print the target names in file order, for a CI matrix or a shell loop' + +# An archive that is not the one the checksum names. +cd "$WORK" +printf x >>"$archive" +run "sha256sum -c $archive.sha256" +expect_status 1 +expect_line "$archive: FAILED" diff --git a/docs/examples/lib.sh b/docs/examples/lib.sh new file mode 100644 index 0000000..27dfe57 --- /dev/null +++ b/docs/examples/lib.sh @@ -0,0 +1,88 @@ +# shellcheck shell=bash +# Shared by the scripts in this directory, which source it. +# +# A script runs the commands of one page in order, the way a reader types +# them: in a home directory of its own, which mktemp makes and the script +# removes on exit, with the eb-pipeline of this checkout on PATH as +# ~/.cargo/bin/eb-pipeline. Build it first with `cargo build --locked`, or +# name another binary in DOCS_EB_PIPELINE. +# +# Each command prints as `+ COMMAND`, then what it wrote to stdout and +# stderr, as a terminal shows them, with the work directory written as $WORK +# and the home directory as $HOME. The pages paste that output. + +set -euo pipefail + +root=$(CDPATH='' cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd) +# shellcheck disable=SC2034 # for the scripts that source this file +pages=$root/docs/orgmode +bin=${DOCS_EB_PIPELINE:-$root/target/debug/eb-pipeline} +if [ ! -x "$bin" ]; then + echo "no eb-pipeline at $bin; run cargo build --locked first" >&2 + exit 2 +fi +bin=$(CDPATH='' cd -- "$(dirname -- "$bin")" && pwd)/$(basename -- "$bin") + +# eb-pipeline takes flags and site file values from these. +for name in "${!EB_PIPELINE_@}"; do + unset "$name" +done + +HOME=$(mktemp -d /tmp/eb-pipeline-docs.XXXXXX) +export HOME +trap 'rm -rf "$HOME"' EXIT +mkdir -p "$HOME/.cargo/bin" +ln -s "$bin" "$HOME/.cargo/bin/eb-pipeline" +export PATH=$HOME/.cargo/bin:/usr/bin:/bin +export LC_ALL=C +cd "$HOME" + +# The exit status and the output of the last command `run` ran. +status=0 +output= + +# Run one command, or a block of them, as the page shows it. +run() { + local log + log=$(mktemp /tmp/eb-pipeline-docs-run.XXXXXX) + printf '+ %s\n' "$1" + set +e + eval "$1" >"$log" 2>&1 + status=$? + set -e + output=$(rewrite <"$log") + rm -f "$log" + if [ -n "$output" ]; then + printf '%s\n' "$output" + fi +} + +# Write the work directory as $WORK and the home directory as $HOME. +rewrite() { + if [ -n "${WORK:-}" ]; then + sed -e "s#$WORK#\$WORK#g" -e "s#$HOME#\$HOME#g" + else + sed -e "s#$HOME#\$HOME#g" + fi +} + +# Stop unless the last command exited with status $1. +expect_status() { + if [ "$status" -ne "$1" ]; then + echo "expected exit status $1, got $status" >&2 + exit 1 + fi +} + +# Stop unless the output of the last command has the line $1. +expect_line() { + if ! grep -qxF -- "$1" <<<"$output"; then + echo "expected the line: $1" >&2 + exit 1 + fi +} + +# The version in Cargo.toml, which `eb-pipeline --version` prints. +crate_version() { + sed -n 's/^version = "\(.*\)"$/\1/p' "$root/Cargo.toml" | head -n 1 +} diff --git a/docs/examples/rotation.sh b/docs/examples/rotation.sh new file mode 100755 index 0000000..2f2b34d --- /dev/null +++ b/docs/examples/rotation.sh @@ -0,0 +1,135 @@ +#!/bin/bash +# The rotation of the log tree that docs/orgmode/howto/rotate-logs.org and +# docs/orgmode/explanation/log-rotation.org show: a run that rotates, runs +# that find another run live or rotating, and runs that find eb-keep-logs +# busy, old or failing; then the rotation outside a run, with flock(1). +# +# The stand-in for eb-keep-logs prints its arguments and exits with +# KEEP_LOGS_EXIT, 0 unless set. With KEEP_LOGS_OLD set, its --help leaves +# out --lock-timeout, as the help of eb-keep-logs 0.2.1 does. +# shellcheck disable=SC2016 # commands stay quoted as the pages show them +# shellcheck source-path=SCRIPTDIR source=lib.sh +. "$(dirname -- "$0")/lib.sh" + +export WORK=$HOME/rotation +mkdir -p "$WORK/bin" +cd "$WORK" +cat >bin/eb <<'EOF' +#!/bin/sh +echo "eb $*" +EOF +cat >bin/eb-keep-logs <<'EOF' +#!/bin/sh +if [ "$1" = --help ]; then + if [ -n "$KEEP_LOGS_OLD" ]; then + echo "usage: eb-keep-logs rotate LOG_ROOT --compress-after DAYS [--delete-after DAYS]" + else + echo "usage: eb-keep-logs rotate LOG_ROOT --compress-after DAYS [--delete-after DAYS] [--lock-timeout SECONDS]" + fi + exit 0 +fi +echo "eb-keep-logs $*" +exit "${KEEP_LOGS_EXIT:-0}" +EOF +chmod +x bin/eb bin/eb-keep-logs +export PATH=$WORK/bin:$PATH +cat >site.toml <build.list +lock=$WORK/logs/.eb-pipeline-rotate.lock +args='--site site.toml --list build.list --target cpu --build-type production' + +# The rotation a run would start. +run "eb-pipeline run $args --dry-run | grep '^\[logs\]'" +expect_status 0 +expect_line '[logs] TZ=UTC eb-keep-logs rotate $WORK/logs --compress-after 30 --delete-after 365 --lock-timeout 0' + +# A run that ends alone rotates. +run "eb-pipeline run $args --log-stamp 20261117_090000 --result result.json" +expect_status 0 +run "grep -B1 -A1 '\"name\": \"logs\"' result.json" +expect_line ' "status": "ok"' +run 'cat logs/20261117_090000/cpu/rotate.log' +expect_line 'eb-keep-logs rotate $WORK/logs --compress-after 30 --delete-after 365 --lock-timeout 0' + +# flock(1) holds the lock shared, as another live run does. +run "flock -s logs/.eb-pipeline-rotate.lock eb-pipeline run $args --log-stamp 20261117_100000 --result result.json" +expect_status 0 +expect_line 'INFO [logs] cpu: rotation skipped: another run under $WORK/logs holds $WORK/logs/.eb-pipeline-rotate.lock, live or rotating; the rotation is left to a run that ends alone' +run "grep -B1 -A2 '\"name\": \"logs\"' result.json" +expect_line ' "status": "skipped"' + +# flock(1) holds the lock alone for two seconds, as a run that rotates does. +flock -x "$lock" sleep 2 & +holder=$! +while flock -n -s "$lock" true; do + sleep 0.1 +done +run "eb-pipeline run $args --log-stamp 20261117_110000" +wait "$holder" +expect_status 0 +expect_line 'INFO [logs] cpu: waiting: another run rotates and holds $WORK/logs/.eb-pipeline-rotate.lock' + +# Another rotate holds the lock of eb-keep-logs. +run "KEEP_LOGS_EXIT=75 eb-pipeline run $args --log-stamp 20261117_120000" +expect_status 0 +expect_line 'INFO [logs] cpu: rotation skipped: eb-keep-logs rotate exited 75: another rotate holds $WORK/logs/.eb-keep-logs-rotate.lock, and this one changed nothing; the rotation is left to it' + +# An eb-keep-logs whose help does not list --lock-timeout. +run "KEEP_LOGS_OLD=1 eb-pipeline run $args --log-stamp 20261117_130000" +expect_status 0 +expect_line 'INFO [logs] cpu: no --lock-timeout for eb-keep-logs rotate: `eb-keep-logs --help` does not list it, as in eb-keep-logs 0.2.1, which takes no lock of its own' +run 'cat logs/20261117_130000/cpu/rotate.log' +expect_line 'eb-keep-logs rotate $WORK/logs --compress-after 30 --delete-after 365' + +# A rotate that fails. +run "KEEP_LOGS_EXIT=1 eb-pipeline run $args --log-stamp 20261117_140000; echo \"exit \$?\"" +expect_line 'ERROR [logs] cpu: eb-keep-logs rotate exited 1' +expect_line 'exit 1' + +# The rotation outside a run, as cron starts it. +run 'TZ=UTC flock -w 3600 -E 75 logs/.eb-pipeline-rotate.lock eb-keep-logs rotate logs --compress-after 30 --delete-after 365; echo "exit $?"' +expect_line 'exit 0' + +# The same while a run is live: flock(1) gives up after its wait. +flock -s "$lock" sleep 3 & +holder=$! +while flock -n -x "$lock" true; do + sleep 0.1 +done +run 'TZ=UTC flock -w 1 -E 75 logs/.eb-pipeline-rotate.lock eb-keep-logs rotate logs --compress-after 30 --delete-after 365; echo "exit $?"' +wait "$holder" +expect_line 'exit 75' + +# A rotation lock that cannot be taken: here its path is a directory. +mkdir -p other/.eb-pipeline-rotate.lock +run 'EB_PIPELINE__FILESYSTEMS__LOG_ROOT=$WORK/other eb-pipeline run '"$args"' --log-stamp 20261117_150000' +expect_status 0 +expect_line 'WARN [logs] cpu: cannot lock $WORK/other/.eb-pipeline-rotate.lock: Is a directory (os error 21); the rotation does not wait for other runs' diff --git a/docs/examples/select.sh b/docs/examples/select.sh new file mode 100755 index 0000000..4de18c3 --- /dev/null +++ b/docs/examples/select.sh @@ -0,0 +1,60 @@ +#!/bin/bash +# What docs/orgmode/howto/select-lines.org shows: the site file of +# build-from-ci/site.toml with a [targets.select] table in each target, a +# build list with a line for zen4 only, and what each target plans and runs +# of it, the last with a copy of the site file that has the local scheduler, +# no modules and its paths under $WORK, and the stand-in eb of the tutorial. +# shellcheck disable=SC2016 # commands stay quoted as the pages show them +# shellcheck source-path=SCRIPTDIR source=lib.sh +. "$(dirname -- "$0")/lib.sh" + +export WORK=$HOME/select +mkdir -p "$WORK" +cd "$WORK" +# The select table of each target goes after its [targets.phases] table. +select_table() { + printf '\n[targets.select]\noption = "--only-targets"\nvalue = "%s"\nstrip = true\n' "$1" +} +while IFS= read -r line; do + printf '%s\n' "$line" + case $line in + 'build = "-p cpu -C zen2 '*) select_table zen2 ;; + 'build = "-p cpu -C zen4 '*) select_table zen4 ;; + esac +done <"$pages/howto/build-from-ci/site.toml" >site.toml +printf '%s\n' Example-1.0-GCCcore-15.2.0.eb 'Example-2.0-GCCcore-15.2.0.eb --only-targets=zen4' >build.list + +run 'eb-pipeline check --site site.toml' +expect_status 0 + +run 'cat build.list' + +run 'eb-pipeline plan --site site.toml --list build.list --target zen2 --build-type production | grep -A5 "\"deselected\""' +expect_status 0 +expect_line ' "easyconfig": "Example-2.0-GCCcore-15.2.0.eb",' + +sed 's/^option = "--only-targets"$/option = "only-targets"/' site.toml >no-dashes.toml +run 'eb-pipeline check --site no-dashes.toml' +expect_status 2 + +mkdir local +sed -e 's/^kind = "slurm"/kind = "local"/' \ + -e "s#/opt/site#$WORK/site#g" \ + -e "s#/scratch/alice#$WORK/scratch#g" \ + -e 's/^init = \["EasyBuild"\]/init = []/' site.toml >local/site.toml +cp build.list local/ +cd local +# shellcheck source=../orgmode/tutorials/first-build-list/eb.sh +. "$pages/tutorials/first-build-list/eb.sh" +export PATH=$WORK/local/bin:$PATH + +run 'eb-pipeline run --site site.toml --list build.list --target zen4 --build-type production --dry-run | grep "^\[build\]" +eb-pipeline run --site site.toml --list build.list --target zen2 --build-type production --dry-run | grep "^\[build\]"' +expect_status 0 + +run 'eb-pipeline run --site site.toml --list build.list --target zen2 --build-type production --log-stamp 20261117_090000 --result result.json; echo "exit $?"' +expect_line 'exit 0' + +run 'cat $WORK/site/logs/20261117_090000/zen2/selected-zen2.list +grep -A4 "\"deselected\"" result.json' +expect_line 'Example-1.0-GCCcore-15.2.0.eb' diff --git a/docs/examples/site-file.sh b/docs/examples/site-file.sh new file mode 100755 index 0000000..b1e5ca7 --- /dev/null +++ b/docs/examples/site-file.sh @@ -0,0 +1,70 @@ +#!/bin/bash +# The site file that docs/orgmode/howto/write-a-site-file.org writes: the +# template it starts from, the checks of write-a-site-file/site.toml, its +# resolved configuration and dry run, an override from the environment, and +# the messages of its table of failures. The stand-in for eb-keep-logs +# prints a version, as `check --probe-tools` asks it to. +# shellcheck disable=SC2016 # commands stay quoted as the pages show them +# shellcheck source-path=SCRIPTDIR source=lib.sh +. "$(dirname -- "$0")/lib.sh" + +export WORK=$HOME/site +mkdir -p "$WORK/bin" "$WORK/lists" +cd "$WORK" +cat >bin/eb-keep-logs <<'EOF' +#!/bin/sh +echo "eb-keep-logs 0.2.1" +EOF +chmod +x bin/eb-keep-logs +export PATH=$WORK/bin:$PATH + +run 'eb-pipeline init --template small-cluster --out site.toml' +expect_status 0 + +# The edits of step 2. +cp "$pages/howto/write-a-site-file/site.toml" site.toml +printf '%s\n' Example-1.0-GCCcore-15.2.0.eb >lists/zen4.list + +run 'eb-pipeline check --site site.toml +eb-pipeline check --site site.toml --lists-dir lists +eb-pipeline check --site site.toml --probe-tools' +expect_status 0 +expect_line 'INFO [check] example: site file is valid' + +run 'eb-pipeline explain --site site.toml --target zen4 --build-type production' +expect_status 0 +expect_line 'EASYBUILD_INSTALLPATH = "/opt/site"' + +run 'eb-pipeline run --site site.toml --list lists/zen4.list --target zen4 --build-type production --dry-run' +expect_status 0 +expect_line 'INFO [run] zen4: dry run: nothing executed' + +run 'EB_PIPELINE__FILESYSTEMS__BUILD_PATH=/local/alice/build eb-pipeline explain --site site.toml --target zen4 | grep BUILDPATH' +expect_status 0 +expect_line 'INFO [site] -: filesystems.build_path set from EB_PIPELINE__FILESYSTEMS__BUILD_PATH' +expect_line 'EASYBUILD_BUILDPATH = "/local/alice/build"' + +# The failures. +sed 's/^log_root/log_rot/' site.toml >typo.toml +run 'eb-pipeline check --site typo.toml' +expect_status 2 +expect_line 'unknown field `log_rot`, expected one of `scratch`, `tmp`, `build_path`, `source_paths`, `install_root`, `export_install_vars`, `log_root`, `shard_dir`, `read_only_installdir`, `read_only_installdir_value`, `configs_repo`' + +sed 's/^kind = "slurm"/kind = "pbs"/' site.toml >pbs.toml +run 'eb-pipeline check --site pbs.toml' +expect_status 2 +expect_line 'ERROR [check] example: scheduler.kind: expected slurm or local, found `pbs`' + +sed 's/^compress_after_days = 30/compress_after_days = 400/' site.toml >rotate.toml +run 'eb-pipeline check --site rotate.toml' +expect_status 2 +expect_line 'ERROR [check] example: logs.rotate.delete_after_days: must be greater than compress_after_days (400), found 365' + +run 'eb-pipeline check --site site.toml --lists-dir .' +expect_status 2 +expect_line 'ERROR [check] example: targets.zen4.build_lists: `zen4.list` not found in .' + +rm bin/eb-keep-logs +run 'eb-pipeline check --site site.toml --probe-tools' +expect_status 2 +expect_line 'ERROR [main] -: eb_keep_logs: cannot run `eb-keep-logs --version`: No such file or directory (os error 2)' diff --git a/docs/examples/staged.sh b/docs/examples/staged.sh new file mode 100755 index 0000000..9f4c71c --- /dev/null +++ b/docs/examples/staged.sh @@ -0,0 +1,92 @@ +#!/bin/bash +# What docs/orgmode/howto/staged-rebuilds.org shows: the site file of +# build-from-ci/site.toml with a [rebuild] table, checked, and the site files +# that check refuses; then a copy of it with the local scheduler, no modules +# and its paths under $WORK, which rebuilds an installed package through a +# stand-in for eb-staged-rebuild. +# +# The stand-in prints its arguments and exits with STAGED_EXIT, 0 unless set. +# With 2 it first prints, on stderr, the refusal of eb-staged-rebuild that +# finds the lock of its state root held. +# shellcheck disable=SC2016 # commands stay quoted as the pages show them +# shellcheck source-path=SCRIPTDIR source=lib.sh +. "$(dirname -- "$0")/lib.sh" + +export WORK=$HOME/staged +mkdir -p "$WORK" +cd "$WORK" +cp "$pages/howto/build-from-ci/site.toml" site.toml +cat >>site.toml <<'EOF' + +[rebuild] +state_root = "/opt/site/{target}/.eb-staged-rebuild" +lock_timeout = 600 +EOF + +run 'eb-pipeline check --site site.toml' +expect_status 0 + +# One ledger configuration for both targets. +sed 's#^lock_timeout = 600$#&\nledger_config = "/opt/site/ledger.json"#' site.toml >shared-ledger.toml +run 'eb-pipeline check --site shared-ledger.toml' +expect_status 2 + +# One software tree for both targets. +sed 's#^site_prefix = "/opt/site/zen[24]"$#site_prefix = "/opt/site"#' site.toml >shared-tree.toml +run 'eb-pipeline check --site shared-tree.toml' +expect_status 2 + +mkdir local +sed -e 's/^kind = "slurm"/kind = "local"/' \ + -e "s#/opt/site#$WORK/site#g" \ + -e "s#/scratch/alice#$WORK/scratch#g" \ + -e 's/^init = \["EasyBuild"\]/init = []/' site.toml >local/site.toml +cd local +# shellcheck source=../orgmode/tutorials/first-build-list/eb.sh +. "$pages/tutorials/first-build-list/eb.sh" +cat >bin/eb-staged-rebuild <<'EOF' +#!/bin/sh +echo "eb-staged-rebuild $*" +state= +while [ $# -gt 0 ]; do + case $1 in + --state-root) state=$2; shift ;; + --) break ;; + esac + shift +done +if [ "${STAGED_EXIT:-0}" -eq 2 ]; then + echo "eb-staged-rebuild: another eb-staged-rebuild holds the lock at $state/.lock" >&2 +fi +exit "${STAGED_EXIT:-0}" +EOF +chmod +x bin/eb-staged-rebuild +export PATH=$WORK/local/bin:$PATH +mkdir -p "$WORK/site/zen4/modules/all/Example" +: >"$WORK/site/zen4/modules/all/Example/1.0-GCCcore-15.2.0.lua" +echo 'Example-1.0-GCCcore-15.2.0.eb --rebuild' >zen4.list +cp zen4.list zen2.list +args='--site site.toml --list zen4.list --target zen4 --build-type production' + +run 'ls $WORK/site/zen4/modules/all/Example' +expect_line '1.0-GCCcore-15.2.0.lua' + +run 'eb-pipeline run '"$args"' --run-id 1234 --dry-run | grep "^\[build\]"' +expect_status 0 + +run 'eb-pipeline run '"$args"' --run-id 1234 --log-stamp 20261117_090000 --result result.json; echo "exit $?"' +expect_line 'exit 0' + +run "grep -A3 '\"easyconfig\": \"Example' result.json" +expect_line ' "note": "ran through eb-staged-rebuild",' + +run 'cat $WORK/site/logs/20261117_090000/zen4/Example-1.0-GCCcore-15.2.0.stdout.log' + +run 'STAGED_EXIT=2 eb-pipeline run '"$args"' --run-id 1235; echo "exit $?"' +expect_line 'exit 78' + +run 'STAGED_EXIT=75 eb-pipeline run '"$args"' --run-id 1236; echo "exit $?"' +expect_line 'exit 75' + +run 'eb-pipeline run --site site.toml --list zen2.list --target zen2 --build-type production --run-id 1237; echo "exit $?"' +expect_line 'exit 0' diff --git a/docs/examples/templates.sh b/docs/examples/templates.sh new file mode 100755 index 0000000..9369fb4 --- /dev/null +++ b/docs/examples/templates.sh @@ -0,0 +1,29 @@ +#!/bin/bash +# The templates that docs/orgmode/reference/templates.org lists: their names, +# a site file written from each, and what `check` says about it. +# shellcheck source-path=SCRIPTDIR source=lib.sh +. "$(dirname -- "$0")/lib.sh" + +run 'eb-pipeline init --list' +expect_status 0 +expect_line 'small-cluster Slurm, one CPU target; no EESSI, inode quota or licences' + +for name in small-cluster eessi-site; do + run "eb-pipeline init --template $name --out $name.toml" + expect_status 0 + expect_line "INFO [init] -: wrote template $name to $name.toml" + if ! cmp -s "$name.toml" "$root/templates/$name.toml"; then + echo "$name.toml differs from templates/$name.toml" >&2 + exit 1 + fi + + run "eb-pipeline check --site $name.toml" + expect_status 0 +done + +run 'eb-pipeline init --template small-cluster --out small-cluster.toml' +expect_status 2 +expect_line 'ERROR [main] -: cannot create small-cluster.toml: File exists (os error 17)' + +run 'eb-pipeline targets --site eessi-site.toml' +expect_status 0 diff --git a/docs/examples/tutorial.sh b/docs/examples/tutorial.sh new file mode 100755 index 0000000..50cfff1 --- /dev/null +++ b/docs/examples/tutorial.sh @@ -0,0 +1,98 @@ +#!/bin/bash +# The commands of the tutorial, docs/orgmode/tutorials/first-build-list.org, +# in order; lib.sh puts the eb-pipeline of this checkout where +# `cargo install` puts it. Checks the exit statuses and the lines the page +# explains. The page shows `cargo --version` of Rust 1.90.0, as in +# RUSTUP_TOOLCHAIN=1.90.0 bash docs/examples/tutorial.sh. +# shellcheck disable=SC2016 # commands stay quoted as the page shows them + +# lib.sh moves HOME and PATH; keep the toolchain of the user who runs this. +cargo=$(command -v cargo) +export RUSTUP_HOME=${RUSTUP_HOME:-$HOME/.rustup} +export CARGO_HOME=${CARGO_HOME:-$HOME/.cargo} +# shellcheck source-path=SCRIPTDIR source=lib.sh +. "$(dirname -- "$0")/lib.sh" +snippets=$pages/tutorials/first-build-list +PATH=$PATH:$(dirname -- "$cargo") + +run 'cargo --version' +expect_status 0 + +run 'eb-pipeline --version' +expect_status 0 +expect_line "eb-pipeline $(crate_version)" + +run 'export WORK=$HOME/eb-tutorial +mkdir -p "$WORK" +cd "$WORK"' +expect_status 0 + +run "$(cat "$snippets/eb.sh")" +expect_status 0 + +run 'export PATH="$WORK/bin:$PATH" +command -v eb' +expect_line '$WORK/bin/eb' + +run "$(cat "$snippets/site.sh")" +expect_status 0 + +run 'eb-pipeline check --site site.toml' +expect_status 0 +expect_line 'INFO [check] example: site file is valid' + +run "cat > build.list <<'EOF' +Example-1.0-GCCcore-15.2.0.eb +zlib-1.3.1-GCCcore-15.2.0.eb --rebuild +EOF" +expect_status 0 + +run 'eb-pipeline run --site site.toml --list build.list --target cpu --build-type production --dry-run' +expect_status 0 +expect_line '[build] eb Example-1.0-GCCcore-15.2.0.eb' +expect_line '[build] eb zlib-1.3.1-GCCcore-15.2.0.eb --rebuild' +expect_line 'INFO [run] cpu: dry run: nothing executed' + +run 'eb-pipeline run --site site.toml --list build.list --target cpu --build-type production --result result.json +echo $?' +expect_line 'INFO [build] cpu: Example-1.0-GCCcore-15.2.0: ok' +expect_line 'INFO [build] cpu: zlib-1.3.1-GCCcore-15.2.0: ok' +expect_line 0 + +run 'cat result.json' +expect_line ' "exit_code": 0,' +expect_line ' "success": 2' + +run 'cat logs/*/cpu/Example-1.0-GCCcore-15.2.0.stdout.log' +expect_status 0 +expect_line 'eb Example-1.0-GCCcore-15.2.0.eb' +expect_line 'EASYBUILD_BUILDPATH=$WORK/scratch/build' + +# The log directory is named after the second the run starts in, and the next +# run needs a directory of its own. +sleep 1 + +run "cat > build.list <<'EOF' +Example-1.0-GCCcore-15.2.0.eb +Broken-1.0-GCCcore-15.2.0.eb +zlib-1.3.1-GCCcore-15.2.0.eb --rebuild +EOF" +expect_status 0 + +run 'eb-pipeline run --site site.toml --list build.list --target cpu --build-type production --result result.json +echo $?' +expect_line 'ERROR [build] cpu: Broken-1.0-GCCcore-15.2.0: failed (exit 1)' +expect_line 'INFO [build] cpu: zlib-1.3.1-GCCcore-15.2.0: ok' +expect_line 1 + +run "grep -A3 '\"counts\"' result.json" +expect_line ' "failed": 1,' +expect_line ' "success": 2' + +run 'cat logs/*/cpu/Broken-1.0-GCCcore-15.2.0.stdout.log' +expect_status 0 +expect_line 'ERROR: cannot build Broken-1.0-GCCcore-15.2.0.eb' + +run 'cd +rm -rf "$WORK"' +expect_status 0 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/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..abffb83 --- /dev/null +++ b/docs/orgmode/contributing.org @@ -0,0 +1,101 @@ +#+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/eb-pipeline][stackhands/eb-pipeline]]. +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 =towncrier.toml= configures: + +| Type | Section of the release notes | +|-----------+------------------------------| +| =feature= | Features | +| =bugfix= | Fixes | +| =doc= | Documentation | +| =removal= | Removals | +| =misc= | Miscellaneous | + +A fragment is one paragraph in the present tense that names the commands, options, keys and files it is about in backticks. +With towncrier 26.9.0 installed, =towncrier build --draft --version 0.3.0= prints the release notes the fragments make. +CI runs the same draft, and fails on a fragment whose name has no type. +A release writes the fragments into =CHANGELOG.md=, as [[https://github.com/stackhands/eb-pipeline/blob/main/RELEASING.md][RELEASING.md]] describes. + +** Run the tests + +With Rust 1.90 or newer, from the top of the repository: + +#+begin_src bash +cargo fmt --all --check +cargo clippy --locked --all-targets -- -D warnings +cargo test --locked +#+end_src + +=tests/run_stubs.rs= runs =eb-pipeline run= against stub programs for =eb=, =eb-stack=, =eb-keep-logs= and =eb-staged-rebuild=, written into a temporary directory. +=tests/examples.rs= checks that the built-in templates hold placeholders only. +Set =EB_PIPELINE_LINT_DENY= to a comma-separated list of your own site's names or paths before =cargo test --locked --test examples= to refuse them in the templates as well; the repository names none. +CI also builds with Rust 1.90.0, the oldest Rust the crate supports, with =cargo build --locked --all-targets=. + +The scripts under =docs/examples/= run the commands the pages show, in order, against the =eb-pipeline= that =cargo build --locked= built, and stop when an exit status or a line that a page explains is not what the page says: + +#+begin_src bash +cargo build --locked +bash docs/examples/tutorial.sh +#+end_src + +The =docs= job of the =ci= workflow runs every one of them but =install.sh=, which downloads release 0.3.0 and builds a clone of the checkout with =cargo install=. +Run that one by hand when the install steps change, with a Rust toolchain of 1.90 or newer, as =RUSTUP_TOOLCHAIN=1.90.0 bash docs/examples/install.sh=. + +** Build the documentation + +The documentation toolchain is pinned in =pixi.lock=: Emacs, Sphinx, lychee, and the Rust 1.90 that builds the API pages. +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 rustdoc warning, any public item of the library without a doc comment, 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 documentation template's Sphinx domain for Zig, unused here | +| =docs/tools/check_site.py= | checks internal links, anchors and forbidden names | +| =docs/tools/api-index.html= | the front page of the rustdoc site, which =cargo doc= does not write | +| =docs/examples/= | the scripts that print the output the pages show | + +The =.rst= files under =docs/source/= and everything under =docs/build/= are generated and not committed. +=pixi run -e docs rustdoc= runs =cargo doc= into =docs/build/cargo/= and copies the result to =docs/build/html/api/=. + +** 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. + +Every command and output block comes from a real run. +A page that shows output has a script under =docs/examples/= that runs its commands and prints what they print, with its temporary directories written as =$WORK= and =$HOME=; paste the output from there. +A file of more than a few lines that a page shows lives beside the page, as =docs/orgmode/tutorials/first-build-list/site.sh= does, and the page pulls it in with =#+INCLUDE=, so that the script runs the file the page shows. + +API documentation is written in the code, and the first sentence of each comment is the summary shown in lists. +In Rust it is a =///= comment above each =pub= item and a =//!= comment at the top of each module. +A site file key is documented once, in the =doc_struct!= table of =src/schema.rs=: that text is both what =eb-pipeline schema= prints and the doc comment of the key's field. +[[file:reference/site-file.org][The site file]] lists the same keys, and =tests/docs.rs= fails when one of its tables and the schema differ in a key, its order, its type or its default. diff --git a/docs/orgmode/explanation/design.org b/docs/orgmode/explanation/design.org new file mode 100644 index 0000000..d5cd8f7 --- /dev/null +++ b/docs/orgmode/explanation/design.org @@ -0,0 +1,82 @@ +#+TITLE: Why one site file drives the build +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Why one site file drives the build + +Why does eb-pipeline keep everything about a site in one Tom's Obvious Minimal Language (TOML) file, and leave the continuous integration (CI) system a caller that passes a list and a target? + +** The problem + +Building a site's software with EasyBuild takes more than =eb=. +The build list is split into units with eb-stack, the sources are fetched, each unit is admitted under the inode quota of scratch, each line builds in a Slurm allocation with the site's modules loaded, a failed build keeps its logs through eb-keep-logs, and the log tree is rotated. +Every step needs something of the site's: the partitions and their limits, the scratch and install paths, the licence groups, the quota command. + +When the CI system holds those, in a Jenkins file, a GitLab CI job or a cron script, each caller has its own copy of them, and of the order of the steps. +Two callers then build the same list in two ways, a change to a path is made in as many places as there are callers, and nothing shows the commands of a run before it starts them on the cluster. + +** How eb-pipeline handles it + +*** One file describes the site, the environment one deployment + +The site file describes the targets, the scheduler allocations, the paths, admission, modules, caches, log handling and licences. +A table that turns on a phase, such as =[admission]= or =[caches]=, can be left out or set =enabled = false=, and the run then passes over that phase and records it as =not configured=. +The parser refuses a key it does not know and a value of the wrong type, so a typing error stops =check= instead of falling back to a default. +The keys that 0.2.0 added are all optional, and their defaults do what 0.1.0 did, so a site file of 0.1.0 stays valid with =schema_version = 1=. + +The environment holds what differs from one deployment of the same file to the next. +Each option falls back to an =EB_PIPELINE_= variable, and =EB_PIPELINE__SECTION__KEY= sets one value of the file; the file and those values go through the same schema as the file alone. +A command logs each such value by its key and its variable, never by the value. + +*** The plan comes before the run + +=plan= works out every command of a run and starts none of them: the launch line, the environment and the argument vector of each, as JavaScript Object Notation (JSON) with sorted keys, the same on every call, so two plans can be compared with =diff=. +=run --dry-run= prints the same commands as text, and =explain= prints what the file comes to for each target. +=run= starts the same commands, with what only a run knows filled in: the job id and the other variables that =plan= shows as =${NAME}=, and, with sharding, the units of the plan that =stack shard= writes, which =plan --shard-plan DIR= reads. + +*** Commands are argument vectors + +=run= starts each command as a list of arguments, and writes its output to a log file of its own. +A string of the site file that holds arguments, such as the launch arguments of a role or =[caches]= =command=, is split on spaces, with quoted text kept together, and no shell takes part, so =$= and backquotes in it stay as they are. +The one shell that eb-pipeline starts is the module wrapper, which a =[modules]= init list puts before a command: a fixed script that loads the modules named in a variable, then runs the command from its own arguments. +=[admission]= =quota_cmd= and =live_jobs_cmd= are shell commands, which eb-stack runs. + +*** The other tools stay programs of their own + +eb-pipeline starts eb-stack, eb-keep-logs and eb-staged-rebuild as programs, and never links them in. +Each keeps its own releases, its own command line and its own documentation, and a site can run each one by hand. +A =min_version= in =[site.tools]= is checked before any work, and the exit statuses of each tool are read as that tool defines them, then mapped onto the statuses of a run, as [[file:phases.org][How a run goes through its phases]] describes. + +*** The caller is thin + +A caller passes a site file, a build list, a target, a build type and a run id, and reads an exit status and a result file. +It names no partition, path, licence group or quota command, so a Jenkins job, a GitLab CI job, a GitHub Actions workflow and a cron line build a list the same way. +[[file:../howto/build-from-ci.org][Build a list on every target from continuous integration]] shows such a caller. + +*** Nothing about a site lives in the repository + +The templates that =init= writes carry placeholders only, and are built into the binary, so =init= works without a checkout. +A test refuses a template value that looks like one site's, and =EB_PIPELINE_LINT_DENY= adds the names and paths of a site of one's own to what it refuses. + +** What was considered and turned down + +- /A run that builds every target of the site file./ + A run builds one target, and the caller starts one run per name that =targets= prints. + Each target has launch lines, an install tree and a log directory of its own, each run writes one result file, and a CI system that starts one job per target shows the state of each, and can run them at once when their paths allow, as [[file:shared-paths.org][What the targets of a site file share]] explains. +- /Module names written into the text of the wrapper./ + The script stays the same for every command and takes the module names from a variable, so a module name cannot become a command of the shell. +- /Linking the tools in./ + Each tool is released, documented and run on its own; started as a program, it stays so, and eb-pipeline needs from it only its command line, its exit statuses and what it writes, such as the shard plan of =stack shard=. + +** Limits + +- =check= reads the site file and, when asked, checks that the build lists are files in a directory and runs the tools for their versions; it does not check that a partition, a path or a group exists on the cluster. +- The licence gate checks the site file only: that every package that needs a licence has a group, a version threshold or an exemption. + It does not check file permissions or group membership on the host. +- A value inside =[[targets]]= cannot be set from the environment; it stays in the file. + +** Further reading + +- [[file:phases.org][How a run goes through its phases]], for the order of the work and the exit status. +- [[file:../reference/site-file.org][The site file]], for every key. +- [[file:../reference/environment.org][Environment variables]], for the variables that a deployment sets. diff --git a/docs/orgmode/explanation/figures/locks.dot b/docs/orgmode/explanation/figures/locks.dot new file mode 100644 index 0000000..ace8dbe --- /dev/null +++ b/docs/orgmode/explanation/figures/locks.dot @@ -0,0 +1,25 @@ +// Who takes the two locks in the log root, and in which order. +digraph locks { + graph [bgcolor="white", rankdir=TB, nodesep=0.6, ranksep=0.6, fontname="Helvetica"]; + node [shape=box, style="rounded,filled", fillcolor="#f4f4f4", color="#555555", fontname="Helvetica", fontsize=11]; + edge [color="#555555", fontname="Helvetica", fontsize=10]; + + live [label="A run, while it writes logs"]; + ends [label="A run, at its end"]; + cron [label="The cron line:\nTZ=UTC flock -w 3600 -E 75 ... eb-keep-logs rotate ..."]; + runrotate [label="eb-keep-logs rotate --lock-timeout 0"]; + cronrotate [label="eb-keep-logs rotate"]; + pipeline [shape=note, fillcolor="#ffffff", label="LOG_ROOT/.eb-pipeline-rotate.lock\neb-pipeline's lock"]; + keeplogs [shape=note, fillcolor="#ffffff", label="LOG_ROOT/.eb-keep-logs-rotate.lock\neb-keep-logs' lock"]; + + {rank=same; live; ends; cron;} + {rank=same; runrotate; cronrotate;} + + live -> pipeline [label=" shared"]; + ends -> pipeline [label=" 1. alone, without waiting;\l otherwise the run leaves the rotation\l to another\l"]; + ends -> runrotate [label=" then starts"]; + cron -> pipeline [label=" 1. alone, waiting up to an hour;\l otherwise exit 75\l"]; + cron -> cronrotate [label=" then starts"]; + runrotate -> keeplogs [label=" 2. alone, without waiting;\l otherwise exit 75\l"]; + cronrotate -> keeplogs [label=" 2. alone, waiting up to\l --lock-timeout seconds\l"]; +} diff --git a/docs/orgmode/explanation/figures/locks.svg b/docs/orgmode/explanation/figures/locks.svg new file mode 100644 index 0000000..618d801 --- /dev/null +++ b/docs/orgmode/explanation/figures/locks.svg @@ -0,0 +1,116 @@ + + + + + + +locks + + + +live + +A run, while it writes logs + + + +pipeline + + + +LOG_ROOT/.eb-pipeline-rotate.lock +eb-pipeline's lock + + + +live->pipeline + + + shared + + + +ends + +A run, at its end + + + +runrotate + +eb-keep-logs rotate --lock-timeout 0 + + + +ends->runrotate + + + then starts + + + +ends->pipeline + + + 1. alone, without waiting; + otherwise the run leaves the rotation + to another + + + +cron + +The cron line: +TZ=UTC flock -w 3600 -E 75 ... eb-keep-logs rotate ... + + + +cronrotate + +eb-keep-logs rotate + + + +cron->cronrotate + + + then starts + + + +cron->pipeline + + + 1. alone, waiting up to an hour; + otherwise exit 75 + + + +keeplogs + + + +LOG_ROOT/.eb-keep-logs-rotate.lock +eb-keep-logs' lock + + + +runrotate->keeplogs + + + 2. alone, without waiting; + otherwise exit 75 + + + +cronrotate->keeplogs + + + 2. alone, waiting up to + --lock-timeout seconds + + + diff --git a/docs/orgmode/explanation/figures/phases.dot b/docs/orgmode/explanation/figures/phases.dot new file mode 100644 index 0000000..ff6714a --- /dev/null +++ b/docs/orgmode/explanation/figures/phases.dot @@ -0,0 +1,33 @@ +// The phases of one run, and what each outcome does to the rest of it. +digraph phases { + 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]; + + inputs [label="Read the site file and the build list,\ncheck the licence gate and the versions of the tools"]; + usage [label="Exit 2, or 78 when only the licence gate fails;\nno result file", fillcolor="#ffffff"]; + preflight [label="preflight: read the variables the site file names"]; + refused [label="Write the result file, exit 78", fillcolor="#ffffff"]; + shard [label="shard: eb-stack stack shard splits the list into units,\nor the list builds as one unit"]; + sources [label="sources: fetch the sources of each line;\na line whose fetch fails is not built"]; + admit [label="admission: eb-stack stack admit, for the next unit"]; + build [label="build: eb, or eb-staged-rebuild run, for each line of the unit;\na failed line keeps its logs, and the next line starts"]; + more [shape=diamond, label="Another unit?", fillcolor="#ffffff"]; + skip [label="The lines of this unit and of the later ones are skipped", fillcolor="#ffffff"]; + caches [label="caches: only after a clean build"]; + logs [label="logs: rotate the log tree, when no other run is live"]; + result [label="Write the result file, and exit:\n1 if anything failed, else 78 if anything was refused,\nelse 75 if anything is pending, else 0"]; + + inputs -> usage [label=" invalid"]; + inputs -> preflight [label=" valid"]; + preflight -> refused [label=" one is unset"]; + preflight -> shard [label=" all are set"]; + shard -> sources -> admit; + admit -> build [label=" admitted"]; + admit -> skip [label=" refused"]; + build -> more; + more -> admit [label=" yes"]; + more -> caches [label=" no"]; + skip -> caches; + caches -> logs -> result; +} diff --git a/docs/orgmode/explanation/figures/phases.svg b/docs/orgmode/explanation/figures/phases.svg new file mode 100644 index 0000000..848ce3e --- /dev/null +++ b/docs/orgmode/explanation/figures/phases.svg @@ -0,0 +1,190 @@ + + + + + + +phases + + + +inputs + +Read the site file and the build list, +check the licence gate and the versions of the tools + + + +usage + +Exit 2, or 78 when only the licence gate fails; +no result file + + + +inputs->usage + + + invalid + + + +preflight + +preflight: read the variables the site file names + + + +inputs->preflight + + + valid + + + +refused + +Write the result file, exit 78 + + + +preflight->refused + + + one is unset + + + +shard + +shard: eb-stack stack shard splits the list into units, +or the list builds as one unit + + + +preflight->shard + + + all are set + + + +sources + +sources: fetch the sources of each line; +a line whose fetch fails is not built + + + +shard->sources + + + + + +admit + +admission: eb-stack stack admit, for the next unit + + + +sources->admit + + + + + +build + +build: eb, or eb-staged-rebuild run, for each line of the unit; +a failed line keeps its logs, and the next line starts + + + +admit->build + + + admitted + + + +skip + +The lines of this unit and of the later ones are skipped + + + +admit->skip + + + refused + + + +more + +Another unit? + + + +build->more + + + + + +more->admit + + + yes + + + +caches + +caches: only after a clean build + + + +more->caches + + + no + + + +skip->caches + + + + + +logs + +logs: rotate the log tree, when no other run is live + + + +caches->logs + + + + + +result + +Write the result file, and exit: +1 if anything failed, else 78 if anything was refused, +else 75 if anything is pending, else 0 + + + +logs->result + + + + + 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/index.org b/docs/orgmode/explanation/index.org new file mode 100644 index 0000000..c7fb3bf --- /dev/null +++ b/docs/orgmode/explanation/index.org @@ -0,0 +1,18 @@ +#+TITLE: Explanation +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Explanation + +These pages say why eb-pipeline 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 + + design + phases + log-rotation + shared-paths +#+end_export diff --git a/docs/orgmode/explanation/log-rotation.org b/docs/orgmode/explanation/log-rotation.org new file mode 100644 index 0000000..36a680e --- /dev/null +++ b/docs/orgmode/explanation/log-rotation.org @@ -0,0 +1,93 @@ +#+TITLE: Why the rotation takes two locks +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Why the rotation takes two locks + +Why does a run rotate the log tree only when it can hold a lock alone, and why does every rotation take two locks, always in the same order? + +** The problem + +Each run writes its logs under =LOG_ROOT/LOG_STAMP/TARGET=, and the runs of every target of a site file, on every host, can share one log root. +=eb-keep-logs rotate= compresses the =*.log= and =*.txt= files of the run directories older than =--compress-after= days, deletes those older than =--delete-after= days, and rewrites the =.licensed-logs= file of each run it compresses: the list of the kept files closed to other users, as a failed compile line of licensed software can print the licence number. + +A run's age counts from the midnight in Coordinated Universal Time (UTC) of its log stamp, so a run that started before midnight is a day old just after it, while it still writes. +Without anything to keep them apart: + +- a rotation compresses the logs of a run that is still writing them, once that run is old enough; +- two rotations at once lose each other's changes to a run's =.licensed-logs=. + +eb-keep-logs 0.2.1 takes no lock, and passes over at most the run that it writes into itself. + +** How eb-pipeline handles it + +Two =flock= locks in the log root keep the rotations apart from each other and from the runs that write into the tree. + +#+CAPTION: Who takes the two locks in the log root, and in which order. +#+ATTR_RST: :alt A run holds eb-pipeline's lock, LOG_ROOT/.eb-pipeline-rotate.lock, shared while it writes logs. At its end it takes that lock alone without waiting, or leaves the rotation to another, and then starts eb-keep-logs rotate --lock-timeout 0, which takes eb-keep-logs' lock, LOG_ROOT/.eb-keep-logs-rotate.lock, alone without waiting, or exits 75. The cron line takes eb-pipeline's lock alone with flock, waiting up to an hour, or exits 75, then starts eb-keep-logs rotate, which takes eb-keep-logs' lock alone, waiting up to --lock-timeout seconds. +[[file:figures/locks.svg]] + +*** No rotation while a run is live + +With =[logs.rotate]=, a run holds =LOG_ROOT/.eb-pipeline-rotate.lock= shared from its start, after =preflight=, to its end. +At its end it lets go of the lock, and takes it alone without waiting. +When it can, it rotates while it holds the lock; when it cannot, another run under the log root is live or rotating, the =logs= phase is =skipped=, and the rotation is left to a run that ends alone. +A run that starts while another rotates waits for it, so a rotation never runs beside a live run, and the last run to end alone rotates. + +*** No two rotates at once + +An eb-keep-logs whose =--help= lists =--lock-timeout= takes =LOG_ROOT/.eb-keep-logs-rotate.lock= alone in =rotate=, from before it lists the log root until it exits. +It waits for the lock up to =--lock-timeout= seconds, 600 unless given, and 0 does not wait; when the wait runs out, it exits 75, having changed nothing. +That lock keeps two rotates apart, but not a rotate and a run that still writes on another host, which is what eb-pipeline's lock is for. + +*** One order + +Whatever takes both locks takes eb-pipeline's first and eb-keep-logs' second. +A run's rotation does, and so does a rotation from cron through =flock(1)=, as in [[file:../howto/rotate-logs.org][Rotate the log tree]]; eb-keep-logs takes only its own. +So nothing waits for eb-pipeline's lock while it holds eb-keep-logs', and two rotations cannot deadlock. + +*** A run does not wait for another rotate + +=run= passes =--lock-timeout 0=. +While it rotates, a run holds eb-pipeline's lock alone, and every run under the log root that starts meanwhile waits for it, so a wait for another rotate would hold those runs back as well. +A =rotate= that exits 75 leaves =logs= =skipped=, with a note that names =.eb-keep-logs-rotate.lock=, and the rotation to the rotate that holds it. +That rotate lists the log root after it takes the lock, so it does this rotation's work, and a later run that ends alone does what is left. + +*** Older eb-keep-logs + +eb-keep-logs 0.2.1 refuses =--lock-timeout= with exit 2, and the builds that take it print the same version, so =run= passes the option only when =eb-keep-logs --help= lists it. +It reads the help where it checks =min_version=, with the environment of the rotation, and only when it rotates. +Without the option the rotation runs as it does with 0.2.1, and an =INFO= line and the note of =logs= say why, here from =docs/examples/rotation.sh= with a stand-in whose help leaves the option out: + +#+begin_example +INFO [logs] cpu: no --lock-timeout for eb-keep-logs rotate: `eb-keep-logs --help` does not list it, as in eb-keep-logs 0.2.1, which takes no lock of its own +#+end_example + +** What was considered and turned down + +- /Waiting for another rotate inside a run./ + The run would hold eb-pipeline's lock alone while it waits, and so every run that starts on the log root meanwhile. +- /Taking eb-pipeline's lock in eb-keep-logs./ + A run starts =eb-keep-logs rotate= while it holds that lock alone, so eb-keep-logs would wait for the run that waits for it. +- /Choosing =--lock-timeout= by the version that eb-keep-logs prints./ + The builds that take the option print 0.2.1 as well, so only the help tells them apart. +- /Recording an exit 75 of =rotate= as a failure./ + Nothing changed, and the rotate that holds the lock does the work, so =logs= is =skipped= and the status of the run stays as it was. + +** Limits + +- The locks hold between nodes only where the filesystem of the log root carries =flock= between them. +- Only a run whose site file has =[logs.rotate]= takes eb-pipeline's lock, so a run of a site file without it that writes into the same log root is not kept apart from the rotations. +- A run can start while the cron line waits, so on a log root that always has a live run the cron line gives up after its hour, and the last run to end alone can rotate before it does. +- eb-keep-logs 0.2.1 takes no lock of its own; the cron line through =flock= keeps a rotation by it apart from the runs and their rotations. +- A run that cannot take its lock at all, as when its path is a directory in =docs/examples/rotation.sh=, logs a =WARN= and rotates without waiting for other runs: + + #+begin_example + WARN [logs] cpu: cannot lock $WORK/other/.eb-pipeline-rotate.lock: Is a directory (os error 21); the rotation does not wait for other runs + #+end_example + +** Further reading + +- [[file:../howto/rotate-logs.org][Rotate the log tree]], for the configuration, the cron line and the messages. +- [[file:../reference/log-tree.org][The log tree and its locks]], for the files and the locks. +- The [[https://stackhands.github.io/eb-keep-logs/][eb-keep-logs documentation]], for what =rotate= does to a run directory. diff --git a/docs/orgmode/explanation/phases.org b/docs/orgmode/explanation/phases.org new file mode 100644 index 0000000..c3d66ab --- /dev/null +++ b/docs/orgmode/explanation/phases.org @@ -0,0 +1,88 @@ +#+TITLE: How a run goes through its phases +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* How a run goes through its phases + +In what order does a run do its work, what stops it, and how does one exit status tell a caller what happened to a list of many lines? + +** The problem + +A run builds a list on one target through several tools, in many processes, and each tool has exit statuses of its own. +Some outcomes say that a build is broken, some that a precondition held the work back, some that a later rerun will do, and one run can end with all three. +The caller reads one exit status, and has to know from it what to do next, without reading the log of every line. + +** How eb-pipeline handles it + +*** The phases, in order + +A run goes through =preflight=, =licences=, =shard=, =sources=, =admission=, =build=, =caches= and =logs=, in that order. +A phase whose table is absent, or has =enabled = false=, is =not configured=, and the run passes over it. + +#+CAPTION: The phases of one run, and what each outcome does to the rest of it. +#+ATTR_RST: :alt The run reads the site file and the build list and checks the licence gate and the versions of the tools; when they are invalid it exits 2, or 78 when only the licence gate fails, with no result file. preflight reads the variables that the site file names; when one is unset, the run writes the result file and exits 78. shard splits the list into units, and sources fetches the sources of each line. Then each unit is admitted and its lines built, one unit after the other; a refused admission skips that unit and the later ones. caches runs only after a clean build, logs rotates the log tree when no other run is live, and the run writes the result file and exits 1 if anything failed, else 78 if anything was refused, else 75 if anything is pending, else 0. +[[file:figures/phases.svg]] + +Before the first phase, =run= reads the site file and the build list, and checks the licence gate and the versions of the tools. +An error there exits 2, or 78 when only the licence gate fails, and writes no result file, so the caller reads the exit status before the file. +The =licences= phase records the gate that passed. + +- =preflight= reads the variables that the site file names, such as the one that =[admission]= =job_id_env= names; one that is unset, or a job id that is not a number, refuses the run, with exit 78. +- =shard= has =eb-stack stack shard= split the list into units, or builds the list as one unit when the planner exits with =shards.planner_exit_unsharded=. + Any other failure ends the run before the first build, with exit 1, or 2 when =stack shard= exits 2. +- =sources= fetches the sources of each line; a line whose fetch fails is =failed= and is not built, and the other lines go on. +- =admission= and =build= take one unit at a time. + A refusal after the last attempt skips the lines of that unit and of every later one, and the run exits 78, or 1 when a line failed before; any other failure of =stack admit= ends the run at once. +- =build= starts the lines of a unit in list order. + A line that fails keeps its logs, with =eb-keep-logs failed= when =[logs]= =keep_failed= is set, and the next line starts; so does the next line after a staged line that eb-staged-rebuild refused or left pending. +- =caches= runs only after a clean build, and =logs= rotates the log tree, as [[file:log-rotation.org][Why the rotation takes two locks]] describes. + +*** Units, one at a time + +=stack shard= splits a list into units: the CPU-only prerequisites, when it lifts them out, then the prelude, which holds the modules that two or more shards need, then each shard. +=run= builds them in that order, one at a time, each after an admission of its own. +Each admission reserves the inodes of one unit, and the reservation is removed when the builds of that unit end, so a run holds the quota for the unit it builds, not for the whole list. + +*** One exit status for the whole run + +A signal ends the run with its own status: =run= passes =SIGTERM= or =SIGINT= to the child that is running, starts no other, writes the result file, and exits 143 or 130. +Otherwise the run exits 1 when a line or a phase failed, else 78 when something was refused, by a precondition, by admission or by eb-staged-rebuild, else 75 when a step is pending, else 0. + +The order puts first what needs the most from a person. +A failed build needs someone to read its log, whatever else happened in the run; a refusal needs a precondition met or the quota freed, and the lines built before it stay built; a pending step needs only a rerun. +The result file keeps what the status leaves out: the status of every line, with its log, and the counts. + +*** The statuses of the tools, mapped + +The same number means different things to different tools: 2 is a usage error for eb-pipeline, and a refusal for =eb-staged-rebuild run=. +So =run= reads the status of each tool as that tool defines it, and records what it means: + +- =eb-stack stack admit= exits 0 when it admits, 78 when it refuses, which =run= retries with the backoff of =[admission]=, 1 when it fails and 2 on a usage error. +- =eb-stack stack shard= exits with =shards.planner_exit_unsharded= when it built the plan unsharded, and the run goes on with one unit. +- =eb-staged-rebuild run= exits 2 for a refusal, which the line records as =refused= with =translated_from = 2=, and 75 when a record that its ledger requires is pending. +- =eb-keep-logs rotate= exits 75 when another rotate holds its lock, and the =logs= phase is =skipped=, with the status of the run as it was. + +Any other status but 0 of these commands is a failure. +=eb-keep-logs failed=, which keeps the logs of a failed line, only logs a =WARN= when it fails. + +** What was considered and turned down + +- /An exit status that counts the failures./ + An exit status is one byte, and a count would run into the statuses that mean something else, such as 2, 75 and 78; the result file has the counts. +- /Passing the status of a tool through as the status of the run./ + The caller would read eb-staged-rebuild's refusal, 2, as a usage error of eb-pipeline's. +- /Building one shard alone./ + A shard can need what the prelude installs, so =run= builds the units in order and has no option to build one of them. + +** Limits + +- A run builds one unit at a time; two units of a list never build at once in one run. +- A shard holds lines of the input list only, so a line whose other dependencies are not installed needs =--robot= to build them. +- A job that the scheduler kills leaves its reservation behind, and =stack admit= counts it, unless =[admission]= =live_jobs_cmd= lists the jobs that still run. +- A signal ends the run only after the running child has ended. + +** Further reading + +- [[file:../reference/exit-status.org][Exit status]], for the table of statuses. +- [[file:../reference/plan-and-result.org][The plan and result files]], for the statuses of the lines and the phases. +- [[file:design.org][Why one site file drives the build]], for why the commands come from the site file. diff --git a/docs/orgmode/explanation/shared-paths.org b/docs/orgmode/explanation/shared-paths.org new file mode 100644 index 0000000..0e2437f --- /dev/null +++ b/docs/orgmode/explanation/shared-paths.org @@ -0,0 +1,70 @@ +#+TITLE: What the targets of a site file share +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* What the targets of a site file share + +Which paths do the targets of one site file share, what goes wrong when two of them build into one path at once, and when can they build at the same time? + +** The problem + +A site file names its paths once, in =[filesystems]= and =[rebuild]=, and every target builds with them unless a path says otherwise. +When two targets build at once with the same paths: + +- EasyBuild builds an easyconfig in =BUILD_PATH/NAME/VERSION/TOOLCHAIN-TOOLCHAIN_VERSION=, followed by the version suffix of the easyconfig, with no target in the path, and removes that directory when the build starts and again after it installs. + Two targets that build one easyconfig at once remove each other's build directory, and the build that loses it fails. +- EasyBuild downloads a missing source into the first entry of =source_paths=, and writes the file in place. + A target that looks for a source that another target is still downloading finds the part that is written, and fails its checksum. +- eb-staged-rebuild holds the lock of its state root for the whole of a staged build and publish, so the staged lines of targets that share a state root take turns. +- =stack shard= writes its plan into =SHARD_DIR/RUN_ID=, which has no target in it, and eb-staged-rebuild refuses a run id it already holds, so two targets that run with one run id write their shard plans into one directory, and pass eb-staged-rebuild the same =RUN_ID-STEM=. + +** How eb-pipeline handles it + +*** ={target}= where a path is not safe to share + +={target}= in =[filesystems]= =build_path=, in the entries of =source_paths= and in =[rebuild]= =state_root= expands to the name of the target, and =plan= and =explain= show the expanded paths: + +- =build_path = "/scratch/alice/build/{target}"= gives each target an =EASYBUILD_BUILDPATH= of its own. +- =source_paths = ["/scratch/alice/sources/{target}", "/opt/site/sources"]= gives each target a download directory of its own, and still finds the sources under =/opt/site/sources=. +- =state_root = "/opt/site/{target}/.eb-staged-rebuild"= gives each target a state root, and so a lock, of its own. + A =state_root= left unset does the same: eb-staged-rebuild then keeps its state in =.eb-staged-rebuild= beside the =software= tree of each target. + +eb-staged-rebuild locks a live tree through its state root, so one tree takes one state root: =check= refuses a ={target}= state root when two targets that take staged rebuilds share a software root. + +*** What is safe to share + +=EASYBUILD_TMPDIR= is safe to share: each =eb= makes a directory of its own, =eb-*=, under it. +So is =log_root=: each run writes under =LOG_STAMP/TARGET=, and with =[logs.rotate]= a run rotates only when no other run under the log root is live, as [[file:log-rotation.org][Why the rotation takes two locks]] explains. + +*** A run id per target + +Each target needs a run id of its own, for its shard plan and its staged rebuilds. +The default run id, the log stamp, is the same for two runs that start in the same second, so a caller that builds several targets gives each run its own, such as the id of the continuous integration (CI) run followed by the target, as [[file:../howto/build-from-ci.org][Build a list on every target from continuous integration]] does. + +*** One target at a time, unless the paths are apart + +The example workflow of =examples/ci/= builds one target at a time, with =max-parallel: 1=, and a target that fails leaves the others running. +Two targets can build at once only when no two of them share a build directory, a download directory or, with staged rebuilds, a state root. +A =build_path= without ={target}= is one path for every target, so it needs storage that the build nodes of no two targets share. + +The =concurrency= group of the build job in that workflow, one per target, keeps two dispatches of the workflow off one target, not off one path: one dispatch can build a target while another builds a different one. +Targets that share a path therefore need one group for the whole build job, with no target in its name. + +** What was considered and turned down + +- /={target}= in every path of =[filesystems]=./ + The log directory of a run already ends with its target, the install tree of a target is its =site_prefix=, and EasyBuild's temporary directory is safe to share, so =check= refuses ={target}= in the other paths of =[filesystems]=. +- /A staged line that waits for the lock with no deadline./ + A second staged build waits up to =[rebuild]= =lock_timeout= for the lock, 600 seconds unless set, and is =refused= when the first still holds it, so the run ends with 78 instead of waiting with no end. + +** Limits + +- eb-staged-rebuild has not measured its lock between two build nodes. +- GitHub keeps one pending job per concurrency group, so a third dispatch replaces the one that waits, which is cancelled. +- The group belongs to the repository and has no workflow name in it, so another workflow of the repository that uses the same group waits as well. + +** Further reading + +- [[file:../howto/build-from-ci.org][Build a list on every target from continuous integration]], for the workflow and the caller script. +- [[file:../reference/site-file.org][The site file]], for ={target}= and the keys it expands in. +- [[file:../howto/staged-rebuilds.org][Rebuild installed software through eb-staged-rebuild]], for the state root of each target. diff --git a/docs/orgmode/howto/build-from-ci.org b/docs/orgmode/howto/build-from-ci.org new file mode 100644 index 0000000..9692d3b --- /dev/null +++ b/docs/orgmode/howto/build-from-ci.org @@ -0,0 +1,133 @@ +#+TITLE: Build a list on every target from continuous integration +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Build a list on every target from continuous integration + +Build one list on every target of a site file from continuous integration (CI): one run per target, each with a run id of its own, and one target at a time unless the targets build in places of their own. +The caller names no partition, path, licence group or quota command; the site file holds them, and the caller keeps the exit status and the result file of each run. + +** Before you start + +- A site file that passes =check=, in a repository with the build lists, as in [[file:write-a-site-file.org][Write a site file for your cluster]]. +- A CI runner that runs as the build account, on a host that can start jobs on the cluster, with eb-pipeline on its =PATH=, as in [[file:install.org][Install eb-pipeline]]. +- For GitHub Actions, a self-hosted runner with a label of its own; the workflow below calls it =eb-build=. + +The site file on this page builds for two kinds of node, =zen2= and =zen4=, each with its own software tree: + +#+INCLUDE: "build-from-ci/site.toml" src toml + +** Steps + +1. List the targets that the runs go through, in the order of the site file, as lines and as the array in JavaScript Object Notation (JSON) that a CI matrix reads: + + #+begin_src bash + eb-pipeline targets --site site.toml + eb-pipeline targets --site site.toml --format json + #+end_src + + #+begin_example + zen2 + zen4 + ["zen2","zen4"] + #+end_example + + A site file that does not pass =check= makes =targets= exit 2 with nothing on stdout, so no run starts. +2. For GitHub Actions, copy =examples/ci/github-actions.yml= of the eb-pipeline repository into =.github/workflows/= of your repository, and change =eb-build= to the label of your runner: + +#+INCLUDE: "../../../examples/ci/github-actions.yml" src yaml + +3. [@3] Keep the run id of each target apart. + The workflow sets =EB_PIPELINE_RUN_ID= to =${{ github.run_id }}-${{ github.run_attempt }}-${{ matrix.target }}=: =stack shard= writes its plan into =SHARD_DIR/RUN_ID=, which has no target in it, and eb-staged-rebuild refuses a run id it already holds. + Without =--run-id=, the run id is the log stamp, which is the same for two runs that start in the same second. +4. Keep =max-parallel: 1= unless no two targets that build at once share a build directory, a download directory or, with staged rebuilds, a state root. + ={target}= in =filesystems.build_path= and in the first entry of =filesystems.source_paths= gives each target its own, as in the site file above; check what each target gets: + + #+begin_src bash + for t in $(eb-pipeline targets --site site.toml); do + eb-pipeline explain --site site.toml --target "$t" | grep -E "BUILDPATH|SOURCEPATH" + done + #+end_src + + #+begin_example + EASYBUILD_BUILDPATH = "/scratch/alice/build/zen2" + EASYBUILD_SOURCEPATH = "/scratch/alice/sources/zen2:/opt/site/sources" + EASYBUILD_BUILDPATH = "/scratch/alice/build/zen4" + EASYBUILD_SOURCEPATH = "/scratch/alice/sources/zen4:/opt/site/sources" + #+end_example + + With staged rebuilds, ={target}= in =rebuild.state_root=, or no =state_root=, gives each target a state root of its own. + Logs need nothing: each run writes under =LOG_ROOT/LOG_STAMP/TARGET=, and with =[logs.rotate]= a run rotates only when no other run under the log root is live, as [[file:../reference/log-tree.org][The log tree and its locks]] says. +5. Keep the =concurrency= of the build job. + =max-parallel= holds within one run of the workflow, and each dispatch is a run of its own. + The build job's =concurrency= group, =eb-pipeline-=, lets one dispatch at a time build a target: another dispatch's job for that target waits until the running one has finished, and =cancel-in-progress: false= leaves the running build alone. + GitHub keeps only one pending job per group, so a third dispatch replaces the waiting one, which is cancelled. + The group belongs to the repository and has no workflow name in it, so another workflow of the repository that uses the same group waits as well. + It keeps two dispatches off one target, not off one path: one dispatch can build a target while another builds a different one. + Targets that share a build directory, a download directory or a state root therefore need one group for the whole build job, =eb-pipeline= with no target in it, so that one build job of the repository runs at a time. +6. For another CI system, run the targets one after the other from a script, and keep its exit status: + +#+INCLUDE: "build-from-ci/build-all.sh" src bash + +The script exits as one run of eb-pipeline would, from what the runs of its targets came to; [[file:../reference/exit-status.org][Exit status]] gives the order. + +** Check that it worked + +Each run prints its lines as it goes, and the script the exit status of each target. +Here the script ran against a copy of the site file above with the =local= scheduler, no modules and paths under a work directory, and with a stand-in for =eb= that fails the second line of the list: + +#+begin_src bash +bash build-all.sh build.list production 1234; echo "exit $?" +#+end_src + +#+begin_example +INFO [licences] zen2: not configured +INFO [shard] zen2: not configured +INFO [sources] zen2: not configured +INFO [admission] zen2: not configured +INFO [caches] zen2: not configured +INFO [logs] zen2: not configured +INFO [build] zen2: Example-1.0-GCCcore-15.2.0: start +INFO [build] zen2: Example-1.0-GCCcore-15.2.0: ok +INFO [build] zen2: Broken-1.0-GCCcore-15.2.0: start +ERROR [build] zen2: Broken-1.0-GCCcore-15.2.0: failed (exit 1) +zen2: exit 1 +INFO [licences] zen4: not configured +... +ERROR [build] zen4: Broken-1.0-GCCcore-15.2.0: failed (exit 1) +zen4: exit 1 +exit 1 +#+end_example + +Each target leaves a result file, and the exit status of the run is its top-level =exit_code=: + +#+begin_src bash +grep -H '^ "exit_code"' result-*.json +#+end_src + +#+begin_example +result-zen2.json: "exit_code": 1, +result-zen4.json: "exit_code": 1, +#+end_example + +In GitHub Actions, each build job uploads its result file as the artifact =result-TARGET=. + +** If it fails + +| Message | Cause | What to do | +|-------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------| +| =ERROR [check] example: targets: duplicate name `zen2`=, from =targets=, and no build job | The site file does not pass =check=; =targets= exits 2 and prints no names. | Correct the site file, and run =eb-pipeline check= on it. | +| =ERROR [main] -: cannot read list missing.list: No such file or directory (os error 2)= | The list is not where the run looks for it, relative to the directory the job runs in. | Give the list relative to the top of the repository, which the workflow checks out; the script stops with exit 2. | +| No result file to upload | The run stopped on an input error before it wrote one, and exited 2 or, for the licence gate alone, 78. | Read the run's =ERROR= lines in the job log. | +| A line =refused= with =another eb-staged-rebuild holds the lock at PATH= | Two targets that share a state root rebuilt at once, and the second waited longer than =rebuild.lock_timeout=. | Give each target a state root of its own, or keep =max-parallel: 1= and one =concurrency= group for the build job. | + +The commands and their output on this page come from =docs/examples/ci.sh=. + +** Related + +- [[file:write-a-site-file.org][Write a site file for your cluster]] +- [[file:../reference/cli.org][The eb-pipeline command]], for =targets= and =run= +- [[file:../reference/site-file.org][The site file]], for ={target}= in paths +- [[file:../reference/exit-status.org][Exit status]] +- [[file:../reference/plan-and-result.org][The plan and result files]] +- [[file:../explanation/shared-paths.org][What the targets of a site file share]], for when targets can build at once diff --git a/docs/orgmode/howto/build-from-ci/build-all.sh b/docs/orgmode/howto/build-from-ci/build-all.sh new file mode 100755 index 0000000..d874f8e --- /dev/null +++ b/docs/orgmode/howto/build-from-ci/build-all.sh @@ -0,0 +1,25 @@ +#!/bin/bash +# Build one list on every target of site.toml, one target after the other. +# Usage: build-all.sh LIST BUILD_TYPE RUN_ID +# Exits as eb-pipeline does: 1 when a target failed, else 78 when one was +# refused, else 75 when one is pending, else 0; a usage error or a signal +# stops the loop with its own status. +set -u +export EB_PIPELINE_SITE=site.toml EB_PIPELINE_LIST=$1 EB_PIPELINE_BUILD_TYPE=$2 +run_id=$3 +names=$(eb-pipeline targets) || exit +worst=0 +for t in $names; do + EB_PIPELINE_TARGET=$t EB_PIPELINE_RUN_ID=$run_id-$t \ + eb-pipeline run --result "result-$t.json" + rc=$? + echo "$t: exit $rc" + case $rc in + 0) ;; + 1) worst=1 ;; + 78) [ "$worst" -eq 1 ] || worst=78 ;; + 75) [ "$worst" -ne 0 ] || worst=75 ;; + *) exit "$rc" ;; + esac +done +exit "$worst" diff --git a/docs/orgmode/howto/build-from-ci/site.toml b/docs/orgmode/howto/build-from-ci/site.toml new file mode 100644 index 0000000..62f00ff --- /dev/null +++ b/docs/orgmode/howto/build-from-ci/site.toml @@ -0,0 +1,51 @@ +# Example University: the zen2 and zen4 nodes of the cpu partition, each +# with a software tree of its own, and EasyBuild from a module. +schema_version = 1 +kind = "site" + +[site] +name = "example" +build_account = "alice" +default_group = "alice" + +[scheduler] +kind = "slurm" +launch = "srun" +job_name_template = "{project}-{build}-{phase}-{target}" + +[phase_defaults] +plan = "-p cpu -N 1 --ntasks-per-node=1 -c 1 -t 15:00" +short = "-p cpu -N 1 --ntasks-per-node=1 -c 1 -t 15:00" +build = "-p cpu -N 1 --ntasks-per-node=1 -c 16 -t 1-00:00:00" +cpu = "-p cpu -N 1 --ntasks-per-node=1 -c 16 -t 1-00:00:00" +cache = "-p cpu -N 1 --ntasks-per-node=1 -c 1 -t 15:00" + +[[targets]] +name = "zen2" +build_lists = ["zen2.list"] +site_prefix = "/opt/site/zen2" + +[targets.phases] +build = "-p cpu -C zen2 -N 1 --ntasks-per-node=1 -c 16 -t 1-00:00:00" + +[[targets]] +name = "zen4" +build_lists = ["zen4.list"] +site_prefix = "/opt/site/zen4" +default = true + +[targets.phases] +build = "-p cpu -C zen4 -N 1 --ntasks-per-node=1 -c 16 -t 1-00:00:00" + +[filesystems] +scratch = "/scratch/alice" +tmp = "/scratch/alice/tmp" +# A build directory and a download directory per target, so that the +# targets can build at once. +build_path = "/scratch/alice/build/{target}" +source_paths = ["/scratch/alice/sources/{target}", "/opt/site/sources"] +install_root = "/opt/site" +log_root = "/opt/site/logs" + +[modules] +init = ["EasyBuild"] diff --git a/docs/orgmode/howto/index.org b/docs/orgmode/howto/index.org new file mode 100644 index 0000000..e112436 --- /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 + write-a-site-file + build-from-ci + rotate-logs + staged-rebuilds + select-lines +#+end_export diff --git a/docs/orgmode/howto/install.org b/docs/orgmode/howto/install.org new file mode 100644 index 0000000..3ebfbb4 --- /dev/null +++ b/docs/orgmode/howto/install.org @@ -0,0 +1,108 @@ +#+TITLE: Install eb-pipeline +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Install eb-pipeline + +Install the =eb-pipeline= command for the account that runs the builds, from a release or from source. + +These pages describe the code on the main branch. +Release 0.3.0 is older: it has no =targets= command, no ={target}= in =[filesystems]= paths, no =rebuild.lock_timeout= and no rotation locks, and it prints the same version, =eb-pipeline 0.3.0=. +Until the next release, install from source to have them. + +** Before you start + +- For a release, a Linux host on x86_64 or aarch64. + Its binary is linked statically against musl, so it needs no other library. +- For a build from source, Rust 1.90 or newer with Cargo, and a checkout of the repository: + + #+begin_src bash + git clone https://github.com/stackhands/eb-pipeline.git + cd eb-pipeline + #+end_src + +- =~/.local/bin= on the =PATH= of the build account, or another directory there in its place below. + +** Install a release + +1. Download the archive of release 0.3.0 and its checksum, and check the archive: + + #+begin_src bash + curl -fsSLO https://github.com/stackhands/eb-pipeline/releases/download/v0.3.0/eb-pipeline-x86_64-unknown-linux-musl.tar.xz + curl -fsSLO https://github.com/stackhands/eb-pipeline/releases/download/v0.3.0/eb-pipeline-x86_64-unknown-linux-musl.tar.xz.sha256 + sha256sum -c eb-pipeline-x86_64-unknown-linux-musl.tar.xz.sha256 + #+end_src + + #+begin_example + eb-pipeline-x86_64-unknown-linux-musl.tar.xz: OK + #+end_example + + On aarch64, write =aarch64= for =x86_64= in the three names. +2. Unpack the archive: + + #+begin_src bash + tar -xJf eb-pipeline-x86_64-unknown-linux-musl.tar.xz + ls eb-pipeline-x86_64-unknown-linux-musl + #+end_src + + #+begin_example + CHANGELOG.md + LICENSE + README.md + eb-pipeline + #+end_example + +3. Install the binary: + + #+begin_src bash + install -D -m 755 eb-pipeline-x86_64-unknown-linux-musl/eb-pipeline ~/.local/bin/eb-pipeline + #+end_src + +** Install from source + +In the checkout, build and install the binary into =~/.local/bin=, with the versions of the dependencies that =Cargo.lock= names: + +#+begin_src bash +cargo install --locked --path . --root ~/.local +#+end_src + +To install another commit, check it out first; to replace an eb-pipeline that is installed there, add =--force=. + +** Check that it worked + +#+begin_src bash +command -v eb-pipeline +eb-pipeline --version +#+end_src + +#+begin_example +$HOME/.local/bin/eb-pipeline +eb-pipeline 0.3.0 +#+end_example + +A build from source also has the =targets= command: + +#+begin_src bash +eb-pipeline targets --help | head -n 1 +#+end_src + +#+begin_example +Print the target names in file order, for a CI matrix or a shell loop +#+end_example + +** If it fails + +| Message | Cause | What to do | +|--------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------+------------------------------------------------------------------| +| =eb-pipeline-x86_64-unknown-linux-musl.tar.xz: FAILED= and =sha256sum: WARNING: 1 computed checksum did NOT match= | The archive is not the one the checksum names, as after a broken download. | Download both files again, and check again. | +| =error: binary `eb-pipeline` already exists in destination=, from =cargo install= | An eb-pipeline is installed there, such as a release. | Add =--force= to replace it. | +| =feature `edition2024` is required=, from =cargo install= | Cargo is older than 1.85, which cannot read the manifests of some dependencies. | Install with Rust 1.90 or newer. | +| =error: unrecognized subcommand 'targets'= | The eb-pipeline on =PATH= is release 0.3.0, or another build older than the =targets= command. | Install from source. | +| The shell does not find =eb-pipeline= | =~/.local/bin= is not on =PATH=. | Add it to =PATH= in the shell startup file of the build account. | + +The commands and their output on this page come from =docs/examples/install.sh=. + +** Related + +- [[file:../tutorials/first-build-list.org][Run your first build list]] +- [[file:../reference/cli.org][The eb-pipeline command]] diff --git a/docs/orgmode/howto/rotate-logs.org b/docs/orgmode/howto/rotate-logs.org new file mode 100644 index 0000000..3ad287f --- /dev/null +++ b/docs/orgmode/howto/rotate-logs.org @@ -0,0 +1,110 @@ +#+TITLE: Rotate the log tree +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Rotate the log tree + +Compress and delete the old run directories under the log root with =eb-keep-logs rotate=, at the end of each run, from cron, or both, without touching the logs of a run that is still writing them. + +** Before you start + +- eb-keep-logs on the =PATH= of the build account, or named in =[site.tools.eb_keep_logs]= =bin=. + A version whose =eb-keep-logs --help= lists =--lock-timeout= takes a lock of its own; eb-keep-logs 0.2.1 takes none. +- A site file with a =[logs]= table, as in [[file:write-a-site-file.org][Write a site file for your cluster]]. +- For a rotation from cron, the crontab of the build account, and =flock= from util-linux on the host that runs it. + +The output on this page comes from =docs/examples/rotation.sh=, which runs a site file with the =local= scheduler and a stand-in for =eb-keep-logs= that prints its arguments. + +** Steps + +1. Add a =[logs.rotate]= table to the site file, with the age in days at which eb-keep-logs compresses a run directory and, if you want, the age at which it deletes one: + + #+begin_src toml + [logs.rotate] + compress_after_days = 30 + delete_after_days = 365 + #+end_src + +2. Check the rotation that a run starts at its end: + + #+begin_src bash + eb-pipeline run --site site.toml --list build.list --target cpu --build-type production --dry-run | grep '^\[logs\]' + #+end_src + + #+begin_example + INFO [run] cpu: dry run: nothing executed + [logs] TZ=UTC eb-keep-logs rotate $WORK/logs --compress-after 30 --delete-after 365 --lock-timeout 0 + #+end_example + + =TZ=UTC= makes eb-keep-logs count the age of a run from the midnight of its log stamp in Coordinated Universal Time (UTC), as the stamp is. + A run leaves out =--lock-timeout 0= when =eb-keep-logs --help= does not list it. +3. Run as before. + A run takes =LOG_ROOT/.eb-pipeline-rotate.lock= shared while it writes logs, and rotates at its end only when it can take that lock alone, so a rotation never compresses the logs of a live run; while other runs are live, the last of them to end rotates. +4. To rotate also when no run ends, as on a quiet day, have cron start =eb-keep-logs rotate= under the same lock, with =flock=: + + #+begin_example + 15 3 * * * TZ=UTC flock -w 3600 -E 75 /opt/site/logs/.eb-pipeline-rotate.lock eb-keep-logs rotate /opt/site/logs --compress-after 30 --delete-after 365 + #+end_example + + =flock= waits up to an hour for the live runs and a rotation that holds the lock to end, then holds it alone while =eb-keep-logs rotate= runs, and a run that starts meanwhile waits for it. + When the hour runs out, it exits 75 without starting =eb-keep-logs=. + Take the lock first and eb-keep-logs' own lock second, as =flock= around =eb-keep-logs rotate= does: [[file:../reference/log-tree.org][The log tree and its locks]] gives the order. + +** Check that it worked + +After a run, the =logs= phase of its result file is =ok=, and =rotate.log= in its log directory holds what eb-keep-logs printed, here the stand-in's arguments: + +#+begin_src bash +grep -B1 -A1 '"name": "logs"' result.json +cat logs/20261117_090000/cpu/rotate.log +#+end_src + +#+begin_example + "exit_code": 0, + "name": "logs", + "status": "ok" +eb-keep-logs rotate $WORK/logs --compress-after 30 --delete-after 365 --lock-timeout 0 +#+end_example + +Run the cron line once by hand, here from the parent of the log root =logs=; exit 0, after the line that the stand-in printed, means that eb-keep-logs rotated: + +#+begin_src bash +TZ=UTC flock -w 3600 -E 75 logs/.eb-pipeline-rotate.lock eb-keep-logs rotate logs --compress-after 30 --delete-after 365; echo "exit $?" +#+end_src + +#+begin_example +eb-keep-logs rotate logs --compress-after 30 --delete-after 365 +exit 0 +#+end_example + +While a run under the log root is live, the same line with a wait of one second gives up, and starts nothing: + +#+begin_src bash +TZ=UTC flock -w 1 -E 75 logs/.eb-pipeline-rotate.lock eb-keep-logs rotate logs --compress-after 30 --delete-after 365; echo "exit $?" +#+end_src + +#+begin_example +exit 75 +#+end_example + +** If it fails + +A run that does not rotate leaves its =logs= phase =skipped=, with the reason in its note, and keeps its exit status; only a rotation that fails changes it. + +| Message | Cause | What to do | +|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------| +| =INFO [logs] cpu: rotation skipped: another run under $WORK/logs holds $WORK/logs/.eb-pipeline-rotate.lock, live or rotating; the rotation is left to a run that ends alone= | Another run under the log root was live when this one ended. | Nothing: the run that ends alone rotates. On a log root that always has a live run, rotate from cron. | +| =INFO [logs] cpu: waiting: another run rotates and holds $WORK/logs/.eb-pipeline-rotate.lock= | The run started while another run, or the cron line, rotated. | Nothing: the run goes on when the rotation ends. | +| =INFO [logs] cpu: rotation skipped: eb-keep-logs rotate exited 75: another rotate holds $WORK/logs/.eb-keep-logs-rotate.lock, and this one changed nothing; the rotation is left to it= | Another =eb-keep-logs rotate= held eb-keep-logs' own lock. | Nothing: that rotate does the work. | +| =INFO [logs] cpu: no --lock-timeout for eb-keep-logs rotate: `eb-keep-logs --help` does not list it, as in eb-keep-logs 0.2.1, which takes no lock of its own= | eb-keep-logs 0.2.1, which refuses =--lock-timeout= and keeps no two rotates apart by itself. | Rotate from cron only with the =flock= line, which keeps it apart from runs and their rotations. | +| =ERROR [logs] cpu: eb-keep-logs rotate exited 1=, and the run exits 1 | =eb-keep-logs rotate= failed. | Read =rotate.log= in the run's log directory. | +| =WARN [logs] cpu: cannot lock $WORK/other/.eb-pipeline-rotate.lock: Is a directory (os error 21); the rotation does not wait for other runs= | The run cannot take its rotation lock, here because the path is a directory, and rotates without it. | Make the path a file that the build account can write, on a filesystem that supports =flock=. | +| Exit 75 from the cron line | Runs under the log root kept the lock for the hour, or another rotate held eb-keep-logs' lock. | Nothing: the tree was busy and nothing changed; the next start tries again. | + +** Related + +- [[file:../reference/log-tree.org][The log tree and its locks]] +- [[file:../explanation/log-rotation.org][Why the rotation takes two locks]] +- [[file:../reference/site-file.org][The site file]], for =[logs]= +- [[file:../reference/plan-and-result.org][The plan and result files]], for the statuses of the =logs= phase +- The [[https://stackhands.github.io/eb-keep-logs/][eb-keep-logs documentation]], for what =rotate= does to a run directory diff --git a/docs/orgmode/howto/select-lines.org b/docs/orgmode/howto/select-lines.org new file mode 100644 index 0000000..90ce417 --- /dev/null +++ b/docs/orgmode/howto/select-lines.org @@ -0,0 +1,132 @@ +#+TITLE: Build some lines of a list on some targets only +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Build some lines of a list on some targets only + +Keep one build list for every target of a site file, and mark the lines that only some targets build. + +** Before you start + +- A site file with a target for each node type, such as the one in [[file:build-from-ci.org][Build a list on every target from continuous integration]]. +- A build list that every target builds. + +The output on this page comes from =docs/examples/select.sh=. +It adds the table of step 1 to each target of the site file of [[file:build-from-ci.org][Build a list on every target from continuous integration]], with the target's own token, and runs the dry runs and the run below on a copy of that file with the =local= scheduler, its paths under =$WORK= and the stand-in =eb= of the [[file:../tutorials/first-build-list.org][tutorial]]. + +** Steps + +1. Pick a long option for the selection, such as =--only-targets=, and add a =[targets.select]= table to the table of each target, after its =[targets.phases]=, with the token of that target; for =zen4=: + + #+begin_src toml + [targets.select] + option = "--only-targets" + value = "zen4" + strip = true + #+end_src + + =strip = true= removes the option from a line before =eb= gets it, as the option is for eb-pipeline, not for EasyBuild. + A line without the option builds on every target; =when_absent = "none"= builds it on none. +2. Check the site file: + + #+begin_src bash + eb-pipeline check --site site.toml + #+end_src + + #+begin_example + INFO [check] example: site file is valid + #+end_example + +3. Give the lines for some targets only the option, with their tokens after it, such as =--only-targets=zen2,zen4= or =--only-targets zen2,zen4=: + + #+begin_src bash + cat build.list + #+end_src + + #+begin_example + Example-1.0-GCCcore-15.2.0.eb + Example-2.0-GCCcore-15.2.0.eb --only-targets=zen4 + #+end_example + +4. Check what each target builds: + + #+begin_src bash + eb-pipeline run --site site.toml --list build.list --target zen4 --build-type production --dry-run | grep "^\[build\]" + eb-pipeline run --site site.toml --list build.list --target zen2 --build-type production --dry-run | grep "^\[build\]" + #+end_src + + #+begin_example + INFO [run] zen4: dry run: nothing executed + [build] eb Example-1.0-GCCcore-15.2.0.eb + [build] eb Example-2.0-GCCcore-15.2.0.eb + INFO [run] zen2: dry run: nothing executed + [build] eb Example-1.0-GCCcore-15.2.0.eb + #+end_example + + =zen4= builds both lines and =zen2= the first, and =eb= gets no =--only-targets=. + The plan of a target lists the lines it leaves out under =deselected=: + + #+begin_src bash + eb-pipeline plan --site site.toml --list build.list --target zen2 --build-type production | grep -A5 "\"deselected\"" + #+end_src + + #+begin_example + "deselected": [ + { + "easyconfig": "Example-2.0-GCCcore-15.2.0.eb", + "unit": "all" + } + ], + #+end_example + +** Check that it worked + +A run says how many lines it left out: + +#+begin_src bash +eb-pipeline run --site site.toml --list build.list --target zen2 --build-type production --log-stamp 20261117_090000 --result result.json; echo "exit $?" +#+end_src + +#+begin_example +INFO [licences] zen2: not configured +INFO [shard] zen2: not configured +INFO [sources] zen2: not configured +INFO [admission] zen2: not configured +INFO [caches] zen2: not configured +INFO [logs] zen2: not configured +INFO [build] zen2: 1 line(s) deselected for this target +INFO [build] zen2: Example-1.0-GCCcore-15.2.0: start +INFO [build] zen2: Example-1.0-GCCcore-15.2.0: ok +exit 0 +#+end_example + +It writes the lines it keeps, with =strip= applied, to =selected-TARGET.list= in its log directory, which =stack shard= gets when the list is sharded, and its result file lists the others under =deselected=, in no status count: + +#+begin_src bash +cat $WORK/site/logs/20261117_090000/zen2/selected-zen2.list +grep -A4 "\"deselected\"" result.json +#+end_src + +#+begin_example +Example-1.0-GCCcore-15.2.0.eb + "deselected": [ + { + "easyconfig": "Example-2.0-GCCcore-15.2.0.eb", + "unit": "all" + } +#+end_example + +** If it fails + +| Message | Cause | What to do | +|---------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+------------------------------------------------------------| +| =ERROR [check] example: targets.zen2.select.option: expected a long option with its leading dashes, such as `--name`, found `only-targets`; write `--only-targets`= | The option has no leading dashes. | Write it with them, as the message says. | +| A line is under =deselected= in the plan of every target | Its option names the token of no target, as a typing error would. | Correct the token in the build list. | +| A line without the option is under =deselected= | The target sets =when_absent = "none"=. | Set =when_absent = "all"=, or name the target in the line. | +| The =[build]= line of a dry run passes the option to =eb= | The target sets no =strip = true=. | Set =strip = true=. | + +** Related + +- [[file:../reference/site-file.org][The site file]], for =[targets.select]= +- [[file:../reference/plan-and-result.org][The plan and result files]], for =deselected= +- [[file:../reference/log-tree.org][The log tree and its locks]], for =selected-TARGET.list= diff --git a/docs/orgmode/howto/staged-rebuilds.org b/docs/orgmode/howto/staged-rebuilds.org new file mode 100644 index 0000000..d7b8f7f --- /dev/null +++ b/docs/orgmode/howto/staged-rebuilds.org @@ -0,0 +1,132 @@ +#+TITLE: Rebuild installed software through eb-staged-rebuild +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Rebuild installed software through eb-staged-rebuild + +Have =eb-pipeline run= rebuild a package that is already installed through eb-staged-rebuild, which builds it in a staged tree and swaps it in, so that jobs that run the installed copy keep their paths. + +** Before you start + +- eb-staged-rebuild on the =PATH= of the build account, or named in =[site.tools.eb_staged_rebuild]= =bin=. +- A site file whose targets have an install prefix each, such as the one in [[file:build-from-ci.org][Build a list on every target from continuous integration]]. +- The package installed on the target already, with its module file under the target's =modules_root=. + +The output on this page comes from =docs/examples/staged.sh=. +It checks the site file of [[file:build-from-ci.org][Build a list on every target from continuous integration]] with the =[rebuild]= table below, then runs a copy of it with the =local= scheduler, its paths under =$WORK= and a stand-in for eb-staged-rebuild that prints its arguments. + +** Steps + +1. Add a =[rebuild]= table to the site file: + + #+begin_src toml + [rebuild] + state_root = "/opt/site/{target}/.eb-staged-rebuild" + lock_timeout = 600 + #+end_src + + Every target then takes staged rebuilds; =staged = false= in the table of a target leaves it out. + eb-staged-rebuild keeps its state, and the lock it holds for the whole of a staged build and publish, in the state root; ={target}= gives each target one of its own. + Without =state_root=, eb-staged-rebuild takes the same directory, =.eb-staged-rebuild= beside the =software= tree of each target, unless a module sets =EB_STAGED_REBUILD_STATE_ROOT=, so set it to tell eb-pipeline which lock a refused line waited for. + =lock_timeout= is how many seconds a staged line waits for that lock. +2. If eb-staged-rebuild records what it publishes in a ledger, give each target a ledger configuration of its own, with =ledger_config= in its =[[targets]]= table: eb-staged-rebuild copies the one target that the file names into every record. +3. Check the site file: + + #+begin_src bash + eb-pipeline check --site site.toml + #+end_src + + #+begin_example + INFO [check] example: site file is valid + #+end_example + +4. Mark the line in the build list of the target with =--rebuild=, =-f= or =--force=; =--force-download= and =--rebuild-from-scratch= do not count: + + #+begin_example + Example-1.0-GCCcore-15.2.0.eb --rebuild + #+end_example + +5. Check that the module of the line is installed: =MODULES_ROOT/all/NAME/VERSION.lua=, or the same path without =.lua=. + In the copy that the script runs, the =site_prefix= of =zen4= is =$WORK/site/zen4=: + + #+begin_src bash + ls $WORK/site/zen4/modules/all/Example + #+end_src + + #+begin_example + 1.0-GCCcore-15.2.0.lua + #+end_example + +6. Check the command that builds the line: + + #+begin_src bash + eb-pipeline run --site site.toml --list zen4.list --target zen4 --build-type production --run-id 1234 --dry-run | grep "^\[build\]" + #+end_src + + #+begin_example + INFO [run] zen4: dry run: nothing executed + [build] eb-staged-rebuild run --software $WORK/site/zen4/software --modules $WORK/site/zen4/modules --backend auto --run-id 1234-Example-1.0-GCCcore-15.2.0 --state-root $WORK/site/zen4/.eb-staged-rebuild --lock-timeout 600 -- Example-1.0-GCCcore-15.2.0.eb --rebuild + #+end_example + + The line passes =--run-id RUN_ID-STEM=, where =STEM= is its easyconfig without =.eb=. + eb-staged-rebuild refuses a run id it already holds, so give each run a run id of its own, or leave the default, the log stamp. +7. Run: + + #+begin_src bash + eb-pipeline run --site site.toml --list zen4.list --target zen4 --build-type production --run-id 1234 --log-stamp 20261117_090000 --result result.json; echo "exit $?" + #+end_src + + #+begin_example + INFO [licences] zen4: not configured + INFO [shard] zen4: not configured + INFO [sources] zen4: not configured + INFO [admission] zen4: not configured + INFO [caches] zen4: not configured + INFO [logs] zen4: not configured + INFO [build] zen4: Example-1.0-GCCcore-15.2.0: start + INFO [build] zen4: Example-1.0-GCCcore-15.2.0: ok + exit 0 + #+end_example + +** Check that it worked + +The line's entry in the result file has the note =ran through eb-staged-rebuild=: + +#+begin_src bash +grep -A3 '"easyconfig": "Example' result.json +#+end_src + +#+begin_example + "easyconfig": "Example-1.0-GCCcore-15.2.0.eb", + "exit_code": 0, + "log": "$WORK/site/logs/20261117_090000/zen4/Example-1.0-GCCcore-15.2.0.stdout.log", + "note": "ran through eb-staged-rebuild", +#+end_example + +The run set =--log-stamp=, so its log directory is =20261117_090000=; without it, the directory is named for the time the run started. +The log of the line holds what eb-staged-rebuild printed, here the stand-in's arguments: + +#+begin_src bash +cat $WORK/site/logs/20261117_090000/zen4/Example-1.0-GCCcore-15.2.0.stdout.log +#+end_src + +#+begin_example +eb-staged-rebuild run --software $WORK/site/zen4/software --modules $WORK/site/zen4/modules --backend auto --run-id 1234-Example-1.0-GCCcore-15.2.0 --state-root $WORK/site/zen4/.eb-staged-rebuild --lock-timeout 600 -- Example-1.0-GCCcore-15.2.0.eb --rebuild +#+end_example + +** If it fails + +| Message | Cause | What to do | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =ERROR [check] example: targets.zen4: records staged rebuilds through /opt/site/ledger.json as targets.zen2 does, under the one target that file names; set ledger_config in each target= | =ledger_config= in =[rebuild]= gives two targets one ledger configuration. | Set =ledger_config= in the table of each target. | +| =ERROR [check] example: targets.zen4: takes staged rebuilds of the live tree /opt/site/software as targets.zen2 does, and rebuild.state_root has {target}, which gives that tree two state roots and two locks; drop {target} from state_root or give each target its own software_root= | Two targets install into one software tree, and ={target}= would give it two state roots. | As the message says. | +| =WARN [build] zen2: Example-1.0-GCCcore-15.2.0: no module file $WORK/site/zen2/modules/all/Example/1.0-GCCcore-15.2.0[.lua]; the rebuild runs as plain eb= | The module of the line is not installed under the =modules_root= of the target, so =eb= builds the line. | Check the =site_prefix= or =modules_root= of the target, or let the first build install the package. | +| =ERROR [build] zen4: Example-1.0-GCCcore-15.2.0: refused (exit 2): another eb-staged-rebuild holds the lock at $WORK/site/zen4/.eb-staged-rebuild/.lock, and rebuild.lock_timeout (600 s) ran out=, and the run exits 78 | Another staged rebuild on the same state root held its lock for longer than =lock_timeout=. | Rerun once it has ended, or raise =lock_timeout=. | +| =ERROR [build] zen4: Example-1.0-GCCcore-15.2.0: pending (exit 75)=, and the run exits 75 | A record that the ledger of eb-staged-rebuild requires is pending, and the live tree is as it was. | =eb-staged-rebuild status= and =resume=, in its [[https://stackhands.github.io/eb-staged-rebuild/howto/recover.html][recovery guide]], read and continue the run =1234-Example-1.0-GCCcore-15.2.0=; a rerun of eb-pipeline starts a new one. | + +** Related + +- [[file:../reference/site-file.org][The site file]], for =[rebuild]= and the keys of =[[targets]]= +- [[file:../reference/exit-status.org][Exit status]], for how the exit statuses of eb-staged-rebuild map to those of a run +- [[file:../explanation/shared-paths.org][What the targets of a site file share]], for a state root per target +- The [[https://stackhands.github.io/eb-staged-rebuild/][eb-staged-rebuild documentation]], for what a staged rebuild does to the live tree diff --git a/docs/orgmode/howto/write-a-site-file.org b/docs/orgmode/howto/write-a-site-file.org new file mode 100644 index 0000000..54c63ca --- /dev/null +++ b/docs/orgmode/howto/write-a-site-file.org @@ -0,0 +1,162 @@ +#+TITLE: Write a site file for your cluster +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Write a site file for your cluster + +Write the site file that tells eb-pipeline how your cluster builds software: how jobs are launched, which targets it builds for, and where builds, installs and logs go. +This guide writes one for Example University, whose cluster has a Slurm partition =cpu= of AMD Zen 4 nodes and EasyBuild in a module, and builds as the account =alice=. +For a site on top of the European Environment for Scientific Software Installations (EESSI), with several node types, start from the =eessi-site= template of [[file:../reference/templates.org][The site file templates]] instead. + +** Before you start + +- eb-pipeline, as in [[file:install.org][Install eb-pipeline]]. +- The values of your cluster: the partition and limits that build jobs get, the build account and its group, the directories for installs, builds and logs, and the name of the EasyBuild module. +- A build list for each target, with one easyconfig on each line, in a directory of its own. + +** Steps + +1. Write the small-cluster template to a new site file: + + #+begin_src bash + eb-pipeline init --template small-cluster --out site.toml + #+end_src + + #+begin_example + INFO [init] -: wrote template small-cluster to site.toml + #+end_example + +2. Replace its values with your cluster's: + + | Section | What to set | + |--------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | =[site]= | The name of the site, which job names and logs carry; the account that owns the installs and their group, which the commands get as =EB_PIPELINE_BUILD_ACCOUNT= and =EB_PIPELINE_DEFAULT_GROUP=; a label for the generation of the stack. | + | =[scheduler]= | =slurm=, to launch every command with =srun=, or =local=, to run it directly. | + | =[phase_defaults]= | The launch arguments of each role: =plan=, =short=, =build=, =cpu= and =cache=. Ask for one task in each: =srun= starts the command once per task. | + | =[[targets]]= | One table per node type you build for, with its name and build lists; =default = true= marks the default target of the site. | + | =[filesystems]= | Where builds run, where EasyBuild looks for sources, where software and modules are installed, and where the logs go. | + | =[modules]= | The modules that a build loads, here only =EasyBuild=. | + | =[logs]= | Keep the EasyBuild log of a failed line, and rotate the log tree. | + + [[file:../reference/site-file.org][The site file]] lists every key of every section. + For Example University, the file becomes: + +#+INCLUDE: "write-a-site-file/site.toml" src toml + +3. [@3] Check the file, then check it with the directory of your build lists, and with the tools it names: + + #+begin_src bash + eb-pipeline check --site site.toml + eb-pipeline check --site site.toml --lists-dir lists + eb-pipeline check --site site.toml --probe-tools + #+end_src + + #+begin_example + INFO [check] example: site file is valid + INFO [check] example: site file is valid + INFO [check] example: site file is valid + #+end_example + + =--lists-dir= checks that each target's =build_lists= are files in that directory. + =--probe-tools= starts =--version= of each sibling tool that an enabled phase calls, here eb-keep-logs for =[logs]=, and compares it with the =min_version= of its =[site.tools]= table. +4. Read what the site file comes to for the target: its install roots, the environment of its commands and the launch line of each role: + + #+begin_src bash + eb-pipeline explain --site site.toml --target zen4 --build-type production + #+end_src + + #+begin_example + build_type = "production" + ... + [[targets]] + build_lists = ["zen4.list"] + default = true + modules_root = "/opt/site/modules" + name = "zen4" + site_prefix = "/opt/site" + software_root = "/opt/site/software" + + [targets.env] + EASYBUILD_BUILDPATH = "/scratch/alice/build" + EASYBUILD_INSTALLPATH = "/opt/site" + EASYBUILD_SOURCEPATH = "/opt/site/sources" + EASYBUILD_TMPDIR = "/scratch/alice/tmp" + EB_PIPELINE_BUILD_ACCOUNT = "alice" + EB_PIPELINE_BUILD_TYPE = "production" + EB_PIPELINE_DEFAULT_GROUP = "alice" + EB_PIPELINE_LOG_DIR = "/opt/site/logs//zen4" + EB_PIPELINE_LOG_STAMP = "" + EB_PIPELINE_MODULES = "EasyBuild" + EB_PIPELINE_RUN_ID = "" + EB_PIPELINE_SITE = "example" + EB_PIPELINE_TARGET = "zen4" + + [targets.phases.build] + args = "-p cpu -N 1 --ntasks-per-node=1 -c 16 -t 1-00:00:00" + launch = [ + "srun", + "--job-name=example-production-build", + ... + #+end_example + +5. To change a value for one run without editing the file, set it in a variable named =EB_PIPELINE__SECTION__KEY=, here a node-local build directory: + + #+begin_src bash + EB_PIPELINE__FILESYSTEMS__BUILD_PATH=/local/alice/build eb-pipeline explain --site site.toml --target zen4 | grep BUILDPATH + #+end_src + + #+begin_example + INFO [site] -: filesystems.build_path set from EB_PIPELINE__FILESYSTEMS__BUILD_PATH + EASYBUILD_BUILDPATH = "/local/alice/build" + #+end_example + + [[file:../reference/environment.org][Environment variables]] gives the rules for these names. + +** Check that it worked + +Ask for a dry run of a build list, which prints every command a run would start, and starts none: + +#+begin_src bash +eb-pipeline run --site site.toml --list lists/zen4.list --target zen4 --build-type production --dry-run +#+end_src + +#+begin_example +# [licences] not configured +# [shard] not configured +# [sources] not configured +# [admission] not configured +[build] srun --job-name=example-production-build -p cpu -N 1 --ntasks-per-node=1 -c 16 -t 1-00:00:00 bash -c 'if [ -n "${EB_PIPELINE_SHELL_INIT:-}" ]; then . "$EB_PIPELINE_SHELL_INIT"; fi +set -e +if [ -n "${EB_PIPELINE_UNUSE_PATH:-}" ]; then MODULEPATH=; export MODULEPATH; fi +module purge +for m in ${EB_PIPELINE_MODULES:-}; do module load "$m"; done +exec "$@"' eb-pipeline eb Example-1.0-GCCcore-15.2.0.eb --tmp-logdir=/opt/site/logs/20261117_032712/zen4/easybuild-logs/Example-1.0-GCCcore-15.2.0 +... +# [caches] not configured +[logs] TZ=UTC srun --job-name=example-production-logs -p cpu -N 1 --ntasks-per-node=1 -c 1 -t 15:00 eb-keep-logs rotate /opt/site/logs --compress-after 30 --delete-after 365 --lock-timeout 0 +INFO [run] zen4: dry run: nothing executed +#+end_example + +Each line is a command that =run= would start, after the phase it belongs to: =srun= with the launch arguments of the role, the module wrapper that loads =EasyBuild=, then =eb= with the easyconfig. + +** If it fails + +Each of these makes =check= exit 2; the problems of a site file that parses end with =ERROR [main] -: N problem(s) in the site file=. + +| Message | Cause | What to do | +|--------------------------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------+--------------------------------------------------------------------| +| =ERROR [main] -: invalid site file: TOML parse error at line 35, column 1=, then =unknown field `log_rot`, expected one of `scratch`, ...= | The section has no such key, here a misspelt =log_root=. | Correct the key; the message lists the keys of the section. | +| =ERROR [check] example: scheduler.kind: expected slurm or local, found `pbs`= | eb-pipeline launches commands with Slurm's =srun=, or runs them directly. | Set =slurm= or =local=. | +| =ERROR [check] example: logs.rotate.delete_after_days: must be greater than compress_after_days (400), found 365= | A log directory would be deleted before it is compressed. | Make =delete_after_days= the greater. | +| =ERROR [check] example: targets.zen4.build_lists: `zen4.list` not found in .= | A build list of the target is not in the =--lists-dir= directory. | Add the list, or correct its name in =build_lists=. | +| =ERROR [main] -: eb_keep_logs: cannot run `eb-keep-logs --version`: No such file or directory (os error 2)= | =--probe-tools= found no =eb-keep-logs= on =PATH=. | Install it, or name its path in =[site.tools.eb_keep_logs]= =bin=. | + +The commands and their output on this page come from =docs/examples/site-file.sh=. + +** Related + +- [[file:../reference/site-file.org][The site file]] +- [[file:../reference/templates.org][The site file templates]] +- [[file:../reference/environment.org][Environment variables]] +- [[file:../reference/cli.org][The eb-pipeline command]], for =check=, =explain= and =run --dry-run= +- [[file:../tutorials/first-build-list.org][Run your first build list]] diff --git a/docs/orgmode/howto/write-a-site-file/site.toml b/docs/orgmode/howto/write-a-site-file/site.toml new file mode 100644 index 0000000..0eb5e63 --- /dev/null +++ b/docs/orgmode/howto/write-a-site-file/site.toml @@ -0,0 +1,45 @@ +# Example University: the zen4 nodes of the cpu partition, with EasyBuild +# from a module and software under /opt/site. +schema_version = 1 +kind = "site" + +[site] +name = "example" +build_account = "alice" +default_group = "alice" +stack_generation = "2026.1" + +[scheduler] +kind = "slurm" +launch = "srun" +job_name_template = "{project}-{build}-{phase}" + +[phase_defaults] +plan = "-p cpu -N 1 --ntasks-per-node=1 -c 1 -t 15:00" +short = "-p cpu -N 1 --ntasks-per-node=1 -c 1 -t 15:00" +build = "-p cpu -N 1 --ntasks-per-node=1 -c 16 -t 1-00:00:00" +cpu = "-p cpu -N 1 --ntasks-per-node=1 -c 16 -t 1-00:00:00" +cache = "-p cpu -N 1 --ntasks-per-node=1 -c 1 -t 15:00" + +[[targets]] +name = "zen4" +build_lists = ["zen4.list"] +default = true + +[filesystems] +scratch = "/scratch/alice" +tmp = "/scratch/alice/tmp" +build_path = "/scratch/alice/build" +source_paths = ["/opt/site/sources"] +install_root = "/opt/site" +log_root = "/opt/site/logs" + +[modules] +init = ["EasyBuild"] + +[logs] +keep_failed = true + +[logs.rotate] +compress_after_days = 30 +delete_after_days = 365 diff --git a/docs/orgmode/index.org b/docs/orgmode/index.org new file mode 100644 index 0000000..72783cf --- /dev/null +++ b/docs/orgmode/index.org @@ -0,0 +1,53 @@ +#+TITLE: eb-pipeline +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* eb-pipeline + +eb-pipeline runs a site's EasyBuild build lists from one file in Tom's Obvious Minimal Language (TOML), the site file, which describes the site: its targets, the scheduler allocation of each phase, its paths, inode admission, modules, caches, log handling and licences. +From the site file, a build list and a target, it plans the commands of each phase and starts them as subprocesses: eb-stack to shard the list and admit each build, EasyBuild to fetch the sources and build, eb-keep-logs to keep a failed build's logs and rotate the log tree, and eb-staged-rebuild for a line that rebuilds a live install. +A continuous integration (CI) system, a cron job or a person on a login node then passes a list and a target, and reads an exit code and a result file. +Nothing about a site lives in eb-pipeline: the site file holds it, and the environment can set any of its values for one deployment. + +New here? +[[file:tutorials/first-build-list.org][Run your first build list]] installs eb-pipeline on one Linux machine, runs a build list against a stand-in for EasyBuild, and ends with a result file, a log for each line, and a line that fails without stopping the run. + +| 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..5bbd230 --- /dev/null +++ b/docs/orgmode/reference/api.org @@ -0,0 +1,13 @@ +#+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/eb_pipeline/index.html][eb_pipeline]]: the Rust library the =eb-pipeline= program is built on, as =cargo doc= documents it, with search and source views. + It lists every =pub= item of the crate: the site file schema, its loading and validation, the planner, the runner and the tool contracts. + +The program itself, =src/main.rs=, is not part of the library; [[file:cli.org][The eb-pipeline command]] describes it. diff --git a/docs/orgmode/reference/cli.org b/docs/orgmode/reference/cli.org new file mode 100644 index 0000000..7162d59 --- /dev/null +++ b/docs/orgmode/reference/cli.org @@ -0,0 +1,232 @@ +#+TITLE: The eb-pipeline command +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* The eb-pipeline command + +=eb-pipeline= reads a site file and a build list, and plans or runs the phases that build the list on one target of the site. +Each command has its own options; =docs/examples/cli.sh= prints every help text on this page. + +** Synopsis + +#+begin_example +eb-pipeline +eb-pipeline check [OPTIONS] --site +eb-pipeline schema +eb-pipeline init [OPTIONS] +eb-pipeline explain [OPTIONS] --site +eb-pipeline targets [OPTIONS] --site +eb-pipeline plan [OPTIONS] --site --list --target --build-type +eb-pipeline run [OPTIONS] --site --list --target --build-type +#+end_example + +=eb-pipeline --help= prints: + +#+begin_example +Site-neutral EasyBuild pipeline driver configured by a per-site TOML file + +Usage: eb-pipeline + +Commands: + check Parse and validate a site file + schema Print the site file reference: every key, type, default and meaning + init Write a starter site file from a built-in template + explain Print the resolved configuration of one or all targets + targets Print the target names in file order, for a CI matrix or a shell loop + plan Compute phases, launch lines, environments and tool calls without executing + run Execute the plan's phases as subprocesses + help Print this message or the help of the given subcommand(s) + +Options: + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version + +Examples: + eb-pipeline init --template small-cluster --out site.toml + eb-pipeline check --site site.toml + eb-pipeline targets --site site.toml --format json + eb-pipeline plan --site site.toml --list list.txt --target cpu --build-type production --out plan.json + eb-pipeline run --site site.toml --list list.txt --target cpu --build-type production --result result.json + +Configuration: every flag above falls back to an EB_PIPELINE_ variable +(EB_PIPELINE_SITE, EB_PIPELINE_LIST, EB_PIPELINE_TARGET, EB_PIPELINE_BUILD_TYPE, +EB_PIPELINE_RUN_ID, EB_PIPELINE_LOG_STAMP, EB_PIPELINE_LISTS_DIR); a flag on the +command line wins. EB_PIPELINE__SECTION__KEY=value sets one site file value, for +example EB_PIPELINE__FILESYSTEMS__SCRATCH=/scratch/eb; the result is validated +like the file. + +Output streams: stdout carries plan, explain, schema, init, targets and run --dry-run +output only. Events go to stderr as `LEVEL [phase] target: message`. The result JSON +goes to --result. + +Exit codes: + 0 all requested work completed + 1 work attempted and failed (a build line or a phase); see the result file + 2 usage error, invalid site file, or a tool below its minimum version + 75 a resource is temporarily unavailable or a step is pending; rerun + 78 refused by a precondition, by admission or by eb-staged-rebuild; lines + built before the refusal stay built, see the result file + 130 interrupted by SIGINT, after the running child ended + 143 interrupted by SIGTERM, after the running child ended + +Sibling tool codes are mapped explicitly: + eb-stack admit 0 admitted, 78 refused, 1 failed, 2 usage + eb-stack shard the code in shards.planner_exit_unsharded (default 3) means + unsharded; the run continues + eb-staged-rebuild 2 is a refusal there; the driver records it as refused + (exit 78), 75 as pending (exit 75), any other non-zero as failed + eb-keep-logs rotate 75 means another rotate holds the log root's lock; + the logs phase is recorded as skipped, any other non-zero + as failed +A signal (130, 143) or a usage error (2) ends the run with that code. Otherwise, +when several apply: 1, then 78, then 75, then 0. Codes are never summed. +#+end_example + +=eb-pipeline --version= prints the version of the crate, the same for a release and for a build from source: + +#+begin_example +eb-pipeline 0.3.0 +#+end_example + +** Arguments + +The first argument names the command. +No command takes an argument other than its options. + +| Command | What it does | +|-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =check= | Read the site file, check it against every rule of [[file:site-file.org][The site file]], and print warnings about settings that are valid but probably wrong. | +| =schema= | Print every key of the site file with its type, its default and what it does, section by section. | +| =init= | Print a built-in template site file, or write it to a new file. | +| =explain= | Print what each target resolves to: paths, launch lines and the environment of its commands. | +| =targets= | Print the names of the targets in the order of the site file. | +| =plan= | Print the plan of a run as JavaScript Object Notation (JSON): its phases and every command with its launch line and environment. It starts nothing. | +| =run= | Run the phases of the plan, one command at a time, and write the result file. | +| =help= | Print the help of the program, or of the command it names. | + +** Options + +Every command takes =-h=, which prints a summary of its options, and =--help=, which prints them in full; both exit 0. +=eb-pipeline -V= and =eb-pipeline --version= print the version. +An option takes its value as the next argument or after an equals sign, as =--site site.toml= or =--site=site.toml=. +An option with a variable in the table takes its value from that variable when the command line does not give it. + +*** check + +| Option | Variable | Meaning | +|-------------------+-------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =--site FILE= | =EB_PIPELINE_SITE= | The site file; required. | +| =--lists-dir DIR= | =EB_PIPELINE_LISTS_DIR= | A directory that must hold every file that the =build_lists= of a target names. A missing file is an error of the site file. | +| =--probe-tools= | | Start =BIN --version= for each sibling tool that an enabled phase calls, and fail when one cannot start, prints no version, or prints one below the =min_version= of its =[site.tools]= table. Without it, =check= starts nothing. | + +=check= writes =INFO [check] NAME: site file is valid= to stderr when the file is valid, where =NAME= is =site.name=. +Before that line it writes a =WARN= line for each of these settings: + +- =modules.unuse_path= with a first =modules.init= entry that is not an absolute path; +- =admission.required= without =admission.quota_cmd= and =admission.reservations=, so that =run= refuses with exit 78; +- =admission.quota_cmd= and =admission.reservations= without =admission.live_jobs_cmd=. + +*** schema + +=schema= takes no options. +It prints the reference of the site file on stdout, one block per section, with one entry per key: +the key, its type, whether it is required or its default, and what it does. + +*** init + +| Option | Meaning | +|-------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =--template NAME= | The template to print; required unless =--list= is given. | +| =--list= | Print the name and summary of each template, one per line, and nothing else. | +| =--out FILE= | Write the template to =FILE= instead of stdout, and write =INFO [init] -: wrote template NAME to FILE= to stderr. =-= is stdout. An existing =FILE= is refused, with exit 2. | + +[[file:templates.org][The site file templates]] shows each template. + +*** explain + +| Option | Variable | Meaning | +|---------------------+--------------------------+----------------------------------------------------------------------------------------------------| +| =--site FILE= | =EB_PIPELINE_SITE= | The site file; required. | +| =--target NAME= | =EB_PIPELINE_TARGET= | The target to explain; every target when absent. | +| =--build-type NAME= | =EB_PIPELINE_BUILD_TYPE= | Apply the =[targets.build_types.NAME]= table of each target to what it prints. | +| =--format FORMAT= | | =toml=, the default, prints Tom's Obvious Minimal Language (TOML); =json= prints the same as JSON. | + +For each target, =explain= prints the resolved paths, the launch line and arguments of each phase role, and the environment of its commands. +It shows == and == where a run puts its own. + +*** targets + +| Option | Variable | Meaning | +|-------------------+--------------------+-----------------------------------------------------------------------------------------------------| +| =--site FILE= | =EB_PIPELINE_SITE= | The site file; required. | +| =--format FORMAT= | | =text=, the default, prints one name per line; =json= prints a JSON array of the names on one line. | + +*** plan + +| Option | Variable | Meaning | +|---------------------+--------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =--site FILE= | =EB_PIPELINE_SITE= | The site file; required. | +| =--list FILE= | =EB_PIPELINE_LIST= | The build list; required. | +| =--target NAME= | =EB_PIPELINE_TARGET= | The target to build on; required. | +| =--build-type NAME= | =EB_PIPELINE_BUILD_TYPE= | The build type; required. A name without a =[targets.build_types.NAME]= table takes the values of the target. | +| =--run-id ID= | =EB_PIPELINE_RUN_ID= | The run label passed to the tools; == when absent. | +| =--log-stamp STAMP= | =EB_PIPELINE_LOG_STAMP= | The name of the run's directory under the log root, a Coordinated Universal Time (UTC) as =YYYYMMDD_HHMMSS=; == when absent. Any other value is refused, with exit 2. | +| =--out FILE= | | Write the plan to =FILE= instead of stdout; =-= is stdout. | +| =--shard-plan DIR= | | Read =DIR/plan.json=, written by =eb-stack stack shard=, and plan its units and their lines instead of the list as one unit. | + +*** run + +=run= takes the first six options of =plan=, and these: + +| Option | Meaning | +|-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =--result FILE= | Write the result file to =FILE= when the run ends. Without it, no result file is written. An error in the input, which stops the run before it starts, leaves an existing =FILE= as it was. | +| =--dry-run= | Print each command of the plan on stdout and start nothing. No result file is written, even with =--result=. | + +=--run-id= defaults to the log stamp, and =--log-stamp= to the UTC time at which the run starts, taken once. +A line that =eb-staged-rebuild= builds passes =RUN_ID-STEM= as its run id, where =STEM= is the easyconfig file name without =.eb=, with =.2=, =.3= and so on added when the list repeats the line. + +With =--dry-run=, a planned command prints as =[PHASE] COMMAND= and a phase that starts nothing as =# [PHASE] STATUS=. + +** Environment + +Each option in the tables above that names a variable reads it when the option is not on the command line. +=EB_PIPELINE__SECTION__KEY=VALUE= sets one value of the site file, and a run sets variables of its own for the commands it starts. +[[file:environment.org][Environment variables]] lists all of them. + +** Exit status + +| Status | Meaning | +|--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 0 | All requested work completed. | +| 1 | =run=: a line or a phase failed. =plan=: the shard plan could not be read. Any command: an output file could not be written. | +| 2 | A usage error, an invalid site file, an unknown target, a list that cannot be read, is empty or has a quote that is not closed, a tool below its =min_version=, or an =init --out= file that cannot be created. | +| 75 | =run=: a resource was busy or a step is pending; run it again. | +| 78 | =run=: a precondition, admission or =eb-staged-rebuild= refused. | +| 130 | =run=: interrupted by =SIGINT=. | +| 143 | =run=: interrupted by =SIGTERM=. | + +The commands other than =run= exit 0, 1 or 2. +[[file:exit-status.org][Exit status]] has the cases behind each status, how =run= picks one when several apply, and how it reads the exit statuses of the tools it starts. + +** Files + +| File | Use | +|---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| the site file, =--site= | Everything about the site; [[file:site-file.org][The site file]] lists its keys. | +| the build list, =--list= | One easyconfig per line, followed by the options =eb= gets for it, as =Name-version-toolchain.eb [eb options]=. Blank lines and lines that start with =#= are skipped. | +| the plan, =plan --out= | What =plan= prints; [[file:plan-and-result.org][The plan and result files]] lists its keys. | +| the result file, =run --result= | What the run did, line by line and phase by phase; [[file:plan-and-result.org][The plan and result files]] lists its keys. | +| =LOG_ROOT/LOG_STAMP/TARGET/= | The log directory of a run, under =filesystems.log_root=; [[file:log-tree.org][The log tree and its locks]] lists its files. | + +A list line is split into words as a shell splits them, with single and double quotes. + +** See also + +- [[file:../tutorials/first-build-list.org][Run your first build list]] +- [[file:site-file.org][The site file]] and [[file:plan-and-result.org][The plan and result files]] +- [[file:environment.org][Environment variables]] and [[file:exit-status.org][Exit status]] +- The [[file:api.org][API]] of the =eb_pipeline= library, which the command is built on. diff --git a/docs/orgmode/reference/environment.org b/docs/orgmode/reference/environment.org new file mode 100644 index 0000000..2b00fda --- /dev/null +++ b/docs/orgmode/reference/environment.org @@ -0,0 +1,129 @@ +#+TITLE: Environment variables +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Environment variables + +The variables =eb-pipeline= reads in place of an option or a site file value, the ones a run reads because the site file names them, and the ones it sets for the commands it starts. + +** Options + +An option that is not on the command line takes its value from its variable. +An option on the command line wins. + +| Variable | Option | Commands | +|--------------------------+----------------+----------------------------------------------| +| =EB_PIPELINE_SITE= | =--site= | =check=, =explain=, =targets=, =plan=, =run= | +| =EB_PIPELINE_LIST= | =--list= | =plan=, =run= | +| =EB_PIPELINE_TARGET= | =--target= | =explain=, =plan=, =run= | +| =EB_PIPELINE_BUILD_TYPE= | =--build-type= | =explain=, =plan=, =run= | +| =EB_PIPELINE_RUN_ID= | =--run-id= | =plan=, =run= | +| =EB_PIPELINE_LOG_STAMP= | =--log-stamp= | =plan=, =run= | +| =EB_PIPELINE_LISTS_DIR= | =--lists-dir= | =check= | + +=--out=, =--result=, =--shard-plan=, =--format=, =--dry-run= and =--probe-tools= have no variable. + +** Site file values + +=EB_PIPELINE__SECTION__KEY=VALUE= sets one value of the site file, after the file is read and before it is checked. +Every command that reads a site file applies these variables. + +- The name after =EB_PIPELINE__= is split at each =__=, and each part, lowercased, names a table or, last, the key. + =EB_PIPELINE__FILESYSTEMS__SCRATCH= sets =scratch= in =[filesystems]=, and =EB_PIPELINE__LOGS__ROTATE__DELETE_AFTER_DAYS= sets =delete_after_days= in =[logs.rotate]=. +- A part must hold letters, digits and underscores only, and none may be empty. +- =VALUE= is read as a TOML value, such as =true=, =16=, ="16"= or =["a", "b"]=, and as a string when it is not one. + =/scratch/alice= is the string ="/scratch/alice"=. +- A table on the path that the file does not have is made. +- A path that reaches into an array of tables, such as =targets=, is refused: the values of a target stay in the file. + So is a path that ends at a table, or that passes through a value that is not a table. +- The variables apply in the order of their names, whatever the order of the environment. +- Each one writes =INFO [site] -: KEY set from NAME= to stderr, with the key and never the value. + +The result is checked like the file itself, so an unknown key or a value of the wrong type exits 2 with =invalid site file after environment overrides:= and the reason. +Since every part is lowercased, these variables cannot set a key that has an upper-case letter, such as a package name under =[modules.package_env]=. + +** Read during a run + +The site file names these variables; =run= reads them before the first build. +=plan= and =run --dry-run= show =${NAME}= in their place. + +| Variable | Use | +|--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| the one named by =admission.job_id_env=, =SLURM_JOB_ID= by default | The job id that =eb-stack stack admit= reserves for. With admission on, =run= refuses with exit 78 before any build when it is unset or not a positive integer without a leading zero. | +| the one named by =targets.route.receipt_digest_env= | A digest that the routed commands get as =EB_PIPELINE_ROUTE_RECEIPT_DIGEST=. =run= refuses with exit 78 when it is unset or empty. | +| each one named in =shards.installed_modules_dirs_from_env= | Module trees, separated by =:=, added to =shards.installed_modules_dirs=. =run= refuses with exit 78 when one is unset; an empty one adds nothing. | + +** Set for the commands of a run + +A command that =run= starts inherits the environment of =eb-pipeline=, with the variables below set over it. +The keys of =[scheduler.env]= come first, and a variable of the table below with the same name replaces one of them. + +| Variable | Value | Set when | +|-----------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------+------------------------------------------------------| +| the keys of =[scheduler.env]= | their values | always | +| =EASYBUILD_TMPDIR= | =filesystems.tmp= | always | +| =EASYBUILD_BUILDPATH= | =filesystems.build_path=, with ={target}= replaced by the target's name | always | +| =EASYBUILD_SOURCEPATH= | the entries of =filesystems.source_paths=, with ={target}= replaced, joined with =:= | =source_paths= is not empty | +| =EASYBUILD_INSTALLPATH= | the target's =site_prefix=, else =filesystems.install_root= | =filesystems.export_install_vars= is =single= | +| =EASYBUILD_INSTALLPATH_SOFTWARE= | the target's =software_root= | =filesystems.export_install_vars= is =split= | +| =EASYBUILD_INSTALLPATH_MODULES= | the target's =modules_root= | =filesystems.export_install_vars= is =split= | +| =EASYBUILD_OPTARCH= | =eb_optarch= of the build type, else of the target | one of them is set | +| =EASYBUILD_MAX_PARALLEL= | =max_parallel= of the build type, else of the target | one of them is set | +| =EASYBUILD_CUDA_COMPUTE_CAPABILITIES= | the target's =cuda_compute_capabilities= | it is set | +| =EASYBUILD_READ_ONLY_INSTALLDIR= | =filesystems.read_only_installdir_value=, =1= by default | =filesystems.read_only_installdir= is =true= | +| =EASYBUILD_CONFIGS_REPOPATH= | =filesystems.configs_repo= | it is set | +| =EB_PIPELINE_SITE= | =site.name= | always | +| =EB_PIPELINE_TARGET= | the target's name | always | +| =EB_PIPELINE_BUILD_TYPE= | the build type | always | +| =EB_PIPELINE_RUN_ID= | the run id | always | +| =EB_PIPELINE_LOG_STAMP= | the log stamp | always | +| =EB_PIPELINE_LOG_DIR= | =LOG_ROOT/LOG_STAMP/TARGET=, the run's log directory | always | +| =EB_PIPELINE_BUILD_ACCOUNT= | =site.build_account= | it is set | +| =EB_PIPELINE_DEFAULT_GROUP= | =site.default_group= | it is set | +| =EB_PIPELINE_MODULES= | the entries of =modules.init=, joined with spaces | =modules.init= is not empty | +| =EB_PIPELINE_UNUSE_PATH= | =1= | =modules.unuse_path= is =true= | +| =EB_PIPELINE_SHELL_INIT= | =modules.shell_init= | it is set | +| =EESSI_SITE_INSTALL= | =1= | =[modules.eessi]= is on and =site_install= is =true= | +| =EESSI_SITE_BOOTSTRAP_MODULEPATH= | =modules.eessi.bootstrap_modulepath= | =[modules.eessi]= is on and it is set | +| the one named by =modules.eessi.cpu_override_var=, =EESSI_SOFTWARE_SUBDIR_OVERRIDE= by default | the target's =cpu_target= | =[modules.eessi]= is on and =cpu_target= is set | +| the one named by =modules.eessi.accel_override_var=, =EESSI_ACCELERATOR_TARGET_OVERRIDE= by default | the target's =accel_target= | =[modules.eessi]= is on and =accel_target= is set | +| =EESSI_SITE_SOFTWARE_PREFIX= | the target's =site_prefix=, else =filesystems.install_root= | =[modules.eessi]= is on | + +=[modules.eessi]= is on when the site file has the table and its =enabled= is not =false=. +=[licences]= is on when its =enabled= and =enforce= are not =false=. +=EESSI= stands for the European Environment for Scientific Software Installations. + +*** Set for some commands + +Some commands get more variables, set over those above. + +| Variable | Value | Commands | +|---------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------+---------------------------------------------------------------------------------| +| the keys of =[modules.package_env.NAME]=, then of the target's =[targets.package_env.NAME]= | their values; per key, the target's wins | the prefetch and build commands of a line whose easyconfig is of package =NAME= | +| the keys of =[licences.env.NAME]= | their values | the same, with =[licences]= on | +| =EB_PIPELINE_LICENCE_GROUP= | the group of =[licences.groups]= that applies to the package and version | the same, with =[licences]= on | +| =EB_PIPELINE_FETCH_PROFILE= | the target's =fetch_profile= as JSON, with sorted keys | the prefetch commands, when the target has a =fetch_profile= | +| =EB_PIPELINE_HW_VENDOR_ID=, =EB_PIPELINE_HW_CPU_FAMILY=, =EB_PIPELINE_HW_MODEL= | the =vendor_id=, =cpu_family= and =model= of the target's =cpu_hardware= for a CPU-role unit, of its =hardware= otherwise | the prefetch and build commands, when the target has a =cpu_hardware= table | +| the keys of =targets.route.env= | their values, with the placeholders of the route replaced | the commands that the route wraps | +| =EB_PIPELINE_ROUTE_RUNTIME_ROOT= | =targets.route.runtime_root= | the same, when it is set | +| =EB_PIPELINE_ROUTE_SHARES_RO=, =EB_PIPELINE_ROUTE_SHARES_RW= | the entries of =targets.route.shares_ro= and =shares_rw=, joined with =:= | the same, when they are not empty | +| =EB_PIPELINE_ROUTE_RECEIPT_DIGEST= | the value of the variable that =targets.route.receipt_digest_env= names | the same, when it is set | +| =EASYBUILD_OUTPUT_STYLE= | =basic=, whatever =[scheduler.env]= sets, so that =eb --last-log= prints the log path on one line | =eb-keep-logs failed=, after a line fails | +| =TZ= | =UTC=, so that =eb-keep-logs rotate= counts the age of a run from the midnight of its log stamp | =eb-keep-logs rotate= | +| =EB_PIPELINE_CACHE_CONFIG= | the =config= of the target's entry in =[[caches.targets]]= | =[caches].command= | +| =EB_PIPELINE_CACHE_BINDINGS= | =caches.bindings= | the same, when it is set | +| =EB_PIPELINE_CACHE_INIT_MODULE= | the =init_module= of the target's entry, else =caches.init_module= | the same, when one of them is set | + +*** The module wrapper + +When =modules.init= is not empty, =modules.unuse_path= is =true= or =modules.shell_init= is set, the shard, prefetch, build, keep-failed and cache commands start through =modules.shell=, which reads three of the variables above: + +1. =EB_PIPELINE_SHELL_INIT=: the file it sources first, when set. +2. =EB_PIPELINE_UNUSE_PATH=: when set, it empties =MODULEPATH=. +3. =EB_PIPELINE_MODULES=: it runs =module purge=, then =module load= for each name in it, in order, then the command. + +The admit and rotate commands start without it. + +** See also + +- [[file:cli.org][The eb-pipeline command]] and [[file:site-file.org][The site file]] diff --git a/docs/orgmode/reference/exit-status.org b/docs/orgmode/reference/exit-status.org new file mode 100644 index 0000000..48f2fc2 --- /dev/null +++ b/docs/orgmode/reference/exit-status.org @@ -0,0 +1,121 @@ +#+TITLE: Exit status +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Exit status + +The exit statuses of =eb-pipeline=, what leads to each, how =run= picks one when several apply, and how it reads the exit statuses of the tools it starts. +The constants are in [[file:../api/eb_pipeline/exit/index.html][eb_pipeline::exit]]. + +** Statuses + +| Status | Constant | Meaning | +|--------+------------+------------------------------------------------------------------------------------------------------| +| 0 | =OK= | All requested work completed. | +| 1 | =FAILED= | Work was attempted and failed: a line or a phase. The result file says which. | +| 2 | =USAGE= | A usage error, an invalid site file, or a tool below its minimum version. Nothing was built. | +| 75 | =TEMPFAIL= | A resource is temporarily unavailable or a step is pending; run again later. | +| 78 | =REFUSED= | A precondition, admission or =eb-staged-rebuild= refused. Lines built before the refusal stay built. | +| 130 | =SIGINT= | Interrupted by =SIGINT=, after the running command ended. | +| 143 | =SIGTERM= | Interrupted by =SIGTERM=, after the running command ended. | + +The exit status is never a sum or a count; the result file holds the count of lines per status. +An error that ends a command is written to stderr as =ERROR [main] -: MESSAGE=. + +** What leads to each status + +*** 0 + +- =check=, =schema=, =init=, =explain=, =targets= and =plan= did what they were asked. +- =run --dry-run= printed its commands. +- =run=: no line failed, was refused or is pending, and no phase failed. + A deselected line, a phase that is not configured, an =unsharded= shard phase and a =logs= phase that another rotation made =skipped= all leave the status at 0. + +*** 1 + +- =run=: the =eb= or =eb-staged-rebuild run= command of a line exited with a status that is not 0 and does not mean refused or pending; the line is =failed=. +- =run=: the source prefetch of a line failed; the line is =failed= and is not built. +- =run=: =eb-stack stack shard= exited with a status other than 0, 2 and =shards.planner_exit_unsharded=, or its plan could not be read; the run ends. +- =run=: =eb-stack stack admit= exited with a status other than 0, 2 and 78; the run ends. +- =run=: =[caches].command= exited with a status other than 0. +- =run=: =eb-keep-logs rotate= exited with a status other than 0 and 75. +- =run=: a log file, a log directory, the list of selected lines or the result file could not be written. +- =plan=: the shard plan given to =--shard-plan= could not be read, or the plan could not be written to =--out=. + +A failed =eb-keep-logs failed= after a failed line leaves the status as it is, with a =WARN= line. + +*** 2 + +- The command line has an unknown option, lacks a required one, or gives a value that is not allowed, such as a =--log-stamp= that is not a date and time in Coordinated Universal Time (UTC). +- The site file cannot be read, is not valid, or is not valid after the =EB_PIPELINE__= variables are applied. +- The target is not one of the site file's. +- The list cannot be read, holds no line, or has a quote that is not closed. +- =run=, and =check --probe-tools=: a tool that needs a =min_version= cannot be started, prints no version, or prints one below the minimum. + =check --probe-tools= also checks the tools without a =min_version=. +- =init=: the template is unknown, or the =--out= file cannot be created, as when it exists. +- =run=: =eb-stack stack shard= or =eb-stack stack admit= exited 2. + +*** 75 + +- =run=: =eb-staged-rebuild run= exited 75 for a line; the line is =pending=. + +*** 78 + +- =run=: every problem the site file has is in =[licences]=. +- =run=: =admission.required= is =true= but =admission.quota_cmd= or =admission.reservations= is missing. +- =run=: =admission.quota_cmd= and =admission.reservations= are set, and the variable that =admission.job_id_env= names is unset or not a positive integer without a leading zero. +- =run=: a variable that =shards.installed_modules_dirs_from_env= names is unset. +- =run=: a unit has CPU-role commands that the target's route wraps, and the variable =targets.route.receipt_digest_env= names is unset or empty. +- =run=: =eb-stack stack admit= still refused after =admission.attempts= attempts. + The lines of that unit are =skipped=, with the note =admission refused=, and those of every later unit with =an earlier unit was refused=. +- =run=: =eb-staged-rebuild run= exited 2 for a line, such as when the lock of its state root was still held after =[rebuild] lock_timeout= seconds; the line is =refused=. + +The refusals before the first build leave every line unbuilt. + +*** 130 and 143 + +=run= passes the signal to the running command and waits for it to end. +It starts no other command, records the phase as =interrupted=, writes the result file and exits 130 for =SIGINT= or 143 for =SIGTERM=. + +** When several apply + +A signal ends a run with 130 or 143, and a usage error with 2, whatever else happened before. +Otherwise the first of these that applies is the status of the run: + +1. a line or a phase failed: 1; +2. a line or admission was refused: 78; +3. a line is pending: 75; +4. none of these: 0. + +A run in which one line failed and another was refused exits 1. + +** Exit statuses of the tools a run starts + +| Command | Status | What the run does | +|-------------------------------+-----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =eb= | 0 | The line is =success=. | +| =eb= | any other | The line is =failed=. | +| =eb-stack stack shard= | 0 | The run builds the units of the shard plan. | +| =eb-stack stack shard= | =shards.planner_exit_unsharded=, 3 by default | The planner built the plan unsharded; the shard phase is =unsharded= and the list builds as one unit. | +| =eb-stack stack shard= | 2 | The shard phase is =failed=, and the run ends with 2. | +| =eb-stack stack shard= | any other | The shard phase is =failed=, and the run ends with 1. | +| =eb-stack stack admit= | 0 | The unit is admitted and builds. | +| =eb-stack stack admit= | 78 | Refused: the run waits and asks again, as =[admission]= sets, and after the last attempt the admission phase is =refused=. | +| =eb-stack stack admit= | 2 | The admission phase is =failed=, and the run ends with 2. | +| =eb-stack stack admit= | any other | The admission phase is =failed=, and the run ends with 1. | +| =eb-staged-rebuild run= | 0 | The line is =success=. | +| =eb-staged-rebuild run= | 2 | A refusal: the line is =refused=, with =translated_from= 2 and =exit_code= 78. | +| =eb-staged-rebuild run= | 75 | The line is =pending=. | +| =eb-staged-rebuild run= | any other | The line is =failed=. | +| =eb-keep-logs rotate= | 0 | The =logs= phase is =ok=. | +| =eb-keep-logs rotate= | 75 | Another rotation holds =LOG_ROOT/.eb-keep-logs-rotate.lock= and this one changed nothing; the =logs= phase is =skipped=, and the status of the run does not change. | +| =eb-keep-logs rotate= | any other | The =logs= phase is =failed=. | +| =eb-keep-logs failed= | any other than 0 | A =WARN= line; nothing else changes. | +| =[caches].command= | any other than 0 | The =caches= phase is =failed=. | +| any command that cannot start | 127 | Recorded as the command's status; its log says why it could not start. | + +** See also + +- [[file:cli.org][The eb-pipeline command]] and [[file:site-file.org][The site file]] +- [[file:plan-and-result.org][The plan and result files]], for the status of each line and phase in the result file +- [[file:../explanation/phases.org][How a run goes through its phases]], for the order of the statuses diff --git a/docs/orgmode/reference/index.org b/docs/orgmode/reference/index.org new file mode 100644 index 0000000..6ccee3b --- /dev/null +++ b/docs/orgmode/reference/index.org @@ -0,0 +1,22 @@ +#+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 + site-file + plan-and-result + log-tree + templates + environment + exit-status + api +#+end_export diff --git a/docs/orgmode/reference/log-tree.org b/docs/orgmode/reference/log-tree.org new file mode 100644 index 0000000..733a1a7 --- /dev/null +++ b/docs/orgmode/reference/log-tree.org @@ -0,0 +1,89 @@ +#+TITLE: The log tree and its locks +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* The log tree and its locks + +A run writes its logs under =filesystems.log_root=, =LOG_ROOT= on this page, in a directory of its own for each target. +It takes locks in the log root, and in the state root of eb-staged-rebuild and the admission lock when the site file uses them. + +** The log directory + +=LOG_DIR= is =LOG_ROOT/LOG_STAMP/TARGET=, and every command of a run gets it as =EB_PIPELINE_LOG_DIR=. +=LOG_STAMP= is =--log-stamp= or =EB_PIPELINE_LOG_STAMP=, else the time =run= starts in Coordinated Universal Time (UTC), as =YYYYMMDD_HHMMSS=. +=plan= without a stamp, and =explain=, show == in its place. +Two runs with the same stamp and target write into the same directory; the runs of one pipeline can share a stamp when each takes a different target. + +After the run in =docs/examples/files.sh=, which builds one line and fails another with =[logs] keep_failed= and =[logs.rotate]= set, the log root holds: + +#+begin_src bash +find logs | sort +#+end_src + +#+begin_example +logs +logs/.eb-pipeline-rotate.lock +logs/20261117_090000 +logs/20261117_090000/cpu +logs/20261117_090000/cpu/Broken-1.0-GCCcore-15.2.0.keep-logs.log +logs/20261117_090000/cpu/Broken-1.0-GCCcore-15.2.0.stdout.log +logs/20261117_090000/cpu/Example-1.0-GCCcore-15.2.0.stdout.log +logs/20261117_090000/cpu/rotate.log +#+end_example + +| File | Phase | What it holds | +|--------------------------------+----------------+------------------------------------------------------------------------------------------------------------| +| =LOG_DIR/selected-TARGET.list= | before =shard= | The lines that =[targets.select]= keeps, which =stack shard= reads. | +| =LOG_DIR/shard.log= | =shard= | The output of =stack shard=. | +| =LOG_DIR/STEM.fetch.log= | =sources= | The output of the prefetch of the line's sources. | +| =LOG_DIR/admission-UNIT.N.log= | =admission= | The output of attempt =N= of =stack admit= for the unit, counting from 1. | +| =LOG_DIR/STEM.stdout.log= | =build= | The output of the line's =eb= or =eb-staged-rebuild run=; the =log= of the line in the result file. | +| =LOG_DIR/easybuild-logs/STEM/= | =build= | The logs of EasyBuild itself, which =eb= writes there with =--tmp-logdir= when =[logs] keep_failed= is on. | +| =LOG_DIR/STEM.keep-logs.log= | =build= | The output of =eb-keep-logs failed= after the line failed. | +| =LOG_DIR/caches.log= | =caches= | The output of the cache command. | +| =LOG_DIR/rotate.log= | =logs= | The output of =eb-keep-logs rotate=. | +| =LOG_DIR/PHASE/= | routed | The directory ={phase_dir}= names, made before a command whose route arguments or shares use it. | + +=STEM= is the easyconfig file name without =.eb=, with =.2=, =.3= and so on added when the list repeats a line, and =UNIT= is =all=, =cpu-prerequisites=, =prelude= or the name of a shard. +Each log holds the standard output and the standard error of its command, which starts with no standard input, and =run= creates it anew when the command starts. +A command that cannot start leaves one line in its log, =cannot start PROGRAM: ERROR=, and counts as exit 127. + +** The log root + +| File | What it is | +|--------------------------------------+---------------------------------------------------------------------------------------------------------| +| =LOG_ROOT/LOG_STAMP/= | The directories of the runs with that stamp, one per target. | +| =LOG_ROOT/.eb-pipeline-rotate.lock= | The rotation lock of eb-pipeline; the first run with =[logs.rotate]= creates it. | +| =LOG_ROOT/.eb-keep-logs-rotate.lock= | The rotation lock of eb-keep-logs, which an =eb-keep-logs rotate= that takes a lock of its own creates. | + +=eb-keep-logs rotate= compresses and deletes the run directories by the age of their stamp, and keeps files of its own in the tree; the [[https://stackhands.github.io/eb-keep-logs/][eb-keep-logs documentation]] describes them. + +** Locks + +| Lock | Taken by | How | While another holder has it | +|--------------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =LOG_ROOT/.eb-pipeline-rotate.lock= | =run= with =[logs.rotate]=, and a rotation outside a run that takes it with =flock(1)= | =flock=: shared from the end of =preflight= to the end of the run, then alone for the rotation, without waiting | A run that starts waits while another holds it alone, as a rotation does. A run that cannot take it alone at its end leaves =logs= =skipped=. | +| =LOG_ROOT/.eb-keep-logs-rotate.lock= | =eb-keep-logs rotate=, where its =--help= lists =--lock-timeout=; eb-keep-logs 0.2.1 takes no lock | =flock=, alone, from before it lists the log root until it exits | It waits up to =--lock-timeout= seconds, 600 unless given, then exits 75 having changed nothing. =run= passes =--lock-timeout 0=, and records exit 75 as =logs= =skipped=. | +| =STATE_ROOT/.lock= | =eb-staged-rebuild run=, for a staged line | Alone, for the whole of its build and publish | It waits up to =rebuild.lock_timeout= seconds, then exits 2, and the line is =refused=. | +| =admission.lock= | =stack admit=, and =run= when it removes the reservation of an admitted job | =flock=, or a POSIX record lock over the whole file, as =admission.lock_kind= says | =run= waits for it. | + +=STATE_ROOT= is =rebuild.state_root=, else the =EB_STAGED_REBUILD_STATE_ROOT= that eb-staged-rebuild sees, else =.eb-staged-rebuild= beside the software tree. +=flock= locks hold between nodes only where the filesystem carries them between nodes. +When a run cannot take its rotation lock at all, it logs =WARN [logs] TARGET: cannot lock PATH: ERROR; the rotation does not wait for other runs= and rotates without it. + +*** Lock order + +Whatever takes both rotation locks takes them in this order: + +1. =LOG_ROOT/.eb-pipeline-rotate.lock= +2. =LOG_ROOT/.eb-keep-logs-rotate.lock= + +A run's rotation does, and so does a rotation outside a run that takes the first with =flock(1)=; eb-keep-logs takes only the second. +A run waits for the first lock only at its start, before it holds any other, and at its end takes it alone only when it can do so at once. + +** See also + +- [[file:site-file.org][The site file]], for =[logs]=, =[rebuild]= and =[admission]= +- [[file:plan-and-result.org][The plan and result files]], for the statuses of the =logs= phase and of a line +- [[file:exit-status.org][Exit status]] +- [[file:../explanation/log-rotation.org][Why the rotation takes two locks]], for why the locks are taken as they are diff --git a/docs/orgmode/reference/plan-and-result.org b/docs/orgmode/reference/plan-and-result.org new file mode 100644 index 0000000..50ce42c --- /dev/null +++ b/docs/orgmode/reference/plan-and-result.org @@ -0,0 +1,314 @@ +#+TITLE: The plan and result files +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* The plan and result files + +=eb-pipeline plan= writes the plan of a run, and =eb-pipeline run --result FILE= the result of one. +Both are objects in JavaScript Object Notation (JSON), with the keys of every object in sorted order, and both have =schema_version= 1. +The examples on this page come from =docs/examples/files.sh=, which plans and runs a two-line list on a site with the =local= scheduler, kept logs and rotation, with stand-ins for =eb= and =eb-keep-logs= that print their arguments. + +** The plan file + +=plan --out FILE= writes the plan to =FILE=, and =plan= without =--out= prints it. +A plan holds every phase, planned or not, in the order a run goes through them, and every command a run would start, with its whole argument vector and environment. + +#+begin_src bash +eb-pipeline plan --site site.toml --list build.list --target cpu --build-type production \ + --run-id nightly --log-stamp 20261117_090000 --out plan.json +cat plan.json +#+end_src + +#+begin_example +{ + "build_type": "production", + "kind": "plan", + "lines": 2, + "list": "build.list", + "log_dir": "$WORK/logs/20261117_090000/cpu", + "phases": [ + { + "commands": [], + "env": {}, + "name": "preflight", + "status": "planned" + }, + { + "commands": [], + "env": {}, + "name": "licences", + "reason": "not configured", + "status": "not configured" + }, +... + { + "commands": [ + { + "argv": [ + "eb", + "Example-1.0-GCCcore-15.2.0.eb", + "--tmp-logdir=$WORK/logs/20261117_090000/cpu/easybuild-logs/Example-1.0-GCCcore-15.2.0" + ], + "name": "build:Example-1.0-GCCcore-15.2.0" + }, + { + "argv": [ + "eb-keep-logs", + "failed", + "", + "Example-1.0-GCCcore-15.2.0", + "$WORK/logs/20261117_090000/cpu", + "$WORK/logs/20261117_090000/cpu/easybuild-logs/Example-1.0-GCCcore-15.2.0" + ], + "env": { + "EASYBUILD_OUTPUT_STYLE": "basic" + }, + "name": "keep-failed:Example-1.0-GCCcore-15.2.0", + "note": "runs after a failed line" + }, +... + ], + "env": { + "EASYBUILD_BUILDPATH": "$WORK/scratch/build", + "EASYBUILD_INSTALLPATH": "$WORK/software", + "EASYBUILD_TMPDIR": "$WORK/scratch/tmp", + "EB_PIPELINE_BUILD_TYPE": "production", + "EB_PIPELINE_LOG_DIR": "$WORK/logs/20261117_090000/cpu", + "EB_PIPELINE_LOG_STAMP": "20261117_090000", + "EB_PIPELINE_RUN_ID": "nightly", + "EB_PIPELINE_SITE": "example", + "EB_PIPELINE_TARGET": "cpu" + }, + "name": "build", + "role": "build", + "status": "planned" + }, +... + ], + "run_id": "nightly", + "schema_version": 1, + "site": "example", + "target": "cpu" +} +#+end_example + +| Key | Type | Meaning | +|------------------+---------+--------------------------------------------------------------------------------------------------------------------------| +| =build_type= | string | The build type. | +| =deselected= | array | The lines that the target's =[targets.select]= leaves out; only when there are some. | +| =kind= | string | =plan=. | +| =lines= | integer | The number of lines of the list, without blank lines and comments. | +| =list= | string | The build list, as =--list= names it. | +| =log_dir= | string | =LOG_ROOT/LOG_STAMP/TARGET=, where the run writes its logs. | +| =phases= | array | Every phase, in the order a run goes through them. | +| =run_id= | string | The run id, == without =--run-id=. | +| =schema_version= | integer | =1=. | +| =selected= | integer | The number of lines that =[targets.select]= keeps; only with that table. | +| =selected_list= | string | =LOG_DIR/selected-TARGET.list=, the file a run writes the kept lines to for =stack shard=; only with =[targets.select]=. | +| =site= | string | =site.name=. | +| =target= | string | The name of the target. | + +Where a run reads a value when it starts, the plan shows a stand-in: == and == without =--run-id= and =--log-stamp=, =${NAME}= for a variable that the site file names, and == for the status of the line that failed. + +*** Each entry of =phases= + +| Key | Type | Meaning | +|------------+--------+----------------------------------------------------------------------------------------------------------------------------------| +| =commands= | array | The commands of the phase, in the order a run starts them. | +| =env= | object | The environment of the phase, which each of its commands gets. | +| =name= | string | =preflight=, =licences=, =shard=, =sources=, =admission=, =build=, =caches= or =logs=. | +| =reason= | string | Why the phase is not planned; only then. | +| =role= | string | The role whose launch arguments its commands take, such as =build= or =short=; only for a phase that has one. | +| =status= | string | =planned=, =not configured=, or =refused= for an admission that =admission.required= asks for when the site file cannot give it. | + +*** Each entry of =commands= + +| Key | Type | Meaning | +|--------+-----------------+---------------------------------------------------------------------------------------------------------------------------| +| =argv= | array of string | The whole command: the route, the launch line and the module wrapper when there are any, then the tool and its arguments. | +| =env= | object | Variables set over the phase environment for this command; only when there are some. | +| =name= | string | =probe:TOOL=, =shard=, =fetch:STEM=, =admit:UNIT=, =build:STEM=, =keep-failed:STEM=, =cache= or =rotate=. | +| =note= | string | What to know about the command, such as what its exit statuses mean; only when there is something. | + +=STEM= is the easyconfig file name without =.eb=, with =.2=, =.3= and so on added when the list repeats a line. +=UNIT= is =all= for the whole list, or =cpu-prerequisites=, =prelude= or the name of a shard with a shard plan. +A =probe:TOOL= command runs the =--version= of a tool that has a =min_version=. + +*** Each entry of =deselected= + +| Key | Type | Meaning | +|--------------+--------+------------------------------------------------------------------| +| =easyconfig= | string | The easyconfig of the line. | +| =unit= | string | =all=: the selection reads the whole list, before =stack shard=. | + +** The result file + +=run --result FILE= writes it when the run ends, and =run= without =--result= writes none. +=run --dry-run= writes none either, and neither does a run that an error in its input stops before it starts, such as an invalid site file, an unknown target, a list that cannot be read or a tool below its =min_version=: those exit 2, or 78 when only the licence gate fails, and leave an existing =FILE= as it was. +Read the exit status before the file. + +#+begin_src bash +eb-pipeline run --site site.toml --list build.list --target cpu --build-type production \ + --run-id nightly --log-stamp 20261117_090000 --result result.json +#+end_src + +#+begin_example +INFO [licences] cpu: not configured +INFO [shard] cpu: not configured +INFO [sources] cpu: not configured +INFO [admission] cpu: not configured +INFO [caches] cpu: not configured +INFO [build] cpu: Example-1.0-GCCcore-15.2.0: start +INFO [build] cpu: Example-1.0-GCCcore-15.2.0: ok +INFO [build] cpu: Broken-1.0-GCCcore-15.2.0: start +ERROR [build] cpu: Broken-1.0-GCCcore-15.2.0: failed (exit 1) +#+end_example + +#+begin_src bash +cat result.json +#+end_src + +#+begin_example +{ + "admission": [], + "build_type": "production", + "counts": { + "failed": 1, + "success": 1 + }, + "ended_at": "2026-11-17T03:07:42.086667400+00:00", + "exit_code": 1, + "kind": "result", + "lines": [ + { + "easyconfig": "Example-1.0-GCCcore-15.2.0.eb", + "exit_code": 0, + "log": "$WORK/logs/20261117_090000/cpu/Example-1.0-GCCcore-15.2.0.stdout.log", + "phase": "build", + "status": "success", + "unit": "all" + }, + { + "easyconfig": "Broken-1.0-GCCcore-15.2.0.eb", + "exit_code": 1, + "log": "$WORK/logs/20261117_090000/cpu/Broken-1.0-GCCcore-15.2.0.stdout.log", + "phase": "build", + "status": "failed", + "unit": "all" + } + ], + "list": "build.list", + "log_dir": "$WORK/logs/20261117_090000/cpu", + "not_configured": [ + "licences", + "shard", + "sources", + "admission", + "caches" + ], + "phases": [ + { + "name": "preflight", + "status": "ok" + }, +... + { + "name": "build", + "status": "failed" + }, + { + "name": "caches", + "status": "not configured" + }, + { + "exit_code": 0, + "name": "logs", + "status": "ok" + } + ], + "run_id": "nightly", + "schema_version": 1, + "sharded": false, + "site": "example", + "started_at": "2026-11-17T03:07:42.003465530+00:00", + "target": "cpu" +} +#+end_example + +| Key | Type | Meaning | +|------------------+---------+------------------------------------------------------------------------------------------------------------------------| +| =admission= | array | The admission of each unit that went through it, in order. | +| =build_type= | string | The build type. | +| =counts= | object | The number of lines with each status, for the statuses that some line has. A deselected line counts for none. | +| =deselected= | array | The lines that the target's =[targets.select]= left out, as in the plan; only when there are some. | +| =ended_at= | string | When the run ended, in Coordinated Universal Time (UTC): the date, the time to the nanosecond and the offset =+00:00=. | +| =exit_code= | integer | The exit status of the run. | +| =interrupted_by= | string | =SIGINT= or =SIGTERM=, when a signal stopped the run. | +| =kind= | string | =result=. | +| =lines= | array | Every line the run reached, in that order. | +| =list= | string | The build list, as =--list= names it. | +| =log_dir= | string | =LOG_ROOT/LOG_STAMP/TARGET=, where the run wrote its logs. | +| =message= | string | The error that stopped the run, when one did. | +| =not_configured= | array | The phases that the site file leaves out, in pipeline order. | +| =phases= | array | Every phase the run reached, in pipeline order from =preflight= to =logs=. | +| =run_id= | string | The run id. | +| =schema_version= | integer | =1=. | +| =sharded= | boolean | Whether the lines were built in the units of a shard plan. | +| =site= | string | =site.name=. | +| =started_at= | string | When the run started, in the same form as =ended_at=. | +| =target= | string | The name of the target. | + +*** Each entry of =lines= + +| Key | Type | Meaning | +|-------------------+---------+-----------------------------------------------------------------------------------------------------------------------------------| +| =easyconfig= | string | The easyconfig of the line. | +| =exit_code= | integer | The exit status the line counts as; absent for a line that did not run. | +| =log= | string | The log of the line's command. | +| =note= | string | Why the line came to its status, when that needs saying. A line that went through eb-staged-rebuild has one, whatever its status. | +| =phase= | string | =build=, or =sources= when the prefetch of its sources failed. | +| =status= | string | =success=, =failed=, =refused=, =pending= or =skipped=. | +| =translated_from= | integer | The command's own exit status, when =exit_code= translates it, as 78 does eb-staged-rebuild's 2. | +| =unit= | string | The unit of the line: =all=, =cpu-prerequisites=, =prelude= or the name of a shard. | + +| Status | Meaning | +|-----------+-----------------------------------------------------------------------------------------------------------------------| +| =success= | Its command exited 0. | +| =failed= | Its command, or the prefetch of its sources, exited with a status that means failure. | +| =refused= | =eb-staged-rebuild run= refused it, with exit 2. | +| =pending= | =eb-staged-rebuild run= exited 75: a ledger event it requires is pending. | +| =skipped= | It did not run: admission refused its unit or an earlier one, or a signal stopped the run first. The note says which. | + +*** Each entry of =phases= + +| Key | Type | Meaning | +|-------------+---------+-----------------------------------------------------------| +| =exit_code= | integer | The exit status behind the status, when there is one. | +| =name= | string | The phase. | +| =note= | string | Why the phase came to its status, when that needs saying. | +| =status= | string | What the phase came to. | + +| Status | Meaning | +|------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =ok= | The phase did its work. | +| =failed= | A command of the phase failed, or, for =build=, a line did. | +| =refused= | Something the phase needs is missing, such as a variable that the site file names, and the run stopped; for =build=, also a line or unit was refused and none succeeded or failed. | +| =skipped= | The phase did not do its work, and the note says why: for =build=, admission refused before any line started; for =caches=, the build did not finish cleanly; for =logs=, another run held the rotation lock, or =eb-keep-logs rotate= exited 75. | +| =unsharded= | =shard= only: =stack shard= exited with =shards.planner_exit_unsharded=, and the list built as one unit. | +| =interrupted= | A signal stopped the run in this phase. | +| =not configured= | The site file leaves the phase out. | + +*** Each entry of =admission= + +| Key | Type | Meaning | +|-------------+---------+---------------------------------------------------| +| =attempts= | integer | How many times =stack admit= ran for the unit. | +| =last_json= | string | The last line in JSON that =stack admit= printed. | +| =outcome= | string | =admitted=, =refused= or =failed=. | +| =unit= | string | The unit, as in =lines=. | + +** See also + +- [[file:cli.org][The eb-pipeline command]] +- [[file:exit-status.org][Exit status]] +- [[file:../api/eb_pipeline/plan/struct.Plan.html][eb_pipeline::plan::Plan]] and [[file:../api/eb_pipeline/run/struct.RunResult.html][eb_pipeline::run::RunResult]], the types behind the two files. diff --git a/docs/orgmode/reference/site-file.org b/docs/orgmode/reference/site-file.org new file mode 100644 index 0000000..60fe1d7 --- /dev/null +++ b/docs/orgmode/reference/site-file.org @@ -0,0 +1,432 @@ +#+TITLE: The site file +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* The site file + +The site file holds everything =eb-pipeline= knows about a site: its scheduler, its node types, its paths, its modules and the tools it calls. +It is one file in Tom's Obvious Minimal Language (TOML), named by =--site=. +=eb-pipeline schema= prints the same keys with their types and defaults; =tests/docs.rs= checks this page against them. + +** Format + +- The file starts with =schema_version = 1= and =kind = "site"=. +- An unknown key, or a value of the wrong type, is an error. + =check= lists every other problem of the file at once, one =ERROR [check] NAME: PROBLEM= line each, then =ERROR [main] -: N problem(s) in the site file=, and exits 2. +- An optional table that the file leaves out turns its phase off, and the plan and the result record the phase as =not configured=. + So does =enabled = false= in the tables that have =enabled=. +- =site.name=, =site.project= and the name of each target hold letters, digits, =.=, =_= and =-= only. + A target name is not =.= or =..=, since it names a directory. +- A value that holds the arguments of a command, such as =scheduler.launch= or a key of =[phase_defaults]=, is split into words as a shell splits them, with single and double quotes. +- The variables =EB_PIPELINE__SECTION__KEY= set values over the file before it is checked; [[file:environment.org][Environment variables]] describes them. + +** Placeholders + +=eb-pipeline= replaces a placeholder in braces in these keys, and =check= refuses any other placeholder in them. + +| Keys | Placeholders | +|-------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------| +| =scheduler.job_name_template= | ={project}=, ={build}=, ={phase}=, ={target}= | +| =filesystems.build_path=, the entries of =filesystems.source_paths=, =rebuild.state_root= | ={target}= | +| =targets.route.args=, the values of =targets.route.env= | ={phase_dir}=, ={log_dir}=, ={work_dir}=, ={target}=, ={phase}=, ={runtime_root}=, ={shares_ro}=, ={shares_rw}= | +| the entries of =targets.route.shares_ro= and =targets.route.shares_rw= | ={phase_dir}=, ={log_dir}=, ={work_dir}=, ={target}=, ={phase}= | + +| Placeholder | Value | +|------------------+-------------------------------------------------------------------------------------------------------| +| ={project}= | =site.project=, else =site.name= | +| ={build}= | the build type | +| ={phase}= | the phase that starts the command, such as =build= or =sources= | +| ={target}= | the name of the target | +| ={log_dir}= | the run's log directory, =LOG_ROOT/LOG_STAMP/TARGET= | +| ={phase_dir}= | =LOG_DIR/PHASE=; when =args= or a share has it, the run makes the directory before the command starts | +| ={work_dir}= | the target's =filesystems.build_path= | +| ={runtime_root}= | =targets.route.runtime_root=, empty when it is unset | +| ={shares_ro}= | the entries of =targets.route.shares_ro=, with their placeholders replaced, joined with =:= | +| ={shares_rw}= | the same for =targets.route.shares_rw= | + +*** {target} in paths + +={target}= in =filesystems.build_path=, in an entry of =filesystems.source_paths= and in =rebuild.state_root= gives each target a path of its own. +=plan= and =explain= show the paths with the name in place. + +- =build_path = "/scratch/alice/build/{target}"= gives each target an =EASYBUILD_BUILDPATH= of its own, and ={work_dir}= follows it. +- EasyBuild looks for a source in every entry of =source_paths= and downloads a missing one into the first, so =source_paths = ["/scratch/alice/sources/{target}", "/opt/site/sources"]= gives each target a download directory of its own and still finds the sources in =/opt/site/sources=. +- =state_root = "/opt/site/{target}/.eb-staged-rebuild"= gives each target an eb-staged-rebuild state root, and so a lock, of its own. + +=check= refuses ={target}= in the other paths of =[filesystems]=, and a =state_root= with ={target}= when two targets that take staged rebuilds share a =software_root=: eb-staged-rebuild locks a live tree through its state root, so one tree takes one state root. + +** Top level + +| Key | Type | Default | Meaning | +|------------------+----------------+----------+---------------------------------------------------------------------------------| +| =schema_version= | integer | required | The version of the format; =1=. | +| =kind= | string | required | The kind of file; =site=. | +| =site= | table | required | The site and its tools. | +| =scheduler= | table | required | How a run starts its commands. | +| =phase_defaults= | table | none | The launch arguments of each phase role. | +| =targets= | array of table | required | The node types to build for; at least one. | +| =filesystems= | table | required | The paths. | +| =admission= | table | none | Admission of each build unit under an inode quota, with =eb-stack stack admit=. | +| =shards= | table | none | Splitting a list into shards, with =eb-stack stack shard=. | +| =sources= | table | none | Fetching the sources of every line before the first build. | +| =modules= | table | required | The environment modules each command loads. | +| =caches= | table | none | The command that writes module caches after a clean build. | +| =logs= | table | none | Keeping the logs of a failed line, and rotating the log tree. | +| =rebuild= | table | none | Rebuilding installed software in a staged tree, with eb-staged-rebuild. | +| =licences= | table | none | The licence gate. | + +** =[site]= + +| Key | Type | Default | Meaning | +|--------------------+--------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------| +| =name= | string | required | The name of the site. A run exports it as =EB_PIPELINE_SITE=, and it is the default of =project=. | +| =project= | string | =site.name= | The value of ={project}= in =scheduler.job_name_template=. | +| =build_account= | string | none | The account that owns the installs; exported as =EB_PIPELINE_BUILD_ACCOUNT= and not read otherwise. | +| =default_group= | string | none | The default Unix group of the installs; exported as =EB_PIPELINE_DEFAULT_GROUP=. | +| =stack_generation= | string | none | A label for the generation of the software stack, such as =2026.1=; not read. | +| =tools= | table | all tools looked up on =PATH=, no minimum version | The programs of the sibling tools and the versions they need. | + +*** =[site.tools]= + +| Key | Type | Default | Meaning | +|---------------------+-------+---------------------------+------------------------------------------------------------------------------| +| =eb_stack= | table | =bin= =eb-stack= | eb-stack, which runs =stack shard= and =stack admit=. | +| =eb_keep_logs= | table | =bin= =eb-keep-logs= | eb-keep-logs, which runs =failed= and =rotate=. | +| =eb_staged_rebuild= | table | =bin= =eb-staged-rebuild= | eb-staged-rebuild, which runs =run= for a line that rebuilds a live install. | + +*** =[site.tools.TOOL]= + +=TOOL= is =eb_stack=, =eb_keep_logs= or =eb_staged_rebuild=. + +| Key | Type | Default | Meaning | +|---------------+--------+------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =bin= | string | the tool's own name, looked up on =PATH= | The program: a path, or a name to look up on =PATH=. | +| =min_version= | string | none | The lowest version accepted, as dotted numbers such as =0.7.4=. When a phase that calls the tool is on, =run= starts =BIN --version= before any other command, and exits 2 when the tool cannot start, prints no dotted number, or prints a lower one first. | + +** =[scheduler]= + +| Key | Type | Default | Meaning | +|---------------------+-----------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------| +| =kind= | string | required | =slurm= starts each command through =launch=, with the launch arguments of its role; =local= starts it as it is, and the launch arguments are not used. | +| =launch= | string | =srun= | The launch command of =slurm=; not empty. | +| =common_args= | array of string | =[]= | Arguments of every launch line, after =launch= and before =--job-name=. | +| =env= | table of string | ={}= | Variables set for every command; a variable that =eb-pipeline= sets itself replaces one of the same name. | +| =job_name_template= | string | ={project}-{build}-{phase}= | The job name each launch line passes as =--job-name=. | + +With =kind = "slurm"=, a command starts as =LAUNCH COMMON_ARGS --job-name=NAME ROLE_ARGS COMMAND=, where =ROLE_ARGS= are the launch arguments of the command's role and =COMMAND= starts with the module wrapper when there is one. +A role without launch arguments launches a bare =srun --job-name=NAME=, and inside an allocation =srun= then starts one task for each task of the allocation, so give each role a task count, such as =-N 1 --ntasks-per-node=1=. + +** =[phase_defaults]= + +Each key holds the launch arguments of one role, for every target that does not set its own in =[targets.phases]=. + +| Key | Type | Default | Meaning | +|---------+--------+---------+--------------------------------------------------------------------------------------------------------| +| =plan= | string | none | =eb-stack stack shard=. | +| =build= | string | none | The builds of the whole list, of the prelude and of each shard. | +| =short= | string | none | Admission, source prefetch, =eb-keep-logs failed= and =eb-keep-logs rotate=. | +| =cpu= | string | none | The builds of the CPU-only prerequisites that =stack shard= lifts out, which the target's route wraps. | +| =cache= | string | none | =[caches].command=, when the target's entry in =[[caches.targets]]= sets no =alloc=. | + +** =[[targets]]= + +One table per node type. +A run builds for one target, named by =--target=. + +| Key | Type | Default | Meaning | +|-----------------------------+-----------------+-----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =name= | string | required | The name of the target, unique in the file. It names the target's log directory, and ={target}= expands to it. | +| =build_lists= | array of string | =[]= | The file names of the build lists of the target; =check --lists-dir DIR= checks that each is a file in =DIR=. | +| =eb_optarch= | string | none | =EASYBUILD_OPTARCH=. | +| =max_parallel= | integer | none | =EASYBUILD_MAX_PARALLEL=. | +| =cuda_compute_capabilities= | string | none | =EASYBUILD_CUDA_COMPUTE_CAPABILITIES=, such as =9.0=. | +| =cpu_target= | string | none | The CPU subdirectory of the European Environment for Scientific Software Installations (EESSI), such as =x86_64/amd/zen4=, exported in the variable =modules.eessi.cpu_override_var= names. With =[modules.eessi]= on, it is =ARCH/UARCH= or =ARCH/VENDOR/UARCH=, and =ARCH= is =x86_64=, =aarch64=, =riscv64= or =ppc64le=. | +| =accel_target= | string | none | The accelerator subdirectory of EESSI, such as =accel/nvidia/cc90=, exported in the variable =modules.eessi.accel_override_var= names; empty means none. With =[modules.eessi]= on, it is =accel/nvidia/ccDIGITS= or =accel/amd/gfxHEX=. | +| =site_prefix= | string | none | The install prefix of the target, exported as =EASYBUILD_INSTALLPATH= and =EESSI_SITE_SOFTWARE_PREFIX=; =filesystems.install_root= when unset. | +| =software_root= | string | =/software= | The live software tree of the target: =EASYBUILD_INSTALLPATH_SOFTWARE= with =export_install_vars = "split"=, and =eb-staged-rebuild --software=. | +| =modules_root= | string | =/modules= | The live module tree of the target: =EASYBUILD_INSTALLPATH_MODULES= with =export_install_vars = "split"=, and =eb-staged-rebuild --modules=. A line's module is installed when =MODULES_ROOT/all/NAME/VERSION.lua=, or the same path without =.lua=, exists. | +| =staged= | boolean | =rebuild.staged= | Whether the target takes staged rebuilds. | +| =ledger_config= | string | =rebuild.ledger_config= | The ledger configuration of the target's staged rebuilds. The file names one target, so =check= refuses two targets that take staged rebuilds through the same file. | +| =default= | boolean | =false= | Marks the default target of the site; =explain= prints it, and nothing else reads it. | +| =phases= | table | =phase_defaults= | The launch arguments of the target, per role; a role it leaves out takes the one in =[phase_defaults]=. | +| =route= | table | none | A command that wraps the CPU-role commands of the target. | +| =select= | table | none | Which lines of a list the target builds; without it, all of them. | +| =hardware= | table | none | The CPU of the target's build nodes. | +| =cpu_hardware= | table | none | The CPU of the nodes that build the CPU-role units. When it is set, the source prefetch and build commands export a CPU class as =EB_PIPELINE_HW_VENDOR_ID=, =EB_PIPELINE_HW_CPU_FAMILY= and =EB_PIPELINE_HW_MODEL=: this one for a CPU-role unit, =hardware= for the others. | +| =fetch_profile= | table | none | A table with any keys, passed to the source prefetch commands as =EB_PIPELINE_FETCH_PROFILE=, in JavaScript Object Notation (JSON) with sorted keys. | +| =package_env= | table of tables | ={}= | Variables per package name, =[targets.package_env.NAME]=, for the lines of that package; per key, they win over =[modules.package_env.NAME]=. | +| =build_types= | table of tables | ={}= | Values per build type, =[targets.build_types.NAME]=. | + +With =[modules.eessi]= on and =site_install = true=, EESSI-extend replaces =EASYBUILD_INSTALLPATH= when it loads, with =$EESSI_SITE_SOFTWARE_PREFIX/versions/RELEASE/software/linux/CPU_TARGET=, followed by =/ACCEL_TARGET= for an NVIDIA target when =EESSI_ACCELERATOR_INSTALL= is set. +=explain= names that path as the target's =install_note=. +A target that then takes staged rebuilds, with =filesystems.export_install_vars = "single"=, sets =software_root= and =modules_root= to the =software= and =modules= directories under it, and =check= refuses the file otherwise. + +*** =[targets.phases]= + +| Key | Type | Default | Meaning | +|---------+--------+---------+-------------------------------------------------| +| =plan= | string | none | =plan= of =[phase_defaults]=, for this target. | +| =build= | string | none | =build= of =[phase_defaults]=, for this target. | +| =short= | string | none | =short= of =[phase_defaults]=, for this target. | +| =cpu= | string | none | =cpu= of =[phase_defaults]=, for this target. | +| =cache= | string | none | =cache= of =[phase_defaults]=, for this target. | + +*** =[targets.route]= + +A route wraps the commands of the CPU-role units, the CPU-only prerequisites that =stack shard= lifts out, in a command of the site's: the command, its arguments, =--= when there are arguments, then the launch line and the command it wraps. + +| Key | Type | Default | Meaning | +|----------------------+-----------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =kind= | string | none | =none= or =command=. Every other key needs =command=. | +| =command= | string | none | The wrapper, before the launch line; required with =kind = "command"=. | +| =args= | array of string | =[]= | Arguments after =command=, with placeholders; when there are any, =--= follows them. | +| =env= | table of string | ={}= | Variables of the wrapped commands; the values take placeholders. | +| =runtime_root= | string | none | The root of the route's runtime: ={runtime_root}=, and =EB_PIPELINE_ROUTE_RUNTIME_ROOT= for the wrapped commands. | +| =shares_ro= | array of string | =[]= | Paths the route shares read-only: ={shares_ro}=, and =EB_PIPELINE_ROUTE_SHARES_RO=, joined with =:=. | +| =shares_rw= | array of string | =[]= | Paths the route shares read-write: ={shares_rw}=, and =EB_PIPELINE_ROUTE_SHARES_RW=, joined with =:=. | +| =receipt_digest_env= | string | none | The name of a variable, in letters, digits and =_=, that holds a receipt digest. =run= refuses with exit 78 when it is unset or empty, and passes its value as =EB_PIPELINE_ROUTE_RECEIPT_DIGEST=; =plan= shows =${NAME}=. | +| =phases= | array of string | =["build"]= | The phases whose CPU-role commands the route wraps: =build=, =sources= or both. | + +A route with only =kind= and =command= puts =command= alone before the launch line. + +*** =[targets.select]= + +A build list can mark a line for some targets only, with an option of the line that names them. + +| Key | Type | Default | Meaning | +|---------------+---------+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =option= | string | required | The long option that carries the selection, with its leading dashes, such as =--only-targets=; a line carries it as =--only-targets=a,b= or =--only-targets a,b=. | +| =value= | string | required | The token of this target in the option's list; not empty, and without =separator=. | +| =separator= | string | =,= | What separates the tokens; not empty. | +| =when_absent= | string | =all= | =all= builds a line without the option on this target; =none= leaves it out. | +| =strip= | boolean | =false= | =true= removes the option from the line before =eb= gets it. | + +=plan= and =run= apply the selection to the whole list, or to each shard unit, and drop a unit left without lines. +With a selection, =run= writes the lines it keeps, in list order and with =strip= applied, to =LOG_DIR/selected-TARGET.list=, and passes that file to =stack shard --build-list=. +The plan and the result list the lines left out under =deselected=, and no status count includes them. + +*** =[targets.hardware]= + +| Key | Type | Default | Meaning | +|--------------+---------+---------+------------------------------------------------------------| +| =vendor_id= | string | none | The CPU vendor, as =EB_PIPELINE_HW_VENDOR_ID= carries it. | +| =cpu_family= | integer | none | The CPU family, as =EB_PIPELINE_HW_CPU_FAMILY= carries it. | +| =model= | integer | none | The CPU model, as =EB_PIPELINE_HW_MODEL= carries it. | + +*** =[targets.cpu_hardware]= + +| Key | Type | Default | Meaning | +|--------------+---------+---------+--------------------------------------------------------| +| =vendor_id= | string | none | The CPU vendor of the nodes that build CPU-role units. | +| =cpu_family= | integer | none | Their CPU family. | +| =model= | integer | none | Their CPU model. | + +*** =[targets.build_types.NAME]= + +=--build-type NAME= applies this table; a build type without one takes the values of the target. + +| Key | Type | Default | Meaning | +|----------------+---------+--------------+-----------------------------------------------| +| =eb_optarch= | string | target value | =EASYBUILD_OPTARCH= for this build type. | +| =max_parallel= | integer | target value | =EASYBUILD_MAX_PARALLEL= for this build type. | + +** =[filesystems]= + +| Key | Type | Default | Meaning | +|------------------------------+-----------------+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =scratch= | string | required | The scratch root; not empty. | +| =tmp= | string | required | =EASYBUILD_TMPDIR=; not empty. Each =eb= makes a directory of its own in it, so targets can share it. | +| =build_path= | string | required | =EASYBUILD_BUILDPATH=; not empty. ={target}= expands to the name of the target. | +| =source_paths= | array of string | =[]= | The entries of =EASYBUILD_SOURCEPATH=, joined with =:=. EasyBuild looks for a source in each entry and downloads a missing one into the first. ={target}= expands to the name of the target. | +| =install_root= | string | required | The install prefix of a target that sets no =site_prefix=; not empty. | +| =export_install_vars= | string | =single= | =single= exports =EASYBUILD_INSTALLPATH=; =split= exports =EASYBUILD_INSTALLPATH_SOFTWARE= and =EASYBUILD_INSTALLPATH_MODULES= from the target's =software_root= and =modules_root= instead. | +| =log_root= | string | required | The root of the log tree, which holds a directory =LOG_STAMP/TARGET= for each run, and the locks of its rotation; not empty. | +| =shard_dir= | string | =/shards= | Where =stack shard= writes, in a directory per run id. | +| =read_only_installdir= | boolean | =false= | =true= exports =EASYBUILD_READ_ONLY_INSTALLDIR=. | +| =read_only_installdir_value= | string | =1= | The value of =EASYBUILD_READ_ONLY_INSTALLDIR=. | +| =configs_repo= | string | none | =EASYBUILD_CONFIGS_REPOPATH=. | + +** =[admission]= + +Before each build unit, =eb-stack stack admit= checks that the unit fits in the free inodes of the scratch quota, and reserves them for the job. + +| Key | Type | Default | Meaning | +|---------------------+---------+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =enabled= | boolean | =true= | =false= turns the phase off. | +| =required= | boolean | =false= | =true= refuses the run with exit 78 when =quota_cmd= or =reservations= is missing; with =false=, the phase is then not configured. | +| =quota_cmd= | string | none | A shell command that prints the quota as JSON: =stack admit --quota-cmd=. | +| =live_jobs_cmd= | string | none | A shell command that prints the ids of the running jobs of the build account, such as =squeue -h -t R -u USER -o %A=: =stack admit --live-jobs-cmd=. Without it, every other job's reservation counts, also that of a job that ended without removing it, and =check= warns. | +| =lock= | string | none | The lock file that every admission takes: =stack admit --lock=. =run= takes it too, to remove the job's reservation. | +| =lock_kind= | string | =flock= | =flock= or =posix=, as the other holders of =lock= take it: =stack admit --lock-kind=. | +| =reservations= | string | none | The directory of reservations: =stack admit --reservations=. | +| =margin= | integer | tool default | The inodes to keep free: =stack admit --margin=, and =stack shard --inode-margin= with =quota_total=. | +| =unknown_reserve= | integer | =0= | The inodes to count for each live job without a reservation: =stack admit --unknown-reserve=. | +| =default_footprint= | integer | none | The inodes of a unit for which the shard plan gives none; required when the table is enabled. | +| =job_id_env= | string | =SLURM_JOB_ID= | The variable that holds the job id at run time, in letters, digits and =_=. =run= refuses with exit 78 before any build when it is unset or not a positive integer without a leading zero; =plan= shows =${NAME}=. | +| =quota_total= | integer | none | The inode quota to plan with: =stack shard --inode-quota=. | +| =footprints= | string | none | A file of inode footprints: =stack shard --inode-footprints=. | +| =line_overhead= | integer | tool default | The inodes of a list line beyond its build tree: =stack shard --inode-line-overhead=. | +| =attempts= | integer | =5= | How many times =stack admit= is asked before the run is refused; at least 1. | +| =wait_seconds= | integer | =60= | The wait before the second attempt, in seconds; it doubles before each later one. | +| =max_wait_seconds= | integer | =600= | The longest wait between two attempts, in seconds. | + +A unit's footprint is the =inode_footprint= of the shard plan, else =default_footprint=. +When an admitted unit's builds end, or the run ends first, =run= removes =RESERVATIONS/JOB.json= while it holds =lock=, taken as =lock_kind=. +A record that another writer has replaced since, such as a =forecast= or =waiting= one, stays, with a =WARN= line. + +** =[shards]= + +=eb-stack stack shard= splits the list into units that build one after the other: the CPU-only prerequisites, the prelude, which holds what two or more shards need, then each shard. + +| Key | Type | Default | Meaning | +|-----------------------------------+-----------------+---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =enabled= | boolean | =true= | =false= turns the phase off. | +| =count= | integer | =1= | The most shards to plan: =stack shard --shards=. Below 2, the phase is off and the list builds as one unit. | +| =planner_exit_unsharded= | integer | =3= | The exit status of =stack shard= that means it built the plan unsharded; the list then builds as one unit. | +| =lift_cpu_prerequisites= | boolean | =false= | =true= passes =--lift-cpu-prerequisites=, which makes the CPU-only prerequisites a unit of their own. | +| =easyconfigs= | array of string | =[]= | The easyconfig trees to resolve the list in: =stack shard --easyconfigs=, once each; at least one when =count= is 2 or more. | +| =weights= | string | none | A table of build times: =stack shard --weights=. | +| =installed_modules_dirs= | array of string | =[]= | Module trees whose modules count as installed: =stack shard --installed-modules-dir=, once each. =run= leaves out a tree that does not exist yet, with a =WARN= line. | +| =installed_modules_dirs_from_env= | array of string | =[]= | Names of variables whose values, separated by =:=, =run= adds to =installed_modules_dirs=. =run= refuses with exit 78 when one is unset, an empty one adds nothing, and =plan= shows =${NAME}=. | + +=stack shard= runs inside the module wrapper, so what the modules of =[modules] init= set reaches it, such as the =EASYBUILD_FILTER_DEPS= of EESSI-extend. +It writes its plan to =SHARD_DIR/RUN_ID/plan.json=, and =plan --shard-plan DIR= reads such a plan. +A shard list holds lines of the input list only, so a line whose dependencies are not installed needs =--robot= to build them. + +** =[sources]= + +| Key | Type | Default | Meaning | +|--------------+-----------------+---------+---------------------------------------------------------------------------------------------------------| +| =enabled= | boolean | =true= | =false= turns the phase off. | +| =prefetch= | boolean | =true= | Run =eb EASYCONFIG --fetch --robot= for every line before the first build; =false= turns the phase off. | +| =extra_args= | array of string | =[]= | Arguments of each prefetch command, after the line's own options. | + +A prefetch command gets the options of its line, except those that start with =--rebuild=. +A line whose prefetch fails is =failed= and is not built. +=--fetch= takes no account of installed modules, so =--robot= fetches the sources of every dependency, those EESSI provides included. +With =--disable-robot= in =extra_args=, a line fetches its own sources only: the prefetch command has no =--robot=, the line's =--robot= is dropped, and the paths of the line's =--robot=PATH= go first in =--robot-paths=, so that its easyconfig is still found. + +** =[modules]= + +| Key | Type | Default | Meaning | +|---------------+-----------------+----------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =init= | array of string | required | The modules to load, in order, after =module purge=, before the shard, prefetch, build, =eb-keep-logs failed= and cache commands; may be empty. | +| =unuse_path= | boolean | =false= | =true= empties =MODULEPATH= after =shell_init= and before =init= loads, so that the first module of =init= needs an absolute path; =check= warns when it has none. | +| =shell= | string | =bash= | The shell that runs the module wrapper. | +| =shell_init= | string | none | A file to source before =module= is called, for a shell that does not define it. It is sourced without =set -e= and =set -u=; a =module= call that fails still stops the command. | +| =eessi= | table | none | The site layer of EESSI. | +| =package_env= | table of tables | ={}= | Variables per package name, =[modules.package_env.NAME]=, for the prefetch and build commands of the lines of that package. | + +The module wrapper starts when =init= is not empty, =unuse_path= is =true= or =shell_init= is set; [[file:environment.org][Environment variables]] describes it. + +*** =[modules.eessi]= + +| Key | Type | Default | Meaning | +|------------------------+---------+-------------------------------------+--------------------------------------------------------| +| =enabled= | boolean | =true= | =false= ignores the table. | +| =site_install= | boolean | =false= | =true= exports =EESSI_SITE_INSTALL=1=. | +| =bootstrap_modulepath= | string | none | Exported as =EESSI_SITE_BOOTSTRAP_MODULEPATH=. | +| =cpu_override_var= | string | =EESSI_SOFTWARE_SUBDIR_OVERRIDE= | The variable that carries the target's =cpu_target=. | +| =accel_override_var= | string | =EESSI_ACCELERATOR_TARGET_OVERRIDE= | The variable that carries the target's =accel_target=. | + +With the table on, every command also gets =EESSI_SITE_SOFTWARE_PREFIX=, the target's install prefix, and =check= checks the form of each target's =cpu_target= and =accel_target=. + +** =[caches]= + +| Key | Type | Default | Meaning | +|---------------+----------------+---------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =enabled= | boolean | =true= | =false= turns the phase off. | +| =command= | string | none | The command that writes the module caches, run once after a clean build of a target that has an entry in =[[caches.targets]]=; without it, the phase is not configured. | +| =bindings= | string | none | Passed to =command= as =EB_PIPELINE_CACHE_BINDINGS=. | +| =init_module= | string | none | Passed as =EB_PIPELINE_CACHE_INIT_MODULE= for an entry that sets none. | +| =targets= | array of table | =[]= | One =[[caches.targets]]= table per target that has caches. | + +A build is clean when no line failed, was refused or is pending; otherwise the =caches= phase is =skipped=. + +*** =[[caches.targets]]= + +| Key | Type | Default | Meaning | +|---------------+--------+------------------------+------------------------------------------------------------------------------| +| =target= | string | required | The name of a target; each target has one entry at most. | +| =config= | string | required | The cache configuration file, passed as =EB_PIPELINE_CACHE_CONFIG=. | +| =alloc= | string | =phase_defaults.cache= | The launch arguments of the cache command for this target. | +| =init_module= | string | none | Passed as =EB_PIPELINE_CACHE_INIT_MODULE=, in place of =caches.init_module=. | + +** =[logs]= + +| Key | Type | Default | Meaning | +|---------------+---------+---------+---------------------------------------------------------------------| +| =enabled= | boolean | =true= | =false= turns the phase off. | +| =keep_failed= | boolean | =true= | Keep the EasyBuild log of a failed line with =eb-keep-logs failed=. | +| =rotate= | table | none | Rotate the log tree with =eb-keep-logs rotate= at the end of a run. | + +With =keep_failed=, each =eb= gets =--tmp-logdir=LOG_DIR/easybuild-logs/STEM=, and after a line fails =run= starts =eb-keep-logs failed STATUS STEM LOG_DIR LOG_DIR/easybuild-logs/STEM=, with =EASYBUILD_OUTPUT_STYLE=basic= whatever =[scheduler.env]= sets, so that =eb --last-log= prints the log path on one line. + +*** =[logs.rotate]= + +| Key | Type | Default | Meaning | +|-----------------------+---------+----------+---------------------------------------------------------------------------| +| =compress_after_days= | integer | required | =eb-keep-logs rotate --compress-after=. | +| =delete_after_days= | integer | none | =eb-keep-logs rotate --delete-after=; greater than =compress_after_days=. | + +The =logs= phase starts =eb-keep-logs rotate LOG_ROOT --compress-after DAYS --delete-after DAYS=, with =TZ=UTC=, since the log directories are named in Coordinated Universal Time (UTC). +A run rotates only when no other run under the log root is live: each run holds =LOG_ROOT/.eb-pipeline-rotate.lock= shared from its start, and rotates when it can take it alone; otherwise the =logs= phase is =skipped=. +Where =eb-keep-logs --help= lists =--lock-timeout=, the rotate also gets =--lock-timeout 0=, and exits 75, recorded as =skipped=, while another rotate holds =LOG_ROOT/.eb-keep-logs-rotate.lock=. +[[file:log-tree.org][The log tree and its locks]] lists the files of a run and the locks, and gives their order. + +** =[rebuild]= + +A line goes through =eb-staged-rebuild run= instead of =eb= when all three hold: + +1. the target takes staged rebuilds: its =staged=, else =rebuild.staged=, is =true=; +2. the line carries =--rebuild=, =-f= or =--force= as a whole option, which =--force-download= and =--rebuild-from-scratch= are not; +3. the line's module is installed under the target's =modules_root=. + +Otherwise the line builds with =eb=; on a target that takes staged rebuilds, a line that has the option but no installed module gets a note in the plan and a =WARN= line in the run. + +| Key | Type | Default | Meaning | +|-----------------+---------+--------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =enabled= | boolean | =true= | =false= turns staged rebuilds off. | +| =staged= | boolean | =true= | Whether a target that sets no =staged= takes staged rebuilds. | +| =state_root= | string | tool default | =eb-staged-rebuild run --state-root=. ={target}= expands to the name of the target. Unset, eb-staged-rebuild takes =EB_STAGED_REBUILD_STATE_ROOT=, which a module can set where =eb-pipeline= cannot see it, else =.eb-staged-rebuild= beside the software tree. | +| =lock_timeout= | integer | =600= | =eb-staged-rebuild run --lock-timeout=: how many seconds a staged line waits for the lock of the state root, which another eb-staged-rebuild holds for the whole of its build and publish; =0= does not wait. A line whose wait runs out is =refused=. | +| =backend= | string | =auto= | =eb-staged-rebuild run --backend=: =auto=, =bwrap=, =userns= or =installpath=. | +| =grace_hours= | integer | tool default | =eb-staged-rebuild run --grace-hours=. | +| =prepare= | string | none | A program, passed as =eb-staged-rebuild run --prepare=. | +| =ledger_config= | string | none | A file in JSON, passed as =eb-staged-rebuild run --ledger-config=, for a target that sets no =ledger_config=. | + +A staged line starts =eb-staged-rebuild run --software SOFTWARE_ROOT --modules MODULES_ROOT --backend BACKEND --run-id RUN_ID-STEM --lock-timeout SECONDS=, with the other keys of the table that are set, then =--=, the easyconfig and the options of the line. +=STEM= is the easyconfig file name without =.eb=, with =.2=, =.3= and so on added when the list repeats a line, since eb-staged-rebuild refuses a run id it has seen. +A line whose wait for a lock runs out is =refused=; its note and its =ERROR= line name the lock that another eb-staged-rebuild holds and, when it is the state root's, say that =lock_timeout= ran out. + +** =[licences]= + +The licence gate checks the site file only: every package that needs a licence has a group, a version threshold or an exemption. +It does not check file permissions or group membership on the host. + +| Key | Type | Default | Meaning | +|-----------------+-----------------+---------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| =enabled= | boolean | =true= | =false= turns the gate off. | +| =enforce= | boolean | =true= | Run the gate: every name of =[licences.required]= needs a group, a threshold or an exemption, and a table with none of the three is refused. | +| =groups= | table of string | ={}= | Package name to Unix group, exported as =EB_PIPELINE_LICENCE_GROUP= for the lines of that package. | +| =below_version= | table of string | ={}= | Package name to a version in dotted numbers; the package's group applies below that version only, and to a version that does not parse. The package needs a group. | +| =required= | table | none | A second list of the packages that need a licence, kept apart from =groups=. | +| =exempt= | array of string | =[]= | Names of =[licences.required]= that have no group on purpose. | +| =env= | table of tables | ={}= | Variables per package name, =[licences.env.NAME]=, for the prefetch and build commands of the lines of that package. | + +The gate is on when =enabled= and =enforce= are both =true=, and only then do the lines get =EB_PIPELINE_LICENCE_GROUP= and the variables of =[licences.env]=. +When the gate's problems are the only ones of the file, =run= exits 78; =check= and =plan= exit 2. + +*** =[licences.required]= + +| Key | Type | Default | Meaning | +|------------+-----------------+---------+------------------------------------------------------------------------| +| =software= | array of string | =[]= | The package names that each need a group, a threshold or an exemption. | + +** See also + +- [[file:cli.org][The eb-pipeline command]] and [[file:environment.org][Environment variables]] +- [[file:exit-status.org][Exit status]] +- [[file:log-tree.org][The log tree and its locks]] +- [[file:templates.org][The site file templates]], two complete site files to start from +- The fields of the site file in [[file:../api/eb_pipeline/schema/index.html][eb_pipeline::schema]], whose doc comments are the text =eb-pipeline schema= prints. diff --git a/docs/orgmode/reference/templates.org b/docs/orgmode/reference/templates.org new file mode 100644 index 0000000..7ad957b --- /dev/null +++ b/docs/orgmode/reference/templates.org @@ -0,0 +1,82 @@ +#+TITLE: The site file templates +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* The site file templates + +=eb-pipeline init= writes a site file from one of two built-in templates. +Each is a complete site file that =check= finds valid, with placeholder values only: names in angle brackets, such as ==, and paths and names, such as =/opt/eb= and =small-lab=, that stand for the site's own. +The examples on this page come from =docs/examples/templates.sh=. + +#+begin_src bash +eb-pipeline init --list +#+end_src + +#+begin_example +small-cluster Slurm, one CPU target; no EESSI, inode quota or licences +eessi-site Slurm, CPU and GPU targets on an EESSI site layer, with quota, caches and licences +#+end_example + +| Template | Targets | Phases it turns on, besides =preflight= and =build= | +|-----------------+------------------------------------+------------------------------------------------------------------| +| =small-cluster= | =cpu= | =logs= | +| =eessi-site= | =cpu-a=, =cpu-b=, =gpu-a=, =gpu-b= | =licences=, =shard=, =sources=, =admission=, =caches= and =logs= | + +=init --template NAME= prints the template, and =init --template NAME --out FILE= writes it to =FILE=: + +#+begin_src bash +eb-pipeline init --template small-cluster --out small-cluster.toml +eb-pipeline check --site small-cluster.toml +#+end_src + +#+begin_example +INFO [init] -: wrote template small-cluster to small-cluster.toml +INFO [check] small-lab: site file is valid +#+end_example + +=init= refuses a file that exists, and exits 2, as it does for an unknown template or none: + +#+begin_src bash +eb-pipeline init --template small-cluster --out small-cluster.toml +#+end_src + +#+begin_example +ERROR [main] -: cannot create small-cluster.toml: File exists (os error 17) +#+end_example + +** =small-cluster= + +A Slurm cluster with one CPU node type, and none of the European Environment for Scientific Software Installations (EESSI), an inode quota or licences. +Each command of a run starts with =srun= and the launch arguments of its role, from =[phase_defaults]=, and the build of a line runs with the =EasyBuild= module loaded. +A failed line keeps its EasyBuild log, and a run rotates the log tree with =eb-keep-logs rotate --compress-after 60=. + +#+INCLUDE: "../../../templates/small-cluster.toml" src toml + +** =eessi-site= + +A site that installs into its own layer on top of EESSI, with two CPU and two GPU node types. +Its targets install where EESSI-extend puts a site installation for their =cpu_target= and =accel_target=. +The GPU target =gpu-a= keeps only the lines of a list that are for it, and wraps the commands of its CPU-only prerequisites in a route command, which build them with the hardware variables of another class. +A run admits each unit against an inode quota, shards the list, prefetches sources without the robot, writes module caches for =cpu-a= and =gpu-a=, rebuilds installed modules through eb-staged-rebuild with a state root per target, and checks that each licensed package has a group, a version threshold or an exemption. + +#+begin_src bash +eb-pipeline init --template eessi-site --out eessi-site.toml +eb-pipeline check --site eessi-site.toml +eb-pipeline targets --site eessi-site.toml +#+end_src + +#+begin_example +INFO [init] -: wrote template eessi-site to eessi-site.toml +INFO [check] cluster-a: site file is valid +cpu-a +cpu-b +gpu-a +gpu-b +#+end_example + +#+INCLUDE: "../../../templates/eessi-site.toml" src toml + +** See also + +- [[file:site-file.org][The site file]], for every key the templates set +- [[file:cli.org][The eb-pipeline command]], for =init=, =check= and =targets= diff --git a/docs/orgmode/tutorials/first-build-list.org b/docs/orgmode/tutorials/first-build-list.org new file mode 100644 index 0000000..8a2a153 --- /dev/null +++ b/docs/orgmode/tutorials/first-build-list.org @@ -0,0 +1,331 @@ +#+TITLE: Run your first build list +#+OPTIONS: toc:nil todo:nil num:nil author:nil title:nil +#+STARTUP: content + +* Run your first build list + +By the end of this tutorial you will have run a build list through eb-pipeline, read the result file it wrote, and seen what a line that fails does to the run and to its exit status. +Everything runs on one Linux machine, as an ordinary user, in a directory under your home. +A stand-in for EasyBuild's =eb= command, six lines of shell, takes the place of EasyBuild and prints what it was asked to do, so you need no cluster, no Slurm and no EasyBuild. + +** What you will need + +- A Linux machine with =git= and Rust 1.90 or newer: + + #+begin_src bash + cargo --version + #+end_src + + #+begin_example + cargo 1.90.0 (840b83a10 2025-07-30) + #+end_example + + If the shell answers =cargo: command not found=, install Rust with [[https://rustup.rs][rustup]] first. + +** Install eb-pipeline + +Clone the repository, check out the commit this tutorial was checked with, and install the program from it: + +#+begin_src bash +git clone https://github.com/stackhands/eb-pipeline.git +cd eb-pipeline +git checkout ef2fbe2 +cargo install --locked --path . +#+end_src + +Cargo builds =eb-pipeline= and installs it in the =bin= directory of its home, =~/.cargo/bin= unless =CARGO_HOME= names another, which rustup puts on your =PATH=. +Ask it for its version: + +#+begin_src bash +eb-pipeline --version +#+end_src + +#+begin_example +eb-pipeline 0.3.0 +#+end_example + +** Make a directory to work in + +Every step from here on runs in one directory, which the commands call =$WORK=: + +#+begin_src bash +export WORK=$HOME/eb-tutorial +mkdir -p "$WORK" +cd "$WORK" +#+end_src + +In the output on this page, =$WORK= stands for that directory as your shell prints it, such as =/home/alice/eb-tutorial=. + +** Put a stand-in for EasyBuild on your =PATH= + +eb-pipeline builds each line of a build list by starting EasyBuild's =eb=. +This stand-in prints the arguments it gets and the EasyBuild settings in its environment, and fails for an easyconfig whose name starts with =Broken-=: + +#+INCLUDE: "first-build-list/eb.sh" src bash + +Put its directory first on your =PATH=, so that eb-pipeline starts it rather than an EasyBuild you may have: + +#+begin_src bash +export PATH="$WORK/bin:$PATH" +command -v eb +#+end_src + +#+begin_example +$WORK/bin/eb +#+end_example + +** Write a site file + +A /site file/ describes a site to eb-pipeline: how each phase of a run starts, the targets it builds for, and the paths EasyBuild works in. +This one starts every phase on this machine, =kind = "local"=, has one target, =cpu=, keeps every path under =$WORK=, and loads no modules, =init = []=: + +#+INCLUDE: "first-build-list/site.sh" src bash + +Check it: + +#+begin_src bash +eb-pipeline check --site site.toml +#+end_src + +#+begin_example +INFO [check] example: site file is valid +#+end_example + +=example= is the site's =name=; for a file it refuses, =check= prints an =ERROR= line for each problem and exits with status 2. + +** Write a build list + +A /build list/ names one easyconfig per line, with any options for =eb= after it: + +#+begin_src bash +cat > build.list <<'EOF' +Example-1.0-GCCcore-15.2.0.eb +zlib-1.3.1-GCCcore-15.2.0.eb --rebuild +EOF +#+end_src + +** See what a run would start + +=run --dry-run= prints the commands a run would start, phase by phase, and starts none of them: + +#+begin_src bash +eb-pipeline run --site site.toml --list build.list --target cpu --build-type production --dry-run +#+end_src + +#+begin_example +# [licences] not configured +# [shard] not configured +# [sources] not configured +# [admission] not configured +[build] eb Example-1.0-GCCcore-15.2.0.eb +[build] eb zlib-1.3.1-GCCcore-15.2.0.eb --rebuild +# [caches] not configured +# [logs] not configured +INFO [run] cpu: dry run: nothing executed +#+end_example + +A run goes through its phases in this order, and this site file configures only =build=, which starts one =eb= for each line, with the line's options. +=--target cpu= picks the target, and =--build-type production= names the kind of build, for which a target can have settings of its own. + +** Run the build list + +Run it again without =--dry-run=, with =--result= to keep a result file, and print the exit status: + +#+begin_src bash +eb-pipeline run --site site.toml --list build.list --target cpu --build-type production --result result.json +echo $? +#+end_src + +#+begin_example +INFO [licences] cpu: not configured +INFO [shard] cpu: not configured +INFO [sources] cpu: not configured +INFO [admission] cpu: not configured +INFO [caches] cpu: not configured +INFO [logs] cpu: not configured +INFO [build] cpu: Example-1.0-GCCcore-15.2.0: start +INFO [build] cpu: Example-1.0-GCCcore-15.2.0: ok +INFO [build] cpu: zlib-1.3.1-GCCcore-15.2.0: start +INFO [build] cpu: zlib-1.3.1-GCCcore-15.2.0: ok +0 +#+end_example + +eb-pipeline reports on standard error as it goes, one line per event, and exits with status 0 when every line built. + +** Read the result file + +The result file is in JavaScript Object Notation (JSON): + +#+begin_src bash +cat result.json +#+end_src + +#+begin_example +{ + "admission": [], + "build_type": "production", + "counts": { + "success": 2 + }, + "ended_at": "2026-11-17T02:40:48.852371271+00:00", + "exit_code": 0, + "kind": "result", + "lines": [ + { + "easyconfig": "Example-1.0-GCCcore-15.2.0.eb", + "exit_code": 0, + "log": "$WORK/logs/20261117_024048/cpu/Example-1.0-GCCcore-15.2.0.stdout.log", + "phase": "build", + "status": "success", + "unit": "all" + }, + { + "easyconfig": "zlib-1.3.1-GCCcore-15.2.0.eb", + "exit_code": 0, + "log": "$WORK/logs/20261117_024048/cpu/zlib-1.3.1-GCCcore-15.2.0.stdout.log", + "phase": "build", + "status": "success", + "unit": "all" + } + ], + "list": "build.list", + "log_dir": "$WORK/logs/20261117_024048/cpu", + "not_configured": [ + "licences", + "shard", + "sources", + "admission", + "caches", + "logs" + ], + "phases": [ + { + "name": "preflight", + "status": "ok" + }, +... + { + "name": "build", + "status": "ok" + }, +... + ], + "run_id": "20261117_024048", + "schema_version": 1, + "sharded": false, + "site": "example", + "started_at": "2026-11-17T02:40:48.811313154+00:00", + "target": "cpu" +} +#+end_example + +- =exit_code= is the status eb-pipeline exited with, and =counts= counts the lines by status. +- =lines= has an entry for each line, with its =status= and the =log= that its =eb= wrote to. +- =phases= has every phase of the run in order, and =not_configured= names the ones the site file leaves out. +- =20261117_024048= is the time the run started, in Coordinated Universal Time (UTC), so yours differs. + It names the run's log directory, and it is the =run_id= too, as no =--run-id= gave another. + +** Read the log of a line + +#+begin_src bash +cat logs/*/cpu/Example-1.0-GCCcore-15.2.0.stdout.log +#+end_src + +#+begin_example +eb Example-1.0-GCCcore-15.2.0.eb +EASYBUILD_BUILDPATH=$WORK/scratch/build +EASYBUILD_INSTALLPATH=$WORK/software +EASYBUILD_TMPDIR=$WORK/scratch/tmp +#+end_example + +The stand-in got the easyconfig as its argument, and the paths of the site file's =[filesystems]= as the variables that configure EasyBuild. + +** Watch a line fail + +Put a line that the stand-in fails between the other two: + +#+begin_src bash +cat > build.list <<'EOF' +Example-1.0-GCCcore-15.2.0.eb +Broken-1.0-GCCcore-15.2.0.eb +zlib-1.3.1-GCCcore-15.2.0.eb --rebuild +EOF +#+end_src + +Run the list again: + +#+begin_src bash +eb-pipeline run --site site.toml --list build.list --target cpu --build-type production --result result.json +echo $? +#+end_src + +#+begin_example +INFO [licences] cpu: not configured +INFO [shard] cpu: not configured +INFO [sources] cpu: not configured +INFO [admission] cpu: not configured +INFO [caches] cpu: not configured +INFO [logs] cpu: not configured +INFO [build] cpu: Example-1.0-GCCcore-15.2.0: start +INFO [build] cpu: Example-1.0-GCCcore-15.2.0: ok +INFO [build] cpu: Broken-1.0-GCCcore-15.2.0: start +ERROR [build] cpu: Broken-1.0-GCCcore-15.2.0: failed (exit 1) +INFO [build] cpu: zlib-1.3.1-GCCcore-15.2.0: start +INFO [build] cpu: zlib-1.3.1-GCCcore-15.2.0: ok +1 +#+end_example + +The line after the one that failed still built, and the exit status is 1: a line failed. +The new result file counts the lines: + +#+begin_src bash +grep -A3 '"counts"' result.json +#+end_src + +#+begin_example + "counts": { + "failed": 1, + "success": 2 + }, +#+end_example + +The log of the failed line ends with what the stand-in printed before it failed: + +#+begin_src bash +cat logs/*/cpu/Broken-1.0-GCCcore-15.2.0.stdout.log +#+end_src + +#+begin_example +eb Broken-1.0-GCCcore-15.2.0.eb +EASYBUILD_BUILDPATH=$WORK/scratch/build +EASYBUILD_INSTALLPATH=$WORK/software +EASYBUILD_TMPDIR=$WORK/scratch/tmp +ERROR: cannot build Broken-1.0-GCCcore-15.2.0.eb +#+end_example + +** Clean up + +Remove the work directory: + +#+begin_src bash +cd +rm -rf "$WORK" +#+end_src + +** What just happened + +1. The site file described a site of one machine: with the =local= scheduler, every phase started there as a plain process. + [[file:../explanation/design.org][Why one site file drives the build]] says why everything about a site lives in that file. +2. =run --dry-run= printed the plan, the phases of a run in their fixed order, of which this site file configures only =build=. + [[file:../explanation/phases.org][How a run goes through its phases]] describes them, and how one exit status sums up a run. +3. =run= started one =eb= for each line, in the order of the list, with the paths from the site file in =EASYBUILD_= variables and its output in a log of its own. +4. The result file recorded every phase and every line, and the exit status gave the outcome: 0 when every line built, 1 when a line failed. +5. A line that failed did not stop the run; the lines after it still built. + +** Next steps + +- [[file:../howto/index.org][The how-to guides]], for a site file for your cluster and for the jobs that call eb-pipeline. +- [[file:../reference/index.org][The reference]], for every command, site file key and exit status. +- [[file:../explanation/index.org][The explanation]], for why eb-pipeline works the way it does. + +Checked with Rust 1.90.0 and eb-pipeline at commit ef2fbe2 on 2026-11-17. diff --git a/docs/orgmode/tutorials/first-build-list/eb.sh b/docs/orgmode/tutorials/first-build-list/eb.sh new file mode 100644 index 0000000..56c26aa --- /dev/null +++ b/docs/orgmode/tutorials/first-build-list/eb.sh @@ -0,0 +1,10 @@ +mkdir -p bin +cat > bin/eb <<'EOF' +#!/bin/sh +echo "eb $*" +env | grep '^EASYBUILD_' | sort +case "$1" in + Broken-*) echo "ERROR: cannot build $1"; exit 1 ;; +esac +EOF +chmod +x bin/eb diff --git a/docs/orgmode/tutorials/first-build-list/site.sh b/docs/orgmode/tutorials/first-build-list/site.sh new file mode 100644 index 0000000..5329672 --- /dev/null +++ b/docs/orgmode/tutorials/first-build-list/site.sh @@ -0,0 +1,23 @@ +cat > site.toml </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/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..ed07e28 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,255 @@ +"""Sphinx configuration for the eb-pipeline 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 = "eb-pipeline" +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 = "" + +# Python: sphinx-autoapi reads the packages listed here, without importing +# them, into reference/api/python/. +PYTHON_PACKAGES = [] +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), + "eessi-arch-guard": ("https://stackhands.github.io/eessi-arch-guard/", 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 = "eb-pipeline" +html_baseurl = "https://stackhands.github.io/eb-pipeline/" +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": "eb-pipeline", + "source_version": "main", + "source_docs_path": "/docs/orgmode/", +} + +html_theme_options = { + "github_url": "https://github.com/stackhands/eb-pipeline", + "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-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": "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", + }, + { + "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/api-index.html b/docs/tools/api-index.html new file mode 100644 index 0000000..714f63b --- /dev/null +++ b/docs/tools/api-index.html @@ -0,0 +1,12 @@ + + + + +eb_pipeline: Rust API + + + + +

The Rust API is at eb_pipeline.

+ + 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/examples/ci/github-actions.yml b/examples/ci/github-actions.yml index 942b2b3..11579f5 100644 --- a/examples/ci/github-actions.yml +++ b/examples/ci/github-actions.yml @@ -43,8 +43,9 @@ jobs: # cancelled. GitHub keeps only one pending job per group, so a third # dispatch replaces the waiting one, which is cancelled. The group # holds across dispatches and workflows of this repository, not across - # targets: two dispatches can still build two targets at once. "One - # job per target" in the eb-pipeline README has the details. + # targets: two dispatches can still build two targets at once. The + # eb-pipeline guide "Build a list on every target from continuous + # integration" has the details. concurrency: group: eb-pipeline-${{ matrix.target }} cancel-in-progress: false @@ -56,8 +57,7 @@ jobs: # Raise max-parallel only when build_path has {target}, or sits on # storage that no two targets' build nodes share, and each target also # has its own first source path and, with staged rebuilds, its own - # state root. "One job per target" in the eb-pipeline README has the - # details. + # state root. The guide named above has the details. max-parallel: 1 # A failed target leaves the others running. fail-fast: false diff --git a/lychee.toml b/lychee.toml new file mode 100644 index 0000000..78aebb7 --- /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 rustdoc site links within itself and to the Rust documentation. + "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/eb\-pipeline/', + # 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..2b4f6c0 --- /dev/null +++ b/pixi.lock @@ -0,0 +1,3781 @@ +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/gcc_impl_linux-64-16.2.0-h9891192_7.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/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/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/libsanitizer-16.2.0-h3048135_7.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/rust-1.90.0-h53717f1_0.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/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-16.2.0-he3ce08f_107.conda + - conda: https://conda.anaconda.org/conda-forge/noarch/libstdcxx-devel_linux-64-16.2.0-h86e191b_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/rust-std-x86_64-unknown-linux-gnu-1.90.0-h2c6d0dc_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/rust-std-aarch64-apple-darwin-1.90.0-hf6ec828_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/libcurl-8.23.0-h6651222_0.conda + - conda: https://conda.anaconda.org/conda-forge/osx-arm64/libcxx-23.1.5-hc645fd0_2.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/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/rust-1.90.0-h4ff7c5d_0.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/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/gcc_impl_linux-64-16.2.0-h9891192_7.conda + sha256: 14acaa661e4c4ef6c65606612b8b08f8f079c6a9e6da3ffcb77056685c675651 + md5: f548b09900fed2701931f8cf925d8b9b + depends: + - binutils_impl_linux-64 >=2.46.1 + - libgcc >=16.2.0 + - libgcc-devel_linux-64 16.2.0 he3ce08f_107 + - libgomp >=16.2.0 + - libsanitizer 16.2.0 h3048135_7 + - libstdcxx >=16.2.0 + - libstdcxx-devel_linux-64 16.2.0 h86e191b_107 + - sysroot_linux-64 + license: GPL-3.0-only WITH GCC-exception-3.1 + license_family: GPL + run_exports: {} + size: 86085260 + timestamp: 1790303193926 +- 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/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/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/libsanitizer-16.2.0-h3048135_7.conda + sha256: e383569c331239308a8663facb76208fc0e141131ff3d17c1c2e50f34716a5a9 + md5: 9cdd9af432fa4eb62094aaf6211425bf + depends: + - __glibc >=2.17,<3.0.a0 + - libgcc >=16.2.0 + - libstdcxx >=16.2.0 + license: GPL-3.0-only WITH GCC-exception-3.1 + license_family: GPL + run_exports: + weak: + - libsanitizer 16.2.0 + size: 8115383 + timestamp: 1790303148068 +- 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/rust-1.90.0-h53717f1_0.conda + sha256: fb9070195495b51787a08430d867a120da2fce4e795df82d77ccc0c62f1ef41a + md5: fd2dd28ade0a278a119bb2a46e3a3d53 + depends: + - __glibc >=2.17,<3.0.a0 + - gcc_impl_linux-64 + - libgcc >=14 + - libzlib >=1.3.1,<2.0a0 + - rust-std-x86_64-unknown-linux-gnu 1.90.0 h2c6d0dc_0 + - sysroot_linux-64 >=2.17 + license: MIT + license_family: MIT + run_exports: + strong_constrains: + - __glibc >=2.17 + size: 227708625 + timestamp: 1758350269748 +- 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/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-16.2.0-he3ce08f_107.conda + sha256: f1e7465f6b53f89b325e441c30ad7b19407b051eca556b6d0386ec05513b8e76 + md5: f689d67c3e828fe80ff290d15f361bc5 + depends: + - __unix + license: GPL-3.0-only WITH GCC-exception-3.1 + license_family: GPL + run_exports: {} + size: 3099665 + timestamp: 1790302976359 +- conda: https://conda.anaconda.org/conda-forge/noarch/libstdcxx-devel_linux-64-16.2.0-h86e191b_107.conda + sha256: ebbad84bdebd8a9964020d74dcce0f211f1431878c66326f6115dcb59e4c3469 + md5: a713d3c09518a9fc8f603ac0e157263c + depends: + - __unix + license: GPL-3.0-only WITH GCC-exception-3.1 + license_family: GPL + run_exports: {} + size: 23329491 + timestamp: 1790303058123 +- 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/rust-std-aarch64-apple-darwin-1.90.0-hf6ec828_0.conda + sha256: 3c39f49325d0335c24ded6c2944734bb1ca3b072255a0a20942e4a0970065ad2 + md5: 051ab4f9607160ed71ad648cf0f222ab + depends: + - __unix + constrains: + - rust >=1.90.0,<1.90.1.0a0 + license: MIT + license_family: MIT + run_exports: {} + size: 34394510 + timestamp: 1758349841329 +- conda: https://conda.anaconda.org/conda-forge/noarch/rust-std-x86_64-unknown-linux-gnu-1.90.0-h2c6d0dc_0.conda + sha256: 364d902ca1b4aa1b92ff4d88e04abaa31713f02aeccd7e86ca854c0100291894 + md5: 3d77dd5f1eb34b823ea59e821c116bcf + depends: + - __unix + constrains: + - rust >=1.90.0,<1.90.1.0a0 + license: MIT + license_family: MIT + run_exports: {} + size: 38036262 + timestamp: 1758350135017 +- 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/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-23.1.5-hc645fd0_2.conda + sha256: a839afbb532798d2cb2c51306506fb4b3aa48e075319513a917bd98d7b6cb0eb + md5: 4a18f321414c5c2471fdb443ba47d7c2 + depends: + - __osx >=11.0 + license: Apache-2.0 WITH LLVM-exception + license_family: Apache + run_exports: {} + size: 567079 + timestamp: 1794552124926 +- 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/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/rust-1.90.0-h4ff7c5d_0.conda + sha256: d8af0ec389e84bd2b2f130e3be35aec799f6c556e9bc369a66a45fd44aabb350 + md5: 6a2a9ecb3dc980c89eb992afca9526f1 + depends: + - rust-std-aarch64-apple-darwin 1.90.0 hf6ec828_0 + license: MIT + license_family: MIT + run_exports: {} + size: 232594078 + timestamp: 1758350126185 +- 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/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..9d39470 --- /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 = "eb-pipeline" +channels = ["conda-forge"] +platforms = ["linux-64", "osx-arm64"] + +[feature.docs.dependencies] +python = "3.13.*" +emacs = "30.*" +curl = "*" +lychee = "*" +rust = "1.90.*" +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" } +sphinxbld = { cmd = "sphinx-build -W -n --keep-going -d docs/build/doctrees -b html docs/source docs/build/html", depends-on = ["mkrst"] } +# The rustdoc site of the eb_pipeline library, served beside the Sphinx pages +# at api/. Any rustdoc warning, such as a broken intra-doc link, fails it, and +# so does a public item without a doc comment. +rustdoc = { cmd = "cargo doc --locked --no-deps --lib --target-dir docs/build/cargo && rm -rf docs/build/html/api && cp -r docs/build/cargo/doc docs/build/html/api && cp docs/tools/api-index.html docs/build/html/api/index.html", env = { RUSTDOCFLAGS = "-D warnings -D missing_docs" }, 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 = ["rustdoc"] } +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/exit.rs b/src/exit.rs index 1318162..117ed15 100644 --- a/src/exit.rs +++ b/src/exit.rs @@ -16,7 +16,7 @@ pub const SIGINT: i32 = 130; /// Interrupted by SIGTERM. pub const SIGTERM: i32 = 143; -/// Table printed in `--help` and the README. +/// Table printed in `--help`. pub const TABLE: &str = "\ Exit codes: 0 all requested work completed @@ -43,17 +43,22 @@ when several apply: 1, then 78, then 75, then 0. Codes are never summed."; /// Error carrying the process exit code. #[derive(Debug)] pub struct Fail { + /// The exit code the program ends with, one of the constants above. pub code: i32, + /// What went wrong; the program prints it as `ERROR [main] -: `. pub msg: String, } impl Fail { + /// A failure that ends the program with `code`. pub fn new(code: i32, msg: impl Into) -> Self { Fail { code, msg: msg.into(), } } + /// A failure with [`USAGE`], 2: a wrong command line, an invalid site + /// file or input, or a tool below its `min_version`. pub fn usage(msg: impl Into) -> Self { Fail::new(USAGE, msg) } diff --git a/src/plan.rs b/src/plan.rs index 2642d01..60f0fd5 100644 --- a/src/plan.rs +++ b/src/plan.rs @@ -13,39 +13,59 @@ use std::path::{Path, PathBuf}; /// One subprocess the driver starts. #[derive(Debug, Clone, Serialize, PartialEq, Eq)] pub struct Cmd { + /// What it is: `probe:`, `shard`, `fetch:`, `admit:`, + /// `build:`, `keep-failed:`, `cache` or `rotate`. pub name: String, /// Full argument vector: launch prefix, module wrapper, tool. pub argv: Vec, /// Environment added to the phase environment. #[serde(skip_serializing_if = "BTreeMap::is_empty")] pub env: BTreeMap, + /// What to know about it, such as what its exit codes mean. #[serde(skip_serializing_if = "Option::is_none")] pub note: Option, } +/// One phase of a plan. #[derive(Debug, Clone, Serialize)] pub struct PlanPhase { + /// The phase, one of [`PHASES`]. pub name: String, - /// `planned` or `not configured`. + /// `planned` or `not configured`; `refused` for an admission that + /// `admission.required` asks for and the site file cannot provide. pub status: String, + /// Why the phase is not planned. #[serde(skip_serializing_if = "Option::is_none")] pub reason: Option, + /// The [`Role`] its commands take their launch arguments from. #[serde(skip_serializing_if = "Option::is_none")] pub role: Option, + /// The phase environment, which every command gets. pub env: BTreeMap, + /// The commands, in the order `run` starts them. pub commands: Vec, } +/// The plan file `plan` writes: every phase of a run, with its commands. #[derive(Debug, Clone, Serialize)] pub struct Plan { + /// Version of this format, 1. pub schema_version: u32, + /// `plan`. pub kind: String, + /// `site.name`. pub site: String, + /// The target's name. pub target: String, + /// The build type, `default` without one. pub build_type: String, + /// The run id. pub run_id: String, + /// The build list, as given. pub list: String, + /// Where the run writes its logs. pub log_dir: String, + /// The build list's lines, without blank lines and comments. pub lines: usize, /// Lines kept by the target's selector; absent without `[targets.select]`. #[serde(skip_serializing_if = "Option::is_none")] @@ -53,6 +73,7 @@ pub struct Plan { /// File the selected lines are written to, which `stack shard` reads. #[serde(skip_serializing_if = "Option::is_none")] pub selected_list: Option, + /// Every phase, in [`PHASES`] order, planned or not. pub phases: Vec, /// Lines left out by the target's selector. #[serde(skip_serializing_if = "Vec::is_empty")] @@ -62,10 +83,13 @@ pub struct Plan { /// A line that the target's selector left out. #[derive(Debug, Clone, Serialize, PartialEq, Eq)] pub struct Deselected { + /// The line's easyconfig. pub easyconfig: String, + /// `all`: the selector reads the whole list, before `stack shard`. pub unit: String, } +/// Every phase, in the order a run goes through them. pub const PHASES: [&str; 8] = [ "preflight", "licences", @@ -80,16 +104,22 @@ pub const PHASES: [&str; 8] = [ /// A build unit: the whole list, or one shard list. #[derive(Debug, Clone)] pub struct Unit { + /// `all`, `cpu-prerequisites`, `prelude`, or the shard's name. pub name: String, + /// [`Role::Cpu`] for the CPU prerequisites, else [`Role::Build`]. pub role: Role, + /// Its build list lines, in order. pub lines: Vec, /// Inode footprint from the shard plan. pub footprint: Option, } +/// Builds the commands of one target's run of a build list. #[derive(Clone)] pub struct Planner<'a> { + /// Where the phases run. pub scope: Scope<'a>, + /// The build list, as given. pub list_path: String, /// Scheduler job id read at run time; `None` plans the `${NAME}` placeholder. pub job_id: Option, @@ -159,6 +189,8 @@ fn stem(easyconfig: &str) -> String { pub struct StemSeq(BTreeMap); impl StemSeq { + /// The log stem of the next line with `easyconfig`: its file name without + /// `.eb`, then `.2`, `.3` and so on for later lines with the same name. pub fn next(&mut self, easyconfig: &str) -> String { let s = stem(easyconfig); let n = self.0.entry(s.clone()).or_insert(0); @@ -178,6 +210,7 @@ pub fn unique_stems(lines: &[ListLine]) -> Vec { } impl<'a> Planner<'a> { + /// A planner without run-time values, which plans placeholders for them. pub fn new(scope: Scope<'a>, list_path: String) -> Self { Planner { scope, @@ -277,6 +310,8 @@ impl<'a> Planner<'a> { Ok(v) } + /// `/`, where `stack shard` writes its plan; + /// `filesystems.shard_dir` defaults to `/shards`. pub fn shard_dir(&self) -> String { let base = self .site() @@ -323,6 +358,8 @@ impl<'a> Planner<'a> { .collect() } + /// The `stack shard` command of the shard phase, for a site with + /// `[shards]` active. pub fn shard_cmd(&self) -> Result { let s = self.site().shards_on().expect("shards active"); let mut a = vec![ @@ -396,6 +433,8 @@ impl<'a> Planner<'a> { } } + /// The `eb --fetch` command of `line`, logged as `name`, in a unit of + /// `unit_role`; the fetch of a CPU-role unit goes through its route. pub fn prefetch_cmd(&self, line: &ListLine, name: &str, unit_role: Role) -> Result { let extra = self .site() @@ -429,6 +468,8 @@ impl<'a> Planner<'a> { }) } + /// The `stack admit` command of `unit`, with its inode `footprint`, for a + /// site with `[admission]` active. pub fn admission_cmd(&self, unit: &str, footprint: u64) -> Result { let adm = self.site().admission_on().expect("admission active"); let job = self @@ -539,14 +580,20 @@ impl<'a> Planner<'a> { )) } + /// `/.stdout.log`, the output of the line's build. pub fn log_stdout(&self, stem: &str) -> String { format!("{}/{}.stdout.log", self.scope.log_dir(), stem) } + /// `/easybuild-logs/`, the line's `--tmp-logdir` with + /// `logs.keep_failed`. pub fn tmp_logdir(&self, stem: &str) -> String { format!("{}/easybuild-logs/{}", self.scope.log_dir(), stem) } + /// The command that builds `line`, logged as `stem`, with the launch + /// arguments of `role`: `eb`, or `eb-staged-rebuild run` for a staged + /// rebuild. pub fn build_cmd(&self, role: Role, line: &ListLine, stem: &str) -> Result { let mut inner: Vec; let note; @@ -604,6 +651,8 @@ impl<'a> Planner<'a> { }) } + /// The `eb-keep-logs failed` command for the line logged as `stem`, which + /// failed with exit `status`. pub fn keep_failed_cmd(&self, stem: &str, status: &str) -> Result { let a = vec![ Tool::EbKeepLogs.bin(self.site()), @@ -682,6 +731,8 @@ impl<'a> Planner<'a> { PathBuf::from(&self.site().filesystems.log_root).join(".eb-keep-logs-rotate.lock") } + /// The cache command of the target's `[[caches.targets]]` entry; `None` + /// without an active `[caches]`, its `command` or such an entry. pub fn cache_cmd(&self) -> Result, Fail> { let Some(c) = self.site().caches_on() else { return Ok(None); diff --git a/src/resolve.rs b/src/resolve.rs index 22888f4..8dc46f3 100644 --- a/src/resolve.rs +++ b/src/resolve.rs @@ -6,17 +6,26 @@ use crate::util::{package_of, split_args}; use serde_json::{json, Value}; use std::collections::BTreeMap; +/// A phase role: which launch arguments a command takes from +/// `[phase_defaults]` or the target's `phases`. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum Role { + /// The planning command, `stack shard`. Plan, + /// The builds of the whole list, the prelude and each shard. Build, + /// Admission, source prefetch and log handling. Short, + /// The CPU-only prerequisite builds; the target's `route` wraps these. Cpu, + /// The module cache command of the `caches` phase. Cache, } impl Role { + /// Every role, in the order `[phase_defaults]` documents them. pub const ALL: [Role; 5] = [Role::Plan, Role::Build, Role::Short, Role::Cpu, Role::Cache]; + /// The role's key in `[phase_defaults]` and `phases`. pub fn name(self) -> &'static str { match self { Role::Plan => "plan", @@ -47,19 +56,25 @@ pub fn role_args(site: &Site, target: &Target, role: Role) -> Option { /// Everything a phase needs to know about where it runs. #[derive(Clone)] pub struct Scope<'a> { + /// The site file. pub site: &'a Site, + /// The target the phase runs for. pub target: &'a Target, + /// The build type, which picks the target's `build_types` override. pub build_type: Option<&'a str>, + /// The run id, `--run-id`. pub run_id: String, /// Timestamp directory name under `filesystems.log_root`. pub log_stamp: String, } impl<'a> Scope<'a> { + /// The build type, `default` without one: the `{build}` of job names. pub fn build_name(&self) -> &str { self.build_type.unwrap_or("default") } + /// `//`, where this run writes its logs. pub fn log_dir(&self) -> String { format!( "{}/{}/{}", @@ -69,6 +84,8 @@ impl<'a> Scope<'a> { ) } + /// The target's `software_root`, else `software` under + /// [`Scope::install_prefix`]. pub fn software_root(&self) -> String { self.target .software_root @@ -76,6 +93,8 @@ impl<'a> Scope<'a> { .unwrap_or_else(|| format!("{}/software", self.install_prefix())) } + /// The target's `modules_root`, else `modules` under + /// [`Scope::install_prefix`]. pub fn modules_root(&self) -> String { self.target .modules_root @@ -93,6 +112,7 @@ impl<'a> Scope<'a> { }) } + /// The target's `site_prefix`, else `filesystems.install_root`. pub fn install_prefix(&self) -> String { self.target .site_prefix @@ -152,18 +172,22 @@ impl<'a> Scope<'a> { self.build_type.and_then(|b| self.target.build_types.get(b)) } + /// The build type's `eb_optarch`, else the target's. pub fn optarch(&self) -> Option { self.type_override() .and_then(|o| o.eb_optarch.clone()) .or_else(|| self.target.eb_optarch.clone()) } + /// The build type's `max_parallel`, else the target's. pub fn max_parallel(&self) -> Option { self.type_override() .and_then(|o| o.max_parallel) .or(self.target.max_parallel) } + /// The job name of `phase`: `scheduler.job_name_template` with + /// `{project}`, `{build}`, `{phase}` and `{target}` filled in. pub fn job_name(&self, phase: &str) -> String { self.site .scheduler diff --git a/src/run.rs b/src/run.rs index e8d5a77..97f02c0 100644 --- a/src/run.rs +++ b/src/run.rs @@ -71,70 +71,111 @@ fn sleep_interruptible(secs: u64) -> bool { interrupted().is_some() } +/// Print a log line on stderr: ` [] : `. pub fn log(level: &str, phase: &str, target: &str, msg: &str) { eprintln!("{level} [{phase}] {target}: {msg}"); } +/// What one phase came to. #[derive(Debug, Serialize, Clone)] pub struct PhaseResult { + /// The phase, one of [`PHASES`]. pub name: String, + /// `ok`, `failed`, `refused`, `skipped`, `unsharded`, `interrupted` or + /// `not configured`. pub status: String, + /// The exit code behind the status, when there is one. #[serde(skip_serializing_if = "Option::is_none")] pub exit_code: Option, + /// Why the phase came to its status, when that needs saying. #[serde(skip_serializing_if = "Option::is_none")] pub note: Option, } +/// What one build list line came to. #[derive(Debug, Serialize, Clone)] pub struct LineResult { + /// The line's easyconfig. pub easyconfig: String, + /// The unit it belongs to: `all`, `cpu-prerequisites`, `prelude`, or a + /// shard's name. pub unit: String, + /// `build`, or `sources` when its source fetch failed. pub phase: String, /// `success`, `failed`, `refused`, `pending`, `skipped`. pub status: String, + /// The exit code the line counts as. #[serde(skip_serializing_if = "Option::is_none")] pub exit_code: Option, + /// The command's own exit code, when `exit_code` translates it, as 78 + /// does eb-staged-rebuild's 2. #[serde(skip_serializing_if = "Option::is_none")] pub translated_from: Option, + /// The log file of the line's command. pub log: String, + /// Why the line came to its status, when that needs saying. #[serde(skip_serializing_if = "Option::is_none")] pub note: Option, } +/// What one unit's admission came to. #[derive(Debug, Serialize, Clone)] pub struct AdmissionResult { + /// The unit, as in [`LineResult::unit`]. pub unit: String, + /// How many times `stack admit` ran. pub attempts: u32, /// `admitted`, `refused` or `failed`. pub outcome: String, + /// The last JSON line `stack admit` printed. #[serde(skip_serializing_if = "Option::is_none")] pub last_json: Option, } +/// The result file `run` writes: what every phase and line came to. #[derive(Debug, Serialize, Clone)] pub struct RunResult { + /// Version of this format, 1. pub schema_version: u32, + /// `result`. pub kind: String, + /// `site.name`. pub site: String, + /// The target's name. pub target: String, + /// The build type, `default` without one. pub build_type: String, + /// The run id. pub run_id: String, + /// The build list, as given. pub list: String, + /// Where the run writes its logs. pub log_dir: String, + /// When the run started, in RFC 3339, in UTC. pub started_at: String, + /// When the run ended, in RFC 3339, in UTC. pub ended_at: String, + /// The process exit code. pub exit_code: i32, + /// Whether the lines were built in the units of a shard plan. pub sharded: bool, + /// How many lines came to each status. pub counts: BTreeMap, + /// The phases the site file leaves out. pub not_configured: Vec, + /// The admission of each unit that went through it, in order. pub admission: Vec, + /// Every phase that was reached, in [`PHASES`] order. pub phases: Vec, + /// Every line, in the order the run reached them. pub lines: Vec, /// Lines the target's selector left out; not counted as results. #[serde(skip_serializing_if = "Vec::is_empty")] pub deselected: Vec, + /// The error that stopped the run, when one did. #[serde(skip_serializing_if = "Option::is_none")] pub message: Option, + /// `SIGINT` or `SIGTERM`, when a signal stopped the run. #[serde(skip_serializing_if = "Option::is_none")] pub interrupted_by: Option, } @@ -410,7 +451,9 @@ fn release(r: Reservation, target: &str) { } } +/// How [`run`] goes through the plan. pub struct Options { + /// Print each planned command, run none, and return exit 0. pub dry_run: bool, } diff --git a/src/schema.rs b/src/schema.rs index a2e82c0..29fe847 100644 --- a/src/schema.rs +++ b/src/schema.rs @@ -10,10 +10,16 @@ use std::collections::BTreeMap; /// One documented key of the site file. #[derive(Debug, Clone, Copy)] pub struct FieldDoc { + /// The key, as the site file spells it. pub key: &'static str, + /// The type of its value: `string`, `integer`, `table`, `array of string` + /// and the like. pub ty: &'static str, + /// The default, as the reference prints it; empty when it prints none. pub default: &'static str, + /// Whether the site file must set the key. pub required: bool, + /// What the key means; also the field's rustdoc. pub doc: &'static str, } @@ -28,9 +34,11 @@ macro_rules! doc_struct { #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct $name { - $( $(#[$fm])* pub $f: $t, )* + $( $(#[$fm])* #[doc = $doc] pub $f: $t, )* } impl $name { + /// The documentation of every key of this table, in declaration + /// order. pub const FIELDS: &'static [FieldDoc] = &[ $( FieldDoc { key: stringify!($f), ty: $ty, default: $def, required: $req, doc: $doc } ),* ]; diff --git a/src/site.rs b/src/site.rs index 5c3fb58..48be2f3 100644 --- a/src/site.rs +++ b/src/site.rs @@ -596,26 +596,37 @@ impl Site { pub fn shards_on(&self) -> Option<&Shards> { self.shards.as_ref().filter(|s| s.enabled && s.count >= 2) } + /// Sources section when it prefetches. pub fn sources_on(&self) -> Option<&Sources> { self.sources.as_ref().filter(|s| s.enabled && s.prefetch) } + /// Caches section when active. pub fn caches_on(&self) -> Option<&Caches> { self.caches.as_ref().filter(|c| c.enabled) } + /// Logs section when active. pub fn logs_on(&self) -> Option<&Logs> { self.logs.as_ref().filter(|l| l.enabled) } + /// Rebuild section when active and `staged` is set in it or on a target. pub fn rebuild_on(&self) -> Option<&Rebuild> { self.rebuild.as_ref().filter(|r| { r.enabled && (r.staged || self.targets.iter().any(|t| t.staged == Some(true))) }) } + /// Licences section when active and enforced. pub fn licences_on(&self) -> Option<&Licences> { self.licences.as_ref().filter(|l| l.enabled && l.enforce) } + /// `[modules.eessi]` when active. pub fn eessi_on(&self) -> Option<&Eessi> { self.modules.eessi.as_ref().filter(|e| e.enabled) } + /// The target called `name`. + /// + /// # Errors + /// + /// A usage [`Fail`] that lists the known targets when none has the name. pub fn target(&self, name: &str) -> Result<&Target, Fail> { self.targets.iter().find(|t| t.name == name).ok_or_else(|| { Fail::usage(format!( @@ -628,6 +639,7 @@ impl Site { )) }) } + /// The `{project}` of job names: `site.project`, else `site.name`. pub fn project(&self) -> &str { self.site.project.as_deref().unwrap_or(&self.site.name) } diff --git a/src/templates.rs b/src/templates.rs index d351bb9..54a3b66 100644 --- a/src/templates.rs +++ b/src/templates.rs @@ -6,8 +6,11 @@ /// One template: its name, a one-line summary, and the file text. pub struct Template { + /// The name `init --template` takes. pub name: &'static str, + /// The line `init --list` prints after the name. pub summary: &'static str, + /// The site file, as `init` writes it. pub text: &'static str, } diff --git a/src/tools.rs b/src/tools.rs index b0878f1..2c6b28b 100644 --- a/src/tools.rs +++ b/src/tools.rs @@ -6,16 +6,23 @@ use crate::util::{cmp_version, find_version, parse_version}; use std::collections::BTreeMap; use std::process::{Command, Stdio}; +/// A sibling tool that eb-pipeline starts as a subprocess. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum Tool { + /// eb-stack, for `stack shard` and `stack admit`. EbStack, + /// eb-keep-logs, for `failed` and `rotate`. EbKeepLogs, + /// eb-staged-rebuild, for `run` on a line that rebuilds a live install. EbStagedRebuild, } impl Tool { + /// Every tool, in the order `[site.tools]` documents them. pub const ALL: [Tool; 3] = [Tool::EbStack, Tool::EbKeepLogs, Tool::EbStagedRebuild]; + /// The tool's key under `[site.tools]`: `eb_stack`, `eb_keep_logs` or + /// `eb_staged_rebuild`. pub fn key(self) -> &'static str { match self { Tool::EbStack => "eb_stack", @@ -24,6 +31,7 @@ impl Tool { } } + /// The program name looked up on `PATH` when the site file sets no `bin`. pub fn default_bin(self) -> &'static str { match self { Tool::EbStack => "eb-stack", @@ -32,6 +40,7 @@ impl Tool { } } + /// The tool's `[site.tools.]` table, when the site file has one. pub fn spec(self, site: &Site) -> Option<&ToolSpec> { let t = site.site.tools.as_ref()?; match self { @@ -41,12 +50,15 @@ impl Tool { } } + /// The program to start: the site file's `bin`, else + /// [`Tool::default_bin`]. pub fn bin(self, site: &Site) -> String { self.spec(site) .and_then(|s| s.bin.clone()) .unwrap_or_else(|| self.default_bin().to_string()) } + /// The site file's `min_version` for the tool, as written. pub fn min_version(self, site: &Site) -> Option { self.spec(site).and_then(|s| s.min_version.clone()) } @@ -143,14 +155,19 @@ fn join(v: &[u64]) -> String { /// Outcome of a staged-rebuild exit code. #[derive(Debug, PartialEq, Eq, Clone, Copy)] pub enum StagedOutcome { + /// Exit 0: the staged rebuild succeeded. Ok, /// Exit 2 in eb-staged-rebuild: refusal. Refused, /// Exit 75: a required ledger event is pending. Pending, + /// Any other exit code. Failed, } +/// Read an `eb-staged-rebuild run` exit code: 0 is [`StagedOutcome::Ok`], +/// 2 [`StagedOutcome::Refused`], 75 [`StagedOutcome::Pending`], and any other +/// [`StagedOutcome::Failed`]. pub fn map_staged(code: i32) -> StagedOutcome { match code { 0 => StagedOutcome::Ok, @@ -163,13 +180,17 @@ pub fn map_staged(code: i32) -> StagedOutcome { /// Outcome of an `eb-keep-logs rotate` exit code. #[derive(Debug, PartialEq, Eq, Clone, Copy)] pub enum RotateOutcome { + /// Exit 0: the log tree was rotated. Ok, /// Exit 75: another rotate of the tree held eb-keep-logs' lock past /// `--lock-timeout`, and this one changed nothing. Locked, + /// Any other exit code. Failed, } +/// Read an `eb-keep-logs rotate` exit code: 0 is [`RotateOutcome::Ok`], 75 +/// [`RotateOutcome::Locked`], and any other [`RotateOutcome::Failed`]. pub fn map_rotate(code: i32) -> RotateOutcome { match code { 0 => RotateOutcome::Ok, diff --git a/tests/docs.rs b/tests/docs.rs new file mode 100644 index 0000000..6b60529 --- /dev/null +++ b/tests/docs.rs @@ -0,0 +1,68 @@ +//! The site file reference, `docs/orgmode/reference/site-file.org`, against +//! the schema: one table per section of `schema::SECTIONS`, with a row per +//! key in declaration order, and the type and default `eb-pipeline schema` +//! prints. + +use eb_pipeline::schema::SECTIONS; +use std::path::PathBuf; + +fn page() -> String { + let p = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("docs/orgmode/reference/site-file.org"); + std::fs::read_to_string(&p).unwrap_or_else(|e| panic!("{}: {e}", p.display())) +} + +/// The heading of a section: `[site.tools.TOOL]`, `[[targets]]`, +/// `[targets.phases]` and the like, in verbatim, or `Top level`. +fn heading(path: &str) -> String { + if path.is_empty() { + return "Top level".into(); + } + let p = path.replace("", "TOOL").replace("", "NAME"); + match p.strip_suffix("[]") { + Some(table) => format!("=[[{table}]]="), + None => format!("=[{}]=", p.replace("[]", "")), + } +} + +/// The rows of the first table under `heading`, before the next heading, +/// as cells without the rule lines. +fn table_under<'a>(lines: &[&'a str], heading: &str) -> Vec> { + let at = lines + .iter() + .position(|l| l.starts_with('*') && l.trim_start_matches('*').trim() == heading) + .unwrap_or_else(|| panic!("site-file.org has no heading {heading}")); + lines[at + 1..] + .iter() + .take_while(|l| !l.starts_with('*')) + .skip_while(|l| !l.starts_with('|')) + .take_while(|l| l.starts_with('|')) + .filter(|l| !l.starts_with("|-")) + .map(|l| l.trim_matches('|').split('|').map(str::trim).collect()) + .collect() +} + +#[test] +fn site_file_page_has_every_key_with_its_type_and_default() { + let text = page(); + let lines: Vec<&str> = text.lines().collect(); + for (path, fields) in SECTIONS { + let h = heading(path); + let rows = table_under(&lines, &h); + assert!(!rows.is_empty(), "no table under {h}"); + assert_eq!(rows[0], ["Key", "Type", "Default", "Meaning"], "{h}"); + let keys: Vec = rows[1..].iter().map(|r| r[0].replace('=', "")).collect(); + let want: Vec<&str> = fields.iter().map(|f| f.key).collect(); + assert_eq!(keys, want, "the keys of {h}"); + for (row, f) in rows[1..].iter().zip(fields.iter()) { + assert_eq!(row[1], f.ty, "the type of {} in {h}", f.key); + let default = if f.required { "required" } else { f.default }; + assert_eq!( + row[2].replace('=', ""), + default, + "the default of {} in {h}", + f.key + ); + assert!(!row[3].is_empty(), "{} in {h} has no meaning", f.key); + } + } +} diff --git a/tests/init_and_env.rs b/tests/init_and_env.rs index fcb9357..151ce51 100644 --- a/tests/init_and_env.rs +++ b/tests/init_and_env.rs @@ -155,7 +155,7 @@ fn site_values_come_from_the_environment() { } #[test] -fn help_and_readme_list_the_codes_run_returns() { +fn help_and_the_exit_status_reference_list_the_codes_run_returns() { let o = bin().arg("--help").output().unwrap(); assert_eq!(o.status.code(), Some(0), "{}", text(&o)); let help = String::from_utf8_lossy(&o.stdout).into_owned(); @@ -166,16 +166,17 @@ fn help_and_readme_list_the_codes_run_returns() { .take_while(|l| !l.is_empty()) .filter_map(|l| l.split_whitespace().next()?.parse().ok()) .collect(); - let readme = - std::fs::read_to_string(PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("README.md")) - .unwrap(); - let readme_codes: Vec = readme + let page = std::fs::read_to_string( + PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("docs/orgmode/reference/exit-status.org"), + ) + .unwrap(); + let page_codes: Vec = page .lines() - .skip_while(|l| *l != "## Exit codes") + .skip_while(|l| *l != "** Statuses") .skip_while(|l| !l.starts_with('|')) .take_while(|l| l.starts_with('|')) .filter_map(|l| l.trim_matches('|').split('|').next()?.trim().parse().ok()) .collect(); assert_eq!(help_codes, [0, 1, 2, 75, 78, 130, 143], "{help}"); - assert_eq!(readme_codes, help_codes); + assert_eq!(page_codes, help_codes); } diff --git a/tests/targets.rs b/tests/targets.rs index 86a4f31..4cde5df 100644 --- a/tests/targets.rs +++ b/tests/targets.rs @@ -105,20 +105,37 @@ fn targets_reads_the_site_file_from_the_environment() { assert_eq!(String::from_utf8_lossy(&o.stdout), want); } +/// The command reference shows `--help` as the binary prints it. #[test] -fn the_readme_lists_targets_among_the_subcommands_and_streams() { - let readme = std::fs::read_to_string(root().join("README.md")).unwrap(); +fn the_cli_reference_lists_targets_among_the_commands_and_streams() { + let path = root().join("docs/orgmode/reference/cli.org"); + let page = std::fs::read_to_string(&path).unwrap(); assert!( - readme - .lines() - .any(|l| l.starts_with("| `targets --site FILE [--format text\\|json]` |")), - "README.md has no `targets` row in its subcommand table" + page.lines().any(|l| l.starts_with("| =targets= |")), + "{} has no `targets` row in its table of commands", + path.display() + ); + let help: String = page + .lines() + .skip_while(|l| *l != "=eb-pipeline --help= prints:") + .skip_while(|l| *l != "#+begin_example") + .skip(1) + .take_while(|l| *l != "#+end_example") + .map(|l| format!("{l}\n")) + .collect(); + let o = bin().arg("--help").output().unwrap(); + assert_eq!(o.status.code(), Some(0), "{}", text(&o)); + assert_eq!( + help, + String::from_utf8_lossy(&o.stdout), + "{}: the `eb-pipeline --help` block", + path.display() ); - let streams = readme + let streams = help .lines() - .find(|l| l.starts_with("Streams: stdout carries ")) + .find(|l| l.starts_with("Output streams: stdout carries ")) .unwrap_or_default(); - assert!(streams.contains("`targets`"), "{streams:?}"); + assert!(streams.contains(" targets "), "{streams:?}"); } #[test] @@ -203,14 +220,19 @@ fn the_ci_example_builds_a_target_for_one_dispatch_at_a_time() { "{}: the build job's concurrency", path.display() ); - let readme = std::fs::read_to_string(root().join("README.md")).unwrap(); - let text = readme.split_whitespace().collect::>().join(" "); + let guide = root().join("docs/orgmode/howto/build-from-ci.org"); + let page = std::fs::read_to_string(&guide).unwrap(); + let text = page.split_whitespace().collect::>().join(" "); for needed in [ - "The build job's `concurrency` group, `eb-pipeline-`,", - "`cancel-in-progress: false` leaves the running build alone", + "The build job's =concurrency= group, =eb-pipeline-=,", + "=cancel-in-progress: false= leaves the running build alone", "GitHub keeps only one pending job per group, so a third dispatch replaces the waiting one", "It keeps two dispatches off one target, not off one path", ] { - assert!(text.contains(needed), "README.md lacks `{needed}`"); + assert!( + text.contains(needed), + "{} lacks `{needed}`", + guide.display() + ); } }