|
Jakub Dorňák |
44a4c48 |
diff --git a/tools/build/v2/doc/bjam.1 b/tools/build/v2/doc/bjam.1
|
|
Jakub Dorňák |
44a4c48 |
new file mode 100644
|
|
Jakub Dorňák |
44a4c48 |
index 0000000..8a44af6
|
|
Jakub Dorňák |
44a4c48 |
--- /dev/null
|
|
Jakub Dorňák |
44a4c48 |
+++ b/tools/build/v2/doc/bjam.1
|
|
Jakub Dorňák |
44a4c48 |
@@ -0,0 +1,144 @@
|
|
Jakub Dorňák |
44a4c48 |
+.TH "bjam" 1 "Sat Nov 19 2011" "Doxygen" \" -*- nroff -*-
|
|
Jakub Dorňák |
44a4c48 |
+.ad l
|
|
Jakub Dorňák |
44a4c48 |
+.nh
|
|
Jakub Dorňák |
44a4c48 |
+.SH NAME
|
|
Jakub Dorňák |
44a4c48 |
+bjam \- Command-line utility to build Boost-related C++ projects with Boost\&.Build
|
|
Jakub Dorňák |
44a4c48 |
+.SH "SYNOPSIS"
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fBbjam\fP \fC[-a] [-dx] [-fx] [-jx] [-lx] [-n] [-ox] [-px] [-q] [-sx=y] [-tx] [-v] [--x]\fP
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fIbjam\fP accepts the following options:
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fB-a\fP
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+ Build all targets, even if they are current
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fB-dx\fP
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+ Set the debug level to x (0-9)
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fB-fx\fP
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+ Read x instead of Jambase
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fB-jx\fP
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+ Run up to x shell commands concurrently
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fB-lx\fP
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+ Limit actions to x number of seconds after which they are stopped
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fB-n\fP
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+ Don't actually execute the updating actions
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fB-ox\fP
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+ Write the updating actions to file x
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fB-px\fP
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+ x=0, pipes action stdout and stderr merged into action output
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fB-q\fP
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+ Quit quickly as soon as a target fails
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fB-sx=y\fP
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+ Set variable x=y, overriding environment
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fB-tx\fP
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+ Rebuild x, even if it is up-to-date
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fB-v\fP
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+ Print the version of jam and exit
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fB--x\fP
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+ Option is ignored
|
|
Jakub Dorňák |
44a4c48 |
+.SH "DESCRIPTION"
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+This section provides the information necessary to create your own projects using \fIBoost\&.Build\fP The information provided here is relatively high-level, and Chapter 6, Reference as well as the on-line help system must be used to obtain low-level documentation (see --help)
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fIBoost\&.Build\fP actually consists of two parts - \fIBoost\&.Jam\fP, a build engine with its own interpreted language, and \fIBoost\&.Build\fP itself, implemented in \fIBoost\&.Jam's\fP language\&. The chain of events when you type bjam on the command line is as follows:
|
|
Jakub Dorňák |
44a4c48 |
+.IP "\(bu" 2
|
|
Jakub Dorňák |
44a4c48 |
+\fIBoost\&.Jam\fP tries to find \fIBoost\&.Build\fP and loads the top-level module\&. The exact process is described in the section called “Initialization”
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+.IP "\(bu" 2
|
|
Jakub Dorňák |
44a4c48 |
+The top-level module loads user-defined configuration files, \fIuser-config\&.jam\fP and \fIsite-config\&.jam\fP, which define available toolsets
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+.IP "\(bu" 2
|
|
Jakub Dorňák |
44a4c48 |
+The \fIJamfile\fP 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
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+.IP "\(bu" 2
|
|
Jakub Dorňák |
44a4c48 |
+Finally, using the build request specified on the command line, \fIBoost\&.Build\fP decides which targets should be built and how\&. That information is passed back to \fIBoost\&.Jam\fP, which takes care of actually running the scheduled build action commands
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+So, to be able to successfully use \fIBoost\&.Build\fP, you need to know only four things:
|
|
Jakub Dorňák |
44a4c48 |
+.IP "\(bu" 2
|
|
Jakub Dorňák |
44a4c48 |
+How to configure \fIBoost\&.Build\fP (http://www.boost.org/boost-build2/doc/html/bbv2/overview/configuration.html)
|
|
Jakub Dorňák |
44a4c48 |
+.IP "\(bu" 2
|
|
Jakub Dorňák |
44a4c48 |
+How to declare targets in Jamfiles (http://www.boost.org/boost-build2/doc/html/bbv2/overview/targets.html)
|
|
Jakub Dorňák |
44a4c48 |
+.IP "\(bu" 2
|
|
Jakub Dorňák |
44a4c48 |
+How the build process works (http://www.boost.org/boost-build2/doc/html/bbv2/overview/build_process.html)
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+Some Basics about the \fIBoost\&.Jam\fP language\&. See the section called “Boost\&.Jam Language” (http://www.boost.org/boost-build2/doc/html/bbv2/overview/jam_language.html)
|
|
Jakub Dorňák |
44a4c48 |
+.SH "CONCEPTS"
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fIBoost\&.Build\fP has a few unique concepts that are introduced in this section\&. The best way to explain the concepts is by comparison with more classical build tools
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+When using any flavour of make, you directly specify targets and commands that are used to create them from other target\&. The below example creates a\&.o from a\&.c using a hardcoded compiler invocation command
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+a\&.o: a\&.c
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+ g++ -o a\&.o -g a\&.c
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+This is rather low-level description mechanism and it is hard to adjust commands, options, and sets of created targets depending on the used compiler and operating system\&.
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+To improve portability, most modern build system provide a set of higher-level functions that can be used in build description files\&. Consider this example:
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+add_program ('a', 'a\&.c')
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+This is a function call that creates targets necessary to create executable file from source file a\&.c\&. Depending on configured properties, different commands line may be used\&. However, \fIadd_program\fP is higher-level, but rather thin level All targets are created immediately when build description is parsed, which makes it impossible to perform multi-variant builds\&. Often, change in any build property requires complete reconfiguration of the build tree
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+In order to support true multivariant builds, Boost\&.Build introduces the concept of metatarget—object that is created when build description is parsed and can be later called with specific build properties to generate actual targets
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+Consider an example:
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+exe a : a\&.cpp ;
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+When this declaration is parsed, \fIBoost\&.Build\fP creates a metatarget, but does not yet decides what files must be created, or what commands must be used\&. After all build files are parsed, Boost\&.Build considers properties requested on the command line\&. Supposed you have invoked \fIBoost\&.Build\fP with:
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fIbjam\fP toolset=gcc toolset=msvc
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+In that case, the metatarget will be called twice, once with toolset=gcc and once with toolset=msvc\&. Both invocations will produce concrete targets, that will have different extensions and use different command lines\&. Another key concept is build property\&. Build property is a variable that affects the build process\&. It can be specified on the command line, and is passed when calling a metatarget
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+While all build tools have a similar mechanism, \fIBoost\&.Build\fP differs by requiring that all build properties are declared in advance, and providing a large set of properties with portable semantics
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+The final concept is property propagation\&. Boost\&.Build does not require that every metatarget is called with the same properties\&. Instead, the 'top-level' metatargets are called with the properties specified on the command line Each metatarget can elect to augment or override some properties (in particular, using the requirements mechanism, see the section called “Requirements”: http://www.boost.org/boost-build2/doc/html/bbv2/overview/targets.html#bbv2.overview.targets.requirements) Then, the dependency metatargets are called with modified properties and produce concrete targets that are then used in build process Of course, dependency metatargets maybe in turn modify build properties and have dependencies of their own\&.
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+For more in-depth treatment of the requirements and concepts, you may refer to SYRCoSE 2009 Boost\&.Build article (http://syrcose.ispras.ru/2009/files/04_paper.pdf)\&.
|
|
Jakub Dorňák |
44a4c48 |
+.SH "SEE ALSO"
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+\fBboost-libraries\fP(3)
|
|
Jakub Dorňák |
44a4c48 |
+.SH "SUPPORT"
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+Please report any bugs to https://svn.boost.org/trac/boost/
|
|
Jakub Dorňák |
44a4c48 |
+.SH "COPYRIGHT"
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+Boost Software License - Version 1\&.0 - August 17th, 2003
|
|
Jakub Dorňák |
44a4c48 |
+.PP
|
|
Jakub Dorňák |
44a4c48 |
+See the LICENSE_1_0\&.txt file for more information on that license, or directly on Internet:
|
|
Jakub Dorňák |
44a4c48 |
+.br
|
|
Jakub Dorňák |
44a4c48 |
+ http://www.boost.org/LICENSE_1_0.txt
|