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

tool_capture

int tool_capture(List arguments, String *output, String *errors)

Runs the host tool arguments without a shell, captures both streams, and returns its shell-style status. A tool that cannot start returns 127 and leaves the reason in errors.

Source: src/toolchain.x:243

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

ToolAction

ToolAction.as_program

void ToolAction.as_program(ToolAction action)

Inherits the standard streams and suppresses the failure summary.

Source: src/toolchain.x:187

ToolAction.run

int ToolAction.run(ToolAction action)

Starts and waits for the action, returning its final status.

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

Source: src/toolchain.x:348

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.

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

Source: src/toolchain.x:298

ToolRun

ToolRun.ready

int ToolRun.ready(ToolRun t)

Checks whether an execution can be waited without blocking. A dry run and a tool that could not start are ready immediately.

Source: src/toolchain.x:316

ToolRun.wait

int ToolRun.wait(ToolRun execution)

Waits for an execution, forwards its captured streams, and returns its shell-style status. Signals return 128 + signal, a tool that could not start returns 127, and a dry run returns 0. Captured output goes to stderr; program actions inherit standard streams.

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

Source: src/toolchain.x:326

Toolchain

Toolchain.archive_action

ToolAction Toolchain.archive_action( Toolchain t, 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:154

Toolchain.compile_action

ToolAction Toolchain.compile_action( Toolchain t, 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:127

Toolchain.link_action

ToolAction Toolchain.link_action(Toolchain t, 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:165

Toolchain.preprocess

int Toolchain.preprocess( Toolchain t, const char *fname, List include_dirs, const char *imacros, 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, 127 when the preprocessor cannot start, or -1 for invalid arguments or local setup failure. 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:367

Toolchain.preprocess_action

ToolAction Toolchain.preprocess_action( Toolchain t, String source, String output, List gen_dirs)

Captures the native preprocessor view used to identify reusable objects. Uses the compilation’s native flags and include order, retaining line markers so source locations also belong to the identity.

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

Source: src/toolchain.x:141

Toolchain.search_directories

List Toolchain.search_directories(Toolchain t)

Returns the directories the C compiler searches for headers and libraries without explicit options, as it reports them, plus the lib directory beside each reported include directory. A compiler that reports none contributes none.

Source: src/toolchain.x:259

Public types

ToolAction

typedef struct ToolAction { Symbol phase, List arguments, int verbose, dry_run, inherit_stdio, 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:28

ToolRun

typedef struct ToolRun { ToolAction action; Job job; String start_error; } *ToolRun

Tracks one Scope-owned started action and its job. A tool that could not start has no job and keeps the message its ToolRun.wait reports. The borrowed action must remain valid through that wait.

Source: src/toolchain.x:37

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

Design notes

Resolves host tools and builds typed argv. Every action runs as a lib/process.x command, without a shell.