Skip to content

Getting started

This page builds piac, proves a first program, compiles it, and sets up VS Code.

Requirements

  • Bazelisk. Pia builds with Bazel, at the version in .bazelversion. Bazelisk reads that file and fetches the right Bazel. On macOS, brew install bazelisk.
  • A C++17 compiler. On macOS, Xcode or its command line tools. On Linux, Clang or GCC.
  • Network access to the Bazel Central Registry and GitHub for the first build, which fetches LLVM, MLIR and Z3.

Pia is developed on Apple Silicon Macs. Everything except running the compiled code builds on Linux as well, since piac cross-compiles to arm64.

Build

git clone https://github.com/deanberris/pia-lang.git
cd pia-lang
bazel build //tools/piac //tools/pia-lsp

The first build compiles the parts of LLVM and MLIR that Pia uses, which takes 15 minutes or more. Later builds reuse the disk cache in ~/.cache/pia-bazel-disk, including after bazel clean.

The compiler is now at bazel-bin/tools/piac/piac. The examples below call it piac, so put it on your PATH or make an alias:

alias piac="$PWD/bazel-bin/tools/piac/piac"

Run the tests with:

bazel test //...

Prove a program

Save this as clamp.pia:

let clamp (lo : i32) (hi : i32) (x : i32) : i32
  requires lo <= hi
  ensures lo <= result && result <= hi
  ensures lo <= x && x <= hi ==> result = x
= if x < lo then lo else if x > hi then hi else x

requires is a precondition: callers must prove it, and the body may assume it. ensures is a postcondition, where result is the value returned. Ask piac to prove it:

$ piac --verify clamp.pia
clamp.pia:3:3: proved: the postcondition holds [smt]
clamp.pia:4:3: proved: the postcondition holds [smt]
2 proved, 0 failed, 0 skipped

Each line is one goal, a fact the compiler had to establish, with its source location and how it was proved: intervals for the cheap range analysis, smt for Z3. The exit status is 0 when nothing failed.

Now break it. Change the postcondition to the wrong claim ensures lo < result, and piac shows inputs where it is false:

let clamp (lo : i32) (hi : i32) (x : i32) : i32
  requires lo <= hi
  ensures lo < result
= if x < lo then lo else if x > hi then hi else x
$ piac --verify clamp_bad.pia
clamp_bad.pia:3:3: failed: the postcondition holds
  counterexample: lo = 1028093, hi = 2147483647, x = 0
0 proved, 1 failed, 0 skipped

The counterexample is an input that breaks the claim. Here x is below lo, so clamp returns lo, and lo < lo is false. Z3 picks whichever values it finds first, so they can look arbitrary, but they always break the goal.

Compile a program

piac --emit=obj proves the program, then compiles it to an object file for Apple Silicon. Code is generated only when no goal fails.

piac --emit=obj -o clamp.o clamp.pia

Each Pia function becomes a C function with the same name, so you can call it from C. A C declaration for clamp is:

#include <stdint.h>
int32_t clamp(int32_t lo, int32_t hi, int32_t x);
cc main.c clamp.o -o main

The C ABI section of the codegen notes says how slices, arrays and records are passed. Other outputs stop earlier in the pipeline: --emit=mlir prints the Pia dialects, --emit=core the core MLIR dialects, --emit=llvm the LLVM IR and --emit=asm the assembly.

piac at a glance

Command What it does
piac --verify f.pia prove every goal and print a report
piac --emit=obj -o f.o f.pia prove, then compile to an arm64 object file
piac --emit=asm f.pia prove, then print arm64 assembly (also llvm, core)
piac --emit=mlir f.pia print the program in Pia's MLIR dialects
piac --verify --emit=mlir f.pia both, with each proved op marked pia.proved
piac --dump-smt f.pia print each SMT query sent to Z3
piac --dump-ast f.pia print the syntax tree
piac --dump-expanded f.pia print the syntax tree after metaprograms run
piac --check f.pia parse only

--target=<triple> and --cpu=<name> choose the machine (default arm64-apple-macosx14.0.0 and apple-m1), and -O0 to -O3 the optimisation level (default -O2). --meta-cycles=N caps metaprogram expansion (default 32).

The exit status is 0 on success, 1 when the program has an error or a goal fails, and 2 for a usage error.

VS Code

The VS Code extension in editors/vscode runs pia-lsp, Pia's language server. It shows failed goals with their counterexamples as errors in the editor, the proofs of each expression on hover, syntax errors as you type, go to definition, an outline and completion.

bazel build //tools/pia-lsp
cd editors/vscode
npm install
npx vsce package
code --install-extension pia-0.1.0.vsix

Then point the extension at the server in VS Code's settings:

"pia.server.path": "/path/to/pia-lang/bazel-bin/tools/pia-lsp/pia-lsp"

By default it verifies when you save. Set "pia.verify.on": "change" to verify as you type. The extension's README lists the settings and how to use pia-lsp from Neovim, Helix, Emacs, Zed or Sublime Text.

Next