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

src/build.x

Typed native build request and artifact graph.

Functions

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 for imported packages. Non-static-library builds also add package archives and link flags; an absent archive then prints a diagnostic and exits with status 2. Static-library builds skip those checks and inputs.

Source: src/build.x:432

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:443

Build.cleanup

void Build.cleanup(Build state, 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:750

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:451

Build.finish

int Build.finish(Build b)

Compiles registered C sources and then archives or links the final output. Returns zero for success, including a current retained artifact, and one when compilation or the final native action fails. Compile-only requests stop after objects; successful retained builds update private state.

Source: src/build.x:582

Build.generated_dir

String Build.generated_dir(Build state, String input)

Returns and registers the generated-file directory for input. The directory is derived from the input path, created unless this is a dry run, and appended once to the build’s generated include directories.

Source: src/build.x:299

Build.record_translation

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

Records the successful translation fingerprint when retained state exists. Dry runs and incomplete fingerprints are ignored. 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:346

Build.report_success

void Build.report_success(Build b)

Prints the completed build receipt and artifact details when enabled.

Source: src/build.x:650

Build.run_program

int Build.run_program(Build state)

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:707

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:327

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:214

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; unsigned long started_at; 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.