echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

CheckPIESupported: Update documentation

Browse Source 
- The module purpose explanation extended to clarify what this module
  enables and what gets configured when not using this module.
- Examples extended with include() and some minor adjustments
- Policy CMP0083 info described with a note directive
This commit is contained in:
Peter Kokot 2025-03-10 01:14:43 +01:00
parent e188d8d6dc
commit eb18960b60
No known key found for this signature in database
GPG Key ID: A94800907AA79B36
1 changed files with 41 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
Modules/CheckPIESupported.cmake
View File

@ -7,10 +7,16 @@ CheckPIESupported
.. versionadded:: 3.14
Check whether the linker supports Position Independent Code (PIE) or No
Position Independent Code (NO_PIE) for executables.
Use this to ensure that the :prop_tgt:`POSITION_INDEPENDENT_CODE` target
property for executables will be honored at link time.
This module provides the ``check_pie_supported()`` function to check whether the
linker supports Position Independent Code (PIE) or No Position Independent Code
(NO_PIE) for executables.
When setting the :prop_tgt:`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.
.. command:: check_pie_supported
@ -36,14 +42,16 @@ property for executables will be honored at link time.
``OBJC``, ``OBJCXX``, ``CUDA``, and ``HIP`` are supported.
It makes no sense to use this module when :policy:`CMP0083` is set to ``OLD``,
so the command will return an error in this case. See policy :policy:`CMP0083`
for details.
.. note::
To use ``check_pie_supported()``, policy :policy:`CMP0083` must be set to
``NEW``; otherwise, a fatal error will occur.
Variables
^^^^^^^^^
For each language checked, two boolean cache variables are defined.
For each language checked, the ``check_pie_supported()`` function defines two
boolean cache variables:
``CMAKE_<lang>_LINK_PIE_SUPPORTED``
Set to true if ``PIE`` is supported by the linker and false otherwise.
@ -53,21 +61,44 @@ For each language checked, two boolean cache variables are defined.
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:
.. code-block:: cmake
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:
.. code-block:: cmake
# Retrieve any error message.
add_executable(foo ...)
include(CheckPIESupported)
check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C)
set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
if(NOT CMAKE_C_LINK_PIE_SUPPORTED)
message(WARNING "PIE is not supported at link time: ${output}.\n"
message(WARNING "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:
.. code-block:: cmake
add_executable(foo ...)
set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
#]=======================================================================]