1bjam(1)                     General Commands Manual                    bjam(1)
2
3
4

NAME

6       bjam - Command-line utility to build Boost-related C++ projects with
7       Boost.Build
8

SYNOPSIS

10       bjam [-a] [-dx] [-fx] [-jx] [-lx] [-n] [-ox] [-px] [-q] [-sx=y] [-tx]
11       [-v] [--x]
12
13       bjam accepts the following options:
14
15       -a
16        Build all targets, even if they are current
17
18       -dx
19        Set the debug level to x (0-9)
20
21       -fx
22        Read x instead of Jambase
23
24       -jx
25        Run up to x shell commands concurrently
26
27       -lx
28        Limit actions to x number of seconds after which they are stopped
29
30       -n
31        Don't actually execute the updating actions
32
33       -ox
34        Write the updating actions to file x
35
36       -px
37        x=0, pipes action stdout and stderr merged into action output
38
39       -q
40        Quit quickly as soon as a target fails
41
42       -sx=y
43        Set variable x=y, overriding environment
44
45       -tx
46        Rebuild x, even if it is up-to-date
47
48       -v
49        Print the version of jam and exit
50
51       --x
52        Option is ignored
53

DESCRIPTION

55       This section provides the information necessary to create your own
56       projects using Boost.Build The information provided here is relatively
57       high-level, and Chapter 6, Reference as well as the on-line help system
58       must be used to obtain low-level documentation (see --help)
59
60       Boost.Build actually consists of two parts - Boost.Jam, a build engine
61       with its own interpreted language, and Boost.Build itself, implemented
62       in Boost.Jam's language. The chain of events when you type bjam on the
63       command line is as follows:
64
65       · Boost.Jam tries to find Boost.Build and loads the top-level module.
66         The exact process is described in the section called “Initialization”
67
68       · The top-level module loads user-defined configuration files, user-
69         config.jam and site-config.jam, which define available toolsets
70
71       · The Jamfile in the current directory is read That in turn might cause
72         reading of further Jamfiles. As a result, a tree of projects is
73         created, with targets inside projects
74
75       · Finally, using the build request specified on the command line,
76         Boost.Build decides which targets should be built and how. That
77         information is passed back to Boost.Jam, which takes care of actually
78         running the scheduled build action commands
79
80       So, to be able to successfully use Boost.Build, you need to know only
81       four things:
82
83       · How to configure Boost.Build (http://www.boost.org/boost-
84         build2/doc/html/bbv2/overview/configuration.html)
85
86       · How to declare targets in Jamfiles (http://www.boost.org/boost-
87         build2/doc/html/bbv2/overview/targets.html)
88
89       · How the build process works (http://www.boost.org/boost-
90         build2/doc/html/bbv2/overview/build_process.html)
91
92       Some Basics about the Boost.Jam language. See the section called
93       “Boost.Jam Language” (http://www.boost.org/boost-
94       build2/doc/html/bbv2/overview/jam_language.html)
95

CONCEPTS

97       Boost.Build has a few unique concepts that are introduced in this
98       section. The best way to explain the concepts is by comparison with
99       more classical build tools
100
101       When using any flavour of make, you directly specify targets and
102       commands that are used to create them from other target. The below
103       example creates a.o from a.c using a hardcoded compiler invocation
104       command
105
106       a.o: a.c
107        g++ -o a.o -g a.c
108
109       This is rather low-level description mechanism and it is hard to adjust
110       commands, options, and sets of created targets depending on the used
111       compiler and operating system.
112
113       To improve portability, most modern build system provide a set of
114       higher-level functions that can be used in build description files.
115       Consider this example:
116
117       add_program ('a', 'a.c')
118
119       This is a function call that creates targets necessary to create
120       executable file from source file a.c. Depending on configured
121       properties, different commands line may be used. However, add_program
122       is higher-level, but rather thin level All targets are created
123       immediately when build description is parsed, which makes it impossible
124       to perform multi-variant builds. Often, change in any build property
125       requires complete reconfiguration of the build tree
126
127       In order to support true multivariant builds, Boost.Build introduces
128       the concept of metatarget—object that is created when build description
129       is parsed and can be later called with specific build properties to
130       generate actual targets
131
132       Consider an example:
133
134       exe a : a.cpp ;
135
136       When this declaration is parsed, Boost.Build creates a metatarget, but
137       does not yet decides what files must be created, or what commands must
138       be used. After all build files are parsed, Boost.Build considers
139       properties requested on the command line. Supposed you have invoked
140       Boost.Build with:
141
142       bjam toolset=gcc toolset=msvc
143
144       In that case, the metatarget will be called twice, once with
145       toolset=gcc and once with toolset=msvc. Both invocations will produce
146       concrete targets, that will have different extensions and use different
147       command lines. Another key concept is build property. Build property is
148       a variable that affects the build process. It can be specified on the
149       command line, and is passed when calling a metatarget
150
151       While all build tools have a similar mechanism, Boost.Build differs by
152       requiring that all build properties are declared in advance, and
153       providing a large set of properties with portable semantics
154
155       The final concept is property propagation. Boost.Build does not require
156       that every metatarget is called with the same properties. Instead, the
157       'top-level' metatargets are called with the properties specified on the
158       command line Each metatarget can elect to augment or override some
159       properties (in particular, using the requirements mechanism, see the
160       section called “Requirements”: http://www.boost.org/boost-
161       build2/doc/html/bbv2/overview/targets.html#bbv2.overview.targets.requirements)
162       Then, the dependency metatargets are called with modified properties
163       and produce concrete targets that are then used in build process Of
164       course, dependency metatargets maybe in turn modify build properties
165       and have dependencies of their own.
166
167       For more in-depth treatment of the requirements and concepts, you may
168       refer to SYRCoSE 2009 Boost.Build article
169       (http://syrcose.ispras.ru/2009/files/04_paper.pdf).
170

SEE ALSO

172       boost-libraries(3)
173

SUPPORT

175       Please report any bugs to https://svn.boost.org/trac/boost/
176
178       Boost Software License - Version 1.0 - August 17th, 2003
179
180       See the LICENSE_1_0.txt file for more information on that license, or
181       directly on Internet:
182        http://www.boost.org/LICENSE_1_0.txt
183
184
185
186Doxygen                         Sat Nov 19 2011                        bjam(1)
Impressum