LD_LIBRARY_PATH vs LIBRARY_PATH

I'm building a simple C++ program and I want to temporarily substitute a system supplied shared library with a more recent version of it, for development and testing.

I tried setting the LD_LIBRARY_PATH variable but the linker (ld) failed with:

/usr/bin/ld: cannot find -lyaml-cpp

I expected that to work because according to the ld man page:

The linker uses the following search paths to locate required shared libraries: ... For a native linker, the contents of the environment variable "LD_LIBRARY_PATH"...

I then tried setting the LIBRARY_PATH, and that worked.

According to the GCC manual:

The value of LIBRARY_PATH is a colon-separated list of directories, much like PATH. When configured as a native compiler, GCC tries the directories thus specified when searching for special linker files, if it can't find them using GCC_EXEC_PREFIX. Linking using GCC also uses these directories when searching for ordinary libraries for the -l option (but directories specified with -L come first).

As the (GCC) manual suggests, LIBRARY_PATH works because I link with GCC.

But..

• Since I link with gcc why ld is being called, as the error message suggests?
• What's the point of having two variables serving the same purpose? Are there any other differences?

LIBRARY_PATH is used by gcc before compilation to search directories containing static and shared libraries that need to be linked to your program.

LD_LIBRARY_PATH is used by your program to search directories containing shared libraries after it has been successfully compiled and linked.

EDIT: As pointed below, your libraries can be static or shared. If it is static then the code is copied over into your program and you don't need to search for the library after your program is compiled and linked. If your library is shared then it needs to be dynamically linked to your program and that's when LD_LIBRARY_PATH comes into play.

LD_LIBRARY_PATH is searched when the program starts, LIBRARY_PATH is searched at link time.

caveat from comments:

• When linking libraries with ld (instead of gcc or g++), the LIBRARY_PATH or LD_LIBRARY_PATH environment variables are not read.
• When linking libraries with gcc or g++, the LIBRARY_PATH environment variable is read (see documentation "gcc uses these directories when searching for ordinary libraries").

Since I link with gcc why ld is being called, as the error message suggests?

gcc calls ld internally when it is in linking mode.