Development environment

Compiler development requires the checkout's pinned LLVM, a C toolchain, Python for the test harness, and either an installed Prismio compiler or the release bootstrap seed (fetched for you). Run setup commands from the compiler repository root: the bootstrap scripts resolve src, runtime, bootstrap, and third_party/llvm-paths.json relative to that checkout.

Required tools

• The pinned LLVM, which tools/setup_llvm.py downloads into third_party/llvm. Do not install one.
• A platform linker and SDK appropriate for the host: Xcode Command Line Tools on macOS, cc and the C library development files on Linux, Visual Studio's C++ tools on Windows.
• Python 3.9 or newer for tests, packaging, and support scripts.
• Git and ordinary shell tooling.

The LLVM a compiler is built against belongs to the checkout, not to the machine. tools/setup_llvm.py downloads LLVM 23.1.1, checks the archive against a SHA-256 recorded in the script, and prepares it under third_party/llvm. It does not look at Homebrew, apt or llvm-config. The download resumes after a stall or a dropped connection, and running the script again once setup has finished does nothing.

The official macOS and Linux archives ship no shared LLVM library, and their static archives are ThinLTO bitcode. Setup therefore lowers the members the compiler uses to native objects once, which takes about 75 s on ten cores, and writes third_party/llvm/link.rsp naming them. Every compiler link after that is an ordinary static link with the system linker, so a compiler binary loads no LLVM at run time and a brew upgrade llvm cannot break it. On Windows, the archive's LLVM-C.lib is linked and LLVM-C.dll is copied beside the compiler.

--check reports without changing the checkout; --force re-downloads and re-prepares; --keep-all keeps LLVM tools the build never runs, which setup normally prunes; and --llvm-dir DIR adopts an existing install. An adopted install is linked dynamically and is not pinned, so use it only as a deliberate opt-in. PRISMIO_LLVM_DIR does the same for a single command.

python3 tools/setup_llvm.py --check
python3 tools/setup_llvm.py

The pinned third_party/llvm/bin/clang is still used, but only to compile the runtime's C to bitcode during bootstrap and packaging, because that bitcode has to come from the same LLVM that reads it. Programs are optimized and emitted in process, and the object is linked by the system's cc. See Runtime platforms and packaging.

Choose the compiler explicitly

The test runner honors PRISMIO before PATH. Point it at the generation you intend to test:

PRISMIO=$PWD/.prismio/build/debug/prismio python3 tests/test_runner.py

If no installed compiler is available, build the first generation from the release IR seed (fetched and checked on first use), then build two self-hosted generations:

python3 tools/bootstrap.py --seed --out build/gen0
python3 tools/bootstrap.py --compiler build/gen0 --out build/gen1
python3 tools/bootstrap.py --compiler build/gen1 --out build/gen2

tools/bootstrap.py is the same script on Windows; --compiler builds from an existing generation (without it the committed seed is used; --seed <path> names another) and --promote installs the last generation as the checkout's local toolchain. Once a compiler exists, build.ums declares the repository's own commands: prismio bootstrap (the three steps above; --promote adds that flag), prismio seed, prismio build, prismio suite, prismio verify, prismio gate and prismio release (see how a release is cut). The compiler links three LLVM backends, AArch64, X86 and WebAssembly; they are listed in runtime/prismio_llvm.h and tools/setup_llvm.py, and tools/check_source_lists.py fails if the two disagree. The committed seed (bootstrap/seed.ll) only has to be able to parse src/; a newer one is cut with prismio seed (tools/refresh_seed.py) and committed only when the maintainer says so. The script compiles the LLVM bridge and runtime support, consume the same source inventory, use a content-keyed object cache, link into a temporary path, and install the completed compiler atomically. PRISMIO_LLVM_DIR overrides recorded LLVM discovery. PRISMIO_OBJ_CACHE=0 disables the cache when investigating it.

For fixed-point work, use a named generation such as build/gen2. For the normal repository loop, use prismio build; build.ums routes project commands to .prismio/build/debug/prismio once the local host exists and this machine has promoted it. A copied binary is not run (P1077); see the local compiler loop.

Validate the setup

build/gen2 --version
python3 tools/package.py --compiler build/gen2 --out build/dist
PRISMIO=$PWD/build/dist/bin/prismio python3 tests/test_runner.py --list
PRISMIO=$PWD/build/dist/bin/prismio python3 tests/test_runner.py test_92_field_view_provenance

A bare generation can build compilers but not ordinary programs, because a program links the runtime as installed bitcode beside the executable, so the tests run against the packaged compiler.

--version prints Prismio, loaded LLVM, compiler executable, and the resolved standard-library directory. Treat an unexpected compiler or (none found) stdlib as a setup error before debugging the language change.

Platform notes

On macOS, Apple's cc and the SDK from the Command Line Tools link programs, and LLVM comes only from third_party/llvm. On Linux, the distribution's cc and C library development package are all the system has to provide. On Windows, use the repository PowerShell bootstrap and packaging paths rather than translating shell commands by hand.

On macOS, debug builds can produce a .dSYM; on Windows, keep MSVC target and SDK selection consistent. Cross-target compilation also needs the target SDK via --sysroot and a matching runtime-<triple> package. LLVM target support alone does not provide a platform runtime.