From 1d0b46111e56db20eb1a53ef259b259819c4ec0e Mon Sep 17 00:00:00 2001 From: Peter Kokot Date: Mon, 18 Aug 2025 11:52:56 +0200 Subject: Help: Add remaining intro code blocks to modules This is a follow-up to add intro code blocks to all remaining utility and find modules. Fixes: #26555 --- Modules/BundleUtilities.cmake | 2 +- Modules/CMakeAddFortranSubdirectory.cmake | 2 +- Modules/CMakeFindDependencyMacro.cmake | 20 ++++++++++++++++++++ Modules/CMakePackageConfigHelpers.cmake | 9 ++++++++- Modules/CMakePrintSystemInformation.cmake | 15 +++++++++++++-- Modules/CMakePushCheckState.cmake | 2 +- Modules/CPack.cmake | 8 +++++++- Modules/CPackComponent.cmake | 11 +++++++++-- Modules/CPackIFW.cmake | 6 ++++++ Modules/CPackIFWConfigureFile.cmake | 7 ++++++- Modules/CTestUseLaunchers.cmake | 6 ++++++ Modules/ExternalData.cmake | 9 ++++++++- Modules/ExternalProject.cmake | 9 +++++++++ Modules/FetchContent.cmake | 9 +++++++++ Modules/FindCUDAToolkit.cmake | 11 ++++++++--- Modules/FindDCMTK.cmake | 9 ++++++++- Modules/FindGTK.cmake | 12 ++++++++---- Modules/FindGTK2.cmake | 16 ++++++++++------ Modules/FindGit.cmake | 6 +++++- Modules/FindHSPELL.cmake | 6 +++++- Modules/FindIcotool.cmake | 6 +++++- Modules/FindImageMagick.cmake | 6 +++++- Modules/FindMatlab.cmake | 6 +++++- Modules/FindOpenAL.cmake | 6 +++++- Modules/FindOpenCL.cmake | 6 +++++- Modules/FindPackageHandleStandardArgs.cmake | 2 +- Modules/FindPackageMessage.cmake | 6 ++++-- Modules/FindPatch.cmake | 6 +++++- Modules/FindPike.cmake | 10 ++++++++-- Modules/FindProducer.cmake | 4 ++-- Modules/FindPython.cmake | 8 ++++++-- Modules/FindPython2.cmake | 8 ++++++-- Modules/FindPython3.cmake | 8 ++++++-- Modules/FindPythonInterp.cmake | 7 +++++-- Modules/FindPythonLibs.cmake | 10 +++++++--- Modules/FindQt.cmake | 11 ++++++++--- Modules/FindUnixCommands.cmake | 6 +++++- Modules/FindX11.cmake | 8 ++++++-- Modules/GenerateExportHeader.cmake | 2 +- Modules/GoogleTest.cmake | 13 ++++++++++--- Modules/InstallRequiredSystemLibraries.cmake | 14 +++++++++++--- Modules/SelectLibraryConfigurations.cmake | 10 ++++++---- Modules/UseEcos.cmake | 2 +- Modules/UseJava.cmake | 6 ++++++ Modules/UseSWIG.cmake | 12 +++++++++--- Modules/WriteCompilerDetectionHeader.cmake | 15 ++++++++++++++- 46 files changed, 300 insertions(+), 73 deletions(-) diff --git a/Modules/BundleUtilities.cmake b/Modules/BundleUtilities.cmake index 0c7fede..40821e0 100644 --- a/Modules/BundleUtilities.cmake +++ b/Modules/BundleUtilities.cmake @@ -9,7 +9,7 @@ This module provides utility commands for assembling standalone, bundle-style applications with CMake, such as macOS ``.app`` bundles or similar directory-based application bundles on other operating systems. -Load this module in CMake installation with: +Load this module in a CMake installation with: .. code-block:: cmake diff --git a/Modules/CMakeAddFortranSubdirectory.cmake b/Modules/CMakeAddFortranSubdirectory.cmake index 9b386b0..7eec1f2 100644 --- a/Modules/CMakeAddFortranSubdirectory.cmake +++ b/Modules/CMakeAddFortranSubdirectory.cmake @@ -8,7 +8,7 @@ CMakeAddFortranSubdirectory This module provides a command to add a Fortran project located in a subdirectory. -Load it in a CMake project with: +Load this module in a CMake project with: .. code-block:: cmake diff --git a/Modules/CMakeFindDependencyMacro.cmake b/Modules/CMakeFindDependencyMacro.cmake index cf2c250..fba1f63 100644 --- a/Modules/CMakeFindDependencyMacro.cmake +++ b/Modules/CMakeFindDependencyMacro.cmake @@ -5,6 +5,26 @@ CMakeFindDependencyMacro ------------------------ +This module provides a command implemented as a macro that finds dependency +for a package. + +Load this module in a CMake package configuration file with: + +.. code-block:: cmake + :caption: ``FooConfig.cmake`` or ``foo-config.cmake``: + + include(CMakeFindDependencyMacro) + +.. note:: + + This module is designed to be used in a :ref:`Package Configuration File + ` (``Config.cmake``). + +Commands +^^^^^^^^ + +This module provides the following command: + .. command:: find_dependency The ``find_dependency()`` macro wraps a :command:`find_package` call for diff --git a/Modules/CMakePackageConfigHelpers.cmake b/Modules/CMakePackageConfigHelpers.cmake index ba03080..c253296 100644 --- a/Modules/CMakePackageConfigHelpers.cmake +++ b/Modules/CMakePackageConfigHelpers.cmake @@ -5,9 +5,16 @@ CMakePackageConfigHelpers ------------------------- -Helper functions for creating config files that can be included by other +This module provides helper commands for creating :ref:`config files +` that can be included by other projects to find and use a package. +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CMakePackageConfigHelpers) + Generating a Package Configuration File ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Modules/CMakePrintSystemInformation.cmake b/Modules/CMakePrintSystemInformation.cmake index 4a539bc..da04af8 100644 --- a/Modules/CMakePrintSystemInformation.cmake +++ b/Modules/CMakePrintSystemInformation.cmake @@ -7,16 +7,27 @@ CMakePrintSystemInformation This module can be used for diagnostics to print system information. +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CMakePrintSystemInformation) + Examples ^^^^^^^^ -Including this module in a project: +For example, including this module in a project: .. code-block:: cmake + :caption: ``CMakeLists.txt`` + + project(Example) + + # ... include(CMakePrintSystemInformation) -prints various internal CMake variables. For example:: +prints various CMake variables:: CMAKE_SYSTEM is Linux-6.11.0-17-generic Linux 6.11.0-17-generic x86_64 CMAKE_SYSTEM file is Platform/Linux diff --git a/Modules/CMakePushCheckState.cmake b/Modules/CMakePushCheckState.cmake index cbf49de..30505cd 100644 --- a/Modules/CMakePushCheckState.cmake +++ b/Modules/CMakePushCheckState.cmake @@ -11,7 +11,7 @@ This module provides commands for managing the state of variables that influence how various CMake check commands (e.g., :command:`check_symbol_exists`, etc.) are performed. -Load this module in CMake project with: +Load this module in a CMake project with: .. code-block:: cmake diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake index 803332b..2da3216 100644 --- a/Modules/CPack.cmake +++ b/Modules/CPack.cmake @@ -5,7 +5,13 @@ CPack ----- -Configure generators for binary installers and source packages. +This module configures generators for binary installers and source packages. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CPack) Introduction ^^^^^^^^^^^^ diff --git a/Modules/CPackComponent.cmake b/Modules/CPackComponent.cmake index 3197fc3..96d6bde 100644 --- a/Modules/CPackComponent.cmake +++ b/Modules/CPackComponent.cmake @@ -5,7 +5,14 @@ CPackComponent -------------- -Configure components for binary installers and source packages. +This module provides commands to configure components for binary installers +and source packages. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CPackComponent) .. only:: html @@ -14,7 +21,7 @@ Configure components for binary installers and source packages. Introduction ^^^^^^^^^^^^ -This module is automatically included by :module:`CPack`. +This module is also automatically included by :module:`CPack`. Certain binary installers (especially the graphical installers) generated by CPack allow users to select individual application *components* to install. diff --git a/Modules/CPackIFW.cmake b/Modules/CPackIFW.cmake index 2a2f478..b114430 100644 --- a/Modules/CPackIFW.cmake +++ b/Modules/CPackIFW.cmake @@ -11,6 +11,12 @@ This module looks for the location of the command-line utilities supplied with t `Qt Installer Framework `_ (QtIFW). +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CPackIFW) + The module also defines several commands to control the behavior of the :cpack_gen:`CPack IFW Generator`. diff --git a/Modules/CPackIFWConfigureFile.cmake b/Modules/CPackIFWConfigureFile.cmake index 6759c9c..f8ddd51 100644 --- a/Modules/CPackIFWConfigureFile.cmake +++ b/Modules/CPackIFWConfigureFile.cmake @@ -7,9 +7,14 @@ CPackIFWConfigureFile .. versionadded:: 3.8 -The module defines :command:`configure_file` similar command to +This module defines :command:`configure_file` similar command to configure file templates prepared in QtIFW/SDK/Creator style. +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CPackIFWConfigureFile) Commands ^^^^^^^^ diff --git a/Modules/CTestUseLaunchers.cmake b/Modules/CTestUseLaunchers.cmake index c26c840..05f8624 100644 --- a/Modules/CTestUseLaunchers.cmake +++ b/Modules/CTestUseLaunchers.cmake @@ -13,6 +13,12 @@ This module sets the ``RULE_LAUNCH_*`` global properties when the * :prop_gbl:`RULE_LAUNCH_CUSTOM` * :prop_gbl:`RULE_LAUNCH_LINK` +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CTestUseLaunchers) + The ``CTestUseLaunchers`` module is automatically included by the :module:`CTest` module when ``include(CTest)`` is called. However, it is provided as a separate module so that projects can use the diff --git a/Modules/ExternalData.cmake b/Modules/ExternalData.cmake index 5d28929..9f3eacc 100644 --- a/Modules/ExternalData.cmake +++ b/Modules/ExternalData.cmake @@ -9,7 +9,14 @@ ExternalData .. contents:: -Manage data files stored outside source tree +This module provides commands to manage data files stored outside source +tree. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(ExternalData) Introduction ^^^^^^^^^^^^ diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake index b314bcc..3bf26f8 100644 --- a/Modules/ExternalProject.cmake +++ b/Modules/ExternalProject.cmake @@ -11,6 +11,15 @@ ExternalProject .. contents:: +This module provides commands to download and build external projects as +part of CMake build phase. + +Load this module in CMake with: + +.. code-block:: cmake + + include(ExternalProject) + External Project Definition ^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Modules/FetchContent.cmake b/Modules/FetchContent.cmake index 2088549..70680de 100644 --- a/Modules/FetchContent.cmake +++ b/Modules/FetchContent.cmake @@ -11,6 +11,15 @@ FetchContent .. contents:: +This module provides commands to populate content at configure time or as +part of the calling script. + +Load this module in CMake with: + +.. code-block:: cmake + + include(FetchContent) + .. note:: The :guide:`Using Dependencies Guide` provides a high-level introduction to this general topic. It provides a broader overview of where the ``FetchContent`` module fits into the bigger picture, diff --git a/Modules/FindCUDAToolkit.cmake b/Modules/FindCUDAToolkit.cmake index f560c51..de0fa5f 100644 --- a/Modules/FindCUDAToolkit.cmake +++ b/Modules/FindCUDAToolkit.cmake @@ -7,9 +7,14 @@ FindCUDAToolkit .. versionadded:: 3.17 -This script locates the NVIDIA CUDA toolkit and the associated libraries, but -does not require the ``CUDA`` language be enabled for a given project. This -module does not search for the NVIDIA CUDA Samples. +Finds the NVIDIA CUDA toolkit and the associated libraries, but does not +require the ``CUDA`` language be enabled for a given project: + +.. code-block:: cmake + + find_package(CUDAToolkit [] [QUIET] [REQUIRED] [EXACT] [...]) + +This module does not search for the NVIDIA CUDA Samples. .. versionadded:: 3.19 QNX support. diff --git a/Modules/FindDCMTK.cmake b/Modules/FindDCMTK.cmake index 4e0ff47..17515d1 100644 --- a/Modules/FindDCMTK.cmake +++ b/Modules/FindDCMTK.cmake @@ -5,7 +5,14 @@ FindDCMTK --------- -Find DICOM ToolKit (DCMTK) libraries and applications +Finds the DICOM ToolKit (DCMTK) libraries and applications: + +.. code-block:: cmake + + find_package(DCMTK [...]) + +DCMTK is a set of libraries and applications implementing large parts of +the DICOM Standard (Digital Imaging and Communications in Medicine). The module defines the following variables:: diff --git a/Modules/FindGTK.cmake b/Modules/FindGTK.cmake index 6e39f5a..c46af4f 100644 --- a/Modules/FindGTK.cmake +++ b/Modules/FindGTK.cmake @@ -5,10 +5,6 @@ FindGTK ------- -Finds GTK, glib and GTKGLArea. - -GTK is a multi-platform toolkit for creating graphical user interfaces. - .. note:: This module works only on Unix-like systems and was intended for early GTK @@ -22,6 +18,14 @@ GTK is a multi-platform toolkit for creating graphical user interfaces. pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk4>=4.14) target_link_libraries(example PRIVATE PkgConfig::GTK) +Finds GTK, glib and GTKGLArea: + +.. code-block:: cmake + + find_package(GTK [...]) + +GTK is a multi-platform toolkit for creating graphical user interfaces. + Result Variables ^^^^^^^^^^^^^^^^ diff --git a/Modules/FindGTK2.cmake b/Modules/FindGTK2.cmake index 9c5bc63..27afe02 100644 --- a/Modules/FindGTK2.cmake +++ b/Modules/FindGTK2.cmake @@ -5,14 +5,10 @@ FindGTK2 -------- -Finds the GTK widget libraries and several of its other optional components. - -GTK is a multi-platform toolkit for creating graphical user interfaces. - .. note:: - This module is specifically for GTK version 2.x, which is obsolete and no - longer maintained. Use the latest supported GTK version and + This module is intended specifically for GTK version 2.x, which is obsolete + and no longer maintained. Use the latest supported GTK version and :module:`FindPkgConfig` module to find GTK in CMake instead of this module. For example: @@ -22,6 +18,14 @@ GTK is a multi-platform toolkit for creating graphical user interfaces. pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk4>=4.14) target_link_libraries(example PRIVATE PkgConfig::GTK) +Finds the GTK widget libraries and several of its other optional components: + +.. code-block:: cmake + + find_package(GTK2 [] [COMPONENTS ...] [...]) + +GTK is a multi-platform toolkit for creating graphical user interfaces. + Components ^^^^^^^^^^ diff --git a/Modules/FindGit.cmake b/Modules/FindGit.cmake index 2b6187e..a2d94d8 100644 --- a/Modules/FindGit.cmake +++ b/Modules/FindGit.cmake @@ -5,7 +5,11 @@ FindGit ------- -Finds the Git distributed version control system. +Finds the Git distributed version control system: + +.. code-block:: cmake + + find_package(Git [] [...]) Imported Targets ^^^^^^^^^^^^^^^^ diff --git a/Modules/FindHSPELL.cmake b/Modules/FindHSPELL.cmake index f326f33..f23acc5 100644 --- a/Modules/FindHSPELL.cmake +++ b/Modules/FindHSPELL.cmake @@ -5,7 +5,11 @@ FindHSPELL ---------- -Finds Hebrew spell-checker (Hspell) and morphology engine. +Finds the Hebrew spell-checker and morphology engine (Hspell): + +.. code-block:: cmake + + find_package(HSPELL [] [...]) Result Variables ^^^^^^^^^^^^^^^^ diff --git a/Modules/FindIcotool.cmake b/Modules/FindIcotool.cmake index 92dfe7f..1009c75 100644 --- a/Modules/FindIcotool.cmake +++ b/Modules/FindIcotool.cmake @@ -6,7 +6,11 @@ FindIcotool ----------- Finds ``icotool``, command-line program for converting and creating Win32 icon -and cursor files. +and cursor files: + +.. code-block:: cmake + + find_package(Icotool [] [...]) Result Variables ^^^^^^^^^^^^^^^^ diff --git a/Modules/FindImageMagick.cmake b/Modules/FindImageMagick.cmake index 8289d6d..bf01c9f 100644 --- a/Modules/FindImageMagick.cmake +++ b/Modules/FindImageMagick.cmake @@ -6,7 +6,11 @@ FindImageMagick --------------- Finds ImageMagick, a software suite for displaying, converting, and manipulating -raster images. +raster images: + +.. code-block:: cmake + + find_package(ImageMagick [] [COMPONENTS ...] [...]) .. versionadded:: 3.9 Support for ImageMagick 7. diff --git a/Modules/FindMatlab.cmake b/Modules/FindMatlab.cmake index 8a7bd80..487ba40 100644 --- a/Modules/FindMatlab.cmake +++ b/Modules/FindMatlab.cmake @@ -6,7 +6,11 @@ FindMatlab ---------- Finds Matlab or Matlab Compiler Runtime (MCR) and provides Matlab tools, -libraries and compilers to CMake. +libraries and compilers to CMake: + +.. code-block:: cmake + + find_package(Matlab [] [COMPONENTS ...] [...]) This package primary purpose is to find the libraries associated with Matlab or the MCR in order to be able to build Matlab extensions (mex files). It diff --git a/Modules/FindOpenAL.cmake b/Modules/FindOpenAL.cmake index dad9ada..fa4c8bf 100644 --- a/Modules/FindOpenAL.cmake +++ b/Modules/FindOpenAL.cmake @@ -5,7 +5,11 @@ FindOpenAL ---------- -Finds the Open Audio Library (OpenAL). +Finds the Open Audio Library (OpenAL): + +.. code-block:: cmake + + find_package(OpenAL [] [...]) OpenAL is a cross-platform 3D audio API designed for efficient rendering of multichannel three-dimensional positional audio. It is commonly used in games diff --git a/Modules/FindOpenCL.cmake b/Modules/FindOpenCL.cmake index 3be945b..ccf78e9 100644 --- a/Modules/FindOpenCL.cmake +++ b/Modules/FindOpenCL.cmake @@ -7,7 +7,11 @@ FindOpenCL .. versionadded:: 3.1 -Finds Open Computing Language (OpenCL). +Finds Open Computing Language (OpenCL): + +.. code-block:: cmake + + find_package(OpenCL [] [...]) .. versionadded:: 3.10 Detection of OpenCL 2.1 and 2.2. diff --git a/Modules/FindPackageHandleStandardArgs.cmake b/Modules/FindPackageHandleStandardArgs.cmake index b4c7291..70c634b 100644 --- a/Modules/FindPackageHandleStandardArgs.cmake +++ b/Modules/FindPackageHandleStandardArgs.cmake @@ -5,7 +5,7 @@ FindPackageHandleStandardArgs ----------------------------- -This module provides commands intended to be used in :ref:`Find Modules` +This module provides commands intended for use in :ref:`Find Modules` implementing :command:`find_package()` calls. Load this module in a CMake find module with: diff --git a/Modules/FindPackageMessage.cmake b/Modules/FindPackageMessage.cmake index 29db756..859b0b6 100644 --- a/Modules/FindPackageMessage.cmake +++ b/Modules/FindPackageMessage.cmake @@ -6,11 +6,13 @@ FindPackageMessage ------------------ This module provides a command for printing find result messages and is -intended for use in :ref:`Find Modules`. +intended for use in :ref:`Find Modules` implementing +:command:`find_package()` calls. -Load it in a CMake find module with: +Load this module in a CMake find module with: .. code-block:: cmake + :caption: ``FindFoo.cmake`` include(FindPackageMessage) diff --git a/Modules/FindPatch.cmake b/Modules/FindPatch.cmake index c6ca07b..6309901 100644 --- a/Modules/FindPatch.cmake +++ b/Modules/FindPatch.cmake @@ -8,7 +8,11 @@ FindPatch .. versionadded:: 3.10 Finds the ``patch`` command-line executable for applying diff patches to -original files. +original files: + +.. code-block:: cmake + + find_package(Patch [...]) Imported Targets ^^^^^^^^^^^^^^^^ diff --git a/Modules/FindPike.cmake b/Modules/FindPike.cmake index 457e82a..2750bc5 100644 --- a/Modules/FindPike.cmake +++ b/Modules/FindPike.cmake @@ -5,8 +5,14 @@ FindPike -------- -Finds the Pike compiler and interpreter. Pike is interpreted, general purpose, -high-level, dynamic programming language. +Finds the Pike compiler and interpreter: + +.. code-block:: cmake + + find_package(Pike [...]) + +Pike is interpreted, general purpose, high-level, dynamic programming +language. Cache Variables ^^^^^^^^^^^^^^^ diff --git a/Modules/FindProducer.cmake b/Modules/FindProducer.cmake index 1769cdd..1400c2a 100644 --- a/Modules/FindProducer.cmake +++ b/Modules/FindProducer.cmake @@ -14,8 +14,8 @@ FindProducer library became obsolete and is no longer maintained. For details about OpenSceneGraph usage, refer to the :module:`FindOpenSceneGraph` module. -This module finds the Producer library, a windowing and event handling library -designed primarily for real-time graphics applications: +Finds the Producer library, a windowing and event handling library designed +primarily for real-time graphics applications: .. code-block:: cmake diff --git a/Modules/FindPython.cmake b/Modules/FindPython.cmake index 8a739af..48744f2 100644 --- a/Modules/FindPython.cmake +++ b/Modules/FindPython.cmake @@ -7,8 +7,12 @@ FindPython .. versionadded:: 3.12 -Find Python interpreter, compiler and development environment (include -directories and libraries). +Finds Python interpreter, compiler and development environment (include +directories and libraries): + +.. code-block:: cmake + + find_package(Python [] [COMPONENTS ...] [...]) .. versionadded:: 3.19 When a version is requested, it can be specified as a simple value or as a diff --git a/Modules/FindPython2.cmake b/Modules/FindPython2.cmake index 535f0be..9e86894 100644 --- a/Modules/FindPython2.cmake +++ b/Modules/FindPython2.cmake @@ -7,8 +7,12 @@ FindPython2 .. versionadded:: 3.12 -Find Python 2 interpreter, compiler and development environment (include -directories and libraries). +Finds Python 2 interpreter, compiler and development environment (include +directories and libraries): + +.. code-block:: cmake + + find_package(Python2 [] [COMPONENTS ...] [...]) .. versionadded:: 3.19 When a version is requested, it can be specified as a simple value or as a diff --git a/Modules/FindPython3.cmake b/Modules/FindPython3.cmake index 84f2d42..66c9d41 100644 --- a/Modules/FindPython3.cmake +++ b/Modules/FindPython3.cmake @@ -7,8 +7,12 @@ FindPython3 .. versionadded:: 3.12 -Find Python 3 interpreter, compiler and development environment (include -directories and libraries). +Finds Python 3 interpreter, compiler and development environment (include +directories and libraries): + +.. code-block:: cmake + + find_package(Python3 [] [COMPONENTS ...] [...]) .. versionadded:: 3.19 When a version is requested, it can be specified as a simple value or as a diff --git a/Modules/FindPythonInterp.cmake b/Modules/FindPythonInterp.cmake index 490d79f..b924ca6 100644 --- a/Modules/FindPythonInterp.cmake +++ b/Modules/FindPythonInterp.cmake @@ -13,8 +13,11 @@ FindPythonInterp Use :module:`FindPython3`, :module:`FindPython2`, or :module:`FindPython` instead. -This module finds the Python interpreter and determines the location of its -executable. +Finds the Python interpreter and determines the location of its executable: + +.. code-block:: cmake + + find_package(PythonInterp [] [...]) .. note:: diff --git a/Modules/FindPythonLibs.cmake b/Modules/FindPythonLibs.cmake index 4a0c1db..00581e1 100644 --- a/Modules/FindPythonLibs.cmake +++ b/Modules/FindPythonLibs.cmake @@ -13,9 +13,13 @@ FindPythonLibs Use :module:`FindPython3`, :module:`FindPython2`, or :module:`FindPython` instead. -This module finds the Python installation and determines the location of its -include directories and libraries, as well as the name of the Python library to -link against. +Finds the Python installation and determines the location of its include +directories and libraries, as well as the name of the Python library to +link against: + +.. code-block:: cmake + + find_package(PythonLibs [] [...]) .. note:: diff --git a/Modules/FindQt.cmake b/Modules/FindQt.cmake index efe5349..0d0d491 100644 --- a/Modules/FindQt.cmake +++ b/Modules/FindQt.cmake @@ -11,9 +11,14 @@ FindQt ``NEW``. It supports only Qt3 and Qt4. For Qt5 or later versions see :manual:`cmake-qt(7)`. -This module finds an installed version of Qt3 or Qt4. Qt is a cross-platform -application development framework for creating graphical user interfaces and -applications. +Finds an installed version of Qt3 or Qt4: + +.. code-block:: cmake + + find_package(Qt [...]) + +Qt is a cross-platform application development framework for creating +graphical user interfaces and applications. Use this module only if the project can work with both Qt3 and Qt4 versions. If a specific version is required, use :module:`FindQt4` or diff --git a/Modules/FindUnixCommands.cmake b/Modules/FindUnixCommands.cmake index 12f1169..40ae8b9 100644 --- a/Modules/FindUnixCommands.cmake +++ b/Modules/FindUnixCommands.cmake @@ -9,7 +9,11 @@ FindUnixCommands Use :option:`${CMAKE_COMMAND} -E ` subcommands instead. -Find Unix commands, including the ones from Cygwin +Finds Unix commands, including the ones from Cygwin: + +.. code-block:: cmake + + find_package(UnixCommands [...]) This module looks for the Unix commands ``bash``, ``cp``, ``gzip``, ``mv``, ``rm``, and ``tar`` and stores the result in the variables diff --git a/Modules/FindX11.cmake b/Modules/FindX11.cmake index b2f23bd..cc80f8b 100644 --- a/Modules/FindX11.cmake +++ b/Modules/FindX11.cmake @@ -5,9 +5,13 @@ FindX11 ------- -Find X11 installation +Finds the X11 installation on Unix-like systems: -Try to find X11 on UNIX systems. The following values are defined +.. code-block:: cmake + + find_package(X11 [COMPONENTS ...] [...]) + +The following values are defined :: diff --git a/Modules/GenerateExportHeader.cmake b/Modules/GenerateExportHeader.cmake index 5467651..52bbe80 100644 --- a/Modules/GenerateExportHeader.cmake +++ b/Modules/GenerateExportHeader.cmake @@ -8,7 +8,7 @@ GenerateExportHeader This module provides commands for generating a header file containing preprocessor macro definitions to control C/C++ symbol visibility. -Load this module in CMake project with: +Load this module in a CMake project with: .. code-block:: cmake diff --git a/Modules/GoogleTest.cmake b/Modules/GoogleTest.cmake index ebf0ba0..bf4c501 100644 --- a/Modules/GoogleTest.cmake +++ b/Modules/GoogleTest.cmake @@ -7,9 +7,16 @@ GoogleTest .. versionadded:: 3.9 -This module defines functions to help use the Google Test infrastructure. Two -mechanisms for adding tests are provided. :command:`gtest_add_tests` has been -around for some time, originally via ``find_package(GTest)``. +This module provides commands to help use the Google Test infrastructure. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(GoogleTest) + +Two mechanisms for adding tests are provided. :command:`gtest_add_tests` has +been around for some time, originally via ``find_package(GTest)``. :command:`gtest_discover_tests` was introduced in CMake 3.10. The (older) :command:`gtest_add_tests` scans source files to identify tests. diff --git a/Modules/InstallRequiredSystemLibraries.cmake b/Modules/InstallRequiredSystemLibraries.cmake index 4d7aff3..ad54a9e 100644 --- a/Modules/InstallRequiredSystemLibraries.cmake +++ b/Modules/InstallRequiredSystemLibraries.cmake @@ -5,9 +5,17 @@ InstallRequiredSystemLibraries ------------------------------ -Include this module to search for compiler-provided system runtime -libraries and add install rules for them. Some optional variables -may be set prior to including the module to adjust behavior: +This module searches for compiler-provided system runtime libraries and adds +installation rules for them. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(InstallRequiredSystemLibraries) + +Some optional variables may be set prior to including this module to adjust +behavior: ``CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS`` Specify additional runtime libraries that may not be detected. diff --git a/Modules/SelectLibraryConfigurations.cmake b/Modules/SelectLibraryConfigurations.cmake index e26c908..5fde66e 100644 --- a/Modules/SelectLibraryConfigurations.cmake +++ b/Modules/SelectLibraryConfigurations.cmake @@ -5,13 +5,15 @@ SelectLibraryConfigurations --------------------------- -This module is intended for use in :ref:`Find Modules` and provides a -command to automatically set library variables when package is available -with multiple :ref:`Build Configurations`. +This module provides a command to automatically set library variables when +package is available with multiple :ref:`Build Configurations`. It is +intended for use in :ref:`Find Modules` implementing +:command:`find_package()` calls. -Load it in a CMake find module with: +Load this module in a CMake find module with: .. code-block:: cmake + :caption: ``FindFoo.cmake`` include(SelectLibraryConfigurations) diff --git a/Modules/UseEcos.cmake b/Modules/UseEcos.cmake index 9c8811b..9deb8d6 100644 --- a/Modules/UseEcos.cmake +++ b/Modules/UseEcos.cmake @@ -8,7 +8,7 @@ UseEcos This module defines variables and provides commands required to build an eCos application. -Load this module in CMake project with: +Load this module in a CMake project with: .. code-block:: cmake diff --git a/Modules/UseJava.cmake b/Modules/UseJava.cmake index b977d95..c7498e3 100644 --- a/Modules/UseJava.cmake +++ b/Modules/UseJava.cmake @@ -9,6 +9,12 @@ This file provides support for ``Java``. It is assumed that :module:`FindJava` has already been loaded. See :module:`FindJava` for information on how to load Java into your CMake project. +Load this module in a CMake project with: + +.. code-block:: cmake + + include(UseJava) + Synopsis ^^^^^^^^ diff --git a/Modules/UseSWIG.cmake b/Modules/UseSWIG.cmake index cc023ee..83ec53b 100644 --- a/Modules/UseSWIG.cmake +++ b/Modules/UseSWIG.cmake @@ -5,13 +5,19 @@ UseSWIG ------- -This file provides support for ``SWIG``. It is assumed that :module:`FindSWIG` -module has already been loaded. - .. only:: html .. contents:: +This module provides support for ``SWIG``. It is assumed that :module:`FindSWIG` +module has already been loaded. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(UseSWIG) + CMake Commands ^^^^^^^^^^^^^^ diff --git a/Modules/WriteCompilerDetectionHeader.cmake b/Modules/WriteCompilerDetectionHeader.cmake index 954875e..10a3c52 100644 --- a/Modules/WriteCompilerDetectionHeader.cmake +++ b/Modules/WriteCompilerDetectionHeader.cmake @@ -11,7 +11,20 @@ WriteCompilerDetectionHeader .. versionadded:: 3.1 -This module provides the function ``write_compiler_detection_header()``. +This module provides a command to generate header with preprocessor macros. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(WriteCompilerDetectionHeader) + +Commands +^^^^^^^^ + +This module provides the following command: + +.. command:: write_compiler_detection_header This function can be used to generate a file suitable for preprocessor inclusion which contains macros to be used in source code: -- cgit v0.12