Added "native" kwarg to add_XXX_args. Closes #3669.

2 files changed, 53 insertions, 9 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 3ae740d..6cf7552 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -13,13 +13,22 @@ afterwards](#returned-objects).
   void add_global_arguments(arg1, arg2, ...)
 ```
 
-Adds the positional arguments to the compiler command line for the
-language specified in `language` keyword argument. If a list of
-languages is given, the arguments are added to each of the
-corresponding compiler command lines. Note that there is no way to
-remove an argument set in this way. If you have an argument that is
-only used in a subset of targets, you have to specify it in per-target
-flags.
+Adds the positional arguments to the compiler command line. This
+function has two keyword arguments:
+
+- `language` specifies the language(s) that the arguments should be
+applied to. If a list of languages is given, the arguments are added
+to each of the corresponding compiler command lines. Note that there
+is no way to remove an argument set in this way. If you have an
+argument that is only used in a subset of targets, you have to specify
+it in per-target flags.
+
+- `native` is a boolean specifying whether the arguments should be
+  applied to the native or cross compilation. If `true` the arguments
+  will only be used for native compilations. If `false` the arguments
+  will only be used in cross compilations. If omitted, the flags are
+  added to native compilations if compiling natively and cross
+  compilations (only) when cross compiling. Available since 0.48.0
 
 The arguments are used in all compiler invocations with the exception
 of compile tests, because you might need to run a compile test with
@@ -60,8 +69,9 @@ 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.
+otherwise. Since *0.47.0* the value of a
+[`feature`](Build-options.md#features) option can also be passed to
+the `required` keyword argument.
 
 ### add_project_arguments()
 
diff --git a/docs/markdown/snippets/native_args.md b/docs/markdown/snippets/native_args.md
new file mode 100644
index 0000000..54c6de2
--- /dev/null
+++ b/docs/markdown/snippets/native_args.md
@@ -0,0 +1,34 @@
+## Projects args can be set separately for cross and native builds (potentially breaking change)
+
+It has been a longstanding bug (or let's call it a "delayed bug fix")
+that if yo do this:
+
+```meson
+add_project_arguments('-DFOO', language : 'c')
+```
+
+Then the flag is used both in native and cross compilations. This is
+very confusing and almost never what you want. To fix this a new
+keyword `native` has been added to all functions that add arguments,
+namely `add_global_arguments`, `add_global_link_arguments`,
+`add_project_arguments` and `add_project_link_arguments` that behaves
+like the following:
+
+```
+## Added to native builds when compiling natively and to cross
+## compilations when doing cross compiles.
+add_project_arguments(...)
+
+## Added only to native compilations, not used in cross compilations.
+add_project_arguments(..., native : true)
+
+## Added only to cross compilations, not used in native compilations.
+add_project_arguments(..., native : false)
+```
+
+Also remember that cross compilation is a property of each
+target. There can be target that are compiled with the native compiler
+and some which are compiled with the cross compiler.
+
+Unfortunately this change is backwards incompatible and may cause some
+projects to fail building. However this should be very rare in practice.