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"
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>">
10 <chapter id=
"bbv2.reference"
11 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
12 <title>Reference
</title>
14 <section id=
"bbv2.reference.general">
15 <title>General information
</title>
17 <section id=
"bbv2.reference.init">
18 <title>Initialization
</title>
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
31 rule boost-build ( location ? )
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:
46 boost-build build-system ;
49 In this case, running
<command>b2
</command> anywhere in the project tree will
50 automatically find the build system.
</para>
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>
59 <section id=
"bbv2.reference.rules">
60 <title>Builtin rules
</title>
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>
68 <term><literal>exe
</literal></term>
70 <listitem><para>Creates an executable file. See
71 <xref linkend=
"bbv2.tasks.programs"/>.
</para></listitem>
75 <term><literal>lib
</literal></term>
77 <listitem><para>Creates an library file. See
78 <xref linkend=
"bbv2.tasks.libraries"/>.
</para></listitem>
82 <term><literal>install
</literal></term>
84 <listitem><para>Installs built targets and other files. See
85 <xref linkend=
"bbv2.tasks.installing"/>.
</para></listitem>
89 <term><literal>alias
</literal></term>
91 <listitem><para>Creates an alias for other targets. See
92 <xref linkend=
"bbv2.tasks.alias"/>.
</para></listitem>
96 <term><literal>unit-test
</literal></term>
98 <listitem><para>Creates an executable that will be automatically run. See
99 <xref linkend=
"bbv2.builtins.testing"/>.
</para></listitem>
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>
110 <listitem><para>Specialized rules for testing. See
111 <xref linkend=
"bbv2.builtins.testing"/>.
</para></listitem>
114 <varlistentry id=
"bbv2.reference.check-target-builds">
115 <indexterm><primary>check-target-builds
</primary></indexterm>
116 <term><literal>check-target-builds
</literal></term>
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:
124 rule check-target-builds ( target message ? : true-properties * : false-properties * )
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>
131 exe app : app.cpp : [ check-target-builds has_foo
"System has foo" :
<library
>foo :
<define
>FOO_MISSING=
1 ] ;
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>
137 alias foobar : : : : [ check-target-builds has_foo
"System has foo" :
<library
>foo :
<library
>bar ] ;
143 <term><literal>obj
</literal></term>
145 <listitem><para>Creates an object file. Useful when a single source
146 file must be compiled with special properties.
</para></listitem>
150 <term><literal>preprocessed
</literal></term>
151 <indexterm><primary>preprocessed
</primary></indexterm>
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>
157 <varlistentry id=
"bbv2.reference.rules.glob">
158 <term><literal>glob
</literal></term>
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:
164 lib tools : [ glob *.cpp ] ;
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:
171 lib tools : [ glob *.cpp : file_to_exclude.cpp bad*.cpp ] ;
176 <varlistentry id=
"bbv2.reference.glob-tree">
177 <indexterm><primary>glob-tree
</primary></indexterm>
178 <term><literal>glob-tree
</literal></term>
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:
184 ECHO [ glob-tree *.cpp : .svn ] ;
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.
194 <term><literal>project
</literal></term>
196 <listitem><para>Declares project id and attributes, including
197 project requirements. See
<xref linkend=
"bbv2.overview.projects"/>.
202 <term><literal>use-project
</literal></term>
204 <listitem><para>Assigns a symbolic project ID to a project at
205 a given path. This rule must be better documented!
209 <varlistentry id=
"bbv2.reference.rules.explicit">
210 <term><literal>explicit
</literal></term>
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>
221 <term><literal>always
</literal></term>
222 <indexterm><primary>always building a metatarget
</primary></indexterm>
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:
229 exe hello : hello.cpp ;
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>
241 <term><literal>constant
</literal></term>
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.
248 constant VERSION :
1.34.0 ;
254 <term><literal>path-constant
</literal></term>
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:
261 path-constant DATA : data/a.txt ;
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>.
272 <term><literal>build-project
</literal></term>
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.
284 <term><literal>test-suite
</literal></term>
286 <listitem><para>This rule is deprecated and equivalent to
287 <code>alias
</code>.
</para></listitem>
294 <section id=
"bbv2.overview.builtins.features">
295 <title>Builtin features
</title>
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>
301 <indexterm><primary>features
</primary><secondary>builtin
</secondary></indexterm>
304 <varlistentry><term><literal>variant
</literal></term>
305 <indexterm><primary>variant
</primary></indexterm>
309 A feature combining several low-level features, making it easy to
310 request common build configurations.
314 <emphasis role=
"bold">Allowed values:
</emphasis>
315 <literal>debug
</literal>,
<literal>release
</literal>,
316 <literal>profile
</literal>.
320 The value
<literal>debug
</literal> expands to
324 <optimization
>off
<debug-symbols
>on
<inlining
>off
<runtime-debugging
>on
328 The value
<literal>release
</literal> expands to
332 <optimization
>speed
<debug-symbols
>off
<inlining
>full
<runtime-debugging
>off
336 The value
<literal>profile
</literal> expands to the same as
337 <literal>release
</literal>, plus:
341 <profiling
>on
<debug-symbols
>on
345 Users can define their own build variants using the
346 <code>variant
</code> rule from the
<code>common
</code> module.
350 <emphasis role=
"bold">Note:
</emphasis> Runtime debugging is on in
351 debug builds to suit the expectations of people used to various
353 <!-- Define "runtime debugging". Why will those people expect it to
354 be on in debug builds? -->
359 <varlistentry id=
"bbv2.overview.builtins.features.link">
360 <term><literal>link
</literal></term>
361 <indexterm><primary>link
</primary></indexterm>
365 <para><emphasis role=
"bold">Allowed values:
</emphasis> <literal>shared
</literal>,
366 <literal>static
</literal></para>
369 A feature controlling how libraries are built.
375 <varlistentry id=
"bbv2.overview.builtins.features.runtime-link">
376 <indexterm><primary>runtime linking
</primary></indexterm>
377 <term><literal>runtime-link
</literal></term>
380 <para><emphasis role=
"bold">Allowed values:
</emphasis> <literal>shared
</literal>,
381 <literal>static
</literal></para>
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.
396 <term><literal>threading
</literal></term>
397 <indexterm><primary>threading
</primary></indexterm>
401 <para><emphasis role=
"bold">Allowed values:
</emphasis> <literal>single
</literal>,
402 <literal>multi
</literal></para>
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.
416 <term><literal>source
</literal></term>
417 <indexterm><primary>source
</primary></indexterm>
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
>
433 <term><literal>library
</literal></term>
434 <indexterm><primary>library
</primary></indexterm>
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.
448 <varlistentry><term><anchor id=
"bbv2.builtin.features.dependency"/>
449 <literal>dependency
</literal></term>
450 <indexterm><primary>dependency
</primary></indexterm>
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.
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
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
471 adds its usage requirements to the build properties
472 of the target being declared.
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.
478 It is hard to picture why anyone would want to do that. Please flesh
480 ====================================================================
486 <varlistentry><term><anchor id=
"bbv2.builtin.features.implicit-dependency"/>
487 <literal>implicit-dependency
</literal></term>
488 <indexterm><primary>implicit-dependency
</primary></indexterm>
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.
501 <varlistentry><term><anchor id=
"bbv2.builtin.features.use"/>
502 <literal>use
</literal></term>
503 <indexterm><primary>use
</primary></indexterm>
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
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. -->
523 <term><anchor id=
"bbv2.reference.features.dll-path"/>
524 <literal>dll-path
</literal></term>
525 <indexterm><primary>dll-path
</primary></indexterm>
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.
535 </listitem></varlistentry>
538 <term><literal>hardcode-dll-paths
</literal></term>
539 <indexterm><primary>hardcode-dll-paths
</primary></indexterm>
543 Controls automatic generation of dll-path properties.
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>
562 <term><literal>cflags
</literal></term>
563 <term><literal>cxxflags
</literal></term>
564 <term><literal>linkflags
</literal></term>
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.
579 <term><literal>include
</literal></term>
580 <indexterm><primary>include
</primary></indexterm>
584 Specifies an additional include path that is to be passed to C and
591 <term><literal>define
</literal></term>
592 <indexterm><primary>define
</primary></indexterm>
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
605 <varlistentry><term><literal>warnings
</literal></term>
608 The
<code><warnings
></code> feature controls the warning level
609 of compilers. It has the following values:
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>
615 Default value is
<code>all
</code>.
620 <varlistentry><term><literal>warnings-as-errors
</literal></term>
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
631 <varlistentry><term><literal>build
</literal></term>
634 <para><emphasis role=
"bold">Allowed values:
</emphasis> <literal>no
</literal></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.
646 <varlistentry><term><anchor id=
"bbv2.builtin.features.tag"/><literal>tag
</literal></term>
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
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.
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>
669 <varlistentry><term><literal>debug-symbols
</literal></term>
672 <para><emphasis role=
"bold">Allowed values:
</emphasis> <literal>on
</literal>,
<literal>off
</literal>.
</para>
674 <para>The
<literal>debug-symbols
</literal> feature specifies if
675 produced object files, executables, and libraries should include
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>
684 <varlistentry><term><literal>runtime-debugging
</literal></term>
687 <para><emphasis role=
"bold">Allowed values:
</emphasis> <literal>on
</literal>,
<literal>off
</literal>.
</para>
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>
699 <varlistentry><term><literal>target-os
</literal></term>
702 <anchor id=
"bbv2.reference.features.target-os"/>
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.
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.
718 <para>See
<xref linkend=
"bbv2.tasks.crosscompile"/> for details of
719 crosscompilation
</para>
725 <varlistentry><term><literal>architecture
</literal></term>
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>.
747 <para>The
<literal>architecture
</literal> features specifies
748 the general processor family to generate code for.
</para>
753 <varlistentry><term><literal>instruction-set
</literal></term>
754 <indexterm><primary>instruction-set
</primary></indexterm>
757 <emphasis role=
"bold">Allowed values:
</emphasis> depend on the used
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>
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.
775 <varlistentry><term><literal>address-model
</literal></term>
776 <indexterm><primary>64-bit compilation
</primary></indexterm>
778 <para><emphasis role=
"bold">Allowed values:
</emphasis> <literal>32</literal>,
<literal>64</literal>.
</para>
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"/>
790 <varlistentry><term><literal>c++-template-depth
</literal></term>
793 <emphasis role=
"bold">Allowed values:
</emphasis> Any positive
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.
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.
815 <varlistentry><term><literal>embed-manifest
</literal></term>
818 <indexterm><primary>manifest file
</primary><secondary>embedding
</secondary></indexterm>
819 <indexterm><primary>embed-manifest
</primary></indexterm>
822 <emphasis role=
"bold">Allowed values:
</emphasis> on, off.
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>.
839 <varlistentry><term><literal>embed-manifest-file
</literal></term>
842 <indexterm><primary>manifest file
</primary><secondary>embedding
</secondary></indexterm>
843 <indexterm><primary>embed-manifest-file
</primary></indexterm>
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>.
863 <section id=
"bbv2.reference.tools">
864 <title>Builtin tools
</title>
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>
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>
876 <para>additional parameters can be passed just like for other rules, for example:
</para>
878 using gcc :
4.0 : g++-
4.0 ;
883 <para>The options that can be passed to each tool are documented in the
884 subsequent sections.
</para>
886 <section id=
"bbv2.reference.tools.compilers">
888 <title>C++ Compilers
</title>
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>
896 <section id=
"bbv2.reference.tools.compiler.gcc">
898 <title>GNU C++
</title>
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"/>.
908 <para>The
<code>gcc
</code> module is initialized using the following
911 using gcc :
&toolset_ops; ;
</programlisting>
915 <!-- FIXME: mention everywhere what is the semantic
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>
927 <xi:include href=
"fragments.xml" xpointer=
"xpointer(id('common_options')/*)"
930 <xi:include href=
"fragments.xml" xpointer=
"xpointer(id('root_option')/*)"
934 <term><literal>archiver
</literal></term>
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>
946 <term><literal>ranlib
</literal></term>
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>
958 <term><literal>rc
</literal></term>
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>
970 <term><literal>rc-type
</literal></term>
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>
981 <indexterm><primary>64-bit compilation
</primary>
982 <secondary>gcc
</secondary></indexterm>
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>.
992 <section id=
"bbv2.reference.tools.compiler.darwin">
994 <title>Apple Darwin gcc
</title>
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.
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.
1015 <section id=
"bbv2.reference.tools.compiler.msvc">
1017 <title>Microsoft Visual C++
</title>
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>
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>
1035 <para>The
<code>msvc
</code> module is initialized using the following
1038 using msvc :
&toolset_ops; ;
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>.
1049 <para>The compiler command should be specified using forward slashes,
1055 <xi:include href=
"fragments.xml" xpointer=
"xpointer(id('common_options')/*)"
1059 <term><literal>assembler
</literal></term>
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>
1068 <term><literal>compiler
</literal></term>
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>
1077 <term><literal>compiler-filter
</literal></term>
1079 <listitem><para>Command through which to pipe the output of
1080 running the compiler. For example to pass the output to STLfilt.
1085 <term><literal>idl-compiler
</literal></term>
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>
1095 <term><literal>linker
</literal></term>
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>
1104 <term><literal>mc-compiler
</literal></term>
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>
1114 <term><literal>resource-compiler
</literal></term>
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>
1123 <term><literal>setup
</literal></term>
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>
1137 <term><literal>setup-amd64
</literal></term>
1138 <term><literal>setup-i386
</literal></term>
1139 <term><literal>setup-ia64
</literal></term>
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>
1148 <section id=
"v2.reference.tools.compiler.msvc.64">
1149 <title>64-bit support
</title>
1151 <indexterm><primary>64-bit compilation
</primary>
1152 <secondary>Microsoft Visual Studio
</secondary></indexterm>
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
1163 <listitem><para>32-bit x86 host,
32-bit x86 target
</para>
1165 <listitem><para>32-bit x86 host,
64-bit AMD64 target
</para>
1167 <listitem><para>32-bit x86 host,
64-bit IA64 target
</para>
1169 <listitem><para>64-bit AMD64 host,
64-bit AMD64 target
</para>
1171 <listitem><para>64-bit IA64 host,
64-bit IA64 target
</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.
1182 <para>To use
64-bit compilation you should:
</para>
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>
1189 <listitem><para>When compiling, use
<code>address-model=
64</code>,
1190 to generate AMD64 code.
</para></listitem>
1192 <listitem><para>To generate IA64 code, use
1193 <code>architecture=ia64
</code></para></listitem>
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>
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>
1210 <section id=
"v2.reference.tools.compiler.msvc.winrt">
1211 <title>Windows Runtime support
</title>
1213 <indexterm><primary>Windows Runtime support
</primary>
1214 <secondary>Microsoft Visual Studio
</secondary></indexterm>
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.
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:
1233 <listitem><para>Windows
8.0: toolset=msvc-
11.0 windows-api=store
</para>
1235 <listitem><para>Windows
8.1: toolset=msvc-
12.0 windows-api=store
</para>
1237 <listitem><para>Windows Phone
8.0: toolset=msvc-
11.0 windows-api=phone
</para>
1239 <listitem><para>Windows Phone
8.1: toolset=msvc-
12.0 windows-api=phone
</para>
1244 For example use the following to build for Windows Store
8.1
1245 with the ARM architecture:
1248 .\b2 toolset=msvc-
12.0 windows-api=store architecture=arm
</programlisting>
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
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>.
1260 <section id=
"bbv2.reference.tools.compiler.intel">
1262 <title>Intel C++
</title>
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>
1268 "http://www.intel.com/cd/software/products/asmo-na/eng/compilers/284527.htm">
1269 Windows
</ulink> versions respectively.
</para>
1271 <para>The module is initialized using the following syntax:
</para>
1273 using intel-linux :
&toolset_ops; ;
</programlisting>
1276 using intel-win :
&toolset_ops; ;
</programlisting>
1277 <para>respectively.
</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).
1290 <xi:include href=
"fragments.xml" xpointer=
"xpointer(id('common_options')/*)"
1295 <para>The Linux version supports the following additional options:
</para>
1298 <xi:include href=
"fragments.xml" xpointer=
"xpointer(id('root_option')/*)"
1303 <!-- the compatibility option appears to be messed up -->
1307 <section id=
"bbv2.reference.tools.compiler.acc">
1309 <title>HP aC++ compiler
</title>
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>
1315 <para>The module is initialized using the following
1318 using acc :
&toolset_ops; ;
</programlisting>
1324 If the command is not specified, the
<command>aCC
</command>
1325 binary will be searched in
<envar>PATH
</envar>.
</para>
1329 <xi:include href=
"fragments.xml" xpointer=
"xpointer(id('common_options')/*)"
1335 <section id=
"bbv2.reference.tools.compiler.borland">
1337 <title>Borland C++ Compiler
</title>
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>
1344 <para>The supported products are listed below. The version reported
1345 by the command lines tools is also listed for reference.:
</para>
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>
1353 <para>The module is initialized using the following syntax:
</para>
1355 using borland :
&toolset_ops; ;
</programlisting>
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>
1364 <xi:include href=
"fragments.xml" xpointer=
"xpointer(id('common_options')/*)"
1370 <section id=
"bbv2.reference.tools.compiler.como">
1372 <title>Comeau C/C++ Compiler
</title>
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>
1379 <para>The module is initialized using the following syntax:
</para>
1381 using como-linux :
&toolset_ops; ;
</programlisting>
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>
1391 <xi:include href=
"fragments.xml" xpointer=
"xpointer(id('common_options')/*)"
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
1402 <section id=
"bbv2.reference.tools.compiler.cw">
1404 <title>Code Warrior
</title>
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>
1413 <para>The module is initialized using the following syntax:
</para>
1415 using cw :
&toolset_ops; ;
</programlisting>
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>
1426 <xi:include href=
"fragments.xml" xpointer=
"xpointer(id('common_options')/*)"
1429 <xi:include href=
"fragments.xml" xpointer=
"xpointer(id('root_option')/*)"
1433 <term><literal>setup
</literal></term>
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>
1444 <term><literal>compiler
</literal></term>
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>
1454 <term><literal>linker
</literal></term>
1456 <listitem><para>The command that links executables and dynamic
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>
1468 <section id=
"bbv2.reference.tools.compiler.dmc">
1470 <title>Digital Mars C/C++ Compiler
</title>
1472 <para>The
<code>dmc
</code> module supports the
1473 <ulink url=
"http://www.digitalmars.com/">Digital Mars C++ compiler.
</ulink>
1476 <para>The module is initialized using the following syntax:
</para>
1478 using dmc :
&toolset_ops; ;
</programlisting>
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>
1488 <xi:include href=
"fragments.xml" xpointer=
"xpointer(id('common_options')/*)"
1494 <section id=
"bbv2.reference.tools.compiler.hp_cxx">
1496 <title>HP C++ Compiler for Tru64 Unix
</title>
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>
1502 <para>The module is initialized using the following syntax:
</para>
1504 using hp_cxx :
&toolset_ops; ;
</programlisting>
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>
1513 <xi:include href=
"fragments.xml" xpointer=
"xpointer(id('common_options')/*)"
1519 <section id=
"bbv2.reference.tools.compiler.sun">
1521 <title>Sun Studio
</title>
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>
1527 <para>The module is initialized using the following syntax:
</para>
1529 using sun :
&toolset_ops; ;
</programlisting>
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>
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:
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>
1549 <xi:include href=
"fragments.xml" xpointer=
"xpointer(id('common_options')/*)"
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.
1560 <section id=
"bbv2.reference.tools.compiler.vacpp">
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>
1568 <para>The module is initialized using the following
1571 using vacpp ;
</programlisting>
1573 <para>The module does not accept any initialization options. The
1574 compiler should be installed in the
<filename>/usr/vacpp/bin
</filename>
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>
1585 <title>Third-party libraries
</title>
1587 <para>Boost.Build provides special support for some
1588 third-party C++ libraries, documented below.
</para>
1590 <section id=
"bbv2.reference.tools.libraries.stlport">
1591 <title>STLport library
</title>
1592 <indexterm><primary>STLport
</primary></indexterm>
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>
1600 <para>Before using STLport, you need to configure it in
1601 <filename>user-config.jam
</filename> using the following syntax:
1604 using stlport :
<optional><replaceable>version
</replaceable></optional> :
<replaceable>header-path
</replaceable> :
<optional><replaceable>library-path
</replaceable></optional> ;
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.
1618 <para>When STLport is configured, you can build with STLport by
1619 requesting
<literal>stdlib=stlport
</literal> on the command line.
1624 <section id=
"bbv2.reference.tools.libraries.zlib">
1626 <indexterm><primary>zlib
</primary></indexterm>
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>
1633 <para>zlib can be initialized using the following syntax
</para>
1635 using zlib :
<optional><replaceable>version
</replaceable></optional> :
<optional><replaceable>options
</replaceable></optional> :
<optional><replaceable>condition
</replaceable></optional> :
<optional><replaceable>is-default
</replaceable></optional> ;
1637 <para>Options for using a prebuilt library:
</para>
1640 <term><literal>search
</literal></term>
1642 <para>The directory containing the zlib binaries.
</para>
1646 <term><literal>name
</literal></term>
1648 <para>Overrides the default library name.
</para>
1652 <term><literal>include
</literal></term>
1654 <para>The directory containing the zlib headers.
</para>
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>
1664 <term><literal>source
</literal></term>
1666 <para>The zlib source directory. Defaults to the
1667 environmental variable ZLIB_SOURCE.
</para>
1671 <term><literal>tag
</literal></term>
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>
1679 <term><literal>build-name
</literal></term>
1681 <para>The base name to use for the compiled library.
1682 Ignored when using precompiled binaries.
</para>
1686 <para>Examples:
</para>
1688 # Find zlib in the default system location
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 ;
1704 <title>Documentation tools
</title>
1706 <para>Boost.Build support for the Boost documentation tools is
1710 <section id=
"bbv2.reference.tools.doc.xsltproc">
1711 <title>xsltproc
</title>
1712 <indexterm><primary>xsltproc
</primary></indexterm>
1714 <para>To use xsltproc, you first need to configure it using the following syntax:
</para>
1716 using xsltproc :
<optional><replaceable>xsltproc
</replaceable></optional> ;
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.
1730 <indexterm><primary>xsl:param
</primary></indexterm>
1731 <term><literal>xsl:param
</literal></term>
1733 <para>Values should have the form
1734 <replaceable>name
</replaceable>=
<replaceable>value
</replaceable></para>
1739 <indexterm><primary>xsl:path
</primary></indexterm>
1740 <term><literal>xsl:path
</literal></term>
1742 <para>Sets an additional search path for xi:include elements.
</para>
1747 <indexterm><primary>catalog
</primary></indexterm>
1748 <term><literal>catalog
</literal></term>
1750 <para>A catalog file used to rewrite remote URL's to a local copy.
</para>
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.
1763 <indexterm><primary>xslt
</primary></indexterm>
1764 <term><literal>xslt
</literal></term>
1767 rule xslt ( target : source stylesheet : properties * )
1769 <para>Runs xsltproc to create a single output file.
</para>
1774 <indexterm><primary>xslt-dir
</primary></indexterm>
1775 <term><literal>xslt-dir
</literal></term>
1778 rule xslt-dir ( target : source stylesheet : properties * : dirname )
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
1792 <section id=
"bbv2.reference.tools.doc.boostbook">
1793 <title>boostbook
</title>
1794 <indexterm><primary>boostbook
</primary><secondary>module
</secondary></indexterm>
1796 <para>To use boostbook, you first need to configure it using the following syntax:
</para>
1798 using boostbook :
<optional><replaceable>docbook-xsl-dir
</replaceable></optional> :
<optional><replaceable>docbook-dtd-dir
</replaceable></optional> :
<optional><replaceable>boostbook-dir
</replaceable></optional> ;
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.
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.
1815 <replaceable>boostbook-dir
</replaceable> is the BoostBook directory
1816 with the DTD and XSL subdirs.
1819 <para>The boostbook module depends on xsltproc. For pdf or ps output,
1820 it also depends on fop.
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>
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>.
1850 <para>The
<literal>format
</literal> feature determines the type
1851 of output produced by the boostbook rule.
</para>
1857 <para>The boostbook module defines a rule for creating a target
1858 following the common syntax.
</para>
1863 <indexterm><primary>boostbook
</primary><secondary>rule
</secondary></indexterm>
1864 <term><literal>boostbook
</literal></term>
1867 rule boostbook ( target-name : sources * : requirements * : default-build * )
1869 <para>Creates a boostbook target.
</para>
1877 <section id=
"bbv2.reference.tools.doc.doxygen">
1878 <title>doxygen
</title>
1879 <indexterm><primary>doxygen
</primary></indexterm>
1881 <para>To use doxygen, you first need to configure it using the following syntax:
</para>
1883 using doxygen :
<optional><replaceable>name
</replaceable></optional> ;
1886 <replaceable>name
</replaceable> is the doxygen command.
1887 If it is not specified, it will be found in the PATH.
1890 <para>The doxygen module depends on the boostbook module when
1891 generating BoostBook XML.
1898 <indexterm><primary>doxygen:param
</primary></indexterm>
1899 <term><literal>doxygen:param
</literal></term>
1901 <para>All the values of
<literal>doxygen:param
</literal>
1902 are added to the doxyfile.
</para>
1907 <indexterm><primary>prefix
</primary></indexterm>
1908 <term><literal>prefix
</literal></term>
1910 <para>Specifies the common prefix of all headers
1911 when generating BoostBook XML. Everything before
1912 this will be stripped off.
1918 <indexterm><primary>reftitle
</primary></indexterm>
1919 <term><literal>reftitle
</literal></term>
1921 <para>Specifies the title of the library-reference section,
1922 when generating BoostBook XML.
</para>
1927 <indexterm><primary>doxygen:xml-imagedir
</primary></indexterm>
1928 <term><literal>doxygen:xml-imagedir
</literal></term>
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.
1942 <para>The doxygen module defines a rule for creating a target
1943 following the common syntax.
</para>
1948 <indexterm><primary>doxygen
</primary><secondary>rule
</secondary></indexterm>
1949 <term><literal>doxygen
</literal></term>
1952 rule doxygen ( target : sources * : requirements * : default-build * : usage-requirements * )
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.
1965 <section id=
"bbv2.reference.tools.doc.quickbook">
1966 <title>quickbook
</title>
1967 <indexterm><primary>quickbook
</primary></indexterm>
1969 <para>The quickbook module provides a generator to convert from
1970 Quickbook to BoostBook XML.
</para>
1972 <para>To use quickbook, you first need to configure it using the following syntax:
</para>
1974 using quickbook :
<optional><replaceable>command
</replaceable></optional> ;
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
1985 <section id=
"bbv2.reference.tools.doc.fop">
1987 <indexterm><primary>fop
</primary></indexterm>
1989 <para>The fop module provides generators to convert from
1990 XSL formatting objects to Postscript and PDF.
</para>
1992 <para>To use fop, you first need to configure it using the following syntax:
</para>
1994 using fop :
<optional><replaceable>fop-command
</replaceable></optional> :
<optional><replaceable>java-home
</replaceable></optional> :
<optional><replaceable>java
</replaceable></optional> ;
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
2002 Either
<replaceable>java-home
</replaceable> or
2003 <replaceable>java
</replaceable>
2004 can be used to specify where to find java.
2013 <section id=
"bbv2.reference.modules">
2014 <title>Builtin modules
</title>
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.
2022 <section id=
"bbv2.reference.modules.modules">
2023 <title>modules
</title>
2024 <indexterm><primary>modules
</primary></indexterm>
2027 The
<code>modules
</code> module defines basic functionality
2028 for handling modules.
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
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
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
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>
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>
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>
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>
2089 For example, to read a variable from the global module:
2090 <programlisting language=
"jam">local ZLIB_INCLUDE = [ modules.peek : ZLIB_INCLUDE ] ;
</programlisting>
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
2102 <note><para>rules called this way may accept at most
2103 8 parameters.
</para></note></para>
2105 <programlisting language=
"jam">
2106 rule filter ( f : values * )
2108 local m = [ CALLER_MODULE ] ;
2112 if [ modules.call-in $(m) : $(f) $(v) ]
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>
2129 <term><literal>module-name
</literal></term>
2130 <listitem><para>Name of module to load.
</para></listitem>
2135 <term><literal>filename
</literal></term>
2136 <listitem><para>(partial) path to file; Defaults to
<code>$(module-name).jam
</code></para></listitem>
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>
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>
2163 <programlisting language=
"jam">
2166 import path : join ;
2167 import path : native make : native-path make-path ;
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>
2186 <xi:include href=
"path.xml"/>
2187 <xi:include href=
"regex.xml"/>
2188 <xi:include href=
"sequence.xml"/>
2189 <xi:include href=
"type.xml"/>
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"/>
2203 <section id=
"bbv2.reference.buildprocess">
2204 <title>Build process
</title>
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.
2211 <para>To recap, building a target with specific properties includes the
2215 <listitem><para>applying default build,
</para></listitem>
2217 <listitem><para>selecting the main target alternative to use,
2220 <listitem><para>determining
"common" properties,
</para></listitem>
2222 <listitem><para>building targets referred by the sources list and
2223 dependency properties,
</para></listitem>
2225 <listitem><para>adding the usage requirements produces when building
2226 dependencies to the
"common" properties,
</para></listitem>
2228 <listitem><para>building the target using generators,
</para></listitem>
2230 <listitem><para>computing the usage requirements to be returned.
</para></listitem>
2235 <section id=
"bbv2.reference.buildprocess.alternatives">
2236 <title>Alternative selection
</title>
2238 <para>When there are several alternatives, one of them must be
2239 selected. The process is as follows:
</para>
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
2253 An alternative is viable only if all properties in condition
2254 are present in build request.
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
2273 <section id=
"bbv2.reference.buildprocess.common">
2274 <title>Determining common properties
</title>
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.
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.
2287 <listitem><para>Non-free feature can have only one
2288 value
</para></listitem>
2290 <listitem><para>A non-conditional property in requirement in always
2291 present in common properties.
</para></listitem>
2293 <listitem><para>A property in build request is present in
2294 common properties, unless (
2) tells otherwise.
</para></listitem>
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>
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>
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>
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
2320 :
<toolset
>gcc:
<variant
>release
2321 <variant
>release:
<define
>FOO ;
2327 <section id=
"bbv2.reference.buildprocess.targetpath">
2328 <title>Target Paths
</title>
2329 <indexterm><primary>path
</primary><secondary>for targets
</secondary></indexterm>
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>
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>
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>
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>
2371 <section id=
"bbv2.reference.definitions">
2373 <title>Definitions
</title>
2375 <section id=
"bbv2.reference.features">
2376 <title>Features and properties
</title>
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>'
2384 And what about dash?
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>
2393 <para>A
<emphasis>property
</emphasis> is a (feature,value) pair, expressed as
2394 <feature
>value.
</para>
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>
2402 <para>A
<emphasis>value-string
</emphasis> for a feature
<emphasis role=
"bold">F
</emphasis> is a string of
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>
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>
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>
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>
2424 <section id=
"bbv2.reference.features.validity">
2425 <title>Property Validity
</title>
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>.
2442 <section id=
"bbv2.reference.features.attributes">
2443 <title>Feature Attributes
</title>
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>
2455 <para><emphasis>incidental
</emphasis></para>
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>
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"/>.
2473 <anchor id=
"bbv2.reference.features.attributes.propagated"/>
2474 <emphasis>propagated
</emphasis>
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
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
2491 <anchor id=
"bbv2.reference.features.attributes.free"/>
2492 <emphasis>free
</emphasis>
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>
2503 <define
>NDEBUG=
1 <define
>HAS_CONFIG_H=
1
2509 <para><emphasis>optional
</emphasis></para>
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>
2521 <para><emphasis>symmetric
</emphasis></para>
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>
2532 <para><emphasis>path
</emphasis></para>
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
2542 <para><emphasis>implicit
</emphasis></para>
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>
2554 <para><emphasis>composite
</emphasis></para>
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>
2566 <para><emphasis>dependency
</emphasis></para>
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>
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>
2580 <para>Features that are neither free nor incidental are called
2581 <emphasis>base
</emphasis> features.
</para>
2585 <section id=
"bbv2.reference.features.declaration">
2586 <title>Feature Declaration
</title>
2588 <para>The low-level feature declaration interface is the
2589 <literal>feature
</literal> rule from the
2590 <literal>feature
</literal> module:
2593 rule feature ( name : allowed-values * : attributes * )
2596 A feature's allowed-values may be extended with the
2597 <code>feature.extend
</code> rule.
2603 <section id=
"bbv2.reference.variants.proprefine">
2604 <title>Property refinement
</title>
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>
2615 Each property in the required set is added to the original
2622 If the original property set includes property with a different
2623 value of non free feature, that property is removed.
2629 <section id=
"bbv2.reference.variants.propcond">
2630 <title>Conditional properties
</title>
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>
2640 property (
"," property ) *
":" property
2644 For example, the problem above would be solved by:
2647 exe hello : hello.cpp :
<toolset
>yfc:
<cxxflags
>-disable-pointless-warning ;
2651 <para>The syntax also allows several properties in the condition, for
2654 exe hello : hello.cpp :
<os
>NT,
<toolset
>gcc:
<link
>static ;
2660 <section id=
"bbv2.reference.ids">
2661 <title>Target identifiers and references
</title>
2663 <para><emphasis>Target identifier
</emphasis> is used to denote a
2664 target. The syntax is:
</para>
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
2676 This grammar allows some elements to be recognized as either
2681 name of target declared in current Jamfile (note that target
2682 names may include slash).
2688 a regular file, denoted by absolute name or name relative to
2689 project's sources location.
2695 project id (at this point, all project ids start with slash).
2701 the directory of another project, denoted by absolute name
2702 or name relative to the current project's location.
2707 To determine the real meaning the possible interpretations
2708 are checked in this order. For example, valid target ids might be:
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
2720 <para><emphasis role=
"bold">Rationale:
</emphasis>Target is separated from project by special
2721 separator (not just slash), because:
</para>
2726 It emphasis that projects and targets are different things.
2732 It allows to have main target names with slashes.
2734 <!-- The motivation for which is:
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
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?
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
2749 That makes good rationale for why main target must contain names.
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>
2761 target-reference -
> target-id [
"/" requested-properties ]
2762 requested-properties -
> property-path
2769 exe compiler : compiler.cpp libs/cmdline/
<optimization
>space ;
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
2787 sgml-parent-document: ("userman.xml" "chapter")