diff --git a/doc/src/advanced.xml b/doc/src/advanced.xml
index bfb62b475..f0370066b 100644
--- a/doc/src/advanced.xml
+++ b/doc/src/advanced.xml
@@ -799,6 +799,26 @@ lib compress : : <file>/opt/libs/compress.a ;
be specified several time, or can be omitted -- in which case only
default compiler paths will be searched.
+
+ The difference between using the file feature as
+ opposed to the name name feature together with the
+ search feature is that file is more
+ precise. A specific file will be used. On the other hand, the
+ search feature only adds a library path, and the
+ name feature gives the basic name of the library. The
+ search rules are specific to the linker. For example, given these
+ definition:
+
+lib a : : <variant>release <file>/pool/release/a.so ;
+lib a : : <variant>debug <file>/pool/debug/a.so ;
+lib b : : <variant>release <file>/pool/release/b.so ;
+lib b : : <variant>debug <file>/pool/debug/b.so ;
+
+ It's possible to use release version of a and debug
+ version of b. Had we used the name and
+ search features, the linker would always pick either
+ release or debug versions.
+
For convenience, the following syntax is allowed:
@@ -1055,14 +1075,10 @@ unit-test helpers_test : helpers_test.cpp helpers ;
- Specify a path where dynamic libraries should be found at
- where executable or shared library is run. This feature
- directly affects binaries with the gcc compiler, allowing them
- to pick specific libraries, and ignoring all environment
- settings. On other toolsets, the binary still requires proper
- environment settings to be run. However, Boost.Build tools
- which run executables will notice dll-path settings and create
- this environment automatically.
+ Specify an additional path where shared libraries should be
+ searched where the executable or shared library is run. This
+ feature only affect Unix compilers. Plase see the FAQ entry for details.
@@ -1073,12 +1089,17 @@ unit-test helpers_test : helpers_test.cpp helpers ;
Controls automatic generation of dll-path properties.
- Allowed values:off, on When this
- property is on, usage requirements for each library will
- include additional dll-path propertry, with the path the the
- generated library file. This allows to run executables
- without placing all the dependent libraries to a single
- location.
+ Allowed values:
+ true, false. This property
+ is specific to Unix systems. If an executable is build with
+ <hardcode-dll-paths>true, the generated binary
+ will contain the list of all the paths to the used shared
+ libraries. As the result, the executable can be run without
+ changing system paths to shared libraries, or installing the
+ libraries to system paths. This is very convenient during
+ development. Plase see the FAQ entry for details.
+
diff --git a/doc/src/faq.xml b/doc/src/faq.xml
index baec2e28f..53c57ad58 100644
--- a/doc/src/faq.xml
+++ b/doc/src/faq.xml
@@ -245,6 +245,75 @@ obj b : b.cpp : <variant>release:<optimization>off ;
+
+ Why are the <code>dll-path</code> and
+ <code>hardcode-dll-paths</code> properties useful?
+
+
+ (This entry is specific to Unix system.)Before answering the
+ questions, let's recall a few points about shared libraries. Shared
+ libraries can be used by several applications, or other libraries,
+ without phisycally including the library in the application. This can
+ greatly decrease the total size of applications. It's also possible to
+ upgrade a shared library when the application is already
+ installed. Finally, shared linking can be faster.
+
+
+ However, the shared library must be found when the application is
+ started. The dynamic linker will search in a system-defined list of
+ paths, load the library and resolve the symbols. Which means that you
+ should either change the system-defined list, given by the
+ LD_LIBRARY_PATH environment variable, or install the
+ libraries to a system location. This can be inconvenient when
+ developing, since the libraries are not yet ready to be installed, and
+ cluttering system paths is undesirable. Luckily, on Unix there's another
+ way.
+
+
+ An executable can include a list of additional library paths, which
+ will be searched before system paths. This is excellent for development,
+ because the build system knows the paths to all libraries and can include
+ them in executables. That's done when the hardcode-dll-paths
+ feature has the true value, which is the
+ default. When the executables should be installed, the story is
+ different.
+
+
+
+ Obviously, installed executable should not hardcode paths to your
+ development tree. (The stage rule explicitly disables the
+ hardcode-dll-paths feature for that reason.) However, you
+ can use the dll-path feature to add explicit paths
+ manually. For example:
+
+stage installed : application : <dll-path>/usr/lib/snake
+ <location>/usr/bin ;
+
+ will allow the application to find libraries placed to
+ /usr/lib/snake.
+
+
+ If you install libraries to a nonstandard location and add an
+ explicit path, you get more control over libraries which will be used. A
+ library of the same name in a system location will not be inadvertently
+ used. If you install libraries to a system location and do not add any
+ paths, the system administrator will have more control. Each library can
+ be individually upgraded, and all applications will use the new library.
+
+
+ Which approach is best depends on your situation. If the libraries
+ are relatively standalone and can be used by third party applications,
+ they should be installed in the system location. If you have lots of
+ libraries which can be used only by our application, it makes sense to
+ install it to a nonstandard directory and add an explicit path, like the
+ example above shows. Please also note that guidelines for different
+ systems differ in this respect. The Debian guidelines prohibit any
+ additional search paths, and Solaris guidelines suggest that they should
+ always be used.
+
+
+
+