diff options
Diffstat (limited to 'Modules/ExternalProject.cmake')
| -rw-r--r-- | Modules/ExternalProject.cmake | 161 |
1 files changed, 95 insertions, 66 deletions
diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake index 0781ea1..84fa613 100644 --- a/Modules/ExternalProject.cmake +++ b/Modules/ExternalProject.cmake @@ -1,7 +1,15 @@ -# - 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 @@ -62,40 +70,49 @@ # #--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. +# +# 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). +# 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: +# +# :: # -# 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 @@ -106,58 +123,70 @@ # [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 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: +# +# :: +# +# 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 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. |