diff --git a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst index 0a4ac9aa5f..51ad4b9ad5 100644 --- a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst +++ b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION.rst @@ -15,3 +15,9 @@ target is created. There is also the per-configuration :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_` target property, which overrides :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` if it is set. + +See Also +^^^^^^^^ + +* The :module:`CheckIPOSupported` module to check whether the compiler + supports interprocedural optimization before enabling this target property. diff --git a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst index 79d46048b1..8778eb1fa9 100644 --- a/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst +++ b/Help/prop_tgt/INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst @@ -10,3 +10,9 @@ configuration. This property is initialized by the :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION_` variable if it is set when a target is created. + +See Also +^^^^^^^^ + +* The :module:`CheckIPOSupported` module to check whether the compiler + supports interprocedural optimization before enabling this target property. diff --git a/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst index cf7da76604..a4b83e3003 100644 --- a/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst +++ b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION.rst @@ -8,3 +8,8 @@ Default value for :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` of targets. This variable is used to initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` property on all the targets. See that target property for additional information. + +See Also +^^^^^^^^ + +* The :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION_` variable. diff --git a/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst index 5b3ee7705b..257c48d01e 100644 --- a/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst +++ b/Help/variable/CMAKE_INTERPROCEDURAL_OPTIMIZATION_CONFIG.rst @@ -8,3 +8,8 @@ Default value for :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_` of targets. This variable is used to initialize the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION_` property on all the targets. See that target property for additional information. + +See Also +^^^^^^^^ + +* The :variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable. diff --git a/Modules/CheckIPOSupported.cmake b/Modules/CheckIPOSupported.cmake index 3db7ae4294..6369a4434d 100644 --- a/Modules/CheckIPOSupported.cmake +++ b/Modules/CheckIPOSupported.cmake @@ -7,25 +7,56 @@ CheckIPOSupported .. versionadded:: 3.9 -This module provides a function to check whether the compiler supports an -interprocedural optimization (IPO/LTO). Use this module before enabling the -:prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property. +This module provides a command to check whether the compiler supports +interprocedural optimization (IPO/LTO). + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(CheckIPOSupported) + +Interprocedural optimization is a compiler technique that performs +optimizations across translation units (i.e., across source files), allowing +the compiler to analyze and optimize the entire program as a whole rather +than file-by-file. This can improve performance by enabling more aggressive +inlining and dead code elimination. When these optimizations are applied at +link time, the process is typically referred to as link-time optimization +(LTO), which is a common form of IPO. + +In CMake, interprocedural optimization can be enabled on a per-target basis +using the :prop_tgt:`INTERPROCEDURAL_OPTIMIZATION` target property, or +for all targets in the current scope using the +:variable:`CMAKE_INTERPROCEDURAL_OPTIMIZATION` variable. + +Use this module before enabling the interprocedural optimization on targets +to ensure the compiler supports IPO/LTO. + +Commands +^^^^^^^^ + +This module provides the following command: .. command:: check_ipo_supported + Checks whether the compiler supports interprocedural optimization (IPO/LTO): + .. code-block:: cmake - check_ipo_supported([RESULT ] [OUTPUT ] - [LANGUAGES ...]) + check_ipo_supported( + [RESULT ] + [OUTPUT ] + [LANGUAGES ...] + ) Options are: - ``RESULT `` - Set ```` variable to ``YES`` if IPO is supported by the + ``RESULT `` + Set ```` variable to ``YES`` if IPO is supported by the compiler and ``NO`` otherwise. If this option is not given then the command will issue a fatal error if IPO is not supported. - ``OUTPUT `` - Set ```` variable with details about any error. + ``OUTPUT `` + Set ```` variable with details about any error. ``LANGUAGES ...`` Specify languages whose compilers to check. @@ -44,18 +75,18 @@ interprocedural optimization (IPO/LTO). Use this module before enabling the If this option is not given, the default languages are picked from the current :prop_gbl:`ENABLED_LANGUAGES` global property. -.. note:: + .. note:: - To use ``check_ipo_supported()``, policy :policy:`CMP0069` must be set to - ``NEW``; otherwise, a fatal error will occur. + To use ``check_ipo_supported()``, policy :policy:`CMP0069` must be set to + ``NEW``; otherwise, a fatal error will occur. -.. versionadded:: 3.13 - Support for Visual Studio generators. + .. versionadded:: 3.13 + Support for Visual Studio generators. -.. versionadded:: 3.24 - The check uses the caller's :variable:`CMAKE__FLAGS` - and :variable:`CMAKE__FLAGS_` values. - See policy :policy:`CMP0138`. + .. versionadded:: 3.24 + The check uses the caller's :variable:`CMAKE__FLAGS` + and :variable:`CMAKE__FLAGS_` values. + See policy :policy:`CMP0138`. Examples ^^^^^^^^ @@ -69,10 +100,10 @@ not supported: check_ipo_supported() # fatal error if IPO is not supported set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE) -The following example demonstrates how to use the ``CheckIPOSupported`` module -to enable IPO for the target only when supported by the compiler and to issue a -warning if it is not. Additionally, projects may want to provide a -configuration option to control when IPO is enabled. For example: +The following example demonstrates how to use this module to enable IPO for +the target only when supported by the compiler and to issue a warning if it +is not. Additionally, projects may want to provide a configuration option +to control when IPO is enabled. For example: .. code-block:: cmake