1. Choose your release
Download and extract the archive matching your operating system and CPU. Keep the lib/, abi/bindings/, and abi/examples/ directories together.
| Platform | CPU | Shared library in lib/ |
|---|---|---|
| Linux | x86_64 or ARM64 | libstardust.so |
| macOS | x86_64 or ARM64 | libstardust.dylib |
| Windows | x86_64 | stardust.dll |
The archive includes the shared library, the codec executable, generated bindings, and runnable examples. Each binding calls the same C ABI.
2. Set the library paths
From any packaged example directory (abi/examples/<language>), the release library directory is ../../../lib. Relative paths below assume you run commands from that directory.
Set these variables in the shell where you run the example:
| Platform | STARDUST_LIBRARY | Loader variable | Library directory |
|---|---|---|---|
| Linux | ../../../lib/libstardust.so | LD_LIBRARY_PATH | ../../../lib |
| macOS | ../../../lib/libstardust.dylib | DYLD_LIBRARY_PATH | ../../../lib |
| Windows | ../../../lib/stardust.dll | PATH | ../../../lib |
Preserve existing loader entries when adding ../../../lib. The packaged Go and Rust bindings already link against the release's lib/ directory; no extra linker variable is needed for these examples.
If Stardust is already installed in the platform's library search directories, use that installation instead. Clojure can load it without STARDUST_LIBRARY. The executable PATH is not the shared-library search path on Linux or macOS.
3. Run a packaged example
Run each command from the directory shown. Use the bindings included in the same release.
| Language | Directory | Command |
|---|---|---|
| Go | abi/examples/go | go run . |
| Rust | abi/examples/rust | cargo run --locked --quiet |
| Clojure | abi/examples/clojure | clojure -J--enable-native-access=ALL-UNNAMED -M:run |
| Python | abi/examples/python | python3 evaluate.py |
| Odin | abi/examples/odin | Use the platform command below. |
Odin linker setup
The relative linker path below points to the extracted release's lib/. The loader variables above let the example find the library when it runs.
| Platform | Command from abi/examples/odin |
|---|---|
| Linux | odin run . -extra-linker-flags:"-L../../../lib" |
| macOS | odin run . -extra-linker-flags:"-L../../../lib" |
| Windows | odin run . -extra-linker-flags:"/LIBPATH:../../../lib" |
If both the linker and runtime loader already find your installed Stardust library, run odin run . without extra flags. On Windows, the linker also needs the supplied stardust.lib import library.
The C reference documents the raw ABI and ownership rules. There is no packaged C application example.
4. Continue with embedded calls
On the following pages, use the language selector to see that binding's code. This tutorial shows verified call fragments; the packaged examples provide runnable programs.
Keep the error checks and handle cleanup when adapting the calls. No server or mounted directory is required.
Read Database for opening options and Ownership for handle lifetimes.