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 Python 3.12 or newer with ctypes available. The binding and generated SDK use standard-library asyncio. Await native operations and use async with for their returned owners. For example, async with await stardust.open(path) as database opens and closes a database. Read subscription events and query rows with async for. Run these examples inside an async def function, then call asyncio.run(main()) at the program entry point. Put python3 on PATH, or use py -3 on Windows. The interpreter must have the same architecture as the release libraries. The packaged examples select abi/bindings/python automatically. For your application, install that package or add its directory to PYTHONPATH. The binding finds lib/<os>_<arch>/ for the platform it runs on when you preserve the release layout. Set STARDUST_LIBRARY to the core library file when using another layout. On Windows, PATH alone does not select libraries for ctypes.

python3 --version
python3 -c 'import ctypes; import struct; print(struct.calcsize("P") * 8)'

Run python3 evaluate.py from abi/examples/python, or py -3 evaluate.py on Windows.

Python loads the shared library at run time through ctypes. 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/python/, and a runnable example is in abi/examples/python/. 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#

PYTHONPATH=$PKG/abi/bindings/python python3 app.py
STARDUST_LIBRARY=/opt/app/lib/libstardust.so PYTHONPATH=$PKG/abi/bindings/python python3 app.py   # explicit library file

Find the shared library at run time#

The binding loads the first of:

1. The file named by the STARDUST_LIBRARY environment variable.
2. stardust/lib/<library file> inside the Python package, as a wheel built with the libraries carries it.
3. The release layout: lib/<os>_<arch>/<library file> in the package for the platform Python runs on, while the binding stays in abi/bindings/python/.
4. The bare file name, through the platform loader: LD_LIBRARY_PATH and the system directories on Linux, DYLD_LIBRARY_PATH on macOS. On Windows, Python's DLL search covers the interpreter's directory, the system directories and directories added with os.add_dll_directory, but not PATH.

Packaging#

The generated pyproject.toml builds a package from the binding. Without library files it is pure Python: 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 set STARDUST_LIBRARY, or keep the release layout.

To build a wheel that carries the libraries, copy the core library and the plugin libraries (not the static archive) into the Python package's stardust/lib/ directory first. The binding then loads the core library from there, and the core library finds the plugin libraries beside it. The wheel holds native code for one platform, so build one wheel for each platform.

mkdir -p $PKG/abi/bindings/python/stardust/lib
cp $PKG/lib/$PLATFORM/*stardust*.so $PKG/abi/bindings/python/stardust/lib/   # Linux; .dylib on macOS, .dll on Windows
python3 -m pip wheel --no-deps -w dist $PKG/abi/bindings/python

Check the mode#

The mode is always shared. To see which file the binding will load:

PYTHONPATH=$PKG/abi/bindings/python python3 -c 'import stardust._native as n; print(n.default_path())'

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.