---
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.