diff options
Diffstat (limited to 'skills')
| -rw-r--r-- | skills/using-test-build/SKILL.md | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/skills/using-test-build/SKILL.md b/skills/using-test-build/SKILL.md new file mode 100644 index 0000000..2de8cbf --- /dev/null +++ b/skills/using-test-build/SKILL.md @@ -0,0 +1,88 @@ +--- +name: using-test-build +description: Use when driving the sbo-dockerbuild `test-build` tool to verify a SlackBuild builds in a container - resolving a target, choosing --stable vs -current, handling deps that current already ships, or reading its per-package status output. +--- + +# Using test-build + +`test-build` builds one SlackBuild in a throwaway Slackware docker container, builds its deps, and lints it. It is the tooling in the **sbo-dockerbuild** repo. + +**You are allowed to run `test-build` yourself.** The disposable docker container is built precisely so an agent can run it. This is the exception to the general "only the maintainer builds SlackBuilds" rule: that rule is about real `bash foo.SlackBuild` / `slackrepo` on host infra. `test-build` builds *in the container*, so drive it freely. + +## The two-source rule (get this right) + +There are TWO different package sources. Do not conflate them: + +- **Target** = the SlackBuild *under edit*. Resolved from **where you are** (CWD or a path you pass), NOT from the config tree. Always rebuilt. +- **Deps** = resolved from the **config tree** (`SBO_TREE_CURRENT` / `SBO_TREE_STABLE`). Built once and cached. + +Common mistake: `cd`ing into the config SBo tree to test an edit. Wrong. The edit lives wherever it was edited. `cd` into *that* dir. If the edit and the config tree happen to be the same dir, fine, but never assume it. + +## Target resolution + +- path (`/abs`, `./x`, anything with `/`): that dir +- bare name `foo`: `./foo/` under CWD, else CWD itself if CWD *is* `foo/` + +So all three work: `cd pkgdir && test-build foo`, `test-build /path/to/foo`, `test-build ./foo`. The dir must contain `foo.info`. + +## Standard workflow (do this, in order) + +```bash +# 1. ALWAYS dry-run first: resolve, apply overrides, print build order, build nothing. +# No image needed. This is how you learn what will happen without guessing. +cd <edited-pkg-dir> && test-build --dry-run foo + +# 2. If the order looks right, build. --yes skips the interactive confirm prompt. +test-build --yes foo # -current (default) +test-build --yes --stable foo # 15.0 +``` + +**`--dry-run` before advising or building.** Do not guess whether a dep is in the base image, or whether an override is needed. Dry-run tells you: a dep satisfied by the base or dropped simply won't appear in the order; an unresolved dep shows as UNMET. + +**`--yes` for any non-interactive run.** Without it `test-build` prints the order then blocks on `read -rp "Proceed?"`. Driving it non-interactively without `--yes` hangs. The order is still printed with `--yes`. + +## Deps that -current already ships + +15.0 is the SBo baseline; `-current` has deltas. `~/.config/sbo-testbuild/overrides` (applied **only on -current**, inert on 15.0) handles them: + +- `drop: <dep>` — a 15.0-only SBo dep whose payload -current's base already ships (`rust-opt`, `google-go-lang`, `cmake-opt`, ...). Skipped at resolution. +- `rename: <old> -> <new>` — dep renamed on -current. +- `fetch: <dep>` — dep removed from the -current tree; built via `sbopkg` in-container. + +**Do not add a `drop:` blind.** A dep may already be satisfied by `installed_in_base` (present in the full image), needing no override at all, it just won't show in the dry-run order. Only add `drop:` when the dry-run shows the dep as UNMET *and* the payload ships in current's base under a different name. When unsure, `--dry-run` is the answer, not an override. + +## Flags + +| Flag | Effect | +|------|--------| +| `--stable` | Target 15.0 (image + tree). Default is -current. | +| `--dry-run` | Resolve + print order, build nothing. No image needed. | +| `--yes` | Skip the confirm prompt (order still printed). Use for non-interactive runs. | +| `--no-cache` | Rebuild all deps this run. | +| `--keep` | Copy the built target `.txz` to `kept/` so it can be installed on the host. | +| `--no-color` | Disable ANSI color (auto-off when not a TTY). | +| `-V`, `--version` | Print version. | + +## Reading the output + +Per-package status in the summary: + +- `SUCCESS` / `CACHED` (green) — built, or dep served from cache. +- `BUILD-FAILED`, `INSTALL-FAILED`, `DOWNLOAD-FAILED`, `MD5-MISMATCH` (red) — see the named log in `RUN_DIR`. +- `UNMET-DEP` (yellow) — a dep couldn't be resolved from tree/base/overrides. Fix the tree or add an override, then rerun. +- `BLOCKED-BY-DEP` (yellow) — a dep earlier in the order failed. +- `ABORTED` — user answered no at the prompt. + +Lint runs in-container on the target only. Findings are **fail-soft**: `LINT-FINDINGS` prints but does not fail the build. `All green.` prints only when zero failed and zero blocked. + +## Setup that must exist + +- `~/.config/sbo-testbuild/config` (from `test-build-config.example`): trees, image tags, `LOG_ROOT`, `PKG_CACHE`. Missing config = hard exit with a copy-the-example message. +- Docker reachable, and the `sbo-testbuild:{current,15.0}` images built by the image-builder (pulled from the LAN registry if not local). A pure `--dry-run` skips the image check. +- `~/.config/sbo-testbuild/overrides` only if you need override rules. + +## Do not + +- Do not lint on the host. `sbopkglint` runs in-container as root; it needs the container. Never run it on a built package on the host. +- Do not assume the target lives in the config tree (see the two-source rule). +- Do not add override rules by guessing. `--dry-run` first. |