How to run builds: commands, modules, output layout, CLI flags, and the C++
compiler toolchain. ./builder is a declarative, modular build system for the
RocketRide monorepo.
To write build tasks — a package's scripts/tasks.js, control-flow helpers,
deduplication, state, patterns — see Build System Authoring.
The recommended way to build the project is:
./builder buildThis configures the environment, resolves dependencies, and builds all modules. Use ./builder build --sequential if parallel builds cause resource issues.
# Windows
.\builder <module>:<command>
# macOS/Linux
./builder <module>:<command>| Command | Description |
|---|---|
<module>:build |
Full build with all dependencies |
<module>:compile |
Quick compile (skip setup if already done) |
<module>:clean |
Remove build artifacts |
<module>:test |
Run tests |
Not all modules support all commands. Run ./builder --help for the full list.
| Module | Description | Commands |
|---|---|---|
ai |
AI/ML modules | build, clean, test |
aparavi-ui |
Aparavi AQL chat application | build, clean, dev |
builder |
Build system maintenance | inject, update |
chat-ui |
Chat web interface | build, clean, dev |
check-externals |
3rd-party interface contract test framework | run, test |
client-mcp |
MCP Protocol client | build, clean, test |
client-python |
Python SDK | build, clean, test |
client-typescript |
TypeScript/JavaScript SDK | build, check, clean, freeze, regen, test |
docs |
Documentation site | build, check, clean, dev, export, serve, test |
dropper-ui |
File drop web interface | build, clean, dev |
events-ui |
Event monitor application | build, clean, dev |
explorer-ui |
File explorer application | build, clean |
hash |
C++ filter fingerprinting document content, for deduplication | build |
hello-ui |
RocketRide Hello — OSS landing application | build, clean, dev |
indexer |
C++ filter building the inverted word index for full-text search | build |
java |
JDK, JRE, and Maven (auto-installed for Tika) | setup-jdk, setup-jre, setup-maven |
mcp-widgets |
MCP Apps widgets (embedded UI served by the ai MCP module) | build, clean, test |
models |
LLM model sync | stamp-locals, update |
monitor-ui |
Server monitor web interface | build, clean |
nodes |
Pipeline nodes | build, clean, test, test-contracts, test-full |
parse |
C++ and Java filter extracting content from documents (Tika) | build |
profiler-ui |
cProfile process profiler | build, clean |
rocket-ui |
Data toolchain interface application | build, clean, dev |
server |
C++ engine (downloads pre-built first, or compile from source) | build, compile, clean, test, build-all, clean-all, configure-cmake, dev, package, run, setup-test-deps |
shared |
RocketRide shared source library | check-gallery-tokens, gen-gallery-tokens, test |
shell |
Shell platform (host + frozen API surface) | build, check, clean, dev, freeze, regen, regen-derived, test |
sql-ui |
SQL Explorer application | build, clean, dev |
test-ui |
Test UI application | build, clean, dev |
ui |
All UI applications | build, clean, register |
vcpkg |
C++ package manager (auto-installed for server build) | bootstrap, clone |
vscode |
VSCode extension | build, compile, clean |
world-ui |
Hello World demo application | build, clean |
./builder build
./builder server:build
./builder client-typescript:build client-python:build client-mcp:build
./builder chat-ui:build dropper-ui:build
./builder vscode:build
./builder clean
./builder server:clean nodes:clean
./builder --helpEach C++ node (hash, indexer, parse) is its own CMake project with its own
build action, for a change-build-test cycle on one node:
./builder hash:buildIt takes the engine the same way server:build does — a prebuilt download when
the local packages/server sources match a release, a source compile otherwise —
and links the node against the engine in dist/server, never a build tree.
A node also links the native packages the engine was built with. It has no
vcpkg manifest of its own, so it installs from the engine's
(packages/server/vcpkg.json) into the same build/vcpkg_installed the engine
uses, and vcpkg does that while the node configures. Nothing has to be
installed by hand — but on a tree whose engine was downloaded, the first
node build pays for the packages, which is long when the binary cache has
nothing to offer.
Changing anything under packages/server gives the engine a new build hash, and
since a node's library records the engine it was built against, every node
rebuilds with it. The reverse is not true: changing one node rebuilds that node
only.
| Directory | Contents |
|---|---|
build/ |
Temporary build artifacts |
dist/ |
Final distributable outputs |
dist/server/ |
Engine executable and runtime |
dist/server/test-logs/ |
Output of the test servers, one <suite>-server.log per suite, written with --verbose and always in CI, traced at debugOut unless --trace is given. Each run replaces the file of the previous one. When tests fail, CI prints these files into the job log (step "Show test server logs"). Not packaged. Keep --trace=debugProtocol out of CI: it logs raw messages, auth keys included |
dist/clients/ |
Client library packages |
dist/vscode/ |
VSCode extension (.vsix) |
dist/examples/ |
Example applications |
# Run a single action
./builder my-package:build
# Run multiple actions
./builder server:build nodes:build ai:build
# Run all builds (global command)
./builder build
# Run with options
./builder my-package:test --force # Force rebuild (ignore cache/state)
./builder my-package:test --verbose # Detailed output
./builder my-package:test --pytest="-s -v" # Pass pytest args
./builder build --sequential # Run modules sequentially
./builder build --autoinstall # Install missing tools automatically
./builder build --arch=arm # Target architecture (macOS cross-compile)
./builder build --suffix=cpp-nodes # Take the server from the server-v<version>-cpp-nodes release
# Show help
./builder --help
# List all actions (including internal)
./builder --list-actions
# Show dependency diagram for an action
./builder my-package:test --list-depsThe engine builds with clang 16–18 + libc++ (it doesn't compile with clang ≥ 19).
server:setup-tools (run by scripts/compiler-unix.sh) provisions it on Fedora,
Ubuntu, and macOS:
- macOS — uses the system Apple Clang (Xcode Command Line Tools) as-is.
- Linux:
- if bare
clangis 16–18 with a working libc++ andld.lld(Crashpad links with-fuse-ld=lld) → used as-is; - otherwise, by default, a self-contained LLVM 18 toolchain (latest 18.x
clang+llvmrelease, bundles its own libc++) is unpacked into~/toolchains/llvm-18— user-local, no root, system compiler untouched. The builder points the build at it viaPATH/CC/CXX/LD_LIBRARY_PATH.
- if bare
dump_syms(crash-symbol generator) is fetched into~/toolchains/bin(root-free) and added to the buildPATH.
Both install the non-compiler build dependencies via apt/dnf (needs root). They
differ only in where the C++ compiler goes:
--autoinstall(default) — keeps clang local: uses the system clang if it's already 16–18, else the~/toolchains/llvm-18toolchain. Never touches the system compiler.--autoinstall --system-compiler— installs a compatible clang system-wide via the package manager and repoints the defaultclang++:- apt — the distro's default
clangif it's 16–18 (e.g. Ubuntu 24.04), else clang-18 from the distro archive or apt.llvm.org (e.g. Ubuntu 22.04) +update-alternatives. - dnf — only if the default
clangis 16–18; Fedora's clang-22 has no matching libc++, so it falls back to the~/toolchainstoolchain. - Needs root. If root isn't available (or
sudocan't authenticate non-interactively) it errors and asks you to run withsudoor drop--system-compiler— it does not silently fall back to the tarball.
- apt — the distro's default
Root-free ~/toolchains downloads (the LLVM toolchain, dump_syms) install
automatically, with or without --autoinstall. Distro packages install only
under --autoinstall. Anything placed in a user home (~/toolchains) is installed
as the invoking user — never as root — even when the script runs under sudo.
A binary's glibc floor is set by the build host, not the compiler. Building on
Ubuntu 22.04 (glibc 2.35) with either the tarball or apt.llvm.org clang-18 produces a
binary that runs on 22.04 and newer; building on 24.04 (glibc 2.39) would not
run on 22.04. So release/CI builds run on the oldest supported LTS (currently
ubuntu-22.04), and --system-compiler there installs clang-18 via apt.llvm.org
(faster than the tarball, same glibc floor). The clang version never changes the floor.
To compile outside the builder (e.g. a raw cmake/ninja invocation), source the
env helper to point CC/CXX/PATH/LD_LIBRARY_PATH at the same toolchain:
. scripts/setenvs.shIt uses ~/toolchains/llvm-18 if present, otherwise the system clang, and always
adds ~/toolchains/bin (for dump_syms) to PATH.