docs: Add a new page with common cross/native file options [skip ci]

Rather than having two separate sections with duplicated information
lets just have one for the common settings, and only document sections
specific to each file in separately

docs/markdown/Cross-compilation.md

@@ -89,40 +89,32 @@ get the hang of it eventually.
 
 Meson requires you to write a cross build definition file. It defines
 various properties of the cross build environment. The cross file
-consists of different sections. The first one is the list of
+consists of different sections.
-executables that we are going to use. A sample snippet might look like
+
-this:
+There are a number of options shared by cross and native files,
+[here](Machine-files.md). It is assumed that you have read that section already,
+as this documentation will only call out options specific to cross files.
+
+### Binaries
 
 ```ini
 [binaries]
-c = '/usr/bin/i586-mingw32msvc-gcc'
-cpp = '/usr/bin/i586-mingw32msvc-g++'
-c_ld = 'gold'
-cpp_ld = 'gold'
-ar = '/usr/i586-mingw32msvc/bin/ar'
-strip = '/usr/i586-mingw32msvc/bin/strip'
-pkgconfig = '/usr/bin/i586-mingw32msvc-pkg-config'
 exe_wrapper = 'wine' # A command used to run generated executables.
 ```
 
-The entries are pretty self explanatory but the last line is
+The `exe_wrapper` option defines a *wrapper command* that can be used to run
-special. It defines a *wrapper command* that can be used to run
+executables for this host. In this case we can use Wine, which runs Windows
-executables for this host. In this case we can use Wine, which runs
+applications on Linux. Other choices include running the application with
-Windows applications on Linux. Other choices include running the
+qemu or a hardware simulator. If you have this kind of a wrapper, these lines
-application with qemu or a hardware simulator. If you have this kind
+are all you need to write. Meson will automatically use the given wrapper
-of a wrapper, these lines are all you need to write. Meson will
+when it needs to run host binaries. This happens e.g. when running the
-automatically use the given wrapper when it needs to run host
+project's test suite.
-binaries. This happens e.g. when running the project's test suite.
+
-
+### Properties
-ld is special because it is compiler specific. For compilers like gcc and
+
-clang which are used to invoke the linker this is a value to pass to their
+In addition to the properites allowed in [all machine
-"choose the linker" argument (-fuse-ld= in this case). For compilers like
+files](Machine-files.md#properties), the cross file may contain specific
-MSVC and Clang-Cl, this is the path to a linker for meson to invoke, such as
+information about the cross compiler or the host machine. It looks like this:
-`link.exe` or `lld-link.exe`. Support for ls is *new in 0.53.0*
-
-The next section lists properties of the cross compiler and its target
-system, and thus properties of host system of what we're building. It
-looks like this:
 
 ```ini
 [properties]
@@ -136,8 +128,6 @@ alignment_double = 4
 
 has_function_printf = true
 
-c_args = ['-DCROSS=1', '-DSOMETHING=3']
-c_link_args = ['-some_link_arg']
 sys_root = '/some/path'
 pkg_config_libdir = '/some/path/lib/pkgconfig'
 ```
@@ -180,6 +170,8 @@ binaries are not actually compatible. In such cases you may use the
 needs_exe_wrapper = true
 ```
 
+### Machine Entries
+
 The next bit is the definition of host and target machines. Every
 cross build definition must have one or both of them. If it had
 neither, the build would not be a cross build but a native build. You
@@ -216,24 +208,6 @@ If you do not define your host machine, it is assumed to be the build
 machine. Similarly if you do not specify target machine, it is assumed
 to be the host machine.
 
-Additionally, you can define the paths that you want to install to in your
-cross file. This may be especially useful when cross compiling an entire
-operating system, or for operating systems to use internally for consistency.
-
-```ini
-[paths]
-prefix = '/my/prefix'
-libdir = 'lib/i386-linux-gnu'
-bindir = 'bin'
-```
-
-This will be overwritten by any options passed on the command line.
-
-Since meson 0.52.0 it is possible to layer cross files together. This
-works like native file layering: the purpose is to compose cross files
-together, and values from the second cross file will replace those
-from the first.
-
 
 ## Starting a cross build
 

docs/markdown/Machine-files.md

@@ -0,0 +1,115 @@
+# Cross and Native File reference
+
+Cross and native files are nearly identical, but not completely. This is the
+documentation on the common values used by both, for the specific values of
+one or the other see the [cross compilation](Cross-compilation.md) and [native
+environments](Native-environments.md).
+
+## Sections
+
+The following sections are allowed:
+- binaries
+- paths
+- properties
+
+### Binaries
+
+The binaries section contains a list of binaries. These can be used
+internally by meson, or by the `find_program` function:
+
+Compilers and linkers are defined here using `<lang>` and `<lang>_ld`.
+`<lang>_ld` is special because it is compiler specific. For compilers like
+gcc and clang which are used to invoke the linker this is a value to pass to
+their "choose the linker" argument (-fuse-ld= in this case). For compilers
+like MSVC and Clang-Cl, this is the path to a linker for meson to invoke,
+such as `link.exe` or `lld-link.exe`. Support for ls is *new in 0.53.0*
+
+*changed in 0.53.1* the `ld` variable was replaced by `<lang>_ld`, because it
+*regressed a large number of projects. in 0.53.0 the `ld` variable was used
+instead.
+
+Native example:
+
+```ini
+c = '/usr/bin/clang'
+c_ld = 'lld'
+sed = 'C:\\program files\\gnu\\sed.exe'
+llvm-config = '/usr/lib/llvm8/bin/llvm-config'
+```
+
+Cross example:
+
+```ini
+c = '/usr/bin/i586-mingw32msvc-gcc'
+cpp = '/usr/bin/i586-mingw32msvc-g++'
+c_ld = 'gold'
+cpp_ld = 'gold'
+ar = '/usr/i586-mingw32msvc/bin/ar'
+strip = '/usr/i586-mingw32msvc/bin/strip'
+pkgconfig = '/usr/bin/i586-mingw32msvc-pkg-config'
+```
+
+An incomplete list of internally used programs that can be overridden here is:
+- cmake
+- cups-config
+- gnustep-config
+- gpgme-config
+- libgcrypt-config
+- libwmf-config
+- llvm-config
+- pcap-config
+- pkgconfig
+- sdl2-config
+- wx-config (or wx-3.0-config or wx-config-gtk)
+
+### Paths and Directories
+
+As of 0.50.0 paths and directories such as libdir can be defined in the native
+file in a paths section
+
+```ini
+[paths]
+libdir = 'mylibdir'
+prefix = '/my prefix'
+```
+
+These values will only be loaded when not cross compiling. Any arguments on the
+command line will override any options in the native file. For example, passing
+`--libdir=otherlibdir` would result in a prefix of `/my prefix` and a libdir of
+`otherlibdir`.
+
+### Properties
+
+*New in native files in 0.54.0*, always in cross files.
+
+In addition to special data that may be specified in cross files, this
+section may contain random key value pairs accessed using the
+`meson.get_external_property()`
+
+## Properties
+
+*New for native files in 0.54.0*
+
+The properties section can contain any variable you like, and is accessed via
+`meson.get_external_property`, or `meson.get_cross_property`.
+
+## Loading multiple machine files
+
+Native files allow layering (cross files can be layered since meson 0.52.0).
+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. This composition is done by passing the command line
+argument multiple times:
+
+```console
+meson setup builddir/ --cross-file first.ini --cross-file second.ini --cross-file thrid.ini
+```
+
+In this case `first.ini` will be loaded, then `second.ini`, with values from
+`second.ini` replacing `first.ini`, and so on.
+
+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.

docs/markdown/Native-environments.md

@@ -19,63 +19,15 @@ 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
+See the [config-files section](Machine-files.md), for options shared by cross
-
+and native files.
-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'
-c_ld = 'gold'
-cpp_ld = 'gold'
-rust_ld = 'gold'
-llvm-config = '/usr/local/llvm-svn/bin/llvm-config'
-```
-
-### Paths and Directories
-
-As of 0.50.0 paths and directories such as libdir can be defined in the native
-file in a paths section
-
-```ini
-[paths]
-libdir = 'mylibdir'
-prefix = '/my prefix'
-```
-
-These values will only be loaded when not cross compiling. Any arguments on the
-command line will override any options in the native file. For example, passing
-`--libdir=otherlibdir` would result in a prefix of `/my prefix` and a libdir of
-`otherlibdir`.
-
-
-## Loading multiple native files
-
-Native files allow layering (cross files can be layered since meson 0.52.0).
-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
 

docs/sitemap.txt

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