1bjam(1) General Commands Manual bjam(1)
2
6 bjam - Command-line utility to build Boost-related C++ projects with
7 Boost.Build
8
10 bjam [-a] [-dx] [-fx] [-jx] [-lx] [-n] [-ox] [-px] [-q] [-sx=y] [-tx]
11 [-v] [--x]
12 bjam accepts the following options:
14 -a
16 Build all targets, even if they are current
17 -dx
19 Set the debug level to x (0-9)
20 -fx
22 Read x instead of Jambase
23 -jx
25 Run up to x shell commands concurrently
26 -lx
28 Limit actions to x number of seconds after which they are stopped
29 -n
31 Don't actually execute the updating actions
32 -ox
34 Write the updating actions to file x
35 -px
37 x=0, pipes action stdout and stderr merged into action output
38 -q
40 Quit quickly as soon as a target fails
41 -sx=y
43 Set variable x=y, overriding environment
44 -tx
46 Rebuild x, even if it is up-to-date
47 -v
49 Print the version of jam and exit
50 --x
52 Option is ignored
53
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 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 · 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 · The top-level module loads user-defined configuration files, user-
69 config.jam and site-config.jam, which define available toolsets
70 · 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 · 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 So, to be able to successfully use Boost.Build, you need to know only
81 four things:
82 · How to configure Boost.Build (http://www.boost.org/boost-
84 build2/doc/html/bbv2/overview/configuration.html)
85 · How to declare targets in Jamfiles (http://www.boost.org/boost-
87 build2/doc/html/bbv2/overview/targets.html)
88 · How the build process works (http://www.boost.org/boost-
90 build2/doc/html/bbv2/overview/build_process.html)
91 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
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 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 a.o: a.c
107 g++ -o a.o -g a.c
108 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 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 add_program ('a', 'a.c')
118 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 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 Consider an example:
133 exe a : a.cpp ;
135 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 bjam toolset=gcc toolset=msvc
143 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 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 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 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
172 boost-libraries(3)
173
175 Please report any bugs to https://svn.boost.org/trac/boost/
176
178 Boost Software License - Version 1.0 - August 17th, 2003
179 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
183Doxygen Sat Nov 19 2011 bjam(1)