docs: Add documentation for Native Files

docs/markdown/Native-environments.md

@@ -0,0 +1,76 @@
+---
+short-description: Setting up native compilation
+...
+
+# Persistent native environments
+
+New in 0.49.0
+
+Meson has [cross files for describing cross compilation environments](Cross-compilation.md),
+for describing native environments it has equivalent "native files".
+
+Natives describe the *build machine*, and can be used to override properties of
+non-cross builds, as well as properties that are marked as "native" in a cross
+build.
+
+There are a couple of reasons you might want to use a native file to keep a
+persistent environment:
+
+* To build with a non-default native tool chain (such as clang instead of gcc)
+* To use a non-default version of another binary, such as yacc, or llvm-config
+
+
+## Changing native file settings
+
+All of the rules about cross files and changed settings apply to native files
+as well, see [here](Cross-compilation.md#Changing-cross-file-settings)
+
+
+## Defining the environment
+
+### Binaries
+
+Currently the only use of native files is to override native binaries. This
+includes the compilers and binaries collected with `find_program`, and those
+used by dependencies that use a config-tool instead of pkgconfig for detection,
+like `llvm-config`
+
+```ini
+[binaries]
+c = '/usr/local/bin/clang'
+cpp = '/usr/local/bin/clang++'
+rust = '/usr/local/bin/rust'
+llvm-conifg = '/usr/local/llvm-svn/bin/llvm-config'
+```
+
+## Loading multiple native files
+
+Unlike cross file, native files allow layering. More than one native file can be
+loaded, with values from a previous file being overridden by the next. The
+intention of this is not overriding, but to allow composing native files.
+
+For example, if there is a project using C and C++, python 3.4-3.7, and LLVM
+5-7, and it needs to build with clang 5, 6, and 7, and gcc 5.x, 6.x, and 7.x;
+expressing all of these configurations in monolithic configurations would
+result in 81 different native files. By layering them, it can be expressed by
+just 12 native files.
+
+
+## Native file locations
+
+Like cross files, native files may be installed to user or system wide
+locations, defined as:
+  - $XDG_DATA_DIRS/meson/native 
+    (/usr/local/share/meson/native:/usr/share/meson/native if $XDG_DATA_DIRS is
+    undefined)
+  - $XDG_DATA_HOME/meson/native ($HOME/.local/share/meson/native if
+    $XDG_DATA_HOME is undefined)
+
+The order of locations tried is as follows:
+ - A file relative to the local dir
+ - The user local location
+ - The system wide locations in order
+
+These files are not intended to be shipped by distributions, unless they are
+specifically for distribution packaging, they are mainly intended for
+developers.

docs/markdown/snippets/native_files.md

@@ -0,0 +1,15 @@
+## Native config files
+
+Native files are the counterpart to cross files, and allow specifying
+information about the build machine, both when cross compiling and when not.
+
+Currently the native files only allow specifying the names of binaries, similar
+to the cross file, for example:
+
+```ini
+[binaries]
+llvm-config = "/opt/llvm-custom/bin/llvm-config"
+```
+
+Will override the llvm-config used for *native* binaries. Targets for the host
+machine will continue to use the cross file.

docs/sitemap.txt

@@ -9,6 +9,7 @@ index.md
 		Using-with-Visual-Studio.md
 		Meson-sample.md
 		Syntax.md
+		Native-environments.md
 		Build-targets.md
 		Include-directories.md
 		Installing.md