kit

env.h (18898B)

---

 #ifndef KIT_DRIVER_ENV_H
 #define KIT_DRIVER_ENV_H
 
 #include <kit/compile.h>
 #include <kit/core.h>
 #include <kit/dbg.h>
 #include <kit/jit.h>
 #include <stddef.h>
 #include <stdint.h>
 
 /* Shared host environment used by every tool that calls into libkit.
  * driver_env_init wires up the libc-backed heap, the stderr diag sink, and
  * a POSIX file_io implementation (open/read/write on real paths). It is
  * the single piece of glue that turns "the host" into a KitContext.
  *
  * The execmem / dbg_os vtables that used to live on KitEnv now live on
  * KitJitHost / KitDbgHost. They are still constructed here so that one
  * DriverEnv covers every libkit-using tool, but they're handed to libkit
  * per-call via the appropriate host struct. */
 typedef struct DriverEnv {
   KitHeap* heap;
   KitDiagSink* diag;
   KitFileIO file_io;
   const KitExecMem* execmem;
   const KitDbgOs* dbg_os;    /* NULL unless `kit dbg` paths run */
   const KitMetrics* metrics; /* optional scoped metrics sink */
   int64_t now;               /* unix seconds; -1 = unknown */
   const char* cache_dir;     /* base cache dir, e.g. ~/.cache/kit */
 } DriverEnv;
 
 void driver_env_init(DriverEnv*);
 void driver_env_fini(DriverEnv*);
 
 /* Build a KitContext value pointing at the DriverEnv's heap/diag/file_io
  * vtables. The returned value can be passed by const-pointer to any
  * libkit entry that takes `const KitContext *`. */
 KitContext driver_env_to_context(const DriverEnv*);
 
 /* Build a KitJitHost from the DriverEnv (execmem). The returned struct
  * holds a borrowed pointer to the vtable owned by g_execmem_posix;
  * callers must not outlive driver_env_fini. */
 KitJitHost driver_env_to_jit_host(const DriverEnv*);
 
 /* Build a KitDbgHost from the DriverEnv (dbg_os). */
 KitDbgHost driver_env_to_dbg_host(const DriverEnv*);
 
 /* Tells the stderr diag sink which compiler to use when resolving
  * SrcLoc.file_id to a path. The driver_compiler_{new,free} helpers
  * below already manage this; call this directly only when you hand a
  * KitCompiler from outside those helpers (none today). */
 void driver_diag_set_compiler(KitCompiler*);
 
 /* Lifecycle helpers around kit_compiler_{new,free}. Identical to the raw
  * entries except they register the active compiler with the stderr diag sink
  * so diagnostics resolve loc.file_id to its registered path. The compiler
  * borrows `target`; callers own it and must free it after driver_compiler_free.
  * Returns KIT_OK on success; on failure *out is NULL. */
 KitStatus driver_compiler_new(const KitTarget*, const KitContext*,
                               KitCompiler** out);
 void driver_compiler_free(KitCompiler*);
 
 /* Default target used by tools that don't expose a target-selection flag
  * yet. v1: native-looking host target (chosen at compile time). */
 KitTargetSpec driver_host_target(void);
 
 /* ----------------------------------------------------------------------
  * Hosted-libc search directories
  *
  * The hosted-libc resolver needs two sets of directories: include roots to add
  * as system header search paths, and library roots to search for the C runtime
  * objects and libc. They come from one of two producers -- expanding an
  * explicit --sysroot/KIT_SYSROOT (portable, in driver/lib/hosted.c) or probing
  * the live host (driver_default_hosted_dirs, below). The resolver copies what
  * it needs into its plan, then releases the whole set with
  * driver_hosted_dirs_fini; the strings stored here are transient scratch.
  *
  * DRIVER_HOSTED_MAX_INCDIRS must stay >= the plan's DRIVER_HOSTED_MAX_INCLUDES
  * (driver/lib/hosted.h): every emitted incdir becomes one owned plan include.
  * ---------------------------------------------------------------------- */
 #define DRIVER_HOSTED_MAX_INCDIRS 4
 #define DRIVER_HOSTED_MAX_LIBDIRS 8
 
 typedef struct DriverHostedDirs {
   DriverEnv* env;
   /* The single sysroot root these dirs came from (an explicit --sysroot/
    * KIT_SYSROOT, or a host probe that resolves to one tree, e.g. the macOS
    * SDK). NULL when the dirs come from a multi-dir source with no single root
    * (the Linux/FreeBSD live-system probe). Borrowed; not freed by fini. */
   const char* root;
   char* incdirs[DRIVER_HOSTED_MAX_INCDIRS];
   size_t incdir_sizes[DRIVER_HOSTED_MAX_INCDIRS];
   uint32_t nincdirs;
   char* libdirs[DRIVER_HOSTED_MAX_LIBDIRS];
   size_t libdir_sizes[DRIVER_HOSTED_MAX_LIBDIRS];
   uint32_t nlibdirs;
 } DriverHostedDirs;
 
 /* Append an include/library directory, heap-duplicated from `dir`. The _join
  * forms join `base` + `sub` with a single '/' separator first. A NULL/empty dir
  * is a successful no-op; returns nonzero on allocation failure or when the list
  * is full (loud overflow -- never a silent drop). dirs->env must be set. */
 int driver_hosted_dirs_add_inc(DriverHostedDirs* dirs, const char* dir);
 int driver_hosted_dirs_add_lib(DriverHostedDirs* dirs, const char* dir);
 int driver_hosted_dirs_add_inc_join(DriverHostedDirs* dirs, const char* base,
                                     const char* sub);
 int driver_hosted_dirs_add_lib_join(DriverHostedDirs* dirs, const char* base,
                                     const char* sub);
 /* Free all stored dir strings and zero the lists. Idempotent. */
 void driver_hosted_dirs_fini(DriverHostedDirs* dirs);
 
 /* Probe the live host for hosted include/library dirs for `target`, used when
  * no --sysroot/KIT_SYSROOT was given. Only the host's own platform is probed
  * (the caller additionally gates on target-OS == host-OS) -- never for cross-
  * compiles. Fills `out`, which the caller zero-inits with out->env set. Returns
  * 0 when it produced at least one library dir, nonzero otherwise (out left
  * empty). macOS resolves the SDK (the canonical Command Line Tools / Xcode
  * roots; no subprocess, no env var) into <sdk>/usr/{include,lib}; Linux
  * enumerates the multiarch dirs; FreeBSD the base dirs; Windows produces
  * nothing (its MinGW sysroot comes from --sysroot/KIT_SYSROOT in the cc
  * driver). The single env-var override, KIT_SYSROOT, is consulted by the
  * caller, not here. */
 int driver_default_hosted_dirs(DriverEnv* env, KitTargetSpec target,
                                DriverHostedDirs* out);
 
 /* ----------------------------------------------------------------------
  * Host-shim helpers
  *
  * driver/env.c is the only TU in the driver allowed to depend on libc
  * facilities that issue syscalls or touch host state -- host stdio, malloc,
  * POSIX I/O, environment, time. Other driver TUs are compiled freestanding
  * against rt/include plus libkit's public headers. The shims below exist
  * primarily for the syscall-shaped surface; other TUs may also call them for
  * consistency.
  * ---------------------------------------------------------------------- */
 
 /* String predicates and lookups. driver_streq / driver_strneq return
  * non-zero when the strings (or first n bytes) match -- sense-flipped
  * from libc's strcmp so call sites read naturally. */
 int driver_streq(const char* a, const char* b);
 int driver_strneq(const char* a, const char* b, size_t n);
 size_t driver_strlen(const char* s);
 const char* driver_strchr(const char* s, int c);
 const char* driver_basename(const char* path);
 int driver_has_suffix(const char* s, const char* suffix);
 
 /* Memory. Allocations route through DriverEnv.heap; release returns the
  * size used at allocation (so the heap implementation can track usage). */
 void* driver_alloc(DriverEnv*, size_t);
 void* driver_alloc_zeroed(DriverEnv*, size_t);
 void driver_free(DriverEnv*, void* p, size_t);
 void driver_memcpy(void* dst, const void* src, size_t n);
 
 /* Opens a Writer that writes to stdout. close frees the struct but does
  * not close stdout. */
 KitWriter* driver_stdout_writer(DriverEnv*);
 
 /* Opens a Writer that writes to stderr. close frees the struct but does
  * not close stderr. */
 KitWriter* driver_stderr_writer(DriverEnv*);
 
 /* Test whether `path` names an existing filesystem entry (any type).
  * Returns nonzero on existence, zero otherwise. Used by library-path
  * resolution; intentionally distinct from read_all so candidate-search
  * loops don't slurp file contents on a hit. */
 int driver_path_exists(const char* path);
 
 /* Read a path's last modification time in nanoseconds since the Unix epoch.
  * Returns 0 on success, nonzero on stat failure. */
 int driver_path_mtime_ns(const char* path, int64_t* out);
 
 /* Stat a host path. Fills *out_size, *out_mtime_ns, and *out_filetype using
  * the KIT_WASM_FILETYPE_* constants (0=unknown 1=block 2=char 3=dir
  * 4=regular 5=dgram 6=stream 7=symlink). Returns 0 on success, 1 if the
  * path does not exist, 2 on any other error. Does not require a DriverEnv. */
 int driver_path_stat(const char* path, uint64_t* out_size,
                      uint64_t* out_mtime_ns, uint8_t* out_filetype);
 
 /* Opaque directory-enumeration handle. Holds a snapshot of all entries
  * (excluding "." and "..") taken at driver_open_dir time. */
 typedef struct DriverDirHandle DriverDirHandle;
 
 /* Open a directory and snapshot its entries. Returns NULL on failure. */
 DriverDirHandle* driver_open_dir(DriverEnv*, const char* path);
 
 /* Read the entry at zero-based index. Sets *out_name to a pointer borrowed
  * from the handle (valid until driver_close_dir), *out_name_len to its byte
  * length (not NUL-terminated), and fills *out_ino, *out_size, *out_mtime_ns,
  * *out_filetype. Returns 0 on success, 1 when index >= entry count. */
 int driver_read_dir_entry(DriverDirHandle*, uint64_t index,
                           const char** out_name, uint32_t* out_name_len,
                           uint64_t* out_ino, uint64_t* out_size,
                           uint64_t* out_mtime_ns, uint8_t* out_filetype);
 
 /* Free a directory handle. Safe to call with NULL. */
 void driver_close_dir(DriverEnv*, DriverDirHandle*);
 
 /* Create a directory and any missing parents. Returns 0 on success. */
 int driver_mkdir_p(DriverEnv*, const char* path);
 
 /* Resolve the absolute path of the running kit executable into a freshly
  * heap-allocated, NUL-terminated buffer (*out / *out_size); free it with
  * driver_free(env, *out, *out_size). Returns 0 on success, nonzero on
  * failure (out untouched). Per-OS: /proc/self/exe (Linux), _NSGetExecutablePath
  * + realpath (macOS), KERN_PROC_PATHNAME sysctl (FreeBSD), GetModuleFileNameW
  * (Windows). Used by `install` to point freshly created links at the binary. */
 int driver_self_exe_path(DriverEnv*, char** out, size_t* out_size);
 
 /* Create a symbolic link named `link_path` that resolves to `target`. Returns
  * 0 on success. POSIX uses symlink(2); Windows uses CreateSymbolicLinkW, which
  * may require privilege or Developer Mode (so `install` defaults to hard links
  * on Windows). */
 int driver_create_symlink(const char* target, const char* link_path);
 
 /* Create a hard link named `link_path` referring to the same file as `target`.
  * Returns 0 on success. POSIX uses link(2); Windows uses CreateHardLinkW. Both
  * require `target` and `link_path` to live on the same filesystem/volume. */
 int driver_create_hardlink(const char* target, const char* link_path);
 
 /* Remove the file or symlink at `path`. Returns 0 when the entry was removed or
  * was already absent, nonzero on any other failure. POSIX unlink(2) / Windows
  * DeleteFileW. */
 int driver_remove_file(const char* path);
 
 /* Test whether a name exists at `path` WITHOUT following symlinks, so a
  * dangling symlink still counts as existing. Returns nonzero on existence.
  * POSIX lstat / Windows GetFileAttributesW. */
 int driver_path_lexists(const char* path);
 
 /* Set a linked binary output's final mode according to the active umask.
  * Returns 0 on success, nonzero on chmod failure. */
 int driver_mark_executable_output(const char* path);
 
 /* Walk regular files below `root`, reporting tree-relative paths with '/'
  * separators. The callback returns nonzero to abort the walk. Unsupported
  * filesystem entries cause a nonzero return from the walk helper. */
 typedef int (*DriverWalkFileFn)(void* user, const char* source_path,
                                 const char* tree_path, int executable);
 int driver_walk_regular_files(DriverEnv*, const char* root, DriverWalkFileFn,
                               void* user);
 
 /* Diagnostic printing to host stderr. Format is `"<tool>: <fmt>\n"`. */
 void driver_errf(const char* tool, const char* fmt, ...);
 
 /* Raw hosted stderr log. Used by optional metrics so libkit stays callback-
  * only and freestanding. */
 void driver_logf(const char* fmt, ...);
 
 /* Formatted output to stdout. */
 void driver_printf(const char* fmt, ...);
 
 /* Monotonic host time in nanoseconds, or 0 if unavailable. */
 uint64_t driver_now_ns(void);
 
 /* Fill `out` with `n` cryptographically-random bytes from the host CSPRNG.
  * Returns 0 on success, non-zero on failure (in which case `out` must not be
  * used). This is the single entropy source for key generation; the crypto
  * primitives themselves never source randomness — it always flows in here. */
 int driver_random_bytes(uint8_t* out, size_t n);
 
 /* Lookup a process environment variable; returns NULL if unset. The returned
  * pointer aliases libc-owned storage and is valid until the next setenv/
  * putenv from any caller. */
 const char* driver_getenv(const char* name);
 
 /* Borrow the process environment as NAME=VALUE strings. The array and strings
  * are libc-owned and remain valid until the process environment is mutated. */
 const char* const* driver_environ(void);
 
 /* Read all of stdin into a freshly-allocated buffer. On success returns 1
  * and stores the buffer/size in out_data/out_size; the caller frees via
  * driver_free(env, *out_data, *out_size). Returns 0 on read failure or
  * allocation failure. */
 int driver_read_stdin(DriverEnv*, uint8_t** out_data, size_t* out_size);
 
 /* Open a temporary file in $VISUAL, then $EDITOR, then vi. `suffix` should
  * include the leading dot when a language-specific extension is useful.
  * On success, returns the edited bytes in a freshly allocated buffer that the
  * caller frees with driver_free(env, *out_data, *out_size). */
 int driver_edit_temp(DriverEnv*, const char* suffix, const uint8_t* initial,
                      size_t initial_size, uint8_t** out_data, size_t* out_size);
 
 /* Path-shaped input loader. Wraps env.file_io.read_all so each tool can
  * convert a list of paths to a list of KitSlice without re-implementing
  * load/release/error bookkeeping. `loaded` is set to 1 on success; release is
  * idempotent and does nothing when loaded is already 0. driver_load_bytes
  * fills `in.name = path` plus the loaded data/len; driver_release_bytes hands
  * the buffer back through file_io.release. On failure an error is emitted via
  * driver_errf using the supplied tool tag. */
 typedef struct DriverLoad {
   KitFileData fd;
   int loaded;
 } DriverLoad;
 
 int driver_load_bytes(const KitFileIO*, const char* tool, const char* path,
                       DriverLoad* out, KitSlice* in);
 void driver_release_bytes(const KitFileIO*, DriverLoad*);
 
 /* Read one line from stdin into `buf` (cap >= 2). Strips the trailing
  * newline and NUL-terminates. Returns the line length on success, 0 at
  * EOF (with buf[0]='\0'), -1 on read error, or -2 when the read was
  * interrupted by a signal (caller should print a fresh prompt and
  * retry). Over-long lines are truncated to cap-1 bytes; the remainder
  * up to the next newline is consumed silently. */
 int driver_read_line(char* buf, size_t cap);
 
 typedef struct DriverLineHistory {
   char** items;
   size_t* sizes;
   uint32_t count;
   uint32_t cap;
 } DriverLineHistory;
 
 typedef struct DriverLineCompletion {
   char* text;
   size_t size;
 } DriverLineCompletion;
 
 typedef struct DriverLineCompletionList {
   DriverEnv* env;
   DriverLineCompletion* items;
   uint32_t count;
   uint32_t cap;
   size_t replace_start;
   size_t replace_end;
 } DriverLineCompletionList;
 
 typedef void (*DriverLineCompleteFn)(void* user, const char* line,
                                      size_t cursor,
                                      DriverLineCompletionList* out);
 
 int driver_line_completion_add(DriverLineCompletionList*, const char* text,
                                size_t len);
 int driver_read_line_edit(DriverEnv*, const char* prompt, char* buf, size_t cap,
                           DriverLineHistory*, DriverLineCompleteFn,
                           void* complete_user);
 void driver_line_history_fini(DriverEnv*, DriverLineHistory*);
 
 /* Flush the host stdout. The dbg REPL prompt has no trailing newline, so
  * without an explicit flush the prompt stays buffered until the next
  * line of output. */
 void driver_flush_stdout(void);
 
 /* Install / restore a SIGINT handler. While installed, SIGINT runs `cb(user)`
  * synchronously (so `cb` must be async-signal safe). Used by `dbg` to
  * forward Ctrl-C into kit_jit_session_interrupt while the worker is
  * running, and to restore SIG_DFL while sitting at the REPL prompt so
  * Ctrl-C terminates the program normally. Returns 0 on success. */
 int driver_install_sigint(void (*cb)(void*), void* user);
 void driver_restore_sigint(void);
 
 /* Crash-guarded execution for `kit run`.
  *
  * `entry` is the JITed program entry, invoked as `entry(argc, argv)`. On a
  * clean return, *ret_out receives the program's status and the call returns 0.
  *
  * On a fatal fault raised by the program (SIGSEGV/SIGBUS/SIGILL/SIGFPE/SIGABRT/
  * SIGTRAP — the last covers __builtin_trap / failed asserts), the guard walks
  * the frame-pointer chain *inside the signal handler* (where the faulting stack
  * is still intact, since `kit run` shares its stack with the program), captures
  * the return addresses innermost-first, and invokes `on_crash(user, signo, pcs,
  * npcs)` from normal context — so symbolization (DWARF/malloc/printf) never
  * runs async-signal. `arch` selects the FP register / pointer width for the
  * walk. The call then returns 1; the program's own return value is undefined on
  * this path, so the caller should treat the run as failed.
  *
  * Hosts without a fault guard (Windows) run `entry` directly, set *ret_out, and
  * return 0 without ever calling on_crash. */
 typedef int (*DriverRunEntryFn)(int argc, char** argv);
 typedef void (*DriverRunCrashFn)(void* user, int signo, const uint64_t* pcs,
                                  int npcs);
 int driver_run_with_crash_guard(DriverEnv* env, KitArchKind arch,
                                 DriverRunEntryFn entry, int argc, char** argv,
                                 int* ret_out, DriverRunCrashFn on_crash,
                                 void* user);
 
 /* Host-symbol resolver for JIT extern_resolver. Looks up `name` via
  * dlsym(RTLD_DEFAULT, ...) on POSIX hosts, returning NULL on miss. Stateless;
  * `user` is ignored and may be NULL. Wired into `kit run` so JITed code
  * can call libc symbols (printf, malloc, ...) without an explicit linker
  * step. */
 void* driver_dlsym_resolver(void* user, KitSlice name);
 
 #endif