Boost.Build V2/GettingStarted

Boost.Build Getting Started Guide

NOTE: [Boost.Build V2] Milestone 12 is the latest version as of Oct 2007.

Key advantages over other build tools

Scales to very big projects well

MSVC and other integrated environments offer nice user interface to specify source files and compiler settings. However they become a maintenance nightmare in large projects.

Jam language effectively fights with duplicated code in project files

It's very hard to maintain consistent compiler settings and build paths in MSVC IDE if your solution contains a lot of projects and configurations.

With Boost.Build, the same settings won't be duplicated in all your projects, making the maintenance easier and reducing the risk of hidden bugs caused by inconsistent #defines or CRT versions during compilation of one of 15 components comprising your application.

Unlike Makefiles, Jamfiles are written in Jam language - a hybrid procedural/object/rule-based language designed for a good readability, giving you more ability to reduce error-prone copy & paste work than Makefile language and other purely non-imperative languages.

Human-readable and source-control friendly

MSVC 7+ XML project files contain a lot of redundant keys and non-human-readable GUIDs. It's not a problem most of the time as the IDE does the dirty work for you. But if you are merging two different versions of a project with version control merge tools, it's easy to get a badly formed XML file which won't open. Advanced XML-aware merge tools such as ClearCase? XML merger won't help either because the order of keys can be changed randomly each time you make big changes to the project.

Your Jamfiles will be human-readable and much smaller than your *.vcproj or *.dsp files. So it will be much easier to merge them. Also the use of wildcards for source files will make the changes to the Jamefiles and the merge operations very rare.

Project Jamfiles are portable and extremely simple

Boost.Build handles header file dependencies automatically and on-the-fly, just like most IDEs. For many projects just a single line in Boost Jam language is enough:

  exe hello : [ glob *.cpp ] ;

This one-liner will include all cpp files in project folder into your project and link them into hello or (or hello.exe on Windows) executable. Compare this with efforts needed to create (and maintain!) a makefile or a Visual Studio project file. And you get cross-compiler portability for free!

Build process is identically simple on different platforms and compilers

A single project file can be used on different platforms and compilers. Only compiler to be used should be specified on command line if default compiler isn't configured:

Command line building with Visual C++ .NET 2003 compiler on Windows:

  > bjam --toolset=vc-7_1

Building with gcc on Linux:

  # bjam --toolset=gcc

Portable compiler configuration switches

Abstract "features" are used instead of compiler-specific switches to improve portablity and reduce clutter in Jamfiles.

Toolset modules map Boost.Build features to actual compiler commandline switches, allowing project and file compilation settings to be specified independently of compiler and OS.

Commonly available settings like <optimization>speed have the same meaning for all compilers reducing or completely removing compiler-specific configuration. If nesessary, compiler- or os-specific options can be set too. Boost.Build doesn't limit you in any way.

  exe hello : [ glob * cpp ] ;
  obj very_slow_class : very_slow_class.cpp : <optimization>speed ; # always optimize, even in debug builds

Many compilers are supported out of the box

Boost.Build supports almost all C++ compilers, several fortran compilers and non-compiler tools like Doxygen auto-documentor, Bison parser generator out of the box. Each such tool is described in a Jam "toolset" module in tools/ folder.

(list supported compilers?)

Support for new compilers and other tools can be added easily

New toolsets for your specific tools can be added easily. For example, code supporting Bison is smaller than 30 lines in Jam language. And for simple command invocations you don't need to define a toolset at all:

  # can someone fix this sample?? I'd like to run hello_test.exe after it's successfully built
  exe hello_test : [ glob * cpp ] //site-config/cppunit ;
  runtests : hello_test ;
  actions runtests
  {
     hello_test
  }

The advantages of defining your own toolsets is platform independence and Jam code reusage. Also can implement a simple Jam module instead of a full toolset. You won't have to implement support for all advanced Boost.Build functionality for your tool if you don't need it.

Well suited for multiproject environments

Abstract, brief project names allow to specify inter-project dependencies and external dependencies independently of disk locations, compiler and platform.

High level of abstraction and project code reuse reduces the need for enterprise-wide project templates and copy & paste between projects.

There is no need to put a copy of library source tree to each project. Developer can install required libraries anywhere and set mappings in site-config.Jam:

  exe hello : [ glob * cpp ] /site-config//zlib ;

Easily integrated into Visual Studio

Despite fully functional project type extension for Visual Studio isn't even planned now, Boost.Build projects can be added to Visual Studio 2002/2003 IDE as Makefile Projects.

Simply invoke bjam with options you need instead of NMake. Use --clean switch to clean a project, and -a switch to rebuild all.

Getting up and running with supplied examples

Compile bjam.exe

Run boost/tools/build/jam_src/build.bat.

If bjam.exe isn't created in jam_src/bin.ntx86 folder, or you are not on Windows, look at complete /BuildingBjam guide.

Configure toolsets

Unlike Boost.Build V1, Boost.Build V2 requires you to configure toolsets you will use in user-config.jam file located at Boost.Build root. Without this configuration, toolset names won't be recognized and you'll get "invalid value for toolset feature" and/or "cannot compile C++ code" errors when you build a project.

So, you need to uncomment each toolset you are going to use with BBv2 and configure it by changing version and path. Note that Jam language is sensitive to whitespace, and all tokens including ; have to be separated by space, tab or line feed. So don't try to delete space before semicolons, it's meaningful!

General syntax for using rule is

  using {toolset} : {version} : {path} ;

All versions of Microsoft Visual Studio are represented with single msvc toolset. If you have just one version of Visual Studio installed, just uncomment

  using msvc ;

clause. If you have several versions installed at the same time, you'll need to put several lines for each version:

  using msvc : 6.0 ; # Visual Studio 6
  using msvc : 7.0 ; # Visual Studio .NET 2002
  using msvc : 7.1 ; # Visual Studio .NET 2003
  using msvc : 8.0 ; # Visual Studio 2005 (including betas and community previews)

For most other toolsets, it's enough just to uncomment "using" line. Some toolsets (which?) require you to specify compiler version, and the location where compiler is installed. See Boost.Build v2 toolset configuration guide.

Microsoft compilers are detected by environment variables which was permanently set by Visual Studio installers. So if you didn't explicitly remove these variables from your NT user profile after installation, autodetection should work perfectly and no paths are required.

Also note that first toolset mentioned in users-config becomes the default toolset. So you may need to move

  using msvc : 7.1 ; 

up if you compile 99% of your code with Visual Studio .NET 2003 or don't plan to use bjam for other compilers.

Try it!

Go to any of sample directories under example/ folder and try the following commands:

  > bjam                   # builds default variant (debug) with default options using default toolset
  > bjam msvc              # builds default variant (debug) with default options using default version of Visual C++ (how this version is determined if multiple versions are specified in user-config?)
  > bjam msvc-7.1          # builds default variant (debug) with default options using Visual C++ .NET 2003
  > bjam release           # builds prefefined "release" variant with default options using default toolset
  > bjam threading=single # builds default variant (debug) with non-thread safe version of runtime library using default toolset
  > bjam release debug threading=multi msvc-7.1 optimization=off borland # 4 total variants of project outputs are built at once
  > bjam release debug threading=single msvc-7.1/release/<optimization>off borland # multiple variants are built with multiple toolsets. Optimization is turned off only for msvc release config

Microsoft Visual Studio Migration Guide

Boost.Build V2/MicrosoftVCProjMigration

[buy fioricet online] [buy fioricet] [[buy fioricet online]]