| 1 |
--- |
| 2 |
short-description: Setting up cross-compilation |
| 3 |
... |
| 4 |
|
| 5 |
# Cross compilation |
| 6 |
|
| 7 |
Meson has full support for cross compilation through the use of |
| 8 |
a cross build definition file. An minimal example of one such |
| 9 |
file `x86_64-w64-mingw32.txt` for a GCC/MinGW cross compiler |
| 10 |
targeting 64-bit Windows could be: |
| 11 |
|
| 12 |
```ini |
| 13 |
[binaries] |
| 14 |
c = 'x86_64-w64-mingw32-gcc' |
| 15 |
cpp = 'x86_64-w64-mingw32-g++' |
| 16 |
ar = 'x86_64-w64-mingw32-ar' |
| 17 |
windres = 'x86_64-w64-mingw32-windres' |
| 18 |
strip = 'x86_64-w64-mingw32-strip' |
| 19 |
exe_wrapper = 'wine64' |
| 20 |
|
| 21 |
[host_machine] |
| 22 |
system = 'windows' |
| 23 |
cpu_family = 'x86_64' |
| 24 |
cpu = 'x86_64' |
| 25 |
endian = 'little' |
| 26 |
``` |
| 27 |
|
| 28 |
Which is then used during the `setup` phase. |
| 29 |
|
| 30 |
```sh |
| 31 |
meson setup --cross-file x86_64-w64-mingw32.txt build-mingw |
| 32 |
meson compile -C build-mingw |
| 33 |
``` |
| 34 |
|
| 35 |
Since cross compiling is |
| 36 |
more complicated than native building, let's first go over some |
| 37 |
nomenclature. The three most important definitions are traditionally |
| 38 |
called *build*, *host* and *target*. This is confusing because those |
| 39 |
terms are used for quite many different things. To simplify the issue, |
| 40 |
we are going to call these the *build machine*, *host machine* and |
| 41 |
*target machine*. Their definitions are the following: |
| 42 |
|
| 43 |
* *build machine* is the computer that is doing the actual compiling. |
| 44 |
* *host machine* is the machine on which the compiled binary will run. |
| 45 |
* *target machine* is the machine on which the compiled binary's |
| 46 |
output will run, *only meaningful* if the program produces |
| 47 |
machine-specific output. |
| 48 |
|
| 49 |
The `tl/dr` summary is the following: if you are doing regular cross |
| 50 |
compilation, you only care about [[@build_machine]] and |
| 51 |
[[@host_machine]]. Just ignore [[@target_machine]] altogether and you will |
| 52 |
be correct 99% of the time. Only compilers and similar tools care |
| 53 |
about the target machine. In fact, for so-called "multi-target" tools |
| 54 |
the target machine need not be fixed at build-time like the others but |
| 55 |
chosen at runtime, so `target_machine` *still* doesn't matter. If your |
| 56 |
needs are more complex or you are interested in the actual details, do |
| 57 |
read on. |
| 58 |
|
| 59 |
This might be easier to understand through examples. Let's start with |
| 60 |
the regular, not cross-compiling case. In these cases all of these |
| 61 |
three machines are the same. Simple so far. |
| 62 |
|
| 63 |
Let's next look at the most common cross-compilation setup. Let's |
| 64 |
suppose you are on a 64 bit OSX machine and you are cross compiling a |
| 65 |
binary that will run on a 32 bit ARM Linux board. In this case your |
| 66 |
*build machine* is 64 bit OSX, your *host machine* is 32 bit ARM Linux |
| 67 |
and your *target machine* is irrelevant (but defaults to the same |
| 68 |
value as the *host machine*). This should be quite understandable as |
| 69 |
well. |
| 70 |
|
| 71 |
The usual mistake in this case is to call the OSX system the *host* |
| 72 |
and the ARM Linux board the *target*. That's because these were their |
| 73 |
actual names when the cross-compiler itself was compiled! Let's assume |
| 74 |
the cross-compiler was created on OSX too. When that happened the |
| 75 |
*build* and *host machines* were the same OSX and different from the |
| 76 |
ARM Linux *target machine*. |
| 77 |
|
| 78 |
In a nutshell, the typical mistake assumes that the terms *build*, |
| 79 |
*host* and *target* refer to some fixed positions whereas they're |
| 80 |
actually relative to where the current compiler is running. Think of |
| 81 |
*host* as a *child* of the current compiler and *target* as an |
| 82 |
optional *grand-child*. Compilers don't change their terminology when |
| 83 |
they're creating another compiler, that would at the very least make |
| 84 |
their user interface much more complex. |
| 85 |
|
| 86 |
The most complicated case is when you cross-compile a cross compiler. |
| 87 |
As an example you can, on a Linux machine, generate a cross compiler |
| 88 |
that runs on Windows but produces binaries on MIPS Linux. In this case |
| 89 |
*build machine* is x86 Linux, *host machine* is x86 Windows and |
| 90 |
*target machine* is MIPS Linux. This setup is known as the [Canadian |
| 91 |
Cross](https://en.wikipedia.org/wiki/Cross_compiler#Canadian_Cross). |
| 92 |
As a side note, be careful when reading cross compilation articles on |
| 93 |
Wikipedia or the net in general. It is very common for them to get |
| 94 |
build, host and target mixed up, even in consecutive sentences, which |
| 95 |
can leave you puzzled until you figure it out. |
| 96 |
|
| 97 |
Again note that when you cross-compile something, the 3 systems |
| 98 |
(*build*, *host*, and *target*) used when building the cross compiler |
| 99 |
don't align with the ones used when building something with that |
| 100 |
newly-built cross compiler. To take our Canadian Cross scenario from |
| 101 |
above (for full generality), since its *host machine* is x86 Windows, |
| 102 |
the *build machine* of anything we build with it is *x86 Windows*. And |
| 103 |
since its *target machine* is MIPS Linux, the *host machine* of |
| 104 |
anything we build with it is *MIPS Linux*. Only the *target machine* |
| 105 |
of whatever we build with it can be freely chosen by us, say if we |
| 106 |
want to build another cross compiler that runs on MIPS Linux and |
| 107 |
targets Aarch64 iOS. As this example hopefully makes clear to you, the |
| 108 |
machine names are relative and shifted over to the left by one |
| 109 |
position. |
| 110 |
|
| 111 |
If you did not understand all of the details, don't worry. For most |
| 112 |
people it takes a while to wrap their head around these concepts. |
| 113 |
Don't panic, it might take a while to click, but you will get the hang |
| 114 |
of it eventually. |
| 115 |
|
| 116 |
## Defining the environment |
| 117 |
|
| 118 |
Meson requires you to write a cross build definition file. It defines |
| 119 |
various properties of the cross build environment. The cross file |
| 120 |
consists of different sections. |
| 121 |
|
| 122 |
There are a number of options shared by cross and native files, |
| 123 |
[here](Machine-files.md). It is assumed that you have read that |
| 124 |
section already, as this documentation will only call out options |
| 125 |
specific to cross files. |
| 126 |
|
| 127 |
### Binaries |
| 128 |
|
| 129 |
```ini |
| 130 |
[binaries] |
| 131 |
exe_wrapper = 'wine' # A command used to run generated executables. |
| 132 |
``` |
| 133 |
|
| 134 |
The `exe_wrapper` option defines a *wrapper command* that can be used |
| 135 |
to run executables for this host. In this case we can use Wine, which |
| 136 |
runs Windows applications on Linux. Other choices include running the |
| 137 |
application with qemu or a hardware simulator. If you have this kind |
| 138 |
of a wrapper, these lines are all you need to write. Meson will |
| 139 |
automatically use the given wrapper when it needs to run host |
| 140 |
binaries. This happens e.g. when running the project's test suite. |
| 141 |
|
| 142 |
### Properties |
| 143 |
|
| 144 |
In addition to the properties allowed in [all machine |
| 145 |
files](Machine-files.md#properties), the cross file may contain |
| 146 |
specific information about the cross compiler or the host machine. It |
| 147 |
looks like this: |
| 148 |
|
| 149 |
```ini |
| 150 |
[properties] |
| 151 |
sizeof_int = 4 |
| 152 |
sizeof_wchar_t = 4 |
| 153 |
sizeof_void* = 4 |
| 154 |
|
| 155 |
alignment_char = 1 |
| 156 |
alignment_void* = 4 |
| 157 |
alignment_double = 4 |
| 158 |
|
| 159 |
has_function_printf = true |
| 160 |
|
| 161 |
sys_root = '/some/path' |
| 162 |
pkg_config_libdir = '/some/path/lib/pkgconfig' |
| 163 |
``` |
| 164 |
|
| 165 |
In most cases you don't need the size and alignment settings, Meson |
| 166 |
will detect all these by compiling and running some sample programs. |
| 167 |
If your build requires some piece of data that is not listed here, |
| 168 |
Meson will stop and write an error message describing how to fix the |
| 169 |
issue. If you need extra compiler arguments to be used during cross |
| 170 |
compilation you can set them with `[langname]_args = [args]`. Just |
| 171 |
remember to specify the args as an array and not as a single string |
| 172 |
(i.e. not as `'-DCROSS=1 -DSOMETHING=3'`). |
| 173 |
|
| 174 |
*Since 0.52.0* The `sys_root` property may point to the root of the |
| 175 |
host system path (the system that will run the compiled binaries). |
| 176 |
This is used internally by Meson to set the PKG_CONFIG_SYSROOT_DIR |
| 177 |
environment variable for pkg-config. If this is unset the host system |
| 178 |
is assumed to share a root with the build system. |
| 179 |
|
| 180 |
*Since 0.54.0* The pkg_config_libdir property may point to a list of |
| 181 |
path used internally by Meson to set the PKG_CONFIG_LIBDIR environment |
| 182 |
variable for pkg-config. This prevents pkg-config from searching cross |
| 183 |
dependencies in system directories. |
| 184 |
|
| 185 |
One important thing to note, if you did not define an `exe_wrapper` in |
| 186 |
the previous section, is that Meson will make a best-effort guess at |
| 187 |
whether it can run the generated binaries on the build machine. It |
| 188 |
determines whether this is possible by looking at the `system` and |
| 189 |
`cpu_family` of build vs host. There will however be cases where they |
| 190 |
do match up, but the build machine is actually not compatible with the |
| 191 |
host machine. Typically this will happen if the libc used by the build |
| 192 |
and host machines are incompatible, or the code relies on kernel |
| 193 |
features not available on the build machine. One concrete example is a |
| 194 |
macOS build machine producing binaries for an iOS Simulator x86-64 |
| 195 |
host. They're both `darwin` and the same architecture, but their |
| 196 |
binaries are not actually compatible. In such cases you may use the |
| 197 |
`needs_exe_wrapper` property to override the auto-detection: |
| 198 |
|
| 199 |
```ini |
| 200 |
[properties] |
| 201 |
needs_exe_wrapper = true |
| 202 |
``` |
| 203 |
|
| 204 |
### Machine Entries |
| 205 |
|
| 206 |
The next bit is the definition of host and target machines. Every |
| 207 |
cross build definition must have one or both of them. If it had |
| 208 |
neither, the build would not be a cross build but a native build. You |
| 209 |
do not need to define the build machine, as all necessary information |
| 210 |
about it is extracted automatically. The definitions for host and |
| 211 |
target machines look the same. Here is a sample for host machine. |
| 212 |
|
| 213 |
```ini |
| 214 |
[host_machine] |
| 215 |
system = 'windows' |
| 216 |
subsystem = 'windows' |
| 217 |
kernel = 'nt' |
| 218 |
cpu_family = 'x86' |
| 219 |
cpu = 'i686' |
| 220 |
endian = 'little' |
| 221 |
``` |
| 222 |
|
| 223 |
These values define the machines sufficiently for cross compilation |
| 224 |
purposes. The corresponding target definition would look the same but |
| 225 |
have `target_machine` in the header. These values are available in |
| 226 |
your Meson scripts. There are three predefined variables called, |
| 227 |
surprisingly, [[@build_machine]], [[@host_machine]] and |
| 228 |
[[@target_machine]]. Determining the operating system of your host |
| 229 |
machine is simply a matter of calling `host_machine.system()`. |
| 230 |
Starting from version 1.2.0 you can get more fine grained information |
| 231 |
using the `.subsystem()` and `.kernel()` methods. The return values of |
| 232 |
these functions are documented in [the reference table |
| 233 |
page](Reference-tables.md). |
| 234 |
|
| 235 |
There are two different values for the CPU. The first one is |
| 236 |
`cpu_family`. It is a general type of the CPU. This should have a |
| 237 |
value from [the CPU Family table](Reference-tables.md#cpu-families). |
| 238 |
*Note* that Meson does not add `el` to end cpu_family value for little |
| 239 |
endian systems. Big endian and little endian mips are both just |
| 240 |
`mips`, with the `endian` field set appropriately. |
| 241 |
|
| 242 |
The second value is `cpu` which is a more specific subtype for the |
| 243 |
CPU. Typical values for a `x86` CPU family might include `i386` or |
| 244 |
`i586` and for `arm` family `armv5` or `armv7hl`. Note that CPU type |
| 245 |
strings are very system dependent. You might get a different value if |
| 246 |
you check its value on the same machine but with different operating |
| 247 |
systems. |
| 248 |
|
| 249 |
If you do not define your host machine, it is assumed to be the build |
| 250 |
machine. Similarly if you do not specify target machine, it is assumed |
| 251 |
to be the host machine. |
| 252 |
|
| 253 |
|
| 254 |
## Starting a cross build |
| 255 |
|
| 256 |
|
| 257 |
Once you have the cross file, starting a build is simple |
| 258 |
|
| 259 |
```console |
| 260 |
$ meson setup builddir --cross-file cross_file.txt |
| 261 |
``` |
| 262 |
|
| 263 |
Once configuration is done, compilation is started by invoking `meson compile` |
| 264 |
in the usual way. |
| 265 |
|
| 266 |
## Introspection and system checks |
| 267 |
|
| 268 |
The main *meson* object provides two functions to determine cross |
| 269 |
compilation status. |
| 270 |
|
| 271 |
```meson |
| 272 |
[[#meson.is_cross_build]] # returns true when cross compiling |
| 273 |
[[#meson.can_run_host_binaries]] # returns true if the host binaries can be run, either with a wrapper or natively |
| 274 |
``` |
| 275 |
|
| 276 |
You can run system checks on both the system compiler or the cross |
| 277 |
compiler. You just have to specify which one to use. |
| 278 |
|
| 279 |
```meson |
| 280 |
build_compiler = [[#meson.get_compiler]]('c', native : true) |
| 281 |
host_compiler = [[#meson.get_compiler]]('c', native : false) |
| 282 |
|
| 283 |
build_int_size = build_compiler.sizeof('int') |
| 284 |
host_int_size = host_compiler.sizeof('int') |
| 285 |
``` |
| 286 |
|
| 287 |
## Mixing host and build targets |
| 288 |
|
| 289 |
Sometimes you need to build a tool which is used to generate source |
| 290 |
files. These are then compiled for the actual target. For this you |
| 291 |
would want to build some targets with the system's native compiler. |
| 292 |
This requires only one extra keyword argument. |
| 293 |
|
| 294 |
```meson |
| 295 |
native_exe = executable('mygen', 'mygen.c', native : true) |
| 296 |
``` |
| 297 |
|
| 298 |
You can then take `native_exe` and use it as part of a generator rule or anything else you might want. |
| 299 |
|
| 300 |
## Using a custom standard library |
| 301 |
|
| 302 |
Sometimes in cross compilation you need to build your own standard |
| 303 |
library instead of using the one provided by the compiler. Meson has |
| 304 |
built-in support for switching standard libraries transparently. The |
| 305 |
invocation to use in your cross file is the following: |
| 306 |
|
| 307 |
```ini |
| 308 |
[properties] |
| 309 |
c_stdlib = ['mylibc', 'mylibc_dep'] # Subproject name, variable name |
| 310 |
``` |
| 311 |
|
| 312 |
This specifies that C standard library is provided in the Meson |
| 313 |
subproject `mylibc` in internal dependency variable `mylibc_dep`. It |
| 314 |
is used on every cross built C target in the entire source tree |
| 315 |
(including subprojects) and the standard library is disabled. The |
| 316 |
build definitions of these targets do not need any modification. |
| 317 |
|
| 318 |
Note that it is supported for any language, not only `c`, using `<lang>_stdlib` |
| 319 |
property. |
| 320 |
|
| 321 |
Since *0.56.0* the variable name parameter is no longer required as long as the |
| 322 |
subproject calls `meson.override_dependency('c_stdlib', mylibc_dep)`. |
| 323 |
The above example becomes: |
| 324 |
|
| 325 |
```ini |
| 326 |
[properties] |
| 327 |
c_stdlib = 'mylibc' |
| 328 |
``` |
| 329 |
|
| 330 |
## Changing cross file settings |
| 331 |
|
| 332 |
Cross file settings are only read when the build directory is set up |
| 333 |
the first time. Any changes to them after the fact will be ignored. |
| 334 |
This is the same as regular compiles where you can't change the |
| 335 |
compiler once a build tree has been set up. If you need to edit your |
| 336 |
cross file, then you need to wipe your build tree and recreate it from |
| 337 |
scratch. |
| 338 |
|
| 339 |
## Custom data |
| 340 |
|
| 341 |
You can store arbitrary data in `properties` and access them from your |
| 342 |
Meson files. As an example if your cross file has this: |
| 343 |
|
| 344 |
```ini |
| 345 |
[properties] |
| 346 |
somekey = 'somevalue' |
| 347 |
``` |
| 348 |
|
| 349 |
then you can access that using the `meson` object like this: |
| 350 |
|
| 351 |
```meson |
| 352 |
myvar = meson.get_external_property('somekey') |
| 353 |
# myvar now has the value 'somevalue' |
| 354 |
``` |
| 355 |
|
| 356 |
## Cross file locations |
| 357 |
|
| 358 |
As of version 0.44.0 Meson supports loading cross files from system |
| 359 |
locations (except on Windows). This will be |
| 360 |
$XDG_DATA_DIRS/meson/cross, or if XDG_DATA_DIRS is undefined, then |
| 361 |
/usr/local/share/meson/cross and /usr/share/meson/cross will be tried |
| 362 |
in that order, for system wide cross files. User local files can be |
| 363 |
put in $XDG_DATA_HOME/meson/cross, or ~/.local/share/meson/cross if |
| 364 |
that is undefined. |
| 365 |
|
| 366 |
The order of locations tried is as follows: |
| 367 |
- A file relative to the local dir |
| 368 |
- The user local location |
| 369 |
- The system wide locations in order |
| 370 |
|
| 371 |
Distributions are encouraged to ship cross files either with their |
| 372 |
cross compiler toolchain packages or as a standalone package, and put |
| 373 |
them in one of the system paths referenced above. |
| 374 |
|
| 375 |
These files can be loaded automatically without adding a path to the |
| 376 |
cross file. For example, if a ~/.local/share/meson/cross contains a |
| 377 |
file called x86-linux, then the following command would start a cross |
| 378 |
build using that cross files: |
| 379 |
|
| 380 |
```sh |
| 381 |
meson setup builddir/ --cross-file x86-linux |
| 382 |
``` |