Skip to content

Commit b10c0b3

Browse files
vkoziovkozio
committed
docs: prebuilt libs for bindings + download script
1 parent d1fc986 commit b10c0b3

File tree

2 files changed

+153
-0
lines changed

2 files changed

+153
-0
lines changed

‎docs/bindings_release.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Prebuilt C API libraries
2+
3+
Ladybug ships precompiled C API libraries for Linux, macOS, and Windows. Use them to build language bindings (Go, Rust, etc.) without compiling Ladybug.
4+
5+
---
6+
7+
## Supported platforms
8+
9+
| Platform | Download | Contents |
10+
| ---------- | -------- | -------- |
11+
| Linux x86_64 | liblbug-linux-x86_64.tar.gz | lbug.h, lbug.hpp, liblbug.so |
12+
| Linux arm64 | liblbug-linux-aarch64.tar.gz | lbug.h, lbug.hpp, liblbug.so |
13+
| macOS (universal) | liblbug-osx-universal.tar.gz | lbug.h, lbug.hpp, liblbug.dylib |
14+
| Windows x86_64 | liblbug-windows-x86_64.zip | lbug.h, lbug.hpp, lbug_shared.dll, lbug_shared.lib |
15+
16+
Artifacts are available on [GitHub Releases](https://github.com/LadybugDB/ladybug/releases). They are produced by the project’s CI; how to build and publish: see [Building and publishing](#building-and-publishing-maintainers) below.
17+
18+
---
19+
20+
## Building and publishing (maintainers)
21+
22+
**Automatic (recommended):** Push a version tag (e.g. `v0.14.1`). The workflow **Build Precompiled Binaries** runs on `push: tags: v*`, builds all platforms, and uploads artifacts to the GitHub Release for that tag. No manual steps.
23+
24+
**Manual:** If you need a build without a tag (e.g. nightly), run **Actions → Build Precompiled Binaries → Run workflow**. To attach those artifacts to an existing release, run **Actions → Release → Run workflow** and enter the tag and the run ID of the completed build.
25+
26+
---
27+
28+
## Getting the libraries
29+
30+
### From GitHub Releases
31+
32+
1. Open [Releases](https://github.com/LadybugDB/ladybug/releases) and pick a version.
33+
2. Download the archive for your platform (see table above).
34+
3. Extract. Files are at the archive root. Put the library in your binding’s search path (e.g. `lib/dynamic/<platform>/`) and `lbug.h` where your build expects headers.
35+
36+
### Using the download script
37+
38+
From a clone of Ladybug (or with the script copied into your binding repo):
39+
40+
```bash
41+
scripts/download_liblbug.sh <version> <platform> [output_dir]
42+
```
43+
44+
- **version** — Release tag (e.g. `v0.14.1`) or `latest`
45+
- **platform** — `linux-amd64`, `linux-arm64`, `darwin`, `windows-amd64`
46+
- **output_dir** — Where to unpack (default: current directory). Creates `lib/dynamic/<platform>/` and `include/`.
47+
48+
Examples:
49+
50+
```bash
51+
./scripts/download_liblbug.sh v0.14.1 linux-amd64 .
52+
./scripts/download_liblbug.sh latest darwin ./vendor/ladybug
53+
```
54+
55+
Requires `curl`, `tar` (for .tar.gz), and `unzip` (for Windows). To use a different repo: `LADYBUG_REPO=owner/repo ./scripts/download_liblbug.sh ...`.
56+
57+
---
58+
59+
## Using in Go (CGO)
60+
61+
1. Get the library and header for your target (see above). Typical layout: `lib/dynamic/<platform>/` for the shared library, `include/` for `lbug.h`.
62+
2. In the Go file that imports `"C"`, set CGO flags for each platform. Example for Linux amd64:
63+
64+
```go
65+
// #cgo linux,amd64 LDFLAGS: -L${SRCDIR}/lib/dynamic/linux-amd64 -llbug -Wl,-rpath,${SRCDIR}/lib/dynamic/linux-amd64
66+
// #cgo linux,amd64 CFLAGS: -I${SRCDIR}/include
67+
import "C"
68+
```
69+
70+
Use the same pattern for other `GOOS/GOARCH` (e.g. darwin → liblbug.dylib, windows → lbug_shared). Then call the C API via CGO as usual.
71+
72+
3. In your binding’s README, state which Ladybug version you tested with (e.g. “Compatible with Ladybug v0.14.x”). You can call `lbug_get_version()` at runtime to check the loaded library.
73+
74+
---
75+
76+
## Using in other languages
77+
78+
The same archives provide the C API header and shared library. Link your language’s FFI to the library and include `lbug.h`. The public API is in [src/include/c_api/lbug.h](../src/include/c_api/lbug.h). No C++ is required at the binding boundary.
79+
80+
---
81+
82+
## Version compatibility
83+
84+
C API compatibility follows the project’s versioning. Prebuilt libs match a specific release; bindings should document the tested Ladybug version. Runtime version strings are available via `lbug_get_version()` and `lbug_get_storage_version()`.

‎scripts/download_liblbug.sh‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
#!/usr/bin/env bash
2+
# Download Ladybug prebuilt library and header for a given version and platform.
3+
# Unpacks into output_dir/lib/dynamic/{platform}/ and output_dir/include/.
4+
#
5+
# Usage: download_liblbug.sh <version> <platform> [output_dir]
6+
# version: release tag (e.g. v0.14.1) or "latest"
7+
# platform: linux-amd64 | linux-arm64 | darwin | windows-amd64
8+
# output_dir: default . (current directory)
9+
#
10+
# Example (from a Go binding repo):
11+
# ./download_liblbug.sh v0.14.1 linux-amd64 .
12+
# ./download_liblbug.sh latest darwin ./libs
13+
#
14+
# Requires: curl, tar (for .tar.gz), unzip (for Windows .zip).
15+
# Optional: LADYBUG_REPO=Owner/repo to override (default: LadybugDB/ladybug).
16+
17+
set -euo pipefail
18+
19+
REPO="${LADYBUG_REPO:-LadybugDB/ladybug}"
20+
VERSION="${1:?Usage: download_liblbug.sh <version> <platform> [output_dir]}"
21+
PLATFORM="${2:?Usage: download_liblbug.sh <version> <platform> [output_dir]}"
22+
OUT_DIR="${3:-.}"
23+
24+
case "$PLATFORM" in
25+
linux-amd64) ASSET="liblbug-linux-x86_64.tar.gz" ;;
26+
linux-arm64) ASSET="liblbug-linux-aarch64.tar.gz" ;;
27+
darwin) ASSET="liblbug-osx-universal.tar.gz" ;;
28+
windows-amd64) ASSET="liblbug-windows-x86_64.zip" ;;
29+
*)
30+
echo "Unknown platform: $PLATFORM" >&2
31+
echo "Supported: linux-amd64, linux-arm64, darwin, windows-amd64" >&2
32+
exit 1
33+
;;
34+
esac
35+
36+
if [ "$VERSION" = "latest" ]; then
37+
# Resolve latest tag from GitHub API
38+
VERSION=$(curl -sSf "https://api.github.com/repos/${REPO}/releases/latest" | grep '"tag_name":' | sed -E 's/.*"tag_name":\s*"([^"]+)".*/\1/')
39+
[ -n "$VERSION" ] || { echo "Could not resolve latest release" >&2; exit 1; }
40+
echo "Resolved latest: $VERSION"
41+
fi
42+
43+
URL="https://github.com/${REPO}/releases/download/${VERSION}/${ASSET}"
44+
LIB_DIR="${OUT_DIR}/lib/dynamic/${PLATFORM}"
45+
INC_DIR="${OUT_DIR}/include"
46+
mkdir -p "$LIB_DIR" "$INC_DIR"
47+
TMP=$(mktemp -d)
48+
trap 'rm -rf "$TMP"' EXIT
49+
50+
echo "Downloading $URL ..."
51+
curl -sSfL -o "$TMP/asset" "$URL"
52+
53+
case "$ASSET" in
54+
*.tar.gz)
55+
tar -xzf "$TMP/asset" -C "$TMP"
56+
# Tarball has lbug.h, lbug.hpp, liblbug.so or liblbug.dylib at root
57+
[ -f "$TMP/lbug.h" ] && cp "$TMP/lbug.h" "$INC_DIR/"
58+
[ -f "$TMP/liblbug.so" ] && cp "$TMP/liblbug.so" "$LIB_DIR/"
59+
[ -f "$TMP/liblbug.dylib" ] && cp "$TMP/liblbug.dylib" "$LIB_DIR/"
60+
;;
61+
*.zip)
62+
unzip -q -o "$TMP/asset" -d "$TMP"
63+
[ -f "$TMP/lbug.h" ] && cp "$TMP/lbug.h" "$INC_DIR/"
64+
[ -f "$TMP/lbug_shared.dll" ] && cp "$TMP/lbug_shared.dll" "$LIB_DIR/"
65+
[ -f "$TMP/lbug_shared.lib" ] && cp "$TMP/lbug_shared.lib" "$LIB_DIR/"
66+
;;
67+
esac
68+
69+
echo "Done. Library in $LIB_DIR, header in $INC_DIR"

0 commit comments

Comments
 (0)