diff --git a/doc/src/advanced.xml b/doc/src/advanced.xml index bcff6af59..598848d1d 100644 --- a/doc/src/advanced.xml +++ b/doc/src/advanced.xml @@ -7,15 +7,14 @@ This section will provide the information necessary to create your own projects using Boost.Build. The information provided here is relatively - high-level, and as - well as the on-line help system must be used to obtain - low-level documentation (see as well as the on-line help + system must be used to obtain low-level documentation (see ). - Boost.Build actually consists of two parts - Boost.Jam, a - build engine with its own interpreted language, and Boost.Build itself, - implemented in Boost.Jam's language. The chain of events when - you type bjam on the command line is: + Boost.Build actually consists of two parts - Boost.Jam, a build engine + with its own interpreted language, and Boost.Build itself, implemented in + Boost.Jam's language. The chain of events when you type + bjam on the command line is: Boost.Jam tries to find Boost.Build and loads the top-level @@ -23,9 +22,10 @@ linkend="bbv2.reference.init"/> - The top-level module loads user-defined configuration - files, user-config.jam and site-config.jam, which define - available toolsets. + The top-level module loads user-defined configuration files, + user-config.jam and + site-config.jam, which define available toolsets. + The Jamfile in the current directory is read. That in turn @@ -37,7 +37,7 @@ Boost.Build decides which targets should be built, and how. That information is passed back to Boost.Jam, which takes care of actually running commands. - + @@ -57,45 +57,45 @@ How the build process works - Some Basics about the Boost.Jam language. See + Some Basics about the Boost.Jam language. See . - +
Boost.Jam Language This section will describe the basics of the Boost.Jam language—just enough for writing Jamfiles. For more information, - please see the Boost.Jam - documentation. - - Boost.Jam has an interpreted, procedural language. - On the lowest level, a Boost.Jam program consists of variables and - rule - rules (the Jam term for function). They are grouped - in modules—there's one global module and a number of named - modules. Besides that, a Boost.Jam program contains classes and class - instances. + please see the Boost.Jam documentation. - Syntantically, a Boost.Jam program consists of two kind of - elements—keywords (which have a special meaning to Boost.Jam) and - literals. + Boost.Jam has an interpreted, + procedural language. On the lowest level, a + Boost.Jam program consists of variables and + rule + rules (the Jam term for function). They are grouped + in modules—there's one global module and a number of named modules. + Besides that, a Boost.Jam program contains + classes and class instances. + + Syntantically, a Boost.Jam program + consists of two kind of elements—keywords (which have a special + meaning to Boost.Jam) and literals. Consider this code: a = b ; which assigns the value b to the variable - a. Here, = and - ; are keywords, while a and - b are literals. + a. Here, = and ; + are keywords, while a and b are + literals. - All syntax elements, even keywords, must be separated by - spaces. For example, omitting the space character before - ; will lead to a syntax error. + All syntax elements, even keywords, must be separated by spaces. + For example, omitting the space character before ; + will lead to a syntax error. If you want to use a literal value that is the same as some keyword, the @@ -103,11 +103,11 @@ a = b ; a = "=" ; - - All variables in Boost.Jam have the same type—list of - strings. To define a variable one assigns a value to it, like in the - previous example. An undefined variable is the same as a variable with - an empty value. Variables can be accessed with the + + All variables in Boost.Jam have the + same type—list of strings. To define a variable one assigns a value + to it, like in the previous example. An undefined variable is the same as + a variable with an empty value. Variables can be accessed using the $(variable) syntax. For example: a = $(b) $(c) ; @@ -115,27 +115,28 @@ a = $(b) $(c) ; Rules are defined by specifying the rule name, the parameter names, - and the allowed size of the list value for each parameter. + and the allowed size of the list value for each parameter. -rule example +rule example ( - parameter1 : - parameter2 ? : + parameter1 : + parameter2 ? : parameter3 + : - parameter4 * + parameter4 * ) { // body } When this rule is called, the list passed as the first argument must have exactly one value. The list passed as the second argument can - either have one value of be empty. The two remaining arguments can - be arbitrary long, but the third argument may not be empty. + either have one value of be empty. The two remaining arguments can be + arbitrarily long, but the third argument may not be empty. - The overview of Boost.Jam language statements is given below: + The overview of Boost.Jam language + statements is given below: -helper 1 : 2 : 3 ; +helper 1 : 2 : 3 ; x = [ helper 1 : 2 : 3 ] ; This code calls the named rule with the specified arguments. When the result of the call must be used inside some expression, you need to add @@ -144,7 +145,7 @@ x = [ helper 1 : 2 : 3 ] ; if cond { statements } [ else { statements } ] This is a regular if-statement. The condition is composed of: - Literals (true if at least one string is not empty) + Literals (true if at least one string is not empty) Comparisons: a operator b where operator is one of =, @@ -163,7 +164,7 @@ for var in list { statements } var to the element value. while cond { statements } - Repeatedly execute statements while cond remains true upon entry. + Repeatedly execute statements while cond remains true upon entry. return values ; This statement should be used only inside a @@ -202,16 +203,17 @@ actions create-file-from-another create-file-from-another $(<) $(>) } - This specifies a named action called - create-file-from-another. The text inside braces is the - command to invoke. The $(<) variable will be expanded to list of - generated files, and the $(>) variable will be expanded - to the list of source files. + This specifies a named action called + create-file-from-another. The text inside braces is + the command to invoke. The $(<) variable will be + expanded to a list of generated files, and the + $(>) variable will be expanded to a list of + source files. - To flexibly adjust command line, you can define a rule with the - same name as the action, and taking three parameters -- targets, sources - and properties. For example: + To flexibly adjust command line, you can define a rule with the same + name as the action, and taking three parameters -- targets, sources and + properties. For example: rule create-file-from-another ( targets * : sources * : properties * ) { @@ -226,14 +228,15 @@ actions create-file-from-another } In this example, the rule checks if certain build property is specified. - If so, it sets variable OPIONS that's used inside - action. Note that the variable is set "on targets" -- the value will - be only visible inside action, not globally. Were it set globally, - using variable named OPTIONS in two unrelated - actions would be impossible. + If so, it sets variable OPIONS that is then used inside + the action. Note that the variables set "on a target" will be visible only + inside actions building that target, not globally. Were they set globally, + using variable named OPTIONS in two unrelated actions + would be impossible. - More details can be found in Jam reference, + More details can be found in Jam reference, +
@@ -243,35 +246,33 @@ actions create-file-from-another The Boost.Build configuration is specified in the file user-config.jam. You can edit the one in the top-level - directory of Boost.Build installation or create a copy in your home directory - and edit that. (See for the - exact search paths.) The primary function of that file is to declare which - compilers and other tools are available. The simplest syntax to configure - a tool is: + directory of Boost.Build installation or create a copy in your home + directory and edit that. (See + for the exact search paths.) The primary function of that file is to declare + which compilers and other tools are available. The simplest syntax to + configure a tool is: -using tool-name ; +using tool-name ; - The using rule is given a name of tool, and will make that tool - available to Boost.Build. For example, using gcc ; will make the gcc compiler - available. + The using rule is given a name of tool, and + will make that tool available to Boost.Build. For example, + using gcc ; will make the gcc compiler available. - Since nothing but a tool name is specified, Boost.Build will - pick some default settings. For example, it will use the - gcc executable found in the - PATH, or look in some known installation - locations. In most cases, this strategy works automatically. In - case you have several versions of a compiler, it's installed in - some unusual location, or you need to tweak its configuration, - you'll need to pass additional parameters to the - using rule. The parameters to - using can be different for each - tool. You can obtain specific documentation for any tool's + Since nothing but a tool name is specified, Boost.Build will pick some + default settings. For example, it will use the gcc + executable found in the PATH, or look in some known + installation locations. In most cases, this strategy works automatically. + In case you have several versions of a compiler, it's installed in some + unusual location, or you need to tweak its configuration, you'll need to + pass additional parameters to the using rule. + The parameters to using can be different for + each tool. You can obtain specific documentation for any tool's configuration parameters by invoking -bjam --help tool-name.init +bjam --help tool-name.init @@ -285,28 +286,23 @@ bjam --help tool-name.init - The version - parameter identifies the toolset version, in case you have - several installed. It can have any form you like, but - it's recommended that you use a numeric identifier like - 7.1. + The version parameter + identifies the toolset version, in case you have several installed. It can + have any form you like, but it is recommended that you use a numeric + identifier like 7.1. - The invocation-command - parameter is the command that must be executed to run the - compiler. This parameter can usually be omitted if the compiler - executable + The invocation-command parameter + is the command that must be executed to run the compiler. This parameter + can usually be omitted if the compiler executable - has its “usual - name” and is in the PATH, - or - was installed in a standard - “installation directory”, - or - - can be found through a global mechanism like the - Windows registry. + has its “usual name” and is in the + PATH, or + was installed in a standard “installation + directory”, or + can be found using a global system like the Windows + registry. For example: @@ -382,7 +378,7 @@ using gcc : 3.4 : g++-3.4 ; using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ; - +
@@ -397,7 +393,7 @@ bjam To build specific targets, specify them on the command line: -bjam lib1 subproject//lib2 +bjam lib1 subproject//lib2 @@ -417,12 +413,12 @@ bjam optimization=space Boost.Build recognizes the following command line options. - + - Cleans all targets in the current directory and - in any subprojects. Note that unlike the clean + Cleans all targets in the current directory and + in any subprojects. Note that unlike the clean target in make, you can use --clean together with target names to clean specific targets. @@ -431,8 +427,8 @@ bjam optimization=space - Cleans all targets, - no matter where they are defined. In particular, it will clean targets + Cleans all targets, + no matter where they are defined. In particular, it will clean targets in parent Jamfiles, and targets defined under other project roots. @@ -444,8 +440,8 @@ bjam optimization=space Changes build directories for all project roots being built. When this option is specified, all Jamroot files should declare project name. The build directory for the project root will be computed by concatanating - the value of the option, the project name - specified in Jamroot, and the build dir specified in Jamroot + the value of the option, the project name + specified in Jamroot, and the build dir specified in Jamroot (or bin, if none is specified). @@ -477,7 +473,7 @@ bjam optimization=space - Produces debug information about loading of Boost.Build + Produces debug information about loading of Boost.Build and toolset files. @@ -493,7 +489,7 @@ bjam optimization=space - Produces debug output from generator search process. + Produces debug output from generator search process. Useful for debugging custom generators. @@ -515,11 +511,11 @@ bjam optimization=space - + - For complete specification of command line syntax, see + For complete specification of command line syntax, see @@ -546,7 +542,7 @@ bjam optimization=space - +
- +
The Build Process When you've described your targets, you want Boost.Build to run the - right tools and create the needed targets. + right tools and create the needed targets. This section will describe two things: how you specify what to build, and how the main targets are @@ -1061,7 +1057,7 @@ project tennis The most important thing to note is that in Boost.Build, unlike other build tools, the targets you declare do not correspond to specific - files. What you declare in a Jamfile is more like a “metatarget.” + files. What you declare in a Jamfile is more like a “metatarget.” - + Selecting the main target alternative to use. For each alternative we look how many properties are present both in alternative's requirements, and in build request. The alternative with large number of matching properties is selected. - - Determining "common" properties. + + Determining "common" properties. The build request is refined - with target's requirements. + with target's requirements. both the set of created "real" targets, and usage requirements. The usage requirements are added to the common properties and the resulting property - set will be used for building the current target. + set will be used for building the current target. - + Building the target using generators. To convert the sources to the desired type, Boost.Build uses "generators" --- - objects that correspond to tools like compilers and - linkers. Each generator declares what type of targets it - - can - produce and what type of sources it requires. Using this - information, Boost.Build determines which generators must be run - to produce a specific target from specific sources. When - generators are run, they return the "real" targets. + objects that correspond to tools like compilers and linkers. Each + generator declares what type of targets it can produce and what + type of sources it requires. Using this information, Boost.Build + determines which generators must be run to produce a specific + target from specific sources. When generators are run, they return + the "real" targets. - + Computing the usage requirements to be returned. The - conditional properties in usage requirements are expanded + conditional properties in usage requirements are expanded - and the - result is returned. - + and the result is returned. +
@@ -1213,22 +1205,20 @@ explicit hello_test ; The Jamfile for a project can include a number of - build-project rule calls - - that specify additional projects - to be built. + build-project rule calls that specify additional projects to + be built. - +