Compiler command-line reference

General commands

prismio build <source.psm> [-o output] [options]
prismio run <source.psm> [options] [-- program-args...]
prismio check <source.psm> [--diagnostic-format=json] [--overlay <file.psm> <text>] [--module <name>]
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 [--release] [target...]
prismio run [--release] [target] [-- program-args...]
prismio test [--release] [test...]
prismio clean [--release]
prismio <declared-command> [args...]

A word that does not end in .psm is a target's name, so prismio build server builds the target server rather than looking for a file of that name.

Built-in commands take precedence, so a manifest cannot redefine one. See the package manager for the manifest and for declaring commands.

--help prints the command summary and, inside a project, the commands its manifest declares; --help-all adds the compiler-development commands and flags. An argument error names the problem and points at --help rather than printing the whole page. --version reports the Prismio compiler and linked/pinned LLVM version information used to identify documentation compatibility, plus the compiler and standard-library directories it resolved — the quickest way to confirm which toolchain is in use.

Which toolchain ran the command

When a project declares toolchain.host, the installed compiler is a launcher: it hands the whole command to that project-local compiler. It says which one it used, on stderr:

Using local toolchain: /repo/.prismio/build/debug/prismio
Using global toolchain: /opt/homebrew/opt/prismio/bin/prismio

You see global when the declared host is missing, was not built on this machine, will not start, or is from an older toolchain generation than the compiler you invoked. A host this machine did not build — one that came with a cloned repository — is never run, for any command (P1077); prismio build builds one. An older-generation host is rebuilt first, and the launcher says so (P1064). A project with no toolchain block has made no such choice and prints neither line.

The banner is suppressed whenever the command's stdout is a format, so --diagnostic-format=json and aif --manifest stay parseable.

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. Everything after -- is passed to the program exactly as typed, and run exits with the program's own exit status. Compiler or linker failure exits nonzero and does not execute a stale artifact as though it were the requested program.

prismio run components/main.psm -- --port 8080

There is no bootstrap command. The Prismio compiler is built from its repository's build.ums, which names its C sources like any other project's, and tools/bootstrap.sh (tools/bootstrap.ps1 on Windows) builds one from the release seed, which it fetches and checks first, on a machine with no Prismio at all.

Inspection commands

check runs everything build does up to code generation — imports, parsing, type checking, ownership — and reports the diagnostics without producing a program. --diagnostic-format=json writes them one JSON object per line for an editor. A file that is one module of a larger program is checked through that program, since its imports resolve against the program's entry and it may use names the program shares: prismio check src/main.psm --overlay src/parse/stmt.psm buffer.psm checks the program with buffer.psm's text standing in for stmt.psm, which is how an editor checks unsaved changes. --module std.map checks a standard-library module on its own.

dump-ast parses a source entry and prints the compiler's current AST representation for development. The textual representation is diagnostic/internal and is not a stable machine protocol.

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 set the level the whole program, standard library included, is optimised and compiled at. With no flag a build is -O3, or -O0 with -g; -g -O2 gives an optimised program you can still step through. -O0 builds fastest: the hosted benchmark program builds in 0.30 s at -O0 and 0.86 s at -O3.

-Os and -Oz trade speed for size. On the same program the code is 36% smaller at -Os and 55% smaller at -Oz, which also outlines repeated instruction sequences into shared ones. Neither is a default, because both make the program slower.

With -o file.ll, the flag applies to the IR written. Record the complete compiler version and command in benchmarks.

--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.

WebAssembly changes target layout/pointer width but does not provide complete browser or WASI packaging.

Freestanding options

For a program with no operating system under it. See freestanding programs.

--freestanding is for a bare-metal --target such as aarch64-unknown-none-elf or i686-unknown-none-elf, and needs ld.lld on PATH. It admits import std.option, std.platform and std.iter and no other std module (P1094).

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.

Benchmarks

prismio bench is a command of the Prismio source repository's own build.ums, not a built-in: it runs benchmarks/run.py against the compiler that checkout builds, so it exists only inside a checkout. Every argument after bench goes to the runner.

prismio bench
prismio bench --suite hosted --runs 9
prismio bench --suite freestanding --only fibonacci --scale 4

The hosted suite compares Prismio with C++ and Rust on the host operating system and reports time. The freestanding suite compares Prismio with C and Rust on bare-metal AArch64 under QEMU and reports guest instructions; see freestanding benchmarks. Both land in one results.json and one report, in tabs.

Exit behavior

Successful inspection/build operations exit zero. Invalid arguments, missing input, compilation failure, IR verification failure, or object/link failure produce a nonzero result. run and a project command exit with the status of the program or step that ran, so a program that returns 3 makes prismio run exit 3.

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.