Native module providers in package.sgl
A library's native-init: names the C initializer linked into its application. The builder preprocesses its C sources for the target and discovers the modules that initializer registers. Ordinary packages need no additional declaration. Header-defined initializers and macros are scanned after expansion.
The supported registration statement is a direct call with exactly two arguments:
sigil_begin_module(vm, "(example native)");The return value may be assigned to a variable in the same statement. A failure guard such as if (!sigil_begin_module(vm, "(example native)")) return; is also supported, including parenthesized and null-comparison variants. A helper may register modules when the initializer calls it directly in a plain statement; its return value may likewise be stored before testing it separately.
Other registrar references in the initializer's reachable functions fail the build. These include computed arguments, expressions after a string literal, function-pointer calls, and references inside sizeof, _Alignof, typeof, or other unsupported expressions. Missing initializer definitions also fail. Diagnostics name the source file and line and offer two remedies: use a plain literal call, or declare the modules explicitly.
The native-modules: escape hatch
native-modules: is an optional package-level field for packages with native-init: libraries. Supply the complete list of module names registered by those libraries when their implementation needs an unsupported C form:
(package
name: "example-native"
sigil: "0.24.9"
native-modules: '((example native) (example helpers))
libraries: (list
(library name: 'example-native
c-sources: '("native/example.c")
native-init: "example_initialize")))The default #f selects automatic scanning. A list, including '(), skips the scan and asserts that it completely describes the package's native modules. The declaration is carried by package output collection and import validation, including when a custom action supplies a prebuilt archive and no C compilation action runs. Such a library may omit c-sources:; its native-init: still links into the target and its Sigil runtime dependency is retained. The declaration does not verify the C implementation. Linking still requires the declared initializer symbols. Providers belong to the linked target; modules registered only in the development CLI cannot satisfy its imports.
Limits of automatic discovery
This check catches ordinary mistakes; it does not prove arbitrary C execution. It recognizes function names and statement forms rather than interpreting C control flow. A call inside if (0), a zero-iteration loop, or code after an early return may be counted even though it never executes. Conditional runtime registration and helper-name shadowing likewise require care. Plain helper calls can reach external definitions in the linked target's other preprocessed units; intermediate helper units are retained even when they name neither the initializer nor the registrar. Static helpers remain scoped to their own unit. A registrar supplied only by a prebuilt object needs an explicit declaration. The package author remains responsible for the initializer registering its stated modules when it runs.