BuildLang Usage Guide

This guide covers installing the buildc compiler and using its real command surface. BuildLang compiles .bld source files to C as the primary verified execution path and emits HLSL/GLSL for shader work, with additional experimental backends.

All commands and flags below are taken from the compiler's actual CLI definition (compiler/src/main.rs). The worked examples were run against a local build of buildc 1.2.0 on Windows; the captured output is shown verbatim. Output captured from an actual run is marked (verified); any output that was not run is marked (illustrative).

Install / Build

From crates.io (installs the buildc binary):

cargo install buildlang

Formerly published as quantalang (deprecated). Use buildlang / buildc.

Or build the compiler from source with Cargo:

cd compiler
cargo build --release

Add the produced binary to your PATH:

• Linux/macOS: compiler/target/release/buildc
• Windows: compiler\target\release\buildc.exe

Confirm your local toolchain (C compiler, stdlib, optional backend tools):

buildc doctor

Command Reference

These are the subcommands exposed by buildc (run buildc --help for the authoritative list and buildc <command> --help for per-command flags):

Command	Purpose
buildc <file>	Compile a file (no subcommand); honors -o, --target, --stdio-mode, -O, -g
buildc run	Compile and run a .bld file via the C backend; --stdio-mode portable-lf gives byte-stable LF stdout/stderr; --emit-receipt/--invariant/--units seal a scientific-runtime receipt; --gpu (with a --features gpu build) dispatches a #[compute] kernel on Vulkan
buildc build	Build a project (`--emit c
buildc check	Type-check; optional --receipt, --policy, --profile
buildc lex	Tokenize a file and print tokens
buildc parse	Parse a file and print the AST (--json for JSON)
buildc fmt	Format source (--check, --write)
buildc lint	Lint a source file
buildc repl	Start a REPL session
buildc lsp	Start the Language Server Protocol server
buildc watch	Watch files and recompile on change (`--target spirv
buildc pkg	Package manager (init, add, resolve, search)
buildc policy	Built-in check policy profiles (list, print, scaffold)
buildc receipt	Re-verify a saved receipt (verify) or export witnessed measurement rows (export)
buildc corpus	Verify the semantic corpus (verify)
buildc mir	Emit or load the versioned buildlang.mir/v0 JSON form (emit, load)
buildc bdf	Build Data Format: encode, decode, validate, flagship-action bridges
buildc test	Run .bld programs against .expected files
buildc doctor	Diagnose local toolchain, backend, and package readiness
buildc version	Print version information

Top-level compile flags

When invoked without a subcommand (buildc <file>):

• -o, --output <FILE> -- output file path
• --target <NAME> -- code generation backend (see below)
• --stdio-mode <native|portable-lf> -- generated-program stdio behavior for the C backend. native is the default; on Windows it keeps CRT text-mode CRLF translation. portable-lf switches stdout and stderr to CRT binary mode on Windows so \n is emitted as LF bytes, and is rejected for non-C targets.
• -O, --opt-level <0-3> -- optimization level (default 0)
• -g, --debug -- emit debug information
• -v, --verbose -- verbose output

Code generation targets

--target (and buildc build --target) accepts:

Target	Flag value(s)	Status
C	c (default)	Primary
HLSL	hlsl, dx, directx	Supported
GLSL	glsl, opengl, gl	Supported
Rust	rust, rs	Experimental
LLVM IR	llvm, llvm-ir, ll	Experimental
WASM	wasm, wasm32, wat	Experimental
SPIR-V	spirv, spir-v, spv	Experimental
x86-64	x86-64, x86_64, x64	Experimental
ARM64	arm64, aarch64	Experimental

buildc build --stdio-mode portable-lf and buildc run --stdio-mode portable-lf apply the same C-runtime mode as top-level compilation. Native mode remains the default for all command forms.

Worked Examples

The repository ships tested quickstart programs under examples/quickstart/. The examples below use those files so they stay aligned with the compiler.

1. Run a program

examples/quickstart/hello.bld:

fn main() ~ Console {
    println!("Hello from BuildLang!");
}

println! is a Console capability, so main declares the ~ Console effect. Compile and run via the C backend:

buildc run examples/quickstart/hello.bld

Output (verified):

Hello from BuildLang!

The ledger.bld example (functions, mutable locals, a while loop):

buildc run examples/quickstart/ledger.bld

Output (verified) -- 100 + 5*3:

balance: 115

2. Compile to C and build by hand

Emit C and compile it with your system C compiler:

buildc examples/quickstart/hello.bld -o hello.c
cc hello.c -o hello
./hello

The first command prints (path will be your output path) (verified):

Compiled examples/quickstart/hello.bld -> hello.c

The generated C begins with // Generated by BuildLang Compiler and a portability prelude before the lowered program.

For byte-stable stdout/stderr across Windows and POSIX receipt lanes, compile or run through the C backend with --stdio-mode portable-lf:

buildc --stdio-mode portable-lf examples/quickstart/hello.bld -o hello.c
buildc run examples/quickstart/hello.bld --stdio-mode portable-lf

Portable LF mode changes only generated-program stdout/stderr mode. It does not promote experimental targets and is refused when paired with a non-C backend.

3. Type-check with a capability policy and receipt

buildc check type-checks and reports capability effects. Add --profile to evaluate a built-in policy and --receipt - to print a machine-readable accountability receipt to stdout:

buildc check examples/quickstart/hello.bld --profile console-only --receipt -

The human summary is printed first, then the JSON receipt. Output begins (verified):

Lexing... OK (15 tokens)
Parsing... OK (1 items)
Type checking... OK

No errors found in 'examples/quickstart/hello.bld'
{
  "schema": "buildlang-check-receipt/v1",
  "compiler": "buildc",
  "compiler_version": "1.2.0",
  "language_version": "1.0.0",
  ...
  "status": "passed",
  "declared_effects": {
    "main": [
      "Console"
    ]
  },
  ...
}

List the built-in policy profiles with:

buildc policy list

Output (verified):

Built-in check policy profiles:
  pure           deny all built-in ambient capability effects
  console-only   allow Console only; deny other ambient capability effects
  offline        allow local file/env/clock/console work; deny network/process/FFI/GPU
  ci-review      require digests and deny Network, Process, Foreign, and Gpu
  strict-accountability require digests, exact allowlists, and deny Network/Process/FFI/GPU

Save a receipt to a file and re-verify it later against the current source:

buildc check app.bld --profile ci-review --receipt receipt.json
buildc receipt verify receipt.json --expect-profile ci-review

4. Compile a shader to HLSL

examples/quickstart/vignette_shader.bld defines a #[fragment] entry point. Compile it to HLSL for ReShade / DirectX:

buildc examples/quickstart/vignette_shader.bld --target hlsl -o vignette_shader.hlsl

The command prints (verified):

Compiled examples/quickstart/vignette_shader.bld -> vignette_shader.hlsl

The generated HLSL (verified, excerpt):

// Generated by BuildLang Compiler
// Target: HLSL (DirectX / ReShade)
// Do not edit manually

float vignette(float uv_x, float uv_y, float strength, float softness) {
    float dx = (uv_x - 0.5);
    float dy = (uv_y - 0.5);
    float dist = sqrt(((dx * dx) + (dy * dy)));
    float vig = smoothstep(0.5, (0.5 * softness), dist);
    return (1.0 - (strength * (1.0 - vig)));
}

float4 PS_Vignette(float4 pos : SV_Position, float2 uv : TEXCOORD) : SV_Target0 {
    float4 color = tex2D(ReShade::BackBuffer, uv);
    float vig = vignette(uv.x, uv.y, 0.5, 0.6);
    return float4((color.x * vig), (color.y * vig), (color.z * vig), 1.0);
}

Use --target glsl to emit GLSL for OpenGL / Vulkan instead.

More

• Introduction and first ten minutes: docs/INTRODUCTION.md
• A runnable demo: examples/demo
• Quickstart programs: examples/quickstart
• Getting started tutorial: docs/GETTING_STARTED.md
• Capability effects reference: docs/EFFECTS_GUIDE.md
• Shader output reference: docs/SHADER_GUIDE.md
• Architecture and design: DESIGN.md