# ExternalProject

Create custom targets to build projects in external trees

`ExternalProject_Add`

  The `ExternalProject_Add` function creates a custom target to drive download, update/patch, configure, build, install and test steps of an external project:

      ExternalProject_Add(<name> [<option>...])

  General options are:

  `DEPENDS <projects>...`
    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 `CMake Options`. Arguments in the form `-Dvar:string=on` are always passed to the command line, and therefore cannot be changed by the user. Arguments may use `generator expressions`.
  `CMAKE_CACHE_ARGS <arg>...`
    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 `cmake -C`. This allows one to overcome command line length limits. These arguments are `set()` using the `FORCE` argument, and therefore cannot be changed by the user. Arguments may use `generator expressions`.
  `CMAKE_CACHE_DEFAULT_ARGS <arg>...`
    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 `cmake -C`. 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 `generator expressions`.

  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 `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 `Ninja` generator, this places the steps in the `console` `pool`. 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_Step`

  The `ExternalProject_Add_Step` function adds a custom step to an external project:

      ExternalProject_Add_Step(<name> <step> [<option>...])

  Options are:

  `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.

  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.

Any builtin step that specifies a `<step>_COMMAND cmd...` or custom step that specifies a `COMMAND cmd...` may specify additional command lines using the form `COMMAND cmd...`. At build time the commands will be executed in order and aborted if any one fails. For example:

    ... BUILD_COMMAND make COMMAND echo done ...

specifies to run `make` and then `echo done` during the build step. Whether the current working directory is preserved between commands is not defined. Behavior of shell operators like `&&` is not defined.

Arguments to `<step>_COMMAND` or `COMMAND` options may use `generator expressions`.

`ExternalProject_Get_Property`

  The `ExternalProject_Get_Property` function retrieves external project target properties:

      ExternalProject_Get_Property(<name> [prop1 [prop2 [...]]])

  It stores property values in variables of the same name. Property names correspond to the keyword argument names of `ExternalProject_Add`.

`ExternalProject_Add_StepTargets`

  The `ExternalProject_Add_StepTargets` function generates custom targets for the steps listed:

      ExternalProject_Add_StepTargets(<name> [NO_DEPENDS] [step1 [step2 [...]]])

If `NO_DEPENDS` is set, the target will not depend on the dependencies of the complete project. This is usually safe to use for the download, update, and patch steps that do not require that all the dependencies are updated and built. Using `NO_DEPENDS` for other of the default steps might break parallel builds, so you should avoid, it. For custom steps, you should consider whether or not the custom commands requires that the dependencies are configured, built and installed.

If `STEP_TARGETS` or `INDEPENDENT_STEP_TARGETS` is set then `ExternalProject_Add_StepTargets` is automatically called at the end of matching calls to `ExternalProject_Add_Step`. Pass `STEP_TARGETS` or `INDEPENDENT_STEP_TARGETS` explicitly to individual `ExternalProject_Add` calls, or implicitly to all `ExternalProject_Add` calls by setting the directory properties `EP_STEP_TARGETS` and `EP_INDEPENDENT_STEP_TARGETS`. The `INDEPENDENT` version of the argument and of the property will call `ExternalProject_Add_StepTargets` with the `NO_DEPENDS` argument.

If `STEP_TARGETS` and `INDEPENDENT_STEP_TARGETS` are not set, clients may still manually call `ExternalProject_Add_StepTargets` after calling `ExternalProject_Add` or `ExternalProject_Add_Step`.

This functionality is provided to make it easy to drive the steps independently of each other by specifying targets on build command lines. For example, you may be submitting to a sub-project based dashboard, where you want to drive the configure portion of the build, then submit to the dashboard, followed by the build portion, followed by tests. If you invoke a custom target that depends on a step halfway through the step dependency chain, then all the previous steps will also run to ensure everything is up to date.

For example, to drive configure, build and test steps independently for each `ExternalProject_Add` call in your project, write the following line prior to any `ExternalProject_Add` calls in your `CMakeLists.txt` file:

    set_property(DIRECTORY PROPERTY EP_STEP_TARGETS configure build test)

`ExternalProject_Add_StepDependencies`

  The `ExternalProject_Add_StepDependencies` function add some dependencies for some external project step:

      ExternalProject_Add_StepDependencies(<name> <step> [target1 [target2 [...]]])

  This function takes care to set both target and file level dependencies, and will ensure that parallel builds will not break. It should be used instead of `add_dependencies()` when adding a dependency for some of the step targets generated by `ExternalProject`.