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

ExternalProject: Use explicit markup and definition lists in docs

Browse Source 
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.
This commit is contained in:
Brad King 2014-10-28 12:44:00 -04:00
parent 98936ae3e0
commit d9c2c17b29
1 changed files with 215 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

256
Modules/ExternalProject.cmake
View File

@ -4,77 +4,150 @@ ExternalProject
Create custom targets to build projects in external trees Create custom targets to build projects in external trees
.. 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 download, update/patch, configure, build, install and test steps of an
external project: external project::
.. code-block:: cmake ExternalProject_Add(<name> [<option>...])
ExternalProject_Add(<name> # Name for custom target General options are:
[DEPENDS projects...] # Targets on which the project depends
[PREFIX dir] # Root dir for entire project ``DEPENDS <projects>...``
[LIST_SEPARATOR sep] # Sep to be replaced by ; in cmd lines Targets on which the project depends
[TMP_DIR dir] # Directory to store temporary files ``PREFIX <dir>``
[STAMP_DIR dir] # Directory to store step timestamps Root dir for entire project
[EXCLUDE_FROM_ALL 1] # The "all" target does not depend on this ``LIST_SEPARATOR <sep>``
#--Download step-------------- Sep to be replaced by ; in cmd lines
[DOWNLOAD_NAME fname] # File name to store (if not end of URL) ``TMP_DIR <dir>``
[DOWNLOAD_DIR dir] # Directory to store downloaded files Directory to store temporary files
[DOWNLOAD_COMMAND cmd...] # Command to download source tree ``STAMP_DIR <dir>``
[DOWNLOAD_NO_PROGRESS 1] # Disable download progress reports Directory to store step timestamps
[CVS_REPOSITORY cvsroot] # CVSROOT of CVS repository ``EXCLUDE_FROM_ALL 1``
[CVS_MODULE mod] # Module to checkout from CVS repo The "all" target does not depend on this
[CVS_TAG tag] # Tag to checkout from CVS repo
[SVN_REPOSITORY url] # URL of Subversion repo Download step options are:
[SVN_REVISION -r<rev>] # Revision to checkout from Subversion repo
[SVN_USERNAME john ] # Username for Subversion checkout and update ``DOWNLOAD_NAME <fname>``
[SVN_PASSWORD doe ] # Password for Subversion checkout and update File name to store (if not end of URL)
[SVN_TRUST_CERT 1 ] # Trust the Subversion server site certificate ``DOWNLOAD_DIR <dir>``
[GIT_REPOSITORY url] # URL of git repo Directory to store downloaded files
[GIT_TAG tag] # Git branch name, commit id or tag ``DOWNLOAD_COMMAND <cmd>...``
[GIT_SUBMODULES modules...] # Git submodules that shall be updated, all if empty Command to download source tree
[HG_REPOSITORY url] # URL of mercurial repo ``DOWNLOAD_NO_PROGRESS 1``
[HG_TAG tag] # Mercurial branch name, commit id or tag Disable download progress reports
[URL /.../src.tgz] # Full path or URL of source ``CVS_REPOSITORY <cvsroot>``
[URL_HASH ALGO=value] # Hash of file at URL CVSROOT of CVS repository
[URL_MD5 md5] # Equivalent to URL_HASH MD5=md5 ``CVS_MODULE <mod>``
[TLS_VERIFY bool] # Should certificate for https be checked Module to checkout from CVS repo
[TLS_CAINFO file] # Path to a certificate authority file ``CVS_TAG <tag>``
[TIMEOUT seconds] # Time allowed for file download operations Tag to checkout from CVS repo
#--Update/Patch step---------- ``SVN_REPOSITORY <url>``
[UPDATE_COMMAND cmd...] # Source work-tree update command URL of Subversion repo
[PATCH_COMMAND cmd...] # Command to patch downloaded source ``SVN_REVISION -r<rev>``
#--Configure step------------- Revision to checkout from Subversion repo
[SOURCE_DIR dir] # Source dir to be used for build ``SVN_USERNAME <username>``
[CONFIGURE_COMMAND cmd...] # Build tree configuration command Username for Subversion checkout and update
[CMAKE_COMMAND /.../cmake] # Specify alternative cmake executable ``SVN_PASSWORD <password>``
[CMAKE_GENERATOR gen] # Specify generator for native build Password for Subversion checkout and update
[CMAKE_GENERATOR_PLATFORM p] # Generator-specific platform name ``SVN_TRUST_CERT 1``
[CMAKE_GENERATOR_TOOLSET t] # Generator-specific toolset name Trust the Subversion server site certificate
[CMAKE_ARGS args...] # Arguments to CMake command line ``GIT_REPOSITORY <url>``
[CMAKE_CACHE_ARGS args...] # Initial cache arguments, of the form -Dvar:string=on URL of git repo
#--Build step----------------- ``GIT_TAG <tag>``
[BINARY_DIR dir] # Specify build dir location Git branch name, commit id or tag
[BUILD_COMMAND cmd...] # Command to drive the native build ``GIT_SUBMODULES <module>...``
[BUILD_IN_SOURCE 1] # Use source dir for build dir Git submodules that shall be updated, all if empty
[BUILD_ALWAYS 1] # No stamp file, build step always runs ``HG_REPOSITORY <url>``
#--Install step--------------- URL of mercurial repo
[INSTALL_DIR dir] # Installation prefix ``HG_TAG <tag>``
[INSTALL_COMMAND cmd...] # Command to drive install after build Mercurial branch name, commit id or tag
#--Test step------------------ ``URL /.../src.tgz``
[TEST_BEFORE_INSTALL 1] # Add test step executed before install step Full path or URL of source
[TEST_AFTER_INSTALL 1] # Add test step executed after install step ``URL_HASH ALGO=value``
[TEST_COMMAND cmd...] # Command to drive test Hash of file at URL
#--Output logging------------- ``URL_MD5 md5``
[LOG_DOWNLOAD 1] # Wrap download in script to log output Equivalent to URL_HASH MD5=md5
[LOG_UPDATE 1] # Wrap update in script to log output ``TLS_VERIFY <bool>``
[LOG_CONFIGURE 1] # Wrap configure in script to log output Should certificate for https be checked
[LOG_BUILD 1] # Wrap build in script to log output ``TLS_CAINFO <file>``
[LOG_TEST 1] # Wrap test in script to log output Path to a certificate authority file
[LOG_INSTALL 1] # Wrap install in script to log output ``TIMEOUT <seconds>``
#--Custom targets------------- Time allowed for file download operations
[STEP_TARGETS st1 st2 ...] # Generate custom targets for these steps
) 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 The ``*_DIR`` options specify directories for the project, with default
directories computed as follows. If the ``PREFIX`` option is given to directories computed as follows. If the ``PREFIX`` option is given to
@ -109,22 +182,33 @@ using one of the ``DOWNLOAD_COMMAND``, ``CVS_*``, ``SVN_*``, or ``URL``
options. The ``URL`` option may refer locally to a directory or source options. The ``URL`` option may refer locally to a directory or source
tarball, or refer to a remote tarball (e.g. ``http://.../src.tgz``). 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 The ``ExternalProject_Add_Step`` function adds a custom step to an
external project: external project::
.. code-block:: cmake ExternalProject_Add_Step(<name> <step> [<option>...])
ExternalProject_Add_Step(<name> <step> # Names of project and custom step Options are:
[COMMAND cmd...] # Command line invoked by this step
[COMMENT "text..."] # Text printed when step executes ``COMMAND <cmd>...``
[DEPENDEES steps...] # Steps on which this step depends Command line invoked by this step
[DEPENDERS steps...] # Steps that depend on this step ``COMMENT "<text>..."``
[DEPENDS files...] # Files on which this step depends Text printed when step executes
[ALWAYS 1] # No stamp file, step always runs ``DEPENDEES <step>...``
[EXCLUDE_FROM_MAIN 1] # Main target does not depend on this step Steps on which this step depends
[WORKING_DIRECTORY dir] # Working directory for command ``DEPENDERS <step>...``
[LOG 1] # Wrap step in script to log output 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 The command line, comment, and working directory of every standard and
custom step is processed to replace tokens ``<SOURCE_DIR>``, custom step is processed to replace tokens ``<SOURCE_DIR>``,
@ -142,6 +226,8 @@ specifies to run ``make`` and then ``echo done`` during the build step.
Whether the current working directory is preserved between commands is Whether the current working directory is preserved between commands is
not defined. Behavior of shell operators like ``&&`` is not defined. not defined. Behavior of shell operators like ``&&`` is not defined.
.. command:: ExternalProject_Get_Property
The ``ExternalProject_Get_Property`` function retrieves external project The ``ExternalProject_Get_Property`` function retrieves external project
target properties:: target properties::
@ -151,6 +237,8 @@ It stores property values in variables of the same name. Property
names correspond to the keyword argument names of names correspond to the keyword argument names of
``ExternalProject_Add``. ``ExternalProject_Add``.
.. command:: ExternalProject_Add_StepTargets
The ``ExternalProject_Add_StepTargets`` function generates custom The ``ExternalProject_Add_StepTargets`` function generates custom
targets for the steps listed:: targets for the steps listed::
@ -201,9 +289,9 @@ file::
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()
@ -211,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}")