boost/build
2
0
Fork 0
mirror of https://github.com/boostorg/build.git synced 2026-02-01 20:32:17 +00:00
Code Issues Projects Releases Wiki Activity

FAQ entry on dll-path. Clarify difference between <file> and <name>

Browse Source 
[SVN r25733]
This commit is contained in:
Vladimir Prus
2004-10-15 10:56:57 +00:00
parent 8b3a91639e
commit f713da2a09
2 changed files with 104 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
doc/src/advanced.xml
View File

@@ -799,6 +799,26 @@ lib compress : : &lt;file&gt;/opt/libs/compress.a ;
be specified several time, or can be omitted -- in which case only
default compiler paths will be searched.
</para>
<para>The difference between using the <code>file</code> feature as
opposed to the <code>name</code> name feature together with the
<code>search</code> feature is that <code>file</code> is more
precise. A specific file will be used. On the other hand, the
<code>search</code> feature only adds a library path, and the
<code>name</code> feature gives the basic name of the library. The
search rules are specific to the linker. For example, given these
definition:
<programlisting>
lib a : : &lt;variant&gt;release &lt;file&gt;/pool/release/a.so ;
lib a : : &lt;variant&gt;debug &lt;file&gt;/pool/debug/a.so ;
lib b : : &lt;variant&gt;release &lt;file&gt;/pool/release/b.so ;
lib b : : &lt;variant&gt;debug &lt;file&gt;/pool/debug/b.so ;
</programlisting>
It's possible to use release version of <code>a</code> and debug
version of <code>b</code>. Had we used the <code>name</code> and
<code>search</code> features, the linker would always pick either
release or debug versions.
</para>
<para>
For convenience, the following syntax is allowed:
@@ -1055,14 +1075,10 @@ unit-test helpers_test : helpers_test.cpp helpers ;
<listitem>
<simpara>
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 <link
linkend="bbv2.faq.dll-path">FAQ entry</link> for details.
</simpara>
</listitem></varlistentry>
@@ -1073,12 +1089,17 @@ unit-test helpers_test : helpers_test.cpp helpers ;
Controls automatic generation of dll-path properties.
</simpara>
<para><emphasis role="bold">Allowed values:</emphasis> <literal>off</literal>, <literal>on</literal> 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.</para>
<para><emphasis role="bold">Allowed values:</emphasis>
<literal>true</literal>, <literal>false</literal>. This property
is specific to Unix systems. If an executable is build with
<code>&lt;hardcode-dll-paths&gt;true</code>, 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 <link
linkend="bbv2.faq.dll-path">FAQ entry</link> for details.
</para>
</listitem></varlistentry>
</variablelist>
</section>

69
doc/src/faq.xml
View File

@@ -245,6 +245,75 @@ obj b : b.cpp : &lt;variant&gt;release:&lt;optimization&gt;off ;
</para>
</section>
<section id="bbv2.faq.dll-path">
<title>Why are the <code>dll-path</code> and
<code>hardcode-dll-paths</code> properties useful?
</title>
<para>(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.
</para>
<para>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
<envar>LD_LIBRARY_PATH</envar> 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.
</para>
<para>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 <code>hardcode-dll-paths</code>
feature has the <literal>true</literal> value, which is the
default. When the executables should be installed, the story is
different.
</para>
<para>
Obviously, installed executable should not hardcode paths to your
development tree. (The <code>stage</code> rule explicitly disables the
<code>hardcode-dll-paths</code> feature for that reason.) However, you
can use the <code>dll-path</code> feature to add explicit paths
manually. For example:
<programlisting>
stage installed : application : &lt;dll-path&gt;/usr/lib/snake
&lt;location&gt;/usr/bin ;
</programlisting>
will allow the application to find libraries placed to
<filename>/usr/lib/snake</filename>.
</para>
<para>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.
</para>
<para>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.
</para>
</section>
</chapter>
<!--