Runtime packages

Nexus Pascal supports ordinary static applications and runtime packages with the standard compiler on Windows x64 and Linux x86-64/glibc.

A static application does not acquire a shared nxrtl dependency merely because the compiler supports packages. Applications choose package dependencies explicitly.

What a package contains

A package combines Pascal units into a native loadable image with Nexus package metadata. The shared foundation, nxrtl, owns the common runtime units. Consumers use a matching package SDK with the compiler, startup units, shared foundation, and identity information.

Package declarations use explicit requirements and contained units:

package CustomerModel;
requires nxrtl;
contains CustomerTypes;
end.

This declaration is an input to a package build; it does not independently provision the SDK or select native linker settings.

Keep identities together

Use the SDK supplied with the compiler release. Its sdk.json identifies the compiler/runtime and packaged files. Nexus Build's Tools.NXPC.PackageSDKIdentity must match that SDK.

The compiler checks package and unit identities. Do not mix startup units, shared RTLs, or compiled units from unrelated builds.

Requires in a Nexus Build project describes project dependencies. Compiler RequiredPackages, package paths, and SDK identities are separate explicit build settings. Project dependency resolution does not infer them.

Loading and unloading

Startup-linked packages and synchronous LoadPackage/UnloadPackage use the package runtime. Before unloading, release objects, interfaces, callbacks, and other references into the image.

Late load/unload involving TLS uses the current single-threaded lifecycle contract. Package support on other CPUs/libcs is not established by the presence of their static RTLs.

Build examples

The Nexus Forge release recipe for Nexus Pascal builds the native package SDK as part of the complete compiler product. A separate experimental compiler executable is unnecessary.

Nexus Lab runtime-loading examples provide application and package sources. Use the matching SDK and the supplied Nexus Forge package templates; inspect their explicit package requirements and publication outputs.

For source construction, see Compiler bootstrap.

Development metadata and distribution

A runtime package normally contains its compressed development metadata inside the .nxpl image. To keep it in an adjacent .nxp file instead, use:

BuildControl Options {
    EmbedPackageMetadata: Disabled;
}

The equivalent compiler option is -FJ-; -FJ enables embedding. Development consumption needs both files when metadata is separate. Runtime deployment needs the .nxpl image and its required package/native libraries. Ordinary native libraries retain their platform filenames.

Embedded metadata takes precedence over a sidecar; damaged embedded metadata does not trigger fallback. Complete the image before signing it and preserve its metadata section if the package will be used to build other applications.

Lifecycle requirements

Use SysUtils.LoadPackage and UnloadPackage, with EPackageError for package diagnostics. Do not bypass their lifecycle through FreeLibrary or dlclose. Dependencies initialize first and finalize in reverse order; startup-linked packages remain loaded until process exit. Package identities are checked before user initialization.

Do not initiate another load/unload from package initialization or finalization. Declare requirements or perform these operations from host code instead. The manager tracks package dependencies and explicit load references, not arbitrary objects, pointers or callbacks retained by application code.

Late lifecycle operations on packages containing threadvars require IsMultiThread=False. Joining workers does not normally reset that flag; do not reset it to bypass the restriction. Cross-thread late load/unload is unsupported. There is one active image per package identity: unload and reload after releasing users, rather than attempting simultaneous versions or live replacement.