Build Wax projects

Check before building

cd MyProject
wax check

check reads the application and installed package sources without producing an artifact. It is the quickest compiler check to run while editing and in CI.

Build the project

wax build

A normal build reads its runtime, backend, bindings, and output directory from wax.json. Wax supports three application shapes:

Override the runtime for one build with --oneshot, --standalone, or --embed:

wax build --oneshot
wax build --standalone
wax build --embed --bindings c

The source must provide the entry points for the runtime you select; these flags do not convert a one-shot program into a standalone loop.

--runtime is a wax new option, not a build option. An embedded override must also choose bindings; use --bindings none when no binding files are needed.

Use wax targets to see the available targets and their manifest settings after inheritance. Omitted values stay omitted in this report; the compiler defaults described below apply when a build runs. Select another target with --target:

wax targets
wax build --target web

Build choices

Wax keeps these choices separate:

The native backend turns Wax IR directly into machine code. It does not generate C or ask Clang to compile the Wax program, so it compiles far faster and should be the go to backend while iterating. Wax emits the object directly, then uses the compiler driver for final native linking. In current benchmark coverage, native output runs at roughly half the speed of the C backend compiled by Clang at -O2. Use an optimized C build when final runtime performance matters more than build time.

wax build --build-tier instant

auto chooses Native for instant and balanced release builds when the platform, runtime, and output support it. It chooses C for optimized builds. With auto, profiling, iOS, and combinations that do not support Native use C. An explicit native request fails when unsupported instead of changing backends.

release and optimized are the defaults, so a plain wax build with auto uses C. The instant command above lets auto choose Native on a supported host without a backend flag. A debug build may still be optimized; it preserves the program structure needed by the debugger. Command line options override the selected target for one build:

wax build --preset debug --build-tier balanced

Compiler guides

Host bindings

Embedded builds can generate bindings for C, C++, C#, Java, Python, Rust, Swift, JavaScript, and TypeScript. The bindings describe the selected Wax API, host functions, lifecycle, and boundary types. Continue with the embedding guides to connect the result to a host application.

Use --bindings <languages> --bindings-dir <directory> for a single build override. Every selected application binding and its shared runtime sibling is written to that directory with its canonical filename. When a host layout requires a specific application filename, repeat --binding-output <language>=<path> for only those exceptions.

For a complete example, create a project named MyApp and place its bindings in separate host repositories. Java application filenames must match the manifest name (MyApp.java here):

wax new MyApp --yes
cd MyApp
wax build --embed --bindings java,cpp \
  --binding-output java=../java-app/src/main/java/wax/MyApp.java \
  --binding-output cpp=../cpp-app/generated/myapp_wax.hpp

Each shared runtime sibling follows its language binding, so this writes WaxBindings.java into the Java tree and wax_bindings.hpp into the C++ tree.

Use waxc directly

wax build and wax check invoke waxc. Use the compiler executable directly for integration work or repeated detailed overrides:

cd MyProject
waxc --check
waxc --target web

C builds and final Native linking go through a C driver. Wax accepts Clang and GCC, and identifies which one it is from the driver's own --version output. GCC is supported on macOS and Linux; Windows requires Clang, because the output has to match the MSVC ABI.

Wax takes the first driver it finds, in this order: --c-compiler, the project's cCompiler setting, WX_C_COMPILER, CC, then clang, cc, or gcc on PATH. The last three make an ordinary machine work with no configuration, and CC means an environment that already names its compiler does not have to name it twice. When nothing is found, Wax names every source it tried, so the fix is visible.

Naming a driver with the flag or the project file also says something about the build: it makes auto choose the C backend, and it conflicts with --backend wasm. Naming one through WX_C_COMPILER or CC does neither. An environment variable answers which driver to use if a C build happens; it never changes what gets built, and never turns a wasm build into an error.

Repeated --c-compiler-arg options pass sysroot, SDK, include, or linker arguments without a shell. They require --c-compiler, because arguments are specific to the driver they are written for. However the driver was chosen, Wax makes it compile and run a qualification program before the first C build, checking the integer, floating point, and GNU C behavior Wax requires; a driver that fails is rejected, named along with where it came from. Wax rejects conflicting arguments and appends the flags that enforce its determinism rules. The build target guide describes the checks and injected flags.

Run waxc --help for the options supported by the installed compiler.