Merge topic 'explicit-system-version'

b31ac171 Allow CMAKE_SYSTEM_VERSION to be set without CMAKE_SYSTEM_NAME
70688609 Help: Improve CMAKE_SYSTEM_{NAME,VERSION} variable documentation

Help/variable/CMAKE_SYSTEM_NAME.rst

@@ -1,8 +1,20 @@
 CMAKE_SYSTEM_NAME
 -----------------
 
-Name of the operating system CMake is building for.
+The name of the operating system for which CMake is to build.
+See the :variable:`CMAKE_SYSTEM_VERSION` variable for the OS version.
 
-This is the name of the operating system on which CMake is targeting.  This
-variable is the same as :variable:`CMAKE_HOST_SYSTEM_NAME` if you build for the
-host system instead of the target system when cross compiling.
+System Name for Host Builds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``CMAKE_SYSTEM_NAME`` is by default set to the same value as the
+:variable:`CMAKE_HOST_SYSTEM_NAME` variable so that the build
+targets the host system.
+
+System Name for Cross Compiling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``CMAKE_SYSTEM_NAME`` may be set explicitly when first configuring a new build
+tree in order to enable :ref:`cross compiling <Cross Compiling Toolchain>`.
+In this case the :variable:`CMAKE_SYSTEM_VERSION` variable must also be
+set explicitly.

Help/variable/CMAKE_SYSTEM_VERSION.rst

@@ -1,8 +1,28 @@
 CMAKE_SYSTEM_VERSION
 --------------------
 
-The operating system version CMake is building for.
+The version of the operating system for which CMake is to build.
+See the :variable:`CMAKE_SYSTEM_NAME` variable for the OS name.
 
-This variable is the same as :variable:`CMAKE_HOST_SYSTEM_VERSION` if
-you build for the host system instead of the target system when
-cross compiling.
+System Version for Host Builds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the :variable:`CMAKE_SYSTEM_NAME` variable takes its default value
+then ``CMAKE_SYSTEM_VERSION`` is by default set to the same value as the
+:variable:`CMAKE_HOST_SYSTEM_VERSION` variable so that the build targets
+the host system version.
+
+In the case of a host build then ``CMAKE_SYSTEM_VERSION`` may be set
+explicitly when first configuring a new build tree in order to enable
+targeting the build for a different version of the host operating system
+than is actually running on the host.  This is allowed and not considered
+cross compiling so long as the binaries built for the specified OS version
+can still run on the host.
+
+System Version for Cross Compiling
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When the :variable:`CMAKE_SYSTEM_NAME` variable is set explicitly to
+enable :ref:`cross compiling <Cross Compiling Toolchain>` then the
+value of ``CMAKE_SYSTEM_VERSION`` must also be set explicitly to specify
+the target system version.

Modules/CMakeDetermineSystem.cmake

@@ -123,7 +123,9 @@ elseif(CMAKE_VS_WINCE_VERSION)
   set(PRESET_CMAKE_SYSTEM_NAME TRUE)
 else()
   set(CMAKE_SYSTEM_NAME      "${CMAKE_HOST_SYSTEM_NAME}")
-  set(CMAKE_SYSTEM_VERSION   "${CMAKE_HOST_SYSTEM_VERSION}")
+  if(NOT DEFINED CMAKE_SYSTEM_VERSION)
+    set(CMAKE_SYSTEM_VERSION "${CMAKE_HOST_SYSTEM_VERSION}")
+  endif()
   set(CMAKE_SYSTEM_PROCESSOR "${CMAKE_HOST_SYSTEM_PROCESSOR}")
   set(CMAKE_CROSSCOMPILING FALSE)
   set(PRESET_CMAKE_SYSTEM_NAME FALSE)