diff options
| -rw-r--r-- | Modules/ExternalProject.cmake | 465 |
1 files changed, 277 insertions, 188 deletions
diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake index d6a6b72..a92f20c 100644 --- a/Modules/ExternalProject.cmake +++ b/Modules/ExternalProject.cmake @@ -1,187 +1,276 @@ -#.rst: -# ExternalProject -# --------------- -# -# Create custom targets to build projects in external trees -# -# The ``ExternalProject_Add`` function creates a custom target to drive -# download, update/patch, configure, build, install and test steps of an -# external project: -# -# .. code-block:: cmake -# -# ExternalProject_Add(<name> # Name for custom target -# [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-------------- -# [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 john ] # Username for Subversion checkout and update -# [SVN_PASSWORD doe ] # 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_SUBMODULES modules...] # Git submodules that shall be updated, all if empty -# [HG_REPOSITORY url] # URL of mercurial repo -# [HG_TAG tag] # Mercurial branch name, commit id or tag -# [URL /.../src.tgz] # Full path or URL of source -# [URL_HASH ALGO=value] # Hash of file at URL -# [URL_MD5 md5] # Equivalent to URL_HASH MD5=md5 -# [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 -# #--Update/Patch step---------- -# [UPDATE_COMMAND cmd...] # Source work-tree update command -# [PATCH_COMMAND cmd...] # Command to patch downloaded source -# #--Configure step------------- -# [SOURCE_DIR dir] # Source dir to be used for build -# [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 p] # Generator-specific platform name -# [CMAKE_GENERATOR_TOOLSET t] # Generator-specific toolset name -# [CMAKE_ARGS args...] # Arguments to CMake command line -# [CMAKE_CACHE_ARGS args...] # Initial cache arguments, of the form -Dvar:string=on -# #--Build step----------------- -# [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 -# #--Install step--------------- -# [INSTALL_DIR dir] # Installation prefix -# [INSTALL_COMMAND cmd...] # Command to drive install after build -# #--Test step------------------ -# [TEST_BEFORE_INSTALL 1] # Add test step executed before install step -# [TEST_AFTER_INSTALL 1] # Add test step executed after install step -# [TEST_COMMAND cmd...] # Command to drive test -# #--Output logging------------- -# [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 -# #--Custom targets------------- -# [STEP_TARGETS st1 st2 ...] # Generate custom targets for these steps -# ) -# -# The ``*_DIR`` options specify directories for the project, with default -# directories computed as follows. If the ``PREFIX`` option is given to -# ``ExternalProject_Add()`` or the ``EP_PREFIX`` directory property is set, -# then an external project is built and installed under the specified prefix:: -# -# TMP_DIR = <prefix>/tmp -# STAMP_DIR = <prefix>/src/<name>-stamp -# DOWNLOAD_DIR = <prefix>/src -# SOURCE_DIR = <prefix>/src/<name> -# BINARY_DIR = <prefix>/src/<name>-build -# INSTALL_DIR = <prefix> -# -# Otherwise, if the ``EP_BASE`` directory property is set then components -# of an external project are stored under the specified base:: -# -# TMP_DIR = <base>/tmp/<name> -# STAMP_DIR = <base>/Stamp/<name> -# DOWNLOAD_DIR = <base>/Download/<name> -# SOURCE_DIR = <base>/Source/<name> -# BINARY_DIR = <base>/Build/<name> -# INSTALL_DIR = <base>/Install/<name> -# -# If no ``PREFIX``, ``EP_PREFIX``, or ``EP_BASE`` is specified then the -# default is to set ``PREFIX`` to ``<name>-prefix``. Relative paths are -# interpreted with respect to the build directory corresponding to the -# source directory in which ``ExternalProject_Add`` is invoked. -# -# If ``SOURCE_DIR`` is explicitly set to an existing directory the project -# will be built from it. Otherwise a download step must be specified -# using one of the ``DOWNLOAD_COMMAND``, ``CVS_*``, ``SVN_*``, or ``URL`` -# options. The ``URL`` option may refer locally to a directory or source -# tarball, or refer to a remote tarball (e.g. ``http://.../src.tgz``). -# -# The ``ExternalProject_Add_Step`` function adds a custom step to an -# external project: -# -# .. code-block:: cmake -# -# ExternalProject_Add_Step(<name> <step> # Names of project and custom step -# [COMMAND cmd...] # Command line invoked by this step -# [COMMENT "text..."] # Text printed when step executes -# [DEPENDEES steps...] # Steps on which this step depends -# [DEPENDERS steps...] # Steps that depend on this step -# [DEPENDS files...] # Files on which this step depends -# [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 -# ) -# -# The command line, comment, and working directory of every standard and -# custom step is processed to replace tokens ``<SOURCE_DIR>``, -# ``<BINARY_DIR>``, ``<INSTALL_DIR>``, and ``<TMP_DIR>`` with -# corresponding property values. -# -# Any builtin step that specifies a ``<step>_COMMAND cmd...`` or custom -# step that specifies a ``COMMAND cmd...`` may specify additional command -# lines using the form ``COMMAND cmd...``. At build time the commands -# will be executed in order and aborted if any one fails. For example:: -# -# ... BUILD_COMMAND make COMMAND echo done ... -# -# specifies to run ``make`` and then ``echo done`` during the build step. -# Whether the current working directory is preserved between commands is -# not defined. Behavior of shell operators like ``&&`` is not defined. -# -# 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``. -# -# The ``ExternalProject_Add_StepTargets`` function generates custom -# targets for the steps listed:: -# -# ExternalProject_Add_StepTargets(<name> [step1 [step2 [...]]]) -# -# If ``STEP_TARGETS`` is set then ``ExternalProject_Add_StepTargets`` is -# automatically called at the end of matching calls to -# ``ExternalProject_Add_Step``. Pass ``STEP_TARGETS`` explicitly to -# individual ``ExternalProject_Add`` calls, or implicitly to all -# ``ExternalProject_Add`` calls by setting the directory property -# ``EP_STEP_TARGETS``. -# -# If ``STEP_TARGETS`` is 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) +#[=======================================================================[.rst: +ExternalProject +--------------- + +Create custom targets to build projects in external trees + +.. command:: 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_SUBMODULES <module>...`` + Git submodules that shall be updated, all if empty + ``HG_REPOSITORY <url>`` + URL of mercurial repo + ``HG_TAG <tag>`` + Mercurial branch name, commit id or tag + ``URL /.../src.tgz`` + Full path or URL of source + ``URL_HASH ALGO=value`` + Hash of file at URL + ``URL_MD5 md5`` + Equivalent to URL_HASH MD5=md5 + ``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 + + Update/Patch step options are: + + ``UPDATE_COMMAND <cmd>...`` + Source work-tree update command + ``PATCH_COMMAND <cmd>...`` + Command to patch downloaded source + + Configure step options are: + + ``SOURCE_DIR <dir>`` + Source dir to be used for build + ``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 + ``CMAKE_CACHE_ARGS <arg>...`` + Initial cache arguments, of the form ``-Dvar:string=on`` + + 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 + + Install step options are: + + ``INSTALL_DIR <dir>`` + Installation prefix + ``INSTALL_COMMAND <cmd>...`` + Command to drive install after build + + 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_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 + + Other options are: + + ``STEP_TARGETS <step-target>...`` + Generate custom targets for these steps + + The ``*_DIR`` options specify directories for the project, with default + directories computed as follows. If the ``PREFIX`` option is given to + ``ExternalProject_Add()`` or the ``EP_PREFIX`` directory property is set, + then an external project is built and installed under the specified prefix:: + + TMP_DIR = <prefix>/tmp + STAMP_DIR = <prefix>/src/<name>-stamp + DOWNLOAD_DIR = <prefix>/src + SOURCE_DIR = <prefix>/src/<name> + BINARY_DIR = <prefix>/src/<name>-build + INSTALL_DIR = <prefix> + + Otherwise, if the ``EP_BASE`` directory property is set then components + of an external project are stored under the specified base:: + + TMP_DIR = <base>/tmp/<name> + STAMP_DIR = <base>/Stamp/<name> + DOWNLOAD_DIR = <base>/Download/<name> + SOURCE_DIR = <base>/Source/<name> + BINARY_DIR = <base>/Build/<name> + INSTALL_DIR = <base>/Install/<name> + + If no ``PREFIX``, ``EP_PREFIX``, or ``EP_BASE`` is specified then the + default is to set ``PREFIX`` to ``<name>-prefix``. Relative paths are + interpreted with respect to the build directory corresponding to the + source directory in which ``ExternalProject_Add`` is invoked. + + If ``SOURCE_DIR`` is explicitly set to an existing directory the project + will be built from it. Otherwise a download step must be specified + using one of the ``DOWNLOAD_COMMAND``, ``CVS_*``, ``SVN_*``, or ``URL`` + options. The ``URL`` option may refer locally to a directory or source + tarball, or refer to a remote tarball (e.g. ``http://.../src.tgz``). + +.. command:: 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 + ``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 + + The command line, comment, and working directory of every standard and + custom step is processed to replace tokens ``<SOURCE_DIR>``, + ``<BINARY_DIR>``, ``<INSTALL_DIR>``, and ``<TMP_DIR>`` with + corresponding property values. + +Any builtin step that specifies a ``<step>_COMMAND cmd...`` or custom +step that specifies a ``COMMAND cmd...`` may specify additional command +lines using the form ``COMMAND cmd...``. At build time the commands +will be executed in order and aborted if any one fails. For example:: + + ... BUILD_COMMAND make COMMAND echo done ... + +specifies to run ``make`` and then ``echo done`` during the build step. +Whether the current working directory is preserved between commands is +not defined. Behavior of shell operators like ``&&`` is not defined. + +.. command:: 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``. + +.. command:: ExternalProject_Add_StepTargets + + The ``ExternalProject_Add_StepTargets`` function generates custom + targets for the steps listed:: + + ExternalProject_Add_StepTargets(<name> [step1 [step2 [...]]]) + +If ``STEP_TARGETS`` is set then ``ExternalProject_Add_StepTargets`` is +automatically called at the end of matching calls to +``ExternalProject_Add_Step``. Pass ``STEP_TARGETS`` explicitly to +individual ``ExternalProject_Add`` calls, or implicitly to all +``ExternalProject_Add`` calls by setting the directory property +``EP_STEP_TARGETS``. + +If ``STEP_TARGETS`` is 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) +#]=======================================================================] #============================================================================= # Copyright 2008-2013 Kitware, Inc. @@ -200,9 +289,9 @@ math(EXPR _ep_documentation_line_count "${CMAKE_CURRENT_LIST_LINE} - 16") file(STRINGS "${CMAKE_CURRENT_LIST_FILE}" lines LIMIT_COUNT ${_ep_documentation_line_count} - REGEX "^# ( \\[[A-Z0-9_]+ [^]]*\\] +#.*$|[A-Za-z0-9_]+\\()") + REGEX "^\\.\\. command:: [A-Za-z0-9_]+|^ ``[A-Z0-9_]+ .*``$") foreach(line IN LISTS lines) - if("${line}" MATCHES "^# ([A-Za-z0-9_]+)\\(") + if("${line}" MATCHES "^\\.\\. command:: ([A-Za-z0-9_]+)") if(_ep_func) set(_ep_keywords_${_ep_func} "${_ep_keywords_${_ep_func}})$") endif() @@ -210,8 +299,8 @@ foreach(line IN LISTS lines) #message("function [${_ep_func}]") set(_ep_keywords_${_ep_func} "^(") set(_ep_keyword_sep) - else() - string(REGEX REPLACE "^# \\[([A-Z0-9_]+) .*" "\\1" _ep_key "${line}") + elseif("${line}" MATCHES "^ ``([A-Z0-9_]+) .*``$") + set(_ep_key "${CMAKE_MATCH_1}") #message(" keyword [${_ep_key}]") set(_ep_keywords_${_ep_func} "${_ep_keywords_${_ep_func}}${_ep_keyword_sep}${_ep_key}") |