# Building Vanta

This is the whole job for a build host. Nothing in the source tree needs editing by hand:
every Vanta change reaches the build through `tools/apply.sh`, which is idempotent.

## Host

x86_64 Linux (Ubuntu 22.04/24.04 or Debian 12), at least 16 cores, 64 GB RAM and 400 GB free.
`tools/preflight.sh` prints what this host has. Run as root (bootstrap installs packages).

## Build

```sh
git clone https://vanta.failure.fail/git/vanta/vanta.git /home/workspace/vanta-kit
cd /home/workspace/vanta-kit

VANTA_DEVICE=b5q tools/host-run.sh          # Galaxy Z Flip5  (default)
VANTA_DEVICE=gsi_arm64 tools/host-run.sh    # GSI, any arm64 Treble phone
```

`host-run.sh` runs every step below in order, stops at the first failure, and logs to
`/home/workspace/vanta-run.log` (`tail -f` it). It pulls the kit first, so re-running it after a
fix pushed to VantaGit picks the fix up. The Android source tree goes to `/home/workspace/vanta`
(set `SRC=` to move it). The first sync downloads roughly 150 GB (plus ~2 GB of Google apps, fetched with git-lfs).

| Step | Script | What it does |
|---|---|---|
| pull | `git pull` | Updates this kit (skip with `VANTA_PULL=0`) |
| profile | `tools/lib/profile.sh` | Loads `devices/$VANTA_DEVICE.env` (product, manifest, make target) |
| start | `tools/host-bootstrap.sh` | apt packages, `repo`, ccache |
| stage | `tools/stage.sh` | Renders the boot animation (or downloads it from the VantaGit release) |
| sync | `tools/sync.sh` | `repo init` LineageOS `lineage-24.0` + the device manifest, `repo sync` |
| apply | `tools/apply.sh` | Lays `vendor/vanta`, the SystemUI patches, fonts, recovery art; ends in `verify_tree.py` |
| build | `tools/build.sh` | `lunch`, `m bacon` (phones) or `m systemimage` (GSI) |

## Output

| Device | File |
|---|---|
| `b5q` | `out/target/product/b5q/Vanta-0.1-<date>-b5q.zip` (+ `.sha256sum`) |
| `gsi_arm64` | `out/target/product/generic_arm64/Vanta-0.1-<date>-gsi_arm64.img.xz` (+ `.sha256sum`) |

`build.sh` prints the full path on its last line: `build: ok <path>`.

## If a step fails

Read the last 40 lines of `vanta-run.log`; the line `== FAILED at <step>` names the step.

- **sync**: GitHub rate limiting. `sync.sh` already backs off from `-j16` to `-j2`; just re-run.
- **fdprobe**: the host ran out of file handles (a gVisor box limit, not `ulimit`). Restart the box.
- **apply / verify_tree**: a printed `FAIL` line says which assumption about the Lineage tree
  broke (a moved hook, a missing blob repo, a resource Vanta overlays). That needs a kit change,
  not a tree edit: report the `FAIL` lines.
- **apply / patches**: `FAIL frameworks/base <patch>` means upstream moved under a patch. Report it.
- **build**: the error is above `build: m ... failed` in `out/vanta-build.log`
  (`grep -n "error:" out/vanta-build.log | head`). Report the first error with its file path.

Do not hand-edit files under the source tree to get past a failure: `apply.sh` restores its
inputs on the next run, and `sync.sh` resets the projects Vanta touches.

## Options

| Variable | Default | Effect |
|---|---|---|
| `VANTA_DEVICE` | `b5q` | `b5q`, `gsi_arm64`, or `beyond2lte` (S10+, cancelled, kept buildable) |
| `SRC` | `/home/workspace/vanta` | Android source tree |
| `LOG` | `/home/workspace/vanta-run.log` | Run log |
| `VANTA_PULL` | `1` | `0` = do not `git pull` the kit first |
| `VANTA_GAPPS` | `true` (b5q, GSI) | Google apps (MindTheGapps, synced by the device manifest). `false` = a build without Google |
| `VANTA_WITH_BRIDGE` / `VANTA_WITH_HALO` | `false` | Optional prebuilt APKs; only from Zo, where their projects live |

Second variant: `tools/build.sh /home/workspace/vanta user` builds `user` instead of `userdebug`.
