build2 | Installation FAQ

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

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 Linux distributions and there are third-party, unofficial binaries available for some platforms. See Other Installation Methods for details.

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 4 or more CPU cores and SSD the installation process takes under 5 minutes and requires about 1GB of disk space during the build and 200MB after the installation is complete. Note also that upgrades should 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?

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 you don't want to build from packages for another reason), 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 a local installation download (or copy) to the build2 build directory the install script and the following archives:

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.

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

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 g++-9

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.

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?


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 corporate network firewalls. You can either contact your network administrator for assistance or try installing build2 outside the firewall.

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.