From d1fffe6ec86bc2e4601b511cc0f318d0be2a2026 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jurko=20Gospodneti=C4=87?= Date: Sat, 6 Sep 2008 02:26:36 +0000 Subject: [PATCH] Minor stylistic and typo correction changes made to the Boost Build src/advanced.xml documentation file. [SVN r48625] --- doc/src/advanced.xml | 441 ++++++++++++++++++++++++------------------- 1 file changed, 245 insertions(+), 196 deletions(-) diff --git a/doc/src/advanced.xml b/doc/src/advanced.xml index 598848d1d..76800ae0b 100644 --- a/doc/src/advanced.xml +++ b/doc/src/advanced.xml @@ -5,60 +5,78 @@ Overview - 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 ). + + 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 ). + - 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 as follows: - Boost.Jam tries to find Boost.Build and loads the top-level - module. The exact process is described in - - - The top-level module loads user-defined configuration files, - user-config.jam and - site-config.jam, which define available toolsets. + + Boost.Jam tries to find Boost.Build and loads the top-level module. + The exact process is described in - The Jamfile in the current directory is read. That in turn - might cause reading of further Jamfiles. As a result, a tree of - projects is created, with targets inside projects. + + The top-level module loads user-defined configuration files, + user-config.jam and site-config.jam + , which define available toolsets. + - Finally, using the build request specified on the command line, - 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. + + The Jamfile in the current directory is read. That in turn might + cause reading of further Jamfiles. As a result, a tree of projects + is created, with targets inside projects. + + + + + Finally, using the build request specified on the command line, + Boost.Build decides which targets should be built and how. That + information is passed back to Boost.Jam, which takes care of + actually running the scheduled build action commands. + - So, to be able to successfully use Boost.Build, you need to know only - four things: + + So, to be able to successfully use Boost.Build, you need to know only four + things: - - How to configure Boost.Build + + How to configure + Boost.Build + - - How to write declares targets in Jamfiles + + How to declare targets in + Jamfiles + - - How the build process works + + How the build process + works + - Some Basics about the Boost.Jam language. See - . + + Some Basics about the Boost.Jam language. See . @@ -67,153 +85,187 @@
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. - - 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. - - 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 - value can be quoted: - -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 using the - $(variable) syntax. For example: - -a = $(b) $(c) ; + + 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. - Rules are defined by specifying the rule name, the parameter names, - and the allowed size of the list value for each parameter. - + Boost.Jam has an interpreted, procedural + language. On the lowest level, a Boost.Jam + program consists of variables and rule + rules (Jam term for + function). They are grouped into modules—there is 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. + + + 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 + value can be quoted: + +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 using the + $(variable) syntax. For example: + +a = $(b) $(c) ; + + + + + Rules are defined by specifying the rule name, the parameter names, and + the allowed value list size for each parameter. + rule example - ( - parameter1 : - parameter2 ? : - parameter3 + : - parameter4 * - ) - { - // body - } + ( + parameter1 : + parameter2 ? : + parameter3 + : + parameter4 * + ) + { + # rule 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 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 ; -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 - brackets around the call, like shown on the second line. - -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) - Comparisons: a - operator b where - operator is one of =, - !=, <, >, - <=, >=. The comparison is done - pairwise between each string in the left and the right arguments. - - - Logical operations: ! a, a && - b, a || b - Grouping: ( cond ) - - -for var in list { statements } - Executes statements for each element in list, setting the variable - var to the element value. - -while cond { statements } - Repeatedly execute statements while cond remains true upon entry. - +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 + brackets around the call, like shown on the second line. + +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) + + + + + Comparisons: a operator b + where operator is one of + =, !=, <, + >, <= or >=. The + comparison is done pairwise between each string in the left and + the right arguments. + + + + + Logical operations: ! a, a && b, + a || b + + + + + Grouping: ( cond ) + + + + +for var in list { statements } + + Executes statements for each element in list, setting the variable + var to the element value. + +while cond { statements } + + Repeatedly execute statements while cond remains true upon entry. + return values ; - This statement should be used only inside a - rule and assigns values to the return value of the - rule. - - The return statement does not exit the rule. For example: - + + This statement should be used only inside a rule and assigns + values to the return value of the rule. + + + The return statement does not exit the rule. For + example: + rule test ( ) { - if 1 = 1 { + if 1 = 1 + { return "reasonable" ; } return "strange" ; -} will return strange, not -reasonable. - - - +} + + will return strange, not + reasonable. + + + import module ; -import module : rule ; - The first form imports the specified bjam module. All rules from - that module are made available using the qualified name: - module.rule. - The second form imports the specified rules only, and they can be called - using unqualified names. +import module : rule ; + + The first form imports the specified bjam module. All rules from that + module are made available using the qualified name: + module.rule. The second + form imports the specified rules only, and they can be called using + unqualified names. Sometimes, you'd need to specify the actual command lines to be used - when creating targets. In jam language, you use named actions to do this. - For example: + when creating targets. In jam language, you use named actions to do + this. For example: 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 a list of generated files, and the - $(>) variable will be expanded to a 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 the 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 * ) { @@ -227,18 +279,18 @@ actions create-file-from-another create-file-from-another $(OPTIONS) $(<) $(>) } - In this example, the rule checks if certain build property is specified. - 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. + In this example, the rule checks if certain build property is specified. + 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, . -
@@ -265,7 +317,7 @@ using tool-name ; 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 + In case you have several versions of a compiler, it is 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 @@ -310,39 +362,39 @@ bjam --help tool-name.init using msvc : 7.1 ; using gcc ; -If the compiler can be found in the PATH but only by a -nonstandard name, you can just supply that name: + If the compiler can be found in the PATH but only by a + nonstandard name, you can just supply that name: using gcc : : g++-3.2 ; -Otherwise, it might be necessary to supply the complete path to the -compiler executable: + Otherwise, it might be necessary to supply the complete path to the + compiler executable: using msvc : : "Z:/Programs/Microsoft Visual Studio/vc98/bin/cl" ; -Some Boost.Build toolsets will use that path to take additional -actions required before invoking the compiler, such as calling -vendor-supplied scripts to set up its required environment variables. -When compiler executables for C and C++ are different, path to the C++ -compiler executable must be specified. The “invocation command” -can be any command allowed by the operating system. For example: + Some Boost.Build toolsets will use that path to take additional actions + required before invoking the compiler, such as calling vendor-supplied + scripts to set up its required environment variables. When compiler + executables for C and C++ are different, path to the C++ compiler + executable must be specified. The “invocation command” can + be any command allowed by the operating system. For example: using msvc : : echo Compiling && foo/bar/baz/cl ; -will work. + will work. - To configure several versions of a toolset, simply invoke - the using rule multiple times: + + To configure several versions of a toolset, simply invoke the + using rule multiple times: using gcc : 3.3 ; using gcc : 3.4 : g++-3.4 ; using gcc : 3.2 : g++-3.2 ; - Note that in the first call to - using, the compiler found in the - PATH will be used, and there's no need to - explicitly specify the command. + Note that in the first call to using, the + compiler found in the PATH will be used, and there is no + need to explicitly specify the command. As shown above, both the - The list of sources can also refer to other main targets. - Targets in the same project can be referred to by name, while - targets in other projects must be qualified with a directory or a - symbolic project name. The directory/project name is separated from - the target name by a double forward slash. There's no special syntax to - distinguish the directory name from the project name—the part before - the double slash is first looked up as project name, and then as directory - name. For example: + The list of sources can also refer to other main targets. Targets in + the same project can be referred to by name, while targets in other + projects must be qualified with a directory or a symbolic project + name. The directory/project name is separated from the target name by + a double forward slash. There is no special syntax to distinguish the + directory name from the project name—the part before the double + slash is first looked up as project name, and then as directory name. + For example: - lib helper : helper.cpp ; exe a : a.cpp helper ; -# Since all project ids start with slash, ".." is directory name. +# Since all project ids start with slash, ".." is a directory name. exe b : b.cpp ..//utils ; exe c : c.cpp /boost/program_options//program_options ; - The first exe uses the library defined in the same - project. The second one uses some target (most likely library) - defined by Jamfile one level higher. Finally, the third target - uses some C++ Boost - library, referring to it by absolute symbolic name. More - information about target references can be found in and C++ Boost library, referring to it using + its absolute symbolic name. More information about target references + can be found in and . -