1CMP0083
2-------
3
4.. versionadded:: 3.14
5
6To control generation of Position Independent Executable (``PIE``) or not, some
7flags are required at link time.
8
9CMake 3.13 and lower did not add these link flags when
10:prop_tgt:`POSITION_INDEPENDENT_CODE` is set.
11
12The ``OLD`` behavior for this policy is to not manage ``PIE`` link flags. The
13``NEW`` behavior is to add link flags if :prop_tgt:`POSITION_INDEPENDENT_CODE`
14is set:
15
16* Set to ``TRUE``: flags to produce a position independent executable are
17  passed to the linker step. For example ``-pie`` for ``GCC``.
18* Set to ``FALSE``: flags not to produce a position independent executable are
19  passed to the linker step. For example ``-no-pie`` for ``GCC``.
20* Not set: no flags are passed to the linker step.
21
22Since a given linker may not support ``PIE`` flags in all environments in
23which it is used, it is the project's responsibility to use the
24:module:`CheckPIESupported` module to check for support to ensure that the
25:prop_tgt:`POSITION_INDEPENDENT_CODE` target property for executables will be
26honored at link time.
27
28This policy was introduced in CMake version 3.14. Use the
29:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
30Unlike most policies, CMake version |release| does not warn when this policy is
31not set and simply uses ``OLD`` behavior.
32
33.. Note::
34
35   Android platform has a special handling of ``PIE`` so it is not required
36   to use the :module:`CheckPIESupported` module to ensure flags are passed to
37   the linker.
38
39.. include:: DEPRECATED.txt
40
41Examples
42^^^^^^^^
43
44Behave like CMake 3.13 and do not apply any ``PIE`` flags at link stage.
45
46.. code-block:: cmake
47
48  cmake_minimum_required(VERSION 3.13)
49  project(foo)
50
51  # ...
52
53  add_executable(foo ...)
54  set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
55
56Use the :module:`CheckPIESupported` module to detect whether ``PIE`` is
57supported by the current linker and environment.  Apply ``PIE`` flags only
58if the linker supports them.
59
60.. code-block:: cmake
61
62  cmake_minimum_required(VERSION 3.14) # CMP0083 NEW
63  project(foo)
64
65  include(CheckPIESupported)
66  check_pie_supported()
67
68  # ...
69
70  add_executable(foo ...)
71  set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
72