CheckIPOSupported

Added in version 3.9.

This module provides a command to check whether the compiler supports interprocedural optimization (IPO/LTO).

Load this module in a CMake project with:

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 INTERPROCEDURAL_OPTIMIZATION target property, or for all targets in the current scope using the 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:

check_ipo_supported

Checks whether the compiler supports interprocedural optimization (IPO/LTO):

check_ipo_supported(
  [RESULT <result-var>]
  [OUTPUT <output-var>]
  [LANGUAGES <lang>...]
)

Options are:

RESULT <result-var>

Set <result-var> 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 <output-var>

Set <output-var> variable with details about any error.

LANGUAGES <lang>...

Specify languages whose compilers to check.

The following languages are supported:

• C

• CXX

• CUDA

  Added in version 3.25.

• Fortran

If this option is not given, the default languages are picked from the current ENABLED_LANGUAGES global property.

Note

To use check_ipo_supported(), policy CMP0069 must be set to NEW; otherwise, a fatal error will occur.

Added in version 3.13: Support for Visual Studio Generators.

Added in version 3.24: The check uses the caller's CMAKE_<LANG>_FLAGS and CMAKE_<LANG>_FLAGS_<CONFIG> values. See policy CMP0138.

Examples

Checking whether the compiler supports IPO and emitting a fatal error if it is not supported:

include(CheckIPOSupported)
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 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:

option(FOO_ENABLE_IPO "Enable IPO/LTO")

if(FOO_ENABLE_IPO)
  include(CheckIPOSupported)
  check_ipo_supported(RESULT result OUTPUT output)
  if(result)
    set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
  else()
    message(WARNING "IPO is not supported: ${output}")
  endif()
endif()