[Cmake-commits] CMake branch, next, updated. v3.1.0-rc1-168-g3155bf4
Brad King
brad.king at kitware.com
Tue Oct 28 12:59:35 EDT 2014
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "CMake".
The branch, next has been updated
via 3155bf4537d145f0f06e679b16b0b6fca338fee6 (commit)
via d9c2c17b29467367ddefbc86cf7e1759c7df27cc (commit)
via 98936ae3e0bd92faf282f78a53c9a177f96294ab (commit)
from cf804761f8e0ea2f3faadeed5d373c2d1e2dcbe5 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=3155bf4537d145f0f06e679b16b0b6fca338fee6
commit 3155bf4537d145f0f06e679b16b0b6fca338fee6
Merge: cf80476 d9c2c17
Author: Brad King <brad.king at kitware.com>
AuthorDate: Tue Oct 28 12:59:34 2014 -0400
Commit: CMake Topic Stage <kwrobot at kitware.com>
CommitDate: Tue Oct 28 12:59:34 2014 -0400
Merge topic 'ExternalProject-format-docs' into next
d9c2c17b ExternalProject: Use explicit markup and definition lists in docs
98936ae3 ExternalProject: Convert docs to a bracket comment
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=d9c2c17b29467367ddefbc86cf7e1759c7df27cc
commit d9c2c17b29467367ddefbc86cf7e1759c7df27cc
Author: Brad King <brad.king at kitware.com>
AuthorDate: Tue Oct 28 12:44:00 2014 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Tue Oct 28 12:46:17 2014 -0400
ExternalProject: Use explicit markup and definition lists in docs
Convert ExternalProject module documentation to use explicit markup
blocks for each command. Enumerate command options with definition
lists instead of a literal block. This will allow more detail to be
added later. Also fix the logic that parses options out of the
documentation to be aware of the new layout.
diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake
index 54432e3..a92f20c 100644
--- a/Modules/ExternalProject.cmake
+++ b/Modules/ExternalProject.cmake
@@ -4,132 +4,216 @@ 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.
+.. 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
@@ -142,19 +226,23 @@ 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::
+.. command:: ExternalProject_Get_Property
- ExternalProject_Get_Property(<name> [prop1 [prop2 [...]]])
+ The ``ExternalProject_Get_Property`` function retrieves external project
+ target properties::
-It stores property values in variables of the same name. Property
-names correspond to the keyword argument names of
-``ExternalProject_Add``.
+ ExternalProject_Get_Property(<name> [prop1 [prop2 [...]]])
-The ``ExternalProject_Add_StepTargets`` function generates custom
-targets for the steps listed::
+ It stores property values in variables of the same name. Property
+ names correspond to the keyword argument names of
+ ``ExternalProject_Add``.
- ExternalProject_Add_StepTargets(<name> [step1 [step2 [...]]])
+.. 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
@@ -201,9 +289,9 @@ file::
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()
@@ -211,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}")
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=98936ae3e0bd92faf282f78a53c9a177f96294ab
commit 98936ae3e0bd92faf282f78a53c9a177f96294ab
Author: Brad King <brad.king at kitware.com>
AuthorDate: Tue Oct 28 12:40:22 2014 -0400
Commit: Brad King <brad.king at kitware.com>
CommitDate: Tue Oct 28 12:41:00 2014 -0400
ExternalProject: Convert docs to a bracket comment
Use a bracket comment to hold the documentation instead of a block of
line comments. This will make further updates easier. Also fix the
logic that parses options out of the documentation to be aware of the
new layout.
diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake
index d6a6b72..54432e3 100644
--- a/Modules/ExternalProject.cmake
+++ b/Modules/ExternalProject.cmake
@@ -1,187 +1,188 @@
-#.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
+
+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)
+#]=======================================================================]
#=============================================================================
# Copyright 2008-2013 Kitware, Inc.
@@ -200,9 +201,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 "^ ( \\[[A-Z0-9_]+ [^]]*\\] +#.*$|[A-Za-z0-9_]+\\()")
foreach(line IN LISTS lines)
- if("${line}" MATCHES "^# ([A-Za-z0-9_]+)\\(")
+ if("${line}" MATCHES "^ ([A-Za-z0-9_]+)\\(")
if(_ep_func)
set(_ep_keywords_${_ep_func} "${_ep_keywords_${_ep_func}})$")
endif()
@@ -211,7 +212,7 @@ foreach(line IN LISTS lines)
set(_ep_keywords_${_ep_func} "^(")
set(_ep_keyword_sep)
else()
- string(REGEX REPLACE "^# \\[([A-Z0-9_]+) .*" "\\1" _ep_key "${line}")
+ string(REGEX REPLACE "^ \\[([A-Z0-9_]+) .*" "\\1" _ep_key "${line}")
#message(" keyword [${_ep_key}]")
set(_ep_keywords_${_ep_func}
"${_ep_keywords_${_ep_func}}${_ep_keyword_sep}${_ep_key}")
-----------------------------------------------------------------------
Summary of changes:
Modules/ExternalProject.cmake | 465 ++++++++++++++++++++++++-----------------
1 file changed, 277 insertions(+), 188 deletions(-)
hooks/post-receive
--
CMake
More information about the Cmake-commits
mailing list