Merge pull request #6161 from scivision/native_property

add meson.get_external_property()

2 files changed, 31 insertions, 4 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index e3830cc..f4fa89e 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -1773,10 +1773,6 @@ the following methods.
   refer to files in the current or any other source directory instead
   of constructing paths manually with `meson.current_source_dir()`.
 
-- `get_cross_property(propname, fallback_value)` returns the given
-  property from a cross file, the optional second argument is returned
-  if not cross compiling or the given property is not found.
-
 - `get_compiler(language)` returns [an object describing a
   compiler](#compiler-object), takes one positional argument which is
   the language to use. It also accepts one keyword argument, `native`
@@ -1786,6 +1782,19 @@ the following methods.
   returns the "cross" compiler if we're currently cross-compiling and
   the "native" compiler if we're not.
 
+- `get_cross_property(propname, fallback_value)`
+  *Consider get_external_property() instead*. Returns the given
+  property from a cross file, the optional fallback_value is returned
+  if not cross compiling or the given property is not found.
+
+- `get_external_property(propname, fallback_value, native: true/false)`
+  *(added 0.54.0)* returns the given property from a native or cross file.
+  The optional fallback_value is returned if the given property is not found.
+  The optional `native: true` forces retrieving a variable from the
+  native file, even when cross-compiling.
+  If `native: false` or not specified, variable is retrieved from the
+  cross-file if cross-compiling, and from the native-file when not cross-compiling.
+
 - `has_exe_wrapper()` returns true when doing a cross build if there
   is a wrapper command that can be used to execute cross built
   binaries (for example when cross compiling from Linux to Windows,
diff --git a/docs/markdown/snippets/native_property.md b/docs/markdown/snippets/native_property.md
new file mode 100644
index 0000000..d3808d8
--- /dev/null
+++ b/docs/markdown/snippets/native_property.md
@@ -0,0 +1,18 @@
+## Native file properties
+
+As of Meson 0.54.0, the `--native-file nativefile.ini` can contain:
+
+* binaries
+* paths
+* properties
+
+which are defined and used the same way as in cross files.
+The `properties` are new for Meson 0.54.0, and are read like:
+
+```meson
+x = meson.get_external_property('foobar', 'foo')
+```
+
+where `foobar` is the property name, and the optional `foo` is the fallback string value.
+
+For cross-compiled projects, `get_external_property()` reads the cross-file unless `native: true` is specified.
\ No newline at end of file