--- title: Bake library paths into RUNPATH with ld -R; check with elfdump and ldd, fix with elfedit area: link impact: HIGH tags: [link, ld, runpath, origin, elfdump, elfedit, ldd, crle, patchelf, porting, packaging] verified: 2026-11-04 --- # Bake library paths into RUNPATH with ld -R; check with elfdump and ldd, fix with elfedit On Solnix a binary finds its libraries through the RUNPATH that the illumos link-editor records with `-R`: absolute `/nix/store` paths, or `$ORIGIN` for files in the same output. Do not rely on `LD_LIBRARY_PATH` or `crle`. Do not use patchelf or readelf; they do not work here. A binary that only runs from your shell breaks somewhere else, and the builders' publish gate (ldd must resolve every NEEDED in /nix/store) refuses it. **Antipattern** ```sh # do not do these patchelf ... prog # does not work on illumos (the addDriverRunpath setup hook exited 127) readelf -a prog # GNU binutils: not in the base system; use elfdump LD_LIBRARY_PATH=$out/lib ./prog # runs in this shell only, and hides a missing RUNPATH pfexec crle -64 -u -l /opt/foo/lib # rewrites /var/ld/64/ld.config, read by every 64-bit process ``` **The Solnix way** ```sh # link: -R (same as -rpath) records the runpath; single quotes keep $ORIGIN literal gcc -o prog main.o -L"$dep/lib" -lfoo -Wl,-R,"$dep/lib" -Wl,-R,'$ORIGIN/../lib' elfdump -d prog | grep -E 'NEEDED|RUNPATH|RPATH' # what the object asks for, and where it looks env -i /usr/bin/ldd prog # no environment: each NEEDED must map to /nix/store ldd -U prog # also lists unused dependencies and unused runpaths # to diagnose (the gate derivation's design plans elfedit in a build hook): read it, write a new file, test that. # The fix that ships goes in the build (the -R flags above), not a hand-edited binary. elfedit -r -e 'dyn:runpath' prog elfedit -e "dyn:runpath \$ORIGIN/../lib:$dep/lib" prog prog.new && env -i /usr/bin/ldd prog.new ``` The ld wrapper turns GNU `-rpath` into `-R`; mk-src-pkg adds each dependency's `lib/amd64`, so a dep that installs to `lib/` needs `-Wl,-R,/lib`. If elfedit has no room for the new string, relink. On aarch64, rewrite RUNPATH before stripping. A secure process (one for which issetugid(2) returns true) expands `$ORIGIN` only to trusted directories, or to one that already provided a dependency. **The illumos way** (OpenIndiana, OmniOS, SmartOS) ```sh gcc -o prog main.o -L/opt/foo/lib -lfoo -Wl,-R,/opt/foo/lib elfedit -e 'dyn:runpath $ORIGIN/../lib' prog prog.new # elfedit(1) Example 1 crle -64 -c /tmp/ld.config -u -l /opt/foo/lib # a new default dir, in a temp file first LD_CONFIG_64=/tmp/ld.config ./prog # crle(1) Example 1, 64-bit ``` The same tools. After the runpath, ld.so.1 searches the defaults `/lib/64`, `/usr/lib/64`, and `crle` can add more. OpenIndiana's userland tooling removes `/lib`, `/usr/lib` and their 64-bit dirs from RUNPATH. **The difference.** Solnix records every dependency in the object itself and bypasses `crle` and `/var/ld`, so a binary needs no environment and no host config. On Linux, nixpkgs does this with GNU ld and patchelf; on Solnix, `ld -R` and `elfedit` do it. The cache's content gate fails any ELF with a `DT_RUNPATH` or `DT_RPATH` entry outside `/nix/store/` or `$ORIGIN`, such as `/usr/lib/amd64` (it refuses the out for tier 1; for tier 2 it logs the finding, per the v2b-live handoff). `LD_LIBRARY_PATH` is searched before the runpath, so a stray setting hides a broken binary. **Check.** `env -i /usr/bin/ldd prog` lists every dependency as `name => /nix/store/...`, and every RUNPATH entry in `elfdump -d prog` starts with `/nix/store/` or `$ORIGIN`. **Unverified** - Whether ld accepts GNU `-rpath-link` or `--enable-new-dtags`. ld(1) does not list them; test before you keep them in a ported link line. **Sources** - [ld(1)](https://solnix.io/docs/man/ld.1) (illumos, CDDL), -R path / -rpath path (a runpath "is preferable to setting global search paths such as through the LD_LIBRARY_PATH environment variable"; $ORIGIN) - [ld.so.1(1)](https://solnix.io/docs/man/ld.so.1.1) (illumos, CDDL), DESCRIPTION (runpath, then /lib/64 and /usr/lib/64); LD_LIBRARY_PATH; SECURITY ($ORIGIN in secure processes, full path names only) - [elfdump(1)](https://solnix.io/docs/man/elfdump.1) (illumos, CDDL), -d (.dynamic section) - [elfedit(1)](https://solnix.io/docs/man/elfedit.1) (illumos, CDDL), -e, -r; OPERANDS infile, outfile; Example 1 Changing the Runpath of an Executable; NOTES (`elfedit -r -e 'dyn:runpath'`; DT_SUNW_STRPAD and DT_NULL room for a new string) - [ldd(1)](https://solnix.io/docs/man/ldd.1) (illumos, CDDL), DESCRIPTION; -U (unused dependencies and search paths) - [crle(1)](https://solnix.io/docs/man/crle.1) (illumos, CDDL), DESCRIPTION (/var/ld/64/ld.config read for all processes; a bad one can stop programs running; LD_CONFIG_64; test in a temporary file first); -64; -c conf; -u; Default Search Paths (LD_LIBRARY_PATH, then runpath, then defaults); -l dir; Example 1 - [env(1)](https://solnix.io/docs/man/env.1) (illumos, CDDL), -i; [grep(1)](https://solnix.io/docs/man/grep.1) (illumos, CDDL), -E - [gcc(1)](https://solnix.io/docs/man/gcc.1) (Solnix pkgs.solnix.gcc), -Wl,option (split at commas) - [compare: ldd(1)](https://solnix.io/docs/man/compare/ldd.1) (/usr/bin/ldd), [compare: elfedit(1)](https://solnix.io/docs/man/compare/elfedit.1), [compare: readelf(1)](https://solnix.io/docs/man/compare/readelf.1) (readelf only in pkgs.solnix.binutils; -a) - [.kiro/steering/illumos-domain.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/.kiro/steering/illumos-domain.md) (solnix 5a8e5ce), libc / linker / runtime (patchelf/readelf will not work; RUNPATH via -R; bypasses crle and /var/ld) - [.kiro/steering/product.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/.kiro/steering/product.md) (solnix 5a8e5ce), Non-negotiable design pillars, 4 RUNPATH, not crle - [docs/design-build-strategy.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/design-build-strategy.md) (solnix 5a8e5ce), Current state (ld-solaris-wrapper.sh: `-rpath` to `-R`; no crle, no patchelf) - [docs/design-seed-extraction.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/design-seed-extraction.md) (solnix 5a8e5ce), §2.1 (`gcc -Wl,-R`; bypass crle); §2.3 (elfedit, not patchelf); §4.3 (`elfdump -d | egrep 'NEEDED|RUNPATH|RPATH'`) - [docs/design-gate-derivation.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/design-gate-derivation.md) (solnix 5a8e5ce), §2.2 The RUNPATH story ($ORIGIN within a component, absolute store paths across; grow-in-place risk, fall back to relink) - [docs/llvm-illumos.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/llvm-illumos.md) (solnix 5a8e5ce), Build hosts (mk-src-pkg RUNPATH takes a dep's lib/amd64 only; add `-Wl,-R,/lib`) - [docs/design-desktop-and-local-ai.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/design-desktop-and-local-ai.md) (solnix 5a8e5ce), G0 MILESTONE (addDriverRunpath's patchelf setup-hook is 127 on illumos) - [docs/aarch64-nix-derivations-2026-10-26.md](https://codeberg.org/solnix/solnix/src/commit/5a8e5ce75a33086d7be4410149847bdf7501b8fc/docs/aarch64-nix-derivations-2026-10-26.md) (solnix 5a8e5ce), Fixes found (elfedit segfault after GNU strip; rewrite RUNPATH before stripping) - [Handbook: How Solnix is built](https://solnix.io/docs/handbook/how-solnix-is-built#runpath-with-the-solaris-link-editor) (site 307b67f), RUNPATH with the Solaris link-editor - [Handbook: For Linux users](https://solnix.io/docs/handbook/for-linux-users#the-differences-that-actually-bite) (site 307b67f), The differences that actually bite (no patchelf) - [handoff: 20261103-v2b-live](https://codeberg.org/solnix/solnix-infra/src/commit/c2ecf4535e0fc32261bbfb2414bc7961a73fa6ca/docs/handoff/20261103-v2b-live.md), §6 The NAR content gate (tier 1 enforced, tier 2 log only; DT_RUNPATH/DT_RPATH under /nix/store/ or $ORIGIN); example rejection (/usr/lib/amd64) - [handoff: from-builder-20261028T231241-cache7-hm-rows-request](https://codeberg.org/solnix/solnix-infra/src/commit/c2ecf4535e0fc32261bbfb2414bc7961a73fa6ca/docs/handoff/from-builder-20261028T231241-cache7-hm-rows-request.md), publish gate (store-only RUNPATH; ldd resolves every NEEDED in /nix/store) - [OpenIndiana 2018.04 release notes](https://docs.openindiana.org/release-notes/2018.04-release-notes/#general-system-changes), General system changes; Server software (standard dirs removed from RUNPATH)