diff --git a/Modules/FindASPELL.cmake b/Modules/FindASPELL.cmake index 2c5cb93e36..3d712d659f 100644 --- a/Modules/FindASPELL.cmake +++ b/Modules/FindASPELL.cmake @@ -5,12 +5,23 @@ FindASPELL ---------- -Finds the GNU Aspell spell checker library. +Finds the GNU Aspell spell checker library: + +.. code-block:: cmake + + find_package(ASPELL [] [COMPONENTS ] [...]) Components ^^^^^^^^^^ -This module supports the following components: +This module supports optional components which can be specified using the +:command:`find_package` command: + +.. code-block:: cmake + + find_package(ASPELL [COMPONENTS ...]) + +Supported components include: ``ASPELL`` .. versionadded:: 4.1 @@ -22,13 +33,7 @@ This module supports the following components: Finds the Aspell command-line interactive spell checker executable. -Components can be specified using the standard CMake syntax: - -.. code-block:: cmake - - find_package(ASPELL [COMPONENTS ...]) - -If no ``COMPONENTS`` are specified, the module searches for both the ``ASPELL`` +If no components are specified, the module searches for both the ``ASPELL`` and ``Executable`` components by default. Imported Targets diff --git a/Modules/FindBISON.cmake b/Modules/FindBISON.cmake index ef76f6a51c..6acebc8716 100644 --- a/Modules/FindBISON.cmake +++ b/Modules/FindBISON.cmake @@ -10,7 +10,7 @@ generate custom build rules for using Bison: .. code-block:: cmake - find_package(BISON [] ...) + find_package(BISON [] [...]) Bison is a parser generator that replaced earlier Yacc (Yet Another Compiler-Compiler). On Unix-like systems, most common implementation is diff --git a/Modules/FindBacktrace.cmake b/Modules/FindBacktrace.cmake index ceea3194ff..052e6b585b 100644 --- a/Modules/FindBacktrace.cmake +++ b/Modules/FindBacktrace.cmake @@ -62,7 +62,7 @@ Examples Finding Backtrace and linking it to a project target as of CMake 3.30: .. code-block:: cmake - :caption: CMakeLists.txt + :caption: ``CMakeLists.txt`` find_package(Backtrace) target_link_libraries(app PRIVATE Backtrace::Backtrace) @@ -71,7 +71,7 @@ The ``Backtrace_HEADER`` variable can be used, for example, in a configuration header file created by :command:`configure_file`: .. code-block:: cmake - :caption: CMakeLists.txt + :caption: ``CMakeLists.txt`` add_library(app app.c) @@ -81,7 +81,7 @@ header file created by :command:`configure_file`: configure_file(config.h.in config.h) .. code-block:: c - :caption: config.h.in + :caption: ``config.h.in`` #cmakedefine01 Backtrace_FOUND #if Backtrace_FOUND @@ -89,7 +89,7 @@ header file created by :command:`configure_file`: #endif .. code-block:: c - :caption: app.c + :caption: ``app.c`` #include "config.h" @@ -97,7 +97,7 @@ If the project needs to support CMake 3.29 or earlier, the imported target can be defined manually: .. code-block:: cmake - :caption: CMakeLists.txt + :caption: ``CMakeLists.txt`` find_package(Backtrace) if(Backtrace_FOUND AND NOT TARGET Backtrace::Backtrace) diff --git a/Modules/FindBoost.cmake b/Modules/FindBoost.cmake index 8ae4223834..78df671df0 100644 --- a/Modules/FindBoost.cmake +++ b/Modules/FindBoost.cmake @@ -47,7 +47,7 @@ Result Variables This module defines the following variables: ``Boost_FOUND`` - True if headers and requested libraries were found. + Boolean indicating whether headers and requested libraries were found. ``Boost_INCLUDE_DIRS`` Boost include directories. @@ -59,7 +59,8 @@ This module defines the following variables: Boost component libraries to be linked. ``Boost__FOUND`` - True if component ```` was found (```` name is upper-case). + Boolean indicating whether the component ```` was found + (```` name is upper-case). ``Boost__LIBRARY`` Libraries to link for component ```` (may include @@ -102,7 +103,7 @@ This module defines the following variables: .. versionadded:: 3.15 The ``Boost_VERSION_`` variables. -Cache variables +Cache Variables ^^^^^^^^^^^^^^^ Search results are saved persistently in CMake cache entries: @@ -172,7 +173,7 @@ Imported Targets .. versionadded:: 3.5 -This module defines the following :prop_tgt:`IMPORTED` targets: +This module provides the following :ref:`Imported Targets`: ``Boost::boost`` Target for header-only dependencies. (Boost include directory). diff --git a/Modules/FindBullet.cmake b/Modules/FindBullet.cmake index 61a5fb31a7..7ae571f2e0 100644 --- a/Modules/FindBullet.cmake +++ b/Modules/FindBullet.cmake @@ -5,7 +5,11 @@ FindBullet ---------- -Finds the Bullet physics engine. +Finds the Bullet physics engine: + +.. code-block:: cmake + + find_package(Bullet [...]) Result Variables ^^^^^^^^^^^^^^^^ @@ -13,8 +17,8 @@ Result Variables This module defines the following variables: ``Bullet_FOUND`` - Boolean true if Bullet was found. For backward compatibility, the - ``BULLET_FOUND`` variable is also set to the same value. + Boolean indicating whether Bullet was found. For backward compatibility, + the ``BULLET_FOUND`` variable is also set to the same value. ``BULLET_INCLUDE_DIRS`` The Bullet include directories. ``BULLET_LIBRARIES`` @@ -33,11 +37,25 @@ This module accepts the following variables: Examples ^^^^^^^^ -Finding Bullet: +Finding Bullet and conditionally creating an interface :ref:`imported target +` that encapsulates its usage requirements for linking to a +project target: .. code-block:: cmake find_package(Bullet) + + if(Bullet_FOUND AND NOT TARGET Bullet::Bullet) + add_library(Bullet::Bullet INTERFACE IMPORTED) + set_target_properties( + Bullet::Bullet + PROPERTIES + INTERFACE_INCLUDE_DIRECTORIES "${BULLET_INCLUDE_DIRS}" + INTERFACE_LINK_LIBRARIES "${BULLET_LIBRARIES}" + ) + endif() + + target_link_libraries(example PRIVATE Bullet::Bullet) #]=======================================================================] macro(_FIND_BULLET_LIBRARY _var) diff --git a/Modules/FindCABLE.cmake b/Modules/FindCABLE.cmake index af0e6b6d70..aa68ff4769 100644 --- a/Modules/FindCABLE.cmake +++ b/Modules/FindCABLE.cmake @@ -8,7 +8,11 @@ FindCABLE .. versionchanged:: 4.1 This module is available only if policy :policy:`CMP0191` is not set to ``NEW``. -Finds the CABLE installation and determines its include paths and libraries. +Finds the CABLE installation and determines its include paths and libraries: + +.. code-block:: cmake + + find_package(CABLE [...]) Package called CABLE (CABLE Automates Bindings for Language Extension) was initially developed by Kitware to generate bindings to C++ classes for use in @@ -25,7 +29,7 @@ package. Cache Variables ^^^^^^^^^^^^^^^ -The following cache variables may be set when using this module: +The following cache variables may also be set: ``CABLE`` Path to the ``cable`` executable. diff --git a/Modules/FindCUDAToolkit.cmake b/Modules/FindCUDAToolkit.cmake index b00cd26b7e..f560c511fc 100644 --- a/Modules/FindCUDAToolkit.cmake +++ b/Modules/FindCUDAToolkit.cmake @@ -107,7 +107,7 @@ Imported Targets An :ref:`imported target ` named ``CUDA::toolkit`` is provided. -This module defines :prop_tgt:`IMPORTED` targets for each +This module provides :ref:`Imported Targets` for each of the following libraries that are part of the CUDAToolkit: - `CUDA Runtime Library`_ @@ -568,8 +568,6 @@ Result variables found to determine the CUDA Toolkit version as well as determining other features of the Toolkit. This variable is set for the convenience of modules that depend on this one. - - #]=======================================================================] # NOTE: much of this was simply extracted from FindCUDA.cmake. diff --git a/Modules/FindCURL.cmake b/Modules/FindCURL.cmake index 148841205b..be3c5bb7c3 100644 --- a/Modules/FindCURL.cmake +++ b/Modules/FindCURL.cmake @@ -6,7 +6,11 @@ FindCURL -------- Finds the native curl installation (include directories and libraries) for -transferring data with URLS. +transferring data with URLS: + +.. code-block:: cmake + + find_package(CURL [] [COMPONENTS ...] [...]) .. versionadded:: 3.17 If curl is built using its CMake-based build system, it will provide its own diff --git a/Modules/FindCVS.cmake b/Modules/FindCVS.cmake index d50a75866c..de64370d83 100644 --- a/Modules/FindCVS.cmake +++ b/Modules/FindCVS.cmake @@ -5,7 +5,11 @@ FindCVS ------- -Finds the Concurrent Versions System (CVS). +Finds the Concurrent Versions System (CVS): + +.. code-block:: cmake + + find_package(CVS [...]) Result Variables ^^^^^^^^^^^^^^^^ @@ -13,7 +17,7 @@ Result Variables This module defines the following variables: ``CVS_FOUND`` - True if the command-line client was found. + Boolean indicating whether the command-line client was found. Cache Variables ^^^^^^^^^^^^^^^ @@ -78,8 +82,5 @@ find_program(CVS_EXECUTABLE cvs ) mark_as_advanced(CVS_EXECUTABLE) -# Handle the QUIETLY and REQUIRED arguments and set CVS_FOUND to TRUE if -# all listed variables are TRUE - include(FindPackageHandleStandardArgs) find_package_handle_standard_args(CVS DEFAULT_MSG CVS_EXECUTABLE) diff --git a/Modules/FindCoin3D.cmake b/Modules/FindCoin3D.cmake index 1d89c604e0..8fd939b7a5 100644 --- a/Modules/FindCoin3D.cmake +++ b/Modules/FindCoin3D.cmake @@ -5,7 +5,11 @@ FindCoin3D ---------- -Finds Coin3D (Open Inventor). +Finds Coin3D (Open Inventor): + +.. code-block:: cmake + + find_package(Coin3D [...]) Coin3D is an implementation of the Open Inventor API. It provides data structures and algorithms for 3D visualization. @@ -16,8 +20,8 @@ Result Variables This module defines the following variables: ``Coin3D_FOUND`` - True if Coin3D, Open Inventor was found. For backward compatibility, the - ``COIN3D_FOUND`` variable is also set to the same value. + Boolean indicating whether Coin3D, Open Inventor is found. For backward + compatibility, the ``COIN3D_FOUND`` variable is also set to the same value. Cache Variables ^^^^^^^^^^^^^^^ @@ -32,11 +36,25 @@ The following cache variables may also be set: Examples ^^^^^^^^ -Finding Coin3D: +Finding Coin3D and conditionally creating an interface :ref:`imported target +` that encapsulates its usage requirements for linking to a +project target: .. code-block:: cmake find_package(Coin3D) + + if(Coin3D_FOUND AND NOT TARGET Coin3D::Coin3D) + add_library(Coin3D::Coin3D INTERFACE IMPORTED) + set_target_properties( + Coin3D::Coin3D + PROPERTIES + INTERFACE_INCLUDE_DIRECTORIES "${COIN3D_INCLUDE_DIRS}" + INTERFACE_LINK_LIBRARIES "${COIN3D_LIBRARIES}" + ) + endif() + + target_link_libraries(example PRIVATE Coin3D::Coin3D) #]=======================================================================] if (WIN32) diff --git a/Modules/FindCurses.cmake b/Modules/FindCurses.cmake index 64600c6c64..5d9952f58c 100644 --- a/Modules/FindCurses.cmake +++ b/Modules/FindCurses.cmake @@ -5,7 +5,11 @@ FindCurses ---------- -Finds the curses or ncurses library. +Finds the curses or ncurses library: + +.. code-block:: cmake + + find_package(Curses [...]) Curses is a terminal control library for Unix-like systems, used to build text user interface (TUI) applications. Originally developed in 1978, it has since diff --git a/Modules/FindCxxTest.cmake b/Modules/FindCxxTest.cmake index 37f1e7adc6..4e46cf4583 100644 --- a/Modules/FindCxxTest.cmake +++ b/Modules/FindCxxTest.cmake @@ -6,7 +6,11 @@ FindCxxTest ----------- Finds `CxxTest`_, a C++ unit testing framework suite, and provides a helper -command to create test runners and integrate them with CTest. +command to create test runners and integrate them with CTest: + +.. code-block:: cmake + + find_package(CxxTest [...]) .. _`CxxTest`: https://github.com/CxxTest/cxxtest diff --git a/Modules/FindCygwin.cmake b/Modules/FindCygwin.cmake index ba26980a8f..38db22df89 100644 --- a/Modules/FindCygwin.cmake +++ b/Modules/FindCygwin.cmake @@ -6,7 +6,11 @@ FindCygwin ---------- Finds Cygwin, a POSIX-compatible environment that runs natively on Microsoft -Windows. +Windows: + +.. code-block:: cmake + + find_package(Cygwin [...]) .. note:: @@ -30,7 +34,7 @@ Examples Finding the Cygwin installation and using its path in a custom find module: .. code-block:: cmake - :caption: FindFoo.cmake + :caption: ``FindFoo.cmake`` find_package(Cygwin) find_program(Foo_EXECUTABLE NAMES foo PATHS ${CYGWIN_INSTALL_PATH}/bin) diff --git a/Modules/FindDart.cmake b/Modules/FindDart.cmake index 96cce45590..252b6fabf9 100644 --- a/Modules/FindDart.cmake +++ b/Modules/FindDart.cmake @@ -8,10 +8,20 @@ FindDart .. deprecated:: 3.27 This module is available only if policy :policy:`CMP0145` is not set to ``NEW``. -Find DART +Finds DART: -This module looks for the dart testing software and sets DART_ROOT to +.. code-block:: cmake + + find_package(DART [...]) + +This module looks for the dart testing software and sets ``DART_ROOT`` to point to where it found it. + +Cache Variables +^^^^^^^^^^^^^^^ + +``DART_ROOT`` + The path to the Dart root installation. #]=======================================================================] if(_FindDart_testing) diff --git a/Modules/FindDevIL.cmake b/Modules/FindDevIL.cmake index 9e195d326a..f8e5575c1d 100644 --- a/Modules/FindDevIL.cmake +++ b/Modules/FindDevIL.cmake @@ -5,7 +5,11 @@ FindDevIL --------- -Finds the Developer's Image Library, `DevIL `_. +Finds the Developer's Image Library, `DevIL `_: + +.. code-block:: cmake + + find_package(DevIL [...]) The DevIL package internally consists of the following libraries, all distributed as part of the same release: diff --git a/Modules/FindEXPAT.cmake b/Modules/FindEXPAT.cmake index 341216735f..ece3fccce5 100644 --- a/Modules/FindEXPAT.cmake +++ b/Modules/FindEXPAT.cmake @@ -27,7 +27,7 @@ This module provides the following :ref:`Imported Targets`: Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: ``EXPAT_FOUND`` Boolean indicating whether (the requested version of) Expat is found. diff --git a/Modules/FindFLEX.cmake b/Modules/FindFLEX.cmake index 11c53a91c1..a25b083c2a 100644 --- a/Modules/FindFLEX.cmake +++ b/Modules/FindFLEX.cmake @@ -10,7 +10,7 @@ and provides CMake commands to create custom build rules for using Flex: .. code-block:: cmake - find_package(FLEX [] ...) + find_package(FLEX [] [...]) Flex generates lexical analyzers, also known as *scanners* or *lexers*. It also includes a runtime library (``fl``) that supplies support functions for the diff --git a/Modules/FindFLTK.cmake b/Modules/FindFLTK.cmake index 6b3438ceaa..adeb57b153 100644 --- a/Modules/FindFLTK.cmake +++ b/Modules/FindFLTK.cmake @@ -6,7 +6,11 @@ FindFLTK -------- Finds the Fast Light Toolkit (FLTK), a cross-platform toolkit for GUI -development. +development: + +.. code-block:: cmake + + find_package(FLTK [...]) FLTK uses CMake-based build system and provides a package configuration file for projects to find it. As of its 1.4.0 version it also provides @@ -18,8 +22,8 @@ This module takes that into account and first attempts to find FLTK in documentation for more information, how to use FLTK with CMake. .. versionadded:: 3.11 - Debug and Release library variants are found separately and use - per-configuration variables. + Debug and release (optimized) library variants are found separately and use + :ref:`per-configuration ` variables. Result Variables ^^^^^^^^^^^^^^^^ diff --git a/Modules/FindFLTK2.cmake b/Modules/FindFLTK2.cmake index c839d3f296..f70c0f036d 100644 --- a/Modules/FindFLTK2.cmake +++ b/Modules/FindFLTK2.cmake @@ -14,7 +14,11 @@ FindFLTK2 modern versions, use the :module:`FindFLTK` module instead. Finds the Fast Light Toolkit (FLTK) version 2.x, a cross-platform toolkit for -GUI development. +GUI development: + +.. code-block:: cmake + + find_package(FLTK2 [...]) Result Variables ^^^^^^^^^^^^^^^^ diff --git a/Modules/FindFontconfig.cmake b/Modules/FindFontconfig.cmake index 218ad2fbfa..e5fccb6a66 100644 --- a/Modules/FindFontconfig.cmake +++ b/Modules/FindFontconfig.cmake @@ -7,7 +7,11 @@ FindFontconfig .. versionadded:: 3.14 -Finds Fontconfig, a library for font configuration and customization. +Finds Fontconfig, a library for font configuration and customization: + +.. code-block:: cmake + + find_package(Fontconfig [] [...]) Imported Targets ^^^^^^^^^^^^^^^^ diff --git a/Modules/FindFreetype.cmake b/Modules/FindFreetype.cmake index a120fec506..d2be44f618 100644 --- a/Modules/FindFreetype.cmake +++ b/Modules/FindFreetype.cmake @@ -11,6 +11,9 @@ Finds the FreeType font renderer library: find_package(Freetype [] [...]) +.. versionadded:: 3.7 + Debug and Release (optimized) library variants are found separately. + Imported Targets ^^^^^^^^^^^^^^^^ diff --git a/Modules/FindGCCXML.cmake b/Modules/FindGCCXML.cmake index fdab959292..cf4a96f208 100644 --- a/Modules/FindGCCXML.cmake +++ b/Modules/FindGCCXML.cmake @@ -7,14 +7,30 @@ FindGCCXML .. versionchanged:: 4.1 This module is available only if policy :policy:`CMP0188` is not set to ``NEW``. - Port projects to search for CastXML by calling ``find_program`` directly. + Port projects to search for CastXML by calling :command:`find_program` directly. -Find the GCC-XML front-end executable. +Finds the GCC-XML front-end executable: -This module will define the following variables: +.. code-block:: cmake + + find_package(GCCXML [...]) + +Cache Variables +^^^^^^^^^^^^^^^ + +The following cache variables may also be set: ``GCCXML`` The GCC-XML front-end executable. + +Examples +^^^^^^^^ + +In new code, find CastXML with :command:`find_program` instead: + +.. code-block:: cmake + + find_program(CASTXML_EXECUTABLE castxml) #]=======================================================================] cmake_policy(GET CMP0188 _FindGCCXML_CMP0188) diff --git a/Modules/FindGLEW.cmake b/Modules/FindGLEW.cmake index 03d19bfabc..b9fe2616af 100644 --- a/Modules/FindGLEW.cmake +++ b/Modules/FindGLEW.cmake @@ -5,7 +5,11 @@ FindGLEW -------- -Finds the OpenGL Extension Wrangler Library (GLEW). +Finds the OpenGL Extension Wrangler Library (GLEW): + +.. code-block:: cmake + + find_package(GLEW [] [...]) GLEW is a cross-platform C/C++ library that helps manage OpenGL extensions by providing efficient run-time mechanisms to query and load OpenGL functionality @@ -53,7 +57,7 @@ Result Variables This module defines the following variables: ``GLEW_FOUND`` - Boolean indicating whether GLEW is found. + Boolean indicating whether (the requested version of) GLEW is found. ``GLEW_VERSION`` .. versionadded:: 3.15 diff --git a/Modules/FindGLUT.cmake b/Modules/FindGLUT.cmake index e29758dc1c..5b773cd0b5 100644 --- a/Modules/FindGLUT.cmake +++ b/Modules/FindGLUT.cmake @@ -5,8 +5,13 @@ FindGLUT -------- -Finds the OpenGL Utility Toolkit (GLUT) library, which provides a simple API for -creating windows, handling input, and managing events in OpenGL applications. +Finds the OpenGL Utility Toolkit (GLUT) library, which provides a simple API +for creating windows, handling input, and managing events in OpenGL +applications: + +.. code-block:: cmake + + find_package(GLUT [...]) Imported Targets ^^^^^^^^^^^^^^^^ diff --git a/Modules/FindHDF5.cmake b/Modules/FindHDF5.cmake index a49e994461..92e42ca531 100644 --- a/Modules/FindHDF5.cmake +++ b/Modules/FindHDF5.cmake @@ -10,7 +10,7 @@ self-describing array data: .. code-block:: cmake - find_package(HDF5 [] ... [COMPONENTS ...] ...) + find_package(HDF5 [] [COMPONENTS ...] [...]) If the HDF5 library is built using its CMake-based build system, it will as of HDF5 version 1.8.15 provide its own CMake Package Configuration file diff --git a/Modules/FindHTMLHelp.cmake b/Modules/FindHTMLHelp.cmake index 76b3dcfdf2..71abbe8b83 100644 --- a/Modules/FindHTMLHelp.cmake +++ b/Modules/FindHTMLHelp.cmake @@ -5,8 +5,12 @@ FindHTMLHelp ------------ -This module finds the Microsoft HTML Help Compiler and its API. It is part of -the HTML Help Workshop. +Finds the Microsoft HTML Help Compiler and its API which is part of the HTML +Help Workshop: + +.. code-block:: cmake + + find_package(HTMLHelp [...]) .. note:: @@ -17,7 +21,7 @@ the HTML Help Workshop. Cache Variables ^^^^^^^^^^^^^^^ -This module may set the following cache variables: +The following cache variables may also be set: ``HTML_HELP_COMPILER`` Full path to the HTML Help Compiler (``hhc.exe``), used to compile ``.chm`` diff --git a/Modules/FindICU.cmake b/Modules/FindICU.cmake index 942a0ae6ab..97d766dc2f 100644 --- a/Modules/FindICU.cmake +++ b/Modules/FindICU.cmake @@ -7,7 +7,11 @@ FindICU .. versionadded:: 3.7 -Finds the International Components for Unicode (ICU) libraries and programs. +Finds the International Components for Unicode (ICU) libraries and programs: + +.. code-block:: cmake + + find_package(ICU [] COMPONENTS ... [...]) .. versionadded:: 3.11 Support for static libraries on Windows. @@ -15,7 +19,13 @@ Finds the International Components for Unicode (ICU) libraries and programs. Components ^^^^^^^^^^ -This module supports the following components: +This module supports components, which can be specified with: + +.. code-block:: cmake + + find_package(ICU COMPONENTS ...) + +The following components are supported: ``data`` Finds the ICU Data library. On Windows, this library component is named @@ -49,12 +59,8 @@ This module supports the following components: all other ICU libraries and is recommended to include when working with ICU components. -At least one component should be specified for this module to successfully find -ICU: - -.. code-block:: cmake - - find_package(ICU COMPONENTS ...) +At least one component should be specified for this module to successfully +find ICU. Imported Targets ^^^^^^^^^^^^^^^^ @@ -74,13 +80,14 @@ Result Variables This module defines the following variables: ``ICU_FOUND`` - Boolean indicating whether the main programs and libraries were found. + Boolean indicating whether the (requested version of) main ICU programs + and libraries were found. +``ICU_VERSION`` + The version of the ICU release found. ``ICU_INCLUDE_DIRS`` The include directories containing the ICU headers. ``ICU_LIBRARIES`` Component libraries to be linked. -``ICU_VERSION`` - The version of the ICU release found. ICU programs are defined in the following variables: diff --git a/Modules/FindIce.cmake b/Modules/FindIce.cmake index 82156747d3..aec8485560 100644 --- a/Modules/FindIce.cmake +++ b/Modules/FindIce.cmake @@ -7,7 +7,12 @@ FindIce .. versionadded:: 3.1 -Finds the Internet Communication Engine (Ice) programs, libraries and datafiles. +Finds the Internet Communication Engine (Ice) programs, libraries and datafiles: + +.. code-block:: cmake + + find_package(Ice [] COMPONENTS ... [...]) + Ice is an open-source remote procedure call (RPC) framework developed by ZeroC and provides SDKs for various languages to develop network applications. diff --git a/Modules/FindIconv.cmake b/Modules/FindIconv.cmake index a11d746a98..d49c2dbaaf 100644 --- a/Modules/FindIconv.cmake +++ b/Modules/FindIconv.cmake @@ -7,9 +7,14 @@ FindIconv .. versionadded:: 3.11 -This module finds the ``iconv()`` POSIX.1 functions on the system. These -functions might be provided in the standard C library or externally in the form -of an additional library. +Finds the ``iconv()`` POSIX.1 functions on the system: + +.. code-block:: cmake + + find_package(Iconv [] [...]) + +Iconv functions might be provided in the standard C library or externally +in the form of an additional library. Imported Targets ^^^^^^^^^^^^^^^^ @@ -26,13 +31,8 @@ Result Variables This module defines the following variables: ``Iconv_FOUND`` - Boolean indicating if the iconv support was found. - -``Iconv_INCLUDE_DIRS`` - The include directories containing the iconv headers. - -``Iconv_LIBRARIES`` - The iconv libraries to be linked. + Boolean indicating whether the (requested version of) iconv support was + found. ``Iconv_VERSION`` .. versionadded:: 3.21 @@ -53,17 +53,23 @@ This module defines the following variables: The minor version of iconv. -``Iconv_IS_BUILT_IN`` - A boolean variable indicating whether iconv support is stemming from the C - standard library or not. Even if the C library provides ``iconv()``, the - presence of an external ``libiconv`` implementation might lead to this being - false. +``Iconv_INCLUDE_DIRS`` + The include directories containing the iconv headers. + +``Iconv_LIBRARIES`` + The iconv libraries to be linked. Cache Variables ^^^^^^^^^^^^^^^ The following cache variables may also be set: +``Iconv_IS_BUILT_IN`` + A boolean variable indicating whether iconv support is stemming from the C + standard library or not. Even if the C library provides ``iconv()``, the + presence of an external ``libiconv`` implementation might lead to this being + false. + ``Iconv_INCLUDE_DIR`` The directory containing the iconv headers. diff --git a/Modules/FindIntl.cmake b/Modules/FindIntl.cmake index cdc6541c9b..4b0808a2b0 100644 --- a/Modules/FindIntl.cmake +++ b/Modules/FindIntl.cmake @@ -8,9 +8,15 @@ FindIntl .. versionadded:: 3.2 Finds internationalization support that includes message translation functions -such as ``gettext()``. These functions originate from the GNU ``libintl`` -library, which is part of the GNU gettext utilities, but may also be provided by -the standard C library. +such as ``gettext()``: + +.. code-block:: cmake + + find_package(Intl [] [...]) + +These functions originate from the GNU ``libintl`` library, which is part +of the GNU gettext utilities, but may also be provided by the standard C +library. Imported Targets ^^^^^^^^^^^^^^^^ @@ -28,13 +34,7 @@ Result Variables This module defines the following variables: ``Intl_FOUND`` - Boolean indicating whether the Intl is found. - -``Intl_INCLUDE_DIRS`` - Include directories containing headers needed to use Intl. - -``Intl_LIBRARIES`` - The libraries needed to link against to use Intl. + Boolean indicating whether (the requested version of) Intl is found. ``Intl_VERSION`` .. versionadded:: 3.21 @@ -61,23 +61,29 @@ This module defines the following variables: The patch version of Intl found. +``Intl_INCLUDE_DIRS`` + Include directories containing headers needed to use Intl. + +``Intl_LIBRARIES`` + The libraries needed to link against to use Intl. + Cache Variables ^^^^^^^^^^^^^^^ The following cache variables may also be set: -``Intl_INCLUDE_DIR`` - The directory containing the ``libintl.h`` header file. - -``Intl_LIBRARY`` - The path to the Intl library (if any). - ``Intl_IS_BUILT_IN`` .. versionadded:: 3.20 Boolean indicating whether the found Intl functionality is provided by the standard C library rather than a separate ``libintl`` library. +``Intl_INCLUDE_DIR`` + The directory containing the ``libintl.h`` header file. + +``Intl_LIBRARY`` + The path to the Intl library (if any). + .. note:: On some platforms, such as Linux with GNU libc, the gettext functions are present in the C standard library and libintl is not required. The diff --git a/Modules/FindJNI.cmake b/Modules/FindJNI.cmake index 10dcc51776..477ff7a159 100644 --- a/Modules/FindJNI.cmake +++ b/Modules/FindJNI.cmake @@ -5,7 +5,11 @@ FindJNI ------- -Finds the Java Native Interface (JNI) include directories and libraries. +Finds the Java Native Interface (JNI) include directories and libraries: + +.. code-block:: cmake + + find_package(JNI [] [COMPONENTS ...] [...]) JNI enables Java code running in a Java Virtual Machine (JVM) or Dalvik Virtual Machine (DVM) on Android to call and be called by native applications and diff --git a/Modules/FindJava.cmake b/Modules/FindJava.cmake index 1587ce648b..acd624f598 100644 --- a/Modules/FindJava.cmake +++ b/Modules/FindJava.cmake @@ -6,7 +6,11 @@ FindJava -------- Finds the Java installation and determines its runtime tools and development -components. +components: + +.. code-block:: cmake + + find_package(Java [] [COMPONENTS ...] [...]) .. versionadded:: 3.10 Support for Java 9+ version parsing. @@ -14,7 +18,14 @@ components. Components ^^^^^^^^^^ -This module supports the following components: +This module supports optional components, which can be specified with the +:command:`find_package` command: + +.. code-block:: cmake + + find_package(Java [COMPONENTS ...]) + +Supported components include: ``Runtime`` Finds the Java Runtime Environment used to execute Java byte-compiled @@ -35,13 +46,7 @@ This module supports the following components: Finds the signer and verifier tool for Java Archive (JAR) files. -Components can optionally be specified using the standard syntax with: - -.. code-block:: cmake - - find_package(Java [COMPONENTS ...]) - -If no ``COMPONENTS`` are specified, the module searches for the ``Runtime`` +If no components are specified, the module searches for the ``Runtime`` component by default. Result Variables diff --git a/Modules/FindKDE3.cmake b/Modules/FindKDE3.cmake index ccfad5e7fb..f8a8615270 100644 --- a/Modules/FindKDE3.cmake +++ b/Modules/FindKDE3.cmake @@ -13,9 +13,15 @@ FindKDE3 `KDE documentation `_. -This module finds KDE 3 include directories, libraries, and KDE-specific -preprocessor tools. It provides usage requirements for building KDE 3 software -and defines several helper commands to simplify working with KDE 3 in CMake. +Finds KDE 3 include directories, libraries, and KDE-specific preprocessor +tools: + +.. code-block:: cmake + + find_package(KDE3 [...]) + +This module provides usage requirements for building KDE 3 software and +defines several helper commands to simplify working with KDE 3 in CMake. Result Variables ^^^^^^^^^^^^^^^^ diff --git a/Modules/FindLATEX.cmake b/Modules/FindLATEX.cmake index e272770af3..613898495e 100644 --- a/Modules/FindLATEX.cmake +++ b/Modules/FindLATEX.cmake @@ -5,8 +5,14 @@ FindLATEX --------- -Finds LaTeX compiler and Latex-related software like BibTeX. LaTeX is a -typesetting system for the production of technical and scientific documentation. +Finds LaTeX compiler and Latex-related software like BibTeX: + +.. code-block:: cmake + + find_package(LATEX [...]) + +LaTeX is a typesetting system for the production of technical and scientific +documentation. Components ^^^^^^^^^^ @@ -40,7 +46,7 @@ Supported components are: Finds the MakeIndex compiler. ``XINDY`` - Find the xindy compiler. + Finds the xindy compiler. ``DVIPS`` Finds the DVI-to-PostScript (DVIPS) converter. diff --git a/Modules/FindLTTngUST.cmake b/Modules/FindLTTngUST.cmake index 273439e9e1..6ca7b8527c 100644 --- a/Modules/FindLTTngUST.cmake +++ b/Modules/FindLTTngUST.cmake @@ -17,7 +17,7 @@ user space tracing library (LTTng-UST): Imported Targets ^^^^^^^^^^^^^^^^ -This module defines the following :ref:`Imported Targets`: +This module provides the following :ref:`Imported Targets`: ``LTTng::UST`` Target providing the LTTng-UST library usage requirements. This target is @@ -26,7 +26,7 @@ This module defines the following :ref:`Imported Targets`: Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: ``LTTngUST_FOUND`` Boolean indicating whether the LTTng-UST library is found. For backward diff --git a/Modules/FindLibArchive.cmake b/Modules/FindLibArchive.cmake index 9072d95da5..5f006e68c9 100644 --- a/Modules/FindLibArchive.cmake +++ b/Modules/FindLibArchive.cmake @@ -5,18 +5,24 @@ FindLibArchive -------------- -Finds the libarchive library and include directories. Libarchive is a -multi-format archive and compression library. +Finds the libarchive library and include directories: -Import Targets -^^^^^^^^^^^^^^ +.. code-block:: cmake -This module defines the following :ref:`Imported Targets`: + find_package(LibArchive [] [...]) + +Libarchive is a multi-format archive and compression library. + +Imported Targets +^^^^^^^^^^^^^^^^ + +This module provides the following :ref:`Imported Targets`: ``LibArchive::LibArchive`` .. versionadded:: 3.17 - A target for linking against libarchive. + A target encapsulating the libarchive usage requirements, available only + if libarchive is found. Result Variables ^^^^^^^^^^^^^^^^ @@ -24,11 +30,8 @@ Result Variables This module defines the following variables: ``LibArchive_FOUND`` - Boolean indicating whether libarchive was found. -``LibArchive_INCLUDE_DIRS`` - Include search path for using libarchive. -``LibArchive_LIBRARIES`` - Libraries to link against libarchive. + Boolean indicating whether (the requested version of) libarchive was found. + ``LibArchive_VERSION`` A 3-component version string (``major.minor.patch``) of libarchive found. @@ -40,10 +43,16 @@ This module defines the following variables: only for libarchive versions 3.1 and earlier. In CMake 3.6 and newer, this variable will be set for all libarchive versions. +``LibArchive_INCLUDE_DIRS`` + Include search path for using libarchive. + +``LibArchive_LIBRARIES`` + Libraries to link against libarchive. + Examples ^^^^^^^^ -Finding LibArchive and linking it to a project target: +Finding libarchive and linking it to a project target: .. code-block:: cmake diff --git a/Modules/FindLibXslt.cmake b/Modules/FindLibXslt.cmake index 5180f4cea9..d77ca1415d 100644 --- a/Modules/FindLibXslt.cmake +++ b/Modules/FindLibXslt.cmake @@ -37,7 +37,7 @@ This module provides the following :ref:`Imported Targets`: Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: ``LibXslt_FOUND`` Boolean indicating whether (the requested version of) libxslt is found. diff --git a/Modules/FindLibinput.cmake b/Modules/FindLibinput.cmake index f3e66af8a2..ca2c2a07e5 100644 --- a/Modules/FindLibinput.cmake +++ b/Modules/FindLibinput.cmake @@ -8,7 +8,11 @@ FindLibinput .. versionadded:: 3.14 Finds the libinput library which handles input devices in Wayland compositors -and provides a generic X.Org input driver. +and provides a generic X.Org input driver: + +.. code-block:: cmake + + find_package(Libinput [] [...]) Imported Targets ^^^^^^^^^^^^^^^^ diff --git a/Modules/FindMFC.cmake b/Modules/FindMFC.cmake index 27c5458358..70f73fb257 100644 --- a/Modules/FindMFC.cmake +++ b/Modules/FindMFC.cmake @@ -6,7 +6,11 @@ FindMFC ------- Finds the native Microsoft Foundation Class Library (MFC) for developing MFC -applications on Windows. +applications on Windows: + +.. code-block:: cmake + + find_package(MFC [...]) .. note:: diff --git a/Modules/FindMPEG.cmake b/Modules/FindMPEG.cmake index 6c49702a14..a84c9b4586 100644 --- a/Modules/FindMPEG.cmake +++ b/Modules/FindMPEG.cmake @@ -5,7 +5,11 @@ FindMPEG -------- -Finds the native MPEG library (libmpeg2). +Finds the native MPEG library (libmpeg2): + +.. code-block:: cmake + + find_package(MPEG [...]) .. note:: @@ -31,7 +35,7 @@ This module defines the following variables: Cache Variables ^^^^^^^^^^^^^^^ -The following cache variables may be also set: +The following cache variables may also be set: ``MPEG_INCLUDE_DIR`` The directory containing the ``mpeg2.h`` and related headers needed to use diff --git a/Modules/FindMPEG2.cmake b/Modules/FindMPEG2.cmake index 103f2c49d1..9ffd0dfa73 100644 --- a/Modules/FindMPEG2.cmake +++ b/Modules/FindMPEG2.cmake @@ -5,7 +5,11 @@ FindMPEG2 --------- -Finds the native MPEG2 library (libmpeg2). +Finds the native MPEG2 library (libmpeg2): + +.. code-block:: cmake + + find_package(MPEG2 [...]) .. note:: @@ -26,7 +30,7 @@ This module defines the following variables: Cache Variables ^^^^^^^^^^^^^^^ -The following cache variables may be also set: +The following cache variables may also be set: ``MPEG2_INCLUDE_DIR`` The directory containing the ``mpeg2.h`` and related headers needed to use diff --git a/Modules/FindMotif.cmake b/Modules/FindMotif.cmake index d72b19309e..e68ed73452 100644 --- a/Modules/FindMotif.cmake +++ b/Modules/FindMotif.cmake @@ -5,7 +5,11 @@ FindMotif --------- -Finds Motif (or LessTif) graphical user interface toolkit. +Finds Motif (or LessTif) graphical user interface toolkit: + +.. code-block:: cmake + + find_package(Motif [...]) Result Variables ^^^^^^^^^^^^^^^^ @@ -21,19 +25,33 @@ Cache Variables The following cache variables may also be set: -``MOTIF_LIBRARIES`` - Libraries needed to link to Motif. ``MOTIF_INCLUDE_DIR`` Include directories needed to use Motif. +``MOTIF_LIBRARIES`` + Libraries needed to link to Motif. + Examples ^^^^^^^^ -Finding Motif: +Finding Motif and creating an imported interface target for linking it to a +project target: .. code-block:: cmake find_package(Motif) + + if(Motif_FOUND AND NOT TARGET Motif::Motif) + add_library(Motif::Motif INTERFACE IMPORTED) + set_target_properties( + Motif::Motif + PROPERTIES + INTERFACE_INCLUDE_DIRECTORIES "${MOTIF_INCLUDE_DIR}" + INTERFACE_LINK_LIBRARIES "${MOTIF_LIBRARIES}" + ) + endif() + + target_link_libraries(example PRIVATE Motif::Motif) #]=======================================================================] if(UNIX) diff --git a/Modules/FindMsys.cmake b/Modules/FindMsys.cmake index 0d78c9bd92..42657984d1 100644 --- a/Modules/FindMsys.cmake +++ b/Modules/FindMsys.cmake @@ -8,7 +8,11 @@ FindMsys .. versionadded:: 3.21 Finds MSYS, a POSIX-compatible environment that runs natively on Microsoft -Windows. +Windows: + +.. code-block:: cmake + + find_package(Msys [...]) .. note:: @@ -32,7 +36,7 @@ Examples Finding the MSYS installation and using its path in a custom find module: .. code-block:: cmake - :caption: FindFoo.cmake + :caption: ``FindFoo.cmake`` find_package(Msys) find_program(Foo_EXECUTABLE NAMES foo PATHS ${MSYS_INSTALL_PATH}/usr/bin) diff --git a/Modules/FindODBC.cmake b/Modules/FindODBC.cmake index 6e103d2e19..bcb9cd3bba 100644 --- a/Modules/FindODBC.cmake +++ b/Modules/FindODBC.cmake @@ -7,11 +7,16 @@ FindODBC .. versionadded:: 3.12 -Finds the Open Database Connectivity (ODBC) library, which implements a standard -API for accessing database systems. ODBC enables applications to communicate -with different database management systems (DBMS) using a common set of -functions. Communication with a specific database is handled through ODBC -drivers, which the library loads at runtime. +Finds the Open Database Connectivity (ODBC) library, which implements a +standard API for accessing database systems: + +.. code-block:: cmake + + find_package(ODBC [...]) + +ODBC enables applications to communicate with different database management +systems (DBMS) using a common set of functions. Communication with a specific +database is handled through ODBC drivers, which the library loads at runtime. On Windows, when building with Visual Studio, this module assumes the ODBC library is provided by the available Windows SDK. @@ -76,19 +81,19 @@ Limitations Examples ^^^^^^^^ -Finding and using ODBC -"""""""""""""""""""""" +Example: Finding and Using ODBC +""""""""""""""""""""""""""""""" Finding ODBC and linking it to a project target: .. code-block:: cmake - :caption: CMakeLists.txt + :caption: ``CMakeLists.txt`` find_package(ODBC) target_link_libraries(project_target PRIVATE ODBC::ODBC) -Finding a custom ODBC installation on Unix-like systems -""""""""""""""""""""""""""""""""""""""""""""""""""""""" +Example: Finding a Custom ODBC Installation +""""""""""""""""""""""""""""""""""""""""""" The following examples are for Unix-like systems and demonstrate how to set hint and cache variables during the CMake configuration phase to help this module diff --git a/Modules/FindOpenACC.cmake b/Modules/FindOpenACC.cmake index b78d3815eb..84c7bf023a 100644 --- a/Modules/FindOpenACC.cmake +++ b/Modules/FindOpenACC.cmake @@ -7,9 +7,12 @@ FindOpenACC .. versionadded:: 3.10 -Detect OpenACC support by the compiler. +Finds and detects the OpenACC support in a compiler: + +.. code-block:: cmake + + find_package(OpenACC [] [...]) -This module can be used to detect OpenACC support in a compiler. If the compiler supports OpenACC, the flags required to compile with OpenACC support are returned in variables for the different languages. Currently, only NVHPC, PGI, GNU and Cray compilers are supported. @@ -17,28 +20,31 @@ Currently, only NVHPC, PGI, GNU and Cray compilers are supported. Imported Targets ^^^^^^^^^^^^^^^^ -.. versionadded:: 3.16 - -The module provides :prop_tgt:`IMPORTED` targets: +This module provides the following :ref:`Imported Targets`: ``OpenACC::OpenACC_`` - Target for using OpenACC from ````. + .. versionadded:: 3.16 -Variables -^^^^^^^^^ + Target encapsulating the usage requirements for using OpenACC from + ````. This target is available only if OpenACC support is found. + ```` is one of C, CXX, or Fortran. -The module defines the following variables: +Result Variables +^^^^^^^^^^^^^^^^ + +This module defines the following variables: ``OpenACC_FOUND`` .. versionadded:: 3.25 - Variable indicating that OpenACC flags for at least one languages have been found. + Boolean variable indicating that OpenACC flags for at least one languages + have been found. -This module will set the following variables per language in your +This module will set the following variables per language in the project, where ```` is one of C, CXX, or Fortran: ``OpenACC__FOUND`` - Variable indicating if OpenACC support for ```` was detected. + Boolean variable indicating if OpenACC support for ```` was detected. ``OpenACC__FLAGS`` OpenACC compiler flags for ````, separated by spaces. ``OpenACC__OPTIONS`` @@ -65,9 +71,21 @@ the OpenACC specification implemented by the ```` compiler. Input Variables ^^^^^^^^^^^^^^^ +This module accepts the following variables: + ``OpenACC_ACCEL_TARGET=`` -If set, will the correct target accelerator flag set to the will -be returned with OpenACC__FLAGS. + If set, the correct target accelerator flag set to the ```` + will be returned with the ``OpenACC__FLAGS`` variable. + +Examples +^^^^^^^^ + +Finding OpenACC support and linking the imported target to a project target: + +.. code-block:: cmake + + find_package(OpenACC) + target_link_libraries(example PRIVATE OpenACC::OpenACC_C) #]=======================================================================] cmake_policy(PUSH) diff --git a/Modules/FindOpenSP.cmake b/Modules/FindOpenSP.cmake index 3ff6a99a48..8609210c1d 100644 --- a/Modules/FindOpenSP.cmake +++ b/Modules/FindOpenSP.cmake @@ -7,8 +7,14 @@ FindOpenSP .. versionadded:: 3.25 -Finds the OpenSP library. OpenSP is an open-source implementation of the SGML -(Standard Generalized Markup Language) parser. +Finds the OpenSP library: + +.. code-block:: cmake + + find_package(OpenSP [] [...]) + +OpenSP is an open-source implementation of the SGML (Standard Generalized +Markup Language) parser. Imported Targets ^^^^^^^^^^^^^^^^ @@ -25,7 +31,7 @@ Result Variables This module defines the following variables: ``OpenSP_FOUND`` - Boolean indicating whether the (requested version of) OpenSP is available. + Boolean indicating whether (the requested version of) OpenSP is available. ``OpenSP_VERSION`` The version of found OpenSP. diff --git a/Modules/FindOpenThreads.cmake b/Modules/FindOpenThreads.cmake index 2e7c84f52e..91d4b06c03 100644 --- a/Modules/FindOpenThreads.cmake +++ b/Modules/FindOpenThreads.cmake @@ -5,7 +5,11 @@ FindOpenThreads --------------- -Finds the OpenThreads C++ based threading library. +Finds the OpenThreads C++ based threading library: + +.. code-block:: cmake + + find_package(OpenThreads [...]) OpenThreads header files are intended to be included as: diff --git a/Modules/FindPHP4.cmake b/Modules/FindPHP4.cmake index edef791cb8..4a8862c90d 100644 --- a/Modules/FindPHP4.cmake +++ b/Modules/FindPHP4.cmake @@ -5,7 +5,11 @@ FindPHP4 -------- -Finds PHP version 4, a general-purpose scripting language. +Finds PHP version 4, a general-purpose scripting language: + +.. code-block:: cmake + + find_package(PHP4 [...]) .. note:: diff --git a/Modules/FindPNG.cmake b/Modules/FindPNG.cmake index 0d5886aafc..a95452754a 100644 --- a/Modules/FindPNG.cmake +++ b/Modules/FindPNG.cmake @@ -19,17 +19,18 @@ Finds libpng, the official reference library for the PNG image format: Imported Targets ^^^^^^^^^^^^^^^^ -This module defines the following :ref:`Imported Targets`: +This module provides the following :ref:`Imported Targets`: ``PNG::PNG`` .. versionadded:: 3.5 - The libpng library, if found. + Target encapsulating the libpng library usage requirements, available if + libpng is found. Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: ``PNG_FOUND`` Boolean indicating whether (the requested version of) PNG library is found. diff --git a/Modules/FindPhysFS.cmake b/Modules/FindPhysFS.cmake index 1894498d9d..fae44218b4 100644 --- a/Modules/FindPhysFS.cmake +++ b/Modules/FindPhysFS.cmake @@ -5,7 +5,11 @@ FindPhysFS ---------- -Finds the PhysicsFS library (PhysFS) for file I/O abstraction. +Finds the PhysicsFS library (PhysFS) for file I/O abstraction: + +.. code-block:: cmake + + find_package(PhysFS [...]) Result Variables ^^^^^^^^^^^^^^^^ @@ -21,11 +25,11 @@ Cache Variables The following cache variables may also be set: +``PHYSFS_INCLUDE_DIR`` + Directory containing the ```` and related headers needed for using + the library. ``PHYSFS_LIBRARY`` Path to the PhysicsFS library needed to link against. -``PHYSFS_INCLUDE_DIR`` - Directory containing the ``physfs.h`` and related headers needed for using - the library. Hints ^^^^^ diff --git a/Modules/FindProducer.cmake b/Modules/FindProducer.cmake index 1d034bc207..1769cdd793 100644 --- a/Modules/FindProducer.cmake +++ b/Modules/FindProducer.cmake @@ -15,7 +15,11 @@ FindProducer 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. +designed primarily for real-time graphics applications: + +.. code-block:: cmake + + find_package(Producer [...]) Producer library headers are intended to be included in C++ project source code as: diff --git a/Modules/FindPython.cmake b/Modules/FindPython.cmake index 28f47b492c..8a739afad8 100644 --- a/Modules/FindPython.cmake +++ b/Modules/FindPython.cmake @@ -87,7 +87,7 @@ To manage concurrent versions 3 and 2 of Python, use :module:`FindPython3` and Imported Targets ^^^^^^^^^^^^^^^^ -This module defines the following :ref:`Imported Targets `: +This module provides the following :ref:`Imported Targets`: .. versionchanged:: 3.14 :ref:`Imported Targets ` are only created when @@ -138,7 +138,7 @@ This module defines the following :ref:`Imported Targets `: Result Variables ^^^^^^^^^^^^^^^^ -This module will set the following variables in your project +This module defines the following variables (see :ref:`Standard Variable Names `): ``Python_FOUND`` diff --git a/Modules/FindPython2.cmake b/Modules/FindPython2.cmake index 869dc70e8b..535f0be0c3 100644 --- a/Modules/FindPython2.cmake +++ b/Modules/FindPython2.cmake @@ -81,7 +81,7 @@ for you. Imported Targets ^^^^^^^^^^^^^^^^ -This module defines the following :ref:`Imported Targets `: +This module provides the following :ref:`Imported Targets`: .. versionchanged:: 3.14 :ref:`Imported Targets ` are only created when @@ -125,7 +125,7 @@ This module defines the following :ref:`Imported Targets `: Result Variables ^^^^^^^^^^^^^^^^ -This module will set the following variables in your project +This module defines the following variables (see :ref:`Standard Variable Names `): ``Python2_FOUND`` diff --git a/Modules/FindPython3.cmake b/Modules/FindPython3.cmake index 66c325ad0b..84f2d421f3 100644 --- a/Modules/FindPython3.cmake +++ b/Modules/FindPython3.cmake @@ -89,7 +89,7 @@ for you. Imported Targets ^^^^^^^^^^^^^^^^ -This module defines the following :ref:`Imported Targets `: +This module provides the following :ref:`Imported Targets`: .. versionchanged:: 3.14 :ref:`Imported Targets ` are only created when @@ -140,7 +140,7 @@ This module defines the following :ref:`Imported Targets `: Result Variables ^^^^^^^^^^^^^^^^ -This module will set the following variables in your project +This module defines the following variables (see :ref:`Standard Variable Names `): ``Python3_FOUND`` diff --git a/Modules/FindQt.cmake b/Modules/FindQt.cmake index 98cd1e2abf..efe5349282 100644 --- a/Modules/FindQt.cmake +++ b/Modules/FindQt.cmake @@ -31,7 +31,7 @@ Behavior: Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: ``QT4_INSTALLED`` ``TRUE`` if Qt4 is found. diff --git a/Modules/FindQt3.cmake b/Modules/FindQt3.cmake index 2c62a5f17f..9ab193a72e 100644 --- a/Modules/FindQt3.cmake +++ b/Modules/FindQt3.cmake @@ -5,8 +5,12 @@ FindQt3 ------- -This module finds Qt3, a cross-platform application development framework for -creating graphical user interfaces and applications. +Finds Qt3, a cross-platform application development framework for creating +graphical user interfaces and applications: + +.. code-block:: cmake + + find_package(Qt3 [] [...]) .. note:: @@ -17,13 +21,13 @@ creating graphical user interfaces and applications. Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: ``Qt3_FOUND`` - True if Qt3 has been found. + Boolean indicating whether Qt3 has been found. ``QT_FOUND`` - True if Qt3 has been found. This variable is for compatibility with other Qt - find modules. + Boolean indicating whether Qt3 has been found. This variable is for + compatibility with other Qt find modules. ``QT_VERSION_STRING`` The version of Qt3 that was found. ``QT_LIBRARIES`` diff --git a/Modules/FindQt4.cmake b/Modules/FindQt4.cmake index 2c9e39f72e..6ba7e1a3a5 100644 --- a/Modules/FindQt4.cmake +++ b/Modules/FindQt4.cmake @@ -5,9 +5,15 @@ FindQt4 ------- -This module finds Qt4, a cross-platform application development framework for -creating graphical user interfaces and applications. It defines a number of -imported targets, macros, and variables to use Qt4 in the project. +Finds Qt4, a cross-platform application development framework for creating +graphical user interfaces and applications: + +.. code-block:: cmake + + find_package(Qt4 [] [...]) + +This module defines a number of imported targets, macros, and variables to +use Qt4 in the project. .. note:: @@ -39,7 +45,7 @@ Imported Targets ^^^^^^^^^^^^^^^^ Qt libraries can be linked using their corresponding -:ref:`IMPORTED target ` with the +:ref:`Imported Target ` with the :command:`target_link_libraries` command: .. code-block:: cmake @@ -118,7 +124,7 @@ This module provides the following imported targets, if found: Result Variables ^^^^^^^^^^^^^^^^ -This module sets the following variables: +This module defines the following variables: ``Qt4_FOUND`` Boolean whether Qt4 has been found. If false, don't try to use Qt4. diff --git a/Modules/FindQuickTime.cmake b/Modules/FindQuickTime.cmake index 3f6b5ee767..55d98d3489 100644 --- a/Modules/FindQuickTime.cmake +++ b/Modules/FindQuickTime.cmake @@ -6,7 +6,11 @@ FindQuickTime ------------- Finds the QuickTime multimedia framework, which provides support for video, -audio, and interactive media. +audio, and interactive media: + +.. code-block:: cmake + + find_package(QuickTime [...]) .. note:: @@ -48,11 +52,24 @@ This module accepts the following variables: Examples ^^^^^^^^ -Finding QuickTime library: +Finding QuickTime library and creating an imported interface target for +linking it to a project target: .. code-block:: cmake find_package(QuickTime) + + if(QuickTime_FOUND AND NOT TARGET QuickTime::QuickTime) + add_library(QuickTime::QuickTime INTERFACE IMPORTED) + set_target_properties( + QuickTime::QuickTime + PROPERTIES + INTERFACE_INCLUDE_DIRECTORIES "${QUICKTIME_INCLUDE_DIR}" + INTERFACE_LINK_LIBRARIES "${QUICKTIME_LIBRARY}" + ) + endif() + + target_link_libraries(example PRIVATE QuickTime::QuickTime) #]=======================================================================] find_path(QUICKTIME_INCLUDE_DIR QuickTime/QuickTime.h QuickTime.h diff --git a/Modules/FindRTI.cmake b/Modules/FindRTI.cmake index 6a1a0245d2..87c97c3b4b 100644 --- a/Modules/FindRTI.cmake +++ b/Modules/FindRTI.cmake @@ -5,7 +5,11 @@ FindRTI ------- -Finds HLA RTI standard libraries and their include directories. +Finds HLA RTI standard libraries and their include directories: + +.. code-block:: cmake + + find_package(RTI [...]) `RTI `_ (Run-Time Infrastructure) is a simulation infrastructure standardized by IEEE @@ -19,7 +23,7 @@ Result Variables This module defines the following variables: ``RTI_FOUND`` - Set to FALSE if any HLA RTI was not found. + Boolean indicating whether HLA RTI is found. ``RTI_LIBRARIES`` The libraries to link against to use RTI. ``RTI_DEFINITIONS`` @@ -37,11 +41,25 @@ The following cache variables may also be set: Examples ^^^^^^^^ -Finding RTI: +Finding RTI and creating an imported interface target for linking it to a +project target: .. code-block:: cmake find_package(RTI) + + if(RTI_FOUND AND NOT TARGET RTI::RTI) + add_library(RTI::RTI INTERFACE IMPORTED) + set_target_properties( + RTI::RTI + PROPERTIES + INTERFACE_INCLUDE_DIRECTORIES "${RTI_INCLUDE_DIR}" + INTERFACE_LINK_LIBRARIES "${RTI_LIBRARIES}" + INTERFACE_COMPILE_DEFINITIONS "${RTI_DEFINITIONS}" + ) + endif() + + target_link_libraries(example PRIVATE RTI::RTI) #]=======================================================================] macro(RTI_MESSAGE_QUIETLY QUIET TYPE MSG) diff --git a/Modules/FindSelfPackers.cmake b/Modules/FindSelfPackers.cmake index dd50ba4697..3742165ee0 100644 --- a/Modules/FindSelfPackers.cmake +++ b/Modules/FindSelfPackers.cmake @@ -5,7 +5,11 @@ FindSelfPackers --------------- -Finds `UPX `_, the Ultimate Packer for eXecutables. +Finds `UPX `_, the Ultimate Packer for eXecutables: + +.. code-block:: cmake + + find_package(SelfPackers [...]) This module searches for executable packers-tools that compress executables or shared libraries into on-the-fly, self-extracting versions. It currently @@ -14,7 +18,7 @@ supports ``UPX``. Cache Variables ^^^^^^^^^^^^^^^ -The following cache variables may be set: +The following cache variables may also be set: ``SELF_PACKER_FOR_EXECUTABLE`` Path to the executable packer for compressing executables. diff --git a/Modules/FindTCL.cmake b/Modules/FindTCL.cmake index 5ed37911f4..d0208d3d58 100644 --- a/Modules/FindTCL.cmake +++ b/Modules/FindTCL.cmake @@ -5,7 +5,11 @@ FindTCL ------- -Finds the Tcl (Tool Command Language), dynamic programming language. +Finds the Tcl (Tool Command Language), dynamic programming language: + +.. code-block:: cmake + + find_package(TCL [...]) This module locates a Tcl installation, including its include directories and libraries, and determines the appropriate Tcl library name for linking. As part @@ -44,14 +48,12 @@ The following cache variables may also be set: ``TK_WISH`` The path to the ``wish`` windowing shell command-line executable. - Other Libraries ^^^^^^^^^^^^^^^ The Tcl Stub Library can be found using the separate :module:`FindTclStub` module. - Examples ^^^^^^^^ diff --git a/Modules/FindTclStub.cmake b/Modules/FindTclStub.cmake index ac0b2a6992..7c8d52cbd8 100644 --- a/Modules/FindTclStub.cmake +++ b/Modules/FindTclStub.cmake @@ -6,7 +6,11 @@ FindTclStub ----------- Finds the Tcl Stub Library, which is used for building version-independent Tcl -extensions. +extensions: + +.. code-block:: cmake + + find_package(TclStub [...]) Tcl (Tool Command Language) is a dynamic programming language, and the Tcl Stub Library provides a mechanism to allow Tcl extensions to be compiled in a way diff --git a/Modules/FindTclsh.cmake b/Modules/FindTclsh.cmake index 81c666a207..976547630e 100644 --- a/Modules/FindTclsh.cmake +++ b/Modules/FindTclsh.cmake @@ -6,7 +6,11 @@ FindTclsh --------- Finds the Tcl shell command-line executable (``tclsh``), which includes the Tcl -(Tool Command Language) interpreter. +(Tool Command Language) interpreter: + +.. code-block:: cmake + + find_package(Tclsh [...]) Result Variables ^^^^^^^^^^^^^^^^ diff --git a/Modules/FindVulkan.cmake b/Modules/FindVulkan.cmake index e10051de2a..5c8545838f 100644 --- a/Modules/FindVulkan.cmake +++ b/Modules/FindVulkan.cmake @@ -8,8 +8,13 @@ FindVulkan .. versionadded:: 3.7 Finds Vulkan, a low-overhead, cross-platform 3D graphics and computing API, -along with related development tools typically provided by the Vulkan SDK. This -includes commonly used utilities such as shader compilers and SPIR-V tools +along with related development tools typically provided by the Vulkan SDK: + +.. code-block:: cmake + + find_package(Vulkan [] [COMPONENTS ...] [...]) + +Vulkan includes commonly used utilities such as shader compilers and SPIR-V tools (e.g., DXC, ``glslc``, ``glslang``, etc.) that support Vulkan-based development workflows. diff --git a/Modules/FindWget.cmake b/Modules/FindWget.cmake index ef63d1eb32..dafbc379f6 100644 --- a/Modules/FindWget.cmake +++ b/Modules/FindWget.cmake @@ -6,15 +6,19 @@ FindWget -------- This module finds the ``wget`` command-line tool for retrieving content from web -servers. +servers: + +.. code-block:: cmake + + find_package(Wget [...]) Result Variables ^^^^^^^^^^^^^^^^ -This module defines the following local variables: +This module defines the following variables: ``Wget_FOUND`` - True if ``wget`` has been found. + Boolean indicating whether ``wget`` has been found. Cache Variables ^^^^^^^^^^^^^^^ diff --git a/Modules/FindWish.cmake b/Modules/FindWish.cmake index 00b120139c..e0a0c1b5b8 100644 --- a/Modules/FindWish.cmake +++ b/Modules/FindWish.cmake @@ -5,7 +5,11 @@ FindWish -------- -Finds ``wish``, a simple windowing shell command-line executable. +Finds ``wish``, a simple windowing shell command-line executable: + +.. code-block:: cmake + + find_package(Wish [...]) This module is commonly used in conjunction with finding a TCL installation (see the :module:`FindTCL` module). It helps determine where the TCL include paths @@ -17,7 +21,7 @@ for the Cygwin version of ``wish`` executable. Cache Variables ^^^^^^^^^^^^^^^ -The following cache variables may be set: +The following cache variables may also be set: ``TK_WISH`` The path to the ``wish`` executable. diff --git a/Modules/FindXCTest.cmake b/Modules/FindXCTest.cmake index 696718b4e0..e345fa4a01 100644 --- a/Modules/FindXCTest.cmake +++ b/Modules/FindXCTest.cmake @@ -7,7 +7,11 @@ FindXCTest .. versionadded:: 3.3 -Finds the XCTest framework for writing unit tests in Xcode projects. +Finds the XCTest framework for writing unit tests in Xcode projects: + +.. code-block:: cmake + + find_package(XCTest [...]) .. note:: diff --git a/Modules/FindXMLRPC.cmake b/Modules/FindXMLRPC.cmake index 949f755476..dc833f9c08 100644 --- a/Modules/FindXMLRPC.cmake +++ b/Modules/FindXMLRPC.cmake @@ -5,9 +5,15 @@ FindXMLRPC ---------- -Finds the native XML-RPC library for C and C++. XML-RPC is a standard network -protocol that enables remote procedure calls (RPC) between systems. It encodes -requests and responses in XML and uses HTTP as the transport mechanism. +Finds the native XML-RPC library for C and C++: + +.. code-block:: cmake + + find_package(XMLRPC [...] [COMPONENTS ...] [...]) + +XML-RPC is a standard network protocol that enables remote procedure calls +(RPC) between systems. It encodes requests and responses in XML and uses +HTTP as the transport mechanism. Components ^^^^^^^^^^ @@ -21,7 +27,7 @@ To list the available features on a system, the ``xmlrpc-c-config`` command-line utility can be used. In CMake, these features can be specified as components with the -``find_package()`` command: +:command:`find_package` command: .. code-block:: cmake @@ -50,29 +56,46 @@ Components may be: ``openssl`` OpenSSL convenience functions. +If no components are specified, this module searches for XML-RPC library and +its include directories without additional features. + Result Variables ^^^^^^^^^^^^^^^^ This module defines the following variables: +``XMLRPC_FOUND`` + Boolean indicating whether the XML-RPC library and all its requested + components are found. ``XMLRPC_INCLUDE_DIRS`` Include directories containing ``xmlrpc.h`` and other headers needed to use the XML-RPC library. ``XMLRPC_LIBRARIES`` List of libraries needed for linking to XML-RPC library and its requested features. -``XMLRPC_FOUND`` - Boolean indicating whether the XML-RPC library and all its requested - components are found. Examples ^^^^^^^^ -Finding XML-RPC library and its ``client`` feature to use in the project: +Finding XML-RPC library and its ``client`` feature, and conditionally +creating an interface :ref:`imported target ` that +encapsulates its usage requirements for linking to a project target: .. code-block:: cmake find_package(XMLRPC REQUIRED COMPONENTS client) + + if(XMLRPC_FOUND AND NOT TARGET XMLRPC::XMLRPC) + add_library(XMLRPC::XMLRPC INTERFACE IMPORTED) + set_target_properties( + XMLRPC::XMLRPC + PROPERTIES + INTERFACE_INCLUDE_DIRECTORIES "${XMLRPC_INCLUDE_DIRS}" + INTERFACE_LINK_LIBRARIES "${XMLRPC_LIBRARIES}" + ) + endif() + + target_link_libraries(example PRIVATE XMLRPC::XMLRPC) #]=======================================================================] # First find the config script from which to obtain other values. diff --git a/Modules/FindXalanC.cmake b/Modules/FindXalanC.cmake index 26d859bd0f..69594951b5 100644 --- a/Modules/FindXalanC.cmake +++ b/Modules/FindXalanC.cmake @@ -7,7 +7,11 @@ FindXalanC .. versionadded:: 3.5 -Finds the Apache Xalan-C++ XSL transform processor headers and libraries. +Finds the Apache Xalan-C++ XSL transform processor headers and libraries: + +.. code-block:: cmake + + find_package(XalaxC [] [...]) .. note:: @@ -29,7 +33,7 @@ Result Variables This module defines the following variables: ``XalanC_FOUND`` - Boolean indicating whether the Xalan-C++ is found. + Boolean indicating whether (the requested version of) Xalan-C++ is found. ``XalanC_VERSION`` The version of the found Xalan-C++ library. ``XalanC_INCLUDE_DIRS`` diff --git a/Modules/FindXercesC.cmake b/Modules/FindXercesC.cmake index c172d28ca8..d33868b5be 100644 --- a/Modules/FindXercesC.cmake +++ b/Modules/FindXercesC.cmake @@ -7,12 +7,16 @@ FindXercesC .. versionadded:: 3.1 -Finds the Apache Xerces-C++ validating XML parser headers and libraries. +Finds the Apache Xerces-C++ validating XML parser headers and libraries: + +.. code-block:: cmake + + find_package(XercesC [] [...]) Imported Targets ^^^^^^^^^^^^^^^^ -This module defines the following :ref:`Imported Targets`: +This module provides the following :ref:`Imported Targets`: ``XercesC::XercesC`` .. versionadded:: 3.5 @@ -26,7 +30,7 @@ Result Variables This module defines the following variables: ``XercesC_FOUND`` - Boolean indicating whether the Xerces-C++ is found. + Boolean indicating whether (the requested version of) Xerces-C++ is found. ``XercesC_VERSION`` The version of the found Xerces-C++ library. ``XercesC_INCLUDE_DIRS``