kolan/CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge topic 'ExternalProject-format-docs'

Browse Source 
d9c2c17b ExternalProject: Use explicit markup and definition lists in docs
98936ae3 ExternalProject: Convert docs to a bracket comment
This commit is contained in:
Brad King 2014-10-29 11:31:13 -04:00 committed by CMake Topic Stage
commit 3942cf68b2
1 changed files with 277 additions and 188 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

465
Modules/ExternalProject.cmake
View File

@ -1,187 +1,276 @@
#.rst: #[=======================================================================[.rst:
# ExternalProject ExternalProject
# --------------- ---------------
#
# Create custom targets to build projects in external trees Create custom targets to build projects in external trees
#
# The ``ExternalProject_Add`` function creates a custom target to drive .. command:: ExternalProject_Add
# download, update/patch, configure, build, install and test steps of an
# external project: The ``ExternalProject_Add`` function creates a custom target to drive
# download, update/patch, configure, build, install and test steps of an
# .. code-block:: cmake external project::
#
# ExternalProject_Add(<name> # Name for custom target ExternalProject_Add(<name> [<option>...])
# [DEPENDS projects...] # Targets on which the project depends
# [PREFIX dir] # Root dir for entire project General options are:
# [LIST_SEPARATOR sep] # Sep to be replaced by ; in cmd lines
# [TMP_DIR dir] # Directory to store temporary files ``DEPENDS <projects>...``
# [STAMP_DIR dir] # Directory to store step timestamps Targets on which the project depends
# [EXCLUDE_FROM_ALL 1] # The "all" target does not depend on this ``PREFIX <dir>``
# #--Download step-------------- Root dir for entire project
# [DOWNLOAD_NAME fname] # File name to store (if not end of URL) ``LIST_SEPARATOR <sep>``
# [DOWNLOAD_DIR dir] # Directory to store downloaded files Sep to be replaced by ; in cmd lines
# [DOWNLOAD_COMMAND cmd...] # Command to download source tree ``TMP_DIR <dir>``
# [DOWNLOAD_NO_PROGRESS 1] # Disable download progress reports Directory to store temporary files
# [CVS_REPOSITORY cvsroot] # CVSROOT of CVS repository ``STAMP_DIR <dir>``
# [CVS_MODULE mod] # Module to checkout from CVS repo Directory to store step timestamps
# [CVS_TAG tag] # Tag to checkout from CVS repo ``EXCLUDE_FROM_ALL 1``
# [SVN_REPOSITORY url] # URL of Subversion repo The "all" target does not depend on this
# [SVN_REVISION -r<rev>] # Revision to checkout from Subversion repo
# [SVN_USERNAME john ] # Username for Subversion checkout and update Download step options are:
# [SVN_PASSWORD doe ] # Password for Subversion checkout and update
# [SVN_TRUST_CERT 1 ] # Trust the Subversion server site certificate ``DOWNLOAD_NAME <fname>``
# [GIT_REPOSITORY url] # URL of git repo File name to store (if not end of URL)
# [GIT_TAG tag] # Git branch name, commit id or tag ``DOWNLOAD_DIR <dir>``
# [GIT_SUBMODULES modules...] # Git submodules that shall be updated, all if empty Directory to store downloaded files
# [HG_REPOSITORY url] # URL of mercurial repo ``DOWNLOAD_COMMAND <cmd>...``
# [HG_TAG tag] # Mercurial branch name, commit id or tag Command to download source tree
# [URL /.../src.tgz] # Full path or URL of source ``DOWNLOAD_NO_PROGRESS 1``
# [URL_HASH ALGO=value] # Hash of file at URL Disable download progress reports
# [URL_MD5 md5] # Equivalent to URL_HASH MD5=md5 ``CVS_REPOSITORY <cvsroot>``
# [TLS_VERIFY bool] # Should certificate for https be checked CVSROOT of CVS repository
# [TLS_CAINFO file] # Path to a certificate authority file ``CVS_MODULE <mod>``
# [TIMEOUT seconds] # Time allowed for file download operations Module to checkout from CVS repo
# #--Update/Patch step---------- ``CVS_TAG <tag>``
# [UPDATE_COMMAND cmd...] # Source work-tree update command Tag to checkout from CVS repo
# [PATCH_COMMAND cmd...] # Command to patch downloaded source ``SVN_REPOSITORY <url>``
# #--Configure step------------- URL of Subversion repo
# [SOURCE_DIR dir] # Source dir to be used for build ``SVN_REVISION -r<rev>``
# [CONFIGURE_COMMAND cmd...] # Build tree configuration command Revision to checkout from Subversion repo
# [CMAKE_COMMAND /.../cmake] # Specify alternative cmake executable ``SVN_USERNAME <username>``
# [CMAKE_GENERATOR gen] # Specify generator for native build Username for Subversion checkout and update
# [CMAKE_GENERATOR_PLATFORM p] # Generator-specific platform name ``SVN_PASSWORD <password>``
# [CMAKE_GENERATOR_TOOLSET t] # Generator-specific toolset name Password for Subversion checkout and update
# [CMAKE_ARGS args...] # Arguments to CMake command line ``SVN_TRUST_CERT 1``
# [CMAKE_CACHE_ARGS args...] # Initial cache arguments, of the form -Dvar:string=on Trust the Subversion server site certificate
# #--Build step----------------- ``GIT_REPOSITORY <url>``
# [BINARY_DIR dir] # Specify build dir location URL of git repo
# [BUILD_COMMAND cmd...] # Command to drive the native build ``GIT_TAG <tag>``
# [BUILD_IN_SOURCE 1] # Use source dir for build dir Git branch name, commit id or tag
# [BUILD_ALWAYS 1] # No stamp file, build step always runs ``GIT_SUBMODULES <module>...``
# #--Install step--------------- Git submodules that shall be updated, all if empty
# [INSTALL_DIR dir] # Installation prefix ``HG_REPOSITORY <url>``
# [INSTALL_COMMAND cmd...] # Command to drive install after build URL of mercurial repo
# #--Test step------------------ ``HG_TAG <tag>``
# [TEST_BEFORE_INSTALL 1] # Add test step executed before install step Mercurial branch name, commit id or tag
# [TEST_AFTER_INSTALL 1] # Add test step executed after install step ``URL /.../src.tgz``
# [TEST_COMMAND cmd...] # Command to drive test Full path or URL of source
# #--Output logging------------- ``URL_HASH ALGO=value``
# [LOG_DOWNLOAD 1] # Wrap download in script to log output Hash of file at URL
# [LOG_UPDATE 1] # Wrap update in script to log output ``URL_MD5 md5``
# [LOG_CONFIGURE 1] # Wrap configure in script to log output Equivalent to URL_HASH MD5=md5
# [LOG_BUILD 1] # Wrap build in script to log output ``TLS_VERIFY <bool>``
# [LOG_TEST 1] # Wrap test in script to log output Should certificate for https be checked
# [LOG_INSTALL 1] # Wrap install in script to log output ``TLS_CAINFO <file>``
# #--Custom targets------------- Path to a certificate authority file
# [STEP_TARGETS st1 st2 ...] # Generate custom targets for these steps ``TIMEOUT <seconds>``
# ) Time allowed for file download operations
#
# The ``*_DIR`` options specify directories for the project, with default Update/Patch step options are:
# directories computed as follows. If the ``PREFIX`` option is given to
# ``ExternalProject_Add()`` or the ``EP_PREFIX`` directory property is set, ``UPDATE_COMMAND <cmd>...``
# then an external project is built and installed under the specified prefix:: Source work-tree update command
# ``PATCH_COMMAND <cmd>...``
# TMP_DIR = <prefix>/tmp Command to patch downloaded source
# STAMP_DIR = <prefix>/src/<name>-stamp
# DOWNLOAD_DIR = <prefix>/src Configure step options are:
# SOURCE_DIR = <prefix>/src/<name>
# BINARY_DIR = <prefix>/src/<name>-build ``SOURCE_DIR <dir>``
# INSTALL_DIR = <prefix> Source dir to be used for build
# ``CONFIGURE_COMMAND <cmd>...``
# Otherwise, if the ``EP_BASE`` directory property is set then components Build tree configuration command
# of an external project are stored under the specified base:: ``CMAKE_COMMAND /.../cmake``
# Specify alternative cmake executable
# TMP_DIR = <base>/tmp/<name> ``CMAKE_GENERATOR <gen>``
# STAMP_DIR = <base>/Stamp/<name> Specify generator for native build
# DOWNLOAD_DIR = <base>/Download/<name> ``CMAKE_GENERATOR_PLATFORM <platform>``
# SOURCE_DIR = <base>/Source/<name> Generator-specific platform name
# BINARY_DIR = <base>/Build/<name> ``CMAKE_GENERATOR_TOOLSET <toolset>``
# INSTALL_DIR = <base>/Install/<name> Generator-specific toolset name
# ``CMAKE_ARGS <arg>...``
# If no ``PREFIX``, ``EP_PREFIX``, or ``EP_BASE`` is specified then the Arguments to CMake command line
# default is to set ``PREFIX`` to ``<name>-prefix``. Relative paths are ``CMAKE_CACHE_ARGS <arg>...``
# interpreted with respect to the build directory corresponding to the Initial cache arguments, of the form ``-Dvar:string=on``
# source directory in which ``ExternalProject_Add`` is invoked.
# Build step options are:
# If ``SOURCE_DIR`` is explicitly set to an existing directory the project
# will be built from it. Otherwise a download step must be specified ``BINARY_DIR <dir>``
# using one of the ``DOWNLOAD_COMMAND``, ``CVS_*``, ``SVN_*``, or ``URL`` Specify build dir location
# options. The ``URL`` option may refer locally to a directory or source ``BUILD_COMMAND <cmd>...``
# tarball, or refer to a remote tarball (e.g. ``http://.../src.tgz``). Command to drive the native build
# ``BUILD_IN_SOURCE 1``
# The ``ExternalProject_Add_Step`` function adds a custom step to an Use source dir for build dir
# external project: ``BUILD_ALWAYS 1``
# No stamp file, build step always runs
# .. code-block:: cmake
# Install step options are:
# ExternalProject_Add_Step(<name> <step> # Names of project and custom step
# [COMMAND cmd...] # Command line invoked by this step ``INSTALL_DIR <dir>``
# [COMMENT "text..."] # Text printed when step executes Installation prefix
# [DEPENDEES steps...] # Steps on which this step depends ``INSTALL_COMMAND <cmd>...``
# [DEPENDERS steps...] # Steps that depend on this step Command to drive install after build
# [DEPENDS files...] # Files on which this step depends
# [ALWAYS 1] # No stamp file, step always runs Test step options are:
# [EXCLUDE_FROM_MAIN 1] # Main target does not depend on this step
# [WORKING_DIRECTORY dir] # Working directory for command ``TEST_BEFORE_INSTALL 1``
# [LOG 1] # Wrap step in script to log output Add test step executed before install step
# ) ``TEST_AFTER_INSTALL 1``
# Add test step executed after install step
# The command line, comment, and working directory of every standard and ``TEST_COMMAND <cmd>...``
# custom step is processed to replace tokens ``<SOURCE_DIR>``, Command to drive test
# ``<BINARY_DIR>``, ``<INSTALL_DIR>``, and ``<TMP_DIR>`` with
# corresponding property values. Output logging options are:
#
# Any builtin step that specifies a ``<step>_COMMAND cmd...`` or custom ``LOG_DOWNLOAD 1``
# step that specifies a ``COMMAND cmd...`` may specify additional command Wrap download in script to log output
# lines using the form ``COMMAND cmd...``. At build time the commands ``LOG_UPDATE 1``
# will be executed in order and aborted if any one fails. For example:: Wrap update in script to log output
# ``LOG_CONFIGURE 1``
# ... BUILD_COMMAND make COMMAND echo done ... Wrap configure in script to log output
# ``LOG_BUILD 1``
# specifies to run ``make`` and then ``echo done`` during the build step. Wrap build in script to log output
# Whether the current working directory is preserved between commands is ``LOG_TEST 1``
# not defined. Behavior of shell operators like ``&&`` is not defined. Wrap test in script to log output
# ``LOG_INSTALL 1``
# The ``ExternalProject_Get_Property`` function retrieves external project Wrap install in script to log output
# target properties::
# Other options are:
# ExternalProject_Get_Property(<name> [prop1 [prop2 [...]]])
# ``STEP_TARGETS <step-target>...``
# It stores property values in variables of the same name. Property Generate custom targets for these steps
# names correspond to the keyword argument names of
# ``ExternalProject_Add``. The ``*_DIR`` options specify directories for the project, with default
# directories computed as follows. If the ``PREFIX`` option is given to
# The ``ExternalProject_Add_StepTargets`` function generates custom ``ExternalProject_Add()`` or the ``EP_PREFIX`` directory property is set,
# targets for the steps listed:: then an external project is built and installed under the specified prefix::
#
# ExternalProject_Add_StepTargets(<name> [step1 [step2 [...]]]) TMP_DIR = <prefix>/tmp
# STAMP_DIR = <prefix>/src/<name>-stamp
# If ``STEP_TARGETS`` is set then ``ExternalProject_Add_StepTargets`` is DOWNLOAD_DIR = <prefix>/src
# automatically called at the end of matching calls to SOURCE_DIR = <prefix>/src/<name>
# ``ExternalProject_Add_Step``. Pass ``STEP_TARGETS`` explicitly to BINARY_DIR = <prefix>/src/<name>-build
# individual ``ExternalProject_Add`` calls, or implicitly to all INSTALL_DIR = <prefix>
# ``ExternalProject_Add`` calls by setting the directory property
# ``EP_STEP_TARGETS``. Otherwise, if the ``EP_BASE`` directory property is set then components
# of an external project are stored under the specified base::
# If ``STEP_TARGETS`` is not set, clients may still manually call
# ``ExternalProject_Add_StepTargets`` after calling TMP_DIR = <base>/tmp/<name>
# ``ExternalProject_Add`` or ``ExternalProject_Add_Step``. STAMP_DIR = <base>/Stamp/<name>
# DOWNLOAD_DIR = <base>/Download/<name>
# This functionality is provided to make it easy to drive the steps SOURCE_DIR = <base>/Source/<name>
# independently of each other by specifying targets on build command BINARY_DIR = <base>/Build/<name>
# lines. For example, you may be submitting to a sub-project based INSTALL_DIR = <base>/Install/<name>
# dashboard, where you want to drive the configure portion of the build,
# then submit to the dashboard, followed by the build portion, followed If no ``PREFIX``, ``EP_PREFIX``, or ``EP_BASE`` is specified then the
# by tests. If you invoke a custom target that depends on a step default is to set ``PREFIX`` to ``<name>-prefix``. Relative paths are
# halfway through the step dependency chain, then all the previous steps interpreted with respect to the build directory corresponding to the
# will also run to ensure everything is up to date. source directory in which ``ExternalProject_Add`` is invoked.
#
# For example, to drive configure, build and test steps independently If ``SOURCE_DIR`` is explicitly set to an existing directory the project
# for each ``ExternalProject_Add`` call in your project, write the following will be built from it. Otherwise a download step must be specified
# line prior to any ``ExternalProject_Add`` calls in your ``CMakeLists.txt`` using one of the ``DOWNLOAD_COMMAND``, ``CVS_*``, ``SVN_*``, or ``URL``
# file:: options. The ``URL`` option may refer locally to a directory or source
# tarball, or refer to a remote tarball (e.g. ``http://.../src.tgz``).
# set_property(DIRECTORY PROPERTY EP_STEP_TARGETS configure build test)
.. 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. # Copyright 2008-2013 Kitware, Inc.
@ -200,9 +289,9 @@
math(EXPR _ep_documentation_line_count "${CMAKE_CURRENT_LIST_LINE} - 16") math(EXPR _ep_documentation_line_count "${CMAKE_CURRENT_LIST_LINE} - 16")
file(STRINGS "${CMAKE_CURRENT_LIST_FILE}" lines file(STRINGS "${CMAKE_CURRENT_LIST_FILE}" lines
LIMIT_COUNT ${_ep_documentation_line_count} 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) foreach(line IN LISTS lines)
if("${line}" MATCHES "^# ([A-Za-z0-9_]+)\\(") if("${line}" MATCHES "^\\.\\. command:: ([A-Za-z0-9_]+)")
if(_ep_func) if(_ep_func)
set(_ep_keywords_${_ep_func} "${_ep_keywords_${_ep_func}})$") set(_ep_keywords_${_ep_func} "${_ep_keywords_${_ep_func}})$")
endif() endif()
@ -210,8 +299,8 @@ foreach(line IN LISTS lines)
#message("function [${_ep_func}]") #message("function [${_ep_func}]")
set(_ep_keywords_${_ep_func} "^(") set(_ep_keywords_${_ep_func} "^(")
set(_ep_keyword_sep) set(_ep_keyword_sep)
else() elseif("${line}" MATCHES "^ ``([A-Z0-9_]+) .*``$")
string(REGEX REPLACE "^# \\[([A-Z0-9_]+) .*" "\\1" _ep_key "${line}") set(_ep_key "${CMAKE_MATCH_1}")
#message(" keyword [${_ep_key}]") #message(" keyword [${_ep_key}]")
set(_ep_keywords_${_ep_func} set(_ep_keywords_${_ep_func}
"${_ep_keywords_${_ep_func}}${_ep_keyword_sep}${_ep_key}") "${_ep_keywords_${_ep_func}}${_ep_keyword_sep}${_ep_key}")