Executable collector settings

Native executables can declare collector policy in their selected package.sgl build configuration. All fields are optional; omitting them preserves the runtime defaults. For example, a fixed nursery budget can be declared with:

(config name: 'release
  gc-young-initial-kib: 512
  gc-young-max-kib: 512)
FieldUnit / typeBuilt-in defaultAccepted rangeTradeoff
gc-young-initial-kibKiB, exact integer40961–137438953471Smaller nurseries shorten individual minors but increase collection frequency and promotions.
gc-young-max-kibKiB, exact integer163841–137438953471Caps adaptive nursery growth; a larger ceiling can improve throughput at the cost of longer minors.
gc-adaptive-youngboolean#t#f or #tAllows the nursery to grow toward its ceiling when young reclamation is low.
gc-minor-enabledboolean#t#f or #tDisabling automatic minors leaves reclamation to majors and explicit collection hints.
gc-heap-grow-factorreal multiplier21.05–8, inclusiveLarger values reduce major frequency while increasing the allowed heap.
gc-major-initial-kibKiB, exact integer40961–137438953471Sets the first automatic major threshold and its post-major floor.
gc-major-min-headroom-kibKiB, exact integer81921–137438953471Sets the minimum free headroom after a major; smaller headroom can cause frequent majors.

One KiB is 1024 bytes. Budget values must also fit the target's size_t; 32-bit targets have a smaller limit, checked when compiling executable metadata. Invalid declarations fail the build with a diagnostic. An explicitly declared young maximum must be at least the effective initial value (4096 KiB if the initial field is omitted); inconsistent declarations fail at build time. If only the initial field is declared above the default maximum, the runtime raises that default maximum to the initial value. Environment overrides may also raise the effective maximum to the effective initial value.

The next major threshold is the maximum of live bytes times the growth factor, live bytes plus minimum headroom, and the initial threshold. A small multiplier may therefore have no effect while either floor dominates.

For each existing environment knob, precedence is valid environment override, then executable setting, then built-in default. SIGIL_YOUNG_THRESHOLD and SIGIL_YOUNG_THRESHOLD_MAX use KiB; SIGIL_GC_HEAP_GROW_FACTOR uses a real multiplier. They retain their existing parsing behavior, with invalid numeric values falling back. SIGIL_GC_ADAPTIVE_YOUNG=0 disables adaptation; other present values enable it. SIGIL_GC_DISABLE_MINOR=1 or SIGIL_GC_ENABLE_MINOR=0 disables automatic minors; either disabling override wins if both switches are supplied. SIGIL_GC_ENABLE_MINOR=1 or SIGIL_GC_DISABLE_MINOR=0 enables them over a disabled build setting. The two major KiB budgets have no environment overrides. Debug, tracing, statistics and stress controls remain environment-only.

The generated app_info.c embeds the settings. GC initialization applies them before the first managed allocation, for every VM in that executable. They change final executable metadata and bundle cache identity, without changing dependency compilation or shared libsigil identity. Configured bytecode/dev applications link a custom runtime. Older SDKs lacking SIGIL_GC_BUILD_CONFIG, WebAssembly and UEFI targets are rejected when settings are declared.

A program does not export these settings into its environment. A distinct unconfigured child executable uses defaults; executing the configured artifact again uses its own embedded settings. Explicit environment overrides inherit normally. A generic prebuilt Sigil CLI cannot acquire settings from a package it evaluates: build and run the configured executable.

Inspect young-threshold-initial-bytes, young-threshold-max-bytes, young-threshold-bytes, adaptive-young-enabled, minor-enabled, heap-grow-factor, major-initial-bytes and major-min-headroom-bytes in (gc-stats). Boolean policy stats use 0 and 1. Measure major pauses and retained heap before selecting a non-default policy for an application.