Bug: Unable to link rust lib against pre-built kuzu

[Brad-Edwards]

Imported from kuzudb/kuzu#6039
Original URL: kuzudb#6039
Original author: @rcrisanti
Original created at: 2025-09-30T13:29:21Z

Kuzu version

v0.11.2

What operating system are you using?

MacOS Sequoia 15.7

What happened?

I am unable to build my rust project, which depends on kuzu, against a pre-built kuzu library. The docs for it for mac give instructions for how to get it to work when you install kuzu with brew, but I want to link it to a version installed from the github releases like here. I also want to link it statically, not dynamically. I haven't done too much with rust build scripts before so perhaps I'm not understanding and/or doing something wrong.

As an aside, my real motivation for doing this is because the kuzu rust crate is incredibly slow compiling - especially on a windows github runner and with the arrow feature enabled (like >1hr). If I'm doing something wrong there and can fix that root cause then maybe I don't really need this

Are there known steps to reproduce?

# set up new project
cargo new test-kuzu-prebuilt
cd test-kuzu-prebuilt
cargo add kuzu
cargo build # just to show that it works when compiling from source

# download
curl -L -O https://github.com/kuzudb/kuzu/releases/download/v0.11.2/libkuzu-osx-universal.tar.gz
mkdir kuzulib
tar -xzf libkuzu-osx-universal.tar.gz -C kuzulib

# try to build with pre-built kuzu
cargo clean
KUZU_LIBRARY_DIR=$(realpath ./kuzulib) KUZU_INCLUDE_DIR=$(realpath ./kuzulib) cargo build --verbose

This last command gives

     Running `/Users/ryan.crisanti/.rustup/toolchains/stable-aarch64-apple-darwin/bin/rustc --crate-name kuzu --edition=2021 /Users/ryan.crisanti/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/kuzu-0.11.2/src/lib.rs --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat --diagnostic-width=197 --crate-type lib --emit=dep-info,metadata,link -C embed-bitcode=no -C debuginfo=2 -C split-debuginfo=unpacked '--warn=clippy::suspicious' '--warn=clippy::style' '--warn=clippy::perf' '--warn=clippy::pedantic' '--warn=clippy::correctness' '--warn=clippy::complexity' '--warn=clippy::cargo' '--allow=clippy::unreadable_literal' '--allow=clippy::type_complexity' '--allow=clippy::too_many_lines' '--allow=clippy::too_many_arguments' '--allow=clippy::struct_excessive_bools' '--allow=clippy::similar_names' '--allow=clippy::return_self_not_must_use' '--allow=clippy::redundant_closure_for_method_calls' '--allow=clippy::needless_pass_by_value' '--allow=clippy::must_use_candidate' '--allow=clippy::module_name_repetitions' '--allow=clippy::missing_panics_doc' '--allow=clippy::missing_errors_doc' '--allow=clippy::inline_always' --cfg 'feature="default"' --check-cfg 'cfg(docsrs,test)' --check-cfg 'cfg(feature, values("arrow", "default", "extension_tests"))' -C metadata=44e709a14c1a85a6 -C extra-filename=-eb381e7e4571c8b4 --out-dir /Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/deps -L dependency=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/deps --extern cxx=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/deps/libcxx-6c930d776ee5c679.rmeta --extern rust_decimal=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/deps/librust_decimal-e60e50d689e50461.rmeta --extern time=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/deps/libtime-2f5ac1bd99a0ae81.rmeta --extern uuid=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/deps/libuuid-0fe2b83305a79439.rmeta --cap-lints allow -L native=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/build/kuzu-8dc935898c4821c2/out -L native=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/build/cxx-03081b9e1f46caf8/out -L native=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/build/link-cplusplus-696e1b7ad2190b03/out -L native=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/kuzulib -l 'static:+whole-archive=kuzu' -l dylib=c++ -l 'static:+whole-archive=utf8proc' -l 'static:+whole-archive=antlr4_cypher' -l 'static:+whole-archive=antlr4_runtime' -l 'static:+whole-archive=re2' -l 'static:+whole-archive=fastpfor' -l 'static:+whole-archive=parquet' -l 'static:+whole-archive=thrift' -l 'static:+whole-archive=snappy' -l 'static:+whole-archive=zstd' -l 'static:+whole-archive=miniz' -l 'static:+whole-archive=mbedtls' -l 'static:+whole-archive=brotlidec' -l 'static:+whole-archive=brotlicommon' -l 'static:+whole-archive=lz4' -l 'static:+whole-archive=roaring_bitmap' -l 'static:+whole-archive=simsimd' -l static=kuzu_rs -C link-arg=-Wl,-rpath,/Users/ryan.crisanti/dev/test-kuzu-prebuilt/kuzulib -C link-arg=-rdynamic`
error: could not find native static library `kuzu`, perhaps an -L flag is missing?

error: could not compile `kuzu` (lib) due to 1 previous error

Caused by:
  process didn't exit successfully: `/Users/ryan.crisanti/.rustup/toolchains/stable-aarch64-apple-darwin/bin/rustc --crate-name kuzu --edition=2021 /Users/ryan.crisanti/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/kuzu-0.11.2/src/lib.rs --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat --diagnostic-width=197 --crate-type lib --emit=dep-info,metadata,link -C embed-bitcode=no -C debuginfo=2 -C split-debuginfo=unpacked '--warn=clippy::suspicious' '--warn=clippy::style' '--warn=clippy::perf' '--warn=clippy::pedantic' '--warn=clippy::correctness' '--warn=clippy::complexity' '--warn=clippy::cargo' '--allow=clippy::unreadable_literal' '--allow=clippy::type_complexity' '--allow=clippy::too_many_lines' '--allow=clippy::too_many_arguments' '--allow=clippy::struct_excessive_bools' '--allow=clippy::similar_names' '--allow=clippy::return_self_not_must_use' '--allow=clippy::redundant_closure_for_method_calls' '--allow=clippy::needless_pass_by_value' '--allow=clippy::must_use_candidate' '--allow=clippy::module_name_repetitions' '--allow=clippy::missing_panics_doc' '--allow=clippy::missing_errors_doc' '--allow=clippy::inline_always' --cfg 'feature="default"' --check-cfg 'cfg(docsrs,test)' --check-cfg 'cfg(feature, values("arrow", "default", "extension_tests"))' -C metadata=44e709a14c1a85a6 -C extra-filename=-eb381e7e4571c8b4 --out-dir /Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/deps -L dependency=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/deps --extern cxx=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/deps/libcxx-6c930d776ee5c679.rmeta --extern rust_decimal=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/deps/librust_decimal-e60e50d689e50461.rmeta --extern time=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/deps/libtime-2f5ac1bd99a0ae81.rmeta --extern uuid=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/deps/libuuid-0fe2b83305a79439.rmeta --cap-lints allow -L native=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/build/kuzu-8dc935898c4821c2/out -L native=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/build/cxx-03081b9e1f46caf8/out -L native=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/target/debug/build/link-cplusplus-696e1b7ad2190b03/out -L native=/Users/ryan.crisanti/dev/test-kuzu-prebuilt/kuzulib -l 'static:+whole-archive=kuzu' -l dylib=c++ -l 'static:+whole-archive=utf8proc' -l 'static:+whole-archive=antlr4_cypher' -l 'static:+whole-archive=antlr4_runtime' -l 'static:+whole-archive=re2' -l 'static:+whole-archive=fastpfor' -l 'static:+whole-archive=parquet' -l 'static:+whole-archive=thrift' -l 'static:+whole-archive=snappy' -l 'static:+whole-archive=zstd' -l 'static:+whole-archive=miniz' -l 'static:+whole-archive=mbedtls' -l 'static:+whole-archive=brotlidec' -l 'static:+whole-archive=brotlicommon' -l 'static:+whole-archive=lz4' -l 'static:+whole-archive=roaring_bitmap' -l 'static:+whole-archive=simsimd' -l static=kuzu_rs -C link-arg=-Wl,-rpath,/Users/ryan.crisanti/dev/test-kuzu-prebuilt/kuzulib -C link-arg=-rdynamic` (exit status: 1)

It does seem to compile if I dynamically link it though:

cargo clean
KUZU_LIBRARY_DIR=$(realpath ./kuzulib) KUZU_INCLUDE_DIR=$(realpath ./kuzulib) KUZU_SHARED=1 cargo build

[Brad-Edwards]

Imported comment from kuzudb/kuzu
Original author: @benjaminwinger
Original created at: 2025-09-30T19:18:14Z
Original URL: kuzudb#6039 (comment)

but I want to link it to a version installed from the github releases like here.
I also want to link it statically, not dynamically.

Unfortunately, you can't do both of these since there is no static library included in the github releases.
If you want to link statically you could build it yourself and store the static libraries somewhere your CI can access. You will also need to move a bunch of other static libraries that are built alongside kuzu into the KUZU_LIBRARY_DIR (see here; the libraries can be found in the third_party directory of your build directory).
It might be easier to set up a build cache for your CI, if you don't already have one, so that it only has to do the long build the first time (or any time you change the version of kuzu you're using).

the kuzu rust crate is incredibly slow compiling - especially on a windows github runner and with the arrow feature enabled (like >1hr).

That does sound long. One possible explanation I can think of is that it's not detecting the number of build jobs correctly when building the C++ library and doing that build single-threaded (we had such an issue in the past on macOS: kuzudb#3784).

[Brad-Edwards]

Imported comment from kuzudb/kuzu
Original author: @rcrisanti
Original created at: 2025-10-02T12:44:57Z
Original URL: kuzudb#6039 (comment)

Unfortunately, you can't do both of these since there is no static library included in the github releases.
If you want to link statically you could build it yourself and store the static libraries somewhere your CI can access. You will also need to move a bunch of other static libraries that are built alongside kuzu into the KUZU_LIBRARY_DIR (see here; the libraries can be found in the third_party directory of your build directory).

Ah I see ok that makes sense. That sounds like a little more than I'd like to do if I can avoid it. I noticed kuzudb#4150 also seems to have a use case for a published static build. Is that something that you guys would consider adding to the releases?

It might be easier to set up a build cache for your CI, if you don't already have one, so that it only has to do the long build the first time (or any time you change the version of kuzu you're using).

the kuzu rust crate is incredibly slow compiling - especially on a windows github runner and with the arrow feature enabled (like >1hr).

That does sound long. One possible explanation I can think of is that it's not detecting the number of build jobs correctly when building the C++ library and doing that build single-threaded (we had such an issue in the past on macOS: kuzudb#3784).

Yeah I think I have the cache and those env vars set correctly, I took a lot of inspiration from your guys' multiplatform-build-test.yml when I set up mine.

I wonder if part of the reason is at all related to the fact that I have a cargo workspace with multiple versions of kuzu in there (because of kuzudb#5528). I am building multiple binaries, each with a different version of kuzu.