aboutsummaryrefslogtreecommitdiff
path: root/INSTALL.cli
blob: fcdd4402198ec7ef98866c3ffab8054a2a6e34eb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
// file      : INSTALL.cli
// copyright : Copyright (c) 2014-2017 Code Synthesis Ltd
// license   : MIT; see accompanying LICENSE file

"
One of the primary goals of the \c{build2} toolchain is to provide a uniform
build interface across all the platforms and compilers. As a result, if you
already have the toolchain installed and would like to upgrade to a newer
version, then there is a single set of \l{#UPGRADE upgrade instructions} for
all the platforms.

If, however, you need to install the toolchain for the first time, then it has
to be bootstrapped and that process is platform-specific. The rest of this
section discusses a few general bootstrap considerations and then directs
you to the appropriate platform-specific instructions.

In the rest of this guide we use the \c{$} symbol for a UNIX shell prompt and
\c{>} for the Windows command prompt. Similarly, we use \c{\\} for UNIX
command line continuations and \c{^} for Windows. Usually you should be able
to copy and paste (sans the prompt) example commands in order to execute them
but sometimes you might need to change a thing or two (for example, replace
\c{X.Y.Z} with the actual version). Once we are able to use the \c{build2}
toolchain, the command line interface becomes regular and we usually only show
the UNIX version of the commands. In this case making a Windows version is
a simple matter of adjusting paths and, if used, line continuations.

The \c{build2} toolchain requires a C++14 compiler. From the commonly-used
options, GCC 4.9, Clang 3.4, and MSVC 14 (2015) Update 3 or any later versions
of these compilers should work. Note also that the C++ compiler that you use
to build the \c{build2} toolchain and the one that you will use to build your
projects need not be the same. For example, if you are using MSVC 12 (2013)
(which cannot build \c{build2}), it is perfectly fine to get a minimal MinGW
toolchain and use that to build \c{build2}; you will still be able to use MSVC
to build your own code.

At the high level, the bootstrap process involves the following 5 steps.

\dl|

\li|\b{1. Bootstrap, Phase 1}\n

First, a minimal build system executable is built using provided shell
scripts/batch files or a GNU makefile. The result is only guaranteed to be
able to rebuild the build system itself.|

\li|\n\b{2. Bootstrap, Phase 2}\n

Then, the build system is rebuilt with static libraries. The result is only
guaranteed to be able to build the build system and the package manager.|

\li|\n\b{3. Stage}\n

At this step the build system and package manager are built with shared
libraries and then staged.|

\li|\n\b{4. Install}\n

Next, the staged tools are used to build and install the entire toolchain
from the package repository with the \cb{bpkg} package manager.|

\li|\n\b{5. Clean}\n

Finally, the staged at step 3 tools are uninstalled.||

The end result of the bootstrap process is the installed toolchain as well as
the \c{bpkg} configuration (created at step 4) that can be used to upgrade to
newer versions. You can also skip step 4 and instead install at step 3 if for
some reason you prefer not to build from packages (for example, because the
machine is offline).


For Windows, if you are using either MSVC or MinGW, continue with
\l{#BOOTSTRAP-WINDOWS Bootstrapping on Windows}. If using MSYS or Cygwin,
then instead refer to \l{#BOOTSTRAP-UNIX Bootstrapping on UNIX}.

For Mac OS X, continue with \l{#BOOTSTRAP-MACOSX Bootstrapping on Mac OS X}.

For other UNIX-like operating systems (GNU/Linux, FreeBSD, etc; this also
includes MSYS/Cygwin), continue with \l{#BOOTSTRAP-UNIX Bootstrapping on
UNIX}.
"