// file : BOOTSTRAP-UNIX.cli // license : MIT; see accompanying LICENSE file " The following instructions are for bootstrapping \c{build2} on UNIX-like operating systems (GNU/Linux, FreeBSD, etc). For Mac OS X first see \l{#bootstrap-macosx Bootstrapping on Mac OS X}. These instructions should also be used for UNIX emulation layers on Windows (for example, WSL, MSYS, or Cygwin) where you already have a UNIX shell with standard utilities. \dl| \li|\b{1. Create Build Directory}\n You will want to keep this directory around in order to upgrade to new toolchain versions in the future. In this guide we use \c{~/build2-build/} as the build directory and \c{/usr/local/} as the installation directory but you can use other paths. \ $ cd $ mkdir build2-build $ cd build2-build \ | \li|\n\b{2. Download, Verify, and Unpack}\n Download \c{build2-toolchain-X.Y.Z.tar.xz} (or its \c{.tar.gz} variant if you don't have \cb{xz(1)}) as well as its \c{.sha256} checksum from \l{https://build2.org/download.xhtml Download} page. Place everything into \c{~/build2-build/} (build directory) and verify the archive checksum matches: \ # Linux, WSL, MSYS, Cygwin: # $ sha256sum -c build2-toolchain-X.Y.Z.tar.xz.sha256 # Mac OS X: # $ shasum -a 256 -c build2-toolchain-X.Y.Z.tar.xz.sha256 # FreeBSD (compare visually): # $ cat build2-toolchain-X.Y.Z.tar.xz.sha256 $ sha256 -r build2-toolchain-X.Y.Z.tar.xz \ Unpack the archive and change to its directory: \ > tar -xf build2-toolchain-X.Y.Z.tar.xz > cd build2-toolchain-X.Y.Z \ || Next you can either perform the rest of the steps manually or, if after reviewing the steps, you are happy with using the defaults, run the \c{build.sh} shell script. It performs (and echoes) the same set of steps as outlined below but only allows you to customize the compiler, installation directory, and a few other things (run \c{build.sh -h} for usage). For example, this command will use \c{g++} and install the toolchain into \c{/usr/local/}. \ $ ./build.sh g++ \ While this will use Clang and install into \c{/opt/build2}: \ $ ./build.sh --install-dir /opt/build2 --sudo sudo clang++ \ If you would like to speed the process up by compiling in parallel, then you can instruct \c{build.sh} to bootstrap using GNU make (can be called \c{gmake} instead of \c{make} on some platforms), for example: \ $ ./build.sh --make make --make -j8 g++ \ \N|Note that at about half way through (\c{bpkg fetch} at step 4 below) the script will stop and prompt you to verify the authenticity of the repository certificate. To run the script unattended you can specify the certificate fingerprint with the \c{--trust} option (see \c{build.sh -h} for details).| The end result of the bootstrap process (performed either with the script or manually) is the installed toolchain as well as the \c{bpkg} configuration in \c{build2-toolchain-X.Y/} that can be used to \l{#upgrade upgrade} to newer versions. It can also be used to uninstall the toolchain: \ $ cd build2-toolchain-X.Y $ bpkg uninstall build2 bpkg bdep \ \N|Note that in both cases (manual or scripted bootstrap), if something goes wrong and you need to restart the process, you \b{must} start with a clean toolchain source by unpacking it afresh from the archive.| The rest of this section outlines the manual bootstrap process. \dl| \li|\b{1. Bootstrap, Phase 1}\n First, we build a minimal build system with the provided \c{bootstrap.sh} script. Normally, the only argument you will pass to this script is the C++ compiler to use but there is also a way to specify compile options and a few other things; run \c{bootstrap.sh -h} and see the \c{build2/INSTALL} file for details. \ $ cd build2 $ ./bootstrap.sh g++ $ build2/b-boot --version \ Alternatively, we can use the \c{bootstrap.gmake} GNU makefile to bootstrap in parallel: \ $ cd build2 $ make -f bootstrap.gmake -j 8 CXX=g++ $ build2/b-boot --version \ | \li|\n\b{2. Bootstrap, Phase 2}\n Then, we rebuild the build system with the result of Phase 1 linking libraries statically. \ $ build2/b-boot config.cxx=g++ config.bin.lib=static build2/exe{b} $ mv build2/b build2/b-boot $ build2/b-boot --version \ | \li|\n\b{3. Stage}\n At this step the build system and package manager are built with shared libraries and then staged. Here you may want to adjust a few things, such as the installation directory or the \c{sudo} program (remove the \c{config.install.sudo} line if you don't need one). You may also need to remove the \c{config.bin.rpath} line if your target doesn't support \i{rpath}. Specifically, if building on Windows (with MSYS or Cygwin), remove both \c{.rpath} and \c{.sudo}. But if unsure, leave \c{.rpath} in \- if your target doesn't support it, you will get an error and will need to reconfigure without it. \ $ cd .. # Back to build2-toolchain-X.Y.Z/ $ build2/build2/b-boot configure \ config.cxx=g++ \ config.bin.lib=shared \ config.bin.suffix=-stage \ config.bin.rpath=/usr/local/lib \ config.install.root=/usr/local \ config.install.data_root=root/stage \ config.install.sudo=sudo $ build2/build2/b-boot install: build2/ bpkg/ \ The strange-looking \c{config.install.data_root=root/stage} means install data files (as opposed to executable files) into the \c{stage/} subdirectory of wherever \c{config.install.root} points to (so in our case it will be \c{/usr/local/stage/}). Note that this subdirectory is temporary and will be removed in a few steps. But if you don't like the default location, feel free to change it (for example, to \c{/tmp/stage}). Depending on the installation directory, the installed \c{build2} binaries may not be automatically found. On most platforms \c{/usr/local/bin/} is in the \c{PATH} environment variable by default and you should be able to run: \ $ which b-stage /usr/local/bin/b-stage $ which bpkg-stage /usr/local/bin/bpkg-stage $ b-stage --version $ bpkg-stage --version \ If, however, you installed, say, into \c{/opt/build2}, then you will need to add its \c{bin/} subdirectory to \c{PATH} (re-run the above commands to verify): \ $ export PATH=\"/opt/build2/bin:$PATH\" \ Strictly speaking this is not absolutely necessary and you can adjust the rest of the commands to use absolute paths. This, however, does not make for very readable examples so below we assume the installation's \c{bin/} subdirectory is in \c{PATH}. At the next step we will use \c{bpkg} to build and install the entire toolchain. If for some reason you prefer not to build from packages (for example, because the machine is offline), then you can convert this step into a local installation and skip the rest. For this you will need to change the \c{configure} and \c{install} command lines above along these lines (see also notes on the following step about only building shared libraries and private installation subdirectory): \ $ build2/build2/b-boot configure \ config.cxx=g++ \ config.cc.coptions=-O3 \ config.bin.lib=shared \ config.bin.rpath=/usr/local/lib/build2 \ config.install.root=/usr/local \ config.install.private=build2 \ config.install.sudo=sudo $ build2/build2/b-boot install: build2/ bpkg/ bdep/ \ \N|To perform a local installation with the \c{build.sh} script, pass the \c{--local} option.| To uninstall such a local installation, run: \ $ b uninstall: build2/ bpkg/ bdep/ \ | \li|\n\b{4. Install}\n Next, we use the staged tools to build and install the entire toolchain from the package repository with the \c{bpkg} package manager. First, we create the \c{bpkg} configuration. The configuration values are pretty similar to the previous step and you may want/need to make similar adjustments. \ $ cd .. # Back to build2-build/ $ mkdir build2-toolchain-X.Y $ cd build2-toolchain-X.Y $ bpkg-stage create \ cc \ config.cxx=g++ \ config.cc.coptions=-O3 \ config.bin.lib=shared \ config.bin.rpath=/usr/local/lib/build2 \ config.install.root=/usr/local \ config.install.private=build2 \ config.install.sudo=sudo \ \N|The above configuration will only build shared libraries. If you would like to build both shared and static, remove \c{config.bin.lib=shared}.| \N|The above configuration will install shared libraries that \c{build2} depends on into a private subdirectory. This is primarily useful when installing into a shared location, such as \c{/usr/local/}. By hiding the libraries in the private subdirectory we make sure that they will not interfere with anything that is already installed into such a shared location and that any further such installations won't interfere with \c{build2}. If, however, you are installing into a private location, such as \c{/opt/build2/}, then you can remove \c{config.install.private=build2}.| Next, we add the package repository, build, and install: \ $ bpkg-stage add https://pkg.cppget.org/1/alpha $ bpkg-stage fetch $ bpkg-stage build --for install build2 bpkg bdep $ bpkg-stage install build2 bpkg bdep \ Finally, we verify the result: \ $ which b /usr/local/bin/b $ which bpkg /usr/local/bin/bpkg $ which bdep /usr/local/bin/bdep $ b --version $ bpkg --version $ bdep --version \ | \li|\n\b{5. Clean}\n The last thing we need to do is uninstall the staged tools: \ $ cd ../build2-toolchain-X.Y.Z # Back to bootstrap. $ b uninstall: build2/ bpkg/ \ || "