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_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:298

ToolAction

ToolAction.as_program

void ToolAction.as_program(ToolAction action)

Inherits the standard streams and suppresses the failure summary.

Source: src/toolchain.x:151

ToolAction.new

ToolAction ToolAction.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:141

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

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

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

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

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

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

Toolchain.for_meta

Toolchain Toolchain.for_meta(String cc)

Creates the toolchain that builds meta code with cc. It selects the archiver as Toolchain.new does and has no native options.

Source: src/toolchain.x:80

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

Toolchain.meta_cc

String Toolchain.meta_cc(String explicit)

Returns the host C compiler that builds meta code, which runs in this process’s host: explicit, X2C_META_CC, META_CC, or cc, never the target compiler.

Source: src/toolchain.x:132

Toolchain.module_action

ToolAction Toolchain.module_action( Toolchain t, String output, List inputs, String loader)

Builds but does not start the link of a native module. The module leaves the x2c runtime unresolved and uses the loading process’s copy. macOS links a bundle against loader, so a runtime function that executable lacks fails this link. Other hosts link a shared object whose calls to its own functions never bind to a same-named compiler function; a missing runtime function fails when the compiler loads it.

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

Source: src/toolchain.x:221

Toolchain.new

Toolchain Toolchain.new(CliRequest request)

Creates a Scope-owned host toolchain with the tools, native options, and verbose and dry-run modes of request, 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:69

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. include_dirs precede the system directories, and the runtime header directory follows them, so a generated string.h never replaces the C library’s. System headers keep their include directives when the host supports that mode. output, errors, and dependencies are cleared before use. Source and include paths remain distinct argv elements, and stdout and stderr are captured separately. The temporary depfile is read into dependencies 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:349

Toolchain.preprocess_action

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

Builds the preprocessor action whose output identifies an object. It uses the compilation’s native flags and include order and keeps line markers, so source locations belong to the identity.

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

Source: src/toolchain.x:180

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

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, inline_macro_expansions; } *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.