The build2 toolchain requires a C++11 compiler with limited C++14 support. GCC
4.8 or later and Clang 3.4 or later are known to work. If you only need the
build2 build system without the bpkg package manager, then the C++ compiler is
all you will need. If, however, you would also like to build bpkg, then you
will also need to obtain SQLite as well as the libodb and libodb-sqlite
libraries (discussed below).

In this guide we install everything that we build into /usr/local. If you would
like to use a different installation location, you will need to make
adjustments to the commands below.

Note on /usr/local: most distributions these days "cripple" this location by
either not searching /usr/local/include for headers during compilation (so we
add the -I option) or not searching /usr/local/lib for libraries either during
linking (so we add the -L option) or at runtime (which we fix with the help of
-rpath). If you know that your installation doesn't suffer from (some of) these
issues, then you can adjust the commands below accordingly. Note that even if
/usr/local/lib is searched in at runtime, you may still have to run ldconfig(1)
(as root) after the installation to refresh the library cache.

Note to Mac OS users: you will need version 10.5 (Leopard) or later. We will
also be using the system C++ toolchain that comes with the Xcode Command Line
Tools. To verify it is installed, run:

$ g++ --version

To install Command Line Tools, run:

$ xcode-select --install

1. Installing SQLite

    Skip this step if you are only interested in the build2 build system.

    To install SQLite, use your distribution's package manager and make sure
    you install both the libraries (most likely already installed) and the
    development files.

    For Debian/Ubuntu:

    $ sudo apt-get install libsqlite3-dev

    For RedHat/Fedora:

    $ sudo yum install sqlite-devel

    For FreeBSD:

    # pkg install sqlite3

    For Mac OS:

    You should already have a system-default version installed. To verify:

    $ ls /usr/include/sqlite3.h /usr/lib/libsqlite3.dylib

    To see which version you have, run:

    $ grep '#define SQLITE_VERSION' /usr/include/sqlite3.h

    Any recent version (i.e., greater than 3.5.0) should work. If for some
    reason you don't seem to have SQLite, download the source code then build
    and install it into /usr/local.

2. Installing libodb and libodb-sqlite

    Again, skip this step if you are only interested in the build2 build
    system.

    [Currently we use pre-release versions of these libraries so they have to
    be built from source.]

    Download source packages for the two libraries from the same location as
    build2-toolchain (https://download.build2.org). Then unpack, build, and
    install:

    $ cd lib*-X.Y.Z

    $ ./configure --prefix=/usr/local \
    CPPFLAGS=-I/usr/local/include     \
    LDFLAGS=-L/usr/local/lib

    $ make
    $ sudo make install

    See the INSTALL file for each library for more information.

3. Bootstrapping build2

    Download build2-toolchain (https://download.build2.org) then unpack and
    bootstrap the build2 build system:

    $ cd build2-toolchain-X.Y.Z
    $ cd build2/
    $ ./bootstrap
    $ cd ..
    $ ./build2/build2/b-boot build2/

    For more information on this step (for example, how to specify the C++
    compiler, options, etc.), refer to the INSTALL file in the build2/
    subdirectory of build2-toolchain. Note that you must use global overrides
    (!) if specifying any config.* variables on the last line. For example:

    $ ./build2/build2/b-boot '!config.cxx=clang++' build2/

4. Configuring, Building, and Installing the Rest of the Toolchain

    $ ./build2/build2/b                      \
    config.cxx.poptions=-I/usr/local/include \
    config.cxx.loptions=-L/usr/local/lib     \
    config.bin.rpath=/usr/local/lib          \
    config.install.root=/usr/local           \
    config.install.root.sudo=sudo            \
    configure

    $ ./build2/build2/b update
    $ ./build2/build2/b install

    To test the installation, run:

    $ which b
    /usr/local/bin/b
    $ b --version

    $ which bpkg
    /usr/local/bin/bpkg
    $ bpkg --version

5. Setting up updates with the package manager

    If you only need to build this specific version of the toolchain, then you
    are done and can skip this step. However, if you are planning to upgrade to
    future versions, then going every time through the bootstrap steps will be
    tedious. Instead, we can use the bpkg package manager to manage upgrades
    automatically. Note also that without periodic upgrades your version of the
    toolchain may become too old to be able to upgrade itself. In this case you
    will have to fall back onto the bootstrap process.

    First, choose a directory where you would like bpkg to build everything,
    for example, build2-toolchain. Then:

    $ cd # back to home directory
    $ mkdir build2-toolchain
    $ cd build2-toolchain

    $ bpkg create                             \
    cxx                                       \
    config.cxx.poptions=-I/usr/local/include  \
    config.cxx.loptions=-L/usr/local/lib      \
    config.bin.rpath=/usr/local/lib           \
    config.install.root=/usr/local            \
    config.install.root.sudo=sudo

    $ bpkg add https://pkg.cppget.org/1/alpha
    $ bpkg fetch
    $ bpkg build build2 bpkg
    $ bpkg install build2 bpkg

    Later, to upgrade to a new version of the toolchain, simply do:

    $ bpkg fetch
    $ bpkg status build2 bpkg   # See if any upgrades are available.
    $ bpkg build build2 bpkg
    $ bpkg install build2 bpkg