path: root/BOOTSTRAP-UNIX.cli

// file      : BOOTSTRAP-UNIX.cli
// copyright : Copyright (c) 2014-2016 Code Synthesis Ltd
// 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, MSYS or
Cygwin) where you already have a UNIX shell with standard utilities.

\dl|

\li|1. Create Build Directory\n

Note that you will want to keep this directory around in order to upgrade to
new toolchain versions in the future. In this guide we will 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|\n2. 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://download.build2.org}.

Place everything into \c{~/build2-build/} (build directory) and verify the
archive checksum matches:

\
# Linux, 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). You can
also specify an alternative package repository with the \c{BUILD2_REPO}
environment variable.

For example, this command will use \c{g++-5} and install the toolchain into
\c{/usr/local/}.

\
$ ./build.sh g++-5
\

While this will use Clang and install into \c{/opt/build2}:

\
$ ./build.sh --install-dir /opt/build2 --sudo sudo clang++
\

Note also 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.

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
\

The rest of this section outlines the manual bootstrap process.

\dl|

\li|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
\

|

\li|\n2. 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
$ mv build2/b build2/b-boot

$ build2/b-boot --version
\

|

\li|\n3. Stage\n

At this step the entire toolchain is built and 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.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
\

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 \"final\"
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
the \"final\" installation and skip the rest. For this your will need to
change the \c{configure} command line above along these lines:

\
$ build2/build2/b-boot configure  \
  config.cxx=g++                  \
  config.cc.coptions=-O3          \
  config.bin.rpath=/usr/local/lib \
  config.install.root=/usr/local  \
  config.install.sudo=sudo
\

|


\li|\n4. Install\n

Next, we use the staged toolchain to build and install the \"final\" toolchain
from the package repository using 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.rpath=/usr/local/lib \
  config.install.root=/usr/local  \
  config.install.sudo=sudo
\

Next, we add the package repository, build, and install:

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

Finally, we verify the result:

\
$ which b
/usr/local/bin/b

$ which bpkg
/usr/local/bin/bpkg

$ b --version
$ bpkg --version
\

|

\li|\n5. Clean\n

The last thing we need to do is uninstall the staged toolchain:

\
$ cd ../build2-toolchain-X.Y.Z  # Back to bootstrap.
$ b uninstall
\

||
"