External package toolchains

A channel package can set toolchain: to the package identity of a channel-published toolchain. The toolchain is realized before its consumer; its compiler programs and measured runtime closure are available inside the build sandbox. Packages without this field use the pinned seed compiler, with the same compiler commands.

Metadata format 1

A selected toolchain installs one data form at share/sigil/toolchain.sgl. The file is read as data and is never evaluated. For example, with the actual store item names in place of the placeholders:

(toolchain
  format: 1
  name: "gcc"
  version: "16.2.0"
  target: "x86_64-linux-gnu"
  cc: "/sigil/store/COMPILER/bin/x86_64-linux-gnu-gcc"
  cxx: "/sigil/store/COMPILER/bin/x86_64-linux-gnu-g++"
  ar: "/sigil/store/BINUTILS/bin/x86_64-linux-gnu-ar"
  ranlib: "/sigil/store/BINUTILS/bin/x86_64-linux-gnu-ranlib"
  dynamic-linker: "/sigil/store/GLIBC/lib/ld-linux-x86-64.so.2"
  include-dirs: ("/sigil/store/HEADERS/include")
  library-dirs: ("/sigil/store/GLIBC/lib" "/sigil/store/COMPILER/lib"))

The required fields are format:, name:, version:, target:, cc:, ar: and ranlib:. Name, version and target are nonempty ASCII identifiers using letters, digits, _, +, . and -. Unknown versions, unknown or duplicate fields, missing required fields and trailing forms are refused.

cxx: and dynamic-linker: may be omitted or #f. A C-only compiler does not provide a C++ wrapper. The include and library directory lists default to empty lists. Command and loader paths must name files; directory entries must name directories. All paths must be canonical absolute store paths, without parent traversal, shell metacharacters or linker delimiters. Both the named item and any resolved symlink destination must belong to the selected toolchain's measured closure. The metadata file itself must also resolve inside that closure. A store toolchain selected through package.toolchain must have metadata. Existing low-level toolchain values without metadata keep their original command contract.

Compiler wrappers

For a toolchain with metadata, the builder creates a private wrapper directory in the build root and puts it first on PATH. It exports absolute CC, CXX, AR and RANLIB wrapper paths. It also provides gcc, g++ and the target-prefixed cc, c++, ar and ranlib commands. The compiler wrappers preserve the caller's arguments, then add:

  • -isystem for each metadata include directory;
  • -L for each metadata runtime library directory;
  • -Wl,--dynamic-linker=PATH when a loader is specified;
  • -Wl,-rpath,PATH for the output's lib and lib64 directories first, followed by each runtime library directory and each existing lib directory in the consumer's dependency closure;
  • -Wl,-rpath-link,PATH for the target runtime and dependency directories when the toolchain specifies a dynamic loader;
  • -Wl,--enable-new-dtags so the library paths use DT_RUNPATH.

Include directories supplement the configured sysroot and builtin search paths. Do not repeat a sysroot C header directory here: putting it before the C++ headers can break their include_next search.

Archive and ranlib wrappers receive no compiler or linker flags. The seed compiler path does not create wrappers or alter the build environment. The self-directory default follows Nix's stdenv behavior. A package can set self-runpath: #f, equivalent to Nix's NIX_NO_SELF_RPATH, when those directories should not be searched. This only disables the two self entries; target runtime and dependency paths remain. Standalone compiler wrappers have no package output and keep their original flags.

The metadata is authenticated by the toolchain output hash, which already participates in the derivation key. The external builder's schema revision rekeys builds when its defaults change. Default package canonical values remain unchanged; explicit RUNPATH opt-outs are sealed into the package and build identities.

Installed runtime dependencies

After installation, Sigil checks every regular ELF file in each output, following Guix's validate-runpath convention. Each DT_NEEDED library must be found through that file's DT_RUNPATH; legacy DT_RPATH is used when DT_RUNPATH is absent. Static and non-ELF files are skipped. The check expands $ORIGIN and ${ORIGIN} relative to the installed file and resolves symlinks only within the output and declared runtime inputs. It uses neither host library directories nor a loader cache or LD_LIBRARY_PATH.

A failure lists each affected installed file, the missing library and the effective RUNPATH. Repair the link or install the library before retrying. For a plugin whose shared libraries are intentionally supplied by the executable loading it, set validate-runpath: #f, the equivalent of Guix's #:validate-runpath? #f. This disables only the ELF check; output reference checks still apply. Ordinary links use RUNPATH. Programs using dlopen may need a program-specific wrapper to supply their runtime library search path.

The loader and runtime library items may appear in the consumer's output. The output reference scanner records the items actually referenced. Compiler-only inputs remain build inputs and cannot leak into outputs.

Sandbox loader paths

Declared runtime inputs are available at their store paths. The sandbox does not create /lib/ld-musl-x86_64.so.1 or /lib64/ld-linux-x86-64.so.2 aliases. A program whose interpreter names one of those paths fails at execution with ENOENT, even when glibc is a declared dependency. Package a static program or set its interpreter to the declared loader's store path.