New in version 3.19.
ExternalProject step targets fully adopt their steps.
STEP_TARGETS option, and the
ExternalProject_Add_StepTargets() function, can be used to
create build targets for individual steps of an external project.
In CMake 3.18 and below, step targets have some limitations:
Step targets always depend on targets named by the
DEPENDSoption even though not all steps need them. In order to allow step targets to be created without those dependencies, the
INDEPENDENT_STEP_TARGETSoption or the
NO_DEPENDSoption may be used. However, adding such "independent" step targets makes sense only for specific steps such as
patchbecause they do not need any of the external project's build dependencies. Furthermore, it does not make sense to create independent step targets for steps that depend on non-independent steps. Such rules are not enforced, and projects that do not follow them can generate build systems with confusing and generator-specific behavior.
Step targets hold copies of the custom commands implementing their steps that are separate from the copies in the primary target created by
ExternalProject_Add(), and the primary target does not depend on the step targets. In parallel builds that drive the primary target and step targets concurrently, multiple copies of the steps' commands may run concurrently and race each other.
Also, prior to policy
CMP0113, the step targets generated by Makefile Generators also contain all the custom commands on which their step depends. This can lead to repeated execution of those steps even in serial builds.
In CMake 3.19 and above, the
ExternalProject module prefers
a revised design to address these problems:
Each step is classified as "independent" if it does not depend on other targets named by the
DEPENDS. The predefined steps are automatically classified by default:
patchsteps are independent.
installsteps are not.
For custom steps, the
ExternalProject_Add_Step()command provides an
INDEPENDENToption to mark them as independent. It is an error to mark a step as independent if it depends on other steps that are not. Note that this use of the term "independent" refers only to independence from external targets and is orthogonal to a step's dependencies on other steps.
Step targets created by the
STEP_TARGETSoption or the
ExternalProject_Add_Step()function are now independent if and only if their steps are marked as independent. The
NO_DEPENDSoption are no longer allowed.
Step targets, when created, are fully responsible for holding the custom commands implementing their steps. The primary target created by
ExternalProject_Add()depends on the step targets, and the step targets depend on each other. The target-level dependencies match the file-level dependencies used by the custom commands for each step.
TEST_EXCLUDE_FROM_MAINoption is used, or the
EXCLUDE_FROM_MAINoption is used for a custom step, some step targets may be created automatically. These are needed to hold the steps commonly depended upon by the primary target and the disconnected step targets.
CMP0114 provides compatibility for projects that have not been
updated to expect the new behavior. The
OLD behavior for this policy
is to use the above-documented behavior from 3.18 and below. The
behavior for this policy is to use the above-documented behavior preferred
by 3.19 and above.
This policy was introduced in CMake version 3.19. CMake version
3.21.7 warns when the policy is not set and uses
cmake_policy() command to set it to