diff options
Diffstat (limited to 'tools/build/v2/doc/src/tutorial.xml')
| -rw-r--r-- | tools/build/v2/doc/src/tutorial.xml | 119 |
1 files changed, 60 insertions, 59 deletions
diff --git a/tools/build/v2/doc/src/tutorial.xml b/tools/build/v2/doc/src/tutorial.xml index 3763471dfe..141ed9196f 100644 --- a/tools/build/v2/doc/src/tutorial.xml +++ b/tools/build/v2/doc/src/tutorial.xml @@ -30,33 +30,33 @@ <filename>example/hello/</filename> directory. The project is described by a file called <filename>Jamroot</filename> that contains: -<programlisting> +<programlisting language="jam"> exe hello : hello.cpp ; </programlisting> Even with this simple setup, you can do some interesting things. First of - all, just invoking <command>bjam</command> will build the <filename>hello + all, just invoking <command>b2</command> will build the <filename>hello </filename> executable by compiling and linking <filename>hello.cpp - </filename>. By default, debug variant is built. Now, to build the release + </filename>. By default, the debug variant is built. Now, to build the release variant of <filename>hello</filename>, invoke <screen> -bjam release +b2 release </screen> - Note that debug and release variants are created in different directories, + Note that the debug and release variants are created in different directories, so you can switch between variants or even build multiple variants at once, without any unnecessary recompilation. Let us extend the example by adding another line to our project's <filename>Jamroot</filename>: -<programlisting> +<programlisting language="jam"> exe hello2 : hello.cpp ; </programlisting> Now let us build both the debug and release variants of our project again: <screen> -bjam debug release +b2 debug release </screen> Note that two variants of <filename>hello2</filename> are linked. Since we @@ -66,7 +66,7 @@ bjam debug release let us remove all the built products: <screen> -bjam --clean debug release +b2 --clean debug release </screen> It is also possible to build or clean specific targets. The following two @@ -74,8 +74,8 @@ bjam --clean debug release <filename>hello2</filename>. <screen> -bjam hello2 -bjam --clean hello2 +b2 hello2 +b2 --clean hello2 </screen> </para> </section> @@ -84,9 +84,9 @@ bjam --clean hello2 <title>Properties</title> <para> - To portably represent aspects of target configuration such as + To represent aspects of target configuration such as debug and release variants, or single- and multi-threaded - builds, Boost.Build uses <firstterm>features</firstterm> with + builds portably, Boost.Build uses <firstterm>features</firstterm> with associated <firstterm>values</firstterm>. For example, the <code>debug-symbols</code> feature can have a value of <code>on</code> or <code>off</code>. A <firstterm>property</firstterm> is just a (feature, @@ -102,7 +102,7 @@ bjam --clean hello2 builds the project's <code>release</code> variant with inlining disabled and debug symbols enabled: <screen> -bjam release inlining=off debug-symbols=on +b2 release inlining=off debug-symbols=on </screen> </para> @@ -116,19 +116,19 @@ bjam release inlining=off debug-symbols=on <para> The <option>release</option> and <option>debug</option> that we have seen - in <command>bjam</command> invocations are just a shorthand way to specify + in <command>b2</command> invocations are just a shorthand way to specify values of the <varname>variant</varname> feature. For example, the command above could also have been written this way: <screen> -bjam variant=release inlining=off debug-symbols=on +b2 variant=release inlining=off debug-symbols=on </screen> </para> <para> <varname>variant</varname> is so commonly-used that it has been given special status as an <firstterm>implicit</firstterm> feature— - Boost.Build will deduce the its identity just from the name of one of its + Boost.Build will deduce its identity just from the name of one of its values. </para> @@ -140,7 +140,7 @@ bjam variant=release inlining=off debug-symbols=on <title>Build Requests and Target Requirements</title> <para> - The set of properties specified on the command line constitute + The set of properties specified on the command line constitutes a <firstterm>build request</firstterm>—a description of the desired properties for building the requested targets (or, if no targets were explicitly requested, the project in the @@ -160,7 +160,7 @@ bjam variant=release inlining=off debug-symbols=on illustrates how these requirements might be specified. </para> -<programlisting> +<programlisting language="jam"> exe hello : hello.cpp : <include>boost <threading>multi @@ -170,7 +170,7 @@ exe hello <para> When <filename>hello</filename> is built, the two requirements specified above will always be present. If the build request given on the - <command>bjam</command> command-line explictly contradicts a target's + <command>b2</command> command-line explictly contradicts a target's requirements, the target requirements usually override (or, in the case of “free”” features like <varname><include></varname>, @@ -195,14 +195,15 @@ exe hello <title>Project Attributes</title> <para> - If we want the same requirements for our other target, <filename>hello2 - </filename>, we could simply duplicate them. However, as projects grow, - that approach leads to a great deal of repeated boilerplate in Jamfiles. + If we want the same requirements for our other target, + <filename>hello2</filename>, we could simply duplicate them. However, + as projects grow, that approach leads to a great deal of repeated + boilerplate in Jamfiles. Fortunately, there's a better way. Each project can specify a set of <firstterm>attributes</firstterm>, including requirements: -<programlisting> +<programlisting language="jam"> project : requirements <include>/home/ghost/Work/boost <threading>multi ; @@ -220,8 +221,8 @@ exe hello2 : hello.cpp ;</programlisting> <title>Project Hierarchies</title> <para> - So far we have only considered examples with one project —a. with - one user-written Boost.Jam file, <filename>Jamroot</filename>). A typical + So far we have only considered examples with one project, with + one user-written Boost.Jam file, <filename>Jamroot</filename>. A typical large codebase would be composed of many projects organized into a tree. The top of the tree is called the <firstterm>project root</firstterm>. Every subproject is defined by a file called <filename>Jamfile</filename> @@ -271,7 +272,7 @@ top/ any requirements specified by the subproject. For example, if <filename>top/Jamroot</filename> has -<programlisting> +<programlisting language="jam"> <include>/home/ghost/local </programlisting> @@ -289,14 +290,14 @@ top/ </para> <para> - Invoking <command>bjam</command> without explicitly specifying + Invoking <command>b2</command> without explicitly specifying any targets on the command line builds the project rooted in the current directory. Building a project does not automatically cause its subprojects to be built unless the parent project's Jamfile explicitly requests it. In our example, <filename>top/Jamroot</filename> might contain: -<programlisting> +<programlisting language="jam"> build-project app ; </programlisting> @@ -312,7 +313,7 @@ build-project app ; <title>Dependent Targets</title> <para> - When a building a target <filename>X</filename> depends on first + When building a target <filename>X</filename> that depends on first building another target <filename>Y</filename> (such as a library that must be linked with <firstterm>X</firstterm>), <filename>Y</filename> is called a @@ -326,14 +327,14 @@ build-project app ; use libraries from <filename>top/util/foo</filename>. If <filename>top/util/foo/Jamfile</filename> contains -<programlisting> +<programlisting language="jam"> lib bar : bar.cpp ; </programlisting> then to use this library in <filename>top/app/Jamfile</filename>, we can write: -<programlisting> +<programlisting language="jam"> exe app : app.cpp ../util/foo//bar ; </programlisting> @@ -352,7 +353,7 @@ exe app : app.cpp ../util/foo//bar ; <para>Suppose we build <filename>app</filename> with: <screen> -bjam app optimization=full define=USE_ASM +b2 app optimization=full define=USE_ASM </screen> Which properties will be used to build <code>foo</code>? The answer is that some features are @@ -369,13 +370,13 @@ bjam app optimization=full define=USE_ASM <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: + 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 language="jam"> project : usage-requirements <include>. ; @@ -397,7 +398,7 @@ lib foo : foo.cpp ;</programlisting> code to <filename>Jamroot</filename>: </para> - <programlisting> + <programlisting language="jam"> use-project /library-example/foo : util/foo ;</programlisting> <para> @@ -424,7 +425,7 @@ exe app : app.cpp /library-example/foo//bar ;</programlisting> requirements, like this: </para> - <programlisting> + <programlisting language="jam"> project : requirements <library>/boost/filesystem//fs ;</programlisting> @@ -448,9 +449,9 @@ project <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> + <programlisting>b2 link=static</programlisting> or in the library's requirements: - <programlisting>lib l : l.cpp : <link>static ;</programlisting> + <programlisting language="jam">lib l : l.cpp : <link>static ;</programlisting> </para> <para> @@ -469,10 +470,10 @@ project VP: to be addressed when this section is moved. See comment below. --> - <programlisting> + <programlisting language="jam"> exe important : main.cpp helpers/<link>static ;</programlisting> - No matter what arguments are specified on the <command>bjam</command> + No matter what arguments are specified on the <command>b2</command> command line, <filename>important</filename> will only be linked with the static version of <filename>helpers</filename>. </para> @@ -484,7 +485,7 @@ exe important : main.cpp helpers/<link>static ;</programlisting> that library is used by many targets, you <emphasis>could</emphasis> use target references everywhere: - <programlisting> + <programlisting language="jam"> exe e1 : e1.cpp /other_project//bar/<link>static ; exe e10 : e10.cpp /other_project//bar/<link>static ;</programlisting> @@ -497,9 +498,9 @@ 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. + The <link linkend="bbv2.tasks.alias">alias</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 @@ -514,7 +515,7 @@ exe e10 : e10.cpp foo ;</programlisting> <para> When one library uses another, you put the second library in the source list of the first. For example: - <programlisting> + <programlisting language="jam"> lib utils : utils.cpp /boost/filesystem//fs ; lib core : core.cpp utils ; exe app : app.cpp core ;</programlisting> @@ -553,14 +554,14 @@ exe app : app.cpp core ;</programlisting> <code>release</code> variant is built. This can be achieved using <firstterm>conditional requirements</firstterm>. - <programlisting> + <programlisting language="jam"> lib network : network.cpp : <emphasis role="bold"><link>shared:<define>NEWORK_LIB_SHARED</emphasis> <variant>release:<define>EXTRA_FAST ;</programlisting> In the example above, whenever <filename>network</filename> is built with - <code><link>shared</code>, <code><define>NEWORK_LIB_SHARED + <code language="jam"><link>shared</code>, <code language="jam"><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. @@ -572,15 +573,15 @@ lib network : network.cpp 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 language="jam"> 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> 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> + match. For example, when building with <code language="jam"><toolset>gcc</code> alternative 2, will be selected, and when building with - <code><toolset>msvc</code> alternative 3 will be selected. In all + <code language="jam"><toolset>msvc</code> alternative 3 will be selected. In all other cases, the most generic alternative 1 will be built. </para> </section> @@ -594,7 +595,7 @@ lib demangler : demangler_msvc.cpp : <toolset>msvc ; # alternative 3</prog <varname>file</varname> property. Target alternatives can be used to associate multiple library files with a single conceptual target. For example: - <programlisting> + <programlisting language="jam"> # util/lib2/Jamfile lib lib2 : @@ -616,7 +617,7 @@ lib lib2 Once a prebuilt target has been declared, it can be used just like any other target: - <programlisting> + <programlisting language="jam"> exe app : app.cpp ../util/lib2//lib2 ;</programlisting> As with any target, the alternative selected depends on the properties @@ -631,7 +632,7 @@ exe app : app.cpp ../util/lib2//lib2 ;</programlisting> by searching through some set of predetermined paths—should be declared almost like regular ones: - <programlisting> + <programlisting language="jam"> lib pythonlib : : <name>python22 ;</programlisting> We again don't specify any sources, but give a <varname>name</varname> @@ -644,12 +645,12 @@ lib pythonlib : : <name>python22 ;</programlisting> <para> We can also specify where the toolset should look for the library: - <programlisting> + <programlisting language="jam"> lib pythonlib : : <name>python22 <search>/opt/lib ;</programlisting> And, of course, target alternatives can be used in the usual way: - <programlisting> + <programlisting language="jam"> lib pythonlib : : <name>python22 <variant>release ; lib pythonlib : : <name>python22_d <variant>debug ;</programlisting> </para> |