| .\" Man page generated from reStructuredText. |
| . |
| .TH "CMAKE-COMMANDS" "7" "May 31, 2017" "3.8.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] |
| [DEPFILE depfile] |
| [VERBATIM] [APPEND] [USES_TERMINAL] |
| [COMMAND_EXPAND_LISTS]) |
| .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 name (created by the |
| \fBadd_executable()\fP command) it will automatically be replaced |
| by the location of the executable created at build time. If set, the |
| \fBCROSSCOMPILING_EMULATOR\fP executable target property will |
| also be prepended to the command to allow the executable to run on |
| the host. |
| (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 \fBCOMMAND_EXPAND_LISTS\fP |
| Lists in \fBCOMMAND\fP arguments will be expanded, including those |
| created with |
| \fBgenerator expressions\fP, |
| allowing \fBCOMMAND\fP arguments such as |
| \fB${CC} "\-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;\-I>" foo.cc\fP |
| to be properly expanded. |
| .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. |
| .TP |
| .B \fBDEPFILE\fP |
| Specify a \fB\&.d\fP depfile for the \fBNinja\fP generator. |
| A \fB\&.d\fP file holds dependencies usually emitted by the custom |
| command itself. |
| Using \fBDEPFILE\fP with other generators than Ninja is an error. |
| .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 \fB<target>\fP\&. The \fB<target>\fP must be defined in the current |
| directory; targets defined in other directories may not be specified. |
| .sp |
| 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] |
| [COMMAND_EXPAND_LISTS] |
| [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 name (created by the |
| \fBadd_executable()\fP command) it will automatically be replaced |
| by the location of the executable created at build time. If set, the |
| \fBCROSSCOMPILING_EMULATOR\fP executable target property will |
| also be prepended to the command to allow the executable to run on |
| the host. |
| 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 \fBCOMMAND_EXPAND_LISTS\fP |
| Lists in \fBCOMMAND\fP arguments will be expanded, including those |
| created with |
| \fBgenerator expressions\fP, |
| allowing \fBCOMMAND\fP arguments such as |
| \fB${CC} "\-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;\-I>" foo.cc\fP |
| to be properly expanded. |
| .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 existence 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. |
| A \fBSHARED\fP or \fBSTATIC\fP library may be marked with the \fBFRAMEWORK\fP |
| target property to create an OS X Framework. |
| .sp |
| If a library does not export any symbols, it must not be declared as a |
| \fBSHARED\fP library. For example, a Windows resource DLL or a managed C++/CLI |
| DLL that exports no unmanaged symbols would need to be a \fBMODULE\fP library. |
| This is because CMake expects a \fBSHARED\fP library to always have an |
| associated import library on Windows. |
| .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 existence 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 \fBbinary_dir\fP 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 \fBbinary_dir\fP is not specified, the value of |
| \fBsource_dir\fP, 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 \fBEXCLUDE_FROM_ALL\fP argument is provided then targets in the |
| subdirectory will not be included in the \fBALL\fP 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 \fBproject()\fP |
| 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 given test command is expected to exit with code \fB0\fP to pass and |
| non\-zero to fail, or vice\-versa if the \fBWILL_FAIL\fP test |
| property is set. Any output written to stdout or stderr will be |
| captured by \fBctest(1)\fP but does not affect the pass/fail status |
| unless the \fBPASS_REGULAR_EXPRESSION\fP or |
| \fBFAIL_REGULAR_EXPRESSION\fP test property is used. |
| .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 \fB<variable>\fP 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 |
| 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 \fB<key>\fP can be provided to select the information to be |
| queried. The list of queried values is stored in \fB<variable>\fP\&. |
| .sp |
| \fB<key>\fP 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 and |
| update \fI\%Policy Settings\fP to match the version given: |
| .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. |
| .sp |
| The \fBFATAL_ERROR\fP 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 Policy Settings |
| .sp |
| The \fBcmake_minimum_required(VERSION)\fP command implicitly invokes the |
| \fBcmake_policy(VERSION)\fP command to specify that the current |
| project code is written for the given version of CMake. |
| All policies introduced in the specified version or earlier will be |
| set to use NEW behavior. All policies introduced after the specified |
| version will be unset. This effectively requests behavior preferred |
| as of a given CMake version and tells newer CMake versions to warn |
| about their new policies. |
| .sp |
| 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. |
| .SS cmake_parse_arguments |
| .sp |
| \fBcmake_parse_arguments\fP is intended to be used in macros or functions for |
| parsing the arguments given to that macro or function. It processes the |
| arguments and defines a set of variables which hold the values of the |
| respective options. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| cmake_parse_arguments(<prefix> <options> <one_value_keywords> |
| <multi_value_keywords> args...) |
| |
| cmake_parse_arguments(PARSE_ARGV N <prefix> <options> <one_value_keywords> |
| <multi_value_keywords>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| The first signature reads processes arguments passed in the \fBargs...\fP\&. |
| This may be used in either a \fBmacro()\fP or a \fBfunction()\fP\&. |
| .sp |
| The \fBPARSE_ARGV\fP signature is only for use in a \fBfunction()\fP |
| body. In this case the arguments that are parsed come from the |
| \fBARGV#\fP variables of the calling function. The parsing starts with |
| the Nth argument, where \fBN\fP is an unsigned integer. This allows for |
| the values to have special characters like \fB;\fP in them. |
| .sp |
| The \fB<options>\fP argument contains all options for the respective macro, |
| i.e. keywords which can be used when calling the macro without any value |
| following, like e.g. the \fBOPTIONAL\fP keyword of the \fBinstall()\fP |
| command. |
| .sp |
| The \fB<one_value_keywords>\fP argument contains all keywords for this macro |
| which are followed by one value, like e.g. \fBDESTINATION\fP keyword of the |
| \fBinstall()\fP command. |
| .sp |
| The \fB<multi_value_keywords>\fP argument contains all keywords for this |
| macro which can be followed by more than one value, like e.g. the |
| \fBTARGETS\fP or \fBFILES\fP keywords of the \fBinstall()\fP command. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| All keywords shall be unique. I.e. every keyword shall only be specified |
| once in either \fB<options>\fP, \fB<one_value_keywords>\fP or |
| \fB<multi_value_keywords>\fP\&. A warning will be emitted if uniqueness is |
| violated. |
| .UNINDENT |
| .UNINDENT |
| .sp |
| When done, \fBcmake_parse_arguments\fP will have defined for each of the |
| keywords listed in \fB<options>\fP, \fB<one_value_keywords>\fP and |
| \fB<multi_value_keywords>\fP a variable composed of the given \fB<prefix>\fP |
| followed by \fB"_"\fP and the name of the respective keyword. These |
| variables will then hold the respective value from the argument list. |
| For the \fB<options>\fP keywords this will be \fBTRUE\fP or \fBFALSE\fP\&. |
| .sp |
| All remaining arguments are collected in a variable |
| \fB<prefix>_UNPARSED_ARGUMENTS\fP, this can be checked afterwards to see |
| whether your macro was called with unrecognized parameters. |
| .sp |
| As an example here a \fBmy_install()\fP macro, which takes similar arguments |
| as the real \fBinstall()\fP command: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| function(MY_INSTALL) |
| set(options OPTIONAL FAST) |
| set(oneValueArgs DESTINATION RENAME) |
| set(multiValueArgs TARGETS CONFIGURATIONS) |
| cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" |
| "${multiValueArgs}" ${ARGN} ) |
| |
| # ... |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Assume \fBmy_install()\fP has been called like this: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| After the \fBcmake_parse_arguments\fP call the macro will have set the |
| following variables: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| MY_INSTALL_OPTIONAL = TRUE |
| MY_INSTALL_FAST = FALSE (was not used in call to my_install) |
| MY_INSTALL_DESTINATION = "bin" |
| MY_INSTALL_RENAME = "" (was not used) |
| MY_INSTALL_TARGETS = "foo;bar" |
| MY_INSTALL_CONFIGURATIONS = "" (was not used) |
| MY_INSTALL_UNPARSED_ARGUMENTS = "blub" (nothing expected after "OPTIONAL") |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| You can then continue and process these variables. |
| .sp |
| Keywords terminate lists of values, e.g. if directly after a |
| one_value_keyword another recognized keyword follows, this is |
| interpreted as the beginning of the new option. E.g. |
| \fBmy_install(TARGETS foo DESTINATION OPTIONAL)\fP would result in |
| \fBMY_INSTALL_DESTINATION\fP set to \fB"OPTIONAL"\fP, but as \fBOPTIONAL\fP |
| is a keyword itself \fBMY_INSTALL_DESTINATION\fP will be empty and |
| \fBMY_INSTALL_OPTIONAL\fP will therefore be set to \fBTRUE\fP\&. |
| .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 |
| \fBsourceListName\fP\&. \fBdriverName\fP 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*[]);) \fBdriverName\fP will be able to call |
| each of the tests by name on the command line. If \fBEXTRA_INCLUDE\fP is |
| specified, then the next argument is included into the generated file. |
| If \fBFUNCTION\fP 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 |
| \fBCMAKE_TESTDRIVER_BEFORE_TESTMAIN\fP cmake variable can be set to |
| have code that will be placed directly before calling the test main function. |
| \fBCMAKE_TESTDRIVER_AFTER_TESTMAIN\fP 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 \fBset_property()\fP and |
| \fBget_property()\fP commands. This is primarily useful to associate |
| documentation with property names that may be retrieved with the |
| \fBget_property()\fP 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 \fBset_property()\fP and \fBget_property()\fP no |
| actual scope needs to be given; only the kind of scope is important. |
| .sp |
| The required \fBPROPERTY\fP option is immediately followed by the name of |
| the property being defined. |
| .sp |
| If the \fBINHERITED\fP option then the \fBget_property()\fP command will |
| chain up to the next higher scope when the requested property is not set |
| in the scope given to the command. \fBDIRECTORY\fP scope chains to |
| \fBGLOBAL\fP\&. \fBTARGET\fP, \fBSOURCE\fP, and \fBTEST\fP chain to \fBDIRECTORY\fP\&. |
| .sp |
| The \fBBRIEF_DOCS\fP and \fBFULL_DOCS\fP options are followed by strings to be |
| associated with the property as its brief and full documentation. |
| Corresponding options to the \fBget_property()\fP 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 \fBif()\fP 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 \fBif()\fP 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 \fBOPTIONAL\fP 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 |
| \fBadd_test()\fP 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 \fBforeach()\fP 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 \fBfunction()\fP 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 \fBif()\fP 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 \fBmacro()\fP 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 \fBwhile()\fP 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] |
| [ENCODING <name>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Runs the given sequence of one or more commands in parallel 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 \fBCOMMAND\fP |
| 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.) |
| .sp |
| If a sequential execution of multiple commands is required, use multiple |
| \fI\%execute_process()\fP calls with a single \fBCOMMAND\fP argument. |
| .TP |
| .B \fBWORKING_DIRECTORY\fP |
| The named directory will be set as the current working directory of |
| the child processes. |
| .TP |
| .B \fBTIMEOUT\fP |
| The child processes will be terminated if they do not finish in the |
| specified number of seconds (fractions are allowed). |
| .TP |
| .B \fBRESULT_VARIABLE\fP |
| 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 \fBOUTPUT_VARIABLE\fP, \fBERROR_VARIABLE\fP |
| 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 \fBINPUT_FILE, OUTPUT_FILE\fP, \fBERROR_FILE\fP |
| 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 \fBOUTPUT_QUIET\fP, \fBERROR_QUIET\fP |
| The standard output or standard error results will be quietly ignored. |
| .TP |
| .B \fBENCODING <name>\fP |
| On Windows, the encoding that is used to decode output from the process. |
| Ignored on other platforms. |
| Valid encoding names are: |
| .INDENT 7.0 |
| .TP |
| .B \fBNONE\fP |
| Perform no decoding. This assumes that the process output is encoded |
| in the same way as CMake\(aqs internal encoding (UTF\-8). |
| This is the default. |
| .TP |
| .B \fBAUTO\fP |
| Use the current active console\(aqs codepage or if that isn\(aqt |
| available then use ANSI. |
| .TP |
| .B \fBANSI\fP |
| Use the ANSI codepage. |
| .TP |
| .B \fBOEM\fP |
| Use the original equipment manufacturer (OEM) code page. |
| .TP |
| .B \fBUTF8\fP |
| Use the UTF\-8 codepage. |
| .UNINDENT |
| .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 \fB<filename>\fP 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 \fBNAMESPACE\fP |
| option is given the \fB<namespace>\fP string will be prepended to all target |
| names written to the file. |
| .sp |
| Target installations are associated with the export \fB<export\-name>\fP |
| 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 \fBinstall(EXPORT)\fP 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 \fB<name>\fP\&. The find_package command may consider the |
| directory while searching for package \fB<name>\fP\&. 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 (\fB<name>Config.cmake\fP) 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. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| export(TARGETS [target1 [target2 [...]]] [ANDROID_MK <filename>]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| This signature exports cmake built targets to the android ndk build system |
| by creating an Android.mk file that references the prebuilt targets. The |
| Android NDK supports the use of prebuilt libraries, both static and shared. |
| This allows cmake to build the libraries of a project and make them available |
| to an ndk build system complete with transitive dependencies, include flags |
| and defines required to use the libraries. The signature takes a list of |
| targets and puts them in the Android.mk file specified by the \fB<filename>\fP |
| given. This signature can only be used if policy CMP0022 is NEW for all |
| targets given. A error will be issued if that policy is set to OLD for one |
| of the targets. |
| .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(<HASH> <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\&. The supported \fB<HASH>\fP algorithm names |
| are those listed by the string(<HASH>) |
| command. |
| |
| .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. No specific order of results is defined other than that it is |
| deterministic. If order is important then sort the list explicitly |
| (e.g. using the \fBlist(SORT)\fP command). |
| .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. No error is emitted if a |
| given file does not exist. |
| |
| .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. |
| .TP |
| .B \fBUSERPWD <username>:<password>\fP |
| Set username and password for operation. |
| .TP |
| .B \fBHTTPHEADER <HTTP\-header>\fP |
| HTTP header for operation. Suboption can be repeated several times. |
| .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 the algorithms supported by \fBfile(<HASH>)\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 |
| Note also that \fBfile(GENERATE)\fP does not create the output file until the |
| generation phase. The output file will not yet have been written when the |
| \fBfile(GENERATE)\fP command returns, it is written only after processing all |
| of a project\(aqs \fBCMakeLists.txt\fP files. |
| |
| .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. |
| .sp |
| Options include: |
| .INDENT 0.0 |
| .TP |
| .B \fBNAMES\fP |
| Specify one or more possible names for the full path to a file\&. |
| .sp |
| When using this to specify names with and without a version |
| suffix, we recommend specifying the unversioned name first |
| so that locally\-built packages can be found before those |
| provided by distributions. |
| .TP |
| .B \fBHINTS\fP, \fBPATHS\fP |
| Specify directories to search in addition to the default locations. |
| The \fBENV var\fP sub\-option reads paths from a system environment |
| variable. |
| .TP |
| .B \fBPATH_SUFFIXES\fP |
| Specify additional subdirectories to check below each directory |
| location otherwise considered. |
| .TP |
| .B \fBDOC\fP |
| Specify the documentation string for the \fB<VAR>\fP cache entry. |
| .UNINDENT |
| .sp |
| If \fBNO_DEFAULT_PATH\fP is specified, then no additional paths are |
| added to the search. |
| If \fBNO_DEFAULT_PATH\fP 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 \fB\-DVAR=value\fP\&. |
| This can be skipped if \fBNO_CMAKE_PATH\fP is passed. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_INCLUDE_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_FRAMEWORK_PATH\fP |
| .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 |
| .IP \(bu 2 |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_INCLUDE_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_FRAMEWORK_PATH\fP |
| .UNINDENT |
| .IP 3. 3 |
| Search the 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 an argument. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| Directories in \fBINCLUDE\fP\&. |
| On Windows hosts: |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>/[s]bin\fP in \fBPATH\fP, and |
| \fB<entry>/include\fP for other entries in \fBPATH\fP, and the |
| directories in \fBPATH\fP itself. |
| .UNINDENT |
| .IP 5. 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 |
| .IP \(bu 2 |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>\fP in |
| \fBCMAKE_SYSTEM_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_INCLUDE_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_FRAMEWORK_PATH\fP |
| .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 OS X the \fBCMAKE_FIND_FRAMEWORK\fP and |
| \fBCMAKE_FIND_APPBUNDLE\fP variables determine the order of |
| preference between Apple\-style and unix\-style package components. |
| .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 using options: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_FIND_ROOT_PATH_BOTH\fP |
| Search in the order described above. |
| .TP |
| .B \fBNO_CMAKE_FIND_ROOT_PATH\fP |
| Do not use the \fBCMAKE_FIND_ROOT_PATH\fP variable. |
| .TP |
| .B \fBONLY_CMAKE_FIND_ROOT_PATH\fP |
| Search only the re\-rooted directories and directories below |
| \fBCMAKE_STAGING_PREFIX\fP\&. |
| .UNINDENT |
| .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. |
| .sp |
| Options include: |
| .INDENT 0.0 |
| .TP |
| .B \fBNAMES\fP |
| Specify one or more possible names for the library\&. |
| .sp |
| When using this to specify names with and without a version |
| suffix, we recommend specifying the unversioned name first |
| so that locally\-built packages can be found before those |
| provided by distributions. |
| .TP |
| .B \fBHINTS\fP, \fBPATHS\fP |
| Specify directories to search in addition to the default locations. |
| The \fBENV var\fP sub\-option reads paths from a system environment |
| variable. |
| .TP |
| .B \fBPATH_SUFFIXES\fP |
| Specify additional subdirectories to check below each directory |
| location otherwise considered. |
| .TP |
| .B \fBDOC\fP |
| Specify the documentation string for the \fB<VAR>\fP cache entry. |
| .UNINDENT |
| .sp |
| If \fBNO_DEFAULT_PATH\fP is specified, then no additional paths are |
| added to the search. |
| If \fBNO_DEFAULT_PATH\fP 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 \fB\-DVAR=value\fP\&. |
| This can be skipped if \fBNO_CMAKE_PATH\fP is passed. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/lib/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP is set, |
| and \fB<prefix>/lib\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_LIBRARY_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_FRAMEWORK_PATH\fP |
| .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 |
| .IP \(bu 2 |
| \fB<prefix>/lib/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP is set, |
| and \fB<prefix>/lib\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_LIBRARY_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_FRAMEWORK_PATH\fP |
| .UNINDENT |
| .IP 3. 3 |
| Search the 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 an argument. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| Directories in \fBLIB\fP\&. |
| On Windows hosts: |
| \fB<prefix>/lib/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP is set, |
| and \fB<prefix>/lib\fP for each \fB<prefix>/[s]bin\fP in \fBPATH\fP, and |
| \fB<entry>/lib\fP for other entries in \fBPATH\fP, |
| and the directories in \fBPATH\fP itself. |
| .UNINDENT |
| .IP 5. 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 |
| .IP \(bu 2 |
| \fB<prefix>/lib/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP is set, |
| and \fB<prefix>/lib\fP for each \fB<prefix>\fP in |
| \fBCMAKE_SYSTEM_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_LIBRARY_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_FRAMEWORK_PATH\fP |
| .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 OS X the \fBCMAKE_FIND_FRAMEWORK\fP and |
| \fBCMAKE_FIND_APPBUNDLE\fP variables determine the order of |
| preference between Apple\-style and unix\-style package components. |
| .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 using options: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_FIND_ROOT_PATH_BOTH\fP |
| Search in the order described above. |
| .TP |
| .B \fBNO_CMAKE_FIND_ROOT_PATH\fP |
| Do not use the \fBCMAKE_FIND_ROOT_PATH\fP variable. |
| .TP |
| .B \fBONLY_CMAKE_FIND_ROOT_PATH\fP |
| Search only the re\-rooted directories and directories below |
| \fBCMAKE_STAGING_PREFIX\fP\&. |
| .UNINDENT |
| .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 \fBNAMES\fP option this command by |
| default will consider one name at a time and search every directory |
| for it. The \fBNAMES_PER_DIR\fP 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 \fB<VAR>\fP will be set to the full |
| path to the framework \fB<fullPath>/A.framework\fP\&. When a full path to a |
| framework is used as a library, CMake will use a \fB\-framework A\fP, and a |
| \fB\-F<fullPath>\fP to link the framework to the target. |
| .sp |
| If the \fBFIND_LIBRARY_USE_LIB32_PATHS\fP global property is set |
| all search paths will be tested as normal, with \fB32/\fP appended, and |
| with all matches of \fBlib/\fP replaced with \fBlib32/\fP\&. This property is |
| automatically set for the platforms that are known to need it if at |
| least one of the languages supported by the \fBproject()\fP command |
| is enabled. |
| .sp |
| If the \fBFIND_LIBRARY_USE_LIB64_PATHS\fP global property is set |
| all search paths will be tested as normal, with \fB64/\fP appended, and |
| with all matches of \fBlib/\fP replaced with \fBlib64/\fP\&. This property is |
| automatically set for the platforms that are known to need it if at |
| least one of the languages supported by the \fBproject()\fP 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: unless the variable \fBCMAKE_FIND_PACKAGE_SORT_ORDER\fP |
| is set no attempt is made to choose a highest or closest version number. |
| .sp |
| To control the order in which \fBfind_package\fP checks for compatibiliy use |
| the two variables \fBCMAKE_FIND_PACKAGE_SORT_ORDER\fP and |
| \fBCMAKE_FIND_PACKAGE_SORT_DIRECTION\fP\&. |
| For instance in order to select the highest version one can set: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) |
| SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| before calling \fBfind_package\fP\&. |
| .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) |
| <prefix>/<name>*/(lib/<arch>|lib|share)/cmake/<name>*/ (W/U) |
| <prefix>/<name>*/(lib/<arch>|lib|share)/<name>*/ (W/U) |
| <prefix>/<name>*/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/ (W/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 |
| \fBCMAKE_FIND_FRAMEWORK\fP and \fBCMAKE_FIND_APPBUNDLE\fP |
| variables determine the order of preference. |
| .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 |
| 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 using options: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_FIND_ROOT_PATH_BOTH\fP |
| Search in the order described above. |
| .TP |
| .B \fBNO_CMAKE_FIND_ROOT_PATH\fP |
| Do not use the \fBCMAKE_FIND_ROOT_PATH\fP variable. |
| .TP |
| .B \fBONLY_CMAKE_FIND_ROOT_PATH\fP |
| Search only the re\-rooted directories and directories below |
| \fBCMAKE_STAGING_PREFIX\fP\&. |
| .UNINDENT |
| .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. |
| .sp |
| Options include: |
| .INDENT 0.0 |
| .TP |
| .B \fBNAMES\fP |
| Specify one or more possible names for the file in a directory\&. |
| .sp |
| When using this to specify names with and without a version |
| suffix, we recommend specifying the unversioned name first |
| so that locally\-built packages can be found before those |
| provided by distributions. |
| .TP |
| .B \fBHINTS\fP, \fBPATHS\fP |
| Specify directories to search in addition to the default locations. |
| The \fBENV var\fP sub\-option reads paths from a system environment |
| variable. |
| .TP |
| .B \fBPATH_SUFFIXES\fP |
| Specify additional subdirectories to check below each directory |
| location otherwise considered. |
| .TP |
| .B \fBDOC\fP |
| Specify the documentation string for the \fB<VAR>\fP cache entry. |
| .UNINDENT |
| .sp |
| If \fBNO_DEFAULT_PATH\fP is specified, then no additional paths are |
| added to the search. |
| If \fBNO_DEFAULT_PATH\fP 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 \fB\-DVAR=value\fP\&. |
| This can be skipped if \fBNO_CMAKE_PATH\fP is passed. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_INCLUDE_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_FRAMEWORK_PATH\fP |
| .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 |
| .IP \(bu 2 |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_INCLUDE_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_FRAMEWORK_PATH\fP |
| .UNINDENT |
| .IP 3. 3 |
| Search the 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 an argument. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| Directories in \fBINCLUDE\fP\&. |
| On Windows hosts: |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>/[s]bin\fP in \fBPATH\fP, and |
| \fB<entry>/include\fP for other entries in \fBPATH\fP, and the |
| directories in \fBPATH\fP itself. |
| .UNINDENT |
| .IP 5. 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 |
| .IP \(bu 2 |
| \fB<prefix>/include/<arch>\fP if \fBCMAKE_LIBRARY_ARCHITECTURE\fP |
| is set, and \fB<prefix>/include\fP for each \fB<prefix>\fP in |
| \fBCMAKE_SYSTEM_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_INCLUDE_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_FRAMEWORK_PATH\fP |
| .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 OS X the \fBCMAKE_FIND_FRAMEWORK\fP and |
| \fBCMAKE_FIND_APPBUNDLE\fP variables determine the order of |
| preference between Apple\-style and unix\-style package components. |
| .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 using options: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_FIND_ROOT_PATH_BOTH\fP |
| Search in the order described above. |
| .TP |
| .B \fBNO_CMAKE_FIND_ROOT_PATH\fP |
| Do not use the \fBCMAKE_FIND_ROOT_PATH\fP variable. |
| .TP |
| .B \fBONLY_CMAKE_FIND_ROOT_PATH\fP |
| Search only the re\-rooted directories and directories below |
| \fBCMAKE_STAGING_PREFIX\fP\&. |
| .UNINDENT |
| .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 \fBA/b.h\fP, then |
| the framework search will look for \fBA.framework/Headers/b.h\fP\&. If that |
| is found the path will be set to the path to the framework. CMake |
| will convert this to the correct \fB\-F\fP 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 ...] [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 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. |
| .sp |
| Options include: |
| .INDENT 0.0 |
| .TP |
| .B \fBNAMES\fP |
| Specify one or more possible names for the program\&. |
| .sp |
| When using this to specify names with and without a version |
| suffix, we recommend specifying the unversioned name first |
| so that locally\-built packages can be found before those |
| provided by distributions. |
| .TP |
| .B \fBHINTS\fP, \fBPATHS\fP |
| Specify directories to search in addition to the default locations. |
| The \fBENV var\fP sub\-option reads paths from a system environment |
| variable. |
| .TP |
| .B \fBPATH_SUFFIXES\fP |
| Specify additional subdirectories to check below each directory |
| location otherwise considered. |
| .TP |
| .B \fBDOC\fP |
| Specify the documentation string for the \fB<VAR>\fP cache entry. |
| .UNINDENT |
| .sp |
| If \fBNO_DEFAULT_PATH\fP is specified, then no additional paths are |
| added to the search. |
| If \fBNO_DEFAULT_PATH\fP 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 \fB\-DVAR=value\fP\&. |
| This can be skipped if \fBNO_CMAKE_PATH\fP is passed. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fB<prefix>/[s]bin\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_PROGRAM_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_APPBUNDLE_PATH\fP |
| .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 |
| .IP \(bu 2 |
| \fB<prefix>/[s]bin\fP for each \fB<prefix>\fP in \fBCMAKE_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_PROGRAM_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_APPBUNDLE_PATH\fP |
| .UNINDENT |
| .IP 3. 3 |
| Search the 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 an argument. |
| .INDENT 3.0 |
| .IP \(bu 2 |
| \fBPATH\fP |
| .UNINDENT |
| .IP 5. 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 |
| .IP \(bu 2 |
| \fB<prefix>/[s]bin\fP for each \fB<prefix>\fP in |
| \fBCMAKE_SYSTEM_PREFIX_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_PROGRAM_PATH\fP |
| .IP \(bu 2 |
| \fBCMAKE_SYSTEM_APPBUNDLE_PATH\fP |
| .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 OS X the \fBCMAKE_FIND_FRAMEWORK\fP and |
| \fBCMAKE_FIND_APPBUNDLE\fP variables determine the order of |
| preference between Apple\-style and unix\-style package components. |
| .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 using options: |
| .INDENT 0.0 |
| .TP |
| .B \fBCMAKE_FIND_ROOT_PATH_BOTH\fP |
| Search in the order described above. |
| .TP |
| .B \fBNO_CMAKE_FIND_ROOT_PATH\fP |
| Do not use the \fBCMAKE_FIND_ROOT_PATH\fP variable. |
| .TP |
| .B \fBONLY_CMAKE_FIND_ROOT_PATH\fP |
| Search only the re\-rooted directories and directories below |
| \fBCMAKE_STAGING_PREFIX\fP\&. |
| .UNINDENT |
| .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. |
| .sp |
| When more than one value is given to the \fBNAMES\fP option this command by |
| default will consider one name at a time and search every directory |
| for it. The \fBNAMES_PER_DIR\fP option tells this command to consider one |
| directory at a time and search for all names in it. |
| .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 |
| \fBresultingLibraryName_FLTK_UI_SRCS\fP 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 |
| \fB${loop_var}\fP 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 \fBLISTS\fP 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 \fBITEMS\fP 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 global 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 global property from the CMake instance. The value of the property is |
| stored in the variable \fBVAR\fP\&. If the property is not found, \fBVAR\fP |
| will be set to "NOTFOUND". See the \fBcmake\-properties(7)\fP manual |
| for available properties. |
| .sp |
| See also the \fBget_property()\fP command \fBGLOBAL\fP option. |
| .sp |
| In addition to global properties, this command (for historical reasons) |
| also supports the \fBVARIABLES\fP and \fBMACROS\fP directory |
| properties. It also supports a special \fBCOMPONENTS\fP global property that |
| lists the components given to the \fBinstall()\fP command. |
| .SS get_directory_property |
| .sp |
| Get a property of \fBDIRECTORY\fP 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 \fBDIRECTORY\fP |
| 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 \fBget_property()\fP command. |
| .SS get_filename_component |
| .sp |
| Get a specific component of a full filename. |
| |
| .sp |
| .ce |
| ---- |
| |
| .ce 0 |
| .sp |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_filename_component(<VAR> <FileName> <COMP> [CACHE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Set \fB<VAR>\fP to a component of \fB<FileName>\fP, where \fB<COMP>\fP 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 |
| 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 slashes. |
| The longest file extension is always considered. If the optional |
| \fBCACHE\fP argument is specified, the result variable is added to the |
| cache. |
| |
| .sp |
| .ce |
| ---- |
| |
| .ce 0 |
| .sp |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| get_filename_component(<VAR> <FileName> |
| <COMP> [BASE_DIR <BASE_DIR>] |
| [CACHE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Set \fB<VAR>\fP to the absolute path of \fB<FileName>\fP, where \fB<COMP>\fP is one |
| of: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| ABSOLUTE = Full path to file |
| REALPATH = Full path to existing file with symlinks resolved |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| If the provided \fB<FileName>\fP is a relative path, it is evaluated relative |
| to the given base directory \fB<BASE_DIR>\fP\&. If no base directory is |
| provided, the default base directory will be |
| \fBCMAKE_CURRENT_SOURCE_DIR\fP\&. |
| .sp |
| Paths are returned with forward slashes and have no trailing slahes. If the |
| optional \fBCACHE\fP argument is specified, the result variable is added to the |
| cache. |
| |
| .sp |
| .ce |
| ---- |
| |
| .ce 0 |
| .sp |
| .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 \fB<FileName>\fP will be found in the system search path or |
| left as a full path. If \fBPROGRAM_ARGS\fP is present with \fBPROGRAM\fP, then |
| any command\-line arguments present in the \fB<FileName>\fP string are split |
| from the program name and stored in \fB<ARG_VAR>\fP\&. 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 \fBVAR\fP\&. If the property is not found, \fBVAR\fP |
| will be set to "NOTFOUND". Use \fBset_source_files_properties()\fP |
| to set property values. Source file properties usually control how the |
| file is built. One property that is always there is \fBLOCATION\fP |
| .sp |
| See also the more general \fBget_property()\fP 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 \fBVAR\fP\&. If the property is not found, \fBVAR\fP will be set to |
| "NOTFOUND". Use \fBset_target_properties()\fP 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 |
| \fBCMakeLists.txt\fP file. |
| .sp |
| See also the more general \fBget_property()\fP 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 \fBVAR\fP\&. If the test or property is not found, \fBVAR\fP will |
| be set to "NOTFOUND". For a list of standard properties you can type |
| \fBcmake \-\-help\-property\-list\fP\&. |
| .sp |
| See also the more general \fBget_property()\fP 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, \fBLESS_EQUAL, \(ga\(gaGREATER\fP, \fBGREATER_EQUAL\fP, |
| \fBSTREQUAL\fP, \fBSTRLESS\fP, \fBSTRLESS_EQUAL\fP, \fBSTRGREATER\fP, |
| \fBSTRGREATER_EQUAL\fP, \fBVERSION_EQUAL\fP, \fBVERSION_LESS\fP, |
| \fBVERSION_LESS_EQUAL\fP, \fBVERSION_GREATER\fP, \fBVERSION_GREATER_EQUAL\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 created |
| by a call to the \fBadd_executable()\fP, \fBadd_library()\fP, |
| or \fBadd_custom_target()\fP command that has already been invoked |
| (in any directory). |
| .TP |
| .B \fBif(TEST test\-name)\fP |
| True if the given name is an existing test name created by the |
| \fBadd_test()\fP command. |
| .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 \fBfile1\fP is newer than \fBfile2\fP 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> LESS_EQUAL <variable|string>)\fP |
| True if the given string or variable\(aqs value is a valid number and less |
| than or equal to that on the right. |
| .TP |
| .B \fBif(<variable|string> GREATER_EQUAL <variable|string>)\fP |
| True if the given string or variable\(aqs value is a valid number and greater |
| than or 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> STRLESS_EQUAL <variable|string>)\fP |
| True if the given string or variable\(aqs value is lexicographically less |
| than or equal to the string or variable on the right. |
| .TP |
| .B \fBif(<variable|string> STRGREATER_EQUAL <variable|string>)\fP |
| True if the given string or variable\(aqs value is lexicographically greater |
| than or 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_GREATER <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_LESS_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_EQUAL <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, \fBEQUAL\fP, |
| \fBLESS_EQUAL\fP, and \fBGREATER_EQUAL\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, \fBSTRGREATER\fP, |
| \fBSTREQUAL\fP, \fBSTRLESS_EQUAL\fP, and \fBSTRGREATER_EQUAL\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_GREATER\fP, \fBVERSION_EQUAL\fP, \fBVERSION_LESS_EQUAL\fP, and |
| \fBVERSION_GREATER_EQUAL\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 \fBadd_dependencies()\fP |
| command to make things depend on the external project. |
| .sp |
| \fBTYPE\fP, \fBGUID\fP and \fBPLATFORM\fP 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). |
| .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 \fBregex_match\fP will be traced as dependencies. Only files |
| matching \fBregex_complain\fP 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 \fBOPTIONAL\fP |
| is present, then no error is raised if the file does not exist. If |
| \fBRESULT_VARIABLE\fP 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 |
| \fB<modulename>.cmake\fP is searched first in \fBCMAKE_MODULE_PATH\fP, |
| then in the CMake module directory. There is one exception to this: if |
| the file which calls \fBinclude()\fP is located itself in the CMake builtin |
| module directory, then first the CMake builtin module directory is searched and |
| \fBCMAKE_MODULE_PATH\fP afterwards. See also policy \fBCMP0017\fP\&. |
| .sp |
| See the \fBcmake_policy()\fP command documentation for discussion of the |
| \fBNO_POLICY_SCOPE\fP 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 unless marked with \fBEXCLUDE_FROM_ALL\fP\&. |
| 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 \fBEXCLUDE_FROM_ALL\fP |
| Specify that the file is excluded from a full installation and only |
| installed as part of a component\-specific installation |
| .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>] |
| [PERMISSIONS permissions...] |
| [CONFIGURATIONS [Debug|Release|...]] |
| [COMPONENT <component>] |
| [OPTIONAL] [EXCLUDE_FROM_ALL] |
| [NAMELINK_ONLY|NAMELINK_SKIP] |
| ] [...] |
| [INCLUDES DESTINATION [<dir> ...]] |
| ) |
| .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 treated as \fBARCHIVE\fP targets, |
| except that those marked with the \fBFRAMEWORK\fP property are treated |
| as \fBFRAMEWORK\fP targets on OS X. |
| 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). |
| .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 |
| 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\&. |
| This is independent of the rest of the argument groups and does |
| not actually install anything. |
| .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] [EXCLUDE_FROM_ALL]) |
| .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. |
| .sp |
| The install destination given to the files 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 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>] [EXCLUDE_FROM_ALL] |
| [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. |
| .sp |
| The list of \fBdirs...\fP given to \fBDIRECTORY\fP and the install destination |
| given to the directory install \fBDESTINATION\fP may use "generator expressions" |
| with the syntax \fB$<...>\fP\&. See the \fBcmake\-generator\-expressions(7)\fP |
| manual for available expressions. |
| .SS Custom Installation Logic |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| install([[SCRIPT <file>] [CODE <code>]] |
| [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...]) |
| .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]| |
| [EXPORT_ANDROID_MK <name>.mk]] |
| [PERMISSIONS permissions...] |
| [CONFIGURATIONS [Debug|Release|...]] |
| [EXPORT_LINK_INTERFACE_LIBRARIES] |
| [COMPONENT <component>] |
| [EXCLUDE_FROM_ALL]) |
| .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 |
| In additon to cmake language files, the \fBEXPORT_ANDROID_MK\fP option maybe |
| used to specifiy an export to the android ndk build system. The Android |
| NDK supports the use of prebuilt libraries, both static and shared. This |
| allows cmake to build the libraries of a project and make them available |
| to an ndk build system complete with transitive dependencies, include flags |
| and defines required to use the libraries. |
| .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) |
| install(EXPORT_ANDROID_MK myexp DESTINATION share/ndk\-modules) |
| .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 and |
| \fB<prefix>/lib/share/ndk\-modules/Android.mk\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 \fBCMP0015\fP\&. |
| .sp |
| Note that this command is rarely necessary. Library locations |
| returned by \fBfind_package()\fP and \fBfind_library()\fP are |
| absolute paths. Pass these absolute library file paths directly to the |
| \fBtarget_link_libraries()\fP 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(FILTER <list> <INCLUDE|EXCLUDE> REGEX <regular_expression>) |
| 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 |
| \fBLENGTH\fP will return a given list\(aqs length. |
| .sp |
| \fBGET\fP will return list of elements specified by indices from the list. |
| .sp |
| \fBAPPEND\fP will append elements to the list. |
| .sp |
| \fBFILTER\fP will include or remove items from the list that match the |
| mode\(aqs pattern. |
| In \fBREGEX\fP mode, items will be matched against the given regular expression. |
| For more information on regular expressions see also the \fBstring()\fP |
| command. |
| .sp |
| \fBFIND\fP will return the index of the element specified in the list or \-1 |
| if it wasn\(aqt found. |
| .sp |
| \fBINSERT\fP will insert elements to the list to the specified location. |
| .sp |
| \fBREMOVE_AT\fP and \fBREMOVE_ITEM\fP will remove items from the list. The |
| difference is that \fBREMOVE_ITEM\fP will remove the given items, while |
| \fBREMOVE_AT\fP will remove the items at the given indices. |
| .sp |
| \fBREMOVE_DUPLICATES\fP will remove duplicated items in the list. |
| .sp |
| \fBREVERSE\fP reverses the contents of the list in\-place. |
| .sp |
| \fBSORT\fP sorts the list in\-place alphabetically. |
| .sp |
| The list subcommands \fBAPPEND\fP, \fBINSERT\fP, \fBFILTER\fP, \fBREMOVE_AT\fP, |
| \fBREMOVE_ITEM\fP, \fBREMOVE_DUPLICATES\fP, \fBREVERSE\fP and \fBSORT\fP may create new |
| values for the list within the current CMake variable scope. Similar to the |
| \fBset()\fP 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 |
| \fBset()\fP with \fBPARENT_SCOPE\fP, \fBset()\fP with |
| \fBCACHE INTERNAL\fP, or some other means of value propagation. |
| .sp |
| NOTES: A list in cmake is a \fB;\fP separated group of strings. To create a |
| list the set command can be used. For example, \fBset(var a b c d e)\fP |
| creates a list with \fBa;b;c;d;e\fP, and \fBset(var "a b c d e")\fP 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 \fB<element index>\fP is 0 or greater, it |
| is indexed from the beginning of the list, with 0 representing the |
| first list element. If \fB<element index>\fP 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. \fBEXCLUDE\fP |
| option can be used to provide a list of entries to be excluded. |
| \fBINCLUDE_INTERNALS\fP 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 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 \fBCLEAR\fP is the first argument advanced |
| variables are changed back to unadvanced. If \fBFORCE\fP is the first |
| argument, then the variable is made advanced. If neither \fBFORCE\fP nor |
| \fBCLEAR\fP 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 |
| \fBEXPR\fP evaluates mathematical expression and returns result in the |
| output variable. Example mathematical expression is \fB5 * (10 + 13)\fP\&. |
| Supported operators are \fB+\fP, \fB\-\fP, \fB*\fP, \fB/\fP, \fB%\fP, \fB|\fP, \fB&\fP, |
| \fB^\fP, \fB~\fP, \fB<<\fP, \fB>>\fP, and \fB(...)\fP\&. 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 \fB<mode>\fP 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 \fBON\fP or \fBOFF\fP\&. If no |
| initial value is provided, \fBOFF\fP is used. |
| .sp |
| If you have options that depend on the values of other options, see |
| the module help for \fBCMakeDependentOption\fP\&. |
| .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 \fBDestName\fP 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 |
| \fBSourceLists\fP\&. The .h files will be added to the library using the |
| \fBHeadersDestNamesource\fP list. The .cxx files will be added to the |
| library using the \fBSourcesDestNamesource\fP list. |
| .SS remove_definitions |
| .sp |
| Removes \-D define flags added by \fBadd_definitions()\fP\&. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| remove_definitions(\-DFOO \-DBAR ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Removes flags (added by \fBadd_definitions()\fP) 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 \fBinclude()\fP or |
| \fBfind_package()\fP), 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 \fBCMakeLists.txt\fP, |
| 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 \fB<var>\fP\&. The |
| entire command line must be given in one "<args>" argument. |
| .sp |
| The \fBUNIX_COMMAND\fP mode separates arguments by unquoted whitespace. It |
| recognizes both single\-quote and double\-quote pairs. A backslash |
| escapes the next literal character (\fB\e"\fP is \fB"\fP); there are no special |
| escapes (\fB\en\fP is just \fBn\fP). |
| .sp |
| The \fBWINDOWS_COMMAND\fP 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 \fI\%Parsing C Command\-Line Arguments\fP for details. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| separate_arguments(<var>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Convert the value of \fB<var>\fP 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. |
| .sp |
| See the \fBcmake\-properties(7)\fP manual for a list of properties |
| in each scope. |
| .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). The previous state of the variable\(aqs value stays the |
| same in the current scope (e.g., if it was undefined before, it is still |
| undefined and if it had a value, it is still that value). |
| .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 \fBget_property()\fP or \fBget_target_property()\fP |
| command. |
| .sp |
| See Target Properties for the list of properties known to CMake. |
| .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. |
| There are two different signatures to create source groups. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| source_group(<name> [FILES <src>...] [REGULAR_EXPRESSION <regex>]) |
| source_group(TREE <root> [PREFIX <prefix>] [FILES <src>...]) |
| .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 \fBTREE\fP |
| CMake will automatically detect, from \fB<src>\fP files paths, source groups |
| it needs to create, to keep structure of source groups analogically to the |
| actual files and directories structure in the project. Paths of \fB<src>\fP |
| files will be cut to be relative to \fB<root>\fP\&. |
| .TP |
| .B \fBPREFIX\fP |
| Source group and files located directly in \fB<root>\fP path, will be placed |
| in \fB<prefix>\fP source groups. |
| .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 and \fB<prefix>\fP argument may contain backslashes |
| to specify subgroups: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| source_group(outer\e\einner ...) |
| source_group(TREE <root> PREFIX sources\e\einc ...) |
| .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. |
| .SS Search and Replace |
| .SS FIND |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(FIND <string> <substring> <output variable> [REVERSE]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Return the position where the given substring was found in |
| the supplied string. If the \fBREVERSE\fP flag was used, the command will |
| search for the position of the last occurrence of the specified |
| substring. If the substring is not found, a position of \-1 is returned. |
| .SS REPLACE |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(REPLACE <match_string> |
| <replace_string> <output variable> |
| <input> [<input>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Replace all occurrences of \fBmatch_string\fP in the input |
| with \fBreplace_string\fP and store the result in the output. |
| .SS Regular Expressions |
| .SS REGEX MATCH |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(REGEX MATCH <regular_expression> |
| <output variable> <input> [<input>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Match the regular expression once and store the match in the output variable. |
| All \fB<input>\fP arguments are concatenated before matching. |
| .SS REGEX MATCHALL |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(REGEX MATCHALL <regular_expression> |
| <output variable> <input> [<input>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Match the regular expression as many times as possible and store the matches |
| in the output variable as a list. |
| All \fB<input>\fP arguments are concatenated before matching. |
| .SS REGEX REPLACE |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(REGEX REPLACE <regular_expression> |
| <replace_expression> <output variable> |
| <input> [<input>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Match the regular expression as many times as possible and substitute the |
| replacement expression for the match in the output. |
| All \fB<input>\fP arguments are concatenated before matching. |
| .sp |
| The replace expression may refer to paren\-delimited subexpressions of the |
| match using \fB\e1\fP, \fB\e2\fP, ..., \fB\e9\fP\&. Note that two backslashes (\fB\e\e1\fP) |
| are required in CMake code to get a backslash through argument parsing. |
| .SS Regex Specification |
| .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. \fB|\fP |
| has lower precedence than concatenation. This means that the regular |
| expression \fB^ab+d$\fP matches \fBabbd\fP but not \fBababd\fP, and the regular |
| expression \fB^(ab|cd)$\fP matches \fBab\fP but not \fBabd\fP\&. |
| .SS Manipulation |
| .SS APPEND |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(APPEND <string variable> [<input>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Append all the input arguments to the string. |
| .SS CONCAT |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(CONCAT <output variable> [<input>...]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Concatenate all the input arguments together and store |
| the result in the named output variable. |
| .SS TOLOWER |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(TOLOWER <string1> <output variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Convert string to lower characters. |
| .SS TOUPPER |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(TOUPPER <string1> <output variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Convert string to upper characters. |
| .SS LENGTH |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(LENGTH <string> <output variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Store in an output variable a given string\(aqs length. |
| .SS SUBSTRING |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(SUBSTRING <string> <begin> <length> <output variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Store in an output variable a substring of a given string. If length is |
| \fB\-1\fP 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 |
| .SS STRIP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(STRIP <string> <output variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Store in an output variable a substring of a given string with leading and |
| trailing spaces removed. |
| .SS GENEX_STRIP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(GENEX_STRIP <input string> <output variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Strip any \fBgenerator expressions\fP |
| from the \fBinput string\fP and store the result in the \fBoutput variable\fP\&. |
| .SS Comparison |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(COMPARE LESS <string1> <string2> <output variable>) |
| string(COMPARE GREATER <string1> <string2> <output variable>) |
| string(COMPARE EQUAL <string1> <string2> <output variable>) |
| string(COMPARE NOTEQUAL <string1> <string2> <output variable>) |
| string(COMPARE LESS_EQUAL <string1> <string2> <output variable>) |
| string(COMPARE GREATER_EQUAL <string1> <string2> <output variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Compare the strings and store true or false in the output variable. |
| .SS Hashing |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(<HASH> <output variable> <input>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Compute a cryptographic hash of the input string. |
| The supported \fB<HASH>\fP algorithm names are: |
| .INDENT 0.0 |
| .TP |
| .B \fBMD5\fP |
| Message\-Digest Algorithm 5, RFC 1321. |
| .TP |
| .B \fBSHA1\fP |
| US Secure Hash Algorithm 1, RFC 3174. |
| .TP |
| .B \fBSHA224\fP |
| US Secure Hash Algorithms, RFC 4634. |
| .TP |
| .B \fBSHA256\fP |
| US Secure Hash Algorithms, RFC 4634. |
| .TP |
| .B \fBSHA384\fP |
| US Secure Hash Algorithms, RFC 4634. |
| .TP |
| .B \fBSHA512\fP |
| US Secure Hash Algorithms, RFC 4634. |
| .TP |
| .B \fBSHA3_224\fP |
| Keccak SHA\-3. |
| .TP |
| .B \fBSHA3_256\fP |
| Keccak SHA\-3. |
| .TP |
| .B \fBSHA3_384\fP |
| Keccak SHA\-3. |
| .TP |
| .B \fBSHA3_512\fP |
| Keccak SHA\-3. |
| .UNINDENT |
| .SS Generation |
| .SS ASCII |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(ASCII <number> [<number> ...] <output variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Convert all numbers into corresponding ASCII characters. |
| .SS CONFIGURE |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(CONFIGURE <string1> <output variable> |
| [@ONLY] [ESCAPE_QUOTES]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Transform a string like \fBconfigure_file()\fP transforms a file. |
| .SS RANDOM |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>] |
| [RANDOM_SEED <seed>] <output variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| 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 \fBRANDOM_SEED\fP is given, its value will be used to seed the |
| random number generator. |
| .SS TIMESTAMP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(TIMESTAMP <output variable> [<format string>] [UTC]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| 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 \fBUTC\fP flag requests the current date/time representation to |
| be in Coordinated Universal Time (UTC) rather than local time. |
| .sp |
| The optional \fB<format string>\fP may contain the following format |
| specifiers: |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| %% A literal percent sign (%). |
| %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). |
| %b Abbreviated month name (e.g. Oct). |
| %M The minute of the current hour (00\-59). |
| %s Seconds since midnight (UTC) 1\-Jan\-1970 (UNIX time). |
| %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) |
| %a Abbreviated weekday name (e.g. Fri). |
| %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 \fB<format string>\fP 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 |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(MAKE_C_IDENTIFIER <input string> <output variable>) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Write a string which can be used as an identifier in C. |
| .sp |
| \fBNOTE:\fP |
| .INDENT 0.0 |
| .INDENT 3.5 |
| If the \fBSOURCE_DATE_EPOCH\fP environment variable is set, |
| its value will be used instead of the current time. |
| See \fI\%https://reproducible\-builds.org/specs/source\-date\-epoch/\fP for details. |
| .UNINDENT |
| .UNINDENT |
| .SS UUID |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| string(UUID <output variable> NAMESPACE <namespace> NAME <name> |
| TYPE <MD5|SHA1> [UPPER]) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Create a univerally unique identifier (aka GUID) as per RFC4122 |
| based on the hash of the combined values of \fB<namespace>\fP |
| (which itself has to be a valid UUID) and \fB<name>\fP\&. |
| 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. |
| .sp |
| On Visual Studio Generators for VS 2010 and above, library files |
| ending in \fB\&.targets\fP will be treated as MSBuild targets files and |
| imported into generated project files. This is not supported by other |
| generators. |
| .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. |
| .sp |
| Link flags specified here are inserted into the link command in the same |
| place as the link libraries. This might not be correct, depending on |
| the linker. Use the \fBLINK_FLAGS\fP target property to add link |
| flags explicitly. The flags will then be placed at the toolchain\-defined |
| flag position in the link command. |
| .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>]] |
| [<LANG>_STANDARD <std>] |
| [<LANG>_STANDARD_REQUIRED <bool>] |
| [<LANG>_EXTENSIONS <bool>] |
| ) |
| .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. |
| .TP |
| .B \fB<LANG>_STANDARD <std>\fP |
| Specify the \fBC_STANDARD\fP, \fBCXX_STANDARD\fP, |
| or \fBCUDA_STANDARD\fP target property of the generated project. |
| .TP |
| .B \fB<LANG>_STANDARD_REQUIRED <bool>\fP |
| Specify the \fBC_STANDARD_REQUIRED\fP, |
| \fBCXX_STANDARD_REQUIRED\fP, or \fBCUDA_STANDARD_REQUIRED\fP |
| target property of the generated project. |
| .TP |
| .B \fB<LANG>_EXTENSIONS <bool>\fP |
| Specify the \fBC_EXTENSIONS\fP, \fBCXX_EXTENSIONS\fP, |
| or \fBCUDA_EXTENSIONS\fP target property of the generated project. |
| .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 |
| If set, the following variables are passed in to the generated |
| try_compile CMakeLists.txt to initialize compile target properties with |
| default values: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCMAKE_ENABLE_EXPORTS\fP |
| .IP \(bu 2 |
| \fBCMAKE_LINK_SEARCH_START_STATIC\fP |
| .IP \(bu 2 |
| \fBCMAKE_LINK_SEARCH_END_STATIC\fP |
| .IP \(bu 2 |
| \fBCMAKE_POSITION_INDEPENDENT_CODE\fP |
| .UNINDENT |
| .sp |
| If \fBCMP0056\fP is set to \fBNEW\fP, then |
| \fBCMAKE_EXE_LINKER_FLAGS\fP is passed in as well. |
| .sp |
| The current setting of \fBCMP0065\fP is set in the generated project. |
| .sp |
| Set the \fBCMAKE_TRY_COMPILE_CONFIGURATION\fP variable to choose |
| a build configuration. |
| .sp |
| Set the \fBCMAKE_TRY_COMPILE_TARGET_TYPE\fP variable to specify |
| the type of target used for the source file signature. |
| .sp |
| Set the \fBCMAKE_TRY_COMPILE_PLATFORM_VARIABLES\fP variable to specify |
| variables that must be propagated into the test project. This variable is |
| meant for use only in toolchain files. |
| .sp |
| If \fBCMP0067\fP is set to \fBNEW\fP, or any of the \fB<LANG>_STANDARD\fP, |
| \fB<LANG>_STANDARD_REQUIRED\fP, or \fB<LANG>_EXTENSIONS\fP options are used, |
| then the language standard variables are honored: |
| .INDENT 0.0 |
| .IP \(bu 2 |
| \fBCMAKE_C_STANDARD\fP |
| .IP \(bu 2 |
| \fBCMAKE_C_STANDARD_REQUIRED\fP |
| .IP \(bu 2 |
| \fBCMAKE_C_EXTENSIONS\fP |
| .IP \(bu 2 |
| \fBCMAKE_CXX_STANDARD\fP |
| .IP \(bu 2 |
| \fBCMAKE_CXX_STANDARD_REQUIRED\fP |
| .IP \(bu 2 |
| \fBCMAKE_CXX_EXTENSIONS\fP |
| .IP \(bu 2 |
| \fBCMAKE_CUDA_STANDARD\fP |
| .IP \(bu 2 |
| \fBCMAKE_CUDA_STANDARD_REQUIRED\fP |
| .IP \(bu 2 |
| \fBCMAKE_CUDA_EXTENSIONS\fP |
| .UNINDENT |
| .sp |
| Their values are used to set the corresponding target properties in |
| the generated project (unless overridden by an explicit option). |
| .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 |
| \fBCACHE\fP is present then the variable is removed from the cache instead |
| of the current scope. |
| .sp |
| If \fBPARENT_SCOPE\fP is present then the variable is removed from the scope |
| above the current scope. See the same option in the \fBset()\fP command |
| for further details. |
| .sp |
| \fB<variable>\fP 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 \fBendwhile()\fP are recorded |
| without being invoked. Once the \fBendwhile()\fP 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 \fBif()\fP 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 \fB${CMAKE_SYSTEM}\fP and \fB${CMAKE_CXX_COMPILER}\fP 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 |
| \fBCMAKE_SYSTEM\fP and |
| \fBCMAKE_CXX_COMPILER\fP variables. |
| .SS exec_program |
| .sp |
| Deprecated. Use the \fBexecute_process()\fP 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 \fBARGS\fP 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 \fBOUTPUT_VARIABLE\fP specifies a |
| variable in which to store the output. To capture the return value of |
| the execution, provide a \fBRETURN_VALUE\fP\&. If \fBOUTPUT_VARIABLE\fP 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 \fBinstall(EXPORT)\fP command to help export targets from an |
| installation tree and the \fBexport()\fP 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 |
| \fBLINK_INTERFACE_LIBRARIES\fP 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 \fB<file>\fP 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 \fBAPPEND\fP option is |
| specified, the SET commands will be appended to the given file instead |
| of replacing it. |
| .SS install_files |
| .sp |
| Deprecated. Use the \fBinstall(FILES)\fP command instead. |
| .sp |
| This command has been superceded by the \fBinstall()\fP command. It is |
| provided for compatibility with older CMake code. The \fBFILES\fP form is |
| directly replaced by the \fBFILES\fP form of the \fBinstall()\fP |
| command. The regexp form can be expressed more clearly using the \fBGLOB\fP |
| form of the \fBfile()\fP 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 \fBFILES\fP keyword will be installed explicitly |
| from the names given. Full paths are allowed in this form. |
| .sp |
| The directory \fB<dir>\fP is relative to the installation prefix, which is |
| stored in the variable \fBCMAKE_INSTALL_PREFIX\fP\&. |
| .SS install_programs |
| .sp |
| Deprecated. Use the \fBinstall(PROGRAMS)\fP command instead. |
| .sp |
| This command has been superceded by the \fBinstall()\fP command. It is |
| provided for compatibility with older CMake code. The \fBFILES\fP form is |
| directly replaced by the \fBPROGRAMS\fP form of the \fBinstall()\fP |
| command. The regexp form can be expressed more clearly using the \fBGLOB\fP |
| form of the \fBfile()\fP 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 \fBFILES\fP 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 \fBTARGETS\fP form of the |
| \fBinstall()\fP command to create installation rules for targets built |
| by cmake. |
| .sp |
| The directory \fB<dir>\fP is relative to the installation prefix, which is |
| stored in the variable \fBCMAKE_INSTALL_PREFIX\fP\&. |
| .SS install_targets |
| .sp |
| Deprecated. Use the \fBinstall(TARGETS)\fP command instead. |
| .sp |
| This command has been superceded by the \fBinstall()\fP 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 \fB<dir>\fP is relative to the installation prefix, which is |
| stored in the variable \fBCMAKE_INSTALL_PREFIX\fP\&. If |
| \fBRUNTIME_DIRECTORY\fP is specified, then on systems with special runtime |
| files (Windows DLL), the files will be copied to that directory. |
| .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, |
| \fBtry_compile()\fP 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 make_directory |
| .sp |
| Deprecated. Use the \fBfile(MAKE_DIRECTORY)\fP 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 \fBlist(REMOVE_ITEM)\fP command instead. |
| .INDENT 0.0 |
| .INDENT 3.5 |
| .sp |
| .nf |
| .ft C |
| remove(VAR VALUE VALUE ...) |
| .ft P |
| .fi |
| .UNINDENT |
| .UNINDENT |
| .sp |
| Removes \fBVALUE\fP from the variable \fBVAR\fP\&. This is typically used to |
| remove entries from a vector (e.g. semicolon separated list). \fBVALUE\fP |
| 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 \fBadd_subdirectory()\fP 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 \fBadd_subdirectory()\fP |
| command should be used instead of \fBsubdirs\fP although \fBsubdirs\fP will still |
| work. This will cause any CMakeLists.txt files in the sub directories |
| to be processed by CMake. Any directories after the \fBPREORDER\fP flag are |
| traversed first by makefile builds, the \fBPREORDER\fP flag has no effect on |
| IDE projects. Any directories after the \fBEXCLUDE_FROM_ALL\fP 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 \fBpath_to_source\fP 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 \fButility_source()\fP |
| 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 \fBif()\fP 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 (\fBTEST_VARIABLE\fP) is the name of the variable to be |
| tested, if that variable is false nothing else is done. If |
| \fBTEST_VARIABLE\fP is true, then the next argument (\fBRESULT_VARIABLE\fP) |
| 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 \fBfile(WRITE)\fP 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 \fBAPPEND\fP is specified, then the |
| message will be appended. |
| .sp |
| NOTE 1: \fBfile(WRITE)\fP and \fBfile(APPEND)\fP do exactly |
| the same as this one but add some more functionality. |
| .sp |
| NOTE 2: When using \fBwrite_file\fP the produced file cannot be used as an |
| input to CMake (CONFIGURE_FILE, source file ...) because it will lead |
| to an infinite loop. Use \fBconfigure_file()\fP 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>] |
| [CAPTURE_CMAKE_ERROR <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 \fBBuild.xml\fP for append to results previously submitted to a |
| dashboard server since the last \fBctest_start()\fP call. |
| Append semantics are defined by the dashboard server in use. |
| This does \fInot\fP cause results to be appended to a \fB\&.xml\fP file |
| produced by a previous call to this command. |
| .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 \fBCAPTURE_CMAKE_ERROR <result\-var>\fP |
| Store in the \fB<result\-var>\fP variable \-1 if there are any errors running |
| the command and prevent ctest from returning non\-zero if an error occurs. |
| .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] |
| [CAPTURE_CMAKE_ERROR <result\-var>]) |
| .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 \fBConfigure.xml\fP for append to results previously submitted to a |
| dashboard server since the last \fBctest_start()\fP call. |
| Append semantics are defined by the dashboard server in use. |
| This does \fInot\fP cause results to be appended to a \fB\&.xml\fP file |
| produced by a previous call to this command. |
| .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 \fBCAPTURE_CMAKE_ERROR <result\-var>\fP |
| Store in the \fB<result\-var>\fP variable \-1 if there are any errors running |
| the command and prevent ctest from returning non\-zero if an error occurs. |
| .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>] |
| [CAPTURE_CMAKE_ERROR <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 \fBCoverage.xml\fP for append to results previously submitted to a |
| dashboard server since the last \fBctest_start()\fP call. |
| Append semantics are defined by the dashboard server in use. |
| This does \fInot\fP cause results to be appended to a \fB\&.xml\fP file |
| produced by a previous call to this command. |
| .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 \fBCAPTURE_CMAKE_ERROR <result\-var>\fP |
| Store in the \fB<result\-var>\fP variable \-1 if there are any errors running |
| the command and prevent ctest from returning non\-zero if an error occurs. |
| .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>] |
| [TEST_LOAD <threshold>] |
| [SCHEDULE_RANDOM <ON|OFF>] |
| [STOP_TIME <time\-of\-day>] |
| [RETURN_VALUE <result\-var>] |
| [DEFECT_COUNT <defect\-count\-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 |
| Most options are the same as those for the \fBctest_test()\fP command. |
| .sp |
| The options unique to this command are: |
| .INDENT 0.0 |
| .TP |
| .B \fBDEFECT_COUNT <defect\-count\-var>\fP |
| Store in the \fB<defect\-count\-var>\fP the number of defects found. |
| .UNINDENT |
| .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. |
| .sp |
| By default, invoking \fBctest(1)\fP without a script will read custom |
| files from the binary 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 \fBNEW_PROCESS\fP is specified then each |
| script will be run in a separate process.If \fBRETURN_VALUE\fP is specified |
| the return value of the last script run will be put into \fBvar\fP\&. |
| .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 \fBQUIET\fP 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>] |
| [RETRY_COUNT <count>] |
| [RETRY_DELAY <delay>] |
| [QUIET]) |
| .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. |
| .sp |
| This signature accepts the \fBRETRY_COUNT\fP, \fBRETRY_DELAY\fP, and \fBQUIET\fP |
| options as described above. |
| .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>] |
| [TEST_LOAD <threshold>] |
| [SCHEDULE_RANDOM <ON|OFF>] |
| [STOP_TIME <time\-of\-day>] |
| [RETURN_VALUE <result\-var>] |
| [CAPTURE_CMAKE_ERROR <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 \fBTest.xml\fP for append to results previously submitted to a |
| dashboard server since the last \fBctest_start()\fP call. |
| Append semantics are defined by the dashboard server in use. |
| This does \fInot\fP cause results to be appended to a \fB\&.xml\fP file |
| produced by a previous call to this command. |
| .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 across 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 \fBTEST_LOAD <threshold>\fP |
| While running tests in parallel, try not to start tests when they |
| may cause the CPU load to pass above a given threshold. If not |
| specified the \fBCTEST_TEST_LOAD\fP variable will be checked, |
| and then the \fB\-\-test\-load\fP command\-line argument to \fBctest(1)\fP\&. |
| See also the \fBTestLoad\fP setting in the CTest Test Step\&. |
| .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 \fBCAPTURE_CMAKE_ERROR <result\-var>\fP |
| Store in the \fB<result\-var>\fP variable \-1 if there are any errors running |
| the command and prevent ctest from returning non\-zero if an error occurs. |
| .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 |
| .sp |
| See also the \fBCTEST_CUSTOM_MAXIMUM_PASSED_TEST_OUTPUT_SIZE\fP |
| and \fBCTEST_CUSTOM_MAXIMUM_FAILED_TEST_OUTPUT_SIZE\fP variables. |
| .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 |
| .sp |
| The update always follows the version control branch currently checked |
| out in the source directory. See the CTest Update Step |
| documentation for more information. |
| .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] [CAPTURE_CMAKE_ERROR <result\-var>]) |
| .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. |
| .TP |
| .B \fBCAPTURE_CMAKE_ERROR <result\-var>\fP |
| Store in the \fB<result\-var>\fP variable \-1 if there are any errors running |
| the command and prevent ctest from returning non\-zero if an error occurs. |
| .UNINDENT |
| .SH COPYRIGHT |
| 2000-2017 Kitware, Inc. and Contributors |
| .\" Generated by docutils manpage writer. |
| . |