Build targets

Define targets

A target can choose the runtime, preset, build tier, backend, host bindings, and artifact directory:

{
  "name": "MyApp",
  "version": "0.1.0",
  "build": {
    "preset": "release",
    "buildTier": "optimized",
    "defaultTarget": "host",
    "targets": {
      "host": {
        "runtime": "embedded",
        "backend": "auto",
        "bindings": ["c", "python"],
        "outputDirectory": "Generated/host"
      },
      "web": {
        "runtime": "embedded",
        "backend": "wasm",
        "bindings": ["js", "typescript"],
        "outputDirectory": "Generated/web"
      }
    }
  }
}

Shared fields may live directly under build. Each target overrides only what differs. Names such as host and web are labels chosen by the project. They do not select a compiler backend by themselves.

Build or inspect a target

wax build
wax build --target web
wax targets
wax targets --json

With one target, Wax selects it automatically. With several, set defaultTarget or pass --target. wax targets resolves manifest inheritance without compiling; values omitted from the manifest remain - in text or null in JSON. * marks the default. The compiler applies its documented defaults when the build runs. The JSON form is available to build tools.

Target fields

When a C build first uses a custom compiler configuration, Wax compiles and runs a qualification program under the selected tier policy. The compiler must preserve Wax's integer layout and floating point semantics and support the GNU C features used by generated code. Wax rejects an incompatible compiler and caches a successful result for that compiler executable, version, target, arguments, tier policy, and qualification version.

Wax owns the flags that enforce its build and determinism rules. It rejects custom arguments that try to replace the optimization level, target, compile mode, output path, or floating point policy. Wax then appends -fno-fast-math and -ffp-contract=off, plus SSE arithmetic flags on x86 targets that could otherwise use x87.

Configure the driver and any compiler arguments together:

{
  "build": {
    "cCompiler": {
      "command": "/opt/llvm/bin/clang",
      "arguments": ["--sysroot", "/opt/sdk"]
    }
  }
}

Each item in arguments is passed as one argument. Wax does not split strings or invoke a shell.

Configuring cCompiler makes auto choose C, including for instant and balanced builds. Select native explicitly when the custom driver is needed only for final Native linking. That request still fails when Native does not support the host, runtime, or output.

native emits machine code directly from Wax IR. It compiles far faster than the C path and is the best choice for the edit and run loop. Its output currently runs at roughly half the speed of the C backend compiled by Clang at -O2. Choose an optimized C build when runtime performance is the priority.

auto uses Wax's native backend for instant and balanced release builds when the host, runtime, and output support it. It uses generated C for optimized builds. An explicit native request fails when unsupported instead of changing backends.

Because optimized is the default tier, a plain wax build with auto uses C. Pass --build-tier instant during iteration to let auto select Native.

Embedded targets must choose bindings. Use an empty array when the host needs no generated binding files.

Override one build

Command line options replace individual fields from the selected target. Other settings still come from wax.json:

wax build --target host --backend wasm --bindings js,typescript
wax build --standalone

Use --oneshot, --standalone, or --embed to replace the target's runtime. Use --bindings none to request no binding files from the command line. Use --bindings-dir <directory> to place all selected bindings and their shared runtime files together. Repeat --binding-output <language>=<path> only when a host layout needs a destination specific to one language; that language's shared runtime sibling follows the overridden binding.