32 lines
2.8 KiB
Markdown
32 lines
2.8 KiB
Markdown
# ctrl/standalone.sh
|
|
|
|
## Purpose
|
|
|
|
Generates the standalone kits: single-file versions of rig's own tools, one folder per profile, for machines the full rig is not going to.
|
|
|
|
A kit is a pure function of rig as it is right now. It gains nothing rig lacks and loses nothing rig has: improve rig, regenerate, and every kit follows. Nothing in `standalone/<profile>/` is ever edited by hand.
|
|
|
|
## The contract
|
|
|
|
What this file does NOT know, on purpose: which tools rig has, what they are called, how its libraries are split, where configuration lives or what it contains. Rig will change shape (scripts get split, renamed and grow new libraries), and a generator that encoded today's layout would quietly produce a wrong kit the first time it did. So it works from a contract a script opts into, and from nothing else:
|
|
|
|
1. A marker comment, alone on a line near the top, declares an entry point: `(hash) rig:standalone <kit-name> <default-verb>`. The default verb must only REPORT: it is run as a smoke test.
|
|
2. Every `source` an entry point makes names a `.sh` file by a path that resolves relative to the entry point. Libraries may source further libraries however they like; bash follows those itself.
|
|
3. Configuration enters through `load_config`, and the libraries provide `config_profiles`, `config_freeze <profile|--current>` (which prints a replacement `load_config` with that resolution frozen in) and, for an export, `config_current_profile` and `config_left_out`. How config is layered, stored, derived or frozen is rig's business; the generator only asks, and embeds the answer without interpreting it.
|
|
|
|
## Bash does the resolving
|
|
|
|
Bash does the resolving, not a parser in the generator. Libraries are sourced in a clean shell and read back with `declare -f` and `declare -p`, so any structure bash can load, this can flatten.
|
|
|
|
## Every kit is proven before it is written
|
|
|
|
Every kit is PROVEN to stand alone before it is written: no `source` left, no path into rig's tree in its code, `bash -n` clean, and its default verb run in an empty directory with nothing from rig present. A shape the generator has never seen either passes that, or generation stops and names the kit, the file, the line and what is wrong. It never writes a kit that only looks finished.
|
|
|
|
## Usage: write, check, export
|
|
|
|
- `standalone.sh write`: generate every kit into `standalone/<profile>/`.
|
|
- `standalone.sh check`: generate into a scratch dir and fail if any kit differs.
|
|
- `standalone.sh export DIR`: ONE kit for the configuration this machine runs (its profile plus the choices in its local config, WITHOUT its credentials), written outside the repo.
|
|
|
|
`write` and `check` are what gets committed: one kit per profile, identical on any machine. `export` answers the other question, "take the setup I have here somewhere else", so it reflects this machine, and for exactly that reason it never lands in the repository.
|