[Derived from http://docs.sun.com/app/docs/doc/816-0559?q=+Solaris+Linker+and+Libraries+Guide&s=t .]

When should I set LD_LIBRARY_PATH?

The short answer is never.

Why?

Some users seem to set this environment variable because of bad advice from other users or badly linked code that they do not know how to fix.

Libraries in UNIX

Linking is the process of joining one or more object code files together with one or more of the system libraries. The C library libc is by default linked in. Other libraries may be specified with -llib options to the compiler (e.g. -lm for the Math library).

Static and dynamic libraries

Libraries are linked either statically or dynamically (also called shared libraries). Libraries live in /usr/lib amongst other places. Static libraries (.a suffix) are incorporated into the binary at link time, whereas dynamic ones (.so suffix) are referenced by location. There is a move in Solaris and less so in UNIX in general to using dynamic libraries wherever possible (Solaris ships with less static libraries at each release). Once a library has been linked with statically, if the same version of the library is updated (eg. minor upgrade, bug fix) the binary would need to be manually relinked to use the new library. Other tricks with dynamic libraries are possible, such as using a per-architecture copy of the library optimised for the processor/architecture on the current host.

Specifying the location of dynamic libraries not in /usr/lib

In UNIX the location of a library can be specified with the -L dir option to the compiler. Furthermore, in Solaris you need to specify the run time location with a corresponding -R dir option. For example, suppose we need to use the freely available libz in our C program, squash, built from squash.c. This is not part of Solaris so it is installed in /usr/local/lib. Here's a typical command to build it with Sun's C compiler - cc(1):

$ cc -o squash -L/usr/local/lib -R/usr/local/lib -lz squash.c

We could check what dynamic libraries are used with ldd(1) (list dynamic dependencies):

$ ldd squash
        libz.so =>       /usr/local/lib/libz.so
        libc.so.1 =>     /usr/lib/libc.so.1
        libdl.so.1 =>    /usr/lib/libdl.so.1
        /usr/platform/SUNW,Ultra-5_10/lib/libc_psr.so.1

Note, the other libraries are incorporated by default, and are not of interest to us. The last one would be different on a different type of Sun host. If we missed out the -R option, the binary would still build, however we could set LD_LIBRARY_PATH for it to find libz. ldd would give something like:

$ ldd squash
        libz.so =>       (file not found)
        libc.so.1 =>     /usr/lib/libc.so.1
        libdl.so.1 =>    /usr/lib/libdl.so.1
        /usr/platform/SUNW,Ultra-5_10/lib/libc_psr.so.1

However, this is a mistake and you should not set LD_LIBRARY_PATH; reasons why not are given below. As an alternative to using the -L and -R options, you can set the environment variable LD_RUN_PATH before compiling the code.

Using C++ compilers

To use Gnu's g++ compiler to compile foo.cc which uses the Standard C++ library, you must do:

$ gcc -o foo -L/gnu/lib -R/gnu/lib -lstdc++ foo.cc
This is because it is not in a standard location as far as Solaris is concerned. This may not be needed in the future because of new functionality in Solaris 8. To build foo using Sun's C++ compiler, you can do:
$ CC -o foo foo.cc
This is because Solaris has its own C++ library which is in a standard location.

Changes in Solaris 8

In Solaris 8, functionality is added for the administrator to easily add default link locations to a host's environment with the crle(1) command. This will lead to less confusion with linking.

Why setting LD_LIBRARY_PATH is considered harmful

For the following reasons:

Further information

The Solaris Linker and Libraries Guide

Some library locations and their contents

First some Solaris library paths; 64-bit libraries typically exist in a sparcv9 subdirectory:

Library pathContentsNotes
/usr/libStandard system librariesDefault search path
/usr/openwin/libX11 librariesnone
/usr/dt/libCDE libraries and Motif (Xm)none
/usr/4libSunOS 4 binary compatibilityDO NOT USE
/usr/ucblibBSD compatibilityDO NOT USE

Some local library path conventions:

Library pathContentsNotes
/usr/local/lib3rd party librariesnone
/gnu/libGnu librariesGnu's C++ compiler uses the libstdc++ here
/usr/lang/libSun compiler extrasalso exists as /opt/SUNWspro/lib
/usr/local/kde/libKDE librariesstandard ones exist elsewhere
/gnu/gnome/libGNOME librariesstandard ones exist elsewhere

[Local mirror site's addendum: Usenet poster Dan Espen recommends, instead: "LDFLAGS='-L/my/strange/path/lib -Wl,-rpath /my/strange/path/lib'"