Compiler command-line reference

General commands

prismio build <source.psm> [-o output] [options]
prismio run <source.psm> [options]
prismio bootstrap [source.psm] [-o output]
prismio check <source.psm> [--diagnostic-format=json]
prismio dump-ast <source.psm>
prismio aif <source.psm> [aif-options]
prismio runtime-hash
prismio --version

Passing a .psm file without a command is accepted as a build shorthand. Prefer the explicit form in scripts.

The same commands with no source named act on the project the nearest ancestor build.ums describes, and a project may declare commands of its own that are invoked the same way:

prismio init [name]
prismio build|run|test|clean [--release]
prismio <declared-command> [args...]

Built-in commands take precedence, so a manifest cannot redefine one. See the build.ums reference for project configuration and declared commands.

--help prints the command summary. --version reports the Prismio compiler and linked/pinned LLVM version information used to identify documentation compatibility.

build

prismio build components/main.psm -o build/app

build resolves source/imports, runs compiler analysis, emits LLVM IR, and—unless the output ends in .ll—creates and links a native artifact. The input file's directory is the source import root.

If -o is omitted, the driver chooses its current default output. Automation should pass an explicit path so artifacts do not depend on host naming conventions.

run

prismio run components/main.psm

run performs a build and launches the resulting program after successful compilation. Compiler or linker failure exits nonzero and does not execute a stale artifact as though it were the requested program.

bootstrap

prismio bootstrap components/main.psm -o build/prismio-next

bootstrap is the compiler-development path. It builds the compiler with repository backend/runtime sources rather than linking only the installed application runtime. Prefer repository bootstrap scripts for multi-generation and platform-specific orchestration.

Inspection commands

dump-ast runs imports and semantic analysis through dumpAstCommand() and prints JSON consumed by the independent AIF oracle. The schema is an internal compiler/oracle contract rather than a public application protocol, but changes must update the oracle and differential fixtures together.

runtime-hash prints the identity used to reason about the embedded/installed runtime content. It helps distinguish a compiler built with different runtime sources.

Build options

-O0 through -O3 control the in-process LLVM module pass pipeline. Native object generation uses the build driver's current Clang policy; -g deliberately changes the program object step to -O0. Record the complete compiler version and command in benchmarks rather than treating the front-end flag as a frozen whole-toolchain recipe.

--verify adds supported allocation/free lifecycle instrumentation. It can change performance and is intended for testing. --debug selects conservative analysis/debug behavior; it is not a promise of an integrated source debugger.

--target calls targetSelect() and asks LLVM for the triple's pointer width and data layout. The native build still requires a matching packaged runtime or target C environment. WebAssembly target selection does not by itself provide browser or WASI packaging.

AIF options

Unknown commands and malformed flags exit nonzero. The default AIF report is an interactive interface and may evolve; use aif --manifest when automation needs the stable line-oriented protocol.

Dispatch implementation

main() gives project-shaped invocations to dispatchToUmsHost() and the UMS command layer; a source argument selects the single-file driver.

--internal-host-abi <token> is answered before dispatch and is deliberately absent from --help. It is a protocol between two compilers: the command prints this executable's own PRISMIO_HOST_ABI and exits 0 only when the argument matches. The launcher runs it against toolchain.host before forwarding anything, and a compiler predating the command rejects the argument as unknown and exits 1 — which is the same answer. Answering it before dispatch is what keeps the reply about the binary asked rather than about the host it would otherwise forward to, and what stops the launcher's own probe from recursing. See Compiler host and promotion. cliAif() parses analysis flags and calls aifCommand(). cliBootstrap() fixes compiler-build mode and accepts only source, -o, and -g. The build/run parser validates incompatible pairs such as --jit with --target before calling compileSource().

Exit behavior

Successful inspection/build operations exit zero. Invalid arguments, missing input, compilation failure, IR verification failure, object/link failure, or a failed run step produce a nonzero result.

Do not parse color, whitespace, or prose from interactive commands as a stable API. For AIF records use --manifest; for other commands assert the exit status and expected artifact, and for negative compiler tests match only the diagnostic fragment needed to identify the rule.

Script examples

Build a debuggable IR artifact:

prismio build components/main.psm -o build/main.ll -O0

Build a verified native test artifact:

prismio build tests/ownership.psm -o build/ownership-test --verify

Inspect one allocation decision:

prismio aif components/main.psm --why=request_buffer

Because the CLI is pre-1.0, scripts should also pin prismio --version and fail early when it differs from the expected toolchain.