Getting Started with Modular Boost

Prerequisites

• Git command line client installed
• A C++ compiler installed

Choose a protocol for cloning

The ​Boost super-project and libraries on GitHub support cloning via HTTPS or SSH protocols. SSH is often used by developers, but HTTPS may be required by some corporate firewalls and for read-only access. To use HTTPS instead of SSH, replace git@github.com:boostorg/boost.git in the examples below with https://github.com/boostorg/boost.git.

Authentication

The Boost super-project and libraries have been set up using relative URLs, so whichever protocol you use in the git clone command will determine how subsequent access to the super-project and libraries is authenticated.

Line endings

The Boost super-project and libraries ensure correct handling of line endings regardless of platform by supplying a .gitattributes file. However, you may also want to set git config options for managing line endings:

On OS X, Linux, and other POSIX-like systems:

git config --global core.autocrlf input

On Windows:

git config --global core.autocrlf true

That sets the core.autocrlf option globally, so only needs to be done once. For more on line endings, see ​GitHub Dealing with line endings.

Installing Modular Boost

From the command line on Windows:

git clone --recursive git@github.com:boostorg/boost.git modular-boost
cd modular-boost
.\bootstrap
.\b2 headers

On POSIX-like operating systems:

git clone --recursive git@github.com:boostorg/boost.git modular-boost
cd modular-boost
./bootstrap.sh
./b2 headers

The b2 headers step creates the boost sub-directory hierarchy and populates it with links to the headers in the include sub-directories of the individual projects.

Experimenting

If you want to build the separately compiled Boost libraries, run the usual b2 command. For Windows:

.\b2

For POSIX-like systems:

./b2

If b2 isn't already in your path, you might want to add it now.

Testing is done just the way it has always been done. For example,

cd libs/system/test
b2

should run the tests for Boost.system, all of which should pass.

Submodules

You might want to review the ​git submodule command at this point, since understanding how to work with submodules is critical to working with the modular Boost repositories.

Developing

Checking out a particular branch

The clone operation above leaves the individual libraries in the modular-boost local repository in a detached state that is not very useful and can result in data loss. So the first thing you want to do is switch a library you want to modify to the branch you want to work on. For example, if you want to do some maintenance on the develop branch of my-lib, do this:

cd modular-boost/libs/my-lib
git checkout -B develop remotes/origin/develop

Be sure to use git checkout as shown. If you just did git checkout develop you would get a local branch that did not track the remote.

You are now ready to start regular maintenance!