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 a C11 compiler and a linker for your target platform. 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, or MinGW-w64. The compiler target must match the release libraries. Add abi/ to the header search path and your platform's lib/<os>_<arch>/ to the linker search path. Configure the runtime library search path for shared builds as described below.

C links the library at build time, in one of two modes: shared (default) or 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 generated C declarations are in abi/stardust.h. Include that header from your C program. 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#

cc main.c -I$PKG/abi -L$PKG/lib/$PLATFORM -lstardust -Wl,-rpath,$PKG/lib/$PLATFORM -o app

Static mode#

cc main.c -I$PKG/abi -L$PKG/lib/$PLATFORM -lstardust_full -lm -ldl -lpthread -lgcc_s -o app   # Linux

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.