# CheckPIESupported

Added in version 3.14.

This module provides a command to check whether the linker supports Position Independent Code (PIE) or No Position Independent Code (NO_PIE) for executables.

Load this module in a CMake project with:

    include(CheckPIESupported)

When setting the `POSITION_INDEPENDENT_CODE` target property, PIC-related compile and link options are added when building library objects, and PIE-related compile options are added when building objects of executable targets, regardless of this module. Use this module to ensure that the `POSITION_INDEPENDENT_CODE` target property for executables is also honored at link time.

## Commands

This module provides the following command:

check_pie_supported

  Checks for PIE/NO_PIE support and prepares all executables to have link time PIE options enabled:

      check_pie_supported([OUTPUT_VARIABLE <output>] [LANGUAGES <langs>...])

  Options are:

  `OUTPUT_VARIABLE <output>`

    Set `<output>` variable with details about any error. If the check is bypassed because it uses cached results from a previous call, the output will be empty even if errors were present in the previous call.

  `LANGUAGES <langs>...`

    Check the linkers used for each of the specified languages. If this option is not provided, the command checks all enabled languages.

    `C`, `CXX`, `Fortran` are supported.

    Added in version 3.23: `OBJC`, `OBJCXX`, `CUDA`, and `HIP` are supported.

  Note

  To use `check_pie_supported()`, policy `CMP0083` must be set to `NEW`; otherwise, a fatal error will occur.

## Variables

For each language checked, the `check_pie_supported()` command defines two boolean cache variables:

`CMAKE_<lang>_LINK_PIE_SUPPORTED`

  Set to true if `PIE` is supported by the linker and false otherwise.

`CMAKE_<lang>_LINK_NO_PIE_SUPPORTED`

  Set to true if `NO_PIE` is supported by the linker and false otherwise.

## Examples

To enable PIE on an executable target at link time as well, include this module and call `check_pie_supported()` before setting the `POSITION_INDEPENDENT_CODE` target property. This will determine whether the linker for each checked language supports PIE-related link options. For example:

    add_executable(foo ...)

    include(CheckPIESupported)
    check_pie_supported()
    set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)

Since not all linkers require or support PIE-related link options (for example, `MSVC`), retrieving any error messages might be useful for logging purposes:

    add_executable(foo ...)

    message(CHECK_START "Checking for C linker PIE support")

    include(CheckPIESupported)
    check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C)
    set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)

    if(CMAKE_C_LINK_PIE_SUPPORTED)
      message(CHECK_PASS "yes")
    else()
      message(CHECK_FAIL "no")
      message(VERBOSE "PIE is not supported at link time:\n${output}"
                      "PIE link options will not be passed to linker.")
    endif()

Setting the `POSITION_INDEPENDENT_CODE` target property on an executable without this module will set PIE-related compile options but not PIE-related link options, which might not be sufficient in certain cases:

    add_executable(foo ...)
    set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)