aboutsummaryrefslogtreecommitdiff
path: root/BOOTSTRAP-UNIX.cli
blob: 1023ca2a26428c4f4e6622e09d74ca8c407443fe (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
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
// 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 --all
\

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

\N|The above command will build all the dependencies of \c{build2} and
\c{bpkg} from sources bundled with \c{build2-toolchain}. If instead you would
like to use system-installed versions for some of them, then you can specify
empty \c{config.import.*} values to disable the use of the bundled versions.
For example, to use the system-installed SQLite:

\
$ build2/build2/b-boot configure \
  ...                            \
  config.import.libsqlite3=
\

If performing an installation with the \c{build.sh} script, then to use the
system-installed dependencies pass the \c{--system} option, specifying such
dependencies as a comma-separated list. For example:

\
$ ./build.sh --system libsqlite3,libpkg-config g++
\

|

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 of the steps.

\N|To perform a local installation with the \c{build.sh} script, pass the
\c{--local} option.|

To perform a local installation 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, private installation
subdirectory, toolchain executables prefix/suffix, etc):

\
$ build2/build2/b-boot configure         \
  config.config.hermetic=true            \
  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/
\

You will also need to build and install the standard build system modules:

\
$ b install: '!config.install.scope=project' libbuild2-*/
\

\N|To verify the build system modules installation you can load them with the
following command:

\
$ b noop: tests/libbuild2-*/
\

|

To uninstall such a local installation, run:

\
$ b uninstall: build2/ bpkg/ bdep/ libbuild2-*/
\

|


\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.config.hermetic=true            \
  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}.|

\N|To add a custom prefix/suffix to the toolchain executables names, add
\c{config.bin.exe.prefix=...} and/or \c{config.bin.exe.suffix=...}.|

\N|The \c{config.config.hermetic=true} configuration variable in the above
command makes sure the embedded \c{~host} and \c{~build2} configurations
include the current environment. This is especially important for \c{~build2}
which is used to dynamically build and load ad hoc recipes and build system
modules and must therefore match the environment that was used to build the
build system itself.|

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

\N|The above command will build all the dependencies of \c{build2}, \c{bpkg},
and \c{bdep} from source packages. If instead you would like to use
system-installed versions for some of them, then you can list them with the
\c{sys} scheme to make \c{bpkg-stage} treat them as available from the system
rather than building them from source. For example, to use the
system-installed SQLite:

\
$ bpkg-stage build --for install build2 bpkg bdep ?sys:libsqlite3
\

|

\N|By default \c{bpkg} will build the latest available version of each
package. You can, however, specify the desired versions explicitly, for
example:

\
$ bpkg-stage build --for install build2/X.Y.Z bpkg/X.Y.Z bdep/X.Y.Z
\

|

To verify the result, run:

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

$ which bpkg
/usr/local/bin/bpkg

$ which bdep
/usr/local/bin/bdep

$ b --version
$ bpkg --version
$ bdep --version
\

Finally, we build and install the standard build system modules:

\
$ bpkg build --for install libbuild2-autoconf libbuild2-kconfig
$ bpkg install '!config.install.scope=project' \
  --all-pattern=libbuild2-*
\

\N|To get a list of the standard pre-installed build system modules in a
specific version of the toolchain, run:

\
$ cd ../build2-toolchain-X.Y.Z
$ ls -d libbuild2-*
\

|

\N|To verify the build system modules installation you can load them with the
following command:

\
$ b noop: ../build2-toolchain-X.Y.Z/tests/libbuild2-*/
\

||

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

||
"