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

src/utils.x

System utilities for environment discovery and workers.

Functions

Functions

file_lock

int file_lock(Path p, int wait)

Locks the file p, creating it, and returns a descriptor that holds the lock until it is closed or the process exits. Returns -1 when wait is zero and another process holds the lock.

Source: src/utils.x:168

file_publish

void file_publish(List outputs)

Replaces each file named in outputs, a List of alternating paths and texts. Every text is written and closed in a process-specific sibling of its path before the first rename, so a failed write replaces no destination. The renames then run in order: each destination holds its old contents or its new ones, and a failed rename leaves the earlier destinations replaced.

Raises: <not-found> or <io-fail>, after removing the siblings.

Source: src/utils.x:188

worker_exit

void worker_exit(int status)

Attempts to flush process streams and terminates a worker with status. Flush failure is ignored. This function does not return and does not run atexit handlers. Those belong to the parent process and would close its log and process-lifetime Scopes twice.

Source: src/utils.x:274

worker_fork

long worker_fork(void)

Forks a worker that continues the current program with inherited state. Returns zero in the child, its PID in the parent, or -1 on fork failure. The call attempts to flush all process streams before the fork so successfully flushed bytes cannot be written by both processes. Flush failure is ignored. The child must leave through worker_exit.

Source: src/utils.x:263

worker_wait_any

int worker_wait_any(long *pids, int count, int *status)

Waits until one of the count workers in pids exits and returns its index, storing its shell-style status: the exit status, 128 + signal, or -1 when it cannot be waited. Other children stay unreaped, so the wait polls with a short sleep.

Source: src/utils.x:284

x2c_cpp_include_dirs

List x2c_cpp_include_dirs(void)

Returns the borrowed preprocessor List <root>/src, then <root>/lib. <root>/src is present only when the home has that directory. Returns NULL before environment setup.

Source: src/utils.x:110

x2c_default_include_dirs

List x2c_default_include_dirs(void)

Returns the borrowed default include List containing <root>/include. Returns NULL before environment setup.

Source: src/utils.x:104

x2c_driver_error

void x2c_driver_error(const char *message)

Prints x2c: error: <message> to stderr and exits with status 2. The streams are flushed and atexit handlers do not run, so the call is safe inside a try body or a catch arm, whose records those handlers would otherwise find still live.

Source: src/utils.x:147

x2c_filename_hash

String x2c_filename_hash(String filename)

Hashes unit filename spelling for stable generated C identifiers.

Source: src/utils.x:299

x2c_find_program

String x2c_find_program(String name)

Returns the spelling of the first PATH candidate for the program name that this process may execute, searched as execvp searches, or NULL. An empty entry names the current directory.

Source: src/utils.x:134

x2c_get_executable

String x2c_get_executable(void)

Returns the borrowed resolved executable path, or NULL when unavailable.

Source: src/utils.x:58

x2c_get_root

String x2c_get_root(void)

Returns the borrowed repository root, or NULL before it is configured. The root is absolute with symbolic links resolved, the one spelling paths below the home are compared in.

Source: src/utils.x:55

x2c_home

String x2c_home(void)

Returns the discovered or configured home, or NULL when there is none.

Source: src/utils.x:113

x2c_home_packages

String x2c_home_packages(void)

Returns <home>/packages, which may not exist, or NULL without a home.

Source: src/utils.x:116

x2c_host_error

void x2c_host_error(List detail)

Reports a caught <not-found> or <io-fail> through x2c_driver_error as its operation, path or program, and system reason.

Source: src/utils.x:156

x2c_initialize_environment

void x2c_initialize_environment(const char *argv0)

Initializes compiler paths and default include Lists once. The executable is resolved from the host, argv0, or PATH. The home is X2C_HOME when it is set and not empty; otherwise discovery walks from the executable and then from the current directory to a directory holding include/ and etc/compiler-sdk.xlisp, a source checkout or an installed prefix alike. The root is kept absolute with symbolic links resolved, the one spelling every path below the home is compared in. Without a home the root is the current directory and x2c_home reports none. An already configured root leaves all state unchanged.

Source: src/utils.x:26

x2c_package_directory

String x2c_package_directory(List roots, String path)

Returns the package directory that holds path below one of roots: the root’s child on the way to path, compared by canonical path, when that child’s name is an identifier. Returns NULL for any other path.

Source: src/utils.x:64

x2c_package_source

int x2c_package_source(String directory, String path)

Recognizes a package’s src/ files or its package-named legacy entry. Other files under the package directory are consumers.

Source: src/utils.x:95

x2c_set_root

void x2c_set_root(String root)

Overrides the repository root and rebuilds its default include Lists. The root is resolved as environment setup resolves it. The rebuilt values must remain valid until the next override or the process no longer uses them.

Source: src/utils.x:43

x2c_source_file

int x2c_source_file(String path)

Reports whether path is x2c source: a .x file, or a file of any other name whose first line is a shebang, which is a script.

Source: src/utils.x:79

x2c_stage_dir

String x2c_stage_dir(void)

Returns the directory of a compiler staged at <home>/builds/<stage>/, or NULL for any other compiler.

Source: src/utils.x:124

Design notes

Owns the environment the driver modules share: where the executable, home, stage, and packages are, how a file is locked or replaced, the driver’s fatal error line, and translation workers. Host tools run through lib/process.x.