Linux & Bash · Part II · Module 25 · EDA Environment and Tool Access

Shared Libraries and LD_LIBRARY_PATH

The executable is found and the tool still does not run, because it loads a dozen libraries at startup and one of them is not where it was built to expect. The message comes from the dynamic loader rather than the tool, the status is a signal death, and on macOS the variable that fixes it is deleted by the operating system between your shell and the program.

Advanced22 min readLinuxPart IIShared LibrariesdyldPortability

Part II · Module 25 · Chapter 25.3 · Shared Libraries and LD_LIBRARY_PATH

A commercial simulator is not one program. It is a small executable and tens or hundreds of shared libraries, loaded at startup from paths decided when the tool was built. Precondition two from Chapter 25.1 is that every one of them resolves.

1. What a Tool Links Against

ldd is the Linux tool for this, and it is not here:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ command -v ldd
$ echo $?
1

The macOS equivalent is otool -L:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ otool -L tools/simtool-2024.09/bin/simtool
tools/simtool-2024.09/bin/simtool:
	@rpath/libsim.dylib (compatibility version 0.0.0, current version 0.0.0)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1356.0.0)

Two dependencies, and they are two different kinds:

/usr/lib/libSystem.B.dylib is an absolute path. The loader opens exactly that file. If it is missing the installation is broken in a way no environment variable will fix.

@rpath/libsim.dylib is relative to a search path baked into the executable, which you can read:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ otool -l tools/simtool-2024.09/bin/simtool | grep -A2 LC_RPATH | grep path
         path @executable_path/../lib (offset 12)

@executable_path/../lib — so the tool looks for its libraries in the lib directory beside its own bin. That is how a self-contained tool installation works, and it is why PATH order in Chapter 25.2 changed the library version as well as the executable: each installation's bin has its own ../lib.

Platform	Inspect	Variable	Baked-in search path
Linux	`ldd`, `objdump -p`, `readelf -d`	`LD_LIBRARY_PATH`	`RPATH` / `RUNPATH`, `$ORIGIN`
macOS	`otool -L`, `otool -l`, `dyld_info`	`DYLD_LIBRARY_PATH`	`LC_RPATH`, `@executable_path`

The concepts map one to one. $ORIGIN on Linux is @executable_path on macOS, and RUNPATH is LC_RPATH. Only the macOS half is demonstrated here, because that is the machine these measurements were taken on; the Linux spellings are attributed, not shown.

2. The Failure, and Who Reports It

Move the library out of the way — which is what a half-finished installation, a wrong PATH, or a tool directory mounted on one machine and not another amounts to:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ mv tools/simtool-2024.09/lib/libsim.dylib /tmp/
$ SIMTOOL_LICENSE_FILE=$LIC ./tools/simtool-2024.09/bin/simtool chip_top
dyld[20842]: Library not loaded: @rpath/libsim.dylib
  Referenced from: <3256BA32-DEF8-3267-9CDB-9E1893613927> /home/engineer/eda/tools/simtool-2024.09/bin/simtool
  Reason: tried: '/home/engineer/eda/tools/simtool-2024.09/lib/libsim.dylib' (no such file), '/home/engineer/eda/tools/simtool-2024.09/lib/libsim.dylib' (no such file)
$ echo $?
134

Five things to read out of that:

dyld[20842] is the dynamic loader, not the tool. The tool's main has not run. So nothing in the tool's documentation, its log, its configuration or your design can be the cause — and searching the vendor's knowledge base for "Library not loaded" finds nothing useful.

The library name is the build-time name, @rpath/libsim.dylib, not a filesystem path. That is what the executable records.

Referenced from: names which binary wanted it, which matters when the failing library is needed by another library rather than by the executable.

Reason: tried: lists every path it attempted. This is the most useful line in the message, and the one people stop reading before. It tells you exactly where the loader looked, so you can see whether your fix changed anything.

And the status is 134, which is 128 + 6 — killed by SIGABRT. Chapter 7.6 established that arithmetic for Ctrl-C; here it appears where you would not expect a signal, and it is the reason a || in a flow script behaves differently from a tool's own non-zero exit:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

simtool chip_top || echo "tool failed with $?"     # prints 134, not 1

The licence was set and it did not matter

The run above had a valid SIMTOOL_LICENSE_FILE and a readable licence file. It made no difference, because precondition two fails before precondition three is examined.

This is why Chapter 25.1 §2 insists on a diagnosis order. Starting with the licence — which is what most people do, because licence problems are the ones they have met before — produces an hour of looking at something that is already correct.

The one-command separator remains -version:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ ./tools/simtool-2024.09/bin/simtool -version
dyld[23487]: Library not loaded: @rpath/libsim.dylib

-version needs no licence, so if it fails the problem is at or below the library layer. If it succeeds and a real run fails, the problem is above. One command, and half the search space is gone.

3. The Variable That Overrides the Search

DYLD_LIBRARY_PATH on macOS, LD_LIBRARY_PATH on Linux — a colon-separated list of directories searched before the baked-in paths:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ DYLD_LIBRARY_PATH=/tmp SIMTOOL_LICENSE_FILE=$LIC ./tools/simtool-2024.09/bin/simtool chip_top
simtool 2024.09 starting (simlib 1.4.2)
simlib: elaborating chip_top
$ echo $?
0

The library is in /tmp, the loader found it there, and the tool ran. That is the fix, and it is also a trap, because it overrides the tool's own correct answer — point it at the wrong version's lib and you get a tool whose executable and library are from different releases, which fails in ways no message explains.

Prefer fixing the installation. Use the variable to diagnose.

macOS deletes this variable behind your back — measured

On Linux, LD_LIBRARY_PATH is an ordinary environment variable and is inherited normally. On macOS, System Integrity Protection strips every DYLD_* variable when exec'ing a protected binary, which includes everything in /bin and /usr/bin:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ DYLD_LIBRARY_PATH=/tmp /bin/sh -c 'echo "DYLD_LIBRARY_PATH=${DYLD_LIBRARY_PATH:-(STRIPPED)}"'
DYLD_LIBRARY_PATH=(STRIPPED)
$ DYLD_LIBRARY_PATH=/tmp env | grep -c DYLD
0

Gone in both cases, and no diagnostic. Yet my own compiled, unsigned simtool does see it, which is why §3's fix worked.

The practical consequence is specific and nasty: the variable survives into a program you exec directly and vanishes if anything system-provided sits in between. So

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

DYLD_LIBRARY_PATH=/opt/lib ./bin/simtool run.sv      # works
DYLD_LIBRARY_PATH=/opt/lib sh -c './bin/simtool run.sv'   # the variable is gone

and a wrapper script with #!/bin/sh is exactly such an in-between. A fix that works when you type it and fails when you put it in a script is the worst kind, and this is a real instance of it.

Three ways to live with it:

Set it inside the final script, not around it. A #!/bin/sh wrapper may not inherit it, but it can export it itself — the stripping happens on exec of the protected binary, not on assignment within it.

Or use install_name_tool to fix the binary, which is the real repair:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

install_name_tool -add_rpath /opt/simtool/lib ./bin/simtool

Or do what a well-built tool does and rely on @executable_path, so no variable is needed at all. That simtool was built this way is why it works from any directory with no environment at all.

None of this applies on Linux, where LD_LIBRARY_PATH is simply inherited — which is also why advice copied from a Linux colleague will appear not to work on a Mac for reasons neither of you can see. Chapter 21.6 is the general problem; this is its least visible instance.

4. The Second-Order Case: a Library Needing a Library

The failure in §2 was the executable missing its own dependency. More often in EDA the chain is longer: the tool loads its own library, which loads a system library, which is the one that is missing — frequently a C++ runtime or a graphics library on a compute node with no display.

otool -L on the library rather than the executable walks one step. The recursive version is the thing to run when a message names a library you have never heard of:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

#!/usr/bin/env bash
# libtree — every library a binary needs, transitively
# usage: libtree <binary>
# exit:  0 walked · 2 usage or no such file
set -o nounset

[ $# -ge 1 ] || { printf 'usage: libtree <binary>\n' >&2; exit 2; }
f=$1
[ -e "$f" ] || { printf 'libtree: no such file: %s\n' "$f" >&2; exit 2; }

seen=" "
walk() {
  local f=$1 depth=$2 dep
  case $seen in (*" $f "*) return ;; esac
  seen="$seen$f "
  while IFS= read -r dep; do
    case $dep in
      (@*) printf '%*s%s   [rpath-relative, not followed]\n' "$depth" "" "$dep"; continue ;;
      (/usr/lib/*|/System/Library/*)
           printf '%*s%s   [system, in the dyld cache]\n' "$depth" "" "$dep"; continue ;;
    esac
    if [ -e "$dep" ]; then
      printf '%*s%s\n' "$depth" "" "$dep"
      walk "$dep" $(( depth + 2 ))
    else
      printf '%*s%s   ** NOT FOUND\n' "$depth" "" "$dep"
    fi
  done < <(otool -L "$f" 2>/dev/null | sed '1d' | awk '{print $1}')
}

printf '%s\n' "$f"
walk "$f" 2

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ ./libtree "$(command -v nvc)"
/opt/homebrew/bin/nvc
  /usr/lib/libSystem.B.dylib   [system, in the dyld cache]
  /usr/lib/libz.1.dylib   [system, in the dyld cache]
  /usr/lib/libffi.dylib   [system, in the dyld cache]
  /opt/homebrew/opt/zstd/lib/libzstd.1.dylib
    /opt/homebrew/opt/zstd/lib/libzstd.1.dylib
    /usr/lib/libSystem.B.dylib   [system, in the dyld cache]
  /opt/homebrew/opt/llvm/lib/libLLVM.23.1.dylib
    /opt/homebrew/opt/llvm/lib/libLLVM.23.1.dylib
    /usr/lib/libffi.dylib   [system, in the dyld cache]
    /usr/lib/libedit.3.dylib   [system, in the dyld cache]
    /usr/lib/libSystem.B.dylib   [system, in the dyld cache]
    /opt/homebrew/opt/z3/lib/libz3.5.1.dylib
      /opt/homebrew/opt/z3/lib/libz3.5.1.dylib
      /usr/lib/libc++.1.dylib   [system, in the dyld cache]
      /usr/lib/libSystem.B.dylib   [system, in the dyld cache]
    /usr/lib/libz.1.dylib   [system, in the dyld cache]
    /opt/homebrew/opt/zstd/lib/libzstd.1.dylib
    /usr/lib/libxml2.2.dylib   [system, in the dyld cache]
    /usr/lib/libc++.1.dylib   [system, in the dyld cache]
  /usr/lib/libc++.1.dylib   [system, in the dyld cache]

A real VHDL simulator needs LLVM, which needs Z3, which needs the C++ runtime. That is the chain a "Library not loaded" message is somewhere inside, and seeing it laid out is usually enough to locate the break.

And on a binary with a genuinely missing dependency:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ ./libtree /tmp/ghostuser
/tmp/ghostuser
  /tmp/libghost-MOVED.dylib   ** NOT FOUND
  /usr/lib/libSystem.B.dylib   [system, in the dyld cache]

Two defects in this script, and the second is a macOS fact worth knowing

otool rejects --. The first version wrote otool -L -- "$f", following the end-of-options habit from Chapter 1.5. The result:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ otool -L -- tools/simtool-2024.09/bin/simtool
error: /Library/Developer/CommandLineTools/usr/bin/otool: unknown char `-' in flag --

No dependencies at all, and libtree printed just the top line. -- is a convention, not a guarantee — it is specified for POSIX utilities and widely honoured, and Apple's otool is neither. The lesson is not to stop using --; it is to run the command once after adding it, because a tool that rejects it may do so by producing nothing rather than by failing loudly.

And [ -e ] is false for most system libraries on modern macOS:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ ls -l /usr/lib/libSystem.B.dylib
ls: /usr/lib/libSystem.B.dylib: No such file or directory
$ ls /usr/lib/*.dylib | wc -l
      12

Twelve files, for an operating system whose binaries reference hundreds. The libraries live in the dyld shared cache, a single prelinked blob, and the individual .dylib files were removed. They are perfectly loadable; they are simply not files.

So the second version of libtree reported every system library on every binary as ** NOT FOUND — an alarm on healthy installations, which is the fastest way to get a diagnostic ignored. The fix is to classify by path rather than test for existence:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

(/usr/lib/*|/System/Library/*) printf '... [system, in the dyld cache]\n'; continue ;;

This is a classification, not a check, and it is worth being clear-eyed about the cost: a genuinely missing /usr/lib library would now be reported as cached. That trade is right here, because on macOS a missing system library means a damaged operating system rather than a misconfigured tool — but it is the kind of compromise that belongs in a comment.

dyld_info -dependents is the tool that knows the truth, and it exists here:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

$ dyld_info -dependents /opt/homebrew/bin/nvc
/opt/homebrew/bin/nvc [arm64]:
    -linked_dylibs:
        attributes     load path
                       /usr/lib/libSystem.B.dylib
                       /usr/lib/libz.1.dylib
                       …

None of this applies on Linux, where /usr/lib libraries are files and ldd resolves them for you, printing not found only when it means it. A script written on either platform and run on the other will be wrong in one of these two ways.

Four more decisions in that script:

case $seen in (*" $f "*) — a visited set held in a string, with the pattern parenthesised for the Bash 3.2 reason Chapter 25.1's callout measured. The set is not optional: with it, nvc produces 21 lines; with the check removed, the walk was still running after five seconds and had produced 114, because system libraries reference each other in cycles.

The spaces around $f in both the set and the pattern, so libfoo does not match inside libfoobar. The same bug as the PATH guard in Chapter 25.6 §3, and the same fix.

printf '%*s%s\n' "$depth" "" for indentation — a * field width takes its value from an argument, which indents by a variable amount with no string building.

And the usage check is explicit rather than ${1:?}, because the documented exit code is 2 and :? gives 1 — measured in Chapter 23.4 §5.

5. The Errors, and What Each One Means

Message	Platform	Means
`Library not loaded: X` + `tried:` list	macOS	the loader looked in those places and found nothing
`error while loading shared libraries: X: cannot open shared object file`	Linux	the same thing
`X: wrong ELF class: ELFCLASS32`	Linux	found a 32-bit library for a 64-bit tool
`Symbol not found: _Y` + `Expected in: X`	macOS	the library was found and is the wrong version
`undefined symbol: Y`	Linux	the same
`GLIBC_2.34' not found`	Linux	the tool is newer than the operating system

The fourth and fifth rows are the ones worth recognising, because they are not "missing library" at all — the file was found and opened, and it does not contain a function the tool needs. That is a version mismatch, and pointing LD_LIBRARY_PATH at more directories usually makes it worse by finding yet another wrong copy.

The last row is the one that cannot be fixed with a variable: a tool built against a newer C library than the machine provides will not run on that machine, and the answer is a different machine or a different tool build. On a farm with mixed operating-system versions, that is a scheduler constraint rather than an environment problem — Chapter 30.5's territory.

6. What To Do, In Order

-version — if that works, this chapter is not your problem.
otool -L (or ldd) on the executable. Absolute paths that do not exist are a broken installation.
Read the tried: list in the error. It tells you where the loader looked.
otool -l | grep -A2 LC_RPATH (or objdump -p | grep RUNPATH) to see the baked-in search path. If it is @executable_path-relative, the tool expects to be self-contained and something has moved.
Only then set the variable, as a diagnosis — and note whether the tried: list changes, which tells you whether the variable reached the loader at all.
Fix the installation, not the environment. A variable that must be set for a tool to run is a tool that will fail for the next person.

Why a flow script should record this, not fix it

A tempting response to all of the above is for the flow to set LD_LIBRARY_PATH defensively, "just in case". That makes things worse, for a reason worth stating:

The variable is inherited by every child process, including the compiler, the waveform viewer and any script the tool invokes — all of which now search your directory first. A library intended to repair one tool silently changes which libraries a dozen other programs load. This is the most common cause of a tool that works alone and breaks when run from inside a flow.

The alternative is to record it and check it:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

printf 'LD_LIBRARY_PATH=%s\n'   "${LD_LIBRARY_PATH:-(unset)}"   >> "$rundir/env.txt"
printf 'DYLD_LIBRARY_PATH=%s\n' "${DYLD_LIBRARY_PATH:-(unset)}" >> "$rundir/env.txt"

so that when a result cannot be reproduced, the difference is visible — which is Chapter 25.8's whole subject. And if the flow must set it, scope it to the one command:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

LD_LIBRARY_PATH=/opt/simtool/lib "$SIMTOOL_BIN" "$@"

Chapter 10.1 §8 measured that a VAR=value command prefix affects exactly that command and leaves your own environment alone. That is the difference between a targeted fix and a change of policy for every process you start.

Practice

Run otool -L or ldd on a tool you use. How many libraries, and how many are absolute paths?
Find the baked-in search path with otool -l | grep -A2 LC_RPATH or objdump -p | grep RUNPATH.
Make a copy of a small program, move one of its libraries, and run it. Record the exact message and the status.
Is the status 128 + N? Which signal?
Set LD_LIBRARY_PATH / DYLD_LIBRARY_PATH to rescue it. Did the tried: list change?
On macOS, run DYLD_LIBRARY_PATH=/tmp /bin/sh -c 'echo $DYLD_LIBRARY_PATH'. Explain the output.
Then run the same with a program you compiled yourself and explain the difference.
Write a #!/bin/sh wrapper around a tool, set DYLD_LIBRARY_PATH outside it, and confirm the tool does not see it.
Write libtree and run it on a tool. How deep does the tree go, and are there cycles?
Remove the visited set from libtree and confirm it does not terminate.
Remove the spaces from the visited-set pattern and find a library pair where it matters.
Find a Symbol not found or undefined symbol error in your own history. Was it fixed by adding a directory or by removing one?
Set LD_LIBRARY_PATH globally in a shell, then run a completely unrelated program. Did anything change?

Check Your Understanding

What are the two kinds of entry in otool -L output, and why does the distinction matter?
What does @executable_path/../lib mean, and why is it good?
Who writes the Library not loaded message, and what does that rule out?
Which line of the loader error is most useful?
Why is the status 134 rather than 1?
Why did the valid licence make no difference?
What does macOS do to DYLD_* variables, and which programs are affected?
Why does a #!/bin/sh wrapper break a DYLD_LIBRARY_PATH fix?
What does Symbol not found mean that Library not loaded does not?
Why is setting LD_LIBRARY_PATH in a flow script harmful?
In libtree, why is a visited set required?

Answers

1. Absolute paths, which the loader opens exactly — a missing one is a broken installation — and @rpath-relative names, which are resolved at run time against search paths baked into the binary, and which an environment variable can redirect. 2. The libraries live in a lib directory beside the executable's bin, so the installation is self-contained and needs no environment variable. It is good because it works from any directory for any user. 3. The dynamic loader, dyld, before the tool's main runs. That rules out the tool's configuration, its log, its documentation and your design. 4. Reason: tried: — it lists every path the loader attempted, so you can see where it looked and whether your fix changed anything. 5. Because the process was killed by signal 6 (SIGABRT): 134 = 128 + 6. A || branch therefore sees 134, not 1. 6. Because preconditions are checked in order and library resolution happens before the tool's own code — including its licence check — runs at all. 7. System Integrity Protection strips every DYLD_* variable when exec'ing a protected binary, which includes everything in /bin and /usr/bin. A program you compiled yourself still receives it. 8. Because /bin/sh is a protected system binary, so the variable is stripped on the exec of the wrapper and never reaches the tool. 9. That the library was found and opened but does not contain a function the tool needs — a version mismatch. Adding more directories usually makes it worse. 10. Because it is inherited by every child process, so a library intended to repair one tool changes what a dozen other programs load. Scope it to the one command with a VAR=value cmd prefix, or record it instead. 11. Because system libraries reference each other in cycles, so without one the walk never terminates.

7. Remember

A tool is an executable plus many libraries, resolved at startup from paths decided at build time.
ldd is Linux; otool -L is macOS. LD_LIBRARY_PATH and DYLD_LIBRARY_PATH are the matching variables; $ORIGIN and @executable_path the matching baked-in roots.
Two kinds of dependency: an absolute path (a missing one is a broken install) and an @rpath name (redirectable).
@executable_path/../lib is a self-contained installation and needs no variable — which is why PATH order changes the library version too.
The loader writes the error, not the tool. dyld[pid]: Library not loaded, before main runs.
Read the tried: list. It is the only line that says where it looked.
The status is 134 = 128 + 6, a SIGABRT, so || sees 134.
A valid licence is irrelevant at this layer. -version splits the diagnosis in one command.
macOS strips DYLD_* for system binaries — measured via /bin/sh and env — so the fix vanishes through a #!/bin/sh wrapper while working when typed directly.
install_name_tool -add_rpath repairs the binary; the variable only diagnoses.
Symbol not found means the wrong version was found, not a missing file. More directories makes it worse.
Never set LD_LIBRARY_PATH globally in a flow. Scope it with a VAR=value cmd prefix, or record it.
A transitive walk needs a visited set — library cycles are normal. Measured: 21 lines with it, still running after five seconds without.
otool rejects --, producing no output rather than an error you notice. Run a command once after adding --.
Most /usr/lib libraries are not files on modern macOS — they live in the dyld shared cache, so [ -e ] is false for a loadable library. Classify by path; dyld_info -dependents knows the truth.

8. What Is Next

Chapter 25.4 takes precondition three: the licence variables, what each spelling means, and how to tell a licence failure apart from a tool failure and a design failure by what the log says.

Where this fits

Part of the Linux & Bash curriculum.