Linking#

A program uses the library in one of two modes.

• Shared (default): the program loads the shared core library at run time, and the core library loads the plugin libraries beside it. The core library and its plugin libraries ship together beside the program.
• Static: the build links the static archive into the executable. The archive contains the core and every plugin of its release, so the executable is the only file that ships. Go, Rust, Odin and C support it; Python and Clojure load the library at run time and use the shared mode only.

The mode changes only how the program finds the library and its plugins. The operations, ownership rules and results are the same in both modes, and a database enables plugins when it opens in both modes. The sections below give this language's commands for each mode.

Prerequisites#

Before running a packaged example, set STARDUST_TEST_LICENSE to your downloaded license token.

Use Go 1.26 or newer and a C compiler for your target platform. Put both on PATH. Enable cgo for go build, go run and go test, including static builds. Select GCC or Clang with CC if the default compiler is unavailable. On Windows, use MinGW-w64 GCC or zig cc as CC. Cross-compilation also requires a C compiler and Stardust libraries for the target.

Check the Go configuration:

go version
go env CGO_ENABLED CC GOOS GOARCH

In a POSIX shell, run the packaged example from abi/examples/go:

CGO_ENABLED=1 go run .

In PowerShell, with MinGW-w64 GCC on PATH:

$env:CGO_ENABLED = '1'
$env:CC = 'gcc'
go run .

Go links the library at build time through cgo, in one of two modes: shared (default) or static (-tags stardust_static).

Release package files#

Extract stardust-<version>.zip. The commands below call that directory $PKG, and the platform directory you build for or run on (linux_amd64, linux_arm64, darwin_amd64, darwin_arm64 or windows_amd64) $PLATFORM. The binding is in abi/bindings/go/, and a runnable example is in abi/examples/go/. The library files are in lib/<os>_<arch>/, one directory per platform. The repository build writes the same library files to build/.

SHA256SUMS lists every file. Signed packages include SHA256SUMS.minisig. Development packages can be unsigned.

Point your module at the binding. The binding's cgo flags already search the package's lib/<os>_<arch>/ for the platform you build for (GOOS and GOARCH), so you set no library path:

go mod edit -require=stardust@v0.0.0 -replace=stardust=$PKG/abi/bindings/go

Shared mode#

CGO_ENABLED=1 go build -o app .

This links -lstardust. To link a library in another directory, such as $STARDUST_LIBRARY_DIR, add it to the linker search path and the run path:

CGO_ENABLED=1 CGO_LDFLAGS="-L$STARDUST_LIBRARY_DIR -Wl,-rpath,$STARDUST_LIBRARY_DIR" go build -o app .

Ship app with the core library (libstardust.so, libstardust.dylib or stardust.dll) and the plugin libraries from lib/$PLATFORM/, kept in one directory.

Static mode#

CGO_ENABLED=1 go build -tags stardust_static -o app .

The stardust_static tag links -lstardust_full instead, plus the system libraries below; the generated cgo directives add them. go test -tags stardust_static and go run -tags stardust_static work the same way. Ship app alone.

Cross-compile#

The package holds every platform's libraries, so one checkout builds for any of them: set GOOS and GOARCH, and give cgo a C compiler for that platform. With Zig as the C compiler, a Linux ARM64 build from any host is:

CGO_ENABLED=1 GOOS=linux GOARCH=arm64 CC="zig cc -target aarch64-linux-gnu" go build -tags stardust_static -o app .

The cgo flags pick lib/linux_arm64/. A shared-mode build works the same way; ship that directory's libraries with it.

Find the shared library at run time#

The core library then loads the plugin libraries from its own directory, so they need no search path of their own. A static-mode executable looks for nothing: the library and its plugins are inside it.

Check the mode#

A shared-mode executable lists the library as a dependency; a static-mode executable does not.

ldd ./app | grep stardust           # Linux: shared prints libstardust.so, static prints nothing
otool -L ./app | grep stardust      # macOS: shared prints @rpath/libstardust.dylib
llvm-objdump -p app.exe | grep -i stardust.dll   # Windows; or dumpbin /dependents app.exe
go version -m ./app | grep -- -tags   # static mode prints build -tags=stardust_static

Plugins#

In shared mode, the core library loads each plugin library (libstardust_<name>.so, libstardust_<name>.dylib or stardust_<name>.dll) from its own directory and checks it against the release it was built with. Keep the plugin libraries beside the core library, from the same release; a plugin whose library is missing or fails a check is unavailable.

In static mode, the archive contains the core and every plugin of its release. The program ships no plugin files and loads none; link with another release's archive to change the plugin set.

In every mode, a database enables plugins when it opens, as its license allows.