build2 | Installation FAQ
Why no (official) binaries?
Several reasons:
- The
build2toolchain 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. - After the initial installation, the toolchain is normally upgraded from the package repository which requires compiling from source.
- 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.