Portable application runtimes

Some applications need more than one executable to run. A browser has helper programs and shared libraries; a game has libraries and a directory of assets. A portable application runtime lets you ship all of that as one download. You build it once, test it on the Linux distributions you want to support, and people run it without installing Sigil first.

You stage your application's files in a directory, describe that directory with (sigil build runtime), and get back a single executable. When someone runs it, a small static launcher verifies the files, unpacks them into their cache and starts your program. Later runs reuse the unpacked files.

If your application is one self-contained program, you don't need any of this: sigil bundle or sigil build already gives you a standalone executable (see Shipping Applications). Reach for a portable runtime when your app needs shared libraries, external helper programs or large data files to travel with it.

The launcher currently supports Linux x86-64. Packaging a runtime doesn't make your app work on a given distribution, graphics driver or sandbox configuration; it only gets your files there. Test the complete application on each platform you intend to support.

Choose how your program starts

The first decision is how your entry program gets loaded. Each mode has its own constructor:

ConstructorExecution policy
(make-runtime-tree root application entry loader library-directories)Format and launcher ABI 1: use the bundled loader and ordered library directories.
(make-host-runtime-tree root application entry)Format and launcher ABI 2: execute the entry directly, using its host interpreter and library search policy.

Host-loader mode is the simpler one. The kernel starts your entry program directly, so it uses the host's ELF interpreter and C library, just like any other program on that system. Choose it when your app can rely on the system's own libraries, built against an old enough baseline to cover the distributions you support. Your application owns its relative RUNPATHs, its minimum host ABI, its dependency checks and its diagnostics. A small entry program can check the host before starting the main application. This mode doesn't remove your application's host-library requirements; it just leaves them in your hands.

Bundled-loader mode carries its own ELF loader and libraries. Choose it when you want your app to run on the loader and libraries you shipped rather than the host's. Stage a compatible ELF loader, your libraries and any helper programs. The launcher gives the loader an explicit library search path and disables its cache. The loader's other lookups still follow glibc's explicit loader invocation rules, so a library you forgot to stage can still be found on the host. This mode doesn't discover your dependencies or audit indirect plugin and system-library lookup, so those checks belong in your packaging process. Helper programs need a small trampoline in this mode, which Helper processes describes.

In both modes, paths inside the runtime are relative to root. The application identifier starts with a lowercase letter or digit and may contain lowercase letters, digits, periods, underscores and hyphens. It also names your application's cache directory.

A worked example

Let's package a small application from start to finish in host-loader mode. almanac prints today's entry from a data file and draws a box around it with a separate helper program, so three things need to travel together: the main program, the helper and the data.

almanac/
├── package-almanac.sgl
├── share/almanac/entries.txt
└── src/
    ├── almanac.sgl
    └── frame.sgl

Find your files at run time

Before it starts your entry program, the launcher sets SIGIL_RUNTIME_ROOT to the absolute path of the unpacked runtime. Build every path to your own files from it. During development there's no launcher, so this example falls back to reading the staged tree directly:

;;; almanac: print today's entry from the bundled data, framed by a helper.
(import (sigil process) (sigil fs) (sigil path) (sigil string) (sigil time))

;; Inside a portable runtime, the launcher sets SIGIL_RUNTIME_ROOT to the
;; extracted tree. During development, read the staged tree directly.
(define root
  (or (getenv "SIGIL_RUNTIME_ROOT")
      (realpath "stage")))

(define entries
  (filter (lambda (line) (not (string=? line "")))
          (string-split (read-file-string (path-join root "share/almanac/entries.txt"))
                        "\n")))

(define entry
  (list-ref entries (modulo (time-yearday (current-second)) (length entries))))

(exit (process-run (path-join root "libexec/almanac-frame") entry))

The helper is an ordinary program. In host-loader mode, staged helpers run directly:

;;; almanac-frame: draw a box around its argument.
(import (sigil process))

(define text (cadr (command-line)))
(define rule (make-string (+ (string-length text) 2) #\-))

(display (string-append "+" rule "+\n"))
(display (string-append "| " text " |\n"))
(display (string-append "+" rule "+\n"))

Stage and package it

This script builds both programs with sigil bundle, copies the data into place, and packages the staged tree:

;;; Stage almanac and package it as one portable executable.
(import (sigil shell prelude) (sigil fs) (sigil build runtime))

(define launcher (arg 1))

;; Stage the runtime tree: the entry program, its helper and its data.
(each directory '("stage/bin" "stage/libexec" "stage/share/almanac" "dist")
  (ensure-directory directory))
($ sigil bundle src/almanac.sgl -o stage/bin/almanac)
($ sigil bundle src/frame.sgl -o stage/libexec/almanac-frame)
(copy-file "share/almanac/entries.txt" "stage/share/almanac/entries.txt")

;; Describe the staged tree, then wrap it in the launcher.
(define runtime
  (make-host-runtime-tree "stage" "almanac" "bin/almanac"))

(println "~a entries, ~a bytes, cache key ~a"
  (length (runtime-tree-entries runtime))
  (runtime-tree-total-bytes runtime)
  (runtime-tree-cache-key runtime))

(write-runtime-bundle! runtime launcher "dist/almanac")

sigil bundle marks its outputs executable, which the entry needs. Only the packaging script uses (sigil shell prelude); the staged programs stick to (sigil process), (sigil fs) and the other standard library modules.

Build the launcher

Run this command from a Sigil source checkout. It adds musl to the Guix development environment for the static launcher and helper builds:

guix shell -m manifest.scm musl -- make CC=gcc PORTABLE_CC=musl-gcc build/boot/bin/sigil-runtime-launcher build/boot/bin/sigil-runtime-helper

These targets build the launcher and its helper trampoline. Build and stage your application's dependencies separately. Use a separate guix shell -m manifest.scm without musl when linking ordinary GCC programs.

Run it

Run the packaging script with the launcher's path:

$ sigil package-almanac.sgl ~/src/sigil/build/boot/bin/sigil-runtime-launcher
7 entries, 19749275 bytes, cache key 9ddc4755ffc0e71fd2cdbea00d05e777e55f50f63c23b4eb0efb618699f6d93a

dist/almanac is the one file you give to people. Your cache key will differ, since it depends on the exact bytes you staged. The first run unpacks the runtime into the cache and then starts the app:

$ ./dist/almanac
+-----------------------------------------------------+
| Bees stay close to the hive when a storm is coming. |
+-----------------------------------------------------+
$ ls -A ~/.cache/sigil/runtime/almanac/9ddc4755ffc0e71fd2cdbea00d05e777e55f50f63c23b4eb0efb618699f6d93a/
.complete  .runtime-manifest  bin  libexec  share

Later runs find the completed tree and go straight to the app. To hash every cached file against the manifest, run the executable with this argument alone:

$ ./dist/almanac --sigil-runtime-verify-cache
Verified runtime /home/you/.cache/sigil/runtime/almanac/9ddc4755ffc0e71fd2cdbea00d05e777e55f50f63c23b4eb0efb618699f6d93a

Desktop integration

To offer a launcher menu entry and file associations on Linux, include desktop metadata in the tree you pass to make-host-runtime-tree or make-runtime-tree. Use the runtime's application identifier in these paths. This example uses org.example.almanac.

Staged pathContents
share/applications/org.example.almanac.desktopDesktop entry template.
share/icons/hicolor/48x48/apps/org.example.almanac.pngOptional application icon. You can also include other square sizes or a scalable SVG under hicolor/scalable/apps/.
share/mime/packages/org.example.almanac.xmlOptional Shared MIME-info package for custom file types.

The template is a UTF-8 desktop entry with a single [Desktop Entry] group. Supply Type=Application, Name, and Exec=@SIGIL_RUNTIME@. Append one of %f, %F, %u, or %U to Exec if the program opens files or URLs. The launcher substitutes the desktop command. It handles the loader and cache lease as it does on a terminal launch. Desktop actions, D-Bus activation, and TryExec are outside the template format.

[Desktop Entry]
Type=Application
Name=Almanac
Exec=@SIGIL_RUNTIME@ %f
Icon=org.example.almanac
MimeType=application/x-almanac;

Use MimeType to advertise the file types your entry can open. Supply a Shared MIME-info package if you also need to define custom types and filename patterns.

Run the packaged executable as the current user to install or remove the registration.

./dist/almanac --sigil-runtime-install-desktop
./dist/almanac --sigil-runtime-remove-desktop

Registration uses $XDG_DATA_HOME, with $HOME/.local/share as the default. Install verifies the cached runtime and refuses a conflicting desktop file, icon, or MIME package. It records the device and inode of each link in a per-app manifest under sigil/runtime-desktop/. The registration directories must share a filesystem that supports hard links to symlinks and atomic no-replace renames. A subsequent launch updates the desktop command and the asset links if the bundle or extracted runtime has moved. Keep the packaged executable available for menu launches. After moving it or changing the cache location, run it once from the new location to update the registration. Use a bundle path without an equals sign or control characters. For a path containing a literal percent sign, desktop launches use env from PATH so desktops expand the percent escape correctly.

Remove uses the manifest and works even if the extraction cache is gone. It reports and preserves replacements at registered paths, including links to the same target. If another process claims the public name before a racing replacement can be restored, remove reports where it retained the file. A retry can restore it after the name is available. Both commands refresh the relevant desktop and MIME databases when the corresponding tools are on PATH.

Bundled-loader mode

For bundled-loader mode, stage the loader and the libraries alongside your program. For example, after staging bin/viewer, lib/ld.so and its libraries:

(import (sigil build runtime) (sigil fs))

(ensure-directory "dist")
(define runtime
  (make-runtime-tree "stage" "viewer" "bin/viewer" "lib/ld.so" '("lib")))
(write-runtime-bundle! runtime
  "build/boot/bin/sigil-runtime-launcher" "dist/viewer")

Only the constructor differs between the modes. For host-loader mode, use this one in the same packaging sequence, as the almanac example does:

(define runtime
  (make-host-runtime-tree "stage" "viewer" "bin/viewer"))

Helper processes

In bundled-loader mode, a helper can't simply be executed, because its own interpreter path would bypass your bundled loader. Instead, place a copy of sigil-runtime-helper at the helper's invocation path, such as libexec/worker, and its real ELF program beside it as libexec/worker.elf. Both must be executable manifest entries. The helper locates and validates its enclosing runtime, then invokes the companion through the bundled loader. Arguments and inherited IPC descriptors are kept.

Host-loader mode can execute ordinary staged helpers directly, as the almanac example does. In either mode, application code still decides how to find helpers, expose resources inside a sandbox and configure plugins, graphics drivers, fonts and media libraries.

Staging rules

Prepare a quiescent stage/ directory containing only regular files and directories. Resolve library symlinks into the staged layout deliberately; symbolic links, devices and other special files are refused. Mark the entry, loader and helper executables as executable before preparing the tree.

write-runtime-bundle! returns the output path. Its parent directory must already exist outside the staged tree. Keep the source tree unchanged until writing finishes. The writer streams file contents and verifies the completed output before publishing it.

Metadata is deterministic: entries are sorted, file contents have SHA-256 digests, and modes normalize to 0600 for data and 0700 for executables and directories. These properties don't promise identical native compiler output.

The format allows at most 32,768 entries, 4 MiB of manifest text, 8 GiB per file and 16 GiB of file contents in total. Bundled-loader mode accepts one to 32 distinct library directories. Invalid paths and exceeded limits raise errors.

API reference

Import (sigil build runtime).

ProcedureResult
(make-runtime-tree root application entry loader library-directories)Prepared bundled-loader tree, format and launcher ABI 1.
(make-host-runtime-tree root application entry)Prepared host-loader tree, format and launcher ABI 2.
(runtime-tree? value)Whether the value is a prepared runtime tree.
(runtime-tree-manifest tree)The canonical manifest text.
(runtime-tree-cache-key tree)The manifest text's SHA-256, which names the cache directory.
(runtime-tree-entries tree)The sorted directory and file entries.
(runtime-tree-total-bytes tree)The total size of the tree's regular files.
(runtime-relative-path? value)Whether the value meets the manifest's relative-path rules.
(write-runtime-bundle! tree launcher output)Writes the executable and returns output.

A relative path is nonempty and has no leading or trailing slash, no empty, . or .. components, no backslash or colon, and no ASCII control characters. UTF-8 names are allowed. A path is at most 4,095 bytes and each component at most 255 bytes. .complete and .runtime-manifest are reserved at the top of the tree.

The cache

The cache lives at $XDG_CACHE_HOME/sigil/runtime/<application>/<manifest-sha256>/, or $HOME/.cache/sigil/runtime/<application>/<manifest-sha256>/ when XDG_CACHE_HOME is unset or empty. The chosen cache home must be absolute, caller-owned and unavailable to other writers. The ancestor check follows no links and permits trusted sticky directories. Only the actual filesystem root owned by 0:0 has the special allowance for group-0 writes. Later ancestors keep their stricter checks.

Your home or cache directory can be reached through a symbolic link, as on systems where /home is itself a link. Only links owned by root or by you, in directories that only root or you can write to, are followed. The launcher resolves the selected cache base to its physical path, then checks that directory and its ancestors without following further links. Paths below the base retain the same no-follow checks. SIGIL_RUNTIME_ROOT names the unpacked runtime in that physical directory.

Cold extraction verifies contents before publishing a complete tree. Concurrent first starts serialize extraction, so they share one completed tree. Warm starts check the cached layout, ownership, modes, metadata and file sizes. They don't rehash file contents; --sigil-runtime-verify-cache does. Verification prepares or repairs the cache when safe and exits without starting the application. It prints the same Verified runtime line whether or not it repaired anything.

A damaged tree is replaced only with an exclusive lifetime lease and no active session markers. A busy tree is preserved: verification stops with an error instead of touching it. There is no automatic pruning of old versions, so each changed build of your app leaves its previous tree in the cache.

An app can provide install and uninstall commands by bundling a static libexec/sigil-install executable with mode 0700 and a share/sigil/install-policy.sgl file. This installer handles the app's own files. After a successful uninstall that confirms removal, the launcher removes the cached runtime. It pins the entries listed in the verified manifest and preserves unexpected files. If the open-file limit prevents verification, the existing tree stays in place. If removal fails after the verified tree moves to a private .remove-* directory, the error identifies that directory. Later starts can extract a new runtime while the preserved files stay there.

The cache must have enough free space and permit execution. These checks protect against other users; same-user processes remain outside the cache isolation boundary. Cache hashes provide integrity, not publisher authentication. Authenticate the downloaded executable through your application's distribution mechanism.

While your app runs

The launcher supervises your app, preserves its exit status and waits for its descendants before clearing its session. If a launcher is killed outright and its cached tree is later damaged, its abandoned session prevents replacement.

With a controlling terminal, the app stays in the shell's job, including when launched in a pipeline. A foreground app can read from the terminal. Use Ctrl+C to interrupt the job, Ctrl+Z to suspend it and fg to resume it in the foreground. An app that suspends itself also stops the job.

The launcher forwards SIGINT, SIGTERM, SIGHUP and SIGQUIT sent to its PID to the supervised app and helpers in a terminal session. Without a controlling terminal, the launcher gives the app its own process group and forwards these signals to that group.

Ordinary app launches require an unprivileged user. A root invocation requires an explicit install or uninstall command and an app-provided libexec/sigil-install-root executable. The launcher refuses kernel secure-execution mode or differing real and effective credentials. It clears its supported loader-injection environment variables before executing the app entry.

Streaming assets and executable transformations

These tools are useful beyond portable runtimes.

For ordinary SGLPAK bundles, (sigil build bundle) provides (bundle-add-file-asset! bundle source archive-name). It defers opening the file until bundle-write!, so keep the source unchanged until writing ends. Archive names must be unique across modules and both asset kinds. The older bundle-add-asset-file! still reads its input eagerly.

Use (bundle-transform-base! source output transform) when stripping or relocating a trailer-based SGLPAK executable. transform receives a temporary file containing only its executable base. The procedure preserves the appended ZIP bytes, updates the trailer offset and publishes only after success. Source and output may be the same path. Allow temporary disk space for the base, archive and completed output.

An ELF inner executable with an image bundle can be transformed as an ordinary ELF file. Preserve its loadable .sglpak section and allocated Sigil bundle note. The outer portable runtime launcher still reads a trailer bundle.

Inside a running bundle, (sigil archive) exports (bundled-archive-extract-file archive-name destination). It streams one entry to the destination and returns a boolean result. The caller chooses a safe destination and removes any partial output after failure; this low-level API doesn't apply runtime-cache or installation ownership policy.