]>
Commit | Line | Data |
---|---|---|
1 | <?xml version="1.0" encoding="UTF-8"?> | |
2 | <!DOCTYPE chapter PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" | |
3 | "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> | |
4 | ||
5 | <!-- Copyright 2006 Vladimir Prus --> | |
6 | <!-- Distributed under the Boost Software License, Version 1.0. --> | |
7 | <!-- (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt) --> | |
8 | ||
9 | <chapter id="bbv2.tasks"> | |
10 | <title>Common tasks</title> | |
11 | ||
12 | <para> | |
13 | This section describes main targets types that Boost.Build supports | |
14 | out-of-the-box. Unless otherwise noted, all mentioned main target rules have | |
15 | the common signature, described in <xref linkend="bbv2.overview.targets"/>. | |
16 | </para> | |
17 | ||
18 | <section id="bbv2.tasks.programs"> | |
19 | <title>Programs</title> | |
20 | ||
21 | <indexterm><primary>exe</primary></indexterm> | |
22 | <para> | |
23 | Programs are created using the <code>exe</code> rule, which follows the | |
24 | <link linkend="bbv2.main-target-rule-syntax">common syntax</link>. For | |
25 | example: | |
26 | <programlisting> | |
27 | exe hello : hello.cpp some_library.lib /some_project//library | |
28 | : <threading>multi | |
29 | ; | |
30 | </programlisting> | |
31 | This will create an executable file from the sources—in this case, one | |
32 | C++ file, one library file present in the same directory, and another | |
33 | library that is created by Boost.Build. Generally, sources can include C | |
34 | and C++ files, object files and libraries. Boost.Build will automatically | |
35 | try to convert targets of other types. | |
36 | </para> | |
37 | ||
38 | <tip> | |
39 | <para> | |
40 | On Windows, if an application uses shared libraries, and both the | |
41 | application and the libraries are built using Boost.Build, it is not | |
42 | possible to immediately run the application, because the <literal>PATH | |
43 | </literal> environment variable should include the path to the | |
44 | libraries. It means you have to either add the paths manually, or have | |
45 | the build place the application and the libraries into the same | |
46 | directory. See <xref linkend="bbv2.tasks.installing"/>. | |
47 | </para> | |
48 | <!-- We should be emphasizing the use of the built-in testing rules | |
49 | rather than continually discussing these quirks of running programs | |
50 | with shared libraries. --> | |
51 | </tip> | |
52 | </section> | |
53 | ||
54 | <section id="bbv2.tasks.libraries"> | |
55 | <title>Libraries</title> | |
56 | ||
57 | <indexterm> | |
58 | <primary>library</primary> | |
59 | <secondary>target</secondary> | |
60 | </indexterm> | |
61 | ||
62 | <para> | |
63 | Library targets are created using the <code>lib</code> rule, which | |
64 | follows the <link linkend="bbv2.main-target-rule-syntax">common syntax | |
65 | </link>. For example: | |
66 | <programlisting> | |
67 | lib helpers : helpers.cpp ; | |
68 | </programlisting> | |
69 | This will define a library target named <code>helpers</code> built from | |
70 | the <code>helpers.cpp</code> source file. | |
71 | It can be either a static library or a shared library, | |
72 | depending on the value of the <link linkend="bbv2.overview.builtins.features.link"><link></link> feature. | |
73 | </para> | |
74 | <para> | |
75 | Library targets can represent: | |
76 | <itemizedlist> | |
77 | <listitem> | |
78 | <para> | |
79 | Libraries that should be built from source, | |
80 | as in the example above. | |
81 | </para> | |
82 | </listitem> | |
83 | <listitem> | |
84 | <para> | |
85 | Prebuilt libraries which already exist on the system. | |
86 | Such libraries can be searched for by the tools using them (typically | |
87 | with the linker's <option>-l</option> option) or their paths can be | |
88 | known in advance by the build system. | |
89 | </para> | |
90 | </listitem> | |
91 | </itemizedlist> | |
92 | </para> | |
93 | ||
94 | <para> | |
95 | The syntax for prebuilt libraries is given below: | |
96 | <programlisting> | |
97 | lib z : : <name>z <search>/home/ghost ; | |
98 | lib compress : : <file>/opt/libs/compress.a ; | |
99 | </programlisting> | |
100 | The <code>name</code> property specifies the name of the library | |
101 | without the standard prefixes and suffixes. For example, depending | |
102 | on the system, <code>z</code> could refer to a file called | |
103 | z.so, libz.a, or z.lib, etc. The <code>search</code> feature | |
104 | specifies paths in which to search for the library in addition | |
105 | to the default compiler paths. <code>search</code> can be specified | |
106 | several times or it can be omitted, in which case only the default | |
107 | compiler paths will be searched. The <code>file</code> property | |
108 | specifies the file location. | |
109 | </para> | |
110 | ||
111 | <para> | |
112 | The difference between using the <code>file</code> feature and | |
113 | using a combination of the <code>name</code> and <code>search</code> | |
114 | features is that <code>file</code> is more precise. | |
115 | ||
116 | <warning> | |
117 | <para> | |
118 | The value of the <code>search</code> feature is just added to the | |
119 | linker search path. When linking to multiple libraries, | |
120 | the paths specified by <code>search</code> are combined without | |
121 | regard to which <code>lib</code> target each path came from. | |
122 | Thus, given | |
123 | <programlisting> | |
124 | lib a : : <name>a <search>/pool/release ; | |
125 | lib b : : <name>b <search>/pool/debug ; | |
126 | </programlisting> | |
127 | If /pool/release/a.so, /pool/release/b.so, /pool/debug/a.so, | |
128 | and /pool/release/b.so all exist, the linker will probably | |
129 | take both <code>a</code> and <code>b</code> from the same | |
130 | directory, instead of finding <code>a</code> in /pool/release | |
131 | and <code>b</code> in /pool/debug. If you need to distinguish | |
132 | between multiple libraries with the same name, it's safer | |
133 | to use <code>file</code>. | |
134 | </para> | |
135 | </warning> | |
136 | </para> | |
137 | ||
138 | <para> | |
139 | For convenience, the following syntax is allowed: | |
140 | <programlisting> | |
141 | lib z ; | |
142 | lib gui db aux ; | |
143 | </programlisting> | |
144 | which has exactly the same effect as: | |
145 | <programlisting> | |
146 | lib z : : <name>z ; | |
147 | lib gui : : <name>gui ; | |
148 | lib db : : <name>db ; | |
149 | lib aux : : <name>aux ; | |
150 | </programlisting> | |
151 | </para> | |
152 | ||
153 | <para> | |
154 | When a library references another library you should put that other | |
155 | library in its list of sources. This will do the right thing in all cases. | |
156 | <!--Add a link to the notes below. --> For portability, you should specify | |
157 | library dependencies even for searched and prebuilt libraries, othewise, | |
158 | static linking on Unix will not work. For example: | |
159 | <programlisting> | |
160 | lib z ; | |
161 | lib png : z : <name>png ; | |
162 | </programlisting> | |
163 | </para> | |
164 | ||
165 | <note> | |
166 | <para> | |
167 | When a library has a shared library as a source, or a static | |
168 | library has another static library as a source then any target | |
169 | linking to the first library with automatically link to its source | |
170 | library as well. | |
171 | </para> | |
172 | <para> | |
173 | On the other hand, when a shared library has a static library as | |
174 | a source then the first library will be built so that it completely | |
175 | includes the second one. | |
176 | </para> | |
177 | <para> | |
178 | If you do not want a shared library to include all the libraries specified | |
179 | in its sources (especially statically linked ones), you would need to | |
180 | use the following: | |
181 | <programlisting> | |
182 | lib b : a.cpp ; | |
183 | lib a : a.cpp : <use>b : : <library>b ; | |
184 | </programlisting> | |
185 | This specifies that library <code>a</code> uses library <code>b</code>, | |
186 | and causes all executables that link to <code>a</code> to link to | |
187 | <code>b</code> also. In this case, even for shared linking, the | |
188 | <code>a</code> library will not refer to <code>b</code>. | |
189 | </para> | |
190 | </note> | |
191 | ||
192 | <para> | |
193 | <!-- FIXME: After adding a full subsection on usage requirements, link to it --> | |
194 | <link linkend="bbv2.overview.targets">Usage requirements</link> are often | |
195 | very useful for defining library targets. For example, imagine that | |
196 | you want you build a <code>helpers</code> library and its interface is | |
197 | described in its <code>helpers.hpp</code> header file located in the same | |
198 | directory as the <code>helpers.cpp</code> source file. Then you could add | |
199 | the following to the Jamfile located in that same directory: | |
200 | <programlisting> | |
201 | lib helpers : helpers.cpp : : : <include>. ; | |
202 | </programlisting> | |
203 | which would automatically add the directory where the target has been | |
204 | defined (and where the library's header file is located) to the compiler's | |
205 | include path for all targets using the <code>helpers</code> library. This | |
206 | feature greatly simplifies Jamfiles. | |
207 | </para> | |
208 | </section> | |
209 | ||
210 | <section id="bbv2.tasks.alias"> | |
211 | <title>Alias</title> | |
212 | ||
213 | <para> | |
214 | The <code language="jam">alias</code> rule gives an alternative name to a | |
215 | group of targets. For example, to give the name <filename>core</filename> | |
216 | to a group of three other targets with the following code: | |
217 | <programlisting> | |
218 | alias core : im reader writer ; | |
219 | </programlisting> | |
220 | Using <filename>core</filename> on the command line, or in the source list | |
221 | of any other target is the same as explicitly using <filename>im | |
222 | </filename>, <filename>reader</filename>, and <filename>writer</filename>. | |
223 | </para> | |
224 | ||
225 | <para> | |
226 | Another use of the <code>alias</code> rule is to change build properties. | |
227 | For example, if you want to use link statically to the Boost Threads | |
228 | library, you can write the following: | |
229 | <programlisting> | |
230 | alias threads : /boost/thread//boost_thread : <link>static ; | |
231 | </programlisting> | |
232 | and use only the <code>threads</code> alias in your Jamfiles. | |
233 | </para> | |
234 | ||
235 | <para> | |
236 | You can also specify usage requirements for the <code>alias</code> target. | |
237 | If you write the following: | |
238 | <programlisting> | |
239 | alias header_only_library : : : : <include>/usr/include/header_only_library ; | |
240 | </programlisting> | |
241 | then using <code>header_only_library</code> in sources will only add an | |
242 | include path. Also note that when an alias has sources, their usage | |
243 | requirements are propagated as well. For example: | |
244 | <programlisting> | |
245 | lib library1 : library1.cpp : : : <include>/library/include1 ; | |
246 | lib library2 : library2.cpp : : : <include>/library/include2 ; | |
247 | alias static_libraries : library1 library2 : <link>static ; | |
248 | exe main : main.cpp static_libraries ; | |
249 | </programlisting> | |
250 | will compile <filename>main.cpp</filename> with additional includes | |
251 | required for using the specified static libraries. | |
252 | </para> | |
253 | </section> | |
254 | ||
255 | <section id="bbv2.tasks.installing"> | |
256 | <title>Installing</title> | |
257 | ||
258 | <para> | |
259 | This section describes various ways to install built target and arbitrary | |
260 | files. | |
261 | </para> | |
262 | ||
263 | <bridgehead>Basic install</bridgehead> | |
264 | ||
265 | <para> | |
266 | For installing a built target you should use the <code>install</code> | |
267 | rule, which follows the <link linkend="bbv2.main-target-rule-syntax"> | |
268 | common syntax</link>. For example: | |
269 | <programlisting> | |
270 | install dist : hello helpers ; | |
271 | </programlisting> | |
272 | will cause the targets <code>hello</code> and <code>helpers</code> to be | |
273 | moved to the <filename>dist</filename> directory, relative to the | |
274 | Jamfile's directory. The directory can be changed using the | |
275 | <code>location</code> property: | |
276 | <programlisting> | |
277 | install dist : hello helpers : <location>/usr/bin ; | |
278 | </programlisting> | |
279 | While you can achieve the same effect by changing the target name to | |
280 | <filename>/usr/bin</filename>, using the <code>location</code> property is | |
281 | better as it allows you to use a mnemonic target name. | |
282 | </para> | |
283 | ||
284 | <para> | |
285 | The <code>location</code> property is especially handy when the location | |
286 | is not fixed, but depends on the build variant or environment variables: | |
287 | <programlisting> | |
288 | install dist : hello helpers : | |
289 | <variant>release:<location>dist/release | |
290 | <variant>debug:<location>dist/debug ; | |
291 | install dist2 : hello helpers : <location>$(DIST) ; | |
292 | </programlisting> | |
293 | See also <link linkend="bbv2.reference.variants.propcond">conditional | |
294 | properties</link> and <link linkend="bbv2.faq.envar">environment | |
295 | variables</link> | |
296 | </para> | |
297 | ||
298 | <bridgehead>Installing with all dependencies</bridgehead> | |
299 | ||
300 | <para> | |
301 | Specifying the names of all libraries to install can be boring. The | |
302 | <code>install</code> allows you to specify only the top-level executable | |
303 | targets to install, and automatically install all dependencies: | |
304 | <programlisting> | |
305 | install dist : hello | |
306 | : <install-dependencies>on <install-type>EXE | |
307 | <install-type>LIB | |
308 | ; | |
309 | </programlisting> | |
310 | will find all targets that <code>hello</code> depends on, and install all | |
311 | of those which are either executables or libraries. More specifically, for | |
312 | each target, other targets that were specified as sources or as dependency | |
313 | properties, will be recursively found. One exception is that targets | |
314 | referred with the <link linkend="bbv2.builtin.features.use"> | |
315 | <code>use</code></link> feature are not considered, as that feature is | |
316 | typically used to refer to header-only libraries. If the set of target | |
317 | types is specified, only targets of that type will be installed, | |
318 | otherwise, all found target will be installed. | |
319 | </para> | |
320 | ||
321 | <bridgehead>Preserving Directory Hierarchy</bridgehead> | |
322 | ||
323 | <indexterm><primary>install-source-root</primary></indexterm> | |
324 | ||
325 | <para> | |
326 | By default, the <code>install</code> rule will strip paths from its | |
327 | sources. So, if sources include <filename>a/b/c.hpp</filename>, the | |
328 | <filename>a/b</filename> part will be ignored. To make the | |
329 | <code>install</code> rule preserve the directory hierarchy you need to | |
330 | use the <literal><install-source-root></literal> feature to specify | |
331 | the root of the hierarchy you are installing. Relative paths from that | |
332 | root will be preserved. For example, if you write: | |
333 | <programlisting> | |
334 | install headers | |
335 | : a/b/c.h | |
336 | : <location>/tmp <install-source-root>a | |
337 | ; | |
338 | </programlisting> | |
339 | the a file named <filename>/tmp/b/c.h</filename> will be created. | |
340 | </para> | |
341 | ||
342 | <para> | |
343 | The <link linkend="bbv2.reference.glob-tree">glob-tree</link> rule can be | |
344 | used to find all files below a given directory, making it easy to install | |
345 | an entire directory tree. | |
346 | </para> | |
347 | ||
348 | <bridgehead>Installing into Several Directories</bridgehead> | |
349 | ||
350 | <para> | |
351 | The <link linkend="bbv2.tasks.alias"><code>alias</code></link> rule can be | |
352 | used when targets need to be installed into several directories: | |
353 | <programlisting> | |
354 | alias install : install-bin install-lib ; | |
355 | install install-bin : applications : /usr/bin ; | |
356 | install install-lib : helper : /usr/lib ; | |
357 | </programlisting> | |
358 | </para> | |
359 | ||
360 | <para> | |
361 | Because the <code>install</code> rule just copies targets, most free | |
362 | features <footnote><para>see the definition of "free" in <xref | |
363 | linkend="bbv2.reference.features.attributes"/>.</para></footnote> have no | |
364 | effect when used in requirements of the <code>install</code> rule. The | |
365 | only two that matter are <link linkend="bbv2.builtin.features.dependency"> | |
366 | <varname>dependency</varname></link> and, on Unix, <link | |
367 | linkend="bbv2.reference.features.dll-path"><varname>dll-path</varname> | |
368 | </link>. | |
369 | </para> | |
370 | ||
371 | <note> | |
372 | <para> | |
373 | (Unix specific) On Unix, executables built using Boost.Build typically | |
374 | contain the list of paths to all used shared libraries. For installing, | |
375 | this is not desired, so Boost.Build relinks the executable with an empty | |
376 | list of paths. You can also specify additional paths for installed | |
377 | executables using the <varname>dll-path</varname> feature. | |
378 | </para> | |
379 | </note> | |
380 | </section> | |
381 | ||
382 | <section id="bbv2.builtins.testing"> | |
383 | <title>Testing</title> | |
384 | ||
385 | <para> | |
386 | Boost.Build has convenient support for running unit tests. The simplest | |
387 | way is the <code>unit-test</code> rule, which follows the <link | |
388 | linkend="bbv2.main-target-rule-syntax">common syntax</link>. For example: | |
389 | <programlisting> | |
390 | unit-test helpers_test : helpers_test.cpp helpers ; | |
391 | </programlisting> | |
392 | </para> | |
393 | ||
394 | <para> | |
395 | The <code language="jam">unit-test</code> rule behaves like the | |
396 | <link linkend="bbv2.tasks.programs">exe</link> rule, but after the executable is created | |
397 | it is also run. If the executable returns an error code, the build system | |
398 | will also return an error and will try running the executable on the next | |
399 | invocation until it runs successfully. This behaviour ensures that you can | |
400 | not miss a unit test failure. | |
401 | </para> | |
402 | ||
403 | ||
404 | <para> | |
405 | There are few specialized testing rules, listed below: | |
406 | <programlisting> | |
407 | rule compile ( sources : requirements * : target-name ? ) | |
408 | rule compile-fail ( sources : requirements * : target-name ? ) | |
409 | rule link ( sources + : requirements * : target-name ? ) | |
410 | rule link-fail ( sources + : requirements * : target-name ? ) | |
411 | </programlisting> | |
412 | They are given a list of sources and requirements. If the target name is | |
413 | not provided, the name of the first source file is used instead. The | |
414 | <literal>compile*</literal> tests try to compile the passed source. The | |
415 | <literal>link*</literal> rules try to compile and link an application from | |
416 | all the passed sources. The <literal>compile</literal> and <literal>link | |
417 | </literal> rules expect that compilation/linking succeeds. The <literal> | |
418 | compile-fail</literal> and <literal>link-fail</literal> rules expect that | |
419 | the compilation/linking fails. | |
420 | </para> | |
421 | ||
422 | <para> | |
423 | There are two specialized rules for running applications, which are more | |
424 | powerful than the <code>unit-test</code> rule. The <code>run</code> rule | |
425 | has the following signature: | |
426 | <programlisting> | |
427 | rule run ( sources + : args * : input-files * : requirements * : target-name ? | |
428 | : default-build * ) | |
429 | </programlisting> | |
430 | The rule builds application from the provided sources and runs it, passing | |
431 | <varname>args</varname> and <varname>input-files</varname> as command-line | |
432 | arguments. The <varname>args</varname> parameter is passed verbatim and | |
433 | the values of the <varname>input-files</varname> parameter are treated as | |
434 | paths relative to containing Jamfile, and are adjusted if <command>b2</command> | |
435 | is invoked from a different directory. The | |
436 | <code>run-fail</code> rule is identical to the <code>run</code> rule, | |
437 | except that it expects that the run fails. | |
438 | </para> | |
439 | ||
440 | <para> | |
441 | All rules described in this section, if executed successfully, create a | |
442 | special manifest file to indicate that the test passed. For the | |
443 | <code>unit-test</code> rule the files is named <filename><replaceable> | |
444 | target-name</replaceable>.passed</filename> and for the other rules it is | |
445 | called <filename><replaceable>target-name</replaceable>.test</filename>. | |
446 | The <code>run*</code> rules also capture all output from the program, and | |
447 | store it in a file named <filename><replaceable> | |
448 | target-name</replaceable>.output</filename>. | |
449 | </para> | |
450 | ||
451 | <para> | |
452 | <indexterm><primary>preserve-test-targets</primary></indexterm> | |
453 | If the <literal>preserve-test-targets</literal> feature has the value | |
454 | <literal>off</literal>, then <code>run</code> and the <code>run-fail</code> | |
455 | rules will remove the executable after running it. This somewhat decreases | |
456 | disk space requirements for continuous testing environments. The default | |
457 | value of <literal>preserve-test-targets</literal> feature is <literal>on</literal>. | |
458 | </para> | |
459 | ||
460 | <para> | |
461 | It is possible to print the list of all test targets (except for | |
462 | <code>unit-test</code>) declared in your project, by passing the <literal> | |
463 | --dump-tests</literal> command-line option. The output will consist of | |
464 | lines of the form: | |
465 | <screen> | |
466 | boost-test(<replaceable>test-type</replaceable>) <replaceable>path</replaceable> : <replaceable>sources</replaceable> | |
467 | </screen> | |
468 | </para> | |
469 | ||
470 | <para> | |
471 | It is possible to process the list of tests, Boost.Build output | |
472 | and the presense/absense of the <filename>*.test</filename> | |
473 | files created when test passes into human-readable status table of tests. | |
474 | Such processing utilities are not included in Boost.Build. | |
475 | </para> | |
476 | ||
477 | <para>The following features adjust behaviour of the testing metatargets.</para> | |
478 | ||
479 | <variablelist> | |
480 | <varlistentry> | |
481 | <term><literal>testing.arg</literal></term> | |
482 | <indexterm><primary>testing.arg</primary></indexterm> | |
483 | ||
484 | <listitem> | |
485 | <para> | |
486 | Defines an argument to be passed to the target when it is executed | |
487 | before the list of input files. | |
488 | </para> | |
489 | ||
490 | <para> | |
491 | <programlisting> | |
492 | unit-test helpers_test | |
493 | : helpers_test.cpp helpers | |
494 | : <emphasis role="bold"><testing.arg>"--foo bar"</emphasis> | |
495 | ; | |
496 | </programlisting> | |
497 | </para> | |
498 | </listitem> | |
499 | </varlistentry> | |
500 | ||
501 | <varlistentry> | |
502 | <term><literal>testing.input-file</literal></term> | |
503 | <indexterm><primary>testing.input-file</primary></indexterm> | |
504 | ||
505 | <listitem> | |
506 | <para> | |
507 | Specifies a file to be passed to the executable on the command line | |
508 | after the arguments. All files must be specified in alphabetical | |
509 | order due to constrainsts in the current implementation. | |
510 | </para> | |
511 | ||
512 | </listitem> | |
513 | </varlistentry> | |
514 | ||
515 | <varlistentry> | |
516 | <term><literal>testing.launcher</literal></term> | |
517 | <indexterm><primary>testing.launcher</primary></indexterm> | |
518 | ||
519 | <listitem> | |
520 | <para> | |
521 | By default, the executable is run directly. Sometimes, it is | |
522 | desirable to run the executable using some helper command. You | |
523 | should use this property to specify the name of the helper | |
524 | command. For example, if you write: | |
525 | <programlisting> | |
526 | unit-test helpers_test | |
527 | : helpers_test.cpp helpers | |
528 | : <emphasis role="bold"><testing.launcher>valgrind</emphasis> | |
529 | ; | |
530 | </programlisting> | |
531 | The command used to run the executable will be: | |
532 | <screen> | |
533 | <emphasis role="bold">valgrind</emphasis> bin/$toolset/debug/helpers_test | |
534 | </screen> | |
535 | </para> | |
536 | </listitem> | |
537 | </varlistentry> | |
538 | ||
539 | <varlistentry> | |
540 | <term><literal>test-info</literal></term> | |
541 | <indexterm><primary>test-info</primary></indexterm> | |
542 | ||
543 | <listitem> | |
544 | <para> | |
545 | A description of the test. This is displayed as part of the | |
546 | <literal>--dump-tests</literal> command-line option. | |
547 | </para> | |
548 | </listitem> | |
549 | </varlistentry> | |
550 | ||
551 | </variablelist> | |
552 | </section> | |
553 | ||
554 | <section id="bbv2.builtins.raw"> | |
555 | <title>Custom commands</title> | |
556 | ||
557 | <para> | |
558 | For most main target rules, Boost.Build automatically figures out | |
559 | the commands to run. When you want to use new | |
560 | file types or support new tools, one approach is to extend Boost.Build to | |
561 | support them smoothly, as documented in <xref linkend="bbv2.extender"/>. | |
562 | However, if the new tool is only used in a single place, it | |
563 | might be easier just to specify the commands to run explicitly. | |
564 | </para> | |
565 | ||
566 | <para> | |
567 | <!-- This paragraph requires links to where the terms 'virtual target' & | |
568 | 'target' are defined. --> | |
569 | Three main target rules can be used for that. The <code language="jam">make | |
570 | </code> rule allows you to construct a single file from any number | |
571 | of source file, by running a command you specify. The <code language="jam"> | |
572 | notfile</code> rule allows you to run an arbitrary command, | |
573 | without creating any files. And finaly, the <code language="jam">generate | |
574 | </code> rule allows you to describe a transformation using | |
575 | Boost.Build's virtual targets. This is higher-level than the file names that | |
576 | the <code language="jam">make</code> rule operates with and allows you to | |
577 | create more than one target, create differently named targets depending on | |
578 | properties, or use more than one tool. | |
579 | </para> | |
580 | ||
581 | <para> | |
582 | The <code language="jam">make</code> rule is used when you want to create | |
583 | one file from a number of sources using some specific command. The | |
584 | <code language="jam">notfile</code> is used to unconditionally run a | |
585 | command. | |
586 | </para> | |
587 | ||
588 | <!-- We need to specify somewhere that the user can get rules like make, | |
589 | notfile & generate defined in his Jamfiles by importing an appropriate | |
590 | Boost.Build module. Also, each of those rules should get a separate | |
591 | documentation page explicitly listing which module needs to be imported for | |
592 | them to become accessible. --> | |
593 | ||
594 | <para> | |
595 | Suppose you want to create the file <filename>file.out</filename> from | |
596 | the file <filename>file.in</filename> by running the command <command> | |
597 | in2out</command>. Here is how you would do this in Boost.Build: | |
598 | <programlisting> | |
599 | make file.out : file.in : @in2out ; | |
600 | actions in2out | |
601 | { | |
602 | in2out $(<) $(>) | |
603 | } | |
604 | </programlisting> | |
605 | If you run <command>b2</command> and <filename>file.out</filename> does | |
606 | not exist, Boost.Build will run the <command>in2out</command> command to | |
607 | create that file. For more details on specifying actions, see <xref | |
608 | linkend="bbv2.overview.jam_language.actions"/>. | |
609 | </para> | |
610 | ||
611 | <para> | |
612 | It could be that you just want to run some command unconditionally, and | |
613 | that command does not create any specific files. For that you can use the | |
614 | <code language="jam">notfile</code> rule. For example: | |
615 | <programlisting> | |
616 | notfile echo_something : @echo ; | |
617 | actions echo | |
618 | { | |
619 | echo "something" | |
620 | } | |
621 | </programlisting> | |
622 | The only difference from the <code language="jam">make</code> rule is | |
623 | that the name of the target is not considered a name of a file, so | |
624 | Boost.Build will unconditionally run the action. | |
625 | </para> | |
626 | ||
627 | <para> | |
628 | <!-- This paragraph requires links to where terms like 'virtual target', | |
629 | 'target', 'project-target' & 'property-set' are defined. --> | |
630 | The <code language="jam">generate</code> rule is used when you want to | |
631 | express transformations using Boost.Build's virtual targets, as opposed to | |
632 | just filenames. The <code language="jam">generate</code> rule has the | |
633 | standard main target rule signature, but you are required to specify the | |
634 | <literal>generating-rule</literal> property. The value of the property | |
635 | should be in the form <literal> | |
636 | @<replaceable>rule-name</replaceable></literal>, the named rule should | |
637 | have the following signature: | |
638 | <programlisting> | |
639 | rule generating-rule ( project name : property-set : sources * ) | |
640 | </programlisting> | |
641 | and will be called with an instance of the <code>project-target</code> | |
642 | class, the name of the main target, an instance of the | |
643 | <code>property-set</code> class containing build properties, and the list | |
644 | of instances of the <code>virtual-target</code> class corresponding to | |
645 | sources. The rule must return a list of <code>virtual-target</code> | |
646 | instances. The interface of the <code>virtual-target</code> class can be | |
647 | learned by looking at the <filename>build/virtual-target.jam</filename> | |
648 | file. The <filename>generate</filename> example contained in the | |
649 | Boost.Build distribution illustrates how the <literal>generate</literal> | |
650 | rule can be used. | |
651 | </para> | |
652 | </section> | |
653 | ||
654 | <section id="bbv2.reference.precompiled_headers"> | |
655 | <title>Precompiled Headers</title> | |
656 | ||
657 | <para> | |
658 | Precompiled headers is a mechanism to speed up compilation by creating a | |
659 | partially processed version of some header files, and then using that | |
660 | version during compilations rather then repeatedly parsing the original | |
661 | headers. Boost.Build supports precompiled headers with gcc and msvc | |
662 | toolsets. | |
663 | </para> | |
664 | ||
665 | <para> | |
666 | To use precompiled headers, follow the following steps: | |
667 | </para> | |
668 | ||
669 | <orderedlist> | |
670 | <listitem> | |
671 | <para> | |
672 | Create a header that includes headers used by your project that you | |
673 | want precompiled. It is better to include only headers that are | |
674 | sufficiently stable — like headers from the compiler and | |
675 | external libraries. Please wrap the header in <code>#ifdef | |
676 | BOOST_BUILD_PCH_ENABLED</code>, so that the potentially expensive | |
677 | inclusion of headers is not done when PCH is not enabled. Include the | |
678 | new header at the top of your source files. | |
679 | </para> | |
680 | </listitem> | |
681 | ||
682 | <listitem> | |
683 | <para> | |
684 | Declare a new Boost.Build target for the precompiled header and add | |
685 | that precompiled header to the sources of the target whose compilation | |
686 | you want to speed up: | |
687 | <programlisting> | |
688 | cpp-pch pch : pch.hpp ; | |
689 | exe main : main.cpp pch ; | |
690 | </programlisting> | |
691 | You can use the <code language="jam">c-pch</code> rule if you want to | |
692 | use the precompiled header in C programs. | |
693 | </para></listitem> | |
694 | </orderedlist> | |
695 | ||
696 | <para> | |
697 | The <filename>pch</filename> example in Boost.Build distribution can be | |
698 | used as reference. | |
699 | </para> | |
700 | ||
701 | <para> | |
702 | Please note the following: | |
703 | </para> | |
704 | ||
705 | <itemizedlist> | |
706 | <listitem> | |
707 | <para> | |
708 | The inclusion of the precompiled header must be the first thing in a | |
709 | source file, before any code or preprocessor directives. | |
710 | </para> | |
711 | </listitem> | |
712 | ||
713 | <listitem> | |
714 | <para> | |
715 | The build properties used to compile the source files and the | |
716 | precompiled header must be the same. Consider using project | |
717 | requirements to assure this. | |
718 | </para> | |
719 | </listitem> | |
720 | ||
721 | <listitem> | |
722 | <para> | |
723 | Precompiled headers must be used purely as a way to improve | |
724 | compilation time, not to save the number of <code>#include</code> | |
725 | statements. If a source file needs to include some header, explicitly | |
726 | include it in the source file, even if the same header is included | |
727 | from the precompiled header. This makes sure that your project will | |
728 | build even if precompiled headers are not supported. | |
729 | </para> | |
730 | </listitem> | |
731 | ||
732 | <listitem> | |
733 | <para> | |
734 | On the gcc compiler, the name of the header being precompiled must be | |
735 | equal to the name of the <code>cpp-pch</code> target. This is a gcc | |
736 | requirement. | |
737 | </para> | |
738 | </listitem> | |
739 | ||
740 | <listitem> | |
741 | <para> | |
742 | Prior to version 4.2, the gcc compiler did not allow anonymous | |
743 | namespaces in precompiled headers, which limits their utility. See the | |
744 | <ulink url="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=29085"> bug | |
745 | report</ulink> for details. | |
746 | </para> | |
747 | </listitem> | |
748 | </itemizedlist> | |
749 | </section> | |
750 | ||
751 | <section id="bbv2.reference.generated_headers"> | |
752 | <title>Generated headers</title> | |
753 | ||
754 | <para> | |
755 | Usually, Boost.Build handles implicit dependendies completely | |
756 | automatically. For example, for C++ files, all <literal>#include</literal> | |
757 | statements are found and handled. The only aspect where user help might be | |
758 | needed is implicit dependency on generated files. | |
759 | </para> | |
760 | ||
761 | <para> | |
762 | By default, Boost.Build handles such dependencies within one main target. | |
763 | For example, assume that main target "app" has two sources, "app.cpp" and | |
764 | "parser.y". The latter source is converted into "parser.c" and "parser.h". | |
765 | Then, if "app.cpp" includes "parser.h", Boost.Build will detect this | |
766 | dependency. Moreover, since "parser.h" will be generated into a build | |
767 | directory, the path to that directory will automatically be added to the include | |
768 | path. | |
769 | </para> | |
770 | ||
771 | <para> | |
772 | Making this mechanism work across main target boundaries is possible, but | |
773 | imposes certain overhead. For that reason, if there is implicit dependency | |
774 | on files from other main targets, the <literal><implicit-dependency> | |
775 | </literal> feature must be used, for example: | |
776 | <programlisting> | |
777 | lib parser : parser.y ; | |
778 | exe app : app.cpp : <implicit-dependency>parser ; | |
779 | </programlisting> | |
780 | The above example tells the build system that when scanning all sources of | |
781 | "app" for implicit-dependencies, it should consider targets from "parser" | |
782 | as potential dependencies. | |
783 | </para> | |
784 | </section> | |
785 | ||
786 | <section id="bbv2.tasks.crosscompile"> | |
787 | <title>Cross-compilation</title> | |
788 | ||
789 | <indexterm><primary>cross compilation</primary></indexterm> | |
790 | ||
791 | <para>Boost.Build supports cross compilation with the gcc and msvc | |
792 | toolsets.</para> | |
793 | ||
794 | <para> | |
795 | When using gcc, you first need to specify your cross compiler | |
796 | in <filename>user-config.jam</filename> (see <xref linkend="bbv2.overview.configuration"/>), | |
797 | for example:</para> | |
798 | <programlisting> | |
799 | using gcc : arm : arm-none-linux-gnueabi-g++ ; | |
800 | </programlisting> | |
801 | <para> | |
802 | After that, if the host and target os are the same, for example Linux, you can | |
803 | just request that this compiler version be used: | |
804 | </para> | |
805 | <screen> | |
806 | b2 toolset=gcc-arm | |
807 | </screen> | |
808 | ||
809 | <para> | |
810 | If you want to target a different operating system from the host, you need | |
811 | to additionally specify the value for the <code>target-os</code> feature, for | |
812 | example: | |
813 | </para> | |
814 | <screen> | |
815 | # On windows box | |
816 | b2 toolset=gcc-arm <emphasis role="bold">target-os=linux</emphasis> | |
817 | # On Linux box | |
818 | b2 toolset=gcc-mingw <emphasis role="bold">target-os=windows</emphasis> | |
819 | </screen> | |
820 | <para> | |
821 | For the complete list of allowed opeating system names, please see the documentation for | |
822 | <link linkend="bbv2.reference.features.target-os">target-os feature</link>. | |
823 | </para> | |
824 | ||
825 | <para> | |
826 | When using the msvc compiler, it's only possible to cross-compile to a 64-bit system | |
827 | on a 32-bit host. Please see <xref linkend="v2.reference.tools.compiler.msvc.64"/> for | |
828 | details. | |
829 | </para> | |
830 | ||
831 | </section> | |
832 | ||
833 | </chapter> | |
834 | ||
835 | <!-- | |
836 | Local Variables: | |
837 | mode: nxml | |
838 | sgml-indent-data: t | |
839 | sgml-parent-document: ("userman.xml" "chapter") | |
840 | sgml-set-face: t | |
841 | End: | |
842 | --> |