1ccmake(1) General Commands Manual ccmake(1)
2
6 ccmake - Curses Interface for CMake.
7
10 ccmake <path-to-source>
11 ccmake <path-to-existing-build>
12
15 The "ccmake" executable is the CMake curses interface. Project config‐
16 uration settings may be specified interactively through this GUI.
17 Brief instructions are provided at the bottom of the terminal when the
18 program is running.
19 CMake is a cross-platform build system generator. Projects specify
22 their build process with platform-independent CMake listfiles included
23 in each directory of a source tree with the name CMakeLists.txt. Users
24 build a project by using CMake to generate a build system for a native
25 tool on their platform.
26
29 -C <initial-cache>
30 Pre-load a script to populate the cache.
31 When cmake is first run in an empty build tree, it creates a
33 CMakeCache.txt file and populates it with customizable settings
34 for the project. This option may be used to specify a file from
35 which to load cache entries before the first pass through the
36 project's cmake listfiles. The loaded entries take priority
37 over the project's default values. The given file should be a
38 CMake script containing SET commands that use the CACHE option,
39 not a cache-format file.
40 -D <var>:<type>=<value>
43 Create a cmake cache entry.
44 When cmake is first run in an empty build tree, it creates a
46 CMakeCache.txt file and populates it with customizable settings
47 for the project. This option may be used to specify a setting
48 that takes priority over the project's default value. The
49 option may be repeated for as many cache entries as desired.
50 -U <globbing_expr>
53 Remove matching entries from CMake cache.
54 This option may be used to remove one or more variables from the
56 CMakeCache.txt file, globbing expressions using * and ? are sup‐
57 ported. The option may be repeated for as many cache entries as
58 desired.
59 Use with care, you can make your CMakeCache.txt non-working.
62 -G <generator-name>
65 Specify a build system generator.
66 CMake may support multiple native build systems on certain plat‐
68 forms. A generator is responsible for generating a particular
69 build system. Possible generator names are specified in the
70 Generators section.
71 -T <toolset-name>
74 Specify toolset name if supported by generator.
75 Some CMake generators support a toolset name to be given to the
77 native build system to choose a compiler. This is supported
78 only on specific generators:
79 Visual Studio >= 10
82 Xcode >= 3.0
83 See native build system documentation for allowed toolset names.
85 -Wno-dev
88 Suppress developer warnings.
89 Suppress warnings that are meant for the author of the CMake‐
91 Lists.txt files.
92 -Wdev Enable developer warnings.
95 Enable warnings that are meant for the author of the CMake‐
97 Lists.txt files.
98 --copyright [file]
101 Print the CMake copyright and exit.
102 If a file is specified, the copyright is written into it.
104 --help,-help,-usage,-h,-H,/?
107 Print usage information and exit.
108 Usage describes the basic command line interface and its
110 options.
111 --help-full [file]
114 Print full help and exit.
115 Full help displays most of the documentation provided by the
117 UNIX man page. It is provided for use on non-UNIX platforms,
118 but is also convenient if the man page is not installed. If a
119 file is specified, the help is written into it.
120 --help-html [file]
123 Print full help in HTML format.
124 This option is used by CMake authors to help produce web pages.
126 If a file is specified, the help is written into it.
127 --help-man [file]
130 Print full help as a UNIX man page and exit.
131 This option is used by the cmake build to generate the UNIX man
133 page. If a file is specified, the help is written into it.
134 --version,-version,/V [file]
137 Show program name/version banner and exit.
138 If a file is specified, the version is written into it.
140
143 Unix Makefiles
144 Generates standard UNIX makefiles.
145 A hierarchy of UNIX makefiles is generated into the build tree.
147 Any standard UNIX-style make program can build the project
148 through the default make target. A "make install" target is
149 also provided.
150 Ninja Generates build.ninja files (experimental).
153 A build.ninja file is generated into the build tree. Recent ver‐
155 sions of the ninja program can build the project through the
156 "all" target. An "install" target is also provided.
157 CodeBlocks - Ninja
160 Generates CodeBlocks project files.
161 Project files for CodeBlocks will be created in the top direc‐
163 tory and in every subdirectory which features a CMakeLists.txt
164 file containing a PROJECT() call. Additionally a hierarchy of
165 makefiles is generated into the build tree. The appropriate
166 make program can build the project through the default make tar‐
167 get. A "make install" target is also provided.
168 CodeBlocks - Unix Makefiles
171 Generates CodeBlocks project files.
172 Project files for CodeBlocks will be created in the top direc‐
174 tory and in every subdirectory which features a CMakeLists.txt
175 file containing a PROJECT() call. Additionally a hierarchy of
176 makefiles is generated into the build tree. The appropriate
177 make program can build the project through the default make tar‐
178 get. A "make install" target is also provided.
179 Eclipse CDT4 - Ninja
182 Generates Eclipse CDT 4.0 project files.
183 Project files for Eclipse will be created in the top directory.
185 In out of source builds, a linked resource to the top level
186 source directory will be created. Additionally a hierarchy of
187 makefiles is generated into the build tree. The appropriate make
188 program can build the project through the default make target. A
189 "make install" target is also provided.
190 Eclipse CDT4 - Unix Makefiles
193 Generates Eclipse CDT 4.0 project files.
194 Project files for Eclipse will be created in the top directory.
196 In out of source builds, a linked resource to the top level
197 source directory will be created. Additionally a hierarchy of
198 makefiles is generated into the build tree. The appropriate make
199 program can build the project through the default make target. A
200 "make install" target is also provided.
201 KDevelop3
204 Generates KDevelop 3 project files.
205 Project files for KDevelop 3 will be created in the top direc‐
207 tory and in every subdirectory which features a CMakeLists.txt
208 file containing a PROJECT() call. If you change the settings
209 using KDevelop cmake will try its best to keep your changes when
210 regenerating the project files. Additionally a hierarchy of UNIX
211 makefiles is generated into the build tree. Any standard
212 UNIX-style make program can build the project through the
213 default make target. A "make install" target is also provided.
214 KDevelop3 - Unix Makefiles
217 Generates KDevelop 3 project files.
218 Project files for KDevelop 3 will be created in the top direc‐
220 tory and in every subdirectory which features a CMakeLists.txt
221 file containing a PROJECT() call. If you change the settings
222 using KDevelop cmake will try its best to keep your changes when
223 regenerating the project files. Additionally a hierarchy of UNIX
224 makefiles is generated into the build tree. Any standard
225 UNIX-style make program can build the project through the
226 default make target. A "make install" target is also provided.
227 Sublime Text 2 - Ninja
230 Generates Sublime Text 2 project files.
231 Project files for Sublime Text 2 will be created in the top
233 directory and in every subdirectory which features a CMake‐
234 Lists.txt file containing a PROJECT() call. Additionally Make‐
235 files (or build.ninja files) are generated into the build tree.
236 The appropriate make program can build the project through the
237 default make target. A "make install" target is also provided.
238 Sublime Text 2 - Unix Makefiles
241 Generates Sublime Text 2 project files.
242 Project files for Sublime Text 2 will be created in the top
244 directory and in every subdirectory which features a CMake‐
245 Lists.txt file containing a PROJECT() call. Additionally Make‐
246 files (or build.ninja files) are generated into the build tree.
247 The appropriate make program can build the project through the
248 default make target. A "make install" target is also provided.
249
252 CMake Properties - Properties supported by CMake, the Cross-Platform Makefile Generator.
253 This is the documentation for the properties supported by CMake. Prop‐
256 erties can have different scopes. They can either be assigned to a
257 source file, a directory, a target or globally to CMake. By modifying
258 the values of properties the behaviour of the build system can be cus‐
259 tomized.
260
263 add_compile_options
264 Adds options to the compilation of source files.
265 add_compile_options(<option> ...)
267 Adds options to the compiler command line for sources in the
269 current directory and below. This command can be used to add
270 any options, but alternative commands exist to add preprocessor
271 definitions or include directories. See documentation of the
272 directory and target COMPILE_OPTIONS properties for details.
273 Arguments to add_compile_options may use "generator expressions"
274 with the syntax "$<...>". Generator expressions are evaluated
275 during build system generation to produce information specific
276 to each build configuration. Valid expressions are:
277 $<0:...> = empty string (ignores "...")
280 $<1:...> = content of "..."
281 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
282 $<CONFIGURATION> = configuration name
283 $<BOOL:...> = '1' if the '...' is true, else '0'
284 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
285 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
286 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
287 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
288 $<JOIN:list,...> = joins the list with the content of "..."
289 $<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.
290 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
291 $<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.
292 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
293 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
294 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
295 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
296 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
297 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
298 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
299 $<C_COMPILER_VERSION> = The version of the C compiler used.
300 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
301 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
302 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
303 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
304 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
305 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
306 where "tgt" is the name of a target. Target file expressions
308 produce a full path, but _DIR and _NAME versions can produce the
309 directory and file name components:
310 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
313 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
314 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
315 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
320 Note that tgt is not added as a dependency of the target this
322 expression is evaluated on.
323 $<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.
326 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
327 Boolean expressions:
329 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
332 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
333 $<NOT:?> = '0' if '?' is '1', else '1'
334 where '?' is always either '0' or '1'.
336 Expressions with an implicit 'this' target:
339 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
342 add_custom_command
345 Add a custom build rule to the generated build system.
346 There are two main signatures for add_custom_command The first
348 signature is for adding a custom command to produce an output.
349 add_custom_command(OUTPUT output1 [output2 ...]
352 COMMAND command1 [ARGS] [args1...]
353 [COMMAND command2 [ARGS] [args2...] ...]
354 [MAIN_DEPENDENCY depend]
355 [DEPENDS [depends...]]
356 [IMPLICIT_DEPENDS <lang1> depend1
357 [<lang2> depend2] ...]
358 [WORKING_DIRECTORY dir]
359 [COMMENT comment] [VERBATIM] [APPEND])
360 This defines a command to generate specified OUTPUT file(s). A
362 target created in the same directory (CMakeLists.txt file) that
363 specifies any output of the custom command as a source file is
364 given a rule to generate the file using the command at build
365 time. Do not list the output in more than one independent tar‐
366 get that may build in parallel or the two instances of the rule
367 may conflict (instead use add_custom_target to drive the command
368 and make the other targets depend on that one). If an output
369 name is a relative path it will be interpreted relative to the
370 build tree directory corresponding to the current source direc‐
371 tory. Note that MAIN_DEPENDENCY is completely optional and is
372 used as a suggestion to visual studio about where to hang the
373 custom command. In makefile terms this creates a new target in
374 the following form:
375 OUTPUT: MAIN_DEPENDENCY DEPENDS
378 COMMAND
379 If more than one command is specified they will be executed in
381 order. The optional ARGS argument is for backward compatibility
382 and will be ignored.
383 The second signature adds a custom command to a target such as a
386 library or executable. This is useful for performing an opera‐
387 tion before or after building the target. The command becomes
388 part of the target and will only execute when the target itself
389 is built. If the target is already built, the command will not
390 execute.
391 add_custom_command(TARGET target
394 PRE_BUILD | PRE_LINK | POST_BUILD
395 COMMAND command1 [ARGS] [args1...]
396 [COMMAND command2 [ARGS] [args2...] ...]
397 [WORKING_DIRECTORY dir]
398 [COMMENT comment] [VERBATIM])
399 This defines a new command that will be associated with building
401 the specified target. When the command will happen is determined
402 by which of the following is specified:
403 PRE_BUILD - run before all other dependencies
406 PRE_LINK - run after other dependencies
407 POST_BUILD - run after the target has been built
408 Note that the PRE_BUILD option is only supported on Visual Stu‐
410 dio 7 or later. For all other generators PRE_BUILD will be
411 treated as PRE_LINK.
412 If WORKING_DIRECTORY is specified the command will be executed
415 in the directory given. If it is a relative path it will be
416 interpreted relative to the build tree directory corresponding
417 to the current source directory. If COMMENT is set, the value
418 will be displayed as a message before the commands are executed
419 at build time. If APPEND is specified the COMMAND and DEPENDS
420 option values are appended to the custom command for the first
421 output specified. There must have already been a previous call
422 to this command with the same output. The COMMENT, WORK‐
423 ING_DIRECTORY, and MAIN_DEPENDENCY options are currently ignored
424 when APPEND is given, but may be used in the future.
425 If VERBATIM is given then all arguments to the commands will be
428 escaped properly for the build tool so that the invoked command
429 receives each argument unchanged. Note that one level of
430 escapes is still used by the CMake language processor before
431 add_custom_command even sees the arguments. Use of VERBATIM is
432 recommended as it enables correct behavior. When VERBATIM is not
433 given the behavior is platform specific because there is no pro‐
434 tection of tool-specific special characters.
435 If the output of the custom command is not actually created as a
438 file on disk it should be marked as SYMBOLIC with
439 SET_SOURCE_FILES_PROPERTIES.
440 The IMPLICIT_DEPENDS option requests scanning of implicit depen‐
443 dencies of an input file. The language given specifies the pro‐
444 gramming language whose corresponding dependency scanner should
445 be used. Currently only C and CXX language scanners are sup‐
446 ported. The language has to be specified for every file in the
447 IMPLICIT_DEPENDS list. Dependencies discovered from the scanning
448 are added to those of the custom command at build time. Note
449 that the IMPLICIT_DEPENDS option is currently supported only for
450 Makefile generators and will be ignored by other generators.
451 If COMMAND specifies an executable target (created by ADD_EXE‐
454 CUTABLE) it will automatically be replaced by the location of
455 the executable created at build time. Additionally a tar‐
456 get-level dependency will be added so that the executable target
457 will be built before any target using this custom command. How‐
458 ever this does NOT add a file-level dependency that would cause
459 the custom command to re-run whenever the executable is recom‐
460 piled.
461 Arguments to COMMAND may use "generator expressions" with the
464 syntax "$<...>". Generator expressions are evaluated during
465 build system generation to produce information specific to each
466 build configuration. Valid expressions are:
467 $<0:...> = empty string (ignores "...")
470 $<1:...> = content of "..."
471 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
472 $<CONFIGURATION> = configuration name
473 $<BOOL:...> = '1' if the '...' is true, else '0'
474 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
475 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
476 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
477 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
478 $<JOIN:list,...> = joins the list with the content of "..."
479 $<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.
480 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
481 $<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.
482 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
483 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
484 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
485 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
486 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
487 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
488 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
489 $<C_COMPILER_VERSION> = The version of the C compiler used.
490 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
491 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
492 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
493 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
494 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
495 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
496 where "tgt" is the name of a target. Target file expressions
498 produce a full path, but _DIR and _NAME versions can produce the
499 directory and file name components:
500 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
503 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
504 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
505 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
510 Note that tgt is not added as a dependency of the target this
512 expression is evaluated on.
513 $<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.
516 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
517 Boolean expressions:
519 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
522 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
523 $<NOT:?> = '0' if '?' is '1', else '1'
524 where '?' is always either '0' or '1'.
526 Expressions with an implicit 'this' target:
529 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
532 References to target names in generator expressions imply tar‐
534 get-level dependencies, but NOT file-level dependencies. List
535 target names with the DEPENDS option to add file dependencies.
536 The DEPENDS option specifies files on which the command depends.
539 If any dependency is an OUTPUT of another custom command in the
540 same directory (CMakeLists.txt file) CMake automatically brings
541 the other custom command into the target in which this command
542 is built. If DEPENDS is not specified the command will run
543 whenever the OUTPUT is missing; if the command does not actually
544 create the OUTPUT then the rule will always run. If DEPENDS
545 specifies any target (created by an ADD_* command) a tar‐
546 get-level dependency is created to make sure the target is built
547 before any target using this custom command. Additionally, if
548 the target is an executable or library a file-level dependency
549 is created to cause the custom command to re-run whenever the
550 target is recompiled.
551 add_custom_target
555 Add a target with no output so it will always be built.
556 add_custom_target(Name [ALL] [command1 [args1...]]
558 [COMMAND command2 [args2...] ...]
559 [DEPENDS depend depend depend ... ]
560 [WORKING_DIRECTORY dir]
561 [COMMENT comment] [VERBATIM]
562 [SOURCES src1 [src2...]])
563 Adds a target with the given name that executes the given com‐
565 mands. The target has no output file and is ALWAYS CONSIDERED
566 OUT OF DATE even if the commands try to create a file with the
567 name of the target. Use ADD_CUSTOM_COMMAND to generate a file
568 with dependencies. By default nothing depends on the custom tar‐
569 get. Use ADD_DEPENDENCIES to add dependencies to or from other
570 targets. If the ALL option is specified it indicates that this
571 target should be added to the default build target so that it
572 will be run every time (the command cannot be called ALL). The
573 command and arguments are optional and if not specified an empty
574 target will be created. If WORKING_DIRECTORY is set, then the
575 command will be run in that directory. If it is a relative path
576 it will be interpreted relative to the build tree directory cor‐
577 responding to the current source directory. If COMMENT is set,
578 the value will be displayed as a message before the commands are
579 executed at build time. Dependencies listed with the DEPENDS
580 argument may reference files and outputs of custom commands cre‐
581 ated with add_custom_command() in the same directory (CMake‐
582 Lists.txt file).
583 If VERBATIM is given then all arguments to the commands will be
586 escaped properly for the build tool so that the invoked command
587 receives each argument unchanged. Note that one level of
588 escapes is still used by the CMake language processor before
589 add_custom_target even sees the arguments. Use of VERBATIM is
590 recommended as it enables correct behavior. When VERBATIM is not
591 given the behavior is platform specific because there is no pro‐
592 tection of tool-specific special characters.
593 The SOURCES option specifies additional source files to be
596 included in the custom target. Specified source files will be
597 added to IDE project files for convenience in editing even if
598 they have not build rules.
599 add_definitions
602 Adds -D define flags to the compilation of source files.
603 add_definitions(-DFOO -DBAR ...)
605 Adds flags to the compiler command line for sources in the cur‐
607 rent directory and below. This command can be used to add any
608 flags, but it was originally intended to add preprocessor defi‐
609 nitions. Flags beginning in -D or /D that look like preproces‐
610 sor definitions are automatically added to the COMPILE_DEFINI‐
611 TIONS property for the current directory. Definitions with
612 non-trivial values may be left in the set of flags instead of
613 being converted for reasons of backwards compatibility. See
614 documentation of the directory, target, and source file COM‐
615 PILE_DEFINITIONS properties for details on adding preprocessor
616 definitions to specific scopes and configurations.
617 add_dependencies
620 Add a dependency between top-level targets.
621 add_dependencies(target-name depend-target1
623 depend-target2 ...)
624 Make a top-level target depend on other top-level targets. A
626 top-level target is one created by ADD_EXECUTABLE, ADD_LIBRARY,
627 or ADD_CUSTOM_TARGET. Adding dependencies with this command can
628 be used to make sure one target is built before another target.
629 Dependencies added to an IMPORTED target are followed transi‐
630 tively in its place since the target itself does not build. See
631 the DEPENDS option of ADD_CUSTOM_TARGET and ADD_CUSTOM_COMMAND
632 for adding file-level dependencies in custom rules. See the
633 OBJECT_DEPENDS option in SET_SOURCE_FILES_PROPERTIES to add
634 file-level dependencies to object files.
635 add_executable
638 Add an executable to the project using the specified source
639 files.
640 add_executable(<name> [WIN32] [MACOSX_BUNDLE]
642 [EXCLUDE_FROM_ALL]
643 source1 source2 ... sourceN)
644 Adds an executable target called <name> to be built from the
646 source files listed in the command invocation. The <name> cor‐
647 responds to the logical target name and must be globally unique
648 within a project. The actual file name of the executable built
649 is constructed based on conventions of the native platform (such
650 as <name>.exe or just <name>).
651 By default the executable file will be created in the build tree
654 directory corresponding to the source tree directory in which
655 the command was invoked. See documentation of the RUNTIME_OUT‐
656 PUT_DIRECTORY target property to change this location. See doc‐
657 umentation of the OUTPUT_NAME target property to change the
658 <name> part of the final file name.
659 If WIN32 is given the property WIN32_EXECUTABLE will be set on
662 the target created. See documentation of that target property
663 for details.
664 If MACOSX_BUNDLE is given the corresponding property will be set
667 on the created target. See documentation of the MACOSX_BUNDLE
668 target property for details.
669 If EXCLUDE_FROM_ALL is given the corresponding property will be
672 set on the created target. See documentation of the
673 EXCLUDE_FROM_ALL target property for details.
674 The add_executable command can also create IMPORTED executable
677 targets using this signature:
678 add_executable(<name> IMPORTED [GLOBAL])
681 An IMPORTED executable target references an executable file
683 located outside the project. No rules are generated to build
684 it. The target name has scope in the directory in which it is
685 created and below, but the GLOBAL option extends visibility. It
686 may be referenced like any target built within the project.
687 IMPORTED executables are useful for convenient reference from
688 commands like add_custom_command. Details about the imported
689 executable are specified by setting properties whose names begin
690 in "IMPORTED_". The most important such property is
691 IMPORTED_LOCATION (and its per-configuration version
692 IMPORTED_LOCATION_<CONFIG>) which specifies the location of the
693 main executable file on disk. See documentation of the
694 IMPORTED_* properties for more information.
695 The signature
698 add_executable(<name> ALIAS <target>)
701 creates an alias, such that <name> can be used to refer to <tar‐
703 get> in subsequent commands. The <name> does not appear in the
704 generated buildsystem as a make target. The <target> may not be
705 an IMPORTED target or an ALIAS. Alias targets can be used as
706 linkable targets, targets to read properties from, executables
707 for custom commands and custom targets. They can also be tested
708 for existance with the regular if(TARGET) subcommand. The
709 <name> may not be used to modify properties of <target>, that
710 is, it may not be used as the operand of set_property, set_tar‐
711 get_properties, target_link_libraries etc. An ALIAS target may
712 not be installed of exported.
713 add_library
716 Add a library to the project using the specified source files.
717 add_library(<name> [STATIC | SHARED | MODULE]
719 [EXCLUDE_FROM_ALL]
720 source1 source2 ... sourceN)
721 Adds a library target called <name> to be built from the source
723 files listed in the command invocation. The <name> corresponds
724 to the logical target name and must be globally unique within a
725 project. The actual file name of the library built is con‐
726 structed based on conventions of the native platform (such as
727 lib<name>.a or <name>.lib).
728 STATIC, SHARED, or MODULE may be given to specify the type of
731 library to be created. STATIC libraries are archives of object
732 files for use when linking other targets. SHARED libraries are
733 linked dynamically and loaded at runtime. MODULE libraries are
734 plugins that are not linked into other targets but may be loaded
735 dynamically at runtime using dlopen-like functionality. If no
736 type is given explicitly the type is STATIC or SHARED based on
737 whether the current value of the variable BUILD_SHARED_LIBS is
738 true. For SHARED and MODULE libraries the POSITION_INDEPEN‐
739 DENT_CODE target property is set to TRUE automatically.
740 By default the library file will be created in the build tree
743 directory corresponding to the source tree directory in which
744 the command was invoked. See documentation of the ARCHIVE_OUT‐
745 PUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUT‐
746 PUT_DIRECTORY target properties to change this location. See
747 documentation of the OUTPUT_NAME target property to change the
748 <name> part of the final file name.
749 If EXCLUDE_FROM_ALL is given the corresponding property will be
752 set on the created target. See documentation of the
753 EXCLUDE_FROM_ALL target property for details.
754 The add_library command can also create IMPORTED library targets
757 using this signature:
758 add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED
761 [GLOBAL])
762 An IMPORTED library target references a library file located
764 outside the project. No rules are generated to build it. The
765 target name has scope in the directory in which it is created
766 and below, but the GLOBAL option extends visibility. It may be
767 referenced like any target built within the project. IMPORTED
768 libraries are useful for convenient reference from commands like
769 target_link_libraries. Details about the imported library are
770 specified by setting properties whose names begin in
771 "IMPORTED_". The most important such property is IMPORTED_LOCA‐
772 TION (and its per-configuration version IMPORTED_LOCATION_<CON‐
773 FIG>) which specifies the location of the main library file on
774 disk. See documentation of the IMPORTED_* properties for more
775 information.
776 The signature
779 add_library(<name> OBJECT <src>...)
782 creates a special "object library" target. An object library
784 compiles source files but does not archive or link their object
785 files into a library. Instead other targets created by
786 add_library or add_executable may reference the objects using an
787 expression of the form $<TARGET_OBJECTS:objlib> as a source,
788 where "objlib" is the object library name. For example:
789 add_library(... $<TARGET_OBJECTS:objlib> ...)
792 add_executable(... $<TARGET_OBJECTS:objlib> ...)
793 will include objlib's object files in a library and an exe‐
795 cutable along with those compiled from their own sources.
796 Object libraries may contain only sources (and headers) that
797 compile to object files. They may contain custom commands gen‐
798 erating such sources, but not PRE_BUILD, PRE_LINK, or POST_BUILD
799 commands. Object libraries cannot be imported, exported,
800 installed, or linked. Some native build systems may not like
801 targets that have only object files, so consider adding at least
802 one real source file to any target that references $<TAR‐
803 GET_OBJECTS:objlib>.
804 The signature
807 add_library(<name> ALIAS <target>)
810 creates an alias, such that <name> can be used to refer to <tar‐
812 get> in subsequent commands. The <name> does not appear in the
813 generated buildsystem as a make target. The <target> may not be
814 an IMPORTED target or an ALIAS. Alias targets can be used as
815 linkable targets, targets to read properties from. They can
816 also be tested for existance with the regular if(TARGET) subcom‐
817 mand. The <name> may not be used to modify properties of <tar‐
818 get>, that is, it may not be used as the operand of set_prop‐
819 erty, set_target_properties, target_link_libraries etc. An
820 ALIAS target may not be installed of exported.
821 add_subdirectory
824 Add a subdirectory to the build.
825 add_subdirectory(source_dir [binary_dir]
827 [EXCLUDE_FROM_ALL])
828 Add a subdirectory to the build. The source_dir specifies the
830 directory in which the source CMakeLists.txt and code files are
831 located. If it is a relative path it will be evaluated with
832 respect to the current directory (the typical usage), but it may
833 also be an absolute path. The binary_dir specifies the directory
834 in which to place the output files. If it is a relative path it
835 will be evaluated with respect to the current output directory,
836 but it may also be an absolute path. If binary_dir is not speci‐
837 fied, the value of source_dir, before expanding any relative
838 path, will be used (the typical usage). The CMakeLists.txt file
839 in the specified source directory will be processed immediately
840 by CMake before processing in the current input file continues
841 beyond this command.
842 If the EXCLUDE_FROM_ALL argument is provided then targets in the
845 subdirectory will not be included in the ALL target of the par‐
846 ent directory by default, and will be excluded from IDE project
847 files. Users must explicitly build targets in the subdirectory.
848 This is meant for use when the subdirectory contains a separate
849 part of the project that is useful but not necessary, such as a
850 set of examples. Typically the subdirectory should contain its
851 own project() command invocation so that a full build system
852 will be generated in the subdirectory (such as a VS IDE solution
853 file). Note that inter-target dependencies supercede this
854 exclusion. If a target built by the parent project depends on a
855 target in the subdirectory, the dependee target will be included
856 in the parent project build system to satisfy the dependency.
857 add_test
860 Add a test to the project with the specified arguments.
861 add_test(testname Exename arg1 arg2 ... )
863 If the ENABLE_TESTING command has been run, this command adds a
865 test target to the current directory. If ENABLE_TESTING has not
866 been run, this command does nothing. The tests are run by the
867 testing subsystem by executing Exename with the specified argu‐
868 ments. Exename can be either an executable built by this
869 project or an arbitrary executable on the system (like tclsh).
870 The test will be run with the current working directory set to
871 the CMakeList.txt files corresponding directory in the binary
872 tree.
873 add_test(NAME <name> [CONFIGURATIONS [Debug|Release|...]]
879 [WORKING_DIRECTORY dir]
880 COMMAND <command> [arg1 [arg2 ...]])
881 Add a test called <name>. The test name may not contain spaces,
883 quotes, or other characters special in CMake syntax. If COMMAND
884 specifies an executable target (created by add_executable) it
885 will automatically be replaced by the location of the executable
886 created at build time. If a CONFIGURATIONS option is given then
887 the test will be executed only when testing under one of the
888 named configurations. If a WORKING_DIRECTORY option is given
889 then the test will be executed in the given directory.
890 Arguments after COMMAND may use "generator expressions" with the
893 syntax "$<...>". Generator expressions are evaluated during
894 build system generation to produce information specific to each
895 build configuration. Valid expressions are:
896 $<0:...> = empty string (ignores "...")
899 $<1:...> = content of "..."
900 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
901 $<CONFIGURATION> = configuration name
902 $<BOOL:...> = '1' if the '...' is true, else '0'
903 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
904 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
905 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
906 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
907 $<JOIN:list,...> = joins the list with the content of "..."
908 $<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.
909 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
910 $<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.
911 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
912 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
913 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
914 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
915 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
916 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
917 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
918 $<C_COMPILER_VERSION> = The version of the C compiler used.
919 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
920 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
921 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
922 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
923 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
924 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
925 where "tgt" is the name of a target. Target file expressions
927 produce a full path, but _DIR and _NAME versions can produce the
928 directory and file name components:
929 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
932 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
933 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
934 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
939 Note that tgt is not added as a dependency of the target this
941 expression is evaluated on.
942 $<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.
945 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
946 Boolean expressions:
948 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
951 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
952 $<NOT:?> = '0' if '?' is '1', else '1'
953 where '?' is always either '0' or '1'.
955 Example usage:
958 add_test(NAME mytest
961 COMMAND testDriver --config $<CONFIGURATION>
962 --exe $<TARGET_FILE:myexe>)
963 This creates a test "mytest" whose command runs a testDriver
965 tool passing the configuration name and the full path to the
966 executable file produced by target "myexe".
967 aux_source_directory
970 Find all source files in a directory.
971 aux_source_directory(<dir> <variable>)
973 Collects the names of all the source files in the specified
975 directory and stores the list in the <variable> provided. This
976 command is intended to be used by projects that use explicit
977 template instantiation. Template instantiation files can be
978 stored in a "Templates" subdirectory and collected automatically
979 using this command to avoid manually listing all instantiations.
980 It is tempting to use this command to avoid writing the list of
983 source files for a library or executable target. While this
984 seems to work, there is no way for CMake to generate a build
985 system that knows when a new source file has been added. Nor‐
986 mally the generated build system knows when it needs to rerun
987 CMake because the CMakeLists.txt file is modified to add a new
988 source. When the source is just added to the directory without
989 modifying this file, one would have to manually rerun CMake to
990 generate a build system incorporating the new file.
991 break Break from an enclosing foreach or while loop.
994 break()
996 Breaks from an enclosing foreach loop or while loop
998 build_command
1001 Get the command line to build this project.
1002 build_command(<variable>
1004 [CONFIGURATION <config>]
1005 [PROJECT_NAME <projname>]
1006 [TARGET <target>])
1007 Sets the given <variable> to a string containing the command
1009 line for building one configuration of a target in a project
1010 using the build tool appropriate for the current CMAKE_GENERA‐
1011 TOR.
1012 If CONFIGURATION is omitted, CMake chooses a reasonable default
1015 value for multi-configuration generators. CONFIGURATION is
1016 ignored for single-configuration generators.
1017 If PROJECT_NAME is omitted, the resulting command line will
1020 build the top level PROJECT in the current build tree.
1021 If TARGET is omitted, the resulting command line will build
1024 everything, effectively using build target 'all' or 'ALL_BUILD'.
1025 build_command(<cachevariable> <makecommand>)
1028 This second signature is deprecated, but still available for
1030 backwards compatibility. Use the first signature instead.
1031 Sets the given <cachevariable> to a string containing the com‐
1034 mand to build this project from the root of the build tree using
1035 the build tool given by <makecommand>. <makecommand> should be
1036 the full path to msdev, devenv, nmake, make or one of the end
1037 user build tools.
1038 cmake_host_system_information
1041 Query host system specific information.
1042 cmake_host_system_information(RESULT <variable> QUERY <key> ...)
1044 Queries system information of the host system on which cmake
1046 runs. One or more <key> can be provided to select the informa‐
1047 tion to be queried. The list of queried values is stored in
1048 <variable>.
1049 <key> can be one of the following values:
1052 NUMBER_OF_LOGICAL_CORES = Number of logical cores.
1055 NUMBER_OF_PHYSICAL_CORES = Number of physical cores.
1056 HOSTNAME = Hostname.
1057 FQDN = Fully qualified domain name.
1058 TOTAL_VIRTUAL_MEMORY = Total virtual memory in megabytes.
1059 AVAILABLE_VIRTUAL_MEMORY = Available virtual memory in megabytes.
1060 TOTAL_PHYSICAL_MEMORY = Total physical memory in megabytes.
1061 AVAILABLE_PHYSICAL_MEMORY = Available physical memory in megabytes.
1062 cmake_minimum_required
1065 Set the minimum required version of cmake for a project.
1066 cmake_minimum_required(VERSION major[.minor[.patch[.tweak]]]
1068 [FATAL_ERROR])
1069 If the current version of CMake is lower than that required it
1071 will stop processing the project and report an error. When a
1072 version higher than 2.4 is specified the command implicitly
1073 invokes
1074 cmake_policy(VERSION major[.minor[.patch[.tweak]]])
1077 which sets the cmake policy version level to the version speci‐
1079 fied. When version 2.4 or lower is given the command implicitly
1080 invokes
1081 cmake_policy(VERSION 2.4)
1084 which enables compatibility features for CMake 2.4 and lower.
1086 The FATAL_ERROR option is accepted but ignored by CMake 2.6 and
1089 higher. It should be specified so CMake versions 2.4 and lower
1090 fail with an error instead of just a warning.
1091 cmake_policy
1094 Manage CMake Policy settings.
1095 As CMake evolves it is sometimes necessary to change existing
1097 behavior in order to fix bugs or improve implementations of
1098 existing features. The CMake Policy mechanism is designed to
1099 help keep existing projects building as new versions of CMake
1100 introduce changes in behavior. Each new policy (behavioral
1101 change) is given an identifier of the form "CMP<NNNN>" where
1102 "<NNNN>" is an integer index. Documentation associated with
1103 each policy describes the OLD and NEW behavior and the reason
1104 the policy was introduced. Projects may set each policy to
1105 select the desired behavior. When CMake needs to know which
1106 behavior to use it checks for a setting specified by the
1107 project. If no setting is available the OLD behavior is assumed
1108 and a warning is produced requesting that the policy be set.
1109 The cmake_policy command is used to set policies to OLD or NEW
1112 behavior. While setting policies individually is supported, we
1113 encourage projects to set policies based on CMake versions.
1114 cmake_policy(VERSION major.minor[.patch[.tweak]])
1117 Specify that the current CMake list file is written for the
1119 given version of CMake. All policies introduced in the speci‐
1120 fied version or earlier will be set to use NEW behavior. All
1121 policies introduced after the specified version will be unset
1122 (unless variable CMAKE_POLICY_DEFAULT_CMP<NNNN> sets a default).
1123 This effectively requests behavior preferred as of a given CMake
1124 version and tells newer CMake versions to warn about their new
1125 policies. The policy version specified must be at least 2.4 or
1126 the command will report an error. In order to get compatibility
1127 features supporting versions earlier than 2.4 see documentation
1128 of policy CMP0001.
1129 cmake_policy(SET CMP<NNNN> NEW)
1132 cmake_policy(SET CMP<NNNN> OLD)
1133 Tell CMake to use the OLD or NEW behavior for a given policy.
1135 Projects depending on the old behavior of a given policy may
1136 silence a policy warning by setting the policy state to OLD.
1137 Alternatively one may fix the project to work with the new
1138 behavior and set the policy state to NEW.
1139 cmake_policy(GET CMP<NNNN> <variable>)
1142 Check whether a given policy is set to OLD or NEW behavior. The
1144 output variable value will be "OLD" or "NEW" if the policy is
1145 set, and empty otherwise.
1146 CMake keeps policy settings on a stack, so changes made by the
1149 cmake_policy command affect only the top of the stack. A new
1150 entry on the policy stack is managed automatically for each sub‐
1151 directory to protect its parents and siblings. CMake also man‐
1152 ages a new entry for scripts loaded by include() and find_pack‐
1153 age() commands except when invoked with the NO_POLICY_SCOPE
1154 option (see also policy CMP0011). The cmake_policy command pro‐
1155 vides an interface to manage custom entries on the policy stack:
1156 cmake_policy(PUSH)
1159 cmake_policy(POP)
1160 Each PUSH must have a matching POP to erase any changes. This
1162 is useful to make temporary changes to policy settings.
1163 Functions and macros record policy settings when they are cre‐
1166 ated and use the pre-record policies when they are invoked. If
1167 the function or macro implementation sets policies, the changes
1168 automatically propagate up through callers until they reach the
1169 closest nested policy stack entry.
1170 configure_file
1173 Copy a file to another location and modify its contents.
1174 configure_file(<input> <output>
1176 [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
1177 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
1178 Copies a file <input> to file <output> and substitutes variable
1180 values referenced in the file content. If <input> is a relative
1181 path it is evaluated with respect to the current source direc‐
1182 tory. The <input> must be a file, not a directory. If <output>
1183 is a relative path it is evaluated with respect to the current
1184 binary directory. If <output> names an existing directory the
1185 input file is placed in that directory with its original name.
1186 If the <input> file is modified the build system will re-run
1189 CMake to re-configure the file and generate the build system
1190 again.
1191 This command replaces any variables in the input file referenced
1194 as ${VAR} or @VAR@ with their values as determined by CMake. If
1195 a variable is not defined, it will be replaced with nothing. If
1196 COPYONLY is specified, then no variable expansion will take
1197 place. If ESCAPE_QUOTES is specified then any substituted
1198 quotes will be C-style escaped. The file will be configured
1199 with the current values of CMake variables. If @ONLY is speci‐
1200 fied, only variables of the form @VAR@ will be replaced and
1201 ${VAR} will be ignored. This is useful for configuring scripts
1202 that use ${VAR}.
1203 Input file lines of the form "#cmakedefine VAR ..." will be
1206 replaced with either "#define VAR ..." or "/* #undef VAR */"
1207 depending on whether VAR is set in CMake to any value not con‐
1208 sidered a false constant by the if() command. (Content of "...",
1209 if any, is processed as above.) Input file lines of the form
1210 "#cmakedefine01 VAR" will be replaced with either "#define VAR
1211 1" or "#define VAR 0" similarly.
1212 With NEWLINE_STYLE the line ending could be adjusted:
1215 'UNIX' or 'LF' for \n, 'DOS', 'WIN32' or 'CRLF' for \r\n.
1218 COPYONLY must not be used with NEWLINE_STYLE.
1220 create_test_sourcelist
1224 Create a test driver and source list for building test programs.
1225 create_test_sourcelist(sourceListName driverName
1227 test1 test2 test3
1228 EXTRA_INCLUDE include.h
1229 FUNCTION function)
1230 A test driver is a program that links together many small tests
1232 into a single executable. This is useful when building static
1233 executables with large libraries to shrink the total required
1234 size. The list of source files needed to build the test driver
1235 will be in sourceListName. DriverName is the name of the test
1236 driver program. The rest of the arguments consist of a list of
1237 test source files, can be semicolon separated. Each test source
1238 file should have a function in it that is the same name as the
1239 file with no extension (foo.cxx should have int foo(int,
1240 char*[]);) DriverName will be able to call each of the tests by
1241 name on the command line. If EXTRA_INCLUDE is specified, then
1242 the next argument is included into the generated file. If FUNC‐
1243 TION is specified, then the next argument is taken as a function
1244 name that is passed a pointer to ac and av. This can be used to
1245 add extra command line processing to each test. The cmake vari‐
1246 able CMAKE_TESTDRIVER_BEFORE_TESTMAIN can be set to have code
1247 that will be placed directly before calling the test main func‐
1248 tion. CMAKE_TESTDRIVER_AFTER_TESTMAIN can be set to have code
1249 that will be placed directly after the call to the test main
1250 function.
1251 define_property
1254 Define and document custom properties.
1255 define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
1257 TEST | VARIABLE | CACHED_VARIABLE>
1258 PROPERTY <name> [INHERITED]
1259 BRIEF_DOCS <brief-doc> [docs...]
1260 FULL_DOCS <full-doc> [docs...])
1261 Define one property in a scope for use with the set_property and
1263 get_property commands. This is primarily useful to associate
1264 documentation with property names that may be retrieved with the
1265 get_property command. The first argument determines the kind of
1266 scope in which the property should be used. It must be one of
1267 the following:
1268 GLOBAL = associated with the global namespace
1271 DIRECTORY = associated with one directory
1272 TARGET = associated with one target
1273 SOURCE = associated with one source file
1274 TEST = associated with a test named with add_test
1275 VARIABLE = documents a CMake language variable
1276 CACHED_VARIABLE = documents a CMake cache variable
1277 Note that unlike set_property and get_property no actual scope
1279 needs to be given; only the kind of scope is important.
1280 The required PROPERTY option is immediately followed by the name
1283 of the property being defined.
1284 If the INHERITED option then the get_property command will chain
1287 up to the next higher scope when the requested property is not
1288 set in the scope given to the command. DIRECTORY scope chains
1289 to GLOBAL. TARGET, SOURCE, and TEST chain to DIRECTORY.
1290 The BRIEF_DOCS and FULL_DOCS options are followed by strings to
1293 be associated with the property as its brief and full documenta‐
1294 tion. Corresponding options to the get_property command will
1295 retrieve the documentation.
1296 else Starts the else portion of an if block.
1299 else(expression)
1301 See the if command.
1303 elseif Starts the elseif portion of an if block.
1306 elseif(expression)
1308 See the if command.
1310 enable_language
1313 Enable a language (CXX/C/Fortran/etc)
1314 enable_language(<lang> [OPTIONAL] )
1316 This command enables support for the named language in CMake.
1318 This is the same as the project command but does not create any
1319 of the extra variables that are created by the project command.
1320 Example languages are CXX, C, Fortran.
1321 This command must be called in file scope, not in a function
1324 call. Furthermore, it must be called in the highest directory
1325 common to all targets using the named language directly for com‐
1326 piling sources or indirectly through link dependencies. It is
1327 simplest to enable all needed languages in the top-level direc‐
1328 tory of a project.
1329 The OPTIONAL keyword is a placeholder for future implementation
1332 and does not currently work.
1333 enable_testing
1336 Enable testing for current directory and below.
1337 enable_testing()
1339 Enables testing for this directory and below. See also the
1341 add_test command. Note that ctest expects to find a test file
1342 in the build directory root. Therefore, this command should be
1343 in the source directory root.
1344 endforeach
1347 Ends a list of commands in a FOREACH block.
1348 endforeach(expression)
1350 See the FOREACH command.
1352 endfunction
1355 Ends a list of commands in a function block.
1356 endfunction(expression)
1358 See the function command.
1360 endif Ends a list of commands in an if block.
1363 endif(expression)
1365 See the if command.
1367 endmacro
1370 Ends a list of commands in a macro block.
1371 endmacro(expression)
1373 See the macro command.
1375 endwhile
1378 Ends a list of commands in a while block.
1379 endwhile(expression)
1381 See the while command.
1383 execute_process
1386 Execute one or more child processes.
1387 execute_process(COMMAND <cmd1> [args1...]]
1389 [COMMAND <cmd2> [args2...] [...]]
1390 [WORKING_DIRECTORY <directory>]
1391 [TIMEOUT <seconds>]
1392 [RESULT_VARIABLE <variable>]
1393 [OUTPUT_VARIABLE <variable>]
1394 [ERROR_VARIABLE <variable>]
1395 [INPUT_FILE <file>]
1396 [OUTPUT_FILE <file>]
1397 [ERROR_FILE <file>]
1398 [OUTPUT_QUIET]
1399 [ERROR_QUIET]
1400 [OUTPUT_STRIP_TRAILING_WHITESPACE]
1401 [ERROR_STRIP_TRAILING_WHITESPACE])
1402 Runs the given sequence of one or more commands with the stan‐
1404 dard output of each process piped to the standard input of the
1405 next. A single standard error pipe is used for all processes.
1406 If WORKING_DIRECTORY is given the named directory will be set as
1407 the current working directory of the child processes. If TIME‐
1408 OUT is given the child processes will be terminated if they do
1409 not finish in the specified number of seconds (fractions are
1410 allowed). If RESULT_VARIABLE is given the variable will be set
1411 to contain the result of running the processes. This will be an
1412 integer return code from the last child or a string describing
1413 an error condition. If OUTPUT_VARIABLE or ERROR_VARIABLE are
1414 given the variable named will be set with the contents of the
1415 standard output and standard error pipes respectively. If the
1416 same variable is named for both pipes their output will be
1417 merged in the order produced. If INPUT_FILE, OUTPUT_FILE, or
1418 ERROR_FILE is given the file named will be attached to the stan‐
1419 dard input of the first process, standard output of the last
1420 process, or standard error of all processes respectively. If
1421 OUTPUT_QUIET or ERROR_QUIET is given then the standard output or
1422 standard error results will be quietly ignored. If more than
1423 one OUTPUT_* or ERROR_* option is given for the same pipe the
1424 precedence is not specified. If no OUTPUT_* or ERROR_* options
1425 are given the output will be shared with the corresponding pipes
1426 of the CMake process itself.
1427 The execute_process command is a newer more powerful version of
1430 exec_program, but the old command has been kept for compatibil‐
1431 ity.
1432 export Export targets from the build tree for use by outside projects.
1435 export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
1437 [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
1438 Create a file <filename> that may be included by outside
1440 projects to import targets from the current project's build
1441 tree. This is useful during cross-compiling to build utility
1442 executables that can run on the host platform in one project and
1443 then import them into another project being compiled for the
1444 target platform. If the NAMESPACE option is given the <names‐
1445 pace> string will be prepended to all target names written to
1446 the file. If the APPEND option is given the generated code will
1447 be appended to the file instead of overwriting it. The
1448 EXPORT_LINK_INTERFACE_LIBRARIES keyword, if present, causes the
1449 contents of the properties matching (IMPORTED_)?LINK_INTER‐
1450 FACE_LIBRARIES(_<CONFIG>)? to be exported, when policy CMP0022
1451 is NEW. If a library target is included in the export but a
1452 target to which it links is not included the behavior is unspec‐
1453 ified.
1454 The file created by this command is specific to the build tree
1457 and should never be installed. See the install(EXPORT) command
1458 to export targets from an installation tree.
1459 Do not set properties that affect the location of a target after
1462 passing it to this command. These include properties whose
1463 names match "(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIREC‐
1464 TORY)(_<CONFIG>)?", "(IMPLIB_)?(PREFIX|SUFFIX)", or "LINKER_LAN‐
1465 GUAGE". Failure to follow this rule is not diagnosed and leaves
1466 the location of the target undefined.
1467 export(PACKAGE <name>)
1470 Store the current build directory in the CMake user package reg‐
1472 istry for package <name>. The find_package command may consider
1473 the directory while searching for package <name>. This helps
1474 dependent projects find and use a package from the current
1475 project's build tree without help from the user. Note that the
1476 entry in the package registry that this command creates works
1477 only in conjunction with a package configuration file
1478 (<name>Config.cmake) that works with the build tree.
1479 file File manipulation command.
1482 file(WRITE filename "message to write"... )
1484 file(APPEND filename "message to write"... )
1485 file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX])
1486 file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> filename variable)
1487 file(STRINGS filename variable [LIMIT_COUNT num]
1488 [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes]
1489 [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes]
1490 [NEWLINE_CONSUME] [REGEX regex]
1491 [NO_HEX_CONVERSION])
1492 file(GLOB variable [RELATIVE path] [globbing expressions]...)
1493 file(GLOB_RECURSE variable [RELATIVE path]
1494 [FOLLOW_SYMLINKS] [globbing expressions]...)
1495 file(RENAME <oldname> <newname>)
1496 file(REMOVE [file1 ...])
1497 file(REMOVE_RECURSE [file1 ...])
1498 file(MAKE_DIRECTORY [directory1 directory2 ...])
1499 file(RELATIVE_PATH variable directory file)
1500 file(TO_CMAKE_PATH path result)
1501 file(TO_NATIVE_PATH path result)
1502 file(DOWNLOAD url file [INACTIVITY_TIMEOUT timeout]
1503 [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS]
1504 [EXPECTED_HASH ALGO=value] [EXPECTED_MD5 sum]
1505 [TLS_VERIFY on|off] [TLS_CAINFO file])
1506 file(UPLOAD filename url [INACTIVITY_TIMEOUT timeout]
1507 [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS])
1508 file(TIMESTAMP filename variable [<format string>] [UTC])
1509 file(GENERATE OUTPUT output_file
1510 <INPUT input_file|CONTENT input_content>
1511 [CONDITION expression])
1512 WRITE will write a message into a file called 'filename'. It
1514 overwrites the file if it already exists, and creates the file
1515 if it does not exist. (If the file is a build input, use config‐
1516 ure_file to update the file only when its content changes.)
1517 APPEND will write a message into a file same as WRITE, except it
1520 will append it to the end of the file
1521 READ will read the content of a file and store it into the vari‐
1524 able. It will start at the given offset and read up to numBytes.
1525 If the argument HEX is given, the binary data will be converted
1526 to hexadecimal representation and this will be stored in the
1527 variable.
1528 MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a
1531 cryptographic hash of the content of a file.
1532 STRINGS will parse a list of ASCII strings from a file and store
1535 it in a variable. Binary data in the file are ignored. Carriage
1536 return (CR) characters are ignored. It works also for Intel Hex
1537 and Motorola S-record files, which are automatically converted
1538 to binary format when reading them. Disable this using
1539 NO_HEX_CONVERSION.
1540 LIMIT_COUNT sets the maximum number of strings to return.
1543 LIMIT_INPUT sets the maximum number of bytes to read from the
1544 input file. LIMIT_OUTPUT sets the maximum number of bytes to
1545 store in the output variable. LENGTH_MINIMUM sets the minimum
1546 length of a string to return. Shorter strings are ignored.
1547 LENGTH_MAXIMUM sets the maximum length of a string to return.
1548 Longer strings are split into strings no longer than the maximum
1549 length. NEWLINE_CONSUME allows newlines to be included in
1550 strings instead of terminating them.
1551 REGEX specifies a regular expression that a string must match to
1554 be returned. Typical usage
1555 file(STRINGS myfile.txt myfile)
1558 stores a list in the variable "myfile" in which each item is a
1560 line from the input file.
1561 GLOB will generate a list of all files that match the globbing
1564 expressions and store it into the variable. Globbing expressions
1565 are similar to regular expressions, but much simpler. If RELA‐
1566 TIVE flag is specified for an expression, the results will be
1567 returned as a relative path to the given path. (We do not rec‐
1568 ommend using GLOB to collect a list of source files from your
1569 source tree. If no CMakeLists.txt file changes when a source is
1570 added or removed then the generated build system cannot know
1571 when to ask CMake to regenerate.)
1572 Examples of globbing expressions include:
1575 *.cxx - match all files with extension cxx
1578 *.vt? - match all files with extension vta,...,vtz
1579 f[3-5].txt - match files f3.txt, f4.txt, f5.txt
1580 GLOB_RECURSE will generate a list similar to the regular GLOB,
1582 except it will traverse all the subdirectories of the matched
1583 directory and match the files. Subdirectories that are symlinks
1584 are only traversed if FOLLOW_SYMLINKS is given or cmake policy
1585 CMP0009 is not set to NEW. See cmake --help-policy CMP0009 for
1586 more information.
1587 Examples of recursive globbing include:
1590 /dir/*.py - match all python files in /dir and subdirectories
1593 MAKE_DIRECTORY will create the given directories, also if their
1595 parent directories don't exist yet
1596 RENAME moves a file or directory within a filesystem, replacing
1599 the destination atomically.
1600 REMOVE will remove the given files, also in subdirectories
1603 REMOVE_RECURSE will remove the given files and directories, also
1606 non-empty directories
1607 RELATIVE_PATH will determine relative path from directory to the
1610 given file.
1611 TO_CMAKE_PATH will convert path into a cmake style path with
1614 unix /. The input can be a single path or a system path like
1615 "$ENV{PATH}". Note the double quotes around the ENV call
1616 TO_CMAKE_PATH only takes one argument. This command will also
1617 convert the native list delimiters for a list of paths like the
1618 PATH environment variable.
1619 TO_NATIVE_PATH works just like TO_CMAKE_PATH, but will convert
1622 from a cmake style path into the native path style \ for win‐
1623 dows and / for UNIX.
1624 DOWNLOAD will download the given URL to the given file. If LOG
1627 var is specified a log of the download will be put in var. If
1628 STATUS var is specified the status of the operation will be put
1629 in var. The status is returned in a list of length 2. The first
1630 element is the numeric return value for the operation, and the
1631 second element is a string value for the error. A 0 numeric
1632 error means no error in the operation. If TIMEOUT time is speci‐
1633 fied, the operation will timeout after time seconds, time should
1634 be specified as an integer. The INACTIVITY_TIMEOUT specifies an
1635 integer number of seconds of inactivity after which the opera‐
1636 tion should terminate. If EXPECTED_HASH ALGO=value is specified,
1637 the operation will verify that the downloaded file's actual hash
1638 matches the expected value, where ALGO is one of MD5, SHA1,
1639 SHA224, SHA256, SHA384, or SHA512. If it does not match, the
1640 operation fails with an error. ("EXPECTED_MD5 sum" is short-hand
1641 for "EXPECTED_HASH MD5=sum".) If SHOW_PROGRESS is specified,
1642 progress information will be printed as status messages until
1643 the operation is complete. For https URLs CMake must be built
1644 with OpenSSL. TLS/SSL certificates are not checked by default.
1645 Set TLS_VERIFY to ON to check certificates and/or use
1646 EXPECTED_HASH to verify downloaded content. Set TLS_CAINFO to
1647 specify a custom Certificate Authority file. If either TLS
1648 option is not given CMake will check variables CMAKE_TLS_VERIFY
1649 and CMAKE_TLS_CAINFO, respectively.
1650 UPLOAD will upload the given file to the given URL. If LOG var
1653 is specified a log of the upload will be put in var. If STATUS
1654 var is specified the status of the operation will be put in var.
1655 The status is returned in a list of length 2. The first element
1656 is the numeric return value for the operation, and the second
1657 element is a string value for the error. A 0 numeric error means
1658 no error in the operation. If TIMEOUT time is specified, the
1659 operation will timeout after time seconds, time should be speci‐
1660 fied as an integer. The INACTIVITY_TIMEOUT specifies an integer
1661 number of seconds of inactivity after which the operation should
1662 terminate. If SHOW_PROGRESS is specified, progress information
1663 will be printed as status messages until the operation is com‐
1664 plete.
1665 TIMESTAMP will write a string representation of the modification
1668 time of filename to variable.
1669 Should the command be unable to obtain a timestamp variable will
1672 be set to the empty string "".
1673 See documentation of the string TIMESTAMP sub-command for more
1676 details.
1677 The file() command also provides COPY and INSTALL signatures:
1680 file(<COPY|INSTALL> files... DESTINATION <dir>
1683 [FILE_PERMISSIONS permissions...]
1684 [DIRECTORY_PERMISSIONS permissions...]
1685 [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
1686 [FILES_MATCHING]
1687 [[PATTERN <pattern> | REGEX <regex>]
1688 [EXCLUDE] [PERMISSIONS permissions...]] [...])
1689 The COPY signature copies files, directories, and symlinks to a
1691 destination folder. Relative input paths are evaluated with
1692 respect to the current source directory, and a relative destina‐
1693 tion is evaluated with respect to the current build directory.
1694 Copying preserves input file timestamps, and optimizes out a
1695 file if it exists at the destination with the same timestamp.
1696 Copying preserves input permissions unless explicit permissions
1697 or NO_SOURCE_PERMISSIONS are given (default is USE_SOURCE_PER‐
1698 MISSIONS). See the install(DIRECTORY) command for documentation
1699 of permissions, PATTERN, REGEX, and EXCLUDE options.
1700 The INSTALL signature differs slightly from COPY: it prints sta‐
1703 tus messages, and NO_SOURCE_PERMISSIONS is default. Installa‐
1704 tion scripts generated by the install() command use this signa‐
1705 ture (with some undocumented options for internal use).
1706 GENERATE will write an <output_file> with content from an
1709 <input_file>, or from <input_content>. The output is generated
1710 conditionally based on the content of the <condition>. The file
1711 is written at CMake generate-time and the input may contain gen‐
1712 erator expressions. The <condition>, <output_file> and
1713 <input_file> may also contain generator expressions. The <con‐
1714 dition> must evaluate to either '0' or '1'. The <output_file>
1715 must evaluate to a unique name among all configurations and
1716 among all invocations of file(GENERATE).
1717 find_file
1720 Find the full path to a file.
1721 find_file(<VAR> name1 [path1 path2 ...])
1723 This is the short-hand signature for the command that is suffi‐
1725 cient in many cases. It is the same as find_file(<VAR> name1
1726 [PATHS path1 path2 ...])
1727 find_file(
1730 <VAR>
1731 name | NAMES name1 [name2 ...]
1732 [HINTS path1 [path2 ... ENV var]]
1733 [PATHS path1 [path2 ... ENV var]]
1734 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1735 [DOC "cache documentation string"]
1736 [NO_DEFAULT_PATH]
1737 [NO_CMAKE_ENVIRONMENT_PATH]
1738 [NO_CMAKE_PATH]
1739 [NO_SYSTEM_ENVIRONMENT_PATH]
1740 [NO_CMAKE_SYSTEM_PATH]
1741 [CMAKE_FIND_ROOT_PATH_BOTH |
1742 ONLY_CMAKE_FIND_ROOT_PATH |
1743 NO_CMAKE_FIND_ROOT_PATH]
1744 )
1745 This command is used to find a full path to named file. A cache
1747 entry named by <VAR> is created to store the result of this com‐
1748 mand. If the full path to a file is found the result is stored
1749 in the variable and the search will not be repeated unless the
1750 variable is cleared. If nothing is found, the result will be
1751 <VAR>-NOTFOUND, and the search will be attempted again the next
1752 time find_file is invoked with the same variable. The name of
1753 the full path to a file that is searched for is specified by the
1754 names listed after the NAMES argument. Additional search loca‐
1755 tions can be specified after the PATHS argument. If ENV var is
1756 found in the HINTS or PATHS section the environment variable var
1757 will be read and converted from a system environment variable to
1758 a cmake style list of paths. For example ENV PATH would be a
1759 way to list the system path variable. The argument after DOC
1760 will be used for the documentation string in the cache.
1761 PATH_SUFFIXES specifies additional subdirectories to check below
1762 each search path.
1763 If NO_DEFAULT_PATH is specified, then no additional paths are
1766 added to the search. If NO_DEFAULT_PATH is not specified, the
1767 search process is as follows:
1768 1. Search paths specified in cmake-specific cache variables.
1771 These are intended to be used on the command line with a
1772 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1773 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1776 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1777 CMAKE_INCLUDE_PATH
1778 CMAKE_FRAMEWORK_PATH
1779 2. Search paths specified in cmake-specific environment vari‐
1781 ables. These are intended to be set in the user's shell config‐
1782 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1783 passed.
1784 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1787 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1788 CMAKE_INCLUDE_PATH
1789 CMAKE_FRAMEWORK_PATH
1790 3. Search the paths specified by the HINTS option. These should
1792 be paths computed by system introspection, such as a hint pro‐
1793 vided by the location of another item already found. Hard-coded
1794 guesses should be specified with the PATHS option.
1795 4. Search the standard system environment variables. This can be
1798 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1799 PATH
1802 INCLUDE
1803 5. Search cmake variables defined in the Platform files for the
1805 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1806 passed.
1807 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1810 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1811 CMAKE_SYSTEM_INCLUDE_PATH
1812 CMAKE_SYSTEM_FRAMEWORK_PATH
1813 6. Search the paths specified by the PATHS option or in the
1815 short-hand version of the command. These are typically
1816 hard-coded guesses.
1817 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1820 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1821 following:
1822 "FIRST" - Try to find frameworks before standard
1825 libraries or headers. This is the default on Darwin.
1826 "LAST" - Try to find frameworks after standard
1827 libraries or headers.
1828 "ONLY" - Only try to find frameworks.
1829 "NEVER" - Never try to find frameworks.
1830 On Darwin or systems supporting OS X Application Bundles, the
1832 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
1833 of the following:
1834 "FIRST" - Try to find application bundles before standard
1837 programs. This is the default on Darwin.
1838 "LAST" - Try to find application bundles after standard
1839 programs.
1840 "ONLY" - Only try to find application bundles.
1841 "NEVER" - Never try to find application bundles.
1842 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
1844 directories to be prepended to all other search directories.
1845 This effectively "re-roots" the entire search under given loca‐
1846 tions. By default it is empty. It is especially useful when
1847 cross-compiling to point to the root directory of the target
1848 environment and CMake will search there too. By default at first
1849 the directories listed in CMAKE_FIND_ROOT_PATH and then the
1850 non-rooted directories will be searched. The default behavior
1851 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
1852 This behavior can be manually overridden on a per-call basis. By
1853 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
1854 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
1855 CMAKE_FIND_ROOT_PATH will not be used. If
1856 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1857 tories will be searched.
1858 The default search order is designed to be most-specific to
1861 least-specific for common use cases. Projects may override the
1862 order by simply calling the command multiple times and using the
1863 NO_* options:
1864 find_file(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1867 find_file(<VAR> NAMES name)
1868 Once one of the calls succeeds the result variable will be set
1870 and stored in the cache so that no call will search again.
1871 find_library
1874 Find a library.
1875 find_library(<VAR> name1 [path1 path2 ...])
1877 This is the short-hand signature for the command that is suffi‐
1879 cient in many cases. It is the same as find_library(<VAR> name1
1880 [PATHS path1 path2 ...])
1881 find_library(
1884 <VAR>
1885 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
1886 [HINTS path1 [path2 ... ENV var]]
1887 [PATHS path1 [path2 ... ENV var]]
1888 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1889 [DOC "cache documentation string"]
1890 [NO_DEFAULT_PATH]
1891 [NO_CMAKE_ENVIRONMENT_PATH]
1892 [NO_CMAKE_PATH]
1893 [NO_SYSTEM_ENVIRONMENT_PATH]
1894 [NO_CMAKE_SYSTEM_PATH]
1895 [CMAKE_FIND_ROOT_PATH_BOTH |
1896 ONLY_CMAKE_FIND_ROOT_PATH |
1897 NO_CMAKE_FIND_ROOT_PATH]
1898 )
1899 This command is used to find a library. A cache entry named by
1901 <VAR> is created to store the result of this command. If the
1902 library is found the result is stored in the variable and the
1903 search will not be repeated unless the variable is cleared. If
1904 nothing is found, the result will be <VAR>-NOTFOUND, and the
1905 search will be attempted again the next time find_library is
1906 invoked with the same variable. The name of the library that is
1907 searched for is specified by the names listed after the NAMES
1908 argument. Additional search locations can be specified after
1909 the PATHS argument. If ENV var is found in the HINTS or PATHS
1910 section the environment variable var will be read and converted
1911 from a system environment variable to a cmake style list of
1912 paths. For example ENV PATH would be a way to list the system
1913 path variable. The argument after DOC will be used for the docu‐
1914 mentation string in the cache. PATH_SUFFIXES specifies addi‐
1915 tional subdirectories to check below each search path.
1916 If NO_DEFAULT_PATH is specified, then no additional paths are
1919 added to the search. If NO_DEFAULT_PATH is not specified, the
1920 search process is as follows:
1921 1. Search paths specified in cmake-specific cache variables.
1924 These are intended to be used on the command line with a
1925 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1926 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1929 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1930 CMAKE_LIBRARY_PATH
1931 CMAKE_FRAMEWORK_PATH
1932 2. Search paths specified in cmake-specific environment vari‐
1934 ables. These are intended to be set in the user's shell config‐
1935 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1936 passed.
1937 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1940 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1941 CMAKE_LIBRARY_PATH
1942 CMAKE_FRAMEWORK_PATH
1943 3. Search the paths specified by the HINTS option. These should
1945 be paths computed by system introspection, such as a hint pro‐
1946 vided by the location of another item already found. Hard-coded
1947 guesses should be specified with the PATHS option.
1948 4. Search the standard system environment variables. This can be
1951 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1952 PATH
1955 LIB
1956 5. Search cmake variables defined in the Platform files for the
1958 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1959 passed.
1960 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
1963 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1964 CMAKE_SYSTEM_LIBRARY_PATH
1965 CMAKE_SYSTEM_FRAMEWORK_PATH
1966 6. Search the paths specified by the PATHS option or in the
1968 short-hand version of the command. These are typically
1969 hard-coded guesses.
1970 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1973 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1974 following:
1975 "FIRST" - Try to find frameworks before standard
1978 libraries or headers. This is the default on Darwin.
1979 "LAST" - Try to find frameworks after standard
1980 libraries or headers.
1981 "ONLY" - Only try to find frameworks.
1982 "NEVER" - Never try to find frameworks.
1983 On Darwin or systems supporting OS X Application Bundles, the
1985 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
1986 of the following:
1987 "FIRST" - Try to find application bundles before standard
1990 programs. This is the default on Darwin.
1991 "LAST" - Try to find application bundles after standard
1992 programs.
1993 "ONLY" - Only try to find application bundles.
1994 "NEVER" - Never try to find application bundles.
1995 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
1997 directories to be prepended to all other search directories.
1998 This effectively "re-roots" the entire search under given loca‐
1999 tions. By default it is empty. It is especially useful when
2000 cross-compiling to point to the root directory of the target
2001 environment and CMake will search there too. By default at first
2002 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2003 non-rooted directories will be searched. The default behavior
2004 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.
2005 This behavior can be manually overridden on a per-call basis. By
2006 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2007 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2008 CMAKE_FIND_ROOT_PATH will not be used. If
2009 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2010 tories will be searched.
2011 The default search order is designed to be most-specific to
2014 least-specific for common use cases. Projects may override the
2015 order by simply calling the command multiple times and using the
2016 NO_* options:
2017 find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2020 find_library(<VAR> NAMES name)
2021 Once one of the calls succeeds the result variable will be set
2023 and stored in the cache so that no call will search again.
2024 When more than one value is given to the NAMES option this com‐
2027 mand by default will consider one name at a time and search
2028 every directory for it. The NAMES_PER_DIR option tells this
2029 command to consider one directory at a time and search for all
2030 names in it.
2031 If the library found is a framework, then VAR will be set to the
2034 full path to the framework <fullPath>/A.framework. When a full
2035 path to a framework is used as a library, CMake will use a
2036 -framework A, and a -F<fullPath> to link the framework to the
2037 target.
2038 If the global property FIND_LIBRARY_USE_LIB64_PATHS is set all
2041 search paths will be tested as normal, with "64/" appended, and
2042 with all matches of "lib/" replaced with "lib64/". This property
2043 is automatically set for the platforms that are known to need it
2044 if at least one of the languages supported by the PROJECT com‐
2045 mand is enabled.
2046 find_package
2049 Load settings for an external project.
2050 find_package(<package> [version] [EXACT] [QUIET] [MODULE]
2052 [REQUIRED] [[COMPONENTS] [components...]]
2053 [OPTIONAL_COMPONENTS components...]
2054 [NO_POLICY_SCOPE])
2055 Finds and loads settings from an external project. <pack‐
2057 age>_FOUND will be set to indicate whether the package was
2058 found. When the package is found package-specific information
2059 is provided through variables and imported targets documented by
2060 the package itself. The QUIET option disables messages if the
2061 package cannot be found. The MODULE option disables the second
2062 signature documented below. The REQUIRED option stops process‐
2063 ing with an error message if the package cannot be found.
2064 A package-specific list of required components may be listed
2067 after the COMPONENTS option (or after the REQUIRED option if
2068 present). Additional optional components may be listed after
2069 OPTIONAL_COMPONENTS. Available components and their influence
2070 on whether a package is considered to be found are defined by
2071 the target package.
2072 The [version] argument requests a version with which the package
2075 found should be compatible (format is
2076 major[.minor[.patch[.tweak]]]). The EXACT option requests that
2077 the version be matched exactly. If no [version] and/or compo‐
2078 nent list is given to a recursive invocation inside a find-mod‐
2079 ule, the corresponding arguments are forwarded automatically
2080 from the outer call (including the EXACT flag for [version]).
2081 Version support is currently provided only on a package-by-pack‐
2082 age basis (details below).
2083 User code should generally look for packages using the above
2086 simple signature. The remainder of this command documentation
2087 specifies the full command signature and details of the search
2088 process. Project maintainers wishing to provide a package to be
2089 found by this command are encouraged to read on.
2090 The command has two modes by which it searches for packages:
2093 "Module" mode and "Config" mode. Module mode is available when
2094 the command is invoked with the above reduced signature. CMake
2095 searches for a file called "Find<package>.cmake" in the
2096 CMAKE_MODULE_PATH followed by the CMake installation. If the
2097 file is found, it is read and processed by CMake. It is respon‐
2098 sible for finding the package, checking the version, and produc‐
2099 ing any needed messages. Many find-modules provide limited or
2100 no support for versioning; check the module documentation. If
2101 no module is found and the MODULE option is not given the com‐
2102 mand proceeds to Config mode.
2103 The complete Config mode command signature is:
2106 find_package(<package> [version] [EXACT] [QUIET]
2109 [REQUIRED] [[COMPONENTS] [components...]]
2110 [CONFIG|NO_MODULE]
2111 [NO_POLICY_SCOPE]
2112 [NAMES name1 [name2 ...]]
2113 [CONFIGS config1 [config2 ...]]
2114 [HINTS path1 [path2 ... ]]
2115 [PATHS path1 [path2 ... ]]
2116 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2117 [NO_DEFAULT_PATH]
2118 [NO_CMAKE_ENVIRONMENT_PATH]
2119 [NO_CMAKE_PATH]
2120 [NO_SYSTEM_ENVIRONMENT_PATH]
2121 [NO_CMAKE_PACKAGE_REGISTRY]
2122 [NO_CMAKE_BUILDS_PATH]
2123 [NO_CMAKE_SYSTEM_PATH]
2124 [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
2125 [CMAKE_FIND_ROOT_PATH_BOTH |
2126 ONLY_CMAKE_FIND_ROOT_PATH |
2127 NO_CMAKE_FIND_ROOT_PATH])
2128 The CONFIG option may be used to skip Module mode explicitly and
2130 switch to Config mode. It is synonymous to using NO_MODULE.
2131 Config mode is also implied by use of options not specified in
2132 the reduced signature.
2133 Config mode attempts to locate a configuration file provided by
2136 the package to be found. A cache entry called <package>_DIR is
2137 created to hold the directory containing the file. By default
2138 the command searches for a package with the name <package>. If
2139 the NAMES option is given the names following it are used
2140 instead of <package>. The command searches for a file called
2141 "<name>Config.cmake" or "<lower-case-name>-config.cmake" for
2142 each name specified. A replacement set of possible configura‐
2143 tion file names may be given using the CONFIGS option. The
2144 search procedure is specified below. Once found, the configura‐
2145 tion file is read and processed by CMake. Since the file is
2146 provided by the package it already knows the location of package
2147 contents. The full path to the configuration file is stored in
2148 the cmake variable <package>_CONFIG.
2149 All configuration files which have been considered by CMake
2152 while searching for an installation of the package with an
2153 appropriate version are stored in the cmake variable <pack‐
2154 age>_CONSIDERED_CONFIGS, the associated versions in <pack‐
2155 age>_CONSIDERED_VERSIONS.
2156 If the package configuration file cannot be found CMake will
2159 generate an error describing the problem unless the QUIET argu‐
2160 ment is specified. If REQUIRED is specified and the package is
2161 not found a fatal error is generated and the configure step
2162 stops executing. If <package>_DIR has been set to a directory
2163 not containing a configuration file CMake will ignore it and
2164 search from scratch.
2165 When the [version] argument is given Config mode will only find
2168 a version of the package that claims compatibility with the
2169 requested version (format is major[.minor[.patch[.tweak]]]). If
2170 the EXACT option is given only a version of the package claiming
2171 an exact match of the requested version may be found. CMake
2172 does not establish any convention for the meaning of version
2173 numbers. Package version numbers are checked by "version" files
2174 provided by the packages themselves. For a candidate package
2175 configuration file "<config-file>.cmake" the corresponding ver‐
2176 sion file is located next to it and named either "<con‐
2177 fig-file>-version.cmake" or "<config-file>Version.cmake". If no
2178 such version file is available then the configuration file is
2179 assumed to not be compatible with any requested version. A
2180 basic version file containing generic version matching code can
2181 be created using the macro write_basic_package_version_file(),
2182 see its documentation for more details. When a version file is
2183 found it is loaded to check the requested version number. The
2184 version file is loaded in a nested scope in which the following
2185 variables have been defined:
2186 PACKAGE_FIND_NAME = the <package> name
2189 PACKAGE_FIND_VERSION = full requested version string
2190 PACKAGE_FIND_VERSION_MAJOR = major version if requested, else 0
2191 PACKAGE_FIND_VERSION_MINOR = minor version if requested, else 0
2192 PACKAGE_FIND_VERSION_PATCH = patch version if requested, else 0
2193 PACKAGE_FIND_VERSION_TWEAK = tweak version if requested, else 0
2194 PACKAGE_FIND_VERSION_COUNT = number of version components, 0 to 4
2195 The version file checks whether it satisfies the requested ver‐
2197 sion and sets these variables:
2198 PACKAGE_VERSION = full provided version string
2201 PACKAGE_VERSION_EXACT = true if version is exact match
2202 PACKAGE_VERSION_COMPATIBLE = true if version is compatible
2203 PACKAGE_VERSION_UNSUITABLE = true if unsuitable as any version
2204 These variables are checked by the find_package command to
2206 determine whether the configuration file provides an acceptable
2207 version. They are not available after the find_package call
2208 returns. If the version is acceptable the following variables
2209 are set:
2210 <package>_VERSION = full provided version string
2213 <package>_VERSION_MAJOR = major version if provided, else 0
2214 <package>_VERSION_MINOR = minor version if provided, else 0
2215 <package>_VERSION_PATCH = patch version if provided, else 0
2216 <package>_VERSION_TWEAK = tweak version if provided, else 0
2217 <package>_VERSION_COUNT = number of version components, 0 to 4
2218 and the corresponding package configuration file is loaded.
2220 When multiple package configuration files are available whose
2221 version files claim compatibility with the version requested it
2222 is unspecified which one is chosen. No attempt is made to
2223 choose a highest or closest version number.
2224 Config mode provides an elaborate interface and search proce‐
2227 dure. Much of the interface is provided for completeness and
2228 for use internally by find-modules loaded by Module mode. Most
2229 user code should simply call
2230 find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
2233 in order to find a package. Package maintainers providing CMake
2235 package configuration files are encouraged to name and install
2236 them such that the procedure outlined below will find them with‐
2237 out requiring use of additional options.
2238 CMake constructs a set of possible installation prefixes for the
2241 package. Under each prefix several directories are searched for
2242 a configuration file. The tables below show the directories
2243 searched. Each entry is meant for installation trees following
2244 Windows (W), UNIX (U), or Apple (A) conventions.
2245 <prefix>/ (W)
2248 <prefix>/(cmake|CMake)/ (W)
2249 <prefix>/<name>*/ (W)
2250 <prefix>/<name>*/(cmake|CMake)/ (W)
2251 <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/ (U)
2252 <prefix>/(lib/<arch>|lib|share)/<name>*/ (U)
2253 <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/ (U)
2254 On systems supporting OS X Frameworks and Application Bundles
2256 the following directories are searched for frameworks or bundles
2257 containing a configuration file:
2258 <prefix>/<name>.framework/Resources/ (A)
2261 <prefix>/<name>.framework/Resources/CMake/ (A)
2262 <prefix>/<name>.framework/Versions/*/Resources/ (A)
2263 <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
2264 <prefix>/<name>.app/Contents/Resources/ (A)
2265 <prefix>/<name>.app/Contents/Resources/CMake/ (A)
2266 In all cases the <name> is treated as case-insensitive and cor‐
2268 responds to any of the names specified (<package> or names given
2269 by NAMES). Paths with lib/<arch> are enabled if
2270 CMAKE_LIBRARY_ARCHITECTURE is set. If PATH_SUFFIXES is speci‐
2271 fied the suffixes are appended to each (W) or (U) directory
2272 entry one-by-one.
2273 This set of directories is intended to work in cooperation with
2276 projects that provide configuration files in their installation
2277 trees. Directories above marked with (W) are intended for
2278 installations on Windows where the prefix may point at the top
2279 of an application's installation directory. Those marked with
2280 (U) are intended for installations on UNIX platforms where the
2281 prefix is shared by multiple packages. This is merely a conven‐
2282 tion, so all (W) and (U) directories are still searched on all
2283 platforms. Directories marked with (A) are intended for instal‐
2284 lations on Apple platforms. The cmake variables
2285 CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE determine the
2286 order of preference as specified below.
2287 The set of installation prefixes is constructed using the fol‐
2290 lowing steps. If NO_DEFAULT_PATH is specified all NO_* options
2291 are enabled.
2292 1. Search paths specified in cmake-specific cache variables.
2295 These are intended to be used on the command line with a
2296 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
2297 CMAKE_PREFIX_PATH
2300 CMAKE_FRAMEWORK_PATH
2301 CMAKE_APPBUNDLE_PATH
2302 2. Search paths specified in cmake-specific environment vari‐
2304 ables. These are intended to be set in the user's shell config‐
2305 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2306 passed.
2307 <package>_DIR
2310 CMAKE_PREFIX_PATH
2311 CMAKE_FRAMEWORK_PATH
2312 CMAKE_APPBUNDLE_PATH
2313 3. Search paths specified by the HINTS option. These should be
2315 paths computed by system introspection, such as a hint provided
2316 by the location of another item already found. Hard-coded
2317 guesses should be specified with the PATHS option.
2318 4. Search the standard system environment variables. This can be
2321 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed. Path entries
2322 ending in "/bin" or "/sbin" are automatically converted to their
2323 parent directories.
2324 PATH
2327 5. Search project build trees recently configured in a CMake
2329 GUI. This can be skipped if NO_CMAKE_BUILDS_PATH is passed. It
2330 is intended for the case when a user is building multiple depen‐
2331 dent projects one after another.
2332 6. Search paths stored in the CMake user package registry. This
2335 can be skipped if NO_CMAKE_PACKAGE_REGISTRY is passed. On Win‐
2336 dows a <package> may appear under registry key
2337 HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package>
2340 as a REG_SZ value, with arbitrary name, that specifies the
2342 directory containing the package configuration file. On UNIX
2343 platforms a <package> may appear under the directory
2344 ~/.cmake/packages/<package>
2347 as a file, with arbitrary name, whose content specifies the
2349 directory containing the package configuration file. See the
2350 export(PACKAGE) command to create user package registry entries
2351 for project build trees.
2352 7. Search cmake variables defined in the Platform files for the
2355 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
2356 passed.
2357 CMAKE_SYSTEM_PREFIX_PATH
2360 CMAKE_SYSTEM_FRAMEWORK_PATH
2361 CMAKE_SYSTEM_APPBUNDLE_PATH
2362 8. Search paths stored in the CMake system package registry.
2364 This can be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is
2365 passed. On Windows a <package> may appear under registry key
2366 HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package>
2369 as a REG_SZ value, with arbitrary name, that specifies the
2371 directory containing the package configuration file. There is
2372 no system package registry on non-Windows platforms.
2373 9. Search paths specified by the PATHS option. These are typi‐
2376 cally hard-coded guesses.
2377 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2380 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
2381 following:
2382 "FIRST" - Try to find frameworks before standard
2385 libraries or headers. This is the default on Darwin.
2386 "LAST" - Try to find frameworks after standard
2387 libraries or headers.
2388 "ONLY" - Only try to find frameworks.
2389 "NEVER" - Never try to find frameworks.
2390 On Darwin or systems supporting OS X Application Bundles, the
2392 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
2393 of the following:
2394 "FIRST" - Try to find application bundles before standard
2397 programs. This is the default on Darwin.
2398 "LAST" - Try to find application bundles after standard
2399 programs.
2400 "ONLY" - Only try to find application bundles.
2401 "NEVER" - Never try to find application bundles.
2402 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
2404 directories to be prepended to all other search directories.
2405 This effectively "re-roots" the entire search under given loca‐
2406 tions. By default it is empty. It is especially useful when
2407 cross-compiling to point to the root directory of the target
2408 environment and CMake will search there too. By default at first
2409 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2410 non-rooted directories will be searched. The default behavior
2411 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.
2412 This behavior can be manually overridden on a per-call basis. By
2413 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2414 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2415 CMAKE_FIND_ROOT_PATH will not be used. If
2416 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2417 tories will be searched.
2418 The default search order is designed to be most-specific to
2421 least-specific for common use cases. Projects may override the
2422 order by simply calling the command multiple times and using the
2423 NO_* options:
2424 find_package(<package> PATHS paths... NO_DEFAULT_PATH)
2427 find_package(<package>)
2428 Once one of the calls succeeds the result variable will be set
2430 and stored in the cache so that no call will search again.
2431 Every non-REQUIRED find_package() call can be disabled by set‐
2434 ting the variable CMAKE_DISABLE_FIND_PACKAGE_<package> to TRUE.
2435 See the documentation for the CMAKE_DISABLE_FIND_PACKAGE_<pack‐
2436 age> variable for more information.
2437 When loading a find module or package configuration file
2440 find_package defines variables to provide information about the
2441 call arguments (and restores their original state before return‐
2442 ing):
2443 <package>_FIND_REQUIRED = true if REQUIRED option was given
2446 <package>_FIND_QUIETLY = true if QUIET option was given
2447 <package>_FIND_VERSION = full requested version string
2448 <package>_FIND_VERSION_MAJOR = major version if requested, else 0
2449 <package>_FIND_VERSION_MINOR = minor version if requested, else 0
2450 <package>_FIND_VERSION_PATCH = patch version if requested, else 0
2451 <package>_FIND_VERSION_TWEAK = tweak version if requested, else 0
2452 <package>_FIND_VERSION_COUNT = number of version components, 0 to 4
2453 <package>_FIND_VERSION_EXACT = true if EXACT option was given
2454 <package>_FIND_COMPONENTS = list of requested components
2455 <package>_FIND_REQUIRED_<c> = true if component <c> is required
2456 false if component <c> is optional
2457 In Module mode the loaded find module is responsible to honor
2459 the request detailed by these variables; see the find module for
2460 details. In Config mode find_package handles REQUIRED, QUIET,
2461 and version options automatically but leaves it to the package
2462 configuration file to handle components in a way that makes
2463 sense for the package. The package configuration file may set
2464 <package>_FOUND to false to tell find_package that component
2465 requirements are not satisfied.
2466 See the cmake_policy() command documentation for discussion of
2469 the NO_POLICY_SCOPE option.
2470 find_path
2473 Find the directory containing a file.
2474 find_path(<VAR> name1 [path1 path2 ...])
2476 This is the short-hand signature for the command that is suffi‐
2478 cient in many cases. It is the same as find_path(<VAR> name1
2479 [PATHS path1 path2 ...])
2480 find_path(
2483 <VAR>
2484 name | NAMES name1 [name2 ...]
2485 [HINTS path1 [path2 ... ENV var]]
2486 [PATHS path1 [path2 ... ENV var]]
2487 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2488 [DOC "cache documentation string"]
2489 [NO_DEFAULT_PATH]
2490 [NO_CMAKE_ENVIRONMENT_PATH]
2491 [NO_CMAKE_PATH]
2492 [NO_SYSTEM_ENVIRONMENT_PATH]
2493 [NO_CMAKE_SYSTEM_PATH]
2494 [CMAKE_FIND_ROOT_PATH_BOTH |
2495 ONLY_CMAKE_FIND_ROOT_PATH |
2496 NO_CMAKE_FIND_ROOT_PATH]
2497 )
2498 This command is used to find a directory containing the named
2500 file. A cache entry named by <VAR> is created to store the
2501 result of this command. If the file in a directory is found the
2502 result is stored in the variable and the search will not be
2503 repeated unless the variable is cleared. If nothing is found,
2504 the result will be <VAR>-NOTFOUND, and the search will be
2505 attempted again the next time find_path is invoked with the same
2506 variable. The name of the file in a directory that is searched
2507 for is specified by the names listed after the NAMES argument.
2508 Additional search locations can be specified after the PATHS
2509 argument. If ENV var is found in the HINTS or PATHS section the
2510 environment variable var will be read and converted from a sys‐
2511 tem environment variable to a cmake style list of paths. For
2512 example ENV PATH would be a way to list the system path vari‐
2513 able. The argument after DOC will be used for the documentation
2514 string in the cache. PATH_SUFFIXES specifies additional subdi‐
2515 rectories to check below each search path.
2516 If NO_DEFAULT_PATH is specified, then no additional paths are
2519 added to the search. If NO_DEFAULT_PATH is not specified, the
2520 search process is as follows:
2521 1. Search paths specified in cmake-specific cache variables.
2524 These are intended to be used on the command line with a
2525 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
2526 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2529 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2530 CMAKE_INCLUDE_PATH
2531 CMAKE_FRAMEWORK_PATH
2532 2. Search paths specified in cmake-specific environment vari‐
2534 ables. These are intended to be set in the user's shell config‐
2535 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2536 passed.
2537 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2540 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2541 CMAKE_INCLUDE_PATH
2542 CMAKE_FRAMEWORK_PATH
2543 3. Search the paths specified by the HINTS option. These should
2545 be paths computed by system introspection, such as a hint pro‐
2546 vided by the location of another item already found. Hard-coded
2547 guesses should be specified with the PATHS option.
2548 4. Search the standard system environment variables. This can be
2551 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2552 PATH
2555 INCLUDE
2556 5. Search cmake variables defined in the Platform files for the
2558 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
2559 passed.
2560 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2563 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2564 CMAKE_SYSTEM_INCLUDE_PATH
2565 CMAKE_SYSTEM_FRAMEWORK_PATH
2566 6. Search the paths specified by the PATHS option or in the
2568 short-hand version of the command. These are typically
2569 hard-coded guesses.
2570 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2573 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
2574 following:
2575 "FIRST" - Try to find frameworks before standard
2578 libraries or headers. This is the default on Darwin.
2579 "LAST" - Try to find frameworks after standard
2580 libraries or headers.
2581 "ONLY" - Only try to find frameworks.
2582 "NEVER" - Never try to find frameworks.
2583 On Darwin or systems supporting OS X Application Bundles, the
2585 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
2586 of the following:
2587 "FIRST" - Try to find application bundles before standard
2590 programs. This is the default on Darwin.
2591 "LAST" - Try to find application bundles after standard
2592 programs.
2593 "ONLY" - Only try to find application bundles.
2594 "NEVER" - Never try to find application bundles.
2595 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
2597 directories to be prepended to all other search directories.
2598 This effectively "re-roots" the entire search under given loca‐
2599 tions. By default it is empty. It is especially useful when
2600 cross-compiling to point to the root directory of the target
2601 environment and CMake will search there too. By default at first
2602 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2603 non-rooted directories will be searched. The default behavior
2604 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
2605 This behavior can be manually overridden on a per-call basis. By
2606 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2607 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2608 CMAKE_FIND_ROOT_PATH will not be used. If
2609 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2610 tories will be searched.
2611 The default search order is designed to be most-specific to
2614 least-specific for common use cases. Projects may override the
2615 order by simply calling the command multiple times and using the
2616 NO_* options:
2617 find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2620 find_path(<VAR> NAMES name)
2621 Once one of the calls succeeds the result variable will be set
2623 and stored in the cache so that no call will search again.
2624 When searching for frameworks, if the file is specified as
2627 A/b.h, then the framework search will look for A.framework/Head‐
2628 ers/b.h. If that is found the path will be set to the path to
2629 the framework. CMake will convert this to the correct -F option
2630 to include the file.
2631 find_program
2634 Find an executable program.
2635 find_program(<VAR> name1 [path1 path2 ...])
2637 This is the short-hand signature for the command that is suffi‐
2639 cient in many cases. It is the same as find_program(<VAR> name1
2640 [PATHS path1 path2 ...])
2641 find_program(
2644 <VAR>
2645 name | NAMES name1 [name2 ...]
2646 [HINTS path1 [path2 ... ENV var]]
2647 [PATHS path1 [path2 ... ENV var]]
2648 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2649 [DOC "cache documentation string"]
2650 [NO_DEFAULT_PATH]
2651 [NO_CMAKE_ENVIRONMENT_PATH]
2652 [NO_CMAKE_PATH]
2653 [NO_SYSTEM_ENVIRONMENT_PATH]
2654 [NO_CMAKE_SYSTEM_PATH]
2655 [CMAKE_FIND_ROOT_PATH_BOTH |
2656 ONLY_CMAKE_FIND_ROOT_PATH |
2657 NO_CMAKE_FIND_ROOT_PATH]
2658 )
2659 This command is used to find a program. A cache entry named by
2661 <VAR> is created to store the result of this command. If the
2662 program is found the result is stored in the variable and the
2663 search will not be repeated unless the variable is cleared. If
2664 nothing is found, the result will be <VAR>-NOTFOUND, and the
2665 search will be attempted again the next time find_program is
2666 invoked with the same variable. The name of the program that is
2667 searched for is specified by the names listed after the NAMES
2668 argument. Additional search locations can be specified after
2669 the PATHS argument. If ENV var is found in the HINTS or PATHS
2670 section the environment variable var will be read and converted
2671 from a system environment variable to a cmake style list of
2672 paths. For example ENV PATH would be a way to list the system
2673 path variable. The argument after DOC will be used for the docu‐
2674 mentation string in the cache. PATH_SUFFIXES specifies addi‐
2675 tional subdirectories to check below each search path.
2676 If NO_DEFAULT_PATH is specified, then no additional paths are
2679 added to the search. If NO_DEFAULT_PATH is not specified, the
2680 search process is as follows:
2681 1. Search paths specified in cmake-specific cache variables.
2684 These are intended to be used on the command line with a
2685 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
2686 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2689 CMAKE_PROGRAM_PATH
2690 CMAKE_APPBUNDLE_PATH
2691 2. Search paths specified in cmake-specific environment vari‐
2693 ables. These are intended to be set in the user's shell config‐
2694 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2695 passed.
2696 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2699 CMAKE_PROGRAM_PATH
2700 CMAKE_APPBUNDLE_PATH
2701 3. Search the paths specified by the HINTS option. These should
2703 be paths computed by system introspection, such as a hint pro‐
2704 vided by the location of another item already found. Hard-coded
2705 guesses should be specified with the PATHS option.
2706 4. Search the standard system environment variables. This can be
2709 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2710 PATH
2713 5. Search cmake variables defined in the Platform files for the
2716 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
2717 passed.
2718 <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2721 CMAKE_SYSTEM_PROGRAM_PATH
2722 CMAKE_SYSTEM_APPBUNDLE_PATH
2723 6. Search the paths specified by the PATHS option or in the
2725 short-hand version of the command. These are typically
2726 hard-coded guesses.
2727 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2730 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
2731 following:
2732 "FIRST" - Try to find frameworks before standard
2735 libraries or headers. This is the default on Darwin.
2736 "LAST" - Try to find frameworks after standard
2737 libraries or headers.
2738 "ONLY" - Only try to find frameworks.
2739 "NEVER" - Never try to find frameworks.
2740 On Darwin or systems supporting OS X Application Bundles, the
2742 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
2743 of the following:
2744 "FIRST" - Try to find application bundles before standard
2747 programs. This is the default on Darwin.
2748 "LAST" - Try to find application bundles after standard
2749 programs.
2750 "ONLY" - Only try to find application bundles.
2751 "NEVER" - Never try to find application bundles.
2752 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
2754 directories to be prepended to all other search directories.
2755 This effectively "re-roots" the entire search under given loca‐
2756 tions. By default it is empty. It is especially useful when
2757 cross-compiling to point to the root directory of the target
2758 environment and CMake will search there too. By default at first
2759 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2760 non-rooted directories will be searched. The default behavior
2761 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.
2762 This behavior can be manually overridden on a per-call basis. By
2763 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2764 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2765 CMAKE_FIND_ROOT_PATH will not be used. If
2766 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2767 tories will be searched.
2768 The default search order is designed to be most-specific to
2771 least-specific for common use cases. Projects may override the
2772 order by simply calling the command multiple times and using the
2773 NO_* options:
2774 find_program(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2777 find_program(<VAR> NAMES name)
2778 Once one of the calls succeeds the result variable will be set
2780 and stored in the cache so that no call will search again.
2781 fltk_wrap_ui
2784 Create FLTK user interfaces Wrappers.
2785 fltk_wrap_ui(resultingLibraryName source1
2787 source2 ... sourceN )
2788 Produce .h and .cxx files for all the .fl and .fld files listed.
2790 The resulting .h and .cxx files will be added to a variable
2791 named resultingLibraryName_FLTK_UI_SRCS which should be added to
2792 your library.
2793 foreach
2796 Evaluate a group of commands for each value in a list.
2797 foreach(loop_var arg1 arg2 ...)
2799 COMMAND1(ARGS ...)
2800 COMMAND2(ARGS ...)
2801 ...
2802 endforeach(loop_var)
2803 All commands between foreach and the matching endforeach are
2805 recorded without being invoked. Once the endforeach is evalu‐
2806 ated, the recorded list of commands is invoked once for each
2807 argument listed in the original foreach command. Before each
2808 iteration of the loop "${loop_var}" will be set as a variable
2809 with the current value in the list.
2810 foreach(loop_var RANGE total)
2813 foreach(loop_var RANGE start stop [step])
2814 Foreach can also iterate over a generated range of numbers.
2816 There are three types of this iteration:
2817 * When specifying single number, the range will have elements 0
2820 to "total".
2821 * When specifying two numbers, the range will have elements from
2824 the first number to the second number.
2825 * The third optional number is the increment used to iterate
2828 from the first number to the second number.
2829 foreach(loop_var IN [LISTS [list1 [...]]]
2832 [ITEMS [item1 [...]]])
2833 Iterates over a precise list of items. The LISTS option names
2835 list-valued variables to be traversed, including empty elements
2836 (an empty string is a zero-length list). The ITEMS option ends
2837 argument parsing and includes all arguments following it in the
2838 iteration.
2839 function
2842 Start recording a function for later invocation as a command.
2843 function(<name> [arg1 [arg2 [arg3 ...]]])
2845 COMMAND1(ARGS ...)
2846 COMMAND2(ARGS ...)
2847 ...
2848 endfunction(<name>)
2849 Define a function named <name> that takes arguments named arg1
2851 arg2 arg3 (...). Commands listed after function, but before the
2852 matching endfunction, are not invoked until the function is
2853 invoked. When it is invoked, the commands recorded in the func‐
2854 tion are first modified by replacing formal parameters (${arg1})
2855 with the arguments passed, and then invoked as normal commands.
2856 In addition to referencing the formal parameters you can refer‐
2857 ence the variable ARGC which will be set to the number of argu‐
2858 ments passed into the function as well as ARGV0 ARGV1 ARGV2 ...
2859 which will have the actual values of the arguments passed in.
2860 This facilitates creating functions with optional arguments.
2861 Additionally ARGV holds the list of all arguments given to the
2862 function and ARGN holds the list of arguments past the last
2863 expected argument.
2864 A function opens a new scope: see set(var PARENT_SCOPE) for
2867 details.
2868 See the cmake_policy() command documentation for the behavior of
2871 policies inside functions.
2872 get_cmake_property
2875 Get a property of the CMake instance.
2876 get_cmake_property(VAR property)
2878 Get a property from the CMake instance. The value of the prop‐
2880 erty is stored in the variable VAR. If the property is not
2881 found, VAR will be set to "NOTFOUND". Some supported properties
2882 include: VARIABLES, CACHE_VARIABLES, COMMANDS, MACROS, and COM‐
2883 PONENTS.
2884 See also the more general get_property() command.
2887 get_directory_property
2890 Get a property of DIRECTORY scope.
2891 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
2893 Store a property of directory scope in the named variable. If
2895 the property is not defined the empty-string is returned. The
2896 DIRECTORY argument specifies another directory from which to
2897 retrieve the property value. The specified directory must have
2898 already been traversed by CMake.
2899 get_directory_property(<variable> [DIRECTORY <dir>]
2902 DEFINITION <var-name>)
2903 Get a variable definition from a directory. This form is useful
2905 to get a variable definition from another directory.
2906 See also the more general get_property() command.
2909 get_filename_component
2912 Get a specific component of a full filename.
2913 get_filename_component(<VAR> <FileName> <COMP> [CACHE])
2915 Set <VAR> to a component of <FileName>, where <COMP> is one of:
2917 DIRECTORY = Directory without file name
2920 NAME = File name without directory
2921 EXT = File name longest extension (.b.c from d/a.b.c)
2922 NAME_WE = File name without directory or longest extension
2923 ABSOLUTE = Full path to file
2924 REALPATH = Full path to existing file with symlinks resolved
2925 PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
2926 Paths are returned with forward slashes and have no trailing
2928 slahes. The longest file extension is always considered. If the
2929 optional CACHE argument is specified, the result variable is
2930 added to the cache.
2931 get_filename_component(<VAR> FileName
2934 PROGRAM [PROGRAM_ARGS <ARG_VAR>]
2935 [CACHE])
2936 The program in FileName will be found in the system search path
2938 or left as a full path. If PROGRAM_ARGS is present with PRO‐
2939 GRAM, then any command-line arguments present in the FileName
2940 string are split from the program name and stored in <ARG_VAR>.
2941 This is used to separate a program name from its arguments in a
2942 command line string.
2943 get_property
2946 Get a property.
2947 get_property(<variable>
2949 <GLOBAL |
2950 DIRECTORY [dir] |
2951 TARGET <target> |
2952 SOURCE <source> |
2953 TEST <test> |
2954 CACHE <entry> |
2955 VARIABLE>
2956 PROPERTY <name>
2957 [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
2958 Get one property from one object in a scope. The first argument
2960 specifies the variable in which to store the result. The second
2961 argument determines the scope from which to get the property.
2962 It must be one of the following:
2963 GLOBAL scope is unique and does not accept a name.
2966 DIRECTORY scope defaults to the current directory but another
2969 directory (already processed by CMake) may be named by full or
2970 relative path.
2971 TARGET scope must name one existing target.
2974 SOURCE scope must name one source file.
2977 TEST scope must name one existing test.
2980 CACHE scope must name one cache entry.
2983 VARIABLE scope is unique and does not accept a name.
2986 The required PROPERTY option is immediately followed by the name
2989 of the property to get. If the property is not set an empty
2990 value is returned. If the SET option is given the variable is
2991 set to a boolean value indicating whether the property has been
2992 set. If the DEFINED option is given the variable is set to a
2993 boolean value indicating whether the property has been defined
2994 such as with define_property. If BRIEF_DOCS or FULL_DOCS is
2995 given then the variable is set to a string containing documenta‐
2996 tion for the requested property. If documentation is requested
2997 for a property that has not been defined NOTFOUND is returned.
2998 get_source_file_property
3001 Get a property for a source file.
3002 get_source_file_property(VAR file property)
3004 Get a property from a source file. The value of the property is
3006 stored in the variable VAR. If the property is not found, VAR
3007 will be set to "NOTFOUND". Use set_source_files_properties to
3008 set property values. Source file properties usually control how
3009 the file is built. One property that is always there is LOCATION
3010 See also the more general get_property() command.
3013 get_target_property
3016 Get a property from a target.
3017 get_target_property(VAR target property)
3019 Get a property from a target. The value of the property is
3021 stored in the variable VAR. If the property is not found, VAR
3022 will be set to "NOTFOUND". Use set_target_properties to set
3023 property values. Properties are usually used to control how a
3024 target is built, but some query the target instead. This com‐
3025 mand can get properties for any target so far created. The tar‐
3026 gets do not need to be in the current CMakeLists.txt file.
3027 See also the more general get_property() command.
3030 get_test_property
3033 Get a property of the test.
3034 get_test_property(test property VAR)
3036 Get a property from the Test. The value of the property is
3038 stored in the variable VAR. If the property is not found, VAR
3039 will be set to "NOTFOUND". For a list of standard properties you
3040 can type cmake --help-property-list
3041 See also the more general get_property() command.
3044 if Conditionally execute a group of commands.
3047 if(expression)
3049 # then section.
3050 COMMAND1(ARGS ...)
3051 COMMAND2(ARGS ...)
3052 ...
3053 elseif(expression2)
3054 # elseif section.
3055 COMMAND1(ARGS ...)
3056 COMMAND2(ARGS ...)
3057 ...
3058 else(expression)
3059 # else section.
3060 COMMAND1(ARGS ...)
3061 COMMAND2(ARGS ...)
3062 ...
3063 endif(expression)
3064 Evaluates the given expression. If the result is true, the com‐
3066 mands in the THEN section are invoked. Otherwise, the commands
3067 in the else section are invoked. The elseif and else sections
3068 are optional. You may have multiple elseif clauses. Note that
3069 the expression in the else and endif clause is optional. Long
3070 expressions can be used and there is a traditional order of
3071 precedence. Parenthetical expressions are evaluated first fol‐
3072 lowed by unary operators such as EXISTS, COMMAND, and DEFINED.
3073 Then any EQUAL, LESS, GREATER, STRLESS, STRGREATER, STREQUAL,
3074 MATCHES will be evaluated. Then NOT operators and finally AND,
3075 OR operators will be evaluated. Possible expressions are:
3076 if(<constant>)
3079 True if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
3081 ber. False if the constant is 0, OFF, NO, FALSE, N, IGNORE,
3082 NOTFOUND, '', or ends in the suffix '-NOTFOUND'. Named boolean
3083 constants are case-insensitive. If the argument is not one of
3084 these constants, it is treated as a variable:
3085 if(<variable>)
3088 True if the variable is defined to a value that is not a false
3090 constant. False otherwise. (Note macro arguments are not vari‐
3091 ables.)
3092 if(NOT <expression>)
3095 True if the expression is not true.
3097 if(<expr1> AND <expr2>)
3100 True if both expressions would be considered true individually.
3102 if(<expr1> OR <expr2>)
3105 True if either expression would be considered true individually.
3107 if(COMMAND command-name)
3110 True if the given name is a command, macro or function that can
3112 be invoked.
3113 if(POLICY policy-id)
3116 True if the given name is an existing policy (of the form
3118 CMP<NNNN>).
3119 if(TARGET target-name)
3122 True if the given name is an existing target, built or imported.
3124 if(EXISTS file-name)
3127 if(EXISTS directory-name)
3128 True if the named file or directory exists. Behavior is
3130 well-defined only for full paths.
3131 if(file1 IS_NEWER_THAN file2)
3134 True if file1 is newer than file2 or if one of the two files
3136 doesn't exist. Behavior is well-defined only for full paths. If
3137 the file time stamps are exactly the same, an IS_NEWER_THAN com‐
3138 parison returns true, so that any dependent build operations
3139 will occur in the event of a tie. This includes the case of
3140 passing the same file name for both file1 and file2.
3141 if(IS_DIRECTORY directory-name)
3144 True if the given name is a directory. Behavior is well-defined
3146 only for full paths.
3147 if(IS_SYMLINK file-name)
3150 True if the given name is a symbolic link. Behavior is
3152 well-defined only for full paths.
3153 if(IS_ABSOLUTE path)
3156 True if the given path is an absolute path.
3158 if(<variable|string> MATCHES regex)
3161 True if the given string or variable's value matches the given
3163 regular expression.
3164 if(<variable|string> LESS <variable|string>)
3167 if(<variable|string> GREATER <variable|string>)
3168 if(<variable|string> EQUAL <variable|string>)
3169 True if the given string or variable's value is a valid number
3171 and the inequality or equality is true.
3172 if(<variable|string> STRLESS <variable|string>)
3175 if(<variable|string> STRGREATER <variable|string>)
3176 if(<variable|string> STREQUAL <variable|string>)
3177 True if the given string or variable's value is lexicographi‐
3179 cally less (or greater, or equal) than the string or variable on
3180 the right.
3181 if(<variable|string> VERSION_LESS <variable|string>)
3184 if(<variable|string> VERSION_EQUAL <variable|string>)
3185 if(<variable|string> VERSION_GREATER <variable|string>)
3186 Component-wise integer version number comparison (version format
3188 is major[.minor[.patch[.tweak]]]).
3189 if(DEFINED <variable>)
3192 True if the given variable is defined. It does not matter if the
3194 variable is true or false just if it has been set.
3195 if((expression) AND (expression OR (expression)))
3198 The expressions inside the parenthesis are evaluated first and
3200 then the remaining expression is evaluated as in the previous
3201 examples. Where there are nested parenthesis the innermost are
3202 evaluated as part of evaluating the expression that contains
3203 them.
3204 The if command was written very early in CMake's history, pre‐
3207 dating the ${} variable evaluation syntax, and for convenience
3208 evaluates variables named by its arguments as shown in the above
3209 signatures. Note that normal variable evaluation with ${}
3210 applies before the if command even receives the arguments.
3211 Therefore code like
3212 set(var1 OFF)
3215 set(var2 "var1")
3216 if(${var2})
3217 appears to the if command as
3219 if(var1)
3222 and is evaluated according to the if(<variable>) case documented
3224 above. The result is OFF which is false. However, if we remove
3225 the ${} from the example then the command sees
3226 if(var2)
3229 which is true because var2 is defined to "var1" which is not a
3231 false constant.
3232 Automatic evaluation applies in the other cases whenever the
3235 above-documented signature accepts <variable|string>:
3236 1) The left hand argument to MATCHES is first checked to see if
3239 it is a defined variable, if so the variable's value is used,
3240 otherwise the original value is used.
3241 2) If the left hand argument to MATCHES is missing it returns
3244 false without error
3245 3) Both left and right hand arguments to LESS GREATER EQUAL are
3248 independently tested to see if they are defined variables, if so
3249 their defined values are used otherwise the original value is
3250 used.
3251 4) Both left and right hand arguments to STRLESS STREQUAL STR‐
3254 GREATER are independently tested to see if they are defined
3255 variables, if so their defined values are used otherwise the
3256 original value is used.
3257 5) Both left and right hand argumemnts to VERSION_LESS VER‐
3260 SION_EQUAL VERSION_GREATER are independently tested to see if
3261 they are defined variables, if so their defined values are used
3262 otherwise the original value is used.
3263 6) The right hand argument to NOT is tested to see if it is a
3266 boolean constant, if so the value is used, otherwise it is
3267 assumed to be a variable and it is dereferenced.
3268 7) The left and right hand arguments to AND OR are independently
3271 tested to see if they are boolean constants, if so they are used
3272 as such, otherwise they are assumed to be variables and are
3273 dereferenced.
3274 include
3278 Load and run CMake code from a file or module.
3279 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
3281 [NO_POLICY_SCOPE])
3282 Load and run CMake code from the file given. Variable reads and
3284 writes access the scope of the caller (dynamic scoping). If
3285 OPTIONAL is present, then no error is raised if the file does
3286 not exist. If RESULT_VARIABLE is given the variable will be set
3287 to the full filename which has been included or NOTFOUND if it
3288 failed.
3289 If a module is specified instead of a file, the file with name
3292 <modulename>.cmake is searched first in CMAKE_MODULE_PATH, then
3293 in the CMake module directory. There is one exception to this:
3294 if the file which calls include() is located itself in the CMake
3295 module directory, then first the CMake module directory is
3296 searched and CMAKE_MODULE_PATH afterwards. See also policy
3297 CMP0017.
3298 See the cmake_policy() command documentation for discussion of
3301 the NO_POLICY_SCOPE option.
3302 include_directories
3305 Add include directories to the build.
3306 include_directories([AFTER|BEFORE] [SYSTEM] dir1 dir2 ...)
3308 Add the given directories to those the compiler uses to search
3310 for include files. Relative paths are interpreted as relative
3311 to the current source directory.
3312 The include directories are added to the directory property
3315 INCLUDE_DIRECTORIES for the current CMakeLists file. They are
3316 also added to the target property INCLUDE_DIRECTORIES for each
3317 target in the current CMakeLists file. The target property val‐
3318 ues are the ones used by the generators.
3319 By default the directories are appended onto the current list of
3322 directories. This default behavior can be changed by setting
3323 CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE
3324 explicitly, you can select between appending and prepending,
3325 independent of the default.
3326 If the SYSTEM option is given, the compiler will be told the
3329 directories are meant as system include directories on some
3330 platforms (signalling this setting might achieve effects such as
3331 the compiler skipping warnings, or these fixed-install system
3332 files not being considered in dependency calculations - see com‐
3333 piler docs).
3334 include_external_msproject
3337 Include an external Microsoft project file in a workspace.
3338 include_external_msproject(projectname location
3340 [TYPE projectTypeGUID]
3341 [GUID projectGUID]
3342 [PLATFORM platformName]
3343 dep1 dep2 ...)
3344 Includes an external Microsoft project in the generated
3346 workspace file. Currently does nothing on UNIX. This will cre‐
3347 ate a target named [projectname]. This can be used in the
3348 add_dependencies command to make things depend on the external
3349 project.
3350 TYPE, GUID and PLATFORM are optional parameters that allow one
3353 to specify the type of project, id (GUID) of the project and the
3354 name of the target platform. This is useful for projects
3355 requiring values other than the default (e.g. WIX projects).
3356 These options are not supported by the Visual Studio 6 genera‐
3357 tor.
3358 include_regular_expression
3361 Set the regular expression used for dependency checking.
3362 include_regular_expression(regex_match [regex_complain])
3364 Set the regular expressions used in dependency checking. Only
3366 files matching regex_match will be traced as dependencies. Only
3367 files matching regex_complain will generate warnings if they
3368 cannot be found (standard header paths are not searched). The
3369 defaults are:
3370 regex_match = "^.*$" (match everything)
3373 regex_complain = "^$" (match empty string only)
3374 install
3377 Specify rules to run at install time.
3378 This command generates installation rules for a project. Rules
3380 specified by calls to this command within a source directory are
3381 executed in order during installation. The order across direc‐
3382 tories is not defined.
3383 There are multiple signatures for this command. Some of them
3386 define installation properties for files and targets. Proper‐
3387 ties common to multiple signatures are covered here but they are
3388 valid only for signatures that specify them.
3389 DESTINATION arguments specify the directory on disk to which a
3392 file will be installed. If a full path (with a leading slash or
3393 drive letter) is given it is used directly. If a relative path
3394 is given it is interpreted relative to the value of
3395 CMAKE_INSTALL_PREFIX. The prefix can be relocated at install
3396 time using DESTDIR mechanism explained in the CMAKE_INSTALL_PRE‐
3397 FIX variable documentation.
3398 PERMISSIONS arguments specify permissions for installed files.
3401 Valid permissions are OWNER_READ, OWNER_WRITE, OWNER_EXECUTE,
3402 GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE,
3403 WORLD_EXECUTE, SETUID, and SETGID. Permissions that do not make
3404 sense on certain platforms are ignored on those platforms.
3405 The CONFIGURATIONS argument specifies a list of build configura‐
3408 tions for which the install rule applies (Debug, Release, etc.).
3409 The COMPONENT argument specifies an installation component name
3412 with which the install rule is associated, such as "runtime" or
3413 "development". During component-specific installation only
3414 install rules associated with the given component name will be
3415 executed. During a full installation all components are
3416 installed. If COMPONENT is not provided a default component
3417 "Unspecified" is created. The default component name may be con‐
3418 trolled with the CMAKE_INSTALL_DEFAULT_COMPONENT_NAME variable.
3419 The RENAME argument specifies a name for an installed file that
3422 may be different from the original file. Renaming is allowed
3423 only when a single file is installed by the command.
3424 The OPTIONAL argument specifies that it is not an error if the
3427 file to be installed does not exist.
3428 The TARGETS signature:
3431 install(TARGETS targets... [EXPORT <export-name>]
3434 [[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE|
3435 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
3436 [DESTINATION <dir>]
3437 [INCLUDES DESTINATION [<dir> ...]]
3438 [PERMISSIONS permissions...]
3439 [CONFIGURATIONS [Debug|Release|...]]
3440 [COMPONENT <component>]
3441 [OPTIONAL] [NAMELINK_ONLY|NAMELINK_SKIP]
3442 ] [...])
3443 The TARGETS form specifies rules for installing targets from a
3445 project. There are five kinds of target files that may be
3446 installed: ARCHIVE, LIBRARY, RUNTIME, FRAMEWORK, and BUNDLE.
3447 Executables are treated as RUNTIME targets, except that those
3448 marked with the MACOSX_BUNDLE property are treated as BUNDLE
3449 targets on OS X. Static libraries are always treated as ARCHIVE
3450 targets. Module libraries are always treated as LIBRARY targets.
3451 For non-DLL platforms shared libraries are treated as LIBRARY
3452 targets, except that those marked with the FRAMEWORK property
3453 are treated as FRAMEWORK targets on OS X. For DLL platforms the
3454 DLL part of a shared library is treated as a RUNTIME target and
3455 the corresponding import library is treated as an ARCHIVE tar‐
3456 get. All Windows-based systems including Cygwin are DLL plat‐
3457 forms. The ARCHIVE, LIBRARY, RUNTIME, and FRAMEWORK arguments
3458 change the type of target to which the subsequent properties
3459 apply. If none is given the installation properties apply to
3460 all target types. If only one is given then only targets of
3461 that type will be installed (which can be used to install just a
3462 DLL or just an import library).The INCLUDES DESTINATION speci‐
3463 fies a list of directories which will be added to the INTER‐
3464 FACE_INCLUDE_DIRECTORIES of the <targets> when exported by
3465 install(EXPORT). If a relative path is specified, it is treated
3466 as relative to the $<INSTALL_PREFIX>.
3467 The PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE arguments cause
3470 subsequent properties to be applied to installing a FRAMEWORK
3471 shared library target's associated files on non-Apple platforms.
3472 Rules defined by these arguments are ignored on Apple platforms
3473 because the associated files are installed into the appropriate
3474 locations inside the framework folder. See documentation of the
3475 PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE target properties
3476 for details.
3477 Either NAMELINK_ONLY or NAMELINK_SKIP may be specified as a
3480 LIBRARY option. On some platforms a versioned shared library
3481 has a symbolic link such as
3482 lib<name>.so -> lib<name>.so.1
3485 where "lib<name>.so.1" is the soname of the library and
3487 "lib<name>.so" is a "namelink" allowing linkers to find the
3488 library when given "-l<name>". The NAMELINK_ONLY option causes
3489 installation of only the namelink when a library target is
3490 installed. The NAMELINK_SKIP option causes installation of
3491 library files other than the namelink when a library target is
3492 installed. When neither option is given both portions are
3493 installed. On platforms where versioned shared libraries do not
3494 have namelinks or when a library is not versioned the
3495 NAMELINK_SKIP option installs the library and the NAMELINK_ONLY
3496 option installs nothing. See the VERSION and SOVERSION target
3497 properties for details on creating versioned shared libraries.
3498 One or more groups of properties may be specified in a single
3501 call to the TARGETS form of this command. A target may be
3502 installed more than once to different locations. Consider hypo‐
3503 thetical targets "myExe", "mySharedLib", and "myStaticLib". The
3504 code
3505 install(TARGETS myExe mySharedLib myStaticLib
3508 RUNTIME DESTINATION bin
3509 LIBRARY DESTINATION lib
3510 ARCHIVE DESTINATION lib/static)
3511 install(TARGETS mySharedLib DESTINATION /some/full/path)
3512 will install myExe to <prefix>/bin and myStaticLib to <pre‐
3514 fix>/lib/static. On non-DLL platforms mySharedLib will be
3515 installed to <prefix>/lib and /some/full/path. On DLL platforms
3516 the mySharedLib DLL will be installed to <prefix>/bin and
3517 /some/full/path and its import library will be installed to
3518 <prefix>/lib/static and /some/full/path.
3519 The EXPORT option associates the installed target files with an
3522 export called <export-name>. It must appear before any RUNTIME,
3523 LIBRARY, or ARCHIVE options. To actually install the export
3524 file itself, call install(EXPORT). See documentation of the
3525 install(EXPORT ...) signature below for details.
3526 Installing a target with EXCLUDE_FROM_ALL set to true has unde‐
3529 fined behavior.
3530 The FILES signature:
3533 install(FILES files... DESTINATION <dir>
3536 [PERMISSIONS permissions...]
3537 [CONFIGURATIONS [Debug|Release|...]]
3538 [COMPONENT <component>]
3539 [RENAME <name>] [OPTIONAL])
3540 The FILES form specifies rules for installing files for a
3542 project. File names given as relative paths are interpreted
3543 with respect to the current source directory. Files installed
3544 by this form are by default given permissions OWNER_WRITE,
3545 OWNER_READ, GROUP_READ, and WORLD_READ if no PERMISSIONS argu‐
3546 ment is given.
3547 The PROGRAMS signature:
3550 install(PROGRAMS files... DESTINATION <dir>
3553 [PERMISSIONS permissions...]
3554 [CONFIGURATIONS [Debug|Release|...]]
3555 [COMPONENT <component>]
3556 [RENAME <name>] [OPTIONAL])
3557 The PROGRAMS form is identical to the FILES form except that the
3559 default permissions for the installed file also include
3560 OWNER_EXECUTE, GROUP_EXECUTE, and WORLD_EXECUTE. This form is
3561 intended to install programs that are not targets, such as shell
3562 scripts. Use the TARGETS form to install targets built within
3563 the project.
3564 The DIRECTORY signature:
3567 install(DIRECTORY dirs... DESTINATION <dir>
3570 [FILE_PERMISSIONS permissions...]
3571 [DIRECTORY_PERMISSIONS permissions...]
3572 [USE_SOURCE_PERMISSIONS] [OPTIONAL]
3573 [CONFIGURATIONS [Debug|Release|...]]
3574 [COMPONENT <component>] [FILES_MATCHING]
3575 [[PATTERN <pattern> | REGEX <regex>]
3576 [EXCLUDE] [PERMISSIONS permissions...]] [...])
3577 The DIRECTORY form installs contents of one or more directories
3579 to a given destination. The directory structure is copied ver‐
3580 batim to the destination. The last component of each directory
3581 name is appended to the destination directory but a trailing
3582 slash may be used to avoid this because it leaves the last com‐
3583 ponent empty. Directory names given as relative paths are
3584 interpreted with respect to the current source directory. If no
3585 input directory names are given the destination directory will
3586 be created but nothing will be installed into it. The FILE_PER‐
3587 MISSIONS and DIRECTORY_PERMISSIONS options specify permissions
3588 given to files and directories in the destination. If
3589 USE_SOURCE_PERMISSIONS is specified and FILE_PERMISSIONS is not,
3590 file permissions will be copied from the source directory struc‐
3591 ture. If no permissions are specified files will be given the
3592 default permissions specified in the FILES form of the command,
3593 and the directories will be given the default permissions speci‐
3594 fied in the PROGRAMS form of the command.
3595 Installation of directories may be controlled with fine granu‐
3598 larity using the PATTERN or REGEX options. These "match"
3599 options specify a globbing pattern or regular expression to
3600 match directories or files encountered within input directories.
3601 They may be used to apply certain options (see below) to a sub‐
3602 set of the files and directories encountered. The full path to
3603 each input file or directory (with forward slashes) is matched
3604 against the expression. A PATTERN will match only complete file
3605 names: the portion of the full path matching the pattern must
3606 occur at the end of the file name and be preceded by a slash. A
3607 REGEX will match any portion of the full path but it may use '/'
3608 and '$' to simulate the PATTERN behavior. By default all files
3609 and directories are installed whether or not they are matched.
3610 The FILES_MATCHING option may be given before the first match
3611 option to disable installation of files (but not directories)
3612 not matched by any expression. For example, the code
3613 install(DIRECTORY src/ DESTINATION include/myproj
3616 FILES_MATCHING PATTERN "*.h")
3617 will extract and install header files from a source tree.
3619 Some options may follow a PATTERN or REGEX expression and are
3622 applied only to files or directories matching them. The EXCLUDE
3623 option will skip the matched file or directory. The PERMISSIONS
3624 option overrides the permissions setting for the matched file or
3625 directory. For example the code
3626 install(DIRECTORY icons scripts/ DESTINATION share/myproj
3629 PATTERN "CVS" EXCLUDE
3630 PATTERN "scripts/*"
3631 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
3632 GROUP_EXECUTE GROUP_READ)
3633 will install the icons directory to share/myproj/icons and the
3635 scripts directory to share/myproj. The icons will get default
3636 file permissions, the scripts will be given specific permis‐
3637 sions, and any CVS directories will be excluded.
3638 The SCRIPT and CODE signature:
3641 install([[SCRIPT <file>] [CODE <code>]] [...])
3644 The SCRIPT form will invoke the given CMake script files during
3646 installation. If the script file name is a relative path it
3647 will be interpreted with respect to the current source direc‐
3648 tory. The CODE form will invoke the given CMake code during
3649 installation. Code is specified as a single argument inside a
3650 double-quoted string. For example, the code
3651 install(CODE "MESSAGE(\"Sample install message.\")")
3654 will print a message during installation.
3656 The EXPORT signature:
3659 install(EXPORT <export-name> DESTINATION <dir>
3662 [NAMESPACE <namespace>] [FILE <name>.cmake]
3663 [PERMISSIONS permissions...]
3664 [CONFIGURATIONS [Debug|Release|...]]
3665 [EXPORT_LINK_INTERFACE_LIBRARIES]
3666 [COMPONENT <component>])
3667 The EXPORT form generates and installs a CMake file containing
3669 code to import targets from the installation tree into another
3670 project. Target installations are associated with the export
3671 <export-name> using the EXPORT option of the install(TARGETS
3672 ...) signature documented above. The NAMESPACE option will
3673 prepend <namespace> to the target names as they are written to
3674 the import file. By default the generated file will be called
3675 <export-name>.cmake but the FILE option may be used to specify a
3676 different name. The value given to the FILE option must be a
3677 file name with the ".cmake" extension. If a CONFIGURATIONS
3678 option is given then the file will only be installed when one of
3679 the named configurations is installed. Additionally, the gener‐
3680 ated import file will reference only the matching target config‐
3681 urations. The EXPORT_LINK_INTERFACE_LIBRARIES keyword, if
3682 present, causes the contents of the properties matching
3683 (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported,
3684 when policy CMP0022 is NEW. If a COMPONENT option is specified
3685 that does not match that given to the targets associated with
3686 <export-name> the behavior is undefined. If a library target is
3687 included in the export but a target to which it links is not
3688 included the behavior is unspecified.
3689 The EXPORT form is useful to help outside projects use targets
3692 built and installed by the current project. For example, the
3693 code
3694 install(TARGETS myexe EXPORT myproj DESTINATION bin)
3697 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
3698 will install the executable myexe to <prefix>/bin and code to
3700 import it in the file "<prefix>/lib/myproj/myproj.cmake". An
3701 outside project may load this file with the include command and
3702 reference the myexe executable from the installation tree using
3703 the imported target name mp_myexe as if the target were built in
3704 its own tree.
3705 NOTE: This command supercedes the INSTALL_TARGETS command and
3708 the target properties PRE_INSTALL_SCRIPT and
3709 POST_INSTALL_SCRIPT. It also replaces the FILES forms of the
3710 INSTALL_FILES and INSTALL_PROGRAMS commands. The processing
3711 order of these install rules relative to those generated by
3712 INSTALL_TARGETS, INSTALL_FILES, and INSTALL_PROGRAMS commands is
3713 not defined.
3714 link_directories
3718 Specify directories in which the linker will look for libraries.
3719 link_directories(directory1 directory2 ...)
3721 Specify the paths in which the linker should search for
3723 libraries. The command will apply only to targets created after
3724 it is called. Relative paths given to this command are inter‐
3725 preted as relative to the current source directory, see CMP0015.
3726 Note that this command is rarely necessary. Library locations
3729 returned by find_package() and find_library() are absolute
3730 paths. Pass these absolute library file paths directly to the
3731 target_link_libraries() command. CMake will ensure the linker
3732 finds them.
3733 list List operations.
3736 list(LENGTH <list> <output variable>)
3738 list(GET <list> <element index> [<element index> ...]
3739 <output variable>)
3740 list(APPEND <list> <element> [<element> ...])
3741 list(FIND <list> <value> <output variable>)
3742 list(INSERT <list> <element_index> <element> [<element> ...])
3743 list(REMOVE_ITEM <list> <value> [<value> ...])
3744 list(REMOVE_AT <list> <index> [<index> ...])
3745 list(REMOVE_DUPLICATES <list>)
3746 list(REVERSE <list>)
3747 list(SORT <list>)
3748 LENGTH will return a given list's length.
3750 GET will return list of elements specified by indices from the
3753 list.
3754 APPEND will append elements to the list.
3757 FIND will return the index of the element specified in the list
3760 or -1 if it wasn't found.
3761 INSERT will insert elements to the list to the specified loca‐
3764 tion.
3765 REMOVE_AT and REMOVE_ITEM will remove items from the list. The
3768 difference is that REMOVE_ITEM will remove the given items,
3769 while REMOVE_AT will remove the items at the given indices.
3770 REMOVE_DUPLICATES will remove duplicated items in the list.
3773 REVERSE reverses the contents of the list in-place.
3776 SORT sorts the list in-place alphabetically.
3779 The list subcommands APPEND, INSERT, REMOVE_AT, REMOVE_ITEM,
3782 REMOVE_DUPLICATES, REVERSE and SORT may create new values for
3783 the list within the current CMake variable scope. Similar to the
3784 SET command, the LIST command creates new variable values in the
3785 current scope, even if the list itself is actually defined in a
3786 parent scope. To propagate the results of these operations
3787 upwards, use SET with PARENT_SCOPE, SET with CACHE INTERNAL, or
3788 some other means of value propagation.
3789 NOTES: A list in cmake is a ; separated group of strings. To
3792 create a list the set command can be used. For example, set(var
3793 a b c d e) creates a list with a;b;c;d;e, and set(var "a b c d
3794 e") creates a string or a list with one item in it.
3795 When specifying index values, if <element index> is 0 or
3798 greater, it is indexed from the beginning of the list, with 0
3799 representing the first list element. If <element index> is -1 or
3800 lesser, it is indexed from the end of the list, with -1 repre‐
3801 senting the last list element. Be careful when counting with
3802 negative indices: they do not start from 0. -0 is equivalent to
3803 0, the first list element.
3804 load_cache
3808 Load in the values from another project's CMake cache.
3809 load_cache(pathToCacheFile READ_WITH_PREFIX
3811 prefix entry1...)
3812 Read the cache and store the requested entries in variables with
3814 their name prefixed with the given prefix. This only reads the
3815 values, and does not create entries in the local project's
3816 cache.
3817 load_cache(pathToCacheFile [EXCLUDE entry1...]
3820 [INCLUDE_INTERNALS entry1...])
3821 Load in the values from another cache and store them in the
3823 local project's cache as internal entries. This is useful for a
3824 project that depends on another project built in a different
3825 tree. EXCLUDE option can be used to provide a list of entries
3826 to be excluded. INCLUDE_INTERNALS can be used to provide a list
3827 of internal entries to be included. Normally, no internal
3828 entries are brought in. Use of this form of the command is
3829 strongly discouraged, but it is provided for backward compati‐
3830 bility.
3831 load_command
3834 Load a command into a running CMake.
3835 load_command(COMMAND_NAME <loc1> [loc2 ...])
3837 The given locations are searched for a library whose name is
3839 cmCOMMAND_NAME. If found, it is loaded as a module and the com‐
3840 mand is added to the set of available CMake commands. Usually,
3841 TRY_COMPILE is used before this command to compile the module.
3842 If the command is successfully loaded a variable named
3843 CMAKE_LOADED_COMMAND_<COMMAND_NAME>
3846 will be set to the full path of the module that was loaded.
3848 Otherwise the variable will not be set.
3849 macro Start recording a macro for later invocation as a command.
3852 macro(<name> [arg1 [arg2 [arg3 ...]]])
3854 COMMAND1(ARGS ...)
3855 COMMAND2(ARGS ...)
3856 ...
3857 endmacro(<name>)
3858 Define a macro named <name> that takes arguments named arg1 arg2
3860 arg3 (...). Commands listed after macro, but before the match‐
3861 ing endmacro, are not invoked until the macro is invoked. When
3862 it is invoked, the commands recorded in the macro are first mod‐
3863 ified by replacing formal parameters (${arg1}) with the argu‐
3864 ments passed, and then invoked as normal commands. In addition
3865 to referencing the formal parameters you can reference the val‐
3866 ues ${ARGC} which will be set to the number of arguments passed
3867 into the function as well as ${ARGV0} ${ARGV1} ${ARGV2} ...
3868 which will have the actual values of the arguments passed in.
3869 This facilitates creating macros with optional arguments. Addi‐
3870 tionally ${ARGV} holds the list of all arguments given to the
3871 macro and ${ARGN} holds the list of arguments past the last
3872 expected argument. Note that the parameters to a macro and val‐
3873 ues such as ARGN are not variables in the usual CMake sense.
3874 They are string replacements much like the C preprocessor would
3875 do with a macro. If you want true CMake variables and/or better
3876 CMake scope control you should look at the function command.
3877 See the cmake_policy() command documentation for the behavior of
3880 policies inside macros.
3881 mark_as_advanced
3884 Mark cmake cached variables as advanced.
3885 mark_as_advanced([CLEAR|FORCE] VAR VAR2 VAR...)
3887 Mark the named cached variables as advanced. An advanced vari‐
3889 able will not be displayed in any of the cmake GUIs unless the
3890 show advanced option is on. If CLEAR is the first argument
3891 advanced variables are changed back to unadvanced. If FORCE is
3892 the first argument, then the variable is made advanced. If nei‐
3893 ther FORCE nor CLEAR is specified, new values will be marked as
3894 advanced, but if the variable already has an
3895 advanced/non-advanced state, it will not be changed.
3896 It does nothing in script mode.
3899 math Mathematical expressions.
3902 math(EXPR <output variable> <math expression>)
3904 EXPR evaluates mathematical expression and returns result in the
3906 output variable. Example mathematical expression is '5 * ( 10 +
3907 13 )'. Supported operators are + - * / % | & ^ ~ << >> * / %.
3908 They have the same meaning as they do in C code.
3909 message
3912 Display a message to the user.
3913 message([STATUS|WARNING|AUTHOR_WARNING|FATAL_ERROR|SEND_ERROR]
3915 "message to display" ...)
3916 The optional keyword determines the type of message:
3918 (none) = Important information
3921 STATUS = Incidental information
3922 WARNING = CMake Warning, continue processing
3923 AUTHOR_WARNING = CMake Warning (dev), continue processing
3924 SEND_ERROR = CMake Error, continue processing,
3925 but skip generation
3926 FATAL_ERROR = CMake Error, stop processing and generation
3927 The CMake command-line tool displays STATUS messages on stdout
3929 and all other message types on stderr. The CMake GUI displays
3930 all messages in its log area. The interactive dialogs (ccmake
3931 and CMakeSetup) show STATUS messages one at a time on a status
3932 line and other messages in interactive pop-up boxes.
3933 CMake Warning and Error message text displays using a simple
3936 markup language. Non-indented text is formatted in line-wrapped
3937 paragraphs delimited by newlines. Indented text is considered
3938 pre-formatted.
3939 option Provides an option that the user can optionally select.
3942 option(<option_variable> "help string describing option"
3944 [initial value])
3945 Provide an option for the user to select as ON or OFF. If no
3947 initial value is provided, OFF is used.
3948 If you have options that depend on the values of other options,
3951 see the module help for CMakeDependentOption.
3952 project
3955 Set a name for the entire project.
3956 project(<projectname> [languageName1 languageName2 ... ] )
3958 Sets the name of the project. Additionally this sets the vari‐
3960 ables <projectName>_BINARY_DIR and <projectName>_SOURCE_DIR to
3961 the respective values.
3962 Optionally you can specify which languages your project sup‐
3965 ports. Example languages are CXX (i.e. C++), C, Fortran, etc.
3966 By default C and CXX are enabled. E.g. if you do not have a C++
3967 compiler, you can disable the check for it by explicitly listing
3968 the languages you want to support, e.g. C. By using the special
3969 language "NONE" all checks for any language can be disabled. If
3970 a variable exists called CMAKE_PROJECT_<projectName>_INCLUDE,
3971 the file pointed to by that variable will be included as the
3972 last step of the project command.
3973 The top-level CMakeLists.txt file for a project must contain a
3976 literal, direct call to the project() command; loading one
3977 through the include() command is not sufficient. If no such
3978 call exists CMake will implicitly add one to the top that
3979 enables the default languages (C and CXX).
3980 qt_wrap_cpp
3983 Create Qt Wrappers.
3984 qt_wrap_cpp(resultingLibraryName DestName
3986 SourceLists ...)
3987 Produce moc files for all the .h files listed in the
3989 SourceLists. The moc files will be added to the library using
3990 the DestName source list.
3991 qt_wrap_ui
3994 Create Qt user interfaces Wrappers.
3995 qt_wrap_ui(resultingLibraryName HeadersDestName
3997 SourcesDestName SourceLists ...)
3998 Produce .h and .cxx files for all the .ui files listed in the
4000 SourceLists. The .h files will be added to the library using
4001 the HeadersDestNamesource list. The .cxx files will be added to
4002 the library using the SourcesDestNamesource list.
4003 remove_definitions
4006 Removes -D define flags added by add_definitions.
4007 remove_definitions(-DFOO -DBAR ...)
4009 Removes flags (added by add_definitions) from the compiler com‐
4011 mand line for sources in the current directory and below.
4012 return Return from a file, directory or function.
4015 return()
4017 Returns from a file, directory or function. When this command is
4019 encountered in an included file (via include() or find_pack‐
4020 age()), it causes processing of the current file to stop and
4021 control is returned to the including file. If it is encountered
4022 in a file which is not included by another file, e.g. a CMake‐
4023 Lists.txt, control is returned to the parent directory if there
4024 is one. If return is called in a function, control is returned
4025 to the caller of the function. Note that a macro is not a func‐
4026 tion and does not handle return like a function does.
4027 separate_arguments
4030 Parse space-separated arguments into a semicolon-separated list.
4031 separate_arguments(<var> <UNIX|WINDOWS>_COMMAND "<args>")
4033 Parses a unix- or windows-style command-line string "<args>" and
4035 stores a semicolon-separated list of the arguments in <var>.
4036 The entire command line must be given in one "<args>" argument.
4037 The UNIX_COMMAND mode separates arguments by unquoted white‐
4040 space. It recognizes both single-quote and double-quote pairs.
4041 A backslash escapes the next literal character (\" is "); there
4042 are no special escapes (\n is just n).
4043 The WINDOWS_COMMAND mode parses a windows command-line using the
4046 same syntax the runtime library uses to construct argv at
4047 startup. It separates arguments by whitespace that is not dou‐
4048 ble-quoted. Backslashes are literal unless they precede dou‐
4049 ble-quotes. See the MSDN article "Parsing C Command-Line Argu‐
4050 ments" for details.
4051 separate_arguments(VARIABLE)
4054 Convert the value of VARIABLE to a semi-colon separated list.
4056 All spaces are replaced with ';'. This helps with generating
4057 command lines.
4058 set Set a CMake, cache or environment variable to a given value.
4061 set(<variable> <value>
4063 [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])
4064 Within CMake sets <variable> to the value <value>. <value> is
4066 expanded before <variable> is set to it. Normally, set will set
4067 a regular CMake variable. If CACHE is present, then the <vari‐
4068 able> is put in the cache instead, unless it is already in the
4069 cache. See section 'Variable types in CMake' below for details
4070 of regular and cache variables and their interactions. If CACHE
4071 is used, <type> and <docstring> are required. <type> is used by
4072 the CMake GUI to choose a widget with which the user sets a
4073 value. The value for <type> may be one of
4074 FILEPATH = File chooser dialog.
4077 PATH = Directory chooser dialog.
4078 STRING = Arbitrary string.
4079 BOOL = Boolean ON/OFF checkbox.
4080 INTERNAL = No GUI entry (used for persistent variables).
4081 If <type> is INTERNAL, the cache variable is marked as internal,
4083 and will not be shown to the user in tools like cmake-gui. This
4084 is intended for values that should be persisted in the cache,
4085 but which users should not normally change. INTERNAL implies
4086 FORCE.
4087 Normally, set(...CACHE...) creates cache variables, but does not
4090 modify them. If FORCE is specified, the value of the cache vari‐
4091 able is set, even if the variable is already in the cache. This
4092 should normally be avoided, as it will remove any changes to the
4093 cache variable's value by the user.
4094 If PARENT_SCOPE is present, the variable will be set in the
4097 scope above the current scope. Each new directory or function
4098 creates a new scope. This command will set the value of a vari‐
4099 able into the parent directory or calling function (whichever is
4100 applicable to the case at hand). PARENT_SCOPE cannot be combined
4101 with CACHE.
4102 If <value> is not specified then the variable is removed instead
4105 of set. See also: the unset() command.
4106 set(<variable> <value1> ... <valueN>)
4109 In this case <variable> is set to a semicolon separated list of
4111 values.
4112 <variable> can be an environment variable such as:
4115 set( ENV{PATH} /home/martink )
4118 in which case the environment variable will be set.
4120 *** Variable types in CMake ***
4123 In CMake there are two types of variables: normal variables and
4126 cache variables. Normal variables are meant for the internal use
4127 of the script (just like variables in most programming lan‐
4128 guages); they are not persisted across CMake runs. Cache vari‐
4129 ables (unless set with INTERNAL) are mostly intended for config‐
4130 uration settings where the first CMake run determines a suitable
4131 default value, which the user can then override, by editing the
4132 cache with tools such as ccmake or cmake-gui. Cache variables
4133 are stored in the CMake cache file, and are persisted across
4134 CMake runs.
4135 Both types can exist at the same time with the same name but
4138 different values. When ${FOO} is evaluated, CMake first looks
4139 for a normal variable 'FOO' in scope and uses it if set. If and
4140 only if no normal variable exists then it falls back to the
4141 cache variable 'FOO'.
4142 Some examples:
4145 The code 'set(FOO "x")' sets the normal variable 'FOO'. It does
4148 not touch the cache, but it will hide any existing cache value
4149 'FOO'.
4150 The code 'set(FOO "x" CACHE ...)' checks for 'FOO' in the cache,
4153 ignoring any normal variable of the same name. If 'FOO' is in
4154 the cache then nothing happens to either the normal variable or
4155 the cache variable. If 'FOO' is not in the cache, then it is
4156 added to the cache.
4157 Finally, whenever a cache variable is added or modified by a
4160 command, CMake also *removes* the normal variable of the same
4161 name from the current scope so that an immediately following
4162 evaluation of it will expose the newly cached value.
4163 Normally projects should avoid using normal and cache variables
4166 of the same name, as this interaction can be hard to follow.
4167 However, in some situations it can be useful. One example (used
4168 by some projects):
4169 A project has a subproject in its source tree. The child project
4172 has its own CMakeLists.txt, which is included from the parent
4173 CMakeLists.txt using add_subdirectory(). Now, if the parent and
4174 the child project provide the same option (for example a com‐
4175 piler option), the parent gets the first chance to add a
4176 user-editable option to the cache. Normally, the child would
4177 then use the same value that the parent uses. However, it may be
4178 necessary to hard-code the value for the child project's option
4179 while still allowing the user to edit the value used by the par‐
4180 ent project. The parent project can achieve this simply by set‐
4181 ting a normal variable with the same name as the option in a
4182 scope sufficient to hide the option's cache variable from the
4183 child completely. The parent has already set the cache variable,
4184 so the child's set(...CACHE...) will do nothing, and evaluating
4185 the option variable will use the value from the normal variable,
4186 which hides the cache variable.
4187 set_directory_properties
4190 Set a property of the directory.
4191 set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
4193 Set a property for the current directory and subdirectories. If
4195 the property is not found, CMake will report an error. The prop‐
4196 erties include: INCLUDE_DIRECTORIES, LINK_DIRECTORIES,
4197 INCLUDE_REGULAR_EXPRESSION, and ADDITIONAL_MAKE_CLEAN_FILES.
4198 ADDITIONAL_MAKE_CLEAN_FILES is a list of files that will be
4199 cleaned as a part of "make clean" stage.
4200 set_property
4203 Set a named property in a given scope.
4204 set_property(<GLOBAL |
4206 DIRECTORY [dir] |
4207 TARGET [target1 [target2 ...]] |
4208 SOURCE [src1 [src2 ...]] |
4209 TEST [test1 [test2 ...]] |
4210 CACHE [entry1 [entry2 ...]]>
4211 [APPEND] [APPEND_STRING]
4212 PROPERTY <name> [value1 [value2 ...]])
4213 Set one property on zero or more objects of a scope. The first
4215 argument determines the scope in which the property is set. It
4216 must be one of the following:
4217 GLOBAL scope is unique and does not accept a name.
4220 DIRECTORY scope defaults to the current directory but another
4223 directory (already processed by CMake) may be named by full or
4224 relative path.
4225 TARGET scope may name zero or more existing targets.
4228 SOURCE scope may name zero or more source files. Note that
4231 source file properties are visible only to targets added in the
4232 same directory (CMakeLists.txt).
4233 TEST scope may name zero or more existing tests.
4236 CACHE scope must name zero or more cache existing entries.
4239 The required PROPERTY option is immediately followed by the name
4242 of the property to set. Remaining arguments are used to compose
4243 the property value in the form of a semicolon-separated list.
4244 If the APPEND option is given the list is appended to any exist‐
4245 ing property value.If the APPEND_STRING option is given the
4246 string is append to any existing property value as string, i.e.
4247 it results in a longer string and not a list of strings.
4248 set_source_files_properties
4251 Source files can have properties that affect how they are built.
4252 set_source_files_properties([file1 [file2 [...]]]
4254 PROPERTIES prop1 value1
4255 [prop2 value2 [...]])
4256 Set properties associated with source files using a key/value
4258 paired list. See properties documentation for those known to
4259 CMake. Unrecognized properties are ignored. Source file prop‐
4260 erties are visible only to targets added in the same directory
4261 (CMakeLists.txt).
4262 set_target_properties
4265 Targets can have properties that affect how they are built.
4266 set_target_properties(target1 target2 ...
4268 PROPERTIES prop1 value1
4269 prop2 value2 ...)
4270 Set properties on a target. The syntax for the command is to
4272 list all the files you want to change, and then provide the val‐
4273 ues you want to set next. You can use any prop value pair you
4274 want and extract it later with the GET_TARGET_PROPERTY command.
4275 Properties that affect the name of a target's output file are as
4278 follows. The PREFIX and SUFFIX properties override the default
4279 target name prefix (such as "lib") and suffix (such as ".so").
4280 IMPORT_PREFIX and IMPORT_SUFFIX are the equivalent properties
4281 for the import library corresponding to a DLL (for SHARED
4282 library targets). OUTPUT_NAME sets the real name of a target
4283 when it is built and can be used to help create two targets of
4284 the same name even though CMake requires unique logical target
4285 names. There is also a <CONFIG>_OUTPUT_NAME that can set the
4286 output name on a per-configuration basis. <CONFIG>_POSTFIX sets
4287 a postfix for the real name of the target when it is built under
4288 the configuration named by <CONFIG> (in upper-case, such as
4289 "DEBUG_POSTFIX"). The value of this property is initialized
4290 when the target is created to the value of the variable
4291 CMAKE_<CONFIG>_POSTFIX (except for executable targets because
4292 earlier CMake versions which did not use this variable for exe‐
4293 cutables).
4294 The LINK_FLAGS property can be used to add extra flags to the
4297 link step of a target. LINK_FLAGS_<CONFIG> will add to the con‐
4298 figuration <CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL,
4299 RELWITHDEBINFO. DEFINE_SYMBOL sets the name of the preprocessor
4300 symbol defined when compiling sources in a shared library. If
4301 not set here then it is set to target_EXPORTS by default (with
4302 some substitutions if the target is not a valid C identifier).
4303 This is useful for headers to know whether they are being
4304 included from inside their library or outside to properly setup
4305 dllexport/dllimport decorations. The COMPILE_FLAGS property sets
4306 additional compiler flags used to build sources within the tar‐
4307 get. It may also be used to pass additional preprocessor defi‐
4308 nitions.
4309 The LINKER_LANGUAGE property is used to change the tool used to
4312 link an executable or shared library. The default is set the
4313 language to match the files in the library. CXX and C are common
4314 values for this property.
4315 For shared libraries VERSION and SOVERSION can be used to spec‐
4318 ify the build version and API version respectively. When build‐
4319 ing or installing appropriate symlinks are created if the plat‐
4320 form supports symlinks and the linker supports so-names. If only
4321 one of both is specified the missing is assumed to have the same
4322 version number. For executables VERSION can be used to specify
4323 the build version. When building or installing appropriate sym‐
4324 links are created if the platform supports symlinks. For shared
4325 libraries and executables on Windows the VERSION attribute is
4326 parsed to extract a "major.minor" version number. These numbers
4327 are used as the image version of the binary.
4328 There are a few properties used to specify RPATH rules.
4331 INSTALL_RPATH is a semicolon-separated list specifying the rpath
4332 to use in installed targets (for platforms that support it).
4333 INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to true
4334 will append directories in the linker search path and outside
4335 the project to the INSTALL_RPATH. SKIP_BUILD_RPATH is a boolean
4336 specifying whether to skip automatic generation of an rpath
4337 allowing the target to run from the build tree.
4338 BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link
4339 the target in the build tree with the INSTALL_RPATH. This takes
4340 precedence over SKIP_BUILD_RPATH and avoids the need for relink‐
4341 ing before installation. INSTALL_NAME_DIR is a string specify‐
4342 ing the directory portion of the "install_name" field of shared
4343 libraries on Mac OSX to use in the installed targets. When the
4344 target is created the values of the variables
4345 CMAKE_INSTALL_RPATH, CMAKE_INSTALL_RPATH_USE_LINK_PATH,
4346 CMAKE_SKIP_BUILD_RPATH, CMAKE_BUILD_WITH_INSTALL_RPATH, and
4347 CMAKE_INSTALL_NAME_DIR are used to initialize these properties.
4348 PROJECT_LABEL can be used to change the name of the target in an
4351 IDE like visual studio. VS_KEYWORD can be set to change the
4352 visual studio keyword, for example Qt integration works better
4353 if this is set to Qt4VSv1.0.
4354 VS_SCC_PROJECTNAME, VS_SCC_LOCALPATH, VS_SCC_PROVIDER and
4357 VS_SCC_AUXPATH can be set to add support for source control
4358 bindings in a Visual Studio project file.
4359 VS_GLOBAL_<variable> can be set to add a Visual Studio
4362 project-specific global variable. Qt integration works better if
4363 VS_GLOBAL_QtVersion is set to the Qt version FindQt4.cmake
4364 found. For example, "4.7.3"
4365 The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are
4368 the old way to specify CMake scripts to run before and after
4369 installing a target. They are used only when the old
4370 INSTALL_TARGETS command is used to install the target. Use the
4371 INSTALL command instead.
4372 The EXCLUDE_FROM_DEFAULT_BUILD property is used by the visual
4375 studio generators. If it is set to 1 the target will not be
4376 part of the default build when you select "Build Solution". This
4377 can also be set on a per-configuration basis using
4378 EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>.
4379 set_tests_properties
4382 Set a property of the tests.
4383 set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
4385 Set a property for the tests. If the property is not found,
4387 CMake will report an error. The properties include:
4388 WILL_FAIL: If set to true, this will invert the pass/fail flag
4391 of the test.
4392 PASS_REGULAR_EXPRESSION: If set, the test output will be checked
4395 against the specified regular expressions and at least one of
4396 the regular expressions has to match, otherwise the test will
4397 fail.
4398 Example: PASS_REGULAR_EXPRESSION "TestPassed;All ok"
4401 FAIL_REGULAR_EXPRESSION: If set, if the output will match to one
4403 of specified regular expressions, the test will fail.
4404 Example: PASS_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed"
4407 Both PASS_REGULAR_EXPRESSION and FAIL_REGULAR_EXPRESSION expect
4409 a list of regular expressions.
4410 TIMEOUT: Setting this will limit the test runtime to the number
4413 of seconds specified.
4414 site_name
4418 Set the given variable to the name of the computer.
4419 site_name(variable)
4421 source_group
4424 Define a grouping for sources in the makefile.
4425 source_group(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])
4427 Defines a group into which sources will be placed in project
4429 files. This is mainly used to setup file tabs in Visual Studio.
4430 Any file whose name is listed or matches the regular expression
4431 will be placed in this group. If a file matches multiple
4432 groups, the LAST group that explicitly lists the file will be
4433 favored, if any. If no group explicitly lists the file, the
4434 LAST group whose regular expression matches the file will be
4435 favored.
4436 The name of the group may contain backslashes to specify sub‐
4439 groups:
4440 source_group(outer\\inner ...)
4443 For backwards compatibility, this command also supports the for‐
4445 mat:
4446 source_group(name regex)
4449 string String operations.
4452 string(REGEX MATCH <regular_expression>
4454 <output variable> <input> [<input>...])
4455 string(REGEX MATCHALL <regular_expression>
4456 <output variable> <input> [<input>...])
4457 string(REGEX REPLACE <regular_expression>
4458 <replace_expression> <output variable>
4459 <input> [<input>...])
4460 string(REPLACE <match_string>
4461 <replace_string> <output variable>
4462 <input> [<input>...])
4463 string(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512>
4464 <output variable> <input>)
4465 string(COMPARE EQUAL <string1> <string2> <output variable>)
4466 string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
4467 string(COMPARE LESS <string1> <string2> <output variable>)
4468 string(COMPARE GREATER <string1> <string2> <output variable>)
4469 string(ASCII <number> [<number> ...] <output variable>)
4470 string(CONFIGURE <string1> <output variable>
4471 [@ONLY] [ESCAPE_QUOTES])
4472 string(TOUPPER <string1> <output variable>)
4473 string(TOLOWER <string1> <output variable>)
4474 string(LENGTH <string> <output variable>)
4475 string(SUBSTRING <string> <begin> <length> <output variable>)
4476 string(STRIP <string> <output variable>)
4477 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
4478 [RANDOM_SEED <seed>] <output variable>)
4479 string(FIND <string> <substring> <output variable> [REVERSE])
4480 string(TIMESTAMP <output variable> [<format string>] [UTC])
4481 string(MAKE_C_IDENTIFIER <input string> <output variable>)
4482 REGEX MATCH will match the regular expression once and store the
4484 match in the output variable.
4485 REGEX MATCHALL will match the regular expression as many times
4488 as possible and store the matches in the output variable as a
4489 list.
4490 REGEX REPLACE will match the regular expression as many times as
4493 possible and substitute the replacement expression for the match
4494 in the output. The replace expression may refer to paren-delim‐
4495 ited subexpressions of the match using \1, \2, ..., \9. Note
4496 that two backslashes (\\1) are required in CMake code to get a
4497 backslash through argument parsing.
4498 REPLACE will replace all occurrences of match_string in the
4501 input with replace_string and store the result in the output.
4502 MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a
4505 cryptographic hash of the input string.
4506 COMPARE EQUAL/NOTEQUAL/LESS/GREATER will compare the strings and
4509 store true or false in the output variable.
4510 ASCII will convert all numbers into corresponding ASCII charac‐
4513 ters.
4514 CONFIGURE will transform a string like CONFIGURE_FILE transforms
4517 a file.
4518 TOUPPER/TOLOWER will convert string to upper/lower characters.
4521 LENGTH will return a given string's length.
4524 SUBSTRING will return a substring of a given string. If length
4527 is -1 the remainder of the string starting at begin will be
4528 returned.
4529 STRIP will return a substring of a given string with leading and
4532 trailing spaces removed.
4533 RANDOM will return a random string of given length consisting of
4536 characters from the given alphabet. Default length is 5 charac‐
4537 ters and default alphabet is all numbers and upper and lower
4538 case letters. If an integer RANDOM_SEED is given, its value
4539 will be used to seed the random number generator.
4540 FIND will return the position where the given substring was
4543 found in the supplied string. If the REVERSE flag was used, the
4544 command will search for the position of the last occurrence of
4545 the specified substring.
4546 The following characters have special meaning in regular expres‐
4549 sions:
4550 ^ Matches at beginning of input
4553 $ Matches at end of input
4554 . Matches any single character
4555 [ ] Matches any character(s) inside the brackets
4556 [^ ] Matches any character(s) not inside the brackets
4557 - Inside brackets, specifies an inclusive range between
4558 characters on either side e.g. [a-f] is [abcdef]
4559 To match a literal - using brackets, make it the first
4560 or the last character e.g. [+*/-] matches basic
4561 mathematical operators.
4562 * Matches preceding pattern zero or more times
4563 + Matches preceding pattern one or more times
4564 ? Matches preceding pattern zero or once only
4565 | Matches a pattern on either side of the |
4566 () Saves a matched subexpression, which can be referenced
4567 in the REGEX REPLACE operation. Additionally it is saved
4568 by all regular expression-related commands, including
4569 e.g. if( MATCHES ), in the variables CMAKE_MATCH_(0..9).
4570 *, + and ? have higher precedence than concatenation. | has
4572 lower precedence than concatenation. This means that the regular
4573 expression "^ab+d$" matches "abbd" but not "ababd", and the reg‐
4574 ular expression "^(ab|cd)$" matches "ab" but not "abd".
4575 TIMESTAMP will write a string representation of the current date
4578 and/or time to the output variable.
4579 Should the command be unable to obtain a timestamp the output
4582 variable will be set to the empty string "".
4583 The optional UTC flag requests the current date/time representa‐
4586 tion to be in Coordinated Universal Time (UTC) rather than local
4587 time.
4588 The optional <format string> may contain the following format
4591 specifiers:
4592 %d The day of the current month (01-31).
4595 %H The hour on a 24-hour clock (00-23).
4596 %I The hour on a 12-hour clock (01-12).
4597 %j The day of the current year (001-366).
4598 %m The month of the current year (01-12).
4599 %M The minute of the current hour (00-59).
4600 %S The second of the current minute.
4601 60 represents a leap second. (00-60)
4602 %U The week number of the current year (00-53).
4603 %w The day of the current week. 0 is Sunday. (0-6)
4604 %y The last two digits of the current year (00-99)
4605 %Y The current year.
4606 Unknown format specifiers will be ignored and copied to the out‐
4608 put as-is.
4609 If no explicit <format string> is given it will default to:
4612 %Y-%m-%dT%H:%M:%S for local time.
4615 %Y-%m-%dT%H:%M:%SZ for UTC.
4616 MAKE_C_IDENTIFIER will write a string which can be used as an
4618 identifier in C.
4619 target_compile_definitions
4622 Add compile definitions to a target.
4623 target_compile_definitions(<target> <INTERFACE|PUBLIC|PRIVATE> [items1...]
4625 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4626 Specify compile definitions to use when compiling a given tar‐
4628 get. The named <target> must have been created by a command
4629 such as add_executable or add_library and must not be an
4630 IMPORTED target. The INTERFACE, PUBLIC and PRIVATE keywords are
4631 required to specify the scope of the following arguments. PRI‐
4632 VATE and PUBLIC items will populate the COMPILE_DEFINITIONS
4633 property of <target>. PUBLIC and INTERFACE items will populate
4634 the INTERFACE_COMPILE_DEFINITIONS property of <target>. The
4635 following arguments specify compile definitions. Repeated calls
4636 for the same <target> append items in the order called.
4637 Arguments to target_compile_definitions may use "generator
4640 expressions" with the syntax "$<...>". Generator expressions
4641 are evaluated during build system generation to produce informa‐
4642 tion specific to each build configuration. Valid expressions
4643 are:
4644 $<0:...> = empty string (ignores "...")
4647 $<1:...> = content of "..."
4648 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
4649 $<CONFIGURATION> = configuration name
4650 $<BOOL:...> = '1' if the '...' is true, else '0'
4651 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
4652 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
4653 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
4654 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
4655 $<JOIN:list,...> = joins the list with the content of "..."
4656 $<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.
4657 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4658 $<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.
4659 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
4660 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4661 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
4662 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4663 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
4664 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
4665 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
4666 $<C_COMPILER_VERSION> = The version of the C compiler used.
4667 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
4668 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
4669 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
4670 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
4671 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
4672 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
4673 where "tgt" is the name of a target. Target file expressions
4675 produce a full path, but _DIR and _NAME versions can produce the
4676 directory and file name components:
4677 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
4680 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
4681 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
4682 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
4687 Note that tgt is not added as a dependency of the target this
4689 expression is evaluated on.
4690 $<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.
4693 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
4694 Boolean expressions:
4696 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
4699 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
4700 $<NOT:?> = '0' if '?' is '1', else '1'
4701 where '?' is always either '0' or '1'.
4703 Expressions with an implicit 'this' target:
4706 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
4709 target_compile_options
4712 Add compile options to a target.
4713 target_compile_options(<target> [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...]
4715 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4716 Specify compile options to use when compiling a given target.
4718 The named <target> must have been created by a command such as
4719 add_executable or add_library and must not be an IMPORTED tar‐
4720 get. If BEFORE is specified, the content will be prepended to
4721 the property instead of being appended.
4722 The INTERFACE, PUBLIC and PRIVATE keywords are required to spec‐
4725 ify the scope of the following arguments. PRIVATE and PUBLIC
4726 items will populate the COMPILE_OPTIONS property of <target>.
4727 PUBLIC and INTERFACE items will populate the INTERFACE_COM‐
4728 PILE_OPTIONS property of <target>. The following arguments
4729 specify compile opitions. Repeated calls for the same <target>
4730 append items in the order called.
4731 Arguments to target_compile_options may use "generator expres‐
4734 sions" with the syntax "$<...>". Generator expressions are
4735 evaluated during build system generation to produce information
4736 specific to each build configuration. Valid expressions are:
4737 $<0:...> = empty string (ignores "...")
4740 $<1:...> = content of "..."
4741 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
4742 $<CONFIGURATION> = configuration name
4743 $<BOOL:...> = '1' if the '...' is true, else '0'
4744 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
4745 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
4746 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
4747 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
4748 $<JOIN:list,...> = joins the list with the content of "..."
4749 $<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.
4750 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4751 $<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.
4752 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
4753 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4754 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
4755 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4756 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
4757 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
4758 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
4759 $<C_COMPILER_VERSION> = The version of the C compiler used.
4760 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
4761 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
4762 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
4763 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
4764 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
4765 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
4766 where "tgt" is the name of a target. Target file expressions
4768 produce a full path, but _DIR and _NAME versions can produce the
4769 directory and file name components:
4770 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
4773 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
4774 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
4775 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
4780 Note that tgt is not added as a dependency of the target this
4782 expression is evaluated on.
4783 $<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.
4786 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
4787 Boolean expressions:
4789 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
4792 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
4793 $<NOT:?> = '0' if '?' is '1', else '1'
4794 where '?' is always either '0' or '1'.
4796 Expressions with an implicit 'this' target:
4799 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
4802 target_include_directories
4805 Add include directories to a target.
4806 target_include_directories(<target> [SYSTEM] [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...]
4808 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4809 Specify include directories or targets to use when compiling a
4811 given target. The named <target> must have been created by a
4812 command such as add_executable or add_library and must not be an
4813 IMPORTED target.
4814 If BEFORE is specified, the content will be prepended to the
4817 property instead of being appended.
4818 The INTERFACE, PUBLIC and PRIVATE keywords are required to spec‐
4821 ify the scope of the following arguments. PRIVATE and PUBLIC
4822 items will populate the INCLUDE_DIRECTORIES property of <tar‐
4823 get>. PUBLIC and INTERFACE items will populate the INTER‐
4824 FACE_INCLUDE_DIRECTORIES property of <target>. The following
4825 arguments specify include directories. Specified include direc‐
4826 tories may be absolute paths or relative paths. Repeated calls
4827 for the same <target> append items in the order called.If SYSTEM
4828 is specified, the compiler will be told the directories are
4829 meant as system include directories on some platforms (sig‐
4830 nalling this setting might achieve effects such as the compiler
4831 skipping warnings, or these fixed-install system files not being
4832 considered in dependency calculations - see compiler docs). If
4833 SYSTEM is used together with PUBLIC or INTERFACE, the INTER‐
4834 FACE_SYSTEM_INCLUDE_DIRECTORIES target property will be popu‐
4835 lated with the specified directories.
4836 Arguments to target_include_directories may use "generator
4839 expressions" with the syntax "$<...>". Generator expressions
4840 are evaluated during build system generation to produce informa‐
4841 tion specific to each build configuration. Valid expressions
4842 are:
4843 $<0:...> = empty string (ignores "...")
4846 $<1:...> = content of "..."
4847 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
4848 $<CONFIGURATION> = configuration name
4849 $<BOOL:...> = '1' if the '...' is true, else '0'
4850 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
4851 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
4852 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
4853 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
4854 $<JOIN:list,...> = joins the list with the content of "..."
4855 $<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.
4856 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4857 $<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.
4858 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
4859 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4860 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
4861 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4862 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
4863 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
4864 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
4865 $<C_COMPILER_VERSION> = The version of the C compiler used.
4866 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
4867 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
4868 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
4869 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
4870 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
4871 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
4872 where "tgt" is the name of a target. Target file expressions
4874 produce a full path, but _DIR and _NAME versions can produce the
4875 directory and file name components:
4876 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
4879 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
4880 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
4881 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
4886 Note that tgt is not added as a dependency of the target this
4888 expression is evaluated on.
4889 $<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.
4892 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
4893 Boolean expressions:
4895 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
4898 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
4899 $<NOT:?> = '0' if '?' is '1', else '1'
4900 where '?' is always either '0' or '1'.
4902 Expressions with an implicit 'this' target:
4905 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
4908 target_link_libraries
4911 Link a target to given libraries.
4912 target_link_libraries(<target> [item1 [item2 [...]]]
4914 [[debug|optimized|general] <item>] ...)
4915 Specify libraries or flags to use when linking a given target.
4917 The named <target> must have been created in the current direc‐
4918 tory by a command such as add_executable or add_library. The
4919 remaining arguments specify library names or flags. Repeated
4920 calls for the same <target> append items in the order called.
4921 If a library name matches that of another target in the project
4924 a dependency will automatically be added in the build system to
4925 make sure the library being linked is up-to-date before the tar‐
4926 get links. Item names starting with '-', but not '-l' or
4927 '-framework', are treated as linker flags.
4928 A "debug", "optimized", or "general" keyword indicates that the
4931 library immediately following it is to be used only for the cor‐
4932 responding build configuration. The "debug" keyword corresponds
4933 to the Debug configuration (or to configurations named in the
4934 DEBUG_CONFIGURATIONS global property if it is set). The "opti‐
4935 mized" keyword corresponds to all other configurations. The
4936 "general" keyword corresponds to all configurations, and is
4937 purely optional (assumed if omitted). Higher granularity may be
4938 achieved for per-configuration rules by creating and linking to
4939 IMPORTED library targets. See the IMPORTED mode of the
4940 add_library command for more information.
4941 Library dependencies are transitive by default with this signa‐
4944 ture. When this target is linked into another target then the
4945 libraries linked to this target will appear on the link line for
4946 the other target too. This transitive "link interface" is
4947 stored in the INTERFACE_LINK_LIBRARIES target property when pol‐
4948 icy CMP0022 is set to NEW and may be overridden by setting the
4949 property directly. (When CMP0022 is not set to NEW, transitive
4950 linking is builtin but may be overridden by the LINK_INTER‐
4951 FACE_LIBRARIES property. Calls to other signatures of this com‐
4952 mand may set the property making any libraries linked exclu‐
4953 sively by this signature private.)
4954 CMake will also propagate "usage requirements" from linked
4957 library targets. Usage requirements affect compilation of
4958 sources in the <target>. They are specified by properties
4959 defined on linked targets. During generation of the build sys‐
4960 tem, CMake integrates usage requirement property values with the
4961 corresponding build properties for <target>:
4962 INTERFACE_COMPILE_DEFINITONS: Appends to COMPILE_DEFINITONS
4965 INTERFACE_INCLUDE_DIRECTORIES: Appends to INCLUDE_DIRECTORIES
4966 INTERFACE_POSITION_INDEPENDENT_CODE: Sets POSITION_INDEPENDENT_CODE
4967 or checked for consistency with existing value
4968 If an <item> is a library in a Mac OX framework, the Headers
4973 directory of the framework will also be processed as a "usage
4974 requirement". This has the same effect as passing the framework
4975 directory as an include directory. target_link_libraries(<tar‐
4976 get>
4977 <PRIVATE|PUBLIC|INTERFACE> <lib> ...
4980 [<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...])
4981 The PUBLIC, PRIVATE and INTERFACE keywords can be used to spec‐
4983 ify both the link dependencies and the link interface in one
4984 command. Libraries and targets following PUBLIC are linked to,
4985 and are made part of the link interface. Libraries and targets
4986 following PRIVATE are linked to, but are not made part of the
4987 link interface. Libraries following INTERFACE are appended to
4988 the link interface and are not used for linking <target>.
4989 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES
4992 [[debug|optimized|general] <lib>] ...)
4993 The LINK_INTERFACE_LIBRARIES mode appends the libraries to the
4995 INTERFACE_LINK_LIBRARIES target property instead of using them
4996 for linking. If policy CMP0022 is not NEW, then this mode also
4997 appends libraries to the LINK_INTERFACE_LIBRARIES and its
4998 per-configuration equivalent. This signature is for compatibil‐
4999 ity only. Prefer the INTERFACE mode instead. Libraries speci‐
5000 fied as "debug" are wrapped in a generator expression to corre‐
5001 spond to debug builds. If policy CMP0022 is not NEW, the
5002 libraries are also appended to the LINK_INTER‐
5003 FACE_LIBRARIES_DEBUG property (or to the properties correspond‐
5004 ing to configurations listed in the DEBUG_CONFIGURATIONS global
5005 property if it is set). Libraries specified as "optimized" are
5006 appended to the INTERFACE_LINK_LIBRARIES property. If policy
5007 CMP0022 is not NEW, they are also appended to the LINK_INTER‐
5008 FACE_LIBRARIES property. Libraries specified as "general" (or
5009 without any keyword) are treated as if specified for both
5010 "debug" and "optimized".
5011 target_link_libraries(<target>
5014 <LINK_PRIVATE|LINK_PUBLIC>
5015 [[debug|optimized|general] <lib>] ...
5016 [<LINK_PRIVATE|LINK_PUBLIC>
5017 [[debug|optimized|general] <lib>] ...])
5018 The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify
5020 both the link dependencies and the link interface in one com‐
5021 mand. This signature is for compatibility only. Prefer the PUB‐
5022 LIC or PRIVATE keywords instead. Libraries and targets follow‐
5023 ing LINK_PUBLIC are linked to, and are made part of the INTER‐
5024 FACE_LINK_LIBRARIES. If policy CMP0022 is not NEW, they are
5025 also made part of the LINK_INTERFACE_LIBRARIES. Libraries and
5026 targets following LINK_PRIVATE are linked to, but are not made
5027 part of the INTERFACE_LINK_LIBRARIES (or LINK_INTER‐
5028 FACE_LIBRARIES).
5029 The library dependency graph is normally acyclic (a DAG), but in
5032 the case of mutually-dependent STATIC libraries CMake allows the
5033 graph to contain cycles (strongly connected components). When
5034 another target links to one of the libraries CMake repeats the
5035 entire connected component. For example, the code
5036 add_library(A STATIC a.c)
5039 add_library(B STATIC b.c)
5040 target_link_libraries(A B)
5041 target_link_libraries(B A)
5042 add_executable(main main.c)
5043 target_link_libraries(main A)
5044 links 'main' to 'A B A B'. (While one repetition is usually
5046 sufficient, pathological object file and symbol arrangements can
5047 require more. One may handle such cases by manually repeating
5048 the component in the last target_link_libraries call. However,
5049 if two archives are really so interdependent they should proba‐
5050 bly be combined into a single archive.)
5051 Arguments to target_link_libraries may use "generator expres‐
5054 sions" with the syntax "$<...>". Note however, that generator
5055 expressions will not be used in OLD handling of CMP0003 or
5056 CMP0004.
5057 Generator expressions are evaluated during build system genera‐
5060 tion to produce information specific to each build configura‐
5061 tion. Valid expressions are:
5062 $<0:...> = empty string (ignores "...")
5065 $<1:...> = content of "..."
5066 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
5067 $<CONFIGURATION> = configuration name
5068 $<BOOL:...> = '1' if the '...' is true, else '0'
5069 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
5070 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
5071 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
5072 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
5073 $<JOIN:list,...> = joins the list with the content of "..."
5074 $<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.
5075 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
5076 $<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.
5077 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
5078 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
5079 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
5080 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
5081 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
5082 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
5083 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
5084 $<C_COMPILER_VERSION> = The version of the C compiler used.
5085 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
5086 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
5087 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
5088 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
5089 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
5090 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
5091 where "tgt" is the name of a target. Target file expressions
5093 produce a full path, but _DIR and _NAME versions can produce the
5094 directory and file name components:
5095 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
5098 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
5099 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
5100 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
5105 Note that tgt is not added as a dependency of the target this
5107 expression is evaluated on.
5108 $<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.
5111 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
5112 Boolean expressions:
5114 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
5117 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
5118 $<NOT:?> = '0' if '?' is '1', else '1'
5119 where '?' is always either '0' or '1'.
5121 Expressions with an implicit 'this' target:
5124 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
5127 try_compile
5130 Try building some code.
5131 try_compile(RESULT_VAR <bindir> <srcdir>
5133 <projectName> [targetName] [CMAKE_FLAGS flags...]
5134 [OUTPUT_VARIABLE <var>])
5135 Try building a project. In this form, srcdir should contain a
5137 complete CMake project with a CMakeLists.txt file and all
5138 sources. The bindir and srcdir will not be deleted after this
5139 command is run. Specify targetName to build a specific target
5140 instead of the 'all' or 'ALL_BUILD' target.
5141 try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...>
5144 [CMAKE_FLAGS flags...]
5145 [COMPILE_DEFINITIONS flags...]
5146 [LINK_LIBRARIES libs...]
5147 [OUTPUT_VARIABLE <var>]
5148 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]])
5149 Try building an executable from one or more source files. In
5151 this form the user need only supply one or more source files
5152 that include a definition for 'main'. CMake will create a
5153 CMakeLists.txt file to build the source(s) as an executable.
5154 Specify COPY_FILE to get a copy of the linked executable at the
5155 given fileName and optionally COPY_FILE_ERROR to capture any
5156 error.
5157 In this version all files in bindir/CMakeFiles/CMakeTmp will be
5160 cleaned automatically. For debugging, --debug-trycompile can be
5161 passed to cmake to avoid this clean. However, multiple sequen‐
5162 tial try_compile operations reuse this single output directory.
5163 If you use --debug-trycompile, you can only debug one try_com‐
5164 pile call at a time. The recommended procedure is to configure
5165 with cmake all the way through once, then delete the cache entry
5166 associated with the try_compile call of interest, and then
5167 re-run cmake again with --debug-trycompile.
5168 Some extra flags that can be included are, INCLUDE_DIRECTORIES,
5171 LINK_DIRECTORIES, and LINK_LIBRARIES. COMPILE_DEFINITIONS are
5172 -Ddefinition that will be passed to the compile line.
5173 The srcfile signature also accepts a LINK_LIBRARIES argument
5176 which may contain a list of libraries or IMPORTED targets which
5177 will be linked to in the generated project. If LINK_LIBRARIES
5178 is specified as a parameter to try_compile, then any
5179 LINK_LIBRARIES passed as CMAKE_FLAGS will be ignored.
5180 try_compile creates a CMakeList.txt file on the fly that looks
5183 like this:
5184 add_definitions( <expanded COMPILE_DEFINITIONS from calling cmake>)
5187 include_directories(${INCLUDE_DIRECTORIES})
5188 link_directories(${LINK_DIRECTORIES})
5189 add_executable(cmTryCompileExec sources)
5190 target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
5191 In both versions of the command, if OUTPUT_VARIABLE is speci‐
5193 fied, then the output from the build process is stored in the
5194 given variable. The success or failure of the try_compile, i.e.
5195 TRUE or FALSE respectively, is returned in RESULT_VAR.
5196 CMAKE_FLAGS can be used to pass -DVAR:TYPE=VALUE flags to the
5197 cmake that is run during the build. Set variable CMAKE_TRY_COM‐
5198 PILE_CONFIGURATION to choose a build configuration.
5199 try_run
5202 Try compiling and then running some code.
5203 try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR
5205 bindir srcfile [CMAKE_FLAGS <Flags>]
5206 [COMPILE_DEFINITIONS <flags>]
5207 [COMPILE_OUTPUT_VARIABLE comp]
5208 [RUN_OUTPUT_VARIABLE run]
5209 [OUTPUT_VARIABLE var]
5210 [ARGS <arg1> <arg2>...])
5211 Try compiling a srcfile. Return TRUE or FALSE for success or
5213 failure in COMPILE_RESULT_VAR. Then if the compile succeeded,
5214 run the executable and return its exit code in RUN_RESULT_VAR.
5215 If the executable was built, but failed to run, then
5216 RUN_RESULT_VAR will be set to FAILED_TO_RUN. COMPILE_OUT‐
5217 PUT_VARIABLE specifies the variable where the output from the
5218 compile step goes. RUN_OUTPUT_VARIABLE specifies the variable
5219 where the output from the running executable goes.
5220 For compatibility reasons OUTPUT_VARIABLE is still supported,
5223 which gives you the output from the compile and run step com‐
5224 bined.
5225 Cross compiling issues
5228 When cross compiling, the executable compiled in the first step
5231 usually cannot be run on the build host. try_run() checks the
5232 CMAKE_CROSSCOMPILING variable to detect whether CMake is in
5233 crosscompiling mode. If that's the case, it will still try to
5234 compile the executable, but it will not try to run the exe‐
5235 cutable. Instead it will create cache variables which must be
5236 filled by the user or by presetting them in some CMake script
5237 file to the values the executable would have produced if it had
5238 been run on its actual target platform. These variables are
5239 RUN_RESULT_VAR (explanation see above) and if RUN_OUTPUT_VARI‐
5240 ABLE (or OUTPUT_VARIABLE) was used, an additional cache variable
5241 RUN_RESULT_VAR__COMPILE_RESULT_VAR__TRYRUN_OUTPUT.This is
5242 intended to hold stdout and stderr from the executable.
5243 In order to make cross compiling your project easier, use
5246 try_run only if really required. If you use try_run, use
5247 RUN_OUTPUT_VARIABLE (or OUTPUT_VARIABLE) only if really
5248 required. Using them will require that when crosscompiling, the
5249 cache variables will have to be set manually to the output of
5250 the executable. You can also "guard" the calls to try_run with
5251 if(CMAKE_CROSSCOMPILING) and provide an easy-to-preset alterna‐
5252 tive for this case.
5253 Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build
5256 configuration.
5257 unset Unset a variable, cache variable, or environment variable.
5260 unset(<variable> [CACHE])
5262 Removes the specified variable causing it to become undefined.
5264 If CACHE is present then the variable is removed from the cache
5265 instead of the current scope.
5266 <variable> can be an environment variable such as:
5269 unset(ENV{LD_LIBRARY_PATH})
5272 in which case the variable will be removed from the current
5274 environment.
5275 variable_watch
5278 Watch the CMake variable for change.
5279 variable_watch(<variable name> [<command to execute>])
5281 If the specified variable changes, the message will be printed
5283 about the variable being changed. If the command is specified,
5284 the command will be executed. The command will receive the fol‐
5285 lowing arguments: COMMAND(<variable> <access> <value> <current
5286 list file> <stack>)
5287 while Evaluate a group of commands while a condition is true
5290 while(condition)
5292 COMMAND1(ARGS ...)
5293 COMMAND2(ARGS ...)
5294 ...
5295 endwhile(condition)
5296 All commands between while and the matching endwhile are
5298 recorded without being invoked. Once the endwhile is evaluated,
5299 the recorded list of commands is invoked as long as the condi‐
5300 tion is true. The condition is evaluated using the same logic as
5301 the if command.
5302
5305 build_name
5306 Deprecated. Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER}
5307 instead.
5308 build_name(variable)
5310 Sets the specified variable to a string representing the plat‐
5312 form and compiler settings. These values are now available
5313 through the CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
5314 exec_program
5317 Deprecated. Use the execute_process() command instead.
5318 Run an executable program during the processing of the CMake‐
5320 List.txt file.
5321 exec_program(Executable [directory in which to run]
5324 [ARGS <arguments to executable>]
5325 [OUTPUT_VARIABLE <var>]
5326 [RETURN_VALUE <var>])
5327 The executable is run in the optionally specified directory.
5329 The executable can include arguments if it is double quoted, but
5330 it is better to use the optional ARGS argument to specify argu‐
5331 ments to the program. This is because cmake will then be able
5332 to escape spaces in the executable path. An optional argument
5333 OUTPUT_VARIABLE specifies a variable in which to store the out‐
5334 put. To capture the return value of the execution, provide a
5335 RETURN_VALUE. If OUTPUT_VARIABLE is specified, then no output
5336 will go to the stdout/stderr of the console running cmake.
5337 export_library_dependencies
5341 Deprecated. Use INSTALL(EXPORT) or EXPORT command.
5342 This command generates an old-style library dependencies file.
5344 Projects requiring CMake 2.6 or later should not use the com‐
5345 mand. Use instead the install(EXPORT) command to help export
5346 targets from an installation tree and the export() command to
5347 export targets from a build tree.
5348 The old-style library dependencies file does not take into
5351 account per-configuration names of libraries or the LINK_INTER‐
5352 FACE_LIBRARIES target property.
5353 export_library_dependencies(<file> [APPEND])
5356 Create a file named <file> that can be included into a CMake
5358 listfile with the INCLUDE command. The file will contain a num‐
5359 ber of SET commands that will set all the variables needed for
5360 library dependency information. This should be the last command
5361 in the top level CMakeLists.txt file of the project. If the
5362 APPEND option is specified, the SET commands will be appended to
5363 the given file instead of replacing it.
5364 install_files
5367 Deprecated. Use the install(FILES ) command instead.
5368 This command has been superceded by the install command. It is
5370 provided for compatibility with older CMake code. The FILES
5371 form is directly replaced by the FILES form of the install com‐
5372 mand. The regexp form can be expressed more clearly using the
5373 GLOB form of the file command.
5374 install_files(<dir> extension file file ...)
5377 Create rules to install the listed files with the given exten‐
5379 sion into the given directory. Only files existing in the cur‐
5380 rent source tree or its corresponding location in the binary
5381 tree may be listed. If a file specified already has an exten‐
5382 sion, that extension will be removed first. This is useful for
5383 providing lists of source files such as foo.cxx when you want
5384 the corresponding foo.h to be installed. A typical extension is
5385 '.h'.
5386 install_files(<dir> regexp)
5389 Any files in the current source directory that match the regular
5391 expression will be installed.
5392 install_files(<dir> FILES file file ...)
5395 Any files listed after the FILES keyword will be installed
5397 explicitly from the names given. Full paths are allowed in this
5398 form.
5399 The directory <dir> is relative to the installation prefix,
5402 which is stored in the variable CMAKE_INSTALL_PREFIX.
5403 install_programs
5406 Deprecated. Use the install(PROGRAMS ) command instead.
5407 This command has been superceded by the install command. It is
5409 provided for compatibility with older CMake code. The FILES
5410 form is directly replaced by the PROGRAMS form of the INSTALL
5411 command. The regexp form can be expressed more clearly using
5412 the GLOB form of the FILE command.
5413 install_programs(<dir> file1 file2 [file3 ...])
5416 install_programs(<dir> FILES file1 [file2 ...])
5417 Create rules to install the listed programs into the given
5419 directory. Use the FILES argument to guarantee that the file
5420 list version of the command will be used even when there is only
5421 one argument.
5422 install_programs(<dir> regexp)
5425 In the second form any program in the current source directory
5427 that matches the regular expression will be installed.
5428 This command is intended to install programs that are not built
5431 by cmake, such as shell scripts. See the TARGETS form of the
5432 INSTALL command to create installation rules for targets built
5433 by cmake.
5434 The directory <dir> is relative to the installation prefix,
5437 which is stored in the variable CMAKE_INSTALL_PREFIX.
5438 install_targets
5441 Deprecated. Use the install(TARGETS ) command instead.
5442 This command has been superceded by the install command. It is
5444 provided for compatibility with older CMake code.
5445 install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
5448 Create rules to install the listed targets into the given direc‐
5450 tory. The directory <dir> is relative to the installation pre‐
5451 fix, which is stored in the variable CMAKE_INSTALL_PREFIX. If
5452 RUNTIME_DIRECTORY is specified, then on systems with special
5453 runtime files (Windows DLL), the files will be copied to that
5454 directory.
5455 link_libraries
5458 Deprecated. Use the target_link_libraries() command instead.
5459 Link libraries to all targets added later.
5461 link_libraries(library1 <debug | optimized> library2 ...)
5464 Specify a list of libraries to be linked into any following tar‐
5466 gets (typically added with the add_executable or add_library
5467 calls). This command is passed down to all subdirectories. The
5468 debug and optimized strings may be used to indicate that the
5469 next library listed is to be used only for that specific type of
5470 build.
5471 make_directory
5474 Deprecated. Use the file(MAKE_DIRECTORY ) command instead.
5475 make_directory(directory)
5477 Creates the specified directory. Full paths should be given.
5479 Any parent directories that do not exist will also be created.
5480 Use with care.
5481 output_required_files
5484 Deprecated. Approximate C preprocessor dependency scanning.
5485 This command exists only because ancient CMake versions provided
5487 it. CMake handles preprocessor dependency scanning automati‐
5488 cally using a more advanced scanner.
5489 output_required_files(srcfile outputfile)
5492 Outputs a list of all the source files that are required by the
5494 specified srcfile. This list is written into outputfile. This is
5495 similar to writing out the dependencies for srcfile except that
5496 it jumps from .h files into .cxx, .c and .cpp files if possible.
5497 remove Deprecated. Use the list(REMOVE_ITEM ) command instead.
5500 remove(VAR VALUE VALUE ...)
5502 Removes VALUE from the variable VAR. This is typically used to
5504 remove entries from a vector (e.g. semicolon separated list).
5505 VALUE is expanded.
5506 subdir_depends
5509 Deprecated. Does nothing.
5510 subdir_depends(subdir dep1 dep2 ...)
5512 Does not do anything. This command used to help projects order
5514 parallel builds correctly. This functionality is now automatic.
5515 subdirs
5518 Deprecated. Use the add_subdirectory() command instead.
5519 Add a list of subdirectories to the build.
5521 subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
5524 [PREORDER] )
5525 Add a list of subdirectories to the build. The add_subdirectory
5527 command should be used instead of subdirs although subdirs will
5528 still work. This will cause any CMakeLists.txt files in the sub
5529 directories to be processed by CMake. Any directories after the
5530 PREORDER flag are traversed first by makefile builds, the PRE‐
5531 ORDER flag has no effect on IDE projects. Any directories after
5532 the EXCLUDE_FROM_ALL marker will not be included in the top
5533 level makefile or project file. This is useful for having CMake
5534 create makefiles or projects for a set of examples in a project.
5535 You would want CMake to generate makefiles or project files for
5536 all the examples at the same time, but you would not want them
5537 to show up in the top level project or be built each time make
5538 is run from the top.
5539 use_mangled_mesa
5542 Copy mesa headers for use in combination with system GL.
5543 use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
5545 The path to mesa includes, should contain gl_mangle.h. The mesa
5547 headers are copied to the specified output directory. This
5548 allows mangled mesa headers to override other GL headers by
5549 being added to the include directory path earlier.
5550 utility_source
5553 Specify the source tree of a third-party utility.
5554 utility_source(cache_entry executable_name
5556 path_to_source [file1 file2 ...])
5557 When a third-party utility's source is included in the distribu‐
5559 tion, this command specifies its location and name. The cache
5560 entry will not be set unless the path_to_source and all listed
5561 files exist. It is assumed that the source tree of the utility
5562 will have been built before it is needed.
5563 When cross compiling CMake will print a warning if a util‐
5566 ity_source() command is executed, because in many cases it is
5567 used to build an executable which is executed later on. This
5568 doesn't work when cross compiling, since the executable can run
5569 only on their target platform. So in this case the cache entry
5570 has to be adjusted manually so it points to an executable which
5571 is runnable on the build host.
5572 variable_requires
5575 Deprecated. Use the if() command instead.
5576 Assert satisfaction of an option's required variables.
5578 variable_requires(TEST_VARIABLE RESULT_VARIABLE
5581 REQUIRED_VARIABLE1
5582 REQUIRED_VARIABLE2 ...)
5583 The first argument (TEST_VARIABLE) is the name of the variable
5585 to be tested, if that variable is false nothing else is done. If
5586 TEST_VARIABLE is true, then the next argument (RESULT_VARIABLE)
5587 is a variable that is set to true if all the required variables
5588 are set. The rest of the arguments are variables that must be
5589 true or not set to NOTFOUND to avoid an error. If any are not
5590 true, an error is reported.
5591 write_file
5594 Deprecated. Use the file(WRITE ) command instead.
5595 write_file(filename "message to write"... [APPEND])
5597 The first argument is the file name, the rest of the arguments
5599 are messages to write. If the argument APPEND is specified, then
5600 the message will be appended.
5601 NOTE 1: file(WRITE ... and file(APPEND ... do exactly the same
5604 as this one but add some more functionality.
5605 NOTE 2: When using write_file the produced file cannot be used
5608 as an input to CMake (CONFIGURE_FILE, source file ...) because
5609 it will lead to an infinite loop. Use configure_file if you want
5610 to generate input files to CMake.
5611
5615 Copyright 2000-2012 Kitware, Inc., Insight Software Consortium. All
5616 rights reserved.
5617 Redistribution and use in source and binary forms, with or without mod‐
5620 ification, are permitted provided that the following conditions are
5621 met:
5622 Redistributions of source code must retain the above copyright notice,
5625 this list of conditions and the following disclaimer.
5626 Redistributions in binary form must reproduce the above copyright
5629 notice, this list of conditions and the following disclaimer in the
5630 documentation and/or other materials provided with the distribution.
5631 Neither the names of Kitware, Inc., the Insight Software Consortium,
5634 nor the names of their contributors may be used to endorse or promote
5635 products derived from this software without specific prior written per‐
5636 mission.
5637 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
5640 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
5641 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
5642 ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
5643 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
5644 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
5645 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
5646 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
5647 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
5648 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
5649 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
5650
5653 cmake(1), ctest(1)
5654 The following resources are available to get help using CMake:
5657 Home Page
5660 http://www.cmake.org
5661 The primary starting point for learning about CMake.
5663 Frequently Asked Questions
5666 http://www.cmake.org/Wiki/CMake_FAQ
5667 A Wiki is provided containing answers to frequently asked ques‐
5669 tions.
5670 Online Documentation
5673 http://www.cmake.org/HTML/Documentation.html
5674 Links to available documentation may be found on this web page.
5676 Mailing List
5679 http://www.cmake.org/HTML/MailingLists.html
5680 For help and discussion about using cmake, a mailing list is
5682 provided at cmake@cmake.org. The list is member-post-only but
5683 one may sign up on the CMake web page. Please first read the
5684 full documentation at http://www.cmake.org before posting ques‐
5685 tions to the list.
5686
5689 This manual page was generated by the "--help-man" option.
5690ccmake 2.8.12.2 October 15, 2014 ccmake(1)