[Boost-commit] svn:boost r77670 - trunk/tools/build/v2/doc/src

Subject: [Boost-commit] svn:boost r77670 - trunk/tools/build/v2/doc/src
From: steven_at_[hidden]
Date: 2012-03-31 15:26:01

Author: steven_watanabe
Date: 2012-03-31 15:26:01 EDT (Sat, 31 Mar 2012)
New Revision: 77670
URL: http://svn.boost.org/trac/boost/changeset/77670

Log:
Redo the documentation of lib to sound less awkward.
Text files modified: 
   trunk/tools/build/v2/doc/src/tasks.xml |   110 +++++++++++++++++++++------------------ 
   1 files changed, 59 insertions(+), 51 deletions(-)

Modified: trunk/tools/build/v2/doc/src/tasks.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/tasks.xml	(original)
+++ trunk/tools/build/v2/doc/src/tasks.xml	2012-03-31 15:26:01 EDT (Sat, 31 Mar 2012)
@@ -54,6 +54,11 @@
   <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 @@
 </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:
-<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 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 -->
+      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;name&gt;a &lt;search&gt;/pool/release ;
+lib b : : &lt;name&gt;b &lt;search&gt;/pool/debug ;
+</programlisting>
+          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 @@
 
     <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 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