cmake: Add cross docs

3 files changed, 102 insertions, 0 deletions

diff --git a/docs/markdown/CMake-module.md b/docs/markdown/CMake-module.md
index fc6157e..48c3d75 100644
--- a/docs/markdown/CMake-module.md
+++ b/docs/markdown/CMake-module.md
@@ -176,6 +176,43 @@ Options that are not set won't affect the generated subproject. So, if for
 instance, `set_install` was not called then the values extracted from CMake will
 be used.
 
+### Cross compilation
+
+*New in 0.56.0*
+
+Meson will try to automatically guess most of the required CMake toolchain
+variables from existing entries in the cross and native files. These variables
+will be stored in an automatically generate CMake toolchain file in the build
+directory. The remaining variables that can't be guessed can be added by the
+user in the `[cmake]` cross/native file section (*new in 0.56.0*).
+
+Adding a manual CMake toolchain file is also supported with the
+`cmake_toolchain_file` setting in the `[properties]` section. Directly setting
+a CMake toolchain file with `-DCMAKE_TOOLCHAIN_FILE=/path/to/some/Toolchain.cmake`
+in the `meson.build` is **not** supported since the automatically generated
+toolchain file is also used by Meson to inject arbitrary code into CMake to
+enable the CMake subproject support.
+
+The closest configuration to only using a manual CMake toolchain file would be
+to set these options in the machine file:
+
+```ini
+[properties]
+
+cmake_toolchain_file = '/path/to/some/Toolchain.cmake'
+cmake_defaults       = false
+
+[cmake]
+
+# No entries in this section
+```
+
+This will result in a toolchain file with just the bare minimum to enable the
+CMake subproject support and `include()` the `cmake_toolchain_file` as the
+last instruction.
+
+For more information see the [cross and native file specification](Machine-files.md).
+
 ## CMake configuration files
 
 ### cmake.write_basic_package_version_file()
diff --git a/docs/markdown/Machine-files.md b/docs/markdown/Machine-files.md
index ab450cc..72d2e0c 100644
--- a/docs/markdown/Machine-files.md
+++ b/docs/markdown/Machine-files.md
@@ -46,6 +46,7 @@ The following sections are allowed:
 - binaries
 - paths
 - properties
+- cmake
 - project options
 - built-in options
 
@@ -203,6 +204,62 @@ section may contain random key value pairs accessed using the
 properties section has been deprecated, and should be put in the built-in
 options section.
 
+#### Supported properties
+
+This is a non exhaustive list of supported variables in the `[properties]`
+section.
+
+- `cmake_toolchain_file` specifies an absoulte path to an already existing
+  CMake toolchain file that will be loaded with `include()` as the last
+  instruction of the automatically generated CMake toolchain file from meson.
+  (*new in 0.56.0*)
+- `cmake_defaults` is a boolean that specifies whether meson should automatically
+  generate default toolchain varaibles from other sections (`binaries`,
+  `host_machine`, etc.) in the machine file. Defaults are always overwritten
+  by variables set in the `[cmake]` section. The default is `true`. (*new in 0.56.0*)
+- `cmake_skip_compiler_test` is an enum that specifies when meson should
+  automatically generate toolchain variables to skip the CMake compiler
+  sanity checks. This only has an effect if `cmake_defaults` is `true`.
+  Supported values are `always`, `never`, `dep_only`. The default is `dep_only`.
+  (*new in 0.56.0*)
+- `cmake_use_exe_wrapper` is a boolean that controlls whether to use the
+  `exe_wrapper` specified in `[binaries]` to run generated executables in CMake
+  subprojects. This setting has no effect if the `exe_wrapper` was not specified.
+  The default value is `true`. (*new in 0.56.0*)
+
+### CMake variables
+
+*New in 0.56.0*
+
+All variables set in the `[cmake]` section will be added to the generate CMake
+toolchain file used for both CMake dependencies and CMake subprojects. The type
+of each entry must be either a string or a list of strings.
+
+**Note:** All occurances of `\` in the value of all keys will be replaced with
+          a `/` since CMake has a lot of issues with correctly escaping `\` when
+          dealing with variables (even in cases where a path in `CMAKE_C_COMPILER`
+          is correctly escaped, CMake will still trip up internaly for instance)
+
+          A custom toolchain file should be used (via the `cmake_toolchain_file`
+          property) if `\` support is required.
+
+```ini
+[cmake]
+
+CMAKE_C_COMPILER    = '/usr/bin/gcc'
+CMAKE_CXX_COMPILER  = 'C:\\user\\bin\\g++'
+CMAKE_SOME_VARIABLE = ['some', 'value with spaces']
+```
+
+For instance, the `[cmake]` section from above will generate the following
+code in the CMake toolchain file:
+
+```cmake
+set(CMAKE_C_COMPILER    "/usr/bin/gcc")
+set(CMAKE_C_COMPILER    "C:/usr/bin/g++")
+set(CMAKE_SOME_VARIABLE "some" "value with spaces")
+```
+
 ### Project specific options
 
 *New in 0.56.0*
diff --git a/docs/markdown/snippets/cmake_cross.md b/docs/markdown/snippets/cmake_cross.md
new file mode 100644
index 0000000..249c95f
--- /dev/null
+++ b/docs/markdown/snippets/cmake_cross.md
@@ -0,0 +1,8 @@
+## CMake subproject cross compilation support
+
+Meson now supports cross compilation for CMake subprojects. Meson will try to
+automatically guess most of the required CMake toolchain variables from existing
+entries in the cross and native files. These variables will be stored in an
+automatically generate CMake toolchain file in the build directory. The
+remaining variables that can't be guessed can be added by the user in the
+new `[cmake]` cross/native file section.