From 2bd173c6936083a862011d73e8a5ae6edf5c150c Mon Sep 17 00:00:00 2001 From: Vladimir Prus Date: Sat, 1 Nov 2008 13:23:12 +0000 Subject: [PATCH] Improve configuration/invocation docs [SVN r49511] --- doc/src/advanced.xml | 577 ++++++++++++++++++++++++++++------------- doc/src/reference.xml | 198 +------------- doc/src/standalone.xml | 2 +- doc/src/tasks.xml | 1 + doc/src/userman.xml | 2 +- 5 files changed, 413 insertions(+), 367 deletions(-) diff --git a/doc/src/advanced.xml b/doc/src/advanced.xml index 76800ae0b..8a046a833 100644 --- a/doc/src/advanced.xml +++ b/doc/src/advanced.xml @@ -296,58 +296,109 @@ actions create-file-from-another
Configuration - 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: + + On startup, Boost.Build searches and reads two configuration files: + site-config.jam and user-config.jam. + The first one is usually installed and maintained by system administrator, and + the second is for user to modify. You can edit the one in the top-level + directory of Boost.Build installation or create a copy in your home + directory and edit the copy. The following table explains where both files + are searched. + + + + Search paths for configuration files + + + + + + + + site-config.jam + + user-config.jam + + + + + + + Linux + + + /etc + $HOME + $BOOST_BUILD_PATH + + + + $HOME + $BOOST_BUILD_PATH + + + + + Windows + + + %SystemRoot% + %HOMEDRIVE%%HOMEPATH% + %HOME% + %BOOST_BUILD_PATH% + + + + %HOMEDRIVE%%HOMEPATH% + %HOME% + %BOOST_BUILD_PATH% + + + + +
+ + + + You can use the --debug-configuration option to + find which configuration files are actually loaded. + + + + + Usually, user-config.jam just defines available compilers + and other tools (see for more advanced + usage). A tool is configured using the following syntax: + -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. + +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 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 - each tool. You can obtain specific documentation for any tool's - configuration parameters by invoking - -bjam --help tool-name.init - + All the supported tools are documented in , + including the specific options they take. Some general notes that apply to most + C++ compilers are below. + - That said, for all the compiler toolsets Boost.Build supports + For all the C++ 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. - - 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 + If you have a single compiler, and the compiler executable has its “usual name” and is in the PATH, or @@ -356,27 +407,24 @@ bjam --help tool-name.init can be found using a global system like the Windows registry. - - For example: + it can be configured by simply: -using msvc : 7.1 ; -using gcc ; +using tool-name ; - If the compiler can be found in the PATH but only by a - nonstandard name, you can just supply that name: + + + If the compiler is installed in a custom directory, you should provide the + command that invokes the compiler, for example: using gcc : : g++-3.2 ; - - 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 + executable must be specified. The command can be any command allowed by the operating system. For example: using msvc : : echo Compiling && foo/bar/baz/cl ; @@ -397,6 +445,7 @@ using gcc : 3.2 : g++-3.2 ; need to explicitly specify the command. + - 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: + + Many of toolsets have an options + parameter to fine-tune the configuration. All of + Boost.Build's standard compiler toolsets accept four options + 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 ; + using gcc : 3.4 : : <compileflags>-m64 <linkflags>-m64 ; + + + Although the syntax used to specify toolset options is very similar + to syntax used to specify requirements in Jamfiles, the toolset options + are not the same as features. Don't try to specify a feature value + in toolset initialization. + + +
Invocation - This section describes how invoke Boost.Build from the command line + To invoke Boost.Build, type bjam on the command line. Three kinds + of command-line tokens are accepted, in any order: + + + options - To build all targets defined in Jamfile in the current directory with default properties, run: + Options start with either dash, or two dashes. The standard options + are listed below, and each project may add additional options + + + + properties + + Properties specify details of what you want to build (e.g. debug + or release variant). Syntactically, all command line tokens with equal sign in them + are considered to specify properties. In the simplest form, property looks like + feature=value + + + + + target + + All tokens that are neither options nor properties specify + what targets to build. The available targets entirely depend on the project + you are building. + + + +
+ Examples + + To build all targets defined in Jamfile in the current directory with default properties, run: bjam - + + - To build specific targets, specify them on the command line: + To build specific targets, specify them on the command line: bjam lib1 subproject//lib2 - + - To request a certain value for some property, add - property=value to the command line: + To request a certain value for some property, add + property=value to the command line: bjam toolset=gcc variant=debug optimization=space - For often used features, like toolset and variant you can - omit the feature name, so the above can be written as: + +
+ +
+ Options + + Boost.Build recognizes the following command line options. + + + + + + + Invokes the online help system. This prints general + information on how to use the help system with additional + --help* options. + + + + + + + + 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. + + + + + + + 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. + + + + + + + + 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 + (or bin, if none is specified). + + + The option is primarily useful when building from read-only + media, when you can't modify Jamroot. + + + + + + + + Prints information on Boost.Build and Boost.Jam + versions. + + + + + + + + Produces debug information about loading of Boost.Build + and toolset files. + + + + + + + Prints what targets are being built and with what properties. + + + + + + + + Produces debug output from generator search process. + Useful for debugging custom generators. + + + + + + + + Do not load site-config.jam and + user-config.jam configuration files. + + + + +
+ +
+ Properties + + In the simplest case, the build is performed with a single set of properties, + that you specify on the command line with elements in the form + feature=value. + The complete list of features can be found in . + The most common features are summarized below. + + + + + + + Feature + + Allowed values + + Notes + + + + + + + variant + + debug,release + + + + + + link + + shared,static + + Determines if Boost.Build creates shared or static libraries + + + + threading + + single,multi + + Cause the produced binaries to be thread-safe. This requires proper support in the source code itself. + + + + toolset + + (Depends on configuration) + + The C++ compiler to use. See for a detailed list. + + + + cxxflags + + (Arbitrary string) + + Custom options to pass to the C++ compiler. + + + + cflags + + (Arbitrary string) + + Custom options to pass to the C compiler. + + + + includes + + (Arbitrary string) + + Additional include paths for C and C++ compilers. + + + + define + + (Arbitrary string) + + Additional macro definitions for C and C++ compilers. + + + + runtime-link + + shared,static + + Determines if shared or static version of C and C++ runtimes should be used. + + + + +
+ + If you have more than one version of a given C++ toolset (e.g. configured in + user-config.jam, or autodetected, as happens with msvc), you can + request the specific version by passing + toolset-version as + the value of the toolset feature, for example toolset=msvc-8.0. + + + + If a feature has a fixed set of values it can be specified more than + once on the command line. + In which case, everything will be built several times -- + once for each specified value of a feature. For example, if you use + -bjam optimization=space +bjam link=static link=shared threading=single threading=multi - + + Then a total of 4 builds will be performed. For convenience, + instead of specifying all requested values of a feature in separate command line elements, + you can separate the values with commands, for example: + + +bjam link=static,shared threading=single,multi + + + The comma has special meaning only if the feature has a fixed set of values, so + + +bjam include=static,shared + + is not treated specially. + +
+
+ Targets - Boost.Build recognizes the following command line options. - - - - - - - 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. - - - - - - - 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. - - - - - - - - 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 - (or bin, if none is specified). - - - The option is primarily useful when building from read-only - media, when you can't modify Jamroot. - - - - - - - - Prints information on Boost.Build and Boost.Jam - versions. - - - - - - - - Invokes the online help system. This prints general - information on how to use the help system with additional - --help* options. - - - - - - - - Produces debug information about loading of Boost.Build - and toolset files. - - - - - - - Prints what targets are being built and with what properties. - - - - - - - - Produces debug output from generator search process. - Useful for debugging custom generators. - - - - - - - - Do not load site-config.jam and - user-config.jam configuration files. - - - - - - - - Enables internal checks. - - - - - - - - For complete specification of command line syntax, see - - - + All command line elements that are neither options nor properties are the names of the + targets to build. See . If no target is specified, + the project in the current directory is built. +
diff --git a/doc/src/reference.xml b/doc/src/reference.xml index 449f6925c..a351b47b1 100644 --- a/doc/src/reference.xml +++ b/doc/src/reference.xml @@ -9,7 +9,7 @@ - Detailed reference + Reference
General information @@ -49,186 +49,9 @@ boost-build build-system ; automatically find the build system. The default bootstrap.jam, after loading some standard - definitions, loads two files, which can be provided/customised by - user: site-config.jam and user-config.jam. - - Locations where those files are searched are summarized below: - - - Search paths for configuration files - - - - - - - - site-config.jam - - user-config.jam - - - - - - - Linux - - - /etc - $HOME - $BOOST_BUILD_PATH - - - - $HOME - $BOOST_BUILD_PATH - - - - - Windows - - - %SystemRoot% - %HOMEDRIVE%%HOMEPATH% - %HOME% - %BOOST_BUILD_PATH% - - - - %HOMEDRIVE%%HOMEPATH% - %HOME% - %BOOST_BUILD_PATH% - - - - -
- - - Boost.Build comes with default versions of those files, - - which can serve as templates for customized versions. - + definitions, loads two site-config.jam and user-config.jam.
-
- Command line - - The command line may contain: - - - Jam options, - - Boost.Build options, - - Command line arguments - - -
- Command line arguments - - - Command line arguments specify targets and build - request using the following rules. - - - - - - An argument that does not contain slashes or the = - symbol is either a value of an implicit feature or of a target to - be built. It is taken to be value of a feature if an appropriate - feature exists. Otherwise, it is considered a target id. Building the - special target name “clean” has the same effect as - using the --clean option. - - - - - - An argument containing either slashes or the = symbol - specifies a number of build request elements (see ). In its simplest form, it is just - a set of properties, separated by slashes, which become a single - build request element, for example: - - -borland/runtime-link=static - - - A more complex form can be used to save typing. For example, - instead of - - -borland/runtime-link=static borland/runtime-link=dynamic - - - one can use - - -borland/runtime-link=static,dynamic - - - Exactly, the conversion from argument to build request - elements is performed by (1) splitting the argument at each slash, - (2) converting each split part into a set of properties and (3) - taking all possible combinations - - of the property sets. Each split - part should have either the form - - -feature-name=feature-value1[","feature-valueN]* - - - or, in case of implicit features - - -feature-value1[","feature-valueN;]* - - - will be converted into the property set - - -<feature-name>feature-value1 .... <feature-name>feature-valueN - - - - - - - - - - For example, the command line - - -target1 debug gcc/runtime-link=dynamic,static - - - would cause target called target1 to be rebuilt in - debug mode, except that for gcc, both dynamically and statically - linked binaries would be created. - - -
-
- Command line options - - All of the Boost.Build options start with the "--" prefix. - They are described in the following table. - - FIXME: That table has moved into "User documentation" section - and there is nothing we can add here. Remove this part? - - -
-
- @@ -805,15 +628,19 @@ path-constant DATA : data/a.txt ; Before using any tool, you must declare your intention, and possibly specify additional information about the tool's configuration. This is - done with the using rule, for example: + done by calling the using rule, typically in your + user-config.jam, for example: using gcc ; - additional parameters can be passed just like for other rules, for example: + additional parameters can be passed just like for other rules, for example: using gcc : 4.0 : g++-4.0 ; - The options that can be passed to each tool will be documented in the + + + + The options that can be passed to each tool are documented in the subsequent sections.
@@ -821,7 +648,10 @@ using gcc : 4.0 : g++-4.0 ; C++ Compilers This section lists all Boost.Build modules that support C++ - compilers and documents how each one can be initialized. + compilers and documents how each one can be initialized. The name + of support module for compiler is also the value for + the toolset feature that can be used to explicitly + request that compiler.
@@ -1310,7 +1140,7 @@ using dmc : &toolset_ops; ; &using_repeation; If the command is not specified, Boost.Build will search for - a binary named como in + a binary named dmc in PATH. &option_list_intro; diff --git a/doc/src/standalone.xml b/doc/src/standalone.xml index decde144a..be5743dfd 100644 --- a/doc/src/standalone.xml +++ b/doc/src/standalone.xml @@ -13,8 +13,8 @@ - + diff --git a/doc/src/tasks.xml b/doc/src/tasks.xml index 6ae6f4c58..8c35ae133 100644 --- a/doc/src/tasks.xml +++ b/doc/src/tasks.xml @@ -712,6 +712,7 @@ exe app : app.cpp : <implicit-dependency>parser ; as potential dependencies.
+