| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" |
| "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> |
| |
| <!-- Copyright 2006 Vladimir Prus --> |
| <!-- Distributed under the Boost Software License, Version 1.0. --> |
| <!-- (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt) --> |
| |
| <chapter id="bbv2.tasks"> |
| <title>Common tasks</title> |
| |
| <para> |
| This section describes main targets types that Boost.Build supports |
| out-of-the-box. Unless otherwise noted, all mentioned main target rules have |
| the common signature, described in <xref linkend="bbv2.overview.targets"/>. |
| </para> |
| |
| <section id="bbv2.tasks.programs"> |
| <title>Programs</title> |
| |
| <indexterm><primary>exe</primary></indexterm> |
| <para> |
| Programs are created using the <code>exe</code> rule, which follows the |
| <link linkend="bbv2.main-target-rule-syntax">common syntax</link>. For |
| example: |
| <programlisting> |
| exe hello : hello.cpp some_library.lib /some_project//library |
| : <threading>multi |
| ; |
| </programlisting> |
| This will create an executable file from the sources -- in this case, one |
| C++ file, one library file present in the same directory, and another |
| library that is created by Boost.Build. Generally, sources can include C |
| and C++ files, object files and libraries. Boost.Build will automatically |
| try to convert targets of other types. |
| </para> |
| |
| <tip> |
| <para> |
| On Windows, if an application uses shared libraries, and both the |
| application and the libraries are built using Boost.Build, it is not |
| possible to immediately run the application, because the <literal>PATH |
| </literal> environment variable should include the path to the |
| libraries. It means you have to either add the paths manually, or have |
| the build place the application and the libraries into the same |
| directory. See <xref linkend="bbv2.tasks.installing"/>. |
| </para> |
| <!-- We should be emphasizing the use of the built-in testing rules |
| rather than continually discussing these quirks of running programs |
| with shared libraries. --> |
| </tip> |
| </section> |
| |
| <section id="bbv2.tasks.libraries"> |
| <title>Libraries</title> |
| |
| <para> |
| Library targets are created using the <code>lib</code> rule, which |
| follows the <link linkend="bbv2.main-target-rule-syntax">common syntax |
| </link>. For example: |
| <programlisting> |
| lib helpers : helpers.cpp ; |
| </programlisting> |
| This will define a library target named <code>helpers</code> built from |
| the <code>helpers.cpp</code> source file. |
| </para> |
| <para> |
| Depending on the given <link> feature value the library will be |
| either static or shared. |
| </para> |
| <para> |
| Library targets may be used to represent: |
| <itemizedlist> |
| <listitem> |
| <para> |
| <code>Built libraries</code> that get built from specified sources, |
| as is the one in the example above. <!-- add link --> |
| </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. --> |
| </para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| The syntax for these case is given below: |
| <programlisting> |
| lib z : : <name>z <search>/home/ghost ; |
| lib compress : : <file>/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. |
| </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 : : <variant>release <file>/pool/release/a.so ; |
| lib a : : <variant>debug <file>/pool/debug/a.so ; |
| lib b : : <variant>release <file>/pool/release/b.so ; |
| lib b : : <variant>debug <file>/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 --> |
| </para> |
| |
| <para> |
| For convenience, the following syntax is allowed: |
| <programlisting> |
| lib z ; |
| lib gui db aux ; |
| </programlisting> |
| which has exactly the same effect as: |
| <programlisting> |
| lib z : : <name>z ; |
| lib gui : : <name>gui ; |
| lib db : : <name>db ; |
| lib aux : : <name>aux ; |
| </programlisting> |
| </para> |
| |
| <para> |
| When a library references another library you should put that other |
| library in its list of sources. This will do the right thing in all cases. |
| <!--Add a link to the notes below. --> For portability, you should specify |
| library dependencies even for searched and prebuilt libraries, othewise, |
| static linking on Unix will not work. For example: |
| <programlisting> |
| lib z ; |
| lib png : z : <name>png ; |
| </programlisting> |
| </para> |
| |
| <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 |
| 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 |
| includes the second one. |
| </para> |
| <para> |
| If you do not want shared libraries to include all libraries specified |
| in its sources (especially statically linked ones), you would need to |
| use the following: |
| <programlisting> |
| lib b : a.cpp ; |
| lib a : a.cpp : <use>b : : <library>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>. |
| </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 |
| 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 |
| the following to the Jamfile located in that same directory: |
| <programlisting> |
| lib helpers : helpers.cpp : : : <include>. ; |
| </programlisting> |
| which would automatically add the directory where the target has been |
| defined (and where the library's header file is located) to the compiler's |
| include path for all targets using the <code>helpers</code> library. This |
| feature greatly simplifies Jamfiles. |
| </para> |
| </section> |
| |
| <section id="bbv2.tasks.alias"> |
| <title>Alias</title> |
| |
| <para> |
| The <functionname>alias</functionname> rule gives an alternative name to a |
| group of targets. For example, to give the name <filename>core</filename> |
| to a group of three other targets with the following code: |
| <programlisting> |
| alias core : im reader writer ; |
| </programlisting> |
| Using <filename>core</filename> on the command line, or in the source list |
| of any other target is the same as explicitly using <filename>im |
| </filename>, <filename>reader</filename>, and <filename>writer</filename>. |
| </para> |
| |
| <para> |
| Another use of the <code>alias</code> rule is to change build properties. |
| For example, if you want to use link statically to the Boost Threads |
| library, you can write the following: |
| <programlisting> |
| alias threads : /boost/thread//boost_thread : <link>static ; |
| </programlisting> |
| and use only the <code>threads</code> alias in your Jamfiles. |
| </para> |
| |
| <para> |
| You can also specify usage requirements for the <code>alias</code> target. |
| If you write the following: |
| <programlisting> |
| alias header_only_library : : : : <include>/usr/include/header_only_library ; |
| </programlisting> |
| then using <code>header_only_library</code> in sources will only add an |
| include path. Also note that when an alias has sources, their usage |
| requirements are propagated as well. For example: |
| <programlisting> |
| lib library1 : library1.cpp : : : <include>/library/include1 ; |
| lib library2 : library2.cpp : : : <include>/library/include2 ; |
| alias static_libraries : library1 library2 : <link>static ; |
| exe main : main.cpp static_libraries ; |
| </programlisting> |
| will compile <filename>main.cpp</filename> with additional includes |
| required for using the specified static libraries. |
| </para> |
| </section> |
| |
| <section id="bbv2.tasks.installing"> |
| <title>Installing</title> |
| |
| <para> |
| This section describes various ways to install built target and arbitrary |
| files. |
| </para> |
| |
| <bridgehead>Basic install</bridgehead> |
| |
| <para> |
| For installing a built target you should use the <code>install</code> |
| rule, which follows the <link linkend="bbv2.main-target-rule-syntax"> |
| common syntax</link>. For example: |
| <programlisting> |
| install dist : hello helpers ; |
| </programlisting> |
| will cause the targets <code>hello</code> and <code>helpers</code> to be |
| moved to the <filename>dist</filename> directory, relative to the |
| Jamfile's directory. The directory can be changed using the |
| <code>location</code> property: |
| <programlisting> |
| install dist : hello helpers : <location>/usr/bin ; |
| </programlisting> |
| While you can achieve the same effect by changing the target name to |
| <filename>/usr/bin</filename>, using the <code>location</code> property is |
| better as it allows you to use a mnemonic target name. |
| </para> |
| |
| <para> |
| The <code>location</code> property is especially handy when the location |
| is not fixed, but depends on the build variant or environment variables: |
| <programlisting> |
| install dist : hello helpers : |
| <variant>release:<location>dist/release |
| <variant>debug:<location>dist/debug ; |
| install dist2 : hello helpers : <location>$(DIST) ; |
| </programlisting> |
| See also <link linkend="bbv2.reference.variants.propcond">conditional |
| properties</link> and <link linkend="bbv2.faq.envar">environment |
| variables</link> |
| </para> |
| |
| <bridgehead>Installing with all dependencies</bridgehead> |
| |
| <para> |
| Specifying the names of all libraries to install can be boring. The |
| <code>install</code> allows you to specify only the top-level executable |
| targets to install, and automatically install all dependencies: |
| <programlisting> |
| install dist : hello |
| : <install-dependencies>on <install-type>EXE |
| <install-type>LIB |
| ; |
| </programlisting> |
| will find all targets that <code>hello</code> depends on, and install all |
| of those which are either executables or libraries. More specifically, for |
| each target, other targets that were specified as sources or as dependency |
| properties, will be recursively found. One exception is that targets |
| referred with the <link linkend="bbv2.builtin.features.use"> |
| <code>use</code></link> feature are not considered, as that feature is |
| typically used to refer to header-only libraries. If the set of target |
| types is specified, only targets of that type will be installed, |
| otherwise, all found target will be installed. |
| </para> |
| |
| <bridgehead>Preserving Directory Hierarchy</bridgehead> |
| |
| <indexterm><primary>install-source-root</primary></indexterm> |
| |
| <para> |
| By default, the <code>install</code> rule will strip paths from its |
| sources. So, if sources include <filename>a/b/c.hpp</filename>, the |
| <filename>a/b</filename> part will be ignored. To make the |
| <code>install</code> rule preserve the directory hierarchy you need to |
| use the <literal><install-source-root></literal> feature to specify |
| the root of the hierarchy you are installing. Relative paths from that |
| root will be preserved. For example, if you write: |
| <programlisting> |
| install headers |
| : a/b/c.h |
| : <location>/tmp <install-source-root>a |
| ; |
| </programlisting> |
| the a file named <filename>/tmp/b/c.h</filename> will be created. |
| </para> |
| |
| <para> |
| The <link linkend="bbv2.reference.glob-tree">glob-tree</link> rule can be |
| used to find all files below a given directory, making it easy to install |
| an entire directory tree. |
| </para> |
| |
| <bridgehead>Installing into Several Directories</bridgehead> |
| |
| <para> |
| The <link linkend="bbv2.tasks.alias"><code>alias</code></link> rule can be |
| used when targets need to be installed into several directories: |
| <programlisting> |
| alias install : install-bin install-lib ; |
| install install-bin : applications : /usr/bin ; |
| install install-lib : helper : /usr/lib ; |
| </programlisting> |
| </para> |
| |
| <para> |
| Because the <code>install</code> rule just copies targets, most free |
| features <footnote><para>see the definition of "free" in <xref |
| linkend="bbv2.reference.features.attributes"/>.</para></footnote> have no |
| effect when used in requirements of the <code>install</code> rule. The |
| only two that matter are <link linkend="bbv2.builtin.features.dependency"> |
| <varname>dependency</varname></link> and, on Unix, <link |
| linkend="bbv2.reference.features.dll-path"><varname>dll-path</varname> |
| </link>. |
| </para> |
| |
| <note> |
| <para> |
| (Unix specific) On Unix, executables built using Boost.Build typically |
| contain the list of paths to all used shared libraries. For installing, |
| this is not desired, so Boost.Build relinks the executable with an empty |
| list of paths. You can also specify additional paths for installed |
| executables using the <varname>dll-path</varname> feature. |
| </para> |
| </note> |
| </section> |
| |
| <section id="bbv2.builtins.testing"> |
| <title>Testing</title> |
| |
| <para> |
| Boost.Build has convenient support for running unit tests. The simplest |
| way is the <code>unit-test</code> rule, which follows the <link |
| linkend="bbv2.main-target-rule-syntax">common syntax</link>. For example: |
| <programlisting> |
| unit-test helpers_test : helpers_test.cpp helpers ; |
| </programlisting> |
| </para> |
| |
| <para> |
| The <functionname>unit-test</functionname> rule behaves like the |
| <functionname>exe</functionname> rule, but after the executable is created |
| it is also run. If the executable returns an error code, the build system |
| will also return an error and will try running the executable on the next |
| invocation until it runs successfully. This behaviour ensures that you can |
| not miss a unit test failure. |
| </para> |
| |
| <para> |
| By default, the executable is run directly. Sometimes, it is desirable to |
| run the executable using some helper command. You should use the <literal> |
| testing.launcher</literal> property to specify the name of the helper |
| command. For example, if you write: |
| <programlisting> |
| unit-test helpers_test |
| : helpers_test.cpp helpers |
| : <emphasis role="bold"><testing.launcher>valgrind</emphasis> |
| ; |
| </programlisting> |
| The command used to run the executable will be: |
| <screen> |
| <emphasis role="bold">valgrind</emphasis> bin/$toolset/debug/helpers_test |
| </screen> |
| </para> |
| |
| <para> |
| There are few specialized testing rules, listed below: |
| <programlisting> |
| rule compile ( sources : requirements * : target-name ? ) |
| rule compile-fail ( sources : requirements * : target-name ? ) |
| rule link ( sources + : requirements * : target-name ? ) |
| rule link-fail ( sources + : requirements * : target-name ? ) |
| </programlisting> |
| They are given a list of sources and requirements. If the target name is |
| not provided, the name of the first source file is used instead. The |
| <literal>compile*</literal> tests try to compile the passed source. The |
| <literal>link*</literal> rules try to compile and link an application from |
| all the passed sources. The <literal>compile</literal> and <literal>link |
| </literal> rules expect that compilation/linking succeeds. The <literal> |
| compile-fail</literal> and <literal>link-fail</literal> rules expect that |
| the compilation/linking fails. |
| </para> |
| |
| <para> |
| There are two specialized rules for running applications, which are more |
| powerful than the <code>unit-test</code> rule. The <code>run</code> rule |
| has the following signature: |
| <programlisting> |
| rule run ( sources + : args * : input-files * : requirements * : target-name ? |
| : default-build * ) |
| </programlisting> |
| The rule builds application from the provided sources and runs it, passing |
| <varname>args</varname> and <varname>input-files</varname> as command-line |
| arguments. The <varname>args</varname> parameter is passed verbatim and |
| the values of the <varname>input-files</varname> parameter are treated as |
| paths relative to containing Jamfile, and are adjusted if <command>bjam |
| </command> is invoked from a different directory. The |
| <code>run-fail</code> rule is identical to the <code>run</code> rule, |
| except that it expects that the run fails. |
| </para> |
| |
| <para> |
| All rules described in this section, if executed successfully, create a |
| special manifest file to indicate that the test passed. For the |
| <code>unit-test</code> rule the files is named <filename><replaceable> |
| target-name</replaceable>.passed</filename> and for the other rules it is |
| called <filename><replaceable>target-name</replaceable>.test</filename>. |
| The <code>run*</code> rules also capture all output from the program, and |
| store it in a file named <filename><replaceable> |
| target-name</replaceable>.output</filename>. |
| </para> |
| |
| <para> |
| <indexterm><primary>preserve-test-targets</primary></indexterm> |
| If the <literal>preserve-test-targets</literal> feature has the value |
| <literal>off</literal>, then <code>run</code> and the <code>run-fail</code> |
| rules will remove the executable after running it. This somewhat decreases |
| disk space requirements for continuous testing environments. The default |
| value of <literal>preserve-test-targets</literal> feature is <literal>on</literal>. |
| </para> |
| |
| <para> |
| It is possible to print the list of all test targets (except for |
| <code>unit-test</code>) declared in your project, by passing the <literal> |
| --dump-tests</literal> command-line option. The output will consist of |
| lines of the form: |
| <screen> |
| boost-test(<replaceable>test-type</replaceable>) <replaceable>path</replaceable> : <replaceable>sources</replaceable> |
| </screen> |
| </para> |
| |
| <para> |
| It is possible to process the list of tests, the output of bjam during |
| command run, and the presense/absense of the <filename>*.test</filename> |
| files created when test passes into human-readable status table of tests. |
| Such processing utilities are not included in Boost.Build. |
| </para> |
| </section> |
| |
| <section id="bbv2.builtins.raw"> |
| <title>Custom commands</title> |
| |
| <para> |
| When you use most of main target rules, Boost.Build automatically figures |
| what commands to run and it what order. As soon as you want to use new |
| file types or support new tools, one approach is to extend Boost.Build to |
| smoothly support them, as documented in <xref linkend="bbv2.extender"/>. |
| However, if there is only a single place where the new tool is used, it |
| might be easier to just explicitly specify the commands to run. |
| </para> |
| |
| <para> |
| <!-- This paragraph requires links to where the terms 'virtual target' & |
| 'target' are defined. --> |
| Three main target rules can be used for that. The <functionname>make |
| </functionname> rule allows you to construct a single file from any number |
| of source file, by running a command you specify. The <functionname> |
| notfile</functionname> rule allows you to run an arbitrary command, |
| without creating any files. And finaly, the <functionname>generate |
| </functionname> rule allows you to describe transformation using |
| Boost.Build's virtual targets. This is higher-level than file names that |
| the <functionname>make</functionname> rule operates with and allows you to |
| create more than one target, create differently named targets depending on |
| properties or use more than one tool. |
| </para> |
| |
| <para> |
| The <functionname>make</functionname> rule is used when you want to create |
| one file from a number of sources using some specific command. The |
| <functionname>notfile</functionname> is used to unconditionally run a |
| command. |
| </para> |
| |
| <!-- We need to specify somewhere that the user can get rules like make, |
| notfile & generate defined in his Jamfiles by importing an appropriate |
| Boost.Build module. Also, each of those rules should get a separate |
| documentation page explicitly listing which module needs to be imported for |
| them to become accessible. --> |
| |
| <para> |
| Suppose you want to create file <filename>file.out</filename> from file |
| <filename>file.in</filename> by running command <command> |
| in2out</command>. Here is how you would do this in Boost.Build: |
| <programlisting> |
| make file.out : file.in : @in2out ; |
| actions in2out |
| { |
| in2out $(<) $(>) |
| } |
| </programlisting> |
| If you run <command>bjam</command> and <filename>file.out</filename> does |
| not exist, Boost.Build will run the <command>in2out</command> command to |
| create that file. For more details on specifying actions, see <xref |
| linkend="bbv2.overview.jam_language.actions"/>. |
| </para> |
| |
| <para> |
| It could be that you just want to run some command unconditionally, and |
| that command does not create any specific files. For that you can use the |
| <functionname>notfile</functionname> rule. For example: |
| <programlisting> |
| notfile echo_something : @echo ; |
| actions echo |
| { |
| echo "something" |
| } |
| </programlisting> |
| The only difference from the <functionname>make</functionname> rule is |
| that the name of the target is not considered a name of a file, so |
| Boost.Build will unconditionally run the action. |
| </para> |
| |
| <para> |
| <!-- This paragraph requires links to where terms like 'virtual target', |
| 'target', 'project-target' & 'property-set' are defined. --> |
| The <functionname>generate</functionname> rule is used when you want to |
| express transformations using Boost.Build's virtual targets, as opposed to |
| just filenames. The <functionname>generate</functionname> rule has the |
| standard main target rule signature, but you are required to specify the |
| <literal>generating-rule</literal> property. The value of the property |
| should be in the form <literal> |
| @<replaceable>rule-name</replaceable></literal>, the named rule should |
| have the following signature: |
| <programlisting> |
| rule generating-rule ( project name : property-set : sources * ) |
| </programlisting> |
| and will be called with an instance of the <code>project-target</code> |
| class, the name of the main target, an instance of the |
| <code>property-set</code> class containing build properties, and the list |
| of instances of the <code>virtual-target</code> class corresponding to |
| sources. The rule must return a list of <code>virtual-target</code> |
| instances. The interface of the <code>virtual-target</code> class can be |
| learned by looking at the <filename>build/virtual-target.jam</filename> |
| file. The <filename>generate</filename> example contained in the |
| Boost.Build distribution illustrates how the <literal>generate</literal> |
| rule can be used. |
| </para> |
| </section> |
| |
| <section id="bbv2.reference.precompiled_headers"> |
| <title>Precompiled Headers</title> |
| |
| <para> |
| Precompiled headers is a mechanism to speed up compilation by creating a |
| partially processed version of some header files, and then using that |
| version during compilations rather then repeatedly parsing the original |
| headers. Boost.Build supports precompiled headers with gcc and msvc |
| toolsets. |
| </para> |
| |
| <para> |
| To use precompiled headers, follow the following steps: |
| </para> |
| |
| <orderedlist> |
| <listitem> |
| <para> |
| Create a header that includes headers used by your project that you |
| want precompiled. It is better to include only headers that are |
| sufficiently stable — like headers from the compiler and |
| external libraries. Please wrap the header in <code>#ifdef |
| BOOST_BUILD_PCH_ENABLED</code>, so that the potentially expensive |
| inclusion of headers is not done when PCH is not enabled. Include the |
| new header at the top of your source files. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Declare a new Boost.Build target for the precompiled header and add |
| that precompiled header to the sources of the target whose compilation |
| you want to speed up: |
| <programlisting> |
| cpp-pch pch : pch.hpp ; |
| exe main : main.cpp pch ; |
| </programlisting> |
| You can use the <functionname>c-pch</functionname> rule if you want to |
| use the precompiled header in C programs. |
| </para></listitem> |
| </orderedlist> |
| |
| <para> |
| The <filename>pch</filename> example in Boost.Build distribution can be |
| used as reference. |
| </para> |
| |
| <para> |
| Please note the following: |
| </para> |
| |
| <itemizedlist> |
| <listitem> |
| <para> |
| The inclusion of the precompiled header must be the first thing in a |
| source file, before any code or preprocessor directives. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| The build properties used to compile the source files and the |
| precompiled header must be the same. Consider using project |
| requirements to assure this. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Precompiled headers must be used purely as a way to improve |
| compilation time, not to save the number of <code>#include</code> |
| statements. If a source file needs to include some header, explicitly |
| include it in the source file, even if the same header is included |
| from the precompiled header. This makes sure that your project will |
| build even if precompiled headers are not supported. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| On the gcc compiler, the name of the header being precompiled must be |
| equal to the name of the <code>cpp-pch</code> target. This is a gcc |
| requirement. |
| </para> |
| </listitem> |
| |
| <listitem> |
| <para> |
| Prior to version 4.2, the gcc compiler did not allow anonymous |
| namespaces in precompiled headers, which limits their utility. See the |
| <ulink url="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=29085"> bug |
| report</ulink> for details. |
| </para> |
| </listitem> |
| </itemizedlist> |
| </section> |
| |
| <section id="bbv2.reference.generated_headers"> |
| <title>Generated headers</title> |
| |
| <para> |
| Usually, Boost.Build handles implicit dependendies completely |
| automatically. For example, for C++ files, all <literal>#include</literal> |
| statements are found and handled. The only aspect where user help might be |
| needed is implicit dependency on generated files. |
| </para> |
| |
| <para> |
| By default, Boost.Build handles such dependencies within one main target. |
| For example, assume that main target "app" has two sources, "app.cpp" and |
| "parser.y". The latter source is converted into "parser.c" and "parser.h". |
| Then, if "app.cpp" includes "parser.h", Boost.Build will detect this |
| dependency. Moreover, since "parser.h" will be generated into a build |
| directory, the path to that directory will automatically added to include |
| path. |
| </para> |
| |
| <para> |
| Making this mechanism work across main target boundaries is possible, but |
| imposes certain overhead. For that reason, if there is implicit dependency |
| on files from other main targets, the <literal><implicit-dependency> |
| </literal> [ link ] feature must be used, for example: |
| <programlisting> |
| lib parser : parser.y ; |
| exe app : app.cpp : <implicit-dependency>parser ; |
| </programlisting> |
| The above example tells the build system that when scanning all sources of |
| "app" for implicit-dependencies, it should consider targets from "parser" |
| as potential dependencies. |
| </para> |
| </section> |
| |
| <section id="bbv2.tasks.crosscompile"> |
| <title>Cross-compilation</title> |
| |
| <indexterm><primary>cross compilation</primary></indexterm> |
| |
| <para>Boost.Build supports cross compilation with the gcc and msvc |
| toolsets.</para> |
| |
| <para> |
| When using gcc, you first need to specify your cross compiler |
| in <filename>user-config.jam</filename> (see <xref linkend="bbv2.overview.configuration"/>), |
| for example:</para> |
| <programlisting> |
| using gcc : arm : arm-none-linux-gnueabi-g++ ; |
| </programlisting> |
| <para> |
| After that, if the host and target os are the same, for example Linux, you can |
| just request that this compiler version to be used: |
| </para> |
| <screen> |
| bjam toolset=gcc-arm |
| </screen> |
| |
| <para> |
| If you want to target different operating system from the host, you need |
| to additionally specify the value for the <code>target-os</code> feature, for |
| example: |
| </para> |
| <screen> |
| # On windows box |
| bjam toolset=gcc-arm <emphasis role="bold">target-os=linux</emphasis> |
| # On Linux box |
| bjam toolset=gcc-mingw <emphasis role="bold">target-os=windows</emphasis> |
| </screen> |
| <para> |
| For the complete list of allowed opeating system names, please see the documentation for |
| <link linkend="bbv2.reference.features.target-os">target-os feature</link>. |
| </para> |
| |
| <para> |
| When using the msvc compiler, it's only possible to cross-compiler to a 64-bit system |
| on a 32-bit host. Please see <xref linkend="v2.reference.tools.compiler.msvc.64"/> for |
| details. |
| </para> |
| |
| </section> |
| |
| </chapter> |
| |
| <!-- |
| Local Variables: |
| mode: nxml |
| sgml-indent-data: t |
| sgml-parent-document: ("userman.xml" "chapter") |
| sgml-set-face: t |
| End: |
| --> |