--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/components/cmake/files/man7/cmake-commands.7 Wed Nov 11 12:06:59 2015 -0800
@@ -0,0 +1,7768 @@
+.\" Man page generated from reStructuredText.
+.
+.TH "CMAKE-COMMANDS" "7" "October 14, 2015" "3.3.2" "CMake"
+.SH NAME
+cmake-commands \- CMake Language Command Reference
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.SH NORMAL COMMANDS
+.sp
+These commands may be used freely in CMake projects.
+.SS add_compile_options
+.sp
+Adds options to the compilation of source files.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_compile_options(<option> ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Adds options to the compiler command line for targets in the current
+directory and below that are added after this command is invoked.
+See documentation of the \fBdirectory\fP and
+\fBtarget\fP \fBCOMPILE_OPTIONS\fP properties.
+.sp
+This command can be used to add any options, but alternative commands
+exist to add preprocessor definitions (\fBtarget_compile_definitions()\fP
+and \fBadd_definitions()\fP) or include directories
+(\fBtarget_include_directories()\fP and \fBinclude_directories()\fP).
+.sp
+Arguments to \fBadd_compile_options\fP may use "generator expressions" with
+the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP
+manual for available expressions. See the \fBcmake\-buildsystem(7)\fP
+manual for more on defining buildsystem properties.
+.SS add_custom_command
+.sp
+Add a custom build rule to the generated build system.
+.sp
+There are two main signatures for \fBadd_custom_command\fP\&.
+.SS Generating Files
+.sp
+The first signature is for adding a custom command to produce an output:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_custom_command(OUTPUT output1 [output2 ...]
+ COMMAND command1 [ARGS] [args1...]
+ [COMMAND command2 [ARGS] [args2...] ...]
+ [MAIN_DEPENDENCY depend]
+ [DEPENDS [depends...]]
+ [BYPRODUCTS [files...]]
+ [IMPLICIT_DEPENDS <lang1> depend1
+ [<lang2> depend2] ...]
+ [WORKING_DIRECTORY dir]
+ [COMMENT comment]
+ [VERBATIM] [APPEND] [USES_TERMINAL])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This defines a command to generate specified \fBOUTPUT\fP file(s).
+A target created in the same directory (\fBCMakeLists.txt\fP 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 the \fBadd_custom_target()\fP command to drive the
+command and make the other targets depend on that one).
+In makefile terms this creates a new target in the following form:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+OUTPUT: MAIN_DEPENDENCY DEPENDS
+ COMMAND
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The options are:
+.INDENT 0.0
+.TP
+.B \fBAPPEND\fP
+Append the \fBCOMMAND\fP and \fBDEPENDS\fP option values 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 \fBCOMMENT\fP, \fBMAIN_DEPENDENCY\fP, and \fBWORKING_DIRECTORY\fP
+options are currently ignored when APPEND is given, but may be
+used in the future.
+.TP
+.B \fBBYPRODUCTS\fP
+Specify the files the command is expected to produce but whose
+modification time may or may not be newer than the dependencies.
+If a byproduct name is a relative path it will be interpreted
+relative to the build tree directory corresponding to the
+current source directory.
+Each byproduct file will be marked with the \fBGENERATED\fP
+source file property automatically.
+.sp
+Explicit specification of byproducts is supported by the
+\fBNinja\fP generator to tell the \fBninja\fP build tool
+how to regenerate byproducts when they are missing. It is
+also useful when other build rules (e.g. custom commands)
+depend on the byproducts. Ninja requires a build rule for any
+generated file on which another rule depends even if there are
+order\-only dependencies to ensure the byproducts will be
+available before their dependents build.
+.sp
+The \fBBYPRODUCTS\fP option is ignored on non\-Ninja generators
+except to mark byproducts \fBGENERATED\fP\&.
+.TP
+.B \fBCOMMAND\fP
+Specify the command\-line(s) to execute at build time.
+If more than one \fBCOMMAND\fP is specified they will be executed in order,
+but \fInot\fP necessarily composed into a stateful shell or batch script.
+(To run a full script, use the \fBconfigure_file()\fP command or the
+\fBfile(GENERATE)\fP command to create it, and then specify
+a \fBCOMMAND\fP to launch it.)
+The optional \fBARGS\fP argument is for backward compatibility and
+will be ignored.
+.sp
+If \fBCOMMAND\fP specifies an executable target (created by the
+\fBadd_executable()\fP command) it will automatically be replaced
+by the location of the executable created at build time.
+(Use the \fBTARGET_FILE\fP
+\fBgenerator expression\fP to
+reference an executable later in the command line.)
+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.
+.sp
+Arguments to \fBCOMMAND\fP may use
+\fBgenerator expressions\fP\&.
+References to target names in generator expressions imply target\-level
+dependencies, but NOT file\-level dependencies. List target names with
+the \fBDEPENDS\fP option to add file\-level dependencies.
+.TP
+.B \fBCOMMENT\fP
+Display the given message before the commands are executed at
+build time.
+.TP
+.B \fBDEPENDS\fP
+Specify files on which the command depends. If any dependency is
+an \fBOUTPUT\fP of another custom command in the same directory
+(\fBCMakeLists.txt\fP file) CMake automatically brings the other
+custom command into the target in which this command is built.
+If \fBDEPENDS\fP is not specified the command will run whenever
+the \fBOUTPUT\fP is missing; if the command does not actually
+create the \fBOUTPUT\fP then the rule will always run.
+If \fBDEPENDS\fP specifies any target (created by the
+\fBadd_custom_target()\fP, \fBadd_executable()\fP, or
+\fBadd_library()\fP 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.
+.sp
+Arguments to \fBDEPENDS\fP may use
+\fBgenerator expressions\fP\&.
+.TP
+.B \fBIMPLICIT_DEPENDS\fP
+Request scanning of implicit dependencies of an input file.
+The language given specifies the programming language whose
+corresponding dependency scanner should be used.
+Currently only \fBC\fP and \fBCXX\fP language scanners are supported.
+The language has to be specified for every file in the
+\fBIMPLICIT_DEPENDS\fP list. Dependencies discovered from the
+scanning are added to those of the custom command at build time.
+Note that the \fBIMPLICIT_DEPENDS\fP option is currently supported
+only for Makefile generators and will be ignored by other generators.
+.TP
+.B \fBMAIN_DEPENDENCY\fP
+Specify the primary input source file to the command. This is
+treated just like any value given to the \fBDEPENDS\fP option
+but also suggests to Visual Studio generators where to hang
+the custom command. At most one custom command may specify a
+given source file as its main dependency.
+.TP
+.B \fBOUTPUT\fP
+Specify the output files the command is expected to produce.
+If an output name is a relative path it will be interpreted
+relative to the build tree directory corresponding to the
+current source directory.
+Each output file will be marked with the \fBGENERATED\fP
+source file property automatically.
+If the output of the custom command is not actually created
+as a file on disk it should be marked with the \fBSYMBOLIC\fP
+source file property.
+.TP
+.B \fBUSES_TERMINAL\fP
+The command will be given direct access to the terminal if possible.
+With the \fBNinja\fP generator, this places the command in
+the \fBconsole\fP \fBpool\fP\&.
+.TP
+.B \fBVERBATIM\fP
+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 \fBVERBATIM\fP is recommended as it enables
+correct behavior. When \fBVERBATIM\fP is not given the behavior
+is platform specific because there is no protection of
+tool\-specific special characters.
+.TP
+.B \fBWORKING_DIRECTORY\fP
+Execute the command with the given current working directory.
+If it is a relative path it will be interpreted relative to the
+build tree directory corresponding to the current source directory.
+.UNINDENT
+.SS Build Events
+.sp
+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.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_custom_command(TARGET target
+ PRE_BUILD | PRE_LINK | POST_BUILD
+ COMMAND command1 [ARGS] [args1...]
+ [COMMAND command2 [ARGS] [args2...] ...]
+ [BYPRODUCTS [files...]]
+ [WORKING_DIRECTORY dir]
+ [COMMENT comment]
+ [VERBATIM] [USES_TERMINAL])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+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:
+.INDENT 0.0
+.TP
+.B \fBPRE_BUILD\fP
+Run before any other rules are executed within the target.
+This is supported only on Visual Studio 7 or later.
+For all other generators \fBPRE_BUILD\fP will be treated as
+\fBPRE_LINK\fP\&.
+.TP
+.B \fBPRE_LINK\fP
+Run after sources have been compiled but before linking the binary
+or running the librarian or archiver tool of a static library.
+This is not defined for targets created by the
+\fBadd_custom_target()\fP command.
+.TP
+.B \fBPOST_BUILD\fP
+Run after all other rules within the target have been executed.
+.UNINDENT
+.SS add_custom_target
+.sp
+Add a target with no output so it will always be built.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_custom_target(Name [ALL] [command1 [args1...]]
+ [COMMAND command2 [args2...] ...]
+ [DEPENDS depend depend depend ... ]
+ [BYPRODUCTS [files...]]
+ [WORKING_DIRECTORY dir]
+ [COMMENT comment]
+ [VERBATIM] [USES_TERMINAL]
+ [SOURCES src1 [src2...]])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Adds a target with the given name that executes the given commands.
+The target has no output file and is \fIalways considered out of date\fP
+even if the commands try to create a file with the name of the target.
+Use the \fBadd_custom_command()\fP command to generate a file with
+dependencies. By default nothing depends on the custom target. Use
+the \fBadd_dependencies()\fP command to add dependencies to or
+from other targets.
+.sp
+The options are:
+.INDENT 0.0
+.TP
+.B \fBALL\fP
+Indicate that this target should be added to the default build
+target so that it will be run every time (the command cannot be
+called \fBALL\fP).
+.TP
+.B \fBBYPRODUCTS\fP
+Specify the files the command is expected to produce but whose
+modification time may or may not be updated on subsequent builds.
+If a byproduct name is a relative path it will be interpreted
+relative to the build tree directory corresponding to the
+current source directory.
+Each byproduct file will be marked with the \fBGENERATED\fP
+source file property automatically.
+.sp
+Explicit specification of byproducts is supported by the
+\fBNinja\fP generator to tell the \fBninja\fP build tool
+how to regenerate byproducts when they are missing. It is
+also useful when other build rules (e.g. custom commands)
+depend on the byproducts. Ninja requires a build rule for any
+generated file on which another rule depends even if there are
+order\-only dependencies to ensure the byproducts will be
+available before their dependents build.
+.sp
+The \fBBYPRODUCTS\fP option is ignored on non\-Ninja generators
+except to mark byproducts \fBGENERATED\fP\&.
+.TP
+.B \fBCOMMAND\fP
+Specify the command\-line(s) to execute at build time.
+If more than one \fBCOMMAND\fP is specified they will be executed in order,
+but \fInot\fP necessarily composed into a stateful shell or batch script.
+(To run a full script, use the \fBconfigure_file()\fP command or the
+\fBfile(GENERATE)\fP command to create it, and then specify
+a \fBCOMMAND\fP to launch it.)
+.sp
+If \fBCOMMAND\fP specifies an executable target (created by the
+\fBadd_executable()\fP command) 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 this custom target.
+.sp
+Arguments to \fBCOMMAND\fP may use
+\fBgenerator expressions\fP\&.
+References to target names in generator expressions imply target\-level
+dependencies.
+.sp
+The command and arguments are optional and if not specified an empty
+target will be created.
+.TP
+.B \fBCOMMENT\fP
+Display the given message before the commands are executed at
+build time.
+.TP
+.B \fBDEPENDS\fP
+Reference files and outputs of custom commands created with
+\fBadd_custom_command()\fP command calls in the same directory
+(\fBCMakeLists.txt\fP file). They will be brought up to date when
+the target is built.
+.sp
+Use the \fBadd_dependencies()\fP command to add dependencies
+on other targets.
+.TP
+.B \fBSOURCES\fP
+Specify 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 no build rules.
+.TP
+.B \fBVERBATIM\fP
+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 \fBadd_custom_target\fP even sees
+the arguments. Use of \fBVERBATIM\fP is recommended as it enables
+correct behavior. When \fBVERBATIM\fP is not given the behavior
+is platform specific because there is no protection of
+tool\-specific special characters.
+.TP
+.B \fBUSES_TERMINAL\fP
+The command will be given direct access to the terminal if possible.
+With the \fBNinja\fP generator, this places the command in
+the \fBconsole\fP \fBpool\fP\&.
+.TP
+.B \fBWORKING_DIRECTORY\fP
+Execute the command with the given current working directory.
+If it is a relative path it will be interpreted relative to the
+build tree directory corresponding to the current source directory.
+.UNINDENT
+.SS add_definitions
+.sp
+Adds \-D define flags to the compilation of source files.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_definitions(\-DFOO \-DBAR ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Adds definitions to the compiler command line for targets in the current
+directory and below (whether added before or after this command is invoked).
+This command can be used to add any flags, but it is intended to add
+preprocessor definitions (see the \fBadd_compile_options()\fP command
+to add other flags).
+Flags beginning in \-D or /D that look like preprocessor definitions are
+automatically added to the \fBCOMPILE_DEFINITIONS\fP directory
+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
+\fBdirectory\fP,
+\fBtarget\fP,
+\fBsource file\fP \fBCOMPILE_DEFINITIONS\fP
+properties for details on adding preprocessor definitions to specific
+scopes and configurations.
+.sp
+See the \fBcmake\-buildsystem(7)\fP manual for more on defining
+buildsystem properties.
+.SS add_dependencies
+.sp
+Add a dependency between top\-level targets.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_dependencies(<target> [<target\-dependency>]...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Make a top\-level \fB<target>\fP depend on other top\-level targets to
+ensure that they build before \fB<target>\fP does. A top\-level target
+is one created by one of the \fBadd_executable()\fP,
+\fBadd_library()\fP, or \fBadd_custom_target()\fP commands
+(but not targets generated by CMake like \fBinstall\fP).
+.sp
+Dependencies added to an imported target
+or an interface library are followed
+transitively in its place since the target itself does not build.
+.sp
+See the \fBDEPENDS\fP option of \fBadd_custom_target()\fP and
+\fBadd_custom_command()\fP commands for adding file\-level
+dependencies in custom rules. See the \fBOBJECT_DEPENDS\fP
+source file property to add file\-level dependencies to object files.
+.SS add_executable
+.sp
+Add an executable to the project using the specified source files.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_executable(<name> [WIN32] [MACOSX_BUNDLE]
+ [EXCLUDE_FROM_ALL]
+ source1 [source2 ...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Adds an executable target called \fB<name>\fP to be built from the source
+files listed in the command invocation. The \fB<name>\fP 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 \fB<name>.exe\fP or just
+\fB<name>\fP\&.
+.sp
+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
+\fBRUNTIME_OUTPUT_DIRECTORY\fP target property to change this
+location. See documentation of the \fBOUTPUT_NAME\fP target property
+to change the \fB<name>\fP part of the final file name.
+.sp
+If \fBWIN32\fP is given the property \fBWIN32_EXECUTABLE\fP will be
+set on the target created. See documentation of that target property for
+details.
+.sp
+If \fBMACOSX_BUNDLE\fP is given the corresponding property will be set on
+the created target. See documentation of the \fBMACOSX_BUNDLE\fP
+target property for details.
+.sp
+If \fBEXCLUDE_FROM_ALL\fP is given the corresponding property will be set on
+the created target. See documentation of the \fBEXCLUDE_FROM_ALL\fP
+target property for details.
+.sp
+Source arguments to \fBadd_executable\fP may use "generator expressions" with
+the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP
+manual for available expressions. See the \fBcmake\-buildsystem(7)\fP
+manual for more on defining buildsystem properties.
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_executable(<name> IMPORTED [GLOBAL])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+An IMPORTED executable target references an
+executable file located outside the project. No rules are generated to
+build it, and the \fBIMPORTED\fP target property is \fBTrue\fP\&. The
+target name has scope in the directory in which it is created and below, but
+the \fBGLOBAL\fP option extends visibility. It may be referenced like any
+target built within the project. \fBIMPORTED\fP executables are useful
+for convenient reference from commands like \fBadd_custom_command()\fP\&.
+Details about the imported executable are specified by setting properties
+whose names begin in \fBIMPORTED_\fP\&. The most important such property is
+\fBIMPORTED_LOCATION\fP (and its per\-configuration version
+\fBIMPORTED_LOCATION_<CONFIG>\fP) which specifies the location of
+the main executable file on disk. See documentation of the \fBIMPORTED_*\fP
+properties for more information.
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_executable(<name> ALIAS <target>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Creates an Alias Target, such that \fB<name>\fP can
+be used to refer to \fB<target>\fP in subsequent commands. The \fB<name>\fP
+does not appear in the generated buildsystem as a make target. The
+\fB<target>\fP may not be an Imported Target or an
+\fBALIAS\fP\&. \fBALIAS\fP targets can be used as targets to read properties
+from, executables for custom commands and custom targets. They can also be
+tested for existance with the regular \fBif(TARGET)\fP subcommand.
+The \fB<name>\fP may not be used to modify properties of \fB<target>\fP, that
+is, it may not be used as the operand of \fBset_property()\fP,
+\fBset_target_properties()\fP, \fBtarget_link_libraries()\fP etc.
+An \fBALIAS\fP target may not be installed or exported.
+.SS add_library
+.sp
+Add a library to the project using the specified source files.
+.SS Normal Libraries
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_library(<name> [STATIC | SHARED | MODULE]
+ [EXCLUDE_FROM_ALL]
+ source1 [source2 ...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Adds a library target called \fB<name>\fP to be built from the source files
+listed in the command invocation. The \fB<name>\fP 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 \fBlib<name>.a\fP or
+\fB<name>.lib\fP).
+.sp
+\fBSTATIC\fP, \fBSHARED\fP, or \fBMODULE\fP may be given to specify the type of
+library to be created. \fBSTATIC\fP libraries are archives of object files
+for use when linking other targets. \fBSHARED\fP libraries are linked
+dynamically and loaded at runtime. \fBMODULE\fP 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 \fBSTATIC\fP or \fBSHARED\fP based on whether the current value of the
+variable \fBBUILD_SHARED_LIBS\fP is \fBON\fP\&. For \fBSHARED\fP and
+\fBMODULE\fP libraries the \fBPOSITION_INDEPENDENT_CODE\fP target
+property is set to \fBON\fP automatically.
+.sp
+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 \fBARCHIVE_OUTPUT_DIRECTORY\fP,
+\fBLIBRARY_OUTPUT_DIRECTORY\fP, and
+\fBRUNTIME_OUTPUT_DIRECTORY\fP target properties to change this
+location. See documentation of the \fBOUTPUT_NAME\fP target
+property to change the \fB<name>\fP part of the final file name.
+.sp
+If \fBEXCLUDE_FROM_ALL\fP is given the corresponding property will be set on
+the created target. See documentation of the \fBEXCLUDE_FROM_ALL\fP
+target property for details.
+.sp
+Source arguments to \fBadd_library\fP may use "generator expressions" with
+the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP
+manual for available expressions. See the \fBcmake\-buildsystem(7)\fP
+manual for more on defining buildsystem properties.
+.SS Imported Libraries
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED
+ [GLOBAL])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+An IMPORTED library target references a library
+file located outside the project. No rules are generated to build it, and
+the \fBIMPORTED\fP target property is \fBTrue\fP\&. The target name has
+scope in the directory in which it is created and below, but the \fBGLOBAL\fP
+option extends visibility. It may be referenced like any target built
+within the project. \fBIMPORTED\fP libraries are useful for convenient
+reference from commands like \fBtarget_link_libraries()\fP\&. Details
+about the imported library are specified by setting properties whose names
+begin in \fBIMPORTED_\fP and \fBINTERFACE_\fP\&. The most important such
+property is \fBIMPORTED_LOCATION\fP (and its per\-configuration
+variant \fBIMPORTED_LOCATION_<CONFIG>\fP) which specifies the
+location of the main library file on disk. See documentation of the
+\fBIMPORTED_*\fP and \fBINTERFACE_*\fP properties for more information.
+.SS Object Libraries
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_library(<name> OBJECT <src>...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Creates an Object Library\&. An object library
+compiles source files but does not archive or link their object files into a
+library. Instead other targets created by \fI\%add_library()\fP or
+\fBadd_executable()\fP may reference the objects using an expression of the
+form \fB$<TARGET_OBJECTS:objlib>\fP as a source, where \fBobjlib\fP is the
+object library name. For example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_library(... $<TARGET_OBJECTS:objlib> ...)
+add_executable(... $<TARGET_OBJECTS:objlib> ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+will include objlib\(aqs object files in a library and an executable
+along with those compiled from their own sources. Object libraries
+may contain only sources that compile, header files, and other files
+that would not affect linking of a normal library (e.g. \fB\&.txt\fP).
+They may contain custom commands generating such sources, but not
+\fBPRE_BUILD\fP, \fBPRE_LINK\fP, or \fBPOST_BUILD\fP 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
+\fB$<TARGET_OBJECTS:objlib>\fP\&.
+.SS Alias Libraries
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_library(<name> ALIAS <target>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Creates an Alias Target, such that \fB<name>\fP can be
+used to refer to \fB<target>\fP in subsequent commands. The \fB<name>\fP does
+not appear in the generatedbuildsystem as a make target. The \fB<target>\fP
+may not be an Imported Target or an \fBALIAS\fP\&.
+\fBALIAS\fP targets can be used as linkable targets and as targets to
+read properties from. They can also be tested for existance with the
+regular \fBif(TARGET)\fP subcommand. The \fB<name>\fP may not be used
+to modify properties of \fB<target>\fP, that is, it may not be used as the
+operand of \fBset_property()\fP, \fBset_target_properties()\fP,
+\fBtarget_link_libraries()\fP etc. An \fBALIAS\fP target may not be
+installed or exported.
+.SS Interface Libraries
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_library(<name> INTERFACE [IMPORTED [GLOBAL]])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Creates an Interface Library\&. An \fBINTERFACE\fP
+library 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 \fBINTERFACE_*\fP properties are populated on
+the interface target using the commands:
+.INDENT 0.0
+.IP \(bu 2
+\fBset_property()\fP,
+.IP \(bu 2
+\fBtarget_link_libraries(INTERFACE)\fP,
+.IP \(bu 2
+\fBtarget_include_directories(INTERFACE)\fP,
+.IP \(bu 2
+\fBtarget_compile_options(INTERFACE)\fP,
+.IP \(bu 2
+\fBtarget_compile_definitions(INTERFACE)\fP, and
+.IP \(bu 2
+\fBtarget_sources(INTERFACE)\fP,
+.UNINDENT
+.sp
+and then it is used as an argument to \fBtarget_link_libraries()\fP
+like any other target.
+.sp
+An \fBINTERFACE\fP Imported Target may also be
+created with this signature. An \fBIMPORTED\fP library target references a
+library defined outside the project. The target name has scope in the
+directory in which it is created and below, but the \fBGLOBAL\fP option
+extends visibility. It may be referenced like any target built within
+the project. \fBIMPORTED\fP libraries are useful for convenient reference
+from commands like \fBtarget_link_libraries()\fP\&.
+.SS add_subdirectory
+.sp
+Add a subdirectory to the build.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_subdirectory(source_dir [binary_dir]
+ [EXCLUDE_FROM_ALL])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+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.
+.sp
+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.
+.SS add_test
+.sp
+Add a test to the project to be run by \fBctest(1)\fP\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_test(NAME <name> COMMAND <command> [<arg>...]
+ [CONFIGURATIONS <config>...]
+ [WORKING_DIRECTORY <dir>])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Add a test called \fB<name>\fP\&. The test name may not contain spaces,
+quotes, or other characters special in CMake syntax. The options are:
+.INDENT 0.0
+.TP
+.B \fBCOMMAND\fP
+Specify the test command\-line. If \fB<command>\fP specifies an
+executable target (created by \fBadd_executable()\fP) it will
+automatically be replaced by the location of the executable created
+at build time.
+.TP
+.B \fBCONFIGURATIONS\fP
+Restrict execution of the test only to the named configurations.
+.TP
+.B \fBWORKING_DIRECTORY\fP
+Set the \fBWORKING_DIRECTORY\fP test property to
+specify the working directory in which to execute the test.
+If not specified the test will be run with the current working
+directory set to the build directory corresponding to the
+current source directory.
+.UNINDENT
+.sp
+The \fBCOMMAND\fP and \fBWORKING_DIRECTORY\fP options may use "generator
+expressions" with the syntax \fB$<...>\fP\&. See the
+\fBcmake\-generator\-expressions(7)\fP manual for available expressions.
+.sp
+Example usage:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_test(NAME mytest
+ COMMAND testDriver \-\-config $<CONFIGURATION>
+ \-\-exe $<TARGET_FILE:myexe>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This creates a test \fBmytest\fP whose command runs a \fBtestDriver\fP tool
+passing the configuration name and the full path to the executable
+file produced by target \fBmyexe\fP\&.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+CMake will generate tests only if the \fBenable_testing()\fP
+command has been invoked. The \fBCTest\fP module invokes the
+command automatically when the \fBBUILD_TESTING\fP option is \fBON\fP\&.
+.UNINDENT
+.UNINDENT
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_test(<name> <command> [<arg>...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Add a test called \fB<name>\fP with the given command\-line. Unlike
+the above \fBNAME\fP signature no transformation is performed on the
+command\-line to support target names or generator expressions.
+.SS aux_source_directory
+.sp
+Find all source files in a directory.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+aux_source_directory(<dir> <variable>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Collects the names of all the source files in the specified directory
+and stores the list in the <variable> provided. This command is
+intended to be used by projects that use explicit template
+instantiation. Template instantiation files can be stored in a
+"Templates" subdirectory and collected automatically using this
+command to avoid manually listing all instantiations.
+.sp
+It is tempting to use this command to avoid writing the list of source
+files for a library or executable target. While this seems to work,
+there is no way for CMake to generate a build system that knows when a
+new source file has been added. Normally the generated build system
+knows when it needs to rerun CMake because the CMakeLists.txt file is
+modified to add a new source. When the source is just added to the
+directory without modifying this file, one would have to manually
+rerun CMake to generate a build system incorporating the new file.
+.SS break
+.sp
+Break from an enclosing foreach or while loop.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+break()
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Breaks from an enclosing foreach loop or while loop
+.sp
+See also the \fBcontinue()\fP command.
+.SS build_command
+.sp
+Get a command line to build the current project.
+This is mainly intended for internal use by the \fBCTest\fP module.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+build_command(<variable>
+ [CONFIGURATION <config>]
+ [TARGET <target>]
+ [PROJECT_NAME <projname>] # legacy, causes warning
+ )
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Sets the given \fB<variable>\fP to a command\-line string of the form:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+<cmake> \-\-build . [\-\-config <config>] [\-\-target <target>] [\-\- \-i]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+where \fB<cmake>\fP is the location of the \fBcmake(1)\fP command\-line
+tool, and \fB<config>\fP and \fB<target>\fP are the values provided to the
+\fBCONFIGURATION\fP and \fBTARGET\fP options, if any. The trailing \fB\-\- \-i\fP
+option is added for Makefile Generators if policy \fBCMP0061\fP
+is not set to \fBNEW\fP\&.
+.sp
+When invoked, this \fBcmake \-\-build\fP command line will launch the
+underlying build system tool.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+build_command(<cachevariable> <makecommand>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This second signature is deprecated, but still available for backwards
+compatibility. Use the first signature instead.
+.sp
+It sets the given \fB<cachevariable>\fP to a command\-line string as
+above but without the \fB\-\-target\fP option.
+The \fB<makecommand>\fP is ignored but should be the full path to
+msdev, devenv, nmake, make or one of the end user build tools
+for legacy invocations.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+In CMake versions prior to 3.0 this command returned a command
+line that directly invokes the native build tool for the current
+generator. Their implementation of the \fBPROJECT_NAME\fP option
+had no useful effects, so CMake now warns on use of the option.
+.UNINDENT
+.UNINDENT
+.SS cmake_host_system_information
+.sp
+Query host system specific information.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmake_host_system_information(RESULT <variable> QUERY <key> ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Queries system information of the host system on which cmake runs.
+One or more <key> can be provided to select the information to be
+queried. The list of queried values is stored in <variable>.
+.sp
+<key> can be one of the following values:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+NUMBER_OF_LOGICAL_CORES = Number of logical cores.
+NUMBER_OF_PHYSICAL_CORES = Number of physical cores.
+HOSTNAME = Hostname.
+FQDN = Fully qualified domain name.
+TOTAL_VIRTUAL_MEMORY = Total virtual memory in megabytes.
+AVAILABLE_VIRTUAL_MEMORY = Available virtual memory in megabytes.
+TOTAL_PHYSICAL_MEMORY = Total physical memory in megabytes.
+AVAILABLE_PHYSICAL_MEMORY = Available physical memory in megabytes.
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS cmake_minimum_required
+.sp
+Set the minimum required version of cmake for a project.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmake_minimum_required(VERSION major[.minor[.patch[.tweak]]]
+ [FATAL_ERROR])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If the current version of CMake is lower than that required it will
+stop processing the project and report an error. When a version
+higher than 2.4 is specified the command implicitly invokes
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmake_policy(VERSION major[.minor[.patch[.tweak]]])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+which sets the cmake policy version level to the version specified.
+When version 2.4 or lower is given the command implicitly invokes
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmake_policy(VERSION 2.4)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+which enables compatibility features for CMake 2.4 and lower.
+.sp
+The FATAL_ERROR option is accepted but ignored by CMake 2.6 and
+higher. It should be specified so CMake versions 2.4 and lower fail
+with an error instead of just a warning.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Call the \fBcmake_minimum_required()\fP command at the beginning of
+the top\-level \fBCMakeLists.txt\fP file even before calling the
+\fBproject()\fP command. It is important to establish version
+and policy settings before invoking other commands whose behavior
+they may affect. See also policy \fBCMP0000\fP\&.
+.sp
+Calling \fBcmake_minimum_required()\fP inside a \fBfunction()\fP
+limits some effects to the function scope when invoked. Such calls
+should not be made with the intention of having global effects.
+.UNINDENT
+.UNINDENT
+.SS cmake_policy
+.sp
+Manage CMake Policy settings. See the \fBcmake\-policies(7)\fP
+manual for defined policies.
+.sp
+As CMake evolves it is sometimes necessary to change existing behavior
+in order to fix bugs or improve implementations of existing features.
+The CMake Policy mechanism is designed to help keep existing projects
+building as new versions of CMake introduce changes in behavior. Each
+new policy (behavioral change) is given an identifier of the form
+\fBCMP<NNNN>\fP where \fB<NNNN>\fP is an integer index. Documentation
+associated with each policy describes the \fBOLD\fP and \fBNEW\fP behavior
+and the reason the policy was introduced. Projects may set each policy
+to select the desired behavior. When CMake needs to know which behavior
+to use it checks for a setting specified by the project. If no
+setting is available the \fBOLD\fP behavior is assumed and a warning is
+produced requesting that the policy be set.
+.SS Setting Policies by CMake Version
+.sp
+The \fBcmake_policy\fP command is used to set policies to \fBOLD\fP or \fBNEW\fP
+behavior. While setting policies individually is supported, we
+encourage projects to set policies based on CMake versions:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmake_policy(VERSION major.minor[.patch[.tweak]])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Specify that the current CMake code is written for the given
+version of CMake. All policies introduced in the specified version or
+earlier will be set to use \fBNEW\fP behavior. All policies introduced
+after the specified version will be unset (unless the
+\fBCMAKE_POLICY_DEFAULT_CMP<NNNN>\fP variable sets a default).
+This effectively requests behavior preferred as of a given CMake
+version and tells newer CMake versions to warn about their new policies.
+The policy version specified must be at least 2.4 or the command will
+report an error.
+.sp
+Note that the \fBcmake_minimum_required(VERSION)\fP
+command implicitly calls \fBcmake_policy(VERSION)\fP too.
+.SS Setting Policies Explicitly
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmake_policy(SET CMP<NNNN> NEW)
+cmake_policy(SET CMP<NNNN> OLD)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Tell CMake to use the \fBOLD\fP or \fBNEW\fP behavior for a given policy.
+Projects depending on the old behavior of a given policy may silence a
+policy warning by setting the policy state to \fBOLD\fP\&. Alternatively
+one may fix the project to work with the new behavior and set the
+policy state to \fBNEW\fP\&.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The \fBOLD\fP behavior of a policy is
+\fBdeprecated by definition\fP
+and may be removed in a future version of CMake.
+.UNINDENT
+.UNINDENT
+.SS Checking Policy Settings
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmake_policy(GET CMP<NNNN> <variable>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Check whether a given policy is set to \fBOLD\fP or \fBNEW\fP behavior.
+The output \fB<variable>\fP value will be \fBOLD\fP or \fBNEW\fP if the
+policy is set, and empty otherwise.
+.SS CMake Policy Stack
+.sp
+CMake keeps policy settings on a stack, so changes made by the
+cmake_policy command affect only the top of the stack. A new entry on
+the policy stack is managed automatically for each subdirectory to
+protect its parents and siblings. CMake also manages a new entry for
+scripts loaded by \fBinclude()\fP and \fBfind_package()\fP commands
+except when invoked with the \fBNO_POLICY_SCOPE\fP option
+(see also policy \fBCMP0011\fP).
+The \fBcmake_policy\fP command provides an interface to manage custom
+entries on the policy stack:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cmake_policy(PUSH)
+cmake_policy(POP)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Each \fBPUSH\fP must have a matching \fBPOP\fP to erase any changes.
+This is useful to make temporary changes to policy settings.
+Calls to the \fBcmake_minimum_required(VERSION)\fP,
+\fBcmake_policy(VERSION)\fP, or \fBcmake_policy(SET)\fP commands
+influence only the current top of the policy stack.
+.sp
+Commands created by the \fBfunction()\fP and \fBmacro()\fP
+commands record policy settings when they are created and
+use the pre\-record policies when they are invoked. If the function or
+macro implementation sets policies, the changes automatically
+propagate up through callers until they reach the closest nested
+policy stack entry.
+.SS configure_file
+.sp
+Copy a file to another location and modify its contents.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+configure_file(<input> <output>
+ [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
+ [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Copies an \fB<input>\fP file to an \fB<output>\fP file and substitutes
+variable values referenced as \fB@VAR@\fP or \fB${VAR}\fP in the input
+file content. Each variable reference will be replaced with the
+current value of the variable, or the empty string if the variable
+is not defined. Furthermore, input lines of the form:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+#cmakedefine VAR ...
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+will be replaced with either:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+#define VAR ...
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+or:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+/* #undef VAR */
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+depending on whether \fBVAR\fP is set in CMake to any value not considered
+a false constant by the \fBif()\fP command. The "..." content on the
+line after the variable name, if any, is processed as above.
+Input file lines of the form \fB#cmakedefine01 VAR\fP will be replaced with
+either \fB#define VAR 1\fP or \fB#define VAR 0\fP similarly.
+.sp
+If the input file is modified the build system will re\-run CMake to
+re\-configure the file and generate the build system again.
+.sp
+The arguments are:
+.INDENT 0.0
+.TP
+.B \fB<input>\fP
+Path to the input file. A relative path is treated with respect to
+the value of \fBCMAKE_CURRENT_SOURCE_DIR\fP\&. The input path
+must be a file, not a directory.
+.TP
+.B \fB<output>\fP
+Path to the output file or directory. A relative path is treated
+with respect to the value of \fBCMAKE_CURRENT_BINARY_DIR\fP\&.
+If the path names an existing directory the output file is placed
+in that directory with the same file name as the input file.
+.TP
+.B \fBCOPYONLY\fP
+Copy the file without replacing any variable references or other
+content. This option may not be used with \fBNEWLINE_STYLE\fP\&.
+.TP
+.B \fBESCAPE_QUOTES\fP
+Escape any substituted quotes with backslashes (C\-style).
+.TP
+.B \fB@ONLY\fP
+Restrict variable replacement to references of the form \fB@VAR@\fP\&.
+This is useful for configuring scripts that use \fB${VAR}\fP syntax.
+.TP
+.B \fBNEWLINE_STYLE <style>\fP
+Specify the newline style for the output file. Specify
+\fBUNIX\fP or \fBLF\fP for \fB\en\fP newlines, or specify
+\fBDOS\fP, \fBWIN32\fP, or \fBCRLF\fP for \fB\er\en\fP newlines.
+This option may not be used with \fBCOPYONLY\fP\&.
+.UNINDENT
+.SS Example
+.sp
+Consider a source tree containing a \fBfoo.h.in\fP file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+#cmakedefine FOO_ENABLE
+#cmakedefine FOO_STRING "@FOO_STRING@"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+An adjacent \fBCMakeLists.txt\fP may use \fBconfigure_file\fP to
+configure the header:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+option(FOO_ENABLE "Enable Foo" ON)
+if(FOO_ENABLE)
+ set(FOO_STRING "foo")
+endif()
+configure_file(foo.h.in foo.h @ONLY)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This creates a \fBfoo.h\fP in the build directory corresponding to
+this source directory. If the \fBFOO_ENABLE\fP option is on, the
+configured file will contain:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+#define FOO_ENABLE
+#define FOO_STRING "foo"
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Otherwise it will contain:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+/* #undef FOO_ENABLE */
+/* #undef FOO_STRING */
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+One may then use the \fBinclude_directories()\fP command to
+specify the output directory as an include directory:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+include_directories(${CMAKE_CURRENT_BINARY_DIR})
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+so that sources may include the header as \fB#include <foo.h>\fP\&.
+.SS continue
+.sp
+Continue to the top of enclosing foreach or while loop.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+continue()
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBcontinue\fP command allows a cmake script to abort the rest of a block
+in a \fBforeach()\fP or \fBwhile()\fP loop, and start at the top of
+the next iteration. See also the \fBbreak()\fP command.
+.SS create_test_sourcelist
+.sp
+Create a test driver and source list for building test programs.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+create_test_sourcelist(sourceListName driverName
+ test1 test2 test3
+ EXTRA_INCLUDE include.h
+ FUNCTION function)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+A test driver is a program that links together many small tests into a
+single executable. This is useful when building static executables
+with large libraries to shrink the total required size. The list of
+source files needed to build the test driver will be in
+sourceListName. DriverName is the name of the test driver program.
+The rest of the arguments consist of a list of test source files, can
+be semicolon separated. Each test source file should have a function
+in it that is the same name as the file with no extension (foo.cxx
+should have int foo(int, char*[]);) DriverName will be able to call
+each of the tests by name on the command line. If EXTRA_INCLUDE is
+specified, then the next argument is included into the generated file.
+If FUNCTION is specified, then the next argument is taken as a
+function name that is passed a pointer to ac and av. This can be used
+to add extra command line processing to each test. The cmake variable
+CMAKE_TESTDRIVER_BEFORE_TESTMAIN can be set to have code that will be
+placed directly before calling the test main function.
+CMAKE_TESTDRIVER_AFTER_TESTMAIN can be set to have code that will be
+placed directly after the call to the test main function.
+.SS define_property
+.sp
+Define and document custom properties.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
+ TEST | VARIABLE | CACHED_VARIABLE>
+ PROPERTY <name> [INHERITED]
+ BRIEF_DOCS <brief\-doc> [docs...]
+ FULL_DOCS <full\-doc> [docs...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Define one property in a scope for use with the set_property and
+get_property commands. This is primarily useful to associate
+documentation with property names that may be retrieved with the
+get_property command. The first argument determines the kind of scope
+in which the property should be used. It must be one of the
+following:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+GLOBAL = associated with the global namespace
+DIRECTORY = associated with one directory
+TARGET = associated with one target
+SOURCE = associated with one source file
+TEST = associated with a test named with add_test
+VARIABLE = documents a CMake language variable
+CACHED_VARIABLE = documents a CMake cache variable
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Note that unlike set_property and get_property no actual scope needs
+to be given; only the kind of scope is important.
+.sp
+The required PROPERTY option is immediately followed by the name of
+the property being defined.
+.sp
+If the INHERITED option then the get_property command will chain up to
+the next higher scope when the requested property is not set in the
+scope given to the command. DIRECTORY scope chains to GLOBAL.
+TARGET, SOURCE, and TEST chain to DIRECTORY.
+.sp
+The BRIEF_DOCS and FULL_DOCS options are followed by strings to be
+associated with the property as its brief and full documentation.
+Corresponding options to the get_property command will retrieve the
+documentation.
+.SS elseif
+.sp
+Starts the elseif portion of an if block.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+elseif(expression)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+See the if command.
+.SS else
+.sp
+Starts the else portion of an if block.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+else(expression)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+See the if command.
+.SS enable_language
+.sp
+Enable a language (CXX/C/Fortran/etc)
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+enable_language(<lang> [OPTIONAL] )
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This command enables support for the named language in CMake. This is
+the same as the project command but does not create any of the extra
+variables that are created by the project command. Example languages
+are CXX, C, Fortran.
+.sp
+This command must be called in file scope, not in a function call.
+Furthermore, it must be called in the highest directory common to all
+targets using the named language directly for compiling sources or
+indirectly through link dependencies. It is simplest to enable all
+needed languages in the top\-level directory of a project.
+.sp
+The OPTIONAL keyword is a placeholder for future implementation and
+does not currently work.
+.SS enable_testing
+.sp
+Enable testing for current directory and below.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+enable_testing()
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Enables testing for this directory and below. See also the add_test
+command. Note that ctest expects to find a test file in the build
+directory root. Therefore, this command should be in the source
+directory root.
+.SS endforeach
+.sp
+Ends a list of commands in a FOREACH block.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+endforeach(expression)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+See the FOREACH command.
+.SS endfunction
+.sp
+Ends a list of commands in a function block.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+endfunction(expression)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+See the function command.
+.SS endif
+.sp
+Ends a list of commands in an if block.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+endif(expression)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+See the if command.
+.SS endmacro
+.sp
+Ends a list of commands in a macro block.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+endmacro(expression)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+See the macro command.
+.SS endwhile
+.sp
+Ends a list of commands in a while block.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+endwhile(expression)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+See the while command.
+.SS execute_process
+.sp
+Execute one or more child processes.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+execute_process(COMMAND <cmd1> [args1...]]
+ [COMMAND <cmd2> [args2...] [...]]
+ [WORKING_DIRECTORY <directory>]
+ [TIMEOUT <seconds>]
+ [RESULT_VARIABLE <variable>]
+ [OUTPUT_VARIABLE <variable>]
+ [ERROR_VARIABLE <variable>]
+ [INPUT_FILE <file>]
+ [OUTPUT_FILE <file>]
+ [ERROR_FILE <file>]
+ [OUTPUT_QUIET]
+ [ERROR_QUIET]
+ [OUTPUT_STRIP_TRAILING_WHITESPACE]
+ [ERROR_STRIP_TRAILING_WHITESPACE])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Runs the given sequence of one or more commands with the standard
+output of each process piped to the standard input of the next.
+A single standard error pipe is used for all processes.
+.sp
+Options:
+.INDENT 0.0
+.TP
+.B COMMAND
+A child process command line.
+.sp
+CMake executes the child process using operating system APIs directly.
+All arguments are passed VERBATIM to the child process.
+No intermediate shell is used, so shell operators such as \fB>\fP
+are treated as normal arguments.
+(Use the \fBINPUT_*\fP, \fBOUTPUT_*\fP, and \fBERROR_*\fP options to
+redirect stdin, stdout, and stderr.)
+.TP
+.B WORKING_DIRECTORY
+The named directory will be set as the current working directory of
+the child processes.
+.TP
+.B TIMEOUT
+The child processes will be terminated if they do not finish in the
+specified number of seconds (fractions are allowed).
+.TP
+.B RESULT_VARIABLE
+The variable will be set to contain the result of running the processes.
+This will be an integer return code from the last child or a string
+describing an error condition.
+.TP
+.B OUTPUT_VARIABLE, ERROR_VARIABLE
+The variable named will be set with the contents of the standard output
+and standard error pipes, respectively. If the same variable is named
+for both pipes their output will be merged in the order produced.
+.TP
+.B INPUT_FILE, OUTPUT_FILE, ERROR_FILE
+The file named will be attached to the standard input of the first
+process, standard output of the last process, or standard error of
+all processes, respectively. If the same file is named for both
+output and error then it will be used for both.
+.TP
+.B OUTPUT_QUIET, ERROR_QUIET
+The standard output or standard error results will be quietly ignored.
+.UNINDENT
+.sp
+If more than one \fBOUTPUT_*\fP or \fBERROR_*\fP option is given for the
+same pipe the precedence is not specified.
+If no \fBOUTPUT_*\fP or \fBERROR_*\fP options are given the output will
+be shared with the corresponding pipes of the CMake process itself.
+.sp
+The \fI\%execute_process()\fP command is a newer more powerful version of
+\fBexec_program()\fP, but the old command has been kept for compatibility.
+Both commands run while CMake is processing the project prior to build
+system generation. Use \fBadd_custom_target()\fP and
+\fBadd_custom_command()\fP to create custom commands that run at
+build time.
+.SS export
+.sp
+Export targets from the build tree for use by outside projects.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+export(EXPORT <export\-name> [NAMESPACE <namespace>] [FILE <filename>])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Create a file <filename> that may be included by outside projects to
+import targets from the current project\(aqs build tree. This is useful
+during cross\-compiling to build utility executables that can run on
+the host platform in one project and then import them into another
+project being compiled for the target platform. If the NAMESPACE
+option is given the <namespace> string will be prepended to all target
+names written to the file.
+.sp
+Target installations are associated with the export <export\-name>
+using the \fBEXPORT\fP option of the \fBinstall(TARGETS)\fP command.
+.sp
+The file created by this command is specific to the build tree and
+should never be installed. See the install(EXPORT) command to export
+targets from an installation tree.
+.sp
+The properties set on the generated IMPORTED targets will have the
+same values as the final values of the input TARGETS.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
+ [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This signature is similar to the \fBEXPORT\fP signature, but targets are listed
+explicitly rather than specified as an export\-name. If the APPEND option is
+given the generated code will be appended to the file instead of overwriting it.
+The EXPORT_LINK_INTERFACE_LIBRARIES keyword, if present, causes the
+contents of the properties matching
+\fB(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?\fP to be exported, when
+policy CMP0022 is NEW. If a library target is included in the export
+but a target to which it links is not included the behavior is
+unspecified.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+export(PACKAGE <name>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Store the current build directory in the CMake user package registry
+for package <name>. The find_package command may consider the
+directory while searching for package <name>. This helps dependent
+projects find and use a package from the current project\(aqs build tree
+without help from the user. Note that the entry in the package
+registry that this command creates works only in conjunction with a
+package configuration file (<name>Config.cmake) that works with the
+build tree. In some cases, for example for packaging and for system
+wide installations, it is not desirable to write the user package
+registry. If the \fBCMAKE_EXPORT_NO_PACKAGE_REGISTRY\fP variable
+is enabled, the \fBexport(PACKAGE)\fP command will do nothing.
+.SS file
+.sp
+File manipulation command.
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(WRITE <filename> <content>...)
+file(APPEND <filename> <content>...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Write \fB<content>\fP into a file called \fB<filename>\fP\&. If the file does
+not exist, it will be created. If the file already exists, \fBWRITE\fP
+mode will overwrite it and \fBAPPEND\fP mode will append to the end.
+(If the file is a build input, use the \fBconfigure_file()\fP command
+to update the file only when its content changes.)
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(READ <filename> <variable>
+ [OFFSET <offset>] [LIMIT <max\-in>] [HEX])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Read content from a file called \fB<filename>\fP and store it in a
+\fB<variable>\fP\&. Optionally start from the given \fB<offset>\fP and
+read at most \fB<max\-in>\fP bytes. The \fBHEX\fP option causes data to
+be converted to a hexadecimal representation (useful for binary data).
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(STRINGS <filename> <variable> [<options>...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Parse a list of ASCII strings from \fB<filename>\fP and store it in
+\fB<variable>\fP\&. Binary data in the file are ignored. Carriage return
+(\fB\er\fP, CR) characters are ignored. The options are:
+.INDENT 0.0
+.TP
+.B \fBLENGTH_MAXIMUM <max\-len>\fP
+Consider only strings of at most a given length.
+.TP
+.B \fBLENGTH_MINIMUM <min\-len>\fP
+Consider only strings of at least a given length.
+.TP
+.B \fBLIMIT_COUNT <max\-num>\fP
+Limit the number of distinct strings to be extracted.
+.TP
+.B \fBLIMIT_INPUT <max\-in>\fP
+Limit the number of input bytes to read from the file.
+.TP
+.B \fBLIMIT_OUTPUT <max\-out>\fP
+Limit the number of total bytes to store in the \fB<variable>\fP\&.
+.TP
+.B \fBNEWLINE_CONSUME\fP
+Treat newline characters (\fB\en\fP, LF) as part of string content
+instead of terminating at them.
+.TP
+.B \fBNO_HEX_CONVERSION\fP
+Intel Hex and Motorola S\-record files are automatically converted to
+binary while reading unless this option is given.
+.TP
+.B \fBREGEX <regex>\fP
+Consider only strings that match the given regular expression.
+.TP
+.B \fBENCODING <encoding\-type>\fP
+Consider strings of a given encoding. Currently supported encodings are:
+UTF\-8, UTF\-16LE, UTF\-16BE, UTF\-32LE, UTF\-32BE. If the ENCODING option
+is not provided and the file has a Byte Order Mark, the ENCODING option
+will be defaulted to respect the Byte Order Mark.
+.UNINDENT
+.sp
+For example, the code
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(STRINGS myfile.txt myfile)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+stores a list in the variable \fBmyfile\fP in which each item is a line
+from the input file.
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> <filename> <variable>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Compute a cryptographic hash of the content of \fB<filename>\fP and
+store it in a \fB<variable>\fP\&.
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(GLOB <variable>
+ [LIST_DIRECTORIES true|false] [RELATIVE <path>]
+ [<globbing\-expressions>...])
+file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
+ [LIST_DIRECTORIES true|false] [RELATIVE <path>]
+ [<globbing\-expressions>...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Generate a list of files that match the \fB<globbing\-expressions>\fP and
+store it into the \fB<variable>\fP\&. Globbing expressions are similar to
+regular expressions, but much simpler. If \fBRELATIVE\fP flag is
+specified, the results will be returned as relative paths to the given
+path.
+.sp
+By default \fBGLOB\fP lists directories \- directories are omited in result if
+\fBLIST_DIRECTORIES\fP is set to false.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+We do not recommend using GLOB to collect a list of source files from
+your source tree. If no CMakeLists.txt file changes when a source is
+added or removed then the generated build system cannot know when to
+ask CMake to regenerate.
+.UNINDENT
+.UNINDENT
+.sp
+Examples of globbing expressions include:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+*.cxx \- match all files with extension cxx
+*.vt? \- match all files with extension vta,...,vtz
+f[3\-5].txt \- match files f3.txt, f4.txt, f5.txt
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBGLOB_RECURSE\fP mode will traverse all the subdirectories of the
+matched directory and match the files. Subdirectories that are symlinks
+are only traversed if \fBFOLLOW_SYMLINKS\fP is given or policy
+\fBCMP0009\fP is not set to \fBNEW\fP\&.
+.sp
+By default \fBGLOB_RECURSE\fP omits directories from result list \- setting
+\fBLIST_DIRECTORIES\fP to true adds directories to result list.
+If \fBFOLLOW_SYMLINKS\fP is given or policy \fBCMP0009\fP is not set to
+\fBOLD\fP then \fBLIST_DIRECTORIES\fP treats symlinks as directories.
+.sp
+Examples of recursive globbing include:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+/dir/*.py \- match all python files in /dir and subdirectories
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(RENAME <oldname> <newname>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Move a file or directory within a filesystem from \fB<oldname>\fP to
+\fB<newname>\fP, replacing the destination atomically.
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(REMOVE [<files>...])
+file(REMOVE_RECURSE [<files>...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Remove the given files. The \fBREMOVE_RECURSE\fP mode will remove the given
+files and directories, also non\-empty directories
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(MAKE_DIRECTORY [<directories>...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Create the given directories and their parents as needed.
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(RELATIVE_PATH <variable> <directory> <file>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Compute the relative path from a \fB<directory>\fP to a \fB<file>\fP and
+store it in the \fB<variable>\fP\&.
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(TO_CMAKE_PATH "<path>" <variable>)
+file(TO_NATIVE_PATH "<path>" <variable>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBTO_CMAKE_PATH\fP mode converts a native \fB<path>\fP into a cmake\-style
+path with forward\-slashes (\fB/\fP). The input can be a single path or a
+system search path like \fB$ENV{PATH}\fP\&. A search path will be converted
+to a cmake\-style list separated by \fB;\fP characters.
+.sp
+The \fBTO_NATIVE_PATH\fP mode converts a cmake\-style \fB<path>\fP into a native
+path with platform\-specific slashes (\fB\e\fP on Windows and \fB/\fP elsewhere).
+.sp
+Always use double quotes around the \fB<path>\fP to be sure it is treated
+as a single argument to this command.
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(DOWNLOAD <url> <file> [<options>...])
+file(UPLOAD <file> <url> [<options>...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBDOWNLOAD\fP mode downloads the given \fB<url>\fP to a local \fB<file>\fP\&.
+The \fBUPLOAD\fP mode uploads a local \fB<file>\fP to a given \fB<url>\fP\&.
+.sp
+Options to both \fBDOWNLOAD\fP and \fBUPLOAD\fP are:
+.INDENT 0.0
+.TP
+.B \fBINACTIVITY_TIMEOUT <seconds>\fP
+Terminate the operation after a period of inactivity.
+.TP
+.B \fBLOG <variable>\fP
+Store a human\-readable log of the operation in a variable.
+.TP
+.B \fBSHOW_PROGRESS\fP
+Print progress information as status messages until the operation is
+complete.
+.TP
+.B \fBSTATUS <variable>\fP
+Store the resulting status of the operation in a variable.
+The status is a \fB;\fP separated list of length 2.
+The first element is the numeric return value for the operation,
+and the second element is a string value for the error.
+A \fB0\fP numeric error means no error in the operation.
+.TP
+.B \fBTIMEOUT <seconds>\fP
+Terminate the operation after a given total time has elapsed.
+.UNINDENT
+.sp
+Additional options to \fBDOWNLOAD\fP are:
+.sp
+\fBEXPECTED_HASH ALGO=<value>\fP
+.INDENT 0.0
+.INDENT 3.5
+Verify that the downloaded content hash matches the expected value, where
+\fBALGO\fP is one of \fBMD5\fP, \fBSHA1\fP, \fBSHA224\fP, \fBSHA256\fP, \fBSHA384\fP, or
+\fBSHA512\fP\&. If it does not match, the operation fails with an error.
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \fBEXPECTED_MD5 <value>\fP
+Historical short\-hand for \fBEXPECTED_HASH MD5=<value>\fP\&.
+.TP
+.B \fBTLS_VERIFY <ON|OFF>\fP
+Specify whether to verify the server certificate for \fBhttps://\fP URLs.
+The default is to \fInot\fP verify.
+.TP
+.B \fBTLS_CAINFO <file>\fP
+Specify a custom Certificate Authority file for \fBhttps://\fP URLs.
+.UNINDENT
+.sp
+For \fBhttps://\fP URLs CMake must be built with OpenSSL support. \fBTLS/SSL\fP
+certificates are not checked by default. Set \fBTLS_VERIFY\fP to \fBON\fP to
+check certificates and/or use \fBEXPECTED_HASH\fP to verify downloaded content.
+If neither \fBTLS\fP option is given CMake will check variables
+\fBCMAKE_TLS_VERIFY\fP and \fBCMAKE_TLS_CAINFO\fP, respectively.
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(TIMESTAMP <filename> <variable> [<format>] [UTC])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Compute a string representation of the modification time of \fB<filename>\fP
+and store it in \fB<variable>\fP\&. Should the command be unable to obtain a
+timestamp variable will be set to the empty string ("").
+.sp
+See the \fBstring(TIMESTAMP)\fP command for documentation of
+the \fB<format>\fP and \fBUTC\fP options.
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(GENERATE OUTPUT output\-file
+ <INPUT input\-file|CONTENT content>
+ [CONDITION expression])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Generate an output file for each build configuration supported by the current
+\fBCMake Generator\fP\&. Evaluate
+\fBgenerator expressions\fP
+from the input content to produce the output content. The options are:
+.INDENT 0.0
+.TP
+.B \fBCONDITION <condition>\fP
+Generate the output file for a particular configuration only if
+the condition is true. The condition must be either \fB0\fP or \fB1\fP
+after evaluating generator expressions.
+.TP
+.B \fBCONTENT <content>\fP
+Use the content given explicitly as input.
+.TP
+.B \fBINPUT <input\-file>\fP
+Use the content from a given file as input.
+.TP
+.B \fBOUTPUT <output\-file>\fP
+Specify the output file name to generate. Use generator expressions
+such as \fB$<CONFIG>\fP to specify a configuration\-specific output file
+name. Multiple configurations may generate the same output file only
+if the generated content is identical. Otherwise, the \fB<output\-file>\fP
+must evaluate to an unique name for each configuration.
+.UNINDENT
+.sp
+Exactly one \fBCONTENT\fP or \fBINPUT\fP option must be given. A specific
+\fBOUTPUT\fP file may be named by at most one invocation of \fBfile(GENERATE)\fP\&.
+Generated files are modified on subsequent cmake runs only if their content
+is changed.
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(<COPY|INSTALL> <files>... DESTINATION <dir>
+ [FILE_PERMISSIONS <permissions>...]
+ [DIRECTORY_PERMISSIONS <permissions>...]
+ [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
+ [FILES_MATCHING]
+ [[PATTERN <pattern> | REGEX <regex>]
+ [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBCOPY\fP signature copies files, directories, and symlinks to a
+destination folder. Relative input paths are evaluated with respect
+to the current source directory, and a relative destination is
+evaluated with respect to the current build directory. Copying
+preserves input file timestamps, and optimizes out a file if it exists
+at the destination with the same timestamp. Copying preserves input
+permissions unless explicit permissions or \fBNO_SOURCE_PERMISSIONS\fP
+are given (default is \fBUSE_SOURCE_PERMISSIONS\fP).
+.sp
+See the \fBinstall(DIRECTORY)\fP command for documentation of
+permissions, \fBFILES_MATCHING\fP, \fBPATTERN\fP, \fBREGEX\fP, and
+\fBEXCLUDE\fP options. Copying directories preserves the structure
+of their content even if options are used to select a subset of
+files.
+.sp
+The \fBINSTALL\fP signature differs slightly from \fBCOPY\fP: it prints
+status messages (subject to the \fBCMAKE_INSTALL_MESSAGE\fP variable),
+and \fBNO_SOURCE_PERMISSIONS\fP is default.
+Installation scripts generated by the \fBinstall()\fP command
+use this signature (with some undocumented options for internal use).
+
+.sp
+.ce
+----
+
+.ce 0
+.sp
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+file(LOCK <path> [DIRECTORY] [RELEASE]
+ [GUARD <FUNCTION|FILE|PROCESS>]
+ [RESULT_VARIABLE <variable>]
+ [TIMEOUT <seconds>])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Lock a file specified by \fB<path>\fP if no \fBDIRECTORY\fP option present and file
+\fB<path>/cmake.lock\fP otherwise. File will be locked for scope defined by
+\fBGUARD\fP option (default value is \fBPROCESS\fP). \fBRELEASE\fP option can be used
+to unlock file explicitly. If option \fBTIMEOUT\fP is not specified CMake will
+wait until lock succeed or until fatal error occurs. If \fBTIMEOUT\fP is set to
+\fB0\fP lock will be tried once and result will be reported immediately. If
+\fBTIMEOUT\fP is not \fB0\fP CMake will try to lock file for the period specified
+by \fB<seconds>\fP value. Any errors will be interpreted as fatal if there is no
+\fBRESULT_VARIABLE\fP option. Otherwise result will be stored in \fB<variable>\fP
+and will be \fB0\fP on success or error message on failure.
+.sp
+Note that lock is advisory \- there is no guarantee that other processes will
+respect this lock, i.e. lock synchronize two or more CMake instances sharing
+some modifiable resources. Similar logic applied to \fBDIRECTORY\fP option \-
+locking parent directory doesn\(aqt prevent other \fBLOCK\fP commands to lock any
+child directory or file.
+.sp
+Trying to lock file twice is not allowed. Any intermediate directories and
+file itself will be created if they not exist. \fBGUARD\fP and \fBTIMEOUT\fP
+options ignored on \fBRELEASE\fP operation.
+.SS find_file
+.sp
+A short\-hand signature is:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_file (<VAR> name1 [path1 path2 ...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The general signature is:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_file (
+ <VAR>
+ name | NAMES name1 [name2 ...]
+ [HINTS path1 [path2 ... ENV var]]
+ [PATHS path1 [path2 ... ENV var]]
+ [PATH_SUFFIXES suffix1 [suffix2 ...]]
+ [DOC "cache documentation string"]
+ [NO_DEFAULT_PATH]
+ [NO_CMAKE_ENVIRONMENT_PATH]
+ [NO_CMAKE_PATH]
+ [NO_SYSTEM_ENVIRONMENT_PATH]
+ [NO_CMAKE_SYSTEM_PATH]
+ [CMAKE_FIND_ROOT_PATH_BOTH |
+ ONLY_CMAKE_FIND_ROOT_PATH |
+ NO_CMAKE_FIND_ROOT_PATH]
+ )
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This command is used to find a full path to named file\&.
+A cache entry named by \fB<VAR>\fP is created to store the result
+of this command.
+If the full path to a file is found the result is stored in the variable
+and the search will not be repeated unless the variable is cleared.
+If nothing is found, the result will be
+\fB<VAR>\-NOTFOUND\fP, and the search will be attempted again the
+next time find_file is invoked with the same variable.
+The name of the full path to a file that
+is searched for is specified by the names listed
+after the NAMES argument. Additional search locations
+can be specified after the PATHS argument. If ENV var is
+found in the HINTS or PATHS section the environment variable var
+will be read and converted from a system environment variable to
+a cmake style list of paths. For example ENV PATH would be a way
+to list the system path variable. The argument
+after DOC will be used for the documentation string in
+the cache.
+PATH_SUFFIXES specifies additional subdirectories to check below
+each search path.
+.sp
+If NO_DEFAULT_PATH is specified, then no additional paths are
+added to the search.
+If NO_DEFAULT_PATH is not specified, the search process is as follows:
+.INDENT 0.0
+.IP 1. 3
+Search paths specified in cmake\-specific cache variables.
+These are intended to be used on the command line with a \-DVAR=value.
+This can be skipped if NO_CMAKE_PATH is passed.
+.INDENT 3.0
+.IP \(bu 2
+<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
+<prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
+.IP \(bu 2
+CMAKE_INCLUDE_PATH
+.IP \(bu 2
+CMAKE_FRAMEWORK_PATH
+.UNINDENT
+.IP 2. 3
+Search paths specified in cmake\-specific environment variables.
+These are intended to be set in the user\(aqs shell configuration.
+This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.
+.INDENT 3.0
+.IP \(bu 2
+<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
+<prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
+.IP \(bu 2
+CMAKE_INCLUDE_PATH
+.IP \(bu 2
+CMAKE_FRAMEWORK_PATH
+.UNINDENT
+.IP 3. 3
+Search the paths specified by the HINTS option.
+These should be paths computed by system introspection, such as a
+hint provided by the location of another item already found.
+Hard\-coded guesses should be specified with the PATHS option.
+.IP 4. 3
+Search the standard system environment variables.
+This can be skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
+.INDENT 3.0
+.IP \(bu 2
+Directories in INCLUDE,
+<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
+<prefix>/include for each <prefix>/[s]bin in PATH, and
+<entry>/include for other entries in PATH,
+and the directories in PATH itself.
+.UNINDENT
+.IP 5. 3
+Search cmake variables defined in the Platform files
+for the current system. This can be skipped if NO_CMAKE_SYSTEM_PATH
+is passed.
+.INDENT 3.0
+.IP \(bu 2
+<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
+<prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
+.IP \(bu 2
+CMAKE_SYSTEM_INCLUDE_PATH
+.IP \(bu 2
+CMAKE_SYSTEM_FRAMEWORK_PATH
+.UNINDENT
+.IP 6. 3
+Search the paths specified by the PATHS option
+or in the short\-hand version of the command.
+These are typically hard\-coded guesses.
+.UNINDENT
+.sp
+On Darwin or systems supporting OS X Frameworks, the cmake variable
+CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
+.INDENT 0.0
+.IP \(bu 2
+FIRST: Try to find frameworks before standard libraries or headers.
+This is the default on Darwin.
+.IP \(bu 2
+LAST: Try to find frameworks after standard libraries or headers.
+.IP \(bu 2
+ONLY: Only try to find frameworks.
+.IP \(bu 2
+NEVER: Never try to find frameworks.
+.UNINDENT
+.sp
+On Darwin or systems supporting OS X Application Bundles, the cmake
+variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
+following:
+.INDENT 0.0
+.IP \(bu 2
+FIRST: Try to find application bundles before standard programs.
+This is the default on Darwin.
+.IP \(bu 2
+LAST: Try to find application bundles after standard programs.
+.IP \(bu 2
+ONLY: Only try to find application bundles.
+.IP \(bu 2
+NEVER: Never try to find application bundles.
+.UNINDENT
+.sp
+The CMake variable \fBCMAKE_FIND_ROOT_PATH\fP specifies one or more
+directories to be prepended to all other search directories. This
+effectively "re\-roots" the entire search under given locations.
+Paths which are descendants of the \fBCMAKE_STAGING_PREFIX\fP are excluded
+from this re\-rooting, because that variable is always a path on the host system.
+By default the \fBCMAKE_FIND_ROOT_PATH\fP is empty.
+.sp
+The \fBCMAKE_SYSROOT\fP variable can also be used to specify exactly one
+directory to use as a prefix. Setting \fBCMAKE_SYSROOT\fP also has other
+effects. See the documentation for that variable for more.
+.sp
+These variables are especially useful when cross\-compiling to
+point to the root directory of the target environment and CMake will
+search there too. By default at first the directories listed in
+\fBCMAKE_FIND_ROOT_PATH\fP are searched, then the \fBCMAKE_SYSROOT\fP
+directory is searched, and then the non\-rooted directories will be
+searched. The default behavior can be adjusted by setting
+\fBCMAKE_FIND_ROOT_PATH_MODE_INCLUDE\fP\&. This behavior can be manually
+overridden on a per\-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH
+the search order will be as described above. If
+NO_CMAKE_FIND_ROOT_PATH is used then \fBCMAKE_FIND_ROOT_PATH\fP will not be
+used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re\-rooted
+directories and directories below \fBCMAKE_STAGING_PREFIX\fP will be searched.
+.sp
+The default search order is designed to be most\-specific to
+least\-specific for common use cases.
+Projects may override the order by simply calling the command
+multiple times and using the \fBNO_*\fP options:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_file (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
+find_file (<VAR> NAMES name)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Once one of the calls succeeds the result variable will be set
+and stored in the cache so that no call will search again.
+.SS find_library
+.sp
+A short\-hand signature is:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_library (<VAR> name1 [path1 path2 ...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The general signature is:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_library (
+ <VAR>
+ name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
+ [HINTS path1 [path2 ... ENV var]]
+ [PATHS path1 [path2 ... ENV var]]
+ [PATH_SUFFIXES suffix1 [suffix2 ...]]
+ [DOC "cache documentation string"]
+ [NO_DEFAULT_PATH]
+ [NO_CMAKE_ENVIRONMENT_PATH]
+ [NO_CMAKE_PATH]
+ [NO_SYSTEM_ENVIRONMENT_PATH]
+ [NO_CMAKE_SYSTEM_PATH]
+ [CMAKE_FIND_ROOT_PATH_BOTH |
+ ONLY_CMAKE_FIND_ROOT_PATH |
+ NO_CMAKE_FIND_ROOT_PATH]
+ )
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This command is used to find a library\&.
+A cache entry named by \fB<VAR>\fP is created to store the result
+of this command.
+If the library is found the result is stored in the variable
+and the search will not be repeated unless the variable is cleared.
+If nothing is found, the result will be
+\fB<VAR>\-NOTFOUND\fP, and the search will be attempted again the
+next time find_library is invoked with the same variable.
+The name of the library that
+is searched for is specified by the names listed
+after the NAMES argument. Additional search locations
+can be specified after the PATHS argument. If ENV var is
+found in the HINTS or PATHS section the environment variable var
+will be read and converted from a system environment variable to
+a cmake style list of paths. For example ENV PATH would be a way
+to list the system path variable. The argument
+after DOC will be used for the documentation string in
+the cache.
+PATH_SUFFIXES specifies additional subdirectories to check below
+each search path.
+.sp
+If NO_DEFAULT_PATH is specified, then no additional paths are
+added to the search.
+If NO_DEFAULT_PATH is not specified, the search process is as follows:
+.INDENT 0.0
+.IP 1. 3
+Search paths specified in cmake\-specific cache variables.
+These are intended to be used on the command line with a \-DVAR=value.
+This can be skipped if NO_CMAKE_PATH is passed.
+.INDENT 3.0
+.IP \(bu 2
+<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
+<prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
+.IP \(bu 2
+CMAKE_LIBRARY_PATH
+.IP \(bu 2
+CMAKE_FRAMEWORK_PATH
+.UNINDENT
+.IP 2. 3
+Search paths specified in cmake\-specific environment variables.
+These are intended to be set in the user\(aqs shell configuration.
+This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.
+.INDENT 3.0
+.IP \(bu 2
+<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
+<prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
+.IP \(bu 2
+CMAKE_LIBRARY_PATH
+.IP \(bu 2
+CMAKE_FRAMEWORK_PATH
+.UNINDENT
+.IP 3. 3
+Search the paths specified by the HINTS option.
+These should be paths computed by system introspection, such as a
+hint provided by the location of another item already found.
+Hard\-coded guesses should be specified with the PATHS option.
+.IP 4. 3
+Search the standard system environment variables.
+This can be skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
+.INDENT 3.0
+.IP \(bu 2
+Directories in LIB,
+<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
+<prefix>/lib for each <prefix>/[s]bin in PATH, and
+<entry>/lib for other entries in PATH,
+and the directories in PATH itself.
+.UNINDENT
+.IP 5. 3
+Search cmake variables defined in the Platform files
+for the current system. This can be skipped if NO_CMAKE_SYSTEM_PATH
+is passed.
+.INDENT 3.0
+.IP \(bu 2
+<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
+<prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
+.IP \(bu 2
+CMAKE_SYSTEM_LIBRARY_PATH
+.IP \(bu 2
+CMAKE_SYSTEM_FRAMEWORK_PATH
+.UNINDENT
+.IP 6. 3
+Search the paths specified by the PATHS option
+or in the short\-hand version of the command.
+These are typically hard\-coded guesses.
+.UNINDENT
+.sp
+On Darwin or systems supporting OS X Frameworks, the cmake variable
+CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
+.INDENT 0.0
+.IP \(bu 2
+FIRST: Try to find frameworks before standard libraries or headers.
+This is the default on Darwin.
+.IP \(bu 2
+LAST: Try to find frameworks after standard libraries or headers.
+.IP \(bu 2
+ONLY: Only try to find frameworks.
+.IP \(bu 2
+NEVER: Never try to find frameworks.
+.UNINDENT
+.sp
+On Darwin or systems supporting OS X Application Bundles, the cmake
+variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
+following:
+.INDENT 0.0
+.IP \(bu 2
+FIRST: Try to find application bundles before standard programs.
+This is the default on Darwin.
+.IP \(bu 2
+LAST: Try to find application bundles after standard programs.
+.IP \(bu 2
+ONLY: Only try to find application bundles.
+.IP \(bu 2
+NEVER: Never try to find application bundles.
+.UNINDENT
+.sp
+The CMake variable \fBCMAKE_FIND_ROOT_PATH\fP specifies one or more
+directories to be prepended to all other search directories. This
+effectively "re\-roots" the entire search under given locations.
+Paths which are descendants of the \fBCMAKE_STAGING_PREFIX\fP are excluded
+from this re\-rooting, because that variable is always a path on the host system.
+By default the \fBCMAKE_FIND_ROOT_PATH\fP is empty.
+.sp
+The \fBCMAKE_SYSROOT\fP variable can also be used to specify exactly one
+directory to use as a prefix. Setting \fBCMAKE_SYSROOT\fP also has other
+effects. See the documentation for that variable for more.
+.sp
+These variables are especially useful when cross\-compiling to
+point to the root directory of the target environment and CMake will
+search there too. By default at first the directories listed in
+\fBCMAKE_FIND_ROOT_PATH\fP are searched, then the \fBCMAKE_SYSROOT\fP
+directory is searched, and then the non\-rooted directories will be
+searched. The default behavior can be adjusted by setting
+\fBCMAKE_FIND_ROOT_PATH_MODE_LIBRARY\fP\&. This behavior can be manually
+overridden on a per\-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH
+the search order will be as described above. If
+NO_CMAKE_FIND_ROOT_PATH is used then \fBCMAKE_FIND_ROOT_PATH\fP will not be
+used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re\-rooted
+directories and directories below \fBCMAKE_STAGING_PREFIX\fP will be searched.
+.sp
+The default search order is designed to be most\-specific to
+least\-specific for common use cases.
+Projects may override the order by simply calling the command
+multiple times and using the \fBNO_*\fP options:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_library (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
+find_library (<VAR> NAMES name)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Once one of the calls succeeds the result variable will be set
+and stored in the cache so that no call will search again.
+.sp
+When more than one value is given to the NAMES option this command by
+default will consider one name at a time and search every directory
+for it. The NAMES_PER_DIR option tells this command to consider one
+directory at a time and search for all names in it.
+.sp
+Each library name given to the \fBNAMES\fP option is first considered
+as a library file name and then considered with platform\-specific
+prefixes (e.g. \fBlib\fP) and suffixes (e.g. \fB\&.so\fP). Therefore one
+may specify library file names such as \fBlibfoo.a\fP directly.
+This can be used to locate static libraries on UNIX\-like systems.
+.sp
+If the library found is a framework, then VAR will be set to the full
+path to the framework <fullPath>/A.framework. When a full path to a
+framework is used as a library, CMake will use a \-framework A, and a
+\-F<fullPath> to link the framework to the target.
+.sp
+If the global property FIND_LIBRARY_USE_LIB64_PATHS is set all search
+paths will be tested as normal, with "64/" appended, and with all
+matches of "lib/" replaced with "lib64/". This property is
+automatically set for the platforms that are known to need it if at
+least one of the languages supported by the PROJECT command is
+enabled.
+.SS find_package
+.sp
+Load settings for an external project.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_package(<package> [version] [EXACT] [QUIET] [MODULE]
+ [REQUIRED] [[COMPONENTS] [components...]]
+ [OPTIONAL_COMPONENTS components...]
+ [NO_POLICY_SCOPE])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Finds and loads settings from an external project. \fB<package>_FOUND\fP
+will be set to indicate whether the package was found. When the
+package is found package\-specific information is provided through
+variables and Imported Targets documented by the package itself. The
+\fBQUIET\fP option disables messages if the package cannot be found. The
+\fBMODULE\fP option disables the second signature documented below. The
+\fBREQUIRED\fP option stops processing with an error message if the package
+cannot be found.
+.sp
+A package\-specific list of required components may be listed after the
+\fBCOMPONENTS\fP option (or after the \fBREQUIRED\fP option if present).
+Additional optional components may be listed after
+\fBOPTIONAL_COMPONENTS\fP\&. Available components and their influence on
+whether a package is considered to be found are defined by the target
+package.
+.sp
+The \fB[version]\fP argument requests a version with which the package found
+should be compatible (format is \fBmajor[.minor[.patch[.tweak]]]\fP). The
+\fBEXACT\fP option requests that the version be matched exactly. If no
+\fB[version]\fP and/or component list is given to a recursive invocation
+inside a find\-module, the corresponding arguments are forwarded
+automatically from the outer call (including the \fBEXACT\fP flag for
+\fB[version]\fP). Version support is currently provided only on a
+package\-by\-package basis (details below).
+.sp
+User code should generally look for packages using the above simple
+signature. The remainder of this command documentation specifies the
+full command signature and details of the search process. Project
+maintainers wishing to provide a package to be found by this command
+are encouraged to read on.
+.sp
+The command has two modes by which it searches for packages: "Module"
+mode and "Config" mode. Module mode is available when the command is
+invoked with the above reduced signature. CMake searches for a file
+called \fBFind<package>.cmake\fP in the \fBCMAKE_MODULE_PATH\fP
+followed by the CMake installation. If the file is found, it is read
+and processed by CMake. It is responsible for finding the package,
+checking the version, and producing any needed messages. Many
+find\-modules provide limited or no support for versioning; check
+the module documentation. If no module is found and the \fBMODULE\fP
+option is not given the command proceeds to Config mode.
+.sp
+The complete Config mode command signature is:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_package(<package> [version] [EXACT] [QUIET]
+ [REQUIRED] [[COMPONENTS] [components...]]
+ [CONFIG|NO_MODULE]
+ [NO_POLICY_SCOPE]
+ [NAMES name1 [name2 ...]]
+ [CONFIGS config1 [config2 ...]]
+ [HINTS path1 [path2 ... ]]
+ [PATHS path1 [path2 ... ]]
+ [PATH_SUFFIXES suffix1 [suffix2 ...]]
+ [NO_DEFAULT_PATH]
+ [NO_CMAKE_ENVIRONMENT_PATH]
+ [NO_CMAKE_PATH]
+ [NO_SYSTEM_ENVIRONMENT_PATH]
+ [NO_CMAKE_PACKAGE_REGISTRY]
+ [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
+ [NO_CMAKE_SYSTEM_PATH]
+ [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
+ [CMAKE_FIND_ROOT_PATH_BOTH |
+ ONLY_CMAKE_FIND_ROOT_PATH |
+ NO_CMAKE_FIND_ROOT_PATH])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBCONFIG\fP option may be used to skip Module mode explicitly and
+switch to Config mode. It is synonymous to using \fBNO_MODULE\fP\&. Config
+mode is also implied by use of options not specified in the reduced
+signature.
+.sp
+Config mode attempts to locate a configuration file provided by the
+package to be found. A cache entry called \fB<package>_DIR\fP is created to
+hold the directory containing the file. By default the command
+searches for a package with the name \fB<package>\fP\&. If the \fBNAMES\fP option
+is given the names following it are used instead of \fB<package>\fP\&. The
+command searches for a file called \fB<name>Config.cmake\fP or
+\fB<lower\-case\-name>\-config.cmake\fP for each name specified. A
+replacement set of possible configuration file names may be given
+using the \fBCONFIGS\fP option. The search procedure is specified below.
+Once found, the configuration file is read and processed by CMake.
+Since the file is provided by the package it already knows the
+location of package contents. The full path to the configuration file
+is stored in the cmake variable \fB<package>_CONFIG\fP\&.
+.sp
+All configuration files which have been considered by CMake while
+searching for an installation of the package with an appropriate
+version are stored in the cmake variable \fB<package>_CONSIDERED_CONFIGS\fP,
+the associated versions in \fB<package>_CONSIDERED_VERSIONS\fP\&.
+.sp
+If the package configuration file cannot be found CMake will generate
+an error describing the problem unless the \fBQUIET\fP argument is
+specified. If \fBREQUIRED\fP is specified and the package is not found a
+fatal error is generated and the configure step stops executing. If
+\fB<package>_DIR\fP has been set to a directory not containing a
+configuration file CMake will ignore it and search from scratch.
+.sp
+When the \fB[version]\fP argument is given Config mode will only find a
+version of the package that claims compatibility with the requested
+version (format is \fBmajor[.minor[.patch[.tweak]]]\fP). If the \fBEXACT\fP
+option is given only a version of the package claiming an exact match
+of the requested version may be found. CMake does not establish any
+convention for the meaning of version numbers. Package version
+numbers are checked by "version" files provided by the packages
+themselves. For a candidate package configuration file
+\fB<config\-file>.cmake\fP the corresponding version file is located next
+to it and named either \fB<config\-file>\-version.cmake\fP or
+\fB<config\-file>Version.cmake\fP\&. If no such version file is available
+then the configuration file is assumed to not be compatible with any
+requested version. A basic version file containing generic version
+matching code can be created using the
+\fBCMakePackageConfigHelpers\fP module. When a version file
+is found it is loaded to check the requested version number. The
+version file is loaded in a nested scope in which the following
+variables have been defined:
+.INDENT 0.0
+.TP
+.B \fBPACKAGE_FIND_NAME\fP
+the \fB<package>\fP name
+.TP
+.B \fBPACKAGE_FIND_VERSION\fP
+full requested version string
+.TP
+.B \fBPACKAGE_FIND_VERSION_MAJOR\fP
+major version if requested, else 0
+.TP
+.B \fBPACKAGE_FIND_VERSION_MINOR\fP
+minor version if requested, else 0
+.TP
+.B \fBPACKAGE_FIND_VERSION_PATCH\fP
+patch version if requested, else 0
+.TP
+.B \fBPACKAGE_FIND_VERSION_TWEAK\fP
+tweak version if requested, else 0
+.TP
+.B \fBPACKAGE_FIND_VERSION_COUNT\fP
+number of version components, 0 to 4
+.UNINDENT
+.sp
+The version file checks whether it satisfies the requested version and
+sets these variables:
+.INDENT 0.0
+.TP
+.B \fBPACKAGE_VERSION\fP
+full provided version string
+.TP
+.B \fBPACKAGE_VERSION_EXACT\fP
+true if version is exact match
+.TP
+.B \fBPACKAGE_VERSION_COMPATIBLE\fP
+true if version is compatible
+.TP
+.B \fBPACKAGE_VERSION_UNSUITABLE\fP
+true if unsuitable as any version
+.UNINDENT
+.sp
+These variables are checked by the \fBfind_package\fP command to determine
+whether the configuration file provides an acceptable version. They
+are not available after the find_package call returns. If the version
+is acceptable the following variables are set:
+.INDENT 0.0
+.TP
+.B \fB<package>_VERSION\fP
+full provided version string
+.TP
+.B \fB<package>_VERSION_MAJOR\fP
+major version if provided, else 0
+.TP
+.B \fB<package>_VERSION_MINOR\fP
+minor version if provided, else 0
+.TP
+.B \fB<package>_VERSION_PATCH\fP
+patch version if provided, else 0
+.TP
+.B \fB<package>_VERSION_TWEAK\fP
+tweak version if provided, else 0
+.TP
+.B \fB<package>_VERSION_COUNT\fP
+number of version components, 0 to 4
+.UNINDENT
+.sp
+and the corresponding package configuration file is loaded. When
+multiple package configuration files are available whose version files
+claim compatibility with the version requested it is unspecified which
+one is chosen. No attempt is made to choose a highest or closest
+version number.
+.sp
+Config mode provides an elaborate interface and search procedure.
+Much of the interface is provided for completeness and for use
+internally by find\-modules loaded by Module mode. Most user code
+should simply call:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+in order to find a package. Package maintainers providing CMake
+package configuration files are encouraged to name and install them
+such that the procedure outlined below will find them without
+requiring use of additional options.
+.sp
+CMake constructs a set of possible installation prefixes for the
+package. Under each prefix several directories are searched for a
+configuration file. The tables below show the directories searched.
+Each entry is meant for installation trees following Windows (W), UNIX
+(U), or Apple (A) conventions:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+<prefix>/ (W)
+<prefix>/(cmake|CMake)/ (W)
+<prefix>/<name>*/ (W)
+<prefix>/<name>*/(cmake|CMake)/ (W)
+<prefix>/(lib/<arch>|lib|share)/cmake/<name>*/ (U)
+<prefix>/(lib/<arch>|lib|share)/<name>*/ (U)
+<prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/ (U)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+On systems supporting OS X Frameworks and Application Bundles the
+following directories are searched for frameworks or bundles
+containing a configuration file:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+<prefix>/<name>.framework/Resources/ (A)
+<prefix>/<name>.framework/Resources/CMake/ (A)
+<prefix>/<name>.framework/Versions/*/Resources/ (A)
+<prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
+<prefix>/<name>.app/Contents/Resources/ (A)
+<prefix>/<name>.app/Contents/Resources/CMake/ (A)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In all cases the \fB<name>\fP is treated as case\-insensitive and corresponds
+to any of the names specified (\fB<package>\fP or names given by \fBNAMES\fP).
+Paths with \fBlib/<arch>\fP are enabled if the
+\fBCMAKE_LIBRARY_ARCHITECTURE\fP variable is set. If \fBPATH_SUFFIXES\fP
+is specified the suffixes are appended to each (W) or (U) directory entry
+one\-by\-one.
+.sp
+This set of directories is intended to work in cooperation with
+projects that provide configuration files in their installation trees.
+Directories above marked with (W) are intended for installations on
+Windows where the prefix may point at the top of an application\(aqs
+installation directory. Those marked with (U) are intended for
+installations on UNIX platforms where the prefix is shared by multiple
+packages. This is merely a convention, so all (W) and (U) directories
+are still searched on all platforms. Directories marked with (A) are
+intended for installations on Apple platforms. The cmake variables
+\fBCMAKE_FIND_FRAMEWORK\fP and \fBCMAKE_FIND_APPBUNDLE\fP
+determine the order of preference as specified below.
+.sp
+The set of installation prefixes is constructed using the following
+steps. If \fBNO_DEFAULT_PATH\fP is specified all \fBNO_*\fP options are
+enabled.
+.INDENT 0.0
+.IP 1. 3
+Search paths specified in cmake\-specific cache variables. These
+are intended to be used on the command line with a \fB\-DVAR=value\fP\&.
+This can be skipped if \fBNO_CMAKE_PATH\fP is passed:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+CMAKE_PREFIX_PATH
+CMAKE_FRAMEWORK_PATH
+CMAKE_APPBUNDLE_PATH
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 2. 3
+Search paths specified in cmake\-specific environment variables.
+These are intended to be set in the user\(aqs shell configuration.
+This can be skipped if \fBNO_CMAKE_ENVIRONMENT_PATH\fP is passed:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+<package>_DIR
+CMAKE_PREFIX_PATH
+CMAKE_FRAMEWORK_PATH
+CMAKE_APPBUNDLE_PATH
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 3. 3
+Search paths specified by the \fBHINTS\fP option. These should be paths
+computed by system introspection, such as a hint provided by the
+location of another item already found. Hard\-coded guesses should
+be specified with the \fBPATHS\fP option.
+.IP 4. 3
+Search the standard system environment variables. This can be
+skipped if \fBNO_SYSTEM_ENVIRONMENT_PATH\fP is passed. Path entries
+ending in \fB/bin\fP or \fB/sbin\fP are automatically converted to their
+parent directories:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+PATH
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 5. 3
+Search paths stored in the CMake User Package Registry\&.
+This can be skipped if \fBNO_CMAKE_PACKAGE_REGISTRY\fP is passed or by
+setting the \fBCMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY\fP
+to \fBTRUE\fP\&.
+See the \fBcmake\-packages(7)\fP manual for details on the user
+package registry.
+.IP 6. 3
+Search cmake variables defined in the Platform files for the
+current system. This can be skipped if \fBNO_CMAKE_SYSTEM_PATH\fP is
+passed:
+.INDENT 3.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+CMAKE_SYSTEM_PREFIX_PATH
+CMAKE_SYSTEM_FRAMEWORK_PATH
+CMAKE_SYSTEM_APPBUNDLE_PATH
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.IP 7. 3
+Search paths stored in the CMake System Package Registry\&.
+This can be skipped if \fBNO_CMAKE_SYSTEM_PACKAGE_REGISTRY\fP is passed
+or by setting the
+\fBCMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY\fP to \fBTRUE\fP\&.
+See the \fBcmake\-packages(7)\fP manual for details on the system
+package registry.
+.IP 8. 3
+Search paths specified by the \fBPATHS\fP option. These are typically
+hard\-coded guesses.
+.UNINDENT
+.sp
+On Darwin or systems supporting OS X Frameworks, the cmake variable
+CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
+.INDENT 0.0
+.IP \(bu 2
+FIRST: Try to find frameworks before standard libraries or headers.
+This is the default on Darwin.
+.IP \(bu 2
+LAST: Try to find frameworks after standard libraries or headers.
+.IP \(bu 2
+ONLY: Only try to find frameworks.
+.IP \(bu 2
+NEVER: Never try to find frameworks.
+.UNINDENT
+.sp
+On Darwin or systems supporting OS X Application Bundles, the cmake
+variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
+following:
+.INDENT 0.0
+.IP \(bu 2
+FIRST: Try to find application bundles before standard programs.
+This is the default on Darwin.
+.IP \(bu 2
+LAST: Try to find application bundles after standard programs.
+.IP \(bu 2
+ONLY: Only try to find application bundles.
+.IP \(bu 2
+NEVER: Never try to find application bundles.
+.UNINDENT
+.sp
+The CMake variable \fBCMAKE_FIND_ROOT_PATH\fP specifies one or more
+directories to be prepended to all other search directories. This
+effectively "re\-roots" the entire search under given locations.
+Paths which are descendants of the \fBCMAKE_STAGING_PREFIX\fP are excluded
+from this re\-rooting, because that variable is always a path on the host system.
+By default the \fBCMAKE_FIND_ROOT_PATH\fP is empty.
+.sp
+The \fBCMAKE_SYSROOT\fP variable can also be used to specify exactly one
+directory to use as a prefix. Setting \fBCMAKE_SYSROOT\fP also has other
+effects. See the documentation for that variable for more.
+.sp
+These variables are especially useful when cross\-compiling to
+point to the root directory of the target environment and CMake will
+search there too. By default at first the directories listed in
+\fBCMAKE_FIND_ROOT_PATH\fP are searched, then the \fBCMAKE_SYSROOT\fP
+directory is searched, and then the non\-rooted directories will be
+searched. The default behavior can be adjusted by setting
+\fBCMAKE_FIND_ROOT_PATH_MODE_PACKAGE\fP\&. This behavior can be manually
+overridden on a per\-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH
+the search order will be as described above. If
+NO_CMAKE_FIND_ROOT_PATH is used then \fBCMAKE_FIND_ROOT_PATH\fP will not be
+used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re\-rooted
+directories and directories below \fBCMAKE_STAGING_PREFIX\fP will be searched.
+.sp
+The default search order is designed to be most\-specific to
+least\-specific for common use cases.
+Projects may override the order by simply calling the command
+multiple times and using the \fBNO_*\fP options:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_package (<package> PATHS paths... NO_DEFAULT_PATH)
+find_package (<package>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Once one of the calls succeeds the result variable will be set
+and stored in the cache so that no call will search again.
+.sp
+Every non\-REQUIRED \fBfind_package\fP call can be disabled by setting the
+\fBCMAKE_DISABLE_FIND_PACKAGE_<PackageName>\fP variable to \fBTRUE\fP\&.
+.sp
+When loading a find module or package configuration file \fBfind_package\fP
+defines variables to provide information about the call arguments (and
+restores their original state before returning):
+.INDENT 0.0
+.TP
+.B \fBCMAKE_FIND_PACKAGE_NAME\fP
+the \fB<package>\fP name which is searched for
+.TP
+.B \fB<package>_FIND_REQUIRED\fP
+true if \fBREQUIRED\fP option was given
+.TP
+.B \fB<package>_FIND_QUIETLY\fP
+true if \fBQUIET\fP option was given
+.TP
+.B \fB<package>_FIND_VERSION\fP
+full requested version string
+.TP
+.B \fB<package>_FIND_VERSION_MAJOR\fP
+major version if requested, else 0
+.TP
+.B \fB<package>_FIND_VERSION_MINOR\fP
+minor version if requested, else 0
+.TP
+.B \fB<package>_FIND_VERSION_PATCH\fP
+patch version if requested, else 0
+.TP
+.B \fB<package>_FIND_VERSION_TWEAK\fP
+tweak version if requested, else 0
+.TP
+.B \fB<package>_FIND_VERSION_COUNT\fP
+number of version components, 0 to 4
+.TP
+.B \fB<package>_FIND_VERSION_EXACT\fP
+true if \fBEXACT\fP option was given
+.TP
+.B \fB<package>_FIND_COMPONENTS\fP
+list of requested components
+.TP
+.B \fB<package>_FIND_REQUIRED_<c>\fP
+true if component \fB<c>\fP is required,
+false if component \fB<c>\fP is optional
+.UNINDENT
+.sp
+In Module mode the loaded find module is responsible to honor the
+request detailed by these variables; see the find module for details.
+In Config mode \fBfind_package\fP handles \fBREQUIRED\fP, \fBQUIET\fP, and
+\fB[version]\fP options automatically but leaves it to the package
+configuration file to handle components in a way that makes sense
+for the package. The package configuration file may set
+\fB<package>_FOUND\fP to false to tell \fBfind_package\fP that component
+requirements are not satisfied.
+.sp
+See the \fBcmake_policy()\fP command documentation for discussion
+of the \fBNO_POLICY_SCOPE\fP option.
+.SS find_path
+.sp
+A short\-hand signature is:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_path (<VAR> name1 [path1 path2 ...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The general signature is:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_path (
+ <VAR>
+ name | NAMES name1 [name2 ...]
+ [HINTS path1 [path2 ... ENV var]]
+ [PATHS path1 [path2 ... ENV var]]
+ [PATH_SUFFIXES suffix1 [suffix2 ...]]
+ [DOC "cache documentation string"]
+ [NO_DEFAULT_PATH]
+ [NO_CMAKE_ENVIRONMENT_PATH]
+ [NO_CMAKE_PATH]
+ [NO_SYSTEM_ENVIRONMENT_PATH]
+ [NO_CMAKE_SYSTEM_PATH]
+ [CMAKE_FIND_ROOT_PATH_BOTH |
+ ONLY_CMAKE_FIND_ROOT_PATH |
+ NO_CMAKE_FIND_ROOT_PATH]
+ )
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This command is used to find a directory containing the named file\&.
+A cache entry named by \fB<VAR>\fP is created to store the result
+of this command.
+If the file in a directory is found the result is stored in the variable
+and the search will not be repeated unless the variable is cleared.
+If nothing is found, the result will be
+\fB<VAR>\-NOTFOUND\fP, and the search will be attempted again the
+next time find_path is invoked with the same variable.
+The name of the file in a directory that
+is searched for is specified by the names listed
+after the NAMES argument. Additional search locations
+can be specified after the PATHS argument. If ENV var is
+found in the HINTS or PATHS section the environment variable var
+will be read and converted from a system environment variable to
+a cmake style list of paths. For example ENV PATH would be a way
+to list the system path variable. The argument
+after DOC will be used for the documentation string in
+the cache.
+PATH_SUFFIXES specifies additional subdirectories to check below
+each search path.
+.sp
+If NO_DEFAULT_PATH is specified, then no additional paths are
+added to the search.
+If NO_DEFAULT_PATH is not specified, the search process is as follows:
+.INDENT 0.0
+.IP 1. 3
+Search paths specified in cmake\-specific cache variables.
+These are intended to be used on the command line with a \-DVAR=value.
+This can be skipped if NO_CMAKE_PATH is passed.
+.INDENT 3.0
+.IP \(bu 2
+<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
+<prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
+.IP \(bu 2
+CMAKE_INCLUDE_PATH
+.IP \(bu 2
+CMAKE_FRAMEWORK_PATH
+.UNINDENT
+.IP 2. 3
+Search paths specified in cmake\-specific environment variables.
+These are intended to be set in the user\(aqs shell configuration.
+This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.
+.INDENT 3.0
+.IP \(bu 2
+<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
+<prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
+.IP \(bu 2
+CMAKE_INCLUDE_PATH
+.IP \(bu 2
+CMAKE_FRAMEWORK_PATH
+.UNINDENT
+.IP 3. 3
+Search the paths specified by the HINTS option.
+These should be paths computed by system introspection, such as a
+hint provided by the location of another item already found.
+Hard\-coded guesses should be specified with the PATHS option.
+.IP 4. 3
+Search the standard system environment variables.
+This can be skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
+.INDENT 3.0
+.IP \(bu 2
+Directories in INCLUDE,
+<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
+<prefix>/include for each <prefix>/[s]bin in PATH, and
+<entry>/include for other entries in PATH,
+and the directories in PATH itself.
+.UNINDENT
+.IP 5. 3
+Search cmake variables defined in the Platform files
+for the current system. This can be skipped if NO_CMAKE_SYSTEM_PATH
+is passed.
+.INDENT 3.0
+.IP \(bu 2
+<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
+<prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
+.IP \(bu 2
+CMAKE_SYSTEM_INCLUDE_PATH
+.IP \(bu 2
+CMAKE_SYSTEM_FRAMEWORK_PATH
+.UNINDENT
+.IP 6. 3
+Search the paths specified by the PATHS option
+or in the short\-hand version of the command.
+These are typically hard\-coded guesses.
+.UNINDENT
+.sp
+On Darwin or systems supporting OS X Frameworks, the cmake variable
+CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
+.INDENT 0.0
+.IP \(bu 2
+FIRST: Try to find frameworks before standard libraries or headers.
+This is the default on Darwin.
+.IP \(bu 2
+LAST: Try to find frameworks after standard libraries or headers.
+.IP \(bu 2
+ONLY: Only try to find frameworks.
+.IP \(bu 2
+NEVER: Never try to find frameworks.
+.UNINDENT
+.sp
+On Darwin or systems supporting OS X Application Bundles, the cmake
+variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
+following:
+.INDENT 0.0
+.IP \(bu 2
+FIRST: Try to find application bundles before standard programs.
+This is the default on Darwin.
+.IP \(bu 2
+LAST: Try to find application bundles after standard programs.
+.IP \(bu 2
+ONLY: Only try to find application bundles.
+.IP \(bu 2
+NEVER: Never try to find application bundles.
+.UNINDENT
+.sp
+The CMake variable \fBCMAKE_FIND_ROOT_PATH\fP specifies one or more
+directories to be prepended to all other search directories. This
+effectively "re\-roots" the entire search under given locations.
+Paths which are descendants of the \fBCMAKE_STAGING_PREFIX\fP are excluded
+from this re\-rooting, because that variable is always a path on the host system.
+By default the \fBCMAKE_FIND_ROOT_PATH\fP is empty.
+.sp
+The \fBCMAKE_SYSROOT\fP variable can also be used to specify exactly one
+directory to use as a prefix. Setting \fBCMAKE_SYSROOT\fP also has other
+effects. See the documentation for that variable for more.
+.sp
+These variables are especially useful when cross\-compiling to
+point to the root directory of the target environment and CMake will
+search there too. By default at first the directories listed in
+\fBCMAKE_FIND_ROOT_PATH\fP are searched, then the \fBCMAKE_SYSROOT\fP
+directory is searched, and then the non\-rooted directories will be
+searched. The default behavior can be adjusted by setting
+\fBCMAKE_FIND_ROOT_PATH_MODE_INCLUDE\fP\&. This behavior can be manually
+overridden on a per\-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH
+the search order will be as described above. If
+NO_CMAKE_FIND_ROOT_PATH is used then \fBCMAKE_FIND_ROOT_PATH\fP will not be
+used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re\-rooted
+directories and directories below \fBCMAKE_STAGING_PREFIX\fP will be searched.
+.sp
+The default search order is designed to be most\-specific to
+least\-specific for common use cases.
+Projects may override the order by simply calling the command
+multiple times and using the \fBNO_*\fP options:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
+find_path (<VAR> NAMES name)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Once one of the calls succeeds the result variable will be set
+and stored in the cache so that no call will search again.
+.sp
+When searching for frameworks, if the file is specified as A/b.h, then
+the framework search will look for A.framework/Headers/b.h. If that
+is found the path will be set to the path to the framework. CMake
+will convert this to the correct \-F option to include the file.
+.SS find_program
+.sp
+A short\-hand signature is:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_program (<VAR> name1 [path1 path2 ...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The general signature is:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_program (
+ <VAR>
+ name | NAMES name1 [name2 ...]
+ [HINTS path1 [path2 ... ENV var]]
+ [PATHS path1 [path2 ... ENV var]]
+ [PATH_SUFFIXES suffix1 [suffix2 ...]]
+ [DOC "cache documentation string"]
+ [NO_DEFAULT_PATH]
+ [NO_CMAKE_ENVIRONMENT_PATH]
+ [NO_CMAKE_PATH]
+ [NO_SYSTEM_ENVIRONMENT_PATH]
+ [NO_CMAKE_SYSTEM_PATH]
+ [CMAKE_FIND_ROOT_PATH_BOTH |
+ ONLY_CMAKE_FIND_ROOT_PATH |
+ NO_CMAKE_FIND_ROOT_PATH]
+ )
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This command is used to find a program\&.
+A cache entry named by \fB<VAR>\fP is created to store the result
+of this command.
+If the program is found the result is stored in the variable
+and the search will not be repeated unless the variable is cleared.
+If nothing is found, the result will be
+\fB<VAR>\-NOTFOUND\fP, and the search will be attempted again the
+next time find_program is invoked with the same variable.
+The name of the program that
+is searched for is specified by the names listed
+after the NAMES argument. Additional search locations
+can be specified after the PATHS argument. If ENV var is
+found in the HINTS or PATHS section the environment variable var
+will be read and converted from a system environment variable to
+a cmake style list of paths. For example ENV PATH would be a way
+to list the system path variable. The argument
+after DOC will be used for the documentation string in
+the cache.
+PATH_SUFFIXES specifies additional subdirectories to check below
+each search path.
+.sp
+If NO_DEFAULT_PATH is specified, then no additional paths are
+added to the search.
+If NO_DEFAULT_PATH is not specified, the search process is as follows:
+.INDENT 0.0
+.IP 1. 3
+Search paths specified in cmake\-specific cache variables.
+These are intended to be used on the command line with a \-DVAR=value.
+This can be skipped if NO_CMAKE_PATH is passed.
+.INDENT 3.0
+.IP \(bu 2
+<prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
+.IP \(bu 2
+CMAKE_PROGRAM_PATH
+.IP \(bu 2
+CMAKE_APPBUNDLE_PATH
+.UNINDENT
+.IP 2. 3
+Search paths specified in cmake\-specific environment variables.
+These are intended to be set in the user\(aqs shell configuration.
+This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.
+.INDENT 3.0
+.IP \(bu 2
+<prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
+.IP \(bu 2
+CMAKE_PROGRAM_PATH
+.IP \(bu 2
+CMAKE_APPBUNDLE_PATH
+.UNINDENT
+.IP 3. 3
+Search the paths specified by the HINTS option.
+These should be paths computed by system introspection, such as a
+hint provided by the location of another item already found.
+Hard\-coded guesses should be specified with the PATHS option.
+.IP 4. 3
+Search the standard system environment variables.
+This can be skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
+.INDENT 3.0
+.IP \(bu 2
+PATH
+.UNINDENT
+.IP 5. 3
+Search cmake variables defined in the Platform files
+for the current system. This can be skipped if NO_CMAKE_SYSTEM_PATH
+is passed.
+.INDENT 3.0
+.IP \(bu 2
+<prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
+.IP \(bu 2
+CMAKE_SYSTEM_PROGRAM_PATH
+.IP \(bu 2
+CMAKE_SYSTEM_APPBUNDLE_PATH
+.UNINDENT
+.IP 6. 3
+Search the paths specified by the PATHS option
+or in the short\-hand version of the command.
+These are typically hard\-coded guesses.
+.UNINDENT
+.sp
+On Darwin or systems supporting OS X Frameworks, the cmake variable
+CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
+.INDENT 0.0
+.IP \(bu 2
+FIRST: Try to find frameworks before standard libraries or headers.
+This is the default on Darwin.
+.IP \(bu 2
+LAST: Try to find frameworks after standard libraries or headers.
+.IP \(bu 2
+ONLY: Only try to find frameworks.
+.IP \(bu 2
+NEVER: Never try to find frameworks.
+.UNINDENT
+.sp
+On Darwin or systems supporting OS X Application Bundles, the cmake
+variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
+following:
+.INDENT 0.0
+.IP \(bu 2
+FIRST: Try to find application bundles before standard programs.
+This is the default on Darwin.
+.IP \(bu 2
+LAST: Try to find application bundles after standard programs.
+.IP \(bu 2
+ONLY: Only try to find application bundles.
+.IP \(bu 2
+NEVER: Never try to find application bundles.
+.UNINDENT
+.sp
+The CMake variable \fBCMAKE_FIND_ROOT_PATH\fP specifies one or more
+directories to be prepended to all other search directories. This
+effectively "re\-roots" the entire search under given locations.
+Paths which are descendants of the \fBCMAKE_STAGING_PREFIX\fP are excluded
+from this re\-rooting, because that variable is always a path on the host system.
+By default the \fBCMAKE_FIND_ROOT_PATH\fP is empty.
+.sp
+The \fBCMAKE_SYSROOT\fP variable can also be used to specify exactly one
+directory to use as a prefix. Setting \fBCMAKE_SYSROOT\fP also has other
+effects. See the documentation for that variable for more.
+.sp
+These variables are especially useful when cross\-compiling to
+point to the root directory of the target environment and CMake will
+search there too. By default at first the directories listed in
+\fBCMAKE_FIND_ROOT_PATH\fP are searched, then the \fBCMAKE_SYSROOT\fP
+directory is searched, and then the non\-rooted directories will be
+searched. The default behavior can be adjusted by setting
+\fBCMAKE_FIND_ROOT_PATH_MODE_PROGRAM\fP\&. This behavior can be manually
+overridden on a per\-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH
+the search order will be as described above. If
+NO_CMAKE_FIND_ROOT_PATH is used then \fBCMAKE_FIND_ROOT_PATH\fP will not be
+used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re\-rooted
+directories and directories below \fBCMAKE_STAGING_PREFIX\fP will be searched.
+.sp
+The default search order is designed to be most\-specific to
+least\-specific for common use cases.
+Projects may override the order by simply calling the command
+multiple times and using the \fBNO_*\fP options:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+find_program (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
+find_program (<VAR> NAMES name)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Once one of the calls succeeds the result variable will be set
+and stored in the cache so that no call will search again.
+.SS fltk_wrap_ui
+.sp
+Create FLTK user interfaces Wrappers.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+fltk_wrap_ui(resultingLibraryName source1
+ source2 ... sourceN )
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Produce .h and .cxx files for all the .fl and .fld files listed. The
+resulting .h and .cxx files will be added to a variable named
+resultingLibraryName_FLTK_UI_SRCS which should be added to your
+library.
+.SS foreach
+.sp
+Evaluate a group of commands for each value in a list.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+foreach(loop_var arg1 arg2 ...)
+ COMMAND1(ARGS ...)
+ COMMAND2(ARGS ...)
+ ...
+endforeach(loop_var)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+All commands between foreach and the matching endforeach are recorded
+without being invoked. Once the endforeach is evaluated, the recorded
+list of commands is invoked once for each argument listed in the
+original foreach command. Before each iteration of the loop
+"${loop_var}" will be set as a variable with the current value in the
+list.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+foreach(loop_var RANGE total)
+foreach(loop_var RANGE start stop [step])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Foreach can also iterate over a generated range of numbers. There are
+three types of this iteration:
+.INDENT 0.0
+.IP \(bu 2
+When specifying single number, the range will have elements 0 to
+"total".
+.IP \(bu 2
+When specifying two numbers, the range will have elements from the
+first number to the second number.
+.IP \(bu 2
+The third optional number is the increment used to iterate from the
+first number to the second number.
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+foreach(loop_var IN [LISTS [list1 [...]]]
+ [ITEMS [item1 [...]]])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Iterates over a precise list of items. The LISTS option names
+list\-valued variables to be traversed, including empty elements (an
+empty string is a zero\-length list). (Note macro
+arguments are not variables.) The ITEMS option ends argument
+parsing and includes all arguments following it in the iteration.
+.SS function
+.sp
+Start recording a function for later invocation as a command:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+function(<name> [arg1 [arg2 [arg3 ...]]])
+ COMMAND1(ARGS ...)
+ COMMAND2(ARGS ...)
+ ...
+endfunction(<name>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Define a function named \fB<name>\fP that takes arguments named \fBarg1\fP,
+\fBarg2\fP, \fBarg3\fP, (...).
+Commands listed after function, but before the matching
+\fBendfunction()\fP, are not invoked until the function is invoked.
+When it is invoked, the commands recorded in the function are first
+modified by replacing formal parameters (\fB${arg1}\fP) with the arguments
+passed, and then invoked as normal commands.
+In addition to referencing the formal parameters you can reference the
+\fBARGC\fP variable which will be set to the number of arguments passed
+into the function as well as \fBARGV0\fP, \fBARGV1\fP, \fBARGV2\fP, ... which
+will have the actual values of the arguments passed in.
+This facilitates creating functions with optional arguments.
+Additionally \fBARGV\fP holds the list of all arguments given to the
+function and \fBARGN\fP holds the list of arguments past the last expected
+argument.
+Referencing to \fBARGV#\fP arguments beyond \fBARGC\fP have undefined
+behavior. Checking that \fBARGC\fP is greater than \fB#\fP is the only way
+to ensure that \fBARGV#\fP was passed to the function as an extra
+argument.
+.sp
+A function opens a new scope: see \fBset(var PARENT_SCOPE)\fP for
+details.
+.sp
+See the \fBcmake_policy()\fP command documentation for the behavior
+of policies inside functions.
+.SS get_cmake_property
+.sp
+Get a property of the CMake instance.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+get_cmake_property(VAR property)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Get a property from the CMake instance. The value of the property is
+stored in the variable VAR. If the property is not found, VAR will be
+set to "NOTFOUND". Some supported properties include: VARIABLES,
+CACHE_VARIABLES, COMMANDS, MACROS, and COMPONENTS.
+.sp
+See also the more general get_property() command.
+.SS get_directory_property
+.sp
+Get a property of DIRECTORY scope.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+get_directory_property(<variable> [DIRECTORY <dir>] <prop\-name>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Store a property of directory scope in the named variable. If the
+property is not defined the empty\-string is returned. The DIRECTORY
+argument specifies another directory from which to retrieve the
+property value. The specified directory must have already been
+traversed by CMake.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+get_directory_property(<variable> [DIRECTORY <dir>]
+ DEFINITION <var\-name>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Get a variable definition from a directory. This form is useful to
+get a variable definition from another directory.
+.sp
+See also the more general get_property() command.
+.SS get_filename_component
+.sp
+Get a specific component of a full filename.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+get_filename_component(<VAR> <FileName> <COMP> [CACHE])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Set <VAR> to a component of <FileName>, where <COMP> is one of:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+DIRECTORY = Directory without file name
+NAME = File name without directory
+EXT = File name longest extension (.b.c from d/a.b.c)
+NAME_WE = File name without directory or longest extension
+ABSOLUTE = Full path to file
+REALPATH = Full path to existing file with symlinks resolved
+PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Paths are returned with forward slashes and have no trailing slahes.
+The longest file extension is always considered. If the optional
+CACHE argument is specified, the result variable is added to the
+cache.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+get_filename_component(<VAR> FileName
+ PROGRAM [PROGRAM_ARGS <ARG_VAR>]
+ [CACHE])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The program in FileName will be found in the system search path or
+left as a full path. If PROGRAM_ARGS is present with PROGRAM, then
+any command\-line arguments present in the FileName string are split
+from the program name and stored in <ARG_VAR>. This is used to
+separate a program name from its arguments in a command line string.
+.SS get_property
+.sp
+Get a property.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+get_property(<variable>
+ <GLOBAL |
+ DIRECTORY [dir] |
+ TARGET <target> |
+ SOURCE <source> |
+ INSTALL <file> |
+ TEST <test> |
+ CACHE <entry> |
+ VARIABLE>
+ PROPERTY <name>
+ [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Get one property from one object in a scope. The first argument
+specifies the variable in which to store the result. The second
+argument determines the scope from which to get the property. It must
+be one of the following:
+.INDENT 0.0
+.TP
+.B \fBGLOBAL\fP
+Scope is unique and does not accept a name.
+.TP
+.B \fBDIRECTORY\fP
+Scope defaults to the current directory but another
+directory (already processed by CMake) may be named by full or
+relative path.
+.TP
+.B \fBTARGET\fP
+Scope must name one existing target.
+.TP
+.B \fBSOURCE\fP
+Scope must name one source file.
+.TP
+.B \fBINSTALL\fP
+Scope must name one installed file path.
+.TP
+.B \fBTEST\fP
+Scope must name one existing test.
+.TP
+.B \fBCACHE\fP
+Scope must name one cache entry.
+.TP
+.B \fBVARIABLE\fP
+Scope is unique and does not accept a name.
+.UNINDENT
+.sp
+The required \fBPROPERTY\fP option is immediately followed by the name of
+the property to get. If the property is not set an empty value is
+returned. If the \fBSET\fP option is given the variable is set to a boolean
+value indicating whether the property has been set. If the \fBDEFINED\fP
+option is given the variable is set to a boolean value indicating
+whether the property has been defined such as with the
+\fBdefine_property()\fP command.
+If \fBBRIEF_DOCS\fP or \fBFULL_DOCS\fP is given then the variable is set to a
+string containing documentation for the requested property. If
+documentation is requested for a property that has not been defined
+\fBNOTFOUND\fP is returned.
+.SS get_source_file_property
+.sp
+Get a property for a source file.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+get_source_file_property(VAR file property)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Get a property from a source file. The value of the property is
+stored in the variable VAR. If the property is not found, VAR will be
+set to "NOTFOUND". Use set_source_files_properties to set property
+values. Source file properties usually control how the file is built.
+One property that is always there is LOCATION
+.sp
+See also the more general get_property() command.
+.SS get_target_property
+.sp
+Get a property from a target.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+get_target_property(VAR target property)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Get a property from a target. The value of the property is stored in
+the variable VAR. If the property is not found, VAR will be set to
+"NOTFOUND". Use set_target_properties to set property values.
+Properties are usually used to control how a target is built, but some
+query the target instead. This command can get properties for any
+target so far created. The targets do not need to be in the current
+CMakeLists.txt file.
+.sp
+See also the more general get_property() command.
+.SS get_test_property
+.sp
+Get a property of the test.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+get_test_property(test property VAR)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Get a property from the test. The value of the property is stored in
+the variable VAR. If the test or property is not found, VAR will be
+set to "NOTFOUND". For a list of standard properties you can type cmake
+\-\-help\-property\-list.
+.sp
+See also the more general get_property() command.
+.SS if
+.sp
+Conditionally execute a group of commands.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+if(expression)
+ # then section.
+ COMMAND1(ARGS ...)
+ COMMAND2(ARGS ...)
+ ...
+elseif(expression2)
+ # elseif section.
+ COMMAND1(ARGS ...)
+ COMMAND2(ARGS ...)
+ ...
+else(expression)
+ # else section.
+ COMMAND1(ARGS ...)
+ COMMAND2(ARGS ...)
+ ...
+endif(expression)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Evaluates the given expression. If the result is true, the commands
+in the THEN section are invoked. Otherwise, the commands in the else
+section are invoked. The elseif and else sections are optional. You
+may have multiple elseif clauses. Note that the expression in the
+else and endif clause is optional. Long expressions can be used and
+there is a traditional order of precedence. Parenthetical expressions
+are evaluated first followed by unary tests such as \fBEXISTS\fP,
+\fBCOMMAND\fP, and \fBDEFINED\fP\&. Then any binary tests such as
+\fBEQUAL\fP, \fBLESS\fP, \fBGREATER\fP, \fBSTRLESS\fP, \fBSTRGREATER\fP,
+\fBSTREQUAL\fP, and \fBMATCHES\fP will be evaluated. Then boolean \fBNOT\fP
+operators and finally boolean \fBAND\fP and then \fBOR\fP operators will
+be evaluated.
+.sp
+Possible expressions are:
+.INDENT 0.0
+.TP
+.B \fBif(<constant>)\fP
+True if the constant is \fB1\fP, \fBON\fP, \fBYES\fP, \fBTRUE\fP, \fBY\fP,
+or a non\-zero number. False if the constant is \fB0\fP, \fBOFF\fP,
+\fBNO\fP, \fBFALSE\fP, \fBN\fP, \fBIGNORE\fP, \fBNOTFOUND\fP, the empty string,
+or ends in the suffix \fB\-NOTFOUND\fP\&. Named boolean constants are
+case\-insensitive. If the argument is not one of these specific
+constants, it is treated as a variable or string and the following
+signature is used.
+.TP
+.B \fBif(<variable|string>)\fP
+True if given a variable that is defined to a value that is not a false
+constant. False otherwise. (Note macro arguments are not variables.)
+.TP
+.B \fBif(NOT <expression>)\fP
+True if the expression is not true.
+.TP
+.B \fBif(<expr1> AND <expr2>)\fP
+True if both expressions would be considered true individually.
+.TP
+.B \fBif(<expr1> OR <expr2>)\fP
+True if either expression would be considered true individually.
+.TP
+.B \fBif(COMMAND command\-name)\fP
+True if the given name is a command, macro or function that can be
+invoked.
+.TP
+.B \fBif(POLICY policy\-id)\fP
+True if the given name is an existing policy (of the form \fBCMP<NNNN>\fP).
+.TP
+.B \fBif(TARGET target\-name)\fP
+True if the given name is an existing logical target name such as those
+created by the \fBadd_executable()\fP, \fBadd_library()\fP, or
+\fBadd_custom_target()\fP commands.
+.TP
+.B \fBif(EXISTS path\-to\-file\-or\-directory)\fP
+True if the named file or directory exists. Behavior is well\-defined
+only for full paths.
+.TP
+.B \fBif(file1 IS_NEWER_THAN file2)\fP
+True if file1 is newer than file2 or if one of the two files doesn\(aqt
+exist. Behavior is well\-defined only for full paths. If the file
+time stamps are exactly the same, an \fBIS_NEWER_THAN\fP comparison returns
+true, so that any dependent build operations will occur in the event
+of a tie. This includes the case of passing the same file name for
+both file1 and file2.
+.TP
+.B \fBif(IS_DIRECTORY path\-to\-directory)\fP
+True if the given name is a directory. Behavior is well\-defined only
+for full paths.
+.TP
+.B \fBif(IS_SYMLINK file\-name)\fP
+True if the given name is a symbolic link. Behavior is well\-defined
+only for full paths.
+.TP
+.B \fBif(IS_ABSOLUTE path)\fP
+True if the given path is an absolute path.
+.TP
+.B \fBif(<variable|string> MATCHES regex)\fP
+True if the given string or variable\(aqs value matches the given regular
+expression.
+.TP
+.B \fBif(<variable|string> LESS <variable|string>)\fP
+True if the given string or variable\(aqs value is a valid number and less
+than that on the right.
+.TP
+.B \fBif(<variable|string> GREATER <variable|string>)\fP
+True if the given string or variable\(aqs value is a valid number and greater
+than that on the right.
+.TP
+.B \fBif(<variable|string> EQUAL <variable|string>)\fP
+True if the given string or variable\(aqs value is a valid number and equal
+to that on the right.
+.TP
+.B \fBif(<variable|string> STRLESS <variable|string>)\fP
+True if the given string or variable\(aqs value is lexicographically less
+than the string or variable on the right.
+.TP
+.B \fBif(<variable|string> STRGREATER <variable|string>)\fP
+True if the given string or variable\(aqs value is lexicographically greater
+than the string or variable on the right.
+.TP
+.B \fBif(<variable|string> STREQUAL <variable|string>)\fP
+True if the given string or variable\(aqs value is lexicographically equal
+to the string or variable on the right.
+.TP
+.B \fBif(<variable|string> VERSION_LESS <variable|string>)\fP
+Component\-wise integer version number comparison (version format is
+\fBmajor[.minor[.patch[.tweak]]]\fP).
+.TP
+.B \fBif(<variable|string> VERSION_EQUAL <variable|string>)\fP
+Component\-wise integer version number comparison (version format is
+\fBmajor[.minor[.patch[.tweak]]]\fP).
+.TP
+.B \fBif(<variable|string> VERSION_GREATER <variable|string>)\fP
+Component\-wise integer version number comparison (version format is
+\fBmajor[.minor[.patch[.tweak]]]\fP).
+.TP
+.B \fBif(<variable|string> IN_LIST <variable>)\fP
+True if the given element is contained in the named list variable.
+.TP
+.B \fBif(DEFINED <variable>)\fP
+True if the given variable is defined. It does not matter if the
+variable is true or false just if it has been set. (Note macro
+arguments are not variables.)
+.TP
+.B \fBif((expression) AND (expression OR (expression)))\fP
+The expressions inside the parenthesis are evaluated first and then
+the remaining expression is evaluated as in the previous examples.
+Where there are nested parenthesis the innermost are evaluated as part
+of evaluating the expression that contains them.
+.UNINDENT
+.sp
+The if command was written very early in CMake\(aqs history, predating
+the \fB${}\fP variable evaluation syntax, and for convenience evaluates
+variables named by its arguments as shown in the above signatures.
+Note that normal variable evaluation with \fB${}\fP applies before the if
+command even receives the arguments. Therefore code like:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+set(var1 OFF)
+set(var2 "var1")
+if(${var2})
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+appears to the if command as:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+if(var1)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+and is evaluated according to the \fBif(<variable>)\fP case documented
+above. The result is \fBOFF\fP which is false. However, if we remove the
+\fB${}\fP from the example then the command sees:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+if(var2)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+which is true because \fBvar2\fP is defined to "var1" which is not a false
+constant.
+.sp
+Automatic evaluation applies in the other cases whenever the
+above\-documented signature accepts \fB<variable|string>\fP:
+.INDENT 0.0
+.IP \(bu 2
+The left hand argument to \fBMATCHES\fP is first checked to see if it is
+a defined variable, if so the variable\(aqs value is used, otherwise the
+original value is used.
+.IP \(bu 2
+If the left hand argument to \fBMATCHES\fP is missing it returns false
+without error
+.IP \(bu 2
+Both left and right hand arguments to \fBLESS\fP, \fBGREATER\fP, and
+\fBEQUAL\fP are independently tested to see if they are defined
+variables, if so their defined values are used otherwise the original
+value is used.
+.IP \(bu 2
+Both left and right hand arguments to \fBSTRLESS\fP, \fBSTREQUAL\fP, and
+\fBSTRGREATER\fP are independently tested to see if they are defined
+variables, if so their defined values are used otherwise the original
+value is used.
+.IP \(bu 2
+Both left and right hand arguments to \fBVERSION_LESS\fP,
+\fBVERSION_EQUAL\fP, and \fBVERSION_GREATER\fP are independently tested
+to see if they are defined variables, if so their defined values are
+used otherwise the original value is used.
+.IP \(bu 2
+The right hand argument to \fBNOT\fP is tested to see if it is a boolean
+constant, if so the value is used, otherwise it is assumed to be a
+variable and it is dereferenced.
+.IP \(bu 2
+The left and right hand arguments to \fBAND\fP and \fBOR\fP are independently
+tested to see if they are boolean constants, if so they are used as
+such, otherwise they are assumed to be variables and are dereferenced.
+.UNINDENT
+.sp
+To prevent ambiguity, potential variable or keyword names can be
+specified in a Quoted Argument or a Bracket Argument\&.
+A quoted or bracketed variable or keyword will be interpreted as a
+string and not dereferenced or interpreted.
+See policy \fBCMP0054\fP\&.
+.SS include_directories
+.sp
+Add include directories to the build.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Add the given directories to those the compiler uses to search for
+include files. Relative paths are interpreted as relative to the
+current source directory.
+.sp
+The include directories are added to the \fBINCLUDE_DIRECTORIES\fP
+directory property for the current \fBCMakeLists\fP file. They are also
+added to the \fBINCLUDE_DIRECTORIES\fP target property for each
+target in the current \fBCMakeLists\fP file. The target property values
+are the ones used by the generators.
+.sp
+By default the directories specified are appended onto the current list of
+directories. This default behavior can be changed by setting
+\fBCMAKE_INCLUDE_DIRECTORIES_BEFORE\fP to \fBON\fP\&. By using
+\fBAFTER\fP or \fBBEFORE\fP explicitly, you can select between appending and
+prepending, independent of the default.
+.sp
+If the \fBSYSTEM\fP option is given, the compiler will be told the
+directories are meant as system include directories on some platforms.
+Signalling this setting might achieve effects such as the compiler
+skipping warnings, or these fixed\-install system files not being
+considered in dependency calculations \- see compiler docs.
+.sp
+Arguments to \fBinclude_directories\fP may use "generator expressions" with
+the syntax "$<...>". See the \fBcmake\-generator\-expressions(7)\fP
+manual for available expressions. See the \fBcmake\-buildsystem(7)\fP
+manual for more on defining buildsystem properties.
+.SS include_external_msproject
+.sp
+Include an external Microsoft project file in a workspace.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+include_external_msproject(projectname location
+ [TYPE projectTypeGUID]
+ [GUID projectGUID]
+ [PLATFORM platformName]
+ dep1 dep2 ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Includes an external Microsoft project in the generated workspace
+file. Currently does nothing on UNIX. This will create a target
+named [projectname]. This can be used in the add_dependencies command
+to make things depend on the external project.
+.sp
+TYPE, GUID and PLATFORM are optional parameters that allow one to
+specify the type of project, id (GUID) of the project and the name of
+the target platform. This is useful for projects requiring values
+other than the default (e.g. WIX projects). These options are not
+supported by the Visual Studio 6 generator.
+.SS include_regular_expression
+.sp
+Set the regular expression used for dependency checking.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+include_regular_expression(regex_match [regex_complain])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Set the regular expressions used in dependency checking. Only files
+matching regex_match will be traced as dependencies. Only files
+matching regex_complain will generate warnings if they cannot be found
+(standard header paths are not searched). The defaults are:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+regex_match = "^.*$" (match everything)
+regex_complain = "^$" (match empty string only)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS include
+.sp
+Load and run CMake code from a file or module.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
+ [NO_POLICY_SCOPE])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Load and run CMake code from the file given. Variable reads and
+writes access the scope of the caller (dynamic scoping). If OPTIONAL
+is present, then no error is raised if the file does not exist. If
+RESULT_VARIABLE is given the variable will be set to the full filename
+which has been included or NOTFOUND if it failed.
+.sp
+If a module is specified instead of a file, the file with name
+<modulename>.cmake is searched first in CMAKE_MODULE_PATH, then in the
+CMake module directory. There is one exception to this: if the file
+which calls include() is located itself in the CMake module directory,
+then first the CMake module directory is searched and
+CMAKE_MODULE_PATH afterwards. See also policy CMP0017.
+.sp
+See the cmake_policy() command documentation for discussion of the
+NO_POLICY_SCOPE option.
+.SS install
+.sp
+Specify rules to run at install time.
+.SS Introduction
+.sp
+This command generates installation rules for a project. Rules
+specified by calls to this command within a source directory are
+executed in order during installation. The order across directories
+is not defined.
+.sp
+There are multiple signatures for this command. Some of them define
+installation options for files and targets. Options common to
+multiple signatures are covered here but they are valid only for
+signatures that specify them. The common options are:
+.INDENT 0.0
+.TP
+.B \fBDESTINATION\fP
+Specify the directory on disk to which a file will be installed.
+If a full path (with a leading slash or drive letter) is given
+it is used directly. If a relative path is given it is interpreted
+relative to the value of the \fBCMAKE_INSTALL_PREFIX\fP variable.
+The prefix can be relocated at install time using the \fBDESTDIR\fP
+mechanism explained in the \fBCMAKE_INSTALL_PREFIX\fP variable
+documentation.
+.TP
+.B \fBPERMISSIONS\fP
+Specify permissions for installed files. Valid permissions are
+\fBOWNER_READ\fP, \fBOWNER_WRITE\fP, \fBOWNER_EXECUTE\fP, \fBGROUP_READ\fP,
+\fBGROUP_WRITE\fP, \fBGROUP_EXECUTE\fP, \fBWORLD_READ\fP, \fBWORLD_WRITE\fP,
+\fBWORLD_EXECUTE\fP, \fBSETUID\fP, and \fBSETGID\fP\&. Permissions that do
+not make sense on certain platforms are ignored on those platforms.
+.TP
+.B \fBCONFIGURATIONS\fP
+Specify a list of build configurations for which the install rule
+applies (Debug, Release, etc.).
+.TP
+.B \fBCOMPONENT\fP
+Specify an installation component name with which the install rule
+is associated, such as "runtime" or "development". During
+component\-specific installation only install rules associated with
+the given component name will be executed. During a full installation
+all components are installed. If \fBCOMPONENT\fP is not provided a
+default component "Unspecified" is created. The default component
+name may be controlled with the
+\fBCMAKE_INSTALL_DEFAULT_COMPONENT_NAME\fP variable.
+.TP
+.B \fBRENAME\fP
+Specify a name for an installed file that may be different from the
+original file. Renaming is allowed only when a single file is
+installed by the command.
+.TP
+.B \fBOPTIONAL\fP
+Specify that it is not an error if the file to be installed does
+not exist.
+.UNINDENT
+.sp
+Command signatures that install files may print messages during
+installation. Use the \fBCMAKE_INSTALL_MESSAGE\fP variable
+to control which messages are printed.
+.SS Installing Targets
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install(TARGETS targets... [EXPORT <export\-name>]
+ [[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE|
+ PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
+ [DESTINATION <dir>]
+ [INCLUDES DESTINATION [<dir> ...]]
+ [PERMISSIONS permissions...]
+ [CONFIGURATIONS [Debug|Release|...]]
+ [COMPONENT <component>]
+ [OPTIONAL] [NAMELINK_ONLY|NAMELINK_SKIP]
+ ] [...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBTARGETS\fP form specifies rules for installing targets from a
+project. There are five kinds of target files that may be installed:
+\fBARCHIVE\fP, \fBLIBRARY\fP, \fBRUNTIME\fP, \fBFRAMEWORK\fP, and \fBBUNDLE\fP\&.
+Executables are treated as \fBRUNTIME\fP targets, except that those
+marked with the \fBMACOSX_BUNDLE\fP property are treated as \fBBUNDLE\fP
+targets on OS X. Static libraries are always treated as \fBARCHIVE\fP
+targets. Module libraries are always treated as \fBLIBRARY\fP targets.
+For non\-DLL platforms shared libraries are treated as \fBLIBRARY\fP
+targets, except that those marked with the \fBFRAMEWORK\fP property are
+treated as \fBFRAMEWORK\fP targets on OS X. For DLL platforms the DLL
+part of a shared library is treated as a \fBRUNTIME\fP target and the
+corresponding import library is treated as an \fBARCHIVE\fP target.
+All Windows\-based systems including Cygwin are DLL platforms.
+The \fBARCHIVE\fP, \fBLIBRARY\fP, \fBRUNTIME\fP, and \fBFRAMEWORK\fP arguments
+change the type of target to which the subsequent properties apply.
+If none is given the installation properties apply to all target
+types. If only one is given then only targets of that type will be
+installed (which can be used to install just a DLL or just an import
+library). The \fBINCLUDES DESTINATION\fP specifies a list of directories
+which will be added to the \fBINTERFACE_INCLUDE_DIRECTORIES\fP
+target property of the \fB<targets>\fP when exported by the
+\fI\%install(EXPORT)\fP command. If a relative path is
+specified, it is treated as relative to the \fB$<INSTALL_PREFIX>\fP\&.
+.sp
+The \fBPRIVATE_HEADER\fP, \fBPUBLIC_HEADER\fP, and \fBRESOURCE\fP arguments
+cause subsequent properties to be applied to installing a \fBFRAMEWORK\fP
+shared library target\(aqs associated files on non\-Apple platforms. Rules
+defined by these arguments are ignored on Apple platforms because the
+associated files are installed into the appropriate locations inside
+the framework folder. See documentation of the
+\fBPRIVATE_HEADER\fP, \fBPUBLIC_HEADER\fP, and
+\fBRESOURCE\fP target properties for details.
+.sp
+Either \fBNAMELINK_ONLY\fP or \fBNAMELINK_SKIP\fP may be specified as a
+\fBLIBRARY\fP option. On some platforms a versioned shared library
+has a symbolic link such as:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+lib<name>.so \-> lib<name>.so.1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+where \fBlib<name>.so.1\fP is the soname of the library and \fBlib<name>.so\fP
+is a "namelink" allowing linkers to find the library when given
+\fB\-l<name>\fP\&. The \fBNAMELINK_ONLY\fP option causes installation of only the
+namelink when a library target is installed. The \fBNAMELINK_SKIP\fP option
+causes installation of library files other than the namelink when a
+library target is installed. When neither option is given both
+portions are installed. On platforms where versioned shared libraries
+do not have namelinks or when a library is not versioned the
+\fBNAMELINK_SKIP\fP option installs the library and the \fBNAMELINK_ONLY\fP
+option installs nothing. See the \fBVERSION\fP and
+\fBSOVERSION\fP target properties for details on creating versioned
+shared libraries.
+.sp
+One or more groups of properties may be specified in a single call to
+the \fBTARGETS\fP form of this command. A target may be installed more than
+once to different locations. Consider hypothetical targets \fBmyExe\fP,
+\fBmySharedLib\fP, and \fBmyStaticLib\fP\&. The code:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install(TARGETS myExe mySharedLib myStaticLib
+ RUNTIME DESTINATION bin
+ LIBRARY DESTINATION lib
+ ARCHIVE DESTINATION lib/static)
+install(TARGETS mySharedLib DESTINATION /some/full/path)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+will install \fBmyExe\fP to \fB<prefix>/bin\fP and \fBmyStaticLib\fP to
+\fB<prefix>/lib/static\fP\&. On non\-DLL platforms \fBmySharedLib\fP will be
+installed to \fB<prefix>/lib\fP and \fB/some/full/path\fP\&. On DLL platforms
+the \fBmySharedLib\fP DLL will be installed to \fB<prefix>/bin\fP and
+\fB/some/full/path\fP and its import library will be installed to
+\fB<prefix>/lib/static\fP and \fB/some/full/path\fP\&.
+.sp
+The \fBEXPORT\fP option associates the installed target files with an
+export called \fB<export\-name>\fP\&. It must appear before any \fBRUNTIME\fP,
+\fBLIBRARY\fP, or \fBARCHIVE\fP options. To actually install the export
+file itself, call \fBinstall(EXPORT)\fP, documented below.
+.sp
+Installing a target with the \fBEXCLUDE_FROM_ALL\fP target property
+set to \fBTRUE\fP has undefined behavior.
+.sp
+The install destination given to the target install \fBDESTINATION\fP may
+use "generator expressions" with the syntax \fB$<...>\fP\&. See the
+\fBcmake\-generator\-expressions(7)\fP manual for available expressions.
+.SS Installing Files
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install(<FILES|PROGRAMS> files... DESTINATION <dir>
+ [PERMISSIONS permissions...]
+ [CONFIGURATIONS [Debug|Release|...]]
+ [COMPONENT <component>]
+ [RENAME <name>] [OPTIONAL])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBFILES\fP form specifies rules for installing files for a project.
+File names given as relative paths are interpreted with respect to the
+current source directory. Files installed by this form are by default
+given permissions \fBOWNER_WRITE\fP, \fBOWNER_READ\fP, \fBGROUP_READ\fP, and
+\fBWORLD_READ\fP if no \fBPERMISSIONS\fP argument is given.
+.sp
+The \fBPROGRAMS\fP form is identical to the \fBFILES\fP form except that the
+default permissions for the installed file also include \fBOWNER_EXECUTE\fP,
+\fBGROUP_EXECUTE\fP, and \fBWORLD_EXECUTE\fP\&. This form is intended to install
+programs that are not targets, such as shell scripts. Use the \fBTARGETS\fP
+form to install targets built within the project.
+.sp
+The list of \fBfiles...\fP given to \fBFILES\fP or \fBPROGRAMS\fP may use
+"generator expressions" with the syntax \fB$<...>\fP\&. See the
+\fBcmake\-generator\-expressions(7)\fP manual for available expressions.
+However, if any item begins in a generator expression it must evaluate
+to a full path.
+.SS Installing Directories
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install(DIRECTORY dirs... DESTINATION <dir>
+ [FILE_PERMISSIONS permissions...]
+ [DIRECTORY_PERMISSIONS permissions...]
+ [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
+ [CONFIGURATIONS [Debug|Release|...]]
+ [COMPONENT <component>] [FILES_MATCHING]
+ [[PATTERN <pattern> | REGEX <regex>]
+ [EXCLUDE] [PERMISSIONS permissions...]] [...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBDIRECTORY\fP form installs contents of one or more directories to a
+given destination. The directory structure is copied verbatim to the
+destination. The last component of each directory name is appended to
+the destination directory but a trailing slash may be used to avoid
+this because it leaves the last component empty. Directory names
+given as relative paths are interpreted with respect to the current
+source directory. If no input directory names are given the
+destination directory will be created but nothing will be installed
+into it. The \fBFILE_PERMISSIONS\fP and \fBDIRECTORY_PERMISSIONS\fP options
+specify permissions given to files and directories in the destination.
+If \fBUSE_SOURCE_PERMISSIONS\fP is specified and \fBFILE_PERMISSIONS\fP is not,
+file permissions will be copied from the source directory structure.
+If no permissions are specified files will be given the default
+permissions specified in the \fBFILES\fP form of the command, and the
+directories will be given the default permissions specified in the
+\fBPROGRAMS\fP form of the command.
+.sp
+The \fBMESSAGE_NEVER\fP option disables file installation status output.
+.sp
+Installation of directories may be controlled with fine granularity
+using the \fBPATTERN\fP or \fBREGEX\fP options. These "match" options specify a
+globbing pattern or regular expression to match directories or files
+encountered within input directories. They may be used to apply
+certain options (see below) to a subset of the files and directories
+encountered. The full path to each input file or directory (with
+forward slashes) is matched against the expression. A \fBPATTERN\fP will
+match only complete file names: the portion of the full path matching
+the pattern must occur at the end of the file name and be preceded by
+a slash. A \fBREGEX\fP will match any portion of the full path but it may
+use \fB/\fP and \fB$\fP to simulate the \fBPATTERN\fP behavior. By default all
+files and directories are installed whether or not they are matched.
+The \fBFILES_MATCHING\fP option may be given before the first match option
+to disable installation of files (but not directories) not matched by
+any expression. For example, the code
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install(DIRECTORY src/ DESTINATION include/myproj
+ FILES_MATCHING PATTERN "*.h")
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+will extract and install header files from a source tree.
+.sp
+Some options may follow a \fBPATTERN\fP or \fBREGEX\fP expression and are applied
+only to files or directories matching them. The \fBEXCLUDE\fP option will
+skip the matched file or directory. The \fBPERMISSIONS\fP option overrides
+the permissions setting for the matched file or directory. For
+example the code
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install(DIRECTORY icons scripts/ DESTINATION share/myproj
+ PATTERN "CVS" EXCLUDE
+ PATTERN "scripts/*"
+ PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
+ GROUP_EXECUTE GROUP_READ)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+will install the \fBicons\fP directory to \fBshare/myproj/icons\fP and the
+\fBscripts\fP directory to \fBshare/myproj\fP\&. The icons will get default
+file permissions, the scripts will be given specific permissions, and any
+\fBCVS\fP directories will be excluded.
+.SS Custom Installation Logic
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install([[SCRIPT <file>] [CODE <code>]]
+ [COMPONENT <component>] [...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBSCRIPT\fP form will invoke the given CMake script files during
+installation. If the script file name is a relative path it will be
+interpreted with respect to the current source directory. The \fBCODE\fP
+form will invoke the given CMake code during installation. Code is
+specified as a single argument inside a double\-quoted string. For
+example, the code
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install(CODE "MESSAGE(\e"Sample install message.\e")")
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+will print a message during installation.
+.SS Installing Exports
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install(EXPORT <export\-name> DESTINATION <dir>
+ [NAMESPACE <namespace>] [FILE <name>.cmake]
+ [PERMISSIONS permissions...]
+ [CONFIGURATIONS [Debug|Release|...]]
+ [EXPORT_LINK_INTERFACE_LIBRARIES]
+ [COMPONENT <component>])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBEXPORT\fP form generates and installs a CMake file containing code to
+import targets from the installation tree into another project.
+Target installations are associated with the export \fB<export\-name>\fP
+using the \fBEXPORT\fP option of the \fBinstall(TARGETS)\fP signature
+documented above. The \fBNAMESPACE\fP option will prepend \fB<namespace>\fP to
+the target names as they are written to the import file. By default
+the generated file will be called \fB<export\-name>.cmake\fP but the \fBFILE\fP
+option may be used to specify a different name. The value given to
+the \fBFILE\fP option must be a file name with the \fB\&.cmake\fP extension.
+If a \fBCONFIGURATIONS\fP option is given then the file will only be installed
+when one of the named configurations is installed. Additionally, the
+generated import file will reference only the matching target
+configurations. The \fBEXPORT_LINK_INTERFACE_LIBRARIES\fP keyword, if
+present, causes the contents of the properties matching
+\fB(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?\fP to be exported, when
+policy \fBCMP0022\fP is \fBNEW\fP\&. If a \fBCOMPONENT\fP option is
+specified that does not match that given to the targets associated with
+\fB<export\-name>\fP the behavior is undefined. If a library target is
+included in the export but a target to which it links is not included
+the behavior is unspecified.
+.sp
+The \fBEXPORT\fP form is useful to help outside projects use targets built
+and installed by the current project. For example, the code
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install(TARGETS myexe EXPORT myproj DESTINATION bin)
+install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+will install the executable myexe to \fB<prefix>/bin\fP and code to import
+it in the file \fB<prefix>/lib/myproj/myproj.cmake\fP\&. An outside project
+may load this file with the include command and reference the \fBmyexe\fP
+executable from the installation tree using the imported target name
+\fBmp_myexe\fP as if the target were built in its own tree.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+This command supercedes the \fBinstall_targets()\fP command and
+the \fBPRE_INSTALL_SCRIPT\fP and \fBPOST_INSTALL_SCRIPT\fP
+target properties. It also replaces the \fBFILES\fP forms of the
+\fBinstall_files()\fP and \fBinstall_programs()\fP commands.
+The processing order of these install rules relative to
+those generated by \fBinstall_targets()\fP,
+\fBinstall_files()\fP, and \fBinstall_programs()\fP commands
+is not defined.
+.UNINDENT
+.UNINDENT
+.SS link_directories
+.sp
+Specify directories in which the linker will look for libraries.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+link_directories(directory1 directory2 ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Specify the paths in which the linker should search for libraries.
+The command will apply only to targets created after it is called.
+Relative paths given to this command are interpreted as relative to
+the current source directory, see CMP0015.
+.sp
+Note that this command is rarely necessary. Library locations
+returned by find_package() and find_library() are absolute paths.
+Pass these absolute library file paths directly to the
+target_link_libraries() command. CMake will ensure the linker finds
+them.
+.SS link_libraries
+.sp
+Link libraries to all targets added later.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+link_libraries([item1 [item2 [...]]]
+ [[debug|optimized|general] <item>] ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Specify libraries or flags to use when linking any targets created later in
+the current directory or below by commands such as \fBadd_executable()\fP
+or \fBadd_library()\fP\&. See the \fBtarget_link_libraries()\fP command
+for meaning of arguments.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The \fBtarget_link_libraries()\fP command should be preferred whenever
+possible. Library dependencies are chained automatically, so directory\-wide
+specification of link libraries is rarely needed.
+.UNINDENT
+.UNINDENT
+.SS list
+.sp
+List operations.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+list(LENGTH <list> <output variable>)
+list(GET <list> <element index> [<element index> ...]
+ <output variable>)
+list(APPEND <list> [<element> ...])
+list(FIND <list> <value> <output variable>)
+list(INSERT <list> <element_index> <element> [<element> ...])
+list(REMOVE_ITEM <list> <value> [<value> ...])
+list(REMOVE_AT <list> <index> [<index> ...])
+list(REMOVE_DUPLICATES <list>)
+list(REVERSE <list>)
+list(SORT <list>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+LENGTH will return a given list\(aqs length.
+.sp
+GET will return list of elements specified by indices from the list.
+.sp
+APPEND will append elements to the list.
+.sp
+FIND will return the index of the element specified in the list or \-1
+if it wasn\(aqt found.
+.sp
+INSERT will insert elements to the list to the specified location.
+.sp
+REMOVE_AT and REMOVE_ITEM will remove items from the list. The
+difference is that REMOVE_ITEM will remove the given items, while
+REMOVE_AT will remove the items at the given indices.
+.sp
+REMOVE_DUPLICATES will remove duplicated items in the list.
+.sp
+REVERSE reverses the contents of the list in\-place.
+.sp
+SORT sorts the list in\-place alphabetically.
+.sp
+The list subcommands APPEND, INSERT, REMOVE_AT, REMOVE_ITEM,
+REMOVE_DUPLICATES, REVERSE and SORT may create new values for the list
+within the current CMake variable scope. Similar to the SET command,
+the LIST command creates new variable values in the current scope,
+even if the list itself is actually defined in a parent scope. To
+propagate the results of these operations upwards, use SET with
+PARENT_SCOPE, SET with CACHE INTERNAL, or some other means of value
+propagation.
+.sp
+NOTES: A list in cmake is a ; separated group of strings. To create a
+list the set command can be used. For example, set(var a b c d e)
+creates a list with a;b;c;d;e, and set(var "a b c d e") creates a
+string or a list with one item in it. (Note macro arguments are not
+variables, and therefore cannot be used in LIST commands.)
+.sp
+When specifying index values, if <element index> is 0 or greater, it
+is indexed from the beginning of the list, with 0 representing the
+first list element. If <element index> is \-1 or lesser, it is indexed
+from the end of the list, with \-1 representing the last list element.
+Be careful when counting with negative indices: they do not start from
+0. \-0 is equivalent to 0, the first list element.
+.SS load_cache
+.sp
+Load in the values from another project\(aqs CMake cache.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+load_cache(pathToCacheFile READ_WITH_PREFIX
+ prefix entry1...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Read the cache and store the requested entries in variables with their
+name prefixed with the given prefix. This only reads the values, and
+does not create entries in the local project\(aqs cache.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+load_cache(pathToCacheFile [EXCLUDE entry1...]
+ [INCLUDE_INTERNALS entry1...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Load in the values from another cache and store them in the local
+project\(aqs cache as internal entries. This is useful for a project
+that depends on another project built in a different tree. EXCLUDE
+option can be used to provide a list of entries to be excluded.
+INCLUDE_INTERNALS can be used to provide a list of internal entries to
+be included. Normally, no internal entries are brought in. Use of
+this form of the command is strongly discouraged, but it is provided
+for backward compatibility.
+.SS load_command
+.sp
+Disallowed. See CMake Policy \fBCMP0031\fP\&.
+.sp
+Load a command into a running CMake.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+load_command(COMMAND_NAME <loc1> [loc2 ...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The given locations are searched for a library whose name is
+cmCOMMAND_NAME. If found, it is loaded as a module and the command is
+added to the set of available CMake commands. Usually, TRY_COMPILE is
+used before this command to compile the module. If the command is
+successfully loaded a variable named
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+CMAKE_LOADED_COMMAND_<COMMAND_NAME>
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+will be set to the full path of the module that was loaded. Otherwise
+the variable will not be set.
+.SS macro
+.sp
+Start recording a macro for later invocation as a command:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+macro(<name> [arg1 [arg2 [arg3 ...]]])
+ COMMAND1(ARGS ...)
+ COMMAND2(ARGS ...)
+ ...
+endmacro(<name>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Define a macro named \fB<name>\fP that takes arguments named \fBarg1\fP,
+\fBarg2\fP, \fBarg3\fP, (...).
+Commands listed after macro, but before the matching
+\fBendmacro()\fP, are not invoked until the macro is invoked.
+When it is invoked, the commands recorded in the macro are first
+modified by replacing formal parameters (\fB${arg1}\fP) with the arguments
+passed, and then invoked as normal commands.
+In addition to referencing the formal parameters you can reference the
+values \fB${ARGC}\fP which will be set to the number of arguments passed
+into the function as well as \fB${ARGV0}\fP, \fB${ARGV1}\fP, \fB${ARGV2}\fP,
+... which will have the actual values of the arguments passed in.
+This facilitates creating macros with optional arguments.
+Additionally \fB${ARGV}\fP holds the list of all arguments given to the
+macro and \fB${ARGN}\fP holds the list of arguments past the last expected
+argument.
+Referencing to \fB${ARGV#}\fP arguments beyond \fB${ARGC}\fP have undefined
+behavior. Checking that \fB${ARGC}\fP is greater than \fB#\fP is the only
+way to ensure that \fB${ARGV#}\fP was passed to the function as an extra
+argument.
+.sp
+See the \fBcmake_policy()\fP command documentation for the behavior
+of policies inside macros.
+.SS Macro Argument Caveats
+.sp
+Note that the parameters to a macro and values such as \fBARGN\fP are
+not variables in the usual CMake sense. They are string
+replacements much like the C preprocessor would do with a macro.
+Therefore you will NOT be able to use commands like:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+if(ARGV1) # ARGV1 is not a variable
+if(DEFINED ARGV2) # ARGV2 is not a variable
+if(ARGC GREATER 2) # ARGC is not a variable
+foreach(loop_var IN LISTS ARGN) # ARGN is not a variable
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In the first case, you can use \fBif(${ARGV1})\fP\&.
+In the second and third case, the proper way to check if an optional
+variable was passed to the macro is to use \fBif(${ARGC} GREATER 2)\fP\&.
+In the last case, you can use \fBforeach(loop_var ${ARGN})\fP but this
+will skip empty arguments.
+If you need to include them, you can use:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+set(list_var "${ARGN}")
+foreach(loop_var IN LISTS list_var)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Note that if you have a variable with the same name in the scope from
+which the macro is called, using unreferenced names will use the
+existing variable instead of the arguments. For example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+macro(_BAR)
+ foreach(arg IN LISTS ARGN)
+ [...]
+ endforeach()
+endmacro()
+
+function(_FOO)
+ _bar(x y z)
+endfunction()
+
+_foo(a b c)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Will loop over \fBa;b;c\fP and not over \fBx;y;z\fP as one might be expecting.
+If you want true CMake variables and/or better CMake scope control you
+should look at the function command.
+.SS mark_as_advanced
+.sp
+Mark cmake cached variables as advanced.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+mark_as_advanced([CLEAR|FORCE] VAR [VAR2 ...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Mark the named cached variables as advanced. An advanced variable
+will not be displayed in any of the cmake GUIs unless the show
+advanced option is on. If CLEAR is the first argument advanced
+variables are changed back to unadvanced. If FORCE is the first
+argument, then the variable is made advanced. If neither FORCE nor
+CLEAR is specified, new values will be marked as advanced, but if the
+variable already has an advanced/non\-advanced state, it will not be
+changed.
+.sp
+It does nothing in script mode.
+.SS math
+.sp
+Mathematical expressions.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+math(EXPR <output variable> <math expression>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+EXPR evaluates mathematical expression and returns result in the
+output variable. Example mathematical expression is \(aq5 * ( 10 + 13
+)\(aq. Supported operators are + \- * / % | & ^ ~ << >> * / %. They have
+the same meaning as they do in C code.
+.SS message
+.sp
+Display a message to the user.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+message([<mode>] "message to display" ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The optional <mode> keyword determines the type of message:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+(none) = Important information
+STATUS = Incidental information
+WARNING = CMake Warning, continue processing
+AUTHOR_WARNING = CMake Warning (dev), continue processing
+SEND_ERROR = CMake Error, continue processing,
+ but skip generation
+FATAL_ERROR = CMake Error, stop processing and generation
+DEPRECATION = CMake Deprecation Error or Warning if variable
+ CMAKE_ERROR_DEPRECATED or CMAKE_WARN_DEPRECATED
+ is enabled, respectively, else no message.
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The CMake command\-line tool displays STATUS messages on stdout and all
+other message types on stderr. The CMake GUI displays all messages in
+its log area. The interactive dialogs (ccmake and CMakeSetup) show
+STATUS messages one at a time on a status line and other messages in
+interactive pop\-up boxes.
+.sp
+CMake Warning and Error message text displays using a simple markup
+language. Non\-indented text is formatted in line\-wrapped paragraphs
+delimited by newlines. Indented text is considered pre\-formatted.
+.SS option
+.sp
+Provides an option that the user can optionally select.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+option(<option_variable> "help string describing option"
+ [initial value])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Provide an option for the user to select as ON or OFF. If no initial
+value is provided, OFF is used.
+.sp
+If you have options that depend on the values of other options, see
+the module help for CMakeDependentOption.
+.SS project
+.sp
+Set a name, version, and enable languages for the entire project.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+project(<PROJECT\-NAME> [LANGUAGES] [<language\-name>...])
+project(<PROJECT\-NAME>
+ [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
+ [LANGUAGES <language\-name>...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Sets the name of the project and stores the name in the
+\fBPROJECT_NAME\fP variable. Additionally this sets variables
+.INDENT 0.0
+.IP \(bu 2
+\fBPROJECT_SOURCE_DIR\fP,
+\fB<PROJECT\-NAME>_SOURCE_DIR\fP
+.IP \(bu 2
+\fBPROJECT_BINARY_DIR\fP,
+\fB<PROJECT\-NAME>_BINARY_DIR\fP
+.UNINDENT
+.sp
+If \fBVERSION\fP is specified, given components must be non\-negative integers.
+If \fBVERSION\fP is not specified, the default version is the empty string.
+The \fBVERSION\fP option may not be used unless policy \fBCMP0048\fP is
+set to \fBNEW\fP\&.
+.sp
+The \fI\%project()\fP command stores the version number and its components
+in variables
+.INDENT 0.0
+.IP \(bu 2
+\fBPROJECT_VERSION\fP,
+\fB<PROJECT\-NAME>_VERSION\fP
+.IP \(bu 2
+\fBPROJECT_VERSION_MAJOR\fP,
+\fB<PROJECT\-NAME>_VERSION_MAJOR\fP
+.IP \(bu 2
+\fBPROJECT_VERSION_MINOR\fP,
+\fB<PROJECT\-NAME>_VERSION_MINOR\fP
+.IP \(bu 2
+\fBPROJECT_VERSION_PATCH\fP,
+\fB<PROJECT\-NAME>_VERSION_PATCH\fP
+.IP \(bu 2
+\fBPROJECT_VERSION_TWEAK\fP,
+\fB<PROJECT\-NAME>_VERSION_TWEAK\fP
+.UNINDENT
+.sp
+Variables corresponding to unspecified versions are set to the empty string
+(if policy \fBCMP0048\fP is set to \fBNEW\fP).
+.sp
+Optionally you can specify which languages your project supports.
+Example languages are \fBC\fP, \fBCXX\fP (i.e. C++), \fBFortran\fP, etc.
+By default \fBC\fP and \fBCXX\fP are enabled if no language options are
+given. Specify language \fBNONE\fP, or use the \fBLANGUAGES\fP keyword
+and list no languages, to skip enabling any languages.
+.sp
+If a variable exists called \fBCMAKE_PROJECT_<PROJECT\-NAME>_INCLUDE\fP,
+the file pointed to by that variable will be included as the last step of the
+project command.
+.sp
+The top\-level \fBCMakeLists.txt\fP file for a project must contain a
+literal, direct call to the \fI\%project()\fP command; loading one
+through the \fBinclude()\fP command is not sufficient. If no such
+call exists CMake will implicitly add one to the top that enables the
+default languages (\fBC\fP and \fBCXX\fP).
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Call the \fBcmake_minimum_required()\fP command at the beginning
+of the top\-level \fBCMakeLists.txt\fP file even before calling the
+\fBproject()\fP command. It is important to establish version and
+policy settings before invoking other commands whose behavior they
+may affect. See also policy \fBCMP0000\fP\&.
+.UNINDENT
+.UNINDENT
+.SS qt_wrap_cpp
+.sp
+Create Qt Wrappers.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+qt_wrap_cpp(resultingLibraryName DestName
+ SourceLists ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Produce moc files for all the .h files listed in the SourceLists. The
+moc files will be added to the library using the DestName source list.
+.SS qt_wrap_ui
+.sp
+Create Qt user interfaces Wrappers.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+qt_wrap_ui(resultingLibraryName HeadersDestName
+ SourcesDestName SourceLists ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Produce .h and .cxx files for all the .ui files listed in the
+SourceLists. The .h files will be added to the library using the
+HeadersDestNamesource list. The .cxx files will be added to the
+library using the SourcesDestNamesource list.
+.SS remove_definitions
+.sp
+Removes \-D define flags added by add_definitions.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+remove_definitions(\-DFOO \-DBAR ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Removes flags (added by add_definitions) from the compiler command
+line for sources in the current directory and below.
+.SS return
+.sp
+Return from a file, directory or function.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+return()
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Returns from a file, directory or function. When this command is
+encountered in an included file (via include() or find_package()), it
+causes processing of the current file to stop and control is returned
+to the including file. If it is encountered in a file which is not
+included by another file, e.g. a CMakeLists.txt, control is returned
+to the parent directory if there is one. If return is called in a
+function, control is returned to the caller of the function. Note
+that a macro is not a function and does not handle return like a
+function does.
+.SS separate_arguments
+.sp
+Parse space\-separated arguments into a semicolon\-separated list.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+separate_arguments(<var> <UNIX|WINDOWS>_COMMAND "<args>")
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Parses a unix\- or windows\-style command\-line string "<args>" and
+stores a semicolon\-separated list of the arguments in <var>. The
+entire command line must be given in one "<args>" argument.
+.sp
+The UNIX_COMMAND mode separates arguments by unquoted whitespace. It
+recognizes both single\-quote and double\-quote pairs. A backslash
+escapes the next literal character (" is "); there are no special
+escapes (n is just n).
+.sp
+The WINDOWS_COMMAND mode parses a windows command\-line using the same
+syntax the runtime library uses to construct argv at startup. It
+separates arguments by whitespace that is not double\-quoted.
+Backslashes are literal unless they precede double\-quotes. See the
+MSDN article "Parsing C Command\-Line Arguments" for details.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+separate_arguments(VARIABLE)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Convert the value of VARIABLE to a semi\-colon separated list. All
+spaces are replaced with \(aq;\(aq. This helps with generating command
+lines.
+.SS set_directory_properties
+.sp
+Set a property of the directory.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Set a property for the current directory and subdirectories. See
+Directory Properties for the list of properties known
+to CMake.
+.SS set_property
+.sp
+Set a named property in a given scope.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+set_property(<GLOBAL |
+ DIRECTORY [dir] |
+ TARGET [target1 [target2 ...]] |
+ SOURCE [src1 [src2 ...]] |
+ INSTALL [file1 [file2 ...]] |
+ TEST [test1 [test2 ...]] |
+ CACHE [entry1 [entry2 ...]]>
+ [APPEND] [APPEND_STRING]
+ PROPERTY <name> [value1 [value2 ...]])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Set one property on zero or more objects of a scope. The first
+argument determines the scope in which the property is set. It must
+be one of the following:
+.INDENT 0.0
+.TP
+.B \fBGLOBAL\fP
+Scope is unique and does not accept a name.
+.TP
+.B \fBDIRECTORY\fP
+Scope defaults to the current directory but another
+directory (already processed by CMake) may be named by full or
+relative path.
+.TP
+.B \fBTARGET\fP
+Scope may name zero or more existing targets.
+.TP
+.B \fBSOURCE\fP
+Scope may name zero or more source files. Note that source
+file properties are visible only to targets added in the same
+directory (CMakeLists.txt).
+.TP
+.B \fBINSTALL\fP
+Scope may name zero or more installed file paths.
+These are made available to CPack to influence deployment.
+.sp
+Both the property key and value may use generator expressions.
+Specific properties may apply to installed files and/or directories.
+.sp
+Path components have to be separated by forward slashes,
+must be normalized and are case sensitive.
+.sp
+To reference the installation prefix itself with a relative path use ".".
+.sp
+Currently installed file properties are only defined for
+the WIX generator where the given paths are relative
+to the installation prefix.
+.TP
+.B \fBTEST\fP
+Scope may name zero or more existing tests.
+.TP
+.B \fBCACHE\fP
+Scope must name zero or more cache existing entries.
+.UNINDENT
+.sp
+The required \fBPROPERTY\fP option is immediately followed by the name of
+the property to set. Remaining arguments are used to compose the
+property value in the form of a semicolon\-separated list. If the
+\fBAPPEND\fP option is given the list is appended to any existing property
+value. If the \fBAPPEND_STRING\fP option is given the string is append to any
+existing property value as string, i.e. it results in a longer string
+and not a list of strings.
+.SS set
+.sp
+Set a normal, cache, or environment variable to a given value.
+See the cmake\-language(7) variables
+documentation for the scopes and interaction of normal variables
+and cache entries.
+.sp
+Signatures of this command that specify a \fB<value>...\fP placeholder
+expect zero or more arguments. Multiple arguments will be joined as
+a ;\-list to form the actual variable
+value to be set. Zero arguments will cause normal variables to be
+unset. See the \fBunset()\fP command to unset variables explicitly.
+.SS Set Normal Variable
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+set(<variable> <value>... [PARENT_SCOPE])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Set the given \fB<variable>\fP in the current function or directory scope.
+.sp
+If the \fBPARENT_SCOPE\fP option is given the variable will be set in
+the scope above the current scope. Each new directory or function
+creates a new scope. This command will set the value of a variable
+into the parent directory or calling function (whichever is applicable
+to the case at hand).
+.SS Set Cache Entry
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+set(<variable> <value>... CACHE <type> <docstring> [FORCE])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Set the given cache \fB<variable>\fP (cache entry). Since cache entries
+are meant to provide user\-settable values this does not overwrite
+existing cache entries by default. Use the \fBFORCE\fP option to
+overwrite existing entries.
+.sp
+The \fB<type>\fP must be specified as one of:
+.INDENT 0.0
+.TP
+.B \fBBOOL\fP
+Boolean \fBON/OFF\fP value. \fBcmake\-gui(1)\fP offers a checkbox.
+.TP
+.B \fBFILEPATH\fP
+Path to a file on disk. \fBcmake\-gui(1)\fP offers a file dialog.
+.TP
+.B \fBPATH\fP
+Path to a directory on disk. \fBcmake\-gui(1)\fP offers a file dialog.
+.TP
+.B \fBSTRING\fP
+A line of text. \fBcmake\-gui(1)\fP offers a text field or a
+drop\-down selection if the \fBSTRINGS\fP cache entry
+property is set.
+.TP
+.B \fBINTERNAL\fP
+A line of text. \fBcmake\-gui(1)\fP does not show internal entries.
+They may be used to store variables persistently across runs.
+Use of this type implies \fBFORCE\fP\&.
+.UNINDENT
+.sp
+The \fB<docstring>\fP must be specified as a line of text providing
+a quick summary of the option for presentation to \fBcmake\-gui(1)\fP
+users.
+.sp
+If the cache entry does not exist prior to the call or the \fBFORCE\fP
+option is given then the cache entry will be set to the given value.
+Furthermore, any normal variable binding in the current scope will
+be removed to expose the newly cached value to any immediately
+following evaluation.
+.sp
+It is possible for the cache entry to exist prior to the call but
+have no type set if it was created on the \fBcmake(1)\fP command
+line by a user through the \fB\-D<var>=<value>\fP option without
+specifying a type. In this case the \fBset\fP command will add the
+type. Furthermore, if the \fB<type>\fP is \fBPATH\fP or \fBFILEPATH\fP
+and the \fB<value>\fP provided on the command line is a relative path,
+then the \fBset\fP command will treat the path as relative to the
+current working directory and convert it to an absolute path.
+.SS Set Environment Variable
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+set(ENV{<variable>} <value>...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Set the current process environment \fB<variable>\fP to the given value.
+.SS set_source_files_properties
+.sp
+Source files can have properties that affect how they are built.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+set_source_files_properties([file1 [file2 [...]]]
+ PROPERTIES prop1 value1
+ [prop2 value2 [...]])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Set properties associated with source files using a key/value paired
+list. See Source File Properties for the list of properties known
+to CMake. Source file properties are visible only to targets added
+in the same directory (CMakeLists.txt).
+.SS set_target_properties
+.sp
+Targets can have properties that affect how they are built.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+set_target_properties(target1 target2 ...
+ PROPERTIES prop1 value1
+ prop2 value2 ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Set properties on a target. The syntax for the command is to list all
+the files you want to change, and then provide the values you want to
+set next. You can use any prop value pair you want and extract it
+later with the GET_TARGET_PROPERTY command.
+.sp
+Properties that affect the name of a target\(aqs output file are as
+follows. The PREFIX and SUFFIX properties override the default target
+name prefix (such as "lib") and suffix (such as ".so"). IMPORT_PREFIX
+and IMPORT_SUFFIX are the equivalent properties for the import library
+corresponding to a DLL (for SHARED library targets). OUTPUT_NAME sets
+the real name of a target when it is built and can be used to help
+create two targets of the same name even though CMake requires unique
+logical target names. There is also a <CONFIG>_OUTPUT_NAME that can
+set the output name on a per\-configuration basis. <CONFIG>_POSTFIX
+sets a postfix for the real name of the target when it is built under
+the configuration named by <CONFIG> (in upper\-case, such as
+"DEBUG_POSTFIX"). The value of this property is initialized when the
+target is created to the value of the variable CMAKE_<CONFIG>_POSTFIX
+(except for executable targets because earlier CMake versions which
+did not use this variable for executables).
+.sp
+The LINK_FLAGS property can be used to add extra flags to the link
+step of a target. LINK_FLAGS_<CONFIG> will add to the configuration
+<CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL, RELWITHDEBINFO.
+DEFINE_SYMBOL sets the name of the preprocessor symbol defined when
+compiling sources in a shared library. If not set here then it is set
+to target_EXPORTS by default (with some substitutions if the target is
+not a valid C identifier). This is useful for headers to know whether
+they are being included from inside their library or outside to
+properly setup dllexport/dllimport decorations. The COMPILE_FLAGS
+property sets additional compiler flags used to build sources within
+the target. It may also be used to pass additional preprocessor
+definitions.
+.sp
+The LINKER_LANGUAGE property is used to change the tool used to link
+an executable or shared library. The default is set the language to
+match the files in the library. CXX and C are common values for this
+property.
+.sp
+For shared libraries VERSION and SOVERSION can be used to specify the
+build version and API version respectively. When building or
+installing appropriate symlinks are created if the platform supports
+symlinks and the linker supports so\-names. If only one of both is
+specified the missing is assumed to have the same version number. For
+executables VERSION can be used to specify the build version. When
+building or installing appropriate symlinks are created if the
+platform supports symlinks. For shared libraries and executables on
+Windows the VERSION attribute is parsed to extract a "major.minor"
+version number. These numbers are used as the image version of the
+binary.
+.sp
+There are a few properties used to specify RPATH rules. INSTALL_RPATH
+is a semicolon\-separated list specifying the rpath to use in installed
+targets (for platforms that support it). INSTALL_RPATH_USE_LINK_PATH
+is a boolean that if set to true will append directories in the linker
+search path and outside the project to the INSTALL_RPATH.
+SKIP_BUILD_RPATH is a boolean specifying whether to skip automatic
+generation of an rpath allowing the target to run from the build tree.
+BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link the
+target in the build tree with the INSTALL_RPATH. This takes
+precedence over SKIP_BUILD_RPATH and avoids the need for relinking
+before installation. INSTALL_NAME_DIR is a string specifying the
+directory portion of the "install_name" field of shared libraries on
+Mac OSX to use in the installed targets. When the target is created
+the values of the variables CMAKE_INSTALL_RPATH,
+CMAKE_INSTALL_RPATH_USE_LINK_PATH, CMAKE_SKIP_BUILD_RPATH,
+CMAKE_BUILD_WITH_INSTALL_RPATH, and CMAKE_INSTALL_NAME_DIR are used to
+initialize these properties.
+.sp
+PROJECT_LABEL can be used to change the name of the target in an IDE
+like visual studio. VS_KEYWORD can be set to change the visual studio
+keyword, for example Qt integration works better if this is set to
+Qt4VSv1.0.
+.sp
+VS_SCC_PROJECTNAME, VS_SCC_LOCALPATH, VS_SCC_PROVIDER and
+VS_SCC_AUXPATH can be set to add support for source control bindings
+in a Visual Studio project file.
+.sp
+VS_GLOBAL_<variable> can be set to add a Visual Studio
+project\-specific global variable. Qt integration works better if
+VS_GLOBAL_QtVersion is set to the Qt version FindQt4.cmake found. For
+example, "4.7.3"
+.sp
+The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are the old
+way to specify CMake scripts to run before and after installing a
+target. They are used only when the old INSTALL_TARGETS command is
+used to install the target. Use the INSTALL command instead.
+.sp
+The EXCLUDE_FROM_DEFAULT_BUILD property is used by the visual studio
+generators. If it is set to 1 the target will not be part of the
+default build when you select "Build Solution". This can also be set
+on a per\-configuration basis using
+EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>.
+.SS set_tests_properties
+.sp
+Set a property of the tests.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Set a property for the tests. If the test is not found, CMake
+will report an error.
+\fBGenerator expressions\fP will be
+expanded the same as supported by the test\(aqs \fBadd_test()\fP call. See
+Test Properties for the list of properties known to CMake.
+.SS site_name
+.sp
+Set the given variable to the name of the computer.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+site_name(variable)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS source_group
+.sp
+Define a grouping for source files in IDE project generation.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Defines a group into which sources will be placed in project files.
+This is intended to set up file tabs in Visual Studio.
+The options are:
+.INDENT 0.0
+.TP
+.B \fBFILES\fP
+Any source file specified explicitly will be placed in group
+\fB<name>\fP\&. Relative paths are interpreted with respect to the
+current source directory.
+.TP
+.B \fBREGULAR_EXPRESSION\fP
+Any source file whose name matches the regular expression will
+be placed in group \fB<name>\fP\&.
+.UNINDENT
+.sp
+If a source file matches multiple groups, the \fIlast\fP group that
+explicitly lists the file with \fBFILES\fP will be favored, if any.
+If no group explicitly lists the file, the \fIlast\fP group whose
+regular expression matches the file will be favored.
+.sp
+The \fB<name>\fP of the group may contain backslashes to specify subgroups:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+source_group(outer\e\einner ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+For backwards compatibility, the short\-hand signature
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+source_group(<name> <regex>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+is equivalent to
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+source_group(<name> REGULAR_EXPRESSION <regex>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS string
+.sp
+String operations.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+string(REGEX MATCH <regular_expression>
+ <output variable> <input> [<input>...])
+string(REGEX MATCHALL <regular_expression>
+ <output variable> <input> [<input>...])
+string(REGEX REPLACE <regular_expression>
+ <replace_expression> <output variable>
+ <input> [<input>...])
+string(REPLACE <match_string>
+ <replace_string> <output variable>
+ <input> [<input>...])
+string(CONCAT <output variable> [<input>...])
+string(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512>
+ <output variable> <input>)
+string(COMPARE EQUAL <string1> <string2> <output variable>)
+string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
+string(COMPARE LESS <string1> <string2> <output variable>)
+string(COMPARE GREATER <string1> <string2> <output variable>)
+string(ASCII <number> [<number> ...] <output variable>)
+string(CONFIGURE <string1> <output variable>
+ [@ONLY] [ESCAPE_QUOTES])
+string(TOUPPER <string1> <output variable>)
+string(TOLOWER <string1> <output variable>)
+string(LENGTH <string> <output variable>)
+string(SUBSTRING <string> <begin> <length> <output variable>)
+string(STRIP <string> <output variable>)
+string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
+ [RANDOM_SEED <seed>] <output variable>)
+string(FIND <string> <substring> <output variable> [REVERSE])
+string(TIMESTAMP <output variable> [<format string>] [UTC])
+string(MAKE_C_IDENTIFIER <input string> <output variable>)
+string(GENEX_STRIP <input string> <output variable>)
+string(UUID <output variable> NAMESPACE <namespace> NAME <name>
+ TYPE <MD5|SHA1> [UPPER])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+REGEX MATCH will match the regular expression once and store the match
+in the output variable.
+.sp
+REGEX MATCHALL will match the regular expression as many times as
+possible and store the matches in the output variable as a list.
+.sp
+REGEX REPLACE will match the regular expression as many times as
+possible and substitute the replacement expression for the match in
+the output. The replace expression may refer to paren\-delimited
+subexpressions of the match using 1, 2, ..., 9. Note that two
+backslashes (\e1) are required in CMake code to get a backslash
+through argument parsing.
+.sp
+REPLACE will replace all occurrences of match_string in the input with
+replace_string and store the result in the output.
+.sp
+CONCAT will concatenate all the input arguments together and store
+the result in the named output variable.
+.sp
+MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a
+cryptographic hash of the input string.
+.sp
+COMPARE EQUAL/NOTEQUAL/LESS/GREATER will compare the strings and store
+true or false in the output variable.
+.sp
+ASCII will convert all numbers into corresponding ASCII characters.
+.sp
+CONFIGURE will transform a string like CONFIGURE_FILE transforms a
+file.
+.sp
+TOUPPER/TOLOWER will convert string to upper/lower characters.
+.sp
+LENGTH will return a given string\(aqs length.
+.sp
+SUBSTRING will return a substring of a given string. If length is \-1
+the remainder of the string starting at begin will be returned.
+If string is shorter than length then end of string is used instead.
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+CMake 3.1 and below reported an error if length pointed past
+the end of string.
+.UNINDENT
+.UNINDENT
+.sp
+STRIP will return a substring of a given string with leading and
+trailing spaces removed.
+.sp
+RANDOM will return a random string of given length consisting of
+characters from the given alphabet. Default length is 5 characters
+and default alphabet is all numbers and upper and lower case letters.
+If an integer RANDOM_SEED is given, its value will be used to seed the
+random number generator.
+.sp
+FIND will return the position where the given substring was found in
+the supplied string. If the REVERSE flag was used, the command will
+search for the position of the last occurrence of the specified
+substring.
+.sp
+The following characters have special meaning in regular expressions:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+^ Matches at beginning of input
+$ Matches at end of input
+\&. Matches any single character
+[ ] Matches any character(s) inside the brackets
+[^ ] Matches any character(s) not inside the brackets
+ \- Inside brackets, specifies an inclusive range between
+ characters on either side e.g. [a\-f] is [abcdef]
+ To match a literal \- using brackets, make it the first
+ or the last character e.g. [+*/\-] matches basic
+ mathematical operators.
+* Matches preceding pattern zero or more times
++ Matches preceding pattern one or more times
+? Matches preceding pattern zero or once only
+| Matches a pattern on either side of the |
+() Saves a matched subexpression, which can be referenced
+ in the REGEX REPLACE operation. Additionally it is saved
+ by all regular expression\-related commands, including
+ e.g. if( MATCHES ), in the variables CMAKE_MATCH_(0..9).
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+\fB*\fP, \fB+\fP and \fB?\fP have higher precedence than concatenation. | has lower
+precedence than concatenation. This means that the regular expression
+"^ab+d$" matches "abbd" but not "ababd", and the regular expression
+"^(ab|cd)$" matches "ab" but not "abd".
+.sp
+TIMESTAMP will write a string representation of the current date
+and/or time to the output variable.
+.sp
+Should the command be unable to obtain a timestamp the output variable
+will be set to the empty string "".
+.sp
+The optional UTC flag requests the current date/time representation to
+be in Coordinated Universal Time (UTC) rather than local time.
+.sp
+The optional <format string> may contain the following format
+specifiers:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+%d The day of the current month (01\-31).
+%H The hour on a 24\-hour clock (00\-23).
+%I The hour on a 12\-hour clock (01\-12).
+%j The day of the current year (001\-366).
+%m The month of the current year (01\-12).
+%M The minute of the current hour (00\-59).
+%S The second of the current minute.
+ 60 represents a leap second. (00\-60)
+%U The week number of the current year (00\-53).
+%w The day of the current week. 0 is Sunday. (0\-6)
+%y The last two digits of the current year (00\-99)
+%Y The current year.
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Unknown format specifiers will be ignored and copied to the output
+as\-is.
+.sp
+If no explicit <format string> is given it will default to:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+%Y\-%m\-%dT%H:%M:%S for local time.
+%Y\-%m\-%dT%H:%M:%SZ for UTC.
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+MAKE_C_IDENTIFIER will write a string which can be used as an
+identifier in C.
+.sp
+\fBGENEX_STRIP\fP will strip any
+\fBgenerator expressions\fP from the
+\fBinput string\fP and store the result in the \fBoutput variable\fP\&.
+.sp
+UUID creates a univerally unique identifier (aka GUID) as per RFC4122
+based on the hash of the combined values of <namespace>
+(which itself has to be a valid UUID) and <name>.
+The hash algorithm can be either \fBMD5\fP (Version 3 UUID) or
+\fBSHA1\fP (Version 5 UUID).
+A UUID has the format \fBxxxxxxxx\-xxxx\-xxxx\-xxxx\-xxxxxxxxxxxx\fP
+where each \fIx\fP represents a lower case hexadecimal character.
+Where required an uppercase representation can be requested
+with the optional \fBUPPER\fP flag.
+.SS target_compile_definitions
+.sp
+Add compile definitions to a target.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+target_compile_definitions(<target>
+ <INTERFACE|PUBLIC|PRIVATE> [items1...]
+ [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Specify compile definitions to use when compiling a given \fB<target>\fP\&. The
+named \fB<target>\fP must have been created by a command such as
+\fBadd_executable()\fP or \fBadd_library()\fP and must not be an
+Imported Target\&.
+.sp
+The \fBINTERFACE\fP, \fBPUBLIC\fP and \fBPRIVATE\fP keywords are required to
+specify the scope of the following arguments. \fBPRIVATE\fP and \fBPUBLIC\fP
+items will populate the \fBCOMPILE_DEFINITIONS\fP property of
+\fB<target>\fP\&. \fBPUBLIC\fP and \fBINTERFACE\fP items will populate the
+\fBINTERFACE_COMPILE_DEFINITIONS\fP property of \fB<target>\fP\&. The
+following arguments specify compile definitions. Repeated calls for the
+same \fB<target>\fP append items in the order called.
+.sp
+Arguments to \fBtarget_compile_definitions\fP may use "generator expressions"
+with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP
+manual for available expressions. See the \fBcmake\-buildsystem(7)\fP
+manual for more on defining buildsystem properties.
+.SS target_compile_features
+.sp
+Add expected compiler features to a target.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+target_compile_features(<target> <PRIVATE|PUBLIC|INTERFACE> <feature> [...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Specify compiler features required when compiling a given target. If the
+feature is not listed in the \fBCMAKE_C_COMPILE_FEATURES\fP variable
+or \fBCMAKE_CXX_COMPILE_FEATURES\fP variable,
+then an error will be reported by CMake. If the use of the feature requires
+an additional compiler flag, such as \fB\-std=gnu++11\fP, the flag will be added
+automatically.
+.sp
+The \fBINTERFACE\fP, \fBPUBLIC\fP and \fBPRIVATE\fP keywords are required to
+specify the scope of the features. \fBPRIVATE\fP and \fBPUBLIC\fP items will
+populate the \fBCOMPILE_FEATURES\fP property of \fB<target>\fP\&.
+\fBPUBLIC\fP and \fBINTERFACE\fP items will populate the
+\fBINTERFACE_COMPILE_FEATURES\fP property of \fB<target>\fP\&. Repeated
+calls for the same \fB<target>\fP append items.
+.sp
+The named \fB<target>\fP must have been created by a command such as
+\fBadd_executable()\fP or \fBadd_library()\fP and must not be
+an \fBIMPORTED\fP target.
+.sp
+Arguments to \fBtarget_compile_features\fP may use "generator expressions"
+with the syntax \fB$<...>\fP\&.
+See the \fBcmake\-generator\-expressions(7)\fP manual for available
+expressions. See the \fBcmake\-compile\-features(7)\fP manual for
+information on compile features and a list of supported compilers.
+.SS target_compile_options
+.sp
+Add compile options to a target.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+target_compile_options(<target> [BEFORE]
+ <INTERFACE|PUBLIC|PRIVATE> [items1...]
+ [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Specify compile options to use when compiling a given target. The
+named \fB<target>\fP must have been created by a command such as
+\fBadd_executable()\fP or \fBadd_library()\fP and must not be an
+IMPORTED Target\&. If \fBBEFORE\fP is specified,
+the content will be prepended to the property instead of being appended.
+.sp
+This command can be used to add any options, but
+alternative commands exist to add preprocessor definitions
+(\fBtarget_compile_definitions()\fP and \fBadd_definitions()\fP) or
+include directories (\fBtarget_include_directories()\fP and
+\fBinclude_directories()\fP). See documentation of the
+\fBdirectory\fP and
+\fBtarget\fP \fBCOMPILE_OPTIONS\fP properties.
+.sp
+The \fBINTERFACE\fP, \fBPUBLIC\fP and \fBPRIVATE\fP keywords are required to
+specify the scope of the following arguments. \fBPRIVATE\fP and \fBPUBLIC\fP
+items will populate the \fBCOMPILE_OPTIONS\fP property of
+\fB<target>\fP\&. \fBPUBLIC\fP and \fBINTERFACE\fP items will populate the
+\fBINTERFACE_COMPILE_OPTIONS\fP property of \fB<target>\fP\&. The
+following arguments specify compile options. Repeated calls for the same
+\fB<target>\fP append items in the order called.
+.sp
+Arguments to \fBtarget_compile_options\fP may use "generator expressions"
+with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP
+manual for available expressions. See the \fBcmake\-buildsystem(7)\fP
+manual for more on defining buildsystem properties.
+.SS target_include_directories
+.sp
+Add include directories to a target.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+target_include_directories(<target> [SYSTEM] [BEFORE]
+ <INTERFACE|PUBLIC|PRIVATE> [items1...]
+ [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Specify include directories to use when compiling a given target.
+The named \fB<target>\fP must have been created by a command such
+as \fBadd_executable()\fP or \fBadd_library()\fP and must not be an
+\fBIMPORTED\fP target.
+.sp
+If \fBBEFORE\fP is specified, the content will be prepended to the property
+instead of being appended.
+.sp
+The \fBINTERFACE\fP, \fBPUBLIC\fP and \fBPRIVATE\fP keywords are required to specify
+the scope of the following arguments. \fBPRIVATE\fP and \fBPUBLIC\fP items will
+populate the \fBINCLUDE_DIRECTORIES\fP property of \fB<target>\fP\&.
+\fBPUBLIC\fP and \fBINTERFACE\fP items will populate the
+\fBINTERFACE_INCLUDE_DIRECTORIES\fP
+property of \fB<target>\fP\&. The following arguments specify include
+directories.
+.sp
+Specified include directories may be absolute paths or relative paths.
+Repeated calls for the same <target> append items in the order called. If
+\fBSYSTEM\fP is specified, the compiler will be told the
+directories are meant as system include directories on some platforms
+(signalling this setting might achieve effects such as the compiler
+skipping warnings, or these fixed\-install system files not being
+considered in dependency calculations \- see compiler docs). If \fBSYSTEM\fP
+is used together with \fBPUBLIC\fP or \fBINTERFACE\fP, the
+\fBINTERFACE_SYSTEM_INCLUDE_DIRECTORIES\fP target property will be
+populated with the specified directories.
+.sp
+Arguments to \fBtarget_include_directories\fP may use "generator expressions"
+with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP
+manual for available expressions. See the \fBcmake\-buildsystem(7)\fP
+manual for more on defining buildsystem properties.
+.sp
+Include directories usage requirements commonly differ between the build\-tree
+and the install\-tree. The \fBBUILD_INTERFACE\fP and \fBINSTALL_INTERFACE\fP
+generator expressions can be used to describe separate usage requirements
+based on the usage location. Relative paths are allowed within the
+\fBINSTALL_INTERFACE\fP expression and are interpreted relative to the
+installation prefix. For example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+target_include_directories(mylib PUBLIC
+ $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
+ $<INSTALL_INTERFACE:include/mylib> # <prefix>/include/mylib
+)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SS Creating Relocatable Packages
+.sp
+Note that it is not advisable to populate the \fBINSTALL_INTERFACE\fP of the
+\fBINTERFACE_INCLUDE_DIRECTORIES\fP of a target with absolute paths to the include
+directories of dependencies. That would hard\-code into installed packages
+the include directory paths for dependencies
+\fBas found on the machine the package was made on\fP\&.
+.sp
+The \fBINSTALL_INTERFACE\fP of the \fBINTERFACE_INCLUDE_DIRECTORIES\fP is only
+suitable for specifying the required include directories for headers
+provided with the target itself, not those provided by the transitive
+dependencies listed in its \fBINTERFACE_LINK_LIBRARIES\fP target
+property. Those dependencies should themselves be targets that specify
+their own header locations in \fBINTERFACE_INCLUDE_DIRECTORIES\fP\&.
+.sp
+See the Creating Relocatable Packages section of the
+\fBcmake\-packages(7)\fP manual for discussion of additional care
+that must be taken when specifying usage requirements while creating
+packages for redistribution.
+.SS target_link_libraries
+.sp
+Specify libraries or flags to use when linking a given target and/or
+its dependents. Usage requirements
+from linked library targets will be propagated. Usage requirements
+of a target\(aqs dependencies affect compilation of its own sources.
+.SS Overview
+.sp
+This command has several signatures as detailed in subsections below.
+All of them have the general form:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+target_link_libraries(<target> ... <item>... ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The named \fB<target>\fP must have been created in the current directory by
+a command such as \fBadd_executable()\fP or \fBadd_library()\fP\&.
+Repeated calls for the same \fB<target>\fP append items in the order called.
+Each \fB<item>\fP may be:
+.INDENT 0.0
+.IP \(bu 2
+\fBA library target name\fP: The generated link line will have the
+full path to the linkable library file associated with the target.
+The buildsystem will have a dependency to re\-link \fB<target>\fP if
+the library file changes.
+.sp
+The named target must be created by \fBadd_library()\fP within
+the project or as an IMPORTED library\&.
+If it is created within the project an ordering dependency will
+automatically be added in the build system to make sure the named
+library target is up\-to\-date before the \fB<target>\fP links.
+.sp
+If an imported library has the \fBIMPORTED_NO_SONAME\fP
+target property set, CMake may ask the linker to search for
+the library instead of using the full path
+(e.g. \fB/usr/lib/libfoo.so\fP becomes \fB\-lfoo\fP).
+.IP \(bu 2
+\fBA full path to a library file\fP: The generated link line will
+normally preserve the full path to the file. The buildsystem will
+have a dependency to re\-link \fB<target>\fP if the library file changes.
+.sp
+There are some cases where CMake may ask the linker to search for
+the library (e.g. \fB/usr/lib/libfoo.so\fP becomes \fB\-lfoo\fP), such
+as when a shared library is detected to have no \fBSONAME\fP field.
+See policy \fBCMP0060\fP for discussion of another case.
+.sp
+If the library file is in a Mac OSX framework, the \fBHeaders\fP directory
+of the framework will also be processed as a
+usage requirement\&. This has the same
+effect as passing the framework directory as an include directory.
+.IP \(bu 2
+\fBA plain library name\fP: The generated link line will ask the linker
+to search for the library (e.g. \fBfoo\fP becomes \fB\-lfoo\fP or \fBfoo.lib\fP).
+.IP \(bu 2
+\fBA link flag\fP: Item names starting with \fB\-\fP, but not \fB\-l\fP or
+\fB\-framework\fP, are treated as linker flags. Note that such flags will
+be treated like any other library link item for purposes of transitive
+dependencies, so they are generally safe to specify only as private link
+items that will not propagate to dependents.
+.IP \(bu 2
+A \fBdebug\fP, \fBoptimized\fP, or \fBgeneral\fP keyword immediately followed
+by another \fB<item>\fP\&. The item following such a keyword will be used
+only for the corresponding build configuration. The \fBdebug\fP keyword
+corresponds to the \fBDebug\fP configuration (or to configurations named
+in the \fBDEBUG_CONFIGURATIONS\fP global property if it is set).
+The \fBoptimized\fP keyword corresponds to all other configurations. The
+\fBgeneral\fP keyword corresponds to all configurations, and is purely
+optional. Higher granularity may be achieved for per\-configuration
+rules by creating and linking to
+IMPORTED library targets\&.
+.UNINDENT
+.sp
+Items containing \fB::\fP, such as \fBFoo::Bar\fP, are assumed to be
+IMPORTED or ALIAS library
+target names and will cause an error if no such target exists.
+See policy \fBCMP0028\fP\&.
+.sp
+Arguments to \fBtarget_link_libraries\fP may use "generator expressions"
+with the syntax \fB$<...>\fP\&. Note however, that generator expressions
+will not be used in OLD handling of \fBCMP0003\fP or \fBCMP0004\fP\&.
+See the \fBcmake\-generator\-expressions(7)\fP manual for available
+expressions. See the \fBcmake\-buildsystem(7)\fP manual for more on
+defining buildsystem properties.
+.SS Libraries for a Target and/or its Dependents
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+target_link_libraries(<target>
+ <PRIVATE|PUBLIC|INTERFACE> <item>...
+ [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBPUBLIC\fP, \fBPRIVATE\fP and \fBINTERFACE\fP keywords can be used to
+specify both the link dependencies and the link interface in one command.
+Libraries and targets following \fBPUBLIC\fP are linked to, and are made
+part of the link interface. Libraries and targets following \fBPRIVATE\fP
+are linked to, but are not made part of the link interface. Libraries
+following \fBINTERFACE\fP are appended to the link interface and are not
+used for linking \fB<target>\fP\&.
+.SS Libraries for both a Target and its Dependents
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+target_link_libraries(<target> <item>...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Library dependencies are transitive by default with this signature.
+When this target is linked into another target then the libraries
+linked to this target will appear on the link line for the other
+target too. This transitive "link interface" is stored in the
+\fBINTERFACE_LINK_LIBRARIES\fP target property and may be overridden
+by setting the property directly. When \fBCMP0022\fP is not set to
+\fBNEW\fP, transitive linking is built in but may be overridden by the
+\fBLINK_INTERFACE_LIBRARIES\fP property. Calls to other signatures
+of this command may set the property making any libraries linked
+exclusively by this signature private.
+.SS Libraries for a Target and/or its Dependents (Legacy)
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+target_link_libraries(<target>
+ <LINK_PRIVATE|LINK_PUBLIC> <lib>...
+ [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBLINK_PUBLIC\fP and \fBLINK_PRIVATE\fP modes can be used to specify both
+the link dependencies and the link interface in one command.
+.sp
+This signature is for compatibility only. Prefer the \fBPUBLIC\fP or
+\fBPRIVATE\fP keywords instead.
+.sp
+Libraries and targets following \fBLINK_PUBLIC\fP are linked to, and are
+made part of the \fBINTERFACE_LINK_LIBRARIES\fP\&. If policy
+\fBCMP0022\fP is not \fBNEW\fP, they are also made part of the
+\fBLINK_INTERFACE_LIBRARIES\fP\&. Libraries and targets following
+\fBLINK_PRIVATE\fP are linked to, but are not made part of the
+\fBINTERFACE_LINK_LIBRARIES\fP (or \fBLINK_INTERFACE_LIBRARIES\fP).
+.SS Libraries for Dependents Only (Legacy)
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The \fBLINK_INTERFACE_LIBRARIES\fP mode appends the libraries to the
+\fBINTERFACE_LINK_LIBRARIES\fP target property instead of using them
+for linking. If policy \fBCMP0022\fP is not \fBNEW\fP, then this mode
+also appends libraries to the \fBLINK_INTERFACE_LIBRARIES\fP and its
+per\-configuration equivalent.
+.sp
+This signature is for compatibility only. Prefer the \fBINTERFACE\fP mode
+instead.
+.sp
+Libraries specified as \fBdebug\fP are wrapped in a generator expression to
+correspond to debug builds. If policy \fBCMP0022\fP is
+not \fBNEW\fP, the libraries are also appended to the
+\fBLINK_INTERFACE_LIBRARIES_DEBUG\fP
+property (or to the properties corresponding to configurations listed in
+the \fBDEBUG_CONFIGURATIONS\fP global property if it is set).
+Libraries specified as \fBoptimized\fP are appended to the
+\fBINTERFACE_LINK_LIBRARIES\fP property. If policy \fBCMP0022\fP
+is not \fBNEW\fP, they are also appended to the
+\fBLINK_INTERFACE_LIBRARIES\fP property. Libraries specified as
+\fBgeneral\fP (or without any keyword) are treated as if specified for both
+\fBdebug\fP and \fBoptimized\fP\&.
+.SS Cyclic Dependencies of Static Libraries
+.sp
+The library dependency graph is normally acyclic (a DAG), but in the case
+of mutually\-dependent \fBSTATIC\fP libraries CMake allows the graph to
+contain cycles (strongly connected components). When another target links
+to one of the libraries, CMake repeats the entire connected component.
+For example, the code
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_library(A STATIC a.c)
+add_library(B STATIC b.c)
+target_link_libraries(A B)
+target_link_libraries(B A)
+add_executable(main main.c)
+target_link_libraries(main A)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+links \fBmain\fP to \fBA B A B\fP\&. While one repetition is usually
+sufficient, pathological object file and symbol arrangements can require
+more. One may handle such cases by using the
+\fBLINK_INTERFACE_MULTIPLICITY\fP target property or by manually
+repeating the component in the last \fBtarget_link_libraries\fP call.
+However, if two archives are really so interdependent they should probably
+be combined into a single archive, perhaps by using Object Libraries\&.
+.SS Creating Relocatable Packages
+.sp
+Note that it is not advisable to populate the
+\fBINTERFACE_LINK_LIBRARIES\fP of a target with absolute paths to dependencies.
+That would hard\-code into installed packages the library file paths
+for dependencies \fBas found on the machine the package was made on\fP\&.
+.sp
+See the Creating Relocatable Packages section of the
+\fBcmake\-packages(7)\fP manual for discussion of additional care
+that must be taken when specifying usage requirements while creating
+packages for redistribution.
+.SS target_sources
+.sp
+Add sources to a target.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+target_sources(<target>
+ <INTERFACE|PUBLIC|PRIVATE> [items1...]
+ [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Specify sources to use when compiling a given target. The
+named \fB<target>\fP must have been created by a command such as
+\fBadd_executable()\fP or \fBadd_library()\fP and must not be an
+IMPORTED Target\&.
+.sp
+The \fBINTERFACE\fP, \fBPUBLIC\fP and \fBPRIVATE\fP keywords are required to
+specify the scope of the following arguments. \fBPRIVATE\fP and \fBPUBLIC\fP
+items will populate the \fBSOURCES\fP property of
+\fB<target>\fP\&. \fBPUBLIC\fP and \fBINTERFACE\fP items will populate the
+\fBINTERFACE_SOURCES\fP property of \fB<target>\fP\&. The
+following arguments specify sources. Repeated calls for the same
+\fB<target>\fP append items in the order called.
+.sp
+Arguments to \fBtarget_sources\fP may use "generator expressions"
+with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP
+manual for available expressions. See the \fBcmake\-buildsystem(7)\fP
+manual for more on defining buildsystem properties.
+.SS try_compile
+.sp
+Try building some code.
+.SS Try Compiling Whole Projects
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+try_compile(RESULT_VAR <bindir> <srcdir>
+ <projectName> [<targetName>] [CMAKE_FLAGS <flags>...]
+ [OUTPUT_VARIABLE <var>])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Try building a project. The success or failure of the \fBtry_compile\fP,
+i.e. \fBTRUE\fP or \fBFALSE\fP respectively, is returned in \fBRESULT_VAR\fP\&.
+.sp
+In this form, \fB<srcdir>\fP should contain a complete CMake project with a
+\fBCMakeLists.txt\fP file and all sources. The \fB<bindir>\fP and \fB<srcdir>\fP
+will not be deleted after this command is run. Specify \fB<targetName>\fP to
+build a specific target instead of the \fBall\fP or \fBALL_BUILD\fP target. See
+below for the meaning of other options.
+.SS Try Compiling Source Files
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...>
+ [CMAKE_FLAGS <flags>...]
+ [COMPILE_DEFINITIONS <defs>...]
+ [LINK_LIBRARIES <libs>...]
+ [OUTPUT_VARIABLE <var>]
+ [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Try building an executable from one or more source files. The success or
+failure of the \fBtry_compile\fP, i.e. \fBTRUE\fP or \fBFALSE\fP respectively, is
+returned in \fBRESULT_VAR\fP\&.
+.sp
+In this form the user need only supply one or more source files that include a
+definition for \fBmain\fP\&. CMake will create a \fBCMakeLists.txt\fP file to build
+the source(s) as an executable that looks something like this:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+add_definitions(<expanded COMPILE_DEFINITIONS from caller>)
+include_directories(${INCLUDE_DIRECTORIES})
+link_directories(${LINK_DIRECTORIES})
+add_executable(cmTryCompileExec <srcfile>...)
+target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The options are:
+.INDENT 0.0
+.TP
+.B \fBCMAKE_FLAGS <flags>...\fP
+Specify flags of the form \fB\-DVAR:TYPE=VALUE\fP to be passed to
+the \fBcmake\fP command\-line used to drive the test build.
+The above example shows how values for variables
+\fBINCLUDE_DIRECTORIES\fP, \fBLINK_DIRECTORIES\fP, and \fBLINK_LIBRARIES\fP
+are used.
+.TP
+.B \fBCOMPILE_DEFINITIONS <defs>...\fP
+Specify \fB\-Ddefinition\fP arguments to pass to \fBadd_definitions\fP
+in the generated test project.
+.TP
+.B \fBCOPY_FILE <fileName>\fP
+Copy the linked executable to the given \fB<fileName>\fP\&.
+.TP
+.B \fBCOPY_FILE_ERROR <var>\fP
+Use after \fBCOPY_FILE\fP to capture into variable \fB<var>\fP any error
+message encountered while trying to copy the file.
+.TP
+.B \fBLINK_LIBRARIES <libs>...\fP
+Specify libraries to be linked in the generated project.
+The list of libraries may refer to system libraries and to
+Imported Targets from the calling project.
+.sp
+If this option is specified, any \fB\-DLINK_LIBRARIES=...\fP value
+given to the \fBCMAKE_FLAGS\fP option will be ignored.
+.TP
+.B \fBOUTPUT_VARIABLE <var>\fP
+Store the output from the build process the given variable.
+.UNINDENT
+.sp
+In this version all files in \fB<bindir>/CMakeFiles/CMakeTmp\fP will be
+cleaned automatically. For debugging, \fB\-\-debug\-trycompile\fP can be
+passed to \fBcmake\fP to avoid this clean. However, multiple sequential
+\fBtry_compile\fP operations reuse this single output directory. If you use
+\fB\-\-debug\-trycompile\fP, you can only debug one \fBtry_compile\fP call at a time.
+The recommended procedure is to protect all \fBtry_compile\fP calls in your
+project by \fBif(NOT DEFINED RESULT_VAR)\fP logic, configure with cmake
+all the way through once, then delete the cache entry associated with
+the try_compile call of interest, and then re\-run cmake again with
+\fB\-\-debug\-trycompile\fP\&.
+.SS Other Behavior Settings
+.sp
+Set the \fBCMAKE_TRY_COMPILE_CONFIGURATION\fP variable to choose
+a build configuration.
+.SS try_run
+.sp
+Try compiling and then running some code.
+.SS Try Compiling and Running Source Files
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR
+ bindir srcfile [CMAKE_FLAGS <flags>...]
+ [COMPILE_DEFINITIONS <defs>...]
+ [LINK_LIBRARIES <libs>...]
+ [COMPILE_OUTPUT_VARIABLE <var>]
+ [RUN_OUTPUT_VARIABLE <var>]
+ [OUTPUT_VARIABLE <var>]
+ [ARGS <args>...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Try compiling a \fB<srcfile>\fP\&. Returns \fBTRUE\fP or \fBFALSE\fP for success
+or failure in \fBCOMPILE_RESULT_VAR\fP\&. If the compile succeeded, runs the
+executable and returns its exit code in \fBRUN_RESULT_VAR\fP\&. If the
+executable was built, but failed to run, then \fBRUN_RESULT_VAR\fP will be
+set to \fBFAILED_TO_RUN\fP\&. See the \fBtry_compile()\fP command for
+information on how the test project is constructed to build the source file.
+.sp
+The options are:
+.INDENT 0.0
+.TP
+.B \fBCMAKE_FLAGS <flags>...\fP
+Specify flags of the form \fB\-DVAR:TYPE=VALUE\fP to be passed to
+the \fBcmake\fP command\-line used to drive the test build.
+The example in \fBtry_compile()\fP shows how values for variables
+\fBINCLUDE_DIRECTORIES\fP, \fBLINK_DIRECTORIES\fP, and \fBLINK_LIBRARIES\fP
+are used.
+.TP
+.B \fBCOMPILE_DEFINITIONS <defs>...\fP
+Specify \fB\-Ddefinition\fP arguments to pass to \fBadd_definitions\fP
+in the generated test project.
+.TP
+.B \fBCOMPILE_OUTPUT_VARIABLE <var>\fP
+Report the compile step build output in a given variable.
+.TP
+.B \fBLINK_LIBRARIES <libs>...\fP
+Specify libraries to be linked in the generated project.
+The list of libraries may refer to system libraries and to
+Imported Targets from the calling project.
+.sp
+If this option is specified, any \fB\-DLINK_LIBRARIES=...\fP value
+given to the \fBCMAKE_FLAGS\fP option will be ignored.
+.TP
+.B \fBOUTPUT_VARIABLE <var>\fP
+Report the compile build output and the output from running the executable
+in the given variable. This option exists for legacy reasons. Prefer
+\fBCOMPILE_OUTPUT_VARIABLE\fP and \fBRUN_OUTPUT_VARIABLE\fP instead.
+.TP
+.B \fBRUN_OUTPUT_VARIABLE <var>\fP
+Report the output from running the executable in a given variable.
+.UNINDENT
+.SS Other Behavior Settings
+.sp
+Set the \fBCMAKE_TRY_COMPILE_CONFIGURATION\fP variable to choose
+a build configuration.
+.SS Behavior when Cross Compiling
+.sp
+When cross compiling, the executable compiled in the first step
+usually cannot be run on the build host. The \fBtry_run\fP command checks
+the \fBCMAKE_CROSSCOMPILING\fP variable to detect whether CMake is in
+cross\-compiling mode. If that is the case, it will still try to compile
+the executable, but it will not try to run the executable unless the
+\fBCMAKE_CROSSCOMPILING_EMULATOR\fP variable is set. Instead it
+will create cache variables which must be filled by the user or by
+presetting them in some CMake script file to the values the executable
+would have produced if it had been run on its actual target platform.
+These cache entries are:
+.INDENT 0.0
+.TP
+.B \fB<RUN_RESULT_VAR>\fP
+Exit code if the executable were to be run on the target platform.
+.TP
+.B \fB<RUN_RESULT_VAR>__TRYRUN_OUTPUT\fP
+Output from stdout and stderr if the executable were to be run on
+the target platform. This is created only if the
+\fBRUN_OUTPUT_VARIABLE\fP or \fBOUTPUT_VARIABLE\fP option was used.
+.UNINDENT
+.sp
+In order to make cross compiling your project easier, use \fBtry_run\fP
+only if really required. If you use \fBtry_run\fP, use the
+\fBRUN_OUTPUT_VARIABLE\fP or \fBOUTPUT_VARIABLE\fP options only if really
+required. Using them will require that when cross\-compiling, the cache
+variables will have to be set manually to the output of the executable.
+You can also "guard" the calls to \fBtry_run\fP with an \fBif()\fP
+block checking the \fBCMAKE_CROSSCOMPILING\fP variable and
+provide an easy\-to\-preset alternative for this case.
+.SS unset
+.sp
+Unset a variable, cache variable, or environment variable.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+unset(<variable> [CACHE | PARENT_SCOPE])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Removes the specified variable causing it to become undefined. If
+CACHE is present then the variable is removed from the cache instead
+of the current scope.
+.sp
+If PARENT_SCOPE is present then the variable is removed from the scope
+above the current scope. See the same option in the set() command for
+further details.
+.sp
+<variable> can be an environment variable such as:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+unset(ENV{LD_LIBRARY_PATH})
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+in which case the variable will be removed from the current
+environment.
+.SS variable_watch
+.sp
+Watch the CMake variable for change.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+variable_watch(<variable name> [<command to execute>])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+If the specified variable changes, the message will be printed about
+the variable being changed. If the command is specified, the command
+will be executed. The command will receive the following arguments:
+COMMAND(<variable> <access> <value> <current list file> <stack>)
+.SS while
+.sp
+Evaluate a group of commands while a condition is true
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+while(condition)
+ COMMAND1(ARGS ...)
+ COMMAND2(ARGS ...)
+ ...
+endwhile(condition)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+All commands between while and the matching endwhile are recorded
+without being invoked. Once the endwhile is evaluated, the recorded
+list of commands is invoked as long as the condition is true. The
+condition is evaluated using the same logic as the if command.
+.SH DEPRECATED COMMANDS
+.sp
+These commands are available only for compatibility with older
+versions of CMake. Do not use them in new code.
+.SS build_name
+.sp
+Disallowed. See CMake Policy \fBCMP0036\fP\&.
+.sp
+Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER} instead.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+build_name(variable)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Sets the specified variable to a string representing the platform and
+compiler settings. These values are now available through the
+CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
+.SS exec_program
+.sp
+Deprecated. Use the execute_process() command instead.
+.sp
+Run an executable program during the processing of the CMakeList.txt
+file.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+exec_program(Executable [directory in which to run]
+ [ARGS <arguments to executable>]
+ [OUTPUT_VARIABLE <var>]
+ [RETURN_VALUE <var>])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The executable is run in the optionally specified directory. The
+executable can include arguments if it is double quoted, but it is
+better to use the optional ARGS argument to specify arguments to the
+program. This is because cmake will then be able to escape spaces in
+the executable path. An optional argument OUTPUT_VARIABLE specifies a
+variable in which to store the output. To capture the return value of
+the execution, provide a RETURN_VALUE. If OUTPUT_VARIABLE is
+specified, then no output will go to the stdout/stderr of the console
+running cmake.
+.SS export_library_dependencies
+.sp
+Disallowed. See CMake Policy \fBCMP0033\fP\&.
+.sp
+Use \fBinstall(EXPORT)\fP or \fBexport()\fP command.
+.sp
+This command generates an old\-style library dependencies file.
+Projects requiring CMake 2.6 or later should not use the command. Use
+instead the install(EXPORT) command to help export targets from an
+installation tree and the export() command to export targets from a
+build tree.
+.sp
+The old\-style library dependencies file does not take into account
+per\-configuration names of libraries or the LINK_INTERFACE_LIBRARIES
+target property.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+export_library_dependencies(<file> [APPEND])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Create a file named <file> that can be included into a CMake listfile
+with the INCLUDE command. The file will contain a number of SET
+commands that will set all the variables needed for library dependency
+information. This should be the last command in the top level
+CMakeLists.txt file of the project. If the APPEND option is
+specified, the SET commands will be appended to the given file instead
+of replacing it.
+.SS install_files
+.sp
+Deprecated. Use the install(FILES ) command instead.
+.sp
+This command has been superceded by the install command. It is
+provided for compatibility with older CMake code. The FILES form is
+directly replaced by the FILES form of the install command. The
+regexp form can be expressed more clearly using the GLOB form of the
+file command.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install_files(<dir> extension file file ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Create rules to install the listed files with the given extension into
+the given directory. Only files existing in the current source tree
+or its corresponding location in the binary tree may be listed. If a
+file specified already has an extension, that extension will be
+removed first. This is useful for providing lists of source files
+such as foo.cxx when you want the corresponding foo.h to be installed.
+A typical extension is \(aq.h\(aq.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install_files(<dir> regexp)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Any files in the current source directory that match the regular
+expression will be installed.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install_files(<dir> FILES file file ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Any files listed after the FILES keyword will be installed explicitly
+from the names given. Full paths are allowed in this form.
+.sp
+The directory <dir> is relative to the installation prefix, which is
+stored in the variable CMAKE_INSTALL_PREFIX.
+.SS install_programs
+.sp
+Deprecated. Use the install(PROGRAMS ) command instead.
+.sp
+This command has been superceded by the install command. It is
+provided for compatibility with older CMake code. The FILES form is
+directly replaced by the PROGRAMS form of the INSTALL command. The
+regexp form can be expressed more clearly using the GLOB form of the
+FILE command.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install_programs(<dir> file1 file2 [file3 ...])
+install_programs(<dir> FILES file1 [file2 ...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Create rules to install the listed programs into the given directory.
+Use the FILES argument to guarantee that the file list version of the
+command will be used even when there is only one argument.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install_programs(<dir> regexp)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+In the second form any program in the current source directory that
+matches the regular expression will be installed.
+.sp
+This command is intended to install programs that are not built by
+cmake, such as shell scripts. See the TARGETS form of the INSTALL
+command to create installation rules for targets built by cmake.
+.sp
+The directory <dir> is relative to the installation prefix, which is
+stored in the variable CMAKE_INSTALL_PREFIX.
+.SS install_targets
+.sp
+Deprecated. Use the install(TARGETS ) command instead.
+.sp
+This command has been superceded by the install command. It is
+provided for compatibility with older CMake code.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Create rules to install the listed targets into the given directory.
+The directory <dir> is relative to the installation prefix, which is
+stored in the variable CMAKE_INSTALL_PREFIX. If RUNTIME_DIRECTORY is
+specified, then on systems with special runtime files (Windows DLL),
+the files will be copied to that directory.
+.SS make_directory
+.sp
+Deprecated. Use the file(MAKE_DIRECTORY ) command instead.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+make_directory(directory)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Creates the specified directory. Full paths should be given. Any
+parent directories that do not exist will also be created. Use with
+care.
+.SS output_required_files
+.sp
+Disallowed. See CMake Policy \fBCMP0032\fP\&.
+.sp
+Approximate C preprocessor dependency scanning.
+.sp
+This command exists only because ancient CMake versions provided it.
+CMake handles preprocessor dependency scanning automatically using a
+more advanced scanner.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+output_required_files(srcfile outputfile)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Outputs a list of all the source files that are required by the
+specified srcfile. This list is written into outputfile. This is
+similar to writing out the dependencies for srcfile except that it
+jumps from .h files into .cxx, .c and .cpp files if possible.
+.SS remove
+.sp
+Deprecated. Use the list(REMOVE_ITEM ) command instead.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+remove(VAR VALUE VALUE ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Removes VALUE from the variable VAR. This is typically used to remove
+entries from a vector (e.g. semicolon separated list). VALUE is
+expanded.
+.SS subdir_depends
+.sp
+Disallowed. See CMake Policy \fBCMP0029\fP\&.
+.sp
+Does nothing.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+subdir_depends(subdir dep1 dep2 ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Does not do anything. This command used to help projects order
+parallel builds correctly. This functionality is now automatic.
+.SS subdirs
+.sp
+Deprecated. Use the add_subdirectory() command instead.
+.sp
+Add a list of subdirectories to the build.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
+ [PREORDER] )
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Add a list of subdirectories to the build. The add_subdirectory
+command should be used instead of subdirs although subdirs will still
+work. This will cause any CMakeLists.txt files in the sub directories
+to be processed by CMake. Any directories after the PREORDER flag are
+traversed first by makefile builds, the PREORDER flag has no effect on
+IDE projects. Any directories after the EXCLUDE_FROM_ALL marker will
+not be included in the top level makefile or project file. This is
+useful for having CMake create makefiles or projects for a set of
+examples in a project. You would want CMake to generate makefiles or
+project files for all the examples at the same time, but you would not
+want them to show up in the top level project or be built each time
+make is run from the top.
+.SS use_mangled_mesa
+.sp
+Disallowed. See CMake Policy \fBCMP0030\fP\&.
+.sp
+Copy mesa headers for use in combination with system GL.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The path to mesa includes, should contain gl_mangle.h. The mesa
+headers are copied to the specified output directory. This allows
+mangled mesa headers to override other GL headers by being added to
+the include directory path earlier.
+.SS utility_source
+.sp
+Disallowed. See CMake Policy \fBCMP0034\fP\&.
+.sp
+Specify the source tree of a third\-party utility.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+utility_source(cache_entry executable_name
+ path_to_source [file1 file2 ...])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When a third\-party utility\(aqs source is included in the distribution,
+this command specifies its location and name. The cache entry will
+not be set unless the path_to_source and all listed files exist. It
+is assumed that the source tree of the utility will have been built
+before it is needed.
+.sp
+When cross compiling CMake will print a warning if a utility_source()
+command is executed, because in many cases it is used to build an
+executable which is executed later on. This doesn\(aqt work when cross
+compiling, since the executable can run only on their target platform.
+So in this case the cache entry has to be adjusted manually so it
+points to an executable which is runnable on the build host.
+.SS variable_requires
+.sp
+Disallowed. See CMake Policy \fBCMP0035\fP\&.
+.sp
+Use the if() command instead.
+.sp
+Assert satisfaction of an option\(aqs required variables.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+variable_requires(TEST_VARIABLE RESULT_VARIABLE
+ REQUIRED_VARIABLE1
+ REQUIRED_VARIABLE2 ...)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The first argument (TEST_VARIABLE) is the name of the variable to be
+tested, if that variable is false nothing else is done. If
+TEST_VARIABLE is true, then the next argument (RESULT_VARIABLE) is a
+variable that is set to true if all the required variables are set.
+The rest of the arguments are variables that must be true or not set
+to NOTFOUND to avoid an error. If any are not true, an error is
+reported.
+.SS write_file
+.sp
+Deprecated. Use the file(WRITE ) command instead.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+write_file(filename "message to write"... [APPEND])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The first argument is the file name, the rest of the arguments are
+messages to write. If the argument APPEND is specified, then the
+message will be appended.
+.sp
+NOTE 1: file(WRITE ... and file(APPEND ... do exactly the same as
+this one but add some more functionality.
+.sp
+NOTE 2: When using write_file the produced file cannot be used as an
+input to CMake (CONFIGURE_FILE, source file ...) because it will lead
+to an infinite loop. Use configure_file if you want to generate input
+files to CMake.
+.SH CTEST COMMANDS
+.sp
+These commands are available only in ctest scripts.
+.SS ctest_build
+.sp
+Perform the CTest Build Step as a Dashboard Client\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ctest_build([BUILD <build\-dir>] [APPEND]
+ [CONFIGURATION <config>]
+ [FLAGS <flags>]
+ [PROJECT_NAME <project\-name>]
+ [TARGET <target\-name>]
+ [NUMBER_ERRORS <num\-err\-var>]
+ [NUMBER_WARNINGS <num\-warn\-var>]
+ [RETURN_VALUE <result\-var>]
+ )
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Build the project and store results in \fBBuild.xml\fP
+for submission with the \fBctest_submit()\fP command.
+.sp
+The \fBCTEST_BUILD_COMMAND\fP variable may be set to explicitly
+specify the build command line. Otherwise the build command line is
+computed automatically based on the options given.
+.sp
+The options are:
+.INDENT 0.0
+.TP
+.B \fBBUILD <build\-dir>\fP
+Specify the top\-level build directory. If not given, the
+\fBCTEST_BINARY_DIRECTORY\fP variable is used.
+.TP
+.B \fBAPPEND\fP
+Mark results for append to those previously submitted to a
+dashboard server since the last \fBctest_start()\fP call.
+Append semantics are defined by the dashboard server in use.
+.TP
+.B \fBCONFIGURATION <config>\fP
+Specify the build configuration (e.g. \fBDebug\fP). If not
+specified the \fBCTEST_BUILD_CONFIGURATION\fP variable will be checked.
+Otherwise the \fB\-C <cfg>\fP option given to the \fBctest(1)\fP
+command will be used, if any.
+.TP
+.B \fBFLAGS <flags>\fP
+Pass additional arguments to the underlying build command.
+If not specified the \fBCTEST_BUILD_FLAGS\fP variable will be checked.
+This can, e.g., be used to trigger a parallel build using the
+\fB\-j\fP option of make. See the \fBProcessorCount\fP module
+for an example.
+.TP
+.B \fBPROJECT_NAME <project\-name>\fP
+Set the name of the project to build. This should correspond
+to the top\-level call to the \fBproject()\fP command.
+If not specified the \fBCTEST_PROJECT_NAME\fP variable will be checked.
+.TP
+.B \fBTARGET <target\-name>\fP
+Specify the name of a target to build. If not specified the
+\fBCTEST_BUILD_TARGET\fP variable will be checked. Otherwise the
+default target will be built. This is the "all" target
+(called \fBALL_BUILD\fP in Visual Studio Generators).
+.TP
+.B \fBNUMBER_ERRORS <num\-err\-var>\fP
+Store the number of build errors detected in the given variable.
+.TP
+.B \fBNUMBER_WARNINGS <num\-warn\-var>\fP
+Store the number of build warnings detected in the given variable.
+.TP
+.B \fBRETURN_VALUE <result\-var>\fP
+Store the return value of the native build tool in the given variable.
+.TP
+.B \fBQUIET\fP
+Suppress any CTest\-specific non\-error output that would have been
+printed to the console otherwise. The summary of warnings / errors,
+as well as the output from the native build tool is unaffected by
+this option.
+.UNINDENT
+.SS ctest_configure
+.sp
+Perform the CTest Configure Step as a Dashboard Client\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ctest_configure([BUILD <build\-dir>] [SOURCE <source\-dir>] [APPEND]
+ [OPTIONS <options>] [RETURN_VALUE <result\-var>] [QUIET])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Configure the project build tree and record results in \fBConfigure.xml\fP
+for submission with the \fBctest_submit()\fP command.
+.sp
+The options are:
+.INDENT 0.0
+.TP
+.B \fBBUILD <build\-dir>\fP
+Specify the top\-level build directory. If not given, the
+\fBCTEST_BINARY_DIRECTORY\fP variable is used.
+.TP
+.B \fBSOURCE <source\-dir>\fP
+Specify the source directory. If not given, the
+\fBCTEST_SOURCE_DIRECTORY\fP variable is used.
+.TP
+.B \fBAPPEND\fP
+Mark results for append to those previously submitted to a
+dashboard server since the last \fBctest_start()\fP call.
+Append semantics are defined by the dashboard server in use.
+.TP
+.B \fBOPTIONS <options>\fP
+Specify command\-line arguments to pass to the configuration tool.
+.TP
+.B \fBRETURN_VALUE <result\-var>\fP
+Store in the \fB<result\-var>\fP variable the return value of the native
+configuration tool.
+.TP
+.B \fBQUIET\fP
+Suppress any CTest\-specific non\-error messages that would have
+otherwise been printed to the console. Output from the underlying
+configure command is not affected.
+.UNINDENT
+.SS ctest_coverage
+.sp
+Perform the CTest Coverage Step as a Dashboard Client\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ctest_coverage([BUILD <build\-dir>] [APPEND]
+ [LABELS <label>...]
+ [RETURN_VALUE <result\-var>]
+ [QUIET]
+ )
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Collect coverage tool results and stores them in \fBCoverage.xml\fP
+for submission with the \fBctest_submit()\fP command.
+.sp
+The options are:
+.INDENT 0.0
+.TP
+.B \fBBUILD <build\-dir>\fP
+Specify the top\-level build directory. If not given, the
+\fBCTEST_BINARY_DIRECTORY\fP variable is used.
+.TP
+.B \fBAPPEND\fP
+Mark results for append to those previously submitted to a
+dashboard server since the last \fBctest_start()\fP call.
+Append semantics are defined by the dashboard server in use.
+.TP
+.B \fBLABELS\fP
+Filter the coverage report to include only source files labeled
+with at least one of the labels specified.
+.TP
+.B \fBRETURN_VALUE <result\-var>\fP
+Store in the \fB<result\-var>\fP variable \fB0\fP if coverage tools
+ran without error and non\-zero otherwise.
+.TP
+.B \fBQUIET\fP
+Suppress any CTest\-specific non\-error output that would have been
+printed to the console otherwise. The summary indicating how many
+lines of code were covered is unaffected by this option.
+.UNINDENT
+.SS ctest_empty_binary_directory
+.sp
+empties the binary directory
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ctest_empty_binary_directory( directory )
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Removes a binary directory. This command will perform some checks
+prior to deleting the directory in an attempt to avoid malicious or
+accidental directory deletion.
+.SS ctest_memcheck
+.sp
+Perform the CTest MemCheck Step as a Dashboard Client\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ctest_memcheck([BUILD <build\-dir>] [APPEND]
+ [START <start\-number>]
+ [END <end\-number>]
+ [STRIDE <stride\-number>]
+ [EXCLUDE <exclude\-regex>]
+ [INCLUDE <include\-regex>]
+ [EXCLUDE_LABEL <label\-exclude\-regex>]
+ [INCLUDE_LABEL <label\-include\-regex>]
+ [PARALLEL_LEVEL <level>]
+ [SCHEDULE_RANDOM <ON|OFF>]
+ [STOP_TIME <time\-of\-day>]
+ [RETURN_VALUE <result\-var>]
+ [QUIET]
+ )
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Run tests with a dynamic analysis tool and store results in
+\fBMemCheck.xml\fP for submission with the \fBctest_submit()\fP
+command.
+.sp
+The options are the same as those for the \fBctest_test()\fP command.
+.SS ctest_read_custom_files
+.sp
+read CTestCustom files.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ctest_read_custom_files( directory ... )
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Read all the CTestCustom.ctest or CTestCustom.cmake files from the
+given directory.
+.SS ctest_run_script
+.sp
+runs a ctest \-S script
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ctest_run_script([NEW_PROCESS] script_file_name script_file_name1
+ script_file_name2 ... [RETURN_VALUE var])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Runs a script or scripts much like if it was run from ctest \-S. If no
+argument is provided then the current script is run using the current
+settings of the variables. If NEW_PROCESS is specified then each
+script will be run in a separate process.If RETURN_VALUE is specified
+the return value of the last script run will be put into var.
+.SS ctest_sleep
+.sp
+sleeps for some amount of time
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ctest_sleep(<seconds>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Sleep for given number of seconds.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ctest_sleep(<time1> <duration> <time2>)
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Sleep for t=(time1 + duration \- time2) seconds if t > 0.
+.SS ctest_start
+.sp
+Starts the testing for a given model
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ctest_start(Model [TRACK <track>] [APPEND] [source [binary]] [QUIET])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Starts the testing for a given model. The command should be called
+after the binary directory is initialized. If the \(aqsource\(aq and
+\(aqbinary\(aq directory are not specified, it reads the
+\fBCTEST_SOURCE_DIRECTORY\fP and \fBCTEST_BINARY_DIRECTORY\fP\&.
+If the track is
+specified, the submissions will go to the specified track. If APPEND
+is used, the existing TAG is used rather than creating a new one based
+on the current time stamp. If QUIET is used, CTest will suppress any
+non\-error messages that it otherwise would have printed to the console.
+.sp
+If the \fBCTEST_CHECKOUT_COMMAND\fP variable
+(or the \fBCTEST_CVS_CHECKOUT\fP variable)
+is set, its content is treated as command\-line. The command is
+invoked with the current working directory set to the parent of the source
+directory, even if the source directory already exists. This can be used
+to create the source tree from a version control repository.
+.SS ctest_submit
+.sp
+Perform the CTest Submit Step as a Dashboard Client\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ctest_submit([PARTS <part>...] [FILES <file>...]
+ [RETRY_COUNT <count>]
+ [RETRY_DELAY <delay>]
+ [RETURN_VALUE <result\-var>]
+ [QUIET]
+ )
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Submit results to a dashboard server.
+By default all available parts are submitted.
+.sp
+The options are:
+.INDENT 0.0
+.TP
+.B \fBPARTS <part>...\fP
+Specify a subset of parts to submit. Valid part names are:
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+Start = nothing
+Update = ctest_update results, in Update.xml
+Configure = ctest_configure results, in Configure.xml
+Build = ctest_build results, in Build.xml
+Test = ctest_test results, in Test.xml
+Coverage = ctest_coverage results, in Coverage.xml
+MemCheck = ctest_memcheck results, in DynamicAnalysis.xml
+Notes = Files listed by CTEST_NOTES_FILES, in Notes.xml
+ExtraFiles = Files listed by CTEST_EXTRA_SUBMIT_FILES
+Upload = Files prepared for upload by ctest_upload(), in Upload.xml
+Submit = nothing
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.TP
+.B \fBFILES <file>...\fP
+Specify an explicit list of specific files to be submitted.
+Each individual file must exist at the time of the call.
+.TP
+.B \fBRETRY_COUNT <count>\fP
+Specify how many times to retry a timed\-out submission.
+.TP
+.B \fBRETRY_DELAY <delay>\fP
+Specify how long (in seconds) to wait after a timed\-out submission
+before attempting to re\-submit.
+.TP
+.B \fBRETURN_VALUE <result\-var>\fP
+Store in the \fB<result\-var>\fP variable \fB0\fP for success and
+non\-zero on failure.
+.TP
+.B \fBQUIET\fP
+Suppress all non\-error messages that would have otherwise been
+printed to the console.
+.UNINDENT
+.SS Submit to CDash Upload API
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ctest_submit(CDASH_UPLOAD <file> [CDASH_UPLOAD_TYPE <type>])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This second signature is used to upload files to CDash via the CDash
+file upload API. The api first sends a request to upload to CDash along
+with a content hash of the file. If CDash does not already have the file,
+then it is uploaded. Along with the file, a CDash type string is specified
+to tell CDash which handler to use to process the data.
+.SS ctest_test
+.sp
+Perform the CTest Test Step as a Dashboard Client\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ctest_test([BUILD <build\-dir>] [APPEND]
+ [START <start\-number>]
+ [END <end\-number>]
+ [STRIDE <stride\-number>]
+ [EXCLUDE <exclude\-regex>]
+ [INCLUDE <include\-regex>]
+ [EXCLUDE_LABEL <label\-exclude\-regex>]
+ [INCLUDE_LABEL <label\-include\-regex>]
+ [PARALLEL_LEVEL <level>]
+ [SCHEDULE_RANDOM <ON|OFF>]
+ [STOP_TIME <time\-of\-day>]
+ [RETURN_VALUE <result\-var>]
+ [QUIET]
+ )
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Run tests in the project build tree and store results in
+\fBTest.xml\fP for submission with the \fBctest_submit()\fP command.
+.sp
+The options are:
+.INDENT 0.0
+.TP
+.B \fBBUILD <build\-dir>\fP
+Specify the top\-level build directory. If not given, the
+\fBCTEST_BINARY_DIRECTORY\fP variable is used.
+.TP
+.B \fBAPPEND\fP
+Mark results for append to those previously submitted to a
+dashboard server since the last \fBctest_start()\fP call.
+Append semantics are defined by the dashboard server in use.
+.TP
+.B \fBSTART <start\-number>\fP
+Specify the beginning of a range of test numbers.
+.TP
+.B \fBEND <end\-number>\fP
+Specify the end of a range of test numbers.
+.TP
+.B \fBSTRIDE <stride\-number>\fP
+Specify the stride by which to step acorss a range of test numbers.
+.TP
+.B \fBEXCLUDE <exclude\-regex>\fP
+Specify a regular expression matching test names to exclude.
+.TP
+.B \fBINCLUDE <include\-regex>\fP
+Specify a regular expression matching test names to include.
+Tests not matching this expression are excluded.
+.TP
+.B \fBEXCLUDE_LABEL <label\-exclude\-regex>\fP
+Specify a regular expression matching test labels to exclude.
+.TP
+.B \fBINCLUDE_LABEL <label\-include\-regex>\fP
+Specify a regular expression matching test labels to include.
+Tests not matching this expression are excluded.
+.TP
+.B \fBPARALLEL_LEVEL <level>\fP
+Specify a positive number representing the number of tests to
+be run in parallel.
+.TP
+.B \fBSCHEDULE_RANDOM <ON|OFF>\fP
+Launch tests in a random order. This may be useful for detecting
+implicit test dependencies.
+.TP
+.B \fBSTOP_TIME <time\-of\-day>\fP
+Specify a time of day at which the tests should all stop running.
+.TP
+.B \fBRETURN_VALUE <result\-var>\fP
+Store in the \fB<result\-var>\fP variable \fB0\fP if all tests passed.
+Store non\-zero if anything went wrong.
+.TP
+.B \fBQUIET\fP
+Suppress any CTest\-specific non\-error messages that would have otherwise
+been printed to the console. Output from the underlying test command is not
+affected. Summary info detailing the percentage of passing tests is also
+unaffected by the \fBQUIET\fP option.
+.UNINDENT
+.SS ctest_update
+.sp
+Perform the CTest Update Step as a Dashboard Client\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ctest_update([SOURCE <source\-dir>] [RETURN_VALUE <result\-var>] [QUIET])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Update the source tree from version control and record results in
+\fBUpdate.xml\fP for submission with the \fBctest_submit()\fP command.
+.sp
+The options are:
+.INDENT 0.0
+.TP
+.B \fBSOURCE <source\-dir>\fP
+Specify the source directory. If not given, the
+\fBCTEST_SOURCE_DIRECTORY\fP variable is used.
+.TP
+.B \fBRETURN_VALUE <result\-var>\fP
+Store in the \fB<result\-var>\fP variable the number of files
+updated or \fB\-1\fP on error.
+.TP
+.B \fBQUIET\fP
+Tell CTest to suppress most non\-error messages that it would
+have otherwise printed to the console. CTest will still report
+the new revision of the repository and any conflicting files
+that were found.
+.UNINDENT
+.SS ctest_upload
+.sp
+Upload files to a dashboard server as a Dashboard Client\&.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+ctest_upload(FILES <file>... [QUIET])
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The options are:
+.INDENT 0.0
+.TP
+.B \fBFILES <file>...\fP
+Specify a list of files to be sent along with the build results to the
+dashboard server.
+.TP
+.B \fBQUIET\fP
+Suppress any CTest\-specific non\-error output that would have been
+printed to the console otherwise.
+.UNINDENT
+.SH COPYRIGHT
+2000-2015 Kitware, Inc.
+.\" Generated by docutils manpage writer.
+.