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 the Clojure CLI and JDK 25 or newer. The supplied binding selects Clojure 1.12.5 and org.babashka/ffi 0.1.2 through deps.edn. Put clojure and java on PATH. If JAVA_HOME is set, it must select that JDK. Enable JVM native access when starting the application.

java -version
clojure -Sdescribe

From abi/examples/clojure:

clojure -J--enable-native-access=ALL-UNNAMED -M:run

The release binding loads the core library from the package's lib/<os>_<arch>/ directory for the platform it runs on and checks its SHA-256 first. To load a core library from elsewhere, set STARDUST_LIBRARY to its file or pass -J-Dstardust.library=<file>. Keep the plugin libraries beside the core library.

Clojure loads the shared library at run time through the JVM's foreign function interface. There is only the shared mode: a static archive cannot be loaded at run time, so the library file always ships with the program. Go, Rust and Odin programs can link a static archive instead.

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

Shared mode#

;; deps.edn
{:deps {stardust/stardust {:local/root "/path/to/stardust-<version>/abi/bindings/clojure"}}}

With the binding used from the package's files, as above, it loads lib/<os>_<arch>/ for the platform it runs on, so no library setting is needed:

clojure -J--enable-native-access=ALL-UNNAMED -M -m app.main

To load another file, name it:

STARDUST_LIBRARY=/path/to/libstardust.so clojure -J--enable-native-access=ALL-UNNAMED -M -m app.main
clojure -J-Dstardust.library=/path/to/libstardust.so -J--enable-native-access=ALL-UNNAMED -M -m app.main

Find the shared library at run time#

The binding loads the first of:

1. The file named by the stardust.library system property (-J-Dstardust.library=<file>).
2. The file named by the STARDUST_LIBRARY environment variable.
3. The platform's core library in the package, lib/<os>_<arch>/, when the binding is loaded from the package's files (not from a jar).
4. The bare file name (the core library (libstardust.so, libstardust.dylib or stardust.dll) and the plugin libraries from lib/$PLATFORM/, kept in one directory), through the platform loader: LD_LIBRARY_PATH and the system directories on Linux, DYLD_LIBRARY_PATH on macOS, the executable's directory and PATH on Windows.

The core library file path is necessary for a release binding's SHA-256 check before loading it. The first three supply it; a loader search path alone does not supply that file path. Only development bindings without a core digest can use the system search.

Packaging#

A jar or uberjar contains no library file. Ship the core library (libstardust.so, libstardust.dylib or stardust.dll) and the plugin libraries from lib/$PLATFORM/, kept in one directory with the application and pass -Dstardust.library=<file> or set STARDUST_LIBRARY.

Check the mode#

The mode is always shared. To see which file a running JVM loaded on Linux:

grep libstardust /proc/<pid>/maps

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 every mode, a database enables plugins when it opens, as its license allows.