summaryrefslogtreecommitdiffstats
path: root/Help/variable
diff options
context:
space:
mode:
authorCraig Scott <craig.scott@crascit.com>2018-01-18 21:30:53 (GMT)
committerCraig Scott <craig.scott@crascit.com>2018-01-18 21:31:34 (GMT)
commit60febda45541c65e0ca7fb4535c629c77c17e13a (patch)
tree4558c35025e73e4bd489aaf132823f1d8750f1ad /Help/variable
parentcbe7314bb0f0ce5dbc7a5a9d71f3688c810cf731 (diff)
downloadCMake-60febda45541c65e0ca7fb4535c629c77c17e13a.zip
CMake-60febda45541c65e0ca7fb4535c629c77c17e13a.tar.gz
CMake-60febda45541c65e0ca7fb4535c629c77c17e13a.tar.bz2
Help: Explain meaning and limitations of CMAKE_CROSSCOMPILING
Fixes: #17653
Diffstat (limited to 'Help/variable')
-rw-r--r--Help/variable/CMAKE_CROSSCOMPILING.rst26
1 files changed, 22 insertions, 4 deletions
diff --git a/Help/variable/CMAKE_CROSSCOMPILING.rst b/Help/variable/CMAKE_CROSSCOMPILING.rst
index cf9865b..9e96769 100644
--- a/Help/variable/CMAKE_CROSSCOMPILING.rst
+++ b/Help/variable/CMAKE_CROSSCOMPILING.rst
@@ -1,8 +1,26 @@
CMAKE_CROSSCOMPILING
--------------------
-Is CMake currently cross compiling.
+Intended to indicate whether CMake is cross compiling, but note limitations
+discussed below.
-This variable will be set to true by CMake if CMake is cross
-compiling. Specifically if the build platform is different from the
-target platform.
+This variable will be set to true by CMake if the :variable:`CMAKE_SYSTEM_NAME`
+variable has been set manually (i.e. in a toolchain file or as a cache entry
+from the :manual:`cmake <cmake(1)>` command line). In most cases, manually
+setting :variable:`CMAKE_SYSTEM_NAME` will only be done when cross compiling,
+since it will otherwise be given the same value as
+:variable:`CMAKE_HOST_SYSTEM_NAME` if not manually set, which is correct for
+the non-cross-compiling case. In the event that :variable:`CMAKE_SYSTEM_NAME`
+is manually set to the same value as :variable:`CMAKE_HOST_SYSTEM_NAME`, then
+``CMAKE_CROSSCOMPILING`` will still be set to true.
+
+Another case to be aware of is that builds targeting Apple platforms other than
+macOS are handled differently to other cross compiling scenarios. Rather than
+relying on :variable:`CMAKE_SYSTEM_NAME` to select the target platform, Apple
+device builds use :variable:`CMAKE_OSX_SYSROOT` to select the appropriate SDK,
+which indirectly determines the target platform. Furthermore, when using the
+Xcode generator, developers can switch between device and simulator builds at
+build time rather than having a single choice at configure time, so the concept
+of whether the build is cross compiling or not is more complex. Therefore, the
+use of ``CMAKE_CROSSCOMPILING`` is not recommended for projects targeting Apple
+devices.