diff --git a/v2/doc/userman.xml b/v2/doc/userman.xml index ef1e23210..59a296f2f 100644 --- a/v2/doc/userman.xml +++ b/v2/doc/userman.xml @@ -8,62 +8,85 @@ How to use this document - If you've just found out about Boost.Build V2 and want to know - if it will work for you, start with . You can continue with the . When you're ready to try Boost.Build in - practice, go to . + + If you've just found out about Boost.Build V2 and want to know + if it will work for you, start with . You can continue with the . When you're ready to try Boost.Build + in practice, go to . + - If you are about to use Boost.Build on your project, or - already using it and have a problem, look at . + + If you are about to use Boost.Build on your project, or already + using it and have a problem, look at . + - If you're trying to build a project which uses Boost.Build, - look at and - then read about . + + If you're trying to build a project which uses Boost.Build, + look at and then read about + . + - Finally, if nothing applies to you, write to our mailing list, - telling what information you'd like to know. + + Finally, if nothing applies to you, write to our mailing list, + telling what information you'd like to know. + + Installation - - Assuming you're installing - Boost.Build from released source distribution, the following - steps are needed. All paths are given relatively to Boost.Build - root directory, which is the directory with the document you are - reading. + + Assuming you're installing Boost.Build from released source + distribution, the following steps are needed. All paths are + given relatively to Boost.Build root directory, which is the + directory with the document you are reading. + - - Go to "jam_src" directory and build Boost.Jam. Two - convenient scripts are provided, "build.sh" (for Unix systems) - and "build.bat" (for Windows). Run the appropriate one and - Boost.Jam will be built to directory - bin.{platform_name}.. The Boost.Jam documentation has more - details in case you need them. + + + + Go to "jam_src" directory and build Boost.Jam. Two convenient + scripts are provided, "build.sh" (for Unix systems) and + "build.bat" (for Windows). Run the appropriate one and + Boost.Jam will be built to directory + bin.{platform_name}.. The Boost.Jam documentation has + more details in case you need them. + + - Place the Boost.Jam binary, called "bjam" or "bjam.exe", - somewhere in your PATH. Go to the root directory of - Boost.Build and run "bjam --version". You should get + + + Place the Boost.Jam binary, called "bjam" or "bjam.exe", + somewhere in your PATH. Go to the root + directory of Boost.Build and run "bjam --version". You should + get - Boost.Build V2 (Milestone N) + Boost.Build V2 (Milestone N) - (where N is the version you've downloaded). - + (where N is the version you've downloaded). + + - Configure toolsets to use. Open the - user-config.jam file and follow instructions - there to specify what compiles/libraries you have and where they - are located. + + + Configure toolsets to use. Open the + user-config.jam file and follow + instructions there to specify what compiles/libraries you + have and where they are located. + + - You should now be able to go to - example/hello, and - run bjam there. A simple application will be - built. You can also play with other projects in - example. + + + You should now be able to go to + example/hello, and run + bjam there. A simple application will be + built. You can also play with other projects in + example. - - + + + - If you use Boost distribution, or Boost CVS, the Boost.Build - root is located at $boost_root/tools/build/v2 - and the installation steps are the same. However, don't skip the bjam - rebuilding step, even if you have a previous version. CVS version - of Boost.Build requires CVS version of Boost.Jam. + + If you use Boost distribution, or Boost CVS, the Boost.Build + root is located at $boost_root/tools/build/v2 + and the installation steps are the same. However, don't skip + the bjam rebuilding step, even if you have a previous version. + CVS version of Boost.Build requires CVS version of Boost.Jam. + - When starting a new project which uses Boost.Build, you need - to make sure that build system can be found. There are two - ways. + + When starting a new project which uses Boost.Build, you need + to make sure that build system can be found. There are two + ways. + - - Set enviromnetal variable BOOST_BUILD_PATH - to the absolute path to Boost.Build installation directory. - + + + + Set enviromnetal variable BOOST_BUILD_PATH + to the absolute path to Boost.Build installation directory. + + - Create, at the top of your project, a file called - boost-build.jam, with a single line: + + + Create, at the top of your project, a file called + boost-build.jam, with a single line: boost-build /path/to/boost.build ; - - + + + If you're trying to use Boost.Build V2 on Boost itself, please note that when building Boost, V1 is used by default. You'd have @@ -494,16 +528,19 @@ per-target basis. + Suppose your library can be only build statically. This is easily achieved using requirements: lib l : l.cpp : <link>static ; - + + + What if library can be both static and shared, but when using it in specific executable, you want it static? Target @@ -513,9 +550,11 @@ lib l : l.cpp : <link>static ; exe important : main.cpp helpers/<link>static ; + + What if the library is defined in some other project, which you cannot change. But still, you want static linking to that library in all cases. You can use target references everywhere: @@ -539,6 +578,7 @@ exe e10 : e10.cpp lib1 ; (Note, that the "alias" target type is not yet implemented, but it's quite simple to do. I bet it's waiting for you to do it ;-)) + @@ -674,11 +714,16 @@ version of zlib, but for other libraries this is quite reasonable. Creating your first project requires three steps: - Create an empty file called "Jamfile" + Create an empty file called "Jamfile" - Create an empty file called "project-root.jam" + + + Create an empty file called "project-root.jam" + + - Either set your BOOST_BUILD_PATH environment + + Either set your BOOST_BUILD_PATH environment variant to Boost.Build root, or create a "boost-build.jam" file with the following content: @@ -686,6 +731,7 @@ version of zlib, but for other libraries this is quite reasonable. boost-build /path/to/boost.build ; + @@ -695,22 +741,34 @@ boost-build /path/to/boost.build ; be: - Adding new main targets to the "Jamfile" file. The basic + + + Adding new main targets to the "Jamfile" file. The basic syntax for declaring a main target is described below, and all builtin functions for declaring main targets are listed. + "bbv2.advanced.builtins.targets">listed. + + - Creating subprojects. Create a directory, put new Jamfile + + + Creating subprojects. Create a directory, put new Jamfile there, and move some main targets to that Jamfile, or declare new ones. The projects - reference will help with this part. + reference will help with this part. + + - Customizing Boost.Build for your needs. You might have + + + Customizing Boost.Build for your needs. You might have additional tools you want to run, or just want different extension for some file. The extender manual is waiting for - you. + you. + + @@ -740,29 +798,49 @@ function-name main-target-name - "main-target-name" is the name used to request the target + + + "main-target-name" is the name used to request the target on command line and to use it from other main targets. Main target name may contain alphanumeric characters and symbols '-' - and '_'; + and '_'; + + - "sources" is the list of source files and other main + + + "sources" is the list of source files and other main targets that must be combined. If source file is specified using relative path, it's considered to be relative to the source directory of the project where the path is used. See the project rule - for information how to change source directory. + for information how to change source directory. + + - "requirements" is the list of properties that must always - be present when this main target is built. + + + "requirements" is the list of properties that must always + be present when this main target is built. + + - "default-build" is the list of properties that will be used + + + "default-build" is the list of properties that will be used unless some other value of the same feature is already - specified. + specified. + + - "usage-requirements" is the list of properties that will be + + + "usage-requirements" is the list of properties that will be propagated to all main targets that use this one, i.e. to all - dependedents. + dependedents. + + Some main target rules have shorter list of parameters, and @@ -846,48 +924,55 @@ to build only helpers, one should run "bjam hello..helpers". below: - - + + <tgroup cols="2"> + <thead> + <row> + <entry>Rule</entry> - <th>Semantic</th> - </tr> + <entry>Semantic</entry> + </row> + </thead> - <tr> - <td><link linkend= + <tbody> + <row> + <entry><link linkend= "bbv2.advanced.projects.attributes.projectrule">project</link> - </td> + </entry> - <td>Define project attributes.</td> - </tr> + <entry>Define project attributes.</entry> + </row> - <tr> - <td><link linkend= - "bbv2.advanced.projects.relationships.useprojectrule">use-project</link></td> + <row> + <entry><link linkend= + "bbv2.advanced.projects.relationships.useprojectrule">use-project</link></entry> - <td>Make another project known.</td> - </tr> + <entry>Make another project known.</entry> + </row> - <tr> - <td><link linkend= - "bbv2.advanced.projects.relationships.buildprojectrule">build-project</link></td> + <row> + <entry><link linkend= + "bbv2.advanced.projects.relationships.buildprojectrule">build-project</link></entry> - <td>Build another project when this one is built.</td> - </tr> + <entry>Build another project when this one is built.</entry> + </row> - <tr> - <td><link linkend= - "bbv2.reference.buildprocess.explict">explicit</link></td> + <row> + <entry><link linkend= + "bbv2.reference.buildprocess.explict">explicit</link></entry> - <td>States that the target should be built only by explicit - request.</td> - </tr> + <entry>States that the target should be built only by explicit + request.</entry> + </row> - <tr> - <td>glob</td> + <row> + <entry>glob</entry> - <td>Takes a list of wildcards, and returns the list of files - which match any of the wildcards.</td> - </tr> + <entry>Takes a list of wildcards, and returns the list of files + which match any of the wildcards.</entry> + </row> + </tbody> + </tgroup> </table> <para>Each project is also associated with <emphasis>project root</emphasis>. @@ -897,21 +982,37 @@ to build only helpers, one should run "bjam hello..helpers". <section id="bbv2.advanced.projects.root"> <title>Project root -Project root for a projects is the nearest - parent directory which contains a file called - project-root.jam. That file defines certain properties - which apply to all projects under project root. It can: + + Project root for a projects is the nearest parent directory + which contains a file called + project-root.jam. That file defines + certain properties which apply to all projects under project + root. It can: - configure toolsets, via call to toolset.using + + + configure toolsets, via call to toolset.using + + - refer to other projects, via the use-project - rule + + + refer to other projects, via the use-project + rule + + - declare constants, via the constant and - path-constant rules. + + + declare constants, via the constant and + path-constant rules. + + + + To facilitate declaration of simple projects, Jamfile and project-root can be merged together. To achieve this effect, the project root file should call the project rule. The @@ -946,7 +1047,8 @@ Project root for a projects is the nearest The default values for those attributes are given in the table below. In order to affect them, Jamfile may - call the project rule. The rule has this syntax: + call the project rule. The rule has this + syntax: project id : <attributes> ; @@ -967,71 +1069,79 @@ project tennis
Rule
- - + + <tgroup cols="4"> + <thead> + <row> + <entry>Attribute</entry> - <th>Name for the 'project' rule</th> + <entry>Name for the 'project' rule</entry> - <th>Default value</th> + <entry>Default value</entry> - <th>Handling by the 'project' rule</th> - </tr> + <entry>Handling by the 'project' rule</entry> + </row> + </thead> - <tr> - <td>Project id</td> + <tbody> - <td>none</td> + <row> + <entry>Project id</entry> - <td>none</td> + <entry>none</entry> - <td>Assigned from the first parameter of the 'project' rule. - It is assumed to denote absolute project id.</td> - </tr> + <entry>none</entry> - <tr> - <td>Source location</td> + <entry>Assigned from the first parameter of the 'project' rule. + It is assumed to denote absolute project id.</entry> + </row> - <td><literal>source-location</literal></td> + <row> + <entry>Source location</entry> - <td>The location of jamfile for the project</td> + <entry><literal>source-location</literal></entry> - <td>Sets to the passed value</td> - </tr> + <entry>The location of jamfile for the project</entry> - <tr> - <td>Requirements</td> + <entry>Sets to the passed value</entry> + </row> - <td><literal>requirements</literal></td> + <row> + <entry>Requirements</entry> - <td>The parent's requirements</td> + <entry><literal>requirements</literal></entry> - <td>The parent's requirements are refined with the passed + <entry>The parent's requirements</entry> + + <entry>The parent's requirements are refined with the passed requirement and the result is used as the project - requirements.</td> - </tr> + requirements.</entry> + </row> - <tr> - <td>Default build</td> + <row> + <entry>Default build</entry> - <td><literal>default-build</literal></td> + <entry><literal>default-build</literal></entry> - <td>none</td> + <entry>none</entry> - <td>Sets to the passed value</td> - </tr> + <entry>Sets to the passed value</entry> + </row> - <tr> - <td>Build directory</td> + <row> + <entry>Build directory</entry> - <td><literal>build-dir</literal></td> + <entry><literal>build-dir</literal></entry> - <td>If parent has a build dir set, the value of it, joined + <entry>If parent has a build dir set, the value of it, joined with the relative path from parent to the current project. - Otherwise, empty</td> + Otherwise, empty</entry> - <td>Sets to the passed value, interpreted as relative to the - project's location.</td> - </tr> + <entry>Sets to the passed value, interpreted as relative to the + project's location.</entry> + </row> + </tbody> + </tgroup> </table> </section> @@ -1060,7 +1170,8 @@ project tennis relationship. In means that one project uses targets from another. It is possible to just refer to target in other projects using target id. However, if target id uses project id, it is - required that the project id is known. The <function>use-project</function> + required that the project id is known. The + <literal>use-project</literal> rule is employed to guarantee that. </para> @@ -1072,7 +1183,7 @@ use-project ( id : location ) It loads the project at the specified location, which makes its project id available in the project which invokes the rule. It is required that the <literal>id</literal> parameter passed to the -<function>use-project</function> rule be equal to the id that the loaded +<literal>use-project</literal> rule be equal to the id that the loaded project declared. At this moment, the <literal>id</literal> paremeter should be absolute project id. </para> @@ -1098,14 +1209,25 @@ directory-name -> path This grammar allows some elements to be recognized as either <itemizedlist> - <listitem>project id (at this point, all project ids start with - slash).</listitem> + <listitem> + <simpara> + project id (at this point, all project ids start with slash). + </simpara> + </listitem> - <listitem>name of target declared in current Jamfile (note that - target names may include slash).</listitem> + <listitem> + <simpara> + name of target declared in current Jamfile (note that target + names may include slash). + </simpara> + </listitem> - <listitem>a regular file, denoted by absolute name or name relative - to project's sources location.</listitem> + <listitem> + <simpara> + a regular file, denoted by absolute name or name relative to + project's sources location. + </simpara> + </listitem> </itemizedlist> To determine the real meaning a check is made if project-id @@ -1125,10 +1247,16 @@ lib/b.cpp -- regular file separator (not just slash), because:</para> <itemizedlist> - <listitem>It emphasises that projects and targets are different - things.</listitem> + <listitem> + <simpara> + It emphasises that projects and targets are different things. + </simpara> + </listitem> + + <listitem> + <simpara> + It allows to have main target names with slashes. - <listitem>It allows to have main target names with slashes. <!-- The motivation for which is: So, to summarize: @@ -1146,6 +1274,7 @@ lib/b.cpp -- regular file That makes good rationale for why main target must contain names. --> + </simpara> </listitem> </itemizedlist> @@ -1181,9 +1310,14 @@ speed. <variablelist> <varlistentry><term><literal>exe</literal></term> - <listitem>Creates a regular executable file. Sources must be either - object files or libraries, and sources of different types will - be converted to accepted types automatically.</listitem></varlistentry> + <listitem> + <simpara> + Creates a regular executable file. Sources must be either + object files or libraries, and sources of different types + will be converted to accepted types automatically. + </simpara> + </listitem> + </varlistentry> <varlistentry><term><literal>lib</literal></term> @@ -1204,21 +1338,33 @@ speed. <varlistentry><term><literal>alias</literal></term> - <listitem>Builds all the source targets and returns them unmodified. - Please run "bjam --help alias" for more details.</listitem></varlistentry> + <listitem> + <simpara> + Builds all the source targets and returns them unmodified. + Please run "bjam --help alias" for more details. + </simpara> + </listitem></varlistentry> <varlistentry><term><literal>stage</literal></term> - <listitem>Copies a number of targets to a single directory. The + <listitem> + <simpara> + Copies a number of targets to a single directory. The primary purpose is installing binaries. Please run "bjam --help - stage" for more details.</listitem></varlistentry> + stage" for more details. + </simpara> + </listitem></varlistentry> <varlistentry><term><literal>unit-test</literal> (from module "testing")</term> - <listitem>Creates an executable file and runs it. Build won't succeed + <listitem> + <simpara> + Creates an executable file and runs it. Build won't succeed unless the executable runs successfully. The rule is usefull for creating test program which should be rerun whenever any - dependency changes. <!-- make? --></listitem></varlistentry> + dependency changes. <!-- make? --> + </simpara> + </listitem></varlistentry> </variablelist> </section> @@ -1230,8 +1376,10 @@ speed. <varlistentry><term><literal>variant</literal></term> <listitem> + <simpara> The feature which combines several low-level features in order to make building most common variants simple. + </simpara> <para><emphasis role="bold">Allowed values:</emphasis> <literal>debug</literal>, <literal>release</literal>, <literal>profile</literal></para> @@ -1264,7 +1412,9 @@ speed. <varlistentry><term><literal>link</literal></term> <listitem> - Feature which controls how libraries are built. + <simpara> + Feature which controls how libraries are built. + </simpara> <para><emphasis role="bold">Allowed values:</emphasis> <literal>shared</literal>, <literal>static</literal></para> @@ -1272,36 +1422,52 @@ speed. <varlistentry><term><literal>library</literal></term> - <listitem>For exe and lib main targets, the <library>X feature + <listitem> + <simpara> + For exe and lib main targets, the <library>X feature is equvivalent to putting X in the list of sources. The feature is sometimes more convenient: you can put <library>X in the requirements for a project and it will be linked to all - executables.</listitem></varlistentry> + executables. + </simpara> + </listitem> + </varlistentry> <varlistentry><term><literal>use</literal></term> - <listitem>Causes the target referenced by the value of this feature + <listitem> + <simpara> + Causes the target referenced by the value of this feature to be constructed and adds it's usage requirements to build properties. The constructed targets are not used in any other way. The primary use case is when you use some library and want it's usage requirements (such as include paths) to be applied, - but don't want to link to the library.</listitem></varlistentry> + but don't want to link to the library. + </simpara> + </listitem> + </varlistentry> <varlistentry><term><literal>dll-path</literal></term> - <listitem>Specify a path where dynamic libraries should be found at + <listitem> + <simpara> + Specify a path where dynamic libraries should be found at where executable or shared library is run. This feature directly affects binaries with the gcc compiler, allowing them to pick specific libraries, and ignoring all environment settings. On other toolsets, the binary still requires proper environment settings to be run. However, Boost.Build tools which run executables will notice dll-path settings and create - this environment automatically.</listitem></varlistentry> + this environment automatically. + </simpara> + </listitem></varlistentry> <varlistentry><term><literal>hardcode-dll-paths</literal></term> <listitem> + <simpara> Controls automatic generation of dll-path properties. + </simpara> <para><emphasis role="bold">Allowed values:</emphasis> <literal>off</literal>, <literal>on</literal> When this property is on, usage requirements for each library will @@ -1375,16 +1541,19 @@ speed. <section id="bbv2.reference.features.validity"> <title>Property Validity - For free features, all - values are valid. For all other features, the valid values are - explicitly specified, and the build system will report an error - for the use of an invalid feature-value. Subproperty validity may - be restricted so that certain values are valid only in the - presence of certain other subproperties. For example, it is - possible to specify that the <gcc-target>mingw - property is only valid in the presence of - <gcc-version>2.95.2. + + For free + features, all values are valid. For all other features, + the valid values are explicitly specified, and the build + system will report an error for the use of an invalid + feature-value. Subproperty validity may be restricted so + that certain values are valid only in the presence of + certain other subproperties. For example, it is possible + to specify that the <gcc-target>mingw + property is only valid in the presence of + <gcc-version>2.95.2. +
@@ -1399,7 +1568,7 @@ speed. - incidental + incidental Incidental features are assumed not to affect build products at all. As a consequence, the build system may use @@ -1416,8 +1585,10 @@ speed. - - propagated + + + propagated + Features of this kind are propagated to dependencies. That is, if a + free + Most features have a finite set of allowed values, and can only take on a single value from that set in a given build @@ -1449,7 +1622,7 @@ speed. - optional + optional An optional feature is a feature which is not required to appear in a build specification. Every non-optional non-free @@ -1461,7 +1634,7 @@ speed. - symmetric + symmetric A symmetric feature's default value is not automatically included in - path + path The value of a path feature specifies a path. The path is treated as relative to the directory of Jamfile where path @@ -1485,7 +1658,7 @@ speed. - implicit + implicit Values of implicit features alone identify the feature. For example, a user is not required to write @@ -1497,7 +1670,7 @@ speed. - composite + composite Composite features actually correspond to groups of properties. For example, a build variant is a composite @@ -1509,14 +1682,14 @@ speed. - link-incompatible + link-incompatible See below. - dependency + dependency The value of dependency feature if a target reference. When used for building of a main target, the value of @@ -1618,15 +1791,26 @@ A build variant, or (simply variant) is a special kind of composite property refinement and is performed by these rules - If original properties and required properties are not - link-compatible, refinement fails. + + + If original properties and required properties are not + link-compatible, refinement fails. + + - Each property in the required set is added to the original - property set + + + Each property in the required set is added to the original + property set + + - If the original property set includes property with a - different value of non free feature, that property is - removed. + + + If the original property set includes property with a different + value of non free feature, that property is removed. + +
@@ -1644,11 +1828,13 @@ A build variant, or (simply variant) is a special kind of composite property ( "," property ) * ":" property + For example, the problem above would be solved by: exe hello : hello.cpp : <toolset>yfc:<cxxflags>-disable-pointless-warning ; + @@ -1693,53 +1879,60 @@ automatically find the build system.Locations where those files a search are summarized below: -
Attribute
- +
- search paths for configuration files -
+ Search paths for configuration files - - + + - + + - - + site-config.jam - - + user-config.jam + - + + + + Linux + + /etc $HOME $BOOST_BUILD_PATH - + - - + + - - + + Windows - + - - + + + +
site-config.jamuser-config.jam
Linux +
+ $HOME $BOOST_BUILD_PATH -
Windows + $SystemRoot $HOME $BOOST_BUILD_PATH - + $HOME $BOOST_BUILD_PATH -
+ Boost.Build comes with default versions of those files, which can serve as templates for customized versions. +
@@ -1748,12 +1941,12 @@ Boost.Build comes with default versions of those files, The command line may contain: - Jam options, + Jam options, - Boost.Build options, + Boost.Build options, - Command line arguments + Command line arguments
@@ -1765,14 +1958,20 @@ Boost.Build comes with default versions of those files, - An argument which does not contain slashes or the "=" + + + An argument which does not contain slashes or the "=" symbol is either a value of an implicit feature, or target to be built. It is taken to be value of a feature if appropriate feature exists. Otherwise, it is considered a target id. Special target name "clean" - has the same effect as "--clean" option. + has the same effect as "--clean" option. + + - An argument with either slashes or the "=" symbol specifies + + + An argument with either slashes or the "=" symbol specifies a number of build request elements. In the simplest form, it's just a set of properties, @@ -1818,6 +2017,7 @@ and will be converted into property set <feature-name>feature-value1 .... <feature-name>feature-valueN + @@ -1840,69 +2040,69 @@ linked binaries would be created. All of the Boost.Build options start with the "--" prefix. They are described in the following table. - - +
- Command line options -
+ Command line options + - - + + Option - - + Description + - - + + --version - - + Prints information on Boost.Build and Boost.Jam + versions. + - - + + --help - - + --help* options. + - - + + --clean - - + some targets. + - - + + --debug - - + Enables internal checks. + - - + + --dump-projects - - + Cause the project structure to be output. + - - + + --no-error-backtrace - - + Don't print backtrace on errors. Primary usefull for + testing. + - - + + --ignore-config - - + Do not load site-config.jam and + user-config.jam + +
OptionDescription
--versionPrints information on Boost.Build and Boost.Jam - versions.
--helpAccess to the online help system. This prints general + Access to the online help system. This prints general information on how to use the help system with additional - --help* options.
--cleanRemoves everything instead of building. Unlike + Removes everything instead of building. Unlike clean target in make, it is possible to clean only - some targets.
--debugEnables internal checks.
--dump-projectsCause the project structure to be output.
--no-error-backtraceDon't print backtrace on errors. Primary usefull for - testing.
--ignore-configDo not load site-config.jam and - user-config.jam
@@ -1911,6 +2111,7 @@ linked binaries would be created.
Build request +
@@ -1982,50 +2183,88 @@ linked binaries would be created. project is skipped. - It is possible to disable building of - certain target using the explicit rule, available in - all project modules. The syntax is - - rule explicit ( target-name ) -If this rule is invoked on a target, it will be built only + It is possible to disable building of certain target using the + explicit rule, available in all project + modules. The syntax is + + +rule explicit ( target-name ) + + + If this rule is invoked on a target, it will be built only when it's explicitly requested on the command line. + - For main target, with several alternatives, one of them is + + + For main target, with several alternatives, one of them is selected as described below. If there's only one alternative, it's used unconditionally. - All main target alternatives which requirements are - satisfied by the build request are enumerated. + + + All main target alternatives which requirements are + satisfied by the build request are enumerated. + + - If there are several such alternatives, the one which - longer requirements list is selected. + + + If there are several such alternatives, the one which + longer requirements list is selected. + + + - For the selected alternative + + + For the selected alternative - Each target reference in the source list are - recursively constructed. + + + Each target reference in the source list are + recursively constructed. + + - Properties are refined with alternative's requirements, - and active features in the resulting set are executed. + + + Properties are refined with alternative's requirements, + and active features in the resulting set are executed. + + - Conditional properties are evaluated. + + + Conditional properties are evaluated. + + - The dependency graph for the target is constructed in a + + + The dependency graph for the target is constructed in a way which depends on the kind of main target, typically - using generators. + using generators. + + + - If, when building sources, the properties on recursively + + + If, when building sources, the properties on recursively created targets are not link-compatibile with build properties, - a warning is issued. + a warning is issued. + +
@@ -2037,21 +2276,33 @@ when it's explicitly requested on the command line. selected. The process is as follows: - For each alternative condition is defined as the - set of base properies in requirements. [Note: it might be + + + For each alternative condition is defined + as the set of base properies in requirements. [Note: it might be better to explicitly specify the condition explicitly, as in - conditional requirements]. + conditional requirements]. + + - An alternative is viable only if all properties in - condition are present in build request. + + + An alternative is viable only if all properties in condition + are present in build request. + + - If there's one viable alternative, it's choosen. Otherwise, + + + If there's one viable alternative, it's choosen. Otherwise, an attempt is made to find one best alternative. An alternative a is better than another alternative b, iff set of properties in b's condition is stict subset of the set of properities of 'a's condition. If there's one viable alternative, which is better than all other, it's selected. Otherwise, an error is - reported. + reported. + +
@@ -2123,16 +2374,28 @@ targets from "parser" as potential dependencies. particular sitiation. Those attributes are: - Required properties, which are properties absolutely + + + Required properties, which are properties absolutely necessary for the generator to work. For example, generator encapsulating the gcc compiler would have <toolset>gcc as - required property. + required property. + + - Optional properties, which increase the generators - suitability for a particual build. - Generator's required and optional properties may not include + + + Optional properties, which increase the generators + suitability for a particual build. + + + + + + Generator's required and optional properties may not include either free or incidental properties. (Allowing this would greatly complicate caching targets). + When trying to construct a target, the first step is to select all possible generators for the requested target type, which @@ -2200,12 +2463,20 @@ targets from "parser" as potential dependencies. are created, so the approach taken is: - When dependency graph is constructed, each action can be - assigned a rule for property adjustment. + + + When dependency graph is constructed, each action can be + assigned a rule for property adjustment. + + - When virtual target is actualized, that rule is run and + + + When virtual target is actualized, that rule is run and return the final set of properties. At this stage it can use - information of all created virtual targets. + information of all created virtual targets. + + In case of quoted includes, no adjustment can give 100% @@ -2273,13 +2544,23 @@ targets from "parser" as potential dependencies. better solution is: - Write the template of the code to be generated, leaving - placeholders at the points which will change + + + Write the template of the code to be generated, leaving + placeholders at the points which will change + + - Access the template in your application and replace - placeholders with appropriate text. + + + Access the template in your application and replace + placeholders with appropriate text. + + - Write the result. + + Write the result. + It's quite easy to archive. You write special verbatim files, @@ -2353,18 +2634,22 @@ and linked it.
Target types +
Tools +
Main target rules +
Scanners +
@@ -2443,17 +2728,33 @@ exe hello : hello.cpp /site-config//zlib ; for right dependency scanning mechanism are: - Support for different scanning algorithms. C++ and XML have + + + Support for different scanning algorithms. C++ and XML have quite different syntax for includes and rules for looking up - included files. + included files. + + - Ability to scan the same file several times. For example, + + + Ability to scan the same file several times. For example, single C++ file can be compiled with different include - paths. + paths. + + - Proper detection of dependencies on generated files. + + + Proper detection of dependencies on generated files. + + - Proper detection of dependencies from generated file. + + + Proper detection of dependencies from generated file. + +
@@ -2507,16 +2808,24 @@ a.cpp (installed copy) <--(copy) ----------------------- a.cpp (no scanner This requirement breaks down to the following ones. - If when compiling "a.cpp" there's include of "a.h", the + + + If when compiling "a.cpp" there's include of "a.h", the "dir" directory is in include path, and a target called "a.h" will be generated to "dir", then bjam should discover the - include, and create "a.h" before compiling "a.cpp". + include, and create "a.h" before compiling "a.cpp". + + - Since almost always Boost.Build generates targets to a + + + Since almost always Boost.Build generates targets to a "bin" directory, it should be supported as well. I.e. in the scanario above, Jamfile in "dir" might create a main target, which generates "a.h". The file will be generated to "dir/bin" - directory, but we still have to recornize the dependency. + directory, but we still have to recornize the dependency. + + The first requirement means that when determining what "a.h" @@ -2524,10 +2833,18 @@ a.cpp (installed copy) <--(copy) ----------------------- a.cpp (no scanner directories in include paths, checking for each one: - If there's file "a.h" in that directory, or + + + If there's file "a.h" in that directory, or + + - If there's a target called "a.h", which will be generated - to that directory. + + + If there's a target called "a.h", which will be generated + to that directory. + + Classic Jam has built-in facilities for point (1) above, but @@ -2604,15 +2921,26 @@ implemented now. is: - The main target to which compiled file belongs is - found. + + + The main target to which compiled file belongs is found. + + - All other main targets that the found one depends on are + + + All other main targets that the found one depends on are found. Those include main target which are used as sources, or - present as values of "dependency" features. + present as values of "dependency" features. + + - All directories where files belonging to those main target - will be generated are added to the include path. + + + All directories where files belonging to those main target + will be generated are added to the include path. + + After this is done, dependencies are found by the approach @@ -2744,22 +3072,34 @@ a.o ---> a.cpp paths are given below: - All targets are placed under directory corresponding to the - project where they are defined. + + + All targets are placed under directory corresponding to the + project where they are defined. + + - Each non free, non incidental property cause an additional + + + Each non free, non incidental property cause an additional element to be added to the target path. That element has the form <feature-name>-<feature-value> for ordinary features and <feature-value> for - implicit ones. [Note about composite features]. + implicit ones. [Note about composite features]. + + - If the set of free, non incidental properties is different + + + If the set of free, non incidental properties is different from the set of free, non incidental properties for the project in which the main target that uses the target is defined, a part of the form main_target-<name> is added to the target path. Note:It would be nice to completely track free features also, but this appears to be complex and - not extremely needed. + not extremely needed. + + For example, we might have these paths: