]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | <!ENTITY toolset_ops "<optional><replaceable>version</replaceable></optional> : <optional><replaceable>c++-compile-command</replaceable></optional> : <optional><replaceable>compiler options</replaceable></optional>"> | |
6 | <!ENTITY option_list_intro "<para>The following options can be provided, using <literal><<replaceable>option-name</replaceable>><replaceable>option-value</replaceable></literal> syntax:</para>"> | |
7 | <!ENTITY using_repeation "<para>This statement may be repeated several times, if you want to configure several versions of the compiler.</para>"> | |
8 | ]> | |
9 | ||
10 | <chapter id="bbv2.reference" | |
11 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
12 | <title>Reference</title> | |
13 | ||
14 | <section id="bbv2.reference.general"> | |
15 | <title>General information</title> | |
16 | ||
17 | <section id="bbv2.reference.init"> | |
18 | <title>Initialization</title> | |
19 | ||
20 | <para> | |
21 | Immediately upon starting, the Boost.Build engine (<command>b2</command>) | |
22 | loads the Jam code that implements the build system. To do this, it searches for a file | |
23 | called <filename>boost-build.jam</filename>, first in the invocation directory, then | |
24 | in its parent and so forth up to the filesystem root, and finally | |
25 | in the directories specified by the environment variable | |
26 | BOOST_BUILD_PATH. When found, the file is interpreted, and should | |
27 | specify the build system location by calling the boost-build | |
28 | rule:</para> | |
29 | ||
30 | <programlisting> | |
31 | rule boost-build ( location ? ) | |
32 | </programlisting> | |
33 | ||
34 | <para> | |
35 | If location is a relative path, it is treated as relative to | |
36 | the directory of <filename>boost-build.jam</filename>. The directory specified by | |
37 | that location and the directories in BOOST_BUILD_PATH are then searched for | |
38 | a file called <filename>bootstrap.jam</filename>, which is expected to | |
39 | bootstrap the build system. This arrangement allows the build | |
40 | system to work without any command-line or environment variable | |
41 | settings. For example, if the build system files were located in a | |
42 | directory "build-system/" at your project root, you might place a | |
43 | <filename>boost-build.jam</filename> at the project root containing: | |
44 | ||
45 | <programlisting> | |
46 | boost-build build-system ; | |
47 | </programlisting> | |
48 | ||
49 | In this case, running <command>b2</command> anywhere in the project tree will | |
50 | automatically find the build system.</para> | |
51 | ||
52 | <para>The default <filename>bootstrap.jam</filename>, after loading some standard | |
53 | definitions, loads both <filename>site-config.jam</filename> and <filename>user-config.jam</filename>.</para> | |
54 | ||
55 | </section> | |
56 | ||
57 | </section> | |
58 | ||
59 | <section id="bbv2.reference.rules"> | |
60 | <title>Builtin rules</title> | |
61 | ||
62 | <para>This section contains the list of all rules that | |
63 | can be used in Jamfile—both rules that define new | |
64 | targets and auxiliary rules.</para> | |
65 | ||
66 | <variablelist> | |
67 | <varlistentry> | |
68 | <term><literal>exe</literal></term> | |
69 | ||
70 | <listitem><para>Creates an executable file. See | |
71 | <xref linkend="bbv2.tasks.programs"/>.</para></listitem> | |
72 | </varlistentry> | |
73 | ||
74 | <varlistentry> | |
75 | <term><literal>lib</literal></term> | |
76 | ||
77 | <listitem><para>Creates an library file. See | |
78 | <xref linkend="bbv2.tasks.libraries"/>.</para></listitem> | |
79 | </varlistentry> | |
80 | ||
81 | <varlistentry> | |
82 | <term><literal>install</literal></term> | |
83 | ||
84 | <listitem><para>Installs built targets and other files. See | |
85 | <xref linkend="bbv2.tasks.installing"/>.</para></listitem> | |
86 | </varlistentry> | |
87 | ||
88 | <varlistentry> | |
89 | <term><literal>alias</literal></term> | |
90 | ||
91 | <listitem><para>Creates an alias for other targets. See | |
92 | <xref linkend="bbv2.tasks.alias"/>.</para></listitem> | |
93 | </varlistentry> | |
94 | ||
95 | <varlistentry> | |
96 | <term><literal>unit-test</literal></term> | |
97 | ||
98 | <listitem><para>Creates an executable that will be automatically run. See | |
99 | <xref linkend="bbv2.builtins.testing"/>.</para></listitem> | |
100 | </varlistentry> | |
101 | ||
102 | <varlistentry> | |
103 | <term><literal>compile</literal></term> | |
104 | <term><literal>compile-fail</literal></term> | |
105 | <term><literal>link</literal></term> | |
106 | <term><literal>link-fail</literal></term> | |
107 | <term><literal>run</literal></term> | |
108 | <term><literal>run-fail</literal></term> | |
109 | ||
110 | <listitem><para>Specialized rules for testing. See | |
111 | <xref linkend="bbv2.builtins.testing"/>.</para></listitem> | |
112 | </varlistentry> | |
113 | ||
114 | <varlistentry id="bbv2.reference.check-target-builds"> | |
115 | <indexterm><primary>check-target-builds</primary></indexterm> | |
116 | <term><literal>check-target-builds</literal></term> | |
117 | ||
118 | <listitem><para>The <literal>check-target-builds</literal> allows you | |
119 | to conditionally use different properties depending on whether some | |
120 | metatarget builds, or not. This is similar to functionality of configure | |
121 | script in autotools projects. The function signature is: | |
122 | </para> | |
123 | <programlisting> | |
124 | rule check-target-builds ( target message ? : true-properties * : false-properties * ) | |
125 | </programlisting> | |
126 | ||
127 | <para>This function can only be used when passing requirements or usage | |
128 | requirements to a metatarget rule. For example, to make an application link | |
129 | to a library if it's available, one has use the following:</para> | |
130 | <programlisting> | |
131 | exe app : app.cpp : [ check-target-builds has_foo "System has foo" : <library>foo : <define>FOO_MISSING=1 ] ; | |
132 | </programlisting> | |
133 | ||
134 | <para>For another example, the alias rule can be used to consolidate configuration | |
135 | choices and make them available to other metatargets, like so:</para> | |
136 | <programlisting> | |
137 | alias foobar : : : : [ check-target-builds has_foo "System has foo" : <library>foo : <library>bar ] ; | |
138 | </programlisting> | |
139 | </listitem> | |
140 | </varlistentry> | |
141 | ||
142 | <varlistentry> | |
143 | <term><literal>obj</literal></term> | |
144 | ||
145 | <listitem><para>Creates an object file. Useful when a single source | |
146 | file must be compiled with special properties.</para></listitem> | |
147 | </varlistentry> | |
148 | ||
149 | <varlistentry> | |
150 | <term><literal>preprocessed</literal></term> | |
151 | <indexterm><primary>preprocessed</primary></indexterm> | |
152 | ||
153 | <listitem><para>Creates an preprocessed source file. The arguments follow the | |
154 | <link linkend="bbv2.main-target-rule-syntax">common syntax</link>.</para></listitem> | |
155 | </varlistentry> | |
156 | ||
157 | <varlistentry id="bbv2.reference.rules.glob"> | |
158 | <term><literal>glob</literal></term> | |
159 | ||
160 | <listitem><para>The <code>glob</code> rule takes a list shell pattern | |
161 | and returns the list of files in the project's source directory that | |
162 | match the pattern. For example: | |
163 | <programlisting> | |
164 | lib tools : [ glob *.cpp ] ; | |
165 | </programlisting> | |
166 | It is possible to also pass a second argument—the list of | |
167 | exclude patterns. The result will then include the list of | |
168 | files matching any of include patterns, and not matching any | |
169 | of the exclude patterns. For example: | |
170 | <programlisting> | |
171 | lib tools : [ glob *.cpp : file_to_exclude.cpp bad*.cpp ] ; | |
172 | </programlisting> | |
173 | </para></listitem> | |
174 | </varlistentry> | |
175 | ||
176 | <varlistentry id="bbv2.reference.glob-tree"> | |
177 | <indexterm><primary>glob-tree</primary></indexterm> | |
178 | <term><literal>glob-tree</literal></term> | |
179 | ||
180 | <listitem><para>The <code>glob-tree</code> is similar to the | |
181 | <code>glob</code> except that it operates recursively from | |
182 | the directory of the containing Jamfile. For example: | |
183 | <programlisting> | |
184 | ECHO [ glob-tree *.cpp : .svn ] ; | |
185 | </programlisting> | |
186 | will print the names of all C++ files in your project. The | |
187 | <literal>.svn</literal> exclude pattern prevents the | |
188 | <code>glob-tree</code> rule from entering administrative | |
189 | directories of the Subversion version control system. | |
190 | </para></listitem> | |
191 | </varlistentry> | |
192 | ||
193 | <varlistentry> | |
194 | <term><literal>project</literal></term> | |
195 | ||
196 | <listitem><para>Declares project id and attributes, including | |
197 | project requirements. See <xref linkend="bbv2.overview.projects"/>. | |
198 | </para></listitem> | |
199 | </varlistentry> | |
200 | ||
201 | <varlistentry> | |
202 | <term><literal>use-project</literal></term> | |
203 | ||
204 | <listitem><para>Assigns a symbolic project ID to a project at | |
205 | a given path. This rule must be better documented! | |
206 | </para></listitem> | |
207 | </varlistentry> | |
208 | ||
209 | <varlistentry id="bbv2.reference.rules.explicit"> | |
210 | <term><literal>explicit</literal></term> | |
211 | ||
212 | <listitem><para>The <literal>explicit</literal> rule takes a single | |
213 | parameter—a list of target names. The named targets will | |
214 | be marked explicit, and will be built only if they are explicitly | |
215 | requested on the command line, or if their dependents are built. | |
216 | Compare this to ordinary targets, that are built implicitly when | |
217 | their containing project is built.</para></listitem> | |
218 | </varlistentry> | |
219 | ||
220 | <varlistentry> | |
221 | <term><literal>always</literal></term> | |
222 | <indexterm><primary>always building a metatarget</primary></indexterm> | |
223 | ||
224 | <listitem><para>The <literal>always</literal> function takes a single | |
225 | parameter—a list of metatarget names. The top-level targets produced | |
226 | by the named metatargets will be always considered out of date. Consider this example: | |
227 | </para> | |
228 | <programlisting> | |
229 | exe hello : hello.cpp ; | |
230 | exe bye : bye.cpp ; | |
231 | always hello ; | |
232 | </programlisting> | |
233 | <para>If a build of <filename>hello</filename> is requested, then the binary will | |
234 | always be relinked. The object files will not be recompiled, though. Note that if | |
235 | a build of <filename>hello</filename> is not requested, for example you specify just | |
236 | <filename>bye</filename> on the command line, <filename>hello</filename> will not | |
237 | be relinked.</para></listitem> | |
238 | </varlistentry> | |
239 | ||
240 | <varlistentry> | |
241 | <term><literal>constant</literal></term> | |
242 | ||
243 | <listitem><para>Sets project-wide constant. Takes two | |
244 | parameters: variable name and a value and makes the specified | |
245 | variable name accessible in this Jamfile and any child Jamfiles. | |
246 | For example: | |
247 | <programlisting> | |
248 | constant VERSION : 1.34.0 ; | |
249 | </programlisting> | |
250 | </para></listitem> | |
251 | </varlistentry> | |
252 | ||
253 | <varlistentry> | |
254 | <term><literal>path-constant</literal></term> | |
255 | ||
256 | <listitem><para>Same as <literal>constant</literal> except that | |
257 | the value is treated as path relative to Jamfile location. For example, | |
258 | if <command>b2</command> is invoked in the current directory, | |
259 | and Jamfile in <filename>helper</filename> subdirectory has: | |
260 | <programlisting> | |
261 | path-constant DATA : data/a.txt ; | |
262 | </programlisting> | |
263 | then the variable <varname>DATA</varname> will be set to | |
264 | <literal>helper/data/a.txt</literal>, and if <command>b2</command> | |
265 | is invoked from the <filename>helper</filename> directory, then | |
266 | the variable <varname>DATA</varname> will be set to | |
267 | <literal>data/a.txt</literal>. | |
268 | </para></listitem> | |
269 | </varlistentry> | |
270 | ||
271 | <varlistentry> | |
272 | <term><literal>build-project</literal></term> | |
273 | ||
274 | <listitem><para>Cause some other project to be built. This rule | |
275 | takes a single parameter—a directory name relative to | |
276 | the containing Jamfile. When the containing Jamfile is built, | |
277 | the project located at that directory will be built as well. | |
278 | At the moment, the parameter to this rule should be a directory | |
279 | name. Project ID or general target references are not allowed. | |
280 | </para></listitem> | |
281 | </varlistentry> | |
282 | ||
283 | <varlistentry> | |
284 | <term><literal>test-suite</literal></term> | |
285 | ||
286 | <listitem><para>This rule is deprecated and equivalent to | |
287 | <code>alias</code>.</para></listitem> | |
288 | </varlistentry> | |
289 | ||
290 | </variablelist> | |
291 | ||
292 | </section> | |
293 | ||
294 | <section id="bbv2.overview.builtins.features"> | |
295 | <title>Builtin features</title> | |
296 | ||
297 | <para>This section documents the features that are built-in into | |
298 | Boost.Build. For features with a fixed set of values, that set is | |
299 | provided, with the default value listed first.</para> | |
300 | ||
301 | <indexterm><primary>features</primary><secondary>builtin</secondary></indexterm> | |
302 | ||
303 | <variablelist> | |
304 | <varlistentry><term><literal>variant</literal></term> | |
305 | <indexterm><primary>variant</primary></indexterm> | |
306 | ||
307 | <listitem> | |
308 | <para> | |
309 | A feature combining several low-level features, making it easy to | |
310 | request common build configurations. | |
311 | </para> | |
312 | ||
313 | <para> | |
314 | <emphasis role="bold">Allowed values:</emphasis> | |
315 | <literal>debug</literal>, <literal>release</literal>, | |
316 | <literal>profile</literal>. | |
317 | </para> | |
318 | ||
319 | <para> | |
320 | The value <literal>debug</literal> expands to | |
321 | </para> | |
322 | ||
323 | <programlisting> | |
324 | <optimization>off <debug-symbols>on <inlining>off <runtime-debugging>on | |
325 | </programlisting> | |
326 | ||
327 | <para> | |
328 | The value <literal>release</literal> expands to | |
329 | </para> | |
330 | ||
331 | <programlisting> | |
332 | <optimization>speed <debug-symbols>off <inlining>full <runtime-debugging>off | |
333 | </programlisting> | |
334 | ||
335 | <para> | |
336 | The value <literal>profile</literal> expands to the same as | |
337 | <literal>release</literal>, plus: | |
338 | </para> | |
339 | ||
340 | <programlisting> | |
341 | <profiling>on <debug-symbols>on | |
342 | </programlisting> | |
343 | ||
344 | <para> | |
345 | Users can define their own build variants using the | |
346 | <code>variant</code> rule from the <code>common</code> module. | |
347 | </para> | |
348 | ||
349 | <para> | |
350 | <emphasis role="bold">Note:</emphasis> Runtime debugging is on in | |
351 | debug builds to suit the expectations of people used to various | |
352 | IDEs. | |
353 | <!-- Define "runtime debugging". Why will those people expect it to | |
354 | be on in debug builds? --> | |
355 | </para> | |
356 | </listitem> | |
357 | </varlistentry> | |
358 | ||
359 | <varlistentry id="bbv2.overview.builtins.features.link"> | |
360 | <term><literal>link</literal></term> | |
361 | <indexterm><primary>link</primary></indexterm> | |
362 | ||
363 | <listitem> | |
364 | ||
365 | <para><emphasis role="bold">Allowed values:</emphasis> <literal>shared</literal>, | |
366 | <literal>static</literal></para> | |
367 | ||
368 | <simpara> | |
369 | A feature controlling how libraries are built. | |
370 | </simpara> | |
371 | ||
372 | </listitem> | |
373 | </varlistentry> | |
374 | ||
375 | <varlistentry id="bbv2.overview.builtins.features.runtime-link"> | |
376 | <indexterm><primary>runtime linking</primary></indexterm> | |
377 | <term><literal>runtime-link</literal></term> | |
378 | ||
379 | <listitem> | |
380 | <para><emphasis role="bold">Allowed values:</emphasis> <literal>shared</literal>, | |
381 | <literal>static</literal></para> | |
382 | ||
383 | <simpara> | |
384 | Controls if a static or shared C/C++ runtime should be used. There | |
385 | are some restrictions how this feature can be used, for example | |
386 | on some compilers an application using static runtime should | |
387 | not use shared libraries at all, and on some compilers, | |
388 | mixing static and shared runtime requires extreme care. Check | |
389 | your compiler documentation for more details. | |
390 | </simpara> | |
391 | ||
392 | </listitem> | |
393 | </varlistentry> | |
394 | ||
395 | <varlistentry> | |
396 | <term><literal>threading</literal></term> | |
397 | <indexterm><primary>threading</primary></indexterm> | |
398 | ||
399 | <listitem> | |
400 | ||
401 | <para><emphasis role="bold">Allowed values:</emphasis> <literal>single</literal>, | |
402 | <literal>multi</literal></para> | |
403 | ||
404 | <simpara> | |
405 | Controls if the project should be built in multi-threaded mode. This feature does not | |
406 | necessary change code generation in the compiler, but it causes the compiler to link | |
407 | to additional or different runtime libraries, and define additional preprocessor | |
408 | symbols (for example, <code>_MT</code> on Windows and <code>_REENTRANT</code> on Linux). | |
409 | How those symbols affect the compiled code depends on the code itself. | |
410 | </simpara> | |
411 | ||
412 | </listitem> | |
413 | </varlistentry> | |
414 | ||
415 | <varlistentry> | |
416 | <term><literal>source</literal></term> | |
417 | <indexterm><primary>source</primary></indexterm> | |
418 | ||
419 | <listitem> | |
420 | <simpara> | |
421 | The <code><source>X</code> feature has the same effect on | |
422 | building a target as putting X in the list of sources. It is useful | |
423 | when you want to add the same source to all targets in the project | |
424 | (you can put <source> in requirements) or to conditionally | |
425 | include a source (using conditional requirements, see <xref linkend= | |
426 | "bbv2.tutorial.conditions"/>). See also the <code><library> | |
427 | </code> feature. | |
428 | </simpara> | |
429 | </listitem> | |
430 | </varlistentry> | |
431 | ||
432 | <varlistentry> | |
433 | <term><literal>library</literal></term> | |
434 | <indexterm><primary>library</primary></indexterm> | |
435 | ||
436 | <listitem> | |
437 | <simpara> | |
438 | This feature is almost equivalent to the <code><source></code> | |
439 | feature, except that it takes effect only for linking. When you want | |
440 | to link all targets in a Jamfile to certain library, the | |
441 | <code><library></code> feature is preferred over | |
442 | <code><source>X</code>—the latter will add the library to | |
443 | all targets, even those that have nothing to do with libraries. | |
444 | </simpara> | |
445 | </listitem> | |
446 | </varlistentry> | |
447 | ||
448 | <varlistentry><term><anchor id="bbv2.builtin.features.dependency"/> | |
449 | <literal>dependency</literal></term> | |
450 | <indexterm><primary>dependency</primary></indexterm> | |
451 | ||
452 | <listitem> | |
453 | <simpara> | |
454 | Introduces a dependency on the target named by the value of this | |
455 | feature (so it will be brought up-to-date whenever the target being | |
456 | declared is). The dependency is not used in any other way. | |
457 | ||
458 | <!-- | |
459 | ==================================================================== | |
460 | An example and a motivation is needed here. Below is some commented | |
461 | out content that used to be here but did not make any sense and | |
462 | seems to have been left unfinished in some previous revision. Should | |
463 | be fixed and this whole feature should be retested and fixed as | |
464 | needed. | |
465 | ==================================================================== | |
466 | For example, in application with plugins, the plugins are not used | |
467 | when linking the application, application might have a dependency on | |
468 | its plugins, even though | |
469 | ||
470 | and | |
471 | adds its usage requirements to the build properties | |
472 | of the target being declared. | |
473 | ||
474 | The primary use case is when you want | |
475 | the usage requirements (such as <code>#include</code> paths) of some | |
476 | library to be applied, but do not want to link to it. | |
477 | ||
478 | It is hard to picture why anyone would want to do that. Please flesh | |
479 | out this motivation. | |
480 | ==================================================================== | |
481 | --> | |
482 | </simpara> | |
483 | </listitem> | |
484 | </varlistentry> | |
485 | ||
486 | <varlistentry><term><anchor id="bbv2.builtin.features.implicit-dependency"/> | |
487 | <literal>implicit-dependency</literal></term> | |
488 | <indexterm><primary>implicit-dependency</primary></indexterm> | |
489 | ||
490 | <listitem> | |
491 | <simpara> | |
492 | Indicates that the target named by the value of this feature | |
493 | may produce files that are included by the sources of the | |
494 | target being declared. See <xref linkend="bbv2.reference.generated_headers"/> | |
495 | for more information. | |
496 | </simpara> | |
497 | </listitem> | |
498 | </varlistentry> | |
499 | ||
500 | ||
501 | <varlistentry><term><anchor id="bbv2.builtin.features.use"/> | |
502 | <literal>use</literal></term> | |
503 | <indexterm><primary>use</primary></indexterm> | |
504 | ||
505 | <listitem> | |
506 | <simpara> | |
507 | Introduces a dependency on the target named by the value of this | |
508 | feature (so it will be brought up-to-date whenever the target being | |
509 | declared is), and adds its usage requirements to the build | |
510 | properties | |
511 | <!-- Do you really mean "to the requirements?" --> | |
512 | of the target being declared. The dependency is not used in any | |
513 | other way. The primary use case is when you want the usage | |
514 | requirements (such as <code>#include</code> paths) of some library | |
515 | to be applied, but do not want to link to it. | |
516 | <!-- It is hard to picture why anyone would want to do that. Please | |
517 | flesh out this motivation. --> | |
518 | </simpara> | |
519 | </listitem> | |
520 | </varlistentry> | |
521 | ||
522 | <varlistentry> | |
523 | <term><anchor id="bbv2.reference.features.dll-path"/> | |
524 | <literal>dll-path</literal></term> | |
525 | <indexterm><primary>dll-path</primary></indexterm> | |
526 | ||
527 | <listitem> | |
528 | <simpara> | |
529 | Specify an additional directory where the system should | |
530 | look for shared libraries when the executable or shared | |
531 | library is run. This feature only affects Unix | |
532 | compilers. Please see <xref linkend="bbv2.faq.dll-path"/> | |
533 | in <xref linkend="bbv2.faq"/> for details. | |
534 | </simpara> | |
535 | </listitem></varlistentry> | |
536 | ||
537 | <varlistentry> | |
538 | <term><literal>hardcode-dll-paths</literal></term> | |
539 | <indexterm><primary>hardcode-dll-paths</primary></indexterm> | |
540 | ||
541 | <listitem> | |
542 | <simpara> | |
543 | Controls automatic generation of dll-path properties. | |
544 | </simpara> | |
545 | ||
546 | <para><emphasis role="bold">Allowed values:</emphasis> | |
547 | <literal>true</literal>, <literal>false</literal>. This property is | |
548 | specific to Unix systems. If an executable is built with | |
549 | <code><hardcode-dll-paths>true</code>, the generated binary | |
550 | will contain the list of all the paths to the used shared libraries. | |
551 | As the result, the executable can be run without changing system | |
552 | paths to shared libraries or installing the libraries to system | |
553 | paths. This <!-- you need an antecedent. This _what_? --> is very | |
554 | convenient during development. Please see the <link linkend= | |
555 | "bbv2.faq.dll-path">FAQ entry</link> for details. Note that on Mac | |
556 | OSX, the paths are unconditionally hardcoded by the linker, and it | |
557 | is not possible to disable that behaviour.</para> | |
558 | </listitem> | |
559 | </varlistentry> | |
560 | ||
561 | <varlistentry> | |
562 | <term><literal>cflags</literal></term> | |
563 | <term><literal>cxxflags</literal></term> | |
564 | <term><literal>linkflags</literal></term> | |
565 | ||
566 | <listitem> | |
567 | <simpara> | |
568 | The value of those features is passed without modification to the | |
569 | corresponding tools. For <code>cflags</code> that is both the C and | |
570 | C++ compilers, for <code>cxxflags</code> that is the C++ compiler, | |
571 | and for <code>linkflags</code> that is the linker. The features are | |
572 | handy when you are trying to do something special that cannot be | |
573 | achieved by a higher-level feature in Boost.Build. | |
574 | </simpara> | |
575 | </listitem> | |
576 | </varlistentry> | |
577 | ||
578 | <varlistentry> | |
579 | <term><literal>include</literal></term> | |
580 | <indexterm><primary>include</primary></indexterm> | |
581 | ||
582 | <listitem> | |
583 | <simpara> | |
584 | Specifies an additional include path that is to be passed to C and | |
585 | C++ compilers. | |
586 | </simpara> | |
587 | </listitem> | |
588 | </varlistentry> | |
589 | ||
590 | <varlistentry> | |
591 | <term><literal>define</literal></term> | |
592 | <indexterm><primary>define</primary></indexterm> | |
593 | ||
594 | <listitem> | |
595 | <simpara> | |
596 | Specifies an preprocessor symbol that should be defined on the command | |
597 | line. You may either specify just the symbol, which will be defined | |
598 | without any value, or both the symbol and the value, separated by | |
599 | equal sign. | |
600 | </simpara> | |
601 | </listitem> | |
602 | </varlistentry> | |
603 | ||
604 | ||
605 | <varlistentry><term><literal>warnings</literal></term> | |
606 | <listitem> | |
607 | <simpara> | |
608 | The <code><warnings></code> feature controls the warning level | |
609 | of compilers. It has the following values: | |
610 | <itemizedlist> | |
611 | <listitem><para><code>off</code> - disables all warnings.</para></listitem> | |
612 | <listitem><para><code>on</code> - enables default warning level for the tool.</para></listitem> | |
613 | <listitem><para><code>all</code> - enables all warnings.</para></listitem> | |
614 | </itemizedlist> | |
615 | Default value is <code>all</code>. | |
616 | </simpara> | |
617 | </listitem> | |
618 | </varlistentry> | |
619 | ||
620 | <varlistentry><term><literal>warnings-as-errors</literal></term> | |
621 | <listitem> | |
622 | <simpara> | |
623 | The <code><warnings-as-errors></code> makes it possible to | |
624 | treat warnings as errors and abort compilation on a warning. The | |
625 | value <code>on</code> enables this behaviour. The default value is | |
626 | <code>off</code>. | |
627 | </simpara> | |
628 | </listitem> | |
629 | </varlistentry> | |
630 | ||
631 | <varlistentry><term><literal>build</literal></term> | |
632 | ||
633 | <listitem> | |
634 | <para><emphasis role="bold">Allowed values:</emphasis> <literal>no</literal></para> | |
635 | ||
636 | <para> | |
637 | The <code>build</code> feature is used to conditionally disable | |
638 | build of a target. If <code><build>no</code> is in properties | |
639 | when building a target, build of that target is skipped. Combined | |
640 | with conditional requirements this allows you to skip building some | |
641 | target in configurations where the build is known to fail. | |
642 | </para> | |
643 | </listitem> | |
644 | </varlistentry> | |
645 | ||
646 | <varlistentry><term><anchor id="bbv2.builtin.features.tag"/><literal>tag</literal></term> | |
647 | ||
648 | <listitem><para>The <literal>tag</literal> feature is used to customize | |
649 | the name of the generated files. The value should have the form: | |
650 | <programlisting>@<replaceable>rulename</replaceable></programlisting> where | |
651 | <replaceable>rulename</replaceable> should be a name of a rule with the | |
652 | following signature: | |
653 | <programlisting>rule tag ( name : type ? : property-set )</programlisting> | |
654 | The rule will be called for each target with the default name computed | |
655 | by Boost.Build, the type of the target, and property set. The rule can | |
656 | either return a string that must be used as the name of the target, or | |
657 | an empty string, in which case the default name will be used. | |
658 | </para> | |
659 | ||
660 | <para>Most typical use of the <literal>tag</literal> feature is to | |
661 | encode build properties, or library version in library target names. You | |
662 | should take care to return non-empty string from the tag rule only for | |
663 | types you care about — otherwise, you might end up modifying | |
664 | names of object files, generated header file and other targets for which | |
665 | changing names does not make sense.</para> | |
666 | </listitem> | |
667 | </varlistentry> | |
668 | ||
669 | <varlistentry><term><literal>debug-symbols</literal></term> | |
670 | ||
671 | <listitem> | |
672 | <para><emphasis role="bold">Allowed values:</emphasis> <literal>on</literal>, <literal>off</literal>.</para> | |
673 | ||
674 | <para>The <literal>debug-symbols</literal> feature specifies if | |
675 | produced object files, executables, and libraries should include | |
676 | debug information. | |
677 | Typically, the value of this feature is implicitly set by the | |
678 | <literal>variant</literal> feature, but it can be explicitly | |
679 | specified by the user. The most common usage is to build | |
680 | release variant with debugging information.</para> | |
681 | </listitem> | |
682 | </varlistentry> | |
683 | ||
684 | <varlistentry><term><literal>runtime-debugging</literal></term> | |
685 | ||
686 | <listitem> | |
687 | <para><emphasis role="bold">Allowed values:</emphasis> <literal>on</literal>, <literal>off</literal>.</para> | |
688 | ||
689 | <para>The <literal>runtime-debugging</literal> feature specifies | |
690 | whether produced object files, executables, and libraries should include | |
691 | behaviour useful only for debugging, such as asserts. | |
692 | Typically, the value of this feature is implicitly set by the | |
693 | <literal>variant</literal> feature, but it can be explicitly | |
694 | specified by the user. The most common usage is to build | |
695 | release variant with debugging output.</para> | |
696 | </listitem> | |
697 | </varlistentry> | |
698 | ||
699 | <varlistentry><term><literal>target-os</literal></term> | |
700 | <listitem> | |
701 | ||
702 | <anchor id="bbv2.reference.features.target-os"/> | |
703 | ||
704 | <para> | |
705 | The operating system for which the code is to be generated. The | |
706 | compiler you used should be the compiler for that operating | |
707 | system. This option causes Boost.Build to use naming conventions | |
708 | suitable for that operating system, and adjust build process | |
709 | accordingly. For example, with gcc, it controls if import | |
710 | libraries are produced for shared libraries or not. | |
711 | </para> | |
712 | ||
713 | <para>The complete list of possible values for this feature is: | |
714 | aix, appletv, bsd, cygwin, darwin, freebsd, hpux, iphone, linux, netbsd, | |
715 | openbsd, osf, qnx, qnxnto, sgi, solaris, unix, unixware, windows. | |
716 | </para> | |
717 | ||
718 | <para>See <xref linkend="bbv2.tasks.crosscompile"/> for details of | |
719 | crosscompilation</para> | |
720 | ||
721 | </listitem> | |
722 | </varlistentry> | |
723 | ||
724 | ||
725 | <varlistentry><term><literal>architecture</literal></term> | |
726 | <listitem> | |
727 | ||
728 | <para> | |
729 | <emphasis role="bold">Allowed values:</emphasis> | |
730 | <literal>x86</literal>, | |
731 | <literal>ia64</literal>, | |
732 | <literal>sparc</literal>, | |
733 | <literal>power</literal>, | |
734 | <literal>mips1</literal>, | |
735 | <literal>mips2</literal>, | |
736 | <literal>mips3</literal>, | |
737 | <literal>mips4</literal>, | |
738 | <literal>mips32</literal>, | |
739 | <literal>mips32r2</literal>, | |
740 | <literal>mips64</literal>, | |
741 | <literal>parisc</literal>, | |
742 | <literal>arm</literal>, | |
743 | <literal>combined</literal>, | |
744 | <literal>combined-x86-power</literal>. | |
745 | </para> | |
746 | ||
747 | <para>The <literal>architecture</literal> features specifies | |
748 | the general processor family to generate code for.</para> | |
749 | ||
750 | </listitem> | |
751 | </varlistentry> | |
752 | ||
753 | <varlistentry><term><literal>instruction-set</literal></term> | |
754 | <indexterm><primary>instruction-set</primary></indexterm> | |
755 | <listitem> | |
756 | <para> | |
757 | <emphasis role="bold">Allowed values:</emphasis> depend on the used | |
758 | toolset. | |
759 | </para> | |
760 | ||
761 | <para>The <literal>instruction-set</literal> specifies for which | |
762 | specific instruction set the code should be generated. The | |
763 | code in general might not run on processors with older/different | |
764 | instruction sets.</para> | |
765 | ||
766 | <para>While Boost.Build allows a large set of possible values | |
767 | for this features, whether a given value works depends on which | |
768 | compiler you use. Please see | |
769 | <xref linkend="bbv2.reference.tools.compilers"/> for details. | |
770 | </para> | |
771 | ||
772 | </listitem> | |
773 | </varlistentry> | |
774 | ||
775 | <varlistentry><term><literal>address-model</literal></term> | |
776 | <indexterm><primary>64-bit compilation</primary></indexterm> | |
777 | <listitem> | |
778 | <para><emphasis role="bold">Allowed values:</emphasis> <literal>32</literal>, <literal>64</literal>.</para> | |
779 | ||
780 | <para>The <literal>address-model</literal> specifies if 32-bit or | |
781 | 64-bit code should be generated by the compiler. Whether this feature | |
782 | works depends on the used compiler, its version, how the compiler is | |
783 | configured, and the values of the <literal>architecture</literal> | |
784 | <literal>instruction-set</literal> | |
785 | features. Please see <xref linkend="bbv2.reference.tools.compilers"/> | |
786 | for details.</para> | |
787 | </listitem> | |
788 | </varlistentry> | |
789 | ||
790 | <varlistentry><term><literal>c++-template-depth</literal></term> | |
791 | <listitem> | |
792 | <para> | |
793 | <emphasis role="bold">Allowed values:</emphasis> Any positive | |
794 | integer. | |
795 | </para> | |
796 | ||
797 | <para> | |
798 | This feature allows configuring a C++ compiler with the maximal | |
799 | template instantiation depth parameter. Specific toolsets may or may | |
800 | not provide support for this feature depending on whether their | |
801 | compilers provide a corresponding command-line option. | |
802 | </para> | |
803 | ||
804 | <para> | |
805 | <emphasis role="bold">Note:</emphasis> Due to some internal details | |
806 | in the current Boost.Build implementation it is not possible to have | |
807 | features whose valid values are all positive integer. As a | |
808 | workaround a large set of allowed values has been defined for this | |
809 | feature and, if a different one is needed, user can easily add it by | |
810 | calling the feature.extend rule. | |
811 | </para> | |
812 | </listitem> | |
813 | </varlistentry> | |
814 | ||
815 | <varlistentry><term><literal>embed-manifest</literal></term> | |
816 | <listitem> | |
817 | ||
818 | <indexterm><primary>manifest file</primary><secondary>embedding</secondary></indexterm> | |
819 | <indexterm><primary>embed-manifest</primary></indexterm> | |
820 | ||
821 | <para> | |
822 | <emphasis role="bold">Allowed values:</emphasis> on, off. | |
823 | </para> | |
824 | ||
825 | <para>This feature is specific to the msvc toolset (see | |
826 | <xref linkend="bbv2.reference.tools.compiler.msvc"/>), | |
827 | and controls whether the manifest files should be embedded inside | |
828 | executables and shared libraries, or placed alongside them. This | |
829 | feature corresponds to the IDE option found in the project settings dialog, | |
830 | under <menuchoice><guimenu>Configuration Properties</guimenu> | |
831 | <guisubmenu>Manifest Tool</guisubmenu> | |
832 | <guisubmenu>Input and Output</guisubmenu> | |
833 | <guimenuitem>Embed manifest</guimenuitem> </menuchoice>. | |
834 | </para> | |
835 | ||
836 | </listitem> | |
837 | </varlistentry> | |
838 | ||
839 | <varlistentry><term><literal>embed-manifest-file</literal></term> | |
840 | <listitem> | |
841 | ||
842 | <indexterm><primary>manifest file</primary><secondary>embedding</secondary></indexterm> | |
843 | <indexterm><primary>embed-manifest-file</primary></indexterm> | |
844 | ||
845 | <para>This feature is specific to the msvc toolset (see | |
846 | <xref linkend="bbv2.reference.tools.compiler.msvc"/>), | |
847 | and controls which manifest files should be embedded inside | |
848 | executables and shared libraries. This | |
849 | feature corresponds to the IDE option found in the project settings dialog, | |
850 | under <menuchoice><guimenu>Configuration Properties</guimenu> | |
851 | <guisubmenu>Manifest Tool</guisubmenu> | |
852 | <guisubmenu>Input and Output</guisubmenu> | |
853 | <guimenuitem>Additional Manifest Files</guimenuitem> </menuchoice>. | |
854 | </para> | |
855 | ||
856 | </listitem> | |
857 | </varlistentry> | |
858 | ||
859 | ||
860 | </variablelist> | |
861 | </section> | |
862 | ||
863 | <section id="bbv2.reference.tools"> | |
864 | <title>Builtin tools</title> | |
865 | ||
866 | <para>Boost.Build comes with support for a large number of C++ compilers, | |
867 | and other tools. This section documents how to use those tools.</para> | |
868 | ||
869 | <para>Before using any tool, you must declare your intention, and possibly | |
870 | specify additional information about the tool's configuration. This is | |
871 | done by calling the <code>using</code> rule, typically in your | |
872 | <filename>user-config.jam</filename>, for example:</para> | |
873 | <programlisting> | |
874 | using gcc ; | |
875 | </programlisting> | |
876 | <para>additional parameters can be passed just like for other rules, for example:</para> | |
877 | <programlisting> | |
878 | using gcc : 4.0 : g++-4.0 ; | |
879 | </programlisting> | |
880 | ||
881 | ||
882 | ||
883 | <para>The options that can be passed to each tool are documented in the | |
884 | subsequent sections.</para> | |
885 | ||
886 | <section id="bbv2.reference.tools.compilers"> | |
887 | ||
888 | <title>C++ Compilers</title> | |
889 | ||
890 | <para>This section lists all Boost.Build modules that support C++ | |
891 | compilers and documents how each one can be initialized. The name | |
892 | of support module for compiler is also the value for | |
893 | the <code>toolset</code> feature that can be used to explicitly | |
894 | request that compiler. </para> | |
895 | ||
896 | <section id="bbv2.reference.tools.compiler.gcc"> | |
897 | ||
898 | <title>GNU C++</title> | |
899 | ||
900 | <para>The <code>gcc</code> module supports the | |
901 | <ulink url="http://gcc.gnu.org">GNU C++ compiler</ulink> | |
902 | on Linux, a number of Unix-like system including SunOS and on Windows | |
903 | (either <ulink url="http://www.cygwin.com">Cygwin</ulink> or | |
904 | <ulink url="http://www.mingw.org">MinGW</ulink>). On Mac OSX, it is recommended | |
905 | to use system gcc, see <xref linkend="bbv2.reference.tools.compiler.darwin"/>. | |
906 | </para> | |
907 | ||
908 | <para>The <code>gcc</code> module is initialized using the following | |
909 | syntax:</para> | |
910 | <programlisting> | |
911 | using gcc : &toolset_ops; ;</programlisting> | |
912 | ||
913 | &using_repeation; | |
914 | ||
915 | <!-- FIXME: mention everywhere what is the semantic | |
916 | of version is --> | |
917 | ||
918 | <para> | |
919 | If the version is not explicitly specified, it will be | |
920 | automatically detected by running the compiler with the <code>-v</code> | |
921 | option. If the command is not specified, the <command>g++</command> | |
922 | binary will be searched in <envar>PATH</envar>.</para> | |
923 | ||
924 | &option_list_intro; | |
925 | <variablelist> | |
926 | ||
927 | <xi:include href="fragments.xml" xpointer="xpointer(id('common_options')/*)" | |
928 | parse="xml"/> | |
929 | ||
930 | <xi:include href="fragments.xml" xpointer="xpointer(id('root_option')/*)" | |
931 | parse="xml"/> | |
932 | ||
933 | <varlistentry> | |
934 | <term><literal>archiver</literal></term> | |
935 | ||
936 | <listitem> | |
937 | <para>Specifies the archiver command that is used to produce static | |
938 | libraries. Normally, it is autodetected using gcc | |
939 | <command>-print-prog-name</command> option or defaulted to <command>ar</command>, | |
940 | but in some cases you might want to override it, for example to explicitly | |
941 | use a system version instead of one included with gcc.</para> | |
942 | </listitem> | |
943 | </varlistentry> | |
944 | ||
945 | <varlistentry> | |
946 | <term><literal>ranlib</literal></term> | |
947 | ||
948 | <listitem> | |
949 | <para>Specifies the ranlib command that is used to generated symbol table | |
950 | for static libraries. Normally, it is autodetected using gcc | |
951 | <command>-print-prog-name</command> option or defaulted to <command>ranlib</command>, | |
952 | but in some cases you might want to override it, for example to explicitly | |
953 | use a system version instead of one included with gcc.</para> | |
954 | </listitem> | |
955 | </varlistentry> | |
956 | ||
957 | <varlistentry> | |
958 | <term><literal>rc</literal></term> | |
959 | ||
960 | <listitem> | |
961 | <para>Specifies the resource compiler command | |
962 | that will be used with the version of gcc that is being | |
963 | configured. This setting makes sense only for Windows and only | |
964 | if you plan to use resource files. By | |
965 | default <command>windres</command> will be used.</para> | |
966 | </listitem> | |
967 | </varlistentry> | |
968 | ||
969 | <varlistentry> | |
970 | <term><literal>rc-type</literal></term> | |
971 | ||
972 | <listitem> | |
973 | <para>Specifies the type of resource compiler. The value can | |
974 | be either <code>windres</code> for msvc resource compiler, | |
975 | or <code>rc</code> for borland's resource compiler.</para> | |
976 | </listitem> | |
977 | </varlistentry> | |
978 | ||
979 | </variablelist> | |
980 | ||
981 | <indexterm><primary>64-bit compilation</primary> | |
982 | <secondary>gcc</secondary></indexterm> | |
983 | ||
984 | In order to compile 64-bit applications, you have to specify | |
985 | <code>address-model=64</code>, and the <code>instruction-set</code> | |
986 | feature should refer to a 64 bit processor. Currently, those | |
987 | include <literal>nocona</literal>, <literal>opteron</literal>, | |
988 | <literal>athlon64</literal> and <literal>athlon-fx</literal>. | |
989 | ||
990 | </section> | |
991 | ||
992 | <section id="bbv2.reference.tools.compiler.darwin"> | |
993 | ||
994 | <title>Apple Darwin gcc</title> | |
995 | ||
996 | <para>The <code>darwin</code> module supports the version of gcc that is | |
997 | modified and provided by Apple. The configuration is essentially identical | |
998 | to that of the gcc module. | |
999 | </para> | |
1000 | ||
1001 | <para> | |
1002 | <indexterm><primary>fat binaries</primary></indexterm> | |
1003 | The darwin toolset can generate so called "fat" | |
1004 | binaries—binaries that can run support more than one | |
1005 | architecture, or address mode. To build a binary that can run both | |
1006 | on Intel and PowerPC processors, specify | |
1007 | <code>architecture=combined</code>. To build a binary that can run | |
1008 | both in 32-bit and 64-bit modes, specify | |
1009 | <code>address-model=32_64</code>. If you specify both of those | |
1010 | properties, a "4-way" fat binary will be generated. | |
1011 | </para> | |
1012 | ||
1013 | </section> | |
1014 | ||
1015 | <section id="bbv2.reference.tools.compiler.msvc"> | |
1016 | ||
1017 | <title>Microsoft Visual C++</title> | |
1018 | ||
1019 | <para>The <code>msvc</code> module supports the | |
1020 | <ulink url="http://msdn.microsoft.com/visualc/">Microsoft Visual | |
1021 | C++</ulink> command-line tools on Microsoft Windows. The supported | |
1022 | products and versions of command line tools are listed below:</para> | |
1023 | <itemizedlist> | |
1024 | <listitem><para>Visual Studio 2015—14.0</para></listitem> | |
1025 | <listitem><para>Visual Studio 2013—12.0</para></listitem> | |
1026 | <listitem><para>Visual Studio 2012—11.0</para></listitem> | |
1027 | <listitem><para>Visual Studio 2010—10.0</para></listitem> | |
1028 | <listitem><para>Visual Studio 2008—9.0</para></listitem> | |
1029 | <listitem><para>Visual Studio 2005—8.0</para></listitem> | |
1030 | <listitem><para>Visual Studio .NET 2003—7.1</para></listitem> | |
1031 | <listitem><para>Visual Studio .NET—7.0</para></listitem> | |
1032 | <listitem><para>Visual Studio 6.0, Service Pack 5—6.5</para></listitem> | |
1033 | </itemizedlist> | |
1034 | ||
1035 | <para>The <code>msvc</code> module is initialized using the following | |
1036 | syntax:</para> | |
1037 | <programlisting> | |
1038 | using msvc : &toolset_ops; ; | |
1039 | </programlisting> | |
1040 | &using_repeation; | |
1041 | <para>If the version is not explicitly specified, the most recent | |
1042 | version found in the registry will be used instead. If the special | |
1043 | value <code>all</code> is passed as the version, all versions found in | |
1044 | the registry will be configured. If a version is specified, but the | |
1045 | command is not, the compiler binary will be searched in standard | |
1046 | installation paths for that version, followed by <envar>PATH</envar>. | |
1047 | </para> | |
1048 | ||
1049 | <para>The compiler command should be specified using forward slashes, | |
1050 | and quoted.</para> | |
1051 | ||
1052 | &option_list_intro; | |
1053 | <variablelist> | |
1054 | ||
1055 | <xi:include href="fragments.xml" xpointer="xpointer(id('common_options')/*)" | |
1056 | parse="xml"/> | |
1057 | ||
1058 | <varlistentry> | |
1059 | <term><literal>assembler</literal></term> | |
1060 | ||
1061 | <listitem><para>The command that compiles assembler sources. If | |
1062 | not specified, <command>ml</command> will be used. The command | |
1063 | will be invoked after the setup script was executed and adjusted | |
1064 | the <envar>PATH</envar> variable.</para></listitem> | |
1065 | </varlistentry> | |
1066 | ||
1067 | <varlistentry> | |
1068 | <term><literal>compiler</literal></term> | |
1069 | ||
1070 | <listitem><para>The command that compiles C and C++ sources. If | |
1071 | not specified, <command>cl</command> will be used. The command | |
1072 | will be invoked after the setup script was executed and adjusted | |
1073 | the <envar>PATH</envar> variable.</para></listitem> | |
1074 | </varlistentry> | |
1075 | ||
1076 | <varlistentry> | |
1077 | <term><literal>compiler-filter</literal></term> | |
1078 | ||
1079 | <listitem><para>Command through which to pipe the output of | |
1080 | running the compiler. For example to pass the output to STLfilt. | |
1081 | </para></listitem> | |
1082 | </varlistentry> | |
1083 | ||
1084 | <varlistentry> | |
1085 | <term><literal>idl-compiler</literal></term> | |
1086 | ||
1087 | <listitem><para>The command that compiles Microsoft COM interface | |
1088 | definition files. If not specified, <command>midl</command> will | |
1089 | be used. The command will be invoked after the setup script was | |
1090 | executed and adjusted the <envar>PATH</envar> variable.</para> | |
1091 | </listitem> | |
1092 | </varlistentry> | |
1093 | ||
1094 | <varlistentry> | |
1095 | <term><literal>linker</literal></term> | |
1096 | ||
1097 | <listitem><para>The command that links executables and dynamic | |
1098 | libraries. If not specified, <command>link</command> will be used. | |
1099 | The command will be invoked after the setup script was executed | |
1100 | and adjusted the <envar>PATH</envar> variable.</para></listitem> | |
1101 | </varlistentry> | |
1102 | ||
1103 | <varlistentry> | |
1104 | <term><literal>mc-compiler</literal></term> | |
1105 | ||
1106 | <listitem><para>The command that compiles Microsoft message | |
1107 | catalog files. If not specified, <command>mc</command> will be | |
1108 | used. The command will be invoked after the setup script was | |
1109 | executed and adjusted the <envar>PATH</envar> variable.</para> | |
1110 | </listitem> | |
1111 | </varlistentry> | |
1112 | ||
1113 | <varlistentry> | |
1114 | <term><literal>resource-compiler</literal></term> | |
1115 | ||
1116 | <listitem><para>The command that compiles resource files. If not | |
1117 | specified, <command>rc</command> will be used. The command will be | |
1118 | invoked after the setup script was executed and adjusted the | |
1119 | <envar>PATH</envar> variable.</para></listitem> | |
1120 | </varlistentry> | |
1121 | ||
1122 | <varlistentry> | |
1123 | <term><literal>setup</literal></term> | |
1124 | ||
1125 | <listitem><para>The filename of the global environment setup | |
1126 | script to run before invoking any of the tools defined in this | |
1127 | toolset. Will not be used in case a target platform specific | |
1128 | script has been explicitly specified for the current target | |
1129 | platform. Used setup script will be passed the target platform | |
1130 | identifier (x86, x86_amd64, x86_ia64, amd64 or ia64) as a | |
1131 | parameter. If not specified a default script is chosen based on the | |
1132 | used compiler binary, e.g. <command>vcvars32.bat</command> or | |
1133 | <command>vsvars32.bat</command>.</para></listitem> | |
1134 | </varlistentry> | |
1135 | ||
1136 | <varlistentry> | |
1137 | <term><literal>setup-amd64</literal></term> | |
1138 | <term><literal>setup-i386</literal></term> | |
1139 | <term><literal>setup-ia64</literal></term> | |
1140 | ||
1141 | <listitem><para>The filename of the target platform specific | |
1142 | environment setup script to run before invoking any of the tools | |
1143 | defined in this toolset. If not specified the global environment | |
1144 | setup script is used.</para></listitem> | |
1145 | </varlistentry> | |
1146 | </variablelist> | |
1147 | ||
1148 | <section id="v2.reference.tools.compiler.msvc.64"> | |
1149 | <title>64-bit support</title> | |
1150 | ||
1151 | <indexterm><primary>64-bit compilation</primary> | |
1152 | <secondary>Microsoft Visual Studio</secondary></indexterm> | |
1153 | ||
1154 | <para>Starting with version 8.0, Microsoft Visual Studio can | |
1155 | generate binaries for 64-bit processor, both 64-bit flavours of x86 | |
1156 | (codenamed AMD64/EM64T), and Itanium (codenamed IA64). In addition, | |
1157 | compilers that are itself run in 64-bit mode, for better | |
1158 | performance, are provided. The complete list of compiler | |
1159 | configurations are as follows (we abbreviate AMD64/EM64T to just | |
1160 | AMD64):</para> | |
1161 | ||
1162 | <itemizedlist> | |
1163 | <listitem><para>32-bit x86 host, 32-bit x86 target</para> | |
1164 | </listitem> | |
1165 | <listitem><para>32-bit x86 host, 64-bit AMD64 target</para> | |
1166 | </listitem> | |
1167 | <listitem><para>32-bit x86 host, 64-bit IA64 target</para> | |
1168 | </listitem> | |
1169 | <listitem><para>64-bit AMD64 host, 64-bit AMD64 target</para> | |
1170 | </listitem> | |
1171 | <listitem><para>64-bit IA64 host, 64-bit IA64 target</para> | |
1172 | </listitem> | |
1173 | </itemizedlist> | |
1174 | <para> | |
1175 | The 32-bit host compilers can be always used, even on 64-bit | |
1176 | Windows. On the contrary, 64-bit host compilers require both 64-bit | |
1177 | host processor and 64-bit Windows, but can be faster. By default, | |
1178 | only 32-bit host, 32-bit target compiler is installed, and | |
1179 | additional compilers need to be installed explicitly. | |
1180 | </para> | |
1181 | ||
1182 | <para>To use 64-bit compilation you should:</para> | |
1183 | <orderedlist> | |
1184 | <listitem><para>Configure you compiler as usual. If you provide a | |
1185 | path to the compiler explicitly, provide the path to the 32-bit | |
1186 | compiler. If you try to specify the path to any of 64-bit | |
1187 | compilers, configuration will not work.</para></listitem> | |
1188 | ||
1189 | <listitem><para>When compiling, use <code>address-model=64</code>, | |
1190 | to generate AMD64 code.</para></listitem> | |
1191 | ||
1192 | <listitem><para>To generate IA64 code, use | |
1193 | <code>architecture=ia64</code></para></listitem> | |
1194 | </orderedlist> | |
1195 | ||
1196 | <para>The (AMD64 host, AMD64 target) compiler will be used | |
1197 | automatically when you are generating AMD64 code and are running | |
1198 | 64-bit Windows on AMD64. The (IA64 host, IA64 target) compiler will | |
1199 | never be used, since nobody has an IA64 machine to test.</para> | |
1200 | ||
1201 | <para>It is believed that AMD64 and EM64T targets are essentially | |
1202 | compatible. The compiler options <code>/favor:AMD64</code> and | |
1203 | <code>/favor:EM64T</code>, which are accepted only by AMD64 | |
1204 | targeting compilers, cause the generated code to be tuned to a | |
1205 | specific flavor of 64-bit x86. Boost.Build will make use of those | |
1206 | options depending on the value of the<code>instruction-set</code> | |
1207 | feature.</para> | |
1208 | </section> | |
1209 | ||
1210 | <section id="v2.reference.tools.compiler.msvc.winrt"> | |
1211 | <title>Windows Runtime support</title> | |
1212 | ||
1213 | <indexterm><primary>Windows Runtime support</primary> | |
1214 | <secondary>Microsoft Visual Studio</secondary></indexterm> | |
1215 | ||
1216 | <para> | |
1217 | Starting with version 11.0, Microsoft Visual Studio can | |
1218 | produce binaries for Windows Store and Phone in addition to | |
1219 | traditional Win32 desktop. To specify which Windows API set | |
1220 | to target, use the <literal>windows-api</literal> feature. | |
1221 | Available options are <literal>desktop</literal>, | |
1222 | <literal>store</literal>, or <literal>phone</literal>. If not | |
1223 | specified, <literal>desktop</literal> will be used. | |
1224 | </para> | |
1225 | ||
1226 | <para> | |
1227 | When using <literal>store</literal> or <literal>phone</literal> | |
1228 | the specified toolset determines what Windows version is | |
1229 | targeted. The following options are available: | |
1230 | </para> | |
1231 | ||
1232 | <itemizedlist> | |
1233 | <listitem><para>Windows 8.0: toolset=msvc-11.0 windows-api=store</para> | |
1234 | </listitem> | |
1235 | <listitem><para>Windows 8.1: toolset=msvc-12.0 windows-api=store</para> | |
1236 | </listitem> | |
1237 | <listitem><para>Windows Phone 8.0: toolset=msvc-11.0 windows-api=phone</para> | |
1238 | </listitem> | |
1239 | <listitem><para>Windows Phone 8.1: toolset=msvc-12.0 windows-api=phone</para> | |
1240 | </listitem> | |
1241 | </itemizedlist> | |
1242 | ||
1243 | <para> | |
1244 | For example use the following to build for Windows Store 8.1 | |
1245 | with the ARM architecture: | |
1246 | </para> | |
1247 | <programlisting> | |
1248 | .\b2 toolset=msvc-12.0 windows-api=store architecture=arm</programlisting> | |
1249 | ||
1250 | <para> | |
1251 | Note that when targeting Windows Phone 8.1, version 12.0 didn't | |
1252 | include the vcvars phone setup scripts. They can be separately | |
1253 | downloaded from | |
1254 | <ulink url="http://blogs.msdn.com/b/vcblog/archive/2014/07/18/using-boost-libraries-in-windows-store-and-phone-applications.aspx">here</ulink>. | |
1255 | </para> | |
1256 | ||
1257 | </section> | |
1258 | </section> | |
1259 | ||
1260 | <section id="bbv2.reference.tools.compiler.intel"> | |
1261 | ||
1262 | <title>Intel C++</title> | |
1263 | ||
1264 | <para>The <code>intel-linux</code> and <code>intel-win</code> modules | |
1265 | support the Intel C++ command-line compiler—the <ulink url= | |
1266 | "http://www.intel.com/software/products/compilers/clin/index.htm">Linux</ulink> | |
1267 | and <ulink url= | |
1268 | "http://www.intel.com/cd/software/products/asmo-na/eng/compilers/284527.htm"> | |
1269 | Windows</ulink> versions respectively.</para> | |
1270 | ||
1271 | <para>The module is initialized using the following syntax:</para> | |
1272 | <programlisting> | |
1273 | using intel-linux : &toolset_ops; ;</programlisting> | |
1274 | <para>or</para> | |
1275 | <programlisting> | |
1276 | using intel-win : &toolset_ops; ;</programlisting> | |
1277 | <para>respectively.</para> | |
1278 | ||
1279 | &using_repeation; | |
1280 | ||
1281 | <para> | |
1282 | If compiler command is not specified, then Boost.Build will | |
1283 | look in <envar>PATH</envar> for an executable <command>icpc</command> | |
1284 | (on Linux), or <command>icc.exe</command> (on Windows). | |
1285 | </para> | |
1286 | ||
1287 | &option_list_intro; | |
1288 | <variablelist> | |
1289 | ||
1290 | <xi:include href="fragments.xml" xpointer="xpointer(id('common_options')/*)" | |
1291 | parse="xml"/> | |
1292 | ||
1293 | </variablelist> | |
1294 | ||
1295 | <para>The Linux version supports the following additional options:</para> | |
1296 | <variablelist> | |
1297 | ||
1298 | <xi:include href="fragments.xml" xpointer="xpointer(id('root_option')/*)" | |
1299 | parse="xml"/> | |
1300 | ||
1301 | </variablelist> | |
1302 | ||
1303 | <!-- the compatibility option appears to be messed up --> | |
1304 | ||
1305 | </section> | |
1306 | ||
1307 | <section id="bbv2.reference.tools.compiler.acc"> | |
1308 | ||
1309 | <title>HP aC++ compiler</title> | |
1310 | ||
1311 | <para>The <code>acc</code> module supports the | |
1312 | <ulink url="http://h21007.www2.hp.com/dspp/tech/tech_TechSoftwareDetailPage_IDX/1,1703,1740,00.html">HP aC++ compiler</ulink> | |
1313 | for the HP-UX operating system.</para> | |
1314 | ||
1315 | <para>The module is initialized using the following | |
1316 | syntax:</para> | |
1317 | <programlisting> | |
1318 | using acc : &toolset_ops; ;</programlisting> | |
1319 | ||
1320 | &using_repeation; | |
1321 | ||
1322 | ||
1323 | <para> | |
1324 | If the command is not specified, the <command>aCC</command> | |
1325 | binary will be searched in <envar>PATH</envar>.</para> | |
1326 | ||
1327 | &option_list_intro; | |
1328 | <variablelist> | |
1329 | <xi:include href="fragments.xml" xpointer="xpointer(id('common_options')/*)" | |
1330 | parse="xml"/> | |
1331 | </variablelist> | |
1332 | ||
1333 | </section> | |
1334 | ||
1335 | <section id="bbv2.reference.tools.compiler.borland"> | |
1336 | ||
1337 | <title>Borland C++ Compiler</title> | |
1338 | ||
1339 | <para>The <code>borland</code> module supports the command line | |
1340 | C++ compiler included in | |
1341 | <ulink url="http://www.borland.com/us/products/cbuilder/index.html">C++ Builder 2006</ulink> | |
1342 | product and earlier version of it, running on Microsoft Windows.</para> | |
1343 | ||
1344 | <para>The supported products are listed below. The version reported | |
1345 | by the command lines tools is also listed for reference.:</para> | |
1346 | <itemizedlist> | |
1347 | <listitem><para>C++ Builder 2006—5.8.2</para></listitem> | |
1348 | <listitem><para>CBuilderX—5.6.5, 5.6.4 (depending on release)</para></listitem> | |
1349 | <listitem><para>CBuilder6—5.6.4</para></listitem> | |
1350 | <listitem><para>Free command line tools—5.5.1</para></listitem> | |
1351 | </itemizedlist> | |
1352 | ||
1353 | <para>The module is initialized using the following syntax:</para> | |
1354 | <programlisting> | |
1355 | using borland : &toolset_ops; ;</programlisting> | |
1356 | ||
1357 | &using_repeation; | |
1358 | ||
1359 | <para>If the command is not specified, Boost.Build will search for | |
1360 | a binary named <command>bcc32</command> in <envar>PATH</envar>.</para> | |
1361 | ||
1362 | &option_list_intro; | |
1363 | <variablelist> | |
1364 | <xi:include href="fragments.xml" xpointer="xpointer(id('common_options')/*)" | |
1365 | parse="xml"/> | |
1366 | </variablelist> | |
1367 | ||
1368 | </section> | |
1369 | ||
1370 | <section id="bbv2.reference.tools.compiler.como"> | |
1371 | ||
1372 | <title>Comeau C/C++ Compiler</title> | |
1373 | ||
1374 | <para>The <code>como-linux</code> and the <code>como-win</code> | |
1375 | modules supports the | |
1376 | <ulink url="http://www.comeaucomputing.com/">Comeau C/C++ Compiler</ulink> | |
1377 | on Linux and Windows respectively.</para> | |
1378 | ||
1379 | <para>The module is initialized using the following syntax:</para> | |
1380 | <programlisting> | |
1381 | using como-linux : &toolset_ops; ;</programlisting> | |
1382 | ||
1383 | &using_repeation; | |
1384 | ||
1385 | <para>If the command is not specified, Boost.Build will search for | |
1386 | a binary named <command>como</command> in | |
1387 | <envar>PATH</envar>.</para> | |
1388 | ||
1389 | &option_list_intro; | |
1390 | <variablelist> | |
1391 | <xi:include href="fragments.xml" xpointer="xpointer(id('common_options')/*)" | |
1392 | parse="xml"/> | |
1393 | </variablelist> | |
1394 | ||
1395 | <para>Before using the Windows version of the compiler, you need to | |
1396 | setup necessary environment variables per compiler's documentation. In | |
1397 | particular, the <envar>COMO_XXX_INCLUDE</envar> variable should be | |
1398 | set, where <envar>XXX</envar> corresponds to the used backend C | |
1399 | compiler.</para> | |
1400 | </section> | |
1401 | ||
1402 | <section id="bbv2.reference.tools.compiler.cw"> | |
1403 | ||
1404 | <title>Code Warrior</title> | |
1405 | ||
1406 | <para>The <code>cw</code> module support CodeWarrior compiler, | |
1407 | originally produced by Metrowerks and presently developed by | |
1408 | Freescale. Boost.Build supports only the versions of the compiler that | |
1409 | target x86 processors. All such versions were released by Metrowerks | |
1410 | before acquisition and are not sold any longer. The last version known | |
1411 | to work is 9.4.</para> | |
1412 | ||
1413 | <para>The module is initialized using the following syntax:</para> | |
1414 | <programlisting> | |
1415 | using cw : &toolset_ops; ;</programlisting> | |
1416 | ||
1417 | &using_repeation; | |
1418 | ||
1419 | <para>If the command is not specified, Boost.Build will search for a | |
1420 | binary named <command>mwcc</command> in default installation paths and | |
1421 | in <envar>PATH</envar>.</para> | |
1422 | ||
1423 | &option_list_intro; | |
1424 | <variablelist> | |
1425 | ||
1426 | <xi:include href="fragments.xml" xpointer="xpointer(id('common_options')/*)" | |
1427 | parse="xml"/> | |
1428 | ||
1429 | <xi:include href="fragments.xml" xpointer="xpointer(id('root_option')/*)" | |
1430 | parse="xml"/> | |
1431 | ||
1432 | <varlistentry> | |
1433 | <term><literal>setup</literal></term> | |
1434 | ||
1435 | <listitem><para>The command that sets up environment variables | |
1436 | prior to invoking the compiler. If not specified, | |
1437 | <command>cwenv.bat</command> alongside the compiler binary | |
1438 | will be used.</para> | |
1439 | </listitem> | |
1440 | </varlistentry> | |
1441 | ||
1442 | ||
1443 | <varlistentry> | |
1444 | <term><literal>compiler</literal></term> | |
1445 | ||
1446 | <listitem><para>The command that compiles C and C++ sources. | |
1447 | If not specified, <command>mwcc</command> will be used. The | |
1448 | command will be invoked after the setup script was | |
1449 | executed and adjusted the <envar>PATH</envar> variable.</para> | |
1450 | </listitem> | |
1451 | </varlistentry> | |
1452 | ||
1453 | <varlistentry> | |
1454 | <term><literal>linker</literal></term> | |
1455 | ||
1456 | <listitem><para>The command that links executables and dynamic | |
1457 | libraries. | |
1458 | If not specified, <command>mwld</command> will be used. The | |
1459 | command will be invoked after the setup script was | |
1460 | executed and adjusted the <envar>PATH</envar> variable.</para> | |
1461 | </listitem> | |
1462 | </varlistentry> | |
1463 | ||
1464 | </variablelist> | |
1465 | ||
1466 | </section> | |
1467 | ||
1468 | <section id="bbv2.reference.tools.compiler.dmc"> | |
1469 | ||
1470 | <title>Digital Mars C/C++ Compiler</title> | |
1471 | ||
1472 | <para>The <code>dmc</code> module supports the | |
1473 | <ulink url="http://www.digitalmars.com/">Digital Mars C++ compiler.</ulink> | |
1474 | </para> | |
1475 | ||
1476 | <para>The module is initialized using the following syntax:</para> | |
1477 | <programlisting> | |
1478 | using dmc : &toolset_ops; ;</programlisting> | |
1479 | ||
1480 | &using_repeation; | |
1481 | ||
1482 | <para>If the command is not specified, Boost.Build will search for | |
1483 | a binary named <command>dmc</command> in | |
1484 | <envar>PATH</envar>.</para> | |
1485 | ||
1486 | &option_list_intro; | |
1487 | <variablelist> | |
1488 | <xi:include href="fragments.xml" xpointer="xpointer(id('common_options')/*)" | |
1489 | parse="xml"/> | |
1490 | </variablelist> | |
1491 | ||
1492 | </section> | |
1493 | ||
1494 | <section id="bbv2.reference.tools.compiler.hp_cxx"> | |
1495 | ||
1496 | <title>HP C++ Compiler for Tru64 Unix</title> | |
1497 | ||
1498 | <para>The <code>hp_cxx</code> modules supports the | |
1499 | <ulink url="http://h30097.www3.hp.com/cplus/?jumpid=reg_R1002_USEN"> | |
1500 | HP C++ Compiler</ulink> for Tru64 Unix.</para> | |
1501 | ||
1502 | <para>The module is initialized using the following syntax:</para> | |
1503 | <programlisting> | |
1504 | using hp_cxx : &toolset_ops; ;</programlisting> | |
1505 | ||
1506 | &using_repeation; | |
1507 | ||
1508 | <para>If the command is not specified, Boost.Build will search for | |
1509 | a binary named <command>hp_cxx</command> in <envar>PATH</envar>.</para> | |
1510 | ||
1511 | &option_list_intro; | |
1512 | <variablelist> | |
1513 | <xi:include href="fragments.xml" xpointer="xpointer(id('common_options')/*)" | |
1514 | parse="xml"/> | |
1515 | </variablelist> | |
1516 | ||
1517 | </section> | |
1518 | ||
1519 | <section id="bbv2.reference.tools.compiler.sun"> | |
1520 | ||
1521 | <title>Sun Studio</title> | |
1522 | ||
1523 | <para>The <code>sun</code> module supports the | |
1524 | <ulink url="http://developers.sun.com/sunstudio/index.jsp"> | |
1525 | Sun Studio</ulink> C++ compilers for the Solaris OS.</para> | |
1526 | ||
1527 | <para>The module is initialized using the following syntax:</para> | |
1528 | <programlisting> | |
1529 | using sun : &toolset_ops; ;</programlisting> | |
1530 | ||
1531 | &using_repeation; | |
1532 | ||
1533 | <para>If the command is not specified, Boost.Build will search for | |
1534 | a binary named <command>CC</command> | |
1535 | in <filename>/opt/SUNWspro/bin</filename> and in | |
1536 | <envar>PATH</envar>.</para> | |
1537 | ||
1538 | <para>When using this compiler on complex C++ code, such as the | |
1539 | <ulink url="http://boost.org">Boost C++ library</ulink>, it is | |
1540 | recommended to specify the following options when initializing the | |
1541 | <code>sun</code> module: | |
1542 | <screen> | |
1543 | -library=stlport4 -features=tmplife -features=tmplrefstatic | |
1544 | </screen> See the <ulink url="http://blogs.sun.com/sga/entry/command_line_options"> | |
1545 | Sun C++ Frontend Tales</ulink> for details.</para> | |
1546 | ||
1547 | &option_list_intro; | |
1548 | <variablelist> | |
1549 | <xi:include href="fragments.xml" xpointer="xpointer(id('common_options')/*)" | |
1550 | parse="xml"/> | |
1551 | </variablelist> | |
1552 | ||
1553 | <indexterm><primary>64-bit compilation</primary> | |
1554 | <secondary>Sun Studio</secondary></indexterm> | |
1555 | Starting with Sun Studio 12, you can create 64-bit applications | |
1556 | by using the <code>address-model=64</code> property. | |
1557 | ||
1558 | </section> | |
1559 | ||
1560 | <section id="bbv2.reference.tools.compiler.vacpp"> | |
1561 | ||
1562 | <title>IBM Visual Age</title> | |
1563 | <para>The <code>vacpp</code> module supports the | |
1564 | <ulink url="http://www.ibm.com/software/ad/vacpp">IBM Visual | |
1565 | Age</ulink> C++ Compiler, for the AIX operating system. Versions | |
1566 | 7.1 and 8.0 are known to work.</para> | |
1567 | ||
1568 | <para>The module is initialized using the following | |
1569 | syntax:</para> | |
1570 | <programlisting> | |
1571 | using vacpp ;</programlisting> | |
1572 | ||
1573 | <para>The module does not accept any initialization options. The | |
1574 | compiler should be installed in the <filename>/usr/vacpp/bin</filename> | |
1575 | directory.</para> | |
1576 | ||
1577 | <para>Later versions of Visual Age are known as XL C/C++. They | |
1578 | were not tested with the the <code>vacpp</code> module.</para> | |
1579 | ||
1580 | </section> | |
1581 | ||
1582 | </section> | |
1583 | ||
1584 | <section> | |
1585 | <title>Third-party libraries</title> | |
1586 | ||
1587 | <para>Boost.Build provides special support for some | |
1588 | third-party C++ libraries, documented below.</para> | |
1589 | ||
1590 | <section id="bbv2.reference.tools.libraries.stlport"> | |
1591 | <title>STLport library</title> | |
1592 | <indexterm><primary>STLport</primary></indexterm> | |
1593 | ||
1594 | <para>The <ulink url="http://stlport.org">STLport</ulink> library | |
1595 | is an alternative implementation of C++ runtime library. Boost.Build | |
1596 | supports using that library on Windows platform. Linux is | |
1597 | hampered by different naming of libraries in each STLport | |
1598 | version and is not officially supported.</para> | |
1599 | ||
1600 | <para>Before using STLport, you need to configure it in | |
1601 | <filename>user-config.jam</filename> using the following syntax: | |
1602 | </para> | |
1603 | <programlisting> | |
1604 | using stlport : <optional><replaceable>version</replaceable></optional> : <replaceable>header-path</replaceable> : <optional><replaceable>library-path</replaceable></optional> ; | |
1605 | </programlisting> | |
1606 | <para> | |
1607 | Where <replaceable>version</replaceable> is the version of | |
1608 | STLport, for example <literal>5.1.4</literal>, | |
1609 | <replaceable>headers</replaceable> is the location where | |
1610 | STLport headers can be found, and <replaceable>libraries</replaceable> | |
1611 | is the location where STLport libraries can be found. | |
1612 | The version should always be provided, and the library path should | |
1613 | be provided if you're using STLport's implementation of | |
1614 | iostreams. Note that STLport 5.* always uses its own iostream | |
1615 | implementation, so the library path is required. | |
1616 | </para> | |
1617 | ||
1618 | <para>When STLport is configured, you can build with STLport by | |
1619 | requesting <literal>stdlib=stlport</literal> on the command line. | |
1620 | </para> | |
1621 | ||
1622 | </section> | |
1623 | ||
1624 | <section id="bbv2.reference.tools.libraries.zlib"> | |
1625 | <title>zlib</title> | |
1626 | <indexterm><primary>zlib</primary></indexterm> | |
1627 | ||
1628 | <para>Provides support for the | |
1629 | <ulink url="http://www.zlib.net">zlib</ulink> library. zlib | |
1630 | can be configured either to use precompiled binaries or to | |
1631 | build the library from source.</para> | |
1632 | ||
1633 | <para>zlib can be initialized using the following syntax</para> | |
1634 | <programlisting> | |
1635 | using zlib : <optional><replaceable>version</replaceable></optional> : <optional><replaceable>options</replaceable></optional> : <optional><replaceable>condition</replaceable></optional> : <optional><replaceable>is-default</replaceable></optional> ; | |
1636 | </programlisting> | |
1637 | <para>Options for using a prebuilt library:</para> | |
1638 | <variablelist> | |
1639 | <varlistentry> | |
1640 | <term><literal>search</literal></term> | |
1641 | <listitem> | |
1642 | <para>The directory containing the zlib binaries.</para> | |
1643 | </listitem> | |
1644 | </varlistentry> | |
1645 | <varlistentry> | |
1646 | <term><literal>name</literal></term> | |
1647 | <listitem> | |
1648 | <para>Overrides the default library name.</para> | |
1649 | </listitem> | |
1650 | </varlistentry> | |
1651 | <varlistentry> | |
1652 | <term><literal>include</literal></term> | |
1653 | <listitem> | |
1654 | <para>The directory containing the zlib headers.</para> | |
1655 | </listitem> | |
1656 | </varlistentry> | |
1657 | </variablelist> | |
1658 | <para>If none of these options is specified, then the environmental | |
1659 | variables ZLIB_LIBRARY_PATH, ZLIB_NAME, and ZLIB_INCLUDE will be | |
1660 | used instead.</para> | |
1661 | <para>Options for building zlib from source:</para> | |
1662 | <variablelist> | |
1663 | <varlistentry> | |
1664 | <term><literal>source</literal></term> | |
1665 | <listitem> | |
1666 | <para>The zlib source directory. Defaults to the | |
1667 | environmental variable ZLIB_SOURCE.</para> | |
1668 | </listitem> | |
1669 | </varlistentry> | |
1670 | <varlistentry> | |
1671 | <term><literal>tag</literal></term> | |
1672 | <listitem> | |
1673 | <para>Sets the <link linkend="bbv2.builtin.features.tag">tag</link> | |
1674 | property to adjust the file name of the library. Ignored | |
1675 | when using precompiled binaries.</para> | |
1676 | </listitem> | |
1677 | </varlistentry> | |
1678 | <varlistentry> | |
1679 | <term><literal>build-name</literal></term> | |
1680 | <listitem> | |
1681 | <para>The base name to use for the compiled library. | |
1682 | Ignored when using precompiled binaries.</para> | |
1683 | </listitem> | |
1684 | </varlistentry> | |
1685 | </variablelist> | |
1686 | <para>Examples:</para> | |
1687 | <programlisting> | |
1688 | # Find zlib in the default system location | |
1689 | using zlib ; | |
1690 | # Build zlib from source | |
1691 | using zlib : 1.2.7 : <source>/home/steven/zlib-1.2.7 ; | |
1692 | # Find zlib in /usr/local | |
1693 | using zlib : 1.2.7 : <include>/usr/local/include <search>/usr/local/lib ; | |
1694 | # Build zlib from source for msvc and find | |
1695 | # prebuilt binaries for gcc. | |
1696 | using zlib : 1.2.7 : <source>C:/Devel/src/zlib-1.2.7 : <toolset>msvc ; | |
1697 | using zlib : 1.2.7 : : <toolset>gcc ; | |
1698 | </programlisting> | |
1699 | </section> | |
1700 | ||
1701 | </section> | |
1702 | ||
1703 | <section> | |
1704 | <title>Documentation tools</title> | |
1705 | ||
1706 | <para>Boost.Build support for the Boost documentation tools is | |
1707 | documented below. | |
1708 | </para> | |
1709 | ||
1710 | <section id="bbv2.reference.tools.doc.xsltproc"> | |
1711 | <title>xsltproc</title> | |
1712 | <indexterm><primary>xsltproc</primary></indexterm> | |
1713 | ||
1714 | <para>To use xsltproc, you first need to configure it using the following syntax:</para> | |
1715 | <programlisting> | |
1716 | using xsltproc : <optional><replaceable>xsltproc</replaceable></optional> ; | |
1717 | </programlisting> | |
1718 | <para> | |
1719 | Where <replaceable>xsltproc</replaceable> is the xsltproc executable. | |
1720 | If <replaceable>xsltproc</replaceable> is not specified, and the | |
1721 | variable XSLTPROC is set, the value of XSLTPROC will be used. | |
1722 | Otherwise, xsltproc will be searched for in PATH. | |
1723 | </para> | |
1724 | ||
1725 | ||
1726 | &option_list_intro; | |
1727 | <variablelist> | |
1728 | ||
1729 | <varlistentry> | |
1730 | <indexterm><primary>xsl:param</primary></indexterm> | |
1731 | <term><literal>xsl:param</literal></term> | |
1732 | <listitem> | |
1733 | <para>Values should have the form | |
1734 | <replaceable>name</replaceable>=<replaceable>value</replaceable></para> | |
1735 | </listitem> | |
1736 | </varlistentry> | |
1737 | ||
1738 | <varlistentry> | |
1739 | <indexterm><primary>xsl:path</primary></indexterm> | |
1740 | <term><literal>xsl:path</literal></term> | |
1741 | <listitem> | |
1742 | <para>Sets an additional search path for xi:include elements.</para> | |
1743 | </listitem> | |
1744 | </varlistentry> | |
1745 | ||
1746 | <varlistentry> | |
1747 | <indexterm><primary>catalog</primary></indexterm> | |
1748 | <term><literal>catalog</literal></term> | |
1749 | <listitem> | |
1750 | <para>A catalog file used to rewrite remote URL's to a local copy.</para> | |
1751 | </listitem> | |
1752 | </varlistentry> | |
1753 | ||
1754 | </variablelist> | |
1755 | ||
1756 | <para>The xsltproc module provides the following rules. Note that | |
1757 | these operate on jam targets and are intended to be used by another | |
1758 | toolset, such as boostbook, rather than directly by users. | |
1759 | </para> | |
1760 | <variablelist> | |
1761 | ||
1762 | <varlistentry> | |
1763 | <indexterm><primary>xslt</primary></indexterm> | |
1764 | <term><literal>xslt</literal></term> | |
1765 | <listitem> | |
1766 | <programlisting> | |
1767 | rule xslt ( target : source stylesheet : properties * ) | |
1768 | </programlisting> | |
1769 | <para>Runs xsltproc to create a single output file.</para> | |
1770 | </listitem> | |
1771 | </varlistentry> | |
1772 | ||
1773 | <varlistentry> | |
1774 | <indexterm><primary>xslt-dir</primary></indexterm> | |
1775 | <term><literal>xslt-dir</literal></term> | |
1776 | <listitem> | |
1777 | <programlisting> | |
1778 | rule xslt-dir ( target : source stylesheet : properties * : dirname ) | |
1779 | </programlisting> | |
1780 | <para>Runs xsltproc to create multiple outputs in a directory. | |
1781 | <literal>dirname</literal> is unused, but exists for | |
1782 | historical reasons. The output directory is determined from the | |
1783 | target. | |
1784 | </para> | |
1785 | </listitem> | |
1786 | </varlistentry> | |
1787 | ||
1788 | </variablelist> | |
1789 | ||
1790 | </section> | |
1791 | ||
1792 | <section id="bbv2.reference.tools.doc.boostbook"> | |
1793 | <title>boostbook</title> | |
1794 | <indexterm><primary>boostbook</primary><secondary>module</secondary></indexterm> | |
1795 | ||
1796 | <para>To use boostbook, you first need to configure it using the following syntax:</para> | |
1797 | <programlisting> | |
1798 | using boostbook : <optional><replaceable>docbook-xsl-dir</replaceable></optional> : <optional><replaceable>docbook-dtd-dir</replaceable></optional> : <optional><replaceable>boostbook-dir</replaceable></optional> ; | |
1799 | </programlisting> | |
1800 | <para> | |
1801 | <replaceable>docbook-xsl-dir</replaceable> is the DocBook XSL stylesheet | |
1802 | directory. If not provided, we use DOCBOOK_XSL_DIR from the environment | |
1803 | (if available) or look in standard locations. Otherwise, we let the | |
1804 | XML processor load the stylesheets remotely. | |
1805 | </para> | |
1806 | ||
1807 | <para> | |
1808 | <replaceable>docbook-dtd-dir</replaceable> is the DocBook DTD directory. | |
1809 | If not provided, we use DOCBOOK_DTD_DIR From the environment (if | |
1810 | available) or look in standard locations. Otherwise, we let the XML | |
1811 | processor load the DTD remotely. | |
1812 | </para> | |
1813 | ||
1814 | <para> | |
1815 | <replaceable>boostbook-dir</replaceable> is the BoostBook directory | |
1816 | with the DTD and XSL subdirs. | |
1817 | </para> | |
1818 | ||
1819 | <para>The boostbook module depends on xsltproc. For pdf or ps output, | |
1820 | it also depends on fop. | |
1821 | </para> | |
1822 | ||
1823 | &option_list_intro; | |
1824 | <variablelist> | |
1825 | ||
1826 | <varlistentry> | |
1827 | <indexterm><primary>format</primary></indexterm> | |
1828 | <indexterm><primary>html</primary></indexterm> | |
1829 | <indexterm><primary>xhtml</primary></indexterm> | |
1830 | <indexterm><primary>htmlhelp</primary></indexterm> | |
1831 | <indexterm><primary>onehtml</primary></indexterm> | |
1832 | <indexterm><primary>man</primary></indexterm> | |
1833 | <indexterm><primary>pdf</primary></indexterm> | |
1834 | <indexterm><primary>ps</primary></indexterm> | |
1835 | <indexterm><primary>docbook</primary></indexterm> | |
1836 | <indexterm><primary>fo</primary></indexterm> | |
1837 | <indexterm><primary>tests</primary></indexterm> | |
1838 | <term><literal>format</literal></term> | |
1839 | <listitem> | |
1840 | <para> | |
1841 | <emphasis role="bold">Allowed values:</emphasis> | |
1842 | <literal>html</literal>, <literal>xhtml</literal>, | |
1843 | <literal>htmlhelp</literal>, <literal>onehtml</literal>, | |
1844 | <literal>man</literal>, <literal>pdf</literal>, | |
1845 | <literal>ps</literal>, <literal>docbook</literal>, | |
1846 | <literal>fo</literal>, <literal>tests</literal>. | |
1847 | </para> | |
1848 | ||
1849 | ||
1850 | <para>The <literal>format</literal> feature determines the type | |
1851 | of output produced by the boostbook rule.</para> | |
1852 | </listitem> | |
1853 | </varlistentry> | |
1854 | ||
1855 | </variablelist> | |
1856 | ||
1857 | <para>The boostbook module defines a rule for creating a target | |
1858 | following the common syntax.</para> | |
1859 | ||
1860 | <variablelist> | |
1861 | ||
1862 | <varlistentry> | |
1863 | <indexterm><primary>boostbook</primary><secondary>rule</secondary></indexterm> | |
1864 | <term><literal>boostbook</literal></term> | |
1865 | <listitem> | |
1866 | <programlisting> | |
1867 | rule boostbook ( target-name : sources * : requirements * : default-build * ) | |
1868 | </programlisting> | |
1869 | <para>Creates a boostbook target.</para> | |
1870 | </listitem> | |
1871 | </varlistentry> | |
1872 | ||
1873 | </variablelist> | |
1874 | ||
1875 | </section> | |
1876 | ||
1877 | <section id="bbv2.reference.tools.doc.doxygen"> | |
1878 | <title>doxygen</title> | |
1879 | <indexterm><primary>doxygen</primary></indexterm> | |
1880 | ||
1881 | <para>To use doxygen, you first need to configure it using the following syntax:</para> | |
1882 | <programlisting> | |
1883 | using doxygen : <optional><replaceable>name</replaceable></optional> ; | |
1884 | </programlisting> | |
1885 | <para> | |
1886 | <replaceable>name</replaceable> is the doxygen command. | |
1887 | If it is not specified, it will be found in the PATH. | |
1888 | </para> | |
1889 | ||
1890 | <para>The doxygen module depends on the boostbook module when | |
1891 | generating BoostBook XML. | |
1892 | </para> | |
1893 | ||
1894 | &option_list_intro; | |
1895 | <variablelist> | |
1896 | ||
1897 | <varlistentry> | |
1898 | <indexterm><primary>doxygen:param</primary></indexterm> | |
1899 | <term><literal>doxygen:param</literal></term> | |
1900 | <listitem> | |
1901 | <para>All the values of <literal>doxygen:param</literal> | |
1902 | are added to the doxyfile.</para> | |
1903 | </listitem> | |
1904 | </varlistentry> | |
1905 | ||
1906 | <varlistentry> | |
1907 | <indexterm><primary>prefix</primary></indexterm> | |
1908 | <term><literal>prefix</literal></term> | |
1909 | <listitem> | |
1910 | <para>Specifies the common prefix of all headers | |
1911 | when generating BoostBook XML. Everything before | |
1912 | this will be stripped off. | |
1913 | </para> | |
1914 | </listitem> | |
1915 | </varlistentry> | |
1916 | ||
1917 | <varlistentry> | |
1918 | <indexterm><primary>reftitle</primary></indexterm> | |
1919 | <term><literal>reftitle</literal></term> | |
1920 | <listitem> | |
1921 | <para>Specifies the title of the library-reference section, | |
1922 | when generating BoostBook XML.</para> | |
1923 | </listitem> | |
1924 | </varlistentry> | |
1925 | ||
1926 | <varlistentry> | |
1927 | <indexterm><primary>doxygen:xml-imagedir</primary></indexterm> | |
1928 | <term><literal>doxygen:xml-imagedir</literal></term> | |
1929 | <listitem> | |
1930 | <para>When generating BoostBook XML, specifies the | |
1931 | directory in which to place the images generated | |
1932 | from LaTex formulae.</para> | |
1933 | <warning><para>The path is interpreted relative to the | |
1934 | current working directory, not relative to the Jamfile. | |
1935 | This is necessary to match the behavior of BoostBook. | |
1936 | </para></warning> | |
1937 | </listitem> | |
1938 | </varlistentry> | |
1939 | ||
1940 | </variablelist> | |
1941 | ||
1942 | <para>The doxygen module defines a rule for creating a target | |
1943 | following the common syntax.</para> | |
1944 | ||
1945 | <variablelist> | |
1946 | ||
1947 | <varlistentry> | |
1948 | <indexterm><primary>doxygen</primary><secondary>rule</secondary></indexterm> | |
1949 | <term><literal>doxygen</literal></term> | |
1950 | <listitem> | |
1951 | <programlisting> | |
1952 | rule doxygen ( target : sources * : requirements * : default-build * : usage-requirements * ) | |
1953 | </programlisting> | |
1954 | <para>Creates a doxygen target. If the target name | |
1955 | ends with .html, then this will generate an html | |
1956 | directory. Otherwise it will generate BoostBook XML. | |
1957 | </para> | |
1958 | </listitem> | |
1959 | </varlistentry> | |
1960 | ||
1961 | </variablelist> | |
1962 | ||
1963 | </section> | |
1964 | ||
1965 | <section id="bbv2.reference.tools.doc.quickbook"> | |
1966 | <title>quickbook</title> | |
1967 | <indexterm><primary>quickbook</primary></indexterm> | |
1968 | ||
1969 | <para>The quickbook module provides a generator to convert from | |
1970 | Quickbook to BoostBook XML.</para> | |
1971 | ||
1972 | <para>To use quickbook, you first need to configure it using the following syntax:</para> | |
1973 | <programlisting> | |
1974 | using quickbook : <optional><replaceable>command</replaceable></optional> ; | |
1975 | </programlisting> | |
1976 | <para> | |
1977 | <replaceable>command</replaceable> is the quickbook executable. | |
1978 | If it is not specified, Boost.Build will compile it from source. | |
1979 | If it is unable to find the source it will search for a quickbook | |
1980 | executable in PATH. | |
1981 | </para> | |
1982 | ||
1983 | </section> | |
1984 | ||
1985 | <section id="bbv2.reference.tools.doc.fop"> | |
1986 | <title>fop</title> | |
1987 | <indexterm><primary>fop</primary></indexterm> | |
1988 | ||
1989 | <para>The fop module provides generators to convert from | |
1990 | XSL formatting objects to Postscript and PDF.</para> | |
1991 | ||
1992 | <para>To use fop, you first need to configure it using the following syntax:</para> | |
1993 | <programlisting> | |
1994 | using fop : <optional><replaceable>fop-command</replaceable></optional> : <optional><replaceable>java-home</replaceable></optional> : <optional><replaceable>java</replaceable></optional> ; | |
1995 | </programlisting> | |
1996 | <para> | |
1997 | <replaceable>fop-command</replaceable> is the command to run fop. | |
1998 | If it is not specified, Boost.Build will search for it in PATH and | |
1999 | FOP_HOME. | |
2000 | </para> | |
2001 | <para> | |
2002 | Either <replaceable>java-home</replaceable> or | |
2003 | <replaceable>java</replaceable> | |
2004 | can be used to specify where to find java. | |
2005 | </para> | |
2006 | ||
2007 | </section> | |
2008 | ||
2009 | </section> | |
2010 | ||
2011 | </section> | |
2012 | ||
2013 | <section id="bbv2.reference.modules"> | |
2014 | <title>Builtin modules</title> | |
2015 | ||
2016 | <para> | |
2017 | This section describes the modules that are provided | |
2018 | by Boost.Build. The import rule allows rules from | |
2019 | one module to be used in another module or Jamfile. | |
2020 | </para> | |
2021 | ||
2022 | <section id="bbv2.reference.modules.modules"> | |
2023 | <title>modules</title> | |
2024 | <indexterm><primary>modules</primary></indexterm> | |
2025 | ||
2026 | <para> | |
2027 | The <code>modules</code> module defines basic functionality | |
2028 | for handling modules. | |
2029 | </para> | |
2030 | ||
2031 | <para> | |
2032 | A module defines a number of rules that can be used in other | |
2033 | modules. Modules can contain code at the top level to initialize | |
2034 | the module. This code is executed the first time the | |
2035 | module is loaded. | |
2036 | <note> | |
2037 | <para> | |
2038 | A Jamfile is a special kind of module which is managed by | |
2039 | the build system. Although they cannot be loaded directly | |
2040 | by users, the other features of modules are still useful | |
2041 | for Jamfiles. | |
2042 | </para> | |
2043 | </note> | |
2044 | </para> | |
2045 | ||
2046 | <para> | |
2047 | Each module has its own namespaces for variables and rules. If two | |
2048 | modules A and B both use a variable named X, each one gets its own | |
2049 | copy of X. They won't interfere with each other in any way. | |
2050 | Similarly, importing rules into one module has no effect on any other | |
2051 | module. | |
2052 | </para> | |
2053 | ||
2054 | <para> | |
2055 | Every module has two special variables. | |
2056 | <code>$(__file__)</code> contains the name of the file that | |
2057 | the module was loaded from and <code>$(__name__)</code> | |
2058 | contains the name of the module. | |
2059 | <note><para><code>$(__file__)</code> does not contain | |
2060 | the full path to the file. If you need this, use | |
2061 | <code>modules.binding</code>.</para></note> | |
2062 | </para> | |
2063 | ||
2064 | <orderedlist> | |
2065 | ||
2066 | <listitem id="bbv2.reference.modules.modules.binding"> | |
2067 | <indexterm zone="bbv2.reference.modules.modules.binding"><primary>binding</primary></indexterm> | |
2068 | <code language="jam">rule binding ( module-name )</code> | |
2069 | <para>Returns the filesystem binding of the given module.</para> | |
2070 | <para>For example, a module can get its own location with: | |
2071 | <programlisting language="jam">me = [ modules.binding $(__name__) ] ;</programlisting> | |
2072 | </para> | |
2073 | </listitem> | |
2074 | ||
2075 | <listitem id="bbv2.reference.modules.modules.poke"> | |
2076 | <indexterm zone="bbv2.reference.modules.modules.poke"><primary>poke</primary></indexterm> | |
2077 | <code language="jam">rule poke ( module-name ? : variables + : value * )</code> | |
2078 | <para>Sets the module-local value of a variable.</para> | |
2079 | <para>For example, to set a variable in the global module: | |
2080 | <programlisting language="jam">modules.poke : ZLIB_INCLUDE : /usr/local/include ;</programlisting> | |
2081 | </para> | |
2082 | </listitem> | |
2083 | ||
2084 | <listitem id="bbv2.reference.modules.modules.peek"> | |
2085 | <indexterm zone="bbv2.reference.modules.modules.peek"><primary>peek</primary></indexterm> | |
2086 | <code language="jam">rule peek ( module-name ? : variables + )</code> | |
2087 | <para>Returns the module-local value of a variable.</para> | |
2088 | <para> | |
2089 | For example, to read a variable from the global module: | |
2090 | <programlisting language="jam">local ZLIB_INCLUDE = [ modules.peek : ZLIB_INCLUDE ] ;</programlisting> | |
2091 | </para> | |
2092 | </listitem> | |
2093 | ||
2094 | <listitem id="bbv2.reference.modules.modules.call-in"> | |
2095 | <indexterm zone="bbv2.reference.modules.modules.call-in"><primary>call-in</primary></indexterm> | |
2096 | <code language="jam">rule call-in ( module-name ? : rule-name args * : * ) </code> | |
2097 | <para>Call the given rule locally in the given module. Use | |
2098 | this for rules accepting rule names as arguments, so that | |
2099 | the passed rule may be invoked in the context of the rule's | |
2100 | caller (for example, if the rule accesses module globals or | |
2101 | is a local rule). | |
2102 | <note><para>rules called this way may accept at most | |
2103 | 8 parameters.</para></note></para> | |
2104 | <para>Example: | |
2105 | <programlisting language="jam"> | |
2106 | rule filter ( f : values * ) | |
2107 | { | |
2108 | local m = [ CALLER_MODULE ] ; | |
2109 | local result ; | |
2110 | for v in $(values) | |
2111 | { | |
2112 | if [ modules.call-in $(m) : $(f) $(v) ] | |
2113 | { | |
2114 | result += $(v) ; | |
2115 | } | |
2116 | } | |
2117 | return result ; | |
2118 | } | |
2119 | </programlisting> | |
2120 | </para> | |
2121 | </listitem> | |
2122 | ||
2123 | <listitem id="bbv2.reference.modules.modules.load"> | |
2124 | <indexterm zone="bbv2.reference.modules.modules.load"><primary>load</primary></indexterm> | |
2125 | <code language="jam">rule load ( module-name : filename ? : search * )</code> | |
2126 | <para>Load the indicated module if it is not already loaded.</para> | |
2127 | <variablelist> | |
2128 | <varlistentry> | |
2129 | <term><literal>module-name</literal></term> | |
2130 | <listitem><para>Name of module to load.</para></listitem> | |
2131 | </varlistentry> | |
2132 | </variablelist> | |
2133 | <variablelist> | |
2134 | <varlistentry> | |
2135 | <term><literal>filename</literal></term> | |
2136 | <listitem><para>(partial) path to file; Defaults to <code>$(module-name).jam</code></para></listitem> | |
2137 | </varlistentry> | |
2138 | </variablelist> | |
2139 | <variablelist> | |
2140 | <varlistentry> | |
2141 | <term><literal>search</literal></term> | |
2142 | <listitem><para>Directories in which to search for filename. | |
2143 | Defaults to <code>$(BOOST_BUILD_PATH)</code>.</para></listitem> | |
2144 | </varlistentry> | |
2145 | </variablelist> | |
2146 | </listitem> | |
2147 | ||
2148 | <listitem id="bbv2.reference.modules.modules.import"> | |
2149 | <indexterm zone="bbv2.reference.modules.modules.import"><primary>import</primary></indexterm> | |
2150 | <code language="jam">rule import ( module-names + : rules-opt * : rename-opt * )</code> | |
2151 | <para>Load the indicated module and import rule names into the | |
2152 | current module. Any members of <code>rules-opt</code> will be | |
2153 | available without qualification in the caller's module. Any | |
2154 | members of <code>rename-opt</code> will be taken as the names | |
2155 | of the rules in the caller's module, in place of the names they | |
2156 | have in the imported module. If <code>rules-opt = '*'</code>, | |
2157 | all rules from the indicated module are imported into the | |
2158 | caller's module. If <code>rename-opt</code> is supplied, it must have the | |
2159 | same number of elements as <code>rules-opt</code>.</para> | |
2160 | <note><para>The <literal>import</literal> rule is available | |
2161 | without qualification in all modules.</para></note> | |
2162 | <para>Examples: | |
2163 | <programlisting language="jam"> | |
2164 | import path ; | |
2165 | import path : * ; | |
2166 | import path : join ; | |
2167 | import path : native make : native-path make-path ; | |
2168 | </programlisting> | |
2169 | </para> | |
2170 | </listitem> | |
2171 | ||
2172 | <listitem id="bbv2.reference.modules.modules.clone-rules"> | |
2173 | <indexterm zone="bbv2.reference.modules.modules.clone-rules"><primary>clone-rules</primary></indexterm> | |
2174 | <code language="jam">rule clone-rules ( source-module target-module )</code> | |
2175 | <para>Define exported copies in <code>$(target-module)</code> | |
2176 | of all rules exported from <code>$(source-module)</code>. Also | |
2177 | make them available in the global module with qualification, | |
2178 | so that it is just as though the rules were defined originally | |
2179 | in <code>$(target-module)</code>.</para> | |
2180 | </listitem> | |
2181 | ||
2182 | </orderedlist> | |
2183 | ||
2184 | </section> | |
2185 | ||
2186 | <xi:include href="path.xml"/> | |
2187 | <xi:include href="regex.xml"/> | |
2188 | <xi:include href="sequence.xml"/> | |
2189 | <xi:include href="type.xml"/> | |
2190 | ||
2191 | </section> | |
2192 | ||
2193 | <section id="bbv2.reference.class"> | |
2194 | <title>Builtin classes</title> | |
2195 | <xi:include href="abstract-target.xml"/> | |
2196 | <xi:include href="project-target.xml"/> | |
2197 | <xi:include href="main-target.xml"/> | |
2198 | <xi:include href="basic-target.xml"/> | |
2199 | <xi:include href="typed-target.xml"/> | |
2200 | <xi:include href="property-set.xml"/> | |
2201 | </section> | |
2202 | ||
2203 | <section id="bbv2.reference.buildprocess"> | |
2204 | <title>Build process</title> | |
2205 | ||
2206 | <para>The general overview of the build process was given in the | |
2207 | <link linkend="bbv2.overview.build_process">user documentation</link>. | |
2208 | This section provides additional details, and some specific rules. | |
2209 | </para> | |
2210 | ||
2211 | <para>To recap, building a target with specific properties includes the | |
2212 | following steps: | |
2213 | <orderedlist> | |
2214 | ||
2215 | <listitem><para>applying default build,</para></listitem> | |
2216 | ||
2217 | <listitem><para>selecting the main target alternative to use, | |
2218 | </para></listitem> | |
2219 | ||
2220 | <listitem><para>determining "common" properties,</para></listitem> | |
2221 | ||
2222 | <listitem><para>building targets referred by the sources list and | |
2223 | dependency properties,</para></listitem> | |
2224 | ||
2225 | <listitem><para>adding the usage requirements produces when building | |
2226 | dependencies to the "common" properties,</para></listitem> | |
2227 | ||
2228 | <listitem><para>building the target using generators,</para></listitem> | |
2229 | ||
2230 | <listitem><para>computing the usage requirements to be returned.</para></listitem> | |
2231 | ||
2232 | </orderedlist> | |
2233 | </para> | |
2234 | ||
2235 | <section id="bbv2.reference.buildprocess.alternatives"> | |
2236 | <title>Alternative selection</title> | |
2237 | ||
2238 | <para>When there are several alternatives, one of them must be | |
2239 | selected. The process is as follows:</para> | |
2240 | ||
2241 | <orderedlist> | |
2242 | <listitem> | |
2243 | <simpara> | |
2244 | For each alternative <emphasis>condition</emphasis> is defined as | |
2245 | the set of base properties in requirements. [Note: it might be | |
2246 | better to specify the condition explicitly, as in conditional | |
2247 | requirements]. | |
2248 | </simpara> | |
2249 | </listitem> | |
2250 | ||
2251 | <listitem> | |
2252 | <simpara> | |
2253 | An alternative is viable only if all properties in condition | |
2254 | are present in build request. | |
2255 | </simpara> | |
2256 | </listitem> | |
2257 | ||
2258 | <listitem> | |
2259 | <simpara> | |
2260 | If there's one viable alternative, it's choosen. Otherwise, | |
2261 | an attempt is made to find one best alternative. An alternative | |
2262 | a is better than another alternative b, if the set of properties | |
2263 | in b's condition is a strict subset of the set of properties of | |
2264 | 'a's condition. If there's one viable alternative, which is | |
2265 | better than all others, it's selected. Otherwise, an error is | |
2266 | reported. | |
2267 | </simpara> | |
2268 | </listitem> | |
2269 | </orderedlist> | |
2270 | ||
2271 | </section> | |
2272 | ||
2273 | <section id="bbv2.reference.buildprocess.common"> | |
2274 | <title>Determining common properties</title> | |
2275 | ||
2276 | <para>The "common" properties is a somewhat artificial term. Those are | |
2277 | the intermediate property set from which both the build request for | |
2278 | dependencies and properties for building the target are derived. | |
2279 | </para> | |
2280 | ||
2281 | <para>Since default build and alternatives are already handled, we have | |
2282 | only two inputs: build requests and requirements. Here are the rules | |
2283 | about common properties. | |
2284 | </para> | |
2285 | ||
2286 | <orderedlist> | |
2287 | <listitem><para>Non-free feature can have only one | |
2288 | value</para></listitem> | |
2289 | ||
2290 | <listitem><para>A non-conditional property in requirement in always | |
2291 | present in common properties.</para></listitem> | |
2292 | ||
2293 | <listitem><para>A property in build request is present in | |
2294 | common properties, unless (2) tells otherwise.</para></listitem> | |
2295 | ||
2296 | <listitem><para>If either build request, or requirements (non-conditional | |
2297 | or conditional) include an expandable property (either composite, | |
2298 | or property with specified subfeature value), the behaviour is | |
2299 | equivalent to explicitly adding all expanded properties to build | |
2300 | request or requirements.</para></listitem> | |
2301 | ||
2302 | <listitem><para>If requirements include a conditional property, and | |
2303 | condition of this property is true in context of common | |
2304 | properties, then the conditional property should be in common | |
2305 | properties as well.</para></listitem> | |
2306 | ||
2307 | <listitem><para>If no value for a feature is given by other rules | |
2308 | here, it has default value in common properties.</para></listitem> | |
2309 | </orderedlist> | |
2310 | ||
2311 | <para>Those rules are declarative, they don't specify how to compute the | |
2312 | common properties. However, they provide enough information for the | |
2313 | user. The important point is the handling of conditional | |
2314 | requirements. The condition can be satisfied either by property in | |
2315 | build request, by non-conditional requirements, or even by another | |
2316 | conditional property. For example, the following example works as | |
2317 | expected: | |
2318 | <programlisting> | |
2319 | exe a : a.cpp | |
2320 | : <toolset>gcc:<variant>release | |
2321 | <variant>release:<define>FOO ; | |
2322 | </programlisting> | |
2323 | </para> | |
2324 | ||
2325 | </section> | |
2326 | ||
2327 | <section id="bbv2.reference.buildprocess.targetpath"> | |
2328 | <title>Target Paths</title> | |
2329 | <indexterm><primary>path</primary><secondary>for targets</secondary></indexterm> | |
2330 | ||
2331 | <para>Several factors determine the location of a concrete | |
2332 | file target. All files in a project are built under | |
2333 | the directory bin unless this is overridden by the build-dir project | |
2334 | attribute. Under bin is a path that depends on the properties | |
2335 | used to build each target. This path is uniquely determined by | |
2336 | all non-free, non-incidental properties. For example, | |
2337 | given a property set containing: | |
2338 | <code><toolset>gcc <toolset-gcc:version>4.6.1 <variant>debug | |
2339 | <warnings>all <define>_DEBUG <include>/usr/local/include | |
2340 | <link>static</code>, | |
2341 | the path will be gcc-4.6.1/debug/link-static. <warnings> is an | |
2342 | incidental feature and <define> and <include> are | |
2343 | free features, so they do not affect the path.</para> | |
2344 | ||
2345 | <para>Sometimes the paths produced by Boost.Build can become excessively | |
2346 | long. There are a couple of command line options that can help with this. | |
2347 | --abbreviate-paths reduces each element to no more than five characters. | |
2348 | For example, link-static becomes lnk-sttc. The --hash option reduces the | |
2349 | path to a single directory using an MD5 hash.</para> | |
2350 | ||
2351 | <para>There are two features that affect the build | |
2352 | directory. The <location> feature completely | |
2353 | overrides the default build directory. For example, | |
2354 | <programlisting>exe a : a.cpp : <location>. ;</programlisting> | |
2355 | builds all the files produced by <code>a</code> | |
2356 | in the directory of the Jamfile. This is generally | |
2357 | discouraged, as it precludes variant builds.</para> | |
2358 | ||
2359 | <para>The <location-prefix> feature adds a | |
2360 | prefix to the path, under the project's build | |
2361 | directory. For example, | |
2362 | <programlisting>exe a : a.cpp : <location-prefix>subdir ;</programlisting> | |
2363 | will create the files for <code>a</code> in bin/subdir/gcc-4.6.1/debug</para> | |
2364 | ||
2365 | </section> | |
2366 | ||
2367 | </section> | |
2368 | ||
2369 | ||
2370 | ||
2371 | <section id="bbv2.reference.definitions"> | |
2372 | ||
2373 | <title>Definitions</title> | |
2374 | ||
2375 | <section id="bbv2.reference.features"> | |
2376 | <title>Features and properties</title> | |
2377 | ||
2378 | <para>A <emphasis>feature</emphasis> is a normalized (toolset-independent) | |
2379 | aspect of a build configuration, such as whether inlining is | |
2380 | enabled. Feature names may not contain the '<literal>></literal>' | |
2381 | character.</para> | |
2382 | ||
2383 | <!-- | |
2384 | And what about dash? | |
2385 | --> | |
2386 | ||
2387 | <para>Each feature in a build configuration has one or more | |
2388 | associated <emphasis>value</emphasis>s. Feature values for non-free features | |
2389 | may not contain the '<literal><</literal>', '<literal>:</literal>', or | |
2390 | '<literal>=</literal>' characters. Feature values for free features may not | |
2391 | contain the '<literal><</literal>' character.</para> | |
2392 | ||
2393 | <para>A <emphasis>property</emphasis> is a (feature,value) pair, expressed as | |
2394 | <feature>value.</para> | |
2395 | ||
2396 | <para>A <emphasis>subfeature</emphasis> is a feature that only exists in the | |
2397 | presence of its parent feature, and whose identity can be derived | |
2398 | (in the context of its parent) from its value. A subfeature's | |
2399 | parent can never be another subfeature. Thus, features and their | |
2400 | subfeatures form a two-level hierarchy.</para> | |
2401 | ||
2402 | <para>A <emphasis>value-string</emphasis> for a feature <emphasis role="bold">F</emphasis> is a string of | |
2403 | the form | |
2404 | <literal>value-subvalue1-subvalue2</literal>...<literal>-subvalueN</literal>, where | |
2405 | <literal>value</literal> is a legal value for <emphasis role="bold">F</emphasis> and | |
2406 | <literal>subvalue1</literal>...<literal>subvalueN</literal> are legal values of some | |
2407 | of <emphasis role="bold">F</emphasis>'s subfeatures. For example, the properties | |
2408 | <literal><toolset>gcc <toolset-version>3.0.1</literal> can be | |
2409 | expressed more concisely using a value-string, as | |
2410 | <literal><toolset>gcc-3.0.1</literal>.</para> | |
2411 | ||
2412 | <para>A <emphasis>property set</emphasis> is a set of properties (i.e. a | |
2413 | collection without duplicates), for instance: | |
2414 | <literal><toolset>gcc <runtime-link>static</literal>.</para> | |
2415 | ||
2416 | <para>A <emphasis>property path</emphasis> is a property set whose elements have | |
2417 | been joined into a single string separated by slashes. A property | |
2418 | path representation of the previous example would be | |
2419 | <literal><toolset>gcc/<runtime-link>static</literal>.</para> | |
2420 | ||
2421 | <para>A <emphasis>build specification</emphasis> is a property set that fully | |
2422 | describes the set of features used to build a target.</para> | |
2423 | ||
2424 | <section id="bbv2.reference.features.validity"> | |
2425 | <title>Property Validity</title> | |
2426 | ||
2427 | <para> | |
2428 | For <link linkend= | |
2429 | "bbv2.reference.features.attributes.free">free</link> | |
2430 | features, all values are valid. For all other features, | |
2431 | the valid values are explicitly specified, and the build | |
2432 | system will report an error for the use of an invalid | |
2433 | feature-value. Subproperty validity may be restricted so | |
2434 | that certain values are valid only in the presence of | |
2435 | certain other subproperties. For example, it is possible | |
2436 | to specify that the <code><gcc-target>mingw</code> | |
2437 | property is only valid in the presence of | |
2438 | <code><gcc-version>2.95.2</code>. | |
2439 | </para> | |
2440 | ||
2441 | </section> | |
2442 | <section id="bbv2.reference.features.attributes"> | |
2443 | <title>Feature Attributes</title> | |
2444 | ||
2445 | <para>Each feature has a collection of zero or more of the following | |
2446 | attributes. Feature attributes are low-level descriptions of how the | |
2447 | build system should interpret a feature's values when they appear in | |
2448 | a build request. We also refer to the attributes of properties, so | |
2449 | that an <emphasis>incidental</emphasis> property, for example, is | |
2450 | one whose feature has the <emphasis>incidental</emphasis> | |
2451 | attribute.</para> | |
2452 | ||
2453 | <itemizedlist> | |
2454 | <listitem> | |
2455 | <para><emphasis>incidental</emphasis></para> | |
2456 | ||
2457 | <para>Incidental features are assumed not to affect build | |
2458 | products at all. As a consequence, the build system may use | |
2459 | the same file for targets whose build specification differs | |
2460 | only in incidental features. A feature that controls a | |
2461 | compiler's warning level is one example of a likely | |
2462 | incidental feature.</para> | |
2463 | ||
2464 | <para>Non-incidental features are assumed to affect build | |
2465 | products, so the files for targets whose build specification | |
2466 | differs in non-incidental features are placed in different | |
2467 | directories as described in <xref linkend="bbv2.reference.buildprocess.targetpath"/>. | |
2468 | </para> | |
2469 | </listitem> | |
2470 | ||
2471 | <listitem> | |
2472 | <para> | |
2473 | <anchor id="bbv2.reference.features.attributes.propagated"/> | |
2474 | <emphasis>propagated</emphasis> | |
2475 | </para> | |
2476 | ||
2477 | <para>Features of this kind are | |
2478 | propagated to dependencies. That is, if a <link linkend= | |
2479 | "bbv2.overview.targets.main">main target</link> is built using a | |
2480 | propagated | |
2481 | property, the build systems attempts to use the same property | |
2482 | when building any of its dependencies as part of that main | |
2483 | target. For instance, when an optimized executable is | |
2484 | requested, one usually wants it to be linked with optimized | |
2485 | libraries. Thus, the <literal><optimization></literal> feature is | |
2486 | propagated.</para> | |
2487 | </listitem> | |
2488 | ||
2489 | <listitem> | |
2490 | <para> | |
2491 | <anchor id="bbv2.reference.features.attributes.free"/> | |
2492 | <emphasis>free</emphasis> | |
2493 | </para> | |
2494 | ||
2495 | <para>Most features have a finite set of allowed values, and can | |
2496 | only take on a single value from that set in a given build | |
2497 | specification. Free features, on the other hand, can have | |
2498 | several values at a time and each value can be an arbitrary | |
2499 | string. For example, it is possible to have several | |
2500 | preprocessor symbols defined simultaneously:</para> | |
2501 | ||
2502 | <programlisting> | |
2503 | <define>NDEBUG=1 <define>HAS_CONFIG_H=1 | |
2504 | </programlisting> | |
2505 | ||
2506 | </listitem> | |
2507 | ||
2508 | <listitem> | |
2509 | <para><emphasis>optional</emphasis></para> | |
2510 | ||
2511 | <para>An optional feature is a feature that is not required to | |
2512 | appear in a build specification. Every non-optional non-free | |
2513 | feature has a default value that is used when a value for | |
2514 | the feature is not otherwise specified, either in a target's | |
2515 | requirements or in the user's build request. [A feature's | |
2516 | default value is given by the first value listed in the | |
2517 | feature's declaration. -- move this elsewhere - dwa]</para> | |
2518 | </listitem> | |
2519 | ||
2520 | <listitem> | |
2521 | <para><emphasis>symmetric</emphasis></para> | |
2522 | ||
2523 | <para>Normally a feature only generates a subvariant directory | |
2524 | when its value differs from its default value, | |
2525 | leading to an asymmetric subvariant directory structure for | |
2526 | certain values of the feature. A symmetric feature | |
2527 | always generates a corresponding | |
2528 | subvariant directory.</para> | |
2529 | </listitem> | |
2530 | ||
2531 | <listitem> | |
2532 | <para><emphasis>path</emphasis></para> | |
2533 | ||
2534 | <para>The value of a path feature specifies a path. The path is | |
2535 | treated as relative to the directory of Jamfile where path | |
2536 | feature is used and is translated appropriately by the build | |
2537 | system when the build is invoked from a different | |
2538 | directory</para> | |
2539 | </listitem> | |
2540 | ||
2541 | <listitem> | |
2542 | <para><emphasis>implicit</emphasis></para> | |
2543 | ||
2544 | <para>Values of implicit features alone identify the feature. | |
2545 | For example, a user is not required to write | |
2546 | "<toolset>gcc", but can simply write "gcc". Implicit | |
2547 | feature names also don't appear in variant paths, although | |
2548 | the values do. Thus: bin/gcc/... as opposed to | |
2549 | bin/toolset-gcc/.... There should typically be only a few | |
2550 | such features, to avoid possible name clashes.</para> | |
2551 | </listitem> | |
2552 | ||
2553 | <listitem> | |
2554 | <para><emphasis>composite</emphasis></para> | |
2555 | ||
2556 | <para>Composite features actually correspond to groups of | |
2557 | properties. For example, a build variant is a composite | |
2558 | feature. When generating targets from a set of build | |
2559 | properties, composite features are recursively expanded and | |
2560 | <emphasis>added</emphasis> to the build property set, so rules can find | |
2561 | them if necessary. Non-composite non-free features override | |
2562 | components of composite features in a build property set.</para> | |
2563 | </listitem> | |
2564 | ||
2565 | <listitem> | |
2566 | <para><emphasis>dependency</emphasis></para> | |
2567 | ||
2568 | <para>The value of a dependency feature is a target reference. | |
2569 | When used for building of a main target, the value of | |
2570 | dependency feature is treated as additional dependency.</para> | |
2571 | ||
2572 | <para>For example, dependency features allow to state that | |
2573 | library A depends on library B. As the result, whenever an | |
2574 | application will link to A, it will also link to B. | |
2575 | Specifying B as dependency of A is different from adding B to | |
2576 | the sources of A. <!-- Need to clarify this. --></para> | |
2577 | </listitem> | |
2578 | </itemizedlist> | |
2579 | ||
2580 | <para>Features that are neither free nor incidental are called | |
2581 | <emphasis>base</emphasis> features.</para> | |
2582 | ||
2583 | ||
2584 | </section> | |
2585 | <section id="bbv2.reference.features.declaration"> | |
2586 | <title>Feature Declaration</title> | |
2587 | ||
2588 | <para>The low-level feature declaration interface is the | |
2589 | <literal>feature</literal> rule from the | |
2590 | <literal>feature</literal> module: | |
2591 | ||
2592 | <programlisting> | |
2593 | rule feature ( name : allowed-values * : attributes * ) | |
2594 | </programlisting> | |
2595 | ||
2596 | A feature's allowed-values may be extended with the | |
2597 | <code>feature.extend</code> rule. | |
2598 | </para> | |
2599 | ||
2600 | </section> | |
2601 | </section> | |
2602 | ||
2603 | <section id="bbv2.reference.variants.proprefine"> | |
2604 | <title>Property refinement</title> | |
2605 | ||
2606 | <para>When a target with certain properties is requested, and that | |
2607 | target requires some set of properties, it is needed to find the | |
2608 | set of properties to use for building. This process is called | |
2609 | <emphasis>property refinement</emphasis> and is performed by these rules</para> | |
2610 | ||
2611 | <orderedlist> | |
2612 | ||
2613 | <listitem> | |
2614 | <simpara> | |
2615 | Each property in the required set is added to the original | |
2616 | property set | |
2617 | </simpara> | |
2618 | </listitem> | |
2619 | ||
2620 | <listitem> | |
2621 | <simpara> | |
2622 | If the original property set includes property with a different | |
2623 | value of non free feature, that property is removed. | |
2624 | </simpara> | |
2625 | </listitem> | |
2626 | </orderedlist> | |
2627 | </section> | |
2628 | ||
2629 | <section id="bbv2.reference.variants.propcond"> | |
2630 | <title>Conditional properties</title> | |
2631 | ||
2632 | <para>Sometime it's desirable to apply certain requirements only for | |
2633 | a specific combination of other properties. For example, one of | |
2634 | compilers that you use issues a pointless warning that you want to | |
2635 | suppress by passing a command line option to it. You would not | |
2636 | want to pass that option to other compilers. Conditional | |
2637 | properties allow you to do just that. Their syntax is:</para> | |
2638 | ||
2639 | <programlisting> | |
2640 | property ( "," property ) * ":" property | |
2641 | </programlisting> | |
2642 | ||
2643 | <para> | |
2644 | For example, the problem above would be solved by: | |
2645 | ||
2646 | <programlisting> | |
2647 | exe hello : hello.cpp : <toolset>yfc:<cxxflags>-disable-pointless-warning ; | |
2648 | </programlisting> | |
2649 | </para> | |
2650 | ||
2651 | <para>The syntax also allows several properties in the condition, for | |
2652 | example: | |
2653 | <programlisting> | |
2654 | exe hello : hello.cpp : <os>NT,<toolset>gcc:<link>static ; | |
2655 | </programlisting> | |
2656 | </para> | |
2657 | ||
2658 | </section> | |
2659 | ||
2660 | <section id="bbv2.reference.ids"> | |
2661 | <title>Target identifiers and references</title> | |
2662 | ||
2663 | <para><emphasis>Target identifier</emphasis> is used to denote a | |
2664 | target. The syntax is:</para> | |
2665 | ||
2666 | <programlisting> | |
2667 | target-id -> (target-name | file-name | project-id | directory-name) | |
2668 | | (project-id | directory-name) "//" target-name | |
2669 | project-id -> path | |
2670 | target-name -> path | |
2671 | file-name -> path | |
2672 | directory-name -> path | |
2673 | </programlisting> | |
2674 | ||
2675 | <para> | |
2676 | This grammar allows some elements to be recognized as either | |
2677 | ||
2678 | <itemizedlist> | |
2679 | <listitem> | |
2680 | <simpara> | |
2681 | name of target declared in current Jamfile (note that target | |
2682 | names may include slash). | |
2683 | </simpara> | |
2684 | </listitem> | |
2685 | ||
2686 | <listitem> | |
2687 | <simpara> | |
2688 | a regular file, denoted by absolute name or name relative to | |
2689 | project's sources location. | |
2690 | </simpara> | |
2691 | </listitem> | |
2692 | ||
2693 | <listitem> | |
2694 | <simpara> | |
2695 | project id (at this point, all project ids start with slash). | |
2696 | </simpara> | |
2697 | </listitem> | |
2698 | ||
2699 | <listitem> | |
2700 | <simpara> | |
2701 | the directory of another project, denoted by absolute name | |
2702 | or name relative to the current project's location. | |
2703 | </simpara> | |
2704 | </listitem> | |
2705 | </itemizedlist> | |
2706 | ||
2707 | To determine the real meaning the possible interpretations | |
2708 | are checked in this order. For example, valid target ids might be: | |
2709 | ||
2710 | <screen> | |
2711 | a -- target in current project | |
2712 | lib/b.cpp -- regular file | |
2713 | /boost/thread -- project "/boost/thread" | |
2714 | /home/ghost/build/lr_library//parser -- target in specific project | |
2715 | ../boost_1_61_0 -- project in specific directory | |
2716 | </screen> | |
2717 | ||
2718 | </para> | |
2719 | ||
2720 | <para><emphasis role="bold">Rationale:</emphasis>Target is separated from project by special | |
2721 | separator (not just slash), because:</para> | |
2722 | ||
2723 | <itemizedlist> | |
2724 | <listitem> | |
2725 | <simpara> | |
2726 | It emphasis that projects and targets are different things. | |
2727 | </simpara> | |
2728 | </listitem> | |
2729 | ||
2730 | <listitem> | |
2731 | <simpara> | |
2732 | It allows to have main target names with slashes. | |
2733 | ||
2734 | <!-- The motivation for which is: | |
2735 | ||
2736 | So, to summarize: | |
2737 | ||
2738 | 1. The project that extract tarfile may extract all possible kinds | |
2739 | of targets, and it's reasonable to use them directly from other | |
2740 | project. | |
2741 | ||
2742 | 2. The rule for unpacking tar is implemented in terms of | |
2743 | "patch-file", for maintainability, and therefore, must use main | |
2744 | target name that contains slashes? | |
2745 | ||
2746 | 3. Using sub-Jamfile in "foo" to declare extracted file "foo/b" is | |
2747 | not an option, because you should not change existing tree | |
2748 | ||
2749 | That makes good rationale for why main target must contain names. | |
2750 | --> | |
2751 | </simpara> | |
2752 | </listitem> | |
2753 | </itemizedlist> | |
2754 | ||
2755 | <para id="bbv2.reference.targets.references"> | |
2756 | <emphasis>Target reference</emphasis> is used to | |
2757 | specify a source target, and may additionally specify desired | |
2758 | properties for that target. It has this syntax:</para> | |
2759 | ||
2760 | <programlisting> | |
2761 | target-reference -> target-id [ "/" requested-properties ] | |
2762 | requested-properties -> property-path | |
2763 | </programlisting> | |
2764 | ||
2765 | <para> | |
2766 | For example, | |
2767 | ||
2768 | <programlisting> | |
2769 | exe compiler : compiler.cpp libs/cmdline/<optimization>space ; | |
2770 | </programlisting> | |
2771 | ||
2772 | would cause the version of <literal>cmdline</literal> library, | |
2773 | optimized for space, to be linked in even if the | |
2774 | <literal>compiler</literal> executable is build with optimization for | |
2775 | speed. | |
2776 | </para> | |
2777 | </section> | |
2778 | ||
2779 | </section> | |
2780 | ||
2781 | </chapter> | |
2782 | ||
2783 | <!-- | |
2784 | Local Variables: | |
2785 | mode: nxml | |
2786 | sgml-indent-data: t | |
2787 | sgml-parent-document: ("userman.xml" "chapter") | |
2788 | sgml-set-face: t | |
2789 | End: | |
2790 | --> |