mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-06 05:40:54 -06:00
Convert builtin help to reStructuredText source files
Run the convert-help.bash script to convert documentation: ./convert-help.bash "/path/to/CMake-build/bin" Then remove it.
This commit is contained in:
Kitware Robot
@@ -1,163 +1,192 @@
|
||||
# - Create custom targets to build projects in external trees
|
||||
#.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:
|
||||
# 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
|
||||
# #--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
|
||||
# [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 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
|
||||
# [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_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
|
||||
# #--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
|
||||
# )
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# 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
|
||||
# #--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
|
||||
# [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 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
|
||||
# [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_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
|
||||
# #--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.
|
||||
# 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).
|
||||
# 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:
|
||||
# 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
|
||||
# [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.
|
||||
# The 'ExternalProject_Add_Step' function adds a custom step to an
|
||||
# external project:
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# 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
|
||||
# [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 ...
|
||||
# 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.
|
||||
# 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_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 [...]]])
|
||||
# The 'ExternalProject_Add_StepTargets' function generates custom
|
||||
# targets for the steps listed:
|
||||
#
|
||||
# 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.
|
||||
# ::
|
||||
#
|
||||
# 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.
|
||||
# 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 file:
|
||||
# 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 file:
|
||||
#
|
||||
# set_property(DIRECTORY PROPERTY EP_STEP_TARGETS configure build test)
|
||||
# ::
|
||||
#
|
||||
# set_property(DIRECTORY PROPERTY EP_STEP_TARGETS configure build test)
|
||||
|
||||
#=============================================================================
|
||||
# Copyright 2008-2012 Kitware, Inc.
|
||||
|
||||
Reference in New Issue
Block a user