From: jurko.gospodnetic_at_[hidden]
Date: 2008-06-03 02:46:17
Author: jurko
Date: 2008-06-03 02:46:16 EDT (Tue, 03 Jun 2008)
New Revision: 46074
URL: http://svn.boost.org/trac/boost/changeset/46074
Log:
Minor stylistic Boost Build documentation changes & typo corrections.
Text files modified:
trunk/tools/build/v2/doc/src/tutorial.xml | 350 ++++++++++++++++++---------------------
1 files changed, 165 insertions(+), 185 deletions(-)
Modified: trunk/tools/build/v2/doc/src/tutorial.xml
==============================================================================
--- trunk/tools/build/v2/doc/src/tutorial.xml (original)
+++ trunk/tools/build/v2/doc/src/tutorial.xml 2008-06-03 02:46:16 EDT (Tue, 03 Jun 2008)
@@ -372,104 +372,95 @@
</para>
- <para>Let's improve this project further.
- The library
- probably has some headers that must be used when compiling
- <filename>app.cpp</filename>. We could manually add the necessary
- <code>#include</code> paths to <filename>app</filename>'s
- requirements as values of the
- <varname><include></varname> feature, but then this work will
- be repeated for all programs
+ <para>
+ Let's improve this project further. The library probably has some headers
+ that must be used when compiling <filename>app.cpp</filename>. We could
+ manually add the necessary <code>#include</code> paths to <filename>app
+ </filename>'s requirements as values of the <varname><include>
+ </varname> feature, but then this work will be repeated for all programs
that use <filename>foo</filename>. A better solution is to modify
<filename>util/foo/Jamfile</filename> in this way:
-<programlisting>
+ <programlisting>
project
: usage-requirements <include>.
;
-lib foo : foo.cpp ;
-</programlisting>
+lib foo : foo.cpp ;</programlisting>
+
+ Usage requirements are applied not to the target being declared but to its
+ dependants. In this case, <literal><include>.</literal> will be
+ applied to all targets that directly depend on <filename>foo</filename>.
+ </para>
+
+ <para>
+ Another improvement is using symbolic identifiers to refer to the library,
+ as opposed to <filename>Jamfile</filename> location. In a large project, a
+ library can be used by many targets, and if they all use <filename>Jamfile
+ </filename> location, a change in directory organization entails much
+ work. The solution is to use project ids—symbolic names not tied to
+ directory layout. First, we need to assign a project id by adding this
+ code to <filename>Jamroot</filename>:
+ </para>
+
+ <programlisting>
+use-project /library-example/foo : util/foo ;</programlisting>
- Usage requirements are applied not to the target being declared
- but to its
- dependents. In this case, <literal><include>.</literal> will be applied to all
- targets that directly depend on <filename>foo</filename>.
- </para>
-
- <para>Another improvement is using symbolic identifiers to refer to
- the library, as opposed to <filename>Jamfile</filename> location.
- In a large project, a library can be used by many targets, and if
- they all use <filename>Jamfile</filename> location,
- a change in directory organization entails much work.
- The solution is to use project ids—symbolic names
- not tied to directory layout. First, we need to assign a project id by
- adding this code to
- <filename>Jamroot</filename>:</para>
- <programlisting>
-use-project /library-example/foo : util/foo ;
- </programlisting>
- <para>Second, we modify <filename>app/Jamfile</filename> to use the
- project id:
-
-<programlisting>
-exe app : app.cpp /library-example/foo//bar ;
-</programlisting>
-The <filename>/library-example/foo//bar</filename> syntax is used
- to refer to the target <filename>bar</filename> in
- the project with id <filename>/library-example/foo</filename>.
- We've achieved our goal—if the library is moved to a different
- directory, only <filename>Jamroot</filename> must be modified.
- Note that project ids are global—two Jamfiles are not
- allowed to assign the same project id to different directories.
+ <para>
+ Second, we modify <filename>app/Jamfile</filename> to use the project id:
+ <programlisting>
+exe app : app.cpp /library-example/foo//bar ;<programlisting>
+ The <filename>/library-example/foo//bar</filename> syntax is used to refer
+ to the target <filename>bar</filename> in the project with id <filename>
+ /library-example/foo</filename>. We've achieved our goal—if the
+ library is moved to a different directory, only <filename>Jamroot
+ </filename> must be modified. Note that project ids are global—two
+ Jamfiles are not allowed to assign the same project id to different
+ directories.
</para>
<tip>
- <para>If you want all applications in some project to link
- to a certain library, you can avoid having to specify it directly the sources of every
- target by using the
- <varname><library></varname> property. For example, if <filename>/boost/filesystem//fs</filename>
- should be linked to all applications in your project, you can add
- <code><library>/boost/filesystem//fs</code> to the project's requirements, like this:</para>
+ <para>If you want all applications in some project to link to a certain
+ library, you can avoid having to specify it directly the sources of
+ every target by using the <varname><library></varname> property.
+ For example, if <filename>/boost/filesystem//fs</filename> should be
+ linked to all applications in your project, you can add
+ <code><library>/boost/filesystem//fs</code> to the project's
+ requirements, like this:
+ </para>
<programlisting>
project
: requirements <source>/boost/filesystem//fs
- ;
- </programlisting>
+ ;</programlisting>
</tip>
-
</section>
<section id="bbv2.tutorial.testing">
<title>Testing</title>
-
-
</section>
<section id="bbv2.tutorial.linkage">
<title>Static and shared libaries</title>
- <para>Libraries can be either
- <emphasis>static</emphasis>, which means they are included in executable
- files that use them, or <emphasis>shared</emphasis> (a.k.a.
- <emphasis>dynamic</emphasis>), which are only referred to from executables,
- and must be available at run time. Boost.Build can create and use both kinds.
- </para>
-
- <para>The kind of library produced from a <code>lib</code> target is
- determined by the value of the <varname>link</varname> feature. Default
- value is <literal>shared</literal>, and to build a static library, the value
- should be <literal>static</literal>. You can request a static build either
- on the command line:
- <screen>
-bjam link=static
- </screen>
- or in the library's requirements:
- <programlisting>
-lib l : l.cpp : <link>static ;
- </programlisting>
+ <para>
+ Libraries can be either <emphasis>static</emphasis>, which means they are
+ included in executable files that use them, or <emphasis>shared</emphasis>
+ (a.k.a. <emphasis>dynamic</emphasis>), which are only referred to from
+ executables, and must be available at run time. Boost.Build can create and
+ use both kinds.
+ </para>
+
+ <para>
+ The kind of library produced from a <code>lib</code> target is determined
+ by the value of the <varname>link</varname> feature. Default value is
+ <literal>shared</literal>, and to build a static library, the value should
+ be <literal>static</literal>. You can request a static build either on the
+ command line:
+ <programlisting>bjam link=static<programlisting>
+ or in the library's requirements:
+ <programlisting>lib l : l.cpp : <link>static ;</programlisting>
</para>
<para>
@@ -488,119 +479,114 @@
VP: to be addressed when this section is moved. See comment below.
-->
- <programlisting>
+ <programlisting>
exe important : main.cpp helpers/<link>static ;</programlisting>
- No matter what arguments are specified on the <command>bjam</command>
- command line, <filename>important</filename> will only be linked with
- the static version of <filename>helpers</filename>.
+ No matter what arguments are specified on the <command>bjam</command>
+ command line, <filename>important</filename> will only be linked with the
+ static version of <filename>helpers</filename>.
</para>
- <para>
- Specifying properties in target references is especially useful if you
- use a library defined in some other project (one you can't
- change) but you still want static (or dynamic) linking to that library
- in all cases. If that library is used by many targets,
- you <emphasis>could</emphasis> use target references
- everywhere:
+ <para>
+ Specifying properties in target references is especially useful if you use
+ a library defined in some other project (one you can't change) but you
+ still want static (or dynamic) linking to that library in all cases. If
+ that library is used by many targets, you <emphasis>could</emphasis> use
+ target references everywhere:
- <programlisting>
+ <programlisting>
exe e1 : e1.cpp /other_project//bar/<link>static ;
exe e10 : e10.cpp /other_project//bar/<link>static ;</programlisting>
- but that's far from being convenient. A better approach is
- to introduce a level of indirection. Create a local
- <type>alias</type> target that refers to the static (or
- dynamic) version of <filename>foo</filename>:
+ but that's far from being convenient. A better approach is to introduce a
+ level of indirection. Create a local <type>alias</type> target that refers
+ to the static (or dynamic) version of <filename>foo</filename>:
- <programlisting>
+ <programlisting>
alias foo : /other_project//bar/<link>static ;
exe e1 : e1.cpp foo ;
exe e10 : e10.cpp foo ;</programlisting>
- The <link linkend="bbv2.tasks.alias"><functionname>alias</functionname></link>
- rule is specifically used to rename a reference to a target and possibly
- change the properties.
-
- <!-- You should introduce the alias rule in an earlier
- section, before describing how it applies to this
- specific use-case, and the foregoing sentence should
- go there.
- VP: we've agreed that this section should be moved further
- in the docs, since it's more like advanced reading. When
- I'll move it, I'll make sure 'alias' is already mentioned.
- -->
- </para>
+ The <link linkend="bbv2.tasks.alias"><functionname>alias</functionname>
+ </link> rule is specifically used to rename a reference to a target and
+ possibly change the properties.
+
+ <!-- You should introduce the alias rule in an earlier section, before
+ describing how it applies to this specific use-case, and the
+ foregoing sentence should go there.
+ VP: we've agreed that this section should be moved further in the
+ docs, since it's more like advanced reading. When I move it, I'll
+ make sure 'alias' is already mentioned.
+ -->
+ </para>
- <tip>
- <para>
- When one library uses another, you put the second library in
- the source list of the first. For example:
- <programlisting>
+ <tip>
+ <para>
+ When one library uses another, you put the second library in the source
+ list of the first. For example:
+ <programlisting>
lib utils : utils.cpp /boost/filesystem//fs ;
lib core : core.cpp utils ;
exe app : app.cpp core ;</programlisting>
- This works no matter what kind of linking is used. When
- <filename>core</filename> is built as a shared library, it is linked
- directly into <filename>utils</filename>. Static libraries can't
- link to other libraries, so when <filename>core</filename> is built
- as a static library, its dependency on <filename>utils</filename> is passed along to
- <filename>core</filename>'s dependents, causing
- <filename>app</filename> to be linked with both
- <filename>core</filename> and <filename>utils</filename>.
- </para>
- </tip>
-
- <note>
- <para>(Note for non-UNIX system). Typically, shared libraries must be
- installed to a directory in the dynamic linker's search
- path. Otherwise, applications that use shared libraries can't be
- started. On Windows, the dynamic linker's search path is given by the
- <envar>PATH</envar> environment variable. This restriction is lifted
- when you use Boost.Build testing facilities—the
- <envar>PATH</envar> variable will be automatically adjusted before
- running executable.
+ This works no matter what kind of linking is used. When <filename>core
+ </filename> is built as a shared library, it is linked directly into
+ <filename>utils</filename>. Static libraries can't link to other
+ libraries, so when <filename>core</filename> is built as a static
+ library, its dependency on <filename>utils</filename> is passed along to
+ <filename>core</filename>'s dependents, causing <filename>app</filename>
+ to be linked with both <filename>core</filename> and <filename>utils
+ </filename>.
+ </para>
+ </tip>
+
+ <note>
+ <para>
+ (Note for non-UNIX system). Typically, shared libraries must be
+ installed to a directory in the dynamic linker's search path. Otherwise,
+ applications that use shared libraries can't be started. On Windows, the
+ dynamic linker's search path is given by the <envar>PATH</envar>
+ environment variable. This restriction is lifted when you use
+ Boost.Build testing facilities—the <envar>PATH</envar> variable
+ will be automatically adjusted before running the executable.
<!-- Need ref here to 'testing facilities' -->
- </para>
- </note>
+ </para>
+ </note>
</section>
<section id="bbv2.tutorial.conditions">
<title>Conditions and alternatives</title>
- <para>Sometimes, particular relationships need to be maintained
- among a target's build properties. For example, you might want to set
- specific <code>#define</code> when a library is built as shared,
- or when a target's <code>release</code> variant is built.
- This can be achieved with <firstterm>conditional requirements</firstterm>.
+ <para>
+ Sometimes, particular relationships need to be maintained among a target's
+ build properties. For example, you might want to set specific <code>
+ #define</code> when a library is built as shared, or when a target's
+ <code>release</code> variant is built. This can be achieved using
+ <firstterm>conditional requirements</firstterm>.
- <programlisting>
+ <programlisting>
lib network : network.cpp
: <emphasis role="bold"><link>shared:<define>NEWORK_LIB_SHARED</emphasis>
<variant>release:<define>EXTRA_FAST
- ;
-</programlisting>
+ ;</programlisting>
- In the example above, whenever <filename>network</filename> is
- built with <code><link>shared</code>,
- <code><define>NEWORK_LIB_SHARED</code> will be in its
- properties, too. Also, whenever its release variant is built,
- <code><define>EXTRA_FAST</code> will appear in its properties.
+ In the example above, whenever <filename>network</filename> is built with
+ <code><link>shared</code>, <code><define>NEWORK_LIB_SHARED
+ </code> will be in its properties, too. Also, whenever its release variant
+ is built, <code><define>EXTRA_FAST</code> will appear in its
+ properties.
</para>
<para>
- Sometimes the ways a target is built are so different that
- describing them using conditional requirements would be
- hard. For example, imagine that a library actually uses
- different source files depending on the toolset used to build
- it. We can express this situation using <firstterm>target
+ Sometimes the ways a target is built are so different that describing them
+ using conditional requirements would be hard. For example, imagine that a
+ library actually uses different source files depending on the toolset used
+ to build it. We can express this situation using <firstterm>target
alternatives</firstterm>:
-<programlisting>
+ <programlisting>
lib demangler : dummy_demangler.cpp ; # alternative 1
lib demangler : demangler_gcc.cpp : <toolset>gcc ; # alternative 2
-lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3
-</programlisting>
+lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3</programlisting>
When building <filename>demangler</filename>, Boost.Build will compare
requirements for each alternative with build properties to find the best
match. For example, when building with <code><toolset>gcc</code>
@@ -619,7 +605,7 @@
<varname>file</varname> property. Target alternatives can be used to
associate multiple library files with a single conceptual target. For
example:
-<programlisting>
+ <programlisting>
# util/lib2/Jamfile
lib lib2
:
@@ -629,67 +615,61 @@
lib lib2
:
: <file>lib2_debug.a <variant>debug
- ;
-</programlisting>
+ ;</programlisting>
This example defines two alternatives for <filename>lib2</filename>, and
for each one names a prebuilt file. Naturally, there are no sources.
Instead, the <varname><file></varname> feature is used to specify
the file name.
</para>
- <para>
- Once a prebuilt target has been declared, it can be used just like any other target:
-<programlisting>
-exe app : app.cpp ../util/lib2//lib2 ;
-</programlisting>
+ <para>
+ Once a prebuilt target has been declared, it can be used just like any
+ other target:
- As with any target, the alternative selected depends on the
- properties propagated from <filename>lib2</filename>'s dependents.
- If we build the the release and debug versions of <filename>app</filename> will be linked
- with <filename>lib2_release.a</filename> and <filename>lib2_debug.a</filename>, respectively.
+ <programlisting>
+exe app : app.cpp ../util/lib2//lib2 ;</programlisting>
+ As with any target, the alternative selected depends on the properties
+ propagated from <filename>lib2</filename>'s dependants. If we build the
+ release and debug versions of <filename>app</filename> will be linked
+ with <filename>lib2_release.a</filename> and <filename>lib2_debug.a
+ </filename>, respectively.
</para>
<para>
- System libraries—those that are automatically found by
- the toolset by searching through some set of predetermined
- paths—should be declared almost like regular ones:
+ System libraries—those that are automatically found by the toolset
+ by searching through some set of predetermined paths—should be
+ declared almost like regular ones:
-<programlisting>
-lib pythonlib : : <name>python22 ;
-</programlisting>
+ <programlisting>
+lib pythonlib : : <name>python22 ;</programlisting>
- We again don't specify any sources, but give a
- <varname>name</varname> that should be passed to the
- compiler. If the gcc toolset were used to link an executable
- target to <filename>pythonlib</filename>, <option>-lpython22</option>
- would appear in the command line (other compilers may use
- different options).
+ We again don't specify any sources, but give a <varname>name</varname>
+ that should be passed to the compiler. If the gcc toolset were used to
+ link an executable target to <filename>pythonlib</filename>,
+ <option>-lpython22</option> would appear in the command line (other
+ compilers may use different options).
</para>
<para>
We can also specify where the toolset should look for the library:
-<programlisting>
-lib pythonlib : : <name>python22 <search>/opt/lib ;
-</programlisting>
+ <programlisting>
+lib pythonlib : : <name>python22 <search>/opt/lib ;</programlisting>
And, of course, target alternatives can be used in the usual way:
-<programlisting>
+ <programlisting>
lib pythonlib : : <name>python22 <variant>release ;
-lib pythonlib : : <name>python22_d <variant>debug ;
-</programlisting>
-
+lib pythonlib : : <name>python22_d <variant>debug ;</programlisting>
</para>
- <para>A more advanced use of prebuilt targets is described in <xref
- linkend="bbv2.recipies.site-config"/>.
+ <para>
+ A more advanced use of prebuilt targets is described in <xref linkend=
+ "bbv2.recipies.site-config"/>.
</para>
-
</section>
-
</chapter>
<!--