cli-build

name

cli-build

description

Build Xenolith apps/projects through the `xenolith-cli` installer tool — the SDK command front-end. Use whenever asked to build, rebuild, run, or compile-check a Xenolith project or app in this repo (e.g. "build the installer", "build utils/installer", "rebuild the CLI", "build tests/window", "run the app", "does it compile"). Drives the toolchain's own make with STAPPLER_ROOT + PATH wired correctly — NEVER hand-roll `gmake`/`make`/`clang`/`cmake`; the CLI is the supported path once an SDK is installed.

Building a Xenolith project via xenolith-cli

xenolith-cli is the installed SDK front-end (/usr/local/bin/xenolith-cli, source at utils/installer/cli). It drives a project's Makefile through the toolchain's own GNU make (the host toolchain's bin/make, NOT the host OS make/gmake), with STAPPLER_ROOT (engine root), PATH, and the toolchain-store→engine symlinks wired up. This is the only supported way to build a project/app once the SDK is provisioned.

Golden rules

• Always use xenolith-cli build, never raw gmake/make/clang. gmake only bootstraps the CLI itself; after that the CLI builds everything (it even builds itself — see self-build below).
• A successful build ends with built <path> for <triple> (<debug|release>). Treat that line + exit 0 as the pass signal. Do not eyeball logs.
• The engine must be present. xenolith-cli build resolves STAPPLER_ROOT from: --engine <path> > $XENOLITH_ENGINE > the cloned default ref (<data>/engines/<ref>). If none is valid it errors — install/clone one first.
• The host + target toolchains must be installed in the shared store (xenolith-cli install <triple>, or xenolith-cli install to provision all). The CLI symlinks them into the engine tree at build time.
• .cpp/.c are compile units; .cc files are #include-only subunits. Don't try to compile a .cc alone — build the .cpp SCU that includes it.

Build command

xenolith-cli build <project-path> [--engine <path>] [--target <triple>] [--release] [--run]

• <project-path> — a directory containing a Makefile (defaults to .).
• --engine <path> — engine root override (else resolved from env/installed ref). Use a local checkout (e.g. this repo) when iterating on engine code: --engine /Users/vitaliyry/PET_PROJECTS/xenolith-engine.
• --target <triple> — cross target (default = native host triple). Cross builds run make install (cannot --run on the host).
• --release — optimized (-O2 -DNDEBUG); else debug (-g).
• --run — after a native build, exec the produced binary (CLI apps: terminal; GUI apps: opens a window).

Output lands in <project>/stappler-build/<target>/<debug|release>/cc/ — a bare binary on Linux, a .exe on Windows, a <name>.app bundle on macOS.

First time on a machine (provision the SDK)

xenolith-cli install                 # engine (git clone) + native host + native target (+sprt)
# or step by step:
xenolith-cli engine-install <ref>    # clone engine branch/tag (default: master; use 'stage'/'installer-cli')
xenolith-cli install <host-triple> --host
xenolith-cli install <host-triple> --target
xenolith-cli install <triple>        # one triple that is both host and target → installs both

Inspect state any time: xenolith-cli detect (native triple), xenolith-cli list (catalogue + install status), xenolith-cli paths, xenolith-cli state, xenolith-cli verify.

Common build targets in this repo

Build	Command
GUI installer (xenolith-installer.app)	xenolith-cli build utils/installer --engine <engine>
The CLI itself (xenolith-cli)	xenolith-cli build utils/installer/cli --engine <engine>
Engine test apps (tests/window, tests/runtime, …)	xenolith-cli build tests/<name> --engine <engine>
A scaffolded project	xenolith-cli new MyApp && xenolith-cli build MyApp --run

After building a GUI app, launch it on macOS with open <name>.app (or add --run to the build). Run the scene-inspector skill to debug the window.

Self-build (the CLI builds the CLI)

The CLI is self-hosting — once bootstrapped, it rebuilds itself:

xenolith-cli build utils/installer/cli --engine <engine>

(Bootstrap from zero uses gmake -C utils/installer/cli -j8 once; after that, always prefer the CLI.)

Engine iteration

To build against engine changes you're editing locally, point --engine at this repo: the build reads make/, stappler/, xenolith/ straight from there, with the installed toolchains symlinked in. No re-clone needed.

When NOT to use this skill

• Building a fresh toolchain/sysroot, or cross-compiling an SDK target that is not an app project — use the lower-level xenolith-build skill / make flow.
• The SDK isn't installed and you only need a compile check of engine sources on the host — a host gmake of a tests/* app is fine (see xenolith-build).