boost/build
2
0
Fork 0
mirror of https://github.com/boostorg/build.git synced 2026-02-16 13:22:11 +00:00
Code Issues Projects Releases Wiki Activity

Redo the documentation of lib to sound less awkward.

Browse Source 
[SVN r77670]
This commit is contained in:
Steven Watanabe
2012-03-31 19:26:01 +00:00
parent 67385c7348
commit 3bb774d828
1 changed files with 57 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
v2/doc/src/tasks.xml
View File

@@ -54,6 +54,11 @@ exe hello : hello.cpp some_library.lib /some_project//library
<section id="bbv2.tasks.libraries">
<title>Libraries</title>
<indexterm>
<primary>library</primary>
<secondary>target</secondary>
</indexterm>
<para>
Library targets are created using the <code>lib</code> rule, which
follows the <link linkend="bbv2.main-target-rule-syntax">common syntax
@@ -63,66 +68,71 @@ lib helpers : helpers.cpp ;
</programlisting>
This will define a library target named <code>helpers</code> built from
the <code>helpers.cpp</code> source file.
It can be either a static library or a shared library,
depending on the value of the <link linkend="bbv2.overview.builtins.features.link">&lt;link&gt;</link> feature.
</para>
<para>
Depending on the given &lt;link&gt; feature value the library will be
either static or shared.
</para>
<para>
Library targets may be used to represent:
Library targets can represent:
<itemizedlist>
<listitem>
<para>
<code>Built libraries</code> that get built from specified sources,
as is the one in the example above. <!-- add link -->
Libraries that should be built from source,
as in the example above.
</para>
</listitem>
<listitem>
<para>
<code>Prebuilt libraries</code> which already exist on the system
and are just supposed to be used by the build system. Such
libraries may be searched for by the tools using them (typically
linkers referencing the library using the <option>-l</option>
option) or their path may be known in advance by the build system.
<!-- We need examples for this. -->
Prebuilt libraries which already exist on the system.
Such libraries can be searched for by the tools using them (typically
with the linker's <option>-l</option> option) or their paths can be
known in advance by the build system.
</para>
</listitem>
</itemizedlist>
</para>
<para>
The syntax for these case is given below:
The syntax for prebuilt libraries is given below:
<programlisting>
lib z : : &lt;name&gt;z &lt;search&gt;/home/ghost ;
lib compress : : &lt;file&gt;/opt/libs/compress.a ;
</programlisting>
The <code>name</code> property specifies the name that should be passed to
the <option>-l</option> option, and the <code>file</code> property
specifies the file location. The <varname>search</varname> feature
specifies paths in which to search for the library. That feature can be
specified several times or it can be omitted, in which case only the
default compiler paths will be searched.
The <code>name</code> property specifies the name of the library
without the standard prefixes and suffixes. For example, depending
on the system, <code>z</code> could refer to a file called
z.so, libz.a, or z.lib, etc. The <code>search</code> feature
specifies paths in which to search for the library in addition
to the default compiler paths. <code>search</code> can be specified
several times or it can be omitted, in which case only the default
compiler paths will be searched. The <code>file</code> property
specifies the file location.
</para>
<para>
The difference between using the <varname>file</varname> feature as
opposed to the <varname>name</varname> feature together with the <varname>
search</varname> feature is that <varname>file</varname> is more precise.
A specific file will be used as opposed to the <varname>search</varname>
feature only adding a library path, or the <varname>name</varname> feature
giving only the basic name of the library. The search rules are specific
to the linker used. For example, given these definition:
The difference between using the <code>file</code> feature and
using a combination of the <code>name</code> and <code>search</code>
features is that <code>file</code> is more precise.
<warning>
<para>
The value of the <code>search</code> feature is just added to the
linker search path. When linking to multiple libraries,
the paths specified by <code>search</code> are combined without
regard to which <code>lib</code> target each path came from.
Thus, given
<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 ;
lib a : : &lt;name&gt;a &lt;search&gt;/pool/release ;
lib b : : &lt;name&gt;b &lt;search&gt;/pool/debug ;
</programlisting>
It is possible to use a release version of <code>a</code> and debug
version of <code>b</code>. Had we used the <varname>name</varname> and
<varname>search</varname> features, the linker would have always picked
either the release or the debug versions.
<!-- explain -->
If /pool/release/a.so, /pool/release/b.so, /pool/debug/a.so,
and /pool/release/b.so all exist, the linker will probably
take both <code>a</code> and <code>b</code> from the same
directory, instead of finding <code>a</code> in /pool/release
and <code>b</code> in /pool/debug. If you need to distinguish
between multiple libraries with the same name, it's safer
to use <code>file</code>.
</para>
</warning>
</para>
<para>
@@ -154,18 +164,18 @@ lib png : z : &lt;name&gt;png ;
<note>
<para>
When a library has a shared library defined as its source, or a static
library has another static library defined as its source then any target
When a library has a shared library as a source, or a static
library has another static library as a source then any target
linking to the first library with automatically link to its source
library as well.
</para>
<para>
On the other hand, when a shared library has a static library defined as
its source then the first library will be built so that it completely
On the other hand, when a shared library has a static library as
a source then the first library will be built so that it completely
includes the second one.
</para>
<para>
If you do not want shared libraries to include all libraries specified
If you do not want a shared library to include all the libraries specified
in its sources (especially statically linked ones), you would need to
use the following:
<programlisting>
@@ -173,18 +183,16 @@ lib b : a.cpp ;
lib a : a.cpp : &lt;use&gt;b : : &lt;library&gt;b ;
</programlisting>
This specifies that library <code>a</code> uses library <code>b</code>,
and causes all executables that link to <code>a</code> also link to
<code>b</code>. In this case, even for shared linking, the
<code>a</code> library will not even refer to <code>b</code>.
and causes all executables that link to <code>a</code> to link to
<code>b</code> also. In this case, even for shared linking, the
<code>a</code> library will not refer to <code>b</code>.
</para>
</note>
<para>
One Boost.Build feature that is often very useful for defining library
targets are usage requirements. <!-- Rephrase that. But then, it is much
too late for an introduction of usage requirements - you have already
discussed them many times. Also, add references to the sections describing
requirements and usage-requirements here. --> For example, imagine that
<!-- FIXME: After adding a full subsection on usage requirements, link to it -->
<link linkend="bbv2.overview.targets">Usage requirements</link> are often
very useful for defining library targets. For example, imagine that
you want you build a <code>helpers</code> library and its interface is
described in its <code>helpers.hpp</code> header file located in the same
directory as the <code>helpers.cpp</code> source file. Then you could add