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.

Install the Odin compiler and put odin on PATH. On macOS, install the Xcode Command Line Tools. On Windows, install Visual Studio C++ Build Tools and the Windows SDK. Use a compiler target that matches the release libraries.

odin version

The packaged examples import the supplied binding by relative path. Your application can use a relative import or -collection:stardust=<release>/abi/bindings. The binding selects the release's lib/<os>_<arch>/ directory for the target you build for. Keep the package's manifest.json beside lib/ and abi/. Use linker search flags when the library is installed outside the release layout. Configure the runtime library search path for shared builds as described below.

Odin links the library at build time through the binding's foreign import, in one of two modes: shared (default) or static (-define:STARDUST_STATIC=true). Import the binding by path or as a collection: -collection:stardust=$PKG/abi/bindings and import stardust "stardust:odin".

The binding selects the target's library or archive from the release layout automatically. Keep manifest.json beside lib/ and abi/. Outside that layout, it uses the linker's search directories.

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

odin build . -collection:stardust=$PKG/abi/bindings
odin build . -collection:stardust=$PKG/abi/bindings -extra-linker-flags:"-Wl,-rpath,\$ORIGIN"   # Linux: library beside the executable
odin build . -collection:stardust=$PKG/abi/bindings -extra-linker-flags:"-Wl,-rpath,@executable_path"   # macOS: library beside the executable

This links the target's shared library (stardust.lib, the import library, on Windows). 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.

Static mode#

odin build . -collection:stardust=$PKG/abi/bindings -define:STARDUST_STATIC=true

The define makes the foreign import name the archive stardust_full and the system libraries below. Ship the executable alone. The archive brings its own copy of the Odin runtime, separate from the program's.

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

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.