Problem

I am trying to build the debug version of agave on an x86_64 intel macOS, and am having trouble getting the ./cargo build to find my libclang.dylib. I have tried installing llvm using brew but it did not resolve the issue. I've verified that the libclang.dylib is installed in the correct location, and that its in my PATH, but its still not being searched/found in the ./cargo build command.

Do I need to

NOTE: Version info is at the bottom

Error Codes

Error Code 1

Formatted the error for easier reading

error: failed to run custom build command for `librocksdb-sys v0.17.1+9.9.3`

Caused by:
  process didn't exit successfully:
    `/path/to/agave/target/debug/build/librocksdb-sys-6ec66246af494b6a/build-script-build`
    (signal: 6, SIGABRT: process abort signal)
  --- stderr
  dyld[51692]: Library not loaded: @rpath/libclang.dylib
    Referenced from:
        <2991979E-D47E-38DF-BED8-158D6FB41A3F> /path/to/agave/target/debug/build/librocksdb-sys-6ec66246af494b6a/build-script-build
    Reason: tried:
        '/path/to/agave/target/debug/deps/libclang.dylib' (no such file),
        '/path/to/agave/target/debug/libclang.dylib' (no such file),
        '/my/toolchains/1.85.1-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/lib/libclang.dylib' (no such file),
        '/my/toolchains/1.85.1-x86_64-apple-darwin/lib/libclang.dylib' (no such file),
        '/Users/me/lib/libclang.dylib' (no such file),
        '/usr/local/lib/libclang.dylib' (no such file),
        '/usr/lib/libclang.dylib' (no such file, not in dyld cache)
warning: build failed, waiting for other jobs to finish...

What I did

Ran this

➜  agave git:(master) ./cargo build

Got error code 1

Well thats not what I wanted?

So I tried this recommendation; installing llvm

➜  agave git:(master) brew install llvm
➜  agave git:(master) LIBCLANG_PATH="$(brew --prefix llvm)/lib" # `/usr/local/opt/llvm`
➜  agave git:(master) export LIBCLANG_PATH
➜  agave git:(master) export PATH=$PATH:$LIBCLANG_PATH

But got the same error

Maybe the PATH wasn't included?

Then checked my PATH (LIBCLANG_PATH not there)
Updated my path
Then re-ran ./cargo build

➜  agave git:(master) echo $PATH
➜  agave git:(master) export PATH=$PATH:$LIBCLANG_PATH
➜  agave git:(master) ✗ ./cargo build

then got the same error again

So its still not checking the LIBCLANG_PATH (/usr/local/opt/llvm)

Making sure the libclang.dylib exists in the LIBCLANG_PATH (/usr/local/opt/llvm)

➜  agave git:(master) ll $LIBCLANG_PATH/libclang.dylib
-r--r--r--@ 1 me  root    49M Mar 29 14:16 `/usr/local/opt/llvm`/lib/libclang.dylib

Went to ./docs/src/cli/install.md and saw I needed to install some additional build dependencies

➜  agave git:(master) brew install pkg-config libudev protobuf llvm coreutils
➜  agave git:(master) ./scripts/cargo-install-all.sh . # This took a while ~47m
➜  agave git:(master) export PATH=$PATH:$PWD/bin # I swapped this order
➜  agave git:(master) ✗ agave-install init
Error: "Please specify the release to install for x86_64-apple-darwin.  See --help for more"

# Adding the release (latest at this time)
➜  agave git:(master) ✗ agave-install init v2.1.16
Error: "Unable to extract \"/var/folders/n4/5t062_593678r40tg4zm5lc00000gn/T/.tmpIASm19/download\" to \"/my/.local/share/solana/install/releases/2.1.16\": failed to iterate over archive"

Ok this seems odd, but I think the instructions in install.md were only for installing a ~prod version? Even if building it from source?

Lets try this one more time, this time with the instructions from the root README, but with a tagged release checked out

➜  agave git:(master) git tags # find the latest tag
➜  agave git:(master) git checkout tags/v2.1.16
➜  agave git:(master) ./cargo build
...
Compiling solana-banking-bench v2.2.6 (/path/to/agave/banking-bench)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 13m 57s

SUCCESS!!!!

Proposed Solution

Ok so I got this working eventually (like 2-3 hrs to figure it out though, mostly due to build time), but theres still some simple things that could be changed that would have saved me hours of time.

1. The directions on the Root README could be a little clearer, they show how to build with linux, but don't specify where to look for other build instructions. This would probably be better to just point to a build.md file that is specifically explaining all of the basic "dev" related todo's, or at least include a line in the root README that describes where to look for macOS/Windows builds (or if those aren't supported, where to look for community support)

2. The --help output for agave-install init is kind of poor/confusing. It has conflicts in the USAGE vs the ARGS section (<> vs []), and even after specifying the release, it still fails to extract the archive. Giving Error: "Unable to extract ... failed to iterate over archive", which I believe is because I was using the cloned repo not a downloaded release src archive? Which doesn't make a ton of sense? If I'm trying to either debug/test and or contribute to the project, I should be able to build it locally without having to redownload a new release archive each time I want to test a change. (idk AITDAH?); at the very least the install.md should include a section near the agave-install init explicitly calling out how this won't work if you're on the main/master branch, and that it needs a specific release tag to work.

I'm gonna go ahead and make a PR for this, so please don't close this issue for at least a day.

Version info

➜  agave git:(master) uname -a
Darwin Maui-0022060 24.3.0
Darwin Kernel Version 24.3.0: Thu Jan  2 20:22:00 PST 2025;
root:xnu-11215.81.4~3/RELEASE_X86_64 x86_64

➜  agave git:(master) cargo version
cargo 1.85.1 (d73d2caf9 2024-12-31)

➜  agave git:(master) rustup toolchain list
stable-x86_64-apple-darwin
beta-x86_64-apple-darwin
nightly-x86_64-apple-darwin (default)
1.85.0-x86_64-apple-darwin
1.85.1-x86_64-apple-darwin (override)

➜  agave git:(master) git rev-parse HEAD
a99bbba064268ff89842c3ebd2b1b36d2e7c0384

➜  agave git:(master) brew list --formula llvm
/usr/local/Cellar/llvm/19.1.7_1/*
... <didnt include individual files due to verbosity of listing>