Link to shared libraries normally or set RPATH, instead of relying on LD_LIBRARY_PATH

[max-privatevoid]

Expected Behaviour

Binaries should run without requring any magical environment variables.

Example & Steps To Reproduce

The examples are not directly runnable (i.e. not using cargo run) due to unnecessary LD_LIBRARY_PATH shenanigans:

$ cargo build -p example-runner-wgpu
$ target/debug/example-runner-wgpu

thread 'main' panicked at crates/spirv-builder/src/lib.rs:745:9:
Could not find librustc_codegen_spirv.so in library path
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

This happens because you're looking for that file by manually parsing the LD_LIBRARY_PATH environment variable. It's my understanding that this lookup is only performed so the location of that file can be passed to a rustc invocation later, so it doesn't even make sense to look this up in LD_LIBRARY_PATH.

Upon manually setting LD_LIBRARY_PATH:

$ LD_LIBRARY_PATH=$PWD/target/debug ./target/debug/example-runner-wgpu

thread 'main' panicked at examples/runners/wgpu/src/graphics.rs:467:49:
called `Result::unwrap()` on an `Err` value: Os(OsError { line: 81, file: "/home/max/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/winit-0.30.7/src/platform_impl/linux/wayland/event_loop/mod.rs", error: WaylandError(Connection(NoWaylandLib)) })
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Regardless of the mechanism that's used to find librustc_codegen_spirv.so, it should not be necessary that these graphics libraries are discovered through LD_LIBRARY_PATH at all. Via RUSTFLAGS, one can configure the output binary's RPATH:

--- a/default.nix
+++ b/default.nix
@@ -14,7 +14,7 @@ in with pkgs; stdenv.mkDerivation rec {
   nativeBuildInputs = [ rustup ];

   # Runtime dependencies (for the example runners).
-  LD_LIBRARY_PATH = with xorg; lib.makeLibraryPath [
+  env.RUSTFLAGS = "-C link-arg=-Wl,-rpath,${with xorg; lib.makeLibraryPath [
     vulkan-loader

     # NOTE(eddyb) winit really wants `libxkbcommon` on Wayland for some reason
@@ -22,5 +22,5 @@ in with pkgs; stdenv.mkDerivation rec {
     wayland libxkbcommon

     libX11 libXcursor libXi libXrandr
-  ];
+  ]}";
 }

$ cargo build -p example-runner-wgpu
$ patchelf --print-rpath target/debug/example-runner-wgpu | tr : \\n
/nix/store/pkzygdv7p08cma6q6zbarprkmdbgqn6m-vulkan-loader-1.4.313.0/lib
/nix/store/h64w118vqfw706px8ranz6cx07ki06jl-wayland-1.23.1/lib
/nix/store/dxh4x7x96lfadv500bdw3m2b3h4a3vwa-libxkbcommon-1.10.0/lib
/nix/store/26c0x3gh2g5dpczvjxgjzn0mc22zxpjz-libX11-1.8.12/lib
/nix/store/2dv3na4hkiq5l3af3a25wb5a390grr2x-libXcursor-1.2.3/lib
/nix/store/mnyka5w2k0jbfnfzrazhgwrhk6nnldnq-libXi-1.8.2/lib
/nix/store/22da37glz0r7vs536nj9n6h56kh1lr7m-libXrandr-1.5.4/lib
/home/max/Projects/rust-gpu/outputs/out/lib
/nix/store/q4wq65gl3r8fy746v9bbwgx4gzn0r2kl-glibc-2.40-66/lib
/nix/store/l7d6vwajpfvgsd3j4cr25imd1mzb7d1d-gcc-14.3.0-lib/lib

The best option would be to actually link the binaries to the shared libraries like normal. For example, ash supports this through an optional feature. wgpu does not seem to expose it.

System Info

• Rust: rustc 1.89.0-nightly (be19eda0d 2025-06-22)
• OS: NixOS 25.11.20250627.30e2e28

[LegNeato]

Awesome, thank you for the detailed report!

[LegNeato]

@eddyb I think you set up the original system, thoughts?

[eddyb]

Sadly this seems to be about ~3 different issues, but I'm not sure how to best split it up.

---

Upon manually setting LD_LIBRARY_PATH:

Slight mistake here, you would need to do LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$PWD/target/debug" tho it's even trickier to be correct if it's not already set (and the syntax I've seen before is bash-specific).

---

For Nix specifically, both LD_LIBRARY_PATH and rpath injection exist, hard to tell which is more common:

• https://github.com/search?q=repo%3ANixOS%2Fnixpkgs+%2F--prefix+LD_LIBRARY_PATH%2F&type=code
• https://github.com/search?q=repo%3ANixOS%2Fnixpkgs+%2F-rpath%2F+makeLibraryPath&type=code
• https://github.com/search?q=repo%3ANixOS%2Fnixpkgs+rustPlatform+%2F%28%3F-i%29FLAGS%2F+%2F%5Cbrpath%5Cb%2F&type=code
  (Rust-specific, honestly it feels like a mess and that consensus hasn't been reached)

I will note that these are libraries that get loaded from /lib or /usr/lib (or lib64 instead of lib) on non-Nix (or rather, FHS-abiding) distros (which is why they don't need rpath or LD_LIBRARY_PATH).

Speaking of FHS, this is a neat trick I picked up in the past (not that I recommend relying on it):

LD_LIBRARY_PATH=$PWD/target/debug nix-shell -p steam-run --run 'steam-run ./target/debug/example-runner-wgpu'

The best option would be to actually link the binaries to the shared libraries like normal. For example, ash supports this through an optional feature. wgpu does not seem to expose it.

I don't have a source for this on hand, but I would argue against "normal". There is significant precedent for libraries like X/Wayland or GL/Vulkan to be loaded dynamically, even if the design of the Vulkan Loader isn't as embedding-averse as older GPU APIs (and some/most distros shipping glvnd and/or Mesa's equivalent, which AIUI is comparable to Vulkan Loader but limited by existing GLX/EGL API choices etc.).

My guess is that's why wgpu doesn't expose such options (though it does allow toggling backends, so they could have "mandatory Vulkan support" feature that implies non-dynamically-loaded Vulkan Loader).

---

For finding librustc_codegen_spirv.so, however, it's sadly a really nasty hack.
spirv-builder depends on rustc_codegen_spirv as a normal dependency, even though it's not linked against it.

It's my understanding that this lookup is only performed so the location of that file can be passed to a rustc invocation later, so it doesn't even make sense to look this up in LD_LIBRARY_PATH.

Yes, but the whole reason to look it up in LD_LIBRARY_PATH is that Cargo sets that (or, rather, it sets the per-platform variable, LD_LIBRARY_PATH specifically on Linux), which allows it to be found.

The closest thing to what we would want to do looks more like artifact dependencies:

• Tracking Issue for RFC 3028: Allow "artifact dependencies" on bin, cdylib, and staticlib crates rust-lang/cargo#9096

Moreover, the whole build setup right now has a bunch of other usability issues (e.g. the debug in your commands makes me think that, unless you have a bunch of Cargo.toml profile overrides, rustc_codegen_spirv would have been built unoptimized and therefore some shaders might be painfully slow to compile).

And my previous attempt at rectifying it was this monstrosity:

• spirv-builder: build rustc_codegen_spirv with the right toolchain via build script. EmbarkStudios/rust-gpu#1103

I have not kept up with cargo-gpu development as much as I should, but I would recommend giving it a try, as it might alleviate some/most of the friction in this area (depending on your usecase).