Merge pull request #6532 from jon-turney/languages-native-kwarg

Add add_languages(native:)

2 files changed, 39 insertions, 9 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 9bb7911..ea02cd4 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -54,9 +54,9 @@ Like `add_global_arguments` but the arguments are passed to the linker.
   bool add_languages(*langs*)
 ```
 
-Add support for new programming languages. Equivalent to having them
-in the `project` declaration. This function is usually used to add
-languages that are only used on some platforms like this:
+Add programming languages used by the project. Equivalent to having them in the
+`project` declaration. This function is usually used to add languages that are
+only used under some conditions, like this:
 
 ```meson
 project('foobar', 'c')
@@ -68,12 +68,22 @@ if add_languages('cpp', required : false)
 endif
 ```
 
-Takes one keyword argument, `required`. It defaults to `true`, which
-means that if any of the languages specified is not found, Meson will
-halt. Returns true if all languages specified were found and false
-otherwise. Since *0.47.0* the value of a
-[`feature`](Build-options.md#features) option can also be passed to
-the `required` keyword argument.
+Takes the following keyword arguments:
+
+- `required` defaults to `true`, which means that if any of the languages
+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. Since *0.54.0*.
+
+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()
 
diff --git a/docs/markdown/snippets/native_compiler_not_required.md b/docs/markdown/snippets/native_compiler_not_required.md
new file mode 100644
index 0000000..331b3c7
--- /dev/null
+++ b/docs/markdown/snippets/native_compiler_not_required.md
@@ -0,0 +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.
+
+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)
+```