Merge topic 'doc-system-names'

ef2547bd6a Help: Document CMAKE_SYSTEM_NAME possible values

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !9211

3 files changed, 85 insertions, 24 deletions

diff --git a/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst b/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst
index e892677..0fe6146 100644
--- a/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst
+++ b/Help/variable/CMAKE_HOST_SYSTEM_NAME.rst
@@ -6,3 +6,5 @@ Name of the OS CMake is running on.
 On systems that have the uname command, this variable is set to the
 output of ``uname -s``.  ``Linux``, ``Windows``, and ``Darwin`` for macOS
 are the values found on the big three operating systems.
+
+For a list of possible values, see :variable:`CMAKE_SYSTEM_NAME`.
diff --git a/Help/variable/CMAKE_SYSTEM_NAME.rst b/Help/variable/CMAKE_SYSTEM_NAME.rst
index fef53ee..e9ffec4 100644
--- a/Help/variable/CMAKE_SYSTEM_NAME.rst
+++ b/Help/variable/CMAKE_SYSTEM_NAME.rst
@@ -21,3 +21,86 @@ System Name for Cross Compiling
 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.
+
+System Names Known to CMake
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following is a list of possible values, each associated with corresponding
+operating systems or environments.
+
+========================= ======================================================
+Value                     Name
+========================= ======================================================
+``ADSP``                  Analog Devices Audio Digital Signal Processing
+``AIX``                   IBM Unix operating system
+``Android``               Android operating system
+``ARTOS``                 Operating system for microcontrollers
+``BeOS``                  Operating system for personal computers (discontinued)
+``BlueGeneL``             Blue Gene/L static environment
+``BlueGeneP-dynamic``     Blue Gene/P dynamic environment
+``BlueGeneP-static``      Blue Gene/P static environment
+``BlueGeneQ-dynamic``     Blue Gene/Q dynamic environment
+``BlueGeneQ-static``      Blue Gene/Q static environment
+``BSDOS``                 BSD operating system (discontinued)
+``Catamount``             Operating system for Cray XT series
+``CrayLinuxEnvironment``  Cray Linux Environment
+``CYGWIN``                Cygwin environment for Windows
+``Darwin``                Apple stationary operating systems (macOS, OS X, etc.)
+``DOS``                   MS-DOS or compatible
+``DragonFly``             BSD-derived operating system
+``eCos``                  Real-time embedded operating system
+``Emscripten``            Compiler toolchain to WebAssembly
+``Euros``                 Real-time operating system for embedded devices
+``FreeBSD``               FreeBSD operating system
+``Fuchsia``               Operating system by Google based on the Zircon kernel
+``Generic-ADSP``          Generic ADSP (Audio DSP) environment
+``Generic-ELF``           Generic ELF (Executable and Linkable Format) environment
+``Generic``               Some platforms, e.g. bare metal embedded devices
+``GHS-MULTI``             Green Hills Software MULTI environment
+``GNU``                   GNU/Hurd-based operating system
+``Haiku``                 Unix operating system inspired by BeOS
+``HP-UX``                 Hewlett Packard Unix
+``iOS``                   Apple mobile phone operating system
+``kFreeBSD``              FreeBSD kernel with a GNU userland
+``Linux``                 All Linux-based distributions
+``Midipix``               POSIX-compatible layer for Windows
+``MirBSD``                MirOS BSD operating system
+``MP-RAS``                MP-RAS UNIX operating system
+``MSYS``                  MSYS environment (MSYSTEM=MSYS)
+``NetBSD``                NetBSD operating systems
+``OpenBSD``               OpenBSD operating systems
+``OpenVMS``               OpenVMS operating system by HP
+``OS2``                   OS/2 operating system
+``OSF1``                  Compaq Tru64 UNIX (formerly DEC OSF/1, Digital Unix) (discontinued)
+``QNX``                   Unix-like operating system by BlackBerry
+``RISCos``                RISC OS operating system
+``SCO_SV``                SCO OpenServer 5
+``SerenityOS``            Unix-like operating system
+``SINIX``                 SINIX operating system
+``SunOS``                 Oracle Solaris and all illumos operating systems
+``syllable``              Syllable operating system
+``Tru64``                 Compaq Tru64 UNIX (formerly DEC OSF/1) operating system
+``tvOS``                  Apple TV operating system
+``ULTRIX``                Unix operating system (discontinued)
+``UNIX_SV``               SCO UnixWare (pre release 7)
+``UnixWare``              SCO UnixWare 7
+``visionOS``              Apple mixed reality operating system
+``watchOS``               Apple watch operating system
+``Windows``               Windows stationary operating systems
+``WindowsCE``             Windows Embedded Compact
+``WindowsPhone``          Windows mobile phone operating system
+``WindowsStore``          Universal Windows Platform applications
+``Xenix``                 SCO Xenix Unix operating system (discontinued)
+========================= ======================================================
+
+Platform-specific notes:
+
+* MSYS2's ``msys/cmake`` package (``/usr/bin/cmake``) works only under
+  ``MSYSTEM=MSYS`` environments, with system name ``MSYS``.  Under other
+  environments like ``MSYSTEM=MINGW64``, use another package such
+  as ``mingw64/mingw-w64-x86_64-cmake`` (``/mingw64/bin/cmake``),
+  which targets ``MSYSTEM=MINGW64`` with system name ``Windows``.
+
+* Cygwin's ``cmake`` package (``/usr/bin/cmake``) uses system name ``CYGWIN``.
+  A non-cygwin CMake on Windows (e.g. ``$PROGRAMFILES/CMake/bin/cmake``)
+  uses system name ``Windows`` even when it runs under a Cygwin environment.
diff --git a/Modules/CMakeDetermineSystem.cmake b/Modules/CMakeDetermineSystem.cmake
index 1ccde43..b330ed9 100644
--- a/Modules/CMakeDetermineSystem.cmake
+++ b/Modules/CMakeDetermineSystem.cmake
@@ -6,30 +6,6 @@
 # CMAKE_SYSTEM_NAME - on unix this is uname -s, for windows it is Windows
 # CMAKE_SYSTEM_VERSION - on unix this is uname -r, for windows it is empty
 # CMAKE_SYSTEM - ${CMAKE_SYSTEM}-${CMAKE_SYSTEM_VERSION}, for windows: ${CMAKE_SYSTEM}
-#
-#  Expected uname -s output:
-#
-# AIX                           AIX
-# BSD/OS                        BSD/OS
-# FreeBSD                       FreeBSD
-# HP-UX                         HP-UX
-# Linux                         Linux
-# GNU/kFreeBSD                  GNU/kFreeBSD
-# NetBSD                        NetBSD
-# OpenBSD                       OpenBSD
-# OFS/1 (Digital Unix)          OSF1
-# SCO OpenServer 5              SCO_SV
-# SCO UnixWare 7                UnixWare
-# SCO UnixWare (pre release 7)  UNIX_SV
-# SCO XENIX                     Xenix
-# Solaris                       SunOS
-# SunOS                         SunOS
-# Tru64                         Tru64
-# Ultrix                        ULTRIX
-# cygwin                        CYGWIN_NT-5.1
-# MSYS                          MSYS_NT-6.1
-# MacOSX                        Darwin
-
 
 # find out on which system cmake runs
 if(CMAKE_HOST_UNIX)