From 10b0a5b71f6dca8d96b034d77935815f9baeedcb Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Wed, 29 Dec 2004 08:56:52 +0000 Subject: [PATCH] Fix emphasis in tutorial examples; begin edits in advanced.xml [SVN r26596] --- doc/src/advanced.xml | 246 ++++++++++++++++++++++++++++--------------- doc/src/tutorial.xml | 4 +- 2 files changed, 162 insertions(+), 88 deletions(-) diff --git a/doc/src/advanced.xml b/doc/src/advanced.xml index 1788564a2..25aa662c8 100644 --- a/doc/src/advanced.xml +++ b/doc/src/advanced.xml @@ -7,25 +7,24 @@ This section will provide the information necessary to create your own projects using Boost.Build. The information provided here is relatively - high-level, and detailed reference as + high-level, and as well as the on-line help system must be used to obtain - low-level documentation (see the help option). + low-level documentation (see the ). - The Boost.Build actually consists of two parts - Boost.Jam, which is a + 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 event which happen when - you type "bjam" on the command is: + you type bjam on the command line is: Boost.Jam tries to find Boost.Build and loads the top-level - module. The exact process is described in the section on - initialization + module. The exact process is described in - Boost.Build top-level module loads user-defined configuration - files, "user-config.jam" and "site-config.jam", which define + The top-level module loads user-defined configuration + files, user-config.jam and site-config.jam, which define available toolsets. @@ -34,7 +33,7 @@ projects is created, with targets inside projects. - Finally, using build request specified on the command line, + 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. @@ -42,7 +41,7 @@ - So, to be able to successfully use Boost.Build, you'd need to know only + So, to be able to successfully use Boost.Build, you need to know only three things: @@ -57,6 +56,21 @@ How the build process works + + Some Basics about the Boost.Jam language. See the + Boost.Jam + and Classic + Jam documentation. + + + @@ -65,80 +79,140 @@ Configuration The Boost.Build configuration is specified in the file - "user-config.jam". You can edit the one which comes with Boost.Build, or + user-config.jam. You can edit the one that comes with Boost.Build, or + create a copy in your home directory and edit that. (See the reference for the exact search - paths.) The primary function of that file is to declarate which compilers + 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 available - the gcc compiler. + 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 tool name is specified, Boost.Build will pick some - default settings -- for example will use gcc found in path, or look in - some known installation locations. For ordinary users, this is quite - fine. In case you have several version of a compiler, or it's located in - some unusual location, or you need to tweak the configuration, you'd - need to pass additional parameters to the "using" rule. Generally, - for every tool module, the parameters differ, and you can obtain the documentaiton - by running + 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 - - on the command line. However, for all compilers the meaning of the first - three parameters is the same: version, invocation command and options. - - - The "version" parameter identifies the compiler, in case you have - several. It can have any form you like, but it's recommended that you use - a numeric identifier, like "7.1". The "invocation command" - parameter is the command which must be executed to run the compiler. This - might be just compiler name, or a name with a path in it. Here are some - examples. - - - To configure a compiler installed in non-standard location and not - present in path, you can do the following: - -using msvc : : Z:/Programs/Microsoft Visual Studio/vc98/bin/cl.exe ; +bjam --help tool-name.init + + That said, for all the compiler toolsets Boost.Build supports + out-of-the-box, the list of parameters to + using is the same: toolset-name, version, invocation-command, and options. + + - To configure several versions of a compiler, the following can be used. + 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 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. + + + For example: + +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: + +using gcc : : g++-3.2 ; + +Otherwise, it might be neccessary 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. + + + + 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 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's no need to + explicitly specify the command. - As shown above, both "version" and "invocation command" parameters - are optional, but there's an important restriction: if you configure the - same compiler more then once, you must pass the "version" parameter - every time. For example, the following is not allowed: + As shown above, both version and invocation-command parameters are + optional, but there's an important restriction: if you configure + the same toolset more than once, you must pass the version + parameter every time. For example, the following is not allowed: using gcc ; using gcc : 3.4 : g++-3.4 ; - because the first "using" does not specify the version. + because the first using call does + not specify a version. - The options parameter is used to fine-tune the - configuration. All compilers allow to pass four option, intentionally - similiar in spelling to builtin features: cflags, - cxxflags, compileflags and - linkflags. They specify additional options which will be - always passed to the corresponding tools. The cflags option - applies only to the C compiler, the cxxflags option applies - only to the C++ compiler and the compileflags options - applies to both. For example, to use 64 bit mode with gcc you can use: + The options + parameter is used to fine-tune the configuration. All of + Boost.Build's standard compiler toolsets accept properties of the + four builtin features cflags, + cxxflags, compileflags and + linkflags as options specifying flags that will be + always passed to the corresponding tools. Values of the + cflags feature are passed directly to the C + compiler, values of the cxxflags feature are + passed directly to the C++ compiler, and values of the + compileflags feature are passed to both. For + example, to configure a gcc toolset so that it + always generates 64-bit code you could write: using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ; @@ -152,10 +226,10 @@ using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ;
Overview - Jamfiles are the thing which is most important to the user, - bacause they declare the targets which should be build. Jamfiles are + Jamfiles are the thing that is most important to the user, + bacause they declare the targets that should be built. Jamfiles are also used for organizing targets -- each Jamfile is a separate project, - which can be build independently from the other projects. + which can be built independently from the other projects. Jamfile mostly contain calls to Boost.Build functions, which do all the work, specifically: @@ -289,7 +363,7 @@ boost-build /path/to/boost.build ; Main target is a user-defined named - entity which can be build, for example a named executable file. + entity that can be built, for example a named executable file. Declaring a main target is usually done using one of main target functions. The user can also declare custom @@ -436,7 +510,7 @@ lib util : util.cpp : <toolset>msvc:<link>static The default-build attribute is - a set of properties which should be used if build request does not + a set of properties that should be used if build request does not specify a value. For example: exe hello : hello.cpp : : <threading>multi ; @@ -656,7 +730,7 @@ project tennis
Additional Jamfile rules - There's a number of other helper rules which can be used in + There's a number of other helper rules that can be used in Jamfile, described in the following table. Detailed information for any of the rules can be obtained by running: @@ -710,20 +784,20 @@ bjam --help project.rule-name glob Takes a list of wildcards, and returns the list of files - which match any of the wildcards. + that match any of the wildcards. constant - Defines a constant which can be used in this project and + Defines a constant that can be used in this project and all child projects. path-constant - Defines a constant which can be used in this project and + Defines a constant that can be used in this project and all child projects. This rule should be used if value is a path relative to the location of the current project. @@ -807,7 +881,7 @@ should be absolute project id. This means that for Boost.Build, you cannot directly obtain build variant from Jamfile. There could be several variants requested by the - user, and each target can be build with different properties. + user, and each target can be built with different properties. @@ -828,7 +902,7 @@ bjam app1 lib1//lib1 toolset=gcc variant=debug optimization=full bjam app1 lib1//lib1 gcc debug optimization=full - The complete syntax which has some additional shortcuts if described here.
@@ -842,7 +916,7 @@ bjam app1 lib1//lib1 gcc debug optimization=full Applying default build. If the default-build - property of a target specifies a value of a feature which is not + property of a target specifies a value of a feature that is not present in the build request, that value is added. Selecting the main target alternative to use. For @@ -879,7 +953,7 @@ bjam app1 lib1//lib1 gcc debug optimization=full Building the target using generators. To convert the sources to the desired type, Boost.Build uses "generators" --- - objects which correspond to tools like compilers and + objects that correspond to tools like compilers and linkers. Each generator declares what type of targets in can produce and what type of sources it requires. Using this information, Boost.Build determines which generators must be run @@ -936,7 +1010,7 @@ exe hello : hello.cpp some_library.lib /some_project//library This will create an executable file from the sources -- in this case, one C++ file, one library file present in the same directory, and - another library which is created by Boost.Build. Generally, sources + another library that is created by Boost.Build. Generally, sources can include C and C++ files, object files and libraries. Boost.Build will automatically try to convert targets of other types. @@ -982,7 +1056,7 @@ lib helpers : helpers.cpp : <include>boost : : <include>. ; lib z : : <name>z <search>/home/ghost ; lib compress : : <file>/opt/libs/compress.a ; - The name property specifies the name which should be + The name property specifies the name that should be passed to the option, and the file property specifies the file location. The search feature specifies paths where the library should be searched. That feature can @@ -1037,23 +1111,23 @@ lib png : z : <name>png ; - When a library (say, a), which has another + When a library (say, a), that has another library, (say, b) is linked dynamically, the b library will be incorporated in a. (If b is dynamic library as well, then a will only refer to it, and not include any extra code.) When the a library is linked statically, Boost.Build will assure that all - executables which link to a will also link to + executables that link to a will also link to b. - One feature of Boost.Build which is very important for libraries + One feature of Boost.Build that is very important for libraries is usage requirements. For example, if you write: lib helpers : helpers.cpp : : : <include>. ; - then compiler include path for all targets which use + then compiler include path for all targets that use helpers will contain the directory where the target is defined.path to "helpers.cpp". So, the user need only to add helpers to the list of sources, and don't bother about @@ -1062,14 +1136,14 @@ lib helpers : helpers.cpp : : : <include>. ; If you don't want shared libraries to include all libraries - which are specified in sources (especially statically linked ones), + that are specified in sources (especially statically linked ones), you'd need to use the following: lib b : a.cpp ; lib a : a.cpp : <use>b : : <library>b ; This specifies that a uses b, and causes - all executables which link to a also link to + all executables that link to a also link to b. In this case, even for shared linking, the a library won't even refer to b. @@ -1170,7 +1244,7 @@ stage dist : hello will find all targets that hello depends on, and install all of the which are either executables or libraries. More - specifically, for each target, other targets which were specified as + specifically, for each target, other targets that were specified as sources or as dependency properties, will be recursively found. One exception is that targets referred with the use feature @@ -1230,7 +1304,7 @@ unit-test helpers_test : helpers_test.cpp helpers ; - The feature which combines several low-level features in + The feature that combines several low-level features in order to make building most common variants simple. @@ -1267,7 +1341,7 @@ unit-test helpers_test : helpers_test.cpp helpers ; - Feature which controls how libraries are built. + Feature that controls how libraries are built. Allowed values: shared, @@ -1403,7 +1477,7 @@ unit-test helpers_test : helpers_test.cpp helpers ; The usage requirements is also important mechanism to simplify Jamfile. If a library requires all clients to use specific includes, or macros when compiling the - code which depends on the library, this information can be cleanly + code that depends on the library, this information can be cleanly represented. The difference between "lib" and "dll" targets in V1 is completely diff --git a/doc/src/tutorial.xml b/doc/src/tutorial.xml index e19da66fb..09b109b42 100644 --- a/doc/src/tutorial.xml +++ b/doc/src/tutorial.xml @@ -755,8 +755,8 @@ exe e10 : e10.cpp foo ; lib network : network.cpp - : <link>shared:<define>NEWORK_LIB_SHARED - <variant>release:<define>EXTRA_FAST + : <link>shared:<define>NEWORK_LIB_SHARED + <variant>release:<define>EXTRA_FAST ;