diff --git a/v2/doc/src/advanced.xml b/v2/doc/src/advanced.xml
index 8187a1f9e..ac7fb615c 100644
--- a/v2/doc/src/advanced.xml
+++ b/v2/doc/src/advanced.xml
@@ -3,7 +3,7 @@
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
- User documentation
+ OverviewThis section will provide the information necessary to create your own
projects using Boost.Build. The information provided here is relatively
@@ -73,7 +73,7 @@
- Boost.Jam language
+ Boost.Jam LanguageThis section will describe the basics of the Boost.Jam
language—just enough for writing Jamfiles. For more information,
@@ -536,7 +536,7 @@ bjam optimization=space
- Declaring targets
+ Declaring Targets
A Main target is a user-defined named
@@ -769,7 +769,7 @@ rule my-rule ( properties * )
- Default build
+ Default BuildThe default-build parameter
is a set of properties to be used if the build request does
@@ -785,7 +785,7 @@ exe hello : hello.cpp : : <threading>multi ;
- Additional information
+ Additional Information
The ways a target is built can be so different that
@@ -826,7 +826,7 @@ exe hello : hello.cpp
explicit request, this can be expressed by the
explicit rule:
- explicit install_programs ;
+explicit install_programs ;
@@ -1028,90 +1028,6 @@ project tennis
perfectly appropriate to start a user guide with that kind
of material. -->
-
-
-
- Jamfile Utility Rules
-
- The following table describes utility rules that can be
- used in Jamfiles. Detailed information for any of these rules can
- be obtained by running:
-
-bjam --help project.rulename
-
-
-
-
-
-
-
-
- Rule
-
- Semantics
-
-
-
-
-
- project
-
-
- Define this project's symbolic ID or attributes.
-
-
-
- use-project
-
- Make another project known so that it can be referred to by symbolic ID.
-
-
-
- build-project
-
- Cause another project to be built when this one is built.
-
-
-
- explicit
-
- State that a target should be built only by explicit
- request.
-
-
-
- glob
-
- Translate a list of shell-style wildcards into a
- corresponding list of files.
-
-
-
- constant
-
- Injects a variable setting into this project's
- Jamfile module and those of all its subprojects.
-
-
-
- path-constant
-
- Injects a variable set to a path value into
- this project's Jamfile module and those of all its subprojects.
- If the value is a relative path it will be adjusted for
- each subproject so that it refers to the same
- directory.
-
-
-
-
-
-
- The Build Process
@@ -1147,7 +1063,7 @@ bjam --help project.rulename
- Build request
+ Build Request
The command line specifies which targets to build and with which
@@ -1253,7 +1169,7 @@ bjam app1 lib1//lib1 gcc debug optimization=full
- Building a project
+ Building a ProjectOften, a user builds a complete project, not just one main
target. In fact, invoking bjam without
@@ -1287,763 +1203,6 @@ explicit hello_test ;
-
-
- Builtin target types
-
- This section describes main targets types that Boost.Build supports
- of-of-the-box. Unless otherwise noted, all mentioned main target rules
- have the common signature, described in .
-
-
-
- Programs
-
- Builtin
- rulesexe
- Programs are created using the exe rule, which
- follows the common
- syntax. For example:
-
-exe hello : hello.cpp some_library.lib /some_project//library
- : <threading>multi
- ;
-
- 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 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.
-
-
-
-
- On Windows, if an application uses dynamic libraries, and both
- the application and the libraries are built by Boost.Build, its not
- possible to immediately run the application, because the
- PATH environment variable should include the path
- to the libraries. It means you have to either add the paths
- manually, or place the application and the libraries to the same
- directory, for example using the
- stage rule.
-
-
-
-
-
-
- Libraries
-
- Libraries are created using the lib rule, which
- follows the common
- syntax. For example:
-
-lib helpers : helpers.cpp : <include>boost : : <include>. ;
-
-
-
- In the most common case, the lib creates a library
- from the specified sources. Depending on the value of
- <link> feature the library will be either static or
- shared. There are two other cases. First is when the library is
- installed somewhere in compiler's search paths, and should be
- searched by the compiler (typically, using the
- option). The second case is where the library is available as a
- prebuilt file and the full path is known.
-
-
-
-
- The syntax for these case is given below:
-
-lib z : : <name>z <search>/home/ghost ;
-lib compress : : <file>/opt/libs/compress.a ;
-
- 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 in which to search for the library. That feature can
- be specified several times, or it can be omitted, in which case only
- default compiler paths will be searched.
-
-
- The difference between using the file feature as
- opposed to the name feature together with the
- search feature is that file is more
- precise. A specific file will be used. On the other hand, the
- search feature only adds a library path, and the
- name feature gives the basic name of the library. The
- search rules are specific to the linker. For example, given these
- definition:
-
-lib a : : <variant>release <file>/pool/release/a.so ;
-lib a : : <variant>debug <file>/pool/debug/a.so ;
-lib b : : <variant>release <file>/pool/release/b.so ;
-lib b : : <variant>debug <file>/pool/debug/b.so ;
-
- It's possible to use release version of a and debug
- version of b. Had we used the name and
- search features, the linker would always pick either
- release or debug versions.
-
-
-
-
- For convenience, the following syntax is allowed:
-
-lib z ;
-lib gui db aux ;
-
- and is does exactly the same as:
-
-lib z : : <name>z ;
-lib gui : : <name>gui ;
-lib db : : <name>db ;
-lib aux : : <name>aux ;
-
-
-
- When a library uses another library you should put that other
- library in the list of sources. This will do the right thing in all
- cases. For portability, you should specify library dependencies even
- for searched and prebuilt libraries, othewise, static linking on
- Unix won't work. For example:
-
-lib z ;
-lib png : z : <name>png ;
-
-
-
-
- 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 that link to a will also link to
- b.
-
-
-
- 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 the compiler include path for all targets that use
- helpers will contain the directory
-
- where the target is defined.path to "helpers.cpp". The user
- only needs to add helpers to the list of sources,
- and needn't consider the requirements its use imposes on a
- dependent target. This feature greatly simplifies Jamfiles.
-
-
-
-
- If you don't want shared libraries to include all libraries
- 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 that link to a also link to
- b. In this case, even for shared linking, the
- a library won't even refer to b.
-
-
-
-
-
-
- Alias
-
-
- The alias rule gives alternative name to
- a group of targets. For example, to give the name
- core to a group of three other targets with the
- following code:
-
-alias core : im reader writer ;
- Using core on the command line, or in the source list
- of any other target is the same as explicitly using
- im, reader, and
- writer, but it is just more convenient.
-
-
-
-
-
- Another use of the alias rule is to change build
- properties. For example, if you always want static linking for a
- specific C++ Boost library, you can write the following:
-
-alias threads : /boost/thread//boost_thread : <link>static ;
-
- and use only the threads alias in your Jamfiles.
-
-
-
-
- You can also specify usage requirements for the
- alias target. If you write the following:
-
-alias header_only_library : : : : <include>/usr/include/header_only_library ;
-
- then using header_only_library in sources will only add an
- include path. Also note that when there are some sources, their usage
- requirements are propagated, too. For example:
-
-lib lib : lib.cpp : : : <include>. ;
-alias lib_alias ;
-exe main : main.cpp lib_alias ;
-
- will compile main.cpp with the additional include.
-
-
-
-
-
- Installing
-
- For installing a built target you should use the
- install rule, which follows the common syntax. For
- example:
-
-install dist : hello helpers ;
-
- will cause the targets hello and helpers to
- be moved to the dist directory, relative to
- Jamfile's directory. The directory can
- be changed with the location property:
-
-install dist : hello helpers : <location>/usr/bin ;
-
- While you can achieve the same effect by changing the target name to
- /usr/bin, using the location
- property is better, because it allows you to use a mnemonic target
- name.
-
-
- The location property is especially handy when the location
- is not fixed, but depends on build variant or environment variables:
-
-install dist : hello helpers : <variant>release:<location>dist/release
- <variant>debug:<location>dist/debug ;
-install dist2 : hello helpers : <location>$(DIST) ;
-
- See also conditional
- properties and environment variables
-
-
-
- Specifying the names of all libraries to install can be boring. The
- install allows you to specify only the top-level executable
- targets to install, and automatically install all dependencies:
-
-install dist : hello
- : <install-dependencies>on <install-type>EXE
- <install-type>LIB
- ;
-
- will find all targets that hello depends on, and install
- all of those which are either executables or libraries. More
- 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
- are not considered, because that feature is typically used to refer to
- header-only libraries.
- If the set of target types is specified, only targets of that type
- will be installed, otherwise, all found target will be installed.
-
-
- The alias
- rule can be used when targets must be installed into several
- directories:
-
-alias install : install-bin install-lib ;
-install install-bin : applications : /usr/bin ;
-install install-lib : helper : /usr/lib ;
-
-
-
- Because the install rule just copies targets, most
- free features see the definition of "free" in .
- have no effect when used in requirements of the install rule.
- The only two which matter are
-
- dependency and, on Unix,
- dll-path.
-
-
-
-
- (Unix specific). On Unix, executables built with Boost.Build typically
- contain the list of paths to all used dynamic libraries. For
- installing, this is not desired, so Boost.Build relinks the executable
- with an empty list of paths. You can also specify additional paths for
- installed executables with the dll-path feature.
-
-
-
-
-
-
-
-
- Testing
-
- Boost.Build has convenient support for running unit tests. The
- simplest way is the unit-test rule, which follows the
- common syntax. For
- example:
-
-unit-test helpers_test : helpers_test.cpp helpers ;
-
-
-
- The unit-test rule behaves like the
- exe rule, but after the executable is created it is
- run. If the executable returns an error code, the build system will also
- return an error and will try running the executable on the next
- invocation until it runs successfully. This behaviour ensures that you
- can't miss a unit test failure.
-
-
- By default, the executable is run directly. Sometimes, it's
- desirable to run the executable using some helper command. You should use the
- testing.launcher property to specify the name of the
- helper command. For example, if you write:
-
-
-unit-test helpers_test
- : helpers_test.cpp helpers
- : <testing.launcher>valgrind
- ;
-
- The command used to run the executable will be:
-
-valgrind bin/$toolset/debug/helpers_test
-
-
-
-
- There are rules for more elaborate testing: compile,
- compile-fail, run and
- run-fail. They are more suitable for automated testing, and
- are not covered here.
-
-
-
-
-
- Raw commands: 'make' and 'notfile'
-
- Sometimes, the builtin target types are not enough, and you
- want Boost.Build to just run specific commands. There are two main
- target rules that make it possible: make
- and notfile.
-
-
- The make rule is used when you want to
- create one file from a number of sources using some specific command.
- The notfile is used to unconditionally run
- a command.
-
-
-
- Suppose you want to create file file.out from
- file file.in by running command
- in2out. Here's how you'd do this in Boost.Build:
-
-actions in2out
-{
- in2out $(<) $(>)
-}
-make file.out : file.in : @in2out ;
-
- If you run bjam and file.out
- does not exist, Boost.Build will run the in2out
- command to create that file. For more details on specifying actions,
- see .
-
-
-
-
- The make rule is useful to express custom
- transformation that are used just once or twice in your project. For
- transformations that are used often, you are advised to declare
- new generator, as described in .
-
-
-
-
- It could be that you just want to run some command unconditionally,
- and that command does not create any specific files. The, you can use
- the notfile rule. For example:
-
-notfile echo_something : @echo ;
-actions echo
-{
- echo "something"
-}
-
- The only difference from the make rule is
- that the name of the target is not considered a name of a file, so
- Boost.Build will unconditionally run the action.
-
-
-
-
-
-
-
- Builtin features
-
-
- variant
-
-
-
- A feature that combines several low-level features, making
- it easy to request common build configurations.
-
-
- Allowed values:debug, release,
- profile.
-
- The value debug expands to
-
-
-<optimization>off <debug-symbols>on <inlining>off <runtime-debugging>on
-
-
- The value release expands to
-
-
-<optimization>speed <debug-symbols>off <inlining>full <runtime-debugging>off
-
-
- The value profile expands to the same as
- release, plus:
-
-
-<profiling>on <debug-symbols>on
-
-
- User can define his own build variants using the variant rule from the common
- module.
-
- Notee: Runtime
- debugging is on in debug builds to suit the expectations of
- people used to various IDEs.
-
-
-
-
-
- link
-
-
-
- A feature that controls how libraries are built.
-
-
- Allowed values:shared,
- static
-
-
- source
-
-
-
- The <source>X feature has the same effect on
- building a target as putting X in the list of sources.
- It's useful when you want to add
- the same source to all targets in the project
- (you can put <source> in requirements) or to conditionally
- include a source (using conditional requirements, see )
- See also the <library> feature.
-
-
-
-
- library
-
-
-
- This feature is almost equivalent to the <source> feature,
- except that it takes effect only for linking. When you want to
- link all targets in a Jamfile to certain library, the
- <library> feature is preferred over
- <source>X -- the latter will add the library to
- all targets, even those that have nothing to do with libraries.
-
-
-
-
-
- dependency
-
-
-
- Introduces a dependency on the target named by the
- value of this feature (so it will be brought
- up-to-date whenever the target being declared is).
- The dependency is not used in any other way. For example, in
- application with plugins, the plugins are not used when linking
- the application,
- application might have dependency on its plugins, even though
-
-
- , and
- adds its usage requirements to the build properties
- of the target being declared.
-
- The primary use case is when you want
- the usage requirements (such as #include paths) of some
- library to be applied, but don't want to link to it.
-
-
-
-
-
-
-
- use
-
-
-
- Introduces a dependency on the target named by the
- value of this feature (so it will be brought
- up-to-date whenever the target being declared is), and
- adds its usage requirements to the build properties
-
- of the target being declared. The dependency is not used
- in any other way. The primary use case is when you want
- the usage requirements (such as #include paths) of some
- library to be applied, but don't want to link to it.
-
-
-
-
-
-
- dll-path
-
-
-
- Specify an additional directory where the system should
- look for shared libraries when the executable or shared
- library is run. This feature only affects Unix
- compilers. Plase see
- in for details.
-
-
-
- hardcode-dll-paths
-
-
-
- Controls automatic generation of dll-path properties.
-
-
- Allowed values:
- true, false. This property
- is specific to Unix systems. If an executable is built with
- <hardcode-dll-paths>true, the generated binary
- will contain the list of all the paths to the used shared
- libraries. As the result, the executable can be run without
- changing system paths to shared libraries or installing the
- libraries to system paths. This
-
- is very convenient during
- development. Plase see the FAQ entry for details.
- Note that on Mac OSX, the paths are unconditionally hardcoded by
- the linker, and it's not possible to disable that behaviour.
-
-
-
-
- cflags
- cxxflags
- linkflags
-
-
-
- The value of those features is passed without modification to the
- corresponding tools. For cflags that's both the C and C++
- compilers, for cxxflags that's the C++ compiler and for
- linkflags that's the linker. The features are handy when
- you're trying to do something special that cannot be achieved by
- higher-level feature in Boost.Build.
-
-
-
-
- warnings
-
-
-
- The <warnings> feature controls the warning level of compilers. It has the following values:
-
- off - disables all warnings.
- on - enables default warning level for the tool.
- all - enables all warnings.
-
- Default value is all.
-
-
-
-
- warnings-as-errors
-
-
-
- The <warnings-as-errors> makes it possible to treat warnings as errors and abort
- compilation on a warning. The value on enables this behaviour. The default value is
- off.
-
-
-
-
- build
-
-
- Allowed values:no
-
-
- The build feature is used to conditionally disable build of a target. If <build>no
- is in properties when building a target, build of that target is skipped. Combined with conditional requirements this
- allows to skip building some target in configurations where the build is known to fail.
-
-
-
-
-
-
-
-
-
-
-
-
- Differences to Boost.Build V1
-
-
- While Boost.Build V2 is based on the same ideas as Boost.Build V1,
- some of the syntax was changed, and some new important features were
- added. This chapter describes most of the changes.
-
-
- Configuration
-
- In V1, toolsets were configured by environment variables. If you
- wanted to use two versions of the same toolset, you had to create a new
- toolset module that would set the variables and then invoke the base
- toolset. In V2, toolsets are configured by the
- using, and you can easily configure several
- versions of a toolset. See for details.
-
-
-
-
-
- Writing Jamfiles
-
- Probably one of the most important differences in V2 Jamfiles is
- the use of project requirements. In V1, if several targets had the same
- requirements (for example, a common #include path), it was necessary to
- manually write the requirements or use a helper rule or template target. In V2, the
- common properties can be specified with the requirements project
- attribute, as documented in .
-
-
- Usage requirements
- also help to simplify Jamfiles.
-
- If a library requires
- all clients to use specific #include paths or macros when compiling
- code that depends on the library, that information can be cleanly
- represented.
-
- The difference between lib and dll targets in V1 is completely
- eliminated in V2. There's only one library target type, lib, which can create
- either static or shared libraries depending on the value of the
- <link>
- feature. If your target should be only built in one way, you
- can add <link>shared or <link>static to its requirements.
-
-
- The syntax for referring to other targets was changed a bit. While
- in V1 one would use:
-
-exe a : a.cpp <lib>../foo/bar ;
-
- the V2 syntax is:
-
-exe a : a.cpp ../foo//bar ;
-
- Note that you don't need to specify the type of other target, but the
- last element should be separated from the others by a double slash to indicate that
- you're referring to target bar in project ../foo, and not to
- project ../foo/bar.
-
-
-
-
-
-
- Build process
-
- The command line syntax in V2 is completely different. For example
-
-bjam -sTOOLS=msvc -sBUILD=release some_target
-
- now becomes:
-
-bjam toolset=msvc variant=release some_target
-
- or, using implicit features, just:
-
-bjam msvc release some_target
-
- See the reference for a
- complete description of the syntax.
-
-
-
-
-
-
diff --git a/v2/doc/src/reference.xml b/v2/doc/src/reference.xml
index ceaa9c98c..d3c6796f6 100644
--- a/v2/doc/src/reference.xml
+++ b/v2/doc/src/reference.xml
@@ -228,49 +228,90 @@ target1 debug gcc/runtime-link=dynamic,static
-
- Writing Jamfiles
+
+ Jamfile Utility Rules
- This section describes specific information about writing Jamfiles.
-
-
- Generated headers
-
- Usually, Boost.Build handles implicit dependendies completely
- automatically. For example, for C++ files, all #include
- statements are found and handled. The only aspect where user help
- might be needed is implicit dependency on generated files.
-
- By default, Boost.Build handles such dependencies within one
- main target. For example, assume that main target "app" has two
- sources, "app.cpp" and "parser.y". The latter source is converted
- into "parser.c" and "parser.h". Then, if "app.cpp" includes
- "parser.h", Boost.Build will detect this dependency. Moreover,
- since "parser.h" will be generated into a build directory, the
- path to that directory will automatically added to include
- path.
-
- Making this mechanism work across main target boundaries is
- possible, but imposes certain overhead. For that reason, if
- there's implicit dependency on files from other main targets, the
- <implicit-dependency> [ link ] feature must
- be used, for example:
-
-
-lib parser : parser.y ;
-exe app : app.cpp : <implicit-dependency>parser ;
-
-
-
- The above example tells the build system that when scanning
- all sources of "app" for implicit-dependencies, it should consider
- targets from "parser" as potential dependencies.
+ The following table describes utility rules that can be
+ used in Jamfiles. Detailed information for any of these rules can
+ be obtained by running:
+
+bjam --help project.rulename
+
+
+
+
+
+
+
+ Rule
+
+ Semantics
+
+
+
+
+
+ project
+
+
+ Define this project's symbolic ID or attributes.
+
+
+
+ use-project
+
+ Make another project known so that it can be referred to by symbolic ID.
+
+
+
+ build-project
+
+ Cause another project to be built when this one is built.
+
+
+
+ explicit
+
+ State that a target should be built only by explicit
+ request.
+
+
+
+ glob
+
+ Translate a list of shell-style wildcards into a
+ corresponding list of files.
+
+
+
+ constant
+
+ Injects a variable setting into this project's
+ Jamfile module and those of all its subprojects.
+
+
+
+ path-constant
+
+ Injects a variable set to a path value into
+ this project's Jamfile module and those of all its subprojects.
+ If the value is a relative path it will be adjusted for
+ each subproject so that it refers to the same
+ directory.
+
+
+
+
+
+
-
-
Build process
diff --git a/v2/doc/src/standalone.xml b/v2/doc/src/standalone.xml
index c16af5dfe..527237274 100644
--- a/v2/doc/src/standalone.xml
+++ b/v2/doc/src/standalone.xml
@@ -1,27 +1,30 @@
-
-
- Boost.Build v2 User Manual
+ Boost.Build V2 User Manual
+
-
+
- Boost.Jam documentation
+ Boost.Jam Documentation
-
+
+
+
diff --git a/v2/doc/src/tasks.xml b/v2/doc/src/tasks.xml
new file mode 100644
index 000000000..eaabf6167
--- /dev/null
+++ b/v2/doc/src/tasks.xml
@@ -0,0 +1,710 @@
+
+
+
+
+ Common tasks
+
+ This section describes main targets types that Boost.Build supports
+ of-of-the-box. Unless otherwise noted, all mentioned main target rules
+ have the common signature, described in .
+
+
+
+ Programs
+
+ Builtin
+ rulesexe
+ Programs are created using the exe rule, which
+ follows the common
+ syntax. For example:
+
+exe hello : hello.cpp some_library.lib /some_project//library
+ : <threading>multi
+ ;
+
+ 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 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.
+
+
+
+
+ On Windows, if an application uses dynamic libraries, and both
+ the application and the libraries are built by Boost.Build, its not
+ possible to immediately run the application, because the
+ PATH environment variable should include the path
+ to the libraries. It means you have to either add the paths
+ manually, or place the application and the libraries to the same
+ directory, for example using the
+ stage rule.
+
+
+
+
+
+
+ Libraries
+
+ Libraries are created using the lib rule, which
+ follows the common
+ syntax. For example:
+
+lib helpers : helpers.cpp : <include>boost : : <include>. ;
+
+
+
+ In the most common case, the lib creates a library
+ from the specified sources. Depending on the value of
+ <link> feature the library will be either static or
+ shared. There are two other cases. First is when the library is
+ installed somewhere in compiler's search paths, and should be
+ searched by the compiler (typically, using the
+ option). The second case is where the library is available as a
+ prebuilt file and the full path is known.
+
+
+
+
+ The syntax for these case is given below:
+
+lib z : : <name>z <search>/home/ghost ;
+lib compress : : <file>/opt/libs/compress.a ;
+
+ 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 in which to search for the library. That feature can
+ be specified several times, or it can be omitted, in which case only
+ default compiler paths will be searched.
+
+
+ The difference between using the file feature as
+ opposed to the name feature together with the
+ search feature is that file is more
+ precise. A specific file will be used. On the other hand, the
+ search feature only adds a library path, and the
+ name feature gives the basic name of the library. The
+ search rules are specific to the linker. For example, given these
+ definition:
+
+lib a : : <variant>release <file>/pool/release/a.so ;
+lib a : : <variant>debug <file>/pool/debug/a.so ;
+lib b : : <variant>release <file>/pool/release/b.so ;
+lib b : : <variant>debug <file>/pool/debug/b.so ;
+
+ It's possible to use release version of a and debug
+ version of b. Had we used the name and
+ search features, the linker would always pick either
+ release or debug versions.
+
+
+
+
+ For convenience, the following syntax is allowed:
+
+lib z ;
+lib gui db aux ;
+
+ and is does exactly the same as:
+
+lib z : : <name>z ;
+lib gui : : <name>gui ;
+lib db : : <name>db ;
+lib aux : : <name>aux ;
+
+
+
+ When a library uses another library you should put that other
+ library in the list of sources. This will do the right thing in all
+ cases. For portability, you should specify library dependencies even
+ for searched and prebuilt libraries, othewise, static linking on
+ Unix won't work. For example:
+
+lib z ;
+lib png : z : <name>png ;
+
+
+
+
+ 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 that link to a will also link to
+ b.
+
+
+
+ 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 the compiler include path for all targets that use
+ helpers will contain the directory
+
+ where the target is defined.path to "helpers.cpp". The user
+ only needs to add helpers to the list of sources,
+ and needn't consider the requirements its use imposes on a
+ dependent target. This feature greatly simplifies Jamfiles.
+
+
+
+
+ If you don't want shared libraries to include all libraries
+ 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 that link to a also link to
+ b. In this case, even for shared linking, the
+ a library won't even refer to b.
+
+
+
+
+
+
+ Alias
+
+
+ The alias rule gives alternative name to
+ a group of targets. For example, to give the name
+ core to a group of three other targets with the
+ following code:
+
+alias core : im reader writer ;
+ Using core on the command line, or in the source list
+ of any other target is the same as explicitly using
+ im, reader, and
+ writer, but it is just more convenient.
+
+
+
+
+
+ Another use of the alias rule is to change build
+ properties. For example, if you always want static linking for a
+ specific C++ Boost library, you can write the following:
+
+alias threads : /boost/thread//boost_thread : <link>static ;
+
+ and use only the threads alias in your Jamfiles.
+
+
+
+
+ You can also specify usage requirements for the
+ alias target. If you write the following:
+
+alias header_only_library : : : : <include>/usr/include/header_only_library ;
+
+ then using header_only_library in sources will only add an
+ include path. Also note that when there are some sources, their usage
+ requirements are propagated, too. For example:
+
+lib lib : lib.cpp : : : <include>. ;
+alias lib_alias ;
+exe main : main.cpp lib_alias ;
+
+ will compile main.cpp with the additional include.
+
+
+
+
+
+ Installing
+
+ For installing a built target you should use the
+ install rule, which follows the common syntax. For
+ example:
+
+install dist : hello helpers ;
+
+ will cause the targets hello and helpers to
+ be moved to the dist directory, relative to
+ Jamfile's directory. The directory can
+ be changed with the location property:
+
+install dist : hello helpers : <location>/usr/bin ;
+
+ While you can achieve the same effect by changing the target name to
+ /usr/bin, using the location
+ property is better, because it allows you to use a mnemonic target
+ name.
+
+
+ The location property is especially handy when the location
+ is not fixed, but depends on build variant or environment variables:
+
+install dist : hello helpers : <variant>release:<location>dist/release
+ <variant>debug:<location>dist/debug ;
+install dist2 : hello helpers : <location>$(DIST) ;
+
+ See also conditional
+ properties and environment variables
+
+
+
+ Specifying the names of all libraries to install can be boring. The
+ install allows you to specify only the top-level executable
+ targets to install, and automatically install all dependencies:
+
+install dist : hello
+ : <install-dependencies>on <install-type>EXE
+ <install-type>LIB
+ ;
+
+ will find all targets that hello depends on, and install
+ all of those which are either executables or libraries. More
+ 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
+ are not considered, because that feature is typically used to refer to
+ header-only libraries.
+ If the set of target types is specified, only targets of that type
+ will be installed, otherwise, all found target will be installed.
+
+
+ The alias
+ rule can be used when targets must be installed into several
+ directories:
+
+alias install : install-bin install-lib ;
+install install-bin : applications : /usr/bin ;
+install install-lib : helper : /usr/lib ;
+
+
+
+ Because the install rule just copies targets, most
+ free features see the definition of "free" in .
+ have no effect when used in requirements of the install rule.
+ The only two which matter are
+
+ dependency and, on Unix,
+ dll-path.
+
+
+
+
+ (Unix specific). On Unix, executables built with Boost.Build typically
+ contain the list of paths to all used dynamic libraries. For
+ installing, this is not desired, so Boost.Build relinks the executable
+ with an empty list of paths. You can also specify additional paths for
+ installed executables with the dll-path feature.
+
+
+
+
+
+
+
+
+ Testing
+
+ Boost.Build has convenient support for running unit tests. The
+ simplest way is the unit-test rule, which follows the
+ common syntax. For
+ example:
+
+unit-test helpers_test : helpers_test.cpp helpers ;
+
+
+
+ The unit-test rule behaves like the
+ exe rule, but after the executable is created it is
+ run. If the executable returns an error code, the build system will also
+ return an error and will try running the executable on the next
+ invocation until it runs successfully. This behaviour ensures that you
+ can't miss a unit test failure.
+
+
+ By default, the executable is run directly. Sometimes, it's
+ desirable to run the executable using some helper command. You should use the
+ testing.launcher property to specify the name of the
+ helper command. For example, if you write:
+
+
+unit-test helpers_test
+ : helpers_test.cpp helpers
+ : <testing.launcher>valgrind
+ ;
+
+ The command used to run the executable will be:
+
+valgrind bin/$toolset/debug/helpers_test
+
+
+
+
+ There are rules for more elaborate testing: compile,
+ compile-fail, run and
+ run-fail. They are more suitable for automated testing, and
+ are not covered here.
+
+
+
+
+
+ Raw commands: 'make' and 'notfile'
+
+ Sometimes, the builtin target types are not enough, and you
+ want Boost.Build to just run specific commands. There are two main
+ target rules that make it possible: make
+ and notfile.
+
+
+ The make rule is used when you want to
+ create one file from a number of sources using some specific command.
+ The notfile is used to unconditionally run
+ a command.
+
+
+
+ Suppose you want to create file file.out from
+ file file.in by running command
+ in2out. Here's how you'd do this in Boost.Build:
+
+actions in2out
+{
+ in2out $(<) $(>)
+}
+make file.out : file.in : @in2out ;
+
+ If you run bjam and file.out
+ does not exist, Boost.Build will run the in2out
+ command to create that file. For more details on specifying actions,
+ see .
+
+
+
+
+ The make rule is useful to express custom
+ transformation that are used just once or twice in your project. For
+ transformations that are used often, you are advised to declare
+ new generator, as described in .
+
+
+
+
+ It could be that you just want to run some command unconditionally,
+ and that command does not create any specific files. The, you can use
+ the notfile rule. For example:
+
+notfile echo_something : @echo ;
+actions echo
+{
+ echo "something"
+}
+
+ The only difference from the make rule is
+ that the name of the target is not considered a name of a file, so
+ Boost.Build will unconditionally run the action.
+
+
+
+
+
+ Generated headers
+
+ Usually, Boost.Build handles implicit dependendies completely
+ automatically. For example, for C++ files, all #include
+ statements are found and handled. The only aspect where user help
+ might be needed is implicit dependency on generated files.
+
+ By default, Boost.Build handles such dependencies within one
+ main target. For example, assume that main target "app" has two
+ sources, "app.cpp" and "parser.y". The latter source is converted
+ into "parser.c" and "parser.h". Then, if "app.cpp" includes
+ "parser.h", Boost.Build will detect this dependency. Moreover,
+ since "parser.h" will be generated into a build directory, the
+ path to that directory will automatically added to include
+ path.
+
+ Making this mechanism work across main target boundaries is
+ possible, but imposes certain overhead. For that reason, if
+ there's implicit dependency on files from other main targets, the
+ <implicit-dependency> [ link ] feature must
+ be used, for example:
+
+
+lib parser : parser.y ;
+exe app : app.cpp : <implicit-dependency>parser ;
+
+
+
+ The above example tells the build system that when scanning
+ all sources of "app" for implicit-dependencies, it should consider
+ targets from "parser" as potential dependencies.
+
+
+
+
+
+ Builtin features
+
+
+ variant
+
+
+
+ A feature that combines several low-level features, making
+ it easy to request common build configurations.
+
+
+ Allowed values:debug, release,
+ profile.
+
+ The value debug expands to
+
+
+<optimization>off <debug-symbols>on <inlining>off <runtime-debugging>on
+
+
+ The value release expands to
+
+
+<optimization>speed <debug-symbols>off <inlining>full <runtime-debugging>off
+
+
+ The value profile expands to the same as
+ release, plus:
+
+
+<profiling>on <debug-symbols>on
+
+
+ User can define his own build variants using the variant rule from the common
+ module.
+
+ Notee: Runtime
+ debugging is on in debug builds to suit the expectations of
+ people used to various IDEs.
+
+
+
+
+
+ link
+
+
+
+ A feature that controls how libraries are built.
+
+
+ Allowed values:shared,
+ static
+
+
+ source
+
+
+
+ The <source>X feature has the same effect on
+ building a target as putting X in the list of sources.
+ It's useful when you want to add
+ the same source to all targets in the project
+ (you can put <source> in requirements) or to conditionally
+ include a source (using conditional requirements, see )
+ See also the <library> feature.
+
+
+
+
+ library
+
+
+
+ This feature is almost equivalent to the <source> feature,
+ except that it takes effect only for linking. When you want to
+ link all targets in a Jamfile to certain library, the
+ <library> feature is preferred over
+ <source>X -- the latter will add the library to
+ all targets, even those that have nothing to do with libraries.
+
+
+
+
+
+ dependency
+
+
+
+ Introduces a dependency on the target named by the
+ value of this feature (so it will be brought
+ up-to-date whenever the target being declared is).
+ The dependency is not used in any other way. For example, in
+ application with plugins, the plugins are not used when linking
+ the application,
+ application might have dependency on its plugins, even though
+
+
+ , and
+ adds its usage requirements to the build properties
+ of the target being declared.
+
+ The primary use case is when you want
+ the usage requirements (such as #include paths) of some
+ library to be applied, but don't want to link to it.
+
+
+
+
+
+
+
+ use
+
+
+
+ Introduces a dependency on the target named by the
+ value of this feature (so it will be brought
+ up-to-date whenever the target being declared is), and
+ adds its usage requirements to the build properties
+
+ of the target being declared. The dependency is not used
+ in any other way. The primary use case is when you want
+ the usage requirements (such as #include paths) of some
+ library to be applied, but don't want to link to it.
+
+
+
+
+
+
+ dll-path
+
+
+
+ Specify an additional directory where the system should
+ look for shared libraries when the executable or shared
+ library is run. This feature only affects Unix
+ compilers. Plase see
+ in for details.
+
+
+
+ hardcode-dll-paths
+
+
+
+ Controls automatic generation of dll-path properties.
+
+
+ Allowed values:
+ true, false. This property
+ is specific to Unix systems. If an executable is built with
+ <hardcode-dll-paths>true, the generated binary
+ will contain the list of all the paths to the used shared
+ libraries. As the result, the executable can be run without
+ changing system paths to shared libraries or installing the
+ libraries to system paths. This
+
+ is very convenient during
+ development. Plase see the FAQ entry for details.
+ Note that on Mac OSX, the paths are unconditionally hardcoded by
+ the linker, and it's not possible to disable that behaviour.
+
+
+
+
+ cflags
+ cxxflags
+ linkflags
+
+
+
+ The value of those features is passed without modification to the
+ corresponding tools. For cflags that's both the C and C++
+ compilers, for cxxflags that's the C++ compiler and for
+ linkflags that's the linker. The features are handy when
+ you're trying to do something special that cannot be achieved by
+ higher-level feature in Boost.Build.
+
+
+
+
+ warnings
+
+
+
+ The <warnings> feature controls the warning level of compilers. It has the following values:
+
+ off - disables all warnings.
+ on - enables default warning level for the tool.
+ all - enables all warnings.
+
+ Default value is all.
+
+
+
+
+ warnings-as-errors
+
+
+
+ The <warnings-as-errors> makes it possible to treat warnings as errors and abort
+ compilation on a warning. The value on enables this behaviour. The default value is
+ off.
+
+
+
+
+ build
+
+
+ Allowed values:no
+
+
+ The build feature is used to conditionally disable build of a target. If <build>no
+ is in properties when building a target, build of that target is skipped. Combined with conditional requirements this
+ allows to skip building some target in configurations where the build is known to fail.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/v2/doc/src/userman.xml b/v2/doc/src/userman.xml
index f4a9202f1..d57e05653 100644
--- a/v2/doc/src/userman.xml
+++ b/v2/doc/src/userman.xml
@@ -5,18 +5,20 @@
- Boost.Build v2 User Manual
+ Boost.Build V2 User Manual
+
-
+
+
diff --git a/v2/doc/src/v1_vs_v2.xml b/v2/doc/src/v1_vs_v2.xml
new file mode 100644
index 000000000..7223175e7
--- /dev/null
+++ b/v2/doc/src/v1_vs_v2.xml
@@ -0,0 +1,107 @@
+
+
+
+
+ Differences to Boost.Build V1
+
+
+ While Boost.Build V2 is based on the same ideas as Boost.Build V1,
+ some of the syntax was changed, and some new important features were
+ added. This chapter describes most of the changes.
+
+
+ Configuration
+
+ In V1, toolsets were configured by environment variables. If you
+ wanted to use two versions of the same toolset, you had to create a new
+ toolset module that would set the variables and then invoke the base
+ toolset. In V2, toolsets are configured by the
+ using, and you can easily configure several
+ versions of a toolset. See for details.
+
+
+
+
+
+ Writing Jamfiles
+
+ Probably one of the most important differences in V2 Jamfiles is
+ the use of project requirements. In V1, if several targets had the same
+ requirements (for example, a common #include path), it was necessary to
+ manually write the requirements or use a helper rule or template target. In V2, the
+ common properties can be specified with the requirements project
+ attribute, as documented in .
+
+
+ Usage requirements
+ also help to simplify Jamfiles.
+
+ If a library requires
+ all clients to use specific #include paths or macros when compiling
+ code that depends on the library, that information can be cleanly
+ represented.
+
+ The difference between lib and dll targets in V1 is completely
+ eliminated in V2. There's only one library target type, lib, which can create
+ either static or shared libraries depending on the value of the
+ <link>
+ feature. If your target should be only built in one way, you
+ can add <link>shared or <link>static to its requirements.
+
+
+ The syntax for referring to other targets was changed a bit. While
+ in V1 one would use:
+
+exe a : a.cpp <lib>../foo/bar ;
+
+ the V2 syntax is:
+
+exe a : a.cpp ../foo//bar ;
+
+ Note that you don't need to specify the type of other target, but the
+ last element should be separated from the others by a double slash to indicate that
+ you're referring to target bar in project ../foo, and not to
+ project ../foo/bar.
+
+
+
+
+
+
+ Build process
+
+ The command line syntax in V2 is completely different. For example
+
+bjam -sTOOLS=msvc -sBUILD=release some_target
+
+ now becomes:
+
+bjam toolset=msvc variant=release some_target
+
+ or, using implicit features, just:
+
+bjam msvc release some_target
+
+ See the reference for a
+ complete description of the syntax.
+
+
+
+
+
+
+
+