CMakeBackwardCompatibilityCXX: Add intro code blocks

This is mainly a sync with other CMake modules for consistency: - Added intro code blocks showing how to include the modules. - Adjusted examples sections. - Added "See Also" sections.
2025-10-14 02:08:27 +08:00 · 2025-05-18 18:38:27 +02:00
parent e33692e625
commit 26dd965037
5 changed files with 103 additions and 12 deletions
--- a/Modules/CMakeBackwardCompatibilityCXX.cmake
+++ b/Modules/CMakeBackwardCompatibilityCXX.cmake
@@ -8,6 +8,12 @@ CMakeBackwardCompatibilityCXX
 This module defines several backward compatibility cache variables for the
 ``CXX`` language to support early C++ (pre-C++98, ANSI C++).

+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CMakeBackwardCompatibilityCXX)
+
 The following modules are included by this module:

 * :module:`TestForANSIForScope`
@@ -30,11 +36,23 @@ Additionally, the following cache variable may be defined:
 Examples
 ^^^^^^^^

-Including this module provides backward compatibility cache variables:
+Including this module provides backward compatibility cache variables, which
+can be used in C++.  For example:

 .. code-block:: cmake
+  :caption: ``CMakeLists.txt``

  include(CMakeBackwardCompatibilityCXX)
+  file(
+    CONFIGURE
+    OUTPUT config.h
+    CONTENT [[
+      #cmakedefine CMAKE_NO_ANSI_FOR_SCOPE
+      #cmakedefine CMAKE_NO_ANSI_STRING_STREAM
+      #cmakedefine CMAKE_NO_ANSI_STREAM_HEADERS
+      #cmakedefine CMAKE_NO_STD_NAMESPACE
+    ]]
+  )
 #]=======================================================================]

 if(NOT CMAKE_SKIP_COMPATIBILITY_TESTS)
--- a/Modules/TestForANSIForScope.cmake
+++ b/Modules/TestForANSIForScope.cmake
@@ -6,9 +6,16 @@ TestForANSIForScope
 -------------------

 This module checks whether the ``CXX`` compiler restricts the scope of variables
-declared in a for-init-statement to the loop body.  In early C++ (pre-C++98),
-variables declared in ``for(<init-statement> ...)`` could remain accessible
-outside the loop after its body (``for() { <body> }``).
+declared in a for-init-statement to the loop body.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(TestForANSIForScope)
+
+In early C++ (pre-C++98), variables declared in ``for(<init-statement> ...)``
+could remain accessible outside the loop after its body (``for() { <body> }``).

 This module defines the following cache variable:

@@ -29,8 +36,30 @@ Including this module will check the ``for()`` loop scope behavior and define
 the ``CMAKE_NO_ANSI_FOR_SCOPE`` cache variable:

 .. code-block:: cmake
+  :caption: ``CMakeLists.txt``

  include(TestForANSIForScope)
+  file(
+    CONFIGURE
+    OUTPUT config.h
+    CONTENT "#cmakedefine CMAKE_NO_ANSI_FOR_SCOPE"
+  )
+
+which can be then used in a C++ program:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include "config.h"
+
+  #ifdef CMAKE_NO_ANSI_FOR_SCOPE
+  #  define for if(false) {} else for
+  #endif
+
+See Also
+^^^^^^^^
+
+* The :module:`CMakeBackwardCompatibilityCXX` module.
 #]=======================================================================]

 if(NOT DEFINED CMAKE_ANSI_FOR_SCOPE)
--- a/Modules/TestForANSIStreamHeaders.cmake
+++ b/Modules/TestForANSIStreamHeaders.cmake
@@ -6,9 +6,16 @@ TestForANSIStreamHeaders
 ------------------------

 This module checks whether the ``CXX`` compiler supports standard library
-headers without the ``.h`` extension (e.g. ``<iostream>``).  Early
-versions of C++ (pre-C++98) didn't support including standard headers without
-extensions.
+headers without the ``.h`` extension (e.g. ``<iostream>``).
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(TestForANSIStreamHeaders)
+
+Early versions of C++ (pre-C++98) didn't support including standard headers
+without extensions.

 This module defines the following cache variable:

@@ -30,6 +37,7 @@ Including this module will check how the C++ standard headers can be included
 and define the ``CMAKE_NO_ANSI_STREAM_HEADERS`` cache variable:

 .. code-block:: cmake
+  :caption: ``CMakeLists.txt``

  include(TestForANSIStreamHeaders)
  file(
@@ -41,6 +49,7 @@ and define the ``CMAKE_NO_ANSI_STREAM_HEADERS`` cache variable:
 C++ program can then include the available header conditionally:

 .. code-block:: c++
+  :caption: ``example.cxx``

  #include "config.h"

@@ -51,6 +60,11 @@ C++ program can then include the available header conditionally:
  #endif

  int main() { ... }
+
+See Also
+^^^^^^^^
+
+* The :module:`CMakeBackwardCompatibilityCXX` module.
 #]=======================================================================]

 include(${CMAKE_CURRENT_LIST_DIR}/CheckIncludeFileCXX.cmake)
--- a/Modules/TestForSSTREAM.cmake
+++ b/Modules/TestForSSTREAM.cmake
@@ -6,7 +6,15 @@ TestForSSTREAM
 --------------

 This module checks whether the C++ standard header ``<sstream>`` exists and
-functions correctly.  In early versions of C++ (pre-C++98), this header was not
+functions correctly.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(TestForSSTREAM)
+
+In early versions of C++ (pre-C++98), the ``<sstream>`` header was not
 formally standardized and may not have been available.

 This module defines the following cache variables:
@@ -32,6 +40,7 @@ Including this module will check for ``<sstream>`` support and define the
 ``CMAKE_NO_ANSI_STRING_STREAM`` cache variable:

 .. code-block:: cmake
+  :caption: ``CMakeLists.txt``

  include(TestForSSTREAM)
  file(
@@ -43,6 +52,7 @@ Including this module will check for ``<sstream>`` support and define the
 Then it can be used in a C++ program:

 .. code-block:: c++
+  :caption: ``example.cxx``

  #include "config.h"

@@ -51,6 +61,11 @@ Then it can be used in a C++ program:
  #endif

  int main() { ... }
+
+See Also
+^^^^^^^^
+
+* The :module:`CMakeBackwardCompatibilityCXX` module.
 #]=======================================================================]

 if(NOT DEFINED CMAKE_HAS_ANSI_STRING_STREAM)
--- a/Modules/TestForSTDNamespace.cmake
+++ b/Modules/TestForSTDNamespace.cmake
@@ -6,10 +6,18 @@ TestForSTDNamespace
 -------------------

 This module checks whether the ``CXX`` compiler supports the ``std`` namespace
-for the C++ Standard Library.  Early versions of C++ (pre-C++98) did not have a
-requirement for a dedicated namespace of C++ Standard Template Library (STL)
-components (e.g. ``list``, etc.) and other parts of the C++ Standard Library
-(such as I/O streams ``cout``, ``endl``, etc), so they were available globally.
+for the C++ Standard Library.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(TestForSTDNamespace)
+
+Early versions of C++ (pre-C++98) did not have a requirement for a dedicated
+namespace of C++ Standard Template Library (STL) components (e.g. ``list``,
+etc.) and other parts of the C++ Standard Library (such as I/O streams
+``cout``, ``endl``, etc), so they were available globally.

 This module defines the following cache variable:

@@ -30,6 +38,7 @@ Including this module will check for the ``std`` namespace support and define
 the ``CMAKE_NO_STD_NAMESPACE`` cache variable:

 .. code-block:: cmake
+  :caption: ``CMakeLists.txt``

  include(TestForSTDNamespace)
  file(
@@ -41,12 +50,18 @@ the ``CMAKE_NO_STD_NAMESPACE`` cache variable:
 which can be then used in a C++ program to define the missing namespace:

 .. code-block:: c++
+  :caption: ``example.cxx``

  #include "config.h"

  #ifdef CMAKE_NO_STD_NAMESPACE
  #  define std
  #endif
+
+See Also
+^^^^^^^^
+
+* The :module:`CMakeBackwardCompatibilityCXX` module.
 #]=======================================================================]

 if(NOT DEFINED CMAKE_STD_NAMESPACE)