Commit 8842a027 authored by Craig Scott's avatar Craig Scott

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.
parent 2ef3527d
......@@ -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>...])
General options are:
``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
Download step options are:
``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>``.
Update/Patch step options are:
``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
Configure step options are:
``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)>`.
Build step options are:
``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 step options are:
``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.
Test step options are:
``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
Output logging options are:
``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
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:
``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.
Other options are:
``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
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_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.
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 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.
ExternalProject_Add(<name> [<option>...])
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.
**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.
``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.
``TMP_DIR <dir>``
Directory in which to store temporary files.
``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).
``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.
``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.
.. 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.
``BINARY_DIR <dir>``
Specify the build directory location. This option is ignored if
``BUILD_IN_SOURCE`` is enabled.
``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>``.
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::
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 :variable:`CMAKE_CURRENT_BINARY_DIR` at the
point where ``ExternalProject_Add()`` is called.
**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.
``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.
*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.
``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.
``URL_MD5 <md5>``
Equivalent to ``URL_HASH MD5=<md5>``.
``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.
``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.
``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.
``TIMEOUT <seconds>``
Maximum time allowed for file download operations.
``HTTP_USERNAME <username>``
Username for the download operation if authentication is required.
``HTTP_PASSWORD <password>``
Password for the download operation if authentication is required.
``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.
``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.
``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)`)
*Git*
NOTE: A git version of 1.6.5 or later is required if this download method
is used.
``GIT_REPOSITORY <url>``
URL of the git repository. Any URL understood by the ``git`` command
may be used.
``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:
- 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.
``GIT_REMOTE_NAME <name>``
The optional name of the remote. If this option is not specified, it
defaults to ``origin``.
``GIT_SUBMODULES <module>...``
Specific git submodules that should also be updated. If this option is
not provided, all git submodules will be updated.
``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.
``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.
``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