Create custom targets to build projects in external trees
ExternalProject_Add
The ExternalProject_Add
function creates a custom target to drive download, update/patch, configure, build, install and test steps of an external project:
ExternalProject_Add(<name> [<option>...])
General options are:
DEPENDS <projects>...
PREFIX <dir>
LIST_SEPARATOR <sep>
TMP_DIR <dir>
STAMP_DIR <dir>
EXCLUDE_FROM_ALL 1
Download step options are:
DOWNLOAD_NAME <fname>
DOWNLOAD_DIR <dir>
DOWNLOAD_COMMAND <cmd>...
DOWNLOAD_NO_PROGRESS 1
CVS_REPOSITORY <cvsroot>
CVS_MODULE <mod>
CVS_TAG <tag>
SVN_REPOSITORY <url>
SVN_REVISION -r<rev>
SVN_USERNAME <username>
SVN_PASSWORD <password>
SVN_TRUST_CERT 1
GIT_REPOSITORY <url>
GIT_TAG <tag>
GIT_REMOTE_NAME <name>
origin
GIT_SUBMODULES <module>...
HG_REPOSITORY <url>
HG_TAG <tag>
URL /.../src.tgz
URL_HASH ALGO=value
URL_MD5 md5
TLS_VERIFY <bool>
TLS_CAINFO <file>
TIMEOUT <seconds>
Update/Patch step options are:
UPDATE_COMMAND <cmd>...
UPDATE_DISCONNECTED 1
PATCH_COMMAND <cmd>...
Configure step options are:
SOURCE_DIR <dir>
CONFIGURE_COMMAND <cmd>...
CMAKE_COMMAND /.../cmake
CMAKE_GENERATOR <gen>
CMAKE_GENERATOR_PLATFORM <platform>
CMAKE_GENERATOR_TOOLSET <toolset>
CMAKE_ARGS <arg>...
CMake Options
. Arguments in the form -Dvar:string=on
are always passed to the command line, and therefore cannot be changed by the user. Arguments may use generator expressions
.CMAKE_CACHE_ARGS <arg>...
-Dvar:string=on
. These arguments are written in a pre-load a script that populates CMake cache, see also cmake -C
. This allows to overcome command line length limits. These arguments are set()
using the FORCE
argument, and therefore cannot be changed by the user. Arguments may use generator expressions
.CMAKE_CACHE_DEFAULT_ARGS <arg>...
-Dvar:string=on
. These arguments are written in a pre-load a script that populates CMake cache, see also cmake -C
. This allows to overcome command line length limits. These arguments can be used as default value that will be set if no previous value is found in the cache, and that the user can change later. Arguments may use generator expressions
.Build step options are:
BINARY_DIR <dir>
BUILD_COMMAND <cmd>...
BUILD_IN_SOURCE 1
BUILD_ALWAYS 1
BUILD_BYPRODUCTS <file>...
Install step options are:
INSTALL_DIR <dir>
INSTALL_COMMAND <cmd>...
Test step options are:
TEST_BEFORE_INSTALL 1
TEST_AFTER_INSTALL 1
TEST_EXCLUDE_FROM_MAIN 1
TEST_COMMAND <cmd>...
Output logging options are:
LOG_DOWNLOAD 1
LOG_UPDATE 1
LOG_CONFIGURE 1
LOG_BUILD 1
LOG_TEST 1
LOG_INSTALL 1
Steps can be given direct access to the terminal if possible. With the Ninja
generator, this places the steps in the console
pool
. Options are:
USES_TERMINAL_DOWNLOAD 1
USES_TERMINAL_UPDATE 1
USES_TERMINAL_CONFIGURE 1
USES_TERMINAL_BUILD 1
USES_TERMINAL_TEST 1
USES_TERMINAL_INSTALL 1
Other options are:
STEP_TARGETS <step-target>...
INDEPENDENT_STEP_TARGETS <step-target>...
The *_DIR
options specify directories for the project, with default directories computed as follows. If the PREFIX
option is given to ExternalProject_Add()
or the EP_PREFIX
directory property is set, then an external project is built and installed under the specified prefix:
TMP_DIR = <prefix>/tmp STAMP_DIR = <prefix>/src/<name>-stamp DOWNLOAD_DIR = <prefix>/src SOURCE_DIR = <prefix>/src/<name> BINARY_DIR = <prefix>/src/<name>-build INSTALL_DIR = <prefix>
Otherwise, if the EP_BASE
directory property is set then components of an external project are stored under the specified base:
TMP_DIR = <base>/tmp/<name> STAMP_DIR = <base>/Stamp/<name> DOWNLOAD_DIR = <base>/Download/<name> SOURCE_DIR = <base>/Source/<name> BINARY_DIR = <base>/Build/<name> INSTALL_DIR = <base>/Install/<name>
If no PREFIX
, EP_PREFIX
, or EP_BASE
is specified then the default is to set PREFIX
to <name>-prefix
. Relative paths are interpreted with respect to the build directory corresponding to the source directory in which ExternalProject_Add
is invoked.
If SOURCE_DIR
is explicitly set to an existing directory the project will be built from it. Otherwise a download step must be specified using one of the DOWNLOAD_COMMAND
, CVS_*
, SVN_*
, or URL
options. The URL
option may refer locally to a directory or source tarball, or refer to a remote tarball (e.g. http://.../src.tgz
).
If UPDATE_DISCONNECTED
is set, the update step is not executed automatically when building the main target. The update step can still be added as a step target and called manually. This is useful if you want to allow to build the project when you are disconnected from the network (you might still need the network for the download step). This is disabled by default. The directory property EP_UPDATE_DISCONNECTED
can be used to change the default value for all the external projects in the current directory and its subdirectories.
ExternalProject_Add_Step
The ExternalProject_Add_Step
function adds a custom step to an external project:
ExternalProject_Add_Step(<name> <step> [<option>...])
Options are:
COMMAND <cmd>...
COMMENT "<text>..."
DEPENDEES <step>...
DEPENDERS <step>...
DEPENDS <file>...
BYPRODUCTS <file>...
ALWAYS 1
EXCLUDE_FROM_MAIN 1
WORKING_DIRECTORY <dir>
LOG 1
USES_TERMINAL 1
The command line, comment, working directory, and byproducts of every standard and custom step are processed to replace tokens <SOURCE_DIR>
, <BINARY_DIR>
, <INSTALL_DIR>
, and <TMP_DIR>
with corresponding property values.
Any builtin step that specifies a <step>_COMMAND cmd...
or custom step that specifies a COMMAND cmd...
may specify additional command lines using the form COMMAND cmd...
. At build time the commands will be executed in order and aborted if any one fails. For example:
... BUILD_COMMAND make COMMAND echo done ...
specifies to run make
and then echo done
during the build step. Whether the current working directory is preserved between commands is not defined. Behavior of shell operators like &&
is not defined.
Arguments to <step>_COMMAND
or COMMAND
options may use generator expressions
.
ExternalProject_Get_Property
The ExternalProject_Get_Property
function retrieves external project target properties:
ExternalProject_Get_Property(<name> [prop1 [prop2 [...]]])
It stores property values in variables of the same name. Property names correspond to the keyword argument names of ExternalProject_Add
.
ExternalProject_Add_StepTargets
The ExternalProject_Add_StepTargets
function generates custom targets for the steps listed:
ExternalProject_Add_StepTargets(<name> [NO_DEPENDS] [step1 [step2 [...]]])
If NO_DEPENDS
is set, the target will not depend on the dependencies of the complete project. This is usually safe to use for the download, update, and patch steps that do not require that all the dependencies are updated and built. Using NO_DEPENDS
for other of the default steps might break parallel builds, so you should avoid, it. For custom steps, you should consider whether or not the custom commands requires that the dependencies are configured, built and installed.
If STEP_TARGETS
or INDEPENDENT_STEP_TARGETS
is set then ExternalProject_Add_StepTargets
is automatically called at the end of matching calls to ExternalProject_Add_Step
. Pass STEP_TARGETS
or INDEPENDENT_STEP_TARGETS
explicitly to individual ExternalProject_Add
calls, or implicitly to all ExternalProject_Add
calls by setting the directory properties EP_STEP_TARGETS
and EP_INDEPENDENT_STEP_TARGETS
. The INDEPENDENT
version of the argument and of the property will call ExternalProject_Add_StepTargets
with the NO_DEPENDS
argument.
If STEP_TARGETS
and INDEPENDENT_STEP_TARGETS
are not set, clients may still manually call ExternalProject_Add_StepTargets
after calling ExternalProject_Add
or ExternalProject_Add_Step
.
This functionality is provided to make it easy to drive the steps independently of each other by specifying targets on build command lines. For example, you may be submitting to a sub-project based dashboard, where you want to drive the configure portion of the build, then submit to the dashboard, followed by the build portion, followed by tests. If you invoke a custom target that depends on a step halfway through the step dependency chain, then all the previous steps will also run to ensure everything is up to date.
For example, to drive configure, build and test steps independently for each ExternalProject_Add
call in your project, write the following line prior to any ExternalProject_Add
calls in your CMakeLists.txt
file:
set_property(DIRECTORY PROPERTY EP_STEP_TARGETS configure build test)
ExternalProject_Add_StepDependencies
The ExternalProject_Add_StepDependencies
function add some dependencies for some external project step:
ExternalProject_Add_StepDependencies(<name> <step> [target1 [target2 [...]]])
This function takes care to set both target and file level dependencies, and will ensure that parallel builds will not break. It should be used instead of add_dependencies()
when adding a dependency for some of the step targets generated by ExternalProject
.
© 2000–2016 Kitware, Inc.
© 2000–2011 Insight Software Consortium
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.5/module/ExternalProject.html