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 Rust 1.85 or newer, Cargo, and a linker for your target platform. Put rustc and cargo on PATH. On Linux, install GCC or Clang with the system development libraries. On macOS, install the Xcode Command Line Tools. On Windows, use Visual Studio C++ Build Tools and the Windows SDK for an MSVC target. A GNU target needs MinGW-w64 instead. The linker, release libraries and Rust target must use the same architecture.

Ordinary binding and generated SDK calls run synchronously on the calling thread. Use standard iterators for query rows. Use subscription.next().await or events.next().await for live events with any executor. Obtain a Canceller before borrowing the subscription for a wait. The binding uses one shared thread to deliver coalesced executor wakeups. Drop cancels a subscription; its final owner releases the native handle. Call close to release it explicitly while cancellation owners remain alive.

rustc --version
cargo --version
rustc -vV

The packaged example's Cargo.toml selects the supplied binding. Its build.rs selects the release's lib/<os>_<arch>/ directory for the target it builds for. Set STARDUST_LIBRARY_DIR when linking libraries from another directory. Configure the runtime library search path for shared builds as described below.

Rust links the library at build time through the binding's build.rs, in one of two modes: shared (default) or static (the static cargo feature). STARDUST_LIBRARY_DIR names the directory that holds the library or archive in both modes; without it the binding uses the package's lib/<os>_<arch>/ for the target being built (--target), so a cross-compile links that platform's library.

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/rust/, and a runnable example is in abi/examples/rust/. 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.

Add the binding to Cargo.toml, and forward the static feature so one flag selects the mode:

[dependencies]
stardust = { path = "/path/to/stardust-<version>/abi/bindings/rust" }
[features]
static = ["stardust/static"]

Shared mode#

cargo build --release

This links dylib=stardust. build.rs sets no run path, so the executable finds the library through the search paths below, or through a run path you add:

RUSTFLAGS='-C link-arg=-Wl,-rpath,$ORIGIN' cargo build --release            # Linux
RUSTFLAGS='-C link-arg=-Wl,-rpath,@executable_path' cargo build --release   # macOS

Ship the executable with the core library (libstardust.so, libstardust.dylib or stardust.dll) and the plugin libraries from lib/$PLATFORM/, kept in one directory. On Windows, both the MSVC and the GNU toolchains link the import library stardust.lib.

Static mode#

cargo build --release --features static
# without a forwarding feature: cargo build --release --features stardust/static

The feature links static=stardust_full instead, plus the system libraries below; build.rs adds them. Ship the executable alone.

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
cargo tree -e features -i stardust | grep static   # static mode lists the feature

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.