Merge topic 'patch-CMAKE_COMPILER_IS_GNU-docs'

7db3f983b3 CMAKE_COMPILER_IS_*: Add RST deprecation directives and update docs

Acked-by: Kitware Robot <[email protected]>
Merge-request: !10550

Help/variable/CMAKE_COMPILER_IS_GNUCC.rst

@@ -1,7 +1,47 @@
 CMAKE_COMPILER_IS_GNUCC
 -----------------------
 
-True if the ``C`` compiler is GNU.
+.. deprecated:: 3.24
 
-This variable is deprecated.  Use
-:variable:`CMAKE_C_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead.
+  Use the :variable:`CMAKE_C_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` variable
+  instead.
+
+  The ``CMAKE_COMPILER_IS_*`` variables were used in early CMake versions before
+  the introduction of :variable:`CMAKE_<LANG>_COMPILER_ID` variables in CMake
+  2.6.
+
+The ``CMAKE_COMPILER_IS_GNUCC`` variable is set to boolean true if the ``C``
+compiler is GNU.
+
+Examples
+^^^^^^^^
+
+In earlier versions of CMake, the ``CMAKE_COMPILER_IS_GNUCC`` variable was used
+to check if the ``C`` compiler was GNU:
+
+.. code-block:: cmake
+
+  if(CMAKE_COMPILER_IS_GNUCC)
+    # GNU C compiler-specific logic.
+  endif()
+
+Starting with CMake 2.6, the ``CMAKE_C_COMPILER_ID`` variable should be used
+instead:
+
+.. code-block:: cmake
+
+  if(CMAKE_C_COMPILER_ID STREQUAL "GNU")
+    # GNU C compiler-specific logic.
+  endif()
+
+When upgrading code, consider whether additional ``C`` compilers should be
+targeted beyond just ``GNU``.  In the past, the ``LCC`` and ``QCC`` compilers
+also had this variable set (see :policy:`CMP0047` and :policy:`CMP0129` policies
+for details). To account for this, the following approach can be used:
+
+.. code-block:: cmake
+
+  # Targeting GNU, LCC, and QCC compilers for C:
+  if(CMAKE_C_COMPILER_ID MATCHES "^(GNU|LCC|QCC)$")
+    # ...
+  endif()

Help/variable/CMAKE_COMPILER_IS_GNUCXX.rst

@@ -1,7 +1,47 @@
 CMAKE_COMPILER_IS_GNUCXX
 ------------------------
 
-True if the C++ (``CXX``) compiler is GNU.
+.. deprecated:: 3.24
 
-This variable is deprecated.  Use
-:variable:`CMAKE_CXX_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead.
+  Use the :variable:`CMAKE_CXX_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` variable
+  instead.
+
+  The ``CMAKE_COMPILER_IS_*`` variables were used in early CMake versions before
+  the introduction of :variable:`CMAKE_<LANG>_COMPILER_ID` variables in CMake
+  2.6.
+
+The ``CMAKE_COMPILER_IS_GNUCXX`` variable is set to boolean true if the C++
+(``CXX``) compiler is GNU.
+
+Examples
+^^^^^^^^
+
+In earlier versions of CMake, the ``CMAKE_COMPILER_IS_GNUCXX`` variable was used
+to check if the ``CXX`` compiler was GNU:
+
+.. code-block:: cmake
+
+  if(CMAKE_COMPILER_IS_GNUCXX)
+    # GNU C++ compiler-specific logic.
+  endif()
+
+Starting with CMake 2.6, the ``CMAKE_CXX_COMPILER_ID`` variable should be used
+instead:
+
+.. code-block:: cmake
+
+  if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+    # GNU C++ compiler-specific logic.
+  endif()
+
+When upgrading code, consider whether additional ``CXX`` compilers should be
+targeted beyond just ``GNU``.  In the past, the ``LCC`` and ``QCC`` compilers
+also had this variable set (see :policy:`CMP0047` and :policy:`CMP0129` policies
+for details). To account for this, the following approach can be used:
+
+.. code-block:: cmake
+
+  # Targeting GNU, LCC, and QCC compilers for CXX:
+  if(CMAKE_CXX_COMPILER_ID MATCHES "^(GNU|LCC|QCC)$")
+    # ...
+  endif()

Help/variable/CMAKE_COMPILER_IS_GNUG77.rst

@@ -1,7 +1,35 @@
 CMAKE_COMPILER_IS_GNUG77
 ------------------------
 
-True if the ``Fortran`` compiler is GNU.
+.. deprecated:: 3.24
 
-This variable is deprecated.  Use
-:variable:`CMAKE_Fortran_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>` instead.
+  Use the :variable:`CMAKE_Fortran_COMPILER_ID <CMAKE_<LANG>_COMPILER_ID>`
+  variable instead.
+
+  The ``CMAKE_COMPILER_IS_*`` variables were used in early CMake versions before
+  the introduction of :variable:`CMAKE_<LANG>_COMPILER_ID` variables in CMake
+  2.6.
+
+The ``CMAKE_COMPILER_IS_GNUG77`` variable is set to boolean true if the
+``Fortran`` compiler is GNU.
+
+Examples
+^^^^^^^^
+
+In earlier versions of CMake, the ``CMAKE_COMPILER_IS_GNUG77`` variable was used
+to check if the ``Fortran`` compiler was GNU:
+
+.. code-block:: cmake
+
+  if(CMAKE_COMPILER_IS_GNUG77)
+    # GNU Fortran compiler-specific logic.
+  endif()
+
+Starting with CMake 2.6, the ``CMAKE_Fortran_COMPILER_ID`` variable should be
+used instead:
+
+.. code-block:: cmake
+
+  if(CMAKE_Fortran_COMPILER_ID STREQUAL "GNU")
+    # GNU Fortran compiler-specific logic.
+  endif()