Merge topic 'ExternalProject-format-docs'

d9c2c17b ExternalProject: Use explicit markup and definition lists in docs
98936ae3 ExternalProject: Convert docs to a bracket comment

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}")