1CMP0114
2-------
3
4.. versionadded:: 3.19
5
6:module:`ExternalProject` step targets fully adopt their steps.
7
8The :command:`ExternalProject_Add` ``STEP_TARGETS`` option, and the
9:command:`ExternalProject_Add_StepTargets` function, can be used to
10create build targets for individual steps of an external project.
11
12In CMake 3.18 and below, step targets have some limitations:
13
14* Step targets always depend on targets named by the
15  :command:`ExternalProject_Add` ``DEPENDS`` option even though
16  not all steps need them.  In order to allow step targets to be created
17  without those dependencies, the :command:`ExternalProject_Add`
18  ``INDEPENDENT_STEP_TARGETS`` option or the
19  :command:`ExternalProject_Add_StepTargets` ``NO_DEPENDS`` option may
20  be used.  However, adding such "independent" step targets makes sense
21  only for specific steps such as ``download``, ``update``, and ``patch``
22  because they do not need any of the external project's build dependencies.
23  Furthermore, it does not make sense to create independent step targets
24  for steps that depend on non-independent steps.  Such rules are not
25  enforced, and projects that do not follow them can generate build systems
26  with confusing and generator-specific behavior.
27
28* Step targets hold copies of the custom commands implementing their
29  steps that are separate from the copies in the primary target created
30  by :command:`ExternalProject_Add`, and the primary target does not
31  depend on the step targets.  In parallel builds that drive the primary
32  target and step targets concurrently, multiple copies of the steps'
33  commands may run concurrently and race each other.
34
35  Also, prior to policy :policy:`CMP0113`, the step targets generated
36  by :ref:`Makefile Generators` also contain all the custom commands
37  on which their step depends.  This can lead to repeated execution of
38  those steps even in serial builds.
39
40In CMake 3.19 and above, the :module:`ExternalProject` module prefers
41a revised design to address these problems:
42
43* Each step is classified as "independent" if it does not depend
44  on other targets named by the :command:`ExternalProject_Add` ``DEPENDS``.
45  The predefined steps are automatically classified by default:
46
47  * The ``download``, ``update``, and ``patch`` steps are independent.
48  * The ``configure``, ``build``, ``test``, and ``install`` steps are not.
49
50  For custom steps, the :command:`ExternalProject_Add_Step` command provides
51  an ``INDEPENDENT`` option to mark them as independent.  It is an error to
52  mark a step as independent if it depends on other steps that are not.  Note
53  that this use of the term "independent" refers only to independence from
54  external targets and is orthogonal to a step's dependencies on other steps.
55
56* Step targets created by the :command:`ExternalProject_Add` ``STEP_TARGETS``
57  option or the :command:`ExternalProject_Add_Step` function are now
58  independent if and only if their steps are marked as independent.
59  The :command:`ExternalProject_Add` ``INDEPENDENT_STEP_TARGETS`` option
60  and :command:`ExternalProject_Add_StepTargets` ``NO_DEPENDS`` option
61  are no longer allowed.
62
63* Step targets, when created, are fully responsible for holding the
64  custom commands implementing their steps.  The primary target created
65  by :command:`ExternalProject_Add` depends on the step targets, and the
66  step targets depend on each other.  The target-level dependencies match
67  the file-level dependencies used by the custom commands for each step.
68
69  When the :command:`ExternalProject_Add` ``UPDATE_DISCONNECTED`` or
70  ``TEST_EXCLUDE_FROM_MAIN`` option is used, or the
71  :command:`ExternalProject_Add_Step` ``EXCLUDE_FROM_MAIN`` option is used
72  for a custom step, some step targets may be created automatically.
73  These are needed to hold the steps commonly depended upon by the primary
74  target and the disconnected step targets.
75
76Policy ``CMP0114`` provides compatibility for projects that have not been
77updated to expect the new behavior.  The ``OLD`` behavior for this policy
78is to use the above-documented behavior from 3.18 and below.  The ``NEW``
79behavior for this policy is to use the above-documented behavior preferred
80by 3.19 and above.
81
82This policy was introduced in CMake version 3.19.  CMake version
83|release| warns when the policy is not set and uses ``OLD`` behavior.
84Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
85explicitly.
86