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
|
# Bootstrappable Toolchain
This repository provides compiler toolchains and additional build tools that are
acquired via [**Bootstrappable Builds**](https://bootstrappable.org/). *For
details about the bootstrap process, see [BOOTSTRAP.md](./doc/BOOTSTRAP.md).*
Available compiler toolchains are:
- `gcc-latest-native`
- `gcc-14.2.0-native`
- `gcc-13.3.0-native`
- `clang-latest-native`
- `clang-20.1.0-native`
- `clang-19.1.1-native`
- `clang-18.1.8-native`
- `clang-17.0.6-native`
- `clang-16.0.6-native`
- `gcc-latest-musl`
- `gcc-14.2.0-musl`
- `gcc-13.3.0-musl`
- `gcc-latest-musl-static`
- `gcc-14.2.0-musl-static`
- `gcc-13.3.0-musl-static`
*For details about how these compilers are built, see
[COMPILERS.md](./doc/COMPILERS.md).*
Available build tools are:
- `busybox-latest`
- `busybox-1.36.1`
- `make-latest`
- `make-4.4.1`
- `cmake-latest`
- `cmake-3.27.1`
- `python-latest`
- `python-3.12.0`
- `tools-all` (bundle of all latest tools)
*All tools are statically linked so that they can run on systems without any
existing C library. For details about how these tools are built, see
[TOOLS.md](./doc/TOOLS.md).*
Details about toolchain variants:
- `<compiler>-native`: *native* compiler
- runs on the build host
- **supports native compilation for the host architecture**
- `<compiler>-musl`: *cross* compiler with musl support
- runs on the build host
- **links against bundled *musl libc***
(*note that dynamically linked binaries require a working musl ld+libc on
the target system*)
- **supports fully static linking (unlike *glibc* toolchains)**
- **supports cross-compilation for project's `TARGET_ARCH`**
- `<compiler>-musl-static`: statically linked *cross* compiler with musl support
- runs on systems without any existing C library
- **links against bundled *musl libc***
(*note that dynamically linked binaries require a working musl ld+libc on
the target system*)
- **supports fully static linking (unlike *glibc* toolchains)**
- **supports cross-compilation for project's `TARGET_ARCH`**
- `<toolchain>+tools` (e.g., `gcc-latest-native+tools`)
- `<toolchain>` bundled with all latest tools (see `tools-all` above)
All `musl` variants support cross-compilation. In your project, make sure
that the variables `ARCH` and `TARGET_ARCH` are set to one of the following
values: `x86`, `x86_64`, `arm`, or `arm64`.
## Usage
All provided toolchains can be
1. imported to an existing
[Justbuild](https://github.com/just-buildsystem/justbuild) project, or
2. installed to local disk to obtain a portable toolchain.
### 1. Importing toolchains to Justbuild projects
If your project includes its toolchain via an open name (usually a repository
named `toolchain`), you can create that repository by adding the following code
to the *imports section* of your `repos.in.json`:
~~~ jsonc
"imports": [
{
"source": "git",
"branch": "master",
"url": "https://github.com/just-buildsystem/bootstrappable-toolchain",
"repos": [{"repo": "gcc-latest-musl+tools", "alias": "toolchain"}]
},
// ...
],
~~~
Afterwards, run `just-lock` to generate the updated `repos.json` repository
lock-file.
### 2. Obtaining a portable toolchain
You can obtain a portable installation of any of the provided toolchains to your
local disk.
To do so, first clone this repository and run `just-mr` to build and install
the requested toolchain (e.g., `gcc-latest-musl`):
~~~ sh
$ just-mr --main gcc-latest-musl install toolchain -D'{"ARCH":"x86_64"}' -o /opt/gcc
~~~
*Note that the configuration variable `ARCH` should be set to the build host
architecture.*
For installing a *cross compiler*, you can additionally set `BUILD_ARCH` to
specify the architecture the compiler should build for:
~~~ sh
$ just-mr --main gcc-latest-musl install toolchain \
-D'{"ARCH":"x86_64","BUILD_ARCH":"arm64"}' -o /opt/gcc-for-arm64
~~~
For installing a *crossed native compiler*, you have to also set the variable
`TARGET_ARCH` (the architecture the compiler is build for) to the same value as
`BUILD_ARCH`:
~~~ sh
$ just-mr --main gcc-latest-musl install toolchain \
-D'{"ARCH":"x86_64","TARGET_ARCH":"arm64","BUILD_ARCH":"arm64"}' -o /opt/arm64-gcc-for-arm64
~~~
## Initial requirements
For bootstrapping the toolchains, the build host must be a Linux system with:
1. C compiler (e.g., TinyCC, old GCC)
2. POSIX-compliant shell located at `/bin/sh`
The C compiler for bootstrapping can be specified by setting the fields
`BOOTSTRAP_CC`, `BOOTSTRAP_CFLAGS`, and `BOOTSTRAP_PATH` in configuration
variable `TOOLCHAIN_CONFIG` (e.g., on command line `-D'{"TOOLCHAIN_CONFIG":
{"BOOTSTRAP_CC": "gcc"}}'`). If not set, the C compiler is assumed to be `cc`
available in the search paths `/bin` or `/usr/bin`.
*Note that currently supported build hosts are required to be an `x86_64`
architecture and use either the GNU or musl C library.*
## Toolchain Targets
All toolchains provide the following target:
- `["", "toolchain"]`:
The portable toolchain file tree (e.g., `bin`, `lib`, etc.)
Set `BUILD_ARCH` to specify the target architecture for cross-compilers.
All compiler toolchains additionally provide:
- `["CC", "defaults"]`:
The `CC` toolchain definition for use with
[rules-cc](https://github.com/just-buildsystem/rules-cc)
All tool toolchains (including `<toolchain>+tools`) provide:
- `["CC/foreign", "defaults"]`:
The `CC/foreign` toolchain definition for use with
[rules-cc](https://github.com/just-buildsystem/rules-cc)
The `busybox` toolchains (including `<toolchain>+tools`) additionally provide:
- `["patch", "defaults"]`:
The `patch` toolchain definition for use with
[rules-cc](https://github.com/just-buildsystem/rules-cc)
## Configuration Variables
The toolchains can be configured via the variable `TOOLCHAIN_CONFIG`, which
contains an object that may specify multiple fields.
Fields for building the toolchains:
- `BOOTSTRAP_CC`:
The initial C compiler for bootstrapping (default: `"cc"`)
- `BOOTSTRAP_CFLAGS`:
The initial C compile flags for bootstrapping (default: `["-w"]`)
- `BOOTSTRAP_PATH`:
Search path for the initial C compiler (default: `["/bin", "/usr/bin"]`)
- `HOST_SYSTEM_HDR_DIR`:
Header directory of the C library on the build host (default: not set)
- `HOST_SYSTEM_LIB_DIR`:
Library directory of the C library on the build host (default: not set)
- `HOST_DYNAMIC_LINKER`:
Absolute path to the dynamic linker on the build host (default: not set)
- `BOOTSTRAP_WRAP_CC`:
If true, when using the bootstrap C compiler with autotools, use a wrapper
script calling the compiler with the `BOOTSTRAP_CFLAGS` instead. In this way,
it can be avoided that the autotools draw wrong conclusions from calling the
compiler without the specified flags (as some tests do).
- `INCLUDE_LINTER`:
Add linter to toolchain if supported. (default: `false`)
Currently this option is only supported by `clang` toolchains, adding
`clang-tidy`. Additionally, Clang versions `18` and newer will also include
the *external project*
[Include What You Use](https://github.com/include-what-you-use/include-what-you-use).
- `INCLUDE_LLD`:
For `clang` toolchains, add the LLD linker to toolchain. (default: `false`)
Fields for using the toolchains
(within [Justbuild](https://github.com/just-buildsystem/justbuild) projects):
- `STATIC_RUNLIBS`:
Statically link runtime libraries, e.g., `libgcc_s`, `libstdc++` (default:
`false`)
- `USE_LIBCXX`:
Use LLVM's `libc++` instead of GNU's `libstdc++` (only for `clang` toolchains,
default: `false`)
### Building on Hosts with Custom System Paths
Some systems (e.g., NixOS) use custom paths for Coreutils, the C library, and
the dynamic linker that the autotools cannot determine. On such systems, `PATH`
is used to locate Coreutils and `TOOLCHAIN_CONFIG` may set additional system
paths.
Example configuration for bootstrapping on NixOS (hashes may vary):
~~~ json
{ "ENV": {"PATH": "/root/.nix-profile/bin"}
, "TOOLCHAIN_CONFIG":
{ "HOST_SYSTEM_HDR_DIR": "/nix/store/y8wfrgk7br5rfz4221lfb9v8w3n0cnyd-glibc-2.37-8-dev/include"
, "HOST_SYSTEM_LIB_DIR": "/nix/store/ld03l52xq2ssn4x0g5asypsxqls40497-glibc-2.37-8/lib"
, "HOST_DYNAMIC_LINKER": "/nix/store/ld03l52xq2ssn4x0g5asypsxqls40497-glibc-2.37-8/lib/ld-linux-x86-64.so.2"
}
}
~~~
On NixOS, the host configuration is most easily obtained using a custom derivation
obtained from a simple [host-configuration package](doc/host-config.nix).
## Musl Performance Issues
Musl has huge allocator contention issues with multithreading. For that reason,
all our `musl` compilers are shipped with the alternative allocator
[mimalloc](https://github.com/microsoft/mimalloc) that solves these issues. If
you notice any performance slowdowns with your Musl-linked binaries, consider
using the alternative allocator by appending `-l:mimalloc.o` to your `LDFLAGS`.
## License
All files are copyright Huawei Cloud Computing Technology Co., Ltd., license
Apache-2.0, except for the patches in `etc/patches`, which are license GPL-2.0
(the same license as the respective upstream project).
|
