StarPilot/docs/how-to/laptop-device-build.md

Laptop and device builds

./build uses a Linux/ARM64 container and a matching AGNOS sysroot on a laptop. On an actual AGNOS/aarch64 device it runs SCons natively in that checkout, using the device Python environment and vendored source imports. It does not copy host-built model files into a device build. The container image pins Cap'n Proto 1.0.1 to the generated cereal contract in this tree.

Prepare the build environment

Install Docker or Podman with Linux/ARM64 support. Run scripts/laptop_device_build.sh doctor to see which local prerequisites are missing. The first setup/build can download a container image, Python dependencies, and an AGNOS system image; run it only when you intend that network activity.

To prepare without a physical device, run:

scripts/laptop_device_build.sh setup

To use an explicitly supplied device sysroot instead, run scripts/laptop_device_build.sh setup-sysroot <device-host> [user] [ssh-port], then scripts/laptop_device_build.sh build-image. The build does not connect to a device or flash firmware. The compatibility alias scripts/starpilot_build_flow.sh laptop-setup invokes the same explicit setup.

If the matching AGNOS ext4 system image is already local, use scripts/laptop_device_build.sh setup-sysroot-local <system-image-path> instead. This extracts a separate ignored .comma_sysroot; it does not change the image. Verify its VERSION against the intended device OS. A sysroot copied from a different AGNOS build does not establish ABI compatibility.

Build

./build                 # complete device-target build
./build 8               # complete build with eight SCons jobs
./build --params        # current params shared library only
./build --cereal        # cereal libraries, bridge, and service header
./build --panda         # signed panda_h7 and body_h7 firmware targets only
./build --panda 8       # same H7 targets with eight jobs
./build --mapd          # explicit offline Mapd provider package, separate from SCons

--mapd cannot be combined with SCons targets or jobs. It builds the pinned Linux/ARM64 static Mapd binary and manifest in ignored openpilot/starpilot/maps/provider/. It does not download map regions, change the selected offline snapshot, start Mapd, or run during plain ./build.

The Mapd shortcut requires Go 1.25.1 and an already populated module cache. On Linux/ARM64 it uses a local Go executable. On other hosts it uses the openpilot-local-mapd-builder:go1.25.1 Linux/ARM64 image, built explicitly from tools/laptop_device_build/Dockerfile.mapd:

docker build --platform linux/arm64 -f tools/laptop_device_build/Dockerfile.mapd \
  -t openpilot-local-mapd-builder:go1.25.1 .
mkdir -p .cache/mapd-go-modules
docker run --rm --platform linux/arm64 \
  --mount "type=bind,src=$PWD/mapd_repo,dst=/work,readonly" \
  --mount "type=bind,src=$PWD/.cache/mapd-go-modules,dst=/gomodcache" \
  -e GOMODCACHE=/gomodcache -w /work \
  openpilot-local-mapd-builder:go1.25.1 go mod download
./build --mapd

The image build and module-cache population above are explicit network setup steps. ./build --mapd itself uses --network none, --pull never, GOPROXY=off, and a read-only module cache. An existing offline cache can be selected with COMMA_MAPD_MODULE_CACHE; an existing reviewed ARM64 Go image can be selected with COMMA_MAPD_BUILD_IMAGE. The generated package is checked for the exact source digest and ARM64/static format by package_shadow.py. It is a build artifact; stage it separately with the source manifest for a device, rather than treating the source-only checkout as containing it.

The historical wrapper's other Panda variants are not targets in the current panda/SConscript; --panda does not claim to build them. Shortcut targets use --no-scrub and leave prebuilt alone. Other SCons arguments pass through the container helper. A full-build invocation with options or explicit targets cannot mark prebuilt: clean, question, and dry-run commands do not compile the complete default graph. scripts/starpilot_build_flow.sh laptop-device [jobs] is the compatibility alias for a complete ./build.

The complete build selects the current comma_arm64 SCons profile in its container, including Ion-backed VisionIPC and QCOM model compilation. It checks the driving model, driver-monitoring model, camera warps, and core runtime libraries before setting prebuilt. QCOM model compilation may require device-class hardware even with an ARM64 container; if it cannot complete, the build fails and prebuilt remains unset. A local DEV=METAL model artifact is not a device build substitute.

scripts/laptop_device_build.sh verify-artifacts inspects the outputs without loading pickle files: it requires ARM64 ELF objects, exact current camera warp dimensions, and QCOM captured backends. It does not run inference. The matching sysroot is passed to Clang at both compile and link time. For a cached compatible base image, COMMA_BASE_IMAGE=<local-image> overrides the Dockerfile's default base only while building the image; record that override when reporting build provenance.

For a single explicit target, use scripts/laptop_device_build.sh scons --no-scrub <target>. Sysroot, cache, and build-venv path overrides must resolve to direct children of this checkout. Relative overrides resolve from the checkout root before Docker bind mounts. The doctor command checks availability only; it does not prove the image or sysroot can compile every target.

scripts/laptop_device_build.sh manager remains an explicit container runtime mode for developers with a complete build. Neither ./build nor the checks above launch it. It can start ordinary manager processes; review that mode separately before using it with connected hardware.

The legacy alias also supports verify, mac, and device. mac checks Python compilation only and does not produce device binaries. device requires AGNOS on ARM64 hardware and is never part of laptop validation.