Troubleshooting error: /usr/bin/ld: cannot find -lxxx

A few days ago, while working on development, I encountered a compilation error that kept me up until 3 AM before I finally resolved it.

The specific error was: /usr/bin/ld: cannot find -lLLVM-13-rust-1.58.0-nightly, which means gcc couldn't find the third-party library lLLVM-13-rust-1.58.0-nightly during compilation. However, the location of this library had already been written into the LD_LIBRARY_PATH variable in the zshrc configuration file, so I was completely baffled. After searching through various resources, I finally discovered the difference between LIBRARY_PATH and LD_LIBRARY_PATH.

---

1. LIBRARY_PATH

• Purpose:

  • Used during the compilation phase to tell the compiler (such as gcc or clang) where to find static libraries (.a) and dynamic libraries (.so or .dylib).
  • The compiler uses this path during linking to locate the required library files.

• Common scenarios:

  • When you compile a program and need to link against certain libraries (e.g., gcc main.c -o main -lfoo), if foo is not in the default library search path, you can set LIBRARY_PATH to tell the compiler where to find it.

• Affected tools:

  • Primarily used by compilers (such as gcc, clang).

• Example:

  export LIBRARY_PATH=/custom/lib/path:$LIBRARY_PATH
  gcc main.c -o main
  

---

2. LD_LIBRARY_PATH

• Purpose:

  • Used during the runtime phase to tell the dynamic linker (ld.so or ld-linux.so) where to preferentially look for .so files when loading dynamic libraries.
  • This is the runtime search path for dynamic libraries.

• Common scenarios:

  • When a program being run depends on dynamic libraries that are not in the default search paths (such as /usr/lib, /lib), you can set LD_LIBRARY_PATH to tell the system where to find the dynamic libraries.

• Affected tools:

  • Primarily used by the dynamic linker (ld.so).

• Example:

  export LD_LIBRARY_PATH=/custom/lib/path:$LD_LIBRARY_PATH
  ./main
  

---

Key Differences

Attribute	LIBRARY_PATH	LD_LIBRARY_PATH
Phase	Compilation phase	Runtime phase
Use case	Find static and dynamic libraries for linking	Load dynamic libraries for program execution
Tools used	Compilers (e.g., gcc, clang)	Dynamic linker (e.g., ld.so, ld-linux.so)
Targets	Static libraries (.a) and dynamic libraries (.so)	Dynamic libraries (.so)

---

How to Use Both Together

If you need to compile and run programs during development and the library files are not in the system default paths, you may need to set both variables.

export LIBRARY_PATH=/custom/lib/path:$LIBRARY_PATH
export LD_LIBRARY_PATH=/custom/lib/path:$LD_LIBRARY_PATH
gcc main.c -o main
./main

This way, both the compiler and the dynamic linker can correctly find the required library files.

---

Important Notes

1. Security concerns:

   • Misusing LD_LIBRARY_PATH can introduce security risks, especially in multi-user systems where attackers can exploit forged dynamic libraries.
   • If possible, prefer using rpath or RUNPATH to specify runtime library paths instead of relying on LD_LIBRARY_PATH.

2. Debugging issues:

   • Setting too many paths can complicate linker behavior. It's recommended to set them only when necessary and pay attention to path priority.

3. Persistent configuration:

   • If you need to use these variables for an extended period, you can add them to ~/.bashrc or ~/.zshrc.

---

Summary

• Library not found during compilation → Set LIBRARY_PATH.
• Library not found during runtime → Set LD_LIBRARY_PATH.
• They serve different functions and are not the same thing.