The compiler

Actions

vxc runs one action per invocation. The default is run-jit.

vxc --run program.vx
vxc -c program.vx -o program.o
vxc --emit-mlir program.vx

Optimization is -O0 through -O3, defaulting to -O0.

Hardware and machine models

--diagnostics-json is the one to reach for in a build script or a CI job. The schema is versioned, and a capacity rejection carries the space, the requirement, the availability and the margin as fields rather than as prose you would have to parse out of a message.

Note that with --verify-seams and no solver on PATH, the compile fails rather than certifying seams it could not check. VX_ALLOW_UNVERIFIED=1 downgrades that to a warning.

Where imports come from

An import that starts with a package name reads only that package (see below). vxc looks for any other import in two places, in this order:

1. The standard library. An installed toolchain keeps it in stdlib/ beside bin/, and a development build uses the stdlib/ of the source tree it was built from. --std-path DIR replaces it. Give the flag once for each directory.
2. The directory of the file you compile, so import helper; reads the helper.vx beside it.

vxc never searches the current directory, so a command gives the same result wherever you run it.

Packages

--package name=dir makes a library in another directory importable by name. With --package textkit=../textkit, import textkit::runs reads ../textkit/runs.vx. Imports that start with textkit are read from that directory only, and the stdlib paths stay as they are. Give the flag once for each package.

vxc --package textkit=../textkit main.vx -o main

Separate compilation

--emit-interface writes a .vxlib: the module’s frozen registry and portable flat-HIR bodies. A downstream compile consumes it with --link-interface and resolves calls into that module without parsing its source.

vxc --emit-interface lib.vx -o lib.vxlib
vxc --link-interface lib.vxlib main.vx -o main

The .vxlib format carries a version tag, and a compiler rejects artifacts written by a different one. Regenerate them when you upgrade the toolchain rather than keeping them in a cache.

Version numbers

vx-api diff compares the interfaces of two versions of a library and prints the smallest safe version bump. An added item needs a minor release. A removed item, or a change that breaks a caller, needs a major one. Anything else is a patch.

vx-api diff old/lib.vxlib new/lib.vxlib

Every item in a .vxlib counts as public, because a program can call any of them. The tool cannot see traits, data-carrying enums, constants or the bounds of generic parameters, because a .vxlib does not hold them.

The other tools

vx-format has no options worth learning: there is one canonical style, and it applies it.

vx-format src/*.vx

The standard library

21 modules, imported as std::<name>. Every type and function is listed in the standard library reference, generated from the sources.

Beyond std the toolchain ships graph, imported as graph::traversal and friends.

The repository also carries examples/llama.vx, a Llama 2 inference port, and an early packages/vx_linalg. Several other package directories exist under packages/ but are still empty placeholders — do not plan around them yet.

Environment variables

An installed toolchain sets the first several of these for you through a wrapper script, so you normally need none of them.