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

fnv_bytes

uint64_t fnv_bytes(uint64_t hash, const void *bytes, size_t length)

Returns hash extended with length bytes by 64-bit FNV-1a.

Source: src/utils.x:404

fnv_file

uint64_t fnv_file(uint64_t hash, String path, int &ok)

Returns hash extended with the contents of the file at path. A missing or unreadable file clears ok.

Source: src/utils.x:389

x2c_get_executable

String x2c_get_executable(void)

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

Source: src/utils.x:185

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

x2c_initialize_command_environment

void x2c_initialize_command_environment( const char *argv0, String embedded_identity)

Initializes an external command with the compiler identity embedded when it was built. A driver-supplied identity must match that compiler.

Source: src/utils.x:86

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 Compiler.home_dir reports none. The compiler identity is taken here, before any later work could observe a replaced executable. An already configured root leaves all state unchanged.

Source: src/utils.x:79

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

Compiler

Compiler.cache_root

String Compiler.cache_root(void)

Returns the per-user cache root: X2C_CACHE_DIR, XDG_CACHE_HOME/x2c, or ~/.cache/x2c, whichever is set first, or NULL when none is.

Source: src/utils.x:497

Compiler.command_environment

Map Compiler.command_environment(void)

Returns the home, driver, and identity supplied to external commands.

Source: src/utils.x:245

Compiler.command_path

String Compiler.command_path(String name)

Returns an executable command in this compiler’s libexec, or NULL.

Source: src/utils.x:237

Compiler.cpp_include_dirs

List Compiler.cpp_include_dirs(void)

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

Source: src/utils.x:278

Compiler.default_include_dirs

List Compiler.default_include_dirs(void)

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

Source: src/utils.x:272

Compiler.driver_executable

String Compiler.driver_executable(void)

Returns the matching compiler executable for a recursive translation. External commands use the driver’s X2C path or their adjacent installed compiler. An unavailable or changed compiler returns NULL.

Source: src/utils.x:190

Compiler.home_dir

String Compiler.home_dir(void)

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

Source: src/utils.x:206

Compiler.home_libexec

String Compiler.home_libexec(void)

Returns the command directory for this checkout or installed home.

Source: src/utils.x:225

Compiler.home_packages

String Compiler.home_packages(void)

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

Source: src/utils.x:219

Compiler.identity

String Compiler.identity(void)

Returns the active compiler’s identity in 16 hexadecimal digits. Ordinary compiler startup hashes its executable with FNV-1a; an external command uses the identity embedded from the compiler that built it. Returns NULL if ordinary startup could not read its executable.

Source: src/utils.x:365

Compiler.is_package_source

int Compiler.is_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:352

Compiler.module_stamp

String Compiler.module_stamp(void)

Returns the stamp a native module records: x2c-module-stamp: and the running compiler’s identity. Returns NULL when the executable cannot be read. Only the compiler that built a module loads it.

Source: src/utils.x:371

Compiler.package_directory

String Compiler.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:318

Compiler.run_command

int Compiler.run_command(String name, List arguments)

Runs an external command with inherited streams and returns its status. Resolves only this compiler’s libexec and passes literal arguments without a shell. An unavailable command reports an error and exits with status 2.

Source: src/utils.x:259

Compiler.stage_dir

String Compiler.stage_dir(void)

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

Source: src/utils.x:211

Diagnostics

Diagnostics.driver_error

void Diagnostics.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:476

Diagnostics.host_error

void Diagnostics.host_error(List detail)

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

Source: src/utils.x:486

Env

Env.find_program

String Env.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:284

Job

Job.decode_wait_status

int Job.decode_wait_status(int raw, int &signal)

Decodes the wait status raw of a child that has ended. Returns its exit status, 128 + signal when a signal ended it, or -1 otherwise, and stores that signal in signal, or 0 when no signal ended it.

Source: src/utils.x:463

Path

Path.content_identity

String Path.content_identity(String path)

Returns the identity a compiler executable at path has when it runs: the FNV-1a hash of its bytes, or NULL when path is NULL or unreadable.

Source: src/utils.x:379

Path.identifier_hash

String Path.identifier_hash(String filename)

Hashes unit filename spelling for stable generated C identifiers.

Source: src/utils.x:414

Path.is_layout_source

int Path.is_layout_source(String path)

Reports whether path names a file in the indentation syntax.

Source: src/utils.x:311

Path.is_x2c_source

int Path.is_x2c_source(String path)

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

Source: src/utils.x:297

Path.lock_file

int Path.lock_file(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:426

Path.publish_files

void Path.publish_files(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:446

SourceView

SourceView.package_entry

String SourceView.package_entry( SourceView sources, List roots, String name, String &directory)

Resolves the first readable package entry under roots, preferring .x to .xp, using the importing compiler’s source view. Returns its directory through directory, or NULL when the package does not exist.

Source: src/utils.x:334

Public types

Compiler

typedef struct Compiler *Compiler

Names the translation state that src/compiler/compiler.x defines.

Source: src/utils.x:31

Diagnostics

typedef struct Diagnostics *Diagnostics

Names the positioned diagnostic store that src/diagnostics.x defines.

Source: src/utils.x:34

Design notes

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