mirror of
https://gitlab.kitware.com/cmake/cmake.git
synced 2026-09-26 04:09:35 +03:00
ExternalProject: Improve documentation
- Added clearer structure by grouping the options into logical sections. - Expanded the details for many of the options. - Added Examples section to show how to use the various commands. - Specifically highlighted that the contents of SOURCE_DIR may be lost if a download method is also provided. - Updated argument-matching regex to be more robust and account for the varying leading spaces before keywords in the docs. - Updated tests to account for slightly changed error messages.
This commit is contained in:
Craig Scott
+792
-345
@@ -5,413 +5,860 @@
|
||||
ExternalProject
|
||||
---------------
|
||||
|
||||
Create custom targets to build projects in external trees
|
||||
.. only:: html
|
||||
|
||||
.. contents::
|
||||
|
||||
External Project Definition
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. command:: ExternalProject_Add
|
||||
|
||||
The ``ExternalProject_Add`` function creates a custom target to drive
|
||||
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>...])
|
||||
ExternalProject_Add(<name> [<option>...])
|
||||
|
||||
General options are:
|
||||
The individual steps within the process can be driven independently if
|
||||
required (e.g. for CDash submission) and extra custom steps can be defined,
|
||||
along with the ability to control the step dependencies. The directory
|
||||
structure used for the management of the external project can also be
|
||||
customized. The function supports a large number of options which can be used
|
||||
to tailor the external project behavior.
|
||||
|
||||
``DEPENDS <projects>...``
|
||||
Targets on which the project depends
|
||||
``PREFIX <dir>``
|
||||
Root dir for entire project
|
||||
``LIST_SEPARATOR <sep>``
|
||||
Sep to be replaced by ; in cmd lines
|
||||
``TMP_DIR <dir>``
|
||||
Directory to store temporary files
|
||||
``STAMP_DIR <dir>``
|
||||
Directory to store step timestamps
|
||||
``EXCLUDE_FROM_ALL 1``
|
||||
The "all" target does not depend on this
|
||||
**Directory Options:**
|
||||
Most of the time, the default directory layout is sufficient. It is largely
|
||||
an implementation detail that the main project usually doesn't need to
|
||||
change. In some circumstances, however, control over the directory layout
|
||||
can be useful or necessary. The directory options are potentially more
|
||||
useful from the point of view that the main build can use the
|
||||
:command:`ExternalProject_Get_Property` command to retrieve their values,
|
||||
thereby allowing the main project to refer to build artifacts of the
|
||||
external project.
|
||||
|
||||
Download step options are:
|
||||
``PREFIX <dir>``
|
||||
Root directory for the external project. Unless otherwise noted below,
|
||||
all other directories associated with the external project will be
|
||||
created under here.
|
||||
|
||||
``DOWNLOAD_NAME <fname>``
|
||||
File name to store (if not end of URL)
|
||||
``DOWNLOAD_DIR <dir>``
|
||||
Directory to store downloaded files
|
||||
``DOWNLOAD_COMMAND <cmd>...``
|
||||
Command to download source tree
|
||||
``DOWNLOAD_NO_PROGRESS 1``
|
||||
Disable download progress reports
|
||||
``CVS_REPOSITORY <cvsroot>``
|
||||
CVSROOT of CVS repository
|
||||
``CVS_MODULE <mod>``
|
||||
Module to checkout from CVS repo
|
||||
``CVS_TAG <tag>``
|
||||
Tag to checkout from CVS repo
|
||||
``SVN_REPOSITORY <url>``
|
||||
URL of Subversion repo
|
||||
``SVN_REVISION -r<rev>``
|
||||
Revision to checkout from Subversion repo
|
||||
``SVN_USERNAME <username>``
|
||||
Username for Subversion checkout and update
|
||||
``SVN_PASSWORD <password>``
|
||||
Password for Subversion checkout and update
|
||||
``SVN_TRUST_CERT 1``
|
||||
Trust the Subversion server site certificate
|
||||
``GIT_REPOSITORY <url>``
|
||||
URL of git repo
|
||||
``GIT_TAG <tag>``
|
||||
Git branch name, commit id or tag
|
||||
``GIT_REMOTE_NAME <name>``
|
||||
The optional name of the remote, default to ``origin``
|
||||
``GIT_SUBMODULES <module>...``
|
||||
Git submodules that shall be updated, all if empty
|
||||
``GIT_SHALLOW 1``
|
||||
Tell Git to clone with ``--depth 1``. Use when ``GIT_TAG`` is not
|
||||
specified or when it names a branch in order to download only the
|
||||
tip of the branch without the rest of its history.
|
||||
``GIT_PROGRESS 1``
|
||||
Tell Git to clone with ``--progress``. For large projects, the clone step
|
||||
does not output anything which can make the build appear to have stalled.
|
||||
This option forces Git to output progress information during the clone step
|
||||
so that forward progress is indicated.
|
||||
``GIT_CONFIG <option>...``
|
||||
Tell Git to clone with ``--config <option>``. Use additional configuration
|
||||
parameters when cloning the project (``key=value`` as expected by ``git
|
||||
config``).
|
||||
``HG_REPOSITORY <url>``
|
||||
URL of mercurial repo
|
||||
``HG_TAG <tag>``
|
||||
Mercurial branch name, commit id or tag
|
||||
``URL /.../src.tgz [/.../src.tgz]...``
|
||||
Full path or URL(s) of source. Multiple URLs are allowed as mirrors.
|
||||
``URL_HASH ALGO=value``
|
||||
Hash of file at URL
|
||||
``URL_MD5 md5``
|
||||
Equivalent to URL_HASH MD5=md5
|
||||
``HTTP_USERNAME <username>``
|
||||
Username for download operation
|
||||
``HTTP_PASSWORD <username>``
|
||||
Password for download operation
|
||||
``HTTP_HEADER <header>``
|
||||
HTTP header for download operation. Suboption can be repeated several times.
|
||||
``TLS_VERIFY <bool>``
|
||||
Should certificate for https be checked
|
||||
``TLS_CAINFO <file>``
|
||||
Path to a certificate authority file
|
||||
``TIMEOUT <seconds>``
|
||||
Time allowed for file download operations
|
||||
``DOWNLOAD_NO_EXTRACT 1``
|
||||
Just download the file and do not extract it; the full path to the
|
||||
downloaded file is available as ``<DOWNLOADED_FILE>``.
|
||||
``TMP_DIR <dir>``
|
||||
Directory in which to store temporary files.
|
||||
|
||||
Update/Patch step options are:
|
||||
``STAMP_DIR <dir>``
|
||||
Directory in which to store the timestamps of each step. Log files from
|
||||
individual steps are also created in here (see *Logging Options* below).
|
||||
|
||||
``UPDATE_COMMAND <cmd>...``
|
||||
Source work-tree update command
|
||||
``UPDATE_DISCONNECTED 1``
|
||||
Never update automatically from the remote repository
|
||||
``PATCH_COMMAND <cmd>...``
|
||||
Command to patch downloaded source
|
||||
``DOWNLOAD_DIR <dir>``
|
||||
Directory in which to store downloaded files before unpacking them. This
|
||||
directory is only used by the URL download method, all other download
|
||||
methods use ``SOURCE_DIR`` directly instead.
|
||||
|
||||
Configure step options are:
|
||||
``SOURCE_DIR <dir>``
|
||||
Source directory into which downloaded contents will be unpacked, or for
|
||||
non-URL download methods, the directory in which the repository should be
|
||||
checked out, cloned, etc. If no download method is specified, this must
|
||||
point to an existing directory where the external project has already
|
||||
been unpacked or cloned/checked out.
|
||||
|
||||
``SOURCE_DIR <dir>``
|
||||
Source dir to be used for build
|
||||
``SOURCE_SUBDIR <dir>``
|
||||
Path to source CMakeLists.txt relative to ``SOURCE_DIR``
|
||||
``CONFIGURE_COMMAND <cmd>...``
|
||||
Build tree configuration command
|
||||
``CMAKE_COMMAND /.../cmake``
|
||||
Specify alternative cmake executable
|
||||
``CMAKE_GENERATOR <gen>``
|
||||
Specify generator for native build
|
||||
``CMAKE_GENERATOR_PLATFORM <platform>``
|
||||
Generator-specific platform name
|
||||
``CMAKE_GENERATOR_TOOLSET <toolset>``
|
||||
Generator-specific toolset name
|
||||
``CMAKE_ARGS <arg>...``
|
||||
Arguments to CMake command line.
|
||||
These arguments are passed to CMake command line, and can contain
|
||||
arguments other than cache values, see also
|
||||
:manual:`CMake Options <cmake(1)>`. 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
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||
``CMAKE_CACHE_ARGS <arg>...``
|
||||
Initial cache arguments, of the form ``-Dvar:string=on``.
|
||||
These arguments are written in a pre-load a script that populates
|
||||
CMake cache, see also :manual:`cmake -C <cmake(1)>`. This allows one to
|
||||
overcome command line length limits.
|
||||
These arguments are :command:`set` using the ``FORCE`` argument,
|
||||
and therefore cannot be changed by the user.
|
||||
Arguments may use
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||
``CMAKE_CACHE_DEFAULT_ARGS <arg>...``
|
||||
Initial default cache arguments, of the form ``-Dvar:string=on``.
|
||||
These arguments are written in a pre-load a script that populates
|
||||
CMake cache, see also :manual:`cmake -C <cmake(1)>`. This allows one 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
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||
.. note::
|
||||
If a download method is specified, any existing contents of the source
|
||||
directory may be deleted. Only the URL download method checks whether
|
||||
this directory is either missing or empty before initiating the
|
||||
download, stopping with an error if it is not empty. All other
|
||||
download methods silently discard any previous contents of the source
|
||||
directory.
|
||||
|
||||
Build step options are:
|
||||
``BINARY_DIR <dir>``
|
||||
Specify the build directory location. This option is ignored if
|
||||
``BUILD_IN_SOURCE`` is enabled.
|
||||
|
||||
``BINARY_DIR <dir>``
|
||||
Specify build dir location
|
||||
``BUILD_COMMAND <cmd>...``
|
||||
Command to drive the native build
|
||||
``BUILD_IN_SOURCE 1``
|
||||
Use source dir for build dir
|
||||
``BUILD_ALWAYS 1``
|
||||
No stamp file, build step always runs
|
||||
``BUILD_BYPRODUCTS <file>...``
|
||||
Files that will be generated by the build command but may or may
|
||||
not have their modification time updated by subsequent builds.
|
||||
``INSTALL_DIR <dir>``
|
||||
Installation prefix to be placed in the ``<INSTALL_DIR>`` placeholder.
|
||||
This does not actually configure the external project to install to
|
||||
the given prefix. That must be done by passing appropriate arguments
|
||||
to the external project configuration step, e.g. using ``<INSTALL_DIR>``.
|
||||
|
||||
Install step options are:
|
||||
If any of the above ``..._DIR`` options are not specified, their defaults
|
||||
are computed as follows. If the ``PREFIX`` option is given or the
|
||||
``EP_PREFIX`` directory property is set, then an external project is built
|
||||
and installed under the specified prefix::
|
||||
|
||||
``INSTALL_DIR <dir>``
|
||||
Installation prefix to be placed in the ``<INSTALL_DIR>`` placeholder.
|
||||
This does not actually configure the external project to install to
|
||||
the given prefix. That must be done by passing appropriate arguments
|
||||
to the external project configuration step, e.g. using ``<INSTALL_DIR>``.
|
||||
``INSTALL_COMMAND <cmd>...``
|
||||
Command to drive installation of the external project after it has been
|
||||
built. This only happens at the *build* time of the calling project.
|
||||
In order to install files from the external project alongside the
|
||||
locally-built files, a separate local :command:`install` call must be
|
||||
added to pick the files up from one of the external project trees.
|
||||
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>
|
||||
|
||||
Test step options are:
|
||||
Otherwise, if the ``EP_BASE`` directory property is set then components
|
||||
of an external project are stored under the specified base::
|
||||
|
||||
``TEST_BEFORE_INSTALL 1``
|
||||
Add test step executed before install step
|
||||
``TEST_AFTER_INSTALL 1``
|
||||
Add test step executed after install step
|
||||
``TEST_EXCLUDE_FROM_MAIN 1``
|
||||
Main target does not depend on the test step
|
||||
``TEST_COMMAND <cmd>...``
|
||||
Command to drive test
|
||||
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>
|
||||
|
||||
Output logging options are:
|
||||
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 :variable:`CMAKE_CURRENT_BINARY_DIR` at the
|
||||
point where ``ExternalProject_Add()`` is called.
|
||||
|
||||
``LOG_DOWNLOAD 1``
|
||||
Wrap download in script to log output
|
||||
``LOG_UPDATE 1``
|
||||
Wrap update in script to log output
|
||||
``LOG_CONFIGURE 1``
|
||||
Wrap configure in script to log output
|
||||
``LOG_BUILD 1``
|
||||
Wrap build in script to log output
|
||||
``LOG_TEST 1``
|
||||
Wrap test in script to log output
|
||||
``LOG_INSTALL 1``
|
||||
Wrap install in script to log output
|
||||
**Download Step Options:**
|
||||
A download method can be omitted if the ``SOURCE_DIR`` option is used to
|
||||
point to an existing non-empty directory. Otherwise, one of the download
|
||||
methods below must be specified (multiple download methods should not be
|
||||
given) or a custom ``DOWNLOAD_COMMAND`` provided.
|
||||
|
||||
Steps can be given direct access to the terminal if possible. With
|
||||
the :generator:`Ninja` generator, this places the steps in the
|
||||
``console`` :prop_gbl:`pool <JOB_POOLS>`. Options are:
|
||||
``DOWNLOAD_COMMAND <cmd>...``
|
||||
Overrides the command used for the download step
|
||||
(:manual:`generator expressions <cmake-generator-expressions(7)>` are
|
||||
supported). If this option is specified, all other download options will
|
||||
be ignored. Providing an empty string for ``<cmd>`` effectively disables
|
||||
the download step.
|
||||
|
||||
``USES_TERMINAL_DOWNLOAD 1``
|
||||
Give download terminal access.
|
||||
``USES_TERMINAL_UPDATE 1``
|
||||
Give update terminal access.
|
||||
``USES_TERMINAL_CONFIGURE 1``
|
||||
Give configure terminal access.
|
||||
``USES_TERMINAL_BUILD 1``
|
||||
Give build terminal access.
|
||||
``USES_TERMINAL_TEST 1``
|
||||
Give test terminal access.
|
||||
``USES_TERMINAL_INSTALL 1``
|
||||
Give install terminal access.
|
||||
*URL Download*
|
||||
``URL <url1> [<url2>...]``
|
||||
List of paths and/or URL(s) of the external project's source. When more
|
||||
than one URL is given, they are tried in turn until one succeeds. A URL
|
||||
may be an ordinary path in the local file system (in which case it
|
||||
must be the only URL provided) or any downloadable URL supported by the
|
||||
:command:`file(DOWNLOAD)` command. A local filesystem path may refer to
|
||||
either an existing directory or to an archive file, whereas a URL is
|
||||
expected to point to a file which can be treated as an archive. When an
|
||||
archive is used, it will be unpacked automatically unless the
|
||||
``DOWNLOAD_NO_EXTRACT`` option is set to prevent it. The archive type
|
||||
is determined by inspecting the actual content rather than using logic
|
||||
based on the file extension.
|
||||
|
||||
Other options are:
|
||||
``URL_HASH ALGO=<value>``
|
||||
Hash of the archive file to be downloaded. The ``<value>`` should be of
|
||||
the form ``algo=hashValue`` where ``algo`` can be any of the hashing
|
||||
algorithms supported by the :command:`file()` command. Specifying this
|
||||
option is strongly recommended for URL downloads, as it ensures the
|
||||
integrity of the downloaded content. It is also used as a check for a
|
||||
previously downloaded file, allowing connection to the remote location
|
||||
to be avoided altogether if the local directory already has a file from
|
||||
an earlier download that matches the specified hash.
|
||||
|
||||
``STEP_TARGETS <step-target>...``
|
||||
Generate custom targets for these steps
|
||||
``INDEPENDENT_STEP_TARGETS <step-target>...``
|
||||
Generate custom targets for these steps that do not depend on other
|
||||
external projects even if a dependency is set
|
||||
``URL_MD5 <md5>``
|
||||
Equivalent to ``URL_HASH MD5=<md5>``.
|
||||
|
||||
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::
|
||||
``DOWNLOAD_NAME <fname>``
|
||||
File name to use for the downloaded file. If not given, the end of the
|
||||
URL is used to determine the file name. This option is rarely needed,
|
||||
the default name is generally suitable and is not normally used outside
|
||||
of code internal to the ``ExternalProject`` module.
|
||||
|
||||
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>
|
||||
``DOWNLOAD_NO_EXTRACT <bool>``
|
||||
Allows the extraction part of the download step to be disabled by
|
||||
passing a boolean true value for this option. If this option is not
|
||||
given, the downloaded contents will be unpacked automatically if
|
||||
required. If extraction has been disabled, the full path to the
|
||||
downloaded file is available as ``<DOWNLOADED_FILE>`` in subsequent
|
||||
steps or as the property ``DOWNLOADED_FILE`` with the
|
||||
:command:`ExternalProject_Get_Property` command.
|
||||
|
||||
Otherwise, if the ``EP_BASE`` directory property is set then components
|
||||
of an external project are stored under the specified base::
|
||||
``DOWNLOAD_NO_PROGRESS <bool>``
|
||||
Can be used to disable logging the download progress. If this option is
|
||||
not given, download progress messages will be logged.
|
||||
|
||||
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>
|
||||
``TIMEOUT <seconds>``
|
||||
Maximum time allowed for file download operations.
|
||||
|
||||
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.
|
||||
``HTTP_USERNAME <username>``
|
||||
Username for the download operation if authentication is required.
|
||||
|
||||
If ``SOURCE_SUBDIR`` is set and no ``CONFIGURE_COMMAND`` is specified, the
|
||||
configure command will run CMake using the ``CMakeLists.txt`` located in the
|
||||
relative path specified by ``SOURCE_SUBDIR``, relative to the ``SOURCE_DIR``.
|
||||
If no ``SOURCE_SUBDIR`` is given, ``SOURCE_DIR`` is used.
|
||||
``HTTP_PASSWORD <password>``
|
||||
Password for the download operation if authentication is required.
|
||||
|
||||
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``).
|
||||
``HTTP_HEADER <header1> [<header2>...]``
|
||||
Provides an arbitrary list of HTTP headers for the download operation.
|
||||
This can be useful for accessing content in systems like AWS, etc.
|
||||
|
||||
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 one 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.
|
||||
``TLS_VERIFY <bool>``
|
||||
Specifies whether certificate verification should be performed for
|
||||
https URLs. If this option is not provided, the default behavior is
|
||||
determined by the ``CMAKE_TLS_VERIFY`` variable (see
|
||||
:command:`file(DOWNLOAD)`). If that is also not set, certificate
|
||||
verification will not be performed. In situations where ``URL_HASH``
|
||||
cannot be provided, this option can be an alternative verification
|
||||
measure.
|
||||
|
||||
.. command:: ExternalProject_Add_Step
|
||||
``TLS_CAINFO <file>``
|
||||
Specify a custom certificate authority file to use if ``TLS_VERIFY``
|
||||
is enabled. If this option is not specified, the value of the
|
||||
``CMAKE_TLS_CAINFO`` variable will be used instead (see
|
||||
:command:`file(DOWNLOAD)`)
|
||||
|
||||
The ``ExternalProject_Add_Step`` function adds a custom step to an
|
||||
external project::
|
||||
*Git*
|
||||
NOTE: A git version of 1.6.5 or later is required if this download method
|
||||
is used.
|
||||
|
||||
ExternalProject_Add_Step(<name> <step> [<option>...])
|
||||
``GIT_REPOSITORY <url>``
|
||||
URL of the git repository. Any URL understood by the ``git`` command
|
||||
may be used.
|
||||
|
||||
Options are:
|
||||
``GIT_TAG <tag>``
|
||||
Git branch name, tag or commit hash. Note that branch names and tags
|
||||
should generally be specified as remote names (i.e. ``origin/myBranch``
|
||||
rather than simply ``myBranch``). This ensures that if the remote end
|
||||
has its tag moved or branch rebased or history rewritten, the local
|
||||
clone will still be updated correctly. In general, however, specifying
|
||||
a commit hash should be preferred for a number of reasons:
|
||||
|
||||
``COMMAND <cmd>...``
|
||||
Command line invoked by this step
|
||||
``COMMENT "<text>..."``
|
||||
Text printed when step executes
|
||||
``DEPENDEES <step>...``
|
||||
Steps on which this step depends
|
||||
``DEPENDERS <step>...``
|
||||
Steps that depend on this step
|
||||
``DEPENDS <file>...``
|
||||
Files on which this step depends
|
||||
``BYPRODUCTS <file>...``
|
||||
Files that will be generated by this step but may or may not
|
||||
have their modification time updated by subsequent builds.
|
||||
``ALWAYS 1``
|
||||
No stamp file, step always runs
|
||||
``EXCLUDE_FROM_MAIN 1``
|
||||
Main target does not depend on this step
|
||||
``WORKING_DIRECTORY <dir>``
|
||||
Working directory for command
|
||||
``LOG 1``
|
||||
Wrap step in script to log output
|
||||
``USES_TERMINAL 1``
|
||||
Give the step direct access to the terminal if possible.
|
||||
- If the local clone already has the commit corresponding to the hash,
|
||||
no ``git fetch`` needs to be performed to check for changes each time
|
||||
CMake is re-run. This can result in a significant speed up if many
|
||||
external projects are being used.
|
||||
- Using a specific git hash ensures that the main project's own history
|
||||
is fully traceable to a specific point in the external project's
|
||||
evolution. If a branch or tag name is used instead, then checking out
|
||||
a specific commit of the main project doesn't necessarily pin the
|
||||
whole build to a specific point in the life of the external project.
|
||||
The lack of such deterministic behavior makes the main project lose
|
||||
traceability and repeatability.
|
||||
|
||||
The command line, comment, working directory, and byproducts of every
|
||||
standard and custom step are processed to replace tokens ``<SOURCE_DIR>``,
|
||||
``<SOURCE_SUBDIR>``, ``<BINARY_DIR>``, ``<INSTALL_DIR>``, and ``<TMP_DIR>``
|
||||
with corresponding property values.
|
||||
``GIT_REMOTE_NAME <name>``
|
||||
The optional name of the remote. If this option is not specified, it
|
||||
defaults to ``origin``.
|
||||
|
||||
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::
|
||||
``GIT_SUBMODULES <module>...``
|
||||
Specific git submodules that should also be updated. If this option is
|
||||
not provided, all git submodules will be updated.
|
||||
|
||||
... BUILD_COMMAND make COMMAND echo done ...
|
||||
``GIT_SHALLOW <bool>``
|
||||
When this option is enabled, the ``git clone`` operation will be given
|
||||
the ``--depth 1`` option. This performs a shallow clone, which avoids
|
||||
downloading the whole history and instead retrieves just the commit
|
||||
denoted by the ``GIT_TAG`` option.
|
||||
|
||||
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.
|
||||
``GIT_PROGRESS <bool>``
|
||||
When enabled, this option instructs the ``git clone`` operation to
|
||||
report its progress by passing it the ``--progress`` option. Without
|
||||
this option, the clone step for large projects may appear to make the
|
||||
build stall, since nothing will be logged until the clone operation
|
||||
finishes. While this option can be used to provide progress to prevent
|
||||
the appearance of the build having stalled, it may also make the build
|
||||
overly noisy if lots of external projects are used.
|
||||
|
||||
Arguments to ``<step>_COMMAND`` or ``COMMAND`` options may use
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||
``GIT_CONFIG <option1> [<option2>...]``
|
||||
Specify a list of config options to pass to ``git clone``. Each option
|
||||
listed will be transformed into its own ``--config <option>`` on the
|
||||
``git clone`` command line, with each option required to be in the
|
||||
form ``key=value``.
|
||||
|
||||
*Subversion*
|
||||
``SVN_REPOSITORY <url>``
|
||||
URL of the Subversion repository.
|
||||
|
||||
``SVN_REVISION -r<rev>``
|
||||
Revision to checkout from the Subversion repository.
|
||||
|
||||
``SVN_USERNAME <username>``
|
||||
Username for the Subversion checkout and update.
|
||||
|
||||
``SVN_PASSWORD <password>``
|
||||
Password for the Subversion checkout and update.
|
||||
|
||||
``SVN_TRUST_CERT <bool>``
|
||||
Specifies whether to trust the Subversion server site certificate. If
|
||||
enabled, the ``--trust-server-cert`` option is passed to the ``svn``
|
||||
checkout and update commands.
|
||||
|
||||
*Mercurial*
|
||||
``HG_REPOSITORY <url>``
|
||||
URL of the mercurial repository.
|
||||
|
||||
``HG_TAG <tag>``
|
||||
Mercurial branch name, tag or commit id.
|
||||
|
||||
*CVS*
|
||||
``CVS_REPOSITORY <cvsroot>``
|
||||
CVSROOT of the CVS repository.
|
||||
|
||||
``CVS_MODULE <mod>``
|
||||
Module to checkout from the CVS repository.
|
||||
|
||||
``CVS_TAG <tag>``
|
||||
Tag to checkout from the CVS repository.
|
||||
|
||||
**Update/Patch Step Options:**
|
||||
Whenever CMake is re-run, by default the external project's sources will be
|
||||
updated if the download method supports updates (e.g. a git repository
|
||||
would be checked if the ``GIT_TAG`` does not refer to a specific commit).
|
||||
|
||||
``UPDATE_COMMAND <cmd>...``
|
||||
Overrides the download method's update step with a custom command.
|
||||
The command may use
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||
|
||||
``UPDATE_DISCONNECTED <bool>``
|
||||
When enabled, this option causes the update step to be skipped. It does
|
||||
not, however, prevent the download step. The update step can still be
|
||||
added as a step target (see :command:`ExternalProject_Add_StepTargets`)
|
||||
and called manually. This is useful if you want to allow developers to
|
||||
build the project when disconnected from the network (the network may
|
||||
still be needed for the download step though).
|
||||
|
||||
When this option is present, it is generally advisable to make the value
|
||||
a cache variable under the developer's control rather than hard-coding
|
||||
it. If this option is not present, the default value is taken from the
|
||||
``EP_UPDATE_DISCONNECTED`` directory property. If that is also not
|
||||
defined, updates are performed as normal. The ``EP_UPDATE_DISCONNECTED``
|
||||
directory property is intended as a convenience for controlling the
|
||||
``UPDATE_DISCONNECTED`` behavior for an entire section of a project's
|
||||
directory hierarchy and may be a more convenient method of giving
|
||||
developers control over whether or not to perform updates (assuming the
|
||||
project also provides a cache variable or some other convenient method
|
||||
for setting the directory property).
|
||||
|
||||
``PATCH_COMMAND <cmd>...``
|
||||
Specifies a custom command to patch the sources after an update. By
|
||||
default, no patch command is defined. Note that it can be quite difficult
|
||||
to define an appropriate patch command that performs robustly, especially
|
||||
for download methods such as git where changing the ``GIT_TAG`` will not
|
||||
discard changes from a previous patch, but the patch command will be
|
||||
called again after updating to the new tag.
|
||||
|
||||
**Configure Step Options:**
|
||||
The configure step is run after the download and update steps. By default,
|
||||
the external project is assumed to be a CMake project, but this can be
|
||||
overridden if required.
|
||||
|
||||
``CONFIGURE_COMMAND <cmd>...``
|
||||
The default configure command runs CMake with options based on the main
|
||||
project. For non-CMake external projects, the ``CONFIGURE_COMMAND``
|
||||
option must be used to override this behavior
|
||||
(:manual:`generator expressions <cmake-generator-expressions(7)>` are
|
||||
supported). For projects that require no configure step, specify this
|
||||
option with an empty string as the command to execute.
|
||||
|
||||
``CMAKE_COMMAND /.../cmake``
|
||||
Specify an alternative cmake executable for the configure step (use an
|
||||
absolute path). This is generally not recommended, since it is
|
||||
usually desirable to use the same CMake version throughout the whole
|
||||
build. This option is ignored if a custom configure command has been
|
||||
specified with ``CONFIGURE_COMMAND``.
|
||||
|
||||
``CMAKE_GENERATOR <gen>``
|
||||
Override the CMake generator used for the configure step. Without this
|
||||
option, the same generator as the main build will be used. This option is
|
||||
ignored if a custom configure command has been specified with the
|
||||
``CONFIGURE_COMMAND`` option.
|
||||
|
||||
``CMAKE_GENERATOR_PLATFORM <platform>``
|
||||
Pass a generator-specific platform name to the CMake command (see
|
||||
:variable:`CMAKE_GENERATOR_PLATFORM`). It is an error to provide this
|
||||
option without the ``CMAKE_GENERATOR`` option.
|
||||
|
||||
``CMAKE_GENERATOR_TOOLSET <toolset>``
|
||||
Pass a generator-specific toolset name to the CMake command (see
|
||||
:variable:`CMAKE_GENERATOR_TOOLSET`). It is an error to provide this
|
||||
option without the ``CMAKE_GENERATOR`` option.
|
||||
|
||||
``CMAKE_ARGS <arg>...``
|
||||
The specified arguments are passed to the ``cmake`` command line. They
|
||||
can be any argument the ``cmake`` command understands, not just cache
|
||||
values defined by ``-D...`` arguments (see also
|
||||
:manual:`CMake Options <cmake(1)>`). In addition, arguments may use
|
||||
:manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||
|
||||
``CMAKE_CACHE_ARGS <arg>...``
|
||||
This is an alternate way of specifying cache variables where command line
|
||||
length issues may become a problem. The arguments are expected to be in
|
||||
the form ``-Dvar:STRING=value``, which are then transformed into
|
||||
CMake :command:`set` commands with the ``FORCE`` option used. These
|
||||
``set()`` commands are written to a pre-load script which is then applied
|
||||
using the :manual:`cmake -C <cmake(1)>` command line option. Arguments
|
||||
may use :manual:`generator expressions <cmake-generator-expressions(7)>`.
|
||||
|
||||
``CMAKE_CACHE_DEFAULT_ARGS <arg>...``
|
||||
This is the same as the ``CMAKE_CACHE_ARGS`` option except the ``set()``
|
||||
commands do not include the ``FORCE`` keyword. This means the values act
|
||||
as initial defaults only and will not override any variables already set
|
||||
from a previous run. Use this option with care, as it can lead to
|
||||
different behavior depending on whether the build starts from a fresh
|
||||
build directory or re-uses previous build contents.
|
||||
|
||||
``SOURCE_SUBDIR <dir>``
|
||||
When no ``CONFIGURE_COMMAND`` option is specified, the configure step
|
||||
assumes the external project has a ``CMakeLists.txt`` file at the top of
|
||||
its source tree (i.e. in ``SOURCE_DIR``). The ``SOURCE_SUBDIR`` option
|
||||
can be used to point to an alternative directory within the source tree
|
||||
to use as the top of the CMake source tree instead. This must be a
|
||||
relative path and it will be interpreted as being relative to
|
||||
``SOURCE_DIR``.
|
||||
|
||||
**Build Step Options:**
|
||||
If the configure step assumed the external project uses CMake as its build
|
||||
system, the build step will also. Otherwise, the build step will assume a
|
||||
Makefile-based build and simply run ``make`` with no arguments as the
|
||||
default build step. This can be overridden with custom build commands if
|
||||
required.
|
||||
|
||||
``BUILD_COMMAND <cmd>...``
|
||||
Overrides the default build command
|
||||
(:manual:`generator expressions <cmake-generator-expressions(7)>` are
|
||||
supported). If this option is not given, the default build command will
|
||||
be chosen to integrate with the main build in the most appropriate way
|
||||
(e.g. using recursive ``make`` for Makefile generators or
|
||||
``cmake --build`` if the project uses a CMake build). This option can be
|
||||
specified with an empty string as the command to make the build step do
|
||||
nothing.
|
||||
|
||||
``BUILD_IN_SOURCE <bool>``
|
||||
When this option is enabled, the build will be done directly within the
|
||||
external project's source tree. This should generally be avoided, the use
|
||||
of a separate build directory is usually preferred, but it can be useful
|
||||
when the external project assumes an in-source build. The ``BINARY_DIR``
|
||||
option should not be specified if building in-source.
|
||||
|
||||
``BUILD_ALWAYS <bool>``
|
||||
Enabling this option forces the build step to always be run. This can be
|
||||
the easiest way to robustly ensure that the external project's own build
|
||||
dependencies are evaluated rather than relying on the default
|
||||
success timestamp-based method. This option is not normally needed unless
|
||||
developers are expected to modify something the external project's build
|
||||
depends on in a way that is not detectable via the step target
|
||||
dependencies (e.g. ``SOURCE_DIR`` is used without a download method and
|
||||
developers might modify the sources in ``SOURCE_DIR``).
|
||||
|
||||
``BUILD_BYPRODUCTS <file>...``
|
||||
Specifies files that will be generated by the build command but which
|
||||
might or might not have their modification time updated by subsequent
|
||||
builds. These ultimately get passed through as ``BYPRODUCTS`` to the
|
||||
build step's own underlying call to :command:`add_custom_command`.
|
||||
|
||||
**Install Step Options:**
|
||||
If the configure step assumed the external project uses CMake as its build
|
||||
system, the install step will also. Otherwise, the install step will assume
|
||||
a Makefile-based build and simply run ``make install`` as the default build
|
||||
step. This can be overridden with custom install commands if required.
|
||||
|
||||
``INSTALL_COMMAND <cmd>...``
|
||||
The external project's own install step is invoked as part of the main
|
||||
project's *build*. It is done after the external project's build step
|
||||
and may be before or after the external project's test step (see the
|
||||
``TEST_BEFORE_INSTALL`` option below). The external project's install
|
||||
rules are not part of the main project's install rules, so if anything
|
||||
from the external project should be installed as part of the main build,
|
||||
these need to be specified in the main build as additional
|
||||
:command:`install` commands. The default install step builds the
|
||||
``install`` target of the external project, but this can be overridden
|
||||
with a custom command using this option
|
||||
(:manual:`generator expressions <cmake-generator-expressions(7)>` are
|
||||
supported). Passing an empty string as the ``<cmd>`` makes the install
|
||||
step do nothing.
|
||||
|
||||
**Test Step Options:**
|
||||
The test step is only defined if at least one of the following ``TEST_...``
|
||||
options are provided.
|
||||
|
||||
``TEST_COMMAND <cmd>...``
|
||||
Overrides the default test command
|
||||
(:manual:`generator expressions <cmake-generator-expressions(7)>` are
|
||||
supported). If this option is not given, the default behavior of the test
|
||||
step is to build the external project's own ``test`` target. This option
|
||||
can be specified with ``<cmd>`` as an empty string, which allows the test
|
||||
step to still be defined, but it will do nothing. Do not specify any of
|
||||
the other ``TEST_...`` options if providing an empty string as the test
|
||||
command, but prefer to omit all ``TEST_...`` options altogether if the
|
||||
test step target is not needed.
|
||||
|
||||
``TEST_BEFORE_INSTALL <bool>``
|
||||
When this option is enabled, the test step will be executed before the
|
||||
install step. The default behavior is for the test step to run after the
|
||||
install step.
|
||||
|
||||
``TEST_AFTER_INSTALL <bool>``
|
||||
This option is mainly useful as a way to indicate that the test step is
|
||||
desired but all default behavior is sufficient. Specifying this option
|
||||
with a boolean true value ensures the test step is defined and that it
|
||||
comes after the install step. If both ``TEST_BEFORE_INSTALL`` and
|
||||
``TEST_AFTER_INSTALL`` are enabled, the latter is silently ignored.
|
||||
|
||||
``TEST_EXCLUDE_FROM_MAIN <bool>``
|
||||
If enabled, the main build's default ALL target will not depend on the
|
||||
test step. This can be a useful way of ensuring the test step is defined
|
||||
but only gets invoked when manually requested.
|
||||
|
||||
**Output Logging Options:**
|
||||
Each of the following ``LOG_...`` options can be used to wrap the relevant
|
||||
step in a script to capture its output to files. The log files will be
|
||||
created in the ``STAMP_DIR`` directory with step-specific file names.
|
||||
|
||||
``LOG_DOWNLOAD <bool>``
|
||||
When enabled, the output of the download step is logged to files.
|
||||
|
||||
``LOG_UPDATE <bool>``
|
||||
When enabled, the output of the update step is logged to files.
|
||||
|
||||
``LOG_CONFIGURE <bool>``
|
||||
When enabled, the output of the configure step is logged to files.
|
||||
|
||||
``LOG_BUILD <bool>``
|
||||
When enabled, the output of the build step is logged to files.
|
||||
|
||||
``LOG_INSTALL <bool>``
|
||||
When enabled, the output of the install step is logged to files.
|
||||
|
||||
``LOG_TEST <bool>``
|
||||
When enabled, the output of the test step is logged to files.
|
||||
|
||||
**Terminal Access Options:**
|
||||
Steps can be given direct access to the terminal in some cases. Giving a
|
||||
step access to the terminal may allow it to receive terminal input if
|
||||
required, such as for authentication details not provided by other options.
|
||||
With the :generator:`Ninja` generator, these options place the steps in the
|
||||
``console`` :prop_gbl:`job pool <JOB_POOLS>`. Each step can be given access
|
||||
to the terminal individually via the following options:
|
||||
|
||||
``USES_TERMINAL_DOWNLOAD <bool>``
|
||||
Give the download step access to the terminal.
|
||||
|
||||
``USES_TERMINAL_UPDATE <bool>``
|
||||
Give the update step access to the terminal.
|
||||
|
||||
``USES_TERMINAL_CONFIGURE <bool>``
|
||||
Give the configure step access to the terminal.
|
||||
|
||||
``USES_TERMINAL_BUILD <bool>``
|
||||
Give the build step access to the terminal.
|
||||
|
||||
``USES_TERMINAL_INSTALL <bool>``
|
||||
Give the install step access to the terminal.
|
||||
|
||||
``USES_TERMINAL_TEST <bool>``
|
||||
Give the test step access to the terminal.
|
||||
|
||||
**Target Options:**
|
||||
``DEPENDS <targets>...``
|
||||
Specify other targets on which the external project depends. The other
|
||||
targets will be brought up to date before any of the external project's
|
||||
steps are executed. Because the external project uses additional custom
|
||||
targets internally for each step, the ``DEPENDS`` option is the most
|
||||
convenient way to ensure all of those steps depend on the other targets.
|
||||
Simply doing
|
||||
:command:`add_dependencies(\<name\> \<targets\>) <add_dependencies>` will
|
||||
not make any of the steps dependent on ``<targets>``.
|
||||
|
||||
``EXCLUDE_FROM_ALL <bool>``
|
||||
When enabled, this option excludes the external project from the default
|
||||
ALL target of the main build.
|
||||
|
||||
``STEP_TARGETS <step-target>...``
|
||||
Generate custom targets for the specified steps. This is required if the
|
||||
steps need to be triggered manually or if they need to be used as
|
||||
dependencies of other targets. If this option is not specified, the
|
||||
default value is taken from the ``EP_STEP_TARGETS`` directory property.
|
||||
See :command:`ExternalProject_Add_Step` below for further discussion of
|
||||
the effects of this option.
|
||||
|
||||
``INDEPENDENT_STEP_TARGETS <step-target>...``
|
||||
Generate custom targets for the specified steps and prevent these targets
|
||||
from having the usual dependencies applied to them. If this option is not
|
||||
specified, the default value is taken from the
|
||||
``EP_INDEPENDENT_STEP_TARGETS`` directory property. This option is mostly
|
||||
useful for allowing individual steps to be driven independently, such as
|
||||
for a CDash setup where each step should be initiated and reported
|
||||
individually rather than as one whole build. See
|
||||
:command:`ExternalProject_Add_Step` below for further discussion of the
|
||||
effects of this option.
|
||||
|
||||
**Miscellaneous Options:**
|
||||
``LIST_SEPARATOR <sep>``
|
||||
For any of the various ``..._COMMAND`` options, replace ``;`` with
|
||||
``<sep>`` in the specified command lines. This can be useful where list
|
||||
variables may be given in commands where they should end up as
|
||||
space-separated arguments (``<sep>`` would be a single space character
|
||||
string in this case).
|
||||
|
||||
``COMMAND <cmd>...``
|
||||
Any of the other ``..._COMMAND`` options can have additional commands
|
||||
appended to them by following them with as many ``COMMAND ...`` options
|
||||
as needed
|
||||
(:manual:`generator expressions <cmake-generator-expressions(7)>` are
|
||||
supported). For example::
|
||||
|
||||
ExternalProject_Add(example
|
||||
... # Download options, etc.
|
||||
BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
|
||||
COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
|
||||
COMMAND ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
|
||||
)
|
||||
|
||||
It should also be noted that each build step is created via a call to
|
||||
:command:`ExternalProject_Add_Step`. See that command's documentation for the
|
||||
automatic substitutions that are supported for some options.
|
||||
|
||||
Obtaining Project Properties
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. command:: ExternalProject_Get_Property
|
||||
|
||||
The ``ExternalProject_Get_Property`` function retrieves external project
|
||||
The ``ExternalProject_Get_Property()`` function retrieves external project
|
||||
target properties::
|
||||
|
||||
ExternalProject_Get_Property(<name> [prop1 [prop2 [...]]])
|
||||
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``.
|
||||
The function stores property values in variables of the same name. Property
|
||||
names correspond to the keyword argument names of ``ExternalProject_Add()``.
|
||||
For example, the source directory might be retrieved like so:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
ExternalProject_Get_property(myExtProj SOURCE_DIR)
|
||||
message("Source dir of myExtProj = ${SOURCE_DIR}")
|
||||
|
||||
Explicit Step Management
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The ``ExternalProject_Add()`` function on its own is often sufficient for
|
||||
incorporating an external project into the main build. Certain scenarios
|
||||
require additional work to implement desired behavior, such as adding in a
|
||||
custom step or making steps available as manually triggerable targets. The
|
||||
``ExternalProject_Add_Step()``, ``ExternalProject_Add_StepTargets()`` and
|
||||
``ExternalProject_Add_StepDependencies`` functions provide the lower level
|
||||
control needed to implement such step-level capabilities.
|
||||
|
||||
.. command:: ExternalProject_Add_Step
|
||||
|
||||
The ``ExternalProject_Add_Step()`` function specifies an additional custom
|
||||
step for an external project defined by an earlier call to
|
||||
:command:`ExternalProject_Add`::
|
||||
|
||||
ExternalProject_Add_Step(<name> <step> [<option>...])
|
||||
|
||||
``<name>`` is the same as the name passed to the original call to
|
||||
:command:`ExternalProject_Add`. The specified ``<step>`` must not be one of
|
||||
the pre-defined steps (``mkdir``, ``download``, ``update``, ``skip-update``,
|
||||
``patch``, ``configure``, ``build``, ``install`` or ``test``). The supported
|
||||
options are:
|
||||
|
||||
``COMMAND <cmd>...``
|
||||
The command line to be executed by this custom step
|
||||
(:manual:`generator expressions <cmake-generator-expressions(7)>` are
|
||||
supported). This option can be repeated multiple times to specify multiple
|
||||
commands to be executed in order.
|
||||
|
||||
``COMMENT "<text>..."``
|
||||
Text to be printed when the custom step executes.
|
||||
|
||||
``DEPENDEES <step>...``
|
||||
Other steps (custom or pre-defined) on which this step depends.
|
||||
|
||||
``DEPENDERS <step>...``
|
||||
Other steps (custom or pre-defined) that depend on this new custom step.
|
||||
|
||||
``DEPENDS <file>...``
|
||||
Files on which this custom step depends.
|
||||
|
||||
``BYPRODUCTS <file>...``
|
||||
Files that will be generated by this custom step but which might or might
|
||||
not have their modification time updated by subsequent builds. This list of
|
||||
files will ultimately be passed through as the ``BYPRODUCTS`` option to the
|
||||
:command:`add_custom_command` used to implement the custom step internally.
|
||||
|
||||
``ALWAYS <bool>``
|
||||
When enabled, this option specifies that the custom step should always be
|
||||
run (i.e. that it is always considered out of date).
|
||||
|
||||
``EXCLUDE_FROM_MAIN <bool>``
|
||||
When enabled, this option specifies that the external project's main target
|
||||
does not depend on the custom step.
|
||||
|
||||
``WORKING_DIRECTORY <dir>``
|
||||
Specifies the working directory to set before running the custom step's
|
||||
command. If this option is not specified, the directory will be the value
|
||||
of the :variable:`CMAKE_CURRENT_BINARY_DIR` at the point where
|
||||
``ExternalProject_Add_Step()`` was called.
|
||||
|
||||
``LOG <bool>``
|
||||
If set, this causes the output from the custom step to be captured to files
|
||||
in the external project's ``STAMP_DIR``.
|
||||
|
||||
``USES_TERMINAL <bool>``
|
||||
If enabled, this gives the custom step direct access to the terminal if
|
||||
possible.
|
||||
|
||||
The command line, comment, working directory and byproducts of every
|
||||
standard and custom step are processed to replace the tokens
|
||||
``<SOURCE_DIR>``, ``<SOURCE_SUBDIR>``, ``<BINARY_DIR>``, ``<INSTALL_DIR>``
|
||||
and ``<TMP_DIR>`` with their corresponding property values defined in the
|
||||
original call to :command:`ExternalProject_Add`.
|
||||
|
||||
.. command:: ExternalProject_Add_StepTargets
|
||||
|
||||
The ``ExternalProject_Add_StepTargets`` function generates custom
|
||||
targets for the steps listed::
|
||||
The ``ExternalProject_Add_StepTargets()`` function generates targets for the
|
||||
steps listed. The name of each created target will be of the form
|
||||
``<name>-<step>``::
|
||||
|
||||
ExternalProject_Add_StepTargets(<name> [NO_DEPENDS] [step1 [step2 [...]]])
|
||||
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.
|
||||
Creating a target for a step allows it to be used as a dependency of another
|
||||
target or to be triggered manually. Having targets for specific steps also
|
||||
allows them to be driven 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.
|
||||
|
||||
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 the ``NO_DEPENDS`` option is specified, the step target will not depend on
|
||||
the dependencies of the external project (i.e. on any dependencies of the
|
||||
``<name>`` custom target created by :command:`ExternalProject_Add`). This is
|
||||
usually safe for the ``download``, ``update`` and ``patch`` steps, since they
|
||||
do not typically require that the dependencies are updated and built. Using
|
||||
``NO_DEPENDS`` for any of the other pre-defined steps, however, may break
|
||||
parallel builds. Only use ``NO_DEPENDS`` where it is certain that the named
|
||||
steps genuinely do not have dependencies. For custom steps, consider whether
|
||||
or not the custom commands require the dependencies to be configured, built
|
||||
and installed.
|
||||
|
||||
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``.
|
||||
Internally, :command:`ExternalProject_Add` calls
|
||||
:command:`ExternalProject_Add_Step` to create each step. If any
|
||||
``STEP_TARGETS`` or ``INDEPENDENT_STEP_TARGETS`` were specified, then
|
||||
``ExternalProject_Add_StepTargets()`` will also be called after
|
||||
:command:`ExternalProject_Add_Step`. ``INDEPENDENT_STEP_TARGETS`` have the
|
||||
``NO_DEPENDS`` option set, whereas ``STEP_TARGETS`` do not. Other than that,
|
||||
the two options result in ``ExternalProject_Add_StepTargets()`` being called
|
||||
in the same way. Even if a step is not mentioned in either of those two
|
||||
options, ``ExternalProject_Add_StepTargets()`` can still be called later to
|
||||
manually define a target for the 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)
|
||||
The ``STEP_TARGETS`` and ``INDEPENDENT_STEP_TARGETS`` options for
|
||||
:command:`ExternalProject_Add` are generally the easiest way to ensure
|
||||
targets are created for specific steps of interest. For custom steps,
|
||||
``ExternalProject_Add_StepTargets()`` must be called explicitly if a target
|
||||
should also be created for that custom step. An alternative to these two
|
||||
options is to populate the ``EP_STEP_TARGETS`` and
|
||||
``EP_INDEPENDENT_STEP_TARGETS`` directory properties. These act as defaults
|
||||
for the step target options and can save having to repeatedly specify the
|
||||
same set of step targets when multiple external projects are being defined.
|
||||
|
||||
.. command:: ExternalProject_Add_StepDependencies
|
||||
|
||||
The ``ExternalProject_Add_StepDependencies`` function add some
|
||||
dependencies for some external project step::
|
||||
The ``ExternalProject_Add_StepDependencies()`` function can be used to add
|
||||
dependencies to a step. The dependencies added must be targets CMake already
|
||||
knows about (these can be ordinary executable or library targets, custom
|
||||
targets or even step targets of another external project)::
|
||||
|
||||
ExternalProject_Add_StepDependencies(<name> <step> [target1 [target2 [...]]])
|
||||
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
|
||||
:command:`add_dependencies` whenever adding a dependency for some of the step
|
||||
targets generated by the ``ExternalProject`` module.
|
||||
|
||||
Examples
|
||||
^^^^^^^^
|
||||
|
||||
The following example shows how to download and build a hypothetical project
|
||||
called *FooBar* from github:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
include(ExternalProject)
|
||||
ExternalProject_Add(foobar
|
||||
GIT_REPOSITORY git@github.com:FooCo/FooBar.git
|
||||
GIT_TAG origin/release/1.2.3
|
||||
)
|
||||
|
||||
For the sake of the example, also define a second hypothetical external project
|
||||
called *SecretSauce*, which is downloaded from a web server. Two URLs are given
|
||||
to take advantage of a faster internal network if available, with a fallback to
|
||||
a slower external server. The project is a typical ``Makefile`` project with no
|
||||
configure step, so some of the default commands are overridden. The build is
|
||||
only required to build the *sauce* target:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
find_program(MAKE_EXE NAMES gmake nmake make)
|
||||
ExternalProject_Add(secretsauce
|
||||
URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
|
||||
https://www.somecompany.com/downloads/sauce-2.7.zip
|
||||
URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
|
||||
CONFIGURE_COMMAND ""
|
||||
BUILD_COMMAND ${MAKE_EXE} sauce
|
||||
)
|
||||
|
||||
Suppose the build step of ``secretsauce`` requires that ``foobar`` must already
|
||||
be built. This could be enforced like so:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
ExternalProject_Add_StepDependencies(secretsauce build foobar)
|
||||
|
||||
Another alternative would be to create a custom target for ``foobar``'s build
|
||||
step and make ``secretsauce`` depend on that rather than the whole ``foobar``
|
||||
project. This would mean ``foobar`` only needs to be built, it doesn't need to
|
||||
run its install or test steps before ``secretsauce`` can be built. The
|
||||
dependency can also be defined along with the ``secretsauce`` project:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
ExternalProject_Add_StepTargets(foobar build)
|
||||
ExternalProject_Add(secretsauce
|
||||
URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
|
||||
https://www.somecompany.com/downloads/sauce-2.7.zip
|
||||
URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
|
||||
CONFIGURE_COMMAND ""
|
||||
BUILD_COMMAND ${MAKE_EXE} sauce
|
||||
DEPENDS foobar-build
|
||||
)
|
||||
|
||||
Instead of calling :command:`ExternalProject_Add_StepTargets`, the target could
|
||||
be defined along with the ``foobar`` project itself:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
ExternalProject_Add(foobar
|
||||
GIT_REPOSITORY git@github.com:FooCo/FooBar.git
|
||||
GIT_TAG origin/release/1.2.3
|
||||
STEP_TARGETS build
|
||||
)
|
||||
|
||||
If many external projects should have the same set of step targets, setting a
|
||||
directory property may be more convenient. The ``build`` step target could be
|
||||
created automatically by setting the ``EP_STEP_TARGETS`` directory property
|
||||
before creating the external projects with :command:`ExternalProject_Add`:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)
|
||||
|
||||
Lastly, suppose that ``secretsauce`` provides a script called ``makedoc`` which
|
||||
can be used to generate its own documentation. Further suppose that the script
|
||||
expects the output directory to be provided as the only parameter and that it
|
||||
should be run from the ``secretsauce`` source directory. A custom step and a
|
||||
custom target to trigger the script can be defined like so:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
ExternalProject_Add_Step(secretsauce docs
|
||||
COMMAND <SOURCE_DIR>/makedoc <BINARY_DIR>
|
||||
WORKING_DIRECTORY <SOURCE_DIR>
|
||||
COMMENT "Building secretsauce docs"
|
||||
ALWAYS TRUE
|
||||
EXCLUDE_FROM_MAIN TRUE
|
||||
)
|
||||
ExternalProject_Add_StepTargets(secretsauce docs)
|
||||
|
||||
The custom step could then be triggered from the main build like so::
|
||||
|
||||
cmake --build . --target secretsauce-docs
|
||||
|
||||
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 :command:`add_dependencies()` when adding
|
||||
a dependency for some of the step targets generated by
|
||||
``ExternalProject``.
|
||||
#]=======================================================================]
|
||||
|
||||
# Pre-compute a regex to match documented keywords for each command.
|
||||
math(EXPR _ep_documentation_line_count "${CMAKE_CURRENT_LIST_LINE} - 16")
|
||||
math(EXPR _ep_documentation_line_count "${CMAKE_CURRENT_LIST_LINE} - 4")
|
||||
file(STRINGS "${CMAKE_CURRENT_LIST_FILE}" lines
|
||||
LIMIT_COUNT ${_ep_documentation_line_count}
|
||||
REGEX "^\\.\\. command:: [A-Za-z0-9_]+|^ ``[A-Z0-9_]+ .*``$")
|
||||
REGEX "^\\.\\. command:: [A-Za-z0-9_]+|^ +``[A-Z0-9_]+ [^`]*``$")
|
||||
foreach(line IN LISTS lines)
|
||||
if("${line}" MATCHES "^\\.\\. command:: ([A-Za-z0-9_]+)")
|
||||
if(_ep_func)
|
||||
@@ -421,7 +868,7 @@ foreach(line IN LISTS lines)
|
||||
#message("function [${_ep_func}]")
|
||||
set(_ep_keywords_${_ep_func} "^(")
|
||||
set(_ep_keyword_sep)
|
||||
elseif("${line}" MATCHES "^ ``([A-Z0-9_]+) .*``$")
|
||||
elseif("${line}" MATCHES "^ +``([A-Z0-9_]+) [^`]*``$")
|
||||
set(_ep_key "${CMAKE_MATCH_1}")
|
||||
#message(" keyword [${_ep_key}]")
|
||||
string(APPEND _ep_keywords_${_ep_func}
|
||||
@@ -504,7 +951,7 @@ define_property(DIRECTORY PROPERTY "EP_STEP_TARGETS" INHERITED
|
||||
BRIEF_DOCS
|
||||
"List of ExternalProject steps that automatically get corresponding targets"
|
||||
FULL_DOCS
|
||||
"These targets will be dependent on the main target dependencies"
|
||||
"These targets will be dependent on the main target dependencies. "
|
||||
"See documentation of the ExternalProject_Add_StepTargets() function in the "
|
||||
"ExternalProject module."
|
||||
)
|
||||
@@ -513,7 +960,7 @@ define_property(DIRECTORY PROPERTY "EP_INDEPENDENT_STEP_TARGETS" INHERITED
|
||||
BRIEF_DOCS
|
||||
"List of ExternalProject steps that automatically get corresponding targets"
|
||||
FULL_DOCS
|
||||
"These targets will not be dependent on the main target dependencies"
|
||||
"These targets will not be dependent on the main target dependencies. "
|
||||
"See documentation of the ExternalProject_Add_StepTargets() function in the "
|
||||
"ExternalProject module."
|
||||
)
|
||||
@@ -2012,12 +2459,12 @@ function(_ep_add_download_command name)
|
||||
" ${source_dir}\n"
|
||||
"is not an existing non-empty directory. Please specify one of:\n"
|
||||
" * SOURCE_DIR with an existing non-empty directory\n"
|
||||
" * DOWNLOAD_COMMAND\n"
|
||||
" * URL\n"
|
||||
" * GIT_REPOSITORY\n"
|
||||
" * SVN_REPOSITORY\n"
|
||||
" * HG_REPOSITORY\n"
|
||||
" * CVS_REPOSITORY and CVS_MODULE\n"
|
||||
" * SVN_REVISION\n"
|
||||
" * DOWNLOAD_COMMAND"
|
||||
" * CVS_REPOSITORY and CVS_MODULE"
|
||||
)
|
||||
endif()
|
||||
endif()
|
||||
|
||||
@@ -6,12 +6,12 @@
|
||||
is not an existing non-empty directory. Please specify one of:
|
||||
|
||||
\* SOURCE_DIR with an existing non-empty directory
|
||||
\* DOWNLOAD_COMMAND
|
||||
\* URL
|
||||
\* GIT_REPOSITORY
|
||||
\* SVN_REPOSITORY
|
||||
\* HG_REPOSITORY
|
||||
\* CVS_REPOSITORY and CVS_MODULE
|
||||
\* SVN_REVISION
|
||||
\* DOWNLOAD_COMMAND
|
||||
Call Stack \(most recent call first\):
|
||||
.*/Modules/ExternalProject.cmake:[0-9]+ \(_ep_add_download_command\)
|
||||
NoOptions.cmake:[0-9]+ \(ExternalProject_Add\)
|
||||
|
||||
@@ -6,12 +6,12 @@
|
||||
is not an existing non-empty directory. Please specify one of:
|
||||
|
||||
\* SOURCE_DIR with an existing non-empty directory
|
||||
\* DOWNLOAD_COMMAND
|
||||
\* URL
|
||||
\* GIT_REPOSITORY
|
||||
\* SVN_REPOSITORY
|
||||
\* HG_REPOSITORY
|
||||
\* CVS_REPOSITORY and CVS_MODULE
|
||||
\* SVN_REVISION
|
||||
\* DOWNLOAD_COMMAND
|
||||
Call Stack \(most recent call first\):
|
||||
.*/Modules/ExternalProject.cmake:[0-9]+ \(_ep_add_download_command\)
|
||||
SourceEmpty.cmake:[0-9]+ \(ExternalProject_Add\)
|
||||
|
||||
@@ -6,12 +6,12 @@
|
||||
is not an existing non-empty directory. Please specify one of:
|
||||
|
||||
\* SOURCE_DIR with an existing non-empty directory
|
||||
\* DOWNLOAD_COMMAND
|
||||
\* URL
|
||||
\* GIT_REPOSITORY
|
||||
\* SVN_REPOSITORY
|
||||
\* HG_REPOSITORY
|
||||
\* CVS_REPOSITORY and CVS_MODULE
|
||||
\* SVN_REVISION
|
||||
\* DOWNLOAD_COMMAND
|
||||
Call Stack \(most recent call first\):
|
||||
.*/Modules/ExternalProject.cmake:[0-9]+ \(_ep_add_download_command\)
|
||||
SourceMissing.cmake:[0-9]+ \(ExternalProject_Add\)
|
||||
|
||||
Reference in New Issue
Block a user