docs: explain cross-compilation names sooner [skip ci]

Meson's documentation about cross-compilation made me finally understand
why the typical confusion about machine names. Thanks, but let's make it
even better. Don't wait until the very end of the section to reveal the
most important information: that machine names are relative. For
suspense we already have TV shows; spill the beans much earlier.

Also fix the first, simplest cross-compilation example: target is
irrelevant.
pull/6326/head
Marc Herbert 5 years ago committed by Jussi Pakkanen
parent 1dda7cde39
commit f2ad800408
  1. 34
      docs/markdown/Cross-compilation.md

@ -35,14 +35,24 @@ three machines are the same. Simple so far.
Let's next look at the most common cross-compilation setup. Let's Let's next look at the most common cross-compilation setup. Let's
suppose you are on a 64 bit OSX machine and you are cross compiling a suppose you are on a 64 bit OSX machine and you are cross compiling a
binary that will run on a 32 bit ARM Linux board. In this case your binary that will run on a 32 bit ARM Linux board. In this case your
*build machine* is 64 bit OSX and both your *host* and *target *build machine* is 64 bit OSX, your *host machine* is 32 bit ARM Linux
machines* are 32 bit ARM Linux. This should be quite understandable as and your *target machine* is irrelevant (but defaults to the same value
well. as the *host machine*). This should be quite understandable as well.
It gets a bit trickier when we think about how the cross compiler was The usual mistake in this case is to call the OSX system the *host* and
generated. It was built and it runs on a specific platform but the the ARM Linux board the *target*. That's because these were their actual
output it generates is for a different platform. In this case *build* names when the cross-compiler itself was compiled! Let's assume the
and *host machines* are the same, but *target machine* is different. cross-compiler was created on OSX too. When that happened the *build*
and *host machines* were the same OSX and different from the ARM Linux
*target machine*.
In a nutshell, the typical mistake assumes that the terms *build*,
*host* and *target* refer to some fixed positions whereas they're
actually relative to where the current compiler is running. Think of
*host* as a *child* of the current compiler and *target* as an optional
*grand-child*. Compilers don't change their terminology when they're
creating another compiler, that would at the very least make their user
interface much more complex.
The most complicated case is when you cross-compile a cross The most complicated case is when you cross-compile a cross
compiler. As an example you can, on a Linux machine, generate a cross compiler. As an example you can, on a Linux machine, generate a cross
@ -56,8 +66,8 @@ Wikipedia or the net in general. It is very common for them to get
build, host and target mixed up, even in consecutive sentences, which build, host and target mixed up, even in consecutive sentences, which
can leave you puzzled until you figure it out. can leave you puzzled until you figure it out.
A lot of confusion stems from the fact that when you cross-compile Again note that when you cross-compile something,
something, the 3 systems (*build*, *host*, and *target*) used when the 3 systems (*build*, *host*, and *target*) used when
building the cross compiler don't align with the ones used when building the cross compiler don't align with the ones used when
building something with that newly-built cross compiler. To take our building something with that newly-built cross compiler. To take our
Canadian Cross scenario from above (for full generality), since its Canadian Cross scenario from above (for full generality), since its
@ -67,8 +77,8 @@ Linux, the *host machine* of anything we build with it is *MIPS
Linux*. Only the *target machine* of whatever we build with it can be Linux*. Only the *target machine* of whatever we build with it can be
freely chosen by us, say if we want to build another cross compiler freely chosen by us, say if we want to build another cross compiler
that runs on MIPS Linux and targets Aarch64 iOS. As this example that runs on MIPS Linux and targets Aarch64 iOS. As this example
hopefully makes clear to you, the platforms are shifted over to the hopefully makes clear to you, the machine names are relative and
left by one position. shifted over to the left by one position.
If you did not understand all of the details, don't worry. For most If you did not understand all of the details, don't worry. For most
people it takes a while to wrap their head around these people it takes a while to wrap their head around these

Loading…
Cancel
Save