Target-specific XELIB libraries

What a XELIB contains

A XELIB contains versioned semantic metadata, public exports and documentation, already-bound implementation IR, generic definitions and dependency identities. It contains no Xenon source, native object/archive, LLVM bitcode or deferred conditional recipes. Its target triple, resolved semantic layout and sorted build defines are part of the artifact.

The consumer reconstructs ordinary Xenon symbols from this metadata, specializes generics it uses, selects reachable implementation bodies and generates native code for a compatible target. Selection follows calls, private helpers, used types and static/TLS fields; merely listing a XELIB does not emit its unrelated functions, dispatch tables or storage. Native export declarations remain roots. The final executable or native library does not need the .xelib file at runtime.

Build for a target

[project]
name = "Geometry"
type = "xenon-library"
version = "1.0.0"

[source]
root = "src"

xenon build Geometry.xeproj
xenon build Geometry.xeproj --target aarch64-unknown-linux-gnu

Without user defines, output is build/<canonical-target-triple>/Geometry.xelib. With user or project defines, an additional defines-<fingerprint> directory identifies the effective set, for example build/aarch64-unknown-linux-gnu/defines-<fingerprint>/Geometry.xelib. The fingerprint is the lowercase 64-hex SHA-256 digest of the sorted, deduplicated define names. Each target and define set has a separate artifact; no native object emitter, archiver or linker runs during XELIB production.

Debug/Release, optimization level, CPU and CPU features are final native-code settings and do not create separate XELIB variants. Both profiles use the same library output path and may consume the same source-independent XELIB when the canonical target triple and fixed producer defines match. See the profile-define policy below.

Reference a XELIB explicitly

[project]
name = "Game"
type = "executable"

[source]
root = "src"

[libraries]
libraries = [
    "../Geometry/build/x86_64-pc-windows-msvc/Geometry.xelib",
    "sqlite3"
]

A path ending in .xelib is resolved relative to the .xeproj file and routed to the Xenon library reader. Every other entry keeps its existing native-linker meaning. library-paths is only a native linker search setting and is not searched for XELIB files.

Identity and dependencies

A XELIB records its name, optional version and deterministic content identity. The identity covers the canonical semantic sections, dependency identities, Library IR version, language version, canonical target triple and sorted producer defines. It deliberately excludes absolute paths, timestamps, section offsets and physical compression layout. Dependencies are matched by content identity, so semantically identical artifacts loaded from different locations are the same library. Two artifacts that claim the same name and version but have different content are rejected.

A xenon-library project may use [references] projects for another xenon-library project. The build runs dependency-first and records the dependency identity without embedding the dependency artifact. A final consumer automatically receives that referenced project's transitive XELIB closure; exact content identities reached through multiple paths are loaded once. XELIB projects cannot reference native project outputs. Every source dependency receives the final build target. An explicit foreign target never falls back to the host.

Conditions are resolved during library production

All target, architecture, CLI and project-local conditional defines are evaluated before binding and serialization. Only selected declarations, fields, externs and bodies enter the XELIB. Ordinary active semantic errors always prevent emission; errors in excluded branches do not.

A consumer's defines cannot change a prebuilt library. Rebuild the library for a different target or feature set. Source-independent generics still specialize from bound generic IR at consumption time, using the same target ABI. Open generic layout expressions resolve when their type arguments become concrete.

XENON_DEBUG and XENON_RELEASE are unavailable in XELIB source directives. Use explicit feature defines when a library needs semantically different behavior. This keeps ordinary Debug/Release and O0/O3 consumers compatible with one artifact.

Tooling and compatibility

The XELIB header keeps three independent validation fields: container version, Library IR version and language version. Their format values are 1 / 1 / 1. Readers require exact values and reject an incompatible artifact rather than guessing or reinterpreting its semantic records.

The language server uses the compiler reader's metadata-only mode: it reads symbols, documentation, semantic summaries and generic implementations while skipping ordinary implementation-body decoding. Completion, hover and signature help work without original sources. Changes to an explicitly referenced XELIB reload the affected workspace. Set initializationOptions.targetTriple for a workspace targeting a different ABI.

The reader validates the XELIB signature, container/Library IR/language versions, section bounds and references, dependency identities, the required BuildConfiguration section and content digest. Missing, unsupported or corrupt artifacts are reported as XELIB build errors and are never passed to the native linker as a fallback.

Compatibility requires an exact canonical triple, including ABI/environment. Architecture aliases such as arm64/aarch64 are normalized; GNU and musl remain distinct. A mismatch reports both targets before source binding or native generation. The Library IR version is 1.

Resumable implementations

Library metadata preserves the IsAsync modifier, await, resolve and reject operator identities, resumable body IR, inferred result lifetime dependencies and lifetime store effects. Lifetime contracts remain available on metadata-only imports without reanalyzing ordinary bodies. Generic resumable functions and operators on generic structs can be specialized by consumers without source files. See Await and resumable functions for the protocol, lifetime rules and diagnostics.