Refine behaviour of add_languages() when native: is missing

This improves the common case of a simple meson.build which doesn't
contain any 'native: true' targets to not require a native compiler when
cross-compiling, without needing any changes in the meson.build.

v2:
Do it the right way around!

docs/markdown/Reference-manual.md

@@ -75,12 +75,16 @@ specified is not found, Meson will halt. Since *0.47.0* the value of a
 [`feature`](Build-options.md#features) option can also be passed.
 
 - `native` if set to `true`, the language will be used to compile for the build
-  machine, if `false`, for the host machine. If omitted, the language may be
+  machine, if `false`, for the host machine. Since *0.54.0*.
-  used for either. Since *0.54.0*. The default may change to `false` in a future
-  meson version.
 
 Returns `true` if all languages specified were found and `false` otherwise.
 
+If `native` is omitted, the languages may be used for either build or host
+machine, but are never required for the build machine.  (i.e. it is equivalent
+to `add_languages(*langs*, native: false, required: *required*) and
+add_languages(*langs*, native: true, required: false)`. This default behaviour
+may change to `native: false` in a future meson version.
+
 ### add_project_arguments()
 
 ``` meson

docs/markdown/snippets/native_compiler_not_required.md

@@ -1,5 +1,20 @@
 ## Native (build machine) compilers not always required
 
 `add_languages()` gained a `native:` keyword, indicating if a native or cross
-compiler is to be used. Currently, for backwards compatibility, if the keyword
+compiler is to be used.
-is absent, that means both are used.
+
+For the benefit of existing simple build definitions which don't contain any
+`native: true` targets, without breaking backwards compatibility for build
+definitions which assume that the native compiler is available after
+`add_languages()`, if the `native:` keyword is absent the languages may be used
+for either the build or host machine, but are never required for the build
+machine.
+
+This changes the behaviour of the following meson fragment (when cross-compiling
+but a native compiler is not available) from reporting an error at
+`add_language` to reporting an error at `executable`.
+
+```
+add_language('c')
+executable('main', 'main.c', native: true)
+```

mesonbuild/interpreter.py

@@ -2927,9 +2927,9 @@ external dependencies (including libraries) must go to "dependencies".''')
             return self.add_languages(args, required, self.machine_from_native_kwarg(kwargs))
         else:
             # absent 'native' means 'both' for backwards compatibility
-            mlog.warning('add_languages is missing native:, assuming languages are required for both host and build.',
+            mlog.warning('add_languages is missing native:, assuming languages are wanted for both host and build.',
                          location=self.current_node)
-            success = self.add_languages(args, required, MachineChoice.BUILD)
+            success = self.add_languages(args, False, MachineChoice.BUILD)
             success &= self.add_languages(args, required, MachineChoice.HOST)
             return success