Fix legacy env var support with cross

Fix #3969

2 files changed, 21 insertions, 13 deletions

diff --git a/docs/markdown/howtox.md b/docs/markdown/howtox.md
index 1a2add0..8231d3d 100644
--- a/docs/markdown/howtox.md
+++ b/docs/markdown/howtox.md
@@ -12,19 +12,15 @@ When first running Meson, set it in an environment variable.
 $ CC=mycc meson <options>
 ```
 
-Note that environment variables like `CC` _always_ refer to the native
-compiler. That is, the compiler used to compile programs that run on
-the current machine. The compiler used in cross compilation is set
-with the cross file.
-
-This behaviour is different from e.g. Autotools, where cross
-compilation is done by setting `CC` to point to the cross compiler
-(such as `/usr/bin/arm-linux-gnueabihf-gcc`). The reason for this is
-that Meson supports natively the case where you compile helper tools
-(such as code generators) and use the results during the
-build. Because of this Meson needs to know both the native and the
-cross compiler. The former is set via the environment variables or
-native-files and the latter via the cross file only.
+Note that environment variables like `CC` only works in native builds. The `CC`
+refers to the compiler for the host platform, that is the compiler used to
+compile programs that run on the machine we will eventually install the project
+on. The compiler used to build things that run on the machine we do the
+building can be specified with `CC_FOR_BUILD`. You can use it in cross builds.
+
+Note that environment variables are never the idiomatic way to do anything with
+Meson, however. It is better to use the native and cross files. And the tools
+for the host platform in cross builds can only be specified with a cross file.
 
 There is a table of all environment variables supported [Here](Reference-tables.md#compiler-and-linker-selection-variables)
 
diff --git a/docs/markdown/snippets/env_vars_and_cross.md b/docs/markdown/snippets/env_vars_and_cross.md
new file mode 100644
index 0000000..61a63f3
--- /dev/null
+++ b/docs/markdown/snippets/env_vars_and_cross.md
@@ -0,0 +1,12 @@
+## Environment Variables with Cross Builds
+
+Previously in Meson, variables like `CC` effected both the host and build
+platforms for native builds, but the just the build platform for cross builds.
+Now `CC_FOR_BUILD` is used for the build platform in cross builds.
+
+This old behavior is inconsistent with the way Autotools works, which
+undermines the purpose of distro-integration that is the only reason
+environment variables are supported at all in Meson. The new behavior is not
+quite the same, but doesn't conflict: meson doesn't always repond to an
+environment when Autoconf would, but when it does it interprets it as Autotools
+would.