Commit f051814e authored by Kitware Robot's avatar Kitware Robot Committed by Brad King
Browse files

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.
parent e94958e9
add_compile_options
-------------------
Adds options to the compilation of source files.
::
add_compile_options(<option> ...)
Adds options to the compiler command line for sources in the current
directory and below. This command can be used to add any options, but
alternative commands exist to add preprocessor definitions or include
directories. See documentation of the directory and target
COMPILE_OPTIONS properties for details. Arguments to
add_compile_options may use "generator expressions" with the syntax
"$<...>". Generator expressions are evaluated during build system
generation to produce information specific to each build
configuration. Valid expressions are:
::
$<0:...> = empty string (ignores "...")
$<1:...> = content of "..."
$<CONFIG:cfg> = '1' if config is "cfg", else '0'
$<CONFIGURATION> = configuration name
$<BOOL:...> = '1' if the '...' is true, else '0'
$<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
$<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
$<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
$<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
$<JOIN:list,...> = joins the list with the content of "..."
$<TARGET_NAME:...> = Marks ... as being the name of a target. This is required if exporting targets to multiple dependent export sets. The '...' must be a literal name of a target- it may not contain generator expressions.
$<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
$<BUILD_INTERFACE:...> = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
$<PLATFORM_ID> = The CMake-id of the platform $<PLATFORM_ID:comp> = '1' if the The CMake-id of the platform matches comp, otherwise '0'.
$<C_COMPILER_ID> = The CMake-id of the C compiler used.
$<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
$<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
$<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
$<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
$<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
$<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
$<C_COMPILER_VERSION> = The version of the C compiler used.
$<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
$<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
$<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
$<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
$<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
$<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
where "tgt" is the name of a target. Target file expressions produce
a full path, but _DIR and _NAME versions can produce the directory and
file name components:
::
$<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
$<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
$<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
::
$<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
::
$<TARGET_POLICY:pol> = '1' if the policy was NEW when the 'head' target was created, else '0'. If the policy was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies.
$<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
Boolean expressions:
::
$<AND:?[,?]...> = '1' if all '?' are '1', else '0'
$<OR:?[,?]...> = '0' if all '?' are '0', else '1'
$<NOT:?> = '0' if '?' is '1', else '1'
where '?' is always either '0' or '1'.
Expressions with an implicit 'this' target:
::
$<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
add_custom_command
------------------
Add a custom build rule to the generated build system.
There are two main signatures for add_custom_command The first
signature is for adding a custom command to produce an output.
::
add_custom_command(OUTPUT output1 [output2 ...]
COMMAND command1 [ARGS] [args1...]
[COMMAND command2 [ARGS] [args2...] ...]
[MAIN_DEPENDENCY depend]
[DEPENDS [depends...]]
[IMPLICIT_DEPENDS <lang1> depend1
[<lang2> depend2] ...]
[WORKING_DIRECTORY dir]
[COMMENT comment] [VERBATIM] [APPEND])
This defines a command to generate specified OUTPUT file(s). A target
created in the same directory (CMakeLists.txt file) that specifies any
output of the custom command as a source file is given a rule to
generate the file using the command at build time. Do not list the
output in more than one independent target that may build in parallel
or the two instances of the rule may conflict (instead use
add_custom_target to drive the command and make the other targets
depend on that one). If an output name is a relative path it will be
interpreted relative to the build tree directory corresponding to the
current source directory. Note that MAIN_DEPENDENCY is completely
optional and is used as a suggestion to visual studio about where to
hang the custom command. In makefile terms this creates a new target
in the following form:
::
OUTPUT: MAIN_DEPENDENCY DEPENDS
COMMAND
If more than one command is specified they will be executed in order.
The optional ARGS argument is for backward compatibility and will be
ignored.
The second signature adds a custom command to a target such as a
library or executable. This is useful for performing an operation
before or after building the target. The command becomes part of the
target and will only execute when the target itself is built. If the
target is already built, the command will not execute.
::
add_custom_command(TARGET target
PRE_BUILD | PRE_LINK | POST_BUILD
COMMAND command1 [ARGS] [args1...]
[COMMAND command2 [ARGS] [args2...] ...]
[WORKING_DIRECTORY dir]
[COMMENT comment] [VERBATIM])
This defines a new command that will be associated with building the
specified target. When the command will happen is determined by which
of the following is specified:
::
PRE_BUILD - run before all other dependencies
PRE_LINK - run after other dependencies
POST_BUILD - run after the target has been built
Note that the PRE_BUILD option is only supported on Visual Studio 7 or
later. For all other generators PRE_BUILD will be treated as
PRE_LINK.
If WORKING_DIRECTORY is specified the command will be executed in the
directory given. If it is a relative path it will be interpreted
relative to the build tree directory corresponding to the current
source directory. If COMMENT is set, the value will be displayed as a
message before the commands are executed at build time. If APPEND is
specified the COMMAND and DEPENDS option values are appended to the
custom command for the first output specified. There must have
already been a previous call to this command with the same output.
The COMMENT, WORKING_DIRECTORY, and MAIN_DEPENDENCY options are
currently ignored when APPEND is given, but may be used in the future.
If VERBATIM is given then all arguments to the commands will be
escaped properly for the build tool so that the invoked command
receives each argument unchanged. Note that one level of escapes is
still used by the CMake language processor before add_custom_command
even sees the arguments. Use of VERBATIM is recommended as it enables
correct behavior. When VERBATIM is not given the behavior is platform
specific because there is no protection of tool-specific special
characters.
If the output of the custom command is not actually created as a file
on disk it should be marked as SYMBOLIC with
SET_SOURCE_FILES_PROPERTIES.
The IMPLICIT_DEPENDS option requests scanning of implicit dependencies
of an input file. The language given specifies the programming
language whose corresponding dependency scanner should be used.
Currently only C and CXX language scanners are supported. The
language has to be specified for every file in the IMPLICIT_DEPENDS
list. Dependencies discovered from the scanning are added to those of
the custom command at build time. Note that the IMPLICIT_DEPENDS
option is currently supported only for Makefile generators and will be
ignored by other generators.
If COMMAND specifies an executable target (created by ADD_EXECUTABLE)
it will automatically be replaced by the location of the executable
created at build time. Additionally a target-level dependency will be
added so that the executable target will be built before any target
using this custom command. However this does NOT add a file-level
dependency that would cause the custom command to re-run whenever the
executable is recompiled.
Arguments to COMMAND may use "generator expressions" with the syntax
"$<...>". Generator expressions are evaluated during build system
generation to produce information specific to each build
configuration. Valid expressions are:
::
$<0:...> = empty string (ignores "...")
$<1:...> = content of "..."
$<CONFIG:cfg> = '1' if config is "cfg", else '0'
$<CONFIGURATION> = configuration name
$<BOOL:...> = '1' if the '...' is true, else '0'
$<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
$<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
$<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
$<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
$<JOIN:list,...> = joins the list with the content of "..."
$<TARGET_NAME:...> = Marks ... as being the name of a target. This is required if exporting targets to multiple dependent export sets. The '...' must be a literal name of a target- it may not contain generator expressions.
$<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
$<BUILD_INTERFACE:...> = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
$<PLATFORM_ID> = The CMake-id of the platform $<PLATFORM_ID:comp> = '1' if the The CMake-id of the platform matches comp, otherwise '0'.
$<C_COMPILER_ID> = The CMake-id of the C compiler used.
$<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
$<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
$<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
$<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
$<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
$<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
$<C_COMPILER_VERSION> = The version of the C compiler used.
$<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
$<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
$<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
$<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
$<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
$<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
where "tgt" is the name of a target. Target file expressions produce
a full path, but _DIR and _NAME versions can produce the directory and
file name components:
::
$<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
$<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
$<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
::
$<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
Note that tgt is not added as a dependency of the target this
expression is evaluated on.
::
$<TARGET_POLICY:pol> = '1' if the policy was NEW when the 'head' target was created, else '0'. If the policy was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies.
$<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
Boolean expressions:
::
$<AND:?[,?]...> = '1' if all '?' are '1', else '0'
$<OR:?[,?]...> = '0' if all '?' are '0', else '1'
$<NOT:?> = '0' if '?' is '1', else '1'
where '?' is always either '0' or '1'.
Expressions with an implicit 'this' target:
::
$<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
References to target names in generator expressions imply target-level
dependencies, but NOT file-level dependencies. List target names with
the DEPENDS option to add file dependencies.
The DEPENDS option specifies files on which the command depends. If
any dependency is an OUTPUT of another custom command in the same
directory (CMakeLists.txt file) CMake automatically brings the other
custom command into the target in which this command is built. If
DEPENDS is not specified the command will run whenever the OUTPUT is
missing; if the command does not actually create the OUTPUT then the
rule will always run. If DEPENDS specifies any target (created by an
ADD_* command) a target-level dependency is created to make sure the
target is built before any target using this custom command.
Additionally, if the target is an executable or library a file-level
dependency is created to cause the custom command to re-run whenever
the target is recompiled.
add_custom_target
-----------------
Add a target with no output so it will always be built.
::
add_custom_target(Name [ALL] [command1 [args1...]]
[COMMAND command2 [args2...] ...]
[DEPENDS depend depend depend ... ]
[WORKING_DIRECTORY dir]
[COMMENT comment] [VERBATIM]
[SOURCES src1 [src2...]])
Adds a target with the given name that executes the given commands.
The target has no output file and is ALWAYS CONSIDERED OUT OF DATE
even if the commands try to create a file with the name of the target.
Use ADD_CUSTOM_COMMAND to generate a file with dependencies. By
default nothing depends on the custom target. Use ADD_DEPENDENCIES to
add dependencies to or from other targets. If the ALL option is
specified it indicates that this target should be added to the default
build target so that it will be run every time (the command cannot be
called ALL). The command and arguments are optional and if not
specified an empty target will be created. If WORKING_DIRECTORY is
set, then the command will be run in that directory. If it is a
relative path it will be interpreted relative to the build tree
directory corresponding to the current source directory. If COMMENT
is set, the value will be displayed as a message before the commands
are executed at build time. Dependencies listed with the DEPENDS
argument may reference files and outputs of custom commands created
with add_custom_command() in the same directory (CMakeLists.txt file).
If VERBATIM is given then all arguments to the commands will be
escaped properly for the build tool so that the invoked command
receives each argument unchanged. Note that one level of escapes is
still used by the CMake language processor before add_custom_target
even sees the arguments. Use of VERBATIM is recommended as it enables
correct behavior. When VERBATIM is not given the behavior is platform
specific because there is no protection of tool-specific special
characters.
The SOURCES option specifies additional source files to be included in
the custom target. Specified source files will be added to IDE
project files for convenience in editing even if they have not build
rules.
add_definitions
---------------
Adds -D define flags to the compilation of source files.
::
add_definitions(-DFOO -DBAR ...)
Adds flags to the compiler command line for sources in the current
directory and below. This command can be used to add any flags, but
it was originally intended to add preprocessor definitions. Flags
beginning in -D or /D that look like preprocessor definitions are
automatically added to the COMPILE_DEFINITIONS property for the
current directory. Definitions with non-trivial values may be left in
the set of flags instead of being converted for reasons of backwards
compatibility. See documentation of the directory, target, and source
file COMPILE_DEFINITIONS properties for details on adding preprocessor
definitions to specific scopes and configurations.
add_dependencies
----------------
Add a dependency between top-level targets.
::
add_dependencies(<target> [<target-dependency>]...)
Make a top-level <target> depend on other top-level targets to ensure
that they build before <target> does. A top-level target is one
created by ADD_EXECUTABLE, ADD_LIBRARY, or ADD_CUSTOM_TARGET.
Dependencies added to an IMPORTED target are followed transitively in
its place since the target itself does not build.
See the DEPENDS option of ADD_CUSTOM_TARGET and ADD_CUSTOM_COMMAND for
adding file-level dependencies in custom rules. See the
OBJECT_DEPENDS option in SET_SOURCE_FILES_PROPERTIES to add file-level
dependencies to object files.
add_executable
--------------
Add an executable to the project using the specified source files.
::
add_executable(<name> [WIN32] [MACOSX_BUNDLE]
[EXCLUDE_FROM_ALL]
source1 source2 ... sourceN)
Adds an executable target called <name> to be built from the source
files listed in the command invocation. The <name> corresponds to the
logical target name and must be globally unique within a project. The
actual file name of the executable built is constructed based on
conventions of the native platform (such as <name>.exe or just
<name>).
By default the executable file will be created in the build tree
directory corresponding to the source tree directory in which the
command was invoked. See documentation of the
RUNTIME_OUTPUT_DIRECTORY target property to change this location. See
documentation of the OUTPUT_NAME target property to change the <name>
part of the final file name.
If WIN32 is given the property WIN32_EXECUTABLE will be set on the
target created. See documentation of that target property for
details.
If MACOSX_BUNDLE is given the corresponding property will be set on
the created target. See documentation of the MACOSX_BUNDLE target
property for details.
If EXCLUDE_FROM_ALL is given the corresponding property will be set on
the created target. See documentation of the EXCLUDE_FROM_ALL target
property for details.
The add_executable command can also create IMPORTED executable targets
using this signature:
::
add_executable(<name> IMPORTED [GLOBAL])
An IMPORTED executable target references an executable file located
outside the project. No rules are generated to build it. The target
name has scope in the directory in which it is created and below, but
the GLOBAL option extends visibility. It may be referenced like any
target built within the project. IMPORTED executables are useful for
convenient reference from commands like add_custom_command. Details
about the imported executable are specified by setting properties
whose names begin in "IMPORTED_". The most important such property is
IMPORTED_LOCATION (and its per-configuration version
IMPORTED_LOCATION_<CONFIG>) which specifies the location of the main
executable file on disk. See documentation of the IMPORTED_*
properties for more information.
The signature
::
add_executable(<name> ALIAS <target>)
creates an alias, such that <name> can be used to refer to <target> in
subsequent commands. The <name> does not appear in the generated
buildsystem as a make target. The <target> may not be an IMPORTED
target or an ALIAS. Alias targets can be used as linkable targets,
targets to read properties from, executables for custom commands and
custom targets. They can also be tested for existance with the
regular if(TARGET) subcommand. The <name> may not be used to modify
properties of <target>, that is, it may not be used as the operand of
set_property, set_target_properties, target_link_libraries etc. An
ALIAS target may not be installed of exported.
add_library
-----------
Add a library to the project using the specified source files.
::
add_library(<name> [STATIC | SHARED | MODULE]
[EXCLUDE_FROM_ALL]
source1 source2 ... sourceN)
Adds a library target called <name> to be built from the source files
listed in the command invocation. The <name> corresponds to the
logical target name and must be globally unique within a project. The
actual file name of the library built is constructed based on
conventions of the native platform (such as lib<name>.a or
<name>.lib).
STATIC, SHARED, or MODULE may be given to specify the type of library
to be created. STATIC libraries are archives of object files for use
when linking other targets. SHARED libraries are linked dynamically
and loaded at runtime. MODULE libraries are plugins that are not
linked into other targets but may be loaded dynamically at runtime
using dlopen-like functionality. If no type is given explicitly the
type is STATIC or SHARED based on whether the current value of the
variable BUILD_SHARED_LIBS is true. For SHARED and MODULE libraries
the POSITION_INDEPENDENT_CODE target property is set to TRUE
automatically.
By default the library file will be created in the build tree
directory corresponding to the source tree directory in which the
command was invoked. See documentation of the
ARCHIVE_OUTPUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY, and
RUNTIME_OUTPUT_DIRECTORY target properties to change this location.
See documentation of the OUTPUT_NAME target property to change the
<name> part of the final file name.
If EXCLUDE_FROM_ALL is given the corresponding property will be set on
the created target. See documentation of the EXCLUDE_FROM_ALL target
property for details.
The add_library command can also create IMPORTED library targets using
this signature:
::
add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED
[GLOBAL])
An IMPORTED library target references a library file located outside
the project. No rules are generated to build it. The target name has
scope in the directory in which it is created and below, but the
GLOBAL option extends visibility. It may be referenced like any
target built within the project. IMPORTED libraries are useful for
convenient reference from commands like target_link_libraries.
Details about the imported library are specified by setting properties
whose names begin in "IMPORTED_". The most important such property is
IMPORTED_LOCATION (and its per-configuration version
IMPORTED_LOCATION_<CONFIG>) which specifies the location of the main
library file on disk. See documentation of the IMPORTED_* properties
for more information.
The signature
::
add_library(<name> OBJECT <src>...)
creates a special "object library" target. An object library compiles
source files but does not archive or link their object files into a
library. Instead other targets created by add_library or
add_executable may reference the objects using an expression of the
form $<TARGET_OBJECTS:objlib> as a source, where "objlib" is the
object library name. For example:
::
add_library(... $<TARGET_OBJECTS:objlib> ...)
add_executable(... $<TARGET_OBJECTS:objlib> ...)
will include objlib's object files in a library and an executable
along with those compiled from their own sources. Object libraries
may contain only sources (and headers) that compile to object files.
They may contain custom commands generating such sources, but not
PRE_BUILD, PRE_LINK, or POST_BUILD commands. Object libraries cannot
be imported, exported, installed, or linked. Some native build
systems may not like targets that have only object files, so consider
adding at least one real source file to any target that references
$<TARGET_OBJECTS:objlib>.
The signature
::
add_library(<name> ALIAS <target>)
creates an alias, such that <name> can be used to refer to <target> in
subsequent commands. The <name> does not appear in the generated
buildsystem as a make target. The <target> may not be an IMPORTED
target or an ALIAS. Alias targets can be used as linkable targets,
targets to read properties from. They can also be tested for
existance with the regular if(TARGET) subcommand. The <name> may not
be used to modify properties of <target>, that is, it may not be used
as the operand of set_property, set_target_properties,
target_link_libraries etc. An ALIAS target may not be installed of
exported.
The signature
::
add_library(<name> INTERFACE)
creates an interface target. An interface target does not directly
create build output, though it may have properties set on it and it
may be installed, exported and imported. Typically the INTERFACE_*
properties are populated on the interface target using the
set_property(), target_link_libraries(), target_include_directories()
and target_compile_defintions() commands, and then it is used as an
argument to target_link_libraries() like any other target.
add_subdirectory
----------------
Add a subdirectory to the build.
::
add_subdirectory(source_dir [binary_dir]
[EXCLUDE_FROM_ALL])
Add a subdirectory to the build. The source_dir specifies the
directory in which the source CMakeLists.txt and code files are
located. If it is a relative path it will be evaluated with respect
to the current directory (the typical usage), but it may also be an
absolute path. The binary_dir specifies the directory in which to
place the output files. If it is a relative path it will be evaluated
with respect to the current output directory, but it may also be an
absolute path. If binary_dir is not specified, the value of
source_dir, before expanding any relative path, will be used (the
typical usage). The CMakeLists.txt file in the specified source
directory will be processed immediately by CMake before processing in
the current input file continues beyond this command.
If the EXCLUDE_FROM_ALL argument is provided then targets in the
subdirectory will not be included in the ALL target of the parent
directory by default, and will be excluded from IDE project files.
Users must explicitly build targets in the subdirectory. This is
meant for use when the subdirectory contains a separate part of the
project that is useful but not necessary, such as a set of examples.
Typically the subdirectory should contain its own project() command
invocation so that a full build system will be generated in the
subdirectory (such as a VS IDE solution file). Note that inter-target
dependencies supercede this exclusion. If a target built by the
parent project depends on a target in the subdirectory, the dependee
target will be included in the parent project build system to satisfy
the dependency.
add_test
--------
Add a test to the project with the specified arguments.
::
add_test(testname Exename arg1 arg2 ... )
If the ENABLE_TESTING command has been run, this command adds a test
target to the current directory. If ENABLE_TESTING has not been run,
this command does nothing. The tests are run by the testing subsystem