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

src/toolchain.x

Host preprocessing, compilation, archive, and link actions.

Functions

Functions

tool_action_new

ToolAction tool_action_new( Symbol phase, List arguments, int verbose, int dry_run)

Creates a Scope-owned action that reports nonzero status by default. The action retains arguments without copying them.

Raises: <alloc-fail> when the action cannot be allocated.

Source: src/toolchain.x:218

toolchain_new

Toolchain toolchain_new( String cc, String ar, List cpp_args, List cc_args, List ld_args, int verbose, int dry_run)

Creates a Scope-owned host toolchain and resolves its native layout. Tool selection is explicit value, X2C_CC or X2C_AR, CC or AR, the installed toolchain record, then cc or ar. Explicit tool Strings and option Lists are borrowed.

Raises: <alloc-fail> or <size-limit> while constructing the toolchain or its canonical layout.

Source: src/toolchain.x:121

ToolAction

ToolAction.as_program

void ToolAction.as_program(ToolAction action)

Routes captured stdout to stdout and suppresses the failure summary. Captured stderr still goes to stderr when the action is waited.

Source: src/toolchain.x:232

ToolAction.run

int ToolAction.run(ToolAction action)

Starts and waits for the action, returning its final status. A partial capture setup failure returns no defined status.

Raises: the same construction and capture-reading causes as ToolAction.start and ToolRun.wait.

Source: src/toolchain.x:326

ToolAction.start

ToolRun ToolAction.start(ToolAction action)

Starts the action without a shell and returns a Scope-owned execution. Verbose and dry-run actions print their quoted argv to stderr. A dry run starts no child. After capture setup succeeds, a non-dry execution must be waited exactly once; partial capture setup leaves a non-waitable result.

Raises: <alloc-fail> or <size-limit> while constructing the execution or argv.

Source: src/toolchain.x:283

ToolRun

ToolRun.wait

int ToolRun.wait(ToolRun execution)

Waits once for an execution, forwards its captured streams, and returns its shell-style status. Signals return 128 + signal; an invalid action, fork failure, or wait failure returns -1, and a dry run returns 0. Stdout goes to stderr unless ToolAction.as_program selected program routing. An execution with partial capture setup is not valid input.

Raises: <io-fail>, <bad-arg>, <size-limit>, or <alloc-fail> while reading either capture as a String.

Source: src/toolchain.x:304

Toolchain

Toolchain.archive_action

ToolAction Toolchain.archive_action( Toolchain toolchain, String output, List objects)

Builds but does not start an ar rcs action in object-list order. The action does not remove an existing archive, so callers requiring exact membership must unlink output before it runs.

Raises: <alloc-fail> or <size-limit> while constructing the action.

Source: src/toolchain.x:182

Toolchain.compile_action

ToolAction Toolchain.compile_action( Toolchain toolchain, String source, String object, String depfile, List gen_dirs)

Builds but does not start one C compilation action. Generated include directories precede the x2c include directory and configured compiler arguments. The action requests dependency output at depfile with object as its target.

Raises: <alloc-fail> or <size-limit> while constructing the action.

Source: src/toolchain.x:149

Toolchain.link_action

ToolAction Toolchain.link_action( Toolchain toolchain, String output, List inputs)

Builds but does not start a host-compiler link action. Input order is preserved; configured linker arguments, the matching x2c runtime archive, and -lm follow the inputs.

Raises: <alloc-fail> or <size-limit> while constructing the action.

Source: src/toolchain.x:199

Toolchain.preprocess

int Toolchain.preprocess( Toolchain toolchain, const char *fname, List include_dirs, const char *imacros, const char *force_include, String *output, String *errors, String *dependencies)

Runs the configured C preprocessor without a shell. fname, output, and errors are required; output pointers are cleared before use. Source and include paths remain distinct argv elements, and stdout and stderr are captured separately. When dependencies is present, its temporary depfile is read when possible and removed on returning paths, including a handled <io-fail> while reading it. A non-returning <bad-arg>, <size-limit>, or <alloc-fail> may transfer before removal. Returns the shell-style child status, or -1 for invalid arguments, local setup failure, child start failure, or wait failure. Partial capture setup returns no defined status. This operation does not consult dry_run.

Raises: <io-fail>, <bad-arg>, <size-limit>, or <alloc-fail> while constructing arguments or reading captured text.

Source: src/toolchain.x:350

Public types

ToolAction

typedef struct ToolAction { Symbol phase, List arguments, int verbose, dry_run, to_stdout, report; } *ToolAction

Describes one Scope-owned host-tool argv action and its reporting policy. The arguments List is retained without copying, follows its owning canonical pool, and must remain valid through the action’s execution.

Source: src/toolchain.x:26

ToolRun

typedef struct ToolRun { ToolAction action; void *process; } *ToolRun

Tracks one Scope-owned started action and its captured child process. After capture setup succeeds, a non-dry execution must be passed to ToolRun.wait exactly once; a returning wait consumes its stdout and stderr files. The borrowed action must remain valid through that wait. Partial capture setup leaves a non-waitable execution.

Source: src/toolchain.x:36

Toolchain

typedef struct Toolchain { String cc, ar, include_dir, runtime_lib, List cpp_args, cc_args, ld_args; int verbose, dry_run, keep_system_includes; } *Toolchain

Holds resolved host tools, native layout, and borrowed option Lists. The record returned by toolchain_new is Scope-owned. Its Strings follow their owning canonical pools, which may be ancestors; cpp_args, cc_args, and ld_args are retained without copying.

Source: src/toolchain.x:17

Design notes

Resolves host tools and builds typed argv. Every action runs through the child-process code in utils.x without a shell.