1cmakecommands(1) General Commands Manual cmakecommands(1)
2
6 cmakecommands - Reference of available CMake commands.
7
10 add_compile_options
11 Adds options to the compilation of source files.
12 add_compile_options(<option> ...)
14 Adds options to the compiler command line for sources in the
16 current directory and below. This command can be used to add
17 any options, but alternative commands exist to add preprocessor
18 definitions or include directories. See documentation of the
19 directory and target COMPILE_OPTIONS properties for details.
20 Arguments to add_compile_options may use "generator expressions"
21 with the syntax "$<...>". Generator expressions are evaluated
22 during build system generation to produce information specific
23 to each build configuration. Valid expressions are:
24 $<0:...> = empty string (ignores "...")
27 $<1:...> = content of "..."
28 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
29 $<CONFIGURATION> = configuration name
30 $<BOOL:...> = '1' if the '...' is true, else '0'
31 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
32 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
33 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
34 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
35 $<JOIN:list,...> = joins the list with the content of "..."
36 $<TARGET_NAME:...> = Marks ... as being the name of a target. This is required if exporting targets to multiple dependent export sets. The '...' must be a literal name of a target- it may not contain generator expressions.
37 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
38 $<BUILD_INTERFACE:...> = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
39 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
40 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
41 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
42 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
43 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
44 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
45 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
46 $<C_COMPILER_VERSION> = The version of the C compiler used.
47 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
48 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
49 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
50 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
51 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
52 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
53 where "tgt" is the name of a target. Target file expressions
55 produce a full path, but _DIR and _NAME versions can produce the
56 directory and file name components:
57 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
60 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
61 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
62 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
67 Note that tgt is not added as a dependency of the target this
69 expression is evaluated on.
70 $<TARGET_POLICY:pol> = '1' if the policy was NEW when the 'head' target was created, else '0'. If the policy was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies.
73 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
74 Boolean expressions:
76 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
79 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
80 $<NOT:?> = '0' if '?' is '1', else '1'
81 where '?' is always either '0' or '1'.
83 Expressions with an implicit 'this' target:
86 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
89 add_custom_command
92 Add a custom build rule to the generated build system.
93 There are two main signatures for add_custom_command The first
95 signature is for adding a custom command to produce an output.
96 add_custom_command(OUTPUT output1 [output2 ...]
99 COMMAND command1 [ARGS] [args1...]
100 [COMMAND command2 [ARGS] [args2...] ...]
101 [MAIN_DEPENDENCY depend]
102 [DEPENDS [depends...]]
103 [IMPLICIT_DEPENDS <lang1> depend1
104 [<lang2> depend2] ...]
105 [WORKING_DIRECTORY dir]
106 [COMMENT comment] [VERBATIM] [APPEND])
107 This defines a command to generate specified OUTPUT file(s). A
109 target created in the same directory (CMakeLists.txt file) that
110 specifies any output of the custom command as a source file is
111 given a rule to generate the file using the command at build
112 time. Do not list the output in more than one independent tar‐
113 get that may build in parallel or the two instances of the rule
114 may conflict (instead use add_custom_target to drive the command
115 and make the other targets depend on that one). If an output
116 name is a relative path it will be interpreted relative to the
117 build tree directory corresponding to the current source direc‐
118 tory. Note that MAIN_DEPENDENCY is completely optional and is
119 used as a suggestion to visual studio about where to hang the
120 custom command. In makefile terms this creates a new target in
121 the following form:
122 OUTPUT: MAIN_DEPENDENCY DEPENDS
125 COMMAND
126 If more than one command is specified they will be executed in
128 order. The optional ARGS argument is for backward compatibility
129 and will be ignored.
130 The second signature adds a custom command to a target such as a
133 library or executable. This is useful for performing an opera‐
134 tion before or after building the target. The command becomes
135 part of the target and will only execute when the target itself
136 is built. If the target is already built, the command will not
137 execute.
138 add_custom_command(TARGET target
141 PRE_BUILD | PRE_LINK | POST_BUILD
142 COMMAND command1 [ARGS] [args1...]
143 [COMMAND command2 [ARGS] [args2...] ...]
144 [WORKING_DIRECTORY dir]
145 [COMMENT comment] [VERBATIM])
146 This defines a new command that will be associated with building
148 the specified target. When the command will happen is determined
149 by which of the following is specified:
150 PRE_BUILD - run before all other dependencies
153 PRE_LINK - run after other dependencies
154 POST_BUILD - run after the target has been built
155 Note that the PRE_BUILD option is only supported on Visual Stu‐
157 dio 7 or later. For all other generators PRE_BUILD will be
158 treated as PRE_LINK.
159 If WORKING_DIRECTORY is specified the command will be executed
162 in the directory given. If it is a relative path it will be
163 interpreted relative to the build tree directory corresponding
164 to the current source directory. If COMMENT is set, the value
165 will be displayed as a message before the commands are executed
166 at build time. If APPEND is specified the COMMAND and DEPENDS
167 option values are appended to the custom command for the first
168 output specified. There must have already been a previous call
169 to this command with the same output. The COMMENT, WORK‐
170 ING_DIRECTORY, and MAIN_DEPENDENCY options are currently ignored
171 when APPEND is given, but may be used in the future.
172 If VERBATIM is given then all arguments to the commands will be
175 escaped properly for the build tool so that the invoked command
176 receives each argument unchanged. Note that one level of
177 escapes is still used by the CMake language processor before
178 add_custom_command even sees the arguments. Use of VERBATIM is
179 recommended as it enables correct behavior. When VERBATIM is not
180 given the behavior is platform specific because there is no pro‐
181 tection of tool-specific special characters.
182 If the output of the custom command is not actually created as a
185 file on disk it should be marked as SYMBOLIC with
186 SET_SOURCE_FILES_PROPERTIES.
187 The IMPLICIT_DEPENDS option requests scanning of implicit depen‐
190 dencies of an input file. The language given specifies the pro‐
191 gramming language whose corresponding dependency scanner should
192 be used. Currently only C and CXX language scanners are sup‐
193 ported. The language has to be specified for every file in the
194 IMPLICIT_DEPENDS list. Dependencies discovered from the scanning
195 are added to those of the custom command at build time. Note
196 that the IMPLICIT_DEPENDS option is currently supported only for
197 Makefile generators and will be ignored by other generators.
198 If COMMAND specifies an executable target (created by ADD_EXE‐
201 CUTABLE) it will automatically be replaced by the location of
202 the executable created at build time. Additionally a tar‐
203 get-level dependency will be added so that the executable target
204 will be built before any target using this custom command. How‐
205 ever this does NOT add a file-level dependency that would cause
206 the custom command to re-run whenever the executable is recom‐
207 piled.
208 Arguments to COMMAND may use "generator expressions" with the
211 syntax "$<...>". Generator expressions are evaluated during
212 build system generation to produce information specific to each
213 build configuration. Valid expressions are:
214 $<0:...> = empty string (ignores "...")
217 $<1:...> = content of "..."
218 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
219 $<CONFIGURATION> = configuration name
220 $<BOOL:...> = '1' if the '...' is true, else '0'
221 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
222 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
223 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
224 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
225 $<JOIN:list,...> = joins the list with the content of "..."
226 $<TARGET_NAME:...> = Marks ... as being the name of a target. This is required if exporting targets to multiple dependent export sets. The '...' must be a literal name of a target- it may not contain generator expressions.
227 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
228 $<BUILD_INTERFACE:...> = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
229 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
230 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
231 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
232 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
233 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
234 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
235 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
236 $<C_COMPILER_VERSION> = The version of the C compiler used.
237 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
238 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
239 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
240 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
241 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
242 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
243 where "tgt" is the name of a target. Target file expressions
245 produce a full path, but _DIR and _NAME versions can produce the
246 directory and file name components:
247 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
250 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
251 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
252 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
257 Note that tgt is not added as a dependency of the target this
259 expression is evaluated on.
260 $<TARGET_POLICY:pol> = '1' if the policy was NEW when the 'head' target was created, else '0'. If the policy was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies.
263 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
264 Boolean expressions:
266 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
269 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
270 $<NOT:?> = '0' if '?' is '1', else '1'
271 where '?' is always either '0' or '1'.
273 Expressions with an implicit 'this' target:
276 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
279 References to target names in generator expressions imply tar‐
281 get-level dependencies, but NOT file-level dependencies. List
282 target names with the DEPENDS option to add file dependencies.
283 The DEPENDS option specifies files on which the command depends.
286 If any dependency is an OUTPUT of another custom command in the
287 same directory (CMakeLists.txt file) CMake automatically brings
288 the other custom command into the target in which this command
289 is built. If DEPENDS is not specified the command will run
290 whenever the OUTPUT is missing; if the command does not actually
291 create the OUTPUT then the rule will always run. If DEPENDS
292 specifies any target (created by an ADD_* command) a tar‐
293 get-level dependency is created to make sure the target is built
294 before any target using this custom command. Additionally, if
295 the target is an executable or library a file-level dependency
296 is created to cause the custom command to re-run whenever the
297 target is recompiled.
298 add_custom_target
302 Add a target with no output so it will always be built.
303 add_custom_target(Name [ALL] [command1 [args1...]]
305 [COMMAND command2 [args2...] ...]
306 [DEPENDS depend depend depend ... ]
307 [WORKING_DIRECTORY dir]
308 [COMMENT comment] [VERBATIM]
309 [SOURCES src1 [src2...]])
310 Adds a target with the given name that executes the given com‐
312 mands. The target has no output file and is ALWAYS CONSIDERED
313 OUT OF DATE even if the commands try to create a file with the
314 name of the target. Use ADD_CUSTOM_COMMAND to generate a file
315 with dependencies. By default nothing depends on the custom tar‐
316 get. Use ADD_DEPENDENCIES to add dependencies to or from other
317 targets. If the ALL option is specified it indicates that this
318 target should be added to the default build target so that it
319 will be run every time (the command cannot be called ALL). The
320 command and arguments are optional and if not specified an empty
321 target will be created. If WORKING_DIRECTORY is set, then the
322 command will be run in that directory. If it is a relative path
323 it will be interpreted relative to the build tree directory cor‐
324 responding to the current source directory. If COMMENT is set,
325 the value will be displayed as a message before the commands are
326 executed at build time. Dependencies listed with the DEPENDS
327 argument may reference files and outputs of custom commands cre‐
328 ated with add_custom_command() in the same directory (CMake‐
329 Lists.txt file).
330 If VERBATIM is given then all arguments to the commands will be
333 escaped properly for the build tool so that the invoked command
334 receives each argument unchanged. Note that one level of
335 escapes is still used by the CMake language processor before
336 add_custom_target even sees the arguments. Use of VERBATIM is
337 recommended as it enables correct behavior. When VERBATIM is not
338 given the behavior is platform specific because there is no pro‐
339 tection of tool-specific special characters.
340 The SOURCES option specifies additional source files to be
343 included in the custom target. Specified source files will be
344 added to IDE project files for convenience in editing even if
345 they have not build rules.
346 add_definitions
349 Adds -D define flags to the compilation of source files.
350 add_definitions(-DFOO -DBAR ...)
352 Adds flags to the compiler command line for sources in the cur‐
354 rent directory and below. This command can be used to add any
355 flags, but it was originally intended to add preprocessor defi‐
356 nitions. Flags beginning in -D or /D that look like preproces‐
357 sor definitions are automatically added to the COMPILE_DEFINI‐
358 TIONS property for the current directory. Definitions with
359 non-trivial values may be left in the set of flags instead of
360 being converted for reasons of backwards compatibility. See
361 documentation of the directory, target, and source file COM‐
362 PILE_DEFINITIONS properties for details on adding preprocessor
363 definitions to specific scopes and configurations.
364 add_dependencies
367 Add a dependency between top-level targets.
368 add_dependencies(target-name depend-target1
370 depend-target2 ...)
371 Make a top-level target depend on other top-level targets. A
373 top-level target is one created by ADD_EXECUTABLE, ADD_LIBRARY,
374 or ADD_CUSTOM_TARGET. Adding dependencies with this command can
375 be used to make sure one target is built before another target.
376 Dependencies added to an IMPORTED target are followed transi‐
377 tively in its place since the target itself does not build. See
378 the DEPENDS option of ADD_CUSTOM_TARGET and ADD_CUSTOM_COMMAND
379 for adding file-level dependencies in custom rules. See the
380 OBJECT_DEPENDS option in SET_SOURCE_FILES_PROPERTIES to add
381 file-level dependencies to object files.
382 add_executable
385 Add an executable to the project using the specified source
386 files.
387 add_executable(<name> [WIN32] [MACOSX_BUNDLE]
389 [EXCLUDE_FROM_ALL]
390 source1 source2 ... sourceN)
391 Adds an executable target called <name> to be built from the
393 source files listed in the command invocation. The <name> cor‐
394 responds to the logical target name and must be globally unique
395 within a project. The actual file name of the executable built
396 is constructed based on conventions of the native platform (such
397 as <name>.exe or just <name>).
398 By default the executable file will be created in the build tree
401 directory corresponding to the source tree directory in which
402 the command was invoked. See documentation of the RUNTIME_OUT‐
403 PUT_DIRECTORY target property to change this location. See doc‐
404 umentation of the OUTPUT_NAME target property to change the
405 <name> part of the final file name.
406 If WIN32 is given the property WIN32_EXECUTABLE will be set on
409 the target created. See documentation of that target property
410 for details.
411 If MACOSX_BUNDLE is given the corresponding property will be set
414 on the created target. See documentation of the MACOSX_BUNDLE
415 target property for details.
416 If EXCLUDE_FROM_ALL is given the corresponding property will be
419 set on the created target. See documentation of the
420 EXCLUDE_FROM_ALL target property for details.
421 The add_executable command can also create IMPORTED executable
424 targets using this signature:
425 add_executable(<name> IMPORTED [GLOBAL])
428 An IMPORTED executable target references an executable file
430 located outside the project. No rules are generated to build
431 it. The target name has scope in the directory in which it is
432 created and below, but the GLOBAL option extends visibility. It
433 may be referenced like any target built within the project.
434 IMPORTED executables are useful for convenient reference from
435 commands like add_custom_command. Details about the imported
436 executable are specified by setting properties whose names begin
437 in "IMPORTED_". The most important such property is
438 IMPORTED_LOCATION (and its per-configuration version
439 IMPORTED_LOCATION_<CONFIG>) which specifies the location of the
440 main executable file on disk. See documentation of the
441 IMPORTED_* properties for more information.
442 The signature
445 add_executable(<name> ALIAS <target>)
448 creates an alias, such that <name> can be used to refer to <tar‐
450 get> in subsequent commands. The <name> does not appear in the
451 generated buildsystem as a make target. The <target> may not be
452 an IMPORTED target or an ALIAS. Alias targets can be used as
453 linkable targets, targets to read properties from, executables
454 for custom commands and custom targets. They can also be tested
455 for existance with the regular if(TARGET) subcommand. The
456 <name> may not be used to modify properties of <target>, that
457 is, it may not be used as the operand of set_property, set_tar‐
458 get_properties, target_link_libraries etc. An ALIAS target may
459 not be installed of exported.
460 add_library
463 Add a library to the project using the specified source files.
464 add_library(<name> [STATIC | SHARED | MODULE]
466 [EXCLUDE_FROM_ALL]
467 source1 source2 ... sourceN)
468 Adds a library target called <name> to be built from the source
470 files listed in the command invocation. The <name> corresponds
471 to the logical target name and must be globally unique within a
472 project. The actual file name of the library built is con‐
473 structed based on conventions of the native platform (such as
474 lib<name>.a or <name>.lib).
475 STATIC, SHARED, or MODULE may be given to specify the type of
478 library to be created. STATIC libraries are archives of object
479 files for use when linking other targets. SHARED libraries are
480 linked dynamically and loaded at runtime. MODULE libraries are
481 plugins that are not linked into other targets but may be loaded
482 dynamically at runtime using dlopen-like functionality. If no
483 type is given explicitly the type is STATIC or SHARED based on
484 whether the current value of the variable BUILD_SHARED_LIBS is
485 true. For SHARED and MODULE libraries the POSITION_INDEPEN‐
486 DENT_CODE target property is set to TRUE automatically.
487 By default the library file will be created in the build tree
490 directory corresponding to the source tree directory in which
491 the command was invoked. See documentation of the ARCHIVE_OUT‐
492 PUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUT‐
493 PUT_DIRECTORY target properties to change this location. See
494 documentation of the OUTPUT_NAME target property to change the
495 <name> part of the final file name.
496 If EXCLUDE_FROM_ALL is given the corresponding property will be
499 set on the created target. See documentation of the
500 EXCLUDE_FROM_ALL target property for details.
501 The add_library command can also create IMPORTED library targets
504 using this signature:
505 add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED
508 [GLOBAL])
509 An IMPORTED library target references a library file located
511 outside the project. No rules are generated to build it. The
512 target name has scope in the directory in which it is created
513 and below, but the GLOBAL option extends visibility. It may be
514 referenced like any target built within the project. IMPORTED
515 libraries are useful for convenient reference from commands like
516 target_link_libraries. Details about the imported library are
517 specified by setting properties whose names begin in
518 "IMPORTED_". The most important such property is IMPORTED_LOCA‐
519 TION (and its per-configuration version IMPORTED_LOCATION_<CON‐
520 FIG>) which specifies the location of the main library file on
521 disk. See documentation of the IMPORTED_* properties for more
522 information.
523 The signature
526 add_library(<name> OBJECT <src>...)
529 creates a special "object library" target. An object library
531 compiles source files but does not archive or link their object
532 files into a library. Instead other targets created by
533 add_library or add_executable may reference the objects using an
534 expression of the form $<TARGET_OBJECTS:objlib> as a source,
535 where "objlib" is the object library name. For example:
536 add_library(... $<TARGET_OBJECTS:objlib> ...)
539 add_executable(... $<TARGET_OBJECTS:objlib> ...)
540 will include objlib's object files in a library and an exe‐
542 cutable along with those compiled from their own sources.
543 Object libraries may contain only sources (and headers) that
544 compile to object files. They may contain custom commands gen‐
545 erating such sources, but not PRE_BUILD, PRE_LINK, or POST_BUILD
546 commands. Object libraries cannot be imported, exported,
547 installed, or linked. Some native build systems may not like
548 targets that have only object files, so consider adding at least
549 one real source file to any target that references $<TAR‐
550 GET_OBJECTS:objlib>.
551 The signature
554 add_library(<name> ALIAS <target>)
557 creates an alias, such that <name> can be used to refer to <tar‐
559 get> in subsequent commands. The <name> does not appear in the
560 generated buildsystem as a make target. The <target> may not be
561 an IMPORTED target or an ALIAS. Alias targets can be used as
562 linkable targets, targets to read properties from. They can
563 also be tested for existance with the regular if(TARGET) subcom‐
564 mand. The <name> may not be used to modify properties of <tar‐
565 get>, that is, it may not be used as the operand of set_prop‐
566 erty, set_target_properties, target_link_libraries etc. An
567 ALIAS target may not be installed of exported.
568 add_subdirectory
571 Add a subdirectory to the build.
572 add_subdirectory(source_dir [binary_dir]
574 [EXCLUDE_FROM_ALL])
575 Add a subdirectory to the build. The source_dir specifies the
577 directory in which the source CMakeLists.txt and code files are
578 located. If it is a relative path it will be evaluated with
579 respect to the current directory (the typical usage), but it may
580 also be an absolute path. The binary_dir specifies the directory
581 in which to place the output files. If it is a relative path it
582 will be evaluated with respect to the current output directory,
583 but it may also be an absolute path. If binary_dir is not speci‐
584 fied, the value of source_dir, before expanding any relative
585 path, will be used (the typical usage). The CMakeLists.txt file
586 in the specified source directory will be processed immediately
587 by CMake before processing in the current input file continues
588 beyond this command.
589 If the EXCLUDE_FROM_ALL argument is provided then targets in the
592 subdirectory will not be included in the ALL target of the par‐
593 ent directory by default, and will be excluded from IDE project
594 files. Users must explicitly build targets in the subdirectory.
595 This is meant for use when the subdirectory contains a separate
596 part of the project that is useful but not necessary, such as a
597 set of examples. Typically the subdirectory should contain its
598 own project() command invocation so that a full build system
599 will be generated in the subdirectory (such as a VS IDE solution
600 file). Note that inter-target dependencies supercede this
601 exclusion. If a target built by the parent project depends on a
602 target in the subdirectory, the dependee target will be included
603 in the parent project build system to satisfy the dependency.
604 add_test
607 Add a test to the project with the specified arguments.
608 add_test(testname Exename arg1 arg2 ... )
610 If the ENABLE_TESTING command has been run, this command adds a
612 test target to the current directory. If ENABLE_TESTING has not
613 been run, this command does nothing. The tests are run by the
614 testing subsystem by executing Exename with the specified argu‐
615 ments. Exename can be either an executable built by this
616 project or an arbitrary executable on the system (like tclsh).
617 The test will be run with the current working directory set to
618 the CMakeList.txt files corresponding directory in the binary
619 tree.
620 add_test(NAME <name> [CONFIGURATIONS [Debug|Release|...]]
626 [WORKING_DIRECTORY dir]
627 COMMAND <command> [arg1 [arg2 ...]])
628 Add a test called <name>. The test name may not contain spaces,
630 quotes, or other characters special in CMake syntax. If COMMAND
631 specifies an executable target (created by add_executable) it
632 will automatically be replaced by the location of the executable
633 created at build time. If a CONFIGURATIONS option is given then
634 the test will be executed only when testing under one of the
635 named configurations. If a WORKING_DIRECTORY option is given
636 then the test will be executed in the given directory.
637 Arguments after COMMAND may use "generator expressions" with the
640 syntax "$<...>". Generator expressions are evaluated during
641 build system generation to produce information specific to each
642 build configuration. Valid expressions are:
643 $<0:...> = empty string (ignores "...")
646 $<1:...> = content of "..."
647 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
648 $<CONFIGURATION> = configuration name
649 $<BOOL:...> = '1' if the '...' is true, else '0'
650 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
651 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
652 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
653 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
654 $<JOIN:list,...> = joins the list with the content of "..."
655 $<TARGET_NAME:...> = Marks ... as being the name of a target. This is required if exporting targets to multiple dependent export sets. The '...' must be a literal name of a target- it may not contain generator expressions.
656 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
657 $<BUILD_INTERFACE:...> = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
658 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
659 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
660 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
661 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
662 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
663 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
664 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
665 $<C_COMPILER_VERSION> = The version of the C compiler used.
666 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
667 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
668 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
669 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
670 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
671 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
672 where "tgt" is the name of a target. Target file expressions
674 produce a full path, but _DIR and _NAME versions can produce the
675 directory and file name components:
676 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
679 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
680 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
681 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
686 Note that tgt is not added as a dependency of the target this
688 expression is evaluated on.
689 $<TARGET_POLICY:pol> = '1' if the policy was NEW when the 'head' target was created, else '0'. If the policy was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies.
692 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
693 Boolean expressions:
695 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
698 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
699 $<NOT:?> = '0' if '?' is '1', else '1'
700 where '?' is always either '0' or '1'.
702 Example usage:
705 add_test(NAME mytest
708 COMMAND testDriver --config $<CONFIGURATION>
709 --exe $<TARGET_FILE:myexe>)
710 This creates a test "mytest" whose command runs a testDriver
712 tool passing the configuration name and the full path to the
713 executable file produced by target "myexe".
714 aux_source_directory
717 Find all source files in a directory.
718 aux_source_directory(<dir> <variable>)
720 Collects the names of all the source files in the specified
722 directory and stores the list in the <variable> provided. This
723 command is intended to be used by projects that use explicit
724 template instantiation. Template instantiation files can be
725 stored in a "Templates" subdirectory and collected automatically
726 using this command to avoid manually listing all instantiations.
727 It is tempting to use this command to avoid writing the list of
730 source files for a library or executable target. While this
731 seems to work, there is no way for CMake to generate a build
732 system that knows when a new source file has been added. Nor‐
733 mally the generated build system knows when it needs to rerun
734 CMake because the CMakeLists.txt file is modified to add a new
735 source. When the source is just added to the directory without
736 modifying this file, one would have to manually rerun CMake to
737 generate a build system incorporating the new file.
738 break Break from an enclosing foreach or while loop.
741 break()
743 Breaks from an enclosing foreach loop or while loop
745 build_command
748 Get the command line to build this project.
749 build_command(<variable>
751 [CONFIGURATION <config>]
752 [PROJECT_NAME <projname>]
753 [TARGET <target>])
754 Sets the given <variable> to a string containing the command
756 line for building one configuration of a target in a project
757 using the build tool appropriate for the current CMAKE_GENERA‐
758 TOR.
759 If CONFIGURATION is omitted, CMake chooses a reasonable default
762 value for multi-configuration generators. CONFIGURATION is
763 ignored for single-configuration generators.
764 If PROJECT_NAME is omitted, the resulting command line will
767 build the top level PROJECT in the current build tree.
768 If TARGET is omitted, the resulting command line will build
771 everything, effectively using build target 'all' or 'ALL_BUILD'.
772 build_command(<cachevariable> <makecommand>)
775 This second signature is deprecated, but still available for
777 backwards compatibility. Use the first signature instead.
778 Sets the given <cachevariable> to a string containing the com‐
781 mand to build this project from the root of the build tree using
782 the build tool given by <makecommand>. <makecommand> should be
783 the full path to msdev, devenv, nmake, make or one of the end
784 user build tools.
785 cmake_host_system_information
788 Query host system specific information.
789 cmake_host_system_information(RESULT <variable> QUERY <key> ...)
791 Queries system information of the host system on which cmake
793 runs. One or more <key> can be provided to select the informa‐
794 tion to be queried. The list of queried values is stored in
795 <variable>.
796 <key> can be one of the following values:
799 NUMBER_OF_LOGICAL_CORES = Number of logical cores.
802 NUMBER_OF_PHYSICAL_CORES = Number of physical cores.
803 HOSTNAME = Hostname.
804 FQDN = Fully qualified domain name.
805 TOTAL_VIRTUAL_MEMORY = Total virtual memory in megabytes.
806 AVAILABLE_VIRTUAL_MEMORY = Available virtual memory in megabytes.
807 TOTAL_PHYSICAL_MEMORY = Total physical memory in megabytes.
808 AVAILABLE_PHYSICAL_MEMORY = Available physical memory in megabytes.
809 cmake_minimum_required
812 Set the minimum required version of cmake for a project.
813 cmake_minimum_required(VERSION major[.minor[.patch[.tweak]]]
815 [FATAL_ERROR])
816 If the current version of CMake is lower than that required it
818 will stop processing the project and report an error. When a
819 version higher than 2.4 is specified the command implicitly
820 invokes
821 cmake_policy(VERSION major[.minor[.patch[.tweak]]])
824 which sets the cmake policy version level to the version speci‐
826 fied. When version 2.4 or lower is given the command implicitly
827 invokes
828 cmake_policy(VERSION 2.4)
831 which enables compatibility features for CMake 2.4 and lower.
833 The FATAL_ERROR option is accepted but ignored by CMake 2.6 and
836 higher. It should be specified so CMake versions 2.4 and lower
837 fail with an error instead of just a warning.
838 cmake_policy
841 Manage CMake Policy settings.
842 As CMake evolves it is sometimes necessary to change existing
844 behavior in order to fix bugs or improve implementations of
845 existing features. The CMake Policy mechanism is designed to
846 help keep existing projects building as new versions of CMake
847 introduce changes in behavior. Each new policy (behavioral
848 change) is given an identifier of the form "CMP<NNNN>" where
849 "<NNNN>" is an integer index. Documentation associated with
850 each policy describes the OLD and NEW behavior and the reason
851 the policy was introduced. Projects may set each policy to
852 select the desired behavior. When CMake needs to know which
853 behavior to use it checks for a setting specified by the
854 project. If no setting is available the OLD behavior is assumed
855 and a warning is produced requesting that the policy be set.
856 The cmake_policy command is used to set policies to OLD or NEW
859 behavior. While setting policies individually is supported, we
860 encourage projects to set policies based on CMake versions.
861 cmake_policy(VERSION major.minor[.patch[.tweak]])
864 Specify that the current CMake list file is written for the
866 given version of CMake. All policies introduced in the speci‐
867 fied version or earlier will be set to use NEW behavior. All
868 policies introduced after the specified version will be unset
869 (unless variable CMAKE_POLICY_DEFAULT_CMP<NNNN> sets a default).
870 This effectively requests behavior preferred as of a given CMake
871 version and tells newer CMake versions to warn about their new
872 policies. The policy version specified must be at least 2.4 or
873 the command will report an error. In order to get compatibility
874 features supporting versions earlier than 2.4 see documentation
875 of policy CMP0001.
876 cmake_policy(SET CMP<NNNN> NEW)
879 cmake_policy(SET CMP<NNNN> OLD)
880 Tell CMake to use the OLD or NEW behavior for a given policy.
882 Projects depending on the old behavior of a given policy may
883 silence a policy warning by setting the policy state to OLD.
884 Alternatively one may fix the project to work with the new
885 behavior and set the policy state to NEW.
886 cmake_policy(GET CMP<NNNN> <variable>)
889 Check whether a given policy is set to OLD or NEW behavior. The
891 output variable value will be "OLD" or "NEW" if the policy is
892 set, and empty otherwise.
893 CMake keeps policy settings on a stack, so changes made by the
896 cmake_policy command affect only the top of the stack. A new
897 entry on the policy stack is managed automatically for each sub‐
898 directory to protect its parents and siblings. CMake also man‐
899 ages a new entry for scripts loaded by include() and find_pack‐
900 age() commands except when invoked with the NO_POLICY_SCOPE
901 option (see also policy CMP0011). The cmake_policy command pro‐
902 vides an interface to manage custom entries on the policy stack:
903 cmake_policy(PUSH)
906 cmake_policy(POP)
907 Each PUSH must have a matching POP to erase any changes. This
909 is useful to make temporary changes to policy settings.
910 Functions and macros record policy settings when they are cre‐
913 ated and use the pre-record policies when they are invoked. If
914 the function or macro implementation sets policies, the changes
915 automatically propagate up through callers until they reach the
916 closest nested policy stack entry.
917 configure_file
920 Copy a file to another location and modify its contents.
921 configure_file(<input> <output>
923 [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
924 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
925 Copies a file <input> to file <output> and substitutes variable
927 values referenced in the file content. If <input> is a relative
928 path it is evaluated with respect to the current source direc‐
929 tory. The <input> must be a file, not a directory. If <output>
930 is a relative path it is evaluated with respect to the current
931 binary directory. If <output> names an existing directory the
932 input file is placed in that directory with its original name.
933 If the <input> file is modified the build system will re-run
936 CMake to re-configure the file and generate the build system
937 again.
938 This command replaces any variables in the input file referenced
941 as ${VAR} or @VAR@ with their values as determined by CMake. If
942 a variable is not defined, it will be replaced with nothing. If
943 COPYONLY is specified, then no variable expansion will take
944 place. If ESCAPE_QUOTES is specified then any substituted
945 quotes will be C-style escaped. The file will be configured
946 with the current values of CMake variables. If @ONLY is speci‐
947 fied, only variables of the form @VAR@ will be replaced and
948 ${VAR} will be ignored. This is useful for configuring scripts
949 that use ${VAR}.
950 Input file lines of the form "#cmakedefine VAR ..." will be
953 replaced with either "#define VAR ..." or "/* #undef VAR */"
954 depending on whether VAR is set in CMake to any value not con‐
955 sidered a false constant by the if() command. (Content of "...",
956 if any, is processed as above.) Input file lines of the form
957 "#cmakedefine01 VAR" will be replaced with either "#define VAR
958 1" or "#define VAR 0" similarly.
959 With NEWLINE_STYLE the line ending could be adjusted:
962 'UNIX' or 'LF' for \n, 'DOS', 'WIN32' or 'CRLF' for \r\n.
965 COPYONLY must not be used with NEWLINE_STYLE.
967 create_test_sourcelist
971 Create a test driver and source list for building test programs.
972 create_test_sourcelist(sourceListName driverName
974 test1 test2 test3
975 EXTRA_INCLUDE include.h
976 FUNCTION function)
977 A test driver is a program that links together many small tests
979 into a single executable. This is useful when building static
980 executables with large libraries to shrink the total required
981 size. The list of source files needed to build the test driver
982 will be in sourceListName. DriverName is the name of the test
983 driver program. The rest of the arguments consist of a list of
984 test source files, can be semicolon separated. Each test source
985 file should have a function in it that is the same name as the
986 file with no extension (foo.cxx should have int foo(int,
987 char*[]);) DriverName will be able to call each of the tests by
988 name on the command line. If EXTRA_INCLUDE is specified, then
989 the next argument is included into the generated file. If FUNC‐
990 TION is specified, then the next argument is taken as a function
991 name that is passed a pointer to ac and av. This can be used to
992 add extra command line processing to each test. The cmake vari‐
993 able CMAKE_TESTDRIVER_BEFORE_TESTMAIN can be set to have code
994 that will be placed directly before calling the test main func‐
995 tion. CMAKE_TESTDRIVER_AFTER_TESTMAIN can be set to have code
996 that will be placed directly after the call to the test main
997 function.
998 define_property
1001 Define and document custom properties.
1002 define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
1004 TEST | VARIABLE | CACHED_VARIABLE>
1005 PROPERTY <name> [INHERITED]
1006 BRIEF_DOCS <brief-doc> [docs...]
1007 FULL_DOCS <full-doc> [docs...])
1008 Define one property in a scope for use with the set_property and
1010 get_property commands. This is primarily useful to associate
1011 documentation with property names that may be retrieved with the
1012 get_property command. The first argument determines the kind of
1013 scope in which the property should be used. It must be one of
1014 the following:
1015 GLOBAL = associated with the global namespace
1018 DIRECTORY = associated with one directory
1019 TARGET = associated with one target
1020 SOURCE = associated with one source file
1021 TEST = associated with a test named with add_test
1022 VARIABLE = documents a CMake language variable
1023 CACHED_VARIABLE = documents a CMake cache variable
1024 Note that unlike set_property and get_property no actual scope
1026 needs to be given; only the kind of scope is important.
1027 The required PROPERTY option is immediately followed by the name
1030 of the property being defined.
1031 If the INHERITED option then the get_property command will chain
1034 up to the next higher scope when the requested property is not
1035 set in the scope given to the command. DIRECTORY scope chains
1036 to GLOBAL. TARGET, SOURCE, and TEST chain to DIRECTORY.
1037 The BRIEF_DOCS and FULL_DOCS options are followed by strings to
1040 be associated with the property as its brief and full documenta‐
1041 tion. Corresponding options to the get_property command will
1042 retrieve the documentation.
1043 else Starts the else portion of an if block.
1046 else(expression)
1048 See the if command.
1050 elseif Starts the elseif portion of an if block.
1053 elseif(expression)
1055 See the if command.
1057 enable_language
1060 Enable a language (CXX/C/Fortran/etc)
1061 enable_language(<lang> [OPTIONAL] )
1063 This command enables support for the named language in CMake.
1065 This is the same as the project command but does not create any
1066 of the extra variables that are created by the project command.
1067 Example languages are CXX, C, Fortran.
1068 This command must be called in file scope, not in a function
1071 call. Furthermore, it must be called in the highest directory
1072 common to all targets using the named language directly for com‐
1073 piling sources or indirectly through link dependencies. It is
1074 simplest to enable all needed languages in the top-level direc‐
1075 tory of a project.
1076 The OPTIONAL keyword is a placeholder for future implementation
1079 and does not currently work.
1080 enable_testing
1083 Enable testing for current directory and below.
1084 enable_testing()
1086 Enables testing for this directory and below. See also the
1088 add_test command. Note that ctest expects to find a test file
1089 in the build directory root. Therefore, this command should be
1090 in the source directory root.
1091 endforeach
1094 Ends a list of commands in a FOREACH block.
1095 endforeach(expression)
1097 See the FOREACH command.
1099 endfunction
1102 Ends a list of commands in a function block.
1103 endfunction(expression)
1105 See the function command.
1107 endif Ends a list of commands in an if block.
1110 endif(expression)
1112 See the if command.
1114 endmacro
1117 Ends a list of commands in a macro block.
1118 endmacro(expression)
1120 See the macro command.
1122 endwhile
1125 Ends a list of commands in a while block.
1126 endwhile(expression)
1128 See the while command.
1130 execute_process
1133 Execute one or more child processes.
1134 execute_process(COMMAND <cmd1> [args1...]]
1136 [COMMAND <cmd2> [args2...] [...]]
1137 [WORKING_DIRECTORY <directory>]
1138 [TIMEOUT <seconds>]
1139 [RESULT_VARIABLE <variable>]
1140 [OUTPUT_VARIABLE <variable>]
1141 [ERROR_VARIABLE <variable>]
1142 [INPUT_FILE <file>]
1143 [OUTPUT_FILE <file>]
1144 [ERROR_FILE <file>]
1145 [OUTPUT_QUIET]
1146 [ERROR_QUIET]
1147 [OUTPUT_STRIP_TRAILING_WHITESPACE]
1148 [ERROR_STRIP_TRAILING_WHITESPACE])
1149 Runs the given sequence of one or more commands with the stan‐
1151 dard output of each process piped to the standard input of the
1152 next. A single standard error pipe is used for all processes.
1153 If WORKING_DIRECTORY is given the named directory will be set as
1154 the current working directory of the child processes. If TIME‐
1155 OUT is given the child processes will be terminated if they do
1156 not finish in the specified number of seconds (fractions are
1157 allowed). If RESULT_VARIABLE is given the variable will be set
1158 to contain the result of running the processes. This will be an
1159 integer return code from the last child or a string describing
1160 an error condition. If OUTPUT_VARIABLE or ERROR_VARIABLE are
1161 given the variable named will be set with the contents of the
1162 standard output and standard error pipes respectively. If the
1163 same variable is named for both pipes their output will be
1164 merged in the order produced. If INPUT_FILE, OUTPUT_FILE, or
1165 ERROR_FILE is given the file named will be attached to the stan‐
1166 dard input of the first process, standard output of the last
1167 process, or standard error of all processes respectively. If
1168 OUTPUT_QUIET or ERROR_QUIET is given then the standard output or
1169 standard error results will be quietly ignored. If more than
1170 one OUTPUT_* or ERROR_* option is given for the same pipe the
1171 precedence is not specified. If no OUTPUT_* or ERROR_* options
1172 are given the output will be shared with the corresponding pipes
1173 of the CMake process itself.
1174 The execute_process command is a newer more powerful version of
1177 exec_program, but the old command has been kept for compatibil‐
1178 ity.
1179 export Export targets from the build tree for use by outside projects.
1182 export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
1184 [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
1185 Create a file <filename> that may be included by outside
1187 projects to import targets from the current project's build
1188 tree. This is useful during cross-compiling to build utility
1189 executables that can run on the host platform in one project and
1190 then import them into another project being compiled for the
1191 target platform. If the NAMESPACE option is given the <names‐
1192 pace> string will be prepended to all target names written to
1193 the file. If the APPEND option is given the generated code will
1194 be appended to the file instead of overwriting it. The
1195 EXPORT_LINK_INTERFACE_LIBRARIES keyword, if present, causes the
1196 contents of the properties matching (IMPORTED_)?LINK_INTER‐
1197 FACE_LIBRARIES(_<CONFIG>)? to be exported, when policy CMP0022
1198 is NEW. If a library target is included in the export but a
1199 target to which it links is not included the behavior is unspec‐
1200 ified.
1201 The file created by this command is specific to the build tree
1204 and should never be installed. See the install(EXPORT) command
1205 to export targets from an installation tree.
1206 Do not set properties that affect the location of a target after
1209 passing it to this command. These include properties whose
1210 names match "(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIREC‐
1211 TORY)(_<CONFIG>)?", "(IMPLIB_)?(PREFIX|SUFFIX)", or "LINKER_LAN‐
1212 GUAGE". Failure to follow this rule is not diagnosed and leaves
1213 the location of the target undefined.
1214 export(PACKAGE <name>)
1217 Store the current build directory in the CMake user package reg‐
1219 istry for package <name>. The find_package command may consider
1220 the directory while searching for package <name>. This helps
1221 dependent projects find and use a package from the current
1222 project's build tree without help from the user. Note that the
1223 entry in the package registry that this command creates works
1224 only in conjunction with a package configuration file
1225 (<name>Config.cmake) that works with the build tree.
1226 file File manipulation command.
1229 file(WRITE filename "message to write"... )
1231 file(APPEND filename "message to write"... )
1232 file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX])
1233 file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> filename variable)
1234 file(STRINGS filename variable [LIMIT_COUNT num]
1235 [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes]
1236 [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes]
1237 [NEWLINE_CONSUME] [REGEX regex]
1238 [NO_HEX_CONVERSION])
1239 file(GLOB variable [RELATIVE path] [globbing expressions]...)
1240 file(GLOB_RECURSE variable [RELATIVE path]
1241 [FOLLOW_SYMLINKS] [globbing expressions]...)
1242 file(RENAME <oldname> <newname>)
1243 file(REMOVE [file1 ...])
1244 file(REMOVE_RECURSE [file1 ...])
1245 file(MAKE_DIRECTORY [directory1 directory2 ...])
1246 file(RELATIVE_PATH variable directory file)
1247 file(TO_CMAKE_PATH path result)
1248 file(TO_NATIVE_PATH path result)
1249 file(DOWNLOAD url file [INACTIVITY_TIMEOUT timeout]
1250 [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS]
1251 [EXPECTED_HASH ALGO=value] [EXPECTED_MD5 sum]
1252 [TLS_VERIFY on|off] [TLS_CAINFO file])
1253 file(UPLOAD filename url [INACTIVITY_TIMEOUT timeout]
1254 [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS])
1255 file(TIMESTAMP filename variable [<format string>] [UTC])
1256 file(GENERATE OUTPUT output_file
1257 <INPUT input_file|CONTENT input_content>
1258 [CONDITION expression])
1259 WRITE will write a message into a file called 'filename'. It
1261 overwrites the file if it already exists, and creates the file
1262 if it does not exist. (If the file is a build input, use config‐
1263 ure_file to update the file only when its content changes.)
1264 APPEND will write a message into a file same as WRITE, except it
1267 will append it to the end of the file
1268 READ will read the content of a file and store it into the vari‐
1271 able. It will start at the given offset and read up to numBytes.
1272 If the argument HEX is given, the binary data will be converted
1273 to hexadecimal representation and this will be stored in the
1274 variable.
1275 MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a
1278 cryptographic hash of the content of a file.
1279 STRINGS will parse a list of ASCII strings from a file and store
1282 it in a variable. Binary data in the file are ignored. Carriage
1283 return (CR) characters are ignored. It works also for Intel Hex
1284 and Motorola S-record files, which are automatically converted
1285 to binary format when reading them. Disable this using
1286 NO_HEX_CONVERSION.
1287 LIMIT_COUNT sets the maximum number of strings to return.
1290 LIMIT_INPUT sets the maximum number of bytes to read from the
1291 input file. LIMIT_OUTPUT sets the maximum number of bytes to
1292 store in the output variable. LENGTH_MINIMUM sets the minimum
1293 length of a string to return. Shorter strings are ignored.
1294 LENGTH_MAXIMUM sets the maximum length of a string to return.
1295 Longer strings are split into strings no longer than the maximum
1296 length. NEWLINE_CONSUME allows newlines to be included in
1297 strings instead of terminating them.
1298 REGEX specifies a regular expression that a string must match to
1301 be returned. Typical usage
1302 file(STRINGS myfile.txt myfile)
1305 stores a list in the variable "myfile" in which each item is a
1307 line from the input file.
1308 GLOB will generate a list of all files that match the globbing
1311 expressions and store it into the variable. Globbing expressions
1312 are similar to regular expressions, but much simpler. If RELA‐
1313 TIVE flag is specified for an expression, the results will be
1314 returned as a relative path to the given path. (We do not rec‐
1315 ommend using GLOB to collect a list of source files from your
1316 source tree. If no CMakeLists.txt file changes when a source is
1317 added or removed then the generated build system cannot know
1318 when to ask CMake to regenerate.)
1319 Examples of globbing expressions include:
1322 *.cxx - match all files with extension cxx
1325 *.vt? - match all files with extension vta,...,vtz
1326 f[3-5].txt - match files f3.txt, f4.txt, f5.txt
1327 GLOB_RECURSE will generate a list similar to the regular GLOB,
1329 except it will traverse all the subdirectories of the matched
1330 directory and match the files. Subdirectories that are symlinks
1331 are only traversed if FOLLOW_SYMLINKS is given or cmake policy
1332 CMP0009 is not set to NEW. See cmake --help-policy CMP0009 for
1333 more information.
1334 Examples of recursive globbing include:
1337 /dir/*.py - match all python files in /dir and subdirectories
1340 MAKE_DIRECTORY will create the given directories, also if their
1342 parent directories don't exist yet
1343 RENAME moves a file or directory within a filesystem, replacing
1346 the destination atomically.
1347 REMOVE will remove the given files, also in subdirectories
1350 REMOVE_RECURSE will remove the given files and directories, also
1353 non-empty directories
1354 RELATIVE_PATH will determine relative path from directory to the
1357 given file.
1358 TO_CMAKE_PATH will convert path into a cmake style path with
1361 unix /. The input can be a single path or a system path like
1362 "$ENV{PATH}". Note the double quotes around the ENV call
1363 TO_CMAKE_PATH only takes one argument. This command will also
1364 convert the native list delimiters for a list of paths like the
1365 PATH environment variable.
1366 TO_NATIVE_PATH works just like TO_CMAKE_PATH, but will convert
1369 from a cmake style path into the native path style \ for win‐
1370 dows and / for UNIX.
1371 DOWNLOAD will download the given URL to the given file. If LOG
1374 var is specified a log of the download will be put in var. If
1375 STATUS var is specified the status of the operation will be put
1376 in var. The status is returned in a list of length 2. The first
1377 element is the numeric return value for the operation, and the
1378 second element is a string value for the error. A 0 numeric
1379 error means no error in the operation. If TIMEOUT time is speci‐
1380 fied, the operation will timeout after time seconds, time should
1381 be specified as an integer. The INACTIVITY_TIMEOUT specifies an
1382 integer number of seconds of inactivity after which the opera‐
1383 tion should terminate. If EXPECTED_HASH ALGO=value is specified,
1384 the operation will verify that the downloaded file's actual hash
1385 matches the expected value, where ALGO is one of MD5, SHA1,
1386 SHA224, SHA256, SHA384, or SHA512. If it does not match, the
1387 operation fails with an error. ("EXPECTED_MD5 sum" is short-hand
1388 for "EXPECTED_HASH MD5=sum".) If SHOW_PROGRESS is specified,
1389 progress information will be printed as status messages until
1390 the operation is complete. For https URLs CMake must be built
1391 with OpenSSL. TLS/SSL certificates are not checked by default.
1392 Set TLS_VERIFY to ON to check certificates and/or use
1393 EXPECTED_HASH to verify downloaded content. Set TLS_CAINFO to
1394 specify a custom Certificate Authority file. If either TLS
1395 option is not given CMake will check variables CMAKE_TLS_VERIFY
1396 and CMAKE_TLS_CAINFO, respectively.
1397 UPLOAD will upload the given file to the given URL. If LOG var
1400 is specified a log of the upload will be put in var. If STATUS
1401 var is specified the status of the operation will be put in var.
1402 The status is returned in a list of length 2. The first element
1403 is the numeric return value for the operation, and the second
1404 element is a string value for the error. A 0 numeric error means
1405 no error in the operation. If TIMEOUT time is specified, the
1406 operation will timeout after time seconds, time should be speci‐
1407 fied as an integer. The INACTIVITY_TIMEOUT specifies an integer
1408 number of seconds of inactivity after which the operation should
1409 terminate. If SHOW_PROGRESS is specified, progress information
1410 will be printed as status messages until the operation is com‐
1411 plete.
1412 TIMESTAMP will write a string representation of the modification
1415 time of filename to variable.
1416 Should the command be unable to obtain a timestamp variable will
1419 be set to the empty string "".
1420 See documentation of the string TIMESTAMP sub-command for more
1423 details.
1424 The file() command also provides COPY and INSTALL signatures:
1427 file(<COPY|INSTALL> files... DESTINATION <dir>
1430 [FILE_PERMISSIONS permissions...]
1431 [DIRECTORY_PERMISSIONS permissions...]
1432 [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
1433 [FILES_MATCHING]
1434 [[PATTERN <pattern> | REGEX <regex>]
1435 [EXCLUDE] [PERMISSIONS permissions...]] [...])
1436 The COPY signature copies files, directories, and symlinks to a
1438 destination folder. Relative input paths are evaluated with
1439 respect to the current source directory, and a relative destina‐
1440 tion is evaluated with respect to the current build directory.
1441 Copying preserves input file timestamps, and optimizes out a
1442 file if it exists at the destination with the same timestamp.
1443 Copying preserves input permissions unless explicit permissions
1444 or NO_SOURCE_PERMISSIONS are given (default is USE_SOURCE_PER‐
1445 MISSIONS). See the install(DIRECTORY) command for documentation
1446 of permissions, PATTERN, REGEX, and EXCLUDE options.
1447 The INSTALL signature differs slightly from COPY: it prints sta‐
1450 tus messages, and NO_SOURCE_PERMISSIONS is default. Installa‐
1451 tion scripts generated by the install() command use this signa‐
1452 ture (with some undocumented options for internal use).
1453 GENERATE will write an <output_file> with content from an
1456 <input_file>, or from <input_content>. The output is generated
1457 conditionally based on the content of the <condition>. The file
1458 is written at CMake generate-time and the input may contain gen‐
1459 erator expressions. The <condition>, <output_file> and
1460 <input_file> may also contain generator expressions. The <con‐
1461 dition> must evaluate to either '0' or '1'. The <output_file>
1462 must evaluate to a unique name among all configurations and
1463 among all invocations of file(GENERATE).
1464 find_file
1467 Find the full path to a file.
1468 find_file(<VAR> name1 [path1 path2 ...])
1470 This is the short-hand signature for the command that is suffi‐
1472 cient in many cases. It is the same as find_file(<VAR> name1
1473 [PATHS path1 path2 ...])
1474 find_file(
1477 <VAR>
1478 name | NAMES name1 [name2 ...]
1479 [HINTS path1 [path2 ... ENV var]]
1480 [PATHS path1 [path2 ... ENV var]]
1481 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1482 [DOC "cache documentation string"]
1483 [NO_DEFAULT_PATH]
1484 [NO_CMAKE_ENVIRONMENT_PATH]
1485 [NO_CMAKE_PATH]
1486 [NO_SYSTEM_ENVIRONMENT_PATH]
1487 [NO_CMAKE_SYSTEM_PATH]
1488 [CMAKE_FIND_ROOT_PATH_BOTH |
1489 ONLY_CMAKE_FIND_ROOT_PATH |
1490 NO_CMAKE_FIND_ROOT_PATH]
1491 )
1492 This command is used to find a full path to named file. A cache
1494 entry named by <VAR> is created to store the result of this com‐
1495 mand. If the full path to a file is found the result is stored
1496 in the variable and the search will not be repeated unless the
1497 variable is cleared. If nothing is found, the result will be
1498 <VAR>-NOTFOUND, and the search will be attempted again the next
1499 time find_file is invoked with the same variable. The name of
1500 the full path to a file that is searched for is specified by the
1501 names listed after the NAMES argument. Additional search loca‐
1502 tions can be specified after the PATHS argument. If ENV var is
1503 found in the HINTS or PATHS section the environment variable var
1504 will be read and converted from a system environment variable to
1505 a cmake style list of paths. For example ENV PATH would be a
1506 way to list the system path variable. The argument after DOC
1507 will be used for the documentation string in the cache.
1508 PATH_SUFFIXES specifies additional subdirectories to check below
1509 each search path.
1510 If NO_DEFAULT_PATH is specified, then no additional paths are
1513 added to the search. If NO_DEFAULT_PATH is not specified, the
1514 search process is as follows:
1515 1. Search paths specified in cmake-specific cache variables.
1518 These are intended to be used on the command line with a
1519 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1520 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1523 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1524 CMAKE_INCLUDE_PATH
1525 CMAKE_FRAMEWORK_PATH
1526 2. Search paths specified in cmake-specific environment vari‐
1528 ables. These are intended to be set in the user's shell config‐
1529 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1530 passed.
1531 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1534 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1535 CMAKE_INCLUDE_PATH
1536 CMAKE_FRAMEWORK_PATH
1537 3. Search the paths specified by the HINTS option. These should
1539 be paths computed by system introspection, such as a hint pro‐
1540 vided by the location of another item already found. Hard-coded
1541 guesses should be specified with the PATHS option.
1542 4. Search the standard system environment variables. This can be
1545 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1546 PATH
1549 INCLUDE
1550 5. Search cmake variables defined in the Platform files for the
1552 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1553 passed.
1554 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1557 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1558 CMAKE_SYSTEM_INCLUDE_PATH
1559 CMAKE_SYSTEM_FRAMEWORK_PATH
1560 6. Search the paths specified by the PATHS option or in the
1562 short-hand version of the command. These are typically
1563 hard-coded guesses.
1564 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1567 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1568 following:
1569 "FIRST" - Try to find frameworks before standard
1572 libraries or headers. This is the default on Darwin.
1573 "LAST" - Try to find frameworks after standard
1574 libraries or headers.
1575 "ONLY" - Only try to find frameworks.
1576 "NEVER" - Never try to find frameworks.
1577 On Darwin or systems supporting OS X Application Bundles, the
1579 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
1580 of the following:
1581 "FIRST" - Try to find application bundles before standard
1584 programs. This is the default on Darwin.
1585 "LAST" - Try to find application bundles after standard
1586 programs.
1587 "ONLY" - Only try to find application bundles.
1588 "NEVER" - Never try to find application bundles.
1589 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
1591 directories to be prepended to all other search directories.
1592 This effectively "re-roots" the entire search under given loca‐
1593 tions. By default it is empty. It is especially useful when
1594 cross-compiling to point to the root directory of the target
1595 environment and CMake will search there too. By default at first
1596 the directories listed in CMAKE_FIND_ROOT_PATH and then the
1597 non-rooted directories will be searched. The default behavior
1598 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
1599 This behavior can be manually overridden on a per-call basis. By
1600 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
1601 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
1602 CMAKE_FIND_ROOT_PATH will not be used. If
1603 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1604 tories will be searched.
1605 The default search order is designed to be most-specific to
1608 least-specific for common use cases. Projects may override the
1609 order by simply calling the command multiple times and using the
1610 NO_* options:
1611 find_file(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1614 find_file(<VAR> NAMES name)
1615 Once one of the calls succeeds the result variable will be set
1617 and stored in the cache so that no call will search again.
1618 find_library
1621 Find a library.
1622 find_library(<VAR> name1 [path1 path2 ...])
1624 This is the short-hand signature for the command that is suffi‐
1626 cient in many cases. It is the same as find_library(<VAR> name1
1627 [PATHS path1 path2 ...])
1628 find_library(
1631 <VAR>
1632 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
1633 [HINTS path1 [path2 ... ENV var]]
1634 [PATHS path1 [path2 ... ENV var]]
1635 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1636 [DOC "cache documentation string"]
1637 [NO_DEFAULT_PATH]
1638 [NO_CMAKE_ENVIRONMENT_PATH]
1639 [NO_CMAKE_PATH]
1640 [NO_SYSTEM_ENVIRONMENT_PATH]
1641 [NO_CMAKE_SYSTEM_PATH]
1642 [CMAKE_FIND_ROOT_PATH_BOTH |
1643 ONLY_CMAKE_FIND_ROOT_PATH |
1644 NO_CMAKE_FIND_ROOT_PATH]
1645 )
1646 This command is used to find a library. A cache entry named by
1648 <VAR> is created to store the result of this command. If the
1649 library is found the result is stored in the variable and the
1650 search will not be repeated unless the variable is cleared. If
1651 nothing is found, the result will be <VAR>-NOTFOUND, and the
1652 search will be attempted again the next time find_library is
1653 invoked with the same variable. The name of the library that is
1654 searched for is specified by the names listed after the NAMES
1655 argument. Additional search locations can be specified after
1656 the PATHS argument. If ENV var is found in the HINTS or PATHS
1657 section the environment variable var will be read and converted
1658 from a system environment variable to a cmake style list of
1659 paths. For example ENV PATH would be a way to list the system
1660 path variable. The argument after DOC will be used for the docu‐
1661 mentation string in the cache. PATH_SUFFIXES specifies addi‐
1662 tional subdirectories to check below each search path.
1663 If NO_DEFAULT_PATH is specified, then no additional paths are
1666 added to the search. If NO_DEFAULT_PATH is not specified, the
1667 search process is as follows:
1668 1. Search paths specified in cmake-specific cache variables.
1671 These are intended to be used on the command line with a
1672 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1673 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1676 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1677 CMAKE_LIBRARY_PATH
1678 CMAKE_FRAMEWORK_PATH
1679 2. Search paths specified in cmake-specific environment vari‐
1681 ables. These are intended to be set in the user's shell config‐
1682 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1683 passed.
1684 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1687 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1688 CMAKE_LIBRARY_PATH
1689 CMAKE_FRAMEWORK_PATH
1690 3. Search the paths specified by the HINTS option. These should
1692 be paths computed by system introspection, such as a hint pro‐
1693 vided by the location of another item already found. Hard-coded
1694 guesses should be specified with the PATHS option.
1695 4. Search the standard system environment variables. This can be
1698 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1699 PATH
1702 LIB
1703 5. Search cmake variables defined in the Platform files for the
1705 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1706 passed.
1707 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1710 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1711 CMAKE_SYSTEM_LIBRARY_PATH
1712 CMAKE_SYSTEM_FRAMEWORK_PATH
1713 6. Search the paths specified by the PATHS option or in the
1715 short-hand version of the command. These are typically
1716 hard-coded guesses.
1717 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1720 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1721 following:
1722 "FIRST" - Try to find frameworks before standard
1725 libraries or headers. This is the default on Darwin.
1726 "LAST" - Try to find frameworks after standard
1727 libraries or headers.
1728 "ONLY" - Only try to find frameworks.
1729 "NEVER" - Never try to find frameworks.
1730 On Darwin or systems supporting OS X Application Bundles, the
1732 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
1733 of the following:
1734 "FIRST" - Try to find application bundles before standard
1737 programs. This is the default on Darwin.
1738 "LAST" - Try to find application bundles after standard
1739 programs.
1740 "ONLY" - Only try to find application bundles.
1741 "NEVER" - Never try to find application bundles.
1742 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
1744 directories to be prepended to all other search directories.
1745 This effectively "re-roots" the entire search under given loca‐
1746 tions. By default it is empty. It is especially useful when
1747 cross-compiling to point to the root directory of the target
1748 environment and CMake will search there too. By default at first
1749 the directories listed in CMAKE_FIND_ROOT_PATH and then the
1750 non-rooted directories will be searched. The default behavior
1751 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.
1752 This behavior can be manually overridden on a per-call basis. By
1753 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
1754 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
1755 CMAKE_FIND_ROOT_PATH will not be used. If
1756 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1757 tories will be searched.
1758 The default search order is designed to be most-specific to
1761 least-specific for common use cases. Projects may override the
1762 order by simply calling the command multiple times and using the
1763 NO_* options:
1764 find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1767 find_library(<VAR> NAMES name)
1768 Once one of the calls succeeds the result variable will be set
1770 and stored in the cache so that no call will search again.
1771 When more than one value is given to the NAMES option this com‐
1774 mand by default will consider one name at a time and search
1775 every directory for it. The NAMES_PER_DIR option tells this
1776 command to consider one directory at a time and search for all
1777 names in it.
1778 If the library found is a framework, then VAR will be set to the
1781 full path to the framework <fullPath>/A.framework. When a full
1782 path to a framework is used as a library, CMake will use a
1783 -framework A, and a -F<fullPath> to link the framework to the
1784 target.
1785 If the global property FIND_LIBRARY_USE_LIB64_PATHS is set all
1788 search paths will be tested as normal, with "64/" appended, and
1789 with all matches of "lib/" replaced with "lib64/". This property
1790 is automatically set for the platforms that are known to need it
1791 if at least one of the languages supported by the PROJECT com‐
1792 mand is enabled.
1793 find_package
1796 Load settings for an external project.
1797 find_package(<package> [version] [EXACT] [QUIET] [MODULE]
1799 [REQUIRED] [[COMPONENTS] [components...]]
1800 [OPTIONAL_COMPONENTS components...]
1801 [NO_POLICY_SCOPE])
1802 Finds and loads settings from an external project. <pack‐
1804 age>_FOUND will be set to indicate whether the package was
1805 found. When the package is found package-specific information
1806 is provided through variables and imported targets documented by
1807 the package itself. The QUIET option disables messages if the
1808 package cannot be found. The MODULE option disables the second
1809 signature documented below. The REQUIRED option stops process‐
1810 ing with an error message if the package cannot be found.
1811 A package-specific list of required components may be listed
1814 after the COMPONENTS option (or after the REQUIRED option if
1815 present). Additional optional components may be listed after
1816 OPTIONAL_COMPONENTS. Available components and their influence
1817 on whether a package is considered to be found are defined by
1818 the target package.
1819 The [version] argument requests a version with which the package
1822 found should be compatible (format is
1823 major[.minor[.patch[.tweak]]]). The EXACT option requests that
1824 the version be matched exactly. If no [version] and/or compo‐
1825 nent list is given to a recursive invocation inside a find-mod‐
1826 ule, the corresponding arguments are forwarded automatically
1827 from the outer call (including the EXACT flag for [version]).
1828 Version support is currently provided only on a package-by-pack‐
1829 age basis (details below).
1830 User code should generally look for packages using the above
1833 simple signature. The remainder of this command documentation
1834 specifies the full command signature and details of the search
1835 process. Project maintainers wishing to provide a package to be
1836 found by this command are encouraged to read on.
1837 The command has two modes by which it searches for packages:
1840 "Module" mode and "Config" mode. Module mode is available when
1841 the command is invoked with the above reduced signature. CMake
1842 searches for a file called "Find<package>.cmake" in the
1843 CMAKE_MODULE_PATH followed by the CMake installation. If the
1844 file is found, it is read and processed by CMake. It is respon‐
1845 sible for finding the package, checking the version, and produc‐
1846 ing any needed messages. Many find-modules provide limited or
1847 no support for versioning; check the module documentation. If
1848 no module is found and the MODULE option is not given the com‐
1849 mand proceeds to Config mode.
1850 The complete Config mode command signature is:
1853 find_package(<package> [version] [EXACT] [QUIET]
1856 [REQUIRED] [[COMPONENTS] [components...]]
1857 [CONFIG|NO_MODULE]
1858 [NO_POLICY_SCOPE]
1859 [NAMES name1 [name2 ...]]
1860 [CONFIGS config1 [config2 ...]]
1861 [HINTS path1 [path2 ... ]]
1862 [PATHS path1 [path2 ... ]]
1863 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1864 [NO_DEFAULT_PATH]
1865 [NO_CMAKE_ENVIRONMENT_PATH]
1866 [NO_CMAKE_PATH]
1867 [NO_SYSTEM_ENVIRONMENT_PATH]
1868 [NO_CMAKE_PACKAGE_REGISTRY]
1869 [NO_CMAKE_BUILDS_PATH]
1870 [NO_CMAKE_SYSTEM_PATH]
1871 [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
1872 [CMAKE_FIND_ROOT_PATH_BOTH |
1873 ONLY_CMAKE_FIND_ROOT_PATH |
1874 NO_CMAKE_FIND_ROOT_PATH])
1875 The CONFIG option may be used to skip Module mode explicitly and
1877 switch to Config mode. It is synonymous to using NO_MODULE.
1878 Config mode is also implied by use of options not specified in
1879 the reduced signature.
1880 Config mode attempts to locate a configuration file provided by
1883 the package to be found. A cache entry called <package>_DIR is
1884 created to hold the directory containing the file. By default
1885 the command searches for a package with the name <package>. If
1886 the NAMES option is given the names following it are used
1887 instead of <package>. The command searches for a file called
1888 "<name>Config.cmake" or "<lower-case-name>-config.cmake" for
1889 each name specified. A replacement set of possible configura‐
1890 tion file names may be given using the CONFIGS option. The
1891 search procedure is specified below. Once found, the configura‐
1892 tion file is read and processed by CMake. Since the file is
1893 provided by the package it already knows the location of package
1894 contents. The full path to the configuration file is stored in
1895 the cmake variable <package>_CONFIG.
1896 All configuration files which have been considered by CMake
1899 while searching for an installation of the package with an
1900 appropriate version are stored in the cmake variable <pack‐
1901 age>_CONSIDERED_CONFIGS, the associated versions in <pack‐
1902 age>_CONSIDERED_VERSIONS.
1903 If the package configuration file cannot be found CMake will
1906 generate an error describing the problem unless the QUIET argu‐
1907 ment is specified. If REQUIRED is specified and the package is
1908 not found a fatal error is generated and the configure step
1909 stops executing. If <package>_DIR has been set to a directory
1910 not containing a configuration file CMake will ignore it and
1911 search from scratch.
1912 When the [version] argument is given Config mode will only find
1915 a version of the package that claims compatibility with the
1916 requested version (format is major[.minor[.patch[.tweak]]]). If
1917 the EXACT option is given only a version of the package claiming
1918 an exact match of the requested version may be found. CMake
1919 does not establish any convention for the meaning of version
1920 numbers. Package version numbers are checked by "version" files
1921 provided by the packages themselves. For a candidate package
1922 configuration file "<config-file>.cmake" the corresponding ver‐
1923 sion file is located next to it and named either "<con‐
1924 fig-file>-version.cmake" or "<config-file>Version.cmake". If no
1925 such version file is available then the configuration file is
1926 assumed to not be compatible with any requested version. A
1927 basic version file containing generic version matching code can
1928 be created using the macro write_basic_package_version_file(),
1929 see its documentation for more details. When a version file is
1930 found it is loaded to check the requested version number. The
1931 version file is loaded in a nested scope in which the following
1932 variables have been defined:
1933 PACKAGE_FIND_NAME = the <package> name
1936 PACKAGE_FIND_VERSION = full requested version string
1937 PACKAGE_FIND_VERSION_MAJOR = major version if requested, else 0
1938 PACKAGE_FIND_VERSION_MINOR = minor version if requested, else 0
1939 PACKAGE_FIND_VERSION_PATCH = patch version if requested, else 0
1940 PACKAGE_FIND_VERSION_TWEAK = tweak version if requested, else 0
1941 PACKAGE_FIND_VERSION_COUNT = number of version components, 0 to 4
1942 The version file checks whether it satisfies the requested ver‐
1944 sion and sets these variables:
1945 PACKAGE_VERSION = full provided version string
1948 PACKAGE_VERSION_EXACT = true if version is exact match
1949 PACKAGE_VERSION_COMPATIBLE = true if version is compatible
1950 PACKAGE_VERSION_UNSUITABLE = true if unsuitable as any version
1951 These variables are checked by the find_package command to
1953 determine whether the configuration file provides an acceptable
1954 version. They are not available after the find_package call
1955 returns. If the version is acceptable the following variables
1956 are set:
1957 <package>_VERSION = full provided version string
1960 <package>_VERSION_MAJOR = major version if provided, else 0
1961 <package>_VERSION_MINOR = minor version if provided, else 0
1962 <package>_VERSION_PATCH = patch version if provided, else 0
1963 <package>_VERSION_TWEAK = tweak version if provided, else 0
1964 <package>_VERSION_COUNT = number of version components, 0 to 4
1965 and the corresponding package configuration file is loaded.
1967 When multiple package configuration files are available whose
1968 version files claim compatibility with the version requested it
1969 is unspecified which one is chosen. No attempt is made to
1970 choose a highest or closest version number.
1971 Config mode provides an elaborate interface and search proce‐
1974 dure. Much of the interface is provided for completeness and
1975 for use internally by find-modules loaded by Module mode. Most
1976 user code should simply call
1977 find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
1980 in order to find a package. Package maintainers providing CMake
1982 package configuration files are encouraged to name and install
1983 them such that the procedure outlined below will find them with‐
1984 out requiring use of additional options.
1985 CMake constructs a set of possible installation prefixes for the
1988 package. Under each prefix several directories are searched for
1989 a configuration file. The tables below show the directories
1990 searched. Each entry is meant for installation trees following
1991 Windows (W), UNIX (U), or Apple (A) conventions.
1992 <prefix>/ (W)
1995 <prefix>/(cmake|CMake)/ (W)
1996 <prefix>/<name>*/ (W)
1997 <prefix>/<name>*/(cmake|CMake)/ (W)
1998 <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/ (U)
1999 <prefix>/(lib/<arch>|lib|share)/<name>*/ (U)
2000 <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/ (U)
2001 On systems supporting OS X Frameworks and Application Bundles
2003 the following directories are searched for frameworks or bundles
2004 containing a configuration file:
2005 <prefix>/<name>.framework/Resources/ (A)
2008 <prefix>/<name>.framework/Resources/CMake/ (A)
2009 <prefix>/<name>.framework/Versions/*/Resources/ (A)
2010 <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
2011 <prefix>/<name>.app/Contents/Resources/ (A)
2012 <prefix>/<name>.app/Contents/Resources/CMake/ (A)
2013 In all cases the <name> is treated as case-insensitive and cor‐
2015 responds to any of the names specified (<package> or names given
2016 by NAMES). Paths with lib/<arch> are enabled if
2017 CMAKE_LIBRARY_ARCHITECTURE is set. If PATH_SUFFIXES is speci‐
2018 fied the suffixes are appended to each (W) or (U) directory
2019 entry one-by-one.
2020 This set of directories is intended to work in cooperation with
2023 projects that provide configuration files in their installation
2024 trees. Directories above marked with (W) are intended for
2025 installations on Windows where the prefix may point at the top
2026 of an application's installation directory. Those marked with
2027 (U) are intended for installations on UNIX platforms where the
2028 prefix is shared by multiple packages. This is merely a conven‐
2029 tion, so all (W) and (U) directories are still searched on all
2030 platforms. Directories marked with (A) are intended for instal‐
2031 lations on Apple platforms. The cmake variables
2032 CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE determine the
2033 order of preference as specified below.
2034 The set of installation prefixes is constructed using the fol‐
2037 lowing steps. If NO_DEFAULT_PATH is specified all NO_* options
2038 are enabled.
2039 1. Search paths specified in cmake-specific cache variables.
2042 These are intended to be used on the command line with a
2043 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
2044 CMAKE_PREFIX_PATH
2047 CMAKE_FRAMEWORK_PATH
2048 CMAKE_APPBUNDLE_PATH
2049 2. Search paths specified in cmake-specific environment vari‐
2051 ables. These are intended to be set in the user's shell config‐
2052 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2053 passed.
2054 <package>_DIR
2057 CMAKE_PREFIX_PATH
2058 CMAKE_FRAMEWORK_PATH
2059 CMAKE_APPBUNDLE_PATH
2060 3. Search paths specified by the HINTS option. These should be
2062 paths computed by system introspection, such as a hint provided
2063 by the location of another item already found. Hard-coded
2064 guesses should be specified with the PATHS option.
2065 4. Search the standard system environment variables. This can be
2068 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed. Path entries
2069 ending in "/bin" or "/sbin" are automatically converted to their
2070 parent directories.
2071 PATH
2074 5. Search project build trees recently configured in a CMake
2076 GUI. This can be skipped if NO_CMAKE_BUILDS_PATH is passed. It
2077 is intended for the case when a user is building multiple depen‐
2078 dent projects one after another.
2079 6. Search paths stored in the CMake user package registry. This
2082 can be skipped if NO_CMAKE_PACKAGE_REGISTRY is passed. On Win‐
2083 dows a <package> may appear under registry key
2084 HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package>
2087 as a REG_SZ value, with arbitrary name, that specifies the
2089 directory containing the package configuration file. On UNIX
2090 platforms a <package> may appear under the directory
2091 ~/.cmake/packages/<package>
2094 as a file, with arbitrary name, whose content specifies the
2096 directory containing the package configuration file. See the
2097 export(PACKAGE) command to create user package registry entries
2098 for project build trees.
2099 7. Search cmake variables defined in the Platform files for the
2102 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
2103 passed.
2104 CMAKE_SYSTEM_PREFIX_PATH
2107 CMAKE_SYSTEM_FRAMEWORK_PATH
2108 CMAKE_SYSTEM_APPBUNDLE_PATH
2109 8. Search paths stored in the CMake system package registry.
2111 This can be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is
2112 passed. On Windows a <package> may appear under registry key
2113 HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package>
2116 as a REG_SZ value, with arbitrary name, that specifies the
2118 directory containing the package configuration file. There is
2119 no system package registry on non-Windows platforms.
2120 9. Search paths specified by the PATHS option. These are typi‐
2123 cally hard-coded guesses.
2124 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2127 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
2128 following:
2129 "FIRST" - Try to find frameworks before standard
2132 libraries or headers. This is the default on Darwin.
2133 "LAST" - Try to find frameworks after standard
2134 libraries or headers.
2135 "ONLY" - Only try to find frameworks.
2136 "NEVER" - Never try to find frameworks.
2137 On Darwin or systems supporting OS X Application Bundles, the
2139 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
2140 of the following:
2141 "FIRST" - Try to find application bundles before standard
2144 programs. This is the default on Darwin.
2145 "LAST" - Try to find application bundles after standard
2146 programs.
2147 "ONLY" - Only try to find application bundles.
2148 "NEVER" - Never try to find application bundles.
2149 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
2151 directories to be prepended to all other search directories.
2152 This effectively "re-roots" the entire search under given loca‐
2153 tions. By default it is empty. It is especially useful when
2154 cross-compiling to point to the root directory of the target
2155 environment and CMake will search there too. By default at first
2156 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2157 non-rooted directories will be searched. The default behavior
2158 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.
2159 This behavior can be manually overridden on a per-call basis. By
2160 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2161 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2162 CMAKE_FIND_ROOT_PATH will not be used. If
2163 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2164 tories will be searched.
2165 The default search order is designed to be most-specific to
2168 least-specific for common use cases. Projects may override the
2169 order by simply calling the command multiple times and using the
2170 NO_* options:
2171 find_package(<package> PATHS paths... NO_DEFAULT_PATH)
2174 find_package(<package>)
2175 Once one of the calls succeeds the result variable will be set
2177 and stored in the cache so that no call will search again.
2178 Every non-REQUIRED find_package() call can be disabled by set‐
2181 ting the variable CMAKE_DISABLE_FIND_PACKAGE_<package> to TRUE.
2182 See the documentation for the CMAKE_DISABLE_FIND_PACKAGE_<pack‐
2183 age> variable for more information.
2184 When loading a find module or package configuration file
2187 find_package defines variables to provide information about the
2188 call arguments (and restores their original state before return‐
2189 ing):
2190 <package>_FIND_REQUIRED = true if REQUIRED option was given
2193 <package>_FIND_QUIETLY = true if QUIET option was given
2194 <package>_FIND_VERSION = full requested version string
2195 <package>_FIND_VERSION_MAJOR = major version if requested, else 0
2196 <package>_FIND_VERSION_MINOR = minor version if requested, else 0
2197 <package>_FIND_VERSION_PATCH = patch version if requested, else 0
2198 <package>_FIND_VERSION_TWEAK = tweak version if requested, else 0
2199 <package>_FIND_VERSION_COUNT = number of version components, 0 to 4
2200 <package>_FIND_VERSION_EXACT = true if EXACT option was given
2201 <package>_FIND_COMPONENTS = list of requested components
2202 <package>_FIND_REQUIRED_<c> = true if component <c> is required
2203 false if component <c> is optional
2204 In Module mode the loaded find module is responsible to honor
2206 the request detailed by these variables; see the find module for
2207 details. In Config mode find_package handles REQUIRED, QUIET,
2208 and version options automatically but leaves it to the package
2209 configuration file to handle components in a way that makes
2210 sense for the package. The package configuration file may set
2211 <package>_FOUND to false to tell find_package that component
2212 requirements are not satisfied.
2213 See the cmake_policy() command documentation for discussion of
2216 the NO_POLICY_SCOPE option.
2217 find_path
2220 Find the directory containing a file.
2221 find_path(<VAR> name1 [path1 path2 ...])
2223 This is the short-hand signature for the command that is suffi‐
2225 cient in many cases. It is the same as find_path(<VAR> name1
2226 [PATHS path1 path2 ...])
2227 find_path(
2230 <VAR>
2231 name | NAMES name1 [name2 ...]
2232 [HINTS path1 [path2 ... ENV var]]
2233 [PATHS path1 [path2 ... ENV var]]
2234 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2235 [DOC "cache documentation string"]
2236 [NO_DEFAULT_PATH]
2237 [NO_CMAKE_ENVIRONMENT_PATH]
2238 [NO_CMAKE_PATH]
2239 [NO_SYSTEM_ENVIRONMENT_PATH]
2240 [NO_CMAKE_SYSTEM_PATH]
2241 [CMAKE_FIND_ROOT_PATH_BOTH |
2242 ONLY_CMAKE_FIND_ROOT_PATH |
2243 NO_CMAKE_FIND_ROOT_PATH]
2244 )
2245 This command is used to find a directory containing the named
2247 file. A cache entry named by <VAR> is created to store the
2248 result of this command. If the file in a directory is found the
2249 result is stored in the variable and the search will not be
2250 repeated unless the variable is cleared. If nothing is found,
2251 the result will be <VAR>-NOTFOUND, and the search will be
2252 attempted again the next time find_path is invoked with the same
2253 variable. The name of the file in a directory that is searched
2254 for is specified by the names listed after the NAMES argument.
2255 Additional search locations can be specified after the PATHS
2256 argument. If ENV var is found in the HINTS or PATHS section the
2257 environment variable var will be read and converted from a sys‐
2258 tem environment variable to a cmake style list of paths. For
2259 example ENV PATH would be a way to list the system path vari‐
2260 able. The argument after DOC will be used for the documentation
2261 string in the cache. PATH_SUFFIXES specifies additional subdi‐
2262 rectories to check below each search path.
2263 If NO_DEFAULT_PATH is specified, then no additional paths are
2266 added to the search. If NO_DEFAULT_PATH is not specified, the
2267 search process is as follows:
2268 1. Search paths specified in cmake-specific cache variables.
2271 These are intended to be used on the command line with a
2272 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
2273 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2276 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2277 CMAKE_INCLUDE_PATH
2278 CMAKE_FRAMEWORK_PATH
2279 2. Search paths specified in cmake-specific environment vari‐
2281 ables. These are intended to be set in the user's shell config‐
2282 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2283 passed.
2284 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2287 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2288 CMAKE_INCLUDE_PATH
2289 CMAKE_FRAMEWORK_PATH
2290 3. Search the paths specified by the HINTS option. These should
2292 be paths computed by system introspection, such as a hint pro‐
2293 vided by the location of another item already found. Hard-coded
2294 guesses should be specified with the PATHS option.
2295 4. Search the standard system environment variables. This can be
2298 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2299 PATH
2302 INCLUDE
2303 5. Search cmake variables defined in the Platform files for the
2305 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
2306 passed.
2307 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2310 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2311 CMAKE_SYSTEM_INCLUDE_PATH
2312 CMAKE_SYSTEM_FRAMEWORK_PATH
2313 6. Search the paths specified by the PATHS option or in the
2315 short-hand version of the command. These are typically
2316 hard-coded guesses.
2317 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2320 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
2321 following:
2322 "FIRST" - Try to find frameworks before standard
2325 libraries or headers. This is the default on Darwin.
2326 "LAST" - Try to find frameworks after standard
2327 libraries or headers.
2328 "ONLY" - Only try to find frameworks.
2329 "NEVER" - Never try to find frameworks.
2330 On Darwin or systems supporting OS X Application Bundles, the
2332 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
2333 of the following:
2334 "FIRST" - Try to find application bundles before standard
2337 programs. This is the default on Darwin.
2338 "LAST" - Try to find application bundles after standard
2339 programs.
2340 "ONLY" - Only try to find application bundles.
2341 "NEVER" - Never try to find application bundles.
2342 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
2344 directories to be prepended to all other search directories.
2345 This effectively "re-roots" the entire search under given loca‐
2346 tions. By default it is empty. It is especially useful when
2347 cross-compiling to point to the root directory of the target
2348 environment and CMake will search there too. By default at first
2349 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2350 non-rooted directories will be searched. The default behavior
2351 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
2352 This behavior can be manually overridden on a per-call basis. By
2353 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2354 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2355 CMAKE_FIND_ROOT_PATH will not be used. If
2356 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2357 tories will be searched.
2358 The default search order is designed to be most-specific to
2361 least-specific for common use cases. Projects may override the
2362 order by simply calling the command multiple times and using the
2363 NO_* options:
2364 find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2367 find_path(<VAR> NAMES name)
2368 Once one of the calls succeeds the result variable will be set
2370 and stored in the cache so that no call will search again.
2371 When searching for frameworks, if the file is specified as
2374 A/b.h, then the framework search will look for A.framework/Head‐
2375 ers/b.h. If that is found the path will be set to the path to
2376 the framework. CMake will convert this to the correct -F option
2377 to include the file.
2378 find_program
2381 Find an executable program.
2382 find_program(<VAR> name1 [path1 path2 ...])
2384 This is the short-hand signature for the command that is suffi‐
2386 cient in many cases. It is the same as find_program(<VAR> name1
2387 [PATHS path1 path2 ...])
2388 find_program(
2391 <VAR>
2392 name | NAMES name1 [name2 ...]
2393 [HINTS path1 [path2 ... ENV var]]
2394 [PATHS path1 [path2 ... ENV var]]
2395 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2396 [DOC "cache documentation string"]
2397 [NO_DEFAULT_PATH]
2398 [NO_CMAKE_ENVIRONMENT_PATH]
2399 [NO_CMAKE_PATH]
2400 [NO_SYSTEM_ENVIRONMENT_PATH]
2401 [NO_CMAKE_SYSTEM_PATH]
2402 [CMAKE_FIND_ROOT_PATH_BOTH |
2403 ONLY_CMAKE_FIND_ROOT_PATH |
2404 NO_CMAKE_FIND_ROOT_PATH]
2405 )
2406 This command is used to find a program. A cache entry named by
2408 <VAR> is created to store the result of this command. If the
2409 program is found the result is stored in the variable and the
2410 search will not be repeated unless the variable is cleared. If
2411 nothing is found, the result will be <VAR>-NOTFOUND, and the
2412 search will be attempted again the next time find_program is
2413 invoked with the same variable. The name of the program that is
2414 searched for is specified by the names listed after the NAMES
2415 argument. Additional search locations can be specified after
2416 the PATHS argument. If ENV var is found in the HINTS or PATHS
2417 section the environment variable var will be read and converted
2418 from a system environment variable to a cmake style list of
2419 paths. For example ENV PATH would be a way to list the system
2420 path variable. The argument after DOC will be used for the docu‐
2421 mentation string in the cache. PATH_SUFFIXES specifies addi‐
2422 tional subdirectories to check below each search path.
2423 If NO_DEFAULT_PATH is specified, then no additional paths are
2426 added to the search. If NO_DEFAULT_PATH is not specified, the
2427 search process is as follows:
2428 1. Search paths specified in cmake-specific cache variables.
2431 These are intended to be used on the command line with a
2432 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
2433 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2436 CMAKE_PROGRAM_PATH
2437 CMAKE_APPBUNDLE_PATH
2438 2. Search paths specified in cmake-specific environment vari‐
2440 ables. These are intended to be set in the user's shell config‐
2441 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2442 passed.
2443 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2446 CMAKE_PROGRAM_PATH
2447 CMAKE_APPBUNDLE_PATH
2448 3. Search the paths specified by the HINTS option. These should
2450 be paths computed by system introspection, such as a hint pro‐
2451 vided by the location of another item already found. Hard-coded
2452 guesses should be specified with the PATHS option.
2453 4. Search the standard system environment variables. This can be
2456 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2457 PATH
2460 5. Search cmake variables defined in the Platform files for the
2463 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
2464 passed.
2465 <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2468 CMAKE_SYSTEM_PROGRAM_PATH
2469 CMAKE_SYSTEM_APPBUNDLE_PATH
2470 6. Search the paths specified by the PATHS option or in the
2472 short-hand version of the command. These are typically
2473 hard-coded guesses.
2474 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2477 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
2478 following:
2479 "FIRST" - Try to find frameworks before standard
2482 libraries or headers. This is the default on Darwin.
2483 "LAST" - Try to find frameworks after standard
2484 libraries or headers.
2485 "ONLY" - Only try to find frameworks.
2486 "NEVER" - Never try to find frameworks.
2487 On Darwin or systems supporting OS X Application Bundles, the
2489 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
2490 of the following:
2491 "FIRST" - Try to find application bundles before standard
2494 programs. This is the default on Darwin.
2495 "LAST" - Try to find application bundles after standard
2496 programs.
2497 "ONLY" - Only try to find application bundles.
2498 "NEVER" - Never try to find application bundles.
2499 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
2501 directories to be prepended to all other search directories.
2502 This effectively "re-roots" the entire search under given loca‐
2503 tions. By default it is empty. It is especially useful when
2504 cross-compiling to point to the root directory of the target
2505 environment and CMake will search there too. By default at first
2506 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2507 non-rooted directories will be searched. The default behavior
2508 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.
2509 This behavior can be manually overridden on a per-call basis. By
2510 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2511 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2512 CMAKE_FIND_ROOT_PATH will not be used. If
2513 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2514 tories will be searched.
2515 The default search order is designed to be most-specific to
2518 least-specific for common use cases. Projects may override the
2519 order by simply calling the command multiple times and using the
2520 NO_* options:
2521 find_program(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2524 find_program(<VAR> NAMES name)
2525 Once one of the calls succeeds the result variable will be set
2527 and stored in the cache so that no call will search again.
2528 fltk_wrap_ui
2531 Create FLTK user interfaces Wrappers.
2532 fltk_wrap_ui(resultingLibraryName source1
2534 source2 ... sourceN )
2535 Produce .h and .cxx files for all the .fl and .fld files listed.
2537 The resulting .h and .cxx files will be added to a variable
2538 named resultingLibraryName_FLTK_UI_SRCS which should be added to
2539 your library.
2540 foreach
2543 Evaluate a group of commands for each value in a list.
2544 foreach(loop_var arg1 arg2 ...)
2546 COMMAND1(ARGS ...)
2547 COMMAND2(ARGS ...)
2548 ...
2549 endforeach(loop_var)
2550 All commands between foreach and the matching endforeach are
2552 recorded without being invoked. Once the endforeach is evalu‐
2553 ated, the recorded list of commands is invoked once for each
2554 argument listed in the original foreach command. Before each
2555 iteration of the loop "${loop_var}" will be set as a variable
2556 with the current value in the list.
2557 foreach(loop_var RANGE total)
2560 foreach(loop_var RANGE start stop [step])
2561 Foreach can also iterate over a generated range of numbers.
2563 There are three types of this iteration:
2564 * When specifying single number, the range will have elements 0
2567 to "total".
2568 * When specifying two numbers, the range will have elements from
2571 the first number to the second number.
2572 * The third optional number is the increment used to iterate
2575 from the first number to the second number.
2576 foreach(loop_var IN [LISTS [list1 [...]]]
2579 [ITEMS [item1 [...]]])
2580 Iterates over a precise list of items. The LISTS option names
2582 list-valued variables to be traversed, including empty elements
2583 (an empty string is a zero-length list). The ITEMS option ends
2584 argument parsing and includes all arguments following it in the
2585 iteration.
2586 function
2589 Start recording a function for later invocation as a command.
2590 function(<name> [arg1 [arg2 [arg3 ...]]])
2592 COMMAND1(ARGS ...)
2593 COMMAND2(ARGS ...)
2594 ...
2595 endfunction(<name>)
2596 Define a function named <name> that takes arguments named arg1
2598 arg2 arg3 (...). Commands listed after function, but before the
2599 matching endfunction, are not invoked until the function is
2600 invoked. When it is invoked, the commands recorded in the func‐
2601 tion are first modified by replacing formal parameters (${arg1})
2602 with the arguments passed, and then invoked as normal commands.
2603 In addition to referencing the formal parameters you can refer‐
2604 ence the variable ARGC which will be set to the number of argu‐
2605 ments passed into the function as well as ARGV0 ARGV1 ARGV2 ...
2606 which will have the actual values of the arguments passed in.
2607 This facilitates creating functions with optional arguments.
2608 Additionally ARGV holds the list of all arguments given to the
2609 function and ARGN holds the list of arguments past the last
2610 expected argument.
2611 A function opens a new scope: see set(var PARENT_SCOPE) for
2614 details.
2615 See the cmake_policy() command documentation for the behavior of
2618 policies inside functions.
2619 get_cmake_property
2622 Get a property of the CMake instance.
2623 get_cmake_property(VAR property)
2625 Get a property from the CMake instance. The value of the prop‐
2627 erty is stored in the variable VAR. If the property is not
2628 found, VAR will be set to "NOTFOUND". Some supported properties
2629 include: VARIABLES, CACHE_VARIABLES, COMMANDS, MACROS, and COM‐
2630 PONENTS.
2631 See also the more general get_property() command.
2634 get_directory_property
2637 Get a property of DIRECTORY scope.
2638 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
2640 Store a property of directory scope in the named variable. If
2642 the property is not defined the empty-string is returned. The
2643 DIRECTORY argument specifies another directory from which to
2644 retrieve the property value. The specified directory must have
2645 already been traversed by CMake.
2646 get_directory_property(<variable> [DIRECTORY <dir>]
2649 DEFINITION <var-name>)
2650 Get a variable definition from a directory. This form is useful
2652 to get a variable definition from another directory.
2653 See also the more general get_property() command.
2656 get_filename_component
2659 Get a specific component of a full filename.
2660 get_filename_component(<VAR> <FileName> <COMP> [CACHE])
2662 Set <VAR> to a component of <FileName>, where <COMP> is one of:
2664 DIRECTORY = Directory without file name
2667 NAME = File name without directory
2668 EXT = File name longest extension (.b.c from d/a.b.c)
2669 NAME_WE = File name without directory or longest extension
2670 ABSOLUTE = Full path to file
2671 REALPATH = Full path to existing file with symlinks resolved
2672 PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
2673 Paths are returned with forward slashes and have no trailing
2675 slahes. The longest file extension is always considered. If the
2676 optional CACHE argument is specified, the result variable is
2677 added to the cache.
2678 get_filename_component(<VAR> FileName
2681 PROGRAM [PROGRAM_ARGS <ARG_VAR>]
2682 [CACHE])
2683 The program in FileName will be found in the system search path
2685 or left as a full path. If PROGRAM_ARGS is present with PRO‐
2686 GRAM, then any command-line arguments present in the FileName
2687 string are split from the program name and stored in <ARG_VAR>.
2688 This is used to separate a program name from its arguments in a
2689 command line string.
2690 get_property
2693 Get a property.
2694 get_property(<variable>
2696 <GLOBAL |
2697 DIRECTORY [dir] |
2698 TARGET <target> |
2699 SOURCE <source> |
2700 TEST <test> |
2701 CACHE <entry> |
2702 VARIABLE>
2703 PROPERTY <name>
2704 [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
2705 Get one property from one object in a scope. The first argument
2707 specifies the variable in which to store the result. The second
2708 argument determines the scope from which to get the property.
2709 It must be one of the following:
2710 GLOBAL scope is unique and does not accept a name.
2713 DIRECTORY scope defaults to the current directory but another
2716 directory (already processed by CMake) may be named by full or
2717 relative path.
2718 TARGET scope must name one existing target.
2721 SOURCE scope must name one source file.
2724 TEST scope must name one existing test.
2727 CACHE scope must name one cache entry.
2730 VARIABLE scope is unique and does not accept a name.
2733 The required PROPERTY option is immediately followed by the name
2736 of the property to get. If the property is not set an empty
2737 value is returned. If the SET option is given the variable is
2738 set to a boolean value indicating whether the property has been
2739 set. If the DEFINED option is given the variable is set to a
2740 boolean value indicating whether the property has been defined
2741 such as with define_property. If BRIEF_DOCS or FULL_DOCS is
2742 given then the variable is set to a string containing documenta‐
2743 tion for the requested property. If documentation is requested
2744 for a property that has not been defined NOTFOUND is returned.
2745 get_source_file_property
2748 Get a property for a source file.
2749 get_source_file_property(VAR file property)
2751 Get a property from a source file. The value of the property is
2753 stored in the variable VAR. If the property is not found, VAR
2754 will be set to "NOTFOUND". Use set_source_files_properties to
2755 set property values. Source file properties usually control how
2756 the file is built. One property that is always there is LOCATION
2757 See also the more general get_property() command.
2760 get_target_property
2763 Get a property from a target.
2764 get_target_property(VAR target property)
2766 Get a property from a target. The value of the property is
2768 stored in the variable VAR. If the property is not found, VAR
2769 will be set to "NOTFOUND". Use set_target_properties to set
2770 property values. Properties are usually used to control how a
2771 target is built, but some query the target instead. This com‐
2772 mand can get properties for any target so far created. The tar‐
2773 gets do not need to be in the current CMakeLists.txt file.
2774 See also the more general get_property() command.
2777 get_test_property
2780 Get a property of the test.
2781 get_test_property(test property VAR)
2783 Get a property from the Test. The value of the property is
2785 stored in the variable VAR. If the property is not found, VAR
2786 will be set to "NOTFOUND". For a list of standard properties you
2787 can type cmake --help-property-list
2788 See also the more general get_property() command.
2791 if Conditionally execute a group of commands.
2794 if(expression)
2796 # then section.
2797 COMMAND1(ARGS ...)
2798 COMMAND2(ARGS ...)
2799 ...
2800 elseif(expression2)
2801 # elseif section.
2802 COMMAND1(ARGS ...)
2803 COMMAND2(ARGS ...)
2804 ...
2805 else(expression)
2806 # else section.
2807 COMMAND1(ARGS ...)
2808 COMMAND2(ARGS ...)
2809 ...
2810 endif(expression)
2811 Evaluates the given expression. If the result is true, the com‐
2813 mands in the THEN section are invoked. Otherwise, the commands
2814 in the else section are invoked. The elseif and else sections
2815 are optional. You may have multiple elseif clauses. Note that
2816 the expression in the else and endif clause is optional. Long
2817 expressions can be used and there is a traditional order of
2818 precedence. Parenthetical expressions are evaluated first fol‐
2819 lowed by unary operators such as EXISTS, COMMAND, and DEFINED.
2820 Then any EQUAL, LESS, GREATER, STRLESS, STRGREATER, STREQUAL,
2821 MATCHES will be evaluated. Then NOT operators and finally AND,
2822 OR operators will be evaluated. Possible expressions are:
2823 if(<constant>)
2826 True if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
2828 ber. False if the constant is 0, OFF, NO, FALSE, N, IGNORE,
2829 NOTFOUND, '', or ends in the suffix '-NOTFOUND'. Named boolean
2830 constants are case-insensitive. If the argument is not one of
2831 these constants, it is treated as a variable:
2832 if(<variable>)
2835 True if the variable is defined to a value that is not a false
2837 constant. False otherwise. (Note macro arguments are not vari‐
2838 ables.)
2839 if(NOT <expression>)
2842 True if the expression is not true.
2844 if(<expr1> AND <expr2>)
2847 True if both expressions would be considered true individually.
2849 if(<expr1> OR <expr2>)
2852 True if either expression would be considered true individually.
2854 if(COMMAND command-name)
2857 True if the given name is a command, macro or function that can
2859 be invoked.
2860 if(POLICY policy-id)
2863 True if the given name is an existing policy (of the form
2865 CMP<NNNN>).
2866 if(TARGET target-name)
2869 True if the given name is an existing target, built or imported.
2871 if(EXISTS file-name)
2874 if(EXISTS directory-name)
2875 True if the named file or directory exists. Behavior is
2877 well-defined only for full paths.
2878 if(file1 IS_NEWER_THAN file2)
2881 True if file1 is newer than file2 or if one of the two files
2883 doesn't exist. Behavior is well-defined only for full paths. If
2884 the file time stamps are exactly the same, an IS_NEWER_THAN com‐
2885 parison returns true, so that any dependent build operations
2886 will occur in the event of a tie. This includes the case of
2887 passing the same file name for both file1 and file2.
2888 if(IS_DIRECTORY directory-name)
2891 True if the given name is a directory. Behavior is well-defined
2893 only for full paths.
2894 if(IS_SYMLINK file-name)
2897 True if the given name is a symbolic link. Behavior is
2899 well-defined only for full paths.
2900 if(IS_ABSOLUTE path)
2903 True if the given path is an absolute path.
2905 if(<variable|string> MATCHES regex)
2908 True if the given string or variable's value matches the given
2910 regular expression.
2911 if(<variable|string> LESS <variable|string>)
2914 if(<variable|string> GREATER <variable|string>)
2915 if(<variable|string> EQUAL <variable|string>)
2916 True if the given string or variable's value is a valid number
2918 and the inequality or equality is true.
2919 if(<variable|string> STRLESS <variable|string>)
2922 if(<variable|string> STRGREATER <variable|string>)
2923 if(<variable|string> STREQUAL <variable|string>)
2924 True if the given string or variable's value is lexicographi‐
2926 cally less (or greater, or equal) than the string or variable on
2927 the right.
2928 if(<variable|string> VERSION_LESS <variable|string>)
2931 if(<variable|string> VERSION_EQUAL <variable|string>)
2932 if(<variable|string> VERSION_GREATER <variable|string>)
2933 Component-wise integer version number comparison (version format
2935 is major[.minor[.patch[.tweak]]]).
2936 if(DEFINED <variable>)
2939 True if the given variable is defined. It does not matter if the
2941 variable is true or false just if it has been set.
2942 if((expression) AND (expression OR (expression)))
2945 The expressions inside the parenthesis are evaluated first and
2947 then the remaining expression is evaluated as in the previous
2948 examples. Where there are nested parenthesis the innermost are
2949 evaluated as part of evaluating the expression that contains
2950 them.
2951 The if command was written very early in CMake's history, pre‐
2954 dating the ${} variable evaluation syntax, and for convenience
2955 evaluates variables named by its arguments as shown in the above
2956 signatures. Note that normal variable evaluation with ${}
2957 applies before the if command even receives the arguments.
2958 Therefore code like
2959 set(var1 OFF)
2962 set(var2 "var1")
2963 if(${var2})
2964 appears to the if command as
2966 if(var1)
2969 and is evaluated according to the if(<variable>) case documented
2971 above. The result is OFF which is false. However, if we remove
2972 the ${} from the example then the command sees
2973 if(var2)
2976 which is true because var2 is defined to "var1" which is not a
2978 false constant.
2979 Automatic evaluation applies in the other cases whenever the
2982 above-documented signature accepts <variable|string>:
2983 1) The left hand argument to MATCHES is first checked to see if
2986 it is a defined variable, if so the variable's value is used,
2987 otherwise the original value is used.
2988 2) If the left hand argument to MATCHES is missing it returns
2991 false without error
2992 3) Both left and right hand arguments to LESS GREATER EQUAL are
2995 independently tested to see if they are defined variables, if so
2996 their defined values are used otherwise the original value is
2997 used.
2998 4) Both left and right hand arguments to STRLESS STREQUAL STR‐
3001 GREATER are independently tested to see if they are defined
3002 variables, if so their defined values are used otherwise the
3003 original value is used.
3004 5) Both left and right hand argumemnts to VERSION_LESS VER‐
3007 SION_EQUAL VERSION_GREATER are independently tested to see if
3008 they are defined variables, if so their defined values are used
3009 otherwise the original value is used.
3010 6) The right hand argument to NOT is tested to see if it is a
3013 boolean constant, if so the value is used, otherwise it is
3014 assumed to be a variable and it is dereferenced.
3015 7) The left and right hand arguments to AND OR are independently
3018 tested to see if they are boolean constants, if so they are used
3019 as such, otherwise they are assumed to be variables and are
3020 dereferenced.
3021 include
3025 Load and run CMake code from a file or module.
3026 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
3028 [NO_POLICY_SCOPE])
3029 Load and run CMake code from the file given. Variable reads and
3031 writes access the scope of the caller (dynamic scoping). If
3032 OPTIONAL is present, then no error is raised if the file does
3033 not exist. If RESULT_VARIABLE is given the variable will be set
3034 to the full filename which has been included or NOTFOUND if it
3035 failed.
3036 If a module is specified instead of a file, the file with name
3039 <modulename>.cmake is searched first in CMAKE_MODULE_PATH, then
3040 in the CMake module directory. There is one exception to this:
3041 if the file which calls include() is located itself in the CMake
3042 module directory, then first the CMake module directory is
3043 searched and CMAKE_MODULE_PATH afterwards. See also policy
3044 CMP0017.
3045 See the cmake_policy() command documentation for discussion of
3048 the NO_POLICY_SCOPE option.
3049 include_directories
3052 Add include directories to the build.
3053 include_directories([AFTER|BEFORE] [SYSTEM] dir1 dir2 ...)
3055 Add the given directories to those the compiler uses to search
3057 for include files. Relative paths are interpreted as relative
3058 to the current source directory.
3059 The include directories are added to the directory property
3062 INCLUDE_DIRECTORIES for the current CMakeLists file. They are
3063 also added to the target property INCLUDE_DIRECTORIES for each
3064 target in the current CMakeLists file. The target property val‐
3065 ues are the ones used by the generators.
3066 By default the directories are appended onto the current list of
3069 directories. This default behavior can be changed by setting
3070 CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE
3071 explicitly, you can select between appending and prepending,
3072 independent of the default.
3073 If the SYSTEM option is given, the compiler will be told the
3076 directories are meant as system include directories on some
3077 platforms (signalling this setting might achieve effects such as
3078 the compiler skipping warnings, or these fixed-install system
3079 files not being considered in dependency calculations - see com‐
3080 piler docs).
3081 include_external_msproject
3084 Include an external Microsoft project file in a workspace.
3085 include_external_msproject(projectname location
3087 [TYPE projectTypeGUID]
3088 [GUID projectGUID]
3089 [PLATFORM platformName]
3090 dep1 dep2 ...)
3091 Includes an external Microsoft project in the generated
3093 workspace file. Currently does nothing on UNIX. This will cre‐
3094 ate a target named [projectname]. This can be used in the
3095 add_dependencies command to make things depend on the external
3096 project.
3097 TYPE, GUID and PLATFORM are optional parameters that allow one
3100 to specify the type of project, id (GUID) of the project and the
3101 name of the target platform. This is useful for projects
3102 requiring values other than the default (e.g. WIX projects).
3103 These options are not supported by the Visual Studio 6 genera‐
3104 tor.
3105 include_regular_expression
3108 Set the regular expression used for dependency checking.
3109 include_regular_expression(regex_match [regex_complain])
3111 Set the regular expressions used in dependency checking. Only
3113 files matching regex_match will be traced as dependencies. Only
3114 files matching regex_complain will generate warnings if they
3115 cannot be found (standard header paths are not searched). The
3116 defaults are:
3117 regex_match = "^.*$" (match everything)
3120 regex_complain = "^$" (match empty string only)
3121 install
3124 Specify rules to run at install time.
3125 This command generates installation rules for a project. Rules
3127 specified by calls to this command within a source directory are
3128 executed in order during installation. The order across direc‐
3129 tories is not defined.
3130 There are multiple signatures for this command. Some of them
3133 define installation properties for files and targets. Proper‐
3134 ties common to multiple signatures are covered here but they are
3135 valid only for signatures that specify them.
3136 DESTINATION arguments specify the directory on disk to which a
3139 file will be installed. If a full path (with a leading slash or
3140 drive letter) is given it is used directly. If a relative path
3141 is given it is interpreted relative to the value of
3142 CMAKE_INSTALL_PREFIX. The prefix can be relocated at install
3143 time using DESTDIR mechanism explained in the CMAKE_INSTALL_PRE‐
3144 FIX variable documentation.
3145 PERMISSIONS arguments specify permissions for installed files.
3148 Valid permissions are OWNER_READ, OWNER_WRITE, OWNER_EXECUTE,
3149 GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE,
3150 WORLD_EXECUTE, SETUID, and SETGID. Permissions that do not make
3151 sense on certain platforms are ignored on those platforms.
3152 The CONFIGURATIONS argument specifies a list of build configura‐
3155 tions for which the install rule applies (Debug, Release, etc.).
3156 The COMPONENT argument specifies an installation component name
3159 with which the install rule is associated, such as "runtime" or
3160 "development". During component-specific installation only
3161 install rules associated with the given component name will be
3162 executed. During a full installation all components are
3163 installed. If COMPONENT is not provided a default component
3164 "Unspecified" is created. The default component name may be con‐
3165 trolled with the CMAKE_INSTALL_DEFAULT_COMPONENT_NAME variable.
3166 The RENAME argument specifies a name for an installed file that
3169 may be different from the original file. Renaming is allowed
3170 only when a single file is installed by the command.
3171 The OPTIONAL argument specifies that it is not an error if the
3174 file to be installed does not exist.
3175 The TARGETS signature:
3178 install(TARGETS targets... [EXPORT <export-name>]
3181 [[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE|
3182 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
3183 [DESTINATION <dir>]
3184 [INCLUDES DESTINATION [<dir> ...]]
3185 [PERMISSIONS permissions...]
3186 [CONFIGURATIONS [Debug|Release|...]]
3187 [COMPONENT <component>]
3188 [OPTIONAL] [NAMELINK_ONLY|NAMELINK_SKIP]
3189 ] [...])
3190 The TARGETS form specifies rules for installing targets from a
3192 project. There are five kinds of target files that may be
3193 installed: ARCHIVE, LIBRARY, RUNTIME, FRAMEWORK, and BUNDLE.
3194 Executables are treated as RUNTIME targets, except that those
3195 marked with the MACOSX_BUNDLE property are treated as BUNDLE
3196 targets on OS X. Static libraries are always treated as ARCHIVE
3197 targets. Module libraries are always treated as LIBRARY targets.
3198 For non-DLL platforms shared libraries are treated as LIBRARY
3199 targets, except that those marked with the FRAMEWORK property
3200 are treated as FRAMEWORK targets on OS X. For DLL platforms the
3201 DLL part of a shared library is treated as a RUNTIME target and
3202 the corresponding import library is treated as an ARCHIVE tar‐
3203 get. All Windows-based systems including Cygwin are DLL plat‐
3204 forms. The ARCHIVE, LIBRARY, RUNTIME, and FRAMEWORK arguments
3205 change the type of target to which the subsequent properties
3206 apply. If none is given the installation properties apply to
3207 all target types. If only one is given then only targets of
3208 that type will be installed (which can be used to install just a
3209 DLL or just an import library).The INCLUDES DESTINATION speci‐
3210 fies a list of directories which will be added to the INTER‐
3211 FACE_INCLUDE_DIRECTORIES of the <targets> when exported by
3212 install(EXPORT). If a relative path is specified, it is treated
3213 as relative to the $<INSTALL_PREFIX>.
3214 The PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE arguments cause
3217 subsequent properties to be applied to installing a FRAMEWORK
3218 shared library target's associated files on non-Apple platforms.
3219 Rules defined by these arguments are ignored on Apple platforms
3220 because the associated files are installed into the appropriate
3221 locations inside the framework folder. See documentation of the
3222 PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE target properties
3223 for details.
3224 Either NAMELINK_ONLY or NAMELINK_SKIP may be specified as a
3227 LIBRARY option. On some platforms a versioned shared library
3228 has a symbolic link such as
3229 lib<name>.so -> lib<name>.so.1
3232 where "lib<name>.so.1" is the soname of the library and
3234 "lib<name>.so" is a "namelink" allowing linkers to find the
3235 library when given "-l<name>". The NAMELINK_ONLY option causes
3236 installation of only the namelink when a library target is
3237 installed. The NAMELINK_SKIP option causes installation of
3238 library files other than the namelink when a library target is
3239 installed. When neither option is given both portions are
3240 installed. On platforms where versioned shared libraries do not
3241 have namelinks or when a library is not versioned the
3242 NAMELINK_SKIP option installs the library and the NAMELINK_ONLY
3243 option installs nothing. See the VERSION and SOVERSION target
3244 properties for details on creating versioned shared libraries.
3245 One or more groups of properties may be specified in a single
3248 call to the TARGETS form of this command. A target may be
3249 installed more than once to different locations. Consider hypo‐
3250 thetical targets "myExe", "mySharedLib", and "myStaticLib". The
3251 code
3252 install(TARGETS myExe mySharedLib myStaticLib
3255 RUNTIME DESTINATION bin
3256 LIBRARY DESTINATION lib
3257 ARCHIVE DESTINATION lib/static)
3258 install(TARGETS mySharedLib DESTINATION /some/full/path)
3259 will install myExe to <prefix>/bin and myStaticLib to <pre‐
3261 fix>/lib/static. On non-DLL platforms mySharedLib will be
3262 installed to <prefix>/lib and /some/full/path. On DLL platforms
3263 the mySharedLib DLL will be installed to <prefix>/bin and
3264 /some/full/path and its import library will be installed to
3265 <prefix>/lib/static and /some/full/path.
3266 The EXPORT option associates the installed target files with an
3269 export called <export-name>. It must appear before any RUNTIME,
3270 LIBRARY, or ARCHIVE options. To actually install the export
3271 file itself, call install(EXPORT). See documentation of the
3272 install(EXPORT ...) signature below for details.
3273 Installing a target with EXCLUDE_FROM_ALL set to true has unde‐
3276 fined behavior.
3277 The FILES signature:
3280 install(FILES files... DESTINATION <dir>
3283 [PERMISSIONS permissions...]
3284 [CONFIGURATIONS [Debug|Release|...]]
3285 [COMPONENT <component>]
3286 [RENAME <name>] [OPTIONAL])
3287 The FILES form specifies rules for installing files for a
3289 project. File names given as relative paths are interpreted
3290 with respect to the current source directory. Files installed
3291 by this form are by default given permissions OWNER_WRITE,
3292 OWNER_READ, GROUP_READ, and WORLD_READ if no PERMISSIONS argu‐
3293 ment is given.
3294 The PROGRAMS signature:
3297 install(PROGRAMS files... DESTINATION <dir>
3300 [PERMISSIONS permissions...]
3301 [CONFIGURATIONS [Debug|Release|...]]
3302 [COMPONENT <component>]
3303 [RENAME <name>] [OPTIONAL])
3304 The PROGRAMS form is identical to the FILES form except that the
3306 default permissions for the installed file also include
3307 OWNER_EXECUTE, GROUP_EXECUTE, and WORLD_EXECUTE. This form is
3308 intended to install programs that are not targets, such as shell
3309 scripts. Use the TARGETS form to install targets built within
3310 the project.
3311 The DIRECTORY signature:
3314 install(DIRECTORY dirs... DESTINATION <dir>
3317 [FILE_PERMISSIONS permissions...]
3318 [DIRECTORY_PERMISSIONS permissions...]
3319 [USE_SOURCE_PERMISSIONS] [OPTIONAL]
3320 [CONFIGURATIONS [Debug|Release|...]]
3321 [COMPONENT <component>] [FILES_MATCHING]
3322 [[PATTERN <pattern> | REGEX <regex>]
3323 [EXCLUDE] [PERMISSIONS permissions...]] [...])
3324 The DIRECTORY form installs contents of one or more directories
3326 to a given destination. The directory structure is copied ver‐
3327 batim to the destination. The last component of each directory
3328 name is appended to the destination directory but a trailing
3329 slash may be used to avoid this because it leaves the last com‐
3330 ponent empty. Directory names given as relative paths are
3331 interpreted with respect to the current source directory. If no
3332 input directory names are given the destination directory will
3333 be created but nothing will be installed into it. The FILE_PER‐
3334 MISSIONS and DIRECTORY_PERMISSIONS options specify permissions
3335 given to files and directories in the destination. If
3336 USE_SOURCE_PERMISSIONS is specified and FILE_PERMISSIONS is not,
3337 file permissions will be copied from the source directory struc‐
3338 ture. If no permissions are specified files will be given the
3339 default permissions specified in the FILES form of the command,
3340 and the directories will be given the default permissions speci‐
3341 fied in the PROGRAMS form of the command.
3342 Installation of directories may be controlled with fine granu‐
3345 larity using the PATTERN or REGEX options. These "match"
3346 options specify a globbing pattern or regular expression to
3347 match directories or files encountered within input directories.
3348 They may be used to apply certain options (see below) to a sub‐
3349 set of the files and directories encountered. The full path to
3350 each input file or directory (with forward slashes) is matched
3351 against the expression. A PATTERN will match only complete file
3352 names: the portion of the full path matching the pattern must
3353 occur at the end of the file name and be preceded by a slash. A
3354 REGEX will match any portion of the full path but it may use '/'
3355 and '$' to simulate the PATTERN behavior. By default all files
3356 and directories are installed whether or not they are matched.
3357 The FILES_MATCHING option may be given before the first match
3358 option to disable installation of files (but not directories)
3359 not matched by any expression. For example, the code
3360 install(DIRECTORY src/ DESTINATION include/myproj
3363 FILES_MATCHING PATTERN "*.h")
3364 will extract and install header files from a source tree.
3366 Some options may follow a PATTERN or REGEX expression and are
3369 applied only to files or directories matching them. The EXCLUDE
3370 option will skip the matched file or directory. The PERMISSIONS
3371 option overrides the permissions setting for the matched file or
3372 directory. For example the code
3373 install(DIRECTORY icons scripts/ DESTINATION share/myproj
3376 PATTERN "CVS" EXCLUDE
3377 PATTERN "scripts/*"
3378 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
3379 GROUP_EXECUTE GROUP_READ)
3380 will install the icons directory to share/myproj/icons and the
3382 scripts directory to share/myproj. The icons will get default
3383 file permissions, the scripts will be given specific permis‐
3384 sions, and any CVS directories will be excluded.
3385 The SCRIPT and CODE signature:
3388 install([[SCRIPT <file>] [CODE <code>]] [...])
3391 The SCRIPT form will invoke the given CMake script files during
3393 installation. If the script file name is a relative path it
3394 will be interpreted with respect to the current source direc‐
3395 tory. The CODE form will invoke the given CMake code during
3396 installation. Code is specified as a single argument inside a
3397 double-quoted string. For example, the code
3398 install(CODE "MESSAGE(\"Sample install message.\")")
3401 will print a message during installation.
3403 The EXPORT signature:
3406 install(EXPORT <export-name> DESTINATION <dir>
3409 [NAMESPACE <namespace>] [FILE <name>.cmake]
3410 [PERMISSIONS permissions...]
3411 [CONFIGURATIONS [Debug|Release|...]]
3412 [EXPORT_LINK_INTERFACE_LIBRARIES]
3413 [COMPONENT <component>])
3414 The EXPORT form generates and installs a CMake file containing
3416 code to import targets from the installation tree into another
3417 project. Target installations are associated with the export
3418 <export-name> using the EXPORT option of the install(TARGETS
3419 ...) signature documented above. The NAMESPACE option will
3420 prepend <namespace> to the target names as they are written to
3421 the import file. By default the generated file will be called
3422 <export-name>.cmake but the FILE option may be used to specify a
3423 different name. The value given to the FILE option must be a
3424 file name with the ".cmake" extension. If a CONFIGURATIONS
3425 option is given then the file will only be installed when one of
3426 the named configurations is installed. Additionally, the gener‐
3427 ated import file will reference only the matching target config‐
3428 urations. The EXPORT_LINK_INTERFACE_LIBRARIES keyword, if
3429 present, causes the contents of the properties matching
3430 (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported,
3431 when policy CMP0022 is NEW. If a COMPONENT option is specified
3432 that does not match that given to the targets associated with
3433 <export-name> the behavior is undefined. If a library target is
3434 included in the export but a target to which it links is not
3435 included the behavior is unspecified.
3436 The EXPORT form is useful to help outside projects use targets
3439 built and installed by the current project. For example, the
3440 code
3441 install(TARGETS myexe EXPORT myproj DESTINATION bin)
3444 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
3445 will install the executable myexe to <prefix>/bin and code to
3447 import it in the file "<prefix>/lib/myproj/myproj.cmake". An
3448 outside project may load this file with the include command and
3449 reference the myexe executable from the installation tree using
3450 the imported target name mp_myexe as if the target were built in
3451 its own tree.
3452 NOTE: This command supercedes the INSTALL_TARGETS command and
3455 the target properties PRE_INSTALL_SCRIPT and
3456 POST_INSTALL_SCRIPT. It also replaces the FILES forms of the
3457 INSTALL_FILES and INSTALL_PROGRAMS commands. The processing
3458 order of these install rules relative to those generated by
3459 INSTALL_TARGETS, INSTALL_FILES, and INSTALL_PROGRAMS commands is
3460 not defined.
3461 link_directories
3465 Specify directories in which the linker will look for libraries.
3466 link_directories(directory1 directory2 ...)
3468 Specify the paths in which the linker should search for
3470 libraries. The command will apply only to targets created after
3471 it is called. Relative paths given to this command are inter‐
3472 preted as relative to the current source directory, see CMP0015.
3473 Note that this command is rarely necessary. Library locations
3476 returned by find_package() and find_library() are absolute
3477 paths. Pass these absolute library file paths directly to the
3478 target_link_libraries() command. CMake will ensure the linker
3479 finds them.
3480 list List operations.
3483 list(LENGTH <list> <output variable>)
3485 list(GET <list> <element index> [<element index> ...]
3486 <output variable>)
3487 list(APPEND <list> <element> [<element> ...])
3488 list(FIND <list> <value> <output variable>)
3489 list(INSERT <list> <element_index> <element> [<element> ...])
3490 list(REMOVE_ITEM <list> <value> [<value> ...])
3491 list(REMOVE_AT <list> <index> [<index> ...])
3492 list(REMOVE_DUPLICATES <list>)
3493 list(REVERSE <list>)
3494 list(SORT <list>)
3495 LENGTH will return a given list's length.
3497 GET will return list of elements specified by indices from the
3500 list.
3501 APPEND will append elements to the list.
3504 FIND will return the index of the element specified in the list
3507 or -1 if it wasn't found.
3508 INSERT will insert elements to the list to the specified loca‐
3511 tion.
3512 REMOVE_AT and REMOVE_ITEM will remove items from the list. The
3515 difference is that REMOVE_ITEM will remove the given items,
3516 while REMOVE_AT will remove the items at the given indices.
3517 REMOVE_DUPLICATES will remove duplicated items in the list.
3520 REVERSE reverses the contents of the list in-place.
3523 SORT sorts the list in-place alphabetically.
3526 The list subcommands APPEND, INSERT, REMOVE_AT, REMOVE_ITEM,
3529 REMOVE_DUPLICATES, REVERSE and SORT may create new values for
3530 the list within the current CMake variable scope. Similar to the
3531 SET command, the LIST command creates new variable values in the
3532 current scope, even if the list itself is actually defined in a
3533 parent scope. To propagate the results of these operations
3534 upwards, use SET with PARENT_SCOPE, SET with CACHE INTERNAL, or
3535 some other means of value propagation.
3536 NOTES: A list in cmake is a ; separated group of strings. To
3539 create a list the set command can be used. For example, set(var
3540 a b c d e) creates a list with a;b;c;d;e, and set(var "a b c d
3541 e") creates a string or a list with one item in it.
3542 When specifying index values, if <element index> is 0 or
3545 greater, it is indexed from the beginning of the list, with 0
3546 representing the first list element. If <element index> is -1 or
3547 lesser, it is indexed from the end of the list, with -1 repre‐
3548 senting the last list element. Be careful when counting with
3549 negative indices: they do not start from 0. -0 is equivalent to
3550 0, the first list element.
3551 load_cache
3555 Load in the values from another project's CMake cache.
3556 load_cache(pathToCacheFile READ_WITH_PREFIX
3558 prefix entry1...)
3559 Read the cache and store the requested entries in variables with
3561 their name prefixed with the given prefix. This only reads the
3562 values, and does not create entries in the local project's
3563 cache.
3564 load_cache(pathToCacheFile [EXCLUDE entry1...]
3567 [INCLUDE_INTERNALS entry1...])
3568 Load in the values from another cache and store them in the
3570 local project's cache as internal entries. This is useful for a
3571 project that depends on another project built in a different
3572 tree. EXCLUDE option can be used to provide a list of entries
3573 to be excluded. INCLUDE_INTERNALS can be used to provide a list
3574 of internal entries to be included. Normally, no internal
3575 entries are brought in. Use of this form of the command is
3576 strongly discouraged, but it is provided for backward compati‐
3577 bility.
3578 load_command
3581 Load a command into a running CMake.
3582 load_command(COMMAND_NAME <loc1> [loc2 ...])
3584 The given locations are searched for a library whose name is
3586 cmCOMMAND_NAME. If found, it is loaded as a module and the com‐
3587 mand is added to the set of available CMake commands. Usually,
3588 TRY_COMPILE is used before this command to compile the module.
3589 If the command is successfully loaded a variable named
3590 CMAKE_LOADED_COMMAND_<COMMAND_NAME>
3593 will be set to the full path of the module that was loaded.
3595 Otherwise the variable will not be set.
3596 macro Start recording a macro for later invocation as a command.
3599 macro(<name> [arg1 [arg2 [arg3 ...]]])
3601 COMMAND1(ARGS ...)
3602 COMMAND2(ARGS ...)
3603 ...
3604 endmacro(<name>)
3605 Define a macro named <name> that takes arguments named arg1 arg2
3607 arg3 (...). Commands listed after macro, but before the match‐
3608 ing endmacro, are not invoked until the macro is invoked. When
3609 it is invoked, the commands recorded in the macro are first mod‐
3610 ified by replacing formal parameters (${arg1}) with the argu‐
3611 ments passed, and then invoked as normal commands. In addition
3612 to referencing the formal parameters you can reference the val‐
3613 ues ${ARGC} which will be set to the number of arguments passed
3614 into the function as well as ${ARGV0} ${ARGV1} ${ARGV2} ...
3615 which will have the actual values of the arguments passed in.
3616 This facilitates creating macros with optional arguments. Addi‐
3617 tionally ${ARGV} holds the list of all arguments given to the
3618 macro and ${ARGN} holds the list of arguments past the last
3619 expected argument. Note that the parameters to a macro and val‐
3620 ues such as ARGN are not variables in the usual CMake sense.
3621 They are string replacements much like the C preprocessor would
3622 do with a macro. If you want true CMake variables and/or better
3623 CMake scope control you should look at the function command.
3624 See the cmake_policy() command documentation for the behavior of
3627 policies inside macros.
3628 mark_as_advanced
3631 Mark cmake cached variables as advanced.
3632 mark_as_advanced([CLEAR|FORCE] VAR VAR2 VAR...)
3634 Mark the named cached variables as advanced. An advanced vari‐
3636 able will not be displayed in any of the cmake GUIs unless the
3637 show advanced option is on. If CLEAR is the first argument
3638 advanced variables are changed back to unadvanced. If FORCE is
3639 the first argument, then the variable is made advanced. If nei‐
3640 ther FORCE nor CLEAR is specified, new values will be marked as
3641 advanced, but if the variable already has an
3642 advanced/non-advanced state, it will not be changed.
3643 It does nothing in script mode.
3646 math Mathematical expressions.
3649 math(EXPR <output variable> <math expression>)
3651 EXPR evaluates mathematical expression and returns result in the
3653 output variable. Example mathematical expression is '5 * ( 10 +
3654 13 )'. Supported operators are + - * / % | & ^ ~ << >> * / %.
3655 They have the same meaning as they do in C code.
3656 message
3659 Display a message to the user.
3660 message([STATUS|WARNING|AUTHOR_WARNING|FATAL_ERROR|SEND_ERROR]
3662 "message to display" ...)
3663 The optional keyword determines the type of message:
3665 (none) = Important information
3668 STATUS = Incidental information
3669 WARNING = CMake Warning, continue processing
3670 AUTHOR_WARNING = CMake Warning (dev), continue processing
3671 SEND_ERROR = CMake Error, continue processing,
3672 but skip generation
3673 FATAL_ERROR = CMake Error, stop processing and generation
3674 The CMake command-line tool displays STATUS messages on stdout
3676 and all other message types on stderr. The CMake GUI displays
3677 all messages in its log area. The interactive dialogs (ccmake
3678 and CMakeSetup) show STATUS messages one at a time on a status
3679 line and other messages in interactive pop-up boxes.
3680 CMake Warning and Error message text displays using a simple
3683 markup language. Non-indented text is formatted in line-wrapped
3684 paragraphs delimited by newlines. Indented text is considered
3685 pre-formatted.
3686 option Provides an option that the user can optionally select.
3689 option(<option_variable> "help string describing option"
3691 [initial value])
3692 Provide an option for the user to select as ON or OFF. If no
3694 initial value is provided, OFF is used.
3695 If you have options that depend on the values of other options,
3698 see the module help for CMakeDependentOption.
3699 project
3702 Set a name for the entire project.
3703 project(<projectname> [languageName1 languageName2 ... ] )
3705 Sets the name of the project. Additionally this sets the vari‐
3707 ables <projectName>_BINARY_DIR and <projectName>_SOURCE_DIR to
3708 the respective values.
3709 Optionally you can specify which languages your project sup‐
3712 ports. Example languages are CXX (i.e. C++), C, Fortran, etc.
3713 By default C and CXX are enabled. E.g. if you do not have a C++
3714 compiler, you can disable the check for it by explicitly listing
3715 the languages you want to support, e.g. C. By using the special
3716 language "NONE" all checks for any language can be disabled. If
3717 a variable exists called CMAKE_PROJECT_<projectName>_INCLUDE,
3718 the file pointed to by that variable will be included as the
3719 last step of the project command.
3720 The top-level CMakeLists.txt file for a project must contain a
3723 literal, direct call to the project() command; loading one
3724 through the include() command is not sufficient. If no such
3725 call exists CMake will implicitly add one to the top that
3726 enables the default languages (C and CXX).
3727 qt_wrap_cpp
3730 Create Qt Wrappers.
3731 qt_wrap_cpp(resultingLibraryName DestName
3733 SourceLists ...)
3734 Produce moc files for all the .h files listed in the
3736 SourceLists. The moc files will be added to the library using
3737 the DestName source list.
3738 qt_wrap_ui
3741 Create Qt user interfaces Wrappers.
3742 qt_wrap_ui(resultingLibraryName HeadersDestName
3744 SourcesDestName SourceLists ...)
3745 Produce .h and .cxx files for all the .ui files listed in the
3747 SourceLists. The .h files will be added to the library using
3748 the HeadersDestNamesource list. The .cxx files will be added to
3749 the library using the SourcesDestNamesource list.
3750 remove_definitions
3753 Removes -D define flags added by add_definitions.
3754 remove_definitions(-DFOO -DBAR ...)
3756 Removes flags (added by add_definitions) from the compiler com‐
3758 mand line for sources in the current directory and below.
3759 return Return from a file, directory or function.
3762 return()
3764 Returns from a file, directory or function. When this command is
3766 encountered in an included file (via include() or find_pack‐
3767 age()), it causes processing of the current file to stop and
3768 control is returned to the including file. If it is encountered
3769 in a file which is not included by another file, e.g. a CMake‐
3770 Lists.txt, control is returned to the parent directory if there
3771 is one. If return is called in a function, control is returned
3772 to the caller of the function. Note that a macro is not a func‐
3773 tion and does not handle return like a function does.
3774 separate_arguments
3777 Parse space-separated arguments into a semicolon-separated list.
3778 separate_arguments(<var> <UNIX|WINDOWS>_COMMAND "<args>")
3780 Parses a unix- or windows-style command-line string "<args>" and
3782 stores a semicolon-separated list of the arguments in <var>.
3783 The entire command line must be given in one "<args>" argument.
3784 The UNIX_COMMAND mode separates arguments by unquoted white‐
3787 space. It recognizes both single-quote and double-quote pairs.
3788 A backslash escapes the next literal character (\" is "); there
3789 are no special escapes (\n is just n).
3790 The WINDOWS_COMMAND mode parses a windows command-line using the
3793 same syntax the runtime library uses to construct argv at
3794 startup. It separates arguments by whitespace that is not dou‐
3795 ble-quoted. Backslashes are literal unless they precede dou‐
3796 ble-quotes. See the MSDN article "Parsing C Command-Line Argu‐
3797 ments" for details.
3798 separate_arguments(VARIABLE)
3801 Convert the value of VARIABLE to a semi-colon separated list.
3803 All spaces are replaced with ';'. This helps with generating
3804 command lines.
3805 set Set a CMake, cache or environment variable to a given value.
3808 set(<variable> <value>
3810 [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])
3811 Within CMake sets <variable> to the value <value>. <value> is
3813 expanded before <variable> is set to it. Normally, set will set
3814 a regular CMake variable. If CACHE is present, then the <vari‐
3815 able> is put in the cache instead, unless it is already in the
3816 cache. See section 'Variable types in CMake' below for details
3817 of regular and cache variables and their interactions. If CACHE
3818 is used, <type> and <docstring> are required. <type> is used by
3819 the CMake GUI to choose a widget with which the user sets a
3820 value. The value for <type> may be one of
3821 FILEPATH = File chooser dialog.
3824 PATH = Directory chooser dialog.
3825 STRING = Arbitrary string.
3826 BOOL = Boolean ON/OFF checkbox.
3827 INTERNAL = No GUI entry (used for persistent variables).
3828 If <type> is INTERNAL, the cache variable is marked as internal,
3830 and will not be shown to the user in tools like cmake-gui. This
3831 is intended for values that should be persisted in the cache,
3832 but which users should not normally change. INTERNAL implies
3833 FORCE.
3834 Normally, set(...CACHE...) creates cache variables, but does not
3837 modify them. If FORCE is specified, the value of the cache vari‐
3838 able is set, even if the variable is already in the cache. This
3839 should normally be avoided, as it will remove any changes to the
3840 cache variable's value by the user.
3841 If PARENT_SCOPE is present, the variable will be set in the
3844 scope above the current scope. Each new directory or function
3845 creates a new scope. This command will set the value of a vari‐
3846 able into the parent directory or calling function (whichever is
3847 applicable to the case at hand). PARENT_SCOPE cannot be combined
3848 with CACHE.
3849 If <value> is not specified then the variable is removed instead
3852 of set. See also: the unset() command.
3853 set(<variable> <value1> ... <valueN>)
3856 In this case <variable> is set to a semicolon separated list of
3858 values.
3859 <variable> can be an environment variable such as:
3862 set( ENV{PATH} /home/martink )
3865 in which case the environment variable will be set.
3867 *** Variable types in CMake ***
3870 In CMake there are two types of variables: normal variables and
3873 cache variables. Normal variables are meant for the internal use
3874 of the script (just like variables in most programming lan‐
3875 guages); they are not persisted across CMake runs. Cache vari‐
3876 ables (unless set with INTERNAL) are mostly intended for config‐
3877 uration settings where the first CMake run determines a suitable
3878 default value, which the user can then override, by editing the
3879 cache with tools such as ccmake or cmake-gui. Cache variables
3880 are stored in the CMake cache file, and are persisted across
3881 CMake runs.
3882 Both types can exist at the same time with the same name but
3885 different values. When ${FOO} is evaluated, CMake first looks
3886 for a normal variable 'FOO' in scope and uses it if set. If and
3887 only if no normal variable exists then it falls back to the
3888 cache variable 'FOO'.
3889 Some examples:
3892 The code 'set(FOO "x")' sets the normal variable 'FOO'. It does
3895 not touch the cache, but it will hide any existing cache value
3896 'FOO'.
3897 The code 'set(FOO "x" CACHE ...)' checks for 'FOO' in the cache,
3900 ignoring any normal variable of the same name. If 'FOO' is in
3901 the cache then nothing happens to either the normal variable or
3902 the cache variable. If 'FOO' is not in the cache, then it is
3903 added to the cache.
3904 Finally, whenever a cache variable is added or modified by a
3907 command, CMake also *removes* the normal variable of the same
3908 name from the current scope so that an immediately following
3909 evaluation of it will expose the newly cached value.
3910 Normally projects should avoid using normal and cache variables
3913 of the same name, as this interaction can be hard to follow.
3914 However, in some situations it can be useful. One example (used
3915 by some projects):
3916 A project has a subproject in its source tree. The child project
3919 has its own CMakeLists.txt, which is included from the parent
3920 CMakeLists.txt using add_subdirectory(). Now, if the parent and
3921 the child project provide the same option (for example a com‐
3922 piler option), the parent gets the first chance to add a
3923 user-editable option to the cache. Normally, the child would
3924 then use the same value that the parent uses. However, it may be
3925 necessary to hard-code the value for the child project's option
3926 while still allowing the user to edit the value used by the par‐
3927 ent project. The parent project can achieve this simply by set‐
3928 ting a normal variable with the same name as the option in a
3929 scope sufficient to hide the option's cache variable from the
3930 child completely. The parent has already set the cache variable,
3931 so the child's set(...CACHE...) will do nothing, and evaluating
3932 the option variable will use the value from the normal variable,
3933 which hides the cache variable.
3934 set_directory_properties
3937 Set a property of the directory.
3938 set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
3940 Set a property for the current directory and subdirectories. If
3942 the property is not found, CMake will report an error. The prop‐
3943 erties include: INCLUDE_DIRECTORIES, LINK_DIRECTORIES,
3944 INCLUDE_REGULAR_EXPRESSION, and ADDITIONAL_MAKE_CLEAN_FILES.
3945 ADDITIONAL_MAKE_CLEAN_FILES is a list of files that will be
3946 cleaned as a part of "make clean" stage.
3947 set_property
3950 Set a named property in a given scope.
3951 set_property(<GLOBAL |
3953 DIRECTORY [dir] |
3954 TARGET [target1 [target2 ...]] |
3955 SOURCE [src1 [src2 ...]] |
3956 TEST [test1 [test2 ...]] |
3957 CACHE [entry1 [entry2 ...]]>
3958 [APPEND] [APPEND_STRING]
3959 PROPERTY <name> [value1 [value2 ...]])
3960 Set one property on zero or more objects of a scope. The first
3962 argument determines the scope in which the property is set. It
3963 must be one of the following:
3964 GLOBAL scope is unique and does not accept a name.
3967 DIRECTORY scope defaults to the current directory but another
3970 directory (already processed by CMake) may be named by full or
3971 relative path.
3972 TARGET scope may name zero or more existing targets.
3975 SOURCE scope may name zero or more source files. Note that
3978 source file properties are visible only to targets added in the
3979 same directory (CMakeLists.txt).
3980 TEST scope may name zero or more existing tests.
3983 CACHE scope must name zero or more cache existing entries.
3986 The required PROPERTY option is immediately followed by the name
3989 of the property to set. Remaining arguments are used to compose
3990 the property value in the form of a semicolon-separated list.
3991 If the APPEND option is given the list is appended to any exist‐
3992 ing property value.If the APPEND_STRING option is given the
3993 string is append to any existing property value as string, i.e.
3994 it results in a longer string and not a list of strings.
3995 set_source_files_properties
3998 Source files can have properties that affect how they are built.
3999 set_source_files_properties([file1 [file2 [...]]]
4001 PROPERTIES prop1 value1
4002 [prop2 value2 [...]])
4003 Set properties associated with source files using a key/value
4005 paired list. See properties documentation for those known to
4006 CMake. Unrecognized properties are ignored. Source file prop‐
4007 erties are visible only to targets added in the same directory
4008 (CMakeLists.txt).
4009 set_target_properties
4012 Targets can have properties that affect how they are built.
4013 set_target_properties(target1 target2 ...
4015 PROPERTIES prop1 value1
4016 prop2 value2 ...)
4017 Set properties on a target. The syntax for the command is to
4019 list all the files you want to change, and then provide the val‐
4020 ues you want to set next. You can use any prop value pair you
4021 want and extract it later with the GET_TARGET_PROPERTY command.
4022 Properties that affect the name of a target's output file are as
4025 follows. The PREFIX and SUFFIX properties override the default
4026 target name prefix (such as "lib") and suffix (such as ".so").
4027 IMPORT_PREFIX and IMPORT_SUFFIX are the equivalent properties
4028 for the import library corresponding to a DLL (for SHARED
4029 library targets). OUTPUT_NAME sets the real name of a target
4030 when it is built and can be used to help create two targets of
4031 the same name even though CMake requires unique logical target
4032 names. There is also a <CONFIG>_OUTPUT_NAME that can set the
4033 output name on a per-configuration basis. <CONFIG>_POSTFIX sets
4034 a postfix for the real name of the target when it is built under
4035 the configuration named by <CONFIG> (in upper-case, such as
4036 "DEBUG_POSTFIX"). The value of this property is initialized
4037 when the target is created to the value of the variable
4038 CMAKE_<CONFIG>_POSTFIX (except for executable targets because
4039 earlier CMake versions which did not use this variable for exe‐
4040 cutables).
4041 The LINK_FLAGS property can be used to add extra flags to the
4044 link step of a target. LINK_FLAGS_<CONFIG> will add to the con‐
4045 figuration <CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL,
4046 RELWITHDEBINFO. DEFINE_SYMBOL sets the name of the preprocessor
4047 symbol defined when compiling sources in a shared library. If
4048 not set here then it is set to target_EXPORTS by default (with
4049 some substitutions if the target is not a valid C identifier).
4050 This is useful for headers to know whether they are being
4051 included from inside their library or outside to properly setup
4052 dllexport/dllimport decorations. The COMPILE_FLAGS property sets
4053 additional compiler flags used to build sources within the tar‐
4054 get. It may also be used to pass additional preprocessor defi‐
4055 nitions.
4056 The LINKER_LANGUAGE property is used to change the tool used to
4059 link an executable or shared library. The default is set the
4060 language to match the files in the library. CXX and C are common
4061 values for this property.
4062 For shared libraries VERSION and SOVERSION can be used to spec‐
4065 ify the build version and API version respectively. When build‐
4066 ing or installing appropriate symlinks are created if the plat‐
4067 form supports symlinks and the linker supports so-names. If only
4068 one of both is specified the missing is assumed to have the same
4069 version number. For executables VERSION can be used to specify
4070 the build version. When building or installing appropriate sym‐
4071 links are created if the platform supports symlinks. For shared
4072 libraries and executables on Windows the VERSION attribute is
4073 parsed to extract a "major.minor" version number. These numbers
4074 are used as the image version of the binary.
4075 There are a few properties used to specify RPATH rules.
4078 INSTALL_RPATH is a semicolon-separated list specifying the rpath
4079 to use in installed targets (for platforms that support it).
4080 INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to true
4081 will append directories in the linker search path and outside
4082 the project to the INSTALL_RPATH. SKIP_BUILD_RPATH is a boolean
4083 specifying whether to skip automatic generation of an rpath
4084 allowing the target to run from the build tree.
4085 BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link
4086 the target in the build tree with the INSTALL_RPATH. This takes
4087 precedence over SKIP_BUILD_RPATH and avoids the need for relink‐
4088 ing before installation. INSTALL_NAME_DIR is a string specify‐
4089 ing the directory portion of the "install_name" field of shared
4090 libraries on Mac OSX to use in the installed targets. When the
4091 target is created the values of the variables
4092 CMAKE_INSTALL_RPATH, CMAKE_INSTALL_RPATH_USE_LINK_PATH,
4093 CMAKE_SKIP_BUILD_RPATH, CMAKE_BUILD_WITH_INSTALL_RPATH, and
4094 CMAKE_INSTALL_NAME_DIR are used to initialize these properties.
4095 PROJECT_LABEL can be used to change the name of the target in an
4098 IDE like visual studio. VS_KEYWORD can be set to change the
4099 visual studio keyword, for example Qt integration works better
4100 if this is set to Qt4VSv1.0.
4101 VS_SCC_PROJECTNAME, VS_SCC_LOCALPATH, VS_SCC_PROVIDER and
4104 VS_SCC_AUXPATH can be set to add support for source control
4105 bindings in a Visual Studio project file.
4106 VS_GLOBAL_<variable> can be set to add a Visual Studio
4109 project-specific global variable. Qt integration works better if
4110 VS_GLOBAL_QtVersion is set to the Qt version FindQt4.cmake
4111 found. For example, "4.7.3"
4112 The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are
4115 the old way to specify CMake scripts to run before and after
4116 installing a target. They are used only when the old
4117 INSTALL_TARGETS command is used to install the target. Use the
4118 INSTALL command instead.
4119 The EXCLUDE_FROM_DEFAULT_BUILD property is used by the visual
4122 studio generators. If it is set to 1 the target will not be
4123 part of the default build when you select "Build Solution". This
4124 can also be set on a per-configuration basis using
4125 EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>.
4126 set_tests_properties
4129 Set a property of the tests.
4130 set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
4132 Set a property for the tests. If the property is not found,
4134 CMake will report an error. The properties include:
4135 WILL_FAIL: If set to true, this will invert the pass/fail flag
4138 of the test.
4139 PASS_REGULAR_EXPRESSION: If set, the test output will be checked
4142 against the specified regular expressions and at least one of
4143 the regular expressions has to match, otherwise the test will
4144 fail.
4145 Example: PASS_REGULAR_EXPRESSION "TestPassed;All ok"
4148 FAIL_REGULAR_EXPRESSION: If set, if the output will match to one
4150 of specified regular expressions, the test will fail.
4151 Example: PASS_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed"
4154 Both PASS_REGULAR_EXPRESSION and FAIL_REGULAR_EXPRESSION expect
4156 a list of regular expressions.
4157 TIMEOUT: Setting this will limit the test runtime to the number
4160 of seconds specified.
4161 site_name
4165 Set the given variable to the name of the computer.
4166 site_name(variable)
4168 source_group
4171 Define a grouping for sources in the makefile.
4172 source_group(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])
4174 Defines a group into which sources will be placed in project
4176 files. This is mainly used to setup file tabs in Visual Studio.
4177 Any file whose name is listed or matches the regular expression
4178 will be placed in this group. If a file matches multiple
4179 groups, the LAST group that explicitly lists the file will be
4180 favored, if any. If no group explicitly lists the file, the
4181 LAST group whose regular expression matches the file will be
4182 favored.
4183 The name of the group may contain backslashes to specify sub‐
4186 groups:
4187 source_group(outer\\inner ...)
4190 For backwards compatibility, this command also supports the for‐
4192 mat:
4193 source_group(name regex)
4196 string String operations.
4199 string(REGEX MATCH <regular_expression>
4201 <output variable> <input> [<input>...])
4202 string(REGEX MATCHALL <regular_expression>
4203 <output variable> <input> [<input>...])
4204 string(REGEX REPLACE <regular_expression>
4205 <replace_expression> <output variable>
4206 <input> [<input>...])
4207 string(REPLACE <match_string>
4208 <replace_string> <output variable>
4209 <input> [<input>...])
4210 string(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512>
4211 <output variable> <input>)
4212 string(COMPARE EQUAL <string1> <string2> <output variable>)
4213 string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
4214 string(COMPARE LESS <string1> <string2> <output variable>)
4215 string(COMPARE GREATER <string1> <string2> <output variable>)
4216 string(ASCII <number> [<number> ...] <output variable>)
4217 string(CONFIGURE <string1> <output variable>
4218 [@ONLY] [ESCAPE_QUOTES])
4219 string(TOUPPER <string1> <output variable>)
4220 string(TOLOWER <string1> <output variable>)
4221 string(LENGTH <string> <output variable>)
4222 string(SUBSTRING <string> <begin> <length> <output variable>)
4223 string(STRIP <string> <output variable>)
4224 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
4225 [RANDOM_SEED <seed>] <output variable>)
4226 string(FIND <string> <substring> <output variable> [REVERSE])
4227 string(TIMESTAMP <output variable> [<format string>] [UTC])
4228 string(MAKE_C_IDENTIFIER <input string> <output variable>)
4229 REGEX MATCH will match the regular expression once and store the
4231 match in the output variable.
4232 REGEX MATCHALL will match the regular expression as many times
4235 as possible and store the matches in the output variable as a
4236 list.
4237 REGEX REPLACE will match the regular expression as many times as
4240 possible and substitute the replacement expression for the match
4241 in the output. The replace expression may refer to paren-delim‐
4242 ited subexpressions of the match using \1, \2, ..., \9. Note
4243 that two backslashes (\\1) are required in CMake code to get a
4244 backslash through argument parsing.
4245 REPLACE will replace all occurrences of match_string in the
4248 input with replace_string and store the result in the output.
4249 MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a
4252 cryptographic hash of the input string.
4253 COMPARE EQUAL/NOTEQUAL/LESS/GREATER will compare the strings and
4256 store true or false in the output variable.
4257 ASCII will convert all numbers into corresponding ASCII charac‐
4260 ters.
4261 CONFIGURE will transform a string like CONFIGURE_FILE transforms
4264 a file.
4265 TOUPPER/TOLOWER will convert string to upper/lower characters.
4268 LENGTH will return a given string's length.
4271 SUBSTRING will return a substring of a given string. If length
4274 is -1 the remainder of the string starting at begin will be
4275 returned.
4276 STRIP will return a substring of a given string with leading and
4279 trailing spaces removed.
4280 RANDOM will return a random string of given length consisting of
4283 characters from the given alphabet. Default length is 5 charac‐
4284 ters and default alphabet is all numbers and upper and lower
4285 case letters. If an integer RANDOM_SEED is given, its value
4286 will be used to seed the random number generator.
4287 FIND will return the position where the given substring was
4290 found in the supplied string. If the REVERSE flag was used, the
4291 command will search for the position of the last occurrence of
4292 the specified substring.
4293 The following characters have special meaning in regular expres‐
4296 sions:
4297 ^ Matches at beginning of input
4300 $ Matches at end of input
4301 . Matches any single character
4302 [ ] Matches any character(s) inside the brackets
4303 [^ ] Matches any character(s) not inside the brackets
4304 - Inside brackets, specifies an inclusive range between
4305 characters on either side e.g. [a-f] is [abcdef]
4306 To match a literal - using brackets, make it the first
4307 or the last character e.g. [+*/-] matches basic
4308 mathematical operators.
4309 * Matches preceding pattern zero or more times
4310 + Matches preceding pattern one or more times
4311 ? Matches preceding pattern zero or once only
4312 | Matches a pattern on either side of the |
4313 () Saves a matched subexpression, which can be referenced
4314 in the REGEX REPLACE operation. Additionally it is saved
4315 by all regular expression-related commands, including
4316 e.g. if( MATCHES ), in the variables CMAKE_MATCH_(0..9).
4317 *, + and ? have higher precedence than concatenation. | has
4319 lower precedence than concatenation. This means that the regular
4320 expression "^ab+d$" matches "abbd" but not "ababd", and the reg‐
4321 ular expression "^(ab|cd)$" matches "ab" but not "abd".
4322 TIMESTAMP will write a string representation of the current date
4325 and/or time to the output variable.
4326 Should the command be unable to obtain a timestamp the output
4329 variable will be set to the empty string "".
4330 The optional UTC flag requests the current date/time representa‐
4333 tion to be in Coordinated Universal Time (UTC) rather than local
4334 time.
4335 The optional <format string> may contain the following format
4338 specifiers:
4339 %d The day of the current month (01-31).
4342 %H The hour on a 24-hour clock (00-23).
4343 %I The hour on a 12-hour clock (01-12).
4344 %j The day of the current year (001-366).
4345 %m The month of the current year (01-12).
4346 %M The minute of the current hour (00-59).
4347 %S The second of the current minute.
4348 60 represents a leap second. (00-60)
4349 %U The week number of the current year (00-53).
4350 %w The day of the current week. 0 is Sunday. (0-6)
4351 %y The last two digits of the current year (00-99)
4352 %Y The current year.
4353 Unknown format specifiers will be ignored and copied to the out‐
4355 put as-is.
4356 If no explicit <format string> is given it will default to:
4359 %Y-%m-%dT%H:%M:%S for local time.
4362 %Y-%m-%dT%H:%M:%SZ for UTC.
4363 MAKE_C_IDENTIFIER will write a string which can be used as an
4365 identifier in C.
4366 target_compile_definitions
4369 Add compile definitions to a target.
4370 target_compile_definitions(<target> <INTERFACE|PUBLIC|PRIVATE> [items1...]
4372 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4373 Specify compile definitions to use when compiling a given tar‐
4375 get. The named <target> must have been created by a command
4376 such as add_executable or add_library and must not be an
4377 IMPORTED target. The INTERFACE, PUBLIC and PRIVATE keywords are
4378 required to specify the scope of the following arguments. PRI‐
4379 VATE and PUBLIC items will populate the COMPILE_DEFINITIONS
4380 property of <target>. PUBLIC and INTERFACE items will populate
4381 the INTERFACE_COMPILE_DEFINITIONS property of <target>. The
4382 following arguments specify compile definitions. Repeated calls
4383 for the same <target> append items in the order called.
4384 Arguments to target_compile_definitions may use "generator
4387 expressions" with the syntax "$<...>". Generator expressions
4388 are evaluated during build system generation to produce informa‐
4389 tion specific to each build configuration. Valid expressions
4390 are:
4391 $<0:...> = empty string (ignores "...")
4394 $<1:...> = content of "..."
4395 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
4396 $<CONFIGURATION> = configuration name
4397 $<BOOL:...> = '1' if the '...' is true, else '0'
4398 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
4399 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
4400 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
4401 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
4402 $<JOIN:list,...> = joins the list with the content of "..."
4403 $<TARGET_NAME:...> = Marks ... as being the name of a target. This is required if exporting targets to multiple dependent export sets. The '...' must be a literal name of a target- it may not contain generator expressions.
4404 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4405 $<BUILD_INTERFACE:...> = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
4406 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
4407 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4408 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
4409 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4410 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
4411 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
4412 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
4413 $<C_COMPILER_VERSION> = The version of the C compiler used.
4414 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
4415 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
4416 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
4417 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
4418 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
4419 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
4420 where "tgt" is the name of a target. Target file expressions
4422 produce a full path, but _DIR and _NAME versions can produce the
4423 directory and file name components:
4424 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
4427 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
4428 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
4429 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
4434 Note that tgt is not added as a dependency of the target this
4436 expression is evaluated on.
4437 $<TARGET_POLICY:pol> = '1' if the policy was NEW when the 'head' target was created, else '0'. If the policy was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies.
4440 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
4441 Boolean expressions:
4443 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
4446 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
4447 $<NOT:?> = '0' if '?' is '1', else '1'
4448 where '?' is always either '0' or '1'.
4450 Expressions with an implicit 'this' target:
4453 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
4456 target_compile_options
4459 Add compile options to a target.
4460 target_compile_options(<target> [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...]
4462 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4463 Specify compile options to use when compiling a given target.
4465 The named <target> must have been created by a command such as
4466 add_executable or add_library and must not be an IMPORTED tar‐
4467 get. If BEFORE is specified, the content will be prepended to
4468 the property instead of being appended.
4469 The INTERFACE, PUBLIC and PRIVATE keywords are required to spec‐
4472 ify the scope of the following arguments. PRIVATE and PUBLIC
4473 items will populate the COMPILE_OPTIONS property of <target>.
4474 PUBLIC and INTERFACE items will populate the INTERFACE_COM‐
4475 PILE_OPTIONS property of <target>. The following arguments
4476 specify compile opitions. Repeated calls for the same <target>
4477 append items in the order called.
4478 Arguments to target_compile_options may use "generator expres‐
4481 sions" with the syntax "$<...>". Generator expressions are
4482 evaluated during build system generation to produce information
4483 specific to each build configuration. Valid expressions are:
4484 $<0:...> = empty string (ignores "...")
4487 $<1:...> = content of "..."
4488 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
4489 $<CONFIGURATION> = configuration name
4490 $<BOOL:...> = '1' if the '...' is true, else '0'
4491 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
4492 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
4493 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
4494 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
4495 $<JOIN:list,...> = joins the list with the content of "..."
4496 $<TARGET_NAME:...> = Marks ... as being the name of a target. This is required if exporting targets to multiple dependent export sets. The '...' must be a literal name of a target- it may not contain generator expressions.
4497 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4498 $<BUILD_INTERFACE:...> = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
4499 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
4500 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4501 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
4502 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4503 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
4504 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
4505 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
4506 $<C_COMPILER_VERSION> = The version of the C compiler used.
4507 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
4508 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
4509 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
4510 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
4511 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
4512 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
4513 where "tgt" is the name of a target. Target file expressions
4515 produce a full path, but _DIR and _NAME versions can produce the
4516 directory and file name components:
4517 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
4520 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
4521 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
4522 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
4527 Note that tgt is not added as a dependency of the target this
4529 expression is evaluated on.
4530 $<TARGET_POLICY:pol> = '1' if the policy was NEW when the 'head' target was created, else '0'. If the policy was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies.
4533 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
4534 Boolean expressions:
4536 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
4539 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
4540 $<NOT:?> = '0' if '?' is '1', else '1'
4541 where '?' is always either '0' or '1'.
4543 Expressions with an implicit 'this' target:
4546 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
4549 target_include_directories
4552 Add include directories to a target.
4553 target_include_directories(<target> [SYSTEM] [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...]
4555 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4556 Specify include directories or targets to use when compiling a
4558 given target. The named <target> must have been created by a
4559 command such as add_executable or add_library and must not be an
4560 IMPORTED target.
4561 If BEFORE is specified, the content will be prepended to the
4564 property instead of being appended.
4565 The INTERFACE, PUBLIC and PRIVATE keywords are required to spec‐
4568 ify the scope of the following arguments. PRIVATE and PUBLIC
4569 items will populate the INCLUDE_DIRECTORIES property of <tar‐
4570 get>. PUBLIC and INTERFACE items will populate the INTER‐
4571 FACE_INCLUDE_DIRECTORIES property of <target>. The following
4572 arguments specify include directories. Specified include direc‐
4573 tories may be absolute paths or relative paths. Repeated calls
4574 for the same <target> append items in the order called.If SYSTEM
4575 is specified, the compiler will be told the directories are
4576 meant as system include directories on some platforms (sig‐
4577 nalling this setting might achieve effects such as the compiler
4578 skipping warnings, or these fixed-install system files not being
4579 considered in dependency calculations - see compiler docs). If
4580 SYSTEM is used together with PUBLIC or INTERFACE, the INTER‐
4581 FACE_SYSTEM_INCLUDE_DIRECTORIES target property will be popu‐
4582 lated with the specified directories.
4583 Arguments to target_include_directories may use "generator
4586 expressions" with the syntax "$<...>". Generator expressions
4587 are evaluated during build system generation to produce informa‐
4588 tion specific to each build configuration. Valid expressions
4589 are:
4590 $<0:...> = empty string (ignores "...")
4593 $<1:...> = content of "..."
4594 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
4595 $<CONFIGURATION> = configuration name
4596 $<BOOL:...> = '1' if the '...' is true, else '0'
4597 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
4598 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
4599 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
4600 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
4601 $<JOIN:list,...> = joins the list with the content of "..."
4602 $<TARGET_NAME:...> = Marks ... as being the name of a target. This is required if exporting targets to multiple dependent export sets. The '...' must be a literal name of a target- it may not contain generator expressions.
4603 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4604 $<BUILD_INTERFACE:...> = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
4605 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
4606 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4607 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
4608 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4609 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
4610 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
4611 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
4612 $<C_COMPILER_VERSION> = The version of the C compiler used.
4613 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
4614 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
4615 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
4616 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
4617 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
4618 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
4619 where "tgt" is the name of a target. Target file expressions
4621 produce a full path, but _DIR and _NAME versions can produce the
4622 directory and file name components:
4623 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
4626 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
4627 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
4628 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
4633 Note that tgt is not added as a dependency of the target this
4635 expression is evaluated on.
4636 $<TARGET_POLICY:pol> = '1' if the policy was NEW when the 'head' target was created, else '0'. If the policy was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies.
4639 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
4640 Boolean expressions:
4642 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
4645 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
4646 $<NOT:?> = '0' if '?' is '1', else '1'
4647 where '?' is always either '0' or '1'.
4649 Expressions with an implicit 'this' target:
4652 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
4655 target_link_libraries
4658 Link a target to given libraries.
4659 target_link_libraries(<target> [item1 [item2 [...]]]
4661 [[debug|optimized|general] <item>] ...)
4662 Specify libraries or flags to use when linking a given target.
4664 The named <target> must have been created in the current direc‐
4665 tory by a command such as add_executable or add_library. The
4666 remaining arguments specify library names or flags. Repeated
4667 calls for the same <target> append items in the order called.
4668 If a library name matches that of another target in the project
4671 a dependency will automatically be added in the build system to
4672 make sure the library being linked is up-to-date before the tar‐
4673 get links. Item names starting with '-', but not '-l' or
4674 '-framework', are treated as linker flags.
4675 A "debug", "optimized", or "general" keyword indicates that the
4678 library immediately following it is to be used only for the cor‐
4679 responding build configuration. The "debug" keyword corresponds
4680 to the Debug configuration (or to configurations named in the
4681 DEBUG_CONFIGURATIONS global property if it is set). The "opti‐
4682 mized" keyword corresponds to all other configurations. The
4683 "general" keyword corresponds to all configurations, and is
4684 purely optional (assumed if omitted). Higher granularity may be
4685 achieved for per-configuration rules by creating and linking to
4686 IMPORTED library targets. See the IMPORTED mode of the
4687 add_library command for more information.
4688 Library dependencies are transitive by default with this signa‐
4691 ture. When this target is linked into another target then the
4692 libraries linked to this target will appear on the link line for
4693 the other target too. This transitive "link interface" is
4694 stored in the INTERFACE_LINK_LIBRARIES target property when pol‐
4695 icy CMP0022 is set to NEW and may be overridden by setting the
4696 property directly. (When CMP0022 is not set to NEW, transitive
4697 linking is builtin but may be overridden by the LINK_INTER‐
4698 FACE_LIBRARIES property. Calls to other signatures of this com‐
4699 mand may set the property making any libraries linked exclu‐
4700 sively by this signature private.)
4701 CMake will also propagate "usage requirements" from linked
4704 library targets. Usage requirements affect compilation of
4705 sources in the <target>. They are specified by properties
4706 defined on linked targets. During generation of the build sys‐
4707 tem, CMake integrates usage requirement property values with the
4708 corresponding build properties for <target>:
4709 INTERFACE_COMPILE_DEFINITONS: Appends to COMPILE_DEFINITONS
4712 INTERFACE_INCLUDE_DIRECTORIES: Appends to INCLUDE_DIRECTORIES
4713 INTERFACE_POSITION_INDEPENDENT_CODE: Sets POSITION_INDEPENDENT_CODE
4714 or checked for consistency with existing value
4715 If an <item> is a library in a Mac OX framework, the Headers
4720 directory of the framework will also be processed as a "usage
4721 requirement". This has the same effect as passing the framework
4722 directory as an include directory. target_link_libraries(<tar‐
4723 get>
4724 <PRIVATE|PUBLIC|INTERFACE> <lib> ...
4727 [<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...])
4728 The PUBLIC, PRIVATE and INTERFACE keywords can be used to spec‐
4730 ify both the link dependencies and the link interface in one
4731 command. Libraries and targets following PUBLIC are linked to,
4732 and are made part of the link interface. Libraries and targets
4733 following PRIVATE are linked to, but are not made part of the
4734 link interface. Libraries following INTERFACE are appended to
4735 the link interface and are not used for linking <target>.
4736 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES
4739 [[debug|optimized|general] <lib>] ...)
4740 The LINK_INTERFACE_LIBRARIES mode appends the libraries to the
4742 INTERFACE_LINK_LIBRARIES target property instead of using them
4743 for linking. If policy CMP0022 is not NEW, then this mode also
4744 appends libraries to the LINK_INTERFACE_LIBRARIES and its
4745 per-configuration equivalent. This signature is for compatibil‐
4746 ity only. Prefer the INTERFACE mode instead. Libraries speci‐
4747 fied as "debug" are wrapped in a generator expression to corre‐
4748 spond to debug builds. If policy CMP0022 is not NEW, the
4749 libraries are also appended to the LINK_INTER‐
4750 FACE_LIBRARIES_DEBUG property (or to the properties correspond‐
4751 ing to configurations listed in the DEBUG_CONFIGURATIONS global
4752 property if it is set). Libraries specified as "optimized" are
4753 appended to the INTERFACE_LINK_LIBRARIES property. If policy
4754 CMP0022 is not NEW, they are also appended to the LINK_INTER‐
4755 FACE_LIBRARIES property. Libraries specified as "general" (or
4756 without any keyword) are treated as if specified for both
4757 "debug" and "optimized".
4758 target_link_libraries(<target>
4761 <LINK_PRIVATE|LINK_PUBLIC>
4762 [[debug|optimized|general] <lib>] ...
4763 [<LINK_PRIVATE|LINK_PUBLIC>
4764 [[debug|optimized|general] <lib>] ...])
4765 The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify
4767 both the link dependencies and the link interface in one com‐
4768 mand. This signature is for compatibility only. Prefer the PUB‐
4769 LIC or PRIVATE keywords instead. Libraries and targets follow‐
4770 ing LINK_PUBLIC are linked to, and are made part of the INTER‐
4771 FACE_LINK_LIBRARIES. If policy CMP0022 is not NEW, they are
4772 also made part of the LINK_INTERFACE_LIBRARIES. Libraries and
4773 targets following LINK_PRIVATE are linked to, but are not made
4774 part of the INTERFACE_LINK_LIBRARIES (or LINK_INTER‐
4775 FACE_LIBRARIES).
4776 The library dependency graph is normally acyclic (a DAG), but in
4779 the case of mutually-dependent STATIC libraries CMake allows the
4780 graph to contain cycles (strongly connected components). When
4781 another target links to one of the libraries CMake repeats the
4782 entire connected component. For example, the code
4783 add_library(A STATIC a.c)
4786 add_library(B STATIC b.c)
4787 target_link_libraries(A B)
4788 target_link_libraries(B A)
4789 add_executable(main main.c)
4790 target_link_libraries(main A)
4791 links 'main' to 'A B A B'. (While one repetition is usually
4793 sufficient, pathological object file and symbol arrangements can
4794 require more. One may handle such cases by manually repeating
4795 the component in the last target_link_libraries call. However,
4796 if two archives are really so interdependent they should proba‐
4797 bly be combined into a single archive.)
4798 Arguments to target_link_libraries may use "generator expres‐
4801 sions" with the syntax "$<...>". Note however, that generator
4802 expressions will not be used in OLD handling of CMP0003 or
4803 CMP0004.
4804 Generator expressions are evaluated during build system genera‐
4807 tion to produce information specific to each build configura‐
4808 tion. Valid expressions are:
4809 $<0:...> = empty string (ignores "...")
4812 $<1:...> = content of "..."
4813 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
4814 $<CONFIGURATION> = configuration name
4815 $<BOOL:...> = '1' if the '...' is true, else '0'
4816 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
4817 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
4818 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
4819 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
4820 $<JOIN:list,...> = joins the list with the content of "..."
4821 $<TARGET_NAME:...> = Marks ... as being the name of a target. This is required if exporting targets to multiple dependent export sets. The '...' must be a literal name of a target- it may not contain generator expressions.
4822 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4823 $<BUILD_INTERFACE:...> = content of "..." when the property is exported using export(), or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise.
4824 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
4825 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4826 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
4827 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4828 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
4829 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
4830 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
4831 $<C_COMPILER_VERSION> = The version of the C compiler used.
4832 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
4833 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
4834 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
4835 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
4836 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
4837 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
4838 where "tgt" is the name of a target. Target file expressions
4840 produce a full path, but _DIR and _NAME versions can produce the
4841 directory and file name components:
4842 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
4845 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
4846 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
4847 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
4852 Note that tgt is not added as a dependency of the target this
4854 expression is evaluated on.
4855 $<TARGET_POLICY:pol> = '1' if the policy was NEW when the 'head' target was created, else '0'. If the policy was not set, the warning message for the policy will be emitted. This generator expression only works for a subset of policies.
4858 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
4859 Boolean expressions:
4861 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
4864 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
4865 $<NOT:?> = '0' if '?' is '1', else '1'
4866 where '?' is always either '0' or '1'.
4868 Expressions with an implicit 'this' target:
4871 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
4874 try_compile
4877 Try building some code.
4878 try_compile(RESULT_VAR <bindir> <srcdir>
4880 <projectName> [targetName] [CMAKE_FLAGS flags...]
4881 [OUTPUT_VARIABLE <var>])
4882 Try building a project. In this form, srcdir should contain a
4884 complete CMake project with a CMakeLists.txt file and all
4885 sources. The bindir and srcdir will not be deleted after this
4886 command is run. Specify targetName to build a specific target
4887 instead of the 'all' or 'ALL_BUILD' target.
4888 try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...>
4891 [CMAKE_FLAGS flags...]
4892 [COMPILE_DEFINITIONS flags...]
4893 [LINK_LIBRARIES libs...]
4894 [OUTPUT_VARIABLE <var>]
4895 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]])
4896 Try building an executable from one or more source files. In
4898 this form the user need only supply one or more source files
4899 that include a definition for 'main'. CMake will create a
4900 CMakeLists.txt file to build the source(s) as an executable.
4901 Specify COPY_FILE to get a copy of the linked executable at the
4902 given fileName and optionally COPY_FILE_ERROR to capture any
4903 error.
4904 In this version all files in bindir/CMakeFiles/CMakeTmp will be
4907 cleaned automatically. For debugging, --debug-trycompile can be
4908 passed to cmake to avoid this clean. However, multiple sequen‐
4909 tial try_compile operations reuse this single output directory.
4910 If you use --debug-trycompile, you can only debug one try_com‐
4911 pile call at a time. The recommended procedure is to configure
4912 with cmake all the way through once, then delete the cache entry
4913 associated with the try_compile call of interest, and then
4914 re-run cmake again with --debug-trycompile.
4915 Some extra flags that can be included are, INCLUDE_DIRECTORIES,
4918 LINK_DIRECTORIES, and LINK_LIBRARIES. COMPILE_DEFINITIONS are
4919 -Ddefinition that will be passed to the compile line.
4920 The srcfile signature also accepts a LINK_LIBRARIES argument
4923 which may contain a list of libraries or IMPORTED targets which
4924 will be linked to in the generated project. If LINK_LIBRARIES
4925 is specified as a parameter to try_compile, then any
4926 LINK_LIBRARIES passed as CMAKE_FLAGS will be ignored.
4927 try_compile creates a CMakeList.txt file on the fly that looks
4930 like this:
4931 add_definitions( <expanded COMPILE_DEFINITIONS from calling cmake>)
4934 include_directories(${INCLUDE_DIRECTORIES})
4935 link_directories(${LINK_DIRECTORIES})
4936 add_executable(cmTryCompileExec sources)
4937 target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
4938 In both versions of the command, if OUTPUT_VARIABLE is speci‐
4940 fied, then the output from the build process is stored in the
4941 given variable. The success or failure of the try_compile, i.e.
4942 TRUE or FALSE respectively, is returned in RESULT_VAR.
4943 CMAKE_FLAGS can be used to pass -DVAR:TYPE=VALUE flags to the
4944 cmake that is run during the build. Set variable CMAKE_TRY_COM‐
4945 PILE_CONFIGURATION to choose a build configuration.
4946 try_run
4949 Try compiling and then running some code.
4950 try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR
4952 bindir srcfile [CMAKE_FLAGS <Flags>]
4953 [COMPILE_DEFINITIONS <flags>]
4954 [COMPILE_OUTPUT_VARIABLE comp]
4955 [RUN_OUTPUT_VARIABLE run]
4956 [OUTPUT_VARIABLE var]
4957 [ARGS <arg1> <arg2>...])
4958 Try compiling a srcfile. Return TRUE or FALSE for success or
4960 failure in COMPILE_RESULT_VAR. Then if the compile succeeded,
4961 run the executable and return its exit code in RUN_RESULT_VAR.
4962 If the executable was built, but failed to run, then
4963 RUN_RESULT_VAR will be set to FAILED_TO_RUN. COMPILE_OUT‐
4964 PUT_VARIABLE specifies the variable where the output from the
4965 compile step goes. RUN_OUTPUT_VARIABLE specifies the variable
4966 where the output from the running executable goes.
4967 For compatibility reasons OUTPUT_VARIABLE is still supported,
4970 which gives you the output from the compile and run step com‐
4971 bined.
4972 Cross compiling issues
4975 When cross compiling, the executable compiled in the first step
4978 usually cannot be run on the build host. try_run() checks the
4979 CMAKE_CROSSCOMPILING variable to detect whether CMake is in
4980 crosscompiling mode. If that's the case, it will still try to
4981 compile the executable, but it will not try to run the exe‐
4982 cutable. Instead it will create cache variables which must be
4983 filled by the user or by presetting them in some CMake script
4984 file to the values the executable would have produced if it had
4985 been run on its actual target platform. These variables are
4986 RUN_RESULT_VAR (explanation see above) and if RUN_OUTPUT_VARI‐
4987 ABLE (or OUTPUT_VARIABLE) was used, an additional cache variable
4988 RUN_RESULT_VAR__COMPILE_RESULT_VAR__TRYRUN_OUTPUT.This is
4989 intended to hold stdout and stderr from the executable.
4990 In order to make cross compiling your project easier, use
4993 try_run only if really required. If you use try_run, use
4994 RUN_OUTPUT_VARIABLE (or OUTPUT_VARIABLE) only if really
4995 required. Using them will require that when crosscompiling, the
4996 cache variables will have to be set manually to the output of
4997 the executable. You can also "guard" the calls to try_run with
4998 if(CMAKE_CROSSCOMPILING) and provide an easy-to-preset alterna‐
4999 tive for this case.
5000 Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build
5003 configuration.
5004 unset Unset a variable, cache variable, or environment variable.
5007 unset(<variable> [CACHE])
5009 Removes the specified variable causing it to become undefined.
5011 If CACHE is present then the variable is removed from the cache
5012 instead of the current scope.
5013 <variable> can be an environment variable such as:
5016 unset(ENV{LD_LIBRARY_PATH})
5019 in which case the variable will be removed from the current
5021 environment.
5022 variable_watch
5025 Watch the CMake variable for change.
5026 variable_watch(<variable name> [<command to execute>])
5028 If the specified variable changes, the message will be printed
5030 about the variable being changed. If the command is specified,
5031 the command will be executed. The command will receive the fol‐
5032 lowing arguments: COMMAND(<variable> <access> <value> <current
5033 list file> <stack>)
5034 while Evaluate a group of commands while a condition is true
5037 while(condition)
5039 COMMAND1(ARGS ...)
5040 COMMAND2(ARGS ...)
5041 ...
5042 endwhile(condition)
5043 All commands between while and the matching endwhile are
5045 recorded without being invoked. Once the endwhile is evaluated,
5046 the recorded list of commands is invoked as long as the condi‐
5047 tion is true. The condition is evaluated using the same logic as
5048 the if command.
5049
5052 Copyright 2000-2012 Kitware, Inc., Insight Software Consortium. All
5053 rights reserved.
5054 Redistribution and use in source and binary forms, with or without mod‐
5057 ification, are permitted provided that the following conditions are
5058 met:
5059 Redistributions of source code must retain the above copyright notice,
5062 this list of conditions and the following disclaimer.
5063 Redistributions in binary form must reproduce the above copyright
5066 notice, this list of conditions and the following disclaimer in the
5067 documentation and/or other materials provided with the distribution.
5068 Neither the names of Kitware, Inc., the Insight Software Consortium,
5071 nor the names of their contributors may be used to endorse or promote
5072 products derived from this software without specific prior written per‐
5073 mission.
5074 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
5077 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
5078 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
5079 ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
5080 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
5081 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
5082 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
5083 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
5084 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
5085 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
5086 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
5087
5090 The following resources are available to get help using CMake:
5091 Home Page
5094 http://www.cmake.org
5095 The primary starting point for learning about CMake.
5097 Frequently Asked Questions
5100 http://www.cmake.org/Wiki/CMake_FAQ
5101 A Wiki is provided containing answers to frequently asked ques‐
5103 tions.
5104 Online Documentation
5107 http://www.cmake.org/HTML/Documentation.html
5108 Links to available documentation may be found on this web page.
5110 Mailing List
5113 http://www.cmake.org/HTML/MailingLists.html
5114 For help and discussion about using cmake, a mailing list is
5116 provided at cmake@cmake.org. The list is member-post-only but
5117 one may sign up on the CMake web page. Please first read the
5118 full documentation at http://www.cmake.org before posting ques‐
5119 tions to the list.
5120cmake 2.8.12.2 October 15, 2014 cmakecommands(1)