Provisional API: This reference documents current compiler behavior. Compatibility is not yet promised.

src/build.x

Typed native build request and artifact graph.

Functions

Functions

build_check_input

void build_check_input(String input)

Exits with a driver error unless input names a regular file. A wildcard or directory operand adds a note on what to pass instead.

Source: src/build.x:211

build_hash_bytes

uint64_t build_hash_bytes(uint64_t hash, const void *bytes, size_t length)

Returns hash extended with length bytes by 64-bit FNV-1a.

Source: src/build.x:84

compile_commands_write

int compile_commands_write(String path, Array commands)

Publishes collected native compilation entries as one JSON database. commands holds serialized entries from each completed build target. The destination’s parent must exist. A failed write preserves the existing database, reports a diagnostic, and returns zero.

Source: src/build.x:542

Build

Build.add_generated

void Build.add_generated(Build state, String input, String directory)

Registers generated artifacts for native compilation. Counts the C and header bytes, appends the C source, and adds include directories and native compile options for imported packages. Programs also add ordered package archives and link flags; an absent archive prints a diagnostic and exits with status 2. Static libraries skip link inputs.

Source: src/build.x:431

Build.begin_translation

void Build.begin_translation(Build state, String input)

Starts translation reporting for input and initializes timing when unset.

Source: src/build.x:444

Build.cleanup

void Build.cleanup(Build b, int success)

Removes the temporary work tree after a successful real build. Failed builds, retained directories, and dry runs are left untouched; a removal failure emits a warning and is not returned to the caller.

Source: src/build.x:876

Build.end_translation

void Build.end_translation(Build state, String input, int cached)

Records one completed translation and reports the phase when all finish. A nonzero cached value also increments the cached-translation count.

Source: src/build.x:452

Build.finish

int Build.finish(Build b)

Compiles registered C sources and then archives or links the final output. Returns zero for success and one when compilation or the final native action fails. Compile-only requests stop after objects. Static archives reuse their recorded inputs; executables always link because library selection and implicit linker inputs are not in the fingerprint. The archiver or linker writes a private sibling that replaces the output by rename, so a concurrent build in the same project finds the whole previous artifact or the whole new one. Mapped macOS debug executables also produce a companion dSYM before cleanup; failed symbol assembly fails the build and preserves intermediates.

Source: src/build.x:716

Build.generated_dir

String Build.generated_dir(Build state, String input)

Returns the generated-file directory for input. The directory is derived from the input path and created unless this is a dry run. Native registration belongs to Build.add_generated.

Source: src/build.x:322

Build.publish_script

void Build.publish_script(Build b, String executable)

Moves a script’s built executable, and its debug symbols on macOS, to executable and records what it was built from, so CliRequest.script_current can reuse it. The record lists the script’s translation and compile prerequisites, package archives, and the runtime archive. A file changed while the build ran records nothing, so the executable is never reused for source it was not built from.

Raises: <io-fail> when the executable cannot be moved.

Source: src/build.x:978

Build.record_translation

void Build.record_translation(Build state, String input, String directory)

Records the successful translation fingerprint when retained state exists. Dry runs, incomplete fingerprints, and a source edited while the build ran are ignored, so the generated C is never reused for an input it does not match. Writing the private state file is best effort; after a write or rename failure, cleanup attempts to unlink the temporary file but cannot guarantee its removal.

Source: src/build.x:372

Build.report_success

void Build.report_success(Build b)

Prints the completed build receipt and artifact details when enabled.

Source: src/build.x:806

Build.run_program

int Build.run_program(Build b)

Runs the built output with the request’s arguments and returns its status. A dry run prints the action without launching the program.

Source: src/build.x:861

Build.script_helpers

List Build.script_helpers(Build b)

Returns the local .x files a script unit includes, which the script’s program must translate and link. The script’s translation depfile already lists every file the translation read, so helpers of helpers appear too. Runtime and package sources are excluded; their objects are archived.

Source: src/build.x:954

Build.translation_current

int Build.translation_current(Build state, String input, String directory)

Reports whether translated C and header artifacts match current inputs. Returns zero without retained state, during a dry run, when either output is absent, or when any compiler, tool, option, depfile, or dependency fingerprint cannot be read or differs.

Source: src/build.x:351

CliRequest

CliRequest.prepare

Build CliRequest.prepare(CliRequest c)

Validates a native build request and returns its Scope-owned build state. It writes the default state seed and selected compiler and archiver back to request, chooses output and intermediate paths, and creates artifact directories unless this is a dry run. Invalid inputs or setup print a diagnostic and exit with status 2.

Source: src/build.x:235

CliRequest.script_current

int CliRequest.script_current(CliRequest c, String directory)

Reports whether the script executable under directory still matches everything recorded when it was built.

Source: src/build.x:1007

Public types

Build

typedef struct Build { CliRequest request; Toolchain toolchain; String work_dir, gen_root, obj_root, dep_root, state_root, output; int temporary, Array c_sources, gen_dirs, native_inputs, objects, units; String compile_directory, Array compile_commands; unsigned long started_at; double started_wall; unsigned long xlat_start; unsigned long cc_start; unsigned long final_at; unsigned long long gen_bytes; int xlat_n, xlat_done, xlat_cached, cc_n, cc_done, cc_cached, final_cached; } *Build

Holds Scope-owned mutable state for one prepared native build target. CliRequest.prepare allocates the record in the current Scope and borrows the supplied request pointer without copying it; that request must outlive the Build and may belong outside the per-target Context. Toolchain and Array storage allocated during preparation follow the current Scope, while referenced Strings and Lists keep their canonical pool lifetimes. cleanup manages only a temporary filesystem tree.

Source: src/build.x:25

Design notes

Direct operands and project targets use the same CliRequest. This module places native artifacts and lowers them to toolchain actions; translation remains with the compiler driver.