b2(1)

📦
version 1.90.0 · 16 versions
, in centos-stream 10, centos-stream 9, fedora 43, fedora 44

✨ NAME ✨

b2 — bestie, this is the command-line utility that builds Boost-related C++ projects with Boost.Build 💖

🌸 SYNOPSIS 🌸

b2 [-a] [-dx] [-fx] [-jx] [-lx] [-n] [-ox] [-px] [-q] [-sx=y] [-tx] [-v]
[--x]

okay so b2 takes these options and you're gonna want to know all of them, no skipping 🙈

  • -a — build all the targets, even the ones that are already current. no chill, we're rebuilding everything 💅
  • -dx — sets the debug level to x, and x lives in the 0-9 range
  • -fx — read x instead of Jambase
  • -jx — run up to x shell commands at the same time (concurrency, we love her) ⚡
  • -lx — cap actions at x seconds, and once that time's up they get stopped
  • -n — don't actually run the updating actions. just vibes, no execution 👀
  • -ox — write the updating actions out to file x
  • -px — with x=0, pipes the action's stdout and stderr merged together into the action output
  • -q — quit quickly the second a target fails, no lingering 😭
  • -sx=y — set variable x=y, overriding the environment
  • -tx — rebuild x, even if it's already up-to-date. main character energy, it gets rebuilt anyway 👑
  • -v — print the version of b2 and exit
  • --x — this option is ignored. literally just there. it's giving decorative 🎀

🦋 DESCRIPTION 🦋

This section hands you everything you need to build your own projects with Boost.Build 🫶 The stuff in here is pretty high-level, so for the low-level tea you're gonna need Chapter 6, Reference, plus the on-line help system (peep --help).

Boost.Build is lowkey two things stitched together — Boost.Jam, which is a build engine with its own interpreted language, and Boost.Build itself, which is implemented in Boost.Jam's language. So when you type b2 on the command line, here's the whole chain of events, in order:

  • Boost.Jam tries to find Boost.Build and loads the top-level module. The exact process is described in the section called “Initialization”
  • The top-level module loads user-defined configuration files, user-config.jam and site-config.jam, which define available toolsets
  • The Jamfile 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
  • Finally, using the build request specified on the command line, Boost.Build decides which targets should be built and how. That information is passed back to Boost.Jam, which takes care of actually running the scheduled build action commands

So to successfully use Boost.Build, bestie, you only need to know four things:

🌈 CONCEPTS 🌈

Boost.Build has a few concepts that are genuinely one of a kind, and this section introduces them. The best way to explain them is by comparing them to the more classical build tools, so buckle up 🎀

When you use any flavour of make, you directly specify targets and the commands used to create them from other targets. The example below creates a.o from a.c using a hardcoded compiler invocation command:

a.o: a.c
g++ -o a.o -g a.c

This is a pretty low-level description mechanism, and adjusting commands, options, and the sets of created targets depending on the used compiler and operating system is hard. not it 😭

To improve portability, most modern build systems provide a set of higher-level functions you can use in build description files. Consider this example:

add_program ('a', 'a.c')

That's a function call that creates the targets necessary to create an executable file from the source file a.c. Depending on configured properties, different commands line may be used. However, add_program is higher-level, but a rather thin level — all targets are created immediately when the build description is parsed, which makes it impossible to perform multi-variant builds. Often, a change in any build property requires a complete reconfiguration of the build tree. exhausting honestly 💀

So in order to support true multivariant builds, Boost.Build introduces the concept of metatarget — an object that is created when the build description is parsed and can later be called with specific build properties to generate actual targets.

Consider an example:

exe a : a.cpp ;

When this declaration is parsed, Boost.Build creates a metatarget, but it doesn't yet decide what files must be created, or what commands must be used. After all build files are parsed, Boost.Build considers the properties requested on the command line. Supposed you have invoked Boost.Build with:

b2 toolset=gcc toolset=msvc

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.

While all build tools have a similar mechanism, Boost.Build differs by requiring that all build properties are declared in advance, and by providing a large set of properties with portable semantics. iconic behavior tbh 👑

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.

For a more in-depth treatment of the requirements and concepts, you may refer to the SYRCoSE 2009 Boost.Build article (http://syrcose.ispras.ru/2009/files/04_paper.pdf).

👀 SEE ALSO 👀

  • boost-libraries(3)

💜 SUPPORT 💜

Please report any bugs to https://svn.boost.org/trac/boost/ — fr fr, they wanna hear it 🫶

Boost Software License - Version 1.0 - August 17th, 2003

See the LICENSE_1_0.txt file for more information on that license, or directly on Internet: http://www.boost.org/LICENSE_1_0.txt

okay that's the whole thing, and yes the vibe check at the bottom says this page is b2(1) from the General Commands Manual, brought to you by Doxygen on Sat Nov 19 2011 — so like, a little vintage, but she ate 💅✨ bye bestie, go build something 💖

📦 where this page comes from