3 files changed, 72 insertions, 11 deletions
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 3ae740d..6d2b2da 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()
 
@@ -370,11 +380,12 @@ otherwise. This function supports the following keyword arguments:
 - `static` tells the dependency provider to try to get static
   libraries instead of dynamic ones (note that this is not supported
   by all dependency backends)
-- `version`, specifies the required version, a string containing a
+- `version` specifies the required version, a string containing a
   comparison operator followed by the version string, examples include
   `>1.0.0`, `<=2.3.5` or `3.1.4` for exact matching. (*Added 0.37.0*)
   You can also specify multiple restrictions by passing a list to this
   keyword argument, such as: `['>=3.14.0', '<=4.1.0']`.
+  These requirements are never met if the version is unknown.
 - other
 [library-specific](Dependencies.md#dependencies-with-custom-lookup-functionality)
 keywords may also be accepted (e.g. `modules` specifies submodules to use for
@@ -1976,7 +1987,9 @@ an external dependency with the following methods:
    with `declare_dependency()` and `pkgconfig` for system dependencies
    obtained with Pkg-config.
 
- - `version()` is the version number as a string, for example `1.2.8`
+ - `version()` is the version number as a string, for example `1.2.8`.
+   `unknown` if the dependency provider doesn't support determining the
+   version.
 
  - `partial_dependency(compile_args : false, link_args : false, links
    : false, includes : false, source : false)` (*added 0.46.0*) returns
diff --git a/docs/markdown/snippets/dependency_version.md b/docs/markdown/snippets/dependency_version.md
new file mode 100644
index 0000000..4bbf346
--- /dev/null
+++ b/docs/markdown/snippets/dependency_version.md
@@ -0,0 +1,14 @@
+## `dependency(version:)` now applies to all dependency types
+
+Previously, version constraints were only enforced for dependencies found using
+the pkg-config dependency provider.  These constraints now apply to dependencies
+found using any dependency provider.
+
+Some combinations of dependency, host and method do not currently support
+discovery of the version.  In these cases, the dependency will not be found if a
+version constraint is applied, otherwise the `version()` method for the
+dependency object will return `'unknown'`.
+
+(If discovering the version in one of these combinations is important to you,
+and a method exists to determine the version in that case, please file an issue
+with as much information as possible.)
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.