From f5c9bf96b370832fc1a6e50771e2c171de0cd79d Mon Sep 17 00:00:00 2001 From: Daniel Mensinger Date: Mon, 5 Oct 2020 20:45:38 +0200 Subject: cmake: Add cross docs --- docs/markdown/CMake-module.md | 37 +++++++++++++++++++++++ docs/markdown/Machine-files.md | 57 +++++++++++++++++++++++++++++++++++ docs/markdown/snippets/cmake_cross.md | 8 +++++ 3 files changed, 102 insertions(+) create mode 100644 docs/markdown/snippets/cmake_cross.md 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. -- cgit v1.1