Documentation channel: current development main at compiler checkpoint 1d7e15e. The latest tagged release is v0.0.3; pages identify APIs that are not yet released.

CLI

Strut keeps the common path short: compile one file by passing it directly to strut, or initialise a project when you want persistent configuration, incremental object builds, tests, packages, and formatter workflows.

Compile one file

The source filename is enough for the ordinary case. Strut writes a native executable beside the source using the source stem as its name.

strut hello.p

Choose the output path

strut hello.p -o bin/hello

Explicit compile command

compile is available when a command-shaped invocation is clearer in scripts, but it does not represent a separate compilation mode.

strut compile hello.p -o bin/hello

Check source without linking

--check runs the front end and semantic checks without generating a native executable.

strut --check hello.p

Inspect lexer output

strut --dump-tokens hello.p

Initialise a project

strut init creates .strut/config.json and, when absent, a minimal strut.json manifest. It does not replace existing project metadata. The build configuration records the entrypoint, output, target, default build mode, linking mode, and incremental strategy.

strut init

Inspect project discovery

strut project reports the discovered root, build configuration, manifest, and platform package-cache path. Use --json for tooling.

strut project
strut project --json

Machine-readable API index

strut api --json is the authoritative discovery surface for coding agents and editor tooling. It includes built-in signatures, methods, checked errors, runtime components, native dependencies, standard modules, and CLI commands.

strut api http
strut api --json
strut api --json sqlite
strut api --json checked-errors

See the API discovery schema for fields and compatibility guarantees.

Example configuration

{
  "entrypoint": "src/main.p",
  "output": "app",
  "target": "native",
  "mode": "debug",
  "linking": "dynamic",
  "incremental": "modified"
}

Build a project

strut make discovers the project root, loads .strut/config.json, builds the configured entrypoint and semantic dependencies, and reuses current native objects.

strut make

Release project build

strut make --release

Explain rebuild decisions

strut make --verbose

Incremental native objects

Objects live under .strut/obj/<target>/<mode>/. Generated bootstrap C++ is kept separately under .strut/gen/, while .strut/info/ stores one JSON metadata file per object.

The metadata records the source, object, local/package dependencies, embedded resources, compiler version, target, mode, and build fingerprint. A unit is rebuilt when an object or metadata file is missing, metadata is invalid, its dependency graph changes, its build fingerprint changes, or a dependency timestamp is equal to or newer than the metadata timestamp. Equal timestamps are deliberately conservative so coarse filesystems do not hide edits.

Run tests

The first native test convention is deliberately small: Strut discovers tests/**/*_test.p, builds each test as a normal native Strut program, and considers exit code zero a pass. Tests run in deterministic path order and sequentially by default.

strut test

Filter tests

The optional filter is a substring matched against each discovered test path.

strut test parser

Format source

strut fmt applies Strut's canonical indentation and type spelling while preserving comments. The formatter only accepts syntactically valid source; it does not silently repair missing mandatory semicolons.

strut fmt

Format one path

strut fmt src/main.p

Check formatting without writing

strut fmt --check

Packages

strut add ../my-package
strut list
strut install
strut install --offline
strut update
strut packages
strut packages --json
strut remove my-package

install preserves and verifies an existing lock, update explicitly re-resolves it, and install --offline forbids acquisition. Use packages --json for deterministic graph, revision, checksum, source, and cache-health data.

Command help

strut help
strut help make
strut test --help

Exit codes

Compiler diagnostics and profiling

strut main.p --release --timings -o main
strut main.p --release --emit-cpp generated.cpp

--timings reports coarse load/parse, semantic, IR and native-backend timing. --emit-cpp is primarily a bootstrap/profiling tool: it emits the generated C++ and stops before invoking the host compiler.