Main - API reference

(main &rest args)

Main entry point. Dispatches on command-line arguments. When invoked as the saved image's toplevel, ARGS is empty (SBCL calls the toplevel with no Lisp arguments), so fall back to the process command line. The build saves with :save-runtime-options t, so SBCL passes flags like –version straight through instead of intercepting them itself.

–resident is the steered production boot: it consumes –control-socket <path> and an optional –ports <set> (value args). It fails closed on a malformed port, and on an absent control socket unless the launch hands over the inherited DNS pair, so an incomplete launcher invocation refuses rather than binding a default port. An absent –ports seeds nothing, and the node serves what its configuration holds. The supervised run modes (–resident, –run and –daemon) end with the status their exit class names (valis/src/exit-status): a refusal that a restart would repeat exits 78, which the unit does not restart, a failure a restart is expected to clear exits 75, and a failure nothing has classified exits 1. The operator verbs keep the exit codes they document. An owner flag on a command line naming no verb, or beside –resident, –daemon, –dev, –backup, or –restore, is refused with 2 and starts nothing. –daemon is a no-op run mode; –run starts the foreground loopback node, and –dev with no owner flag beside it starts the development listener.

(open-development-image-configuration)

Install the node's configuration under the data root, read-only, as this image's store, and return it, or NIL when the data root holds none. A development image loads valis without booting a node, so nothing else opens the store there. The store is read-only so the image never holds the lock a node beside it needs. The image holds the configuration as the file stood when a setting was first read.

(stamp-build-commit)

Set COMMIT from the source tree valis was compiled from and return it. Builders call this immediately before dumping the image.

(toplevel &rest args)

The entry point of a built binary: run main on ARGS and exit the process with the status main returned.

UIOP's image restore reads an entry point's value only as true or false, so while main was the entry point no status it returned reached the exit code, and a resident launch that main refused reached its supervisor as a clean start. I exit here rather than in main so main still returns its status to a caller in a development image instead of ending that image.

(try-install-module designation &key source-root custody revocation-path vouch-path loader)

Ask whether the module DESIGNATION names can be installed into this image, by installing it through install-module, and return (values status message).

The node's stores are read and never written, and nothing is appended to the grant audit trail: the vouch store at VOUCH-PATH is decoded into a store held only in memory, which is what admission records into and files a shipped vouch into, and the revocation store at REVOCATION-PATH is only consulted. Either file may be absent, and is then taken as empty. CUSTODY is the node's owner custody, NIL when the node has none. SOURCE-ROOT is the module source root. LOADER is the test seam install-module passes to admission.

STATUS is 0 when the module was admitted and loaded; 2 when no designation was given; 3 when DESIGNATION is not a module designation; 4 when no identity directory under the root holds that module; 5 when it was refused before any of its code ran; 6 when the question could not be asked, because the root or the node state it needs is missing or unusable; and 7 when both signatures admitted it and its load then failed, so some of its code may have run. MESSAGE says which, and why.

(try-supersede-module old-designation new-designation &key source-root custody revocation-path vouch-path loader)

Ask whether the module version NEW-DESIGNATION names can supersede the one OLD-DESIGNATION names, by loading the old version into this process as a restart stands it up, and then the new one as an install admits it, and return (values status message phase redefined warnings).

This is the dry run a node asks for before it compiles anything of a new version into itself, because compiling into a running image is already a change to it. It must run in a process of its own, which it then leaves: the node's stores are read and never written, exactly as try-install-module reads them. CUSTODY, SOURCE-ROOT, REVOCATION-PATH, VOUCH-PATH and LOADER are as for try-install-module.

The old version is re-admitted on the credentials and admission time the node recorded for it, as a restart would, so a version the node could no longer stand up is refused here too. The new version goes through install-module, the gate a fresh install passes.

STATUS is 0 when both loaded; 2 when a designation is missing; 3 when one is not a module designation; 4 when no identity directory holds one of them; 5 when a version was refused before any of its code ran; 6 when the question could not be asked; and 7 when a version was admitted and its load failed. PHASE is "old" or "new", the version STATUS is about, or NIL before either was tried. REDEFINED names each definition the new version's load replaced, and WARNINGS holds the text of every warning that load raised that was not a style warning.