gdiazlo.tngl.sh / duckdb
An experimental duckdb bindings for Ocaml
0
Fork 0

Configure Feed

Select the types of activity you want to include in your feed.

duckdb / vendor / README.md
5.6 kB

Vendored DuckDB prebuilt#

This directory holds the prebuilt DuckDB C library and header the bindings compile and link against. We do not vendor DuckDB source (see spec.md); instead we download an official prebuilt archive, exactly like the Python and Go bindings do, so end users need not install DuckDB separately.

What's committed vs provisioned#

Committed (tracked in git):

File Role
duckdb.version The single source of truth for the pinned DuckDB version.
duckdb.checksums Pinned SHA-256 of each platform archive (bump alongside version).
README.md This file.

Provisioned on demand by ../scripts/fetch-duckdb.sh (gitignored, never committed — see /vendor/duckdb/ in .gitignore):

File under duckdb/ Role
duckdb.h C API header (compiled against).
duckdb.hpp C++ header (shipped by upstream; unused by these bindings).
libduckdb.so / .dylib Shared library (linked; resolved at runtime via rpath).
libduckdb_static.a Static archive (Linux only; upstream ships none on macOS).
libduckdb.a Stable-name symlink to libduckdb_static.a when present.
cflags.sexp -I include flag, spliced into lib/duckdb_c/dune.
link-flags.sexp -L/-l/-rpath flags, spliced into lib/duckdb_c/dune.

Provisioning#

./scripts/fetch-duckdb.sh

The script reads the pinned version from vendor/duckdb.version, picks the platform-correct archive, downloads it, verifies it against vendor/duckdb.checksums, unpacks it here, and emits the dune flag fragments. It refuses unsupported platforms (notably Windows) with a clear error.

Bumping the DuckDB version (e.g. to 2.x)#

This is a one-line change plus checksums:

  1. Edit vendor/duckdb.version to the new version (e.g. 2.0.0).
  2. Update the two checksums in vendor/duckdb.checksums to match the new archives (download them once and run sha256sum).
  3. Run ./scripts/fetch-duckdb.sh and dune build.

No OCaml or dune file changes are required — the version flows into the build through the generated Duckdb_c.target_api_version, and the test asserts the linked library actually reports the pinned version.

opam strategy#

Decision: ship the prebuilt via the package, gated to Linux + macOS. Like the Python (duckdb wheel) and Go bindings, an end user installing this opam package should not need a system DuckDB. The package provisions the prebuilt itself:

  • Platform gate. The package is available only on Linux and macOS. In the published opam file this is the field:

    available: [ os = "linux" | os = "macos" ]

    Windows is explicitly out of scope for now. As a defence in depth, scripts/fetch-duckdb.sh also fails fast with a clear message on any unsupported platform/architecture.

  • Provisioning, without network in the build. The opam build sandbox has no network, so the prebuilt archives are declared as extra-sources in duckdb.opam (pinned by URL and SHA-256); opam downloads and verifies them before the build. scripts/fetch-duckdb.sh then runs in the build: step, uses the opam-provided archive (instead of downloading), unpacks it into vendor/duckdb/, and emits the dune compile/link-flag fragments.

  • Shared library, installed into the switch. DuckDB is C++ and its official prebuilt static archive is not self-contained (it references extension symbols defined only in the shared object), so static linking is not viable. The package therefore links the shared libduckdb.so/.dylib and the opam install: step (scripts/install-duckdb-lib.sh) copies it into %{lib}%/duckdb. The link step embeds an rpath to that install location (plus the vendor dir, so the package's own build-time tests resolve it), so a consumer's binary finds the library at runtime with no system DuckDB.

  • Single version pin. vendor/duckdb.version is the only place the version lives; bump it with vendor/duckdb.checksums and the matching extra-source URLs/checksums in duckdb.opam.

duckdb.opam is hand-maintained (not generated by dune): it needs fields dune cannot emit — available:, the extra-source archives, and the custom build/install. generate_opam_files is therefore off in dune-project.

Publishing to a private opam repository#

The repository here builds and installs locally (dune build, and opam install . once the prebuilt is provisioned). To publish a versioned release into a private opam-repository:

  1. Tag a release (e.g. v0.1.0) and produce a source tarball of the OCaml project (this repo's source — not the prebuilt; that comes via extra-source).
  2. Add packages/duckdb/duckdb.0.1.0/opam to the private repo: a copy of duckdb.opam plus a url { src: "<tarball-url>" checksum: "sha256=…" } pointing at that source tarball.
  3. If the repo is served over HTTP, run opam admin index.
  4. Consumers: opam repo add <name> <repo-url> then opam install duckdb.