ExternalProject: Format module documentation
Manually revise the .rst format of the documentation. Use inline literal quotes appropriately in paragraph text. Move the :: literal block openers to the end of the preceding paragraphs. Convert the command signature documentation and examples to cmake code-block directives.
This commit is contained in:
Brad King
parent
4bb41b30d6
commit
01ecd24fa6
|
|
@ -4,11 +4,11 @@
|
|||
#
|
||||
# Create custom targets to build projects in external trees
|
||||
#
|
||||
# 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
|
||||
# external project:
|
||||
#
|
||||
# ::
|
||||
# .. code-block:: cmake
|
||||
#
|
||||
# ExternalProject_Add(<name> # Name for custom target
|
||||
# [DEPENDS projects...] # Targets on which the project depends
|
||||
|
|
@ -72,46 +72,42 @@
|
|||
# )
|
||||
#
|
||||
# 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:
|
||||
# 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>
|
||||
#
|
||||
# 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::
|
||||
#
|
||||
# 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.
|
||||
#
|
||||
# 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
|
||||
# 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).
|
||||
# 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
|
||||
# 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
|
||||
|
|
@ -125,51 +121,45 @@
|
|||
# )
|
||||
#
|
||||
# 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.
|
||||
# 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:
|
||||
# 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 ...
|
||||
#
|
||||
# ... BUILD_COMMAND make COMMAND echo done ...
|
||||
#
|
||||
# specifies to run "make" and then "echo done" during the build step.
|
||||
# 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.
|
||||
# not defined. Behavior of shell operators like ``&&`` is not defined.
|
||||
#
|
||||
# The 'ExternalProject_Get_Property' function retrieves external project
|
||||
# target properties:
|
||||
# The ``ExternalProject_Get_Property`` function retrieves external project
|
||||
# target properties::
|
||||
#
|
||||
# ::
|
||||
#
|
||||
# ExternalProject_Get_Property(<name> [prop1 [prop2 [...]]])
|
||||
# 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'.
|
||||
# ``ExternalProject_Add``.
|
||||
#
|
||||
# The 'ExternalProject_Add_StepTargets' function generates custom
|
||||
# targets for the steps listed:
|
||||
# The ``ExternalProject_Add_StepTargets`` function generates custom
|
||||
# targets for the steps listed::
|
||||
#
|
||||
# ::
|
||||
# ExternalProject_Add_StepTargets(<name> [step1 [step2 [...]]])
|
||||
#
|
||||
# ExternalProject_Add_StepTargets(<name> [step1 [step2 [...]]])
|
||||
#
|
||||
#
|
||||
#
|
||||
# If STEP_TARGETS is set then ExternalProject_Add_StepTargets is
|
||||
# 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_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.
|
||||
# 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
|
||||
|
|
@ -181,15 +171,14 @@
|
|||
# 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 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)
|
||||
# set_property(DIRECTORY PROPERTY EP_STEP_TARGETS configure build test)
|
||||
|
||||
#=============================================================================
|
||||
# Copyright 2008-2012 Kitware, Inc.
|
||||
# Copyright 2008-2013 Kitware, Inc.
|
||||
#
|
||||
# Distributed under the OSI-approved BSD License (the "License");
|
||||
# see accompanying file Copyright.txt for details.
|
||||
|
|
|
|||
Loading…
Reference in New Issue