Debian Codegraph @

subprojects/meson-docs/docs/markdown/Cross-compilation.md

raw
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 ```