Please document need to run install_name_tool when installing boost on MacOSX

[dank@…]

This was originally discussed in 2008 on the Boost.build mailing list in thread "Install_name wrong on OS X dylibs with latest CVS"

To recap, building on MacOSX with seems to work, but the resulting shared libraries lack an absolute path in their install_name, so apps using them fail to load; instead, one gets an error like

dyld: Library not loaded: libboost_thread.dylib
  Referenced from: a.out
  Reason: image not found
Trace/BPT trap: 5

To work around this, the user can set DYLIB_LIBRARY_PATH to point to the libraries, but that's not very satisfying. Or the packager can use Apple's install_name_tool to set the absolute path at install time.

This last bit was made possible by the fix to bug 1927.

This should be documented, perhaps near where hardcode-dll-paths is documented. The document might say something like

Note about building on MacOSX

Shared libraries on MacOSX generally have their absolute path embedded in them in a field called install_name. This field is copied into any executable that links against them. The executable then looks exactly at that absolute path to find the library. If the library is not there, the executable will fail to load. If you use e.g. homebrew to install Boost, this is taken care of for you, but if you're building boost yourself, read on.

With the default build of Boost, doing e.g.

otool -D libboost_regex.dylib

produces just a pathless filename, and doing

otool -L a.out | grep libboost

on a library linked against this will show that the executable is trying to load the library without a path.

A user can work around this by add the install directory to the DYLIB_LIBRARY_PATH environment variable, but that's often not acceptable.

A nicer way to work around this is to use Apple's install_name_tool to embed the library's full path inside the library at install time, e.g.

install_name_tool -id /foo/bar/libboost_regex.dylib /foo/bar/libboost_regex.dylib

(Alternately, you can patch the use of -install_name in tools/build/v2/tools/darwin.jam before building, but that's ugly.)