compiler.runtime.customInstaller

📄Description

Load the optional compiler module with ncc('--help'). This function creates a runtime-only installer from one to 64 compiler.build.Results objects, or a list of buildresult.json paths. It has no output argument and does not install application executables.

Windows generation uses Inno Setup 6; NELSONC_ISCC can specify ISCC.exe. Linux generation produces a self-contained .install using Bash 4, GNU tar, gzip and core utilities. macOS generation produces a native .pkg using pkgbuild and productbuild. A small native helper is included on Linux and macOS, without a Nelson or Python installation requirement on the target. The installer includes the frozen runtime dependency closure; generation verifies recorded SHA-256 digests and rejects conflicting files, architectures, versions or startup ordering.

RuntimeDelivery accepts web (default) or installer. Web fails explicitly because a runtime download service is not available. Use installer for an offline package. PackageType accepts auto (default) or zip; zip requires installer delivery and Windows. Compression accepts normal (default), fast, max or none for the Windows payload. Existing output files are never overwritten.

OutputDir defaults to a folder named installerName in the current directory. OptionalDependencies accepts all (default) or none. The current Dependencies.Optional table is empty, so both select the same required closure. Required graphical services are never omitted.

Windows installation uses one directory per engine fingerprint. The default is LocalAppData/Nelson/Runtime/fingerprint for a per-user installation and ProgramFiles/Nelson/Runtime/fingerprint for an administrative installation. Standard Inno Setup options, including /CURRENTUSER and /DIR, are accepted.

For noninteractive Windows installation, specify -agreeToLicense yes first, followed by optional -destinationFolder and -outputFile arguments. The destination must be absolute and selects the exact runtime root. Alternatively, -inputfile FILE reads a UTF-8 control file with agreeToLicense=yes first and optional destinationFolder and outputFile entries, one key=value pair per line. The lowercase f distinguishes this runtime argument from an application installer's -inputFile. Agreement may instead precede -inputfile on the command line. Destination and log settings cannot be duplicated between the command line and the file; repeated license consent is allowed.

The Windows control file accepts a UTF-8 BOM, CRLF and lines starting with # as comments, up to 1 MiB. Paths are literal: environment variables and shell expressions are not expanded. Unknown options, applicationFolder, runtimeFolder, shortcut settings, malformed input and existing output logs are rejected before starting the native installer. Without -outputFile, a new nelson_installer_*.log is created in TEMP. Installation waits for completion and returns the native exit code. /CURRENTUSER or /ALLUSERS and /PORTABLE=1 are Nelson-specific additions accepted with these arguments; standard Inno command lines remain a separate form.

Generated Windows runtime installers include a small installation-only launcher with a static C runtime. The compiler verifies its supported format before packaging. It checks the embedded installer's checksum before execution, using bounded buffering, and removes its private extraction directory after normal completion. An abruptly terminated launcher can leave temporary files. This launcher is not included in the installed numerical runtime and does not change application startup. Rebuild older runtime installers to use these deployment arguments.

Successive compatible installers add components to the same runtime. Existing payload files are verified and identical payload files are not rewritten. Module startup order and runtime.json are regenerated from the union. Damaged files, unmanaged collisions, redirected filesystem paths and conflicting identities are rejected before installation. A shared operation lock prevents installation and uninstallation from running simultaneously.

The standard Windows installation registers its root under Software/Nelson/Runtime/architecture/fingerprint in the 64-bit current-user or machine registry. Launchers check NELSONC_RUNTIME_ROOT first, then an adjacent executable.runtime, NELSON_RUNTIME_PATH, shared registrations and standard shared directories on Windows, and finally PATH. A matching interpreter digest is required; PATH is never modified.

On Windows, /PORTABLE=1 suppresses registration while preserving the local uninstaller. A nonstandard portable directory requires NELSONC_RUNTIME_ROOT. Rebuild applications with current launchers to use automatic shared discovery.

The runtime has one independent uninstaller. Removing it removes the shared runtime for all applications that use it, but does not remove those applications or user-created files. Removing an application does not uninstall this separately installed runtime.

For Windows process interruption, rerun the same runtime installer with the same destination, user/administrator scope and portable setting. A private .nelson-runtime-update journal records the previous metadata and expected additions. Recovery checks every recorded path and digest before restoring metadata and reinstalling verified additions, including their uninstall records. Existing runtime payload files are not rewritten. This also supports an interrupted first installation and an interrupted recovery.

Another runtime package and the current uninstaller refuse an incomplete update until recovery finishes. Unknown journal entries, redirected paths, modified payloads and damaged backups are preserved and reported; do not delete the journal to bypass these checks. Incomplete finalization returns a nonzero installer exit code even if payload extraction finished. A fully committed update is verified and its journal retired before another compatible package can proceed. Recovery is not an authentication mechanism and does not protect against concurrent external edits.

Interrupted preparation may leave .nelson-runtime-prepare-* directories. Interrupted cleanup or preserved uninstall state may leave .nelson-runtime-recovered-* directories. These private directories and unclaimed temporary files are retained rather than removed recursively. Recovery covers process interruption, not power-loss durability or an atomic swap of the entire runtime. Its checks run only in the installer, never in application startup or numerical execution.

Linux installation is noninteractive. Use -agreeToLicense yes first, optionally followed by -destinationFolder and -outputFile. The alternative -inputfile FILE accepts UTF-8 key=value lines for agreeToLicense, destinationFolder and outputFile, with agreement first. Its lowercase f differs from the application installer's -inputFile. BOM and CRLF are accepted; NUL bytes, unknown or conflicting options and existing output logs are rejected. Values are never evaluated as shell code. ZIP and applicationFolder are not supported by this runtime installer.

Linux defaults to XDG_DATA_HOME/nelson/runtimes/fingerprint, falling back to HOME/.local/share, for an ordinary user, and /usr/local/lib/nelson/runtimes/fingerprint for root. Registration uses XDG_CONFIG_HOME (or HOME/.config), or /etc/xdg for root, with the format documented by ncc. Installer paths cannot contain symbolic links or dot segments; the runtime directory cannot contain colon, semicolon or dollar characters. Root privileges are not required for a writable per-user destination. Linux build reports must record runtimeDiscoveryVersion 3; older applications must be rebuilt.

The Linux helper merges compatible inventories and copies only new payload files. It verifies existing files and rejects unmanaged collisions, changed permissions and conflicting startup catalogs. The local .nelson-runtime/uninstall executable takes no arguments and removes unchanged owned files; modified payload files and user data are preserved. Ownership metadata must remain intact. Operation lock files are deliberately retained, so the destination can remain after removal. Stop applications before updating or removing their runtime.

For Linux process interruption, rerun the same package with the same destination and registration scope. The private .nelson-runtime/update.json journal records old and proposed inventories. Recovery validates old files, verified additions and old/new metadata before completing the update. First installations and interruptions during metadata publication or registration are supported. Another package and the uninstaller refuse an active journal. After successful journal retirement, another compatible package can proceed even if the preceding process did not finish reporting success. Unknown or modified files are not forcibly replaced. Interrupted staging may leave private temporary directories or .nelson-runtime-write-* files. Recovery is not an atomic whole-runtime replacement and does not guarantee power-loss durability or protection against concurrent external edits.

Linux uninstallation has a separate .nelson-runtime/remove.json journal. Rerun the installed uninstaller after interruption, including an interrupted recovery. The journal binds the original ownership inventory to the runtime directory and checks its checksum and remaining metadata before further removal. Installation refuses a pending removal. The uninstaller removes only the matching registration and unchanged owned payload files; modified, redirected or unverifiable files and user data are preserved. Failure to delete a verified owned file returns an error and keeps removal pending. Restore the required directory permissions and rerun the uninstaller.

Removal records a complete receipt before deleting the uninstaller itself. This receipt and operation locks remain after success, so the directory can remain. A completed operation never scans payload files again when resumed. A subsequent installer can retire the verified receipt and reuse an otherwise empty managed directory, including for another runtime version. Preserved files or unrecognized leftovers prevent reuse; they are not deleted or overwritten. Do not modify or remove the journal to bypass these checks. These recovery rules require the current native helper and do not authenticate the publisher.

Linux .install output is reproducible with identical runtime/helper bytes, attributes, options and packaging tools. New payload files use 2000-01-01 UTC; existing identical payload files retain their dates. Generated metadata has installation-time dates. The CLI deployment gate uses Debian 13 x86-64; other distributions, system-wide installation and graphical applications require additional native validation.

On macOS, the package installs a fingerprint-addressed runtime under Library/Application Support/Nelson/Runtimes and registers it under Library/Application Support/Nelson/config for maca64 or maci64 launchers. The native helper merges compatible inventories and rejects changed files, unmanaged collisions, conflicting module order or a different identity. Its .nelson-runtime/uninstall program removes only unchanged owned files and the matching registration; modified and user-created files are preserved. Application packages and this shared runtime package have independent removal.

The macOS package preserves dylib and framework layout, validates architecture and install names, rewrites relocatable non-system dependencies and locally ad-hoc signs modified binaries. The generated package is otherwise unsigned. Developer ID Installer signing, notarization and Gatekeeper validation require suitable credentials and network services and are not claimed by a local build. System-wide installation requires administrator authority; an isolated alternate target may be used for testing the package scripts.

Runtime hashes provide consistency checks, not publisher authentication. Signing, automatic repair, interactive Linux installation and very large multi-volume outputs remain separate work. Inventory hashing and compression occur during packaging or installation, not inside numerical operations.

Unsigned EXE and ZIP outputs follow the reproducibility contract of compiler.package.installer. Newly installed packaged files use 1980-01-01 00:00:00 UTC. Existing identical runtime files retain their modification dates. The union inventory and startup files are generated during installation and are not covered by that fixed-date guarantee.

Build reports must use format 2 and include a supported native launcher contract. Older reports cannot establish that their applications support shared-runtime discovery; rebuild those applications with current launchers before generating this installer.