build2 | Installation FAQ

Why no (official) binaries?
Are the install scripts secure?
What are the system requirements?
Which compilers are supported?
How to use system-installed libraries?
How to install offline?

Linux-specific Issues:
Linux: g++: internal compiler error: killed

Mac OS-specific Issues:
Mac OS: can not execute clang++: too many open files

Windows-specific Issues:
Windows: curl: SSL certificate problem
Windows: strange/other errors

Why no (official) binaries?

Several reasons:

  1. The build2 toolchain has to be compiled with the same compiler as what's available on your machine since it may need to build and dynamically load additional components later.
  2. After the initial installation, the toolchain is normally upgraded from the package repository which requires compiling from source.
  3. If we cannot reliably and reasonably easily build from source on all the major platforms, then we probably shouldn't be making build tools.

As a result, while the initial installation is a bit more involved, upgrades are not much more inconvenient than using the system package manager while being more reliable and timely.

Note also that the build2 binary packages are starting to appear in the official package repositories of some distributions and there are third-party, unofficial binaries available for some platforms. See Other Installation Methods for details.

Are the install scripts secure?

The automated install scripts download everything over HTTPS. They also contain embedded SHA256 checksums which they use to verify every downloaded package. So if you have verified the SHA256 checksum for the script itself, then everything should be reasonably secure.

See also How to install offline?

What are the system requirements?

Because the install scripts build everything from source, the process may take some time and require some disk space. While the exact numbers depend on the compiler and operating system, as a general guideline, on a modern machine with 8 CPU cores and SSD the installation process takes about 5 minutes and requires about 500MB of disk space during the build and 100MB after the installation is complete. Note also that upgrades will normally be significantly faster.

You can shorten the build time (at the expense of faster upgrades) by performing a local installation as described in How to install offline?

See also Which compilers are supported?

Which compilers are supported?

GCC 4.9, Clang 3.7, and MSVC 14 (2015) Update 3 or any later versions of these compilers.

The build2-install.sh script allows specifying an alternative C++ compiler with the --cxx option, for example:

$ sh build2-install-X.Y.Z.sh --cxx clang++

Note also that the compiler you use to build the build2 toolchain and those that you will be using to build your projects don't have to be the same. For example, you can build build2 with MinGW GCC and then use it to build your own projects with MSVC or Clang.

How to use system-installed libraries?

As part of the installation the install script builds from source a number of commonly-used libraries, such as libsqlite3. If you have some of these libraries already installed (for example, with your system's package manager), then you can instruct the install script to use them instead by specifying a comma-separated list of such libraries with the --system option. For example:

$ sh build2-install-X.Y.Z.sh --system libsqlite3,libpkg-config

Do note, however, that the system-installed version may not have the desired configuration. For example, build2 uses SQLite's ATTACH DATABASE to implement support for linked build configuration. SQLite places a compile-time limit on the number of databases that can be attached with the default being 10. While this should be sufficient for normal use, it's not impossible to reach this limit in more advanced scenarios. As a result, if unsure, we recommend that you let the install script build the common libraries from source to make sure they have the desired configuration.

How to install offline?

By default the install scripts download source archives necessary to bootstrap the toolchain (build2-toolchain plus, in case of Windows, base utilities) and build the final installation from packages obtained from the package repository (cppget.org). This allows upgrading to a newer version of build2 directly from packages and without having to go through the bootstrap process.

However, if your machine is offline, or if your organization's network security breaks the installation process (often the case on Windows when trying to use curl), or you don't want to build from packages for another reason (for example, speed), then it is possible to pre-download the necessary source archives and perform a local installation from that without any further network access. Note that in this case an upgrade to a newer version involves performing the same from-scratch installation (after uninstalling the previous version; see below).

To perform an offline installation download (or copy) to the build2 build directory the install script and the following archives (if you don't care about offline and just want the local installation, you can skip this step):

build2-toolchain-X.Y.Z.tar.xz
build2-toolchain-X.Y.Z.tar.gz              (only on Unix without xz)
build2-baseutils-X.Y.Z-x86_64-windows.zip  (only on Windows)
build2-mingw-X.Y.Z-x86_64-windows.tar.xz   (only for install-mingw.bat)

Then on Unix run:

$ sh build2-install-X.Y.Z.sh --local --no-check

Or on Windows (replacing NNN with msvc, clang, or mingw):

> build2-install-NNN-X.Y.Z.bat --local --no-check

The --no-check option instructs the install script to not check if a newer version is available. You can omit it if you are not offline.

To uninstall a local installation, change to the build2 build directory and then on Unix run:

$ sh build2-install-X.Y.Z.sh --local --uninstall

Or on Windows:

> build2-install-NNN-X.Y.Z.bat --local --uninstall


Linux-specific Issues:

Linux: g++: internal compiler error: killed

By default build2 uses all the available hardware threads and this error usually indicates that you are running out of memory. Workarounds for this problem include increasing the amount of RAM (for example, if you are building in a virtual machine; 0.5G per thread is a good rule of thumb) or reducing the number of jobs used by the build2 build, for example:

sh build2-install-X.Y.Z.sh -j 1


Mac OS-specific Issues:

Mac OS: can not execute clang++: too many open files

This error appears to be related to the limit on the number of open files in Mac OS. There are both the per-process (ulimit -n) and the per-system (sysctl kern.maxfiles) limits. If the machine is loaded with other tasks and you are building build2 in parallel (the default is to use all the available hardware threads), then you may reach one of these limits (most likely the system-wide). One workaround for this problem is to reduce the number of jobs used by the build2 build, for example:

sh build2-install-X.Y.Z.sh -j 1


Windows-specific Issues:

Windows: curl: SSL certificate problem

This error is normally caused by an overly-restrictive network security in your organization. You can either contact your network administrator for assistance or try installing offline.

Windows: strange/other errors

Sometimes you may encounter strange errors when running the install scripts on Windows. These include the inability to create/copy/move/delete files or directories (usually due to "Access Denied") or certain programs crashing with the cryptic "cygheap base mismatch detected" message. Oftentimes, if you try to perform the same action manually, it succeeds.

While the exact reasons are usually difficult to pinpoint, generally this is believed to be caused by other programs interfering with the files and/or programs we are trying to use. The two well-known offenders are Windows Defender and Windows Search Indexer but third-party anti-virus and anti-spyware programs are also known to cause this.

One possible solution to this problem is to disable all such programs either entirely or for the directories used by build2 (for example, the build directory and the installation directory). If this is not possible/desirable (or does not help), the only other alternative is to keep retrying the installation process, perhaps using different installation and/or build directories.