Telling the loader where to find shared libraries

The problem

When you compile a program, you may use functions that are already compiled in shared libraries. Shared libraries have names that end with .so on linux, .dylib on Mac OS, and .dll on windows.

You may tell the linker to look for functions in shared libraries with directives such as:

 g++ main.cpp -o test -L/home/toto/my_shared_libraries -lshl

On linux, this tells the compiler/linker to compile "main.cpp" into a program "test", and to look for pre-compiled functions in the shared library "libshl.so" (the "lib" prefix and ".so" suffix are implicitly added by the linker). The linker will search into the standard system directories for this file (i.e. /usr/lib, /usr/local/lib, etc.). In this example, we explicitly tell the linker to also look into the "/home/toto/my_shared_libraries" directory.

When the compilation succeeds, you may want to execute your program with:

 ./test

but this will probably fail. The loader reads in the "test" binary that it needs the "libshl.so" shared library to execute, but it does not know where to find it.

Environment variables

Systems use an environment variables to store the list of additional directories to search for shared libraries. The name of the variable depends on the system:

On UNIX (Mac OS and Linux), separate multiple directories with colons (:). Use semicolons (;) on Windows.

Examples

 # with tcsh
 setenv LD_LIBRARY_PATH "/home/toto/my_shared_libraries:/home/toto/OpenSceneGraph3.4.0/lib"

 # with bash
 export LD_LIBRARY_PATH="/home/toto/my_shared_libraries:/home/toto/OpenSceneGraph3.4.0/lib"

Debugging

You can use tools to analyze a program and know which shared libraries it depends on: "ldd" on Linux, "otool -L" on Mac OS, and dependency walker on windows.

Example:

 > ldd bin/osgviewer 
	linux-vdso.so.1 =>  (0x00007ffcfb78d000)
	libosgViewer.so.130 => /tmp/OpenSceneGraph/lib/libosgViewer.so.130 (0x00007fee3fadd000)
	libosg.so.130 => /tmp/OpenSceneGraph/lib/libosg.so.130 (0x00007fee3eb5f000)
	libstdc++.so.6 => /usr/lib/x86_64-linux-gnu/libstdc++.so.6 (0x00007fee3e7c1000)
	libgcc_s.so.1 => /lib/x86_64-linux-gnu/libgcc_s.so.1 (0x00007fee3e5ab000)
	libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007fee3e1e2000)
 (...)