# sethLabels build scripts

Canonical recipe for building sethLabels artifacts. CI YAML at the public-flip
will call these scripts unmodified — no logic moves into YAML (spec §I3).

## Quick reference

```
./scripts/lib/deps-debian.sh         # check / install build deps
./scripts/check-no-upstream-edits.sh # enforce strict-zero (I1)
./scripts/compute-version.sh         # emit <upstream-tag>-seth<N>
./scripts/build-deb.sh               # → build/deb/glabels-qt_<VERSION>_amd64.deb
./scripts/build-appimages.sh         # → sethlabels-{gui,batch}-<VERSION>-x86_64.AppImage
```

## Prerequisites

Debian 13 (Trixie) or Ubuntu 24.04 LTS. Run:

```
./scripts/lib/deps-debian.sh
```

If anything is missing, the script prints the exact `sudo apt install ...`
command to run.

`bats` (bash test framework) is in the dep list — it's required for the
implementation tests under `tests-impl/`.

`linuxdeploy` and `linuxdeploy-plugin-qt` are NOT apt-installable; they're
downloaded automatically by `scripts/lib/linuxdeploy.sh` to `scripts/.cache/`
on first AppImage build.

## Versioning

`<upstream-tag>-seth<N>` (e.g., `3.99-master618-seth1`). The `<N>` counter is
computed from existing git tags matching `<upstream-tag>-seth*`. See spec §D4.

**Caller responsibility:** the local tag db must be fresh before running
`compute-version.sh`. Run `git fetch origin --tags` first if you're not
inside the release flow (which fetches tags as step 1).

## Release flow

See spec §6 for the canonical step-by-step. TL;DR:

```
git fetch --all --tags
git rebase upstream/master
./scripts/check-no-upstream-edits.sh
./scripts/build-deb.sh                       # ~2 min
./scripts/build-appimages.sh                 # ~5 min
VERSION=$(./scripts/compute-version.sh)
git tag "$VERSION"
git push origin main --tags
# Create Gitea release for $VERSION; attach the three artifacts.
# Bump ../homebrew-tap/Formula/glabels-qt.rb (tag + revision); commit; push.
# Smoke verify on a clean Debian 13 VM (T5).
```

## Layout

```
scripts/
├── README.md                     ← this file
├── compute-version.sh            ← pure logic; emits version string
├── check-no-upstream-edits.sh    ← guardrail enforcing I1
├── build-deb.sh                  ← end-to-end .deb pipeline
├── build-appimages.sh            ← end-to-end AppImage pipeline (GUI + batch)
├── lib/
│   ├── deps-debian.sh            ← build-dep manifest + checker
│   └── linuxdeploy.sh            ← linuxdeploy + plugin-qt bootstrapper
└── .cache/                       ← gitignored; linuxdeploy AppImages cache
```

## Tests

```
./tests-impl/run-all.sh
```

Runs the bats suite for pure-logic scripts. Build-script smoke tests (T1–T4)
are inline in `build-deb.sh` and `build-appimages.sh` — they fire automatically
on each build.

## Spec

The design rationale, invariants, and failure modes live in
[`../sethlabels-docs/specs/2026-04-29-packaging-design.md`](../sethlabels-docs/specs/2026-04-29-packaging-design.md).
Read it before changing any script.