1cmake(1) General Commands Manual cmake(1)
2
6 cmake - Cross-Platform Makefile Generator.
7
10 cmake [options] <path-to-source>
11 cmake [options] <path-to-existing-build>
12
15 The "cmake" executable is the CMake command-line interface. It may be
16 used to configure projects in scripts. Project configuration settings
17 may be specified on the command line with the -D option. The -i option
18 will cause cmake to interactively prompt for such settings.
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 -E CMake command mode.
101 For true platform independence, CMake provides a list of com‐
103 mands that can be used on all systems. Run with -E help for the
104 usage information. Commands available are: chdir, compare_files,
105 copy, copy_directory, copy_if_different, echo, echo_append,
106 environment, make_directory, md5sum, remove, remove_directory,
107 rename, tar, time, touch, touch_nocreate. In addition, some
108 platform specific commands are available. On Windows: comspec,
109 delete_regv, write_regv. On UNIX: create_symlink.
110 -i Run in wizard mode.
113 Wizard mode runs cmake interactively without a GUI. The user is
115 prompted to answer questions about the project configuration.
116 The answers are used to set cmake cache values.
117 -L[A][H]
120 List non-advanced cached variables.
121 List cache variables will run CMake and list all the variables
123 from the CMake cache that are not marked as INTERNAL or
124 ADVANCED. This will effectively display current CMake settings,
125 which can then be changed with -D option. Changing some of the
126 variables may result in more variables being created. If A is
127 specified, then it will display also advanced variables. If H is
128 specified, it will also display help for each variable.
129 --build <dir>
132 Build a CMake-generated project binary tree.
133 This abstracts a native build tool's command-line interface with
135 the following options:
136 <dir> = Project binary directory to be built.
139 --target <tgt> = Build <tgt> instead of default targets.
140 --config <cfg> = For multi-configuration tools, choose <cfg>.
141 --clean-first = Build target 'clean' first, then build.
142 (To clean only, use --target 'clean'.)
143 --use-stderr = Don't merge stdout/stderr output and pass the
144 original stdout/stderr handles to the native
145 tool so it can use the capabilities of the
146 calling terminal (e.g. colored output).
147 -- = Pass remaining options to the native tool.
148 Run cmake --build with no options for quick help.
150 -N View mode only.
153 Only load the cache. Do not actually run configure and generate
155 steps.
156 -P <file>
159 Process script mode.
160 Process the given cmake file as a script written in the CMake
162 language. No configure or generate step is performed and the
163 cache is not modified. If variables are defined using -D, this
164 must be done before the -P argument.
165 --find-package
168 Run in pkg-config like mode.
169 Search a package using find_package() and print the resulting
171 flags to stdout. This can be used to use cmake instead of
172 pkg-config to find installed libraries in plain Makefile-based
173 projects or in autoconf-based projects (via share/aclo‐
174 cal/cmake.m4).
175 --graphviz=[file]
178 Generate graphviz of dependencies, see CMakeGraphVizOp‐
179 tions.cmake for more.
180 Generate a graphviz input file that will contain all the library
182 and executable dependencies in the project. See the documenta‐
183 tion for CMakeGraphVizOptions.cmake for more details.
184 --system-information [file]
187 Dump information about this system.
188 Dump a wide range of information about the current system. If
190 run from the top of a binary tree for a CMake project it will
191 dump additional information such as the cache, log files etc.
192 --debug-trycompile
195 Do not delete the try_compile build tree. Only useful on one
196 try_compile at a time.
197 Do not delete the files and directories created for try_compile
199 calls. This is useful in debugging failed try_compiles. It may
200 however change the results of the try-compiles as old junk from
201 a previous try-compile may cause a different test to either pass
202 or fail incorrectly. This option is best used for one try-com‐
203 pile at a time, and only when debugging.
204 --debug-output
207 Put cmake in a debug mode.
208 Print extra stuff during the cmake run like stack traces with
210 message(send_error ) calls.
211 --trace
214 Put cmake in trace mode.
215 Print a trace of all calls made and from where with mes‐
217 sage(send_error ) calls.
218 --warn-uninitialized
221 Warn about uninitialized values.
222 Print a warning when an uninitialized variable is used.
224 --warn-unused-vars
227 Warn about unused variables.
228 Find variables that are declared or set, but not used.
230 --no-warn-unused-cli
233 Don't warn about command line options.
234 Don't find variables that are declared on the command line, but
236 not used.
237 --check-system-vars
240 Find problems with variable usage in system files.
241 Normally, unused and uninitialized variables are searched for
243 only in CMAKE_SOURCE_DIR and CMAKE_BINARY_DIR. This flag tells
244 CMake to warn about other files as well.
245 --help-command cmd [file]
248 Print help for a single command and exit.
249 Full documentation specific to the given command is displayed.
251 If a file is specified, the documentation is written into and
252 the output format is determined depending on the filename suf‐
253 fix. Supported are man page, HTML, DocBook and plain text.
254 --help-command-list [file]
257 List available listfile commands and exit.
258 The list contains all commands for which help may be obtained by
260 using the --help-command argument followed by a command name. If
261 a file is specified, the documentation is written into and the
262 output format is determined depending on the filename suffix.
263 Supported are man page, HTML, DocBook and plain text.
264 --help-commands [file]
267 Print help for all commands and exit.
268 Full documentation specific for all current commands is dis‐
270 played.If a file is specified, the documentation is written into
271 and the output format is determined depending on the filename
272 suffix. Supported are man page, HTML, DocBook and plain text.
273 --help-compatcommands [file]
276 Print help for compatibility commands.
277 Full documentation specific for all compatibility commands is
279 displayed.If a file is specified, the documentation is written
280 into and the output format is determined depending on the file‐
281 name suffix. Supported are man page, HTML, DocBook and plain
282 text.
283 --help-module module [file]
286 Print help for a single module and exit.
287 Full documentation specific to the given module is displayed.If
289 a file is specified, the documentation is written into and the
290 output format is determined depending on the filename suffix.
291 Supported are man page, HTML, DocBook and plain text.
292 --help-module-list [file]
295 List available modules and exit.
296 The list contains all modules for which help may be obtained by
298 using the --help-module argument followed by a module name. If a
299 file is specified, the documentation is written into and the
300 output format is determined depending on the filename suffix.
301 Supported are man page, HTML, DocBook and plain text.
302 --help-modules [file]
305 Print help for all modules and exit.
306 Full documentation for all modules is displayed. If a file is
308 specified, the documentation is written into and the output for‐
309 mat is determined depending on the filename suffix. Supported
310 are man page, HTML, DocBook and plain text.
311 --help-custom-modules [file]
314 Print help for all custom modules and exit.
315 Full documentation for all custom modules is displayed. If a
317 file is specified, the documentation is written into and the
318 output format is determined depending on the filename suffix.
319 Supported are man page, HTML, DocBook and plain text.
320 --help-policy cmp [file]
323 Print help for a single policy and exit.
324 Full documentation specific to the given policy is displayed.If
326 a file is specified, the documentation is written into and the
327 output format is determined depending on the filename suffix.
328 Supported are man page, HTML, DocBook and plain text.
329 --help-policies [file]
332 Print help for all policies and exit.
333 Full documentation for all policies is displayed.If a file is
335 specified, the documentation is written into and the output for‐
336 mat is determined depending on the filename suffix. Supported
337 are man page, HTML, DocBook and plain text.
338 --help-property prop [file]
341 Print help for a single property and exit.
342 Full documentation specific to the given property is dis‐
344 played.If a file is specified, the documentation is written into
345 and the output format is determined depending on the filename
346 suffix. Supported are man page, HTML, DocBook and plain text.
347 --help-property-list [file]
350 List available properties and exit.
351 The list contains all properties for which help may be obtained
353 by using the --help-property argument followed by a property
354 name. If a file is specified, the help is written into it.If a
355 file is specified, the documentation is written into and the
356 output format is determined depending on the filename suffix.
357 Supported are man page, HTML, DocBook and plain text.
358 --help-properties [file]
361 Print help for all properties and exit.
362 Full documentation for all properties is displayed.If a file is
364 specified, the documentation is written into and the output for‐
365 mat is determined depending on the filename suffix. Supported
366 are man page, HTML, DocBook and plain text.
367 --help-variable var [file]
370 Print help for a single variable and exit.
371 Full documentation specific to the given variable is dis‐
373 played.If a file is specified, the documentation is written into
374 and the output format is determined depending on the filename
375 suffix. Supported are man page, HTML, DocBook and plain text.
376 --help-variable-list [file]
379 List documented variables and exit.
380 The list contains all variables for which help may be obtained
382 by using the --help-variable argument followed by a variable
383 name. If a file is specified, the help is written into it.If a
384 file is specified, the documentation is written into and the
385 output format is determined depending on the filename suffix.
386 Supported are man page, HTML, DocBook and plain text.
387 --help-variables [file]
390 Print help for all variables and exit.
391 Full documentation for all variables is displayed.If a file is
393 specified, the documentation is written into and the output for‐
394 mat is determined depending on the filename suffix. Supported
395 are man page, HTML, DocBook and plain text.
396 --copyright [file]
399 Print the CMake copyright and exit.
400 If a file is specified, the copyright is written into it.
402 --help,-help,-usage,-h,-H,/?
405 Print usage information and exit.
406 Usage describes the basic command line interface and its
408 options.
409 --help-full [file]
412 Print full help and exit.
413 Full help displays most of the documentation provided by the
415 UNIX man page. It is provided for use on non-UNIX platforms,
416 but is also convenient if the man page is not installed. If a
417 file is specified, the help is written into it.
418 --help-html [file]
421 Print full help in HTML format.
422 This option is used by CMake authors to help produce web pages.
424 If a file is specified, the help is written into it.
425 --help-man [file]
428 Print full help as a UNIX man page and exit.
429 This option is used by the cmake build to generate the UNIX man
431 page. If a file is specified, the help is written into it.
432 --version,-version,/V [file]
435 Show program name/version banner and exit.
436 If a file is specified, the version is written into it.
438
441 The following generators are available on this platform:
442 Unix Makefiles
445 Generates standard UNIX makefiles.
446 A hierarchy of UNIX makefiles is generated into the build tree.
448 Any standard UNIX-style make program can build the project
449 through the default make target. A "make install" target is
450 also provided.
451 Ninja Generates build.ninja files (experimental).
454 A build.ninja file is generated into the build tree. Recent ver‐
456 sions of the ninja program can build the project through the
457 "all" target. An "install" target is also provided.
458 CodeBlocks - Ninja
461 Generates CodeBlocks project files.
462 Project files for CodeBlocks will be created in the top direc‐
464 tory and in every subdirectory which features a CMakeLists.txt
465 file containing a PROJECT() call. Additionally a hierarchy of
466 makefiles is generated into the build tree. The appropriate
467 make program can build the project through the default make tar‐
468 get. A "make install" target is also provided.
469 CodeBlocks - Unix Makefiles
472 Generates CodeBlocks project files.
473 Project files for CodeBlocks will be created in the top direc‐
475 tory and in every subdirectory which features a CMakeLists.txt
476 file containing a PROJECT() call. Additionally a hierarchy of
477 makefiles is generated into the build tree. The appropriate
478 make program can build the project through the default make tar‐
479 get. A "make install" target is also provided.
480 Eclipse CDT4 - Ninja
483 Generates Eclipse CDT 4.0 project files.
484 Project files for Eclipse will be created in the top directory.
486 In out of source builds, a linked resource to the top level
487 source directory will be created. Additionally a hierarchy of
488 makefiles is generated into the build tree. The appropriate make
489 program can build the project through the default make target. A
490 "make install" target is also provided.
491 Eclipse CDT4 - Unix Makefiles
494 Generates Eclipse CDT 4.0 project files.
495 Project files for Eclipse will be created in the top directory.
497 In out of source builds, a linked resource to the top level
498 source directory will be created. Additionally a hierarchy of
499 makefiles is generated into the build tree. The appropriate make
500 program can build the project through the default make target. A
501 "make install" target is also provided.
502 KDevelop3
505 Generates KDevelop 3 project files.
506 Project files for KDevelop 3 will be created in the top direc‐
508 tory and in every subdirectory which features a CMakeLists.txt
509 file containing a PROJECT() call. If you change the settings
510 using KDevelop cmake will try its best to keep your changes when
511 regenerating the project files. Additionally a hierarchy of UNIX
512 makefiles is generated into the build tree. Any standard
513 UNIX-style make program can build the project through the
514 default make target. A "make install" target is also provided.
515 KDevelop3 - Unix Makefiles
518 Generates KDevelop 3 project files.
519 Project files for KDevelop 3 will be created in the top direc‐
521 tory and in every subdirectory which features a CMakeLists.txt
522 file containing a PROJECT() call. If you change the settings
523 using KDevelop cmake will try its best to keep your changes when
524 regenerating the project files. Additionally a hierarchy of UNIX
525 makefiles is generated into the build tree. Any standard
526 UNIX-style make program can build the project through the
527 default make target. A "make install" target is also provided.
528 Sublime Text 2 - Ninja
531 Generates Sublime Text 2 project files.
532 Project files for Sublime Text 2 will be created in the top
534 directory and in every subdirectory which features a CMake‐
535 Lists.txt file containing a PROJECT() call. Additionally Make‐
536 files (or build.ninja files) are generated into the build tree.
537 The appropriate make program can build the project through the
538 default make target. A "make install" target is also provided.
539 Sublime Text 2 - Unix Makefiles
542 Generates Sublime Text 2 project files.
543 Project files for Sublime Text 2 will be created in the top
545 directory and in every subdirectory which features a CMake‐
546 Lists.txt file containing a PROJECT() call. Additionally Make‐
547 files (or build.ninja files) are generated into the build tree.
548 The appropriate make program can build the project through the
549 default make target. A "make install" target is also provided.
550
553 add_compile_options
554 Adds options to the compilation of source files.
555 add_compile_options(<option> ...)
557 Adds options to the compiler command line for sources in the
559 current directory and below. This command can be used to add
560 any options, but alternative commands exist to add preprocessor
561 definitions or include directories. See documentation of the
562 directory and target COMPILE_OPTIONS properties for details.
563 Arguments to add_compile_options may use "generator expressions"
564 with the syntax "$<...>". Generator expressions are evaluated
565 during build system generation to produce information specific
566 to each build configuration. Valid expressions are:
567 $<0:...> = empty string (ignores "...")
570 $<1:...> = content of "..."
571 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
572 $<CONFIGURATION> = configuration name
573 $<BOOL:...> = '1' if the '...' is true, else '0'
574 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
575 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
576 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
577 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
578 $<JOIN:list,...> = joins the list with the content of "..."
579 $<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.
580 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
581 $<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.
582 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
583 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
584 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
585 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
586 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
587 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
588 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
589 $<C_COMPILER_VERSION> = The version of the C compiler used.
590 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
591 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
592 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
593 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
594 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
595 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
596 where "tgt" is the name of a target. Target file expressions
598 produce a full path, but _DIR and _NAME versions can produce the
599 directory and file name components:
600 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
603 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
604 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
605 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
610 Note that tgt is not added as a dependency of the target this
612 expression is evaluated on.
613 $<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.
616 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
617 Boolean expressions:
619 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
622 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
623 $<NOT:?> = '0' if '?' is '1', else '1'
624 where '?' is always either '0' or '1'.
626 Expressions with an implicit 'this' target:
629 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
632 add_custom_command
635 Add a custom build rule to the generated build system.
636 There are two main signatures for add_custom_command The first
638 signature is for adding a custom command to produce an output.
639 add_custom_command(OUTPUT output1 [output2 ...]
642 COMMAND command1 [ARGS] [args1...]
643 [COMMAND command2 [ARGS] [args2...] ...]
644 [MAIN_DEPENDENCY depend]
645 [DEPENDS [depends...]]
646 [IMPLICIT_DEPENDS <lang1> depend1
647 [<lang2> depend2] ...]
648 [WORKING_DIRECTORY dir]
649 [COMMENT comment] [VERBATIM] [APPEND])
650 This defines a command to generate specified OUTPUT file(s). A
652 target created in the same directory (CMakeLists.txt file) that
653 specifies any output of the custom command as a source file is
654 given a rule to generate the file using the command at build
655 time. Do not list the output in more than one independent tar‐
656 get that may build in parallel or the two instances of the rule
657 may conflict (instead use add_custom_target to drive the command
658 and make the other targets depend on that one). If an output
659 name is a relative path it will be interpreted relative to the
660 build tree directory corresponding to the current source direc‐
661 tory. Note that MAIN_DEPENDENCY is completely optional and is
662 used as a suggestion to visual studio about where to hang the
663 custom command. In makefile terms this creates a new target in
664 the following form:
665 OUTPUT: MAIN_DEPENDENCY DEPENDS
668 COMMAND
669 If more than one command is specified they will be executed in
671 order. The optional ARGS argument is for backward compatibility
672 and will be ignored.
673 The second signature adds a custom command to a target such as a
676 library or executable. This is useful for performing an opera‐
677 tion before or after building the target. The command becomes
678 part of the target and will only execute when the target itself
679 is built. If the target is already built, the command will not
680 execute.
681 add_custom_command(TARGET target
684 PRE_BUILD | PRE_LINK | POST_BUILD
685 COMMAND command1 [ARGS] [args1...]
686 [COMMAND command2 [ARGS] [args2...] ...]
687 [WORKING_DIRECTORY dir]
688 [COMMENT comment] [VERBATIM])
689 This defines a new command that will be associated with building
691 the specified target. When the command will happen is determined
692 by which of the following is specified:
693 PRE_BUILD - run before all other dependencies
696 PRE_LINK - run after other dependencies
697 POST_BUILD - run after the target has been built
698 Note that the PRE_BUILD option is only supported on Visual Stu‐
700 dio 7 or later. For all other generators PRE_BUILD will be
701 treated as PRE_LINK.
702 If WORKING_DIRECTORY is specified the command will be executed
705 in the directory given. If it is a relative path it will be
706 interpreted relative to the build tree directory corresponding
707 to the current source directory. If COMMENT is set, the value
708 will be displayed as a message before the commands are executed
709 at build time. If APPEND is specified the COMMAND and DEPENDS
710 option values are appended to the custom command for the first
711 output specified. There must have already been a previous call
712 to this command with the same output. The COMMENT, WORK‐
713 ING_DIRECTORY, and MAIN_DEPENDENCY options are currently ignored
714 when APPEND is given, but may be used in the future.
715 If VERBATIM is given then all arguments to the commands will be
718 escaped properly for the build tool so that the invoked command
719 receives each argument unchanged. Note that one level of
720 escapes is still used by the CMake language processor before
721 add_custom_command even sees the arguments. Use of VERBATIM is
722 recommended as it enables correct behavior. When VERBATIM is not
723 given the behavior is platform specific because there is no pro‐
724 tection of tool-specific special characters.
725 If the output of the custom command is not actually created as a
728 file on disk it should be marked as SYMBOLIC with
729 SET_SOURCE_FILES_PROPERTIES.
730 The IMPLICIT_DEPENDS option requests scanning of implicit depen‐
733 dencies of an input file. The language given specifies the pro‐
734 gramming language whose corresponding dependency scanner should
735 be used. Currently only C and CXX language scanners are sup‐
736 ported. The language has to be specified for every file in the
737 IMPLICIT_DEPENDS list. Dependencies discovered from the scanning
738 are added to those of the custom command at build time. Note
739 that the IMPLICIT_DEPENDS option is currently supported only for
740 Makefile generators and will be ignored by other generators.
741 If COMMAND specifies an executable target (created by ADD_EXE‐
744 CUTABLE) it will automatically be replaced by the location of
745 the executable created at build time. Additionally a tar‐
746 get-level dependency will be added so that the executable target
747 will be built before any target using this custom command. How‐
748 ever this does NOT add a file-level dependency that would cause
749 the custom command to re-run whenever the executable is recom‐
750 piled.
751 Arguments to COMMAND may use "generator expressions" with the
754 syntax "$<...>". Generator expressions are evaluated during
755 build system generation to produce information specific to each
756 build configuration. Valid expressions are:
757 $<0:...> = empty string (ignores "...")
760 $<1:...> = content of "..."
761 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
762 $<CONFIGURATION> = configuration name
763 $<BOOL:...> = '1' if the '...' is true, else '0'
764 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
765 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
766 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
767 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
768 $<JOIN:list,...> = joins the list with the content of "..."
769 $<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.
770 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
771 $<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.
772 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
773 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
774 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
775 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
776 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
777 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
778 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
779 $<C_COMPILER_VERSION> = The version of the C compiler used.
780 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
781 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
782 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
783 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
784 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
785 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
786 where "tgt" is the name of a target. Target file expressions
788 produce a full path, but _DIR and _NAME versions can produce the
789 directory and file name components:
790 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
793 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
794 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
795 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
800 Note that tgt is not added as a dependency of the target this
802 expression is evaluated on.
803 $<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.
806 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
807 Boolean expressions:
809 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
812 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
813 $<NOT:?> = '0' if '?' is '1', else '1'
814 where '?' is always either '0' or '1'.
816 Expressions with an implicit 'this' target:
819 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
822 References to target names in generator expressions imply tar‐
824 get-level dependencies, but NOT file-level dependencies. List
825 target names with the DEPENDS option to add file dependencies.
826 The DEPENDS option specifies files on which the command depends.
829 If any dependency is an OUTPUT of another custom command in the
830 same directory (CMakeLists.txt file) CMake automatically brings
831 the other custom command into the target in which this command
832 is built. If DEPENDS is not specified the command will run
833 whenever the OUTPUT is missing; if the command does not actually
834 create the OUTPUT then the rule will always run. If DEPENDS
835 specifies any target (created by an ADD_* command) a tar‐
836 get-level dependency is created to make sure the target is built
837 before any target using this custom command. Additionally, if
838 the target is an executable or library a file-level dependency
839 is created to cause the custom command to re-run whenever the
840 target is recompiled.
841 add_custom_target
845 Add a target with no output so it will always be built.
846 add_custom_target(Name [ALL] [command1 [args1...]]
848 [COMMAND command2 [args2...] ...]
849 [DEPENDS depend depend depend ... ]
850 [WORKING_DIRECTORY dir]
851 [COMMENT comment] [VERBATIM]
852 [SOURCES src1 [src2...]])
853 Adds a target with the given name that executes the given com‐
855 mands. The target has no output file and is ALWAYS CONSIDERED
856 OUT OF DATE even if the commands try to create a file with the
857 name of the target. Use ADD_CUSTOM_COMMAND to generate a file
858 with dependencies. By default nothing depends on the custom tar‐
859 get. Use ADD_DEPENDENCIES to add dependencies to or from other
860 targets. If the ALL option is specified it indicates that this
861 target should be added to the default build target so that it
862 will be run every time (the command cannot be called ALL). The
863 command and arguments are optional and if not specified an empty
864 target will be created. If WORKING_DIRECTORY is set, then the
865 command will be run in that directory. If it is a relative path
866 it will be interpreted relative to the build tree directory cor‐
867 responding to the current source directory. If COMMENT is set,
868 the value will be displayed as a message before the commands are
869 executed at build time. Dependencies listed with the DEPENDS
870 argument may reference files and outputs of custom commands cre‐
871 ated with add_custom_command() in the same directory (CMake‐
872 Lists.txt file).
873 If VERBATIM is given then all arguments to the commands will be
876 escaped properly for the build tool so that the invoked command
877 receives each argument unchanged. Note that one level of
878 escapes is still used by the CMake language processor before
879 add_custom_target even sees the arguments. Use of VERBATIM is
880 recommended as it enables correct behavior. When VERBATIM is not
881 given the behavior is platform specific because there is no pro‐
882 tection of tool-specific special characters.
883 The SOURCES option specifies additional source files to be
886 included in the custom target. Specified source files will be
887 added to IDE project files for convenience in editing even if
888 they have not build rules.
889 add_definitions
892 Adds -D define flags to the compilation of source files.
893 add_definitions(-DFOO -DBAR ...)
895 Adds flags to the compiler command line for sources in the cur‐
897 rent directory and below. This command can be used to add any
898 flags, but it was originally intended to add preprocessor defi‐
899 nitions. Flags beginning in -D or /D that look like preproces‐
900 sor definitions are automatically added to the COMPILE_DEFINI‐
901 TIONS property for the current directory. Definitions with
902 non-trivial values may be left in the set of flags instead of
903 being converted for reasons of backwards compatibility. See
904 documentation of the directory, target, and source file COM‐
905 PILE_DEFINITIONS properties for details on adding preprocessor
906 definitions to specific scopes and configurations.
907 add_dependencies
910 Add a dependency between top-level targets.
911 add_dependencies(target-name depend-target1
913 depend-target2 ...)
914 Make a top-level target depend on other top-level targets. A
916 top-level target is one created by ADD_EXECUTABLE, ADD_LIBRARY,
917 or ADD_CUSTOM_TARGET. Adding dependencies with this command can
918 be used to make sure one target is built before another target.
919 Dependencies added to an IMPORTED target are followed transi‐
920 tively in its place since the target itself does not build. See
921 the DEPENDS option of ADD_CUSTOM_TARGET and ADD_CUSTOM_COMMAND
922 for adding file-level dependencies in custom rules. See the
923 OBJECT_DEPENDS option in SET_SOURCE_FILES_PROPERTIES to add
924 file-level dependencies to object files.
925 add_executable
928 Add an executable to the project using the specified source
929 files.
930 add_executable(<name> [WIN32] [MACOSX_BUNDLE]
932 [EXCLUDE_FROM_ALL]
933 source1 source2 ... sourceN)
934 Adds an executable target called <name> to be built from the
936 source files listed in the command invocation. The <name> cor‐
937 responds to the logical target name and must be globally unique
938 within a project. The actual file name of the executable built
939 is constructed based on conventions of the native platform (such
940 as <name>.exe or just <name>).
941 By default the executable file will be created in the build tree
944 directory corresponding to the source tree directory in which
945 the command was invoked. See documentation of the RUNTIME_OUT‐
946 PUT_DIRECTORY target property to change this location. See doc‐
947 umentation of the OUTPUT_NAME target property to change the
948 <name> part of the final file name.
949 If WIN32 is given the property WIN32_EXECUTABLE will be set on
952 the target created. See documentation of that target property
953 for details.
954 If MACOSX_BUNDLE is given the corresponding property will be set
957 on the created target. See documentation of the MACOSX_BUNDLE
958 target property for details.
959 If EXCLUDE_FROM_ALL is given the corresponding property will be
962 set on the created target. See documentation of the
963 EXCLUDE_FROM_ALL target property for details.
964 The add_executable command can also create IMPORTED executable
967 targets using this signature:
968 add_executable(<name> IMPORTED [GLOBAL])
971 An IMPORTED executable target references an executable file
973 located outside the project. No rules are generated to build
974 it. The target name has scope in the directory in which it is
975 created and below, but the GLOBAL option extends visibility. It
976 may be referenced like any target built within the project.
977 IMPORTED executables are useful for convenient reference from
978 commands like add_custom_command. Details about the imported
979 executable are specified by setting properties whose names begin
980 in "IMPORTED_". The most important such property is
981 IMPORTED_LOCATION (and its per-configuration version
982 IMPORTED_LOCATION_<CONFIG>) which specifies the location of the
983 main executable file on disk. See documentation of the
984 IMPORTED_* properties for more information.
985 The signature
988 add_executable(<name> ALIAS <target>)
991 creates an alias, such that <name> can be used to refer to <tar‐
993 get> in subsequent commands. The <name> does not appear in the
994 generated buildsystem as a make target. The <target> may not be
995 an IMPORTED target or an ALIAS. Alias targets can be used as
996 linkable targets, targets to read properties from, executables
997 for custom commands and custom targets. They can also be tested
998 for existance with the regular if(TARGET) subcommand. The
999 <name> may not be used to modify properties of <target>, that
1000 is, it may not be used as the operand of set_property, set_tar‐
1001 get_properties, target_link_libraries etc. An ALIAS target may
1002 not be installed of exported.
1003 add_library
1006 Add a library to the project using the specified source files.
1007 add_library(<name> [STATIC | SHARED | MODULE]
1009 [EXCLUDE_FROM_ALL]
1010 source1 source2 ... sourceN)
1011 Adds a library target called <name> to be built from the source
1013 files listed in the command invocation. The <name> corresponds
1014 to the logical target name and must be globally unique within a
1015 project. The actual file name of the library built is con‐
1016 structed based on conventions of the native platform (such as
1017 lib<name>.a or <name>.lib).
1018 STATIC, SHARED, or MODULE may be given to specify the type of
1021 library to be created. STATIC libraries are archives of object
1022 files for use when linking other targets. SHARED libraries are
1023 linked dynamically and loaded at runtime. MODULE libraries are
1024 plugins that are not linked into other targets but may be loaded
1025 dynamically at runtime using dlopen-like functionality. If no
1026 type is given explicitly the type is STATIC or SHARED based on
1027 whether the current value of the variable BUILD_SHARED_LIBS is
1028 true. For SHARED and MODULE libraries the POSITION_INDEPEN‐
1029 DENT_CODE target property is set to TRUE automatically.
1030 By default the library file will be created in the build tree
1033 directory corresponding to the source tree directory in which
1034 the command was invoked. See documentation of the ARCHIVE_OUT‐
1035 PUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUT‐
1036 PUT_DIRECTORY target properties to change this location. See
1037 documentation of the OUTPUT_NAME target property to change the
1038 <name> part of the final file name.
1039 If EXCLUDE_FROM_ALL is given the corresponding property will be
1042 set on the created target. See documentation of the
1043 EXCLUDE_FROM_ALL target property for details.
1044 The add_library command can also create IMPORTED library targets
1047 using this signature:
1048 add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED
1051 [GLOBAL])
1052 An IMPORTED library target references a library file located
1054 outside the project. No rules are generated to build it. The
1055 target name has scope in the directory in which it is created
1056 and below, but the GLOBAL option extends visibility. It may be
1057 referenced like any target built within the project. IMPORTED
1058 libraries are useful for convenient reference from commands like
1059 target_link_libraries. Details about the imported library are
1060 specified by setting properties whose names begin in
1061 "IMPORTED_". The most important such property is IMPORTED_LOCA‐
1062 TION (and its per-configuration version IMPORTED_LOCATION_<CON‐
1063 FIG>) which specifies the location of the main library file on
1064 disk. See documentation of the IMPORTED_* properties for more
1065 information.
1066 The signature
1069 add_library(<name> OBJECT <src>...)
1072 creates a special "object library" target. An object library
1074 compiles source files but does not archive or link their object
1075 files into a library. Instead other targets created by
1076 add_library or add_executable may reference the objects using an
1077 expression of the form $<TARGET_OBJECTS:objlib> as a source,
1078 where "objlib" is the object library name. For example:
1079 add_library(... $<TARGET_OBJECTS:objlib> ...)
1082 add_executable(... $<TARGET_OBJECTS:objlib> ...)
1083 will include objlib's object files in a library and an exe‐
1085 cutable along with those compiled from their own sources.
1086 Object libraries may contain only sources (and headers) that
1087 compile to object files. They may contain custom commands gen‐
1088 erating such sources, but not PRE_BUILD, PRE_LINK, or POST_BUILD
1089 commands. Object libraries cannot be imported, exported,
1090 installed, or linked. Some native build systems may not like
1091 targets that have only object files, so consider adding at least
1092 one real source file to any target that references $<TAR‐
1093 GET_OBJECTS:objlib>.
1094 The signature
1097 add_library(<name> ALIAS <target>)
1100 creates an alias, such that <name> can be used to refer to <tar‐
1102 get> in subsequent commands. The <name> does not appear in the
1103 generated buildsystem as a make target. The <target> may not be
1104 an IMPORTED target or an ALIAS. Alias targets can be used as
1105 linkable targets, targets to read properties from. They can
1106 also be tested for existance with the regular if(TARGET) subcom‐
1107 mand. The <name> may not be used to modify properties of <tar‐
1108 get>, that is, it may not be used as the operand of set_prop‐
1109 erty, set_target_properties, target_link_libraries etc. An
1110 ALIAS target may not be installed of exported.
1111 add_subdirectory
1114 Add a subdirectory to the build.
1115 add_subdirectory(source_dir [binary_dir]
1117 [EXCLUDE_FROM_ALL])
1118 Add a subdirectory to the build. The source_dir specifies the
1120 directory in which the source CMakeLists.txt and code files are
1121 located. If it is a relative path it will be evaluated with
1122 respect to the current directory (the typical usage), but it may
1123 also be an absolute path. The binary_dir specifies the directory
1124 in which to place the output files. If it is a relative path it
1125 will be evaluated with respect to the current output directory,
1126 but it may also be an absolute path. If binary_dir is not speci‐
1127 fied, the value of source_dir, before expanding any relative
1128 path, will be used (the typical usage). The CMakeLists.txt file
1129 in the specified source directory will be processed immediately
1130 by CMake before processing in the current input file continues
1131 beyond this command.
1132 If the EXCLUDE_FROM_ALL argument is provided then targets in the
1135 subdirectory will not be included in the ALL target of the par‐
1136 ent directory by default, and will be excluded from IDE project
1137 files. Users must explicitly build targets in the subdirectory.
1138 This is meant for use when the subdirectory contains a separate
1139 part of the project that is useful but not necessary, such as a
1140 set of examples. Typically the subdirectory should contain its
1141 own project() command invocation so that a full build system
1142 will be generated in the subdirectory (such as a VS IDE solution
1143 file). Note that inter-target dependencies supercede this
1144 exclusion. If a target built by the parent project depends on a
1145 target in the subdirectory, the dependee target will be included
1146 in the parent project build system to satisfy the dependency.
1147 add_test
1150 Add a test to the project with the specified arguments.
1151 add_test(testname Exename arg1 arg2 ... )
1153 If the ENABLE_TESTING command has been run, this command adds a
1155 test target to the current directory. If ENABLE_TESTING has not
1156 been run, this command does nothing. The tests are run by the
1157 testing subsystem by executing Exename with the specified argu‐
1158 ments. Exename can be either an executable built by this
1159 project or an arbitrary executable on the system (like tclsh).
1160 The test will be run with the current working directory set to
1161 the CMakeList.txt files corresponding directory in the binary
1162 tree.
1163 add_test(NAME <name> [CONFIGURATIONS [Debug|Release|...]]
1169 [WORKING_DIRECTORY dir]
1170 COMMAND <command> [arg1 [arg2 ...]])
1171 Add a test called <name>. The test name may not contain spaces,
1173 quotes, or other characters special in CMake syntax. If COMMAND
1174 specifies an executable target (created by add_executable) it
1175 will automatically be replaced by the location of the executable
1176 created at build time. If a CONFIGURATIONS option is given then
1177 the test will be executed only when testing under one of the
1178 named configurations. If a WORKING_DIRECTORY option is given
1179 then the test will be executed in the given directory.
1180 Arguments after COMMAND may use "generator expressions" with the
1183 syntax "$<...>". Generator expressions are evaluated during
1184 build system generation to produce information specific to each
1185 build configuration. Valid expressions are:
1186 $<0:...> = empty string (ignores "...")
1189 $<1:...> = content of "..."
1190 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
1191 $<CONFIGURATION> = configuration name
1192 $<BOOL:...> = '1' if the '...' is true, else '0'
1193 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
1194 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
1195 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
1196 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
1197 $<JOIN:list,...> = joins the list with the content of "..."
1198 $<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.
1199 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
1200 $<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.
1201 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
1202 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
1203 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
1204 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
1205 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
1206 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
1207 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
1208 $<C_COMPILER_VERSION> = The version of the C compiler used.
1209 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
1210 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
1211 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
1212 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
1213 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
1214 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
1215 where "tgt" is the name of a target. Target file expressions
1217 produce a full path, but _DIR and _NAME versions can produce the
1218 directory and file name components:
1219 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
1222 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
1223 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
1224 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
1229 Note that tgt is not added as a dependency of the target this
1231 expression is evaluated on.
1232 $<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.
1235 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
1236 Boolean expressions:
1238 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
1241 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
1242 $<NOT:?> = '0' if '?' is '1', else '1'
1243 where '?' is always either '0' or '1'.
1245 Example usage:
1248 add_test(NAME mytest
1251 COMMAND testDriver --config $<CONFIGURATION>
1252 --exe $<TARGET_FILE:myexe>)
1253 This creates a test "mytest" whose command runs a testDriver
1255 tool passing the configuration name and the full path to the
1256 executable file produced by target "myexe".
1257 aux_source_directory
1260 Find all source files in a directory.
1261 aux_source_directory(<dir> <variable>)
1263 Collects the names of all the source files in the specified
1265 directory and stores the list in the <variable> provided. This
1266 command is intended to be used by projects that use explicit
1267 template instantiation. Template instantiation files can be
1268 stored in a "Templates" subdirectory and collected automatically
1269 using this command to avoid manually listing all instantiations.
1270 It is tempting to use this command to avoid writing the list of
1273 source files for a library or executable target. While this
1274 seems to work, there is no way for CMake to generate a build
1275 system that knows when a new source file has been added. Nor‐
1276 mally the generated build system knows when it needs to rerun
1277 CMake because the CMakeLists.txt file is modified to add a new
1278 source. When the source is just added to the directory without
1279 modifying this file, one would have to manually rerun CMake to
1280 generate a build system incorporating the new file.
1281 break Break from an enclosing foreach or while loop.
1284 break()
1286 Breaks from an enclosing foreach loop or while loop
1288 build_command
1291 Get the command line to build this project.
1292 build_command(<variable>
1294 [CONFIGURATION <config>]
1295 [PROJECT_NAME <projname>]
1296 [TARGET <target>])
1297 Sets the given <variable> to a string containing the command
1299 line for building one configuration of a target in a project
1300 using the build tool appropriate for the current CMAKE_GENERA‐
1301 TOR.
1302 If CONFIGURATION is omitted, CMake chooses a reasonable default
1305 value for multi-configuration generators. CONFIGURATION is
1306 ignored for single-configuration generators.
1307 If PROJECT_NAME is omitted, the resulting command line will
1310 build the top level PROJECT in the current build tree.
1311 If TARGET is omitted, the resulting command line will build
1314 everything, effectively using build target 'all' or 'ALL_BUILD'.
1315 build_command(<cachevariable> <makecommand>)
1318 This second signature is deprecated, but still available for
1320 backwards compatibility. Use the first signature instead.
1321 Sets the given <cachevariable> to a string containing the com‐
1324 mand to build this project from the root of the build tree using
1325 the build tool given by <makecommand>. <makecommand> should be
1326 the full path to msdev, devenv, nmake, make or one of the end
1327 user build tools.
1328 cmake_host_system_information
1331 Query host system specific information.
1332 cmake_host_system_information(RESULT <variable> QUERY <key> ...)
1334 Queries system information of the host system on which cmake
1336 runs. One or more <key> can be provided to select the informa‐
1337 tion to be queried. The list of queried values is stored in
1338 <variable>.
1339 <key> can be one of the following values:
1342 NUMBER_OF_LOGICAL_CORES = Number of logical cores.
1345 NUMBER_OF_PHYSICAL_CORES = Number of physical cores.
1346 HOSTNAME = Hostname.
1347 FQDN = Fully qualified domain name.
1348 TOTAL_VIRTUAL_MEMORY = Total virtual memory in megabytes.
1349 AVAILABLE_VIRTUAL_MEMORY = Available virtual memory in megabytes.
1350 TOTAL_PHYSICAL_MEMORY = Total physical memory in megabytes.
1351 AVAILABLE_PHYSICAL_MEMORY = Available physical memory in megabytes.
1352 cmake_minimum_required
1355 Set the minimum required version of cmake for a project.
1356 cmake_minimum_required(VERSION major[.minor[.patch[.tweak]]]
1358 [FATAL_ERROR])
1359 If the current version of CMake is lower than that required it
1361 will stop processing the project and report an error. When a
1362 version higher than 2.4 is specified the command implicitly
1363 invokes
1364 cmake_policy(VERSION major[.minor[.patch[.tweak]]])
1367 which sets the cmake policy version level to the version speci‐
1369 fied. When version 2.4 or lower is given the command implicitly
1370 invokes
1371 cmake_policy(VERSION 2.4)
1374 which enables compatibility features for CMake 2.4 and lower.
1376 The FATAL_ERROR option is accepted but ignored by CMake 2.6 and
1379 higher. It should be specified so CMake versions 2.4 and lower
1380 fail with an error instead of just a warning.
1381 cmake_policy
1384 Manage CMake Policy settings.
1385 As CMake evolves it is sometimes necessary to change existing
1387 behavior in order to fix bugs or improve implementations of
1388 existing features. The CMake Policy mechanism is designed to
1389 help keep existing projects building as new versions of CMake
1390 introduce changes in behavior. Each new policy (behavioral
1391 change) is given an identifier of the form "CMP<NNNN>" where
1392 "<NNNN>" is an integer index. Documentation associated with
1393 each policy describes the OLD and NEW behavior and the reason
1394 the policy was introduced. Projects may set each policy to
1395 select the desired behavior. When CMake needs to know which
1396 behavior to use it checks for a setting specified by the
1397 project. If no setting is available the OLD behavior is assumed
1398 and a warning is produced requesting that the policy be set.
1399 The cmake_policy command is used to set policies to OLD or NEW
1402 behavior. While setting policies individually is supported, we
1403 encourage projects to set policies based on CMake versions.
1404 cmake_policy(VERSION major.minor[.patch[.tweak]])
1407 Specify that the current CMake list file is written for the
1409 given version of CMake. All policies introduced in the speci‐
1410 fied version or earlier will be set to use NEW behavior. All
1411 policies introduced after the specified version will be unset
1412 (unless variable CMAKE_POLICY_DEFAULT_CMP<NNNN> sets a default).
1413 This effectively requests behavior preferred as of a given CMake
1414 version and tells newer CMake versions to warn about their new
1415 policies. The policy version specified must be at least 2.4 or
1416 the command will report an error. In order to get compatibility
1417 features supporting versions earlier than 2.4 see documentation
1418 of policy CMP0001.
1419 cmake_policy(SET CMP<NNNN> NEW)
1422 cmake_policy(SET CMP<NNNN> OLD)
1423 Tell CMake to use the OLD or NEW behavior for a given policy.
1425 Projects depending on the old behavior of a given policy may
1426 silence a policy warning by setting the policy state to OLD.
1427 Alternatively one may fix the project to work with the new
1428 behavior and set the policy state to NEW.
1429 cmake_policy(GET CMP<NNNN> <variable>)
1432 Check whether a given policy is set to OLD or NEW behavior. The
1434 output variable value will be "OLD" or "NEW" if the policy is
1435 set, and empty otherwise.
1436 CMake keeps policy settings on a stack, so changes made by the
1439 cmake_policy command affect only the top of the stack. A new
1440 entry on the policy stack is managed automatically for each sub‐
1441 directory to protect its parents and siblings. CMake also man‐
1442 ages a new entry for scripts loaded by include() and find_pack‐
1443 age() commands except when invoked with the NO_POLICY_SCOPE
1444 option (see also policy CMP0011). The cmake_policy command pro‐
1445 vides an interface to manage custom entries on the policy stack:
1446 cmake_policy(PUSH)
1449 cmake_policy(POP)
1450 Each PUSH must have a matching POP to erase any changes. This
1452 is useful to make temporary changes to policy settings.
1453 Functions and macros record policy settings when they are cre‐
1456 ated and use the pre-record policies when they are invoked. If
1457 the function or macro implementation sets policies, the changes
1458 automatically propagate up through callers until they reach the
1459 closest nested policy stack entry.
1460 configure_file
1463 Copy a file to another location and modify its contents.
1464 configure_file(<input> <output>
1466 [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
1467 [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
1468 Copies a file <input> to file <output> and substitutes variable
1470 values referenced in the file content. If <input> is a relative
1471 path it is evaluated with respect to the current source direc‐
1472 tory. The <input> must be a file, not a directory. If <output>
1473 is a relative path it is evaluated with respect to the current
1474 binary directory. If <output> names an existing directory the
1475 input file is placed in that directory with its original name.
1476 If the <input> file is modified the build system will re-run
1479 CMake to re-configure the file and generate the build system
1480 again.
1481 This command replaces any variables in the input file referenced
1484 as ${VAR} or @VAR@ with their values as determined by CMake. If
1485 a variable is not defined, it will be replaced with nothing. If
1486 COPYONLY is specified, then no variable expansion will take
1487 place. If ESCAPE_QUOTES is specified then any substituted
1488 quotes will be C-style escaped. The file will be configured
1489 with the current values of CMake variables. If @ONLY is speci‐
1490 fied, only variables of the form @VAR@ will be replaced and
1491 ${VAR} will be ignored. This is useful for configuring scripts
1492 that use ${VAR}.
1493 Input file lines of the form "#cmakedefine VAR ..." will be
1496 replaced with either "#define VAR ..." or "/* #undef VAR */"
1497 depending on whether VAR is set in CMake to any value not con‐
1498 sidered a false constant by the if() command. (Content of "...",
1499 if any, is processed as above.) Input file lines of the form
1500 "#cmakedefine01 VAR" will be replaced with either "#define VAR
1501 1" or "#define VAR 0" similarly.
1502 With NEWLINE_STYLE the line ending could be adjusted:
1505 'UNIX' or 'LF' for \n, 'DOS', 'WIN32' or 'CRLF' for \r\n.
1508 COPYONLY must not be used with NEWLINE_STYLE.
1510 create_test_sourcelist
1514 Create a test driver and source list for building test programs.
1515 create_test_sourcelist(sourceListName driverName
1517 test1 test2 test3
1518 EXTRA_INCLUDE include.h
1519 FUNCTION function)
1520 A test driver is a program that links together many small tests
1522 into a single executable. This is useful when building static
1523 executables with large libraries to shrink the total required
1524 size. The list of source files needed to build the test driver
1525 will be in sourceListName. DriverName is the name of the test
1526 driver program. The rest of the arguments consist of a list of
1527 test source files, can be semicolon separated. Each test source
1528 file should have a function in it that is the same name as the
1529 file with no extension (foo.cxx should have int foo(int,
1530 char*[]);) DriverName will be able to call each of the tests by
1531 name on the command line. If EXTRA_INCLUDE is specified, then
1532 the next argument is included into the generated file. If FUNC‐
1533 TION is specified, then the next argument is taken as a function
1534 name that is passed a pointer to ac and av. This can be used to
1535 add extra command line processing to each test. The cmake vari‐
1536 able CMAKE_TESTDRIVER_BEFORE_TESTMAIN can be set to have code
1537 that will be placed directly before calling the test main func‐
1538 tion. CMAKE_TESTDRIVER_AFTER_TESTMAIN can be set to have code
1539 that will be placed directly after the call to the test main
1540 function.
1541 define_property
1544 Define and document custom properties.
1545 define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
1547 TEST | VARIABLE | CACHED_VARIABLE>
1548 PROPERTY <name> [INHERITED]
1549 BRIEF_DOCS <brief-doc> [docs...]
1550 FULL_DOCS <full-doc> [docs...])
1551 Define one property in a scope for use with the set_property and
1553 get_property commands. This is primarily useful to associate
1554 documentation with property names that may be retrieved with the
1555 get_property command. The first argument determines the kind of
1556 scope in which the property should be used. It must be one of
1557 the following:
1558 GLOBAL = associated with the global namespace
1561 DIRECTORY = associated with one directory
1562 TARGET = associated with one target
1563 SOURCE = associated with one source file
1564 TEST = associated with a test named with add_test
1565 VARIABLE = documents a CMake language variable
1566 CACHED_VARIABLE = documents a CMake cache variable
1567 Note that unlike set_property and get_property no actual scope
1569 needs to be given; only the kind of scope is important.
1570 The required PROPERTY option is immediately followed by the name
1573 of the property being defined.
1574 If the INHERITED option then the get_property command will chain
1577 up to the next higher scope when the requested property is not
1578 set in the scope given to the command. DIRECTORY scope chains
1579 to GLOBAL. TARGET, SOURCE, and TEST chain to DIRECTORY.
1580 The BRIEF_DOCS and FULL_DOCS options are followed by strings to
1583 be associated with the property as its brief and full documenta‐
1584 tion. Corresponding options to the get_property command will
1585 retrieve the documentation.
1586 else Starts the else portion of an if block.
1589 else(expression)
1591 See the if command.
1593 elseif Starts the elseif portion of an if block.
1596 elseif(expression)
1598 See the if command.
1600 enable_language
1603 Enable a language (CXX/C/Fortran/etc)
1604 enable_language(<lang> [OPTIONAL] )
1606 This command enables support for the named language in CMake.
1608 This is the same as the project command but does not create any
1609 of the extra variables that are created by the project command.
1610 Example languages are CXX, C, Fortran.
1611 This command must be called in file scope, not in a function
1614 call. Furthermore, it must be called in the highest directory
1615 common to all targets using the named language directly for com‐
1616 piling sources or indirectly through link dependencies. It is
1617 simplest to enable all needed languages in the top-level direc‐
1618 tory of a project.
1619 The OPTIONAL keyword is a placeholder for future implementation
1622 and does not currently work.
1623 enable_testing
1626 Enable testing for current directory and below.
1627 enable_testing()
1629 Enables testing for this directory and below. See also the
1631 add_test command. Note that ctest expects to find a test file
1632 in the build directory root. Therefore, this command should be
1633 in the source directory root.
1634 endforeach
1637 Ends a list of commands in a FOREACH block.
1638 endforeach(expression)
1640 See the FOREACH command.
1642 endfunction
1645 Ends a list of commands in a function block.
1646 endfunction(expression)
1648 See the function command.
1650 endif Ends a list of commands in an if block.
1653 endif(expression)
1655 See the if command.
1657 endmacro
1660 Ends a list of commands in a macro block.
1661 endmacro(expression)
1663 See the macro command.
1665 endwhile
1668 Ends a list of commands in a while block.
1669 endwhile(expression)
1671 See the while command.
1673 execute_process
1676 Execute one or more child processes.
1677 execute_process(COMMAND <cmd1> [args1...]]
1679 [COMMAND <cmd2> [args2...] [...]]
1680 [WORKING_DIRECTORY <directory>]
1681 [TIMEOUT <seconds>]
1682 [RESULT_VARIABLE <variable>]
1683 [OUTPUT_VARIABLE <variable>]
1684 [ERROR_VARIABLE <variable>]
1685 [INPUT_FILE <file>]
1686 [OUTPUT_FILE <file>]
1687 [ERROR_FILE <file>]
1688 [OUTPUT_QUIET]
1689 [ERROR_QUIET]
1690 [OUTPUT_STRIP_TRAILING_WHITESPACE]
1691 [ERROR_STRIP_TRAILING_WHITESPACE])
1692 Runs the given sequence of one or more commands with the stan‐
1694 dard output of each process piped to the standard input of the
1695 next. A single standard error pipe is used for all processes.
1696 If WORKING_DIRECTORY is given the named directory will be set as
1697 the current working directory of the child processes. If TIME‐
1698 OUT is given the child processes will be terminated if they do
1699 not finish in the specified number of seconds (fractions are
1700 allowed). If RESULT_VARIABLE is given the variable will be set
1701 to contain the result of running the processes. This will be an
1702 integer return code from the last child or a string describing
1703 an error condition. If OUTPUT_VARIABLE or ERROR_VARIABLE are
1704 given the variable named will be set with the contents of the
1705 standard output and standard error pipes respectively. If the
1706 same variable is named for both pipes their output will be
1707 merged in the order produced. If INPUT_FILE, OUTPUT_FILE, or
1708 ERROR_FILE is given the file named will be attached to the stan‐
1709 dard input of the first process, standard output of the last
1710 process, or standard error of all processes respectively. If
1711 OUTPUT_QUIET or ERROR_QUIET is given then the standard output or
1712 standard error results will be quietly ignored. If more than
1713 one OUTPUT_* or ERROR_* option is given for the same pipe the
1714 precedence is not specified. If no OUTPUT_* or ERROR_* options
1715 are given the output will be shared with the corresponding pipes
1716 of the CMake process itself.
1717 The execute_process command is a newer more powerful version of
1720 exec_program, but the old command has been kept for compatibil‐
1721 ity.
1722 export Export targets from the build tree for use by outside projects.
1725 export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
1727 [APPEND] FILE <filename> [EXPORT_LINK_INTERFACE_LIBRARIES])
1728 Create a file <filename> that may be included by outside
1730 projects to import targets from the current project's build
1731 tree. This is useful during cross-compiling to build utility
1732 executables that can run on the host platform in one project and
1733 then import them into another project being compiled for the
1734 target platform. If the NAMESPACE option is given the <names‐
1735 pace> string will be prepended to all target names written to
1736 the file. If the APPEND option is given the generated code will
1737 be appended to the file instead of overwriting it. The
1738 EXPORT_LINK_INTERFACE_LIBRARIES keyword, if present, causes the
1739 contents of the properties matching (IMPORTED_)?LINK_INTER‐
1740 FACE_LIBRARIES(_<CONFIG>)? to be exported, when policy CMP0022
1741 is NEW. If a library target is included in the export but a
1742 target to which it links is not included the behavior is unspec‐
1743 ified.
1744 The file created by this command is specific to the build tree
1747 and should never be installed. See the install(EXPORT) command
1748 to export targets from an installation tree.
1749 Do not set properties that affect the location of a target after
1752 passing it to this command. These include properties whose
1753 names match "(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIREC‐
1754 TORY)(_<CONFIG>)?", "(IMPLIB_)?(PREFIX|SUFFIX)", or "LINKER_LAN‐
1755 GUAGE". Failure to follow this rule is not diagnosed and leaves
1756 the location of the target undefined.
1757 export(PACKAGE <name>)
1760 Store the current build directory in the CMake user package reg‐
1762 istry for package <name>. The find_package command may consider
1763 the directory while searching for package <name>. This helps
1764 dependent projects find and use a package from the current
1765 project's build tree without help from the user. Note that the
1766 entry in the package registry that this command creates works
1767 only in conjunction with a package configuration file
1768 (<name>Config.cmake) that works with the build tree.
1769 file File manipulation command.
1772 file(WRITE filename "message to write"... )
1774 file(APPEND filename "message to write"... )
1775 file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX])
1776 file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> filename variable)
1777 file(STRINGS filename variable [LIMIT_COUNT num]
1778 [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes]
1779 [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes]
1780 [NEWLINE_CONSUME] [REGEX regex]
1781 [NO_HEX_CONVERSION])
1782 file(GLOB variable [RELATIVE path] [globbing expressions]...)
1783 file(GLOB_RECURSE variable [RELATIVE path]
1784 [FOLLOW_SYMLINKS] [globbing expressions]...)
1785 file(RENAME <oldname> <newname>)
1786 file(REMOVE [file1 ...])
1787 file(REMOVE_RECURSE [file1 ...])
1788 file(MAKE_DIRECTORY [directory1 directory2 ...])
1789 file(RELATIVE_PATH variable directory file)
1790 file(TO_CMAKE_PATH path result)
1791 file(TO_NATIVE_PATH path result)
1792 file(DOWNLOAD url file [INACTIVITY_TIMEOUT timeout]
1793 [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS]
1794 [EXPECTED_HASH ALGO=value] [EXPECTED_MD5 sum]
1795 [TLS_VERIFY on|off] [TLS_CAINFO file])
1796 file(UPLOAD filename url [INACTIVITY_TIMEOUT timeout]
1797 [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS])
1798 file(TIMESTAMP filename variable [<format string>] [UTC])
1799 file(GENERATE OUTPUT output_file
1800 <INPUT input_file|CONTENT input_content>
1801 [CONDITION expression])
1802 WRITE will write a message into a file called 'filename'. It
1804 overwrites the file if it already exists, and creates the file
1805 if it does not exist. (If the file is a build input, use config‐
1806 ure_file to update the file only when its content changes.)
1807 APPEND will write a message into a file same as WRITE, except it
1810 will append it to the end of the file
1811 READ will read the content of a file and store it into the vari‐
1814 able. It will start at the given offset and read up to numBytes.
1815 If the argument HEX is given, the binary data will be converted
1816 to hexadecimal representation and this will be stored in the
1817 variable.
1818 MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a
1821 cryptographic hash of the content of a file.
1822 STRINGS will parse a list of ASCII strings from a file and store
1825 it in a variable. Binary data in the file are ignored. Carriage
1826 return (CR) characters are ignored. It works also for Intel Hex
1827 and Motorola S-record files, which are automatically converted
1828 to binary format when reading them. Disable this using
1829 NO_HEX_CONVERSION.
1830 LIMIT_COUNT sets the maximum number of strings to return.
1833 LIMIT_INPUT sets the maximum number of bytes to read from the
1834 input file. LIMIT_OUTPUT sets the maximum number of bytes to
1835 store in the output variable. LENGTH_MINIMUM sets the minimum
1836 length of a string to return. Shorter strings are ignored.
1837 LENGTH_MAXIMUM sets the maximum length of a string to return.
1838 Longer strings are split into strings no longer than the maximum
1839 length. NEWLINE_CONSUME allows newlines to be included in
1840 strings instead of terminating them.
1841 REGEX specifies a regular expression that a string must match to
1844 be returned. Typical usage
1845 file(STRINGS myfile.txt myfile)
1848 stores a list in the variable "myfile" in which each item is a
1850 line from the input file.
1851 GLOB will generate a list of all files that match the globbing
1854 expressions and store it into the variable. Globbing expressions
1855 are similar to regular expressions, but much simpler. If RELA‐
1856 TIVE flag is specified for an expression, the results will be
1857 returned as a relative path to the given path. (We do not rec‐
1858 ommend using GLOB to collect a list of source files from your
1859 source tree. If no CMakeLists.txt file changes when a source is
1860 added or removed then the generated build system cannot know
1861 when to ask CMake to regenerate.)
1862 Examples of globbing expressions include:
1865 *.cxx - match all files with extension cxx
1868 *.vt? - match all files with extension vta,...,vtz
1869 f[3-5].txt - match files f3.txt, f4.txt, f5.txt
1870 GLOB_RECURSE will generate a list similar to the regular GLOB,
1872 except it will traverse all the subdirectories of the matched
1873 directory and match the files. Subdirectories that are symlinks
1874 are only traversed if FOLLOW_SYMLINKS is given or cmake policy
1875 CMP0009 is not set to NEW. See cmake --help-policy CMP0009 for
1876 more information.
1877 Examples of recursive globbing include:
1880 /dir/*.py - match all python files in /dir and subdirectories
1883 MAKE_DIRECTORY will create the given directories, also if their
1885 parent directories don't exist yet
1886 RENAME moves a file or directory within a filesystem, replacing
1889 the destination atomically.
1890 REMOVE will remove the given files, also in subdirectories
1893 REMOVE_RECURSE will remove the given files and directories, also
1896 non-empty directories
1897 RELATIVE_PATH will determine relative path from directory to the
1900 given file.
1901 TO_CMAKE_PATH will convert path into a cmake style path with
1904 unix /. The input can be a single path or a system path like
1905 "$ENV{PATH}". Note the double quotes around the ENV call
1906 TO_CMAKE_PATH only takes one argument. This command will also
1907 convert the native list delimiters for a list of paths like the
1908 PATH environment variable.
1909 TO_NATIVE_PATH works just like TO_CMAKE_PATH, but will convert
1912 from a cmake style path into the native path style \ for win‐
1913 dows and / for UNIX.
1914 DOWNLOAD will download the given URL to the given file. If LOG
1917 var is specified a log of the download will be put in var. If
1918 STATUS var is specified the status of the operation will be put
1919 in var. The status is returned in a list of length 2. The first
1920 element is the numeric return value for the operation, and the
1921 second element is a string value for the error. A 0 numeric
1922 error means no error in the operation. If TIMEOUT time is speci‐
1923 fied, the operation will timeout after time seconds, time should
1924 be specified as an integer. The INACTIVITY_TIMEOUT specifies an
1925 integer number of seconds of inactivity after which the opera‐
1926 tion should terminate. If EXPECTED_HASH ALGO=value is specified,
1927 the operation will verify that the downloaded file's actual hash
1928 matches the expected value, where ALGO is one of MD5, SHA1,
1929 SHA224, SHA256, SHA384, or SHA512. If it does not match, the
1930 operation fails with an error. ("EXPECTED_MD5 sum" is short-hand
1931 for "EXPECTED_HASH MD5=sum".) If SHOW_PROGRESS is specified,
1932 progress information will be printed as status messages until
1933 the operation is complete. For https URLs CMake must be built
1934 with OpenSSL. TLS/SSL certificates are not checked by default.
1935 Set TLS_VERIFY to ON to check certificates and/or use
1936 EXPECTED_HASH to verify downloaded content. Set TLS_CAINFO to
1937 specify a custom Certificate Authority file. If either TLS
1938 option is not given CMake will check variables CMAKE_TLS_VERIFY
1939 and CMAKE_TLS_CAINFO, respectively.
1940 UPLOAD will upload the given file to the given URL. If LOG var
1943 is specified a log of the upload will be put in var. If STATUS
1944 var is specified the status of the operation will be put in var.
1945 The status is returned in a list of length 2. The first element
1946 is the numeric return value for the operation, and the second
1947 element is a string value for the error. A 0 numeric error means
1948 no error in the operation. If TIMEOUT time is specified, the
1949 operation will timeout after time seconds, time should be speci‐
1950 fied as an integer. The INACTIVITY_TIMEOUT specifies an integer
1951 number of seconds of inactivity after which the operation should
1952 terminate. If SHOW_PROGRESS is specified, progress information
1953 will be printed as status messages until the operation is com‐
1954 plete.
1955 TIMESTAMP will write a string representation of the modification
1958 time of filename to variable.
1959 Should the command be unable to obtain a timestamp variable will
1962 be set to the empty string "".
1963 See documentation of the string TIMESTAMP sub-command for more
1966 details.
1967 The file() command also provides COPY and INSTALL signatures:
1970 file(<COPY|INSTALL> files... DESTINATION <dir>
1973 [FILE_PERMISSIONS permissions...]
1974 [DIRECTORY_PERMISSIONS permissions...]
1975 [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
1976 [FILES_MATCHING]
1977 [[PATTERN <pattern> | REGEX <regex>]
1978 [EXCLUDE] [PERMISSIONS permissions...]] [...])
1979 The COPY signature copies files, directories, and symlinks to a
1981 destination folder. Relative input paths are evaluated with
1982 respect to the current source directory, and a relative destina‐
1983 tion is evaluated with respect to the current build directory.
1984 Copying preserves input file timestamps, and optimizes out a
1985 file if it exists at the destination with the same timestamp.
1986 Copying preserves input permissions unless explicit permissions
1987 or NO_SOURCE_PERMISSIONS are given (default is USE_SOURCE_PER‐
1988 MISSIONS). See the install(DIRECTORY) command for documentation
1989 of permissions, PATTERN, REGEX, and EXCLUDE options.
1990 The INSTALL signature differs slightly from COPY: it prints sta‐
1993 tus messages, and NO_SOURCE_PERMISSIONS is default. Installa‐
1994 tion scripts generated by the install() command use this signa‐
1995 ture (with some undocumented options for internal use).
1996 GENERATE will write an <output_file> with content from an
1999 <input_file>, or from <input_content>. The output is generated
2000 conditionally based on the content of the <condition>. The file
2001 is written at CMake generate-time and the input may contain gen‐
2002 erator expressions. The <condition>, <output_file> and
2003 <input_file> may also contain generator expressions. The <con‐
2004 dition> must evaluate to either '0' or '1'. The <output_file>
2005 must evaluate to a unique name among all configurations and
2006 among all invocations of file(GENERATE).
2007 find_file
2010 Find the full path to a file.
2011 find_file(<VAR> name1 [path1 path2 ...])
2013 This is the short-hand signature for the command that is suffi‐
2015 cient in many cases. It is the same as find_file(<VAR> name1
2016 [PATHS path1 path2 ...])
2017 find_file(
2020 <VAR>
2021 name | NAMES name1 [name2 ...]
2022 [HINTS path1 [path2 ... ENV var]]
2023 [PATHS path1 [path2 ... ENV var]]
2024 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2025 [DOC "cache documentation string"]
2026 [NO_DEFAULT_PATH]
2027 [NO_CMAKE_ENVIRONMENT_PATH]
2028 [NO_CMAKE_PATH]
2029 [NO_SYSTEM_ENVIRONMENT_PATH]
2030 [NO_CMAKE_SYSTEM_PATH]
2031 [CMAKE_FIND_ROOT_PATH_BOTH |
2032 ONLY_CMAKE_FIND_ROOT_PATH |
2033 NO_CMAKE_FIND_ROOT_PATH]
2034 )
2035 This command is used to find a full path to named file. A cache
2037 entry named by <VAR> is created to store the result of this com‐
2038 mand. If the full path to a file is found the result is stored
2039 in the variable and the search will not be repeated unless the
2040 variable is cleared. If nothing is found, the result will be
2041 <VAR>-NOTFOUND, and the search will be attempted again the next
2042 time find_file is invoked with the same variable. The name of
2043 the full path to a file that is searched for is specified by the
2044 names listed after the NAMES argument. Additional search loca‐
2045 tions can be specified after the PATHS argument. If ENV var is
2046 found in the HINTS or PATHS section the environment variable var
2047 will be read and converted from a system environment variable to
2048 a cmake style list of paths. For example ENV PATH would be a
2049 way to list the system path variable. The argument after DOC
2050 will be used for the documentation string in the cache.
2051 PATH_SUFFIXES specifies additional subdirectories to check below
2052 each search path.
2053 If NO_DEFAULT_PATH is specified, then no additional paths are
2056 added to the search. If NO_DEFAULT_PATH is not specified, the
2057 search process is as follows:
2058 1. Search paths specified in cmake-specific cache variables.
2061 These are intended to be used on the command line with a
2062 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
2063 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2066 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2067 CMAKE_INCLUDE_PATH
2068 CMAKE_FRAMEWORK_PATH
2069 2. Search paths specified in cmake-specific environment vari‐
2071 ables. These are intended to be set in the user's shell config‐
2072 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2073 passed.
2074 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2077 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2078 CMAKE_INCLUDE_PATH
2079 CMAKE_FRAMEWORK_PATH
2080 3. Search the paths specified by the HINTS option. These should
2082 be paths computed by system introspection, such as a hint pro‐
2083 vided by the location of another item already found. Hard-coded
2084 guesses should be specified with the PATHS option.
2085 4. Search the standard system environment variables. This can be
2088 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2089 PATH
2092 INCLUDE
2093 5. Search cmake variables defined in the Platform files for the
2095 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
2096 passed.
2097 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2100 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2101 CMAKE_SYSTEM_INCLUDE_PATH
2102 CMAKE_SYSTEM_FRAMEWORK_PATH
2103 6. Search the paths specified by the PATHS option or in the
2105 short-hand version of the command. These are typically
2106 hard-coded guesses.
2107 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2110 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
2111 following:
2112 "FIRST" - Try to find frameworks before standard
2115 libraries or headers. This is the default on Darwin.
2116 "LAST" - Try to find frameworks after standard
2117 libraries or headers.
2118 "ONLY" - Only try to find frameworks.
2119 "NEVER" - Never try to find frameworks.
2120 On Darwin or systems supporting OS X Application Bundles, the
2122 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
2123 of the following:
2124 "FIRST" - Try to find application bundles before standard
2127 programs. This is the default on Darwin.
2128 "LAST" - Try to find application bundles after standard
2129 programs.
2130 "ONLY" - Only try to find application bundles.
2131 "NEVER" - Never try to find application bundles.
2132 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
2134 directories to be prepended to all other search directories.
2135 This effectively "re-roots" the entire search under given loca‐
2136 tions. By default it is empty. It is especially useful when
2137 cross-compiling to point to the root directory of the target
2138 environment and CMake will search there too. By default at first
2139 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2140 non-rooted directories will be searched. The default behavior
2141 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
2142 This behavior can be manually overridden on a per-call basis. By
2143 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2144 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2145 CMAKE_FIND_ROOT_PATH will not be used. If
2146 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2147 tories will be searched.
2148 The default search order is designed to be most-specific to
2151 least-specific for common use cases. Projects may override the
2152 order by simply calling the command multiple times and using the
2153 NO_* options:
2154 find_file(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2157 find_file(<VAR> NAMES name)
2158 Once one of the calls succeeds the result variable will be set
2160 and stored in the cache so that no call will search again.
2161 find_library
2164 Find a library.
2165 find_library(<VAR> name1 [path1 path2 ...])
2167 This is the short-hand signature for the command that is suffi‐
2169 cient in many cases. It is the same as find_library(<VAR> name1
2170 [PATHS path1 path2 ...])
2171 find_library(
2174 <VAR>
2175 name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
2176 [HINTS path1 [path2 ... ENV var]]
2177 [PATHS path1 [path2 ... ENV var]]
2178 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2179 [DOC "cache documentation string"]
2180 [NO_DEFAULT_PATH]
2181 [NO_CMAKE_ENVIRONMENT_PATH]
2182 [NO_CMAKE_PATH]
2183 [NO_SYSTEM_ENVIRONMENT_PATH]
2184 [NO_CMAKE_SYSTEM_PATH]
2185 [CMAKE_FIND_ROOT_PATH_BOTH |
2186 ONLY_CMAKE_FIND_ROOT_PATH |
2187 NO_CMAKE_FIND_ROOT_PATH]
2188 )
2189 This command is used to find a library. A cache entry named by
2191 <VAR> is created to store the result of this command. If the
2192 library is found the result is stored in the variable and the
2193 search will not be repeated unless the variable is cleared. If
2194 nothing is found, the result will be <VAR>-NOTFOUND, and the
2195 search will be attempted again the next time find_library is
2196 invoked with the same variable. The name of the library that is
2197 searched for is specified by the names listed after the NAMES
2198 argument. Additional search locations can be specified after
2199 the PATHS argument. If ENV var is found in the HINTS or PATHS
2200 section the environment variable var will be read and converted
2201 from a system environment variable to a cmake style list of
2202 paths. For example ENV PATH would be a way to list the system
2203 path variable. The argument after DOC will be used for the docu‐
2204 mentation string in the cache. PATH_SUFFIXES specifies addi‐
2205 tional subdirectories to check below each search path.
2206 If NO_DEFAULT_PATH is specified, then no additional paths are
2209 added to the search. If NO_DEFAULT_PATH is not specified, the
2210 search process is as follows:
2211 1. Search paths specified in cmake-specific cache variables.
2214 These are intended to be used on the command line with a
2215 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
2216 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2219 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
2220 CMAKE_LIBRARY_PATH
2221 CMAKE_FRAMEWORK_PATH
2222 2. Search paths specified in cmake-specific environment vari‐
2224 ables. These are intended to be set in the user's shell config‐
2225 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2226 passed.
2227 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2230 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
2231 CMAKE_LIBRARY_PATH
2232 CMAKE_FRAMEWORK_PATH
2233 3. Search the paths specified by the HINTS option. These should
2235 be paths computed by system introspection, such as a hint pro‐
2236 vided by the location of another item already found. Hard-coded
2237 guesses should be specified with the PATHS option.
2238 4. Search the standard system environment variables. This can be
2241 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2242 PATH
2245 LIB
2246 5. Search cmake variables defined in the Platform files for the
2248 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
2249 passed.
2250 <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2253 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2254 CMAKE_SYSTEM_LIBRARY_PATH
2255 CMAKE_SYSTEM_FRAMEWORK_PATH
2256 6. Search the paths specified by the PATHS option or in the
2258 short-hand version of the command. These are typically
2259 hard-coded guesses.
2260 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2263 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
2264 following:
2265 "FIRST" - Try to find frameworks before standard
2268 libraries or headers. This is the default on Darwin.
2269 "LAST" - Try to find frameworks after standard
2270 libraries or headers.
2271 "ONLY" - Only try to find frameworks.
2272 "NEVER" - Never try to find frameworks.
2273 On Darwin or systems supporting OS X Application Bundles, the
2275 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
2276 of the following:
2277 "FIRST" - Try to find application bundles before standard
2280 programs. This is the default on Darwin.
2281 "LAST" - Try to find application bundles after standard
2282 programs.
2283 "ONLY" - Only try to find application bundles.
2284 "NEVER" - Never try to find application bundles.
2285 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
2287 directories to be prepended to all other search directories.
2288 This effectively "re-roots" the entire search under given loca‐
2289 tions. By default it is empty. It is especially useful when
2290 cross-compiling to point to the root directory of the target
2291 environment and CMake will search there too. By default at first
2292 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2293 non-rooted directories will be searched. The default behavior
2294 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.
2295 This behavior can be manually overridden on a per-call basis. By
2296 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2297 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2298 CMAKE_FIND_ROOT_PATH will not be used. If
2299 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2300 tories will be searched.
2301 The default search order is designed to be most-specific to
2304 least-specific for common use cases. Projects may override the
2305 order by simply calling the command multiple times and using the
2306 NO_* options:
2307 find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2310 find_library(<VAR> NAMES name)
2311 Once one of the calls succeeds the result variable will be set
2313 and stored in the cache so that no call will search again.
2314 When more than one value is given to the NAMES option this com‐
2317 mand by default will consider one name at a time and search
2318 every directory for it. The NAMES_PER_DIR option tells this
2319 command to consider one directory at a time and search for all
2320 names in it.
2321 If the library found is a framework, then VAR will be set to the
2324 full path to the framework <fullPath>/A.framework. When a full
2325 path to a framework is used as a library, CMake will use a
2326 -framework A, and a -F<fullPath> to link the framework to the
2327 target.
2328 If the global property FIND_LIBRARY_USE_LIB64_PATHS is set all
2331 search paths will be tested as normal, with "64/" appended, and
2332 with all matches of "lib/" replaced with "lib64/". This property
2333 is automatically set for the platforms that are known to need it
2334 if at least one of the languages supported by the PROJECT com‐
2335 mand is enabled.
2336 find_package
2339 Load settings for an external project.
2340 find_package(<package> [version] [EXACT] [QUIET] [MODULE]
2342 [REQUIRED] [[COMPONENTS] [components...]]
2343 [OPTIONAL_COMPONENTS components...]
2344 [NO_POLICY_SCOPE])
2345 Finds and loads settings from an external project. <pack‐
2347 age>_FOUND will be set to indicate whether the package was
2348 found. When the package is found package-specific information
2349 is provided through variables and imported targets documented by
2350 the package itself. The QUIET option disables messages if the
2351 package cannot be found. The MODULE option disables the second
2352 signature documented below. The REQUIRED option stops process‐
2353 ing with an error message if the package cannot be found.
2354 A package-specific list of required components may be listed
2357 after the COMPONENTS option (or after the REQUIRED option if
2358 present). Additional optional components may be listed after
2359 OPTIONAL_COMPONENTS. Available components and their influence
2360 on whether a package is considered to be found are defined by
2361 the target package.
2362 The [version] argument requests a version with which the package
2365 found should be compatible (format is
2366 major[.minor[.patch[.tweak]]]). The EXACT option requests that
2367 the version be matched exactly. If no [version] and/or compo‐
2368 nent list is given to a recursive invocation inside a find-mod‐
2369 ule, the corresponding arguments are forwarded automatically
2370 from the outer call (including the EXACT flag for [version]).
2371 Version support is currently provided only on a package-by-pack‐
2372 age basis (details below).
2373 User code should generally look for packages using the above
2376 simple signature. The remainder of this command documentation
2377 specifies the full command signature and details of the search
2378 process. Project maintainers wishing to provide a package to be
2379 found by this command are encouraged to read on.
2380 The command has two modes by which it searches for packages:
2383 "Module" mode and "Config" mode. Module mode is available when
2384 the command is invoked with the above reduced signature. CMake
2385 searches for a file called "Find<package>.cmake" in the
2386 CMAKE_MODULE_PATH followed by the CMake installation. If the
2387 file is found, it is read and processed by CMake. It is respon‐
2388 sible for finding the package, checking the version, and produc‐
2389 ing any needed messages. Many find-modules provide limited or
2390 no support for versioning; check the module documentation. If
2391 no module is found and the MODULE option is not given the com‐
2392 mand proceeds to Config mode.
2393 The complete Config mode command signature is:
2396 find_package(<package> [version] [EXACT] [QUIET]
2399 [REQUIRED] [[COMPONENTS] [components...]]
2400 [CONFIG|NO_MODULE]
2401 [NO_POLICY_SCOPE]
2402 [NAMES name1 [name2 ...]]
2403 [CONFIGS config1 [config2 ...]]
2404 [HINTS path1 [path2 ... ]]
2405 [PATHS path1 [path2 ... ]]
2406 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2407 [NO_DEFAULT_PATH]
2408 [NO_CMAKE_ENVIRONMENT_PATH]
2409 [NO_CMAKE_PATH]
2410 [NO_SYSTEM_ENVIRONMENT_PATH]
2411 [NO_CMAKE_PACKAGE_REGISTRY]
2412 [NO_CMAKE_BUILDS_PATH]
2413 [NO_CMAKE_SYSTEM_PATH]
2414 [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
2415 [CMAKE_FIND_ROOT_PATH_BOTH |
2416 ONLY_CMAKE_FIND_ROOT_PATH |
2417 NO_CMAKE_FIND_ROOT_PATH])
2418 The CONFIG option may be used to skip Module mode explicitly and
2420 switch to Config mode. It is synonymous to using NO_MODULE.
2421 Config mode is also implied by use of options not specified in
2422 the reduced signature.
2423 Config mode attempts to locate a configuration file provided by
2426 the package to be found. A cache entry called <package>_DIR is
2427 created to hold the directory containing the file. By default
2428 the command searches for a package with the name <package>. If
2429 the NAMES option is given the names following it are used
2430 instead of <package>. The command searches for a file called
2431 "<name>Config.cmake" or "<lower-case-name>-config.cmake" for
2432 each name specified. A replacement set of possible configura‐
2433 tion file names may be given using the CONFIGS option. The
2434 search procedure is specified below. Once found, the configura‐
2435 tion file is read and processed by CMake. Since the file is
2436 provided by the package it already knows the location of package
2437 contents. The full path to the configuration file is stored in
2438 the cmake variable <package>_CONFIG.
2439 All configuration files which have been considered by CMake
2442 while searching for an installation of the package with an
2443 appropriate version are stored in the cmake variable <pack‐
2444 age>_CONSIDERED_CONFIGS, the associated versions in <pack‐
2445 age>_CONSIDERED_VERSIONS.
2446 If the package configuration file cannot be found CMake will
2449 generate an error describing the problem unless the QUIET argu‐
2450 ment is specified. If REQUIRED is specified and the package is
2451 not found a fatal error is generated and the configure step
2452 stops executing. If <package>_DIR has been set to a directory
2453 not containing a configuration file CMake will ignore it and
2454 search from scratch.
2455 When the [version] argument is given Config mode will only find
2458 a version of the package that claims compatibility with the
2459 requested version (format is major[.minor[.patch[.tweak]]]). If
2460 the EXACT option is given only a version of the package claiming
2461 an exact match of the requested version may be found. CMake
2462 does not establish any convention for the meaning of version
2463 numbers. Package version numbers are checked by "version" files
2464 provided by the packages themselves. For a candidate package
2465 configuration file "<config-file>.cmake" the corresponding ver‐
2466 sion file is located next to it and named either "<con‐
2467 fig-file>-version.cmake" or "<config-file>Version.cmake". If no
2468 such version file is available then the configuration file is
2469 assumed to not be compatible with any requested version. A
2470 basic version file containing generic version matching code can
2471 be created using the macro write_basic_package_version_file(),
2472 see its documentation for more details. When a version file is
2473 found it is loaded to check the requested version number. The
2474 version file is loaded in a nested scope in which the following
2475 variables have been defined:
2476 PACKAGE_FIND_NAME = the <package> name
2479 PACKAGE_FIND_VERSION = full requested version string
2480 PACKAGE_FIND_VERSION_MAJOR = major version if requested, else 0
2481 PACKAGE_FIND_VERSION_MINOR = minor version if requested, else 0
2482 PACKAGE_FIND_VERSION_PATCH = patch version if requested, else 0
2483 PACKAGE_FIND_VERSION_TWEAK = tweak version if requested, else 0
2484 PACKAGE_FIND_VERSION_COUNT = number of version components, 0 to 4
2485 The version file checks whether it satisfies the requested ver‐
2487 sion and sets these variables:
2488 PACKAGE_VERSION = full provided version string
2491 PACKAGE_VERSION_EXACT = true if version is exact match
2492 PACKAGE_VERSION_COMPATIBLE = true if version is compatible
2493 PACKAGE_VERSION_UNSUITABLE = true if unsuitable as any version
2494 These variables are checked by the find_package command to
2496 determine whether the configuration file provides an acceptable
2497 version. They are not available after the find_package call
2498 returns. If the version is acceptable the following variables
2499 are set:
2500 <package>_VERSION = full provided version string
2503 <package>_VERSION_MAJOR = major version if provided, else 0
2504 <package>_VERSION_MINOR = minor version if provided, else 0
2505 <package>_VERSION_PATCH = patch version if provided, else 0
2506 <package>_VERSION_TWEAK = tweak version if provided, else 0
2507 <package>_VERSION_COUNT = number of version components, 0 to 4
2508 and the corresponding package configuration file is loaded.
2510 When multiple package configuration files are available whose
2511 version files claim compatibility with the version requested it
2512 is unspecified which one is chosen. No attempt is made to
2513 choose a highest or closest version number.
2514 Config mode provides an elaborate interface and search proce‐
2517 dure. Much of the interface is provided for completeness and
2518 for use internally by find-modules loaded by Module mode. Most
2519 user code should simply call
2520 find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
2523 in order to find a package. Package maintainers providing CMake
2525 package configuration files are encouraged to name and install
2526 them such that the procedure outlined below will find them with‐
2527 out requiring use of additional options.
2528 CMake constructs a set of possible installation prefixes for the
2531 package. Under each prefix several directories are searched for
2532 a configuration file. The tables below show the directories
2533 searched. Each entry is meant for installation trees following
2534 Windows (W), UNIX (U), or Apple (A) conventions.
2535 <prefix>/ (W)
2538 <prefix>/(cmake|CMake)/ (W)
2539 <prefix>/<name>*/ (W)
2540 <prefix>/<name>*/(cmake|CMake)/ (W)
2541 <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/ (U)
2542 <prefix>/(lib/<arch>|lib|share)/<name>*/ (U)
2543 <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/ (U)
2544 On systems supporting OS X Frameworks and Application Bundles
2546 the following directories are searched for frameworks or bundles
2547 containing a configuration file:
2548 <prefix>/<name>.framework/Resources/ (A)
2551 <prefix>/<name>.framework/Resources/CMake/ (A)
2552 <prefix>/<name>.framework/Versions/*/Resources/ (A)
2553 <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
2554 <prefix>/<name>.app/Contents/Resources/ (A)
2555 <prefix>/<name>.app/Contents/Resources/CMake/ (A)
2556 In all cases the <name> is treated as case-insensitive and cor‐
2558 responds to any of the names specified (<package> or names given
2559 by NAMES). Paths with lib/<arch> are enabled if
2560 CMAKE_LIBRARY_ARCHITECTURE is set. If PATH_SUFFIXES is speci‐
2561 fied the suffixes are appended to each (W) or (U) directory
2562 entry one-by-one.
2563 This set of directories is intended to work in cooperation with
2566 projects that provide configuration files in their installation
2567 trees. Directories above marked with (W) are intended for
2568 installations on Windows where the prefix may point at the top
2569 of an application's installation directory. Those marked with
2570 (U) are intended for installations on UNIX platforms where the
2571 prefix is shared by multiple packages. This is merely a conven‐
2572 tion, so all (W) and (U) directories are still searched on all
2573 platforms. Directories marked with (A) are intended for instal‐
2574 lations on Apple platforms. The cmake variables
2575 CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE determine the
2576 order of preference as specified below.
2577 The set of installation prefixes is constructed using the fol‐
2580 lowing steps. If NO_DEFAULT_PATH is specified all NO_* options
2581 are enabled.
2582 1. Search paths specified in cmake-specific cache variables.
2585 These are intended to be used on the command line with a
2586 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
2587 CMAKE_PREFIX_PATH
2590 CMAKE_FRAMEWORK_PATH
2591 CMAKE_APPBUNDLE_PATH
2592 2. Search paths specified in cmake-specific environment vari‐
2594 ables. These are intended to be set in the user's shell config‐
2595 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2596 passed.
2597 <package>_DIR
2600 CMAKE_PREFIX_PATH
2601 CMAKE_FRAMEWORK_PATH
2602 CMAKE_APPBUNDLE_PATH
2603 3. Search paths specified by the HINTS option. These should be
2605 paths computed by system introspection, such as a hint provided
2606 by the location of another item already found. Hard-coded
2607 guesses should be specified with the PATHS option.
2608 4. Search the standard system environment variables. This can be
2611 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed. Path entries
2612 ending in "/bin" or "/sbin" are automatically converted to their
2613 parent directories.
2614 PATH
2617 5. Search project build trees recently configured in a CMake
2619 GUI. This can be skipped if NO_CMAKE_BUILDS_PATH is passed. It
2620 is intended for the case when a user is building multiple depen‐
2621 dent projects one after another.
2622 6. Search paths stored in the CMake user package registry. This
2625 can be skipped if NO_CMAKE_PACKAGE_REGISTRY is passed. On Win‐
2626 dows a <package> may appear under registry key
2627 HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package>
2630 as a REG_SZ value, with arbitrary name, that specifies the
2632 directory containing the package configuration file. On UNIX
2633 platforms a <package> may appear under the directory
2634 ~/.cmake/packages/<package>
2637 as a file, with arbitrary name, whose content specifies the
2639 directory containing the package configuration file. See the
2640 export(PACKAGE) command to create user package registry entries
2641 for project build trees.
2642 7. Search cmake variables defined in the Platform files for the
2645 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
2646 passed.
2647 CMAKE_SYSTEM_PREFIX_PATH
2650 CMAKE_SYSTEM_FRAMEWORK_PATH
2651 CMAKE_SYSTEM_APPBUNDLE_PATH
2652 8. Search paths stored in the CMake system package registry.
2654 This can be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is
2655 passed. On Windows a <package> may appear under registry key
2656 HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package>
2659 as a REG_SZ value, with arbitrary name, that specifies the
2661 directory containing the package configuration file. There is
2662 no system package registry on non-Windows platforms.
2663 9. Search paths specified by the PATHS option. These are typi‐
2666 cally hard-coded guesses.
2667 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2670 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
2671 following:
2672 "FIRST" - Try to find frameworks before standard
2675 libraries or headers. This is the default on Darwin.
2676 "LAST" - Try to find frameworks after standard
2677 libraries or headers.
2678 "ONLY" - Only try to find frameworks.
2679 "NEVER" - Never try to find frameworks.
2680 On Darwin or systems supporting OS X Application Bundles, the
2682 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
2683 of the following:
2684 "FIRST" - Try to find application bundles before standard
2687 programs. This is the default on Darwin.
2688 "LAST" - Try to find application bundles after standard
2689 programs.
2690 "ONLY" - Only try to find application bundles.
2691 "NEVER" - Never try to find application bundles.
2692 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
2694 directories to be prepended to all other search directories.
2695 This effectively "re-roots" the entire search under given loca‐
2696 tions. By default it is empty. It is especially useful when
2697 cross-compiling to point to the root directory of the target
2698 environment and CMake will search there too. By default at first
2699 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2700 non-rooted directories will be searched. The default behavior
2701 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.
2702 This behavior can be manually overridden on a per-call basis. By
2703 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2704 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2705 CMAKE_FIND_ROOT_PATH will not be used. If
2706 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2707 tories will be searched.
2708 The default search order is designed to be most-specific to
2711 least-specific for common use cases. Projects may override the
2712 order by simply calling the command multiple times and using the
2713 NO_* options:
2714 find_package(<package> PATHS paths... NO_DEFAULT_PATH)
2717 find_package(<package>)
2718 Once one of the calls succeeds the result variable will be set
2720 and stored in the cache so that no call will search again.
2721 Every non-REQUIRED find_package() call can be disabled by set‐
2724 ting the variable CMAKE_DISABLE_FIND_PACKAGE_<package> to TRUE.
2725 See the documentation for the CMAKE_DISABLE_FIND_PACKAGE_<pack‐
2726 age> variable for more information.
2727 When loading a find module or package configuration file
2730 find_package defines variables to provide information about the
2731 call arguments (and restores their original state before return‐
2732 ing):
2733 <package>_FIND_REQUIRED = true if REQUIRED option was given
2736 <package>_FIND_QUIETLY = true if QUIET option was given
2737 <package>_FIND_VERSION = full requested version string
2738 <package>_FIND_VERSION_MAJOR = major version if requested, else 0
2739 <package>_FIND_VERSION_MINOR = minor version if requested, else 0
2740 <package>_FIND_VERSION_PATCH = patch version if requested, else 0
2741 <package>_FIND_VERSION_TWEAK = tweak version if requested, else 0
2742 <package>_FIND_VERSION_COUNT = number of version components, 0 to 4
2743 <package>_FIND_VERSION_EXACT = true if EXACT option was given
2744 <package>_FIND_COMPONENTS = list of requested components
2745 <package>_FIND_REQUIRED_<c> = true if component <c> is required
2746 false if component <c> is optional
2747 In Module mode the loaded find module is responsible to honor
2749 the request detailed by these variables; see the find module for
2750 details. In Config mode find_package handles REQUIRED, QUIET,
2751 and version options automatically but leaves it to the package
2752 configuration file to handle components in a way that makes
2753 sense for the package. The package configuration file may set
2754 <package>_FOUND to false to tell find_package that component
2755 requirements are not satisfied.
2756 See the cmake_policy() command documentation for discussion of
2759 the NO_POLICY_SCOPE option.
2760 find_path
2763 Find the directory containing a file.
2764 find_path(<VAR> name1 [path1 path2 ...])
2766 This is the short-hand signature for the command that is suffi‐
2768 cient in many cases. It is the same as find_path(<VAR> name1
2769 [PATHS path1 path2 ...])
2770 find_path(
2773 <VAR>
2774 name | NAMES name1 [name2 ...]
2775 [HINTS path1 [path2 ... ENV var]]
2776 [PATHS path1 [path2 ... ENV var]]
2777 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2778 [DOC "cache documentation string"]
2779 [NO_DEFAULT_PATH]
2780 [NO_CMAKE_ENVIRONMENT_PATH]
2781 [NO_CMAKE_PATH]
2782 [NO_SYSTEM_ENVIRONMENT_PATH]
2783 [NO_CMAKE_SYSTEM_PATH]
2784 [CMAKE_FIND_ROOT_PATH_BOTH |
2785 ONLY_CMAKE_FIND_ROOT_PATH |
2786 NO_CMAKE_FIND_ROOT_PATH]
2787 )
2788 This command is used to find a directory containing the named
2790 file. A cache entry named by <VAR> is created to store the
2791 result of this command. If the file in a directory is found the
2792 result is stored in the variable and the search will not be
2793 repeated unless the variable is cleared. If nothing is found,
2794 the result will be <VAR>-NOTFOUND, and the search will be
2795 attempted again the next time find_path is invoked with the same
2796 variable. The name of the file in a directory that is searched
2797 for is specified by the names listed after the NAMES argument.
2798 Additional search locations can be specified after the PATHS
2799 argument. If ENV var is found in the HINTS or PATHS section the
2800 environment variable var will be read and converted from a sys‐
2801 tem environment variable to a cmake style list of paths. For
2802 example ENV PATH would be a way to list the system path vari‐
2803 able. The argument after DOC will be used for the documentation
2804 string in the cache. PATH_SUFFIXES specifies additional subdi‐
2805 rectories to check below each search path.
2806 If NO_DEFAULT_PATH is specified, then no additional paths are
2809 added to the search. If NO_DEFAULT_PATH is not specified, the
2810 search process is as follows:
2811 1. Search paths specified in cmake-specific cache variables.
2814 These are intended to be used on the command line with a
2815 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
2816 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2819 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2820 CMAKE_INCLUDE_PATH
2821 CMAKE_FRAMEWORK_PATH
2822 2. Search paths specified in cmake-specific environment vari‐
2824 ables. These are intended to be set in the user's shell config‐
2825 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2826 passed.
2827 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2830 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
2831 CMAKE_INCLUDE_PATH
2832 CMAKE_FRAMEWORK_PATH
2833 3. Search the paths specified by the HINTS option. These should
2835 be paths computed by system introspection, such as a hint pro‐
2836 vided by the location of another item already found. Hard-coded
2837 guesses should be specified with the PATHS option.
2838 4. Search the standard system environment variables. This can be
2841 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2842 PATH
2845 INCLUDE
2846 5. Search cmake variables defined in the Platform files for the
2848 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
2849 passed.
2850 <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
2853 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2854 CMAKE_SYSTEM_INCLUDE_PATH
2855 CMAKE_SYSTEM_FRAMEWORK_PATH
2856 6. Search the paths specified by the PATHS option or in the
2858 short-hand version of the command. These are typically
2859 hard-coded guesses.
2860 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2863 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
2864 following:
2865 "FIRST" - Try to find frameworks before standard
2868 libraries or headers. This is the default on Darwin.
2869 "LAST" - Try to find frameworks after standard
2870 libraries or headers.
2871 "ONLY" - Only try to find frameworks.
2872 "NEVER" - Never try to find frameworks.
2873 On Darwin or systems supporting OS X Application Bundles, the
2875 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
2876 of the following:
2877 "FIRST" - Try to find application bundles before standard
2880 programs. This is the default on Darwin.
2881 "LAST" - Try to find application bundles after standard
2882 programs.
2883 "ONLY" - Only try to find application bundles.
2884 "NEVER" - Never try to find application bundles.
2885 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
2887 directories to be prepended to all other search directories.
2888 This effectively "re-roots" the entire search under given loca‐
2889 tions. By default it is empty. It is especially useful when
2890 cross-compiling to point to the root directory of the target
2891 environment and CMake will search there too. By default at first
2892 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2893 non-rooted directories will be searched. The default behavior
2894 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
2895 This behavior can be manually overridden on a per-call basis. By
2896 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2897 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2898 CMAKE_FIND_ROOT_PATH will not be used. If
2899 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2900 tories will be searched.
2901 The default search order is designed to be most-specific to
2904 least-specific for common use cases. Projects may override the
2905 order by simply calling the command multiple times and using the
2906 NO_* options:
2907 find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2910 find_path(<VAR> NAMES name)
2911 Once one of the calls succeeds the result variable will be set
2913 and stored in the cache so that no call will search again.
2914 When searching for frameworks, if the file is specified as
2917 A/b.h, then the framework search will look for A.framework/Head‐
2918 ers/b.h. If that is found the path will be set to the path to
2919 the framework. CMake will convert this to the correct -F option
2920 to include the file.
2921 find_program
2924 Find an executable program.
2925 find_program(<VAR> name1 [path1 path2 ...])
2927 This is the short-hand signature for the command that is suffi‐
2929 cient in many cases. It is the same as find_program(<VAR> name1
2930 [PATHS path1 path2 ...])
2931 find_program(
2934 <VAR>
2935 name | NAMES name1 [name2 ...]
2936 [HINTS path1 [path2 ... ENV var]]
2937 [PATHS path1 [path2 ... ENV var]]
2938 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2939 [DOC "cache documentation string"]
2940 [NO_DEFAULT_PATH]
2941 [NO_CMAKE_ENVIRONMENT_PATH]
2942 [NO_CMAKE_PATH]
2943 [NO_SYSTEM_ENVIRONMENT_PATH]
2944 [NO_CMAKE_SYSTEM_PATH]
2945 [CMAKE_FIND_ROOT_PATH_BOTH |
2946 ONLY_CMAKE_FIND_ROOT_PATH |
2947 NO_CMAKE_FIND_ROOT_PATH]
2948 )
2949 This command is used to find a program. A cache entry named by
2951 <VAR> is created to store the result of this command. If the
2952 program is found the result is stored in the variable and the
2953 search will not be repeated unless the variable is cleared. If
2954 nothing is found, the result will be <VAR>-NOTFOUND, and the
2955 search will be attempted again the next time find_program is
2956 invoked with the same variable. The name of the program that is
2957 searched for is specified by the names listed after the NAMES
2958 argument. Additional search locations can be specified after
2959 the PATHS argument. If ENV var is found in the HINTS or PATHS
2960 section the environment variable var will be read and converted
2961 from a system environment variable to a cmake style list of
2962 paths. For example ENV PATH would be a way to list the system
2963 path variable. The argument after DOC will be used for the docu‐
2964 mentation string in the cache. PATH_SUFFIXES specifies addi‐
2965 tional subdirectories to check below each search path.
2966 If NO_DEFAULT_PATH is specified, then no additional paths are
2969 added to the search. If NO_DEFAULT_PATH is not specified, the
2970 search process is as follows:
2971 1. Search paths specified in cmake-specific cache variables.
2974 These are intended to be used on the command line with a
2975 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
2976 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2979 CMAKE_PROGRAM_PATH
2980 CMAKE_APPBUNDLE_PATH
2981 2. Search paths specified in cmake-specific environment vari‐
2983 ables. These are intended to be set in the user's shell config‐
2984 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2985 passed.
2986 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2989 CMAKE_PROGRAM_PATH
2990 CMAKE_APPBUNDLE_PATH
2991 3. Search the paths specified by the HINTS option. These should
2993 be paths computed by system introspection, such as a hint pro‐
2994 vided by the location of another item already found. Hard-coded
2995 guesses should be specified with the PATHS option.
2996 4. Search the standard system environment variables. This can be
2999 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
3000 PATH
3003 5. Search cmake variables defined in the Platform files for the
3006 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
3007 passed.
3008 <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
3011 CMAKE_SYSTEM_PROGRAM_PATH
3012 CMAKE_SYSTEM_APPBUNDLE_PATH
3013 6. Search the paths specified by the PATHS option or in the
3015 short-hand version of the command. These are typically
3016 hard-coded guesses.
3017 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
3020 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
3021 following:
3022 "FIRST" - Try to find frameworks before standard
3025 libraries or headers. This is the default on Darwin.
3026 "LAST" - Try to find frameworks after standard
3027 libraries or headers.
3028 "ONLY" - Only try to find frameworks.
3029 "NEVER" - Never try to find frameworks.
3030 On Darwin or systems supporting OS X Application Bundles, the
3032 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
3033 of the following:
3034 "FIRST" - Try to find application bundles before standard
3037 programs. This is the default on Darwin.
3038 "LAST" - Try to find application bundles after standard
3039 programs.
3040 "ONLY" - Only try to find application bundles.
3041 "NEVER" - Never try to find application bundles.
3042 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
3044 directories to be prepended to all other search directories.
3045 This effectively "re-roots" the entire search under given loca‐
3046 tions. By default it is empty. It is especially useful when
3047 cross-compiling to point to the root directory of the target
3048 environment and CMake will search there too. By default at first
3049 the directories listed in CMAKE_FIND_ROOT_PATH and then the
3050 non-rooted directories will be searched. The default behavior
3051 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.
3052 This behavior can be manually overridden on a per-call basis. By
3053 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
3054 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
3055 CMAKE_FIND_ROOT_PATH will not be used. If
3056 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
3057 tories will be searched.
3058 The default search order is designed to be most-specific to
3061 least-specific for common use cases. Projects may override the
3062 order by simply calling the command multiple times and using the
3063 NO_* options:
3064 find_program(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
3067 find_program(<VAR> NAMES name)
3068 Once one of the calls succeeds the result variable will be set
3070 and stored in the cache so that no call will search again.
3071 fltk_wrap_ui
3074 Create FLTK user interfaces Wrappers.
3075 fltk_wrap_ui(resultingLibraryName source1
3077 source2 ... sourceN )
3078 Produce .h and .cxx files for all the .fl and .fld files listed.
3080 The resulting .h and .cxx files will be added to a variable
3081 named resultingLibraryName_FLTK_UI_SRCS which should be added to
3082 your library.
3083 foreach
3086 Evaluate a group of commands for each value in a list.
3087 foreach(loop_var arg1 arg2 ...)
3089 COMMAND1(ARGS ...)
3090 COMMAND2(ARGS ...)
3091 ...
3092 endforeach(loop_var)
3093 All commands between foreach and the matching endforeach are
3095 recorded without being invoked. Once the endforeach is evalu‐
3096 ated, the recorded list of commands is invoked once for each
3097 argument listed in the original foreach command. Before each
3098 iteration of the loop "${loop_var}" will be set as a variable
3099 with the current value in the list.
3100 foreach(loop_var RANGE total)
3103 foreach(loop_var RANGE start stop [step])
3104 Foreach can also iterate over a generated range of numbers.
3106 There are three types of this iteration:
3107 * When specifying single number, the range will have elements 0
3110 to "total".
3111 * When specifying two numbers, the range will have elements from
3114 the first number to the second number.
3115 * The third optional number is the increment used to iterate
3118 from the first number to the second number.
3119 foreach(loop_var IN [LISTS [list1 [...]]]
3122 [ITEMS [item1 [...]]])
3123 Iterates over a precise list of items. The LISTS option names
3125 list-valued variables to be traversed, including empty elements
3126 (an empty string is a zero-length list). The ITEMS option ends
3127 argument parsing and includes all arguments following it in the
3128 iteration.
3129 function
3132 Start recording a function for later invocation as a command.
3133 function(<name> [arg1 [arg2 [arg3 ...]]])
3135 COMMAND1(ARGS ...)
3136 COMMAND2(ARGS ...)
3137 ...
3138 endfunction(<name>)
3139 Define a function named <name> that takes arguments named arg1
3141 arg2 arg3 (...). Commands listed after function, but before the
3142 matching endfunction, are not invoked until the function is
3143 invoked. When it is invoked, the commands recorded in the func‐
3144 tion are first modified by replacing formal parameters (${arg1})
3145 with the arguments passed, and then invoked as normal commands.
3146 In addition to referencing the formal parameters you can refer‐
3147 ence the variable ARGC which will be set to the number of argu‐
3148 ments passed into the function as well as ARGV0 ARGV1 ARGV2 ...
3149 which will have the actual values of the arguments passed in.
3150 This facilitates creating functions with optional arguments.
3151 Additionally ARGV holds the list of all arguments given to the
3152 function and ARGN holds the list of arguments past the last
3153 expected argument.
3154 A function opens a new scope: see set(var PARENT_SCOPE) for
3157 details.
3158 See the cmake_policy() command documentation for the behavior of
3161 policies inside functions.
3162 get_cmake_property
3165 Get a property of the CMake instance.
3166 get_cmake_property(VAR property)
3168 Get a property from the CMake instance. The value of the prop‐
3170 erty is stored in the variable VAR. If the property is not
3171 found, VAR will be set to "NOTFOUND". Some supported properties
3172 include: VARIABLES, CACHE_VARIABLES, COMMANDS, MACROS, and COM‐
3173 PONENTS.
3174 See also the more general get_property() command.
3177 get_directory_property
3180 Get a property of DIRECTORY scope.
3181 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
3183 Store a property of directory scope in the named variable. If
3185 the property is not defined the empty-string is returned. The
3186 DIRECTORY argument specifies another directory from which to
3187 retrieve the property value. The specified directory must have
3188 already been traversed by CMake.
3189 get_directory_property(<variable> [DIRECTORY <dir>]
3192 DEFINITION <var-name>)
3193 Get a variable definition from a directory. This form is useful
3195 to get a variable definition from another directory.
3196 See also the more general get_property() command.
3199 get_filename_component
3202 Get a specific component of a full filename.
3203 get_filename_component(<VAR> <FileName> <COMP> [CACHE])
3205 Set <VAR> to a component of <FileName>, where <COMP> is one of:
3207 DIRECTORY = Directory without file name
3210 NAME = File name without directory
3211 EXT = File name longest extension (.b.c from d/a.b.c)
3212 NAME_WE = File name without directory or longest extension
3213 ABSOLUTE = Full path to file
3214 REALPATH = Full path to existing file with symlinks resolved
3215 PATH = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)
3216 Paths are returned with forward slashes and have no trailing
3218 slahes. The longest file extension is always considered. If the
3219 optional CACHE argument is specified, the result variable is
3220 added to the cache.
3221 get_filename_component(<VAR> FileName
3224 PROGRAM [PROGRAM_ARGS <ARG_VAR>]
3225 [CACHE])
3226 The program in FileName will be found in the system search path
3228 or left as a full path. If PROGRAM_ARGS is present with PRO‐
3229 GRAM, then any command-line arguments present in the FileName
3230 string are split from the program name and stored in <ARG_VAR>.
3231 This is used to separate a program name from its arguments in a
3232 command line string.
3233 get_property
3236 Get a property.
3237 get_property(<variable>
3239 <GLOBAL |
3240 DIRECTORY [dir] |
3241 TARGET <target> |
3242 SOURCE <source> |
3243 TEST <test> |
3244 CACHE <entry> |
3245 VARIABLE>
3246 PROPERTY <name>
3247 [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
3248 Get one property from one object in a scope. The first argument
3250 specifies the variable in which to store the result. The second
3251 argument determines the scope from which to get the property.
3252 It must be one of the following:
3253 GLOBAL scope is unique and does not accept a name.
3256 DIRECTORY scope defaults to the current directory but another
3259 directory (already processed by CMake) may be named by full or
3260 relative path.
3261 TARGET scope must name one existing target.
3264 SOURCE scope must name one source file.
3267 TEST scope must name one existing test.
3270 CACHE scope must name one cache entry.
3273 VARIABLE scope is unique and does not accept a name.
3276 The required PROPERTY option is immediately followed by the name
3279 of the property to get. If the property is not set an empty
3280 value is returned. If the SET option is given the variable is
3281 set to a boolean value indicating whether the property has been
3282 set. If the DEFINED option is given the variable is set to a
3283 boolean value indicating whether the property has been defined
3284 such as with define_property. If BRIEF_DOCS or FULL_DOCS is
3285 given then the variable is set to a string containing documenta‐
3286 tion for the requested property. If documentation is requested
3287 for a property that has not been defined NOTFOUND is returned.
3288 get_source_file_property
3291 Get a property for a source file.
3292 get_source_file_property(VAR file property)
3294 Get a property from a source file. The value of the property is
3296 stored in the variable VAR. If the property is not found, VAR
3297 will be set to "NOTFOUND". Use set_source_files_properties to
3298 set property values. Source file properties usually control how
3299 the file is built. One property that is always there is LOCATION
3300 See also the more general get_property() command.
3303 get_target_property
3306 Get a property from a target.
3307 get_target_property(VAR target property)
3309 Get a property from a target. The value of the property is
3311 stored in the variable VAR. If the property is not found, VAR
3312 will be set to "NOTFOUND". Use set_target_properties to set
3313 property values. Properties are usually used to control how a
3314 target is built, but some query the target instead. This com‐
3315 mand can get properties for any target so far created. The tar‐
3316 gets do not need to be in the current CMakeLists.txt file.
3317 See also the more general get_property() command.
3320 get_test_property
3323 Get a property of the test.
3324 get_test_property(test property VAR)
3326 Get a property from the Test. The value of the property is
3328 stored in the variable VAR. If the property is not found, VAR
3329 will be set to "NOTFOUND". For a list of standard properties you
3330 can type cmake --help-property-list
3331 See also the more general get_property() command.
3334 if Conditionally execute a group of commands.
3337 if(expression)
3339 # then section.
3340 COMMAND1(ARGS ...)
3341 COMMAND2(ARGS ...)
3342 ...
3343 elseif(expression2)
3344 # elseif section.
3345 COMMAND1(ARGS ...)
3346 COMMAND2(ARGS ...)
3347 ...
3348 else(expression)
3349 # else section.
3350 COMMAND1(ARGS ...)
3351 COMMAND2(ARGS ...)
3352 ...
3353 endif(expression)
3354 Evaluates the given expression. If the result is true, the com‐
3356 mands in the THEN section are invoked. Otherwise, the commands
3357 in the else section are invoked. The elseif and else sections
3358 are optional. You may have multiple elseif clauses. Note that
3359 the expression in the else and endif clause is optional. Long
3360 expressions can be used and there is a traditional order of
3361 precedence. Parenthetical expressions are evaluated first fol‐
3362 lowed by unary operators such as EXISTS, COMMAND, and DEFINED.
3363 Then any EQUAL, LESS, GREATER, STRLESS, STRGREATER, STREQUAL,
3364 MATCHES will be evaluated. Then NOT operators and finally AND,
3365 OR operators will be evaluated. Possible expressions are:
3366 if(<constant>)
3369 True if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
3371 ber. False if the constant is 0, OFF, NO, FALSE, N, IGNORE,
3372 NOTFOUND, '', or ends in the suffix '-NOTFOUND'. Named boolean
3373 constants are case-insensitive. If the argument is not one of
3374 these constants, it is treated as a variable:
3375 if(<variable>)
3378 True if the variable is defined to a value that is not a false
3380 constant. False otherwise. (Note macro arguments are not vari‐
3381 ables.)
3382 if(NOT <expression>)
3385 True if the expression is not true.
3387 if(<expr1> AND <expr2>)
3390 True if both expressions would be considered true individually.
3392 if(<expr1> OR <expr2>)
3395 True if either expression would be considered true individually.
3397 if(COMMAND command-name)
3400 True if the given name is a command, macro or function that can
3402 be invoked.
3403 if(POLICY policy-id)
3406 True if the given name is an existing policy (of the form
3408 CMP<NNNN>).
3409 if(TARGET target-name)
3412 True if the given name is an existing target, built or imported.
3414 if(EXISTS file-name)
3417 if(EXISTS directory-name)
3418 True if the named file or directory exists. Behavior is
3420 well-defined only for full paths.
3421 if(file1 IS_NEWER_THAN file2)
3424 True if file1 is newer than file2 or if one of the two files
3426 doesn't exist. Behavior is well-defined only for full paths. If
3427 the file time stamps are exactly the same, an IS_NEWER_THAN com‐
3428 parison returns true, so that any dependent build operations
3429 will occur in the event of a tie. This includes the case of
3430 passing the same file name for both file1 and file2.
3431 if(IS_DIRECTORY directory-name)
3434 True if the given name is a directory. Behavior is well-defined
3436 only for full paths.
3437 if(IS_SYMLINK file-name)
3440 True if the given name is a symbolic link. Behavior is
3442 well-defined only for full paths.
3443 if(IS_ABSOLUTE path)
3446 True if the given path is an absolute path.
3448 if(<variable|string> MATCHES regex)
3451 True if the given string or variable's value matches the given
3453 regular expression.
3454 if(<variable|string> LESS <variable|string>)
3457 if(<variable|string> GREATER <variable|string>)
3458 if(<variable|string> EQUAL <variable|string>)
3459 True if the given string or variable's value is a valid number
3461 and the inequality or equality is true.
3462 if(<variable|string> STRLESS <variable|string>)
3465 if(<variable|string> STRGREATER <variable|string>)
3466 if(<variable|string> STREQUAL <variable|string>)
3467 True if the given string or variable's value is lexicographi‐
3469 cally less (or greater, or equal) than the string or variable on
3470 the right.
3471 if(<variable|string> VERSION_LESS <variable|string>)
3474 if(<variable|string> VERSION_EQUAL <variable|string>)
3475 if(<variable|string> VERSION_GREATER <variable|string>)
3476 Component-wise integer version number comparison (version format
3478 is major[.minor[.patch[.tweak]]]).
3479 if(DEFINED <variable>)
3482 True if the given variable is defined. It does not matter if the
3484 variable is true or false just if it has been set.
3485 if((expression) AND (expression OR (expression)))
3488 The expressions inside the parenthesis are evaluated first and
3490 then the remaining expression is evaluated as in the previous
3491 examples. Where there are nested parenthesis the innermost are
3492 evaluated as part of evaluating the expression that contains
3493 them.
3494 The if command was written very early in CMake's history, pre‐
3497 dating the ${} variable evaluation syntax, and for convenience
3498 evaluates variables named by its arguments as shown in the above
3499 signatures. Note that normal variable evaluation with ${}
3500 applies before the if command even receives the arguments.
3501 Therefore code like
3502 set(var1 OFF)
3505 set(var2 "var1")
3506 if(${var2})
3507 appears to the if command as
3509 if(var1)
3512 and is evaluated according to the if(<variable>) case documented
3514 above. The result is OFF which is false. However, if we remove
3515 the ${} from the example then the command sees
3516 if(var2)
3519 which is true because var2 is defined to "var1" which is not a
3521 false constant.
3522 Automatic evaluation applies in the other cases whenever the
3525 above-documented signature accepts <variable|string>:
3526 1) The left hand argument to MATCHES is first checked to see if
3529 it is a defined variable, if so the variable's value is used,
3530 otherwise the original value is used.
3531 2) If the left hand argument to MATCHES is missing it returns
3534 false without error
3535 3) Both left and right hand arguments to LESS GREATER EQUAL are
3538 independently tested to see if they are defined variables, if so
3539 their defined values are used otherwise the original value is
3540 used.
3541 4) Both left and right hand arguments to STRLESS STREQUAL STR‐
3544 GREATER are independently tested to see if they are defined
3545 variables, if so their defined values are used otherwise the
3546 original value is used.
3547 5) Both left and right hand argumemnts to VERSION_LESS VER‐
3550 SION_EQUAL VERSION_GREATER are independently tested to see if
3551 they are defined variables, if so their defined values are used
3552 otherwise the original value is used.
3553 6) The right hand argument to NOT is tested to see if it is a
3556 boolean constant, if so the value is used, otherwise it is
3557 assumed to be a variable and it is dereferenced.
3558 7) The left and right hand arguments to AND OR are independently
3561 tested to see if they are boolean constants, if so they are used
3562 as such, otherwise they are assumed to be variables and are
3563 dereferenced.
3564 include
3568 Load and run CMake code from a file or module.
3569 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
3571 [NO_POLICY_SCOPE])
3572 Load and run CMake code from the file given. Variable reads and
3574 writes access the scope of the caller (dynamic scoping). If
3575 OPTIONAL is present, then no error is raised if the file does
3576 not exist. If RESULT_VARIABLE is given the variable will be set
3577 to the full filename which has been included or NOTFOUND if it
3578 failed.
3579 If a module is specified instead of a file, the file with name
3582 <modulename>.cmake is searched first in CMAKE_MODULE_PATH, then
3583 in the CMake module directory. There is one exception to this:
3584 if the file which calls include() is located itself in the CMake
3585 module directory, then first the CMake module directory is
3586 searched and CMAKE_MODULE_PATH afterwards. See also policy
3587 CMP0017.
3588 See the cmake_policy() command documentation for discussion of
3591 the NO_POLICY_SCOPE option.
3592 include_directories
3595 Add include directories to the build.
3596 include_directories([AFTER|BEFORE] [SYSTEM] dir1 dir2 ...)
3598 Add the given directories to those the compiler uses to search
3600 for include files. Relative paths are interpreted as relative
3601 to the current source directory.
3602 The include directories are added to the directory property
3605 INCLUDE_DIRECTORIES for the current CMakeLists file. They are
3606 also added to the target property INCLUDE_DIRECTORIES for each
3607 target in the current CMakeLists file. The target property val‐
3608 ues are the ones used by the generators.
3609 By default the directories are appended onto the current list of
3612 directories. This default behavior can be changed by setting
3613 CMAKE_INCLUDE_DIRECTORIES_BEFORE to ON. By using AFTER or BEFORE
3614 explicitly, you can select between appending and prepending,
3615 independent of the default.
3616 If the SYSTEM option is given, the compiler will be told the
3619 directories are meant as system include directories on some
3620 platforms (signalling this setting might achieve effects such as
3621 the compiler skipping warnings, or these fixed-install system
3622 files not being considered in dependency calculations - see com‐
3623 piler docs).
3624 include_external_msproject
3627 Include an external Microsoft project file in a workspace.
3628 include_external_msproject(projectname location
3630 [TYPE projectTypeGUID]
3631 [GUID projectGUID]
3632 [PLATFORM platformName]
3633 dep1 dep2 ...)
3634 Includes an external Microsoft project in the generated
3636 workspace file. Currently does nothing on UNIX. This will cre‐
3637 ate a target named [projectname]. This can be used in the
3638 add_dependencies command to make things depend on the external
3639 project.
3640 TYPE, GUID and PLATFORM are optional parameters that allow one
3643 to specify the type of project, id (GUID) of the project and the
3644 name of the target platform. This is useful for projects
3645 requiring values other than the default (e.g. WIX projects).
3646 These options are not supported by the Visual Studio 6 genera‐
3647 tor.
3648 include_regular_expression
3651 Set the regular expression used for dependency checking.
3652 include_regular_expression(regex_match [regex_complain])
3654 Set the regular expressions used in dependency checking. Only
3656 files matching regex_match will be traced as dependencies. Only
3657 files matching regex_complain will generate warnings if they
3658 cannot be found (standard header paths are not searched). The
3659 defaults are:
3660 regex_match = "^.*$" (match everything)
3663 regex_complain = "^$" (match empty string only)
3664 install
3667 Specify rules to run at install time.
3668 This command generates installation rules for a project. Rules
3670 specified by calls to this command within a source directory are
3671 executed in order during installation. The order across direc‐
3672 tories is not defined.
3673 There are multiple signatures for this command. Some of them
3676 define installation properties for files and targets. Proper‐
3677 ties common to multiple signatures are covered here but they are
3678 valid only for signatures that specify them.
3679 DESTINATION arguments specify the directory on disk to which a
3682 file will be installed. If a full path (with a leading slash or
3683 drive letter) is given it is used directly. If a relative path
3684 is given it is interpreted relative to the value of
3685 CMAKE_INSTALL_PREFIX. The prefix can be relocated at install
3686 time using DESTDIR mechanism explained in the CMAKE_INSTALL_PRE‐
3687 FIX variable documentation.
3688 PERMISSIONS arguments specify permissions for installed files.
3691 Valid permissions are OWNER_READ, OWNER_WRITE, OWNER_EXECUTE,
3692 GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE,
3693 WORLD_EXECUTE, SETUID, and SETGID. Permissions that do not make
3694 sense on certain platforms are ignored on those platforms.
3695 The CONFIGURATIONS argument specifies a list of build configura‐
3698 tions for which the install rule applies (Debug, Release, etc.).
3699 The COMPONENT argument specifies an installation component name
3702 with which the install rule is associated, such as "runtime" or
3703 "development". During component-specific installation only
3704 install rules associated with the given component name will be
3705 executed. During a full installation all components are
3706 installed. If COMPONENT is not provided a default component
3707 "Unspecified" is created. The default component name may be con‐
3708 trolled with the CMAKE_INSTALL_DEFAULT_COMPONENT_NAME variable.
3709 The RENAME argument specifies a name for an installed file that
3712 may be different from the original file. Renaming is allowed
3713 only when a single file is installed by the command.
3714 The OPTIONAL argument specifies that it is not an error if the
3717 file to be installed does not exist.
3718 The TARGETS signature:
3721 install(TARGETS targets... [EXPORT <export-name>]
3724 [[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE|
3725 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
3726 [DESTINATION <dir>]
3727 [INCLUDES DESTINATION [<dir> ...]]
3728 [PERMISSIONS permissions...]
3729 [CONFIGURATIONS [Debug|Release|...]]
3730 [COMPONENT <component>]
3731 [OPTIONAL] [NAMELINK_ONLY|NAMELINK_SKIP]
3732 ] [...])
3733 The TARGETS form specifies rules for installing targets from a
3735 project. There are five kinds of target files that may be
3736 installed: ARCHIVE, LIBRARY, RUNTIME, FRAMEWORK, and BUNDLE.
3737 Executables are treated as RUNTIME targets, except that those
3738 marked with the MACOSX_BUNDLE property are treated as BUNDLE
3739 targets on OS X. Static libraries are always treated as ARCHIVE
3740 targets. Module libraries are always treated as LIBRARY targets.
3741 For non-DLL platforms shared libraries are treated as LIBRARY
3742 targets, except that those marked with the FRAMEWORK property
3743 are treated as FRAMEWORK targets on OS X. For DLL platforms the
3744 DLL part of a shared library is treated as a RUNTIME target and
3745 the corresponding import library is treated as an ARCHIVE tar‐
3746 get. All Windows-based systems including Cygwin are DLL plat‐
3747 forms. The ARCHIVE, LIBRARY, RUNTIME, and FRAMEWORK arguments
3748 change the type of target to which the subsequent properties
3749 apply. If none is given the installation properties apply to
3750 all target types. If only one is given then only targets of
3751 that type will be installed (which can be used to install just a
3752 DLL or just an import library).The INCLUDES DESTINATION speci‐
3753 fies a list of directories which will be added to the INTER‐
3754 FACE_INCLUDE_DIRECTORIES of the <targets> when exported by
3755 install(EXPORT). If a relative path is specified, it is treated
3756 as relative to the $<INSTALL_PREFIX>.
3757 The PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE arguments cause
3760 subsequent properties to be applied to installing a FRAMEWORK
3761 shared library target's associated files on non-Apple platforms.
3762 Rules defined by these arguments are ignored on Apple platforms
3763 because the associated files are installed into the appropriate
3764 locations inside the framework folder. See documentation of the
3765 PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE target properties
3766 for details.
3767 Either NAMELINK_ONLY or NAMELINK_SKIP may be specified as a
3770 LIBRARY option. On some platforms a versioned shared library
3771 has a symbolic link such as
3772 lib<name>.so -> lib<name>.so.1
3775 where "lib<name>.so.1" is the soname of the library and
3777 "lib<name>.so" is a "namelink" allowing linkers to find the
3778 library when given "-l<name>". The NAMELINK_ONLY option causes
3779 installation of only the namelink when a library target is
3780 installed. The NAMELINK_SKIP option causes installation of
3781 library files other than the namelink when a library target is
3782 installed. When neither option is given both portions are
3783 installed. On platforms where versioned shared libraries do not
3784 have namelinks or when a library is not versioned the
3785 NAMELINK_SKIP option installs the library and the NAMELINK_ONLY
3786 option installs nothing. See the VERSION and SOVERSION target
3787 properties for details on creating versioned shared libraries.
3788 One or more groups of properties may be specified in a single
3791 call to the TARGETS form of this command. A target may be
3792 installed more than once to different locations. Consider hypo‐
3793 thetical targets "myExe", "mySharedLib", and "myStaticLib". The
3794 code
3795 install(TARGETS myExe mySharedLib myStaticLib
3798 RUNTIME DESTINATION bin
3799 LIBRARY DESTINATION lib
3800 ARCHIVE DESTINATION lib/static)
3801 install(TARGETS mySharedLib DESTINATION /some/full/path)
3802 will install myExe to <prefix>/bin and myStaticLib to <pre‐
3804 fix>/lib/static. On non-DLL platforms mySharedLib will be
3805 installed to <prefix>/lib and /some/full/path. On DLL platforms
3806 the mySharedLib DLL will be installed to <prefix>/bin and
3807 /some/full/path and its import library will be installed to
3808 <prefix>/lib/static and /some/full/path.
3809 The EXPORT option associates the installed target files with an
3812 export called <export-name>. It must appear before any RUNTIME,
3813 LIBRARY, or ARCHIVE options. To actually install the export
3814 file itself, call install(EXPORT). See documentation of the
3815 install(EXPORT ...) signature below for details.
3816 Installing a target with EXCLUDE_FROM_ALL set to true has unde‐
3819 fined behavior.
3820 The FILES signature:
3823 install(FILES files... DESTINATION <dir>
3826 [PERMISSIONS permissions...]
3827 [CONFIGURATIONS [Debug|Release|...]]
3828 [COMPONENT <component>]
3829 [RENAME <name>] [OPTIONAL])
3830 The FILES form specifies rules for installing files for a
3832 project. File names given as relative paths are interpreted
3833 with respect to the current source directory. Files installed
3834 by this form are by default given permissions OWNER_WRITE,
3835 OWNER_READ, GROUP_READ, and WORLD_READ if no PERMISSIONS argu‐
3836 ment is given.
3837 The PROGRAMS signature:
3840 install(PROGRAMS files... DESTINATION <dir>
3843 [PERMISSIONS permissions...]
3844 [CONFIGURATIONS [Debug|Release|...]]
3845 [COMPONENT <component>]
3846 [RENAME <name>] [OPTIONAL])
3847 The PROGRAMS form is identical to the FILES form except that the
3849 default permissions for the installed file also include
3850 OWNER_EXECUTE, GROUP_EXECUTE, and WORLD_EXECUTE. This form is
3851 intended to install programs that are not targets, such as shell
3852 scripts. Use the TARGETS form to install targets built within
3853 the project.
3854 The DIRECTORY signature:
3857 install(DIRECTORY dirs... DESTINATION <dir>
3860 [FILE_PERMISSIONS permissions...]
3861 [DIRECTORY_PERMISSIONS permissions...]
3862 [USE_SOURCE_PERMISSIONS] [OPTIONAL]
3863 [CONFIGURATIONS [Debug|Release|...]]
3864 [COMPONENT <component>] [FILES_MATCHING]
3865 [[PATTERN <pattern> | REGEX <regex>]
3866 [EXCLUDE] [PERMISSIONS permissions...]] [...])
3867 The DIRECTORY form installs contents of one or more directories
3869 to a given destination. The directory structure is copied ver‐
3870 batim to the destination. The last component of each directory
3871 name is appended to the destination directory but a trailing
3872 slash may be used to avoid this because it leaves the last com‐
3873 ponent empty. Directory names given as relative paths are
3874 interpreted with respect to the current source directory. If no
3875 input directory names are given the destination directory will
3876 be created but nothing will be installed into it. The FILE_PER‐
3877 MISSIONS and DIRECTORY_PERMISSIONS options specify permissions
3878 given to files and directories in the destination. If
3879 USE_SOURCE_PERMISSIONS is specified and FILE_PERMISSIONS is not,
3880 file permissions will be copied from the source directory struc‐
3881 ture. If no permissions are specified files will be given the
3882 default permissions specified in the FILES form of the command,
3883 and the directories will be given the default permissions speci‐
3884 fied in the PROGRAMS form of the command.
3885 Installation of directories may be controlled with fine granu‐
3888 larity using the PATTERN or REGEX options. These "match"
3889 options specify a globbing pattern or regular expression to
3890 match directories or files encountered within input directories.
3891 They may be used to apply certain options (see below) to a sub‐
3892 set of the files and directories encountered. The full path to
3893 each input file or directory (with forward slashes) is matched
3894 against the expression. A PATTERN will match only complete file
3895 names: the portion of the full path matching the pattern must
3896 occur at the end of the file name and be preceded by a slash. A
3897 REGEX will match any portion of the full path but it may use '/'
3898 and '$' to simulate the PATTERN behavior. By default all files
3899 and directories are installed whether or not they are matched.
3900 The FILES_MATCHING option may be given before the first match
3901 option to disable installation of files (but not directories)
3902 not matched by any expression. For example, the code
3903 install(DIRECTORY src/ DESTINATION include/myproj
3906 FILES_MATCHING PATTERN "*.h")
3907 will extract and install header files from a source tree.
3909 Some options may follow a PATTERN or REGEX expression and are
3912 applied only to files or directories matching them. The EXCLUDE
3913 option will skip the matched file or directory. The PERMISSIONS
3914 option overrides the permissions setting for the matched file or
3915 directory. For example the code
3916 install(DIRECTORY icons scripts/ DESTINATION share/myproj
3919 PATTERN "CVS" EXCLUDE
3920 PATTERN "scripts/*"
3921 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
3922 GROUP_EXECUTE GROUP_READ)
3923 will install the icons directory to share/myproj/icons and the
3925 scripts directory to share/myproj. The icons will get default
3926 file permissions, the scripts will be given specific permis‐
3927 sions, and any CVS directories will be excluded.
3928 The SCRIPT and CODE signature:
3931 install([[SCRIPT <file>] [CODE <code>]] [...])
3934 The SCRIPT form will invoke the given CMake script files during
3936 installation. If the script file name is a relative path it
3937 will be interpreted with respect to the current source direc‐
3938 tory. The CODE form will invoke the given CMake code during
3939 installation. Code is specified as a single argument inside a
3940 double-quoted string. For example, the code
3941 install(CODE "MESSAGE(\"Sample install message.\")")
3944 will print a message during installation.
3946 The EXPORT signature:
3949 install(EXPORT <export-name> DESTINATION <dir>
3952 [NAMESPACE <namespace>] [FILE <name>.cmake]
3953 [PERMISSIONS permissions...]
3954 [CONFIGURATIONS [Debug|Release|...]]
3955 [EXPORT_LINK_INTERFACE_LIBRARIES]
3956 [COMPONENT <component>])
3957 The EXPORT form generates and installs a CMake file containing
3959 code to import targets from the installation tree into another
3960 project. Target installations are associated with the export
3961 <export-name> using the EXPORT option of the install(TARGETS
3962 ...) signature documented above. The NAMESPACE option will
3963 prepend <namespace> to the target names as they are written to
3964 the import file. By default the generated file will be called
3965 <export-name>.cmake but the FILE option may be used to specify a
3966 different name. The value given to the FILE option must be a
3967 file name with the ".cmake" extension. If a CONFIGURATIONS
3968 option is given then the file will only be installed when one of
3969 the named configurations is installed. Additionally, the gener‐
3970 ated import file will reference only the matching target config‐
3971 urations. The EXPORT_LINK_INTERFACE_LIBRARIES keyword, if
3972 present, causes the contents of the properties matching
3973 (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)? to be exported,
3974 when policy CMP0022 is NEW. If a COMPONENT option is specified
3975 that does not match that given to the targets associated with
3976 <export-name> the behavior is undefined. If a library target is
3977 included in the export but a target to which it links is not
3978 included the behavior is unspecified.
3979 The EXPORT form is useful to help outside projects use targets
3982 built and installed by the current project. For example, the
3983 code
3984 install(TARGETS myexe EXPORT myproj DESTINATION bin)
3987 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
3988 will install the executable myexe to <prefix>/bin and code to
3990 import it in the file "<prefix>/lib/myproj/myproj.cmake". An
3991 outside project may load this file with the include command and
3992 reference the myexe executable from the installation tree using
3993 the imported target name mp_myexe as if the target were built in
3994 its own tree.
3995 NOTE: This command supercedes the INSTALL_TARGETS command and
3998 the target properties PRE_INSTALL_SCRIPT and
3999 POST_INSTALL_SCRIPT. It also replaces the FILES forms of the
4000 INSTALL_FILES and INSTALL_PROGRAMS commands. The processing
4001 order of these install rules relative to those generated by
4002 INSTALL_TARGETS, INSTALL_FILES, and INSTALL_PROGRAMS commands is
4003 not defined.
4004 link_directories
4008 Specify directories in which the linker will look for libraries.
4009 link_directories(directory1 directory2 ...)
4011 Specify the paths in which the linker should search for
4013 libraries. The command will apply only to targets created after
4014 it is called. Relative paths given to this command are inter‐
4015 preted as relative to the current source directory, see CMP0015.
4016 Note that this command is rarely necessary. Library locations
4019 returned by find_package() and find_library() are absolute
4020 paths. Pass these absolute library file paths directly to the
4021 target_link_libraries() command. CMake will ensure the linker
4022 finds them.
4023 list List operations.
4026 list(LENGTH <list> <output variable>)
4028 list(GET <list> <element index> [<element index> ...]
4029 <output variable>)
4030 list(APPEND <list> <element> [<element> ...])
4031 list(FIND <list> <value> <output variable>)
4032 list(INSERT <list> <element_index> <element> [<element> ...])
4033 list(REMOVE_ITEM <list> <value> [<value> ...])
4034 list(REMOVE_AT <list> <index> [<index> ...])
4035 list(REMOVE_DUPLICATES <list>)
4036 list(REVERSE <list>)
4037 list(SORT <list>)
4038 LENGTH will return a given list's length.
4040 GET will return list of elements specified by indices from the
4043 list.
4044 APPEND will append elements to the list.
4047 FIND will return the index of the element specified in the list
4050 or -1 if it wasn't found.
4051 INSERT will insert elements to the list to the specified loca‐
4054 tion.
4055 REMOVE_AT and REMOVE_ITEM will remove items from the list. The
4058 difference is that REMOVE_ITEM will remove the given items,
4059 while REMOVE_AT will remove the items at the given indices.
4060 REMOVE_DUPLICATES will remove duplicated items in the list.
4063 REVERSE reverses the contents of the list in-place.
4066 SORT sorts the list in-place alphabetically.
4069 The list subcommands APPEND, INSERT, REMOVE_AT, REMOVE_ITEM,
4072 REMOVE_DUPLICATES, REVERSE and SORT may create new values for
4073 the list within the current CMake variable scope. Similar to the
4074 SET command, the LIST command creates new variable values in the
4075 current scope, even if the list itself is actually defined in a
4076 parent scope. To propagate the results of these operations
4077 upwards, use SET with PARENT_SCOPE, SET with CACHE INTERNAL, or
4078 some other means of value propagation.
4079 NOTES: A list in cmake is a ; separated group of strings. To
4082 create a list the set command can be used. For example, set(var
4083 a b c d e) creates a list with a;b;c;d;e, and set(var "a b c d
4084 e") creates a string or a list with one item in it.
4085 When specifying index values, if <element index> is 0 or
4088 greater, it is indexed from the beginning of the list, with 0
4089 representing the first list element. If <element index> is -1 or
4090 lesser, it is indexed from the end of the list, with -1 repre‐
4091 senting the last list element. Be careful when counting with
4092 negative indices: they do not start from 0. -0 is equivalent to
4093 0, the first list element.
4094 load_cache
4098 Load in the values from another project's CMake cache.
4099 load_cache(pathToCacheFile READ_WITH_PREFIX
4101 prefix entry1...)
4102 Read the cache and store the requested entries in variables with
4104 their name prefixed with the given prefix. This only reads the
4105 values, and does not create entries in the local project's
4106 cache.
4107 load_cache(pathToCacheFile [EXCLUDE entry1...]
4110 [INCLUDE_INTERNALS entry1...])
4111 Load in the values from another cache and store them in the
4113 local project's cache as internal entries. This is useful for a
4114 project that depends on another project built in a different
4115 tree. EXCLUDE option can be used to provide a list of entries
4116 to be excluded. INCLUDE_INTERNALS can be used to provide a list
4117 of internal entries to be included. Normally, no internal
4118 entries are brought in. Use of this form of the command is
4119 strongly discouraged, but it is provided for backward compati‐
4120 bility.
4121 load_command
4124 Load a command into a running CMake.
4125 load_command(COMMAND_NAME <loc1> [loc2 ...])
4127 The given locations are searched for a library whose name is
4129 cmCOMMAND_NAME. If found, it is loaded as a module and the com‐
4130 mand is added to the set of available CMake commands. Usually,
4131 TRY_COMPILE is used before this command to compile the module.
4132 If the command is successfully loaded a variable named
4133 CMAKE_LOADED_COMMAND_<COMMAND_NAME>
4136 will be set to the full path of the module that was loaded.
4138 Otherwise the variable will not be set.
4139 macro Start recording a macro for later invocation as a command.
4142 macro(<name> [arg1 [arg2 [arg3 ...]]])
4144 COMMAND1(ARGS ...)
4145 COMMAND2(ARGS ...)
4146 ...
4147 endmacro(<name>)
4148 Define a macro named <name> that takes arguments named arg1 arg2
4150 arg3 (...). Commands listed after macro, but before the match‐
4151 ing endmacro, are not invoked until the macro is invoked. When
4152 it is invoked, the commands recorded in the macro are first mod‐
4153 ified by replacing formal parameters (${arg1}) with the argu‐
4154 ments passed, and then invoked as normal commands. In addition
4155 to referencing the formal parameters you can reference the val‐
4156 ues ${ARGC} which will be set to the number of arguments passed
4157 into the function as well as ${ARGV0} ${ARGV1} ${ARGV2} ...
4158 which will have the actual values of the arguments passed in.
4159 This facilitates creating macros with optional arguments. Addi‐
4160 tionally ${ARGV} holds the list of all arguments given to the
4161 macro and ${ARGN} holds the list of arguments past the last
4162 expected argument. Note that the parameters to a macro and val‐
4163 ues such as ARGN are not variables in the usual CMake sense.
4164 They are string replacements much like the C preprocessor would
4165 do with a macro. If you want true CMake variables and/or better
4166 CMake scope control you should look at the function command.
4167 See the cmake_policy() command documentation for the behavior of
4170 policies inside macros.
4171 mark_as_advanced
4174 Mark cmake cached variables as advanced.
4175 mark_as_advanced([CLEAR|FORCE] VAR VAR2 VAR...)
4177 Mark the named cached variables as advanced. An advanced vari‐
4179 able will not be displayed in any of the cmake GUIs unless the
4180 show advanced option is on. If CLEAR is the first argument
4181 advanced variables are changed back to unadvanced. If FORCE is
4182 the first argument, then the variable is made advanced. If nei‐
4183 ther FORCE nor CLEAR is specified, new values will be marked as
4184 advanced, but if the variable already has an
4185 advanced/non-advanced state, it will not be changed.
4186 It does nothing in script mode.
4189 math Mathematical expressions.
4192 math(EXPR <output variable> <math expression>)
4194 EXPR evaluates mathematical expression and returns result in the
4196 output variable. Example mathematical expression is '5 * ( 10 +
4197 13 )'. Supported operators are + - * / % | & ^ ~ << >> * / %.
4198 They have the same meaning as they do in C code.
4199 message
4202 Display a message to the user.
4203 message([STATUS|WARNING|AUTHOR_WARNING|FATAL_ERROR|SEND_ERROR]
4205 "message to display" ...)
4206 The optional keyword determines the type of message:
4208 (none) = Important information
4211 STATUS = Incidental information
4212 WARNING = CMake Warning, continue processing
4213 AUTHOR_WARNING = CMake Warning (dev), continue processing
4214 SEND_ERROR = CMake Error, continue processing,
4215 but skip generation
4216 FATAL_ERROR = CMake Error, stop processing and generation
4217 The CMake command-line tool displays STATUS messages on stdout
4219 and all other message types on stderr. The CMake GUI displays
4220 all messages in its log area. The interactive dialogs (ccmake
4221 and CMakeSetup) show STATUS messages one at a time on a status
4222 line and other messages in interactive pop-up boxes.
4223 CMake Warning and Error message text displays using a simple
4226 markup language. Non-indented text is formatted in line-wrapped
4227 paragraphs delimited by newlines. Indented text is considered
4228 pre-formatted.
4229 option Provides an option that the user can optionally select.
4232 option(<option_variable> "help string describing option"
4234 [initial value])
4235 Provide an option for the user to select as ON or OFF. If no
4237 initial value is provided, OFF is used.
4238 If you have options that depend on the values of other options,
4241 see the module help for CMakeDependentOption.
4242 project
4245 Set a name for the entire project.
4246 project(<projectname> [languageName1 languageName2 ... ] )
4248 Sets the name of the project. Additionally this sets the vari‐
4250 ables <projectName>_BINARY_DIR and <projectName>_SOURCE_DIR to
4251 the respective values.
4252 Optionally you can specify which languages your project sup‐
4255 ports. Example languages are CXX (i.e. C++), C, Fortran, etc.
4256 By default C and CXX are enabled. E.g. if you do not have a C++
4257 compiler, you can disable the check for it by explicitly listing
4258 the languages you want to support, e.g. C. By using the special
4259 language "NONE" all checks for any language can be disabled. If
4260 a variable exists called CMAKE_PROJECT_<projectName>_INCLUDE,
4261 the file pointed to by that variable will be included as the
4262 last step of the project command.
4263 The top-level CMakeLists.txt file for a project must contain a
4266 literal, direct call to the project() command; loading one
4267 through the include() command is not sufficient. If no such
4268 call exists CMake will implicitly add one to the top that
4269 enables the default languages (C and CXX).
4270 qt_wrap_cpp
4273 Create Qt Wrappers.
4274 qt_wrap_cpp(resultingLibraryName DestName
4276 SourceLists ...)
4277 Produce moc files for all the .h files listed in the
4279 SourceLists. The moc files will be added to the library using
4280 the DestName source list.
4281 qt_wrap_ui
4284 Create Qt user interfaces Wrappers.
4285 qt_wrap_ui(resultingLibraryName HeadersDestName
4287 SourcesDestName SourceLists ...)
4288 Produce .h and .cxx files for all the .ui files listed in the
4290 SourceLists. The .h files will be added to the library using
4291 the HeadersDestNamesource list. The .cxx files will be added to
4292 the library using the SourcesDestNamesource list.
4293 remove_definitions
4296 Removes -D define flags added by add_definitions.
4297 remove_definitions(-DFOO -DBAR ...)
4299 Removes flags (added by add_definitions) from the compiler com‐
4301 mand line for sources in the current directory and below.
4302 return Return from a file, directory or function.
4305 return()
4307 Returns from a file, directory or function. When this command is
4309 encountered in an included file (via include() or find_pack‐
4310 age()), it causes processing of the current file to stop and
4311 control is returned to the including file. If it is encountered
4312 in a file which is not included by another file, e.g. a CMake‐
4313 Lists.txt, control is returned to the parent directory if there
4314 is one. If return is called in a function, control is returned
4315 to the caller of the function. Note that a macro is not a func‐
4316 tion and does not handle return like a function does.
4317 separate_arguments
4320 Parse space-separated arguments into a semicolon-separated list.
4321 separate_arguments(<var> <UNIX|WINDOWS>_COMMAND "<args>")
4323 Parses a unix- or windows-style command-line string "<args>" and
4325 stores a semicolon-separated list of the arguments in <var>.
4326 The entire command line must be given in one "<args>" argument.
4327 The UNIX_COMMAND mode separates arguments by unquoted white‐
4330 space. It recognizes both single-quote and double-quote pairs.
4331 A backslash escapes the next literal character (\" is "); there
4332 are no special escapes (\n is just n).
4333 The WINDOWS_COMMAND mode parses a windows command-line using the
4336 same syntax the runtime library uses to construct argv at
4337 startup. It separates arguments by whitespace that is not dou‐
4338 ble-quoted. Backslashes are literal unless they precede dou‐
4339 ble-quotes. See the MSDN article "Parsing C Command-Line Argu‐
4340 ments" for details.
4341 separate_arguments(VARIABLE)
4344 Convert the value of VARIABLE to a semi-colon separated list.
4346 All spaces are replaced with ';'. This helps with generating
4347 command lines.
4348 set Set a CMake, cache or environment variable to a given value.
4351 set(<variable> <value>
4353 [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])
4354 Within CMake sets <variable> to the value <value>. <value> is
4356 expanded before <variable> is set to it. Normally, set will set
4357 a regular CMake variable. If CACHE is present, then the <vari‐
4358 able> is put in the cache instead, unless it is already in the
4359 cache. See section 'Variable types in CMake' below for details
4360 of regular and cache variables and their interactions. If CACHE
4361 is used, <type> and <docstring> are required. <type> is used by
4362 the CMake GUI to choose a widget with which the user sets a
4363 value. The value for <type> may be one of
4364 FILEPATH = File chooser dialog.
4367 PATH = Directory chooser dialog.
4368 STRING = Arbitrary string.
4369 BOOL = Boolean ON/OFF checkbox.
4370 INTERNAL = No GUI entry (used for persistent variables).
4371 If <type> is INTERNAL, the cache variable is marked as internal,
4373 and will not be shown to the user in tools like cmake-gui. This
4374 is intended for values that should be persisted in the cache,
4375 but which users should not normally change. INTERNAL implies
4376 FORCE.
4377 Normally, set(...CACHE...) creates cache variables, but does not
4380 modify them. If FORCE is specified, the value of the cache vari‐
4381 able is set, even if the variable is already in the cache. This
4382 should normally be avoided, as it will remove any changes to the
4383 cache variable's value by the user.
4384 If PARENT_SCOPE is present, the variable will be set in the
4387 scope above the current scope. Each new directory or function
4388 creates a new scope. This command will set the value of a vari‐
4389 able into the parent directory or calling function (whichever is
4390 applicable to the case at hand). PARENT_SCOPE cannot be combined
4391 with CACHE.
4392 If <value> is not specified then the variable is removed instead
4395 of set. See also: the unset() command.
4396 set(<variable> <value1> ... <valueN>)
4399 In this case <variable> is set to a semicolon separated list of
4401 values.
4402 <variable> can be an environment variable such as:
4405 set( ENV{PATH} /home/martink )
4408 in which case the environment variable will be set.
4410 *** Variable types in CMake ***
4413 In CMake there are two types of variables: normal variables and
4416 cache variables. Normal variables are meant for the internal use
4417 of the script (just like variables in most programming lan‐
4418 guages); they are not persisted across CMake runs. Cache vari‐
4419 ables (unless set with INTERNAL) are mostly intended for config‐
4420 uration settings where the first CMake run determines a suitable
4421 default value, which the user can then override, by editing the
4422 cache with tools such as ccmake or cmake-gui. Cache variables
4423 are stored in the CMake cache file, and are persisted across
4424 CMake runs.
4425 Both types can exist at the same time with the same name but
4428 different values. When ${FOO} is evaluated, CMake first looks
4429 for a normal variable 'FOO' in scope and uses it if set. If and
4430 only if no normal variable exists then it falls back to the
4431 cache variable 'FOO'.
4432 Some examples:
4435 The code 'set(FOO "x")' sets the normal variable 'FOO'. It does
4438 not touch the cache, but it will hide any existing cache value
4439 'FOO'.
4440 The code 'set(FOO "x" CACHE ...)' checks for 'FOO' in the cache,
4443 ignoring any normal variable of the same name. If 'FOO' is in
4444 the cache then nothing happens to either the normal variable or
4445 the cache variable. If 'FOO' is not in the cache, then it is
4446 added to the cache.
4447 Finally, whenever a cache variable is added or modified by a
4450 command, CMake also *removes* the normal variable of the same
4451 name from the current scope so that an immediately following
4452 evaluation of it will expose the newly cached value.
4453 Normally projects should avoid using normal and cache variables
4456 of the same name, as this interaction can be hard to follow.
4457 However, in some situations it can be useful. One example (used
4458 by some projects):
4459 A project has a subproject in its source tree. The child project
4462 has its own CMakeLists.txt, which is included from the parent
4463 CMakeLists.txt using add_subdirectory(). Now, if the parent and
4464 the child project provide the same option (for example a com‐
4465 piler option), the parent gets the first chance to add a
4466 user-editable option to the cache. Normally, the child would
4467 then use the same value that the parent uses. However, it may be
4468 necessary to hard-code the value for the child project's option
4469 while still allowing the user to edit the value used by the par‐
4470 ent project. The parent project can achieve this simply by set‐
4471 ting a normal variable with the same name as the option in a
4472 scope sufficient to hide the option's cache variable from the
4473 child completely. The parent has already set the cache variable,
4474 so the child's set(...CACHE...) will do nothing, and evaluating
4475 the option variable will use the value from the normal variable,
4476 which hides the cache variable.
4477 set_directory_properties
4480 Set a property of the directory.
4481 set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
4483 Set a property for the current directory and subdirectories. If
4485 the property is not found, CMake will report an error. The prop‐
4486 erties include: INCLUDE_DIRECTORIES, LINK_DIRECTORIES,
4487 INCLUDE_REGULAR_EXPRESSION, and ADDITIONAL_MAKE_CLEAN_FILES.
4488 ADDITIONAL_MAKE_CLEAN_FILES is a list of files that will be
4489 cleaned as a part of "make clean" stage.
4490 set_property
4493 Set a named property in a given scope.
4494 set_property(<GLOBAL |
4496 DIRECTORY [dir] |
4497 TARGET [target1 [target2 ...]] |
4498 SOURCE [src1 [src2 ...]] |
4499 TEST [test1 [test2 ...]] |
4500 CACHE [entry1 [entry2 ...]]>
4501 [APPEND] [APPEND_STRING]
4502 PROPERTY <name> [value1 [value2 ...]])
4503 Set one property on zero or more objects of a scope. The first
4505 argument determines the scope in which the property is set. It
4506 must be one of the following:
4507 GLOBAL scope is unique and does not accept a name.
4510 DIRECTORY scope defaults to the current directory but another
4513 directory (already processed by CMake) may be named by full or
4514 relative path.
4515 TARGET scope may name zero or more existing targets.
4518 SOURCE scope may name zero or more source files. Note that
4521 source file properties are visible only to targets added in the
4522 same directory (CMakeLists.txt).
4523 TEST scope may name zero or more existing tests.
4526 CACHE scope must name zero or more cache existing entries.
4529 The required PROPERTY option is immediately followed by the name
4532 of the property to set. Remaining arguments are used to compose
4533 the property value in the form of a semicolon-separated list.
4534 If the APPEND option is given the list is appended to any exist‐
4535 ing property value.If the APPEND_STRING option is given the
4536 string is append to any existing property value as string, i.e.
4537 it results in a longer string and not a list of strings.
4538 set_source_files_properties
4541 Source files can have properties that affect how they are built.
4542 set_source_files_properties([file1 [file2 [...]]]
4544 PROPERTIES prop1 value1
4545 [prop2 value2 [...]])
4546 Set properties associated with source files using a key/value
4548 paired list. See properties documentation for those known to
4549 CMake. Unrecognized properties are ignored. Source file prop‐
4550 erties are visible only to targets added in the same directory
4551 (CMakeLists.txt).
4552 set_target_properties
4555 Targets can have properties that affect how they are built.
4556 set_target_properties(target1 target2 ...
4558 PROPERTIES prop1 value1
4559 prop2 value2 ...)
4560 Set properties on a target. The syntax for the command is to
4562 list all the files you want to change, and then provide the val‐
4563 ues you want to set next. You can use any prop value pair you
4564 want and extract it later with the GET_TARGET_PROPERTY command.
4565 Properties that affect the name of a target's output file are as
4568 follows. The PREFIX and SUFFIX properties override the default
4569 target name prefix (such as "lib") and suffix (such as ".so").
4570 IMPORT_PREFIX and IMPORT_SUFFIX are the equivalent properties
4571 for the import library corresponding to a DLL (for SHARED
4572 library targets). OUTPUT_NAME sets the real name of a target
4573 when it is built and can be used to help create two targets of
4574 the same name even though CMake requires unique logical target
4575 names. There is also a <CONFIG>_OUTPUT_NAME that can set the
4576 output name on a per-configuration basis. <CONFIG>_POSTFIX sets
4577 a postfix for the real name of the target when it is built under
4578 the configuration named by <CONFIG> (in upper-case, such as
4579 "DEBUG_POSTFIX"). The value of this property is initialized
4580 when the target is created to the value of the variable
4581 CMAKE_<CONFIG>_POSTFIX (except for executable targets because
4582 earlier CMake versions which did not use this variable for exe‐
4583 cutables).
4584 The LINK_FLAGS property can be used to add extra flags to the
4587 link step of a target. LINK_FLAGS_<CONFIG> will add to the con‐
4588 figuration <CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL,
4589 RELWITHDEBINFO. DEFINE_SYMBOL sets the name of the preprocessor
4590 symbol defined when compiling sources in a shared library. If
4591 not set here then it is set to target_EXPORTS by default (with
4592 some substitutions if the target is not a valid C identifier).
4593 This is useful for headers to know whether they are being
4594 included from inside their library or outside to properly setup
4595 dllexport/dllimport decorations. The COMPILE_FLAGS property sets
4596 additional compiler flags used to build sources within the tar‐
4597 get. It may also be used to pass additional preprocessor defi‐
4598 nitions.
4599 The LINKER_LANGUAGE property is used to change the tool used to
4602 link an executable or shared library. The default is set the
4603 language to match the files in the library. CXX and C are common
4604 values for this property.
4605 For shared libraries VERSION and SOVERSION can be used to spec‐
4608 ify the build version and API version respectively. When build‐
4609 ing or installing appropriate symlinks are created if the plat‐
4610 form supports symlinks and the linker supports so-names. If only
4611 one of both is specified the missing is assumed to have the same
4612 version number. For executables VERSION can be used to specify
4613 the build version. When building or installing appropriate sym‐
4614 links are created if the platform supports symlinks. For shared
4615 libraries and executables on Windows the VERSION attribute is
4616 parsed to extract a "major.minor" version number. These numbers
4617 are used as the image version of the binary.
4618 There are a few properties used to specify RPATH rules.
4621 INSTALL_RPATH is a semicolon-separated list specifying the rpath
4622 to use in installed targets (for platforms that support it).
4623 INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to true
4624 will append directories in the linker search path and outside
4625 the project to the INSTALL_RPATH. SKIP_BUILD_RPATH is a boolean
4626 specifying whether to skip automatic generation of an rpath
4627 allowing the target to run from the build tree.
4628 BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link
4629 the target in the build tree with the INSTALL_RPATH. This takes
4630 precedence over SKIP_BUILD_RPATH and avoids the need for relink‐
4631 ing before installation. INSTALL_NAME_DIR is a string specify‐
4632 ing the directory portion of the "install_name" field of shared
4633 libraries on Mac OSX to use in the installed targets. When the
4634 target is created the values of the variables
4635 CMAKE_INSTALL_RPATH, CMAKE_INSTALL_RPATH_USE_LINK_PATH,
4636 CMAKE_SKIP_BUILD_RPATH, CMAKE_BUILD_WITH_INSTALL_RPATH, and
4637 CMAKE_INSTALL_NAME_DIR are used to initialize these properties.
4638 PROJECT_LABEL can be used to change the name of the target in an
4641 IDE like visual studio. VS_KEYWORD can be set to change the
4642 visual studio keyword, for example Qt integration works better
4643 if this is set to Qt4VSv1.0.
4644 VS_SCC_PROJECTNAME, VS_SCC_LOCALPATH, VS_SCC_PROVIDER and
4647 VS_SCC_AUXPATH can be set to add support for source control
4648 bindings in a Visual Studio project file.
4649 VS_GLOBAL_<variable> can be set to add a Visual Studio
4652 project-specific global variable. Qt integration works better if
4653 VS_GLOBAL_QtVersion is set to the Qt version FindQt4.cmake
4654 found. For example, "4.7.3"
4655 The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are
4658 the old way to specify CMake scripts to run before and after
4659 installing a target. They are used only when the old
4660 INSTALL_TARGETS command is used to install the target. Use the
4661 INSTALL command instead.
4662 The EXCLUDE_FROM_DEFAULT_BUILD property is used by the visual
4665 studio generators. If it is set to 1 the target will not be
4666 part of the default build when you select "Build Solution". This
4667 can also be set on a per-configuration basis using
4668 EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>.
4669 set_tests_properties
4672 Set a property of the tests.
4673 set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
4675 Set a property for the tests. If the property is not found,
4677 CMake will report an error. The properties include:
4678 WILL_FAIL: If set to true, this will invert the pass/fail flag
4681 of the test.
4682 PASS_REGULAR_EXPRESSION: If set, the test output will be checked
4685 against the specified regular expressions and at least one of
4686 the regular expressions has to match, otherwise the test will
4687 fail.
4688 Example: PASS_REGULAR_EXPRESSION "TestPassed;All ok"
4691 FAIL_REGULAR_EXPRESSION: If set, if the output will match to one
4693 of specified regular expressions, the test will fail.
4694 Example: PASS_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed"
4697 Both PASS_REGULAR_EXPRESSION and FAIL_REGULAR_EXPRESSION expect
4699 a list of regular expressions.
4700 TIMEOUT: Setting this will limit the test runtime to the number
4703 of seconds specified.
4704 site_name
4708 Set the given variable to the name of the computer.
4709 site_name(variable)
4711 source_group
4714 Define a grouping for sources in the makefile.
4715 source_group(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])
4717 Defines a group into which sources will be placed in project
4719 files. This is mainly used to setup file tabs in Visual Studio.
4720 Any file whose name is listed or matches the regular expression
4721 will be placed in this group. If a file matches multiple
4722 groups, the LAST group that explicitly lists the file will be
4723 favored, if any. If no group explicitly lists the file, the
4724 LAST group whose regular expression matches the file will be
4725 favored.
4726 The name of the group may contain backslashes to specify sub‐
4729 groups:
4730 source_group(outer\\inner ...)
4733 For backwards compatibility, this command also supports the for‐
4735 mat:
4736 source_group(name regex)
4739 string String operations.
4742 string(REGEX MATCH <regular_expression>
4744 <output variable> <input> [<input>...])
4745 string(REGEX MATCHALL <regular_expression>
4746 <output variable> <input> [<input>...])
4747 string(REGEX REPLACE <regular_expression>
4748 <replace_expression> <output variable>
4749 <input> [<input>...])
4750 string(REPLACE <match_string>
4751 <replace_string> <output variable>
4752 <input> [<input>...])
4753 string(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512>
4754 <output variable> <input>)
4755 string(COMPARE EQUAL <string1> <string2> <output variable>)
4756 string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
4757 string(COMPARE LESS <string1> <string2> <output variable>)
4758 string(COMPARE GREATER <string1> <string2> <output variable>)
4759 string(ASCII <number> [<number> ...] <output variable>)
4760 string(CONFIGURE <string1> <output variable>
4761 [@ONLY] [ESCAPE_QUOTES])
4762 string(TOUPPER <string1> <output variable>)
4763 string(TOLOWER <string1> <output variable>)
4764 string(LENGTH <string> <output variable>)
4765 string(SUBSTRING <string> <begin> <length> <output variable>)
4766 string(STRIP <string> <output variable>)
4767 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
4768 [RANDOM_SEED <seed>] <output variable>)
4769 string(FIND <string> <substring> <output variable> [REVERSE])
4770 string(TIMESTAMP <output variable> [<format string>] [UTC])
4771 string(MAKE_C_IDENTIFIER <input string> <output variable>)
4772 REGEX MATCH will match the regular expression once and store the
4774 match in the output variable.
4775 REGEX MATCHALL will match the regular expression as many times
4778 as possible and store the matches in the output variable as a
4779 list.
4780 REGEX REPLACE will match the regular expression as many times as
4783 possible and substitute the replacement expression for the match
4784 in the output. The replace expression may refer to paren-delim‐
4785 ited subexpressions of the match using \1, \2, ..., \9. Note
4786 that two backslashes (\\1) are required in CMake code to get a
4787 backslash through argument parsing.
4788 REPLACE will replace all occurrences of match_string in the
4791 input with replace_string and store the result in the output.
4792 MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a
4795 cryptographic hash of the input string.
4796 COMPARE EQUAL/NOTEQUAL/LESS/GREATER will compare the strings and
4799 store true or false in the output variable.
4800 ASCII will convert all numbers into corresponding ASCII charac‐
4803 ters.
4804 CONFIGURE will transform a string like CONFIGURE_FILE transforms
4807 a file.
4808 TOUPPER/TOLOWER will convert string to upper/lower characters.
4811 LENGTH will return a given string's length.
4814 SUBSTRING will return a substring of a given string. If length
4817 is -1 the remainder of the string starting at begin will be
4818 returned.
4819 STRIP will return a substring of a given string with leading and
4822 trailing spaces removed.
4823 RANDOM will return a random string of given length consisting of
4826 characters from the given alphabet. Default length is 5 charac‐
4827 ters and default alphabet is all numbers and upper and lower
4828 case letters. If an integer RANDOM_SEED is given, its value
4829 will be used to seed the random number generator.
4830 FIND will return the position where the given substring was
4833 found in the supplied string. If the REVERSE flag was used, the
4834 command will search for the position of the last occurrence of
4835 the specified substring.
4836 The following characters have special meaning in regular expres‐
4839 sions:
4840 ^ Matches at beginning of input
4843 $ Matches at end of input
4844 . Matches any single character
4845 [ ] Matches any character(s) inside the brackets
4846 [^ ] Matches any character(s) not inside the brackets
4847 - Inside brackets, specifies an inclusive range between
4848 characters on either side e.g. [a-f] is [abcdef]
4849 To match a literal - using brackets, make it the first
4850 or the last character e.g. [+*/-] matches basic
4851 mathematical operators.
4852 * Matches preceding pattern zero or more times
4853 + Matches preceding pattern one or more times
4854 ? Matches preceding pattern zero or once only
4855 | Matches a pattern on either side of the |
4856 () Saves a matched subexpression, which can be referenced
4857 in the REGEX REPLACE operation. Additionally it is saved
4858 by all regular expression-related commands, including
4859 e.g. if( MATCHES ), in the variables CMAKE_MATCH_(0..9).
4860 *, + and ? have higher precedence than concatenation. | has
4862 lower precedence than concatenation. This means that the regular
4863 expression "^ab+d$" matches "abbd" but not "ababd", and the reg‐
4864 ular expression "^(ab|cd)$" matches "ab" but not "abd".
4865 TIMESTAMP will write a string representation of the current date
4868 and/or time to the output variable.
4869 Should the command be unable to obtain a timestamp the output
4872 variable will be set to the empty string "".
4873 The optional UTC flag requests the current date/time representa‐
4876 tion to be in Coordinated Universal Time (UTC) rather than local
4877 time.
4878 The optional <format string> may contain the following format
4881 specifiers:
4882 %d The day of the current month (01-31).
4885 %H The hour on a 24-hour clock (00-23).
4886 %I The hour on a 12-hour clock (01-12).
4887 %j The day of the current year (001-366).
4888 %m The month of the current year (01-12).
4889 %M The minute of the current hour (00-59).
4890 %S The second of the current minute.
4891 60 represents a leap second. (00-60)
4892 %U The week number of the current year (00-53).
4893 %w The day of the current week. 0 is Sunday. (0-6)
4894 %y The last two digits of the current year (00-99)
4895 %Y The current year.
4896 Unknown format specifiers will be ignored and copied to the out‐
4898 put as-is.
4899 If no explicit <format string> is given it will default to:
4902 %Y-%m-%dT%H:%M:%S for local time.
4905 %Y-%m-%dT%H:%M:%SZ for UTC.
4906 MAKE_C_IDENTIFIER will write a string which can be used as an
4908 identifier in C.
4909 target_compile_definitions
4912 Add compile definitions to a target.
4913 target_compile_definitions(<target> <INTERFACE|PUBLIC|PRIVATE> [items1...]
4915 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
4916 Specify compile definitions to use when compiling a given tar‐
4918 get. The named <target> must have been created by a command
4919 such as add_executable or add_library and must not be an
4920 IMPORTED target. The INTERFACE, PUBLIC and PRIVATE keywords are
4921 required to specify the scope of the following arguments. PRI‐
4922 VATE and PUBLIC items will populate the COMPILE_DEFINITIONS
4923 property of <target>. PUBLIC and INTERFACE items will populate
4924 the INTERFACE_COMPILE_DEFINITIONS property of <target>. The
4925 following arguments specify compile definitions. Repeated calls
4926 for the same <target> append items in the order called.
4927 Arguments to target_compile_definitions may use "generator
4930 expressions" with the syntax "$<...>". Generator expressions
4931 are evaluated during build system generation to produce informa‐
4932 tion specific to each build configuration. Valid expressions
4933 are:
4934 $<0:...> = empty string (ignores "...")
4937 $<1:...> = content of "..."
4938 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
4939 $<CONFIGURATION> = configuration name
4940 $<BOOL:...> = '1' if the '...' is true, else '0'
4941 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
4942 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
4943 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
4944 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
4945 $<JOIN:list,...> = joins the list with the content of "..."
4946 $<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.
4947 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
4948 $<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.
4949 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
4950 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
4951 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
4952 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
4953 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
4954 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
4955 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
4956 $<C_COMPILER_VERSION> = The version of the C compiler used.
4957 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
4958 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
4959 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
4960 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
4961 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
4962 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
4963 where "tgt" is the name of a target. Target file expressions
4965 produce a full path, but _DIR and _NAME versions can produce the
4966 directory and file name components:
4967 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
4970 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
4971 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
4972 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
4977 Note that tgt is not added as a dependency of the target this
4979 expression is evaluated on.
4980 $<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.
4983 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
4984 Boolean expressions:
4986 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
4989 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
4990 $<NOT:?> = '0' if '?' is '1', else '1'
4991 where '?' is always either '0' or '1'.
4993 Expressions with an implicit 'this' target:
4996 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
4999 target_compile_options
5002 Add compile options to a target.
5003 target_compile_options(<target> [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...]
5005 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
5006 Specify compile options to use when compiling a given target.
5008 The named <target> must have been created by a command such as
5009 add_executable or add_library and must not be an IMPORTED tar‐
5010 get. If BEFORE is specified, the content will be prepended to
5011 the property instead of being appended.
5012 The INTERFACE, PUBLIC and PRIVATE keywords are required to spec‐
5015 ify the scope of the following arguments. PRIVATE and PUBLIC
5016 items will populate the COMPILE_OPTIONS property of <target>.
5017 PUBLIC and INTERFACE items will populate the INTERFACE_COM‐
5018 PILE_OPTIONS property of <target>. The following arguments
5019 specify compile opitions. Repeated calls for the same <target>
5020 append items in the order called.
5021 Arguments to target_compile_options may use "generator expres‐
5024 sions" with the syntax "$<...>". Generator expressions are
5025 evaluated during build system generation to produce information
5026 specific to each build configuration. Valid expressions are:
5027 $<0:...> = empty string (ignores "...")
5030 $<1:...> = content of "..."
5031 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
5032 $<CONFIGURATION> = configuration name
5033 $<BOOL:...> = '1' if the '...' is true, else '0'
5034 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
5035 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
5036 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
5037 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
5038 $<JOIN:list,...> = joins the list with the content of "..."
5039 $<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.
5040 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
5041 $<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.
5042 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
5043 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
5044 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
5045 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
5046 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
5047 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
5048 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
5049 $<C_COMPILER_VERSION> = The version of the C compiler used.
5050 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
5051 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
5052 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
5053 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
5054 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
5055 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
5056 where "tgt" is the name of a target. Target file expressions
5058 produce a full path, but _DIR and _NAME versions can produce the
5059 directory and file name components:
5060 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
5063 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
5064 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
5065 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
5070 Note that tgt is not added as a dependency of the target this
5072 expression is evaluated on.
5073 $<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.
5076 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
5077 Boolean expressions:
5079 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
5082 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
5083 $<NOT:?> = '0' if '?' is '1', else '1'
5084 where '?' is always either '0' or '1'.
5086 Expressions with an implicit 'this' target:
5089 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
5092 target_include_directories
5095 Add include directories to a target.
5096 target_include_directories(<target> [SYSTEM] [BEFORE] <INTERFACE|PUBLIC|PRIVATE> [items1...]
5098 [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
5099 Specify include directories or targets to use when compiling a
5101 given target. The named <target> must have been created by a
5102 command such as add_executable or add_library and must not be an
5103 IMPORTED target.
5104 If BEFORE is specified, the content will be prepended to the
5107 property instead of being appended.
5108 The INTERFACE, PUBLIC and PRIVATE keywords are required to spec‐
5111 ify the scope of the following arguments. PRIVATE and PUBLIC
5112 items will populate the INCLUDE_DIRECTORIES property of <tar‐
5113 get>. PUBLIC and INTERFACE items will populate the INTER‐
5114 FACE_INCLUDE_DIRECTORIES property of <target>. The following
5115 arguments specify include directories. Specified include direc‐
5116 tories may be absolute paths or relative paths. Repeated calls
5117 for the same <target> append items in the order called.If SYSTEM
5118 is specified, the compiler will be told the directories are
5119 meant as system include directories on some platforms (sig‐
5120 nalling this setting might achieve effects such as the compiler
5121 skipping warnings, or these fixed-install system files not being
5122 considered in dependency calculations - see compiler docs). If
5123 SYSTEM is used together with PUBLIC or INTERFACE, the INTER‐
5124 FACE_SYSTEM_INCLUDE_DIRECTORIES target property will be popu‐
5125 lated with the specified directories.
5126 Arguments to target_include_directories may use "generator
5129 expressions" with the syntax "$<...>". Generator expressions
5130 are evaluated during build system generation to produce informa‐
5131 tion specific to each build configuration. Valid expressions
5132 are:
5133 $<0:...> = empty string (ignores "...")
5136 $<1:...> = content of "..."
5137 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
5138 $<CONFIGURATION> = configuration name
5139 $<BOOL:...> = '1' if the '...' is true, else '0'
5140 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
5141 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
5142 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
5143 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
5144 $<JOIN:list,...> = joins the list with the content of "..."
5145 $<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.
5146 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
5147 $<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.
5148 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
5149 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
5150 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
5151 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
5152 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
5153 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
5154 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
5155 $<C_COMPILER_VERSION> = The version of the C compiler used.
5156 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
5157 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
5158 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
5159 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
5160 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
5161 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
5162 where "tgt" is the name of a target. Target file expressions
5164 produce a full path, but _DIR and _NAME versions can produce the
5165 directory and file name components:
5166 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
5169 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
5170 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
5171 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
5176 Note that tgt is not added as a dependency of the target this
5178 expression is evaluated on.
5179 $<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.
5182 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
5183 Boolean expressions:
5185 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
5188 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
5189 $<NOT:?> = '0' if '?' is '1', else '1'
5190 where '?' is always either '0' or '1'.
5192 Expressions with an implicit 'this' target:
5195 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
5198 target_link_libraries
5201 Link a target to given libraries.
5202 target_link_libraries(<target> [item1 [item2 [...]]]
5204 [[debug|optimized|general] <item>] ...)
5205 Specify libraries or flags to use when linking a given target.
5207 The named <target> must have been created in the current direc‐
5208 tory by a command such as add_executable or add_library. The
5209 remaining arguments specify library names or flags. Repeated
5210 calls for the same <target> append items in the order called.
5211 If a library name matches that of another target in the project
5214 a dependency will automatically be added in the build system to
5215 make sure the library being linked is up-to-date before the tar‐
5216 get links. Item names starting with '-', but not '-l' or
5217 '-framework', are treated as linker flags.
5218 A "debug", "optimized", or "general" keyword indicates that the
5221 library immediately following it is to be used only for the cor‐
5222 responding build configuration. The "debug" keyword corresponds
5223 to the Debug configuration (or to configurations named in the
5224 DEBUG_CONFIGURATIONS global property if it is set). The "opti‐
5225 mized" keyword corresponds to all other configurations. The
5226 "general" keyword corresponds to all configurations, and is
5227 purely optional (assumed if omitted). Higher granularity may be
5228 achieved for per-configuration rules by creating and linking to
5229 IMPORTED library targets. See the IMPORTED mode of the
5230 add_library command for more information.
5231 Library dependencies are transitive by default with this signa‐
5234 ture. When this target is linked into another target then the
5235 libraries linked to this target will appear on the link line for
5236 the other target too. This transitive "link interface" is
5237 stored in the INTERFACE_LINK_LIBRARIES target property when pol‐
5238 icy CMP0022 is set to NEW and may be overridden by setting the
5239 property directly. (When CMP0022 is not set to NEW, transitive
5240 linking is builtin but may be overridden by the LINK_INTER‐
5241 FACE_LIBRARIES property. Calls to other signatures of this com‐
5242 mand may set the property making any libraries linked exclu‐
5243 sively by this signature private.)
5244 CMake will also propagate "usage requirements" from linked
5247 library targets. Usage requirements affect compilation of
5248 sources in the <target>. They are specified by properties
5249 defined on linked targets. During generation of the build sys‐
5250 tem, CMake integrates usage requirement property values with the
5251 corresponding build properties for <target>:
5252 INTERFACE_COMPILE_DEFINITONS: Appends to COMPILE_DEFINITONS
5255 INTERFACE_INCLUDE_DIRECTORIES: Appends to INCLUDE_DIRECTORIES
5256 INTERFACE_POSITION_INDEPENDENT_CODE: Sets POSITION_INDEPENDENT_CODE
5257 or checked for consistency with existing value
5258 If an <item> is a library in a Mac OX framework, the Headers
5263 directory of the framework will also be processed as a "usage
5264 requirement". This has the same effect as passing the framework
5265 directory as an include directory. target_link_libraries(<tar‐
5266 get>
5267 <PRIVATE|PUBLIC|INTERFACE> <lib> ...
5270 [<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...])
5271 The PUBLIC, PRIVATE and INTERFACE keywords can be used to spec‐
5273 ify both the link dependencies and the link interface in one
5274 command. Libraries and targets following PUBLIC are linked to,
5275 and are made part of the link interface. Libraries and targets
5276 following PRIVATE are linked to, but are not made part of the
5277 link interface. Libraries following INTERFACE are appended to
5278 the link interface and are not used for linking <target>.
5279 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES
5282 [[debug|optimized|general] <lib>] ...)
5283 The LINK_INTERFACE_LIBRARIES mode appends the libraries to the
5285 INTERFACE_LINK_LIBRARIES target property instead of using them
5286 for linking. If policy CMP0022 is not NEW, then this mode also
5287 appends libraries to the LINK_INTERFACE_LIBRARIES and its
5288 per-configuration equivalent. This signature is for compatibil‐
5289 ity only. Prefer the INTERFACE mode instead. Libraries speci‐
5290 fied as "debug" are wrapped in a generator expression to corre‐
5291 spond to debug builds. If policy CMP0022 is not NEW, the
5292 libraries are also appended to the LINK_INTER‐
5293 FACE_LIBRARIES_DEBUG property (or to the properties correspond‐
5294 ing to configurations listed in the DEBUG_CONFIGURATIONS global
5295 property if it is set). Libraries specified as "optimized" are
5296 appended to the INTERFACE_LINK_LIBRARIES property. If policy
5297 CMP0022 is not NEW, they are also appended to the LINK_INTER‐
5298 FACE_LIBRARIES property. Libraries specified as "general" (or
5299 without any keyword) are treated as if specified for both
5300 "debug" and "optimized".
5301 target_link_libraries(<target>
5304 <LINK_PRIVATE|LINK_PUBLIC>
5305 [[debug|optimized|general] <lib>] ...
5306 [<LINK_PRIVATE|LINK_PUBLIC>
5307 [[debug|optimized|general] <lib>] ...])
5308 The LINK_PUBLIC and LINK_PRIVATE modes can be used to specify
5310 both the link dependencies and the link interface in one com‐
5311 mand. This signature is for compatibility only. Prefer the PUB‐
5312 LIC or PRIVATE keywords instead. Libraries and targets follow‐
5313 ing LINK_PUBLIC are linked to, and are made part of the INTER‐
5314 FACE_LINK_LIBRARIES. If policy CMP0022 is not NEW, they are
5315 also made part of the LINK_INTERFACE_LIBRARIES. Libraries and
5316 targets following LINK_PRIVATE are linked to, but are not made
5317 part of the INTERFACE_LINK_LIBRARIES (or LINK_INTER‐
5318 FACE_LIBRARIES).
5319 The library dependency graph is normally acyclic (a DAG), but in
5322 the case of mutually-dependent STATIC libraries CMake allows the
5323 graph to contain cycles (strongly connected components). When
5324 another target links to one of the libraries CMake repeats the
5325 entire connected component. For example, the code
5326 add_library(A STATIC a.c)
5329 add_library(B STATIC b.c)
5330 target_link_libraries(A B)
5331 target_link_libraries(B A)
5332 add_executable(main main.c)
5333 target_link_libraries(main A)
5334 links 'main' to 'A B A B'. (While one repetition is usually
5336 sufficient, pathological object file and symbol arrangements can
5337 require more. One may handle such cases by manually repeating
5338 the component in the last target_link_libraries call. However,
5339 if two archives are really so interdependent they should proba‐
5340 bly be combined into a single archive.)
5341 Arguments to target_link_libraries may use "generator expres‐
5344 sions" with the syntax "$<...>". Note however, that generator
5345 expressions will not be used in OLD handling of CMP0003 or
5346 CMP0004.
5347 Generator expressions are evaluated during build system genera‐
5350 tion to produce information specific to each build configura‐
5351 tion. Valid expressions are:
5352 $<0:...> = empty string (ignores "...")
5355 $<1:...> = content of "..."
5356 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
5357 $<CONFIGURATION> = configuration name
5358 $<BOOL:...> = '1' if the '...' is true, else '0'
5359 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
5360 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
5361 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
5362 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
5363 $<JOIN:list,...> = joins the list with the content of "..."
5364 $<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.
5365 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
5366 $<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.
5367 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
5368 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
5369 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
5370 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
5371 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
5372 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
5373 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
5374 $<C_COMPILER_VERSION> = The version of the C compiler used.
5375 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
5376 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
5377 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
5378 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
5379 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
5380 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
5381 where "tgt" is the name of a target. Target file expressions
5383 produce a full path, but _DIR and _NAME versions can produce the
5384 directory and file name components:
5385 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
5388 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
5389 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
5390 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
5395 Note that tgt is not added as a dependency of the target this
5397 expression is evaluated on.
5398 $<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.
5401 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
5402 Boolean expressions:
5404 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
5407 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
5408 $<NOT:?> = '0' if '?' is '1', else '1'
5409 where '?' is always either '0' or '1'.
5411 Expressions with an implicit 'this' target:
5414 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
5417 try_compile
5420 Try building some code.
5421 try_compile(RESULT_VAR <bindir> <srcdir>
5423 <projectName> [targetName] [CMAKE_FLAGS flags...]
5424 [OUTPUT_VARIABLE <var>])
5425 Try building a project. In this form, srcdir should contain a
5427 complete CMake project with a CMakeLists.txt file and all
5428 sources. The bindir and srcdir will not be deleted after this
5429 command is run. Specify targetName to build a specific target
5430 instead of the 'all' or 'ALL_BUILD' target.
5431 try_compile(RESULT_VAR <bindir> <srcfile|SOURCES srcfile...>
5434 [CMAKE_FLAGS flags...]
5435 [COMPILE_DEFINITIONS flags...]
5436 [LINK_LIBRARIES libs...]
5437 [OUTPUT_VARIABLE <var>]
5438 [COPY_FILE <fileName> [COPY_FILE_ERROR <var>]])
5439 Try building an executable from one or more source files. In
5441 this form the user need only supply one or more source files
5442 that include a definition for 'main'. CMake will create a
5443 CMakeLists.txt file to build the source(s) as an executable.
5444 Specify COPY_FILE to get a copy of the linked executable at the
5445 given fileName and optionally COPY_FILE_ERROR to capture any
5446 error.
5447 In this version all files in bindir/CMakeFiles/CMakeTmp will be
5450 cleaned automatically. For debugging, --debug-trycompile can be
5451 passed to cmake to avoid this clean. However, multiple sequen‐
5452 tial try_compile operations reuse this single output directory.
5453 If you use --debug-trycompile, you can only debug one try_com‐
5454 pile call at a time. The recommended procedure is to configure
5455 with cmake all the way through once, then delete the cache entry
5456 associated with the try_compile call of interest, and then
5457 re-run cmake again with --debug-trycompile.
5458 Some extra flags that can be included are, INCLUDE_DIRECTORIES,
5461 LINK_DIRECTORIES, and LINK_LIBRARIES. COMPILE_DEFINITIONS are
5462 -Ddefinition that will be passed to the compile line.
5463 The srcfile signature also accepts a LINK_LIBRARIES argument
5466 which may contain a list of libraries or IMPORTED targets which
5467 will be linked to in the generated project. If LINK_LIBRARIES
5468 is specified as a parameter to try_compile, then any
5469 LINK_LIBRARIES passed as CMAKE_FLAGS will be ignored.
5470 try_compile creates a CMakeList.txt file on the fly that looks
5473 like this:
5474 add_definitions( <expanded COMPILE_DEFINITIONS from calling cmake>)
5477 include_directories(${INCLUDE_DIRECTORIES})
5478 link_directories(${LINK_DIRECTORIES})
5479 add_executable(cmTryCompileExec sources)
5480 target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
5481 In both versions of the command, if OUTPUT_VARIABLE is speci‐
5483 fied, then the output from the build process is stored in the
5484 given variable. The success or failure of the try_compile, i.e.
5485 TRUE or FALSE respectively, is returned in RESULT_VAR.
5486 CMAKE_FLAGS can be used to pass -DVAR:TYPE=VALUE flags to the
5487 cmake that is run during the build. Set variable CMAKE_TRY_COM‐
5488 PILE_CONFIGURATION to choose a build configuration.
5489 try_run
5492 Try compiling and then running some code.
5493 try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR
5495 bindir srcfile [CMAKE_FLAGS <Flags>]
5496 [COMPILE_DEFINITIONS <flags>]
5497 [COMPILE_OUTPUT_VARIABLE comp]
5498 [RUN_OUTPUT_VARIABLE run]
5499 [OUTPUT_VARIABLE var]
5500 [ARGS <arg1> <arg2>...])
5501 Try compiling a srcfile. Return TRUE or FALSE for success or
5503 failure in COMPILE_RESULT_VAR. Then if the compile succeeded,
5504 run the executable and return its exit code in RUN_RESULT_VAR.
5505 If the executable was built, but failed to run, then
5506 RUN_RESULT_VAR will be set to FAILED_TO_RUN. COMPILE_OUT‐
5507 PUT_VARIABLE specifies the variable where the output from the
5508 compile step goes. RUN_OUTPUT_VARIABLE specifies the variable
5509 where the output from the running executable goes.
5510 For compatibility reasons OUTPUT_VARIABLE is still supported,
5513 which gives you the output from the compile and run step com‐
5514 bined.
5515 Cross compiling issues
5518 When cross compiling, the executable compiled in the first step
5521 usually cannot be run on the build host. try_run() checks the
5522 CMAKE_CROSSCOMPILING variable to detect whether CMake is in
5523 crosscompiling mode. If that's the case, it will still try to
5524 compile the executable, but it will not try to run the exe‐
5525 cutable. Instead it will create cache variables which must be
5526 filled by the user or by presetting them in some CMake script
5527 file to the values the executable would have produced if it had
5528 been run on its actual target platform. These variables are
5529 RUN_RESULT_VAR (explanation see above) and if RUN_OUTPUT_VARI‐
5530 ABLE (or OUTPUT_VARIABLE) was used, an additional cache variable
5531 RUN_RESULT_VAR__COMPILE_RESULT_VAR__TRYRUN_OUTPUT.This is
5532 intended to hold stdout and stderr from the executable.
5533 In order to make cross compiling your project easier, use
5536 try_run only if really required. If you use try_run, use
5537 RUN_OUTPUT_VARIABLE (or OUTPUT_VARIABLE) only if really
5538 required. Using them will require that when crosscompiling, the
5539 cache variables will have to be set manually to the output of
5540 the executable. You can also "guard" the calls to try_run with
5541 if(CMAKE_CROSSCOMPILING) and provide an easy-to-preset alterna‐
5542 tive for this case.
5543 Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build
5546 configuration.
5547 unset Unset a variable, cache variable, or environment variable.
5550 unset(<variable> [CACHE])
5552 Removes the specified variable causing it to become undefined.
5554 If CACHE is present then the variable is removed from the cache
5555 instead of the current scope.
5556 <variable> can be an environment variable such as:
5559 unset(ENV{LD_LIBRARY_PATH})
5562 in which case the variable will be removed from the current
5564 environment.
5565 variable_watch
5568 Watch the CMake variable for change.
5569 variable_watch(<variable name> [<command to execute>])
5571 If the specified variable changes, the message will be printed
5573 about the variable being changed. If the command is specified,
5574 the command will be executed. The command will receive the fol‐
5575 lowing arguments: COMMAND(<variable> <access> <value> <current
5576 list file> <stack>)
5577 while Evaluate a group of commands while a condition is true
5580 while(condition)
5582 COMMAND1(ARGS ...)
5583 COMMAND2(ARGS ...)
5584 ...
5585 endwhile(condition)
5586 All commands between while and the matching endwhile are
5588 recorded without being invoked. Once the endwhile is evaluated,
5589 the recorded list of commands is invoked as long as the condi‐
5590 tion is true. The condition is evaluated using the same logic as
5591 the if command.
5592
5595 CMake Properties - Properties supported by CMake, the Cross-Platform Makefile Generator.
5596 This is the documentation for the properties supported by CMake. Prop‐
5599 erties can have different scopes. They can either be assigned to a
5600 source file, a directory, a target or globally to CMake. By modifying
5601 the values of properties the behaviour of the build system can be cus‐
5602 tomized.
5603
5606 ALLOW_DUPLICATE_CUSTOM_TARGETS
5607 Allow duplicate custom targets to be created.
5608 Normally CMake requires that all targets built in a project have
5610 globally unique logical names (see policy CMP0002). This is
5611 necessary to generate meaningful project file names in Xcode and
5612 VS IDE generators. It also allows the target names to be refer‐
5613 enced unambiguously.
5614 Makefile generators are capable of supporting duplicate custom
5617 target names. For projects that care only about Makefile gener‐
5618 ators and do not wish to support Xcode or VS IDE generators, one
5619 may set this property to true to allow duplicate custom targets.
5620 The property allows multiple add_custom_target command calls in
5621 different directories to specify the same target name. However,
5622 setting this property will cause non-Makefile generators to pro‐
5623 duce an error and refuse to generate the project.
5624 AUTOMOC_TARGETS_FOLDER
5627 Name of FOLDER for *_automoc targets that are added automati‐
5628 cally by CMake for targets for which AUTOMOC is enabled.
5629 If not set, CMake uses the FOLDER property of the parent target
5631 as a default value for this property. See also the documentation
5632 for the FOLDER target property and the AUTOMOC target property.
5633 DEBUG_CONFIGURATIONS
5636 Specify which configurations are for debugging.
5637 The value must be a semi-colon separated list of configuration
5639 names. Currently this property is used only by the tar‐
5640 get_link_libraries command (see its documentation for details).
5641 Additional uses may be defined in the future.
5642 This property must be set at the top level of the project and
5645 before the first target_link_libraries command invocation. If
5646 any entry in the list does not match a valid configuration for
5647 the project the behavior is undefined.
5648 DISABLED_FEATURES
5651 List of features which are disabled during the CMake run.
5652 List of features which are disabled during the CMake run. By
5654 default it contains the names of all packages which were not
5655 found. This is determined using the <NAME>_FOUND variables.
5656 Packages which are searched QUIET are not listed. A project can
5657 add its own features to this list. This property is used by the
5658 macros in FeatureSummary.cmake.
5659 ENABLED_FEATURES
5662 List of features which are enabled during the CMake run.
5663 List of features which are enabled during the CMake run. By
5665 default it contains the names of all packages which were found.
5666 This is determined using the <NAME>_FOUND variables. Packages
5667 which are searched QUIET are not listed. A project can add its
5668 own features to this list. This property is used by the macros
5669 in FeatureSummary.cmake.
5670 ENABLED_LANGUAGES
5673 Read-only property that contains the list of currently enabled
5674 languages
5675 Set to list of currently enabled languages.
5677 FIND_LIBRARY_USE_LIB64_PATHS
5680 Whether FIND_LIBRARY should automatically search lib64 directo‐
5681 ries.
5682 FIND_LIBRARY_USE_LIB64_PATHS is a boolean specifying whether the
5684 FIND_LIBRARY command should automatically search the lib64 vari‐
5685 ant of directories called lib in the search path when building
5686 64-bit binaries.
5687 FIND_LIBRARY_USE_OPENBSD_VERSIONING
5690 Whether FIND_LIBRARY should find OpenBSD-style shared libraries.
5691 This property is a boolean specifying whether the FIND_LIBRARY
5693 command should find shared libraries with OpenBSD-style ver‐
5694 sioned extension: ".so.<major>.<minor>". The property is set to
5695 true on OpenBSD and false on other platforms.
5696 GLOBAL_DEPENDS_DEBUG_MODE
5699 Enable global target dependency graph debug mode.
5700 CMake automatically analyzes the global inter-target dependency
5702 graph at the beginning of native build system generation. This
5703 property causes it to display details of its analysis to stderr.
5704 GLOBAL_DEPENDS_NO_CYCLES
5707 Disallow global target dependency graph cycles.
5708 CMake automatically analyzes the global inter-target dependency
5710 graph at the beginning of native build system generation. It
5711 reports an error if the dependency graph contains a cycle that
5712 does not consist of all STATIC library targets. This property
5713 tells CMake to disallow all cycles completely, even among static
5714 libraries.
5715 IN_TRY_COMPILE
5718 Read-only property that is true during a try-compile configura‐
5719 tion.
5720 True when building a project inside a TRY_COMPILE or TRY_RUN
5722 command.
5723 PACKAGES_FOUND
5726 List of packages which were found during the CMake run.
5727 List of packages which were found during the CMake run. Whether
5729 a package has been found is determined using the <NAME>_FOUND
5730 variables.
5731 PACKAGES_NOT_FOUND
5734 List of packages which were not found during the CMake run.
5735 List of packages which were not found during the CMake run.
5737 Whether a package has been found is determined using the
5738 <NAME>_FOUND variables.
5739 PREDEFINED_TARGETS_FOLDER
5742 Name of FOLDER for targets that are added automatically by
5743 CMake.
5744 If not set, CMake uses "CMakePredefinedTargets" as a default
5746 value for this property. Targets such as INSTALL, PACKAGE and
5747 RUN_TESTS will be organized into this FOLDER. See also the docu‐
5748 mentation for the FOLDER target property.
5749 REPORT_UNDEFINED_PROPERTIES
5752 If set, report any undefined properties to this file.
5753 If this property is set to a filename then when CMake runs it
5755 will report any properties or variables that were accessed but
5756 not defined into the filename specified in this property.
5757 RULE_LAUNCH_COMPILE
5760 Specify a launcher for compile rules.
5761 Makefile generators prefix compiler commands with the given
5763 launcher command line. This is intended to allow launchers to
5764 intercept build problems with high granularity. Non-Makefile
5765 generators currently ignore this property.
5766 RULE_LAUNCH_CUSTOM
5769 Specify a launcher for custom rules.
5770 Makefile generators prefix custom commands with the given
5772 launcher command line. This is intended to allow launchers to
5773 intercept build problems with high granularity. Non-Makefile
5774 generators currently ignore this property.
5775 RULE_LAUNCH_LINK
5778 Specify a launcher for link rules.
5779 Makefile generators prefix link and archive commands with the
5781 given launcher command line. This is intended to allow launch‐
5782 ers to intercept build problems with high granularity.
5783 Non-Makefile generators currently ignore this property.
5784 RULE_MESSAGES
5787 Specify whether to report a message for each make rule.
5788 This property specifies whether Makefile generators should add a
5790 progress message describing what each build rule does. If the
5791 property is not set the default is ON. Set the property to OFF
5792 to disable granular messages and report only as each target com‐
5793 pletes. This is intended to allow scripted builds to avoid the
5794 build time cost of detailed reports. If a CMAKE_RULE_MESSAGES
5795 cache entry exists its value initializes the value of this prop‐
5796 erty. Non-Makefile generators currently ignore this property.
5797 TARGET_ARCHIVES_MAY_BE_SHARED_LIBS
5800 Set if shared libraries may be named like archives.
5801 On AIX shared libraries may be named "lib<name>.a". This prop‐
5803 erty is set to true on such platforms.
5804 TARGET_SUPPORTS_SHARED_LIBS
5807 Does the target platform support shared libraries.
5808 TARGET_SUPPORTS_SHARED_LIBS is a boolean specifying whether the
5810 target platform supports shared libraries. Basically all current
5811 general general purpose OS do so, the exception are usually
5812 embedded systems with no or special OSs.
5813 USE_FOLDERS
5816 Use the FOLDER target property to organize targets into folders.
5817 If not set, CMake treats this property as OFF by default. CMake
5819 generators that are capable of organizing into a hierarchy of
5820 folders use the values of the FOLDER target property to name
5821 those folders. See also the documentation for the FOLDER target
5822 property.
5823 __CMAKE_DELETE_CACHE_CHANGE_VARS_
5826 Internal property
5827 Used to detect compiler changes, Do not set.
5829
5832 ADDITIONAL_MAKE_CLEAN_FILES
5833 Additional files to clean during the make clean stage.
5834 A list of files that will be cleaned as a part of the "make
5836 clean" stage.
5837 CACHE_VARIABLES
5840 List of cache variables available in the current directory.
5841 This read-only property specifies the list of CMake cache vari‐
5843 ables currently defined. It is intended for debugging purposes.
5844 CLEAN_NO_CUSTOM
5847 Should the output of custom commands be left.
5848 If this is true then the outputs of custom commands for this
5850 directory will not be removed during the "make clean" stage.
5851 COMPILE_DEFINITIONS
5854 Preprocessor definitions for compiling a directory's sources.
5855 The COMPILE_DEFINITIONS property may be set to a semicolon-sepa‐
5857 rated list of preprocessor definitions using the syntax VAR or
5858 VAR=value. Function-style definitions are not supported. CMake
5859 will automatically escape the value correctly for the native
5860 build system (note that CMake language syntax may require
5861 escapes to specify some values). This property may be set on a
5862 per-configuration basis using the name COMPILE_DEFINITIONS_<CON‐
5863 FIG> where <CONFIG> is an upper-case name (ex. "COMPILE_DEFINI‐
5864 TIONS_DEBUG"). This property will be initialized in each direc‐
5865 tory by its value in the directory's parent.
5866 CMake will automatically drop some definitions that are not sup‐
5869 ported by the native build tool. The VS6 IDE does not support
5870 definition values with spaces (but NMake does).
5871 Disclaimer: Most native build tools have poor support for escap‐
5874 ing certain values. CMake has work-arounds for many cases but
5875 some values may just not be possible to pass correctly. If a
5876 value does not seem to be escaped correctly, do not attempt to
5877 work-around the problem by adding escape sequences to the value.
5878 Your work-around may break in a future version of CMake that has
5879 improved escape support. Instead consider defining the macro in
5880 a (configured) header file. Then report the limitation. Known
5881 limitations include:
5882 # - broken almost everywhere
5885 ; - broken in VS IDE 7.0 and Borland Makefiles
5886 , - broken in VS IDE
5887 % - broken in some cases in NMake
5888 & | - broken in some cases on MinGW
5889 ^ < > \" - broken in most Make tools on Windows
5890 CMake does not reject these values outright because they do work
5892 in some cases. Use with caution.
5893 COMPILE_DEFINITIONS_<CONFIG>
5896 Per-configuration preprocessor definitions in a directory.
5897 This is the configuration-specific version of COMPILE_DEFINI‐
5899 TIONS. This property will be initialized in each directory by
5900 its value in the directory's parent.
5901 COMPILE_OPTIONS
5905 List of options to pass to the compiler.
5906 This property specifies the list of directories given so far for
5908 this property. This property exists on directories and targets.
5909 The target property values are used by the generators to set the
5912 options for the compiler.
5913 Contents of COMPILE_OPTIONS may use "generator expressions" with
5916 the syntax "$<...>". Generator expressions are evaluated during
5917 build system generation to produce information specific to each
5918 build configuration. Valid expressions are:
5919 $<0:...> = empty string (ignores "...")
5922 $<1:...> = content of "..."
5923 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
5924 $<CONFIGURATION> = configuration name
5925 $<BOOL:...> = '1' if the '...' is true, else '0'
5926 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
5927 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
5928 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
5929 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
5930 $<JOIN:list,...> = joins the list with the content of "..."
5931 $<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.
5932 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
5933 $<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.
5934 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
5935 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
5936 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
5937 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
5938 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
5939 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
5940 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
5941 $<C_COMPILER_VERSION> = The version of the C compiler used.
5942 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
5943 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
5944 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
5945 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
5946 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
5947 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
5948 where "tgt" is the name of a target. Target file expressions
5950 produce a full path, but _DIR and _NAME versions can produce the
5951 directory and file name components:
5952 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
5955 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
5956 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
5957 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
5962 Note that tgt is not added as a dependency of the target this
5964 expression is evaluated on.
5965 $<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.
5968 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
5969 Boolean expressions:
5971 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
5974 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
5975 $<NOT:?> = '0' if '?' is '1', else '1'
5976 where '?' is always either '0' or '1'.
5978 Expressions with an implicit 'this' target:
5981 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
5984 DEFINITIONS
5987 For CMake 2.4 compatibility only. Use COMPILE_DEFINITIONS
5988 instead.
5989 This read-only property specifies the list of flags given so far
5991 to the add_definitions command. It is intended for debugging
5992 purposes. Use the COMPILE_DEFINITIONS instead.
5993 EXCLUDE_FROM_ALL
5996 Exclude the directory from the all target of its parent.
5997 A property on a directory that indicates if its targets are
5999 excluded from the default build target. If it is not, then with
6000 a Makefile for example typing make will cause the targets to be
6001 built. The same concept applies to the default build of other
6002 generators.
6003 IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
6006 Specify #include line transforms for dependencies in a direc‐
6007 tory.
6008 This property specifies rules to transform macro-like #include
6010 lines during implicit dependency scanning of C and C++ source
6011 files. The list of rules must be semicolon-separated with each
6012 entry of the form "A_MACRO(%)=value-with-%" (the % must be lit‐
6013 eral). During dependency scanning occurrences of A_MACRO(...)
6014 on #include lines will be replaced by the value given with the
6015 macro argument substituted for '%'. For example, the entry
6016 MYDIR(%)=<mydir/%>
6019 will convert lines of the form
6021 #include MYDIR(myheader.h)
6024 to
6026 #include <mydir/myheader.h>
6029 allowing the dependency to be followed.
6031 This property applies to sources in all targets within a direc‐
6034 tory. The property value is initialized in each directory by
6035 its value in the directory's parent.
6036 INCLUDE_DIRECTORIES
6039 List of preprocessor include file search directories.
6040 This property specifies the list of directories given so far to
6042 the include_directories command. This property exists on direc‐
6043 tories and targets. In addition to accepting values from the
6044 include_directories command, values may be set directly on any
6045 directory or any target using the set_property command. A tar‐
6046 get gets its initial value for this property from the value of
6047 the directory property. A directory gets its initial value from
6048 its parent directory if it has one. Both directory and target
6049 property values are adjusted by calls to the include_directories
6050 command.
6051 The target property values are used by the generators to set the
6054 include paths for the compiler. See also the include_directo‐
6055 ries command.
6056 INCLUDE_REGULAR_EXPRESSION
6059 Include file scanning regular expression.
6060 This read-only property specifies the regular expression used
6062 during dependency scanning to match include files that should be
6063 followed. See the include_regular_expression command.
6064 INTERPROCEDURAL_OPTIMIZATION
6067 Enable interprocedural optimization for targets in a directory.
6068 If set to true, enables interprocedural optimizations if they
6070 are known to be supported by the compiler.
6071 INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
6074 Per-configuration interprocedural optimization for a directory.
6075 This is a per-configuration version of INTERPROCEDURAL_OPTIMIZA‐
6077 TION. If set, this property overrides the generic property for
6078 the named configuration.
6079 LINK_DIRECTORIES
6082 List of linker search directories.
6083 This read-only property specifies the list of directories given
6085 so far to the link_directories command. It is intended for
6086 debugging purposes.
6087 LISTFILE_STACK
6090 The current stack of listfiles being processed.
6091 This property is mainly useful when trying to debug errors in
6093 your CMake scripts. It returns a list of what list files are
6094 currently being processed, in order. So if one listfile does an
6095 INCLUDE command then that is effectively pushing the included
6096 listfile onto the stack.
6097 MACROS List of macro commands available in the current directory.
6100 This read-only property specifies the list of CMake macros cur‐
6102 rently defined. It is intended for debugging purposes. See the
6103 macro command.
6104 PARENT_DIRECTORY
6107 Source directory that added current subdirectory.
6108 This read-only property specifies the source directory that
6110 added the current source directory as a subdirectory of the
6111 build. In the top-level directory the value is the
6112 empty-string.
6113 RULE_LAUNCH_COMPILE
6116 Specify a launcher for compile rules.
6117 See the global property of the same name for details. This
6119 overrides the global property for a directory.
6120 RULE_LAUNCH_CUSTOM
6123 Specify a launcher for custom rules.
6124 See the global property of the same name for details. This
6126 overrides the global property for a directory.
6127 RULE_LAUNCH_LINK
6130 Specify a launcher for link rules.
6131 See the global property of the same name for details. This
6133 overrides the global property for a directory.
6134 TEST_INCLUDE_FILE
6137 A cmake file that will be included when ctest is run.
6138 If you specify TEST_INCLUDE_FILE, that file will be included and
6140 processed when ctest is run on the directory.
6141 VARIABLES
6144 List of variables defined in the current directory.
6145 This read-only property specifies the list of CMake variables
6147 currently defined. It is intended for debugging purposes.
6148 VS_GLOBAL_SECTION_POST_<section>
6151 Specify a postSolution global section in Visual Studio.
6152 Setting a property like this generates an entry of the following
6154 form in the solution file:
6155 GlobalSection(<section>) = postSolution
6158 <contents based on property value>
6159 EndGlobalSection
6160 The property must be set to a semicolon-separated list of
6162 key=value pairs. Each such pair will be transformed into an
6163 entry in the solution global section. Whitespace around key and
6164 value is ignored. List elements which do not contain an equal
6165 sign are skipped.
6166 This property only works for Visual Studio 7 and above; it is
6169 ignored on other generators. The property only applies when set
6170 on a directory whose CMakeLists.txt contains a project() com‐
6171 mand.
6172 Note that CMake generates postSolution sections Extensibility‐
6175 Globals and ExtensibilityAddIns by default. If you set the cor‐
6176 responding property, it will override the default section. For
6177 example, setting VS_GLOBAL_SECTION_POST_ExtensibilityGlobals
6178 will override the default contents of the ExtensibilityGlobals
6179 section, while keeping ExtensibilityAddIns on its default.
6180 VS_GLOBAL_SECTION_PRE_<section>
6183 Specify a preSolution global section in Visual Studio.
6184 Setting a property like this generates an entry of the following
6186 form in the solution file:
6187 GlobalSection(<section>) = preSolution
6190 <contents based on property value>
6191 EndGlobalSection
6192 The property must be set to a semicolon-separated list of
6194 key=value pairs. Each such pair will be transformed into an
6195 entry in the solution global section. Whitespace around key and
6196 value is ignored. List elements which do not contain an equal
6197 sign are skipped.
6198 This property only works for Visual Studio 7 and above; it is
6201 ignored on other generators. The property only applies when set
6202 on a directory whose CMakeLists.txt contains a project() com‐
6203 mand.
6204
6207 <CONFIG>_OUTPUT_NAME
6208 Old per-configuration target file base name.
6209 This is a configuration-specific version of OUTPUT_NAME. Use
6211 OUTPUT_NAME_<CONFIG> instead.
6212 <CONFIG>_POSTFIX
6215 Postfix to append to the target file name for configuration
6216 <CONFIG>.
6217 When building with configuration <CONFIG> the value of this
6219 property is appended to the target file name built on disk. For
6220 non-executable targets, this property is initialized by the
6221 value of the variable CMAKE_<CONFIG>_POSTFIX if it is set when a
6222 target is created. This property is ignored on the Mac for
6223 Frameworks and App Bundles.
6224 <LANG>_VISIBILITY_PRESET
6227 Value for symbol visibility compile flags
6228 The <LANG>_VISIBILITY_PRESET property determines the value
6230 passed in a visibility related compile option, such as -fvisi‐
6231 bility= for <LANG>. This property only has an affect for
6232 libraries and executables with exports. This property is ini‐
6233 tialized by the value of the variable CMAKE_<LANG>_VISIBIL‐
6234 ITY_PRESET if it is set when a target is created.
6235 ALIASED_TARGET
6238 Name of target aliased by this target.
6239 If this is an ALIAS target, this property contains the name of
6241 the target aliased.
6242 ARCHIVE_OUTPUT_DIRECTORY
6245 Output directory in which to build ARCHIVE target files.
6246 This property specifies the directory into which archive target
6248 files should be built. Multi-configuration generators (VS,
6249 Xcode) append a per-configuration subdirectory to the specified
6250 directory. There are three kinds of target files that may be
6251 built: archive, library, and runtime. Executables are always
6252 treated as runtime targets. Static libraries are always treated
6253 as archive targets. Module libraries are always treated as
6254 library targets. For non-DLL platforms shared libraries are
6255 treated as library targets. For DLL platforms the DLL part of a
6256 shared library is treated as a runtime target and the corre‐
6257 sponding import library is treated as an archive target. All
6258 Windows-based systems including Cygwin are DLL platforms. This
6259 property is initialized by the value of the variable CMAKE_AR‐
6260 CHIVE_OUTPUT_DIRECTORY if it is set when a target is created.
6261 ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>
6264 Per-configuration output directory for ARCHIVE target files.
6265 This is a per-configuration version of ARCHIVE_OUTPUT_DIRECTORY,
6267 but multi-configuration generators (VS, Xcode) do NOT append a
6268 per-configuration subdirectory to the specified directory. This
6269 property is initialized by the value of the variable CMAKE_AR‐
6270 CHIVE_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is
6271 created.
6272 ARCHIVE_OUTPUT_NAME
6275 Output name for ARCHIVE target files.
6276 This property specifies the base name for archive target files.
6278 It overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
6279 There are three kinds of target files that may be built: ar‐
6280 chive, library, and runtime. Executables are always treated as
6281 runtime targets. Static libraries are always treated as archive
6282 targets. Module libraries are always treated as library targets.
6283 For non-DLL platforms shared libraries are treated as library
6284 targets. For DLL platforms the DLL part of a shared library is
6285 treated as a runtime target and the corresponding import library
6286 is treated as an archive target. All Windows-based systems
6287 including Cygwin are DLL platforms.
6288 ARCHIVE_OUTPUT_NAME_<CONFIG>
6291 Per-configuration output name for ARCHIVE target files.
6292 This is the configuration-specific version of ARCHIVE_OUT‐
6294 PUT_NAME.
6295 AUTOMOC
6298 Should the target be processed with automoc (for Qt projects).
6299 AUTOMOC is a boolean specifying whether CMake will handle the Qt
6301 moc preprocessor automatically, i.e. without having to use the
6302 QT4_WRAP_CPP() or QT5_WRAP_CPP() macro. Currently Qt4 and Qt5
6303 are supported. When this property is set to TRUE, CMake will
6304 scan the source files at build time and invoke moc accordingly.
6305 If an #include statement like #include "moc_foo.cpp" is found,
6306 the Q_OBJECT class declaration is expected in the header, and
6307 moc is run on the header file. If an #include statement like
6308 #include "foo.moc" is found, then a Q_OBJECT is expected in the
6309 current source file and moc is run on the file itself. Addition‐
6310 ally, all header files are parsed for Q_OBJECT macros, and if
6311 found, moc is also executed on those files. The resulting moc
6312 files, which are not included as shown above in any of the
6313 source files are included in a generated <targetname>_auto‐
6314 moc.cpp file, which is compiled as part of the target.This prop‐
6315 erty is initialized by the value of the variable CMAKE_AUTOMOC
6316 if it is set when a target is created.
6317 Additional command line options for moc can be set via the AUTO‐
6320 MOC_MOC_OPTIONS property.
6321 By setting the CMAKE_AUTOMOC_RELAXED_MODE variable to TRUE the
6324 rules for searching the files which will be processed by moc can
6325 be relaxed. See the documentation for this variable for more
6326 details.
6327 The global property AUTOMOC_TARGETS_FOLDER can be used to group
6330 the automoc targets together in an IDE, e.g. in MSVS.
6331 AUTOMOC_MOC_OPTIONS
6334 Additional options for moc when using automoc (see the AUTOMOC
6335 property)
6336 This property is only used if the AUTOMOC property is set to
6338 TRUE for this target. In this case, it holds additional command
6339 line options which will be used when moc is executed during the
6340 build, i.e. it is equivalent to the optional OPTIONS argument of
6341 the qt4_wrap_cpp() macro.
6342 By default it is empty.
6345 BUILD_WITH_INSTALL_RPATH
6348 Should build tree targets have install tree rpaths.
6349 BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link
6351 the target in the build tree with the INSTALL_RPATH. This takes
6352 precedence over SKIP_BUILD_RPATH and avoids the need for relink‐
6353 ing before installation. This property is initialized by the
6354 value of the variable CMAKE_BUILD_WITH_INSTALL_RPATH if it is
6355 set when a target is created.
6356 BUNDLE This target is a CFBundle on the Mac.
6359 If a module library target has this property set to true it will
6361 be built as a CFBundle when built on the mac. It will have the
6362 directory structure required for a CFBundle and will be suitable
6363 to be used for creating Browser Plugins or other application
6364 resources.
6365 BUNDLE_EXTENSION
6368 The file extension used to name a BUNDLE target on the Mac.
6369 The default value is "bundle" - you can also use "plugin" or
6371 whatever file extension is required by the host app for your
6372 bundle.
6373 COMPATIBLE_INTERFACE_BOOL
6376 Properties which must be compatible with their link interface
6377 The COMPATIBLE_INTERFACE_BOOL property may contain a list of
6379 propertiesfor this target which must be consistent when evalu‐
6380 ated as a boolean in the INTERFACE of all linked dependees. For
6381 example, if a property "FOO" appears in the list, then for each
6382 dependee, the "INTERFACE_FOO" property content in all of its
6383 dependencies must be consistent with each other, and with the
6384 "FOO" property in the dependee. Consistency in this sense has
6385 the meaning that if the property is set, then it must have the
6386 same boolean value as all others, and if the property is not
6387 set, then it is ignored. Note that for each dependee, the set
6388 of properties from this property must not intersect with the set
6389 of properties from the COMPATIBLE_INTERFACE_STRING property.
6390 COMPATIBLE_INTERFACE_STRING
6393 Properties which must be string-compatible with their link
6394 interface
6395 The COMPATIBLE_INTERFACE_STRING property may contain a list of
6397 properties for this target which must be the same when evaluated
6398 as a string in the INTERFACE of all linked dependees. For exam‐
6399 ple, if a property "FOO" appears in the list, then for each
6400 dependee, the "INTERFACE_FOO" property content in all of its
6401 dependencies must be equal with each other, and with the "FOO"
6402 property in the dependee. If the property is not set, then it
6403 is ignored. Note that for each dependee, the set of properties
6404 from this property must not intersect with the set of properties
6405 from the COMPATIBLE_INTERFACE_BOOL property.
6406 COMPILE_DEFINITIONS
6409 Preprocessor definitions for compiling a target's sources.
6410 The COMPILE_DEFINITIONS property may be set to a semicolon-sepa‐
6412 rated list of preprocessor definitions using the syntax VAR or
6413 VAR=value. Function-style definitions are not supported. CMake
6414 will automatically escape the value correctly for the native
6415 build system (note that CMake language syntax may require
6416 escapes to specify some values). This property may be set on a
6417 per-configuration basis using the name COMPILE_DEFINITIONS_<CON‐
6418 FIG> where <CONFIG> is an upper-case name (ex. "COMPILE_DEFINI‐
6419 TIONS_DEBUG").
6420 CMake will automatically drop some definitions that are not sup‐
6423 ported by the native build tool. The VS6 IDE does not support
6424 definition values with spaces (but NMake does).
6425 Contents of COMPILE_DEFINITIONS may use "generator expressions"
6428 with the syntax "$<...>". Generator expressions are evaluated
6429 during build system generation to produce information specific
6430 to each build configuration. Valid expressions are:
6431 $<0:...> = empty string (ignores "...")
6434 $<1:...> = content of "..."
6435 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
6436 $<CONFIGURATION> = configuration name
6437 $<BOOL:...> = '1' if the '...' is true, else '0'
6438 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
6439 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
6440 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
6441 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
6442 $<JOIN:list,...> = joins the list with the content of "..."
6443 $<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.
6444 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
6445 $<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.
6446 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
6447 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
6448 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
6449 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
6450 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
6451 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
6452 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
6453 $<C_COMPILER_VERSION> = The version of the C compiler used.
6454 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
6455 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
6456 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
6457 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
6458 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
6459 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
6460 where "tgt" is the name of a target. Target file expressions
6462 produce a full path, but _DIR and _NAME versions can produce the
6463 directory and file name components:
6464 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
6467 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
6468 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
6469 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
6474 Note that tgt is not added as a dependency of the target this
6476 expression is evaluated on.
6477 $<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.
6480 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
6481 Boolean expressions:
6483 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
6486 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
6487 $<NOT:?> = '0' if '?' is '1', else '1'
6488 where '?' is always either '0' or '1'.
6490 Expressions with an implicit 'this' target:
6493 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
6496 Disclaimer: Most native build tools have poor support for escap‐
6498 ing certain values. CMake has work-arounds for many cases but
6499 some values may just not be possible to pass correctly. If a
6500 value does not seem to be escaped correctly, do not attempt to
6501 work-around the problem by adding escape sequences to the value.
6502 Your work-around may break in a future version of CMake that has
6503 improved escape support. Instead consider defining the macro in
6504 a (configured) header file. Then report the limitation. Known
6505 limitations include:
6506 # - broken almost everywhere
6509 ; - broken in VS IDE 7.0 and Borland Makefiles
6510 , - broken in VS IDE
6511 % - broken in some cases in NMake
6512 & | - broken in some cases on MinGW
6513 ^ < > \" - broken in most Make tools on Windows
6514 CMake does not reject these values outright because they do work
6516 in some cases. Use with caution.
6517 COMPILE_DEFINITIONS_<CONFIG>
6520 Per-configuration preprocessor definitions on a target.
6521 This is the configuration-specific version of COMPILE_DEFINI‐
6523 TIONS.
6524 COMPILE_FLAGS
6527 Additional flags to use when compiling this target's sources.
6528 The COMPILE_FLAGS property sets additional compiler flags used
6530 to build sources within the target. Use COMPILE_DEFINITIONS to
6531 pass additional preprocessor definitions.
6532 COMPILE_OPTIONS
6535 List of options to pass to the compiler.
6536 This property specifies the list of options specified so far for
6538 this property. This property exists on directories and targets.
6539 The target property values are used by the generators to set the
6542 options for the compiler.
6543 Contents of COMPILE_OPTIONS may use "generator expressions" with
6546 the syntax "$<...>". Generator expressions are evaluated during
6547 build system generation to produce information specific to each
6548 build configuration. Valid expressions are:
6549 $<0:...> = empty string (ignores "...")
6552 $<1:...> = content of "..."
6553 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
6554 $<CONFIGURATION> = configuration name
6555 $<BOOL:...> = '1' if the '...' is true, else '0'
6556 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
6557 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
6558 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
6559 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
6560 $<JOIN:list,...> = joins the list with the content of "..."
6561 $<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.
6562 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
6563 $<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.
6564 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
6565 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
6566 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
6567 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
6568 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
6569 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
6570 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
6571 $<C_COMPILER_VERSION> = The version of the C compiler used.
6572 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
6573 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
6574 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
6575 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
6576 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
6577 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
6578 where "tgt" is the name of a target. Target file expressions
6580 produce a full path, but _DIR and _NAME versions can produce the
6581 directory and file name components:
6582 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
6585 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
6586 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
6587 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
6592 Note that tgt is not added as a dependency of the target this
6594 expression is evaluated on.
6595 $<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.
6598 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
6599 Boolean expressions:
6601 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
6604 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
6605 $<NOT:?> = '0' if '?' is '1', else '1'
6606 where '?' is always either '0' or '1'.
6608 Expressions with an implicit 'this' target:
6611 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
6614 DEBUG_POSTFIX
6617 See target property <CONFIG>_POSTFIX.
6618 This property is a special case of the more-general <CON‐
6620 FIG>_POSTFIX property for the DEBUG configuration.
6621 DEFINE_SYMBOL
6624 Define a symbol when compiling this target's sources.
6625 DEFINE_SYMBOL sets the name of the preprocessor symbol defined
6627 when compiling sources in a shared library. If not set here then
6628 it is set to target_EXPORTS by default (with some substitutions
6629 if the target is not a valid C identifier). This is useful for
6630 headers to know whether they are being included from inside
6631 their library or outside to properly setup dllexport/dllimport
6632 decorations.
6633 ENABLE_EXPORTS
6636 Specify whether an executable exports symbols for loadable mod‐
6637 ules.
6638 Normally an executable does not export any symbols because it is
6640 the final program. It is possible for an executable to export
6641 symbols to be used by loadable modules. When this property is
6642 set to true CMake will allow other targets to "link" to the exe‐
6643 cutable with the TARGET_LINK_LIBRARIES command. On all plat‐
6644 forms a target-level dependency on the executable is created for
6645 targets that link to it. For DLL platforms an import library
6646 will be created for the exported symbols and then used for link‐
6647 ing. All Windows-based systems including Cygwin are DLL plat‐
6648 forms. For non-DLL platforms that require all symbols to be
6649 resolved at link time, such as Mac OS X, the module will "link"
6650 to the executable using a flag like "-bundle_loader". For other
6651 non-DLL platforms the link rule is simply ignored since the
6652 dynamic loader will automatically bind symbols when the module
6653 is loaded.
6654 EXCLUDE_FROM_ALL
6657 Exclude the target from the all target.
6658 A property on a target that indicates if the target is excluded
6660 from the default build target. If it is not, then with a Make‐
6661 file for example typing make will cause this target to be built.
6662 The same concept applies to the default build of other genera‐
6663 tors. Installing a target with EXCLUDE_FROM_ALL set to true has
6664 undefined behavior.
6665 EXCLUDE_FROM_DEFAULT_BUILD
6668 Exclude target from "Build Solution".
6669 This property is only used by Visual Studio generators 7 and
6671 above. When set to TRUE, the target will not be built when you
6672 press "Build Solution".
6673 EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG>
6676 Per-configuration version of target exclusion from "Build Solu‐
6677 tion".
6678 This is the configuration-specific version of
6680 EXCLUDE_FROM_DEFAULT_BUILD. If the generic
6681 EXCLUDE_FROM_DEFAULT_BUILD is also set on a target,
6682 EXCLUDE_FROM_DEFAULT_BUILD_<CONFIG> takes precedence in configu‐
6683 rations for which it has a value.
6684 EXPORT_NAME
6687 Exported name for target files.
6688 This sets the name for the IMPORTED target generated when it
6690 this target is is exported. If not set, the logical target name
6691 is used by default.
6692 EchoString
6695 A message to be displayed when the target is built.
6696 A message to display on some generators (such as makefiles) when
6698 the target is built.
6699 FOLDER Set the folder name. Use to organize targets in an IDE.
6702 Targets with no FOLDER property will appear as top level enti‐
6704 ties in IDEs like Visual Studio. Targets with the same FOLDER
6705 property value will appear next to each other in a folder of
6706 that name. To nest folders, use FOLDER values such as
6707 'GUI/Dialogs' with '/' characters separating folder levels.
6708 FRAMEWORK
6711 This target is a framework on the Mac.
6712 If a shared library target has this property set to true it will
6714 be built as a framework when built on the mac. It will have the
6715 directory structure required for a framework and will be suit‐
6716 able to be used with the -framework option
6717 Fortran_FORMAT
6720 Set to FIXED or FREE to indicate the Fortran source layout.
6721 This property tells CMake whether the Fortran source files in a
6723 target use fixed-format or free-format. CMake will pass the
6724 corresponding format flag to the compiler. Use the source-spe‐
6725 cific Fortran_FORMAT property to change the format of a specific
6726 source file. If the variable CMAKE_Fortran_FORMAT is set when a
6727 target is created its value is used to initialize this property.
6728 Fortran_MODULE_DIRECTORY
6731 Specify output directory for Fortran modules provided by the
6732 target.
6733 If the target contains Fortran source files that provide modules
6735 and the compiler supports a module output directory this speci‐
6736 fies the directory in which the modules will be placed. When
6737 this property is not set the modules will be placed in the build
6738 directory corresponding to the target's source directory. If
6739 the variable CMAKE_Fortran_MODULE_DIRECTORY is set when a target
6740 is created its value is used to initialize this property.
6741 Note that some compilers will automatically search the module
6744 output directory for modules USEd during compilation but others
6745 will not. If your sources USE modules their location must be
6746 specified by INCLUDE_DIRECTORIES regardless of this property.
6747 GENERATOR_FILE_NAME
6750 Generator's file for this target.
6751 An internal property used by some generators to record the name
6753 of the project or dsp file associated with this target. Note
6754 that at configure time, this property is only set for targets
6755 created by include_external_msproject().
6756 GNUtoMS
6759 Convert GNU import library (.dll.a) to MS format (.lib).
6760 When linking a shared library or executable that exports symbols
6762 using GNU tools on Windows (MinGW/MSYS) with Visual Studio
6763 installed convert the import library (.dll.a) from GNU to MS
6764 format (.lib). Both import libraries will be installed by
6765 install(TARGETS) and exported by install(EXPORT) and export() to
6766 be linked by applications with either GNU- or MS-compatible
6767 tools.
6768 If the variable CMAKE_GNUtoMS is set when a target is created
6771 its value is used to initialize this property. The variable
6772 must be set prior to the first command that enables a language
6773 such as project() or enable_language(). CMake provides the
6774 variable as an option to the user automatically when configuring
6775 on Windows with GNU tools.
6776 HAS_CXX
6779 Link the target using the C++ linker tool (obsolete).
6780 This is equivalent to setting the LINKER_LANGUAGE property to
6782 CXX. See that property's documentation for details.
6783 IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
6786 Specify #include line transforms for dependencies in a target.
6787 This property specifies rules to transform macro-like #include
6789 lines during implicit dependency scanning of C and C++ source
6790 files. The list of rules must be semicolon-separated with each
6791 entry of the form "A_MACRO(%)=value-with-%" (the % must be lit‐
6792 eral). During dependency scanning occurrences of A_MACRO(...)
6793 on #include lines will be replaced by the value given with the
6794 macro argument substituted for '%'. For example, the entry
6795 MYDIR(%)=<mydir/%>
6798 will convert lines of the form
6800 #include MYDIR(myheader.h)
6803 to
6805 #include <mydir/myheader.h>
6808 allowing the dependency to be followed.
6810 This property applies to sources in the target on which it is
6813 set.
6814 IMPORTED
6817 Read-only indication of whether a target is IMPORTED.
6818 The boolean value of this property is true for targets created
6820 with the IMPORTED option to add_executable or add_library. It
6821 is false for targets built within the project.
6822 IMPORTED_CONFIGURATIONS
6825 Configurations provided for an IMPORTED target.
6826 Set this to the list of configuration names available for an
6828 IMPORTED target. The names correspond to configurations defined
6829 in the project from which the target is imported. If the
6830 importing project uses a different set of configurations the
6831 names may be mapped using the MAP_IMPORTED_CONFIG_<CONFIG> prop‐
6832 erty. Ignored for non-imported targets.
6833 IMPORTED_IMPLIB
6836 Full path to the import library for an IMPORTED target.
6837 Set this to the location of the ".lib" part of a windows DLL.
6839 Ignored for non-imported targets.
6840 IMPORTED_IMPLIB_<CONFIG>
6843 <CONFIG>-specific version of IMPORTED_IMPLIB property.
6844 Configuration names correspond to those provided by the project
6846 from which the target is imported.
6847 IMPORTED_LINK_DEPENDENT_LIBRARIES
6850 Dependent shared libraries of an imported shared library.
6851 Shared libraries may be linked to other shared libraries as part
6853 of their implementation. On some platforms the linker searches
6854 for the dependent libraries of shared libraries they are includ‐
6855 ing in the link. Set this property to the list of dependent
6856 shared libraries of an imported library. The list should be
6857 disjoint from the list of interface libraries in the INTER‐
6858 FACE_LINK_LIBRARIES property. On platforms requiring dependent
6859 shared libraries to be found at link time CMake uses this list
6860 to add appropriate files or paths to the link command line.
6861 Ignored for non-imported targets.
6862 IMPORTED_LINK_DEPENDENT_LIBRARIES_<CONFIG>
6865 <CONFIG>-specific version of IMPORTED_LINK_DEPENDENT_LIBRARIES.
6866 Configuration names correspond to those provided by the project
6868 from which the target is imported. If set, this property com‐
6869 pletely overrides the generic property for the named configura‐
6870 tion.
6871 IMPORTED_LINK_INTERFACE_LANGUAGES
6874 Languages compiled into an IMPORTED static library.
6875 Set this to the list of languages of source files compiled to
6877 produce a STATIC IMPORTED library (such as "C" or "CXX"). CMake
6878 accounts for these languages when computing how to link a target
6879 to the imported library. For example, when a C executable links
6880 to an imported C++ static library CMake chooses the C++ linker
6881 to satisfy language runtime dependencies of the static library.
6882 This property is ignored for targets that are not STATIC
6885 libraries. This property is ignored for non-imported targets.
6886 IMPORTED_LINK_INTERFACE_LANGUAGES_<CONFIG>
6889 <CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LANGUAGES.
6890 Configuration names correspond to those provided by the project
6892 from which the target is imported. If set, this property com‐
6893 pletely overrides the generic property for the named configura‐
6894 tion.
6895 IMPORTED_LINK_INTERFACE_LIBRARIES
6898 Transitive link interface of an IMPORTED target.
6899 Set this to the list of libraries whose interface is included
6901 when an IMPORTED library target is linked to another target.
6902 The libraries will be included on the link line for the target.
6903 Unlike the LINK_INTERFACE_LIBRARIES property, this property
6904 applies to all imported target types, including STATIC
6905 libraries. This property is ignored for non-imported targets.
6906 This property is ignored if the target also has a non-empty
6909 INTERFACE_LINK_LIBRARIES property.
6910 This property is deprecated. Use INTERFACE_LINK_LIBRARIES
6913 instead.
6914 IMPORTED_LINK_INTERFACE_LIBRARIES_<CONFIG>
6917 <CONFIG>-specific version of IMPORTED_LINK_INTERFACE_LIBRARIES.
6918 Configuration names correspond to those provided by the project
6920 from which the target is imported. If set, this property com‐
6921 pletely overrides the generic property for the named configura‐
6922 tion.
6923 This property is ignored if the target also has a non-empty
6926 INTERFACE_LINK_LIBRARIES property.
6927 This property is deprecated. Use INTERFACE_LINK_LIBRARIES
6930 instead.
6931 IMPORTED_LINK_INTERFACE_MULTIPLICITY
6934 Repetition count for cycles of IMPORTED static libraries.
6935 This is LINK_INTERFACE_MULTIPLICITY for IMPORTED targets.
6937 IMPORTED_LINK_INTERFACE_MULTIPLICITY_<CONFIG>
6940 <CONFIG>-specific version of IMPORTED_LINK_INTERFACE_MULTIPLIC‐
6941 ITY.
6942 If set, this property completely overrides the generic property
6944 for the named configuration.
6945 IMPORTED_LOCATION
6948 Full path to the main file on disk for an IMPORTED target.
6949 Set this to the location of an IMPORTED target file on disk.
6951 For executables this is the location of the executable file.
6952 For bundles on OS X this is the location of the executable file
6953 inside Contents/MacOS under the application bundle folder. For
6954 static libraries and modules this is the location of the library
6955 or module. For shared libraries on non-DLL platforms this is
6956 the location of the shared library. For frameworks on OS X this
6957 is the location of the library file symlink just inside the
6958 framework folder. For DLLs this is the location of the ".dll"
6959 part of the library. For UNKNOWN libraries this is the location
6960 of the file to be linked. Ignored for non-imported targets.
6961 Projects may skip IMPORTED_LOCATION if the configuration-spe‐
6964 cific property IMPORTED_LOCATION_<CONFIG> is set. To get the
6965 location of an imported target read one of the LOCATION or LOCA‐
6966 TION_<CONFIG> properties.
6967 IMPORTED_LOCATION_<CONFIG>
6970 <CONFIG>-specific version of IMPORTED_LOCATION property.
6971 Configuration names correspond to those provided by the project
6973 from which the target is imported.
6974 IMPORTED_NO_SONAME
6977 Specifies that an IMPORTED shared library target has no "son‐
6978 ame".
6979 Set this property to true for an imported shared library file
6981 that has no "soname" field. CMake may adjust generated link
6982 commands for some platforms to prevent the linker from using the
6983 path to the library in place of its missing soname. Ignored for
6984 non-imported targets.
6985 IMPORTED_NO_SONAME_<CONFIG>
6988 <CONFIG>-specific version of IMPORTED_NO_SONAME property.
6989 Configuration names correspond to those provided by the project
6991 from which the target is imported.
6992 IMPORTED_SONAME
6995 The "soname" of an IMPORTED target of shared library type.
6996 Set this to the "soname" embedded in an imported shared library.
6998 This is meaningful only on platforms supporting the feature.
6999 Ignored for non-imported targets.
7000 IMPORTED_SONAME_<CONFIG>
7003 <CONFIG>-specific version of IMPORTED_SONAME property.
7004 Configuration names correspond to those provided by the project
7006 from which the target is imported.
7007 IMPORT_PREFIX
7010 What comes before the import library name.
7011 Similar to the target property PREFIX, but used for import
7013 libraries (typically corresponding to a DLL) instead of regular
7014 libraries. A target property that can be set to override the
7015 prefix (such as "lib") on an import library name.
7016 IMPORT_SUFFIX
7019 What comes after the import library name.
7020 Similar to the target property SUFFIX, but used for import
7022 libraries (typically corresponding to a DLL) instead of regular
7023 libraries. A target property that can be set to override the
7024 suffix (such as ".lib") on an import library name.
7025 INCLUDE_DIRECTORIES
7028 List of preprocessor include file search directories.
7029 This property specifies the list of directories given so far to
7031 the include_directories command. This property exists on direc‐
7032 tories and targets. In addition to accepting values from the
7033 include_directories command, values may be set directly on any
7034 directory or any target using the set_property command. A target
7035 gets its initial value for this property from the value of the
7036 directory property. A directory gets its initial value from its
7037 parent directory if it has one. Both directory and target prop‐
7038 erty values are adjusted by calls to the include_directories
7039 command.
7040 The target property values are used by the generators to set the
7043 include paths for the compiler. See also the include_directo‐
7044 ries command.
7045 Contents of INCLUDE_DIRECTORIES may use "generator expressions"
7048 with the syntax "$<...>". Generator expressions are evaluated
7049 during build system generation to produce information specific
7050 to each build configuration. Valid expressions are:
7051 $<0:...> = empty string (ignores "...")
7054 $<1:...> = content of "..."
7055 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
7056 $<CONFIGURATION> = configuration name
7057 $<BOOL:...> = '1' if the '...' is true, else '0'
7058 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
7059 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
7060 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
7061 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
7062 $<JOIN:list,...> = joins the list with the content of "..."
7063 $<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.
7064 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
7065 $<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.
7066 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
7067 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
7068 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
7069 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
7070 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
7071 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
7072 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
7073 $<C_COMPILER_VERSION> = The version of the C compiler used.
7074 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
7075 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
7076 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
7077 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
7078 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
7079 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
7080 where "tgt" is the name of a target. Target file expressions
7082 produce a full path, but _DIR and _NAME versions can produce the
7083 directory and file name components:
7084 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
7087 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
7088 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
7089 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
7094 Note that tgt is not added as a dependency of the target this
7096 expression is evaluated on.
7097 $<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.
7100 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
7101 Boolean expressions:
7103 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
7106 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
7107 $<NOT:?> = '0' if '?' is '1', else '1'
7108 where '?' is always either '0' or '1'.
7110 Expressions with an implicit 'this' target:
7113 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
7116 INSTALL_NAME_DIR
7119 Mac OSX directory name for installed targets.
7120 INSTALL_NAME_DIR is a string specifying the directory portion of
7122 the "install_name" field of shared libraries on Mac OSX to use
7123 in the installed targets.
7124 INSTALL_RPATH
7127 The rpath to use for installed targets.
7128 A semicolon-separated list specifying the rpath to use in
7130 installed targets (for platforms that support it). This prop‐
7131 erty is initialized by the value of the variable
7132 CMAKE_INSTALL_RPATH if it is set when a target is created.
7133 INSTALL_RPATH_USE_LINK_PATH
7136 Add paths to linker search and installed rpath.
7137 INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to true
7139 will append directories in the linker search path and outside
7140 the project to the INSTALL_RPATH. This property is initialized
7141 by the value of the variable CMAKE_INSTALL_RPATH_USE_LINK_PATH
7142 if it is set when a target is created.
7143 INTERFACE_COMPILE_DEFINITIONS
7146 List of public compile definitions for a library.
7147 Targets may populate this property to publish the compile defi‐
7149 nitions required to compile against the headers for the target.
7150 Consuming targets can add entries to their own COMPILE_DEFINI‐
7151 TIONS property such as $<TARGET_PROPERTY:foo,INTERFACE_COM‐
7152 PILE_DEFINITIONS> to use the compile definitions specified in
7153 the interface of 'foo'.
7154 Generator expressions are evaluated during build system genera‐
7157 tion to produce information specific to each build configura‐
7158 tion. Valid expressions are:
7159 $<0:...> = empty string (ignores "...")
7162 $<1:...> = content of "..."
7163 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
7164 $<CONFIGURATION> = configuration name
7165 $<BOOL:...> = '1' if the '...' is true, else '0'
7166 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
7167 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
7168 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
7169 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
7170 $<JOIN:list,...> = joins the list with the content of "..."
7171 $<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.
7172 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
7173 $<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.
7174 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
7175 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
7176 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
7177 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
7178 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
7179 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
7180 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
7181 $<C_COMPILER_VERSION> = The version of the C compiler used.
7182 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
7183 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
7184 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
7185 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
7186 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
7187 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
7188 where "tgt" is the name of a target. Target file expressions
7190 produce a full path, but _DIR and _NAME versions can produce the
7191 directory and file name components:
7192 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
7195 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
7196 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
7197 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
7202 Note that tgt is not added as a dependency of the target this
7204 expression is evaluated on.
7205 $<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.
7208 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
7209 Boolean expressions:
7211 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
7214 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
7215 $<NOT:?> = '0' if '?' is '1', else '1'
7216 where '?' is always either '0' or '1'.
7218 Expressions with an implicit 'this' target:
7221 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
7224 INTERFACE_COMPILE_OPTIONS
7227 List of interface options to pass to the compiler.
7228 Targets may populate this property to publish the compile
7230 options required to compile against the headers for the target.
7231 Consuming targets can add entries to their own COMPILE_OPTIONS
7232 property such as $<TARGET_PROPERTY:foo,INTERFACE_COM‐
7233 PILE_OPTIONS> to use the compile options specified in the inter‐
7234 face of 'foo'.
7235 Generator expressions are evaluated during build system genera‐
7238 tion to produce information specific to each build configura‐
7239 tion. Valid expressions are:
7240 $<0:...> = empty string (ignores "...")
7243 $<1:...> = content of "..."
7244 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
7245 $<CONFIGURATION> = configuration name
7246 $<BOOL:...> = '1' if the '...' is true, else '0'
7247 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
7248 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
7249 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
7250 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
7251 $<JOIN:list,...> = joins the list with the content of "..."
7252 $<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.
7253 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
7254 $<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.
7255 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
7256 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
7257 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
7258 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
7259 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
7260 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
7261 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
7262 $<C_COMPILER_VERSION> = The version of the C compiler used.
7263 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
7264 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
7265 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
7266 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
7267 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
7268 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
7269 where "tgt" is the name of a target. Target file expressions
7271 produce a full path, but _DIR and _NAME versions can produce the
7272 directory and file name components:
7273 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
7276 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
7277 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
7278 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
7283 Note that tgt is not added as a dependency of the target this
7285 expression is evaluated on.
7286 $<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.
7289 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
7290 Boolean expressions:
7292 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
7295 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
7296 $<NOT:?> = '0' if '?' is '1', else '1'
7297 where '?' is always either '0' or '1'.
7299 Expressions with an implicit 'this' target:
7302 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
7305 INTERFACE_INCLUDE_DIRECTORIES
7308 List of public include directories for a library.
7309 Targets may populate this property to publish the include direc‐
7311 tories required to compile against the headers for the target.
7312 Consuming targets can add entries to their own INCLUDE_DIRECTO‐
7313 RIES property such as $<TARGET_PROPERTY:foo,INTER‐
7314 FACE_INCLUDE_DIRECTORIES> to use the include directories speci‐
7315 fied in the interface of 'foo'.
7316 Generator expressions are evaluated during build system genera‐
7319 tion to produce information specific to each build configura‐
7320 tion. Valid expressions are:
7321 $<0:...> = empty string (ignores "...")
7324 $<1:...> = content of "..."
7325 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
7326 $<CONFIGURATION> = configuration name
7327 $<BOOL:...> = '1' if the '...' is true, else '0'
7328 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
7329 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
7330 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
7331 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
7332 $<JOIN:list,...> = joins the list with the content of "..."
7333 $<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.
7334 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
7335 $<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.
7336 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
7337 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
7338 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
7339 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
7340 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
7341 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
7342 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
7343 $<C_COMPILER_VERSION> = The version of the C compiler used.
7344 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
7345 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
7346 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
7347 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
7348 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
7349 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
7350 where "tgt" is the name of a target. Target file expressions
7352 produce a full path, but _DIR and _NAME versions can produce the
7353 directory and file name components:
7354 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
7357 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
7358 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
7359 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
7364 Note that tgt is not added as a dependency of the target this
7366 expression is evaluated on.
7367 $<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.
7370 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
7371 Boolean expressions:
7373 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
7376 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
7377 $<NOT:?> = '0' if '?' is '1', else '1'
7378 where '?' is always either '0' or '1'.
7380 Expressions with an implicit 'this' target:
7383 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
7386 INTERFACE_LINK_LIBRARIES
7389 List public interface libraries for a library.
7390 This property contains the list of transitive link dependencies.
7392 When the target is linked into another target the libraries
7393 listed (and recursively their link interface libraries) will be
7394 provided to the other target also. This property is overridden
7395 by the LINK_INTERFACE_LIBRARIES or LINK_INTER‐
7396 FACE_LIBRARIES_<CONFIG> property if policy CMP0022 is OLD or
7397 unset.
7398 Generator expressions are evaluated during build system genera‐
7404 tion to produce information specific to each build configura‐
7405 tion. Valid expressions are:
7406 $<0:...> = empty string (ignores "...")
7409 $<1:...> = content of "..."
7410 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
7411 $<CONFIGURATION> = configuration name
7412 $<BOOL:...> = '1' if the '...' is true, else '0'
7413 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
7414 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
7415 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
7416 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
7417 $<JOIN:list,...> = joins the list with the content of "..."
7418 $<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.
7419 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
7420 $<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.
7421 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
7422 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
7423 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
7424 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
7425 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
7426 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
7427 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
7428 $<C_COMPILER_VERSION> = The version of the C compiler used.
7429 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
7430 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
7431 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
7432 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
7433 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
7434 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
7435 where "tgt" is the name of a target. Target file expressions
7437 produce a full path, but _DIR and _NAME versions can produce the
7438 directory and file name components:
7439 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
7442 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
7443 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
7444 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
7449 Note that tgt is not added as a dependency of the target this
7451 expression is evaluated on.
7452 $<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.
7455 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
7456 Boolean expressions:
7458 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
7461 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
7462 $<NOT:?> = '0' if '?' is '1', else '1'
7463 where '?' is always either '0' or '1'.
7465 Expressions with an implicit 'this' target:
7468 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
7471 INTERFACE_POSITION_INDEPENDENT_CODE
7474 Whether consumers need to create a position-independent target
7475 The INTERFACE_POSITION_INDEPENDENT_CODE property informs con‐
7477 sumers of this target whether they must set their POSITION_INDE‐
7478 PENDENT_CODE property to ON. If this property is set to ON,
7479 then the POSITION_INDEPENDENT_CODE property on all consumers
7480 will be set to ON. Similarly, if this property is set to OFF,
7481 then the POSITION_INDEPENDENT_CODE property on all consumers
7482 will be set to OFF. If this property is undefined, then con‐
7483 sumers will determine their POSITION_INDEPENDENT_CODE property
7484 by other means. Consumers must ensure that the targets that
7485 they link to have a consistent requirement for their INTER‐
7486 FACE_POSITION_INDEPENDENT_CODE property.
7487 INTERFACE_SYSTEM_INCLUDE_DIRECTORIES
7490 List of public system include directories for a library.
7491 Targets may populate this property to publish the include direc‐
7493 tories which contain system headers, and therefore should not
7494 result in compiler warnings. Consuming targets will then mark
7495 the same include directories as system headers.
7496 Generator expressions are evaluated during build system genera‐
7499 tion to produce information specific to each build configura‐
7500 tion. Valid expressions are:
7501 $<0:...> = empty string (ignores "...")
7504 $<1:...> = content of "..."
7505 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
7506 $<CONFIGURATION> = configuration name
7507 $<BOOL:...> = '1' if the '...' is true, else '0'
7508 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
7509 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
7510 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
7511 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
7512 $<JOIN:list,...> = joins the list with the content of "..."
7513 $<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.
7514 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
7515 $<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.
7516 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
7517 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
7518 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
7519 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
7520 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
7521 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
7522 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
7523 $<C_COMPILER_VERSION> = The version of the C compiler used.
7524 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
7525 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
7526 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
7527 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
7528 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
7529 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
7530 where "tgt" is the name of a target. Target file expressions
7532 produce a full path, but _DIR and _NAME versions can produce the
7533 directory and file name components:
7534 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
7537 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
7538 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
7539 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
7544 Note that tgt is not added as a dependency of the target this
7546 expression is evaluated on.
7547 $<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.
7550 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
7551 Boolean expressions:
7553 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
7556 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
7557 $<NOT:?> = '0' if '?' is '1', else '1'
7558 where '?' is always either '0' or '1'.
7560 Expressions with an implicit 'this' target:
7563 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
7566 INTERPROCEDURAL_OPTIMIZATION
7569 Enable interprocedural optimization for a target.
7570 If set to true, enables interprocedural optimizations if they
7572 are known to be supported by the compiler.
7573 INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
7576 Per-configuration interprocedural optimization for a target.
7577 This is a per-configuration version of INTERPROCEDURAL_OPTIMIZA‐
7579 TION. If set, this property overrides the generic property for
7580 the named configuration.
7581 LABELS Specify a list of text labels associated with a target.
7584 Target label semantics are currently unspecified.
7586 LIBRARY_OUTPUT_DIRECTORY
7589 Output directory in which to build LIBRARY target files.
7590 This property specifies the directory into which library target
7592 files should be built. Multi-configuration generators (VS,
7593 Xcode) append a per-configuration subdirectory to the specified
7594 directory. There are three kinds of target files that may be
7595 built: archive, library, and runtime. Executables are always
7596 treated as runtime targets. Static libraries are always treated
7597 as archive targets. Module libraries are always treated as
7598 library targets. For non-DLL platforms shared libraries are
7599 treated as library targets. For DLL platforms the DLL part of a
7600 shared library is treated as a runtime target and the corre‐
7601 sponding import library is treated as an archive target. All
7602 Windows-based systems including Cygwin are DLL platforms. This
7603 property is initialized by the value of the variable
7604 CMAKE_LIBRARY_OUTPUT_DIRECTORY if it is set when a target is
7605 created.
7606 LIBRARY_OUTPUT_DIRECTORY_<CONFIG>
7609 Per-configuration output directory for LIBRARY target files.
7610 This is a per-configuration version of LIBRARY_OUTPUT_DIRECTORY,
7612 but multi-configuration generators (VS, Xcode) do NOT append a
7613 per-configuration subdirectory to the specified directory. This
7614 property is initialized by the value of the variable
7615 CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> if it is set when a tar‐
7616 get is created.
7617 LIBRARY_OUTPUT_NAME
7620 Output name for LIBRARY target files.
7621 This property specifies the base name for library target files.
7623 It overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
7624 There are three kinds of target files that may be built: ar‐
7625 chive, library, and runtime. Executables are always treated as
7626 runtime targets. Static libraries are always treated as archive
7627 targets. Module libraries are always treated as library targets.
7628 For non-DLL platforms shared libraries are treated as library
7629 targets. For DLL platforms the DLL part of a shared library is
7630 treated as a runtime target and the corresponding import library
7631 is treated as an archive target. All Windows-based systems
7632 including Cygwin are DLL platforms.
7633 LIBRARY_OUTPUT_NAME_<CONFIG>
7636 Per-configuration output name for LIBRARY target files.
7637 This is the configuration-specific version of LIBRARY_OUT‐
7639 PUT_NAME.
7640 LINKER_LANGUAGE
7643 Specifies language whose compiler will invoke the linker.
7644 For executables, shared libraries, and modules, this sets the
7646 language whose compiler is used to link the target (such as "C"
7647 or "CXX"). A typical value for an executable is the language of
7648 the source file providing the program entry point (main). If
7649 not set, the language with the highest linker preference value
7650 is the default. See documentation of CMAKE_<LANG>_LINKER_PREF‐
7651 ERENCE variables.
7652 If this property is not set by the user, it will be calculated
7655 at generate-time by CMake.
7656 LINK_DEPENDS
7659 Additional files on which a target binary depends for linking.
7660 Specifies a semicolon-separated list of full-paths to files on
7662 which the link rule for this target depends. The target binary
7663 will be linked if any of the named files is newer than it.
7664 This property is ignored by non-Makefile generators. It is
7667 intended to specify dependencies on "linker scripts" for custom
7668 Makefile link rules.
7669 LINK_DEPENDS_NO_SHARED
7672 Do not depend on linked shared library files.
7673 Set this property to true to tell CMake generators not to add
7675 file-level dependencies on the shared library files linked by
7676 this target. Modification to the shared libraries will not be
7677 sufficient to re-link this target. Logical target-level depen‐
7678 dencies will not be affected so the linked shared libraries will
7679 still be brought up to date before this target is built.
7680 This property is initialized by the value of the variable
7683 CMAKE_LINK_DEPENDS_NO_SHARED if it is set when a target is cre‐
7684 ated.
7685 LINK_FLAGS
7688 Additional flags to use when linking this target.
7689 The LINK_FLAGS property can be used to add extra flags to the
7691 link step of a target. LINK_FLAGS_<CONFIG> will add to the con‐
7692 figuration <CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL,
7693 RELWITHDEBINFO.
7694 LINK_FLAGS_<CONFIG>
7697 Per-configuration linker flags for a target.
7698 This is the configuration-specific version of LINK_FLAGS.
7700 LINK_INTERFACE_LIBRARIES
7703 List public interface libraries for a shared library or exe‐
7704 cutable.
7705 By default linking to a shared library target transitively links
7707 to targets with which the library itself was linked. For an
7708 executable with exports (see the ENABLE_EXPORTS property) no
7709 default transitive link dependencies are used. This property
7710 replaces the default transitive link dependencies with an
7711 explicit list. When the target is linked into another target
7712 the libraries listed (and recursively their link interface
7713 libraries) will be provided to the other target also. If the
7714 list is empty then no transitive link dependencies will be
7715 incorporated when this target is linked into another target even
7716 if the default set is non-empty. This property is initialized
7717 by the value of the variable CMAKE_LINK_INTERFACE_LIBRARIES if
7718 it is set when a target is created. This property is ignored
7719 for STATIC libraries.
7720 This property is overridden by the INTERFACE_LINK_LIBRARIES
7723 property if policy CMP0022 is NEW.
7724 This property is deprecated. Use INTERFACE_LINK_LIBRARIES
7727 instead.
7728 LINK_INTERFACE_LIBRARIES_<CONFIG>
7731 Per-configuration list of public interface libraries for a tar‐
7732 get.
7733 This is the configuration-specific version of LINK_INTER‐
7735 FACE_LIBRARIES. If set, this property completely overrides the
7736 generic property for the named configuration.
7737 This property is overridden by the INTERFACE_LINK_LIBRARIES
7740 property if policy CMP0022 is NEW.
7741 This property is deprecated. Use INTERFACE_LINK_LIBRARIES
7744 instead.
7745 LINK_INTERFACE_MULTIPLICITY
7748 Repetition count for STATIC libraries with cyclic dependencies.
7749 When linking to a STATIC library target with cyclic dependencies
7751 the linker may need to scan more than once through the archives
7752 in the strongly connected component of the dependency graph.
7753 CMake by default constructs the link line so that the linker
7754 will scan through the component at least twice. This property
7755 specifies the minimum number of scans if it is larger than the
7756 default. CMake uses the largest value specified by any target
7757 in a component.
7758 LINK_INTERFACE_MULTIPLICITY_<CONFIG>
7761 Per-configuration repetition count for cycles of STATIC
7762 libraries.
7763 This is the configuration-specific version of LINK_INTER‐
7765 FACE_MULTIPLICITY. If set, this property completely overrides
7766 the generic property for the named configuration.
7767 LINK_LIBRARIES
7770 List of direct link dependencies.
7771 This property specifies the list of libraries or targets which
7773 will be used for linking. In addition to accepting values from
7774 the target_link_libraries command, values may be set directly on
7775 any target using the set_property command.
7776 The target property values are used by the generators to set the
7779 link libraries for the compiler. See also the tar‐
7780 get_link_libraries command.
7781 Contents of LINK_LIBRARIES may use "generator expressions" with
7784 the syntax "$<...>". Generator expressions are evaluated during
7785 build system generation to produce information specific to each
7786 build configuration. Valid expressions are:
7787 $<0:...> = empty string (ignores "...")
7790 $<1:...> = content of "..."
7791 $<CONFIG:cfg> = '1' if config is "cfg", else '0'
7792 $<CONFIGURATION> = configuration name
7793 $<BOOL:...> = '1' if the '...' is true, else '0'
7794 $<STREQUAL:a,b> = '1' if a is STREQUAL b, else '0'
7795 $<ANGLE-R> = A literal '>'. Used to compare strings which contain a '>' for example.
7796 $<COMMA> = A literal ','. Used to compare strings which contain a ',' for example.
7797 $<SEMICOLON> = A literal ';'. Used to prevent list expansion on an argument with ';'.
7798 $<JOIN:list,...> = joins the list with the content of "..."
7799 $<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.
7800 $<INSTALL_INTERFACE:...> = content of "..." when the property is exported using install(EXPORT), and empty otherwise.
7801 $<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.
7802 $<C_COMPILER_ID> = The CMake-id of the C compiler used.
7803 $<C_COMPILER_ID:comp> = '1' if the CMake-id of the C compiler matches comp, otherwise '0'.
7804 $<CXX_COMPILER_ID> = The CMake-id of the CXX compiler used.
7805 $<CXX_COMPILER_ID:comp> = '1' if the CMake-id of the CXX compiler matches comp, otherwise '0'.
7806 $<VERSION_GREATER:v1,v2> = '1' if v1 is a version greater than v2, else '0'.
7807 $<VERSION_LESS:v1,v2> = '1' if v1 is a version less than v2, else '0'.
7808 $<VERSION_EQUAL:v1,v2> = '1' if v1 is the same version as v2, else '0'.
7809 $<C_COMPILER_VERSION> = The version of the C compiler used.
7810 $<C_COMPILER_VERSION:ver> = '1' if the version of the C compiler matches ver, otherwise '0'.
7811 $<CXX_COMPILER_VERSION> = The version of the CXX compiler used.
7812 $<CXX_COMPILER_VERSION:ver> = '1' if the version of the CXX compiler matches ver, otherwise '0'.
7813 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
7814 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
7815 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
7816 where "tgt" is the name of a target. Target file expressions
7818 produce a full path, but _DIR and _NAME versions can produce the
7819 directory and file name components:
7820 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
7823 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
7824 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
7825 $<TARGET_PROPERTY:tgt,prop> = The value of the property prop on the target tgt.
7830 Note that tgt is not added as a dependency of the target this
7832 expression is evaluated on.
7833 $<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.
7836 $<INSTALL_PREFIX> = Content of the install prefix when the target is exported via INSTALL(EXPORT) and empty otherwise.
7837 Boolean expressions:
7839 $<AND:?[,?]...> = '1' if all '?' are '1', else '0'
7842 $<OR:?[,?]...> = '0' if all '?' are '0', else '1'
7843 $<NOT:?> = '0' if '?' is '1', else '1'
7844 where '?' is always either '0' or '1'.
7846 Expressions with an implicit 'this' target:
7849 $<TARGET_PROPERTY:prop> = The value of the property prop on the target on which the generator expression is evaluated.
7852 LINK_SEARCH_END_STATIC
7855 End a link line such that static system libraries are used.
7856 Some linkers support switches such as -Bstatic and -Bdynamic to
7858 determine whether to use static or shared libraries for -lXXX
7859 options. CMake uses these options to set the link type for
7860 libraries whose full paths are not known or (in some cases) are
7861 in implicit link directories for the platform. By default CMake
7862 adds an option at the end of the library list (if necessary) to
7863 set the linker search type back to its starting type. This
7864 property switches the final linker search type to -Bstatic
7865 regardless of how it started. See also
7866 LINK_SEARCH_START_STATIC.
7867 LINK_SEARCH_START_STATIC
7870 Assume the linker looks for static libraries by default.
7871 Some linkers support switches such as -Bstatic and -Bdynamic to
7873 determine whether to use static or shared libraries for -lXXX
7874 options. CMake uses these options to set the link type for
7875 libraries whose full paths are not known or (in some cases) are
7876 in implicit link directories for the platform. By default the
7877 linker search type is assumed to be -Bdynamic at the beginning
7878 of the library list. This property switches the assumption to
7879 -Bstatic. It is intended for use when linking an executable
7880 statically (e.g. with the GNU -static option). See also
7881 LINK_SEARCH_END_STATIC.
7882 LOCATION
7885 Read-only location of a target on disk.
7886 For an imported target, this read-only property returns the
7888 value of the LOCATION_<CONFIG> property for an unspecified con‐
7889 figuration <CONFIG> provided by the target.
7890 For a non-imported target, this property is provided for compat‐
7893 ibility with CMake 2.4 and below. It was meant to get the loca‐
7894 tion of an executable target's output file for use in add_cus‐
7895 tom_command. The path may contain a build-system-specific por‐
7896 tion that is replaced at build time with the configuration get‐
7897 ting built (such as "$(ConfigurationName)" in VS). In CMake 2.6
7898 and above add_custom_command automatically recognizes a target
7899 name in its COMMAND and DEPENDS options and computes the target
7900 location. In CMake 2.8.4 and above add_custom_command recog‐
7901 nizes generator expressions to refer to target locations any‐
7902 where in the command. Therefore this property is not needed for
7903 creating custom commands.
7904 Do not set properties that affect the location of a target after
7907 reading this property. These include properties whose names
7908 match "(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CON‐
7909 FIG>)?", "(IMPLIB_)?(PREFIX|SUFFIX)", or "LINKER_LANGUAGE".
7910 Failure to follow this rule is not diagnosed and leaves the
7911 location of the target undefined.
7912 LOCATION_<CONFIG>
7915 Read-only property providing a target location on disk.
7916 A read-only property that indicates where a target's main file
7918 is located on disk for the configuration <CONFIG>. The property
7919 is defined only for library and executable targets. An imported
7920 target may provide a set of configurations different from that
7921 of the importing project. By default CMake looks for an
7922 exact-match but otherwise uses an arbitrary available configura‐
7923 tion. Use the MAP_IMPORTED_CONFIG_<CONFIG> property to map
7924 imported configurations explicitly.
7925 Do not set properties that affect the location of a target after
7928 reading this property. These include properties whose names
7929 match "(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CON‐
7930 FIG>)?", "(IMPLIB_)?(PREFIX|SUFFIX)", or "LINKER_LANGUAGE".
7931 Failure to follow this rule is not diagnosed and leaves the
7932 location of the target undefined.
7933 MACOSX_BUNDLE
7936 Build an executable as an application bundle on Mac OS X.
7937 When this property is set to true the executable when built on
7939 Mac OS X will be created as an application bundle. This makes
7940 it a GUI executable that can be launched from the Finder. See
7941 the MACOSX_BUNDLE_INFO_PLIST target property for information
7942 about creation of the Info.plist file for the application bun‐
7943 dle. This property is initialized by the value of the variable
7944 CMAKE_MACOSX_BUNDLE if it is set when a target is created.
7945 MACOSX_BUNDLE_INFO_PLIST
7948 Specify a custom Info.plist template for a Mac OS X App Bundle.
7949 An executable target with MACOSX_BUNDLE enabled will be built as
7951 an application bundle on Mac OS X. By default its Info.plist
7952 file is created by configuring a template called MacOSXBundle‐
7953 Info.plist.in located in the CMAKE_MODULE_PATH. This property
7954 specifies an alternative template file name which may be a full
7955 path.
7956 The following target properties may be set to specify content to
7959 be configured into the file:
7960 MACOSX_BUNDLE_INFO_STRING
7963 MACOSX_BUNDLE_ICON_FILE
7964 MACOSX_BUNDLE_GUI_IDENTIFIER
7965 MACOSX_BUNDLE_LONG_VERSION_STRING
7966 MACOSX_BUNDLE_BUNDLE_NAME
7967 MACOSX_BUNDLE_SHORT_VERSION_STRING
7968 MACOSX_BUNDLE_BUNDLE_VERSION
7969 MACOSX_BUNDLE_COPYRIGHT
7970 CMake variables of the same name may be set to affect all tar‐
7972 gets in a directory that do not have each specific property set.
7973 If a custom Info.plist is specified by this property it may of
7974 course hard-code all the settings instead of using the target
7975 properties.
7976 MACOSX_FRAMEWORK_INFO_PLIST
7979 Specify a custom Info.plist template for a Mac OS X Framework.
7980 A library target with FRAMEWORK enabled will be built as a
7982 framework on Mac OS X. By default its Info.plist file is cre‐
7983 ated by configuring a template called MacOSXFramework‐
7984 Info.plist.in located in the CMAKE_MODULE_PATH. This property
7985 specifies an alternative template file name which may be a full
7986 path.
7987 The following target properties may be set to specify content to
7990 be configured into the file:
7991 MACOSX_FRAMEWORK_ICON_FILE
7994 MACOSX_FRAMEWORK_IDENTIFIER
7995 MACOSX_FRAMEWORK_SHORT_VERSION_STRING
7996 MACOSX_FRAMEWORK_BUNDLE_VERSION
7997 CMake variables of the same name may be set to affect all tar‐
7999 gets in a directory that do not have each specific property set.
8000 If a custom Info.plist is specified by this property it may of
8001 course hard-code all the settings instead of using the target
8002 properties.
8003 MACOSX_RPATH
8006 Whether to use rpaths on Mac OS X.
8007 When this property is set to true, the directory portion of
8009 the"install_name" field of shared libraries will default to
8010 "@rpath".Runtime paths will also be embedded in binaries using
8011 this target.This property is initialized by the value of the
8012 variable CMAKE_MACOSX_RPATH if it is set when a target is cre‐
8013 ated.
8014 MAP_IMPORTED_CONFIG_<CONFIG>
8017 Map from project configuration to IMPORTED target's configura‐
8018 tion.
8019 Set this to the list of configurations of an imported target
8021 that may be used for the current project's <CONFIG> configura‐
8022 tion. Targets imported from another project may not provide the
8023 same set of configuration names available in the current
8024 project. Setting this property tells CMake what imported con‐
8025 figurations are suitable for use when building the <CONFIG> con‐
8026 figuration. The first configuration in the list found to be
8027 provided by the imported target is selected. If this property
8028 is set and no matching configurations are available, then the
8029 imported target is considered to be not found. This property is
8030 ignored for non-imported targets.
8031 NAME Logical name for the target.
8034 Read-only logical name for the target as used by CMake.
8036 NO_SONAME
8039 Whether to set "soname" when linking a shared library or module.
8040 Enable this boolean property if a generated shared library or
8042 module should not have "soname" set. Default is to set "soname"
8043 on all shared libraries and modules as long as the platform sup‐
8044 ports it. Generally, use this property only for leaf private
8045 libraries or plugins. If you use it on normal shared libraries
8046 which other targets link against, on some platforms a linker
8047 will insert a full path to the library (as specified at link
8048 time) into the dynamic section of the dependent binary. There‐
8049 fore, once installed, dynamic loader may eventually fail to
8050 locate the library for the binary.
8051 OSX_ARCHITECTURES
8054 Target specific architectures for OS X.
8055 The OSX_ARCHITECTURES property sets the target binary architec‐
8057 ture for targets on OS X. This property is initialized by the
8058 value of the variable CMAKE_OSX_ARCHITECTURES if it is set when
8059 a target is created. Use OSX_ARCHITECTURES_<CONFIG> to set the
8060 binary architectures on a per-configuration basis. <CONFIG> is
8061 an upper-case name (ex: "OSX_ARCHITECTURES_DEBUG").
8062 OSX_ARCHITECTURES_<CONFIG>
8065 Per-configuration OS X binary architectures for a target.
8066 This property is the configuration-specific version of
8068 OSX_ARCHITECTURES.
8069 OUTPUT_NAME
8072 Output name for target files.
8073 This sets the base name for output files created for an exe‐
8075 cutable or library target. If not set, the logical target name
8076 is used by default.
8077 OUTPUT_NAME_<CONFIG>
8080 Per-configuration target file base name.
8081 This is the configuration-specific version of OUTPUT_NAME.
8083 PDB_NAME
8086 Output name for MS debug symbols .pdb file from linker.
8087 Set the base name for debug symbols file created for an exe‐
8089 cutable or shared library target. If not set, the logical tar‐
8090 get name is used by default.
8091 This property is not implemented by the Visual Studio 6 genera‐
8094 tor.
8095 PDB_NAME_<CONFIG>
8098 Per-configuration name for MS debug symbols .pdb file.
8099 This is the configuration-specific version of PDB_NAME.
8101 This property is not implemented by the Visual Studio 6 genera‐
8104 tor.
8105 PDB_OUTPUT_DIRECTORY
8108 Output directory for MS debug symbols .pdb file from linker.
8109 This property specifies the directory into which the MS debug
8111 symbols will be placed by the linker. This property is initial‐
8112 ized by the value of the variable CMAKE_PDB_OUTPUT_DIRECTORY if
8113 it is set when a target is created.
8114 This property is not implemented by the Visual Studio 6 genera‐
8117 tor.
8118 PDB_OUTPUT_DIRECTORY_<CONFIG>
8121 Per-configuration output directory for MS debug symbols .pdb
8122 files.
8123 This is a per-configuration version of PDB_OUTPUT_DIRECTORY, but
8125 multi-configuration generators (VS, Xcode) do NOT append a
8126 per-configuration subdirectory to the specified directory. This
8127 property is initialized by the value of the variable
8128 CMAKE_PDB_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target
8129 is created.
8130 This property is not implemented by the Visual Studio 6 genera‐
8133 tor.
8134 POSITION_INDEPENDENT_CODE
8137 Whether to create a position-independent target
8138 The POSITION_INDEPENDENT_CODE property determines whether posi‐
8140 tion independent executables or shared libraries will be cre‐
8141 ated. This property is true by default for SHARED and MODULE
8142 library targets and false otherwise. This property is initial‐
8143 ized by the value of the variable CMAKE_POSITION_INDEPEN‐
8144 DENT_CODE if it is set when a target is created.
8145 POST_INSTALL_SCRIPT
8148 Deprecated install support.
8149 The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are
8151 the old way to specify CMake scripts to run before and after
8152 installing a target. They are used only when the old
8153 INSTALL_TARGETS command is used to install the target. Use the
8154 INSTALL command instead.
8155 PREFIX What comes before the library name.
8158 A target property that can be set to override the prefix (such
8160 as "lib") on a library name.
8161 PRE_INSTALL_SCRIPT
8164 Deprecated install support.
8165 The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are
8167 the old way to specify CMake scripts to run before and after
8168 installing a target. They are used only when the old
8169 INSTALL_TARGETS command is used to install the target. Use the
8170 INSTALL command instead.
8171 PRIVATE_HEADER
8174 Specify private header files in a FRAMEWORK shared library tar‐
8175 get.
8176 Shared library targets marked with the FRAMEWORK property gener‐
8178 ate frameworks on OS X and normal shared libraries on other
8179 platforms. This property may be set to a list of header files
8180 to be placed in the PrivateHeaders directory inside the frame‐
8181 work folder. On non-Apple platforms these headers may be
8182 installed using the PRIVATE_HEADER option to the install(TAR‐
8183 GETS) command.
8184 PROJECT_LABEL
8187 Change the name of a target in an IDE.
8188 Can be used to change the name of the target in an IDE like Vis‐
8190 ual Studio.
8191 PUBLIC_HEADER
8194 Specify public header files in a FRAMEWORK shared library tar‐
8195 get.
8196 Shared library targets marked with the FRAMEWORK property gener‐
8198 ate frameworks on OS X and normal shared libraries on other
8199 platforms. This property may be set to a list of header files
8200 to be placed in the Headers directory inside the framework
8201 folder. On non-Apple platforms these headers may be installed
8202 using the PUBLIC_HEADER option to the install(TARGETS) command.
8203 RESOURCE
8206 Specify resource files in a FRAMEWORK shared library target.
8207 Shared library targets marked with the FRAMEWORK property gener‐
8209 ate frameworks on OS X and normal shared libraries on other
8210 platforms. This property may be set to a list of files to be
8211 placed in the Resources directory inside the framework folder.
8212 On non-Apple platforms these files may be installed using the
8213 RESOURCE option to the install(TARGETS) command.
8214 RULE_LAUNCH_COMPILE
8217 Specify a launcher for compile rules.
8218 See the global property of the same name for details. This
8220 overrides the global and directory property for a target.
8221 RULE_LAUNCH_CUSTOM
8224 Specify a launcher for custom rules.
8225 See the global property of the same name for details. This
8227 overrides the global and directory property for a target.
8228 RULE_LAUNCH_LINK
8231 Specify a launcher for link rules.
8232 See the global property of the same name for details. This
8234 overrides the global and directory property for a target.
8235 RUNTIME_OUTPUT_DIRECTORY
8238 Output directory in which to build RUNTIME target files.
8239 This property specifies the directory into which runtime target
8241 files should be built. Multi-configuration generators (VS,
8242 Xcode) append a per-configuration subdirectory to the specified
8243 directory. There are three kinds of target files that may be
8244 built: archive, library, and runtime. Executables are always
8245 treated as runtime targets. Static libraries are always treated
8246 as archive targets. Module libraries are always treated as
8247 library targets. For non-DLL platforms shared libraries are
8248 treated as library targets. For DLL platforms the DLL part of a
8249 shared library is treated as a runtime target and the corre‐
8250 sponding import library is treated as an archive target. All
8251 Windows-based systems including Cygwin are DLL platforms. This
8252 property is initialized by the value of the variable CMAKE_RUN‐
8253 TIME_OUTPUT_DIRECTORY if it is set when a target is created.
8254 RUNTIME_OUTPUT_DIRECTORY_<CONFIG>
8257 Per-configuration output directory for RUNTIME target files.
8258 This is a per-configuration version of RUNTIME_OUTPUT_DIRECTORY,
8260 but multi-configuration generators (VS, Xcode) do NOT append a
8261 per-configuration subdirectory to the specified directory. This
8262 property is initialized by the value of the variable CMAKE_RUN‐
8263 TIME_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is
8264 created.
8265 RUNTIME_OUTPUT_NAME
8268 Output name for RUNTIME target files.
8269 This property specifies the base name for runtime target files.
8271 It overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
8272 There are three kinds of target files that may be built: ar‐
8273 chive, library, and runtime. Executables are always treated as
8274 runtime targets. Static libraries are always treated as archive
8275 targets. Module libraries are always treated as library targets.
8276 For non-DLL platforms shared libraries are treated as library
8277 targets. For DLL platforms the DLL part of a shared library is
8278 treated as a runtime target and the corresponding import library
8279 is treated as an archive target. All Windows-based systems
8280 including Cygwin are DLL platforms.
8281 RUNTIME_OUTPUT_NAME_<CONFIG>
8284 Per-configuration output name for RUNTIME target files.
8285 This is the configuration-specific version of RUNTIME_OUT‐
8287 PUT_NAME.
8288 SKIP_BUILD_RPATH
8291 Should rpaths be used for the build tree.
8292 SKIP_BUILD_RPATH is a boolean specifying whether to skip auto‐
8294 matic generation of an rpath allowing the target to run from the
8295 build tree. This property is initialized by the value of the
8296 variable CMAKE_SKIP_BUILD_RPATH if it is set when a target is
8297 created.
8298 SOURCES
8301 Source names specified for a target.
8302 Read-only list of sources specified for a target. The names
8304 returned are suitable for passing to the set_source_files_prop‐
8305 erties command.
8306 SOVERSION
8309 What version number is this target.
8310 For shared libraries VERSION and SOVERSION can be used to spec‐
8312 ify the build version and API version respectively. When build‐
8313 ing or installing appropriate symlinks are created if the plat‐
8314 form supports symlinks and the linker supports so-names. If only
8315 one of both is specified the missing is assumed to have the same
8316 version number. SOVERSION is ignored if NO_SONAME property is
8317 set. For shared libraries and executables on Windows the VERSION
8318 attribute is parsed to extract a "major.minor" version number.
8319 These numbers are used as the image version of the binary.
8320 STATIC_LIBRARY_FLAGS
8323 Extra flags to use when linking static libraries.
8324 Extra flags to use when linking a static library.
8326 STATIC_LIBRARY_FLAGS_<CONFIG>
8329 Per-configuration flags for creating a static library.
8330 This is the configuration-specific version of
8332 STATIC_LIBRARY_FLAGS.
8333 SUFFIX What comes after the target name.
8336 A target property that can be set to override the suffix (such
8338 as ".so" or ".exe") on the name of a library, module or exe‐
8339 cutable.
8340 TYPE The type of the target.
8343 This read-only property can be used to test the type of the
8345 given target. It will be one of STATIC_LIBRARY, MODULE_LIBRARY,
8346 SHARED_LIBRARY, EXECUTABLE or one of the internal target types.
8347 VERSION
8350 What version number is this target.
8351 For shared libraries VERSION and SOVERSION can be used to spec‐
8353 ify the build version and API version respectively. When build‐
8354 ing or installing appropriate symlinks are created if the plat‐
8355 form supports symlinks and the linker supports so-names. If only
8356 one of both is specified the missing is assumed to have the same
8357 version number. For executables VERSION can be used to specify
8358 the build version. When building or installing appropriate sym‐
8359 links are created if the platform supports symlinks. For shared
8360 libraries and executables on Windows the VERSION attribute is
8361 parsed to extract a "major.minor" version number. These numbers
8362 are used as the image version of the binary.
8363 VISIBILITY_INLINES_HIDDEN
8366 Whether to add a compile flag to hide symbols of inline func‐
8367 tions
8368 The VISIBILITY_INLINES_HIDDEN property determines whether a flag
8370 for hiding symbols for inline functions. the value passed used
8371 in a visibility related compile option, such as -fvisibility=.
8372 This property only has an affect for libraries and executables
8373 with exports. This property is initialized by the value of the
8374 variable CMAKE_VISIBILITY_INLINES_HIDDEN if it is set when a
8375 target is created.
8376 VS_DOTNET_REFERENCES
8379 Visual Studio managed project .NET references
8380 Adds one or more semicolon-delimited .NET references to a gener‐
8382 ated Visual Studio project. For example, "System;System.Win‐
8383 dows.Forms".
8384 VS_DOTNET_TARGET_FRAMEWORK_VERSION
8387 Specify the .NET target framework version.
8388 Used to specify the .NET target framework version for C++/CLI.
8390 For example, "v4.5".
8391 VS_GLOBAL_<variable>
8394 Visual Studio project-specific global variable.
8395 Tell the Visual Studio generator to set the global variable
8397 '<variable>' to a given value in the generated Visual Studio
8398 project. Ignored on other generators. Qt integration works bet‐
8399 ter if VS_GLOBAL_QtVersion is set to the version FindQt4.cmake
8400 found. For example, "4.7.3"
8401 VS_GLOBAL_KEYWORD
8404 Visual Studio project keyword.
8405 Sets the "keyword" attribute for a generated Visual Studio
8407 project. Defaults to "Win32Proj". You may wish to override this
8408 value with "ManagedCProj", for example, in a Visual Studio man‐
8409 aged C++ unit test project.
8410 VS_GLOBAL_PROJECT_TYPES
8413 Visual Studio project type(s).
8414 Can be set to one or more UUIDs recognized by Visual Studio to
8416 indicate the type of project. This value is copied verbatim into
8417 the generated project file. Example for a managed C++ unit test‐
8418 ing project:
8419 {3AC096D0-A1C2-E12C-1390-A8335801FDAB};{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}
8422 UUIDs are semicolon-delimited.
8424 VS_GLOBAL_ROOTNAMESPACE
8427 Visual Studio project root namespace.
8428 Sets the "RootNamespace" attribute for a generated Visual Studio
8430 project. The attribute will be generated only if this is set.
8431 VS_KEYWORD
8434 Visual Studio project keyword.
8435 Can be set to change the visual studio keyword, for example Qt
8437 integration works better if this is set to Qt4VSv1.0.
8438 VS_SCC_AUXPATH
8441 Visual Studio Source Code Control Aux Path.
8442 Can be set to change the visual studio source code control aux‐
8444 path property.
8445 VS_SCC_LOCALPATH
8448 Visual Studio Source Code Control Local Path.
8449 Can be set to change the visual studio source code control local
8451 path property.
8452 VS_SCC_PROJECTNAME
8455 Visual Studio Source Code Control Project.
8456 Can be set to change the visual studio source code control
8458 project name property.
8459 VS_SCC_PROVIDER
8462 Visual Studio Source Code Control Provider.
8463 Can be set to change the visual studio source code control
8465 provider property.
8466 VS_WINRT_EXTENSIONS
8469 Visual Studio project C++/CX language extensions for Windows
8470 Runtime
8471 Can be set to enable C++/CX language extensions.
8473 VS_WINRT_REFERENCES
8476 Visual Studio project Windows Runtime Metadata references
8477 Adds one or more semicolon-delimited WinRT references to a gen‐
8479 erated Visual Studio project. For example, "Windows;Win‐
8480 dows.UI.Core".
8481 WIN32_EXECUTABLE
8484 Build an executable with a WinMain entry point on windows.
8485 When this property is set to true the executable when linked on
8487 Windows will be created with a WinMain() entry point instead of
8488 just main(). This makes it a GUI executable instead of a con‐
8489 sole application. See the CMAKE_MFC_FLAG variable documentation
8490 to configure use of MFC for WinMain executables. This property
8491 is initialized by the value of the variable CMAKE_WIN32_EXE‐
8492 CUTABLE if it is set when a target is created.
8493 XCODE_ATTRIBUTE_<an-attribute>
8496 Set Xcode target attributes directly.
8497 Tell the Xcode generator to set '<an-attribute>' to a given
8499 value in the generated Xcode project. Ignored on other genera‐
8500 tors.
8501
8504 ATTACHED_FILES
8505 Attach a list of files to a dashboard submission.
8506 Set this property to a list of files that will be encoded and
8508 submitted to the dashboard as an addition to the test result.
8509 ATTACHED_FILES_ON_FAIL
8512 Attach a list of files to a dashboard submission if the test
8513 fails.
8514 Same as ATTACHED_FILES, but these files will only be included if
8516 the test does not pass.
8517 COST Set this to a floating point value. Tests in a test set will be
8520 run in descending order of cost.
8521 This property describes the cost of a test. You can explicitly
8523 set this value; tests with higher COST values will run first.
8524 DEPENDS
8527 Specifies that this test should only be run after the specified
8528 list of tests.
8529 Set this to a list of tests that must finish before this test is
8531 run.
8532 ENVIRONMENT
8535 Specify environment variables that should be defined for running
8536 a test.
8537 If set to a list of environment variables and values of the form
8539 MYVAR=value those environment variables will be defined while
8540 running the test. The environment is restored to its previous
8541 state after the test is done.
8542 FAIL_REGULAR_EXPRESSION
8545 If the output matches this regular expression the test will
8546 fail.
8547 If set, if the output matches one of specified regular expres‐
8549 sions, the test will fail.For example: FAIL_REGULAR_EXPRESSION
8550 "[^a-z]Error;ERROR;Failed"
8551 LABELS Specify a list of text labels associated with a test.
8554 The list is reported in dashboard submissions.
8556 MEASUREMENT
8559 Specify a CDASH measurement and value to be reported for a test.
8560 If set to a name then that name will be reported to CDASH as a
8562 named measurement with a value of 1. You may also specify a
8563 value by setting MEASUREMENT to "measurement=value".
8564 PASS_REGULAR_EXPRESSION
8567 The output must match this regular expression for the test to
8568 pass.
8569 If set, the test output will be checked against the specified
8571 regular expressions and at least one of the regular expressions
8572 has to match, otherwise the test will fail.
8573 PROCESSORS
8576 How many process slots this test requires
8577 Denotes the number of processors that this test will require.
8579 This is typically used for MPI tests, and should be used in con‐
8580 junction with the ctest_test PARALLEL_LEVEL option.
8581 REQUIRED_FILES
8584 List of files required to run the test.
8585 If set to a list of files, the test will not be run unless all
8587 of the files exist.
8588 RESOURCE_LOCK
8591 Specify a list of resources that are locked by this test.
8592 If multiple tests specify the same resource lock, they are guar‐
8594 anteed not to run concurrently.
8595 RUN_SERIAL
8598 Do not run this test in parallel with any other test.
8599 Use this option in conjunction with the ctest_test PARAL‐
8601 LEL_LEVEL option to specify that this test should not be run in
8602 parallel with any other tests.
8603 TIMEOUT
8606 How many seconds to allow for this test.
8607 This property if set will limit a test to not take more than the
8609 specified number of seconds to run. If it exceeds that the test
8610 process will be killed and ctest will move to the next test.
8611 This setting takes precedence over CTEST_TESTING_TIMEOUT.
8612 WILL_FAIL
8615 If set to true, this will invert the pass/fail flag of the test.
8616 This property can be used for tests that are expected to fail
8618 and return a non zero return code.
8619 WORKING_DIRECTORY
8622 The directory from which the test executable will be called.
8623 If this is not set it is called from the directory the test exe‐
8625 cutable is located in.
8626
8629 ABSTRACT
8630 Is this source file an abstract class.
8631 A property on a source file that indicates if the source file
8633 represents a class that is abstract. This only makes sense for
8634 languages that have a notion of an abstract class and it is only
8635 used by some tools that wrap classes into other languages.
8636 COMPILE_DEFINITIONS
8639 Preprocessor definitions for compiling a source file.
8640 The COMPILE_DEFINITIONS property may be set to a semicolon-sepa‐
8642 rated list of preprocessor definitions using the syntax VAR or
8643 VAR=value. Function-style definitions are not supported. CMake
8644 will automatically escape the value correctly for the native
8645 build system (note that CMake language syntax may require
8646 escapes to specify some values). This property may be set on a
8647 per-configuration basis using the name COMPILE_DEFINITIONS_<CON‐
8648 FIG> where <CONFIG> is an upper-case name (ex. "COMPILE_DEFINI‐
8649 TIONS_DEBUG").
8650 CMake will automatically drop some definitions that are not sup‐
8653 ported by the native build tool. The VS6 IDE does not support
8654 definition values with spaces (but NMake does). Xcode does not
8655 support per-configuration definitions on source files.
8656 Disclaimer: Most native build tools have poor support for escap‐
8659 ing certain values. CMake has work-arounds for many cases but
8660 some values may just not be possible to pass correctly. If a
8661 value does not seem to be escaped correctly, do not attempt to
8662 work-around the problem by adding escape sequences to the value.
8663 Your work-around may break in a future version of CMake that has
8664 improved escape support. Instead consider defining the macro in
8665 a (configured) header file. Then report the limitation. Known
8666 limitations include:
8667 # - broken almost everywhere
8670 ; - broken in VS IDE 7.0 and Borland Makefiles
8671 , - broken in VS IDE
8672 % - broken in some cases in NMake
8673 & | - broken in some cases on MinGW
8674 ^ < > \" - broken in most Make tools on Windows
8675 CMake does not reject these values outright because they do work
8677 in some cases. Use with caution.
8678 COMPILE_DEFINITIONS_<CONFIG>
8681 Per-configuration preprocessor definitions on a source file.
8682 This is the configuration-specific version of COMPILE_DEFINI‐
8684 TIONS. Note that Xcode does not support per-configuration
8685 source file flags so this property will be ignored by the Xcode
8686 generator.
8687 COMPILE_FLAGS
8690 Additional flags to be added when compiling this source file.
8691 These flags will be added to the list of compile flags when this
8693 source file builds. Use COMPILE_DEFINITIONS to pass additional
8694 preprocessor definitions.
8695 EXTERNAL_OBJECT
8698 If set to true then this is an object file.
8699 If this property is set to true then the source file is really
8701 an object file and should not be compiled. It will still be
8702 linked into the target though.
8703 Fortran_FORMAT
8706 Set to FIXED or FREE to indicate the Fortran source layout.
8707 This property tells CMake whether a given Fortran source file
8709 uses fixed-format or free-format. CMake will pass the corre‐
8710 sponding format flag to the compiler. Consider using the tar‐
8711 get-wide Fortran_FORMAT property if all source files in a target
8712 share the same format.
8713 GENERATED
8716 Is this source file generated as part of the build process.
8717 If a source file is generated by the build process CMake will
8719 handle it differently in terms of dependency checking etc. Oth‐
8720 erwise having a non-existent source file could create problems.
8721 HEADER_FILE_ONLY
8724 Is this source file only a header file.
8725 A property on a source file that indicates if the source file is
8727 a header file with no associated implementation. This is set
8728 automatically based on the file extension and is used by CMake
8729 to determine if certain dependency information should be com‐
8730 puted.
8731 KEEP_EXTENSION
8734 Make the output file have the same extension as the source file.
8735 If this property is set then the file extension of the output
8737 file will be the same as that of the source file. Normally the
8738 output file extension is computed based on the language of the
8739 source file, for example .cxx will go to a .o extension.
8740 LABELS Specify a list of text labels associated with a source file.
8743 This property has meaning only when the source file is listed in
8745 a target whose LABELS property is also set. No other semantics
8746 are currently specified.
8747 LANGUAGE
8750 What programming language is the file.
8751 A property that can be set to indicate what programming language
8753 the source file is. If it is not set the language is determined
8754 based on the file extension. Typical values are CXX C etc. Set‐
8755 ting this property for a file means this file will be compiled.
8756 Do not set this for headers or files that should not be com‐
8757 piled.
8758 LOCATION
8761 The full path to a source file.
8762 A read only property on a SOURCE FILE that contains the full
8764 path to the source file.
8765 MACOSX_PACKAGE_LOCATION
8768 Place a source file inside a Mac OS X bundle, CFBundle, or
8769 framework.
8770 Executable targets with the MACOSX_BUNDLE property set are built
8772 as Mac OS X application bundles on Apple platforms. Shared
8773 library targets with the FRAMEWORK property set are built as Mac
8774 OS X frameworks on Apple platforms. Module library targets with
8775 the BUNDLE property set are built as Mac OS X CFBundle bundles
8776 on Apple platforms. Source files listed in the target with this
8777 property set will be copied to a directory inside the bundle or
8778 framework content folder specified by the property value. For
8779 bundles the content folder is "<name>.app/Contents". For frame‐
8780 works the content folder is "<name>.framework/Versions/<ver‐
8781 sion>". For cfbundles the content folder is "<name>.bundle/Con‐
8782 tents" (unless the extension is changed). See the PUB‐
8783 LIC_HEADER, PRIVATE_HEADER, and RESOURCE target properties for
8784 specifying files meant for Headers, PrivateHeaders, or Resources
8785 directories.
8786 OBJECT_DEPENDS
8789 Additional files on which a compiled object file depends.
8790 Specifies a semicolon-separated list of full-paths to files on
8792 which any object files compiled from this source file depend.
8793 An object file will be recompiled if any of the named files is
8794 newer than it.
8795 This property need not be used to specify the dependency of a
8798 source file on a generated header file that it includes.
8799 Although the property was originally introduced for this pur‐
8800 pose, it is no longer necessary. If the generated header file
8801 is created by a custom command in the same target as the source
8802 file, the automatic dependency scanning process will recognize
8803 the dependency. If the generated header file is created by
8804 another target, an inter-target dependency should be created
8805 with the add_dependencies command (if one does not already exist
8806 due to linking relationships).
8807 OBJECT_OUTPUTS
8810 Additional outputs for a Makefile rule.
8811 Additional outputs created by compilation of this source file.
8813 If any of these outputs is missing the object will be recom‐
8814 piled. This is supported only on Makefile generators and will be
8815 ignored on other generators.
8816 SYMBOLIC
8819 Is this just a name for a rule.
8820 If SYMBOLIC (boolean) is set to true the build system will be
8822 informed that the source file is not actually created on disk
8823 but instead used as a symbolic name for a build rule.
8824 WRAP_EXCLUDE
8827 Exclude this source file from any code wrapping techniques.
8828 Some packages can wrap source files into alternate languages to
8830 provide additional functionality. For example, C++ code can be
8831 wrapped into Java or Python etc using SWIG etc. If WRAP_EXCLUDE
8832 is set to true (1 etc) that indicates that this source file
8833 should not be wrapped.
8834
8837 ADVANCED
8838 True if entry should be hidden by default in GUIs.
8839 This is a boolean value indicating whether the entry is consid‐
8841 ered interesting only for advanced configuration. The
8842 mark_as_advanced() command modifies this property.
8843 HELPSTRING
8846 Help associated with entry in GUIs.
8847 This string summarizes the purpose of an entry to help users set
8849 it through a CMake GUI.
8850 MODIFIED
8853 Internal management property. Do not set or get.
8854 This is an internal cache entry property managed by CMake to
8856 track interactive user modification of entries. Ignore it.
8857 STRINGS
8860 Enumerate possible STRING entry values for GUI selection.
8861 For cache entries with type STRING, this enumerates a set of
8863 values. CMake GUIs may use this to provide a selection widget
8864 instead of a generic string entry field. This is for conve‐
8865 nience only. CMake does not enforce that the value matches one
8866 of those listed.
8867 TYPE Widget type for entry in GUIs.
8870 Cache entry values are always strings, but CMake GUIs present
8872 widgets to help users set values. The GUIs use this property as
8873 a hint to determine the widget type. Valid TYPE values are:
8874 BOOL = Boolean ON/OFF value.
8877 PATH = Path to a directory.
8878 FILEPATH = Path to a file.
8879 STRING = Generic string value.
8880 INTERNAL = Do not present in GUI at all.
8881 STATIC = Value managed by CMake, do not change.
8882 UNINITIALIZED = Type not yet specified.
8883 Generally the TYPE of a cache entry should be set by the command
8885 which creates it (set, option, find_library, etc.).
8886 VALUE Value of a cache entry.
8889 This property maps to the actual value of a cache entry. Set‐
8891 ting this property always sets the value without checking, so
8892 use with care.
8893
8896 CMake Compatibility Listfile Commands - Obsolete commands supported by CMake for compatibility.
8897 This is the documentation for now obsolete listfile commands from pre‐
8900 vious CMake versions, which are still supported for compatibility rea‐
8901 sons. You should instead use the newer, faster and shinier new com‐
8902 mands. ;-)
8903 build_name
8906 Deprecated. Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER}
8907 instead.
8908 build_name(variable)
8910 Sets the specified variable to a string representing the plat‐
8912 form and compiler settings. These values are now available
8913 through the CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
8914 exec_program
8917 Deprecated. Use the execute_process() command instead.
8918 Run an executable program during the processing of the CMake‐
8920 List.txt file.
8921 exec_program(Executable [directory in which to run]
8924 [ARGS <arguments to executable>]
8925 [OUTPUT_VARIABLE <var>]
8926 [RETURN_VALUE <var>])
8927 The executable is run in the optionally specified directory.
8929 The executable can include arguments if it is double quoted, but
8930 it is better to use the optional ARGS argument to specify argu‐
8931 ments to the program. This is because cmake will then be able
8932 to escape spaces in the executable path. An optional argument
8933 OUTPUT_VARIABLE specifies a variable in which to store the out‐
8934 put. To capture the return value of the execution, provide a
8935 RETURN_VALUE. If OUTPUT_VARIABLE is specified, then no output
8936 will go to the stdout/stderr of the console running cmake.
8937 export_library_dependencies
8941 Deprecated. Use INSTALL(EXPORT) or EXPORT command.
8942 This command generates an old-style library dependencies file.
8944 Projects requiring CMake 2.6 or later should not use the com‐
8945 mand. Use instead the install(EXPORT) command to help export
8946 targets from an installation tree and the export() command to
8947 export targets from a build tree.
8948 The old-style library dependencies file does not take into
8951 account per-configuration names of libraries or the LINK_INTER‐
8952 FACE_LIBRARIES target property.
8953 export_library_dependencies(<file> [APPEND])
8956 Create a file named <file> that can be included into a CMake
8958 listfile with the INCLUDE command. The file will contain a num‐
8959 ber of SET commands that will set all the variables needed for
8960 library dependency information. This should be the last command
8961 in the top level CMakeLists.txt file of the project. If the
8962 APPEND option is specified, the SET commands will be appended to
8963 the given file instead of replacing it.
8964 install_files
8967 Deprecated. Use the install(FILES ) command instead.
8968 This command has been superceded by the install command. It is
8970 provided for compatibility with older CMake code. The FILES
8971 form is directly replaced by the FILES form of the install com‐
8972 mand. The regexp form can be expressed more clearly using the
8973 GLOB form of the file command.
8974 install_files(<dir> extension file file ...)
8977 Create rules to install the listed files with the given exten‐
8979 sion into the given directory. Only files existing in the cur‐
8980 rent source tree or its corresponding location in the binary
8981 tree may be listed. If a file specified already has an exten‐
8982 sion, that extension will be removed first. This is useful for
8983 providing lists of source files such as foo.cxx when you want
8984 the corresponding foo.h to be installed. A typical extension is
8985 '.h'.
8986 install_files(<dir> regexp)
8989 Any files in the current source directory that match the regular
8991 expression will be installed.
8992 install_files(<dir> FILES file file ...)
8995 Any files listed after the FILES keyword will be installed
8997 explicitly from the names given. Full paths are allowed in this
8998 form.
8999 The directory <dir> is relative to the installation prefix,
9002 which is stored in the variable CMAKE_INSTALL_PREFIX.
9003 install_programs
9006 Deprecated. Use the install(PROGRAMS ) command instead.
9007 This command has been superceded by the install command. It is
9009 provided for compatibility with older CMake code. The FILES
9010 form is directly replaced by the PROGRAMS form of the INSTALL
9011 command. The regexp form can be expressed more clearly using
9012 the GLOB form of the FILE command.
9013 install_programs(<dir> file1 file2 [file3 ...])
9016 install_programs(<dir> FILES file1 [file2 ...])
9017 Create rules to install the listed programs into the given
9019 directory. Use the FILES argument to guarantee that the file
9020 list version of the command will be used even when there is only
9021 one argument.
9022 install_programs(<dir> regexp)
9025 In the second form any program in the current source directory
9027 that matches the regular expression will be installed.
9028 This command is intended to install programs that are not built
9031 by cmake, such as shell scripts. See the TARGETS form of the
9032 INSTALL command to create installation rules for targets built
9033 by cmake.
9034 The directory <dir> is relative to the installation prefix,
9037 which is stored in the variable CMAKE_INSTALL_PREFIX.
9038 install_targets
9041 Deprecated. Use the install(TARGETS ) command instead.
9042 This command has been superceded by the install command. It is
9044 provided for compatibility with older CMake code.
9045 install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
9048 Create rules to install the listed targets into the given direc‐
9050 tory. The directory <dir> is relative to the installation pre‐
9051 fix, which is stored in the variable CMAKE_INSTALL_PREFIX. If
9052 RUNTIME_DIRECTORY is specified, then on systems with special
9053 runtime files (Windows DLL), the files will be copied to that
9054 directory.
9055 link_libraries
9058 Deprecated. Use the target_link_libraries() command instead.
9059 Link libraries to all targets added later.
9061 link_libraries(library1 <debug | optimized> library2 ...)
9064 Specify a list of libraries to be linked into any following tar‐
9066 gets (typically added with the add_executable or add_library
9067 calls). This command is passed down to all subdirectories. The
9068 debug and optimized strings may be used to indicate that the
9069 next library listed is to be used only for that specific type of
9070 build.
9071 make_directory
9074 Deprecated. Use the file(MAKE_DIRECTORY ) command instead.
9075 make_directory(directory)
9077 Creates the specified directory. Full paths should be given.
9079 Any parent directories that do not exist will also be created.
9080 Use with care.
9081 output_required_files
9084 Deprecated. Approximate C preprocessor dependency scanning.
9085 This command exists only because ancient CMake versions provided
9087 it. CMake handles preprocessor dependency scanning automati‐
9088 cally using a more advanced scanner.
9089 output_required_files(srcfile outputfile)
9092 Outputs a list of all the source files that are required by the
9094 specified srcfile. This list is written into outputfile. This is
9095 similar to writing out the dependencies for srcfile except that
9096 it jumps from .h files into .cxx, .c and .cpp files if possible.
9097 remove Deprecated. Use the list(REMOVE_ITEM ) command instead.
9100 remove(VAR VALUE VALUE ...)
9102 Removes VALUE from the variable VAR. This is typically used to
9104 remove entries from a vector (e.g. semicolon separated list).
9105 VALUE is expanded.
9106 subdir_depends
9109 Deprecated. Does nothing.
9110 subdir_depends(subdir dep1 dep2 ...)
9112 Does not do anything. This command used to help projects order
9114 parallel builds correctly. This functionality is now automatic.
9115 subdirs
9118 Deprecated. Use the add_subdirectory() command instead.
9119 Add a list of subdirectories to the build.
9121 subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
9124 [PREORDER] )
9125 Add a list of subdirectories to the build. The add_subdirectory
9127 command should be used instead of subdirs although subdirs will
9128 still work. This will cause any CMakeLists.txt files in the sub
9129 directories to be processed by CMake. Any directories after the
9130 PREORDER flag are traversed first by makefile builds, the PRE‐
9131 ORDER flag has no effect on IDE projects. Any directories after
9132 the EXCLUDE_FROM_ALL marker will not be included in the top
9133 level makefile or project file. This is useful for having CMake
9134 create makefiles or projects for a set of examples in a project.
9135 You would want CMake to generate makefiles or project files for
9136 all the examples at the same time, but you would not want them
9137 to show up in the top level project or be built each time make
9138 is run from the top.
9139 use_mangled_mesa
9142 Copy mesa headers for use in combination with system GL.
9143 use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
9145 The path to mesa includes, should contain gl_mangle.h. The mesa
9147 headers are copied to the specified output directory. This
9148 allows mangled mesa headers to override other GL headers by
9149 being added to the include directory path earlier.
9150 utility_source
9153 Specify the source tree of a third-party utility.
9154 utility_source(cache_entry executable_name
9156 path_to_source [file1 file2 ...])
9157 When a third-party utility's source is included in the distribu‐
9159 tion, this command specifies its location and name. The cache
9160 entry will not be set unless the path_to_source and all listed
9161 files exist. It is assumed that the source tree of the utility
9162 will have been built before it is needed.
9163 When cross compiling CMake will print a warning if a util‐
9166 ity_source() command is executed, because in many cases it is
9167 used to build an executable which is executed later on. This
9168 doesn't work when cross compiling, since the executable can run
9169 only on their target platform. So in this case the cache entry
9170 has to be adjusted manually so it points to an executable which
9171 is runnable on the build host.
9172 variable_requires
9175 Deprecated. Use the if() command instead.
9176 Assert satisfaction of an option's required variables.
9178 variable_requires(TEST_VARIABLE RESULT_VARIABLE
9181 REQUIRED_VARIABLE1
9182 REQUIRED_VARIABLE2 ...)
9183 The first argument (TEST_VARIABLE) is the name of the variable
9185 to be tested, if that variable is false nothing else is done. If
9186 TEST_VARIABLE is true, then the next argument (RESULT_VARIABLE)
9187 is a variable that is set to true if all the required variables
9188 are set. The rest of the arguments are variables that must be
9189 true or not set to NOTFOUND to avoid an error. If any are not
9190 true, an error is reported.
9191 write_file
9194 Deprecated. Use the file(WRITE ) command instead.
9195 write_file(filename "message to write"... [APPEND])
9197 The first argument is the file name, the rest of the arguments
9199 are messages to write. If the argument APPEND is specified, then
9200 the message will be appended.
9201 NOTE 1: file(WRITE ... and file(APPEND ... do exactly the same
9204 as this one but add some more functionality.
9205 NOTE 2: When using write_file the produced file cannot be used
9208 as an input to CMake (CONFIGURE_FILE, source file ...) because
9209 it will lead to an infinite loop. Use configure_file if you want
9210 to generate input files to CMake.
9211
9214 The following modules are provided with CMake. They can be used with
9215 INCLUDE(ModuleName).
9216 CMake Modules - Modules coming with CMake, the Cross-Platform Makefile Generator.
9219 This is the documentation for the modules and scripts coming with
9222 CMake. Using these modules you can check the computer system for
9223 installed software packages, features of the compiler and the existence
9224 of headers to name just a few.
9225 AddFileDependencies
9228 ADD_FILE_DEPENDENCIES(source_file depend_files...)
9229 Adds the given files as dependencies to source_file
9231 BundleUtilities
9235 Functions to help assemble a standalone bundle application.
9236 A collection of CMake utility functions useful for dealing with
9238 .app bundles on the Mac and bundle-like directories on any OS.
9239 The following functions are provided by this module:
9242 fixup_bundle
9245 copy_and_fixup_bundle
9246 verify_app
9247 get_bundle_main_executable
9248 get_dotapp_dir
9249 get_bundle_and_executable
9250 get_bundle_all_executables
9251 get_item_key
9252 clear_bundle_keys
9253 set_bundle_key_values
9254 get_bundle_keys
9255 copy_resolved_item_into_bundle
9256 copy_resolved_framework_into_bundle
9257 fixup_bundle_item
9258 verify_bundle_prerequisites
9259 verify_bundle_symlinks
9260 Requires CMake 2.6 or greater because it uses function, break
9262 and PARENT_SCOPE. Also depends on GetPrerequisites.cmake.
9263 FIXUP_BUNDLE(<app> <libs> <dirs>)
9266 Fix up a bundle in-place and make it standalone, such that it
9268 can be drag-n-drop copied to another machine and run on that
9269 machine as long as all of the system libraries are compatible.
9270 If you pass plugins to fixup_bundle as the libs parameter, you
9273 should install them or copy them into the bundle before calling
9274 fixup_bundle. The "libs" parameter is a list of libraries that
9275 must be fixed up, but that cannot be determined by otool output
9276 analysis. (i.e., plugins)
9277 Gather all the keys for all the executables and libraries in a
9280 bundle, and then, for each key, copy each prerequisite into the
9281 bundle. Then fix each one up according to its own list of pre‐
9282 requisites.
9283 Then clear all the keys and call verify_app on the final bundle
9286 to ensure that it is truly standalone.
9287 COPY_AND_FIXUP_BUNDLE(<src> <dst> <libs> <dirs>)
9290 Makes a copy of the bundle <src> at location <dst> and then
9292 fixes up the new copied bundle in-place at <dst>...
9293 VERIFY_APP(<app>)
9296 Verifies that an application <app> appears valid based on run‐
9298 ning analysis tools on it. Calls "message(FATAL_ERROR" if the
9299 application is not verified.
9300 GET_BUNDLE_MAIN_EXECUTABLE(<bundle> <result_var>)
9303 The result will be the full path name of the bundle's main exe‐
9305 cutable file or an "error:" prefixed string if it could not be
9306 determined.
9307 GET_DOTAPP_DIR(<exe> <dotapp_dir_var>)
9310 Returns the nearest parent dir whose name ends with ".app" given
9312 the full path to an executable. If there is no such parent dir,
9313 then simply return the dir containing the executable.
9314 The returned directory may or may not exist.
9317 GET_BUNDLE_AND_EXECUTABLE(<app> <bundle_var> <executable_var> <valid_var>)
9320 Takes either a ".app" directory name or the name of an exe‐
9322 cutable nested inside a ".app" directory and returns the path to
9323 the ".app" directory in <bundle_var> and the path to its main
9324 executable in <executable_var>
9325 GET_BUNDLE_ALL_EXECUTABLES(<bundle> <exes_var>)
9328 Scans the given bundle recursively for all executable files and
9330 accumulates them into a variable.
9331 GET_ITEM_KEY(<item> <key_var>)
9334 Given a file (item) name, generate a key that should be unique
9336 considering the set of libraries that need copying or fixing up
9337 to make a bundle standalone. This is essentially the file name
9338 including extension with "." replaced by "_"
9339 This key is used as a prefix for CMake variables so that we can
9342 associate a set of variables with a given item based on its key.
9343 CLEAR_BUNDLE_KEYS(<keys_var>)
9346 Loop over the list of keys, clearing all the variables associ‐
9348 ated with each key. After the loop, clear the list of keys
9349 itself.
9350 Caller of get_bundle_keys should call clear_bundle_keys when
9353 done with list of keys.
9354 SET_BUNDLE_KEY_VALUES(<keys_var> <context> <item> <exepath> <dirs>
9357 <copyflag>)
9358 Add a key to the list (if necessary) for the given item. If
9360 added, also set all the variables associated with that key.
9361 GET_BUNDLE_KEYS(<app> <libs> <dirs> <keys_var>)
9364 Loop over all the executable and library files within the bundle
9366 (and given as extra <libs>) and accumulate a list of keys repre‐
9367 senting them. Set values associated with each key such that we
9368 can loop over all of them and copy prerequisite libs into the
9369 bundle and then do appropriate install_name_tool fixups.
9370 COPY_RESOLVED_ITEM_INTO_BUNDLE(<resolved_item> <resolved_embedded_item>)
9373 Copy a resolved item into the bundle if necessary. Copy is not
9375 necessary if the resolved_item is "the same as" the
9376 resolved_embedded_item.
9377 COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE(<resolved_item> <resolved_embedded_item>)
9380 Copy a resolved framework into the bundle if necessary. Copy is
9382 not necessary if the resolved_item is "the same as" the
9383 resolved_embedded_item.
9384 By default, BU_COPY_FULL_FRAMEWORK_CONTENTS is not set. If you
9387 want full frameworks embedded in your bundles, set
9388 BU_COPY_FULL_FRAMEWORK_CONTENTS to ON before calling fixup_bun‐
9389 dle. By default, COPY_RESOLVED_FRAMEWORK_INTO_BUNDLE copies the
9390 framework dylib itself plus the framework Resources directory.
9391 FIXUP_BUNDLE_ITEM(<resolved_embedded_item> <exepath> <dirs>)
9394 Get the direct/non-system prerequisites of the resolved embedded
9396 item. For each prerequisite, change the way it is referenced to
9397 the value of the _EMBEDDED_ITEM keyed variable for that prereq‐
9398 uisite. (Most likely changing to an "@executable_path" style
9399 reference.)
9400 This function requires that the resolved_embedded_item be
9403 "inside" the bundle already. In other words, if you pass plugins
9404 to fixup_bundle as the libs parameter, you should install them
9405 or copy them into the bundle before calling fixup_bundle. The
9406 "libs" parameter is a list of libraries that must be fixed up,
9407 but that cannot be determined by otool output analysis. (i.e.,
9408 plugins)
9409 Also, change the id of the item being fixed up to its own
9412 _EMBEDDED_ITEM value.
9413 Accumulate changes in a local variable and make *one* call to
9416 install_name_tool at the end of the function with all the
9417 changes at once.
9418 If the BU_CHMOD_BUNDLE_ITEMS variable is set then bundle items
9421 will be marked writable before install_name_tool tries to change
9422 them.
9423 VERIFY_BUNDLE_PREREQUISITES(<bundle> <result_var> <info_var>)
9426 Verifies that the sum of all prerequisites of all files inside
9428 the bundle are contained within the bundle or are "system"
9429 libraries, presumed to exist everywhere.
9430 VERIFY_BUNDLE_SYMLINKS(<bundle> <result_var> <info_var>)
9433 Verifies that any symlinks found in the bundle point to other
9435 files that are already also in the bundle... Anything that
9436 points to an external file causes this function to fail the ver‐
9437 ification.
9438 CMakeAddFortranSubdirectory
9441 Use MinGW gfortran from VS if a fortran compiler is not found.
9442 The 'add_fortran_subdirectory' function adds a subdirectory to a
9444 project that contains a fortran only sub-project. The module
9445 will check the current compiler and see if it can support for‐
9446 tran. If no fortran compiler is found and the compiler is MSVC,
9447 then this module will find the MinGW gfortran. It will then use
9448 an external project to build with the MinGW tools. It will also
9449 create imported targets for the libraries created. This will
9450 only work if the fortran code is built into a dll, so
9451 BUILD_SHARED_LIBS is turned on in the project. In addition the
9452 CMAKE_GNUtoMS option is set to on, so that the MS .lib files are
9453 created. Usage is as follows:
9454 cmake_add_fortran_subdirectory(
9457 <subdir> # name of subdirectory
9458 PROJECT <project_name> # project name in subdir top CMakeLists.txt
9459 ARCHIVE_DIR <dir> # dir where project places .lib files
9460 RUNTIME_DIR <dir> # dir where project places .dll files
9461 LIBRARIES <lib>... # names of library targets to import
9462 LINK_LIBRARIES # link interface libraries for LIBRARIES
9463 [LINK_LIBS <lib> <dep>...]...
9464 CMAKE_COMMAND_LINE ... # extra command line flags to pass to cmake
9465 NO_EXTERNAL_INSTALL # skip installation of external project
9466 )
9467 Relative paths in ARCHIVE_DIR and RUNTIME_DIR are interpreted
9469 with respect to the build directory corresponding to the source
9470 directory in which the function is invoked.
9471 Limitations:
9474 NO_EXTERNAL_INSTALL is required for forward compatibility with a
9477 future version that supports installation of the external
9478 project binaries during "make install".
9479 CMakeBackwardCompatibilityCXX
9482 define a bunch of backwards compatibility variables
9483 CMAKE_ANSI_CXXFLAGS - flag for ansi c++
9485 CMAKE_HAS_ANSI_STRING_STREAM - has <strstream>
9486 include(TestForANSIStreamHeaders)
9487 include(CheckIncludeFileCXX)
9488 include(TestForSTDNamespace)
9489 include(TestForANSIForScope)
9490 CMakeDependentOption
9493 Macro to provide an option dependent on other options.
9494 This macro presents an option to the user only if a set of other
9496 conditions are true. When the option is not presented a default
9497 value is used, but any value set by the user is preserved for
9498 when the option is presented again. Example invocation:
9499 CMAKE_DEPENDENT_OPTION(USE_FOO "Use Foo" ON
9502 "USE_BAR;NOT USE_ZOT" OFF)
9503 If USE_BAR is true and USE_ZOT is false, this provides an option
9505 called USE_FOO that defaults to ON. Otherwise, it sets USE_FOO
9506 to OFF. If the status of USE_BAR or USE_ZOT ever changes, any
9507 value for the USE_FOO option is saved so that when the option is
9508 re-enabled it retains its old value.
9509 CMakeDetermineVSServicePack
9512 Determine the Visual Studio service pack of the 'cl' in use.
9513 The functionality of this module has been superseded by the
9515 platform variable CMAKE_<LANG>_COMPILER_VERSION that contains
9516 the compiler version number.
9517 Usage:
9520 if(MSVC)
9523 include(CMakeDetermineVSServicePack)
9524 DetermineVSServicePack( my_service_pack )
9525 if( my_service_pack )
9526 message(STATUS "Detected: ${my_service_pack}")
9527 endif()
9528 endif()
9529 Function DetermineVSServicePack sets the given variable to one
9531 of the following values or an empty string if unknown:
9532 vc80, vc80sp1
9535 vc90, vc90sp1
9536 vc100, vc100sp1
9537 vc110, vc110sp1, vc110sp2
9538 CMakeExpandImportedTargets
9541 CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
9544 [CONFIGURATION <config>] )
9547 CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and
9552 replaces all imported targets contained in this list with their
9553 actual file paths of the referenced libraries on disk, including
9554 the libraries from their link interfaces. If a CONFIGURATION is
9555 given, it uses the respective configuration of the imported tar‐
9556 gets if it exists. If no CONFIGURATION is given, it uses the
9557 first configuration from ${CMAKE_CONFIGURATION_TYPES} if set,
9558 otherwise ${CMAKE_BUILD_TYPE}. This macro is used by all
9559 Check*.cmake files which use try_compile() or try_run() and sup‐
9560 port CMAKE_REQUIRED_LIBRARIES , so that these checks support
9561 imported targets in CMAKE_REQUIRED_LIBRARIES:
9562 cmake_expand_imported_targets(expandedLibs LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
9565 CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
9566 CMakeFindFrameworks
9569 helper module to find OSX frameworks
9570 CMakeFindPackageMode
9573 This file is executed by cmake when invoked with --find-package.
9576 It expects that the following variables are set using -D:
9577 NAME = name of the package
9580 COMPILER_ID = the CMake compiler ID for which the result is, i.e. GNU/Intel/Clang/MSVC, etc.
9581 LANGUAGE = language for which the result will be used, i.e. C/CXX/Fortan/ASM
9582 MODE = EXIST : only check for existence of the given package
9583 COMPILE : print the flags needed for compiling an object file which uses the given package
9584 LINK : print the flags needed for linking when using the given package
9585 QUIET = if TRUE, don't print anything
9586 CMakeForceCompiler
9589 This module defines macros intended for use by cross-compiling
9592 toolchain files when CMake is not able to automatically detect
9593 the compiler identification.
9594 Macro CMAKE_FORCE_C_COMPILER has the following signature:
9597 CMAKE_FORCE_C_COMPILER(<compiler> <compiler-id>)
9600 It sets CMAKE_C_COMPILER to the given compiler and the cmake
9602 internal variable CMAKE_C_COMPILER_ID to the given compiler-id.
9603 It also bypasses the check for working compiler and basic com‐
9604 piler information tests.
9605 Macro CMAKE_FORCE_CXX_COMPILER has the following signature:
9608 CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler-id>)
9611 It sets CMAKE_CXX_COMPILER to the given compiler and the cmake
9613 internal variable CMAKE_CXX_COMPILER_ID to the given com‐
9614 piler-id. It also bypasses the check for working compiler and
9615 basic compiler information tests.
9616 Macro CMAKE_FORCE_Fortran_COMPILER has the following signature:
9619 CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler-id>)
9622 It sets CMAKE_Fortran_COMPILER to the given compiler and the
9624 cmake internal variable CMAKE_Fortran_COMPILER_ID to the given
9625 compiler-id. It also bypasses the check for working compiler and
9626 basic compiler information tests.
9627 So a simple toolchain file could look like this:
9630 include (CMakeForceCompiler)
9633 set(CMAKE_SYSTEM_NAME Generic)
9634 CMAKE_FORCE_C_COMPILER (chc12 MetrowerksHicross)
9635 CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross)
9636 CMakeGraphVizOptions
9639 The builtin graphviz support of CMake.
9640 CMake can generate graphviz files, showing the dependencies
9642 between the targets in a project and also external libraries
9643 which are linked against. When CMake is run with the --gra‐
9644 phiz=foo option, it will produce
9645 * a foo.dot file showing all dependencies in the project
9648 * a foo.dot.<target> file for each target, file showing on which other targets the respective target depends
9649 * a foo.dot.<target>.dependers file, showing which other targets depend on the respective target
9650 This can result in huge graphs. Using the file CMakeGraphVizOp‐
9655 tions.cmake the look and content of the generated graphs can be
9656 influenced. This file is searched first in ${CMAKE_BINARY_DIR}
9657 and then in ${CMAKE_SOURCE_DIR}. If found, it is read and the
9658 variables set in it are used to adjust options for the generated
9659 graphviz files.
9660 GRAPHVIZ_GRAPH_TYPE - The graph type
9663 Mandatory : NO
9664 Default : "digraph"
9665 GRAPHVIZ_GRAPH_NAME - The graph name.
9666 Mandatory : NO
9667 Default : "GG"
9668 GRAPHVIZ_GRAPH_HEADER - The header written at the top of the graphviz file.
9669 Mandatory : NO
9670 Default : "node [n fontsize = "12"];"
9671 GRAPHVIZ_NODE_PREFIX - The prefix for each node in the graphviz file.
9672 Mandatory : NO
9673 Default : "node"
9674 GRAPHVIZ_EXECUTABLES - Set this to FALSE to exclude executables from the generated graphs.
9675 Mandatory : NO
9676 Default : TRUE
9677 GRAPHVIZ_STATIC_LIBS - Set this to FALSE to exclude static libraries from the generated graphs.
9678 Mandatory : NO
9679 Default : TRUE
9680 GRAPHVIZ_SHARED_LIBS - Set this to FALSE to exclude shared libraries from the generated graphs.
9681 Mandatory : NO
9682 Default : TRUE
9683 GRAPHVIZ_MODULE_LIBS - Set this to FALSE to exclude static libraries from the generated graphs.
9684 Mandatory : NO
9685 Default : TRUE
9686 GRAPHVIZ_EXTERNAL_LIBS - Set this to FALSE to exclude external libraries from the generated graphs.
9687 Mandatory : NO
9688 Default : TRUE
9689 GRAPHVIZ_IGNORE_TARGETS - A list of regular expressions for ignoring targets.
9690 Mandatory : NO
9691 Default : empty
9692 CMakePackageConfigHelpers
9695 CONFIGURE_PACKAGE_CONFIG_FILE(), WRITE_BASIC_PACKAGE_VER‐
9696 SION_FILE()
9697 CONFIGURE_PACKAGE_CONFIG_FILE(<input> <output> INSTALL_DESTINATION <path>
9702 [PATH_VARS <var1> <var2> ... <varN>]
9703 [NO_SET_AND_CHECK_MACRO]
9704 [NO_CHECK_REQUIRED_COMPONENTS_MACRO])
9705 CONFIGURE_PACKAGE_CONFIG_FILE() should be used instead of the
9710 plain configure_file() command when creating the <Name>Con‐
9711 fig.cmake or <Name>-config.cmake file for installing a project
9712 or library. It helps making the resulting package relocatable by
9713 avoiding hardcoded paths in the installed Config.cmake file.
9714 In a FooConfig.cmake file there may be code like this to make
9717 the install destinations know to the using project:
9718 set(FOO_INCLUDE_DIR "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
9721 set(FOO_DATA_DIR "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
9722 set(FOO_ICONS_DIR "@CMAKE_INSTALL_PREFIX@/share/icons" )
9723 ...logic to determine installedPrefix from the own location...
9724 set(FOO_CONFIG_DIR "${installedPrefix}/@CONFIG_INSTALL_DIR@" )
9725 All 4 options shown above are not sufficient, since the first 3
9727 hardcode the absolute directory locations, and the 4th case
9728 works only if the logic to determine the installedPrefix is cor‐
9729 rect, and if CONFIG_INSTALL_DIR contains a relative path, which
9730 in general cannot be guaranteed. This has the effect that the
9731 resulting FooConfig.cmake file would work poorly under Windows
9732 and OSX, where users are used to choose the install location of
9733 a binary package at install time, independent from how
9734 CMAKE_INSTALL_PREFIX was set at build/cmake time.
9735 Using CONFIGURE_PACKAGE_CONFIG_FILE() helps. If used correctly,
9738 it makes the resulting FooConfig.cmake file relocatable. Usage:
9739 1. write a FooConfig.cmake.in file as you are used to
9742 2. insert a line containing only the string "@PACKAGE_INIT@"
9743 3. instead of set(FOO_DIR "@SOME_INSTALL_DIR@"), use set(FOO_DIR "@PACKAGE_SOME_INSTALL_DIR@")
9744 (this must be after the @PACKAGE_INIT@ line)
9745 4. instead of using the normal configure_file(), use CONFIGURE_PACKAGE_CONFIG_FILE()
9746 The <input> and <output> arguments are the input and output
9751 file, the same way as in configure_file().
9752 The <path> given to INSTALL_DESTINATION must be the destination
9755 where the FooConfig.cmake file will be installed to. This can
9756 either be a relative or absolute path, both work.
9757 The variables <var1> to <varN> given as PATH_VARS are the vari‐
9760 ables which contain install destinations. For each of them the
9761 macro will create a helper variable PACKAGE_<var...>. These
9762 helper variables must be used in the FooConfig.cmake.in file for
9763 setting the installed location. They are calculated by CONFIG‐
9764 URE_PACKAGE_CONFIG_FILE() so that they are always relative to
9765 the installed location of the package. This works both for rela‐
9766 tive and also for absolute locations. For absolute locations it
9767 works only if the absolute location is a subdirectory of
9768 CMAKE_INSTALL_PREFIX.
9769 By default configure_package_config_file() also generates two
9772 helper macros, set_and_check() and check_required_components()
9773 into the FooConfig.cmake file.
9774 set_and_check() should be used instead of the normal set() com‐
9777 mand for setting directories and file locations. Additionally to
9778 setting the variable it also checks that the referenced file or
9779 directory actually exists and fails with a FATAL_ERROR other‐
9780 wise. This makes sure that the created FooConfig.cmake file does
9781 not contain wrong references. When using the
9782 NO_SET_AND_CHECK_MACRO, this macro is not generated into the
9783 FooConfig.cmake file.
9784 check_required_components(<package_name>) should be called at
9787 the end of the FooConfig.cmake file if the package supports com‐
9788 ponents. This macro checks whether all requested, non-optional
9789 components have been found, and if this is not the case, sets
9790 the Foo_FOUND variable to FALSE, so that the package is consid‐
9791 ered to be not found. It does that by testing the Foo_<Compo‐
9792 nent>_FOUND variables for all requested required components.
9793 When using the NO_CHECK_REQUIRED_COMPONENTS option, this macro
9794 is not generated into the FooConfig.cmake file.
9795 For an example see below the documentation for WRITE_BASIC_PACK‐
9798 AGE_VERSION_FILE().
9799 WRITE_BASIC_PACKAGE_VERSION_FILE( filename VERSION major.minor.patch COMPATIBILITY (AnyNewerVersion|SameMajorVersion|ExactVersion) )
9805 Writes a file for use as <package>ConfigVersion.cmake file to
9810 <filename>. See the documentation of find_package() for details
9811 on this.
9812 filename is the output filename, it should be in the build tree.
9815 major.minor.patch is the version number of the project to be installed
9816 The COMPATIBILITY mode AnyNewerVersion means that the installed
9818 package version will be considered compatible if it is newer or
9819 exactly the same as the requested version. This mode should be
9820 used for packages which are fully backward compatible, also
9821 across major versions. If SameMajorVersion is used instead, then
9822 the behaviour differs from AnyNewerVersion in that the major
9823 version number must be the same as requested, e.g. version 2.0
9824 will not be considered compatible if 1.0 is requested. This mode
9825 should be used for packages which guarantee backward compatibil‐
9826 ity within the same major version. If ExactVersion is used, then
9827 the package is only considered compatible if the requested ver‐
9828 sion matches exactly its own version number (not considering the
9829 tweak version). For example, version 1.2.3 of a package is only
9830 considered compatible to requested version 1.2.3. This mode is
9831 for packages without compatibility guarantees. If your project
9832 has more elaborated version matching rules, you will need to
9833 write your own custom ConfigVersion.cmake file instead of using
9834 this macro.
9835 Internally, this macro executes configure_file() to create the
9838 resulting version file. Depending on the COMPATIBLITY, either
9839 the file BasicConfigVersion-SameMajorVersion.cmake.in or Basic‐
9840 ConfigVersion-AnyNewerVersion.cmake.in is used. Please note that
9841 these two files are internal to CMake and you should not call
9842 configure_file() on them yourself, but they can be used as
9843 starting point to create more sophisticted custom ConfigVer‐
9844 sion.cmake files.
9845 Example using both configure_package_config_file() and
9851 write_basic_package_version_file(): CMakeLists.txt:
9852 set(INCLUDE_INSTALL_DIR include/ ... CACHE )
9855 set(LIB_INSTALL_DIR lib/ ... CACHE )
9856 set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
9857 ...
9858 include(CMakePackageConfigHelpers)
9859 configure_package_config_file(FooConfig.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
9860 INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
9861 PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
9862 write_basic_package_version_file(${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
9863 VERSION 1.2.3
9864 COMPATIBILITY SameMajorVersion )
9865 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
9866 DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )
9867 With a FooConfig.cmake.in:
9872 set(FOO_VERSION x.y.z)
9875 ...
9876 @PACKAGE_INIT@
9877 ...
9878 set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
9879 set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")
9880 check_required_components(Foo)
9885 CMakeParseArguments
9888 CMAKE_PARSE_ARGUMENTS(<prefix> <options> <one_value_keywords>
9891 <multi_value_keywords> args...)
9892 CMAKE_PARSE_ARGUMENTS() is intended to be used in macros or
9895 functions for parsing the arguments given to that macro or func‐
9896 tion. It processes the arguments and defines a set of variables
9897 which hold the values of the respective options.
9898 The <options> argument contains all options for the respective
9901 macro, i.e. keywords which can be used when calling the macro
9902 without any value following, like e.g. the OPTIONAL keyword of
9903 the install() command.
9904 The <one_value_keywords> argument contains all keywords for this
9907 macro which are followed by one value, like e.g. DESTINATION
9908 keyword of the install() command.
9909 The <multi_value_keywords> argument contains all keywords for
9912 this macro which can be followed by more than one value, like
9913 e.g. the TARGETS or FILES keywords of the install() command.
9914 When done, CMAKE_PARSE_ARGUMENTS() will have defined for each of
9917 the keywords listed in <options>, <one_value_keywords> and
9918 <multi_value_keywords> a variable composed of the given <prefix>
9919 followed by "_" and the name of the respective keyword. These
9920 variables will then hold the respective value from the argument
9921 list. For the <options> keywords this will be TRUE or FALSE.
9922 All remaining arguments are collected in a variable <pre‐
9925 fix>_UNPARSED_ARGUMENTS, this can be checked afterwards to see
9926 whether your macro was called with unrecognized parameters.
9927 As an example here a my_install() macro, which takes similar
9930 arguments as the real install() command:
9931 function(MY_INSTALL)
9934 set(options OPTIONAL FAST)
9935 set(oneValueArgs DESTINATION RENAME)
9936 set(multiValueArgs TARGETS CONFIGURATIONS)
9937 cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN} )
9938 ...
9939 Assume my_install() has been called like this:
9944 my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub)
9947 After the cmake_parse_arguments() call the macro will have set
9952 the following variables:
9953 MY_INSTALL_OPTIONAL = TRUE
9956 MY_INSTALL_FAST = FALSE (this option was not used when calling my_install()
9957 MY_INSTALL_DESTINATION = "bin"
9958 MY_INSTALL_RENAME = "" (was not used)
9959 MY_INSTALL_TARGETS = "foo;bar"
9960 MY_INSTALL_CONFIGURATIONS = "" (was not used)
9961 MY_INSTALL_UNPARSED_ARGUMENTS = "blub" (no value expected after "OPTIONAL"
9962 You can then continue and process these variables.
9967 Keywords terminate lists of values, e.g. if directly after a
9970 one_value_keyword another recognized keyword follows, this is
9971 interpreted as the beginning of the new option. E.g.
9972 my_install(TARGETS foo DESTINATION OPTIONAL) would result in
9973 MY_INSTALL_DESTINATION set to "OPTIONAL", but MY_INSTALL_DESTI‐
9974 NATION would be empty and MY_INSTALL_OPTIONAL would be set to
9975 TRUE therefor.
9976 CMakePrintHelpers
9979 Convenience macros for printing properties and variables, useful
9980 e.g. for debugging.
9981 CMAKE_PRINT_PROPERTIES([TARGETS target1 .. targetN]
9989 [SOURCES source1 .. sourceN]
9992 [DIRECTORIES dir1 .. dirN]
9993 [TESTS test1 .. testN]
9994 [CACHE_ENTRIES entry1 .. entryN]
9995 PROPERTIES prop1 .. propN )
9996 This macro prints the values of the properties of the given tar‐
10001 gets, source files, directories, tests or cache entries. Exactly
10002 one of the scope keywords must be used. Example:
10003 cmake_print_properties(TARGETS foo bar PROPERTIES LOCATION INTERFACE_INCLUDE_DIRS)
10006 This will print the LOCATION and INTERFACE_INCLUDE_DIRS proper‐
10008 ties for both targets foo and bar.
10009 CMAKE_PRINT_VARIABLES(var1 var2 .. varN)
10015 This macro will print the name of each variable followed by its
10018 value. Example:
10019 cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION THIS_ONE_DOES_NOT_EXIST)
10022 Gives:
10024 -- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; THIS_ONE_DOES_NOT_EXIST=""
10027 CMakePrintSystemInformation
10030 print system information
10031 This file can be used for diagnostic purposes just include it in
10033 a project to see various internal CMake variables.
10034 CMakePushCheckState
10037 This module defines three macros: CMAKE_PUSH_CHECK_STATE()
10040 CMAKE_POP_CHECK_STATE() and CMAKE_RESET_CHECK_STATE() These
10041 macros can be used to save, restore and reset (i.e., clear con‐
10042 tents) the state of the variables CMAKE_REQUIRED_FLAGS,
10043 CMAKE_REQUIRED_DEFINITIONS, CMAKE_REQUIRED_LIBRARIES and
10044 CMAKE_REQUIRED_INCLUDES used by the various Check-files coming
10045 with CMake, like e.g. check_function_exists() etc. The variable
10046 contents are pushed on a stack, pushing multiple times is sup‐
10047 ported. This is useful e.g. when executing such tests in a
10048 Find-module, where they have to be set, but after the Find-mod‐
10049 ule has been executed they should have the same value as they
10050 had before.
10051 CMAKE_PUSH_CHECK_STATE() macro receives optional argument RESET.
10054 Whether it's specified, CMAKE_PUSH_CHECK_STATE() will set all
10055 CMAKE_REQUIRED_* variables to empty values, same as
10056 CMAKE_RESET_CHECK_STATE() call will do.
10057 Usage:
10060 cmake_push_check_state(RESET)
10063 set(CMAKE_REQUIRED_DEFINITIONS -DSOME_MORE_DEF)
10064 check_function_exists(...)
10065 cmake_reset_check_state()
10066 set(CMAKE_REQUIRED_DEFINITIONS -DANOTHER_DEF)
10067 check_function_exists(...)
10068 cmake_pop_check_state()
10069 CMakeVerifyManifest
10072 CMakeVerifyManifest.cmake
10075 This script is used to verify that embeded manifests and side by
10078 side manifests for a project match. To run this script, cd to a
10079 directory and run the script with cmake -P. On the command line
10080 you can pass in versions that are OK even if not found in the
10081 .manifest files. For example, cmake -Dallow_versions=8.0.50608.0
10082 -PCmakeVerifyManifest.cmake could be used to allow an embeded
10083 manifest of 8.0.50608.0 to be used in a project even if that
10084 version was not found in the .manifest file.
10085 CPack Build binary and source package installers.
10088 The CPack module generates binary and source installers in a
10090 variety of formats using the cpack program. Inclusion of the
10091 CPack module adds two new targets to the resulting makefiles,
10092 package and package_source, which build the binary and source
10093 installers, respectively. The generated binary installers con‐
10094 tain everything installed via CMake's INSTALL command (and the
10095 deprecated INSTALL_FILES, INSTALL_PROGRAMS, and INSTALL_TARGETS
10096 commands).
10097 For certain kinds of binary installers (including the graphical
10100 installers on Mac OS X and Windows), CPack generates installers
10101 that allow users to select individual application components to
10102 install. See CPackComponent module for that.
10103 The CPACK_GENERATOR variable has different meanings in different
10106 contexts. In your CMakeLists.txt file, CPACK_GENERATOR is a
10107 *list of generators*: when run with no other arguments, CPack
10108 will iterate over that list and produce one package for each
10109 generator. In a CPACK_PROJECT_CONFIG_FILE, though, CPACK_GENERA‐
10110 TOR is a *string naming a single generator*. If you need
10111 per-cpack- generator logic to control *other* cpack settings,
10112 then you need a CPACK_PROJECT_CONFIG_FILE.
10113 The CMake source tree itself contains a CPACK_PROJECT_CON‐
10116 FIG_FILE. See the top level file CMakeCPackOptions.cmake.in for
10117 an example.
10118 If set, the CPACK_PROJECT_CONFIG_FILE is included automatically
10121 on a per-generator basis. It only need contain overrides.
10122 Here's how it works:
10125 - cpack runs
10128 - it includes CPackConfig.cmake
10129 - it iterates over the generators listed in that file's
10130 CPACK_GENERATOR list variable (unless told to use just a
10131 specific one via -G on the command line...)
10132 - foreach generator, it then
10137 - sets CPACK_GENERATOR to the one currently being iterated
10138 - includes the CPACK_PROJECT_CONFIG_FILE
10139 - produces the package for that generator
10140 This is the key: For each generator listed in CPACK_GENERATOR in
10145 CPackConfig.cmake, cpack will *reset* CPACK_GENERATOR internally
10146 to *the one currently being used* and then include the
10147 CPACK_PROJECT_CONFIG_FILE.
10148 Before including this CPack module in your CMakeLists.txt file,
10151 there are a variety of variables that can be set to customize
10152 the resulting installers. The most commonly-used variables are:
10153 CPACK_PACKAGE_NAME - The name of the package (or application). If
10156 not specified, defaults to the project name.
10157 CPACK_PACKAGE_VENDOR - The name of the package vendor. (e.g.,
10162 "Kitware").
10163 CPACK_PACKAGE_DIRECTORY - The directory in which CPack is doing its
10168 packaging. If it is not set then this will default (internally) to the
10169 build dir. This variable may be defined in CPack config file or from
10170 the cpack command line option "-B". If set the command line option
10171 override the value found in the config file.
10172 CPACK_PACKAGE_VERSION_MAJOR - Package major Version
10177 CPACK_PACKAGE_VERSION_MINOR - Package minor Version
10182 CPACK_PACKAGE_VERSION_PATCH - Package patch Version
10187 CPACK_PACKAGE_DESCRIPTION_FILE - A text file used to describe the
10192 project. Used, for example, the introduction screen of a
10193 CPack-generated Windows installer to describe the project.
10194 CPACK_PACKAGE_DESCRIPTION_SUMMARY - Short description of the
10199 project (only a few words).
10200 CPACK_PACKAGE_FILE_NAME - The name of the package file to generate,
10205 not including the extension. For example, cmake-2.6.1-Linux-i686.
10206 The default value is
10207 ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}.
10212 CPACK_PACKAGE_INSTALL_DIRECTORY - Installation directory on the
10217 target system. This may be used by some CPack generators
10218 like NSIS to create an installation directory e.g., "CMake 2.5"
10219 below the installation prefix. All installed element will be
10220 put inside this directory.
10221 CPACK_PACKAGE_ICON - A branding image that will be displayed inside
10226 the installer (used by GUI installers).
10227 CPACK_PROJECT_CONFIG_FILE - CPack-time project CPack configuration
10232 file. This file included at cpack time, once per
10233 generator after CPack has set CPACK_GENERATOR to the actual generator
10234 being used. It allows per-generator setting of CPACK_* variables at
10235 cpack time.
10236 CPACK_RESOURCE_FILE_LICENSE - License to be embedded in the installer. It
10241 will typically be displayed to the user by the produced installer
10242 (often with an explicit "Accept" button, for graphical installers)
10243 prior to installation. This license file is NOT added to installed
10244 file but is used by some CPack generators like NSIS. If you want
10245 to install a license file (may be the same as this one)
10246 along with your project you must add an appropriate CMake INSTALL
10247 command in your CMakeLists.txt.
10248 CPACK_RESOURCE_FILE_README - ReadMe file to be embedded in the installer. It
10253 typically describes in some detail the purpose of the project
10254 during the installation. Not all CPack generators uses
10255 this file.
10256 CPACK_RESOURCE_FILE_WELCOME - Welcome file to be embedded in the
10261 installer. It welcomes users to this installer.
10262 Typically used in the graphical installers on Windows and Mac OS X.
10263 CPACK_MONOLITHIC_INSTALL - Disables the component-based
10268 installation mechanism. When set the component specification is ignored
10269 and all installed items are put in a single "MONOLITHIC" package.
10270 Some CPack generators do monolithic packaging by default and
10271 may be asked to do component packaging by setting
10272 CPACK_<GENNAME>_COMPONENT_INSTALL to 1/TRUE.
10273 CPACK_GENERATOR - List of CPack generators to use. If not
10278 specified, CPack will create a set of options CPACK_BINARY_<GENNAME> (e.g.,
10279 CPACK_BINARY_NSIS) allowing the user to enable/disable individual
10280 generators. This variable may be used on the command line
10281 as well as in:
10282 cpack -D CPACK_GENERATOR="ZIP;TGZ" /path/to/build/tree
10287 CPACK_OUTPUT_CONFIG_FILE - The name of the CPack binary configuration
10292 file. This file is the CPack configuration generated by the CPack module
10293 for binary installers. Defaults to CPackConfig.cmake.
10294 CPACK_PACKAGE_EXECUTABLES - Lists each of the executables and associated
10299 text label to be used to create Start Menu shortcuts. For example,
10300 setting this to the list ccmake;CMake will
10301 create a shortcut named "CMake" that will execute the installed
10302 executable ccmake. Not all CPack generators use it (at least NSIS and
10303 OSXX11 do).
10304 CPACK_STRIP_FILES - List of files to be stripped. Starting with
10309 CMake 2.6.0 CPACK_STRIP_FILES will be a boolean variable which
10310 enables stripping of all files (a list of files evaluates to TRUE
10311 in CMake, so this change is compatible).
10312 The following CPack variables are specific to source packages,
10317 and will not affect binary packages:
10318 CPACK_SOURCE_PACKAGE_FILE_NAME - The name of the source package. For
10321 example cmake-2.6.1.
10322 CPACK_SOURCE_STRIP_FILES - List of files in the source tree that
10327 will be stripped. Starting with CMake 2.6.0
10328 CPACK_SOURCE_STRIP_FILES will be a boolean variable which enables
10329 stripping of all files (a list of files evaluates to TRUE in CMake,
10330 so this change is compatible).
10331 CPACK_SOURCE_GENERATOR - List of generators used for the source
10336 packages. As with CPACK_GENERATOR, if this is not specified then
10337 CPack will create a set of options (e.g., CPACK_SOURCE_ZIP)
10338 allowing users to select which packages will be generated.
10339 CPACK_SOURCE_OUTPUT_CONFIG_FILE - The name of the CPack source
10344 configuration file. This file is the CPack configuration generated by the
10345 CPack module for source installers. Defaults to CPackSourceConfig.cmake.
10346 CPACK_SOURCE_IGNORE_FILES - Pattern of files in the source tree
10351 that won't be packaged when building a source package. This is a
10352 list of regular expression patterns (that must be properly escaped),
10353 e.g., /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
10354 The following variables are for advanced uses of CPack:
10359 CPACK_CMAKE_GENERATOR - What CMake generator should be used if the
10362 project is CMake project. Defaults to the value of CMAKE_GENERATOR
10363 few users will want to change this setting.
10364 CPACK_INSTALL_CMAKE_PROJECTS - List of four values that specify
10369 what project to install. The four values are: Build directory,
10370 Project Name, Project Component, Directory. If omitted, CPack will
10371 build an installer that installers everything.
10372 CPACK_SYSTEM_NAME - System name, defaults to the value of
10377 ${CMAKE_SYSTEM_NAME}.
10378 CPACK_PACKAGE_VERSION - Package full version, used internally. By
10383 default, this is built from CPACK_PACKAGE_VERSION_MAJOR,
10384 CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH.
10385 CPACK_TOPLEVEL_TAG - Directory for the installed files.
10390 CPACK_INSTALL_COMMANDS - Extra commands to install components.
10395 CPACK_INSTALLED_DIRECTORIES - Extra directories to install.
10400 CPACK_PACKAGE_INSTALL_REGISTRY_KEY - Registry key used when
10405 installing this project. This is only used by installer for Windows.
10406 The default value is based on the installation directory.
10407 CPACK_CREATE_DESKTOP_LINKS - List of desktop links to create.
10408 CPackBundle
10414 CPack Bundle generator (Mac OS X) specific options
10415 Installers built on Mac OS X using the Bundle generator use the
10420 aforementioned DragNDrop (CPACK_DMG_xxx) variables, plus the
10421 following Bundle-specific parameters (CPACK_BUNDLE_xxx).
10422 CPACK_BUNDLE_NAME - The name of the generated bundle. This
10425 appears in the OSX finder as the bundle name. Required.
10426 CPACK_BUNDLE_PLIST - Path to an OSX plist file that will be used
10431 for the generated bundle. This assumes that the caller has generated
10432 or specified their own Info.plist file. Required.
10433 CPACK_BUNDLE_ICON - Path to an OSX icon file that will be used as
10438 the icon for the generated bundle. This is the icon that appears in the
10439 OSX finder for the bundle, and in the OSX dock when the bundle is opened.
10440 Required.
10441 CPACK_BUNDLE_STARTUP_COMMAND - Path to a startup script. This is a path to
10446 an executable or script that will be run whenever an end-user double-clicks
10447 the generated bundle in the OSX Finder. Optional.
10448 CPackComponent
10451 Build binary and source package installers
10452 The CPackComponent module is the module which handles the compo‐
10457 nent part of CPack. See CPack module for general information
10458 about CPack.
10459 For certain kinds of binary installers (including the graphical
10462 installers on Mac OS X and Windows), CPack generates installers
10463 that allow users to select individual application components to
10464 install. The contents of each of the components are identified
10465 by the COMPONENT argument of CMake's INSTALL command. These com‐
10466 ponents can be annotated with user-friendly names and descrip‐
10467 tions, inter-component dependencies, etc., and grouped in vari‐
10468 ous ways to customize the resulting installer. See the
10469 cpack_add_* commands, described below, for more information
10470 about component-specific installations.
10471 Component-specific installation allows users to select specific
10474 sets of components to install during the install process.
10475 Installation components are identified by the COMPONENT argument
10476 of CMake's INSTALL commands, and should be further described by
10477 the following CPack commands:
10478 CPACK_COMPONENTS_ALL - The list of component to install.
10481 The default value of this variable is computed by CPack and con‐
10486 tains all components defined by the project. The user may set it
10487 to only include the specified components.
10488 CPACK_<GENNAME>_COMPONENT_INSTALL - Enable/Disable component install for
10491 CPack generator <GENNAME>.
10492 Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc...) has
10497 a legacy default behavior. e.g. RPM builds monolithic whereas
10498 NSIS builds component. One can change the default behavior by
10499 setting this variable to 0/1 or OFF/ON.
10500 CPACK_COMPONENTS_GROUPING - Specify how components are grouped for multi-package
10503 component-aware CPack generators.
10504 Some generators like RPM or ARCHIVE family (TGZ, ZIP, ...) gen‐
10509 erates several packages files when asked for component packag‐
10510 ing. They group the component differently depending on the value
10511 of this variable:
10512 - ONE_PER_GROUP (default): creates one package file per component group
10515 - ALL_COMPONENTS_IN_ONE : creates a single package with all (requested) component
10516 - IGNORE : creates one package per component, i.e. IGNORE component group
10517 One can specify different grouping for different CPack generator
10519 by using a CPACK_PROJECT_CONFIG_FILE.
10520 CPACK_COMPONENT_<compName>_DISPLAY_NAME - The name to be displayed for a component.
10523 CPACK_COMPONENT_<compName>_DESCRIPTION - The description of a component.
10524 CPACK_COMPONENT_<compName>_GROUP - The group of a component.
10525 CPACK_COMPONENT_<compName>_DEPENDS - The dependencies (list of components)
10526 on which this component depends.
10527 CPACK_COMPONENT_<compName>_REQUIRED - True is this component is required.
10528 cpack_add_component - Describes a CPack installation component
10530 named by the COMPONENT argument to a CMake INSTALL command.
10531 cpack_add_component(compname
10534 [DISPLAY_NAME name]
10535 [DESCRIPTION description]
10536 [HIDDEN | REQUIRED | DISABLED ]
10537 [GROUP group]
10538 [DEPENDS comp1 comp2 ... ]
10539 [INSTALL_TYPES type1 type2 ... ]
10540 [DOWNLOADED]
10541 [ARCHIVE_FILE filename])
10542 The cmake_add_component command describes an installation compo‐
10547 nent, which the user can opt to install or remove as part of the
10548 graphical installation process. compname is the name of the com‐
10549 ponent, as provided to the COMPONENT argument of one or more
10550 CMake INSTALL commands.
10551 DISPLAY_NAME is the displayed name of the component, used in
10554 graphical installers to display the component name. This value
10555 can be any string.
10556 DESCRIPTION is an extended description of the component, used in
10559 graphical installers to give the user additional information
10560 about the component. Descriptions can span multiple lines using
10561 "\n" as the line separator. Typically, these descriptions should
10562 be no more than a few lines long.
10563 HIDDEN indicates that this component will be hidden in the
10566 graphical installer, so that the user cannot directly change
10567 whether it is installed or not.
10568 REQUIRED indicates that this component is required, and there‐
10571 fore will always be installed. It will be visible in the graphi‐
10572 cal installer, but it cannot be unselected. (Typically, required
10573 components are shown greyed out).
10574 DISABLED indicates that this component should be disabled (unse‐
10577 lected) by default. The user is free to select this component
10578 for installation, unless it is also HIDDEN.
10579 DEPENDS lists the components on which this component depends. If
10582 this component is selected, then each of the components listed
10583 must also be selected. The dependency information is encoded
10584 within the installer itself, so that users cannot install incon‐
10585 sistent sets of components.
10586 GROUP names the component group of which this component is a
10589 part. If not provided, the component will be a standalone compo‐
10590 nent, not part of any component group. Component groups are
10591 described with the cpack_add_component_group command, detailed
10592 below.
10593 INSTALL_TYPES lists the installation types of which this compo‐
10596 nent is a part. When one of these installations types is
10597 selected, this component will automatically be selected. Instal‐
10598 lation types are described with the cpack_add_install_type com‐
10599 mand, detailed below.
10600 DOWNLOADED indicates that this component should be downloaded
10603 on-the-fly by the installer, rather than packaged in with the
10604 installer itself. For more information, see the cpack_config‐
10605 ure_downloads command.
10606 ARCHIVE_FILE provides a name for the archive file created by
10609 CPack to be used for downloaded components. If not supplied,
10610 CPack will create a file with some name based on CPACK_PACK‐
10611 AGE_FILE_NAME and the name of the component. See cpack_config‐
10612 ure_downloads for more information.
10613 cpack_add_component_group - Describes a group of related CPack
10616 installation components.
10617 cpack_add_component_group(groupname
10620 [DISPLAY_NAME name]
10621 [DESCRIPTION description]
10622 [PARENT_GROUP parent]
10623 [EXPANDED]
10624 [BOLD_TITLE])
10625 The cpack_add_component_group describes a group of installation
10630 components, which will be placed together within the listing of
10631 options. Typically, component groups allow the user to
10632 select/deselect all of the components within a single group via
10633 a single group-level option. Use component groups to reduce the
10634 complexity of installers with many options. groupname is an
10635 arbitrary name used to identify the group in the GROUP argument
10636 of the cpack_add_component command, which is used to place a
10637 component in a group. The name of the group must not conflict
10638 with the name of any component.
10639 DISPLAY_NAME is the displayed name of the component group, used
10642 in graphical installers to display the component group name.
10643 This value can be any string.
10644 DESCRIPTION is an extended description of the component group,
10647 used in graphical installers to give the user additional infor‐
10648 mation about the components within that group. Descriptions can
10649 span multiple lines using "\n" as the line separator. Typically,
10650 these descriptions should be no more than a few lines long.
10651 PARENT_GROUP, if supplied, names the parent group of this group.
10654 Parent groups are used to establish a hierarchy of groups, pro‐
10655 viding an arbitrary hierarchy of groups.
10656 EXPANDED indicates that, by default, the group should show up as
10659 "expanded", so that the user immediately sees all of the compo‐
10660 nents within the group. Otherwise, the group will initially show
10661 up as a single entry.
10662 BOLD_TITLE indicates that the group title should appear in bold,
10665 to call the user's attention to the group.
10666 cpack_add_install_type - Add a new installation type containing
10669 a set of predefined component selections to the graphical in‐
10670 staller.
10671 cpack_add_install_type(typename
10674 [DISPLAY_NAME name])
10675 The cpack_add_install_type command identifies a set of prese‐
10680 lected components that represents a common use case for an
10681 application. For example, a "Developer" install type might
10682 include an application along with its header and library files,
10683 while an "End user" install type might just include the applica‐
10684 tion's executable. Each component identifies itself with one or
10685 more install types via the INSTALL_TYPES argument to
10686 cpack_add_component.
10687 DISPLAY_NAME is the displayed name of the install type, which
10690 will typically show up in a drop-down box within a graphical in‐
10691 staller. This value can be any string.
10692 cpack_configure_downloads - Configure CPack to download selected
10695 components on-the-fly as part of the installation process.
10696 cpack_configure_downloads(site
10699 [UPLOAD_DIRECTORY dirname]
10700 [ALL]
10701 [ADD_REMOVE|NO_ADD_REMOVE])
10702 The cpack_configure_downloads command configures installa‐
10707 tion-time downloads of selected components. For each download‐
10708 able component, CPack will create an archive containing the con‐
10709 tents of that component, which should be uploaded to the given
10710 site. When the user selects that component for installation, the
10711 installer will download and extract the component in place. This
10712 feature is useful for creating small installers that only down‐
10713 load the requested components, saving bandwidth. Additionally,
10714 the installers are small enough that they will be installed as
10715 part of the normal installation process, and the "Change" button
10716 in Windows Add/Remove Programs control panel will allow one to
10717 add or remove parts of the application after the original
10718 installation. On Windows, the downloaded-components functional‐
10719 ity requires the ZipDLL plug-in for NSIS, available at:
10720 http://nsis.sourceforge.net/ZipDLL_plug-in
10723 On Mac OS X, installers that download components on-the-fly can
10728 only be built and installed on system using Mac OS X 10.5 or
10729 later.
10730 The site argument is a URL where the archives for downloadable
10733 components will reside, e.g.,
10734 http://www.cmake.org/files/2.6.1/installer/ All of the archives
10735 produced by CPack should be uploaded to that location.
10736 UPLOAD_DIRECTORY is the local directory where CPack will create
10739 the various archives for each of the components. The contents of
10740 this directory should be uploaded to a location accessible by
10741 the URL given in the site argument. If omitted, CPack will use
10742 the directory CPackUploads inside the CMake binary directory to
10743 store the generated archives.
10744 The ALL flag indicates that all components be downloaded. Other‐
10747 wise, only those components explicitly marked as DOWNLOADED or
10748 that have a specified ARCHIVE_FILE will be downloaded. Addition‐
10749 ally, the ALL option implies ADD_REMOVE (unless NO_ADD_REMOVE is
10750 specified).
10751 ADD_REMOVE indicates that CPack should install a copy of the in‐
10754 staller that can be called from Windows' Add/Remove Programs
10755 dialog (via the "Modify" button) to change the set of installed
10756 components. NO_ADD_REMOVE turns off this behavior. This option
10757 is ignored on Mac OS X.
10758 CPackCygwin
10761 Cygwin CPack generator (Cygwin).
10762 The following variable is specific to installers build on and/or
10764 for Cygwin:
10765 CPACK_CYGWIN_PATCH_NUMBER - The Cygwin patch number.
10768 FIXME: This documentation is incomplete.
10769 CPACK_CYGWIN_PATCH_FILE - The Cygwin patch file.
10770 FIXME: This documentation is incomplete.
10771 CPACK_CYGWIN_BUILD_SCRIPT - The Cygwin build script.
10772 FIXME: This documentation is incomplete.
10773 CPackDMG
10776 DragNDrop CPack generator (Mac OS X).
10777 The following variables are specific to the DragNDrop installers
10779 built on Mac OS X:
10780 CPACK_DMG_VOLUME_NAME - The volume name of the generated disk
10783 image. Defaults to CPACK_PACKAGE_FILE_NAME.
10784 CPACK_DMG_FORMAT - The disk image format. Common values are UDRO
10789 (UDIF read-only), UDZO (UDIF zlib-compressed) or UDBZ (UDIF
10790 bzip2-compressed). Refer to hdiutil(1) for more information on
10791 other available formats.
10792 CPACK_DMG_DS_STORE - Path to a custom DS_Store file. This .DS_Store
10797 file e.g. can be used to specify the Finder window
10798 position/geometry and layout (such as hidden toolbars, placement of the
10799 icons etc.). This file has to be generated by the Finder (either manually or
10800 through OSA-script) using a normal folder from which the .DS_Store
10801 file can then be extracted.
10802 CPACK_DMG_BACKGROUND_IMAGE - Path to a background image file. This
10807 file will be used as the background for the Finder Window when the disk
10808 image is opened. By default no background image is set. The background
10809 image is applied after applying the custom .DS_Store file.
10810 CPACK_COMMAND_HDIUTIL - Path to the hdiutil(1) command used to
10815 operate on disk image files on Mac OS X. This variable can be used
10816 to override the automatically detected command (or specify its
10817 location if the auto-detection fails to find it.)
10818 CPACK_COMMAND_SETFILE - Path to the SetFile(1) command used to set
10823 extended attributes on files and directories on Mac OS X. This
10824 variable can be used to override the automatically detected
10825 command (or specify its location if the auto-detection fails to
10826 find it.)
10827 CPACK_COMMAND_REZ - Path to the Rez(1) command used to compile
10832 resources on Mac OS X. This variable can be used to override the
10833 automatically detected command (or specify its location if the
10834 auto-detection fails to find it.)
10835 CPackDeb
10838 The builtin (binary) CPack Deb generator (Unix only)
10839 CPackDeb may be used to create Deb package using CPack. CPackDeb
10841 is a CPack generator thus it uses the CPACK_XXX variables used
10842 by CPack : http://www.cmake.org/Wiki/CMake:CPackConfiguration.
10843 CPackDeb generator should work on any linux host but it will
10844 produce better deb package when Debian specific tools 'dpkg-xxx'
10845 are usable on the build system.
10846 CPackDeb has specific features which are controlled by the
10849 specifics CPACK_DEBIAN_XXX variables.You'll find a detailed
10850 usage on the wiki:
10851 http://www.cmake.org/Wiki/CMake:CPackPackageGenerators#DEB_.28UNIX_only.29
10854 However as a handy reminder here comes the list of specific
10856 variables:
10857 CPACK_DEBIAN_PACKAGE_NAME
10860 Mandatory : YES
10863 Default : CPACK_PACKAGE_NAME (lower case)
10864 The debian package summary
10865 CPACK_DEBIAN_PACKAGE_VERSION
10867 Mandatory : YES
10870 Default : CPACK_PACKAGE_VERSION
10871 The debian package version
10872 CPACK_DEBIAN_PACKAGE_ARCHITECTURE
10874 Mandatory : YES
10877 Default : Output of dpkg --print-architecture (or i386 if dpkg is not found)
10878 The debian package architecture
10879 CPACK_DEBIAN_PACKAGE_DEPENDS
10881 Mandatory : NO
10884 Default : -
10885 May be used to set deb dependencies.
10886 CPACK_DEBIAN_PACKAGE_MAINTAINER
10888 Mandatory : YES
10891 Default : CPACK_PACKAGE_CONTACT
10892 The debian package maintainer
10893 CPACK_DEBIAN_PACKAGE_DESCRIPTION
10895 Mandatory : YES
10898 Default : CPACK_PACKAGE_DESCRIPTION_SUMMARY
10899 The debian package description
10900 CPACK_DEBIAN_PACKAGE_SECTION
10902 Mandatory : YES
10905 Default : 'devel'
10906 The debian package section
10907 CPACK_DEBIAN_PACKAGE_PRIORITY
10909 Mandatory : YES
10912 Default : 'optional'
10913 The debian package priority
10914 CPACK_DEBIAN_PACKAGE_HOMEPAGE
10916 Mandatory : NO
10919 Default : -
10920 The URL of the web site for this package, preferably (when applicable) the
10921 site from which the original source can be obtained and any additional
10922 upstream documentation or information may be found.
10923 The content of this field is a simple URL without any surrounding
10924 characters such as <>.
10925 CPACK_DEBIAN_PACKAGE_SHLIBDEPS
10927 Mandatory : NO
10930 Default : OFF
10931 May be set to ON in order to use dpkg-shlibdeps to generate
10932 better package dependency list.
10933 You may need set CMAKE_INSTALL_RPATH toi appropriate value
10934 if you use this feature, because if you don't dpkg-shlibdeps
10935 may fail to find your own shared libs.
10936 See http://www.cmake.org/Wiki/CMake_RPATH_handling.
10937 CPACK_DEBIAN_PACKAGE_DEBUG
10939 Mandatory : NO
10942 Default : -
10943 May be set when invoking cpack in order to trace debug information
10944 during CPackDeb run.
10945 CPACK_DEBIAN_PACKAGE_PREDEPENDS
10947 Mandatory : NO
10950 Default : -
10951 see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
10952 This field is like Depends, except that it also forces dpkg to complete installation of
10953 the packages named before even starting the installation of the package which declares
10954 the pre-dependency.
10955 CPACK_DEBIAN_PACKAGE_ENHANCES
10957 Mandatory : NO
10960 Default : -
10961 see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
10962 This field is similar to Suggests but works in the opposite direction.
10963 It is used to declare that a package can enhance the functionality of another package.
10964 CPACK_DEBIAN_PACKAGE_BREAKS
10966 Mandatory : NO
10969 Default : -
10970 see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
10971 When one binary package declares that it breaks another, dpkg will refuse to allow the
10972 package which declares Breaks be installed unless the broken package is deconfigured first,
10973 and it will refuse to allow the broken package to be reconfigured.
10974 CPACK_DEBIAN_PACKAGE_CONFLICTS
10976 Mandatory : NO
10979 Default : -
10980 see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
10981 When one binary package declares a conflict with another using a Conflicts field,
10982 dpkg will refuse to allow them to be installed on the system at the same time.
10983 CPACK_DEBIAN_PACKAGE_PROVIDES
10985 Mandatory : NO
10988 Default : -
10989 see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
10990 A virtual package is one which appears in the Provides control field of another package.
10991 CPACK_DEBIAN_PACKAGE_REPLACES
10993 Mandatory : NO
10996 Default : -
10997 see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
10998 Packages can declare in their control file that they should overwrite
10999 files in certain other packages, or completely replace other packages.
11000 CPACK_DEBIAN_PACKAGE_RECOMMENDS
11002 Mandatory : NO
11005 Default : -
11006 see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
11007 Allows packages to declare a strong, but not absolute, dependency on other packages.
11008 CPACK_DEBIAN_PACKAGE_SUGGESTS
11010 Mandatory : NO
11013 Default : -
11014 see http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps
11015 Allows packages to declare a suggested package install grouping.
11016 CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
11018 Mandatory : NO
11021 Default : -
11022 This variable allow advanced user to add custom script to the control.tar.gz
11023 Typical usage is for conffiles, postinst, postrm, prerm.
11024 Usage: set(CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA
11025 "${CMAKE_CURRENT_SOURCE_DIR/prerm;${CMAKE_CURRENT_SOURCE_DIR}/postrm")
11026 CPackNSIS
11029 CPack NSIS generator specific options
11030 The following variables are specific to the graphical installers
11035 built on Windows using the Nullsoft Installation System.
11036 CPACK_NSIS_INSTALL_ROOT - The default installation directory presented
11039 to the end user by the NSIS installer is under this root dir. The full
11040 directory presented to the end user is:
11041 ${CPACK_NSIS_INSTALL_ROOT}/${CPACK_PACKAGE_INSTALL_DIRECTORY}
11042 CPACK_NSIS_MUI_ICON - An icon filename.
11047 The name of a *.ico file used as the main icon for the generated
11048 install program.
11049 CPACK_NSIS_MUI_UNIICON - An icon filename.
11054 The name of a *.ico file used as the main icon for the generated
11055 uninstall program.
11056 CPACK_NSIS_INSTALLER_MUI_ICON_CODE - undocumented.
11061 CPACK_NSIS_EXTRA_PREINSTALL_COMMANDS - Extra NSIS commands that
11066 will be added to the beginning of the install Section, before your
11067 install tree is available on the target system.
11068 CPACK_NSIS_EXTRA_INSTALL_COMMANDS - Extra NSIS commands that
11073 will be added to the end of the install Section, after your
11074 install tree is available on the target system.
11075 CPACK_NSIS_EXTRA_UNINSTALL_COMMANDS - Extra NSIS commands that will
11080 be added to the uninstall Section, before your install tree is
11081 removed from the target system.
11082 CPACK_NSIS_COMPRESSOR - The arguments that will be passed to the
11087 NSIS SetCompressor command.
11088 CPACK_NSIS_ENABLE_UNINSTALL_BEFORE_INSTALL - Ask about uninstalling
11093 previous versions first.
11094 If this is set to "ON", then an installer will look for previous
11095 installed versions and if one is found, ask the user whether to
11096 uninstall it before proceeding with the install.
11097 CPACK_NSIS_MODIFY_PATH - Modify PATH toggle.
11102 If this is set to "ON", then an extra page
11103 will appear in the installer that will allow the user to choose
11104 whether the program directory should be added to the system PATH
11105 variable.
11106 CPACK_NSIS_DISPLAY_NAME - The display name string that appears in
11111 the Windows Add/Remove Program control panel
11112 CPACK_NSIS_PACKAGE_NAME - The title displayed at the top of the
11117 installer.
11118 CPACK_NSIS_INSTALLED_ICON_NAME - A path to the executable that
11123 contains the installer icon.
11124 CPACK_NSIS_HELP_LINK - URL to a web site providing assistance in
11129 installing your application.
11130 CPACK_NSIS_URL_INFO_ABOUT - URL to a web site providing more
11135 information about your application.
11136 CPACK_NSIS_CONTACT - Contact information for questions and comments
11141 about the installation process.
11142 CPACK_NSIS_CREATE_ICONS_EXTRA - Additional NSIS commands for
11147 creating start menu shortcuts.
11148 CPACK_NSIS_DELETE_ICONS_EXTRA -Additional NSIS commands to
11153 uninstall start menu shortcuts.
11154 CPACK_NSIS_EXECUTABLES_DIRECTORY - Creating NSIS start menu links
11159 assumes that they are in 'bin' unless this variable is set.
11160 For example, you would set this to 'exec' if your executables are
11161 in an exec directory.
11162 CPACK_NSIS_MUI_FINISHPAGE_RUN - Specify an executable to add an option
11167 to run on the finish page of the NSIS installer.
11168 CPACK_NSIS_MENU_LINKS - Specify links in [application] menu.
11169 This should contain a list of pair "link" "link name". The link
11170 may be an URL or a path relative to installation prefix.
11171 Like:
11172 set(CPACK_NSIS_MENU_LINKS
11173 "doc/cmake-@CMake_VERSION_MAJOR@.@CMake_VERSION_MINOR@/cmake.html" "CMake Help"
11174 "http://www.cmake.org" "CMake Web Site")
11175 CPackPackageMaker
11178 PackageMaker CPack generator (Mac OS X).
11179 The following variable is specific to installers built on Mac OS
11181 X using PackageMaker:
11182 CPACK_OSX_PACKAGE_VERSION - The version of Mac OS X that the
11185 resulting PackageMaker archive should be compatible with. Different
11186 versions of Mac OS X support different
11187 features. For example, CPack can only build component-based
11188 installers for Mac OS X 10.4 or newer, and can only build
11189 installers that download component son-the-fly for Mac OS X 10.5
11190 or newer. If left blank, this value will be set to the minimum
11191 version of Mac OS X that supports the requested features. Set this
11192 variable to some value (e.g., 10.4) only if you want to guarantee
11193 that your installer will work on that version of Mac OS X, and
11194 don't mind missing extra features available in the installer
11195 shipping with later versions of Mac OS X.
11196 CPackRPM
11199 The builtin (binary) CPack RPM generator (Unix only)
11200 CPackRPM may be used to create RPM package using CPack. CPackRPM
11202 is a CPack generator thus it uses the CPACK_XXX variables used
11203 by CPack : http://www.cmake.org/Wiki/CMake:CPackConfiguration
11204 However CPackRPM has specific features which are controlled by
11207 the specifics CPACK_RPM_XXX variables. CPackRPM is a component
11208 aware generator so when CPACK_RPM_COMPONENT_INSTALL is ON some
11209 more CPACK_RPM_<ComponentName>_XXXX variables may be used in
11210 order to have component specific values. Note however that <com‐
11211 ponentName> refers to the **grouping name**. This may be either
11212 a component name or a component GROUP name. Usually those vars
11213 correspond to RPM spec file entities, one may find information
11214 about spec files here http://www.rpm.org/wiki/Docs. You'll find
11215 a detailed usage of CPackRPM on the wiki:
11216 http://www.cmake.org/Wiki/CMake:CPackPackageGenerators#RPM_.28Unix_Only.29
11219 However as a handy reminder here comes the list of specific
11221 variables:
11222 CPACK_RPM_PACKAGE_SUMMARY - The RPM package summary.
11225 Mandatory : YES
11226 Default : CPACK_PACKAGE_DESCRIPTION_SUMMARY
11227 CPACK_RPM_PACKAGE_NAME - The RPM package name.
11228 Mandatory : YES
11229 Default : CPACK_PACKAGE_NAME
11230 CPACK_RPM_PACKAGE_VERSION - The RPM package version.
11231 Mandatory : YES
11232 Default : CPACK_PACKAGE_VERSION
11233 CPACK_RPM_PACKAGE_ARCHITECTURE - The RPM package architecture.
11234 Mandatory : NO
11235 Default : -
11236 This may be set to "noarch" if you
11237 know you are building a noarch package.
11238 CPACK_RPM_PACKAGE_RELEASE - The RPM package release.
11239 Mandatory : YES
11240 Default : 1
11241 This is the numbering of the RPM package
11242 itself, i.e. the version of the packaging and not the version of the
11243 content (see CPACK_RPM_PACKAGE_VERSION). One may change the default
11244 value if the previous packaging was buggy and/or you want to put here
11245 a fancy Linux distro specific numbering.
11246 CPACK_RPM_PACKAGE_LICENSE - The RPM package license policy.
11247 Mandatory : YES
11248 Default : "unknown"
11249 CPACK_RPM_PACKAGE_GROUP - The RPM package group.
11250 Mandatory : YES
11251 Default : "unknown"
11252 CPACK_RPM_PACKAGE_VENDOR - The RPM package vendor.
11253 Mandatory : YES
11254 Default : CPACK_PACKAGE_VENDOR if set or "unknown"
11255 CPACK_RPM_PACKAGE_URL - The projects URL.
11256 Mandatory : NO
11257 Default : -
11258 CPACK_RPM_PACKAGE_DESCRIPTION - RPM package description.
11259 Mandatory : YES
11260 Default : CPACK_PACKAGE_DESCRIPTION_FILE if set or "no package description available"
11261 CPACK_RPM_COMPRESSION_TYPE - RPM compression type.
11262 Mandatory : NO
11263 Default : -
11264 May be used to override RPM compression type to be used
11265 to build the RPM. For example some Linux distribution now default
11266 to lzma or xz compression whereas older cannot use such RPM.
11267 Using this one can enforce compression type to be used.
11268 Possible value are: lzma, xz, bzip2 and gzip.
11269 CPACK_RPM_PACKAGE_REQUIRES - RPM spec requires field.
11270 Mandatory : NO
11271 Default : -
11272 May be used to set RPM dependencies (requires).
11273 Note that you must enclose the complete requires string between quotes,
11274 for example:
11275 set(CPACK_RPM_PACKAGE_REQUIRES "python >= 2.5.0, cmake >= 2.8")
11276 The required package list of an RPM file could be printed with
11277 rpm -qp --requires file.rpm
11278 CPACK_RPM_PACKAGE_SUGGESTS - RPM spec suggest field.
11279 Mandatory : NO
11280 Default : -
11281 May be used to set weak RPM dependencies (suggests).
11282 Note that you must enclose the complete requires string between quotes.
11283 CPACK_RPM_PACKAGE_PROVIDES - RPM spec provides field.
11284 Mandatory : NO
11285 Default : -
11286 May be used to set RPM dependencies (provides).
11287 The provided package list of an RPM file could be printed with
11288 rpm -qp --provides file.rpm
11289 CPACK_RPM_PACKAGE_OBSOLETES - RPM spec obsoletes field.
11290 Mandatory : NO
11291 Default : -
11292 May be used to set RPM packages that are obsoleted by this one.
11293 CPACK_RPM_PACKAGE_RELOCATABLE - build a relocatable RPM.
11294 Mandatory : NO
11295 Default : CPACK_PACKAGE_RELOCATABLE
11296 If this variable is set to TRUE or ON CPackRPM will try
11297 to build a relocatable RPM package. A relocatable RPM may
11298 be installed using rpm --prefix or --relocate in order to
11299 install it at an alternate place see rpm(8).
11300 Note that currently this may fail if CPACK_SET_DESTDIR is set to ON.
11301 If CPACK_SET_DESTDIR is set then you will get a warning message
11302 but if there is file installed with absolute path you'll get
11303 unexpected behavior.
11304 CPACK_RPM_SPEC_INSTALL_POST - [deprecated].
11305 Mandatory : NO
11306 Default : -
11307 This way of specifying post-install script is deprecated use
11308 CPACK_RPM_POST_INSTALL_SCRIPT_FILE
11309 May be used to set an RPM post-install command inside the spec file.
11310 For example setting it to "/bin/true" may be used to prevent
11311 rpmbuild to strip binaries.
11312 CPACK_RPM_SPEC_MORE_DEFINE - RPM extended spec definitions lines.
11313 Mandatory : NO
11314 Default : -
11315 May be used to add any %define lines to the generated spec file.
11316 CPACK_RPM_PACKAGE_DEBUG - Toggle CPackRPM debug output.
11317 Mandatory : NO
11318 Default : -
11319 May be set when invoking cpack in order to trace debug information
11320 during CPack RPM run. For example you may launch CPack like this
11321 cpack -D CPACK_RPM_PACKAGE_DEBUG=1 -G RPM
11322 CPACK_RPM_USER_BINARY_SPECFILE - A user provided spec file.
11323 Mandatory : NO
11324 Default : -
11325 May be set by the user in order to specify a USER binary spec file
11326 to be used by CPackRPM instead of generating the file.
11327 The specified file will be processed by configure_file( @ONLY).
11328 One can provide a component specific file by setting
11329 CPACK_RPM_<componentName>_USER_BINARY_SPECFILE.
11330 CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE - Spec file template.
11331 Mandatory : NO
11332 Default : -
11333 If set CPack will generate a template for USER specified binary
11334 spec file and stop with an error. For example launch CPack like this
11335 cpack -D CPACK_RPM_GENERATE_USER_BINARY_SPECFILE_TEMPLATE=1 -G RPM
11336 The user may then use this file in order to hand-craft is own
11337 binary spec file which may be used with CPACK_RPM_USER_BINARY_SPECFILE.
11338 CPACK_RPM_PRE_INSTALL_SCRIPT_FILE
11339 CPACK_RPM_PRE_UNINSTALL_SCRIPT_FILE
11340 Mandatory : NO
11341 Default : -
11342 May be used to embed a pre (un)installation script in the spec file.
11343 The refered script file(s) will be read and directly
11344 put after the %pre or %preun section
11345 If CPACK_RPM_COMPONENT_INSTALL is set to ON the (un)install script for
11346 each component can be overridden with
11347 CPACK_RPM_<COMPONENT>_PRE_INSTALL_SCRIPT_FILE and
11348 CPACK_RPM_<COMPONENT>_PRE_UNINSTALL_SCRIPT_FILE
11349 One may verify which scriptlet has been included with
11350 rpm -qp --scripts package.rpm
11351 CPACK_RPM_POST_INSTALL_SCRIPT_FILE
11352 CPACK_RPM_POST_UNINSTALL_SCRIPT_FILE
11353 Mandatory : NO
11354 Default : -
11355 May be used to embed a post (un)installation script in the spec file.
11356 The refered script file(s) will be read and directly
11357 put after the %post or %postun section
11358 If CPACK_RPM_COMPONENT_INSTALL is set to ON the (un)install script for
11359 each component can be overridden with
11360 CPACK_RPM_<COMPONENT>_POST_INSTALL_SCRIPT_FILE and
11361 CPACK_RPM_<COMPONENT>_POST_UNINSTALL_SCRIPT_FILE
11362 One may verify which scriptlet has been included with
11363 rpm -qp --scripts package.rpm
11364 CPACK_RPM_USER_FILELIST
11365 CPACK_RPM_<COMPONENT>_USER_FILELIST
11366 Mandatory : NO
11367 Default : -
11368 May be used to explicitly specify %(<directive>) file line
11369 in the spec file. Like %config(noreplace) or any other directive
11370 that be found in the %files section. Since CPackRPM is generating
11371 the list of files (and directories) the user specified files of
11372 the CPACK_RPM_<COMPONENT>_USER_FILELIST list will be removed from the generated list.
11373 CPACK_RPM_CHANGELOG_FILE - RPM changelog file.
11374 Mandatory : NO
11375 Default : -
11376 May be used to embed a changelog in the spec file.
11377 The refered file will be read and directly put after the %changelog
11378 section.
11379 CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST - list of path to be excluded.
11380 Mandatory : NO
11381 Default : /etc /etc/init.d /usr /usr/share /usr/share/doc /usr/bin /usr/lib /usr/lib64 /usr/include
11382 May be used to exclude path (directories or files) from the auto-generated
11383 list of paths discovered by CPack RPM. The defaut value contains a reasonable
11384 set of values if the variable is not defined by the user. If the variable
11385 is defined by the user then CPackRPM will NOT any of the default path.
11386 If you want to add some path to the default list then you can use
11387 CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION variable.
11388 CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION - additional list of path to be excluded.
11389 Mandatory : NO
11390 Default : -
11391 May be used to add more exclude path (directories or files) from the initial
11392 default list of excluded paths. See CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST.
11393 CPackWIX
11396 CPack WiX generator specific options
11397 The following variables are specific to the installers built on
11402 Windows using WiX.
11403 CPACK_WIX_UPGRADE_GUID - Upgrade GUID (Product/@UpgradeCode)
11406 Will be automatically generated unless explicitly provided.
11411 It should be explicitly set to a constant generated gloabally
11414 unique identifier (GUID) to allow your installers to replace
11415 existing installations that use the same GUID.
11416 You may for example explicitly set this variable in your CMake‐
11419 Lists.txt to the value that has been generated per default. You
11420 should not use GUIDs that you did not generate yourself or which
11421 may belong to other projects.
11422 A GUID shall have the following fixed length syntax:
11425 XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
11426 (each X represents an uppercase hexadecimal digit)
11429 CPACK_WIX_PRODUCT_GUID - Product GUID (Product/@Id)
11430 Will be automatically generated unless explicitly provided.
11435 If explicitly provided this will set the Product Id of your in‐
11438 staller.
11439 The installer will abort if it detects a pre-existing installa‐
11442 tion that uses the same GUID.
11443 The GUID shall use the syntax described for
11446 CPACK_WIX_UPGRADE_GUID.
11447 CPACK_WIX_LICENSE_RTF - RTF License File
11450 If CPACK_RESOURCE_FILE_LICENSE has an .rtf extension it is used
11455 as-is.
11456 If CPACK_RESOURCE_FILE_LICENSE has an .txt extension it is
11459 implicitly converted to RTF by the WiX Generator.
11460 With CPACK_WIX_LICENSE_RTF you can override the license file
11463 used by the WiX Generator in case CPACK_RESOURCE_FILE_LICENSE is
11464 in an unsupported format or the .txt -> .rtf conversion does not
11465 work as expected.
11466 CPACK_WIX_PRODUCT_ICON - The Icon shown next to the program name
11472 in Add/Remove programs.
11473 If set, this icon is used in place of the default icon.
11476 CPACK_WIX_UI_BANNER - The bitmap will appear at the top of all
11482 installer pages other than the welcome and completion dialogs.
11483 If set, this image will replace the default banner image.
11486 This image must be 493 by 58 pixels.
11489 CPACK_WIX_UI_DIALOG - Background bitmap used on the welcome and
11495 completion dialogs.
11496 If this variable is set, the installer will replace the default
11499 dialog image.
11500 This image must be 493 by 312 pixels.
11503 CPACK_WIX_PROGRAM_MENU_FOLDER - Start menu folder name for
11509 launcher.
11510 If this variable is not set, it will be initialized with
11513 CPACK_PACKAGE_NAME
11514 CPACK_WIX_CULTURES - Language(s) of the installer
11517 Languages are compiled into the WixUI extension library. To use
11520 them, simply provide the name of the culture. If you specify
11521 more than one culture identifier in a comma or semicolon delim‐
11522 ited list, the first one that is found will be used. You can
11523 find a list of supported languages at: http://wix.source‐
11524 forge.net/manual-wix3/WixUI_localization.htm
11525 CPACK_WIX_TEMPLATE - Template file for WiX generation
11528 If this variable is set, the specified template will be used to
11531 generate the WiX wxs file. This should be used if further cus‐
11532 tomization of the output is required.
11533 If this variable is not set, the default MSI template included
11536 with CMake will be used.
11537 CTest Configure a project for testing with CTest/CDash
11541 Include this module in the top CMakeLists.txt file of a project
11543 to enable testing with CTest and dashboard submissions to CDash:
11544 project(MyProject)
11547 ...
11548 include(CTest)
11549 The module automatically creates a BUILD_TESTING option that
11551 selects whether to enable testing support (ON by default).
11552 After including the module, use code like
11553 if(BUILD_TESTING)
11556 # ... CMake code to create tests ...
11557 endif()
11558 to creating tests when testing is enabled.
11560 To enable submissions to a CDash server, create a CTestCon‐
11563 fig.cmake file at the top of the project with content such as
11564 set(CTEST_PROJECT_NAME "MyProject")
11567 set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
11568 set(CTEST_DROP_METHOD "http")
11569 set(CTEST_DROP_SITE "my.cdash.org")
11570 set(CTEST_DROP_LOCATION "/submit.php?project=MyProject")
11571 set(CTEST_DROP_SITE_CDASH TRUE)
11572 (the CDash server can provide the file to a project administra‐
11574 tor who configures 'MyProject'). Settings in the config file are
11575 shared by both this CTest module and the CTest command-line
11576 tool's dashboard script mode (ctest -S).
11577 While building a project for submission to CDash, CTest scans
11580 the build output for errors and warnings and reports them with
11581 surrounding context from the build log. This generic approach
11582 works for all build tools, but does not give details about the
11583 command invocation that produced a given problem. One may get
11584 more detailed reports by adding
11585 set(CTEST_USE_LAUNCHERS 1)
11588 to the CTestConfig.cmake file. When this option is enabled, the
11590 CTest module tells CMake's Makefile generators to invoke every
11591 command in the generated build system through a CTest launcher
11592 program. (Currently the CTEST_USE_LAUNCHERS option is ignored
11593 on non-Makefile generators.) During a manual build each
11594 launcher transparently runs the command it wraps. During a
11595 CTest-driven build for submission to CDash each launcher reports
11596 detailed information when its command fails or warns. (Setting
11597 CTEST_USE_LAUNCHERS in CTestConfig.cmake is convenient, but also
11598 adds the launcher overhead even for manual builds. One may
11599 instead set it in a CTest dashboard script and add it to the
11600 CMake cache for the build tree.)
11601 CTestScriptMode
11604 This file is read by ctest in script mode (-S)
11607 CTestUseLaunchers
11610 Set the RULE_LAUNCH_* global properties when CTEST_USE_LAUNCHERS
11611 is on.
11612 CTestUseLaunchers is automatically included when you
11614 include(CTest). However, it is split out into its own module
11615 file so projects can use the CTEST_USE_LAUNCHERS functionality
11616 independently.
11617 To use launchers, set CTEST_USE_LAUNCHERS to ON in a ctest -S
11620 dashboard script, and then also set it in the cache of the con‐
11621 figured project. Both cmake and ctest need to know the value of
11622 it for the launchers to work properly. CMake needs to know in
11623 order to generate proper build rules, and ctest, in order to
11624 produce the proper error and warning analysis.
11625 For convenience, you may set the ENV variable CTEST_USE_LAUNCH‐
11628 ERS_DEFAULT in your ctest -S script, too. Then, as long as your
11629 CMakeLists uses include(CTest) or include(CTestUseLaunchers), it
11630 will use the value of the ENV variable to initialize a
11631 CTEST_USE_LAUNCHERS cache variable. This cache variable initial‐
11632 ization only occurs if CTEST_USE_LAUNCHERS is not already
11633 defined.
11634 CheckCCompilerFlag
11637 Check whether the C compiler supports a given flag.
11638 CHECK_C_COMPILER_FLAG(<flag> <var>)
11640 <flag> - the compiler flag
11643 <var> - variable to store the result
11644 This internally calls the check_c_source_compiles macro and sets
11646 CMAKE_REQUIRED_DEFINITIONS to <flag>. See help for CheckCSource‐
11647 Compiles for a listing of variables that can otherwise modify
11648 the build. The result only tells that the compiler does not give
11649 an error message when it encounters the flag. If the flag has
11650 any effect or even a specific one is beyond the scope of this
11651 module.
11652 CheckCSourceCompiles
11655 Check if given C source compiles and links into an executable
11656 CHECK_C_SOURCE_COMPILES(<code> <var> [FAIL_REGEX <fail-regex>])
11658 <code> - source code to try to compile, must define 'main'
11661 <var> - variable to store whether the source code compiled
11662 <fail-regex> - fail if test output matches this regex
11663 The following variables may be set before calling this macro to
11665 modify the way the check is run:
11666 CMAKE_REQUIRED_FLAGS = string of compile command line flags
11669 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
11670 CMAKE_REQUIRED_INCLUDES = list of include directories
11671 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
11672 CheckCSourceRuns
11675 Check if the given C source code compiles and runs.
11676 CHECK_C_SOURCE_RUNS(<code> <var>)
11678 <code> - source code to try to compile
11681 <var> - variable to store the result
11682 (1 for success, empty for failure)
11683 The following variables may be set before calling this macro to
11685 modify the way the check is run:
11686 CMAKE_REQUIRED_FLAGS = string of compile command line flags
11689 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
11690 CMAKE_REQUIRED_INCLUDES = list of include directories
11691 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
11692 CheckCXXCompilerFlag
11695 Check whether the CXX compiler supports a given flag.
11696 CHECK_CXX_COMPILER_FLAG(<flag> <var>)
11698 <flag> - the compiler flag
11701 <var> - variable to store the result
11702 This internally calls the check_cxx_source_compiles macro and
11704 sets CMAKE_REQUIRED_DEFINITIONS to <flag>. See help for Check‐
11705 CXXSourceCompiles for a listing of variables that can otherwise
11706 modify the build. The result only tells that the compiler does
11707 not give an error message when it encounters the flag. If the
11708 flag has any effect or even a specific one is beyond the scope
11709 of this module.
11710 CheckCXXSourceCompiles
11713 Check if given C++ source compiles and links into an executable
11714 CHECK_CXX_SOURCE_COMPILES(<code> <var> [FAIL_REGEX
11716 <fail-regex>])
11717 <code> - source code to try to compile, must define 'main'
11720 <var> - variable to store whether the source code compiled
11721 <fail-regex> - fail if test output matches this regex
11722 The following variables may be set before calling this macro to
11724 modify the way the check is run:
11725 CMAKE_REQUIRED_FLAGS = string of compile command line flags
11728 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
11729 CMAKE_REQUIRED_INCLUDES = list of include directories
11730 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
11731 CheckCXXSourceRuns
11734 Check if the given C++ source code compiles and runs.
11735 CHECK_CXX_SOURCE_RUNS(<code> <var>)
11737 <code> - source code to try to compile
11740 <var> - variable to store the result
11741 (1 for success, empty for failure)
11742 The following variables may be set before calling this macro to
11744 modify the way the check is run:
11745 CMAKE_REQUIRED_FLAGS = string of compile command line flags
11748 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
11749 CMAKE_REQUIRED_INCLUDES = list of include directories
11750 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
11751 CheckCXXSymbolExists
11754 Check if a symbol exists as a function, variable, or macro in
11755 C++
11756 CHECK_CXX_SYMBOL_EXISTS(<symbol> <files> <variable>)
11758 Check that the <symbol> is available after including given
11761 header <files> and store the result in a <variable>. Specify
11762 the list of files in one argument as a semicolon-separated list.
11763 CHECK_CXX_SYMBOL_EXISTS() can be used to check in C++ files, as
11764 opposed to CHECK_SYMBOL_EXISTS(), which works only for C.
11765 If the header files define the symbol as a macro it is consid‐
11768 ered available and assumed to work. If the header files declare
11769 the symbol as a function or variable then the symbol must also
11770 be available for linking. If the symbol is a type or enum value
11771 it will not be recognized (consider using CheckTypeSize or
11772 CheckCSourceCompiles).
11773 The following variables may be set before calling this macro to
11776 modify the way the check is run:
11777 CMAKE_REQUIRED_FLAGS = string of compile command line flags
11780 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
11781 CMAKE_REQUIRED_INCLUDES = list of include directories
11782 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
11783 CheckFortranFunctionExists
11786 macro which checks if the Fortran function exists
11787 CHECK_FORTRAN_FUNCTION_EXISTS(FUNCTION VARIABLE)
11789 FUNCTION - the name of the Fortran function
11792 VARIABLE - variable to store the result
11793 The following variables may be set before calling this macro to
11798 modify the way the check is run:
11799 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
11802 CheckFunctionExists
11805 Check if a C function can be linked
11806 CHECK_FUNCTION_EXISTS(<function> <variable>)
11808 Check that the <function> is provided by libraries on the system
11811 and store the result in a <variable>. This does not verify that
11812 any system header file declares the function, only that it can
11813 be found at link time (consider using CheckSymbolExists).
11814 The following variables may be set before calling this macro to
11817 modify the way the check is run:
11818 CMAKE_REQUIRED_FLAGS = string of compile command line flags
11821 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
11822 CMAKE_REQUIRED_INCLUDES = list of include directories
11823 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
11824 CheckIncludeFile
11827 macro which checks the include file exists.
11828 CHECK_INCLUDE_FILE(INCLUDE VARIABLE)
11830 INCLUDE - name of include file
11833 VARIABLE - variable to return result
11834 an optional third argument is the CFlags to add to the compile
11839 line or you can use CMAKE_REQUIRED_FLAGS
11840 The following variables may be set before calling this macro to
11843 modify the way the check is run:
11844 CMAKE_REQUIRED_FLAGS = string of compile command line flags
11847 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
11848 CMAKE_REQUIRED_INCLUDES = list of include directories
11849 CheckIncludeFileCXX
11855 Check if the include file exists.
11856 CHECK_INCLUDE_FILE_CXX(INCLUDE VARIABLE)
11858 INCLUDE - name of include file
11863 VARIABLE - variable to return result
11864 An optional third argument is the CFlags to add to the compile
11869 line or you can use CMAKE_REQUIRED_FLAGS.
11870 The following variables may be set before calling this macro to
11873 modify the way the check is run:
11874 CMAKE_REQUIRED_FLAGS = string of compile command line flags
11877 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
11878 CMAKE_REQUIRED_INCLUDES = list of include directories
11879 CheckIncludeFiles
11885 Check if the files can be included
11886 CHECK_INCLUDE_FILES(INCLUDE VARIABLE)
11891 INCLUDE - list of files to include
11894 VARIABLE - variable to return result
11895 The following variables may be set before calling this macro to
11900 modify the way the check is run:
11901 CMAKE_REQUIRED_FLAGS = string of compile command line flags
11904 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
11905 CMAKE_REQUIRED_INCLUDES = list of include directories
11906 CheckLanguage
11909 Check if a language can be enabled
11910 Usage:
11912 check_language(<lang>)
11915 where <lang> is a language that may be passed to enable_lan‐
11917 guage() such as "Fortran". If CMAKE_<lang>_COMPILER is already
11918 defined the check does nothing. Otherwise it tries enabling the
11919 language in a test project. The result is cached in
11920 CMAKE_<lang>_COMPILER as the compiler that was found, or NOT‐
11921 FOUND if the language cannot be enabled.
11922 Example:
11925 check_language(Fortran)
11928 if(CMAKE_Fortran_COMPILER)
11929 enable_language(Fortran)
11930 else()
11931 message(STATUS "No Fortran support")
11932 endif()
11933 CheckLibraryExists
11936 Check if the function exists.
11937 CHECK_LIBRARY_EXISTS (LIBRARY FUNCTION LOCATION VARIABLE)
11939 LIBRARY - the name of the library you are looking for
11942 FUNCTION - the name of the function
11943 LOCATION - location where the library should be found
11944 VARIABLE - variable to store the result
11945 The following variables may be set before calling this macro to
11950 modify the way the check is run:
11951 CMAKE_REQUIRED_FLAGS = string of compile command line flags
11954 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
11955 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
11956 CheckPrototypeDefinition
11959 Check if the protoype we expect is correct.
11960 check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER
11962 VARIABLE)
11963 FUNCTION - The name of the function (used to check if prototype exists)
11966 PROTOTYPE- The prototype to check.
11967 RETURN - The return value of the function.
11968 HEADER - The header files required.
11969 VARIABLE - The variable to store the result.
11970 Example:
11972 check_prototype_definition(getpwent_r
11975 "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)"
11976 "NULL"
11977 "unistd.h;pwd.h"
11978 SOLARIS_GETPWENT_R)
11979 The following variables may be set before calling this macro to
11981 modify the way the check is run:
11982 CMAKE_REQUIRED_FLAGS = string of compile command line flags
11985 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
11986 CMAKE_REQUIRED_INCLUDES = list of include directories
11987 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
11988 CheckStructHasMember
11991 Check if the given struct or class has the specified member
11992 variable
11993 CHECK_STRUCT_HAS_MEMBER (STRUCT MEMBER HEADER VARIABLE)
11995 STRUCT - the name of the struct or class you are interested in
11998 MEMBER - the member which existence you want to check
11999 HEADER - the header(s) where the prototype should be declared
12000 VARIABLE - variable to store the result
12001 The following variables may be set before calling this macro to
12006 modify the way the check is run:
12007 CMAKE_REQUIRED_FLAGS = string of compile command line flags
12010 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
12011 CMAKE_REQUIRED_INCLUDES = list of include directories
12012 Example: CHECK_STRUCT_HAS_MEMBER("struct timeval" tv_sec
12017 sys/select.h HAVE_TIMEVAL_TV_SEC)
12018 CheckSymbolExists
12021 Check if a symbol exists as a function, variable, or macro
12022 CHECK_SYMBOL_EXISTS(<symbol> <files> <variable>)
12024 Check that the <symbol> is available after including given
12027 header <files> and store the result in a <variable>. Specify
12028 the list of files in one argument as a semicolon-separated list.
12029 If the header files define the symbol as a macro it is consid‐
12032 ered available and assumed to work. If the header files declare
12033 the symbol as a function or variable then the symbol must also
12034 be available for linking. If the symbol is a type or enum value
12035 it will not be recognized (consider using CheckTypeSize or
12036 CheckCSourceCompiles). If the check needs to be done in C++,
12037 consider using CHECK_CXX_SYMBOL_EXISTS(), which does the same as
12038 CHECK_SYMBOL_EXISTS(), but in C++.
12039 The following variables may be set before calling this macro to
12042 modify the way the check is run:
12043 CMAKE_REQUIRED_FLAGS = string of compile command line flags
12046 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
12047 CMAKE_REQUIRED_INCLUDES = list of include directories
12048 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
12049 CheckTypeSize
12052 Check sizeof a type
12053 CHECK_TYPE_SIZE(TYPE VARIABLE [BUILTIN_TYPES_ONLY])
12055 Check if the type exists and determine its size. On return,
12057 "HAVE_${VARIABLE}" holds the existence of the type, and "${VARI‐
12058 ABLE}" holds one of the following:
12059 <size> = type has non-zero size <size>
12062 "0" = type has arch-dependent size (see below)
12063 "" = type does not exist
12064 Furthermore, the variable "${VARIABLE}_CODE" holds C preproces‐
12066 sor code to define the macro "${VARIABLE}" to the size of the
12067 type, or leave the macro undefined if the type does not exist.
12068 The variable "${VARIABLE}" may be "0" when CMAKE_OSX_ARCHITEC‐
12071 TURES has multiple architectures for building OS X universal
12072 binaries. This indicates that the type size varies across archi‐
12073 tectures. In this case "${VARIABLE}_CODE" contains C preproces‐
12074 sor tests mapping from each architecture macro to the corre‐
12075 sponding type size. The list of architecture macros is stored in
12076 "${VARIABLE}_KEYS", and the value for each key is stored in
12077 "${VARIABLE}-${KEY}".
12078 If the BUILTIN_TYPES_ONLY option is not given, the macro checks
12081 for headers <sys/types.h>, <stdint.h>, and <stddef.h>, and saves
12082 results in HAVE_SYS_TYPES_H, HAVE_STDINT_H, and HAVE_STDDEF_H.
12083 The type size check automatically includes the available head‐
12084 ers, thus supporting checks of types defined in the headers.
12085 Despite the name of the macro you may use it to check the size
12088 of more complex expressions, too. To check e.g. for the size of
12089 a struct member you can do something like this:
12090 check_type_size("((struct something*)0)->member" SIZEOF_MEMBER)
12093 The following variables may be set before calling this macro to
12098 modify the way the check is run:
12099 CMAKE_REQUIRED_FLAGS = string of compile command line flags
12102 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
12103 CMAKE_REQUIRED_INCLUDES = list of include directories
12104 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
12105 CMAKE_EXTRA_INCLUDE_FILES = list of extra headers to include
12106 CheckVariableExists
12109 Check if the variable exists.
12110 CHECK_VARIABLE_EXISTS(VAR VARIABLE)
12112 VAR - the name of the variable
12117 VARIABLE - variable to store the result
12118 This macro is only for C variables.
12123 The following variables may be set before calling this macro to
12126 modify the way the check is run:
12127 CMAKE_REQUIRED_FLAGS = string of compile command line flags
12130 CMAKE_REQUIRED_DEFINITIONS = list of macros to define (-DFOO=bar)
12131 CMAKE_REQUIRED_LIBRARIES = list of libraries to link
12132 Dart Configure a project for testing with CTest or old Dart Tcl
12135 Client
12136 This file is the backwards-compatibility version of the CTest
12138 module. It supports using the old Dart 1 Tcl client for driving
12139 dashboard submissions as well as testing with CTest. This mod‐
12140 ule should be included in the CMakeLists.txt file at the top of
12141 a project. Typical usage:
12142 include(Dart)
12145 if(BUILD_TESTING)
12146 # ... testing related CMake code ...
12147 endif()
12148 The BUILD_TESTING option is created by the Dart module to deter‐
12150 mine whether testing support should be enabled. The default is
12151 ON.
12152 DeployQt4
12155 Functions to help assemble a standalone Qt4 executable.
12156 A collection of CMake utility functions useful for deploying Qt4
12158 executables.
12159 The following functions are provided by this module:
12162 write_qt4_conf
12165 resolve_qt4_paths
12166 fixup_qt4_executable
12167 install_qt4_plugin_path
12168 install_qt4_plugin
12169 install_qt4_executable
12170 Requires CMake 2.6 or greater because it uses function and PAR‐
12172 ENT_SCOPE. Also depends on BundleUtilities.cmake.
12173 WRITE_QT4_CONF(<qt_conf_dir> <qt_conf_contents>)
12176 Writes a qt.conf file with the <qt_conf_contents> into
12178 <qt_conf_dir>.
12179 RESOLVE_QT4_PATHS(<paths_var> [<executable_path>])
12182 Loop through <paths_var> list and if any don't exist resolve
12184 them relative to the <executable_path> (if supplied) or the
12185 CMAKE_INSTALL_PREFIX.
12186 FIXUP_QT4_EXECUTABLE(<executable> [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>])
12189 Copies Qt plugins, writes a Qt configuration file (if needed)
12191 and fixes up a Qt4 executable using BundleUtilities so it is
12192 standalone and can be drag-and-drop copied to another machine as
12193 long as all of the system libraries are compatible.
12194 <executable> should point to the executable to be fixed-up.
12197 <qtplugins> should contain a list of the names or paths of any
12200 Qt plugins to be installed.
12201 <libs> will be passed to BundleUtilities and should be a list of
12204 any already installed plugins, libraries or executables to also
12205 be fixed-up.
12206 <dirs> will be passed to BundleUtilities and should contain and
12209 directories to be searched to find library dependencies.
12210 <plugins_dir> allows an custom plugins directory to be used.
12213 <request_qt_conf> will force a qt.conf file to be written even
12216 if not needed.
12217 INSTALL_QT4_PLUGIN_PATH(plugin executable copy installed_plugin_path_var <plugins_dir> <component> <configurations>)
12220 Install (or copy) a resolved <plugin> to the default plugins
12222 directory (or <plugins_dir>) relative to <executable> and store
12223 the result in <installed_plugin_path_var>.
12224 If <copy> is set to TRUE then the plugins will be copied rather
12227 than installed. This is to allow this module to be used at CMake
12228 time rather than install time.
12229 If <component> is set then anything installed will use this COM‐
12232 PONENT.
12233 INSTALL_QT4_PLUGIN(plugin executable copy installed_plugin_path_var <plugins_dir> <component>)
12236 Install (or copy) an unresolved <plugin> to the default plugins
12238 directory (or <plugins_dir>) relative to <executable> and store
12239 the result in <installed_plugin_path_var>. See documentation of
12240 INSTALL_QT4_PLUGIN_PATH.
12241 INSTALL_QT4_EXECUTABLE(<executable> [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>])
12244 Installs Qt plugins, writes a Qt configuration file (if needed)
12246 and fixes up a Qt4 executable using BundleUtilities so it is
12247 standalone and can be drag-and-drop copied to another machine as
12248 long as all of the system libraries are compatible. The exe‐
12249 cutable will be fixed-up at install time. <component> is the
12250 COMPONENT used for bundle fixup and plugin installation. See
12251 documentation of FIXUP_QT4_BUNDLE.
12252 Documentation
12255 DocumentationVTK.cmake
12256 This file provides support for the VTK documentation framework.
12258 It relies on several tools (Doxygen, Perl, etc).
12259 ExternalData
12262 Manage data files stored outside source tree
12263 Use this module to unambiguously reference data files stored
12265 outside the source tree and fetch them at build time from arbi‐
12266 trary local and remote content-addressed locations. Functions
12267 provided by this module recognize arguments with the syntax
12268 "DATA{<name>}" as references to external data, replace them with
12269 full paths to local copies of those data, and create build rules
12270 to fetch and update the local copies.
12271 The DATA{} syntax is literal and the <name> is a full or rela‐
12274 tive path within the source tree. The source tree must contain
12275 either a real data file at <name> or a "content link" at
12276 <name><ext> containing a hash of the real file using a hash
12277 algorithm corresponding to <ext>. For example, the argument
12278 "DATA{img.png}" may be satisfied by either a real "img.png" file
12279 in the current source directory or a "img.png.md5" file contain‐
12280 ing its MD5 sum.
12281 The 'ExternalData_Expand_Arguments' function evaluates DATA{}
12284 references in its arguments and constructs a new list of argu‐
12285 ments:
12286 ExternalData_Expand_Arguments(
12289 <target> # Name of data management target
12290 <outVar> # Output variable
12291 [args...] # Input arguments, DATA{} allowed
12292 )
12293 It replaces each DATA{} reference in an argument with the full
12295 path of a real data file on disk that will exist after the <tar‐
12296 get> builds.
12297 The 'ExternalData_Add_Test' function wraps around the CMake
12300 add_test() command but supports DATA{} references in its argu‐
12301 ments:
12302 ExternalData_Add_Test(
12305 <target> # Name of data management target
12306 ... # Arguments of add_test(), DATA{} allowed
12307 )
12308 It passes its arguments through ExternalData_Expand_Arguments
12310 and then invokes add_test() using the results.
12311 The 'ExternalData_Add_Target' function creates a custom target
12314 to manage local instances of data files stored externally:
12315 ExternalData_Add_Target(
12318 <target> # Name of data management target
12319 )
12320 It creates custom commands in the target as necessary to make
12322 data files available for each DATA{} reference previously evalu‐
12323 ated by other functions provided by this module. A list of URL
12324 templates must be provided in the variable ExternalData_URL_TEM‐
12325 PLATES using the placeholders "%(algo)" and "%(hash)" in each
12326 template. Data fetch rules try each URL template in order by
12327 substituting the hash algorithm name for "%(algo)" and the hash
12328 value for "%(hash)".
12329 The following hash algorithms are supported:
12332 %(algo) <ext> Description
12335 ------- ----- -----------
12336 MD5 .md5 Message-Digest Algorithm 5, RFC 1321
12337 SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174
12338 SHA224 .sha224 US Secure Hash Algorithms, RFC 4634
12339 SHA256 .sha256 US Secure Hash Algorithms, RFC 4634
12340 SHA384 .sha384 US Secure Hash Algorithms, RFC 4634
12341 SHA512 .sha512 US Secure Hash Algorithms, RFC 4634
12342 Note that the hashes are used only for unique data identifica‐
12344 tion and download verification. This is not security software.
12345 Example usage:
12348 include(ExternalData)
12351 set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
12352 "http://data.org/%(algo)/%(hash)")
12353 ExternalData_Add_Test(MyData
12354 NAME MyTest
12355 COMMAND MyExe DATA{MyInput.png}
12356 )
12357 ExternalData_Add_Target(MyData)
12358 When test "MyTest" runs the "DATA{MyInput.png}" argument will be
12360 replaced by the full path to a real instance of the data file
12361 "MyInput.png" on disk. If the source tree contains a content
12362 link such as "MyInput.png.md5" then the "MyData" target creates
12363 a real "MyInput.png" in the build tree.
12364 The DATA{} syntax can be told to fetch a file series using the
12367 form "DATA{<name>,:}", where the ":" is literal. If the source
12368 tree contains a group of files or content links named like a
12369 series then a reference to one member adds rules to fetch all of
12370 them. Although all members of a series are fetched, only the
12371 file originally named by the DATA{} argument is substituted for
12372 it. The default configuration recognizes file series names end‐
12373 ing with "#.ext", "_#.ext", ".#.ext", or "-#.ext" where "#" is a
12374 sequence of decimal digits and ".ext" is any single extension.
12375 Configure it with a regex that parses <number> and <suffix>
12376 parts from the end of <name>:
12377 ExternalData_SERIES_PARSE = regex of the form (<number>)(<suffix>)$
12380 For more complicated cases set:
12382 ExternalData_SERIES_PARSE = regex with at least two () groups
12385 ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
12386 ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
12387 ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number
12388 Configure series number matching with a regex that matches the
12390 <number> part of series members named <prefix><number><suffix>:
12391 ExternalData_SERIES_MATCH = regex matching <number> in all series members
12394 Note that the <suffix> of a series does not include a hash-algo‐
12396 rithm extension.
12397 The DATA{} syntax can alternatively match files associated with
12400 the named file and contained in the same directory. Associated
12401 files may be specified by options using the syntax
12402 DATA{<name>,<opt1>,<opt2>,...}. Each option may specify one
12403 file by name or specify a regular expression to match file names
12404 using the syntax REGEX:<regex>. For example, the arguments
12405 DATA{MyData/MyInput.mhd,MyInput.img} # File pair
12408 DATA{MyData/MyFrames00.png,REGEX:MyFrames[0-9]+\\.png} # Series
12409 will pass MyInput.mha and MyFrames00.png on the command line but
12411 ensure that the associated files are present next to them.
12412 The DATA{} syntax may reference a directory using a trailing
12415 slash and a list of associated files. The form
12416 DATA{<name>/,<opt1>,<opt2>,...} adds rules to fetch any files in
12417 the directory that match one of the associated file options.
12418 For example, the argument DATA{MyDataDir/,REGEX:.*} will pass
12419 the full path to a MyDataDir directory on the command line and
12420 ensure that the directory contains files corresponding to every
12421 file or content link in the MyDataDir source directory.
12422 The variable ExternalData_LINK_CONTENT may be set to the name of
12425 a supported hash algorithm to enable automatic conversion of
12426 real data files referenced by the DATA{} syntax into content
12427 links. For each such <file> a content link named "<file><ext>"
12428 is created. The original file is renamed to the form ".Exter‐
12429 nalData_<algo>_<hash>" to stage it for future transmission to
12430 one of the locations in the list of URL templates (by means out‐
12431 side the scope of this module). The data fetch rule created for
12432 the content link will use the staged object if it cannot be
12433 found using any URL template.
12434 The variable ExternalData_OBJECT_STORES may be set to a list of
12437 local directories that store objects using the layout
12438 <dir>/%(algo)/%(hash). These directories will be searched first
12439 for a needed object. If the object is not available in any
12440 store then it will be fetched remotely using the URL templates
12441 and added to the first local store listed. If no stores are
12442 specified the default is a location inside the build tree.
12443 The variable ExternalData_SOURCE_ROOT may be set to the highest
12446 source directory containing any path named by a DATA{} refer‐
12447 ence. The default is CMAKE_SOURCE_DIR. External‐
12448 Data_SOURCE_ROOT and CMAKE_SOURCE_DIR must refer to directories
12449 within a single source distribution (e.g. they come together in
12450 one tarball).
12451 The variable ExternalData_BINARY_ROOT may be set to the direc‐
12454 tory to hold the real data files named by expanded DATA{} refer‐
12455 ences. The default is CMAKE_BINARY_DIR. The directory layout
12456 will mirror that of content links under External‐
12457 Data_SOURCE_ROOT.
12458 Variables ExternalData_TIMEOUT_INACTIVITY and ExternalData_TIME‐
12461 OUT_ABSOLUTE set the download inactivity and absolute timeouts,
12462 in seconds. The defaults are 60 seconds and 300 seconds,
12463 respectively. Set either timeout to 0 seconds to disable
12464 enforcement.
12465 ExternalProject
12468 Create custom targets to build projects in external trees
12469 The 'ExternalProject_Add' function creates a custom target to
12471 drive download, update/patch, configure, build, install and test
12472 steps of an external project:
12473 ExternalProject_Add(<name> # Name for custom target
12476 [DEPENDS projects...] # Targets on which the project depends
12477 [PREFIX dir] # Root dir for entire project
12478 [LIST_SEPARATOR sep] # Sep to be replaced by ; in cmd lines
12479 [TMP_DIR dir] # Directory to store temporary files
12480 [STAMP_DIR dir] # Directory to store step timestamps
12481 #--Download step--------------
12482 [DOWNLOAD_NAME fname] # File name to store (if not end of URL)
12483 [DOWNLOAD_DIR dir] # Directory to store downloaded files
12484 [DOWNLOAD_COMMAND cmd...] # Command to download source tree
12485 [CVS_REPOSITORY cvsroot] # CVSROOT of CVS repository
12486 [CVS_MODULE mod] # Module to checkout from CVS repo
12487 [CVS_TAG tag] # Tag to checkout from CVS repo
12488 [SVN_REPOSITORY url] # URL of Subversion repo
12489 [SVN_REVISION rev] # Revision to checkout from Subversion repo
12490 [SVN_USERNAME john ] # Username for Subversion checkout and update
12491 [SVN_PASSWORD doe ] # Password for Subversion checkout and update
12492 [SVN_TRUST_CERT 1 ] # Trust the Subversion server site certificate
12493 [GIT_REPOSITORY url] # URL of git repo
12494 [GIT_TAG tag] # Git branch name, commit id or tag
12495 [HG_REPOSITORY url] # URL of mercurial repo
12496 [HG_TAG tag] # Mercurial branch name, commit id or tag
12497 [URL /.../src.tgz] # Full path or URL of source
12498 [URL_HASH ALGO=value] # Hash of file at URL
12499 [URL_MD5 md5] # Equivalent to URL_HASH MD5=md5
12500 [TLS_VERIFY bool] # Should certificate for https be checked
12501 [TLS_CAINFO file] # Path to a certificate authority file
12502 [TIMEOUT seconds] # Time allowed for file download operations
12503 #--Update/Patch step----------
12504 [UPDATE_COMMAND cmd...] # Source work-tree update command
12505 [PATCH_COMMAND cmd...] # Command to patch downloaded source
12506 #--Configure step-------------
12507 [SOURCE_DIR dir] # Source dir to be used for build
12508 [CONFIGURE_COMMAND cmd...] # Build tree configuration command
12509 [CMAKE_COMMAND /.../cmake] # Specify alternative cmake executable
12510 [CMAKE_GENERATOR gen] # Specify generator for native build
12511 [CMAKE_GENERATOR_TOOLSET t] # Generator-specific toolset name
12512 [CMAKE_ARGS args...] # Arguments to CMake command line
12513 [CMAKE_CACHE_ARGS args...] # Initial cache arguments, of the form -Dvar:string=on
12514 #--Build step-----------------
12515 [BINARY_DIR dir] # Specify build dir location
12516 [BUILD_COMMAND cmd...] # Command to drive the native build
12517 [BUILD_IN_SOURCE 1] # Use source dir for build dir
12518 #--Install step---------------
12519 [INSTALL_DIR dir] # Installation prefix
12520 [INSTALL_COMMAND cmd...] # Command to drive install after build
12521 #--Test step------------------
12522 [TEST_BEFORE_INSTALL 1] # Add test step executed before install step
12523 [TEST_AFTER_INSTALL 1] # Add test step executed after install step
12524 [TEST_COMMAND cmd...] # Command to drive test
12525 #--Output logging-------------
12526 [LOG_DOWNLOAD 1] # Wrap download in script to log output
12527 [LOG_UPDATE 1] # Wrap update in script to log output
12528 [LOG_CONFIGURE 1] # Wrap configure in script to log output
12529 [LOG_BUILD 1] # Wrap build in script to log output
12530 [LOG_TEST 1] # Wrap test in script to log output
12531 [LOG_INSTALL 1] # Wrap install in script to log output
12532 #--Custom targets-------------
12533 [STEP_TARGETS st1 st2 ...] # Generate custom targets for these steps
12534 )
12535 The *_DIR options specify directories for the project, with
12537 default directories computed as follows. If the PREFIX option is
12538 given to ExternalProject_Add() or the EP_PREFIX directory prop‐
12539 erty is set, then an external project is built and installed
12540 under the specified prefix:
12541 TMP_DIR = <prefix>/tmp
12544 STAMP_DIR = <prefix>/src/<name>-stamp
12545 DOWNLOAD_DIR = <prefix>/src
12546 SOURCE_DIR = <prefix>/src/<name>
12547 BINARY_DIR = <prefix>/src/<name>-build
12548 INSTALL_DIR = <prefix>
12549 Otherwise, if the EP_BASE directory property is set then compo‐
12551 nents of an external project are stored under the specified
12552 base:
12553 TMP_DIR = <base>/tmp/<name>
12556 STAMP_DIR = <base>/Stamp/<name>
12557 DOWNLOAD_DIR = <base>/Download/<name>
12558 SOURCE_DIR = <base>/Source/<name>
12559 BINARY_DIR = <base>/Build/<name>
12560 INSTALL_DIR = <base>/Install/<name>
12561 If no PREFIX, EP_PREFIX, or EP_BASE is specified then the
12563 default is to set PREFIX to "<name>-prefix". Relative paths are
12564 interpreted with respect to the build directory corresponding to
12565 the source directory in which ExternalProject_Add is invoked.
12566 If SOURCE_DIR is explicitly set to an existing directory the
12569 project will be built from it. Otherwise a download step must be
12570 specified using one of the DOWNLOAD_COMMAND, CVS_*, SVN_*, or
12571 URL options. The URL option may refer locally to a directory or
12572 source tarball, or refer to a remote tarball (e.g.
12573 http://.../src.tgz).
12574 The 'ExternalProject_Add_Step' function adds a custom step to an
12577 external project:
12578 ExternalProject_Add_Step(<name> <step> # Names of project and custom step
12581 [COMMAND cmd...] # Command line invoked by this step
12582 [COMMENT "text..."] # Text printed when step executes
12583 [DEPENDEES steps...] # Steps on which this step depends
12584 [DEPENDERS steps...] # Steps that depend on this step
12585 [DEPENDS files...] # Files on which this step depends
12586 [ALWAYS 1] # No stamp file, step always runs
12587 [WORKING_DIRECTORY dir] # Working directory for command
12588 [LOG 1] # Wrap step in script to log output
12589 )
12590 The command line, comment, and working directory of every stan‐
12592 dard and custom step is processed to replace tokens
12593 <SOURCE_DIR>, <BINARY_DIR>, <INSTALL_DIR>, and <TMP_DIR> with
12594 corresponding property values.
12595 Any builtin step that specifies a "<step>_COMMAND cmd..." or
12598 custom step that specifies a "COMMAND cmd..." may specify addi‐
12599 tional command lines using the form "COMMAND cmd...". At build
12600 time the commands will be executed in order and aborted if any
12601 one fails. For example:
12602 ... BUILD_COMMAND make COMMAND echo done ...
12605 specifies to run "make" and then "echo done" during the build
12607 step. Whether the current working directory is preserved between
12608 commands is not defined. Behavior of shell operators like "&&"
12609 is not defined.
12610 The 'ExternalProject_Get_Property' function retrieves external
12613 project target properties:
12614 ExternalProject_Get_Property(<name> [prop1 [prop2 [...]]])
12617 It stores property values in variables of the same name. Prop‐
12619 erty names correspond to the keyword argument names of 'Exter‐
12620 nalProject_Add'.
12621 The 'ExternalProject_Add_StepTargets' function generates custom
12624 targets for the steps listed:
12625 ExternalProject_Add_StepTargets(<name> [step1 [step2 [...]]])
12628 If STEP_TARGETS is set then ExternalProject_Add_StepTargets is
12633 automatically called at the end of matching calls to External‐
12634 Project_Add_Step. Pass STEP_TARGETS explicitly to individual
12635 ExternalProject_Add calls, or implicitly to all ExternalPro‐
12636 ject_Add calls by setting the directory property EP_STEP_TAR‐
12637 GETS.
12638 If STEP_TARGETS is not set, clients may still manually call
12641 ExternalProject_Add_StepTargets after calling ExternalPro‐
12642 ject_Add or ExternalProject_Add_Step.
12643 This functionality is provided to make it easy to drive the
12646 steps independently of each other by specifying targets on build
12647 command lines. For example, you may be submitting to a
12648 sub-project based dashboard, where you want to drive the config‐
12649 ure portion of the build, then submit to the dashboard, followed
12650 by the build portion, followed by tests. If you invoke a custom
12651 target that depends on a step halfway through the step depen‐
12652 dency chain, then all the previous steps will also run to ensure
12653 everything is up to date.
12654 For example, to drive configure, build and test steps indepen‐
12657 dently for each ExternalProject_Add call in your project, write
12658 the following line prior to any ExternalProject_Add calls in
12659 your CMakeLists file:
12660 set_property(DIRECTORY PROPERTY EP_STEP_TARGETS configure build test)
12663 FeatureSummary
12666 Macros for generating a summary of enabled/disabled features
12667 This module provides the macros feature_summary(), set_pack‐
12672 age_properties() and add_feature_info(). For compatibility it
12673 also still provides set_package_info(), set_feature_info(),
12674 print_enabled_features() and print_disabled_features().
12675 These macros can be used to generate a summary of enabled and
12678 disabled packages and/or feature for a build tree:
12679 -- The following OPTIONAL packages have been found:
12682 LibXml2 (required version >= 2.4) , XML processing library. , <http://xmlsoft.org>
12683 * Enables HTML-import in MyWordProcessor
12684 * Enables odt-export in MyWordProcessor
12685 PNG , A PNG image library. , <http://www.libpng.org/pub/png/>
12686 * Enables saving screenshots
12687 -- The following OPTIONAL packages have not been found:
12688 Lua51 , The Lua scripting language. , <http://www.lua.org>
12689 * Enables macros in MyWordProcessor
12690 Foo , Foo provides cool stuff.
12691 FEATURE_SUMMARY( [FILENAME <file>]
12699 [APPEND]
12700 [VAR <variable_name>]
12701 [INCLUDE_QUIET_PACKAGES]
12702 [FATAL_ON_MISSING_REQUIRED_PACKAGES]
12703 [DESCRIPTION "Found packages:"]
12704 WHAT (ALL | PACKAGES_FOUND | PACKAGES_NOT_FOUND
12705 | ENABLED_FEATURES | DISABLED_FEATURES]
12706 )
12707 The FEATURE_SUMMARY() macro can be used to print information
12712 about enabled or disabled packages or features of a project. By
12713 default, only the names of the features/packages will be printed
12714 and their required version when one was specified. Use SET_PACK‐
12715 AGE_PROPERTIES() to add more useful information, like e.g. a
12716 download URL for the respective package or their purpose in the
12717 project.
12718 The WHAT option is the only mandatory option. Here you specify
12721 what information will be printed:
12722 ALL: print everything
12725 ENABLED_FEATURES: the list of all features which are enabled
12726 DISABLED_FEATURES: the list of all features which are disabled
12727 PACKAGES_FOUND: the list of all packages which have been found
12728 PACKAGES_NOT_FOUND: the list of all packages which have not been found
12729 OPTIONAL_PACKAGES_FOUND: only those packages which have been found which have the type OPTIONAL
12730 OPTIONAL_PACKAGES_NOT_FOUND: only those packages which have not been found which have the type OPTIONAL
12731 RECOMMENDED_PACKAGES_FOUND: only those packages which have been found which have the type RECOMMENDED
12732 RECOMMENDED_PACKAGES_NOT_FOUND: only those packages which have not been found which have the type RECOMMENDED
12733 REQUIRED_PACKAGES_FOUND: only those packages which have been found which have the type REQUIRED
12734 REQUIRED_PACKAGES_NOT_FOUND: only those packages which have not been found which have the type REQUIRED
12735 RUNTIME_PACKAGES_FOUND: only those packages which have been found which have the type RUNTIME
12736 RUNTIME_PACKAGES_NOT_FOUND: only those packages which have not been found which have the type RUNTIME
12737 If a FILENAME is given, the information is printed into this
12742 file. If APPEND is used, it is appended to this file, otherwise
12743 the file is overwritten if it already existed. If the VAR option
12744 is used, the information is "printed" into the specified vari‐
12745 able. If FILENAME is not used, the information is printed to the
12746 terminal. Using the DESCRIPTION option a description or headline
12747 can be set which will be printed above the actual content. If
12748 INCLUDE_QUIET_PACKAGES is given, packages which have been
12749 searched with find_package(... QUIET) will also be listed. By
12750 default they are skipped. If FATAL_ON_MISSING_REQUIRED_PACKAGES
12751 is given, CMake will abort if a package which is marked as
12752 REQUIRED has not been found.
12753 Example 1, append everything to a file:
12756 feature_summary(WHAT ALL
12759 FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
12760 Example 2, print the enabled features into the variable enabled‐
12765 FeaturesText, including QUIET packages:
12766 feature_summary(WHAT ENABLED_FEATURES
12769 INCLUDE_QUIET_PACKAGES
12770 DESCRIPTION "Enabled Features:"
12771 VAR enabledFeaturesText)
12772 message(STATUS "${enabledFeaturesText}")
12773 SET_PACKAGE_PROPERTIES(<name> PROPERTIES [ URL <url> ]
12781 [ DESCRIPTION <description> ]
12782 [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
12783 [ PURPOSE <purpose> ]
12784 )
12785 Use this macro to set up information about the named package,
12790 which can then be displayed via FEATURE_SUMMARY(). This can be
12791 done either directly in the Find-module or in the project which
12792 uses the module after the find_package() call. The features for
12793 which information can be set are added automatically by the
12794 find_package() command.
12795 URL: this should be the homepage of the package, or something
12798 similar. Ideally this is set already directly in the Find-mod‐
12799 ule.
12800 DESCRIPTION: A short description what that package is, at most
12803 one sentence. Ideally this is set already directly in the
12804 Find-module.
12805 TYPE: What type of dependency has the using project on that
12808 package. Default is OPTIONAL. In this case it is a package which
12809 can be used by the project when available at buildtime, but it
12810 also work without. RECOMMENDED is similar to OPTIONAL, i.e. the
12811 project will build if the package is not present, but the func‐
12812 tionality of the resulting binaries will be severly limited. If
12813 a REQUIRED package is not available at buildtime, the project
12814 may not even build. This can be combined with the FATAL_ON_MISS‐
12815 ING_REQUIRED_PACKAGES argument for feature_summary(). Last, a
12816 RUNTIME package is a package which is actually not used at all
12817 during the build, but which is required for actually running the
12818 resulting binaries. So if such a package is missing, the project
12819 can still be built, but it may not work later on. If set_pack‐
12820 age_properties() is called multiple times for the same package
12821 with different TYPEs, the TYPE is only changed to higher TYPEs (
12822 RUNTIME < OPTIONAL < RECOMMENDED < REQUIRED ), lower TYPEs are
12823 ignored. The TYPE property is project-specific, so it cannot be
12824 set by the Find-module, but must be set in the project.
12825 PURPOSE: This describes which features this package enables in
12828 the project, i.e. it tells the user what functionality he gets
12829 in the resulting binaries. If set_package_properties() is called
12830 multiple times for a package, all PURPOSE properties are
12831 appended to a list of purposes of the package in the project. As
12832 the TYPE property, also the PURPOSE property is project-spe‐
12833 cific, so it cannot be set by the Find-module, but must be set
12834 in the project.
12835 Example for setting the info for a package:
12841 find_package(LibXml2)
12844 set_package_properties(LibXml2 PROPERTIES DESCRIPTION "A XML processing library."
12845 URL "http://xmlsoft.org/")
12846 set_package_properties(LibXml2 PROPERTIES TYPE RECOMMENDED
12851 PURPOSE "Enables HTML-import in MyWordProcessor")
12852 ...
12853 set_package_properties(LibXml2 PROPERTIES TYPE OPTIONAL
12854 PURPOSE "Enables odt-export in MyWordProcessor")
12855 find_package(DBUS)
12860 set_package_properties(DBUS PROPERTIES TYPE RUNTIME
12861 PURPOSE "Necessary to disable the screensaver during a presentation" )
12862 ADD_FEATURE_INFO(<name> <enabled> <description>)
12867 Use this macro to add information about a feature with the given
12869 <name>. <enabled> contains whether this feature is enabled or
12870 not, <description> is a text describing the feature. The infor‐
12871 mation can be displayed using feature_summary() for ENABLED_FEA‐
12872 TURES and DISABLED_FEATURES respectively.
12873 Example for setting the info for a feature:
12876 option(WITH_FOO "Help for foo" ON)
12879 add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
12880 The following macros are provided for compatibility with previ‐
12888 ous CMake versions:
12889 SET_PACKAGE_INFO(<name> <description> [<url> [<purpose>] ] )
12892 Use this macro to set up information about the named package,
12894 which can then be displayed via FEATURE_SUMMARY(). This can be
12895 done either directly in the Find-module or in the project which
12896 uses the module after the find_package() call. The features for
12897 which information can be set are added automatically by the
12898 find_package() command.
12899 PRINT_ENABLED_FEATURES()
12902 Does the same as FEATURE_SUMMARY(WHAT ENABLED_FEATURES DESCRIP‐
12904 TION "Enabled features:")
12905 PRINT_DISABLED_FEATURES()
12908 Does the same as FEATURE_SUMMARY(WHAT DISABLED_FEATURES
12910 DESCRIPTION "Disabled features:")
12911 SET_FEATURE_INFO(<name> <description> [<url>] )
12914 Does the same as SET_PACKAGE_INFO(<name> <description> <url> )
12916 FindALSA
12919 Find alsa
12920 Find the alsa libraries (asound)
12922 This module defines the following variables:
12925 ALSA_FOUND - True if ALSA_INCLUDE_DIR & ALSA_LIBRARY are found
12926 ALSA_LIBRARIES - Set when ALSA_LIBRARY is found
12927 ALSA_INCLUDE_DIRS - Set when ALSA_INCLUDE_DIR is found
12928 ALSA_INCLUDE_DIR - where to find asoundlib.h, etc.
12933 ALSA_LIBRARY - the asound library
12934 ALSA_VERSION_STRING - the version of alsa found (since CMake 2.8.8)
12935 FindASPELL
12941 Try to find ASPELL
12942 Once done this will define
12944 ASPELL_FOUND - system has ASPELL
12947 ASPELL_EXECUTABLE - the ASPELL executable
12948 ASPELL_INCLUDE_DIR - the ASPELL include directory
12949 ASPELL_LIBRARIES - The libraries needed to use ASPELL
12950 ASPELL_DEFINITIONS - Compiler switches required for using ASPELL
12951 FindAVIFile
12954 Locate AVIFILE library and include paths
12955 AVIFILE (http://avifile.sourceforge.net/)is a set of libraries
12957 for i386 machines to use various AVI codecs. Support is limited
12958 beyond Linux. Windows provides native AVI support, and so
12959 doesn't need this library. This module defines
12960 AVIFILE_INCLUDE_DIR, where to find avifile.h , etc.
12963 AVIFILE_LIBRARIES, the libraries to link against
12964 AVIFILE_DEFINITIONS, definitions to use when compiling
12965 AVIFILE_FOUND, If false, don't try to use AVIFILE
12966 FindArmadillo
12969 Find Armadillo
12970 Find the Armadillo C++ library
12972 Using Armadillo:
12975 find_package(Armadillo REQUIRED)
12978 include_directories(${ARMADILLO_INCLUDE_DIRS})
12979 add_executable(foo foo.cc)
12980 target_link_libraries(foo ${ARMADILLO_LIBRARIES})
12981 This module sets the following variables:
12983 ARMADILLO_FOUND - set to true if the library is found
12986 ARMADILLO_INCLUDE_DIRS - list of required include directories
12987 ARMADILLO_LIBRARIES - list of libraries to be linked
12988 ARMADILLO_VERSION_MAJOR - major version number
12989 ARMADILLO_VERSION_MINOR - minor version number
12990 ARMADILLO_VERSION_PATCH - patch version number
12991 ARMADILLO_VERSION_STRING - version number as a string (ex: "1.0.4")
12992 ARMADILLO_VERSION_NAME - name of the version (ex: "Antipodean Antileech")
12993 FindBISON
12996 Find bison executable and provides macros to generate custom
12997 build rules
12998 The module defines the following variables:
13000 BISON_EXECUTABLE - path to the bison program
13003 BISON_VERSION - version of bison
13004 BISON_FOUND - true if the program was found
13005 The minimum required version of bison can be specified using the
13010 standard CMake syntax, e.g. find_package(BISON 2.1.3)
13011 If bison is found, the module defines the macros:
13014 BISON_TARGET(<Name> <YaccInput> <CodeOutput> [VERBOSE <file>]
13017 [COMPILE_FLAGS <string>])
13018 which will create a custom rule to generate a parser. <YaccIn‐
13020 put> is the path to a yacc file. <CodeOutput> is the name of
13021 the source file generated by bison. A header file is also be
13022 generated, and contains the token list. If COMPILE_FLAGS
13023 option is specified, the next parameter is added in the
13024 bison command line. if VERBOSE option is specified, <file> is
13025 created and contains verbose descriptions of the grammar and
13026 parser. The macro defines a set of variables:
13027 BISON_${Name}_DEFINED - true is the macro ran successfully
13030 BISON_${Name}_INPUT - The input source file, an alias for <YaccInput>
13031 BISON_${Name}_OUTPUT_SOURCE - The source file generated by bison
13032 BISON_${Name}_OUTPUT_HEADER - The header file generated by bison
13033 BISON_${Name}_OUTPUTS - The sources files generated by bison
13034 BISON_${Name}_COMPILE_FLAGS - Options used in the bison command line
13035 ====================================================================
13040 Example:
13041 find_package(BISON)
13046 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
13047 add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
13048 ====================================================================
13049 FindBLAS
13052 Find BLAS library
13053 This module finds an installed fortran library that implements
13055 the BLAS linear-algebra interface (see
13056 http://www.netlib.org/blas/). The list of libraries searched for
13057 is taken from the autoconf macro file, acx_blas.m4 (distributed
13058 at http://ac-archive.sourceforge.net/ac-archive/acx_blas.html).
13059 This module sets the following variables:
13062 BLAS_FOUND - set to true if a library implementing the BLAS interface
13065 is found
13066 BLAS_LINKER_FLAGS - uncached list of required linker flags (excluding -l
13067 and -L).
13068 BLAS_LIBRARIES - uncached list of libraries (using full path name) to
13069 link against to use BLAS
13070 BLAS95_LIBRARIES - uncached list of libraries (using full path name)
13071 to link against to use BLAS95 interface
13072 BLAS95_FOUND - set to true if a library implementing the BLAS f95 interface
13073 is found
13074 BLA_STATIC if set on this determines what kind of linkage we do (static)
13075 BLA_VENDOR if set checks only the specified vendor, if not set checks
13076 all the possibilities
13077 BLA_F95 if set on tries to find the f95 interfaces for BLAS/LAPACK
13078 C/CXX should be enabled to use Intel mkl
13080 FindBZip2
13083 Try to find BZip2
13084 Once done this will define
13086 BZIP2_FOUND - system has BZip2
13089 BZIP2_INCLUDE_DIR - the BZip2 include directory
13090 BZIP2_LIBRARIES - Link these to use BZip2
13091 BZIP2_NEED_PREFIX - this is set if the functions are prefixed with BZ2_
13092 BZIP2_VERSION_STRING - the version of BZip2 found (since CMake 2.8.8)
13093 FindBoost
13096 Find Boost include dirs and libraries
13097 Use this module by invoking find_package with the form:
13099 find_package(Boost
13102 [version] [EXACT] # Minimum or EXACT version e.g. 1.36.0
13103 [REQUIRED] # Fail with error if Boost is not found
13104 [COMPONENTS <libs>...] # Boost libraries by their canonical name
13105 ) # e.g. "date_time" for "libboost_date_time"
13106 This module finds headers and requested component libraries OR a
13108 CMake package configuration file provided by a "Boost CMake"
13109 build. For the latter case skip to the "Boost CMake" section
13110 below. For the former case results are reported in variables:
13111 Boost_FOUND - True if headers and requested libraries were found
13114 Boost_INCLUDE_DIRS - Boost include directories
13115 Boost_LIBRARY_DIRS - Link directories for Boost libraries
13116 Boost_LIBRARIES - Boost component libraries to be linked
13117 Boost_<C>_FOUND - True if component <C> was found (<C> is upper-case)
13118 Boost_<C>_LIBRARY - Libraries to link for component <C> (may include
13119 target_link_libraries debug/optimized keywords)
13120 Boost_VERSION - BOOST_VERSION value from boost/version.hpp
13121 Boost_LIB_VERSION - Version string appended to library filenames
13122 Boost_MAJOR_VERSION - Boost major version number (X in X.y.z)
13123 Boost_MINOR_VERSION - Boost minor version number (Y in x.Y.z)
13124 Boost_SUBMINOR_VERSION - Boost subminor version number (Z in x.y.Z)
13125 Boost_LIB_DIAGNOSTIC_DEFINITIONS (Windows)
13126 - Pass to add_definitions() to have diagnostic
13127 information about Boost's automatic linking
13128 displayed during compilation
13129 This module reads hints about search locations from variables:
13134 BOOST_ROOT - Preferred installation prefix
13137 (or BOOSTROOT)
13138 BOOST_INCLUDEDIR - Preferred include directory e.g. <prefix>/include
13139 BOOST_LIBRARYDIR - Preferred library directory e.g. <prefix>/lib
13140 Boost_NO_SYSTEM_PATHS - Set to ON to disable searching in locations not
13141 specified by these hint variables. Default is OFF.
13142 Boost_ADDITIONAL_VERSIONS
13143 - List of Boost versions not known to this module
13144 (Boost install locations may contain the version)
13145 and saves search results persistently in CMake cache entries:
13147 Boost_INCLUDE_DIR - Directory containing Boost headers
13150 Boost_LIBRARY_DIR - Directory containing Boost libraries
13151 Boost_<C>_LIBRARY_DEBUG - Component <C> library debug variant
13152 Boost_<C>_LIBRARY_RELEASE - Component <C> library release variant
13153 Users may set these hints or results as cache entries. Projects
13155 should not read these entries directly but instead use the above
13156 result variables. Note that some hint names start in upper-case
13157 "BOOST". One may specify these as environment variables if they
13158 are not specified as CMake variables or cache entries.
13159 This module first searches for the Boost header files using the
13162 above hint variables (excluding BOOST_LIBRARYDIR) and saves the
13163 result in Boost_INCLUDE_DIR. Then it searches for requested
13164 component libraries using the above hints (excluding
13165 BOOST_INCLUDEDIR and Boost_ADDITIONAL_VERSIONS), "lib" directo‐
13166 ries near Boost_INCLUDE_DIR, and the library name configuration
13167 settings below. It saves the library directory in
13168 Boost_LIBRARY_DIR and individual library locations in
13169 Boost_<C>_LIBRARY_DEBUG and Boost_<C>_LIBRARY_RELEASE. When one
13170 changes settings used by previous searches in the same build
13171 tree (excluding environment variables) this module discards pre‐
13172 vious search results affected by the changes and searches again.
13173 Boost libraries come in many variants encoded in their file
13176 name. Users or projects may tell this module which variant to
13177 find by setting variables:
13178 Boost_USE_MULTITHREADED - Set to OFF to use the non-multithreaded
13181 libraries ('mt' tag). Default is ON.
13182 Boost_USE_STATIC_LIBS - Set to ON to force the use of the static
13183 libraries. Default is OFF.
13184 Boost_USE_STATIC_RUNTIME - Set to ON or OFF to specify whether to use
13185 libraries linked statically to the C++ runtime
13186 ('s' tag). Default is platform dependent.
13187 Boost_USE_DEBUG_PYTHON - Set to ON to use libraries compiled with a
13188 debug Python build ('y' tag). Default is OFF.
13189 Boost_USE_STLPORT - Set to ON to use libraries compiled with
13190 STLPort ('p' tag). Default is OFF.
13191 Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
13192 - Set to ON to use libraries compiled with
13193 STLPort deprecated "native iostreams"
13194 ('n' tag). Default is OFF.
13195 Boost_COMPILER - Set to the compiler-specific library suffix
13196 (e.g. "-gcc43"). Default is auto-computed
13197 for the C++ compiler in use.
13198 Boost_THREADAPI - Suffix for "thread" component library name,
13199 such as "pthread" or "win32". Names with
13200 and without this suffix will both be tried.
13201 Other variables one may set to control this module are:
13203 Boost_DEBUG - Set to ON to enable debug output from FindBoost.
13206 Please enable this before filing any bug report.
13207 Boost_DETAILED_FAILURE_MSG
13208 - Set to ON to add detailed information to the
13209 failure message even when the REQUIRED option
13210 is not given to the find_package call.
13211 Boost_REALPATH - Set to ON to resolve symlinks for discovered
13212 libraries to assist with packaging. For example,
13213 the "system" component library may be resolved to
13214 "/usr/lib/libboost_system.so.1.42.0" instead of
13215 "/usr/lib/libboost_system.so". This does not
13216 affect linking and should not be enabled unless
13217 the user needs this information.
13218 On Visual Studio and Borland compilers Boost headers request
13220 automatic linking to corresponding libraries. This requires
13221 matching libraries to be linked explicitly or available in the
13222 link library search path. In this case setting
13223 Boost_USE_STATIC_LIBS to OFF may not achieve dynamic linking.
13224 Boost automatic linking typically requests static libraries with
13225 a few exceptions (such as Boost.Python). Use
13226 add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})
13229 to ask Boost to report information about automatic linking
13231 requests.
13232 Example to find Boost headers only:
13235 find_package(Boost 1.36.0)
13238 if(Boost_FOUND)
13239 include_directories(${Boost_INCLUDE_DIRS})
13240 add_executable(foo foo.cc)
13241 endif()
13242 Example to find Boost headers and some libraries:
13244 set(Boost_USE_STATIC_LIBS ON)
13247 set(Boost_USE_MULTITHREADED ON)
13248 set(Boost_USE_STATIC_RUNTIME OFF)
13249 find_package(Boost 1.36.0 COMPONENTS date_time filesystem system ...)
13250 if(Boost_FOUND)
13251 include_directories(${Boost_INCLUDE_DIRS})
13252 add_executable(foo foo.cc)
13253 target_link_libraries(foo ${Boost_LIBRARIES})
13254 endif()
13255 Boost CMake
13260 ----------------------------------------------------------
13261 If Boost was built using the boost-cmake project it provides a
13264 package configuration file for use with find_package's Config
13265 mode. This module looks for the package configuration file
13266 called BoostConfig.cmake or boost-config.cmake and stores the
13267 result in cache entry "Boost_DIR". If found, the package con‐
13268 figuration file is loaded and this module returns with no fur‐
13269 ther action. See documentation of the Boost CMake package con‐
13270 figuration for details on what it provides.
13271 Set Boost_NO_BOOST_CMAKE to ON to disable the search for
13274 boost-cmake.
13275 FindBullet
13278 Try to find the Bullet physics engine
13279 This module defines the following variables
13284 BULLET_FOUND - Was bullet found
13289 BULLET_INCLUDE_DIRS - the Bullet include directories
13290 BULLET_LIBRARIES - Link to this, by default it includes
13291 all bullet components (Dynamics,
13292 Collision, LinearMath, & SoftBody)
13293 This module accepts the following variables
13298 BULLET_ROOT - Can be set to bullet install path or Windows build path
13303 FindCABLE
13309 Find CABLE
13310 This module finds if CABLE is installed and determines where the
13312 include files and libraries are. This code sets the following
13313 variables:
13314 CABLE the path to the cable executable
13317 CABLE_TCL_LIBRARY the path to the Tcl wrapper library
13318 CABLE_INCLUDE_DIR the path to the include directory
13319 To build Tcl wrappers, you should add shared library and link it
13324 to ${CABLE_TCL_LIBRARY}. You should also add
13325 ${CABLE_INCLUDE_DIR} as an include directory.
13326 FindCUDA
13329 Tools for building CUDA C files: libraries and build dependen‐
13330 cies.
13331 This script locates the NVIDIA CUDA C tools. It should work on
13333 linux, windows, and mac and should be reasonably up to date with
13334 CUDA C releases.
13335 This script makes use of the standard find_package arguments of
13338 <VERSION>, REQUIRED and QUIET. CUDA_FOUND will report if an
13339 acceptable version of CUDA was found.
13340 The script will prompt the user to specify CUDA_TOOLKIT_ROOT_DIR
13343 if the prefix cannot be determined by the location of nvcc in
13344 the system path and REQUIRED is specified to find_package(). To
13345 use a different installed version of the toolkit set the envi‐
13346 ronment variable CUDA_BIN_PATH before running cmake (e.g.
13347 CUDA_BIN_PATH=/usr/local/cuda1.0 instead of the default
13348 /usr/local/cuda) or set CUDA_TOOLKIT_ROOT_DIR after configuring.
13349 If you change the value of CUDA_TOOLKIT_ROOT_DIR, various compo‐
13350 nents that depend on the path will be relocated.
13351 It might be necessary to set CUDA_TOOLKIT_ROOT_DIR manually on
13354 certain platforms, or to use a cuda runtime not installed in the
13355 default location. In newer versions of the toolkit the cuda
13356 library is included with the graphics driver- be sure that the
13357 driver version matches what is needed by the cuda runtime ver‐
13358 sion.
13359 The following variables affect the behavior of the macros in the
13362 script (in alphebetical order). Note that any of these flags
13363 can be changed multiple times in the same directory before call‐
13364 ing CUDA_ADD_EXECUTABLE, CUDA_ADD_LIBRARY, CUDA_COMPILE,
13365 CUDA_COMPILE_PTX or CUDA_WRAP_SRCS.
13366 CUDA_64_BIT_DEVICE_CODE (Default matches host bit size)
13369 -- Set to ON to compile for 64 bit device code, OFF for 32 bit device code.
13370 Note that making this different from the host code when generating object
13371 or C files from CUDA code just won't work, because size_t gets defined by
13372 nvcc in the generated source. If you compile to PTX and then load the
13373 file yourself, you can mix bit sizes between device and host.
13374 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE (Default ON)
13379 -- Set to ON if you want the custom build rule to be attached to the source
13380 file in Visual Studio. Turn OFF if you add the same cuda file to multiple
13381 targets.
13382 This allows the user to build the target from the CUDA file; however, bad
13387 things can happen if the CUDA source file is added to multiple targets.
13388 When performing parallel builds it is possible for the custom build
13389 command to be run more than once and in parallel causing cryptic build
13390 errors. VS runs the rules for every source file in the target, and a
13391 source can have only one rule no matter how many projects it is added to.
13392 When the rule is run from multiple targets race conditions can occur on
13393 the generated file. Eventually everything will get built, but if the user
13394 is unaware of this behavior, there may be confusion. It would be nice if
13395 this script could detect the reuse of source files across multiple targets
13396 and turn the option off for the user, but no good solution could be found.
13397 CUDA_BUILD_CUBIN (Default OFF)
13402 -- Set to ON to enable and extra compilation pass with the -cubin option in
13403 Device mode. The output is parsed and register, shared memory usage is
13404 printed during build.
13405 CUDA_BUILD_EMULATION (Default OFF for device mode)
13410 -- Set to ON for Emulation mode. -D_DEVICEEMU is defined for CUDA C files
13411 when CUDA_BUILD_EMULATION is TRUE.
13412 CUDA_GENERATED_OUTPUT_DIR (Default CMAKE_CURRENT_BINARY_DIR)
13417 -- Set to the path you wish to have the generated files placed. If it is
13418 blank output files will be placed in CMAKE_CURRENT_BINARY_DIR.
13419 Intermediate files will always be placed in
13420 CMAKE_CURRENT_BINARY_DIR/CMakeFiles.
13421 CUDA_HOST_COMPILATION_CPP (Default ON)
13426 -- Set to OFF for C compilation of host code.
13427 CUDA_HOST_COMPILER (Default CMAKE_C_COMPILER, $(VCInstallDir)/bin for VS)
13432 -- Set the host compiler to be used by nvcc. Ignored if -ccbin or
13433 --compiler-bindir is already present in the CUDA_NVCC_FLAGS or
13434 CUDA_NVCC_FLAGS_<CONFIG> variables. For Visual Studio targets
13435 $(VCInstallDir)/bin is a special value that expands out to the path when
13436 the command is run from withing VS.
13437 CUDA_NVCC_FLAGS
13442 CUDA_NVCC_FLAGS_<CONFIG>
13443 -- Additional NVCC command line arguments. NOTE: multiple arguments must be
13444 semi-colon delimited (e.g. --compiler-options;-Wall)
13445 CUDA_PROPAGATE_HOST_FLAGS (Default ON)
13450 -- Set to ON to propagate CMAKE_{C,CXX}_FLAGS and their configuration
13451 dependent counterparts (e.g. CMAKE_C_FLAGS_DEBUG) automatically to the
13452 host compiler through nvcc's -Xcompiler flag. This helps make the
13453 generated host code match the rest of the system better. Sometimes
13454 certain flags give nvcc problems, and this will help you turn the flag
13455 propagation off. This does not affect the flags supplied directly to nvcc
13456 via CUDA_NVCC_FLAGS or through the OPTION flags specified through
13457 CUDA_ADD_LIBRARY, CUDA_ADD_EXECUTABLE, or CUDA_WRAP_SRCS. Flags used for
13458 shared library compilation are not affected by this flag.
13459 CUDA_SEPARABLE_COMPILATION (Default OFF)
13464 -- If set this will enable separable compilation for all CUDA runtime object
13465 files. If used outside of CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY
13466 (e.g. calling CUDA_WRAP_SRCS directly),
13467 CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME and
13468 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS should be called.
13469 CUDA_VERBOSE_BUILD (Default OFF)
13474 -- Set to ON to see all the commands used when building the CUDA file. When
13475 using a Makefile generator the value defaults to VERBOSE (run make
13476 VERBOSE=1 to see output), although setting CUDA_VERBOSE_BUILD to ON will
13477 always print the output.
13478 The script creates the following macros (in alphebetical order):
13483 CUDA_ADD_CUFFT_TO_TARGET( cuda_target )
13486 -- Adds the cufft library to the target (can be any target). Handles whether
13487 you are in emulation mode or not.
13488 CUDA_ADD_CUBLAS_TO_TARGET( cuda_target )
13493 -- Adds the cublas library to the target (can be any target). Handles
13494 whether you are in emulation mode or not.
13495 CUDA_ADD_EXECUTABLE( cuda_target file0 file1 ...
13500 [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
13501 -- Creates an executable "cuda_target" which is made up of the files
13502 specified. All of the non CUDA C files are compiled using the standard
13503 build rules specified by CMAKE and the cuda files are compiled to object
13504 files using nvcc and the host compiler. In addition CUDA_INCLUDE_DIRS is
13505 added automatically to include_directories(). Some standard CMake target
13506 calls can be used on the target after calling this macro
13507 (e.g. set_target_properties and target_link_libraries), but setting
13508 properties that adjust compilation flags will not affect code compiled by
13509 nvcc. Such flags should be modified before calling CUDA_ADD_EXECUTABLE,
13510 CUDA_ADD_LIBRARY or CUDA_WRAP_SRCS.
13511 CUDA_ADD_LIBRARY( cuda_target file0 file1 ...
13516 [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [OPTIONS ...] )
13517 -- Same as CUDA_ADD_EXECUTABLE except that a library is created.
13518 CUDA_BUILD_CLEAN_TARGET()
13523 -- Creates a convience target that deletes all the dependency files
13524 generated. You should make clean after running this target to ensure the
13525 dependency files get regenerated.
13526 CUDA_COMPILE( generated_files file0 file1 ... [STATIC | SHARED | MODULE]
13531 [OPTIONS ...] )
13532 -- Returns a list of generated files from the input source files to be used
13533 with ADD_LIBRARY or ADD_EXECUTABLE.
13534 CUDA_COMPILE_PTX( generated_files file0 file1 ... [OPTIONS ...] )
13539 -- Returns a list of PTX files generated from the input source files.
13540 CUDA_COMPUTE_SEPARABLE_COMPILATION_OBJECT_FILE_NAME( output_file_var
13545 cuda_target
13546 object_files )
13547 -- Compute the name of the intermediate link file used for separable
13548 compilation. This file name is typically passed into
13549 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS. output_file_var is produced
13550 based on cuda_target the list of objects files that need separable
13551 compilation as specified by object_files. If the object_files list is
13552 empty, then output_file_var will be empty. This function is called
13553 automatically for CUDA_ADD_LIBRARY and CUDA_ADD_EXECUTABLE. Note that
13554 this is a function and not a macro.
13555 CUDA_INCLUDE_DIRECTORIES( path0 path1 ... )
13560 -- Sets the directories that should be passed to nvcc
13561 (e.g. nvcc -Ipath0 -Ipath1 ... ). These paths usually contain other .cu
13562 files.
13563 CUDA_LINK_SEPARABLE_COMPILATION_OBJECTS( output_file_var cuda_target
13571 nvcc_flags object_files)
13572 -- Generates the link object required by separable compilation from the given
13577 object files. This is called automatically for CUDA_ADD_EXECUTABLE and
13578 CUDA_ADD_LIBRARY, but can be called manually when using CUDA_WRAP_SRCS
13579 directly. When called from CUDA_ADD_LIBRARY or CUDA_ADD_EXECUTABLE the
13580 nvcc_flags passed in are the same as the flags passed in via the OPTIONS
13581 argument. The only nvcc flag added automatically is the bitness flag as
13582 specified by CUDA_64_BIT_DEVICE_CODE. Note that this is a function
13583 instead of a macro.
13584 CUDA_WRAP_SRCS ( cuda_target format generated_files file0 file1 ...
13589 [STATIC | SHARED | MODULE] [OPTIONS ...] )
13590 -- This is where all the magic happens. CUDA_ADD_EXECUTABLE,
13591 CUDA_ADD_LIBRARY, CUDA_COMPILE, and CUDA_COMPILE_PTX all call this
13592 function under the hood.
13593 Given the list of files (file0 file1 ... fileN) this macro generates
13598 custom commands that generate either PTX or linkable objects (use "PTX" or
13599 "OBJ" for the format argument to switch). Files that don't end with .cu
13600 or have the HEADER_FILE_ONLY property are ignored.
13601 The arguments passed in after OPTIONS are extra command line options to
13606 give to nvcc. You can also specify per configuration options by
13607 specifying the name of the configuration followed by the options. General
13608 options must preceed configuration specific options. Not all
13609 configurations need to be specified, only the ones provided will be used.
13610 OPTIONS -DFLAG=2 "-DFLAG_OTHER=space in flag"
13615 DEBUG -g
13616 RELEASE --use_fast_math
13617 RELWITHDEBINFO --use_fast_math;-g
13618 MINSIZEREL --use_fast_math
13619 For certain configurations (namely VS generating object files with
13624 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE set to ON), no generated file will
13625 be produced for the given cuda file. This is because when you add the
13626 cuda file to Visual Studio it knows that this file produces an object file
13627 and will link in the resulting object file automatically.
13628 This script will also generate a separate cmake script that is used at
13633 build time to invoke nvcc. This is for several reasons.
13634 1. nvcc can return negative numbers as return values which confuses
13639 Visual Studio into thinking that the command succeeded. The script now
13640 checks the error codes and produces errors when there was a problem.
13641 2. nvcc has been known to not delete incomplete results when it
13646 encounters problems. This confuses build systems into thinking the
13647 target was generated when in fact an unusable file exists. The script
13648 now deletes the output files if there was an error.
13649 3. By putting all the options that affect the build into a file and then
13654 make the build rule dependent on the file, the output files will be
13655 regenerated when the options change.
13656 This script also looks at optional arguments STATIC, SHARED, or MODULE to
13661 determine when to target the object compilation for a shared library.
13662 BUILD_SHARED_LIBS is ignored in CUDA_WRAP_SRCS, but it is respected in
13663 CUDA_ADD_LIBRARY. On some systems special flags are added for building
13664 objects intended for shared libraries. A preprocessor macro,
13665 <target_name>_EXPORTS is defined when a shared library compilation is
13666 detected.
13667 Flags passed into add_definitions with -D or /D are passed along to nvcc.
13672 The script defines the following variables:
13677 CUDA_VERSION_MAJOR -- The major version of cuda as reported by nvcc.
13680 CUDA_VERSION_MINOR -- The minor version.
13681 CUDA_VERSION
13682 CUDA_VERSION_STRING -- CUDA_VERSION_MAJOR.CUDA_VERSION_MINOR
13683 CUDA_TOOLKIT_ROOT_DIR -- Path to the CUDA Toolkit (defined if not set).
13688 CUDA_SDK_ROOT_DIR -- Path to the CUDA SDK. Use this to find files in the
13689 SDK. This script will not directly support finding
13690 specific libraries or headers, as that isn't
13691 supported by NVIDIA. If you want to change
13692 libraries when the path changes see the
13693 FindCUDA.cmake script for an example of how to clear
13694 these variables. There are also examples of how to
13695 use the CUDA_SDK_ROOT_DIR to locate headers or
13696 libraries, if you so choose (at your own risk).
13697 CUDA_INCLUDE_DIRS -- Include directory for cuda headers. Added automatically
13698 for CUDA_ADD_EXECUTABLE and CUDA_ADD_LIBRARY.
13699 CUDA_LIBRARIES -- Cuda RT library.
13700 CUDA_CUFFT_LIBRARIES -- Device or emulation library for the Cuda FFT
13701 implementation (alternative to:
13702 CUDA_ADD_CUFFT_TO_TARGET macro)
13703 CUDA_CUBLAS_LIBRARIES -- Device or emulation library for the Cuda BLAS
13704 implementation (alterative to:
13705 CUDA_ADD_CUBLAS_TO_TARGET macro).
13706 CUDA_cupti_LIBRARY -- CUDA Profiling Tools Interface library.
13707 Only available for CUDA version 4.0+.
13708 CUDA_curand_LIBRARY -- CUDA Random Number Generation library.
13709 Only available for CUDA version 3.2+.
13710 CUDA_cusparse_LIBRARY -- CUDA Sparse Matrix library.
13711 Only available for CUDA version 3.2+.
13712 CUDA_npp_LIBRARY -- NVIDIA Performance Primitives library.
13713 Only available for CUDA version 4.0+.
13714 CUDA_nppc_LIBRARY -- NVIDIA Performance Primitives library (core).
13715 Only available for CUDA version 5.5+.
13716 CUDA_nppi_LIBRARY -- NVIDIA Performance Primitives library (image processing).
13717 Only available for CUDA version 5.5+.
13718 CUDA_npps_LIBRARY -- NVIDIA Performance Primitives library (signal processing).
13719 Only available for CUDA version 5.5+.
13720 CUDA_nvcuvenc_LIBRARY -- CUDA Video Encoder library.
13721 Only available for CUDA version 3.2+.
13722 Windows only.
13723 CUDA_nvcuvid_LIBRARY -- CUDA Video Decoder library.
13724 Only available for CUDA version 3.2+.
13725 Windows only.
13726 James Bigler, NVIDIA Corp (nvidia.com - jbigler)
13734 Abe Stephens, SCI Institute -- http://www.sci.utah.edu/~abe/FindCuda.html
13735 Copyright (c) 2008 - 2009 NVIDIA Corporation. All rights reserved.
13740 Copyright (c) 2007-2009
13745 Scientific Computing and Imaging Institute, University of Utah
13746 This code is licensed under the MIT License. See the FindCUDA.cmake script
13751 for the text of the license.
13752 FindCURL
13755 Find curl
13756 Find the native CURL headers and libraries.
13758 CURL_INCLUDE_DIRS - where to find curl/curl.h, etc.
13761 CURL_LIBRARIES - List of libraries when using curl.
13762 CURL_FOUND - True if curl found.
13763 CURL_VERSION_STRING - the version of curl found (since CMake 2.8.8)
13764 FindCVS
13767 The module defines the following variables:
13770 CVS_EXECUTABLE - path to cvs command line client
13773 CVS_FOUND - true if the command line client was found
13774 Example usage:
13776 find_package(CVS)
13779 if(CVS_FOUND)
13780 message("CVS found: ${CVS_EXECUTABLE}")
13781 endif()
13782 FindCoin3D
13785 Find Coin3D (Open Inventor)
13786 Coin3D is an implementation of the Open Inventor API. It pro‐
13788 vides data structures and algorithms for 3D visualization
13789 http://www.coin3d.org/
13790 This module defines the following variables
13793 COIN3D_FOUND - system has Coin3D - Open Inventor
13796 COIN3D_INCLUDE_DIRS - where the Inventor include directory can be found
13797 COIN3D_LIBRARIES - Link to this to use Coin3D
13798 FindCups
13804 Try to find the Cups printing system
13805 Once done this will define
13807 CUPS_FOUND - system has Cups
13810 CUPS_INCLUDE_DIR - the Cups include directory
13811 CUPS_LIBRARIES - Libraries needed to use Cups
13812 CUPS_VERSION_STRING - version of Cups found (since CMake 2.8.8)
13813 Set CUPS_REQUIRE_IPP_DELETE_ATTRIBUTE to TRUE if you need a version which
13814 features this function (i.e. at least 1.1.19)
13815 FindCurses
13818 Find the curses include file and library
13819 CURSES_FOUND - system has Curses
13824 CURSES_INCLUDE_DIR - the Curses include directory
13825 CURSES_LIBRARIES - The libraries needed to use Curses
13826 CURSES_HAVE_CURSES_H - true if curses.h is available
13827 CURSES_HAVE_NCURSES_H - true if ncurses.h is available
13828 CURSES_HAVE_NCURSES_NCURSES_H - true if ncurses/ncurses.h is available
13829 CURSES_HAVE_NCURSES_CURSES_H - true if ncurses/curses.h is available
13830 CURSES_LIBRARY - set for backwards compatibility with 2.4 CMake
13831 Set CURSES_NEED_NCURSES to TRUE before the find_package() com‐
13836 mand if NCurses functionality is required.
13837 FindCxxTest
13840 Find CxxTest
13841 Find the CxxTest suite and declare a helper macro for creating
13843 unit tests and integrating them with CTest. For more details on
13844 CxxTest see http://cxxtest.tigris.org
13845 INPUT Variables
13848 CXXTEST_USE_PYTHON [deprecated since 1.3]
13851 Only used in the case both Python & Perl
13852 are detected on the system to control
13853 which CxxTest code generator is used.
13854 Valid only for CxxTest version 3.
13855 NOTE: In older versions of this Find Module,
13860 this variable controlled if the Python test
13861 generator was used instead of the Perl one,
13862 regardless of which scripting language the
13863 user had installed.
13864 CXXTEST_TESTGEN_ARGS (since CMake 2.8.3)
13869 Specify a list of options to pass to the CxxTest code
13870 generator. If not defined, --error-printer is
13871 passed.
13872 OUTPUT Variables
13877 CXXTEST_FOUND
13880 True if the CxxTest framework was found
13881 CXXTEST_INCLUDE_DIRS
13882 Where to find the CxxTest include directory
13883 CXXTEST_PERL_TESTGEN_EXECUTABLE
13884 The perl-based test generator
13885 CXXTEST_PYTHON_TESTGEN_EXECUTABLE
13886 The python-based test generator
13887 CXXTEST_TESTGEN_EXECUTABLE (since CMake 2.8.3)
13888 The test generator that is actually used (chosen using user preferences
13889 and interpreters found in the system)
13890 CXXTEST_TESTGEN_INTERPRETER (since CMake 2.8.3)
13891 The full path to the Perl or Python executable on the system
13892 MACROS for optional use by CMake users:
13897 CXXTEST_ADD_TEST(<test_name> <gen_source_file> <input_files_to_testgen...>)
13900 Creates a CxxTest runner and adds it to the CTest testing suite
13901 Parameters:
13902 test_name The name of the test
13903 gen_source_file The generated source filename to be
13904 generated by CxxTest
13905 input_files_to_testgen The list of header files containing the
13906 CxxTest::TestSuite's to be included in
13907 this runner
13908 #==============
13913 Example Usage:
13914 find_package(CxxTest)
13919 if(CXXTEST_FOUND)
13920 include_directories(${CXXTEST_INCLUDE_DIR})
13921 enable_testing()
13922 CXXTEST_ADD_TEST(unittest_foo foo_test.cc
13927 ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h)
13928 target_link_libraries(unittest_foo foo) # as needed
13929 endif()
13930 This will (if CxxTest is found):
13935 1. Invoke the testgen executable to autogenerate foo_test.cc in the
13936 binary tree from "foo_test.h" in the current source directory.
13937 2. Create an executable and test called unittest_foo.
13938 #=============
13943 Example foo_test.h:
13944 #include <cxxtest/TestSuite.h>
13949 class MyTestSuite : public CxxTest::TestSuite
13954 {
13955 public:
13956 void testAddition( void )
13957 {
13958 TS_ASSERT( 1 + 1 > 1 );
13959 TS_ASSERT_EQUALS( 1 + 1, 2 );
13960 }
13961 };
13962 FindCygwin
13968 this module looks for Cygwin
13969 FindDCMTK
13975 find DCMTK libraries and applications
13976 FindDart
13982 Find DART
13983 This module looks for the dart testing software and sets
13985 DART_ROOT to point to where it found it.
13986 FindDevIL
13990 This module locates the developer's image library. http://ope‐
13993 nil.sourceforge.net/
13994 This module sets:
13997 IL_LIBRARIES - the name of the IL library. These include the full path to
14000 the core DevIL library. This one has to be linked into the
14001 application.
14002 ILU_LIBRARIES - the name of the ILU library. Again, the full path. This
14003 library is for filters and effects, not actual loading. It
14004 doesn't have to be linked if the functionality it provides
14005 is not used.
14006 ILUT_LIBRARIES - the name of the ILUT library. Full path. This part of the
14007 library interfaces with OpenGL. It is not strictly needed
14008 in applications.
14009 IL_INCLUDE_DIR - where to find the il.h, ilu.h and ilut.h files.
14010 IL_FOUND - this is set to TRUE if all the above variables were set.
14011 This will be set to false if ILU or ILUT are not found,
14012 even if they are not needed. In most systems, if one
14013 library is found all the others are as well. That's the
14014 way the DevIL developers release it.
14015 FindDoxygen
14018 This module looks for Doxygen and the path to Graphviz's dot
14019 Doxygen is a documentation generation tool. Please see
14021 http://www.doxygen.org
14022 This module accepts the following optional variables:
14025 DOXYGEN_SKIP_DOT = If true this module will skip trying to find Dot
14028 (an optional component often used by Doxygen)
14029 This modules defines the following variables:
14034 DOXYGEN_EXECUTABLE = The path to the doxygen command.
14037 DOXYGEN_FOUND = Was Doxygen found or not?
14038 DOXYGEN_VERSION = The version reported by doxygen --version
14039 DOXYGEN_DOT_EXECUTABLE = The path to the dot program used by doxygen.
14044 DOXYGEN_DOT_FOUND = Was Dot found or not?
14045 DOXYGEN_DOT_PATH = The path to dot not including the executable
14046 FindEXPAT
14055 Find expat
14056 Find the native EXPAT headers and libraries.
14058 EXPAT_INCLUDE_DIRS - where to find expat.h, etc.
14061 EXPAT_LIBRARIES - List of libraries when using expat.
14062 EXPAT_FOUND - True if expat found.
14063 FindFLEX
14066 Find flex executable and provides a macro to generate custom
14067 build rules
14068 The module defines the following variables:
14073 FLEX_FOUND - true is flex executable is found
14076 FLEX_EXECUTABLE - the path to the flex executable
14077 FLEX_VERSION - the version of flex
14078 FLEX_LIBRARIES - The flex libraries
14079 FLEX_INCLUDE_DIRS - The path to the flex headers
14080 The minimum required version of flex can be specified using the
14085 standard syntax, e.g. find_package(FLEX 2.5.13)
14086 If flex is found on the system, the module provides the macro:
14092 FLEX_TARGET(Name FlexInput FlexOutput [COMPILE_FLAGS <string>])
14095 which creates a custom command to generate the <FlexOutput>
14097 file from the <FlexInput> file. If COMPILE_FLAGS option is
14098 specified, the next parameter is added to the flex command
14099 line. Name is an alias used to get details of this custom
14100 command. Indeed the macro defines the following variables:
14101 FLEX_${Name}_DEFINED - true is the macro ran successfully
14104 FLEX_${Name}_OUTPUTS - the source file generated by the custom rule, an
14105 alias for FlexOutput
14106 FLEX_${Name}_INPUT - the flex source file, an alias for ${FlexInput}
14107 Flex scanners oftenly use tokens defined by Bison: the code
14112 generated by Flex depends of the header generated by Bison.
14113 This module also defines a macro:
14114 ADD_FLEX_BISON_DEPENDENCY(FlexTarget BisonTarget)
14117 which adds the required dependency between a scanner and a
14119 parser where <FlexTarget> and <BisonTarget> are the first
14120 parameters of respectively FLEX_TARGET and BISON_TARGET macros.
14121 ====================================================================
14124 Example:
14125 find_package(BISON)
14130 find_package(FLEX)
14131 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
14136 FLEX_TARGET(MyScanner lexer.l ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp)
14137 ADD_FLEX_BISON_DEPENDENCY(MyScanner MyParser)
14138 include_directories(${CMAKE_CURRENT_BINARY_DIR})
14143 add_executable(Foo
14144 Foo.cc
14145 ${BISON_MyParser_OUTPUTS}
14146 ${FLEX_MyScanner_OUTPUTS}
14147 )
14148 ====================================================================
14149 FindFLTK
14152 Find the native FLTK includes and library
14153 By default FindFLTK.cmake will search for all of the FLTK compo‐
14158 nents and add them to the FLTK_LIBRARIES variable.
14159 You can limit the components which get placed in FLTK_LIBRARIES by
14162 defining one or more of the following three options:
14163 FLTK_SKIP_OPENGL, set to true to disable searching for opengl and
14168 the FLTK GL library
14169 FLTK_SKIP_FORMS, set to true to disable searching for fltk_forms
14170 FLTK_SKIP_IMAGES, set to true to disable searching for fltk_images
14171 FLTK_SKIP_FLUID, set to true if the fluid binary need not be present
14176 at build time
14177 The following variables will be defined:
14182 FLTK_FOUND, True if all components not skipped were found
14185 FLTK_INCLUDE_DIR, where to find include files
14186 FLTK_LIBRARIES, list of fltk libraries you should link against
14187 FLTK_FLUID_EXECUTABLE, where to find the Fluid tool
14188 FLTK_WRAP_UI, This enables the FLTK_WRAP_UI command
14189 The following cache variables are assigned but should not be
14194 used. See the FLTK_LIBRARIES variable instead.
14195 FLTK_BASE_LIBRARY = the full path to fltk.lib
14198 FLTK_GL_LIBRARY = the full path to fltk_gl.lib
14199 FLTK_FORMS_LIBRARY = the full path to fltk_forms.lib
14200 FLTK_IMAGES_LIBRARY = the full path to fltk_images.lib
14201 FindFLTK2
14204 Find the native FLTK2 includes and library
14205 The following settings are defined
14207 FLTK2_FLUID_EXECUTABLE, where to find the Fluid tool
14210 FLTK2_WRAP_UI, This enables the FLTK2_WRAP_UI command
14211 FLTK2_INCLUDE_DIR, where to find include files
14212 FLTK2_LIBRARIES, list of fltk2 libraries
14213 FLTK2_FOUND, Don't use FLTK2 if false.
14214 The following settings should not be used in general.
14216 FLTK2_BASE_LIBRARY = the full path to fltk2.lib
14219 FLTK2_GL_LIBRARY = the full path to fltk2_gl.lib
14220 FLTK2_IMAGES_LIBRARY = the full path to fltk2_images.lib
14221 FindFreetype
14224 Locate FreeType library
14225 This module defines
14227 FREETYPE_LIBRARIES, the library to link against
14230 FREETYPE_FOUND, if false, do not try to link to FREETYPE
14231 FREETYPE_INCLUDE_DIRS, where to find headers.
14232 FREETYPE_VERSION_STRING, the version of freetype found (since CMake 2.8.8)
14233 This is the concatenation of the paths:
14234 FREETYPE_INCLUDE_DIR_ft2build
14235 FREETYPE_INCLUDE_DIR_freetype2
14236 $FREETYPE_DIR is an environment variable that would correspond
14241 to the ./configure --prefix=$FREETYPE_DIR used in building
14242 FREETYPE.
14243 FindGCCXML
14246 Find the GCC-XML front-end executable.
14247 This module will define the following variables:
14252 GCCXML - the GCC-XML front-end executable.
14255 FindGDAL
14258 Locate gdal
14261 This module accepts the following environment variables:
14264 GDAL_DIR or GDAL_ROOT - Specify the location of GDAL
14267 This module defines the following CMake variables:
14272 GDAL_FOUND - True if libgdal is found
14275 GDAL_LIBRARY - A variable pointing to the GDAL library
14276 GDAL_INCLUDE_DIR - Where to find the headers
14277 FindGIF
14280 This module searches giflib and defines GIF_LIBRARIES -
14283 libraries to link to in order to use GIF GIF_FOUND, if false, do
14284 not try to link GIF_INCLUDE_DIR, where to find the headers
14285 GIF_VERSION, reports either version 4 or 3 (for everything
14286 before version 4)
14287 The minimum required version of giflib can be specified using
14290 the standard syntax, e.g. find_package(GIF 4)
14291 $GIF_DIR is an environment variable that would correspond to the
14294 ./configure --prefix=$GIF_DIR
14295 FindGLEW
14298 Find the OpenGL Extension Wrangler Library (GLEW)
14299 This module defines the following variables:
14301 GLEW_INCLUDE_DIRS - include directories for GLEW
14304 GLEW_LIBRARIES - libraries to link against GLEW
14305 GLEW_FOUND - true if GLEW has been found and can be used
14306 FindGLUT
14309 try to find glut library and include files
14310 GLUT_INCLUDE_DIR, where to find GL/glut.h, etc.
14312 GLUT_LIBRARIES, the libraries to link against
14313 GLUT_FOUND, If false, do not try to use GLUT.
14314 Also defined, but not for general use are:
14316 GLUT_glut_LIBRARY = the full path to the glut library.
14319 GLUT_Xmu_LIBRARY = the full path to the Xmu library.
14320 GLUT_Xi_LIBRARY = the full path to the Xi Library.
14321 FindGTK
14324 try to find GTK (and glib) and GTKGLArea
14325 GTK_INCLUDE_DIR - Directories to include to use GTK
14327 GTK_LIBRARIES - Files to link against to use GTK
14328 GTK_FOUND - GTK was found
14329 GTK_GL_FOUND - GTK's GL features were found
14330 FindGTK2
14333 FindGTK2.cmake
14334 This module can find the GTK2 widget libraries and several of
14336 its other optional components like gtkmm, glade, and glademm.
14337 NOTE: If you intend to use version checking, CMake 2.6.2 or
14340 later is
14341 required.
14344 Specify one or more of the following components as you call this
14349 find module. See example below.
14350 gtk
14353 gtkmm
14354 glade
14355 glademm
14356 The following variables will be defined for your use
14361 GTK2_FOUND - Were all of your specified components found?
14364 GTK2_INCLUDE_DIRS - All include directories
14365 GTK2_LIBRARIES - All libraries
14366 GTK2_DEFINITIONS - Additional compiler flags
14367 GTK2_VERSION - The version of GTK2 found (x.y.z)
14372 GTK2_MAJOR_VERSION - The major version of GTK2
14373 GTK2_MINOR_VERSION - The minor version of GTK2
14374 GTK2_PATCH_VERSION - The patch version of GTK2
14375 Optional variables you can define prior to calling this module:
14380 GTK2_DEBUG - Enables verbose debugging of the module
14383 GTK2_ADDITIONAL_SUFFIXES - Allows defining additional directories to
14384 search for include files
14385 ================= Example Usage:
14390 Call find_package() once, here are some examples to pick from:
14393 Require GTK 2.6 or later
14398 find_package(GTK2 2.6 REQUIRED gtk)
14399 Require GTK 2.10 or later and Glade
14404 find_package(GTK2 2.10 REQUIRED gtk glade)
14405 Search for GTK/GTKMM 2.8 or later
14410 find_package(GTK2 2.8 COMPONENTS gtk gtkmm)
14411 if(GTK2_FOUND)
14416 include_directories(${GTK2_INCLUDE_DIRS})
14417 add_executable(mygui mygui.cc)
14418 target_link_libraries(mygui ${GTK2_LIBRARIES})
14419 endif()
14420 FindGTest
14426 --------------------
14427 Locate the Google C++ Testing Framework.
14429 Defines the following variables:
14432 GTEST_FOUND - Found the Google Testing framework
14435 GTEST_INCLUDE_DIRS - Include directories
14436 Also defines the library variables below as normal variables.
14441 These contain debug/optimized keywords when a debugging library
14442 is found.
14443 GTEST_BOTH_LIBRARIES - Both libgtest & libgtest-main
14446 GTEST_LIBRARIES - libgtest
14447 GTEST_MAIN_LIBRARIES - libgtest-main
14448 Accepts the following variables as input:
14453 GTEST_ROOT - (as a CMake or environment variable)
14456 The root directory of the gtest install prefix
14457 GTEST_MSVC_SEARCH - If compiling with MSVC, this variable can be set to
14462 "MD" or "MT" to enable searching a GTest build tree
14463 (defaults: "MD")
14464 Example Usage:
14469 enable_testing()
14472 find_package(GTest REQUIRED)
14473 include_directories(${GTEST_INCLUDE_DIRS})
14474 add_executable(foo foo.cc)
14479 target_link_libraries(foo ${GTEST_BOTH_LIBRARIES})
14480 add_test(AllTestsInFoo foo)
14485 If you would like each Google test to show up in CTest as a test
14493 you may use the following macro. NOTE: It will slow down your
14494 tests by running an executable for each test and test fixture.
14495 You will also have to rerun CMake after adding or removing tests
14496 or test fixtures.
14497 GTEST_ADD_TESTS(executable extra_args ARGN)
14500 executable = The path to the test executable
14503 extra_args = Pass a list of extra arguments to be passed to
14504 executable enclosed in quotes (or "" for none)
14505 ARGN = A list of source files to search for tests & test
14506 fixtures.
14507 Example:
14512 set(FooTestArgs --foo 1 --bar 2)
14513 add_executable(FooTest FooUnitTest.cc)
14514 GTEST_ADD_TESTS(FooTest "${FooTestArgs}" FooUnitTest.cc)
14515 FindGettext
14518 Find GNU gettext tools
14519 This module looks for the GNU gettext tools. This module defines
14521 the following values:
14522 GETTEXT_MSGMERGE_EXECUTABLE: the full path to the msgmerge tool.
14525 GETTEXT_MSGFMT_EXECUTABLE: the full path to the msgfmt tool.
14526 GETTEXT_FOUND: True if gettext has been found.
14527 GETTEXT_VERSION_STRING: the version of gettext found (since CMake 2.8.8)
14528 Additionally it provides the following macros: GETTEXT_CRE‐
14533 ATE_TRANSLATIONS ( outputFile [ALL] file1 ... fileN )
14534 This will create a target "translations" which will convert the
14537 given input po files into the binary output mo file. If the
14538 ALL option is used, the translations will also be created when
14539 building the default target.
14540 GETTEXT_PROCESS_POT( <potfile> [ALL] [INSTALL_DESTINATION <dest‐
14542 dir>] LANGUAGES <lang1> <lang2> ... )
14543 Process the given pot file to mo files.
14546 If INSTALL_DESTINATION is given then automatically install rules will be created,
14547 the language subdirectory will be taken into account (by default use share/locale/).
14548 If ALL is specified, the pot file is processed when building the all traget.
14549 It creates a custom target "potfile".
14550 GETTEXT_PROCESS_PO_FILES( <lang> [ALL] [INSTALL_DESTINATION
14552 <dir>] PO_FILES <po1> <po2> ... )
14553 Process the given po files to mo files for the given language.
14556 If INSTALL_DESTINATION is given then automatically install rules will be created,
14557 the language subdirectory will be taken into account (by default use share/locale/).
14558 If ALL is specified, the po files are processed when building the all traget.
14559 It creates a custom target "pofiles".
14560 FindGit
14563 The module defines the following variables:
14566 GIT_EXECUTABLE - path to git command line client
14569 GIT_FOUND - true if the command line client was found
14570 GIT_VERSION_STRING - the version of git found (since CMake 2.8.8)
14571 Example usage:
14573 find_package(Git)
14576 if(GIT_FOUND)
14577 message("git found: ${GIT_EXECUTABLE}")
14578 endif()
14579 FindGnuTLS
14582 Try to find the GNU Transport Layer Security library (gnutls)
14583 Once done this will define
14588 GNUTLS_FOUND - System has gnutls
14591 GNUTLS_INCLUDE_DIR - The gnutls include directory
14592 GNUTLS_LIBRARIES - The libraries needed to use gnutls
14593 GNUTLS_DEFINITIONS - Compiler switches required for using gnutls
14594 FindGnuplot
14597 this module looks for gnuplot
14598 Once done this will define
14603 GNUPLOT_FOUND - system has Gnuplot
14606 GNUPLOT_EXECUTABLE - the Gnuplot executable
14607 GNUPLOT_VERSION_STRING - the version of Gnuplot found (since CMake 2.8.8)
14608 GNUPLOT_VERSION_STRING will not work for old versions like
14613 3.7.1.
14614 FindHDF5
14617 Find HDF5, a library for reading and writing self describing
14618 array data.
14619 This module invokes the HDF5 wrapper compiler that should be
14624 installed alongside HDF5. Depending upon the HDF5 Configura‐
14625 tion, the wrapper compiler is called either h5cc or h5pcc. If
14626 this succeeds, the module will then call the compiler with the
14627 -show argument to see what flags are used when compiling an HDF5
14628 client application.
14629 The module will optionally accept the COMPONENTS argument. If
14632 no COMPONENTS are specified, then the find module will default
14633 to finding only the HDF5 C library. If one or more COMPONENTS
14634 are specified, the module will attempt to find the language
14635 bindings for the specified components. The only valid compo‐
14636 nents are C, CXX, Fortran, HL, and Fortran_HL. If the COMPO‐
14637 NENTS argument is not given, the module will attempt to find
14638 only the C bindings.
14639 On UNIX systems, this module will read the variable
14642 HDF5_USE_STATIC_LIBRARIES to determine whether or not to prefer
14643 a static link to a dynamic link for HDF5 and all of it's depen‐
14644 dencies. To use this feature, make sure that the
14645 HDF5_USE_STATIC_LIBRARIES variable is set before the call to
14646 find_package.
14647 To provide the module with a hint about where to find your HDF5
14650 installation, you can set the environment variable HDF5_ROOT.
14651 The Find module will then look in this path when searching for
14652 HDF5 executables, paths, and libraries.
14653 In addition to finding the includes and libraries required to
14656 compile an HDF5 client application, this module also makes an
14657 effort to find tools that come with the HDF5 distribution that
14658 may be useful for regression testing.
14659 This module will define the following variables:
14662 HDF5_INCLUDE_DIRS - Location of the hdf5 includes
14665 HDF5_INCLUDE_DIR - Location of the hdf5 includes (deprecated)
14666 HDF5_DEFINITIONS - Required compiler definitions for HDF5
14667 HDF5_C_LIBRARIES - Required libraries for the HDF5 C bindings.
14668 HDF5_CXX_LIBRARIES - Required libraries for the HDF5 C++ bindings
14669 HDF5_Fortran_LIBRARIES - Required libraries for the HDF5 Fortran bindings
14670 HDF5_HL_LIBRARIES - Required libraries for the HDF5 high level API
14671 HDF5_Fortran_HL_LIBRARIES - Required libraries for the high level Fortran
14672 bindings.
14673 HDF5_LIBRARIES - Required libraries for all requested bindings
14674 HDF5_FOUND - true if HDF5 was found on the system
14675 HDF5_LIBRARY_DIRS - the full set of library directories
14676 HDF5_IS_PARALLEL - Whether or not HDF5 was found with parallel IO support
14677 HDF5_C_COMPILER_EXECUTABLE - the path to the HDF5 C wrapper compiler
14678 HDF5_CXX_COMPILER_EXECUTABLE - the path to the HDF5 C++ wrapper compiler
14679 HDF5_Fortran_COMPILER_EXECUTABLE - the path to the HDF5 Fortran wrapper compiler
14680 HDF5_DIFF_EXECUTABLE - the path to the HDF5 dataset comparison tool
14681 FindHSPELL
14684 Try to find Hspell
14685 Once done this will define
14687 HSPELL_FOUND - system has Hspell
14690 HSPELL_INCLUDE_DIR - the Hspell include directory
14691 HSPELL_LIBRARIES - The libraries needed to use Hspell
14692 HSPELL_DEFINITIONS - Compiler switches required for using Hspell
14693 HSPELL_VERSION_STRING - The version of Hspell found (x.y)
14698 HSPELL_MAJOR_VERSION - the major version of Hspell
14699 HSPELL_MINOR_VERSION - The minor version of Hspell
14700 FindHTMLHelp
14703 This module looks for Microsoft HTML Help Compiler
14704 It defines:
14706 HTML_HELP_COMPILER : full path to the Compiler (hhc.exe)
14709 HTML_HELP_INCLUDE_PATH : include path to the API (htmlhelp.h)
14710 HTML_HELP_LIBRARY : full path to the library (htmlhelp.lib)
14711 FindHg
14717 The module defines the following variables:
14720 HG_EXECUTABLE - path to mercurial command line client (hg)
14723 HG_FOUND - true if the command line client was found
14724 HG_VERSION_STRING - the version of mercurial found
14725 Example usage:
14727 find_package(Hg)
14730 if(HG_FOUND)
14731 message("hg found: ${HG_EXECUTABLE}")
14732 endif()
14733 FindITK
14736 Find an ITK installation or build tree.
14737 FindIcotool
14740 Find icotool
14741 This module looks for icotool. This module defines the following
14743 values:
14744 ICOTOOL_EXECUTABLE: the full path to the icotool tool.
14747 ICOTOOL_FOUND: True if icotool has been found.
14748 ICOTOOL_VERSION_STRING: the version of icotool found.
14749 FindImageMagick
14755 Find the ImageMagick binary suite.
14756 This module will search for a set of ImageMagick tools specified
14758 as components in the FIND_PACKAGE call. Typical components
14759 include, but are not limited to (future versions of ImageMagick
14760 might have additional components not listed here):
14761 animate
14764 compare
14765 composite
14766 conjure
14767 convert
14768 display
14769 identify
14770 import
14771 mogrify
14772 montage
14773 stream
14774 If no component is specified in the FIND_PACKAGE call, then it
14779 only searches for the ImageMagick executable directory. This
14780 code defines the following variables:
14781 ImageMagick_FOUND - TRUE if all components are found.
14784 ImageMagick_EXECUTABLE_DIR - Full path to executables directory.
14785 ImageMagick_<component>_FOUND - TRUE if <component> is found.
14786 ImageMagick_<component>_EXECUTABLE - Full path to <component> executable.
14787 ImageMagick_VERSION_STRING - the version of ImageMagick found
14788 (since CMake 2.8.8)
14789 ImageMagick_VERSION_STRING will not work for old versions like
14794 5.2.3.
14795 There are also components for the following ImageMagick APIs:
14798 Magick++
14801 MagickWand
14802 MagickCore
14803 For these components the following variables are set:
14808 ImageMagick_FOUND - TRUE if all components are found.
14811 ImageMagick_INCLUDE_DIRS - Full paths to all include dirs.
14812 ImageMagick_LIBRARIES - Full paths to all libraries.
14813 ImageMagick_<component>_FOUND - TRUE if <component> is found.
14814 ImageMagick_<component>_INCLUDE_DIRS - Full path to <component> include dirs.
14815 ImageMagick_<component>_LIBRARIES - Full path to <component> libraries.
14816 Example Usages:
14821 find_package(ImageMagick)
14824 find_package(ImageMagick COMPONENTS convert)
14825 find_package(ImageMagick COMPONENTS convert mogrify display)
14826 find_package(ImageMagick COMPONENTS Magick++)
14827 find_package(ImageMagick COMPONENTS Magick++ convert)
14828 Note that the standard FIND_PACKAGE features are supported
14833 (i.e., QUIET, REQUIRED, etc.).
14834 FindJNI
14837 Find JNI java libraries.
14838 This module finds if Java is installed and determines where the
14840 include files and libraries are. It also determines what the
14841 name of the library is. This code sets the following variables:
14842 JNI_INCLUDE_DIRS = the include dirs to use
14845 JNI_LIBRARIES = the libraries to use
14846 JNI_FOUND = TRUE if JNI headers and libraries were found.
14847 JAVA_AWT_LIBRARY = the path to the jawt library
14848 JAVA_JVM_LIBRARY = the path to the jvm library
14849 JAVA_INCLUDE_PATH = the include path to jni.h
14850 JAVA_INCLUDE_PATH2 = the include path to jni_md.h
14851 JAVA_AWT_INCLUDE_PATH = the include path to jawt.h
14852 FindJPEG
14858 Find JPEG
14859 Find the native JPEG includes and library This module defines
14861 JPEG_INCLUDE_DIR, where to find jpeglib.h, etc.
14864 JPEG_LIBRARIES, the libraries needed to use JPEG.
14865 JPEG_FOUND, If false, do not try to use JPEG.
14866 also defined, but not for general use are
14868 JPEG_LIBRARY, where to find the JPEG library.
14871 FindJasper
14874 Try to find the Jasper JPEG2000 library
14875 Once done this will define
14877 JASPER_FOUND - system has Jasper
14880 JASPER_INCLUDE_DIR - the Jasper include directory
14881 JASPER_LIBRARIES - the libraries needed to use Jasper
14882 JASPER_VERSION_STRING - the version of Jasper found (since CMake 2.8.8)
14883 FindJava
14886 Find Java
14887 This module finds if Java is installed and determines where the
14889 include files and libraries are. This code sets the following
14890 variables:
14891 Java_JAVA_EXECUTABLE = the full path to the Java runtime
14894 Java_JAVAC_EXECUTABLE = the full path to the Java compiler
14895 Java_JAVAH_EXECUTABLE = the full path to the Java header generator
14896 Java_JAVADOC_EXECUTABLE = the full path to the Java documention generator
14897 Java_JAR_EXECUTABLE = the full path to the Java archiver
14898 Java_VERSION_STRING = Version of the package found (java version), eg. 1.6.0_12
14899 Java_VERSION_MAJOR = The major version of the package found.
14900 Java_VERSION_MINOR = The minor version of the package found.
14901 Java_VERSION_PATCH = The patch version of the package found.
14902 Java_VERSION_TWEAK = The tweak version of the package found (after '_')
14903 Java_VERSION = This is set to: $major.$minor.$patch(.$tweak)
14904 The minimum required version of Java can be specified using the
14909 standard CMake syntax, e.g. find_package(Java 1.5)
14910 NOTE: ${Java_VERSION} and ${Java_VERSION_STRING} are not guaran‐
14913 teed to be identical. For example some java version may return:
14914 Java_VERSION_STRING = 1.5.0_17 and Java_VERSION =
14915 1.5.0.17
14916 another example is the Java OEM, with: Java_VERSION_STRING =
14919 1.6.0-oem and Java_VERSION = 1.6.0
14920 For these components the following variables are set:
14923 Java_FOUND - TRUE if all components are found.
14926 Java_INCLUDE_DIRS - Full paths to all include dirs.
14927 Java_LIBRARIES - Full paths to all libraries.
14928 Java_<component>_FOUND - TRUE if <component> is found.
14929 Example Usages:
14934 find_package(Java)
14937 find_package(Java COMPONENTS Runtime)
14938 find_package(Java COMPONENTS Development)
14939 FindKDE3
14945 Find the KDE3 include and library dirs, KDE preprocessors and
14946 define a some macros
14947 This module defines the following variables:
14952 KDE3_DEFINITIONS - compiler definitions required for compiling KDE software
14955 KDE3_INCLUDE_DIR - the KDE include directory
14956 KDE3_INCLUDE_DIRS - the KDE and the Qt include directory, for use with include_directories()
14957 KDE3_LIB_DIR - the directory where the KDE libraries are installed, for use with link_directories()
14958 QT_AND_KDECORE_LIBS - this contains both the Qt and the kdecore library
14959 KDE3_DCOPIDL_EXECUTABLE - the dcopidl executable
14960 KDE3_DCOPIDL2CPP_EXECUTABLE - the dcopidl2cpp executable
14961 KDE3_KCFGC_EXECUTABLE - the kconfig_compiler executable
14962 KDE3_FOUND - set to TRUE if all of the above has been found
14963 The following user adjustable options are provided:
14968 KDE3_BUILD_TESTS - enable this to build KDE testcases
14971 It also adds the following macros (from KDE3Macros.cmake)
14979 SRCS_VAR is always the variable which contains the list of
14980 source files for your application or library.
14981 KDE3_AUTOMOC(file1 ... fileN)
14984 Call this if you want to have automatic moc file handling.
14987 This means if you include "foo.moc" in the source file foo.cpp
14988 a moc file for the header foo.h will be created automatically.
14989 You can set the property SKIP_AUTOMAKE using set_source_files_properties()
14990 to exclude some files in the list from being processed.
14991 KDE3_ADD_MOC_FILES(SRCS_VAR file1 ... fileN )
14996 If you don't use the KDE3_AUTOMOC() macro, for the files
14999 listed here moc files will be created (named "foo.moc.cpp")
15000 KDE3_ADD_DCOP_SKELS(SRCS_VAR header1.h ... headerN.h )
15005 Use this to generate DCOP skeletions from the listed headers.
15008 KDE3_ADD_DCOP_STUBS(SRCS_VAR header1.h ... headerN.h )
15013 Use this to generate DCOP stubs from the listed headers.
15016 KDE3_ADD_UI_FILES(SRCS_VAR file1.ui ... fileN.ui )
15021 Use this to add the Qt designer ui files to your application/library.
15024 KDE3_ADD_KCFG_FILES(SRCS_VAR file1.kcfgc ... fileN.kcfgc )
15029 Use this to add KDE kconfig compiler files to your application/library.
15032 KDE3_INSTALL_LIBTOOL_FILE(target)
15037 This will create and install a simple libtool file for the given target.
15040 KDE3_ADD_EXECUTABLE(name file1 ... fileN )
15045 Currently identical to add_executable(), may provide some advanced features in the future.
15048 KDE3_ADD_KPART(name [WITH_PREFIX] file1 ... fileN )
15053 Create a KDE plugin (KPart, kioslave, etc.) from the given source files.
15056 If WITH_PREFIX is given, the resulting plugin will have the prefix "lib", otherwise it won't.
15057 It creates and installs an appropriate libtool la-file.
15058 KDE3_ADD_KDEINIT_EXECUTABLE(name file1 ... fileN )
15063 Create a KDE application in the form of a module loadable via kdeinit.
15066 A library named kdeinit_<name> will be created and a small executable which links to it.
15067 The option KDE3_ENABLE_FINAL to enable all-in-one compilation is
15072 no longer supported.
15073 Author: Alexander Neundorf <neundorf@kde.org>
15079 FindKDE4
15082 Find KDE4 and provide all necessary variables and macros to com‐
15085 pile software for it. It looks for KDE 4 in the following direc‐
15086 tories in the given order:
15087 CMAKE_INSTALL_PREFIX
15090 KDEDIRS
15091 /opt/kde4
15092 Please look in FindKDE4Internal.cmake and KDE4Macros.cmake for
15097 more information. They are installed with the KDE 4 libraries in
15098 $KDEDIRS/share/apps/cmake/modules/.
15099 Author: Alexander Neundorf <neundorf@kde.org>
15102 FindLAPACK
15105 Find LAPACK library
15106 This module finds an installed fortran library that implements
15108 the LAPACK linear-algebra interface (see
15109 http://www.netlib.org/lapack/).
15110 The approach follows that taken for the autoconf macro file,
15113 acx_lapack.m4 (distributed at http://ac-archive.source‐
15114 forge.net/ac-archive/acx_lapack.html).
15115 This module sets the following variables:
15118 LAPACK_FOUND - set to true if a library implementing the LAPACK interface
15121 is found
15122 LAPACK_LINKER_FLAGS - uncached list of required linker flags (excluding -l
15123 and -L).
15124 LAPACK_LIBRARIES - uncached list of libraries (using full path name) to
15125 link against to use LAPACK
15126 LAPACK95_LIBRARIES - uncached list of libraries (using full path name) to
15127 link against to use LAPACK95
15128 LAPACK95_FOUND - set to true if a library implementing the LAPACK f95
15129 interface is found
15130 BLA_STATIC if set on this determines what kind of linkage we do (static)
15131 BLA_VENDOR if set checks only the specified vendor, if not set checks
15132 all the possibilities
15133 BLA_F95 if set on tries to find the f95 interfaces for BLAS/LAPACK
15134 FindLATEX
15137 Find Latex
15138 This module finds if Latex is installed and determines where the
15140 executables are. This code sets the following variables:
15141 LATEX_COMPILER: path to the LaTeX compiler
15144 PDFLATEX_COMPILER: path to the PdfLaTeX compiler
15145 BIBTEX_COMPILER: path to the BibTeX compiler
15146 MAKEINDEX_COMPILER: path to the MakeIndex compiler
15147 DVIPS_CONVERTER: path to the DVIPS converter
15148 PS2PDF_CONVERTER: path to the PS2PDF converter
15149 LATEX2HTML_CONVERTER: path to the LaTeX2Html converter
15150 FindLibArchive
15156 Find libarchive library and headers
15157 The module defines the following variables:
15159 LibArchive_FOUND - true if libarchive was found
15162 LibArchive_INCLUDE_DIRS - include search path
15163 LibArchive_LIBRARIES - libraries to link
15164 LibArchive_VERSION - libarchive 3-component version number
15165 FindLibLZMA
15168 Find LibLZMA
15169 Find LibLZMA headers and library
15171 LIBLZMA_FOUND - True if liblzma is found.
15174 LIBLZMA_INCLUDE_DIRS - Directory where liblzma headers are located.
15175 LIBLZMA_LIBRARIES - Lzma libraries to link against.
15176 LIBLZMA_HAS_AUTO_DECODER - True if lzma_auto_decoder() is found (required).
15177 LIBLZMA_HAS_EASY_ENCODER - True if lzma_easy_encoder() is found (required).
15178 LIBLZMA_HAS_LZMA_PRESET - True if lzma_lzma_preset() is found (required).
15179 LIBLZMA_VERSION_MAJOR - The major version of lzma
15180 LIBLZMA_VERSION_MINOR - The minor version of lzma
15181 LIBLZMA_VERSION_PATCH - The patch version of lzma
15182 LIBLZMA_VERSION_STRING - version number as a string (ex: "5.0.3")
15183 FindLibXml2
15186 Try to find the LibXml2 xml processing library
15187 Once done this will define
15189 LIBXML2_FOUND - System has LibXml2
15192 LIBXML2_INCLUDE_DIR - The LibXml2 include directory
15193 LIBXML2_LIBRARIES - The libraries needed to use LibXml2
15194 LIBXML2_DEFINITIONS - Compiler switches required for using LibXml2
15195 LIBXML2_XMLLINT_EXECUTABLE - The XML checking tool xmllint coming with LibXml2
15196 LIBXML2_VERSION_STRING - the version of LibXml2 found (since CMake 2.8.8)
15197 FindLibXslt
15200 Try to find the LibXslt library
15201 Once done this will define
15203 LIBXSLT_FOUND - system has LibXslt
15206 LIBXSLT_INCLUDE_DIR - the LibXslt include directory
15207 LIBXSLT_LIBRARIES - Link these to LibXslt
15208 LIBXSLT_DEFINITIONS - Compiler switches required for using LibXslt
15209 LIBXSLT_VERSION_STRING - version of LibXslt found (since CMake 2.8.8)
15210 Additionally, the following two variables are set (but not
15212 required for using xslt):
15213 LIBXSLT_EXSLT_LIBRARIES - Link to these if you need to link against the exslt library
15216 LIBXSLT_XSLTPROC_EXECUTABLE - Contains the full path to the xsltproc executable if found
15217 FindLua50
15220 Locate Lua library This module defines
15223 LUA50_FOUND, if false, do not try to link to Lua
15226 LUA_LIBRARIES, both lua and lualib
15227 LUA_INCLUDE_DIR, where to find lua.h and lualib.h (and probably lauxlib.h)
15228 Note that the expected include convention is
15233 #include "lua.h"
15236 and not
15238 #include <lua/lua.h>
15241 This is because, the lua location is not standardized and may
15243 exist in locations other than lua/
15244 FindLua51
15247 Locate Lua library This module defines
15250 LUA51_FOUND, if false, do not try to link to Lua
15253 LUA_LIBRARIES
15254 LUA_INCLUDE_DIR, where to find lua.h
15255 LUA_VERSION_STRING, the version of Lua found (since CMake 2.8.8)
15256 Note that the expected include convention is
15261 #include "lua.h"
15264 and not
15266 #include <lua/lua.h>
15269 This is because, the lua location is not standardized and may
15271 exist in locations other than lua/
15272 FindLua52
15275 Locate Lua library This module defines
15278 LUA52_FOUND, if false, do not try to link to Lua
15281 LUA_LIBRARIES
15282 LUA_INCLUDE_DIR, where to find lua.h
15283 LUA_VERSION_STRING, the version of Lua found (since CMake 2.8.8)
15284 Note that the expected include convention is
15289 #include "lua.h"
15292 and not
15294 #include <lua/lua.h>
15297 This is because, the lua location is not standardized and may
15299 exist in locations other than lua/
15300 FindMFC
15303 Find MFC on Windows
15304 Find the native MFC - i.e. decide if an application can link to
15306 the MFC libraries.
15307 MFC_FOUND - Was MFC support found
15310 You don't need to include anything or link anything to use it.
15312 FindMPEG
15315 Find the native MPEG includes and library
15316 This module defines
15318 MPEG_INCLUDE_DIR, where to find MPEG.h, etc.
15321 MPEG_LIBRARIES, the libraries required to use MPEG.
15322 MPEG_FOUND, If false, do not try to use MPEG.
15323 also defined, but not for general use are
15325 MPEG_mpeg2_LIBRARY, where to find the MPEG library.
15328 MPEG_vo_LIBRARY, where to find the vo library.
15329 FindMPEG2
15332 Find the native MPEG2 includes and library
15333 This module defines
15335 MPEG2_INCLUDE_DIR, path to mpeg2dec/mpeg2.h, etc.
15338 MPEG2_LIBRARIES, the libraries required to use MPEG2.
15339 MPEG2_FOUND, If false, do not try to use MPEG2.
15340 also defined, but not for general use are
15342 MPEG2_mpeg2_LIBRARY, where to find the MPEG2 library.
15345 MPEG2_vo_LIBRARY, where to find the vo library.
15346 FindMPI
15349 Find a Message Passing Interface (MPI) implementation
15350 The Message Passing Interface (MPI) is a library used to write
15352 high-performance distributed-memory parallel applications, and
15353 is typically deployed on a cluster. MPI is a standard interface
15354 (defined by the MPI forum) for which many implementations are
15355 available. All of them have somewhat different include paths,
15356 libraries to link against, etc., and this module tries to smooth
15357 out those differences.
15358 === Variables ===
15361 This module will set the following variables per language in
15364 your project, where <lang> is one of C, CXX, or Fortran:
15365 MPI_<lang>_FOUND TRUE if FindMPI found MPI flags for <lang>
15368 MPI_<lang>_COMPILER MPI Compiler wrapper for <lang>
15369 MPI_<lang>_COMPILE_FLAGS Compilation flags for MPI programs
15370 MPI_<lang>_INCLUDE_PATH Include path(s) for MPI header
15371 MPI_<lang>_LINK_FLAGS Linking flags for MPI programs
15372 MPI_<lang>_LIBRARIES All libraries to link MPI programs against
15373 Additionally, FindMPI sets the following variables for running
15375 MPI programs from the command line:
15376 MPIEXEC Executable for running MPI programs
15379 MPIEXEC_NUMPROC_FLAG Flag to pass to MPIEXEC before giving
15380 it the number of processors to run on
15381 MPIEXEC_PREFLAGS Flags to pass to MPIEXEC directly
15382 before the executable to run.
15383 MPIEXEC_POSTFLAGS Flags to pass to MPIEXEC after other flags
15384 === Usage ===
15386 To use this module, simply call FindMPI from a CMakeLists.txt
15389 file, or run find_package(MPI), then run CMake. If you are
15390 happy with the auto- detected configuration for your language,
15391 then you're done. If not, you have two options:
15392 1. Set MPI_<lang>_COMPILER to the MPI wrapper (mpicc, etc.) of your
15395 choice and reconfigure. FindMPI will attempt to determine all the
15396 necessary variables using THAT compiler's compile and link flags.
15397 2. If this fails, or if your MPI implementation does not come with
15398 a compiler wrapper, then set both MPI_<lang>_LIBRARIES and
15399 MPI_<lang>_INCLUDE_PATH. You may also set any other variables
15400 listed above, but these two are required. This will circumvent
15401 autodetection entirely.
15402 When configuration is successful, MPI_<lang>_COMPILER will be
15404 set to the compiler wrapper for <lang>, if it was found.
15405 MPI_<lang>_FOUND and other variables above will be set if any
15406 MPI implementation was found for <lang>, regardless of whether a
15407 compiler was found.
15408 When using MPIEXEC to execute MPI applications, you should typi‐
15411 cally use all of the MPIEXEC flags as follows:
15412 ${MPIEXEC} ${MPIEXEC_NUMPROC_FLAG} PROCS
15415 ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS
15416 where PROCS is the number of processors on which to execute the
15418 program, EXECUTABLE is the MPI program, and ARGS are the argu‐
15419 ments to pass to the MPI program.
15420 === Backward Compatibility ===
15423 For backward compatibility with older versions of FindMPI, these
15426 variables are set, but deprecated:
15427 MPI_FOUND MPI_COMPILER MPI_LIBRARY
15430 MPI_COMPILE_FLAGS MPI_INCLUDE_PATH MPI_EXTRA_LIBRARY
15431 MPI_LINK_FLAGS MPI_LIBRARIES
15432 In new projects, please use the MPI_<lang>_XXX equivalents.
15434 FindMatlab
15437 this module looks for Matlab
15438 Defines:
15440 MATLAB_INCLUDE_DIR: include path for mex.h, engine.h
15443 MATLAB_LIBRARIES: required libraries: libmex, etc
15444 MATLAB_MEX_LIBRARY: path to libmex.lib
15445 MATLAB_MX_LIBRARY: path to libmx.lib
15446 MATLAB_ENG_LIBRARY: path to libeng.lib
15447 FindMotif
15450 Try to find Motif (or lesstif)
15451 Once done this will define:
15453 MOTIF_FOUND - system has MOTIF
15456 MOTIF_INCLUDE_DIR - include paths to use Motif
15457 MOTIF_LIBRARIES - Link these to use Motif
15458 FindOpenAL
15461 Locate OpenAL This module defines OPENAL_LIBRARY OPENAL_FOUND,
15464 if false, do not try to link to OpenAL OPENAL_INCLUDE_DIR, where
15465 to find the headers
15466 $OPENALDIR is an environment variable that would correspond to
15469 the ./configure --prefix=$OPENALDIR used in building OpenAL.
15470 Created by Eric Wing. This was influenced by the FindSDL.cmake
15473 module.
15474 FindOpenGL
15477 Try to find OpenGL
15478 Once done this will define
15480 OPENGL_FOUND - system has OpenGL
15483 OPENGL_XMESA_FOUND - system has XMESA
15484 OPENGL_GLU_FOUND - system has GLU
15485 OPENGL_INCLUDE_DIR - the GL include directory
15486 OPENGL_LIBRARIES - Link these to use OpenGL and GLU
15487 If you want to use just GL you can use these values
15492 OPENGL_gl_LIBRARY - Path to OpenGL Library
15495 OPENGL_glu_LIBRARY - Path to GLU Library
15496 On OSX default to using the framework version of opengl People
15501 will have to change the cache values of OPENGL_glu_LIBRARY and
15502 OPENGL_gl_LIBRARY to use OpenGL with X11 on OSX
15503 FindOpenMP
15506 Finds OpenMP support
15507 This module can be used to detect OpenMP support in a compiler.
15509 If the compiler supports OpenMP, the flags required to compile
15510 with OpenMP support are returned in variables for the different
15511 languages. The variables may be empty if the compiler does not
15512 need a special flag to support OpenMP.
15513 The following variables are set:
15516 OpenMP_C_FLAGS - flags to add to the C compiler for OpenMP support
15519 OpenMP_CXX_FLAGS - flags to add to the CXX compiler for OpenMP support
15520 OPENMP_FOUND - true if openmp is detected
15521 Supported compilers can be found at
15526 http://openmp.org/wp/openmp-compilers/
15527 FindOpenSSL
15530 Try to find the OpenSSL encryption library
15531 Once done this will define
15533 OPENSSL_ROOT_DIR - Set this variable to the root installation of OpenSSL
15536 Read-Only variables:
15541 OPENSSL_FOUND - system has the OpenSSL library
15544 OPENSSL_INCLUDE_DIR - the OpenSSL include directory
15545 OPENSSL_LIBRARIES - The libraries needed to use OpenSSL
15546 OPENSSL_VERSION - This is set to $major.$minor.$revision$path (eg. 0.9.8s)
15547 FindOpenSceneGraph
15550 Find OpenSceneGraph
15551 This module searches for the OpenSceneGraph core "osg" library
15553 as well as OpenThreads, and whatever additional COMPONENTS
15554 (nodekits) that you specify.
15555 See http://www.openscenegraph.org
15558 NOTE: To use this module effectively you must either require
15563 CMake >= 2.6.3 with cmake_minimum_required(VERSION 2.6.3) or
15564 download and place FindOpenThreads.cmake, Findosg_func‐
15565 tions.cmake, Findosg.cmake, and Find<etc>.cmake files into your
15566 CMAKE_MODULE_PATH.
15567 ==================================
15570 This module accepts the following variables (note mixed case)
15573 OpenSceneGraph_DEBUG - Enable debugging output
15576 OpenSceneGraph_MARK_AS_ADVANCED - Mark cache variables as advanced
15581 automatically
15582 The following environment variables are also respected for find‐
15587 ing the OSG and it's various components. CMAKE_PREFIX_PATH can
15588 also be used for this (see find_library() CMake documentation).
15589 <MODULE>_DIR (where MODULE is of the form "OSGVOLUME" and there is a FindosgVolume.cmake file)
15592 OSG_DIR
15593 OSGDIR
15594 OSG_ROOT
15595 [CMake 2.8.10]: The CMake variable OSG_DIR can now be used as
15600 well to influence detection, instead of needing to specify an
15601 environment variable.
15602 This module defines the following output variables:
15605 OPENSCENEGRAPH_FOUND - Was the OSG and all of the specified components found?
15608 OPENSCENEGRAPH_VERSION - The version of the OSG which was found
15613 OPENSCENEGRAPH_INCLUDE_DIRS - Where to find the headers
15618 OPENSCENEGRAPH_LIBRARIES - The OSG libraries
15623 ================================== Example Usage:
15628 find_package(OpenSceneGraph 2.0.0 REQUIRED osgDB osgUtil)
15631 # libOpenThreads & libosg automatically searched
15632 include_directories(${OPENSCENEGRAPH_INCLUDE_DIRS})
15633 add_executable(foo foo.cc)
15638 target_link_libraries(foo ${OPENSCENEGRAPH_LIBRARIES})
15639 FindOpenThreads
15645 OpenThreads is a C++ based threading library. Its largest user‐
15648 base seems to OpenSceneGraph so you might notice I accept OSGDIR
15649 as an environment path. I consider this part of the Findosg*
15650 suite used to find OpenSceneGraph components. Each component is
15651 separate and you must opt in to each module.
15652 Locate OpenThreads This module defines OPENTHREADS_LIBRARY
15655 OPENTHREADS_FOUND, if false, do not try to link to OpenThreads
15656 OPENTHREADS_INCLUDE_DIR, where to find the headers
15657 $OPENTHREADS_DIR is an environment variable that would corre‐
15660 spond to the ./configure --prefix=$OPENTHREADS_DIR used in
15661 building osg.
15662 [CMake 2.8.10]: The CMake variables OPENTHREADS_DIR or OSG_DIR
15665 can now be used as well to influence detection, instead of need‐
15666 ing to specify an environment variable.
15667 Created by Eric Wing.
15670 FindPHP4
15673 Find PHP4
15674 This module finds if PHP4 is installed and determines where the
15676 include files and libraries are. It also determines what the
15677 name of the library is. This code sets the following variables:
15678 PHP4_INCLUDE_PATH = path to where php.h can be found
15681 PHP4_EXECUTABLE = full path to the php4 binary
15682 FindPNG
15688 Find the native PNG includes and library
15689 This module searches libpng, the library for working with PNG
15694 images.
15695 It defines the following variables
15698 PNG_INCLUDE_DIRS, where to find png.h, etc.
15701 PNG_LIBRARIES, the libraries to link against to use PNG.
15702 PNG_DEFINITIONS - You should add_definitons(${PNG_DEFINITIONS}) before compiling code that includes png library files.
15703 PNG_FOUND, If false, do not try to use PNG.
15704 PNG_VERSION_STRING - the version of the PNG library found (since CMake 2.8.8)
15705 Also defined, but not for general use are
15707 PNG_LIBRARY, where to find the PNG library.
15710 For backward compatiblity the variable PNG_INCLUDE_DIR is also
15712 set. It has the same value as PNG_INCLUDE_DIRS.
15713 Since PNG depends on the ZLib compression library, none of the
15716 above will be defined unless ZLib can be found.
15717 FindPackageHandleStandardArgs
15720 FIND_PACKAGE_HANDLE_STANDARD_ARGS(<name> ... )
15723 This function is intended to be used in FindXXX.cmake modules
15726 files. It handles the REQUIRED, QUIET and version-related argu‐
15727 ments to find_package(). It also sets the <packagename>_FOUND
15728 variable. The package is considered found if all variables
15729 <var1>... listed contain valid results, e.g. valid filepaths.
15730 There are two modes of this function. The first argument in both
15733 modes is the name of the Find-module where it is called (in
15734 original casing).
15735 The first simple mode looks like this:
15738 FIND_PACKAGE_HANDLE_STANDARD_ARGS(<name> (DEFAULT_MSG|"Custom failure message") <var1>...<varN> )
15741 If the variables <var1> to <varN> are all valid, then <UPPER‐
15743 CASED_NAME>_FOUND will be set to TRUE. If DEFAULT_MSG is given
15744 as second argument, then the function will generate itself use‐
15745 ful success and error messages. You can also supply a custom
15746 error message for the failure case. This is not recommended.
15747 The second mode is more powerful and also supports version
15750 checking:
15751 FIND_PACKAGE_HANDLE_STANDARD_ARGS(NAME [FOUND_VAR <resultVar>]
15754 [REQUIRED_VARS <var1>...<varN>]
15755 [VERSION_VAR <versionvar>]
15756 [HANDLE_COMPONENTS]
15757 [CONFIG_MODE]
15758 [FAIL_MESSAGE "Custom failure message"] )
15759 In this mode, the name of the result-variable can be set either
15764 to either <UPPERCASED_NAME>_FOUND or <OriginalCase_Name>_FOUND
15765 using the FOUND_VAR option. Other names for the result-variable
15766 are not allowed. So for a Find-module named FindFooBar.cmake,
15767 the two possible names are FooBar_FOUND and FOOBAR_FOUND. It is
15768 recommended to use the original case version. If the FOUND_VAR
15769 option is not used, the default is <UPPERCASED_NAME>_FOUND.
15770 As in the simple mode, if <var1> through <varN> are all valid,
15773 <packagename>_FOUND will be set to TRUE. After REQUIRED_VARS the
15774 variables which are required for this package are listed. Fol‐
15775 lowing VERSION_VAR the name of the variable can be specified
15776 which holds the version of the package which has been found. If
15777 this is done, this version will be checked against the (poten‐
15778 tially) specified required version used in the find_package()
15779 call. The EXACT keyword is also handled. The default messages
15780 include information about the required version and the version
15781 which has been actually found, both if the version is ok or not.
15782 If the package supports components, use the HANDLE_COMPONENTS
15783 option to enable handling them. In this case, find_package_han‐
15784 dle_standard_args() will report which components have been found
15785 and which are missing, and the <packagename>_FOUND variable will
15786 be set to FALSE if any of the required components (i.e. not the
15787 ones listed after OPTIONAL_COMPONENTS) are missing. Use the
15788 option CONFIG_MODE if your FindXXX.cmake module is a wrapper for
15789 a find_package(... NO_MODULE) call. In this case VERSION_VAR
15790 will be set to <NAME>_VERSION and the macro will automatically
15791 check whether the Config module was found. Via FAIL_MESSAGE a
15792 custom failure message can be specified, if this is not used,
15793 the default message will be displayed.
15794 Example for mode 1:
15797 find_package_handle_standard_args(LibXml2 DEFAULT_MSG LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
15800 LibXml2 is considered to be found, if both LIBXML2_LIBRARY and
15805 LIBXML2_INCLUDE_DIR are valid. Then also LIBXML2_FOUND is set to
15806 TRUE. If it is not found and REQUIRED was used, it fails with
15807 FATAL_ERROR, independent whether QUIET was used or not. If it is
15808 found, success will be reported, including the content of
15809 <var1>. On repeated Cmake runs, the same message won't be
15810 printed again.
15811 Example for mode 2:
15814 find_package_handle_standard_args(LibXslt FOUND_VAR LibXslt_FOUND
15817 REQUIRED_VARS LibXslt_LIBRARIES LibXslt_INCLUDE_DIRS
15818 VERSION_VAR LibXslt_VERSION_STRING)
15819 In this case, LibXslt is considered to be found if the vari‐
15821 able(s) listed after REQUIRED_VAR are all valid, i.e.
15822 LibXslt_LIBRARIES and LibXslt_INCLUDE_DIRS in this case. The
15823 result will then be stored in LibXslt_FOUND . Also the version
15824 of LibXslt will be checked by using the version contained in
15825 LibXslt_VERSION_STRING. Since no FAIL_MESSAGE is given, the
15826 default messages will be printed.
15827 Another example for mode 2:
15830 find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
15833 find_package_handle_standard_args(Automoc4 CONFIG_MODE)
15834 In this case, FindAutmoc4.cmake wraps a call to find_pack‐
15836 age(Automoc4 NO_MODULE) and adds an additional search directory
15837 for automoc4. Here the result will be stored in AUTOMOC4_FOUND.
15838 The following FIND_PACKAGE_HANDLE_STANDARD_ARGS() call produces
15839 a proper success/error message.
15840 FindPackageMessage
15843 FIND_PACKAGE_MESSAGE(<name> "message for user" "find result
15846 details")
15847 This macro is intended to be used in FindXXX.cmake modules
15850 files. It will print a message once for each unique find result.
15851 This is useful for telling the user where a package was found.
15852 The first argument specifies the name (XXX) of the package. The
15853 second argument specifies the message to display. The third
15854 argument lists details about the find result so that if they
15855 change the message will be displayed again. The macro also obeys
15856 the QUIET argument to the find_package command.
15857 Example:
15860 if(X11_FOUND)
15863 FIND_PACKAGE_MESSAGE(X11 "Found X11: ${X11_X11_LIB}"
15864 "[${X11_X11_LIB}][${X11_INCLUDE_DIR}]")
15865 else()
15866 ...
15867 endif()
15868 FindPerl
15871 Find perl
15872 this module looks for Perl
15874 PERL_EXECUTABLE - the full path to perl
15877 PERL_FOUND - If false, don't attempt to use perl.
15878 PERL_VERSION_STRING - version of perl found (since CMake 2.8.8)
15879 FindPerlLibs
15882 Find Perl libraries
15883 This module finds if PERL is installed and determines where the
15885 include files and libraries are. It also determines what the
15886 name of the library is. This code sets the following variables:
15887 PERLLIBS_FOUND = True if perl.h & libperl were found
15890 PERL_INCLUDE_PATH = path to where perl.h is found
15891 PERL_LIBRARY = path to libperl
15892 PERL_EXECUTABLE = full path to the perl binary
15893 The minimum required version of Perl can be specified using the
15898 standard syntax, e.g. find_package(PerlLibs 6.0)
15899 The following variables are also available if needed
15902 (introduced after CMake 2.6.4)
15903 PERL_SITESEARCH = path to the sitesearch install dir
15908 PERL_SITELIB = path to the sitelib install directory
15909 PERL_VENDORARCH = path to the vendor arch install directory
15910 PERL_VENDORLIB = path to the vendor lib install directory
15911 PERL_ARCHLIB = path to the arch lib install directory
15912 PERL_PRIVLIB = path to the priv lib install directory
15913 PERL_EXTRA_C_FLAGS = Compilation flags used to build perl
15914 FindPhysFS
15920 Locate PhysFS library This module defines PHYSFS_LIBRARY, the
15923 name of the library to link against PHYSFS_FOUND, if false, do
15924 not try to link to PHYSFS PHYSFS_INCLUDE_DIR, where to find
15925 physfs.h
15926 $PHYSFSDIR is an environment variable that would correspond to
15929 the ./configure --prefix=$PHYSFSDIR used in building PHYSFS.
15930 Created by Eric Wing.
15933 FindPike
15936 Find Pike
15937 This module finds if PIKE is installed and determines where the
15939 include files and libraries are. It also determines what the
15940 name of the library is. This code sets the following variables:
15941 PIKE_INCLUDE_PATH = path to where program.h is found
15944 PIKE_EXECUTABLE = full path to the pike binary
15945 FindPkgConfig
15951 a pkg-config module for CMake
15952 Usage:
15957 pkg_check_modules(<PREFIX> [REQUIRED] [QUIET] <MODULE> [<MODULE>]*)
15960 checks for all the given modules
15961 pkg_search_module(<PREFIX> [REQUIRED] [QUIET] <MODULE> [<MODULE>]*)
15966 checks for given modules and uses the first working one
15967 When the 'REQUIRED' argument was set, macros will fail with an
15972 error when module(s) could not be found
15973 When the 'QUIET' argument is set, no status messages will be
15976 printed.
15977 It sets the following variables:
15980 PKG_CONFIG_FOUND ... if pkg-config executable was found
15983 PKG_CONFIG_EXECUTABLE ... pathname of the pkg-config program
15984 PKG_CONFIG_VERSION_STRING ... the version of the pkg-config program found
15985 (since CMake 2.8.8)
15986 For the following variables two sets of values exist; first one
15991 is the common one and has the given PREFIX. The second set con‐
15992 tains flags which are given out when pkgconfig was called with
15993 the '--static' option.
15994 <XPREFIX>_FOUND ... set to 1 if module(s) exist
15997 <XPREFIX>_LIBRARIES ... only the libraries (w/o the '-l')
15998 <XPREFIX>_LIBRARY_DIRS ... the paths of the libraries (w/o the '-L')
15999 <XPREFIX>_LDFLAGS ... all required linker flags
16000 <XPREFIX>_LDFLAGS_OTHER ... all other linker flags
16001 <XPREFIX>_INCLUDE_DIRS ... the '-I' preprocessor flags (w/o the '-I')
16002 <XPREFIX>_CFLAGS ... all required cflags
16003 <XPREFIX>_CFLAGS_OTHER ... the other compiler flags
16004 <XPREFIX> = <PREFIX> for common case
16009 <XPREFIX> = <PREFIX>_STATIC for static linking
16010 There are some special variables whose prefix depends on the
16015 count of given modules. When there is only one module, <PREFIX>
16016 stays unchanged. When there are multiple modules, the prefix
16017 will be changed to <PREFIX>_<MODNAME>:
16018 <XPREFIX>_VERSION ... version of the module
16021 <XPREFIX>_PREFIX ... prefix-directory of the module
16022 <XPREFIX>_INCLUDEDIR ... include-dir of the module
16023 <XPREFIX>_LIBDIR ... lib-dir of the module
16024 <XPREFIX> = <PREFIX> when |MODULES| == 1, else
16029 <XPREFIX> = <PREFIX>_<MODNAME>
16030 A <MODULE> parameter can have the following formats:
16035 {MODNAME} ... matches any version
16038 {MODNAME}>={VERSION} ... at least version <VERSION> is required
16039 {MODNAME}={VERSION} ... exactly version <VERSION> is required
16040 {MODNAME}<={VERSION} ... modules must not be newer than <VERSION>
16041 Examples
16046 pkg_check_modules (GLIB2 glib-2.0)
16049 pkg_check_modules (GLIB2 glib-2.0>=2.10)
16054 requires at least version 2.10 of glib2 and defines e.g.
16055 GLIB2_VERSION=2.10.3
16056 pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0)
16061 requires both glib2 and gtk2, and defines e.g.
16062 FOO_glib-2.0_VERSION=2.10.3
16063 FOO_gtk+-2.0_VERSION=2.8.20
16064 pkg_check_modules (XRENDER REQUIRED xrender)
16069 defines e.g.:
16070 XRENDER_LIBRARIES=Xrender;X11
16071 XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp
16072 pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2)
16077 FindPostgreSQL
16080 Find the PostgreSQL installation.
16081 In Windows, we make the assumption that, if the PostgreSQL files
16083 are installed, the default directory will be C:\Program
16084 Files\PostgreSQL.
16085 This module defines
16088 PostgreSQL_LIBRARIES - the PostgreSQL libraries needed for linking
16091 PostgreSQL_INCLUDE_DIRS - the directories of the PostgreSQL headers
16092 PostgreSQL_VERSION_STRING - the version of PostgreSQL found (since CMake 2.8.8)
16093 FindProducer
16096 Though Producer isn't directly part of OpenSceneGraph, its pri‐
16099 mary user is OSG so I consider this part of the Findosg* suite
16100 used to find OpenSceneGraph components. You'll notice that I
16101 accept OSGDIR as an environment path.
16102 Each component is separate and you must opt in to each module.
16105 You must also opt into OpenGL (and OpenThreads?) as these mod‐
16106 ules won't do it for you. This is to allow you control over your
16107 own system piece by piece in case you need to opt out of certain
16108 components or change the Find behavior for a particular module
16109 (perhaps because the default FindOpenGL.cmake module doesn't
16110 work with your system as an example). If you want to use a more
16111 convenient module that includes everything, use the FindOpen‐
16112 SceneGraph.cmake instead of the Findosg*.cmake modules.
16113 Locate Producer This module defines PRODUCER_LIBRARY PRO‐
16116 DUCER_FOUND, if false, do not try to link to Producer PRO‐
16117 DUCER_INCLUDE_DIR, where to find the headers
16118 $PRODUCER_DIR is an environment variable that would correspond
16121 to the ./configure --prefix=$PRODUCER_DIR used in building osg.
16122 Created by Eric Wing.
16125 FindProtobuf
16128 Locate and configure the Google Protocol Buffers library.
16131 The following variables can be set and are optional:
16134 PROTOBUF_SRC_ROOT_FOLDER - When compiling with MSVC, if this cache variable is set
16137 the protobuf-default VS project build locations
16138 (vsprojects/Debug & vsprojects/Release) will be searched
16139 for libraries and binaries.
16140 PROTOBUF_IMPORT_DIRS - List of additional directories to be searched for
16145 imported .proto files. (New in CMake 2.8.8)
16146 Defines the following variables:
16151 PROTOBUF_FOUND - Found the Google Protocol Buffers library (libprotobuf & header files)
16154 PROTOBUF_INCLUDE_DIRS - Include directories for Google Protocol Buffers
16155 PROTOBUF_LIBRARIES - The protobuf libraries
16156 [New in CMake 2.8.5]
16158 PROTOBUF_PROTOC_LIBRARIES - The protoc libraries
16161 PROTOBUF_LITE_LIBRARIES - The protobuf-lite libraries
16162 The following cache variables are also available to set or use:
16167 PROTOBUF_LIBRARY - The protobuf library
16170 PROTOBUF_PROTOC_LIBRARY - The protoc library
16171 PROTOBUF_INCLUDE_DIR - The include directory for protocol buffers
16172 PROTOBUF_PROTOC_EXECUTABLE - The protoc compiler
16173 [New in CMake 2.8.5]
16175 PROTOBUF_LIBRARY_DEBUG - The protobuf library (debug)
16178 PROTOBUF_PROTOC_LIBRARY_DEBUG - The protoc library (debug)
16179 PROTOBUF_LITE_LIBRARY - The protobuf lite library
16180 PROTOBUF_LITE_LIBRARY_DEBUG - The protobuf lite library (debug)
16181 ====================================================================
16186 Example:
16187 find_package(Protobuf REQUIRED)
16192 include_directories(${PROTOBUF_INCLUDE_DIRS})
16193 include_directories(${CMAKE_CURRENT_BINARY_DIR})
16198 PROTOBUF_GENERATE_CPP(PROTO_SRCS PROTO_HDRS foo.proto)
16199 add_executable(bar bar.cc ${PROTO_SRCS} ${PROTO_HDRS})
16200 target_link_libraries(bar ${PROTOBUF_LIBRARIES})
16201 NOTE: You may need to link against pthreads, depending
16206 on the platform.
16209 NOTE: The PROTOBUF_GENERATE_CPP macro & add_executable() or
16214 add_library()
16215 calls only work properly within the same directory.
16218 ====================================================================
16223 PROTOBUF_GENERATE_CPP (public function)
16228 SRCS = Variable to define with autogenerated
16231 source files
16232 HDRS = Variable to define with autogenerated
16233 header files
16234 ARGN = proto files
16235 ====================================================================
16240 FindPythonInterp
16243 Find python interpreter
16244 This module finds if Python interpreter is installed and deter‐
16246 mines where the executables are. This code sets the following
16247 variables:
16248 PYTHONINTERP_FOUND - Was the Python executable found
16251 PYTHON_EXECUTABLE - path to the Python interpreter
16252 PYTHON_VERSION_STRING - Python version found e.g. 2.5.2
16257 PYTHON_VERSION_MAJOR - Python major version found e.g. 2
16258 PYTHON_VERSION_MINOR - Python minor version found e.g. 5
16259 PYTHON_VERSION_PATCH - Python patch version found e.g. 2
16260 The Python_ADDITIONAL_VERSIONS variable can be used to specify a
16265 list of version numbers that should be taken into account when
16266 searching for Python. You need to set this variable before call‐
16267 ing find_package(PythonInterp).
16268 FindPythonLibs
16271 Find python libraries
16272 This module finds if Python is installed and determines where
16274 the include files and libraries are. It also determines what the
16275 name of the library is. This code sets the following variables:
16276 PYTHONLIBS_FOUND - have the Python libs been found
16279 PYTHON_LIBRARIES - path to the python library
16280 PYTHON_INCLUDE_PATH - path to where Python.h is found (deprecated)
16281 PYTHON_INCLUDE_DIRS - path to where Python.h is found
16282 PYTHON_DEBUG_LIBRARIES - path to the debug library (deprecated)
16283 PYTHONLIBS_VERSION_STRING - version of the Python libs found (since CMake 2.8.8)
16284 The Python_ADDITIONAL_VERSIONS variable can be used to specify a
16289 list of version numbers that should be taken into account when
16290 searching for Python. You need to set this variable before call‐
16291 ing find_package(PythonLibs).
16292 If you'd like to specify the installation of Python to use, you
16295 should modify the following cache variables:
16296 PYTHON_LIBRARY - path to the python library
16299 PYTHON_INCLUDE_DIR - path to where Python.h is found
16300 FindQt Searches for all installed versions of Qt.
16303 This should only be used if your project can work with multiple
16305 versions of Qt. If not, you should just directly use FindQt4 or
16306 FindQt3. If multiple versions of Qt are found on the machine,
16307 then The user must set the option DESIRED_QT_VERSION to the ver‐
16308 sion they want to use. If only one version of qt is found on
16309 the machine, then the DESIRED_QT_VERSION is set to that version
16310 and the matching FindQt3 or FindQt4 module is included. Once the
16311 user sets DESIRED_QT_VERSION, then the FindQt3 or FindQt4 module
16312 is included.
16313 QT_REQUIRED if this is set to TRUE then if CMake can
16316 not find Qt4 or Qt3 an error is raised
16317 and a message is sent to the user.
16318 DESIRED_QT_VERSION OPTION is created
16323 QT4_INSTALLED is set to TRUE if qt4 is found.
16324 QT3_INSTALLED is set to TRUE if qt3 is found.
16325 FindQt3
16328 Locate Qt include paths and libraries
16329 This module defines:
16331 QT_INCLUDE_DIR - where to find qt.h, etc.
16334 QT_LIBRARIES - the libraries to link against to use Qt.
16335 QT_DEFINITIONS - definitions to use when
16336 compiling code that uses Qt.
16337 QT_FOUND - If false, don't try to use Qt.
16338 QT_VERSION_STRING - the version of Qt found
16339 If you need the multithreaded version of Qt, set QT_MT_REQUIRED
16344 to TRUE
16345 Also defined, but not for general use are:
16348 QT_MOC_EXECUTABLE, where to find the moc tool.
16351 QT_UIC_EXECUTABLE, where to find the uic tool.
16352 QT_QT_LIBRARY, where to find the Qt library.
16353 QT_QTMAIN_LIBRARY, where to find the qtmain
16354 library. This is only required by Qt3 on Windows.
16355 FindQt4
16358 Find Qt 4
16359 This module can be used to find Qt4. The most important issue is
16361 that the Qt4 qmake is available via the system path. This qmake
16362 is then used to detect basically everything else. This module
16363 defines a number of key variables and macros. The variable
16364 QT_USE_FILE is set which is the path to a CMake file that can be
16365 included to compile Qt 4 applications and libraries. It sets up
16366 the compilation environment for include directories, preproces‐
16367 sor defines and populates a QT_LIBRARIES variable.
16368 Typical usage could be something like:
16371 find_package(Qt4 4.4.3 REQUIRED QtCore QtGui QtXml)
16374 include(${QT_USE_FILE})
16375 add_executable(myexe main.cpp)
16376 target_link_libraries(myexe ${QT_LIBRARIES})
16377 The minimum required version can be specified using the standard
16382 find_package()-syntax (see example above). For compatibility
16383 with older versions of FindQt4.cmake it is also possible to set
16384 the variable QT_MIN_VERSION to the minimum required version of
16385 Qt4 before the find_package(Qt4) command. If both are used, the
16386 version used in the find_package() command overrides the one
16387 from QT_MIN_VERSION.
16388 When using the components argument, QT_USE_QT* variables are
16391 automatically set for the QT_USE_FILE to pick up. If one wishes
16392 to manually set them, the available ones to set include:
16393 QT_DONT_USE_QTCORE
16396 QT_DONT_USE_QTGUI
16397 QT_USE_QT3SUPPORT
16398 QT_USE_QTASSISTANT
16399 QT_USE_QAXCONTAINER
16400 QT_USE_QAXSERVER
16401 QT_USE_QTDESIGNER
16402 QT_USE_QTMOTIF
16403 QT_USE_QTMAIN
16404 QT_USE_QTMULTIMEDIA
16405 QT_USE_QTNETWORK
16406 QT_USE_QTNSPLUGIN
16407 QT_USE_QTOPENGL
16408 QT_USE_QTSQL
16409 QT_USE_QTXML
16410 QT_USE_QTSVG
16411 QT_USE_QTTEST
16412 QT_USE_QTUITOOLS
16413 QT_USE_QTDBUS
16414 QT_USE_QTSCRIPT
16415 QT_USE_QTASSISTANTCLIENT
16416 QT_USE_QTHELP
16417 QT_USE_QTWEBKIT
16418 QT_USE_QTXMLPATTERNS
16419 QT_USE_PHONON
16420 QT_USE_QTSCRIPTTOOLS
16421 QT_USE_QTDECLARATIVE
16422 QT_USE_IMPORTED_TARGETS
16427 If this variable is set to TRUE, FindQt4.cmake will create imported
16428 library targets for the various Qt libraries and set the
16429 library variables like QT_QTCORE_LIBRARY to point at these imported
16430 targets instead of the library file on disk. This provides much better
16431 handling of the release and debug versions of the Qt libraries and is
16432 also always backwards compatible, except for the case that dependencies
16433 of libraries are exported, these will then also list the names of the
16434 imported targets as dependency and not the file location on disk. This
16435 is much more flexible, but requires that FindQt4.cmake is executed before
16436 such an exported dependency file is processed.
16437 Note that if using IMPORTED targets, the qtmain.lib static library is
16442 automatically linked on Windows. To disable that globally, set the
16443 QT4_NO_LINK_QTMAIN variable before finding Qt4. To disable that for a
16444 particular executable, set the QT4_NO_LINK_QTMAIN target property to
16445 True on the executable.
16446 QT_INCLUDE_DIRS_NO_SYSTEM
16451 If this variable is set to TRUE, the Qt include directories
16452 in the QT_USE_FILE will NOT have the SYSTEM keyword set.
16453 There are also some files that need processing by some Qt tools
16458 such as moc and uic. Listed below are macros that may be used
16459 to process those files.
16460 macro QT4_WRAP_CPP(outfiles inputfile ... OPTIONS ...)
16463 create moc code from a list of files containing Qt class with
16464 the Q_OBJECT declaration. Per-directory preprocessor definitions
16465 are also added. Options may be given to moc, such as those found
16466 when executing "moc -help".
16467 macro QT4_WRAP_UI(outfiles inputfile ... OPTIONS ...)
16472 create code from a list of Qt designer ui files.
16473 Options may be given to uic, such as those found
16474 when executing "uic -help"
16475 macro QT4_ADD_RESOURCES(outfiles inputfile ... OPTIONS ...)
16480 create code from a list of Qt resource files.
16481 Options may be given to rcc, such as those found
16482 when executing "rcc -help"
16483 macro QT4_GENERATE_MOC(inputfile outputfile )
16488 creates a rule to run moc on infile and create outfile.
16489 Use this if for some reason QT4_WRAP_CPP() isn't appropriate, e.g.
16490 because you need a custom filename for the moc file or something similar.
16491 macro QT4_AUTOMOC(sourcefile1 sourcefile2 ... )
16496 The qt4_automoc macro is obsolete. Use the CMAKE_AUTOMOC feature instead.
16497 This macro is still experimental.
16498 It can be used to have moc automatically handled.
16499 So if you have the files foo.h and foo.cpp, and in foo.h a
16500 a class uses the Q_OBJECT macro, moc has to run on it. If you don't
16501 want to use QT4_WRAP_CPP() (which is reliable and mature), you can insert
16502 #include "foo.moc"
16503 in foo.cpp and then give foo.cpp as argument to QT4_AUTOMOC(). This will the
16504 scan all listed files at cmake-time for such included moc files and if it finds
16505 them cause a rule to be generated to run moc at build time on the
16506 accompanying header file foo.h.
16507 If a source file has the SKIP_AUTOMOC property set it will be ignored by this macro.
16508 You should have a look on the AUTOMOC property for targets to achieve the same results.
16513 macro QT4_ADD_DBUS_INTERFACE(outfiles interface basename)
16518 Create the interface header and implementation files with the
16519 given basename from the given interface xml file and add it to
16520 the list of sources.
16521 You can pass additional parameters to the qdbusxml2cpp call by setting
16526 properties on the input file:
16527 INCLUDE the given file will be included in the generate interface header
16532 CLASSNAME the generated class is named accordingly
16537 NO_NAMESPACE the generated class is not wrapped in a namespace
16542 macro QT4_ADD_DBUS_INTERFACES(outfiles inputfile ... )
16547 Create the interface header and implementation files
16548 for all listed interface xml files.
16549 The basename will be automatically determined from the name of the xml file.
16550 The source file properties described for QT4_ADD_DBUS_INTERFACE also apply here.
16555 macro QT4_ADD_DBUS_ADAPTOR(outfiles xmlfile parentheader parentclassname [basename] [classname])
16560 create a dbus adaptor (header and implementation file) from the xml file
16561 describing the interface, and add it to the list of sources. The adaptor
16562 forwards the calls to a parent class, defined in parentheader and named
16563 parentclassname. The name of the generated files will be
16564 <basename>adaptor.{cpp,h} where basename defaults to the basename of the xml file.
16565 If <classname> is provided, then it will be used as the classname of the
16566 adaptor itself.
16567 macro QT4_GENERATE_DBUS_INTERFACE( header [interfacename] OPTIONS ...)
16572 generate the xml interface file from the given header.
16573 If the optional argument interfacename is omitted, the name of the
16574 interface file is constructed from the basename of the header with
16575 the suffix .xml appended.
16576 Options may be given to qdbuscpp2xml, such as those found when executing "qdbuscpp2xml --help"
16577 macro QT4_CREATE_TRANSLATION( qm_files directories ... sources ...
16582 ts_files ... OPTIONS ...)
16583 out: qm_files
16584 in: directories sources ts_files
16585 options: flags to pass to lupdate, such as -extensions to specify
16586 extensions for a directory scan.
16587 generates commands to create .ts (vie lupdate) and .qm
16588 (via lrelease) - files from directories and/or sources. The ts files are
16589 created and/or updated in the source tree (unless given with full paths).
16590 The qm files are generated in the build tree.
16591 Updating the translations can be done by adding the qm_files
16592 to the source list of your library/executable, so they are
16593 always updated, or by adding a custom target to control when
16594 they get updated/generated.
16595 macro QT4_ADD_TRANSLATION( qm_files ts_files ... )
16600 out: qm_files
16601 in: ts_files
16602 generates commands to create .qm from .ts - files. The generated
16603 filenames can be found in qm_files. The ts_files
16604 must exist and are not updated in any way.
16605 function QT4_USE_MODULES( target [link_type] modules...)
16610 This function is obsolete. Use target_link_libraries with IMPORTED targets instead.
16613 Make <target> use the <modules> from Qt. Using a Qt module means
16614 to link to the library, add the relevant include directories for the module,
16615 and add the relevant compiler defines for using the module.
16616 Modules are roughly equivalent to components of Qt4, so usage would be
16617 something like:
16618 qt4_use_modules(myexe Core Gui Declarative)
16619 to use QtCore, QtGui and QtDeclarative. The optional <link_type> argument can
16620 be specified as either LINK_PUBLIC or LINK_PRIVATE to specify the same argument
16621 to the target_link_libraries call.
16622 Below is a detailed list of variables that FindQt4.cmake sets.
16630 QT_FOUND If false, don't try to use Qt.
16631 Qt4_FOUND If false, don't try to use Qt 4.
16632 QT4_FOUND If false, don't try to use Qt 4. This variable is for compatibility only.
16633 QT_VERSION_MAJOR The major version of Qt found.
16638 QT_VERSION_MINOR The minor version of Qt found.
16639 QT_VERSION_PATCH The patch version of Qt found.
16640 QT_EDITION Set to the edition of Qt (i.e. DesktopLight)
16645 QT_EDITION_DESKTOPLIGHT True if QT_EDITION == DesktopLight
16646 QT_QTCORE_FOUND True if QtCore was found.
16647 QT_QTGUI_FOUND True if QtGui was found.
16648 QT_QT3SUPPORT_FOUND True if Qt3Support was found.
16649 QT_QTASSISTANT_FOUND True if QtAssistant was found.
16650 QT_QTASSISTANTCLIENT_FOUND True if QtAssistantClient was found.
16651 QT_QAXCONTAINER_FOUND True if QAxContainer was found (Windows only).
16652 QT_QAXSERVER_FOUND True if QAxServer was found (Windows only).
16653 QT_QTDBUS_FOUND True if QtDBus was found.
16654 QT_QTDESIGNER_FOUND True if QtDesigner was found.
16655 QT_QTDESIGNERCOMPONENTS True if QtDesignerComponents was found.
16656 QT_QTHELP_FOUND True if QtHelp was found.
16657 QT_QTMOTIF_FOUND True if QtMotif was found.
16658 QT_QTMULTIMEDIA_FOUND True if QtMultimedia was found (since Qt 4.6.0).
16659 QT_QTNETWORK_FOUND True if QtNetwork was found.
16660 QT_QTNSPLUGIN_FOUND True if QtNsPlugin was found.
16661 QT_QTOPENGL_FOUND True if QtOpenGL was found.
16662 QT_QTSQL_FOUND True if QtSql was found.
16663 QT_QTSVG_FOUND True if QtSvg was found.
16664 QT_QTSCRIPT_FOUND True if QtScript was found.
16665 QT_QTSCRIPTTOOLS_FOUND True if QtScriptTools was found.
16666 QT_QTTEST_FOUND True if QtTest was found.
16667 QT_QTUITOOLS_FOUND True if QtUiTools was found.
16668 QT_QTWEBKIT_FOUND True if QtWebKit was found.
16669 QT_QTXML_FOUND True if QtXml was found.
16670 QT_QTXMLPATTERNS_FOUND True if QtXmlPatterns was found.
16671 QT_PHONON_FOUND True if phonon was found.
16672 QT_QTDECLARATIVE_FOUND True if QtDeclarative was found.
16673 QT_MAC_USE_COCOA For Mac OS X, its whether Cocoa or Carbon is used.
16678 In general, this should not be used, but its useful
16679 when having platform specific code.
16680 QT_DEFINITIONS Definitions to use when compiling code that uses Qt.
16685 You do not need to use this if you include QT_USE_FILE.
16686 The QT_USE_FILE will also define QT_DEBUG and QT_NO_DEBUG
16687 to fit your current build type. Those are not contained
16688 in QT_DEFINITIONS.
16689 QT_INCLUDES List of paths to all include directories of
16694 Qt4 QT_INCLUDE_DIR and QT_QTCORE_INCLUDE_DIR are
16695 always in this variable even if NOTFOUND,
16696 all other INCLUDE_DIRS are
16697 only added if they are found.
16698 You do not need to use this if you include QT_USE_FILE.
16699 Include directories for the Qt modules are listed here.
16707 You do not need to use these variables if you include QT_USE_FILE.
16708 QT_INCLUDE_DIR Path to "include" of Qt4
16713 QT_QT3SUPPORT_INCLUDE_DIR Path to "include/Qt3Support"
16714 QT_QTASSISTANT_INCLUDE_DIR Path to "include/QtAssistant"
16715 QT_QTASSISTANTCLIENT_INCLUDE_DIR Path to "include/QtAssistant"
16716 QT_QAXCONTAINER_INCLUDE_DIR Path to "include/ActiveQt" (Windows only)
16717 QT_QAXSERVER_INCLUDE_DIR Path to "include/ActiveQt" (Windows only)
16718 QT_QTCORE_INCLUDE_DIR Path to "include/QtCore"
16719 QT_QTDBUS_INCLUDE_DIR Path to "include/QtDBus"
16720 QT_QTDESIGNER_INCLUDE_DIR Path to "include/QtDesigner"
16721 QT_QTDESIGNERCOMPONENTS_INCLUDE_DIR Path to "include/QtDesigner"
16722 QT_QTGUI_INCLUDE_DIR Path to "include/QtGui"
16723 QT_QTHELP_INCLUDE_DIR Path to "include/QtHelp"
16724 QT_QTMOTIF_INCLUDE_DIR Path to "include/QtMotif"
16725 QT_QTMULTIMEDIA_INCLUDE_DIR Path to "include/QtMultimedia"
16726 QT_QTNETWORK_INCLUDE_DIR Path to "include/QtNetwork"
16727 QT_QTNSPLUGIN_INCLUDE_DIR Path to "include/QtNsPlugin"
16728 QT_QTOPENGL_INCLUDE_DIR Path to "include/QtOpenGL"
16729 QT_QTSCRIPT_INCLUDE_DIR Path to "include/QtScript"
16730 QT_QTSQL_INCLUDE_DIR Path to "include/QtSql"
16731 QT_QTSVG_INCLUDE_DIR Path to "include/QtSvg"
16732 QT_QTTEST_INCLUDE_DIR Path to "include/QtTest"
16733 QT_QTWEBKIT_INCLUDE_DIR Path to "include/QtWebKit"
16734 QT_QTXML_INCLUDE_DIR Path to "include/QtXml"
16735 QT_QTXMLPATTERNS_INCLUDE_DIR Path to "include/QtXmlPatterns"
16736 QT_PHONON_INCLUDE_DIR Path to "include/phonon"
16737 QT_QTSCRIPTTOOLS_INCLUDE_DIR Path to "include/QtScriptTools"
16738 QT_QTDECLARATIVE_INCLUDE_DIR Path to "include/QtDeclarative"
16739 QT_BINARY_DIR Path to "bin" of Qt4
16744 QT_LIBRARY_DIR Path to "lib" of Qt4
16745 QT_PLUGINS_DIR Path to "plugins" for Qt4
16746 QT_TRANSLATIONS_DIR Path to "translations" of Qt4
16747 QT_IMPORTS_DIR Path to "imports" of Qt4
16748 QT_DOC_DIR Path to "doc" of Qt4
16749 QT_MKSPECS_DIR Path to "mkspecs" of Qt4
16750 The Qt toolkit may contain both debug and release libraries. In
16758 that case, the following library variables will contain both.
16759 You do not need to use these variables if you include
16760 QT_USE_FILE, and use QT_LIBRARIES.
16761 QT_QT3SUPPORT_LIBRARY The Qt3Support library
16764 QT_QTASSISTANT_LIBRARY The QtAssistant library
16765 QT_QTASSISTANTCLIENT_LIBRARY The QtAssistantClient library
16766 QT_QAXCONTAINER_LIBRARY The QAxContainer library (Windows only)
16767 QT_QAXSERVER_LIBRARY The QAxServer library (Windows only)
16768 QT_QTCORE_LIBRARY The QtCore library
16769 QT_QTDBUS_LIBRARY The QtDBus library
16770 QT_QTDESIGNER_LIBRARY The QtDesigner library
16771 QT_QTDESIGNERCOMPONENTS_LIBRARY The QtDesignerComponents library
16772 QT_QTGUI_LIBRARY The QtGui library
16773 QT_QTHELP_LIBRARY The QtHelp library
16774 QT_QTMOTIF_LIBRARY The QtMotif library
16775 QT_QTMULTIMEDIA_LIBRARY The QtMultimedia library
16776 QT_QTNETWORK_LIBRARY The QtNetwork library
16777 QT_QTNSPLUGIN_LIBRARY The QtNsPLugin library
16778 QT_QTOPENGL_LIBRARY The QtOpenGL library
16779 QT_QTSCRIPT_LIBRARY The QtScript library
16780 QT_QTSQL_LIBRARY The QtSql library
16781 QT_QTSVG_LIBRARY The QtSvg library
16782 QT_QTTEST_LIBRARY The QtTest library
16783 QT_QTUITOOLS_LIBRARY The QtUiTools library
16784 QT_QTWEBKIT_LIBRARY The QtWebKit library
16785 QT_QTXML_LIBRARY The QtXml library
16786 QT_QTXMLPATTERNS_LIBRARY The QtXmlPatterns library
16787 QT_QTMAIN_LIBRARY The qtmain library for Windows
16788 QT_PHONON_LIBRARY The phonon library
16789 QT_QTSCRIPTTOOLS_LIBRARY The QtScriptTools library
16790 The QtDeclarative library: QT_QTDECLARATIVE_LIBRARY
16795 also defined, but NOT for general use are
16798 QT_MOC_EXECUTABLE Where to find the moc tool.
16801 QT_UIC_EXECUTABLE Where to find the uic tool.
16802 QT_UIC3_EXECUTABLE Where to find the uic3 tool.
16803 QT_RCC_EXECUTABLE Where to find the rcc tool
16804 QT_DBUSCPP2XML_EXECUTABLE Where to find the qdbuscpp2xml tool.
16805 QT_DBUSXML2CPP_EXECUTABLE Where to find the qdbusxml2cpp tool.
16806 QT_LUPDATE_EXECUTABLE Where to find the lupdate tool.
16807 QT_LRELEASE_EXECUTABLE Where to find the lrelease tool.
16808 QT_QCOLLECTIONGENERATOR_EXECUTABLE Where to find the qcollectiongenerator tool.
16809 QT_DESIGNER_EXECUTABLE Where to find the Qt designer tool.
16810 QT_LINGUIST_EXECUTABLE Where to find the Qt linguist tool.
16811 These are around for backwards compatibility they will be set
16819 QT_WRAP_CPP Set true if QT_MOC_EXECUTABLE is found
16822 QT_WRAP_UI Set true if QT_UIC_EXECUTABLE is found
16823 These variables do _NOT_ have any effect anymore (compared to
16828 FindQt.cmake)
16829 QT_MT_REQUIRED Qt4 is now always multithreaded
16832 These variables are set to "" Because Qt structure changed (They
16837 make no sense in Qt4)
16838 QT_QT_LIBRARY Qt-Library is now split
16841 FindQuickTime
16844 Locate QuickTime This module defines QUICKTIME_LIBRARY QUICK‐
16847 TIME_FOUND, if false, do not try to link to gdal QUICK‐
16848 TIME_INCLUDE_DIR, where to find the headers
16849 $QUICKTIME_DIR is an environment variable that would correspond
16852 to the ./configure --prefix=$QUICKTIME_DIR
16853 Created by Eric Wing.
16856 FindRTI
16859 Try to find M&S HLA RTI libraries
16860 This module finds if any HLA RTI is installed and locates the
16862 standard RTI include files and libraries.
16863 RTI is a simulation infrastructure standardized by IEEE and
16866 SISO. It has a well defined C++ API that assures that simulation
16867 applications are independent on a particular RTI implementation.
16868 http://en.wikipedia.org/wiki/Run-Time_Infrastructure_(simulation)
16871 This code sets the following variables:
16876 RTI_INCLUDE_DIR = the directory where RTI includes file are found
16879 RTI_LIBRARIES = The libraries to link against to use RTI
16880 RTI_DEFINITIONS = -DRTI_USES_STD_FSTREAM
16881 RTI_FOUND = Set to FALSE if any HLA RTI was not found
16882 Report problems to <certi-devel@nongnu.org>
16887 FindRuby
16890 Find Ruby
16891 This module finds if Ruby is installed and determines where the
16893 include files and libraries are. Ruby 1.8 and 1.9 are supported.
16894 The minimum required version of Ruby can be specified using the
16897 standard syntax, e.g. find_package(Ruby 1.8)
16898 It also determines what the name of the library is. This code
16901 sets the following variables:
16902 RUBY_EXECUTABLE = full path to the ruby binary
16905 RUBY_INCLUDE_DIRS = include dirs to be used when using the ruby library
16906 RUBY_LIBRARY = full path to the ruby library
16907 RUBY_VERSION = the version of ruby which was found, e.g. "1.8.7"
16908 RUBY_FOUND = set to true if ruby ws found successfully
16909 RUBY_INCLUDE_PATH = same as RUBY_INCLUDE_DIRS, only provided for compatibility reasons, don't use it
16914 FindSDL
16917 Locate SDL library
16918 This module defines
16920 SDL_LIBRARY, the name of the library to link against
16923 SDL_FOUND, if false, do not try to link to SDL
16924 SDL_INCLUDE_DIR, where to find SDL.h
16925 SDL_VERSION_STRING, human-readable string containing the version of SDL
16926 This module responds to the the flag:
16931 SDL_BUILDING_LIBRARY
16934 If this is defined, then no SDL_main will be linked in because
16935 only applications need main().
16936 Otherwise, it is assumed you are building an application and this
16937 module will attempt to locate and set the the proper link flags
16938 as part of the returned SDL_LIBRARY variable.
16939 Don't forget to include SDLmain.h and SDLmain.m your project for
16944 the OS X framework based version. (Other versions link to -lSDL‐
16945 main which this module will try to find on your behalf.) Also
16946 for OS X, this module will automatically add the -framework
16947 Cocoa on your behalf.
16948 Additional Note: If you see an empty SDL_LIBRARY_TEMP in your
16954 configuration and no SDL_LIBRARY, it means CMake did not find
16955 your SDL library (SDL.dll, libsdl.so, SDL.framework, etc). Set
16956 SDL_LIBRARY_TEMP to point to your SDL library, and configure
16957 again. Similarly, if you see an empty SDLMAIN_LIBRARY, you
16958 should set this value as appropriate. These values are used to
16959 generate the final SDL_LIBRARY variable, but when these values
16960 are unset, SDL_LIBRARY does not get created.
16961 $SDLDIR is an environment variable that would correspond to the
16967 ./configure --prefix=$SDLDIR used in building SDL. l.e.galup
16968 9-20-02
16969 Modified by Eric Wing. Added code to assist with automated
16972 building by using environmental variables and providing a more
16973 controlled/consistent search behavior. Added new modifications
16974 to recognize OS X frameworks and additional Unix paths (FreeBSD,
16975 etc). Also corrected the header search path to follow "proper"
16976 SDL guidelines. Added a search for SDLmain which is needed by
16977 some platforms. Added a search for threads which is needed by
16978 some platforms. Added needed compile switches for MinGW.
16979 On OSX, this will prefer the Framework version (if found) over
16982 others. People will have to manually change the cache values of
16983 SDL_LIBRARY to override this selection or set the CMake environ‐
16984 ment CMAKE_INCLUDE_PATH to modify the search paths.
16985 Note that the header path has changed from SDL/SDL.h to just
16988 SDL.h This needed to change because "proper" SDL convention is
16989 #include "SDL.h", not <SDL/SDL.h>. This is done for portability
16990 reasons because not all systems place things in SDL/ (see Free‐
16991 BSD).
16992 FindSDL_image
16995 Locate SDL_image library
16996 This module defines:
16998 SDL_IMAGE_LIBRARIES, the name of the library to link against
17001 SDL_IMAGE_INCLUDE_DIRS, where to find the headers
17002 SDL_IMAGE_FOUND, if false, do not try to link against
17003 SDL_IMAGE_VERSION_STRING - human-readable string containing the version of SDL_image
17004 For backward compatiblity the following variables are also set:
17009 SDLIMAGE_LIBRARY (same value as SDL_IMAGE_LIBRARIES)
17012 SDLIMAGE_INCLUDE_DIR (same value as SDL_IMAGE_INCLUDE_DIRS)
17013 SDLIMAGE_FOUND (same value as SDL_IMAGE_FOUND)
17014 $SDLDIR is an environment variable that would correspond to the
17019 ./configure --prefix=$SDLDIR used in building SDL.
17020 Created by Eric Wing. This was influenced by the FindSDL.cmake
17023 module, but with modifications to recognize OS X frameworks and
17024 additional Unix paths (FreeBSD, etc).
17025 FindSDL_mixer
17028 Locate SDL_mixer library
17029 This module defines:
17031 SDL_MIXER_LIBRARIES, the name of the library to link against
17034 SDL_MIXER_INCLUDE_DIRS, where to find the headers
17035 SDL_MIXER_FOUND, if false, do not try to link against
17036 SDL_MIXER_VERSION_STRING - human-readable string containing the version of SDL_mixer
17037 For backward compatiblity the following variables are also set:
17042 SDLMIXER_LIBRARY (same value as SDL_MIXER_LIBRARIES)
17045 SDLMIXER_INCLUDE_DIR (same value as SDL_MIXER_INCLUDE_DIRS)
17046 SDLMIXER_FOUND (same value as SDL_MIXER_FOUND)
17047 $SDLDIR is an environment variable that would correspond to the
17052 ./configure --prefix=$SDLDIR used in building SDL.
17053 Created by Eric Wing. This was influenced by the FindSDL.cmake
17056 module, but with modifications to recognize OS X frameworks and
17057 additional Unix paths (FreeBSD, etc).
17058 FindSDL_net
17061 Locate SDL_net library
17062 This module defines:
17064 SDL_NET_LIBRARIES, the name of the library to link against
17067 SDL_NET_INCLUDE_DIRS, where to find the headers
17068 SDL_NET_FOUND, if false, do not try to link against
17069 SDL_NET_VERSION_STRING - human-readable string containing the version of SDL_net
17070 For backward compatiblity the following variables are also set:
17075 SDLNET_LIBRARY (same value as SDL_NET_LIBRARIES)
17078 SDLNET_INCLUDE_DIR (same value as SDL_NET_INCLUDE_DIRS)
17079 SDLNET_FOUND (same value as SDL_NET_FOUND)
17080 $SDLDIR is an environment variable that would correspond to the
17085 ./configure --prefix=$SDLDIR used in building SDL.
17086 Created by Eric Wing. This was influenced by the FindSDL.cmake
17089 module, but with modifications to recognize OS X frameworks and
17090 additional Unix paths (FreeBSD, etc).
17091 FindSDL_sound
17094 Locates the SDL_sound library
17095 This module depends on SDL being found and must be called AFTER
17100 FindSDL.cmake is called.
17101 This module defines
17104 SDL_SOUND_INCLUDE_DIR, where to find SDL_sound.h
17107 SDL_SOUND_FOUND, if false, do not try to link to SDL_sound
17108 SDL_SOUND_LIBRARIES, this contains the list of libraries that you need
17109 to link against. This is a read-only variable and is marked INTERNAL.
17110 SDL_SOUND_EXTRAS, this is an optional variable for you to add your own
17111 flags to SDL_SOUND_LIBRARIES. This is prepended to SDL_SOUND_LIBRARIES.
17112 This is available mostly for cases this module failed to anticipate for
17113 and you must add additional flags. This is marked as ADVANCED.
17114 SDL_SOUND_VERSION_STRING, human-readable string containing the version of SDL_sound
17115 This module also defines (but you shouldn't need to use
17120 directly)
17121 SDL_SOUND_LIBRARY, the name of just the SDL_sound library you would link
17124 against. Use SDL_SOUND_LIBRARIES for you link instructions and not this one.
17125 And might define the following as needed
17127 MIKMOD_LIBRARY
17130 MODPLUG_LIBRARY
17131 OGG_LIBRARY
17132 VORBIS_LIBRARY
17133 SMPEG_LIBRARY
17134 FLAC_LIBRARY
17135 SPEEX_LIBRARY
17136 Typically, you should not use these variables directly, and you
17141 should use SDL_SOUND_LIBRARIES which contains SDL_SOUND_LIBRARY
17142 and the other audio libraries (if needed) to successfully com‐
17143 pile on your system.
17144 Created by Eric Wing. This module is a bit more complicated than
17147 the other FindSDL* family modules. The reason is that SDL_sound
17148 can be compiled in a large variety of different ways which are
17149 independent of platform. SDL_sound may dynamically link against
17150 other 3rd party libraries to get additional codec support, such
17151 as Ogg Vorbis, SMPEG, ModPlug, MikMod, FLAC, Speex, and poten‐
17152 tially others. Under some circumstances which I don't fully
17153 understand, there seems to be a requirement that dependent
17154 libraries of libraries you use must also be explicitly linked
17155 against in order to successfully compile. SDL_sound does not
17156 currently have any system in place to know how it was compiled.
17157 So this CMake module does the hard work in trying to discover
17158 which 3rd party libraries are required for building (if any).
17159 This module uses a brute force approach to create a test program
17160 that uses SDL_sound, and then tries to build it. If the build
17161 fails, it parses the error output for known symbol names to fig‐
17162 ure out which libraries are needed.
17163 Responds to the $SDLDIR and $SDLSOUNDDIR environmental variable
17166 that would correspond to the ./configure --prefix=$SDLDIR used
17167 in building SDL.
17168 On OSX, this will prefer the Framework version (if found) over
17171 others. People will have to manually change the cache values of
17172 SDL_LIBRARY to override this selectionor set the CMake environ‐
17173 ment CMAKE_INCLUDE_PATH to modify the search paths.
17174 FindSDL_ttf
17177 Locate SDL_ttf library
17178 This module defines:
17180 SDL_TTF_LIBRARIES, the name of the library to link against
17183 SDL_TTF_INCLUDE_DIRS, where to find the headers
17184 SDL_TTF_FOUND, if false, do not try to link against
17185 SDL_TTF_VERSION_STRING - human-readable string containing the version of SDL_ttf
17186 For backward compatiblity the following variables are also set:
17191 SDLTTF_LIBRARY (same value as SDL_TTF_LIBRARIES)
17194 SDLTTF_INCLUDE_DIR (same value as SDL_TTF_INCLUDE_DIRS)
17195 SDLTTF_FOUND (same value as SDL_TTF_FOUND)
17196 $SDLDIR is an environment variable that would correspond to the
17201 ./configure --prefix=$SDLDIR used in building SDL.
17202 Created by Eric Wing. This was influenced by the FindSDL.cmake
17205 module, but with modifications to recognize OS X frameworks and
17206 additional Unix paths (FreeBSD, etc).
17207 FindSWIG
17210 Find SWIG
17211 This module finds an installed SWIG. It sets the following
17213 variables:
17214 SWIG_FOUND - set to true if SWIG is found
17217 SWIG_DIR - the directory where swig is installed
17218 SWIG_EXECUTABLE - the path to the swig executable
17219 SWIG_VERSION - the version number of the swig executable
17220 The minimum required version of SWIG can be specified using the
17225 standard syntax, e.g. find_package(SWIG 1.1)
17226 All information is collected from the SWIG_EXECUTABLE so the
17229 version to be found can be changed from the command line by
17230 means of setting SWIG_EXECUTABLE
17231 FindSelfPackers
17235 Find upx
17236 This module looks for some executable packers (i.e. software
17238 that compress executables or shared libs into on-the-fly
17239 self-extracting executables or shared libs. Examples:
17240 UPX: http://wildsau.idv.uni-linz.ac.at/mfx/upx.html
17243 FindSquish
17246 -- Typical Use
17247 This module can be used to find Squish. Currently Squish ver‐
17252 sions 3 and 4 are supported.
17253 SQUISH_FOUND If false, don't try to use Squish
17256 SQUISH_VERSION The full version of Squish found
17257 SQUISH_VERSION_MAJOR The major version of Squish found
17258 SQUISH_VERSION_MINOR The minor version of Squish found
17259 SQUISH_VERSION_PATCH The patch version of Squish found
17260 SQUISH_INSTALL_DIR The Squish installation directory (containing bin, lib, etc)
17265 SQUISH_SERVER_EXECUTABLE The squishserver executable
17266 SQUISH_CLIENT_EXECUTABLE The squishrunner executable
17267 SQUISH_INSTALL_DIR_FOUND Was the install directory found?
17272 SQUISH_SERVER_EXECUTABLE_FOUND Was the server executable found?
17273 SQUISH_CLIENT_EXECUTABLE_FOUND Was the client executable found?
17274 It provides the function squish_v4_add_test() for adding a
17279 squish test to cmake using Squish 4.x:
17280 squish_v4_add_test(cmakeTestName AUT targetName SUITE suiteName TEST squishTestName
17283 [SETTINGSGROUP group] [PRE_COMMAND command] [POST_COMMAND command] )
17284 The arguments have the following meaning:
17289 cmakeTestName: this will be used as the first argument for add_test()
17292 AUT targetName: the name of the cmake target which will be used as AUT, i.e. the
17293 executable which will be tested.
17294 SUITE suiteName: this is either the full path to the squish suite, or just the
17295 last directory of the suite, i.e. the suite name. In this case
17296 the CMakeLists.txt which calls squish_add_test() must be located
17297 in the parent directory of the suite directory.
17298 TEST squishTestName: the name of the squish test, i.e. the name of the subdirectory
17299 of the test inside the suite directory.
17300 SETTINGSGROUP group: if specified, the given settings group will be used for executing the test.
17301 If not specified, the groupname will be "CTest_<username>"
17302 PRE_COMMAND command: if specified, the given command will be executed before starting the squish test.
17303 POST_COMMAND command: same as PRE_COMMAND, but after the squish test has been executed.
17304 enable_testing()
17309 find_package(Squish 4.0)
17310 if (SQUISH_FOUND)
17311 squish_v4_add_test(myTestName AUT myApp SUITE ${CMAKE_SOURCE_DIR}/tests/mySuite TEST someSquishTest SETTINGSGROUP myGroup )
17312 endif ()
17313 For users of Squish version 3.x the macro squish_v3_add_test()
17321 is provided:
17322 squish_v3_add_test(testName applicationUnderTest testCase envVars testWrapper)
17325 Use this macro to add a test using Squish 3.x.
17326 enable_testing()
17331 find_package(Squish)
17332 if (SQUISH_FOUND)
17333 squish_v3_add_test(myTestName myApplication testCase envVars testWrapper)
17334 endif ()
17335 macro SQUISH_ADD_TEST(testName applicationUnderTest testCase
17340 envVars testWrapper)
17341 This is deprecated. Use SQUISH_V3_ADD_TEST() if you are using Squish 3.x instead.
17344 FindSubversion
17347 Extract information from a subversion working copy
17348 The module defines the following variables:
17350 Subversion_SVN_EXECUTABLE - path to svn command line client
17353 Subversion_VERSION_SVN - version of svn command line client
17354 Subversion_FOUND - true if the command line client was found
17355 SUBVERSION_FOUND - same as Subversion_FOUND, set for compatiblity reasons
17356 The minimum required version of Subversion can be specified
17361 using the standard syntax, e.g. find_package(Subversion 1.4)
17362 If the command line client executable is found two macros are
17365 defined:
17366 Subversion_WC_INFO(<dir> <var-prefix>)
17369 Subversion_WC_LOG(<dir> <var-prefix>)
17370 Subversion_WC_INFO extracts information of a subversion working
17372 copy at a given location. This macro defines the following vari‐
17373 ables:
17374 <var-prefix>_WC_URL - url of the repository (at <dir>)
17377 <var-prefix>_WC_ROOT - root url of the repository
17378 <var-prefix>_WC_REVISION - current revision
17379 <var-prefix>_WC_LAST_CHANGED_AUTHOR - author of last commit
17380 <var-prefix>_WC_LAST_CHANGED_DATE - date of last commit
17381 <var-prefix>_WC_LAST_CHANGED_REV - revision of last commit
17382 <var-prefix>_WC_INFO - output of command `svn info <dir>'
17383 Subversion_WC_LOG retrieves the log message of the base revision
17385 of a subversion working copy at a given location. This macro
17386 defines the variable:
17387 <var-prefix>_LAST_CHANGED_LOG - last log of base revision
17390 Example usage:
17392 find_package(Subversion)
17395 if(SUBVERSION_FOUND)
17396 Subversion_WC_INFO(${PROJECT_SOURCE_DIR} Project)
17397 message("Current revision is ${Project_WC_REVISION}")
17398 Subversion_WC_LOG(${PROJECT_SOURCE_DIR} Project)
17399 message("Last changed log is ${Project_LAST_CHANGED_LOG}")
17400 endif()
17401 FindTCL
17404 TK_INTERNAL_PATH was removed.
17405 This module finds if Tcl is installed and determines where the
17407 include files and libraries are. It also determines what the
17408 name of the library is. This code sets the following variables:
17409 TCL_FOUND = Tcl was found
17412 TK_FOUND = Tk was found
17413 TCLTK_FOUND = Tcl and Tk were found
17414 TCL_LIBRARY = path to Tcl library (tcl tcl80)
17415 TCL_INCLUDE_PATH = path to where tcl.h can be found
17416 TCL_TCLSH = path to tclsh binary (tcl tcl80)
17417 TK_LIBRARY = path to Tk library (tk tk80 etc)
17418 TK_INCLUDE_PATH = path to where tk.h can be found
17419 TK_WISH = full path to the wish executable
17420 In an effort to remove some clutter and clear up some issues for
17425 people who are not necessarily Tcl/Tk gurus/developpers, some
17426 variables were moved or removed. Changes compared to CMake 2.4
17427 are:
17428 => they were only useful for people writing Tcl/Tk extensions.
17431 => these libs are not packaged by default with Tcl/Tk distributions.
17432 Even when Tcl/Tk is built from source, several flavors of debug libs
17433 are created and there is no real reason to pick a single one
17434 specifically (say, amongst tcl84g, tcl84gs, or tcl84sgx).
17435 Let's leave that choice to the user by allowing him to assign
17436 TCL_LIBRARY to any Tcl library, debug or not.
17437 => this ended up being only a Win32 variable, and there is a lot of
17438 confusion regarding the location of this file in an installed Tcl/Tk
17439 tree anyway (see 8.5 for example). If you need the internal path at
17440 this point it is safer you ask directly where the *source* tree is
17441 and dig from there.
17442 FindTIFF
17445 Find TIFF library
17446 Find the native TIFF includes and library This module defines
17448 TIFF_INCLUDE_DIR, where to find tiff.h, etc.
17451 TIFF_LIBRARIES, libraries to link against to use TIFF.
17452 TIFF_FOUND, If false, do not try to use TIFF.
17453 also defined, but not for general use are
17455 TIFF_LIBRARY, where to find the TIFF library.
17458 FindTclStub
17461 TCL_STUB_LIBRARY_DEBUG and TK_STUB_LIBRARY_DEBUG were removed.
17462 This module finds Tcl stub libraries. It first finds Tcl include
17464 files and libraries by calling FindTCL.cmake. How to Use the Tcl
17465 Stubs Library:
17466 http://tcl.activestate.com/doc/howto/stubs.html
17469 Using Stub Libraries:
17471 http://safari.oreilly.com/0130385603/ch48lev1sec3
17474 This code sets the following variables:
17476 TCL_STUB_LIBRARY = path to Tcl stub library
17479 TK_STUB_LIBRARY = path to Tk stub library
17480 TTK_STUB_LIBRARY = path to ttk stub library
17481 In an effort to remove some clutter and clear up some issues for
17486 people who are not necessarily Tcl/Tk gurus/developpers, some
17487 variables were moved or removed. Changes compared to CMake 2.4
17488 are:
17489 => these libs are not packaged by default with Tcl/Tk distributions.
17492 Even when Tcl/Tk is built from source, several flavors of debug libs
17493 are created and there is no real reason to pick a single one
17494 specifically (say, amongst tclstub84g, tclstub84gs, or tclstub84sgx).
17495 Let's leave that choice to the user by allowing him to assign
17496 TCL_STUB_LIBRARY to any Tcl library, debug or not.
17497 FindTclsh
17500 Find tclsh
17501 This module finds if TCL is installed and determines where the
17503 include files and libraries are. It also determines what the
17504 name of the library is. This code sets the following variables:
17505 TCLSH_FOUND = TRUE if tclsh has been found
17508 TCL_TCLSH = the path to the tclsh executable
17509 In cygwin, look for the cygwin version first. Don't look for it
17511 later to avoid finding the cygwin version on a Win32 build.
17512 FindThreads
17515 This module determines the thread library of the system.
17516 The following variables are set
17518 CMAKE_THREAD_LIBS_INIT - the thread library
17521 CMAKE_USE_SPROC_INIT - are we using sproc?
17522 CMAKE_USE_WIN32_THREADS_INIT - using WIN32 threads?
17523 CMAKE_USE_PTHREADS_INIT - are we using pthreads
17524 CMAKE_HP_PTHREADS_INIT - are we using hp pthreads
17525 For systems with multiple thread libraries, caller can set
17527 CMAKE_THREAD_PREFER_PTHREAD
17530 FindUnixCommands
17533 Find unix commands from cygwin
17534 This module looks for some usual Unix commands.
17536 FindVTK
17540 Find a VTK installation or build tree.
17541 The following variables are set if VTK is found. If VTK is not
17543 found, VTK_FOUND is set to false.
17544 VTK_FOUND - Set to true when VTK is found.
17547 VTK_USE_FILE - CMake file to use VTK.
17548 VTK_MAJOR_VERSION - The VTK major version number.
17549 VTK_MINOR_VERSION - The VTK minor version number
17550 (odd non-release).
17551 VTK_BUILD_VERSION - The VTK patch level
17552 (meaningless for odd minor).
17553 VTK_INCLUDE_DIRS - Include directories for VTK
17554 VTK_LIBRARY_DIRS - Link directories for VTK libraries
17555 VTK_KITS - List of VTK kits, in CAPS
17556 (COMMON,IO,) etc.
17557 VTK_LANGUAGES - List of wrapped languages, in CAPS
17558 (TCL, PYHTON,) etc.
17559 The following cache entries must be set by the user to locate
17561 VTK:
17562 VTK_DIR - The directory containing VTKConfig.cmake.
17565 This is either the root of the build tree,
17566 or the lib/vtk directory. This is the
17567 only cache entry.
17568 The following variables are set for backward compatibility and
17570 should not be used in new code:
17571 USE_VTK_FILE - The full path to the UseVTK.cmake file.
17574 This is provided for backward
17575 compatibility. Use VTK_USE_FILE
17576 instead.
17577 FindWget
17583 Find wget
17584 This module looks for wget. This module defines the following
17586 values:
17587 WGET_EXECUTABLE: the full path to the wget tool.
17590 WGET_FOUND: True if wget has been found.
17591 FindWish
17594 Find wish installation
17595 This module finds if TCL is installed and determines where the
17597 include files and libraries are. It also determines what the
17598 name of the library is. This code sets the following variables:
17599 TK_WISH = the path to the wish executable
17602 if UNIX is defined, then it will look for the cygwin version
17607 first
17608 FindX11
17611 Find X11 installation
17612 Try to find X11 on UNIX systems. The following values are
17614 defined
17615 X11_FOUND - True if X11 is available
17618 X11_INCLUDE_DIR - include directories to use X11
17619 X11_LIBRARIES - link against these to use X11
17620 and also the following more fine grained variables: Include
17625 paths: X11_ICE_INCLUDE_PATH, X11_ICE_LIB,
17626 X11_ICE_FOUND
17627 X11_SM_INCLUDE_PATH, X11_SM_LIB, X11_SM_FOUND
17630 X11_X11_INCLUDE_PATH, X11_X11_LIB
17631 X11_Xaccessrules_INCLUDE_PATH, X11_Xaccess_FOUND
17632 X11_Xaccessstr_INCLUDE_PATH, X11_Xaccess_FOUND
17633 X11_Xau_INCLUDE_PATH, X11_Xau_LIB, X11_Xau_FOUND
17634 X11_Xcomposite_INCLUDE_PATH, X11_Xcomposite_LIB, X11_Xcomposite_FOUND
17635 X11_Xcursor_INCLUDE_PATH, X11_Xcursor_LIB, X11_Xcursor_FOUND
17636 X11_Xdamage_INCLUDE_PATH, X11_Xdamage_LIB, X11_Xdamage_FOUND
17637 X11_Xdmcp_INCLUDE_PATH, X11_Xdmcp_LIB, X11_Xdmcp_FOUND
17638 X11_Xext_LIB, X11_Xext_FOUND
17639 X11_dpms_INCLUDE_PATH, (in X11_Xext_LIB), X11_dpms_FOUND
17640 X11_XShm_INCLUDE_PATH, (in X11_Xext_LIB), X11_XShm_FOUND
17641 X11_Xshape_INCLUDE_PATH, (in X11_Xext_LIB), X11_Xshape_FOUND
17642 X11_xf86misc_INCLUDE_PATH, X11_Xxf86misc_LIB, X11_xf86misc_FOUND
17643 X11_xf86vmode_INCLUDE_PATH, X11_Xxf86vm_LIB X11_xf86vmode_FOUND
17644 X11_Xfixes_INCLUDE_PATH, X11_Xfixes_LIB, X11_Xfixes_FOUND
17645 X11_Xft_INCLUDE_PATH, X11_Xft_LIB, X11_Xft_FOUND
17646 X11_Xi_INCLUDE_PATH, X11_Xi_LIB, X11_Xi_FOUND
17647 X11_Xinerama_INCLUDE_PATH, X11_Xinerama_LIB, X11_Xinerama_FOUND
17648 X11_Xinput_INCLUDE_PATH, X11_Xinput_LIB, X11_Xinput_FOUND
17649 X11_Xkb_INCLUDE_PATH, X11_Xkb_FOUND
17650 X11_Xkblib_INCLUDE_PATH, X11_Xkb_FOUND
17651 X11_Xkbfile_INCLUDE_PATH, X11_Xkbfile_LIB, X11_Xkbfile_FOUND
17652 X11_Xmu_INCLUDE_PATH, X11_Xmu_LIB, X11_Xmu_FOUND
17653 X11_Xpm_INCLUDE_PATH, X11_Xpm_LIB, X11_Xpm_FOUND
17654 X11_XTest_INCLUDE_PATH, X11_XTest_LIB, X11_XTest_FOUND
17655 X11_Xrandr_INCLUDE_PATH, X11_Xrandr_LIB, X11_Xrandr_FOUND
17656 X11_Xrender_INCLUDE_PATH, X11_Xrender_LIB, X11_Xrender_FOUND
17657 X11_Xscreensaver_INCLUDE_PATH, X11_Xscreensaver_LIB, X11_Xscreensaver_FOUND
17658 X11_Xt_INCLUDE_PATH, X11_Xt_LIB, X11_Xt_FOUND
17659 X11_Xutil_INCLUDE_PATH, X11_Xutil_FOUND
17660 X11_Xv_INCLUDE_PATH, X11_Xv_LIB, X11_Xv_FOUND
17661 X11_XSync_INCLUDE_PATH, (in X11_Xext_LIB), X11_XSync_FOUND
17662 FindXMLRPC
17665 Find xmlrpc
17666 Find the native XMLRPC headers and libraries.
17668 XMLRPC_INCLUDE_DIRS - where to find xmlrpc.h, etc.
17671 XMLRPC_LIBRARIES - List of libraries when using xmlrpc.
17672 XMLRPC_FOUND - True if xmlrpc found.
17673 XMLRPC modules may be specified as components for this find mod‐
17675 ule. Modules may be listed by running "xmlrpc-c-config". Mod‐
17676 ules include:
17677 c++ C++ wrapper code
17680 libwww-client libwww-based client
17681 cgi-server CGI-based server
17682 abyss-server ABYSS-based server
17683 Typical usage:
17685 find_package(XMLRPC REQUIRED libwww-client)
17688 FindZLIB
17691 Find zlib
17692 Find the native ZLIB includes and library. Once done this will
17694 define
17695 ZLIB_INCLUDE_DIRS - where to find zlib.h, etc.
17698 ZLIB_LIBRARIES - List of libraries when using zlib.
17699 ZLIB_FOUND - True if zlib found.
17700 ZLIB_VERSION_STRING - The version of zlib found (x.y.z)
17705 ZLIB_VERSION_MAJOR - The major version of zlib
17706 ZLIB_VERSION_MINOR - The minor version of zlib
17707 ZLIB_VERSION_PATCH - The patch version of zlib
17708 ZLIB_VERSION_TWEAK - The tweak version of zlib
17709 The following variable are provided for backward compatibility
17714 ZLIB_MAJOR_VERSION - The major version of zlib
17717 ZLIB_MINOR_VERSION - The minor version of zlib
17718 ZLIB_PATCH_VERSION - The patch version of zlib
17719 An includer may set ZLIB_ROOT to a zlib installation root to
17724 tell this module where to look.
17725 Findosg
17728 NOTE: It is highly recommended that you use the new FindOpen‐
17734 SceneGraph.cmake introduced in CMake 2.6.3 and not use this Find
17735 module directly.
17736 This is part of the Findosg* suite used to find OpenSceneGraph
17739 components. Each component is separate and you must opt in to
17740 each module. You must also opt into OpenGL and OpenThreads (and
17741 Producer if needed) as these modules won't do it for you. This
17742 is to allow you control over your own system piece by piece in
17743 case you need to opt out of certain components or change the
17744 Find behavior for a particular module (perhaps because the
17745 default FindOpenGL.cmake module doesn't work with your system as
17746 an example). If you want to use a more convenient module that
17747 includes everything, use the FindOpenSceneGraph.cmake instead of
17748 the Findosg*.cmake modules.
17749 Locate osg This module defines
17752 OSG_FOUND - Was the Osg found? OSG_INCLUDE_DIR - Where to find
17755 the headers OSG_LIBRARIES - The libraries to link against for
17756 the OSG (use this)
17757 OSG_LIBRARY - The OSG library OSG_LIBRARY_DEBUG - The OSG debug
17760 library
17761 $OSGDIR is an environment variable that would correspond to the
17764 ./configure --prefix=$OSGDIR used in building osg.
17765 Created by Eric Wing.
17768 FindosgAnimation
17771 This is part of the Findosg* suite used to find OpenSceneGraph
17774 components. Each component is separate and you must opt in to
17775 each module. You must also opt into OpenGL and OpenThreads (and
17776 Producer if needed) as these modules won't do it for you. This
17777 is to allow you control over your own system piece by piece in
17778 case you need to opt out of certain components or change the
17779 Find behavior for a particular module (perhaps because the
17780 default FindOpenGL.cmake module doesn't work with your system as
17781 an example). If you want to use a more convenient module that
17782 includes everything, use the FindOpenSceneGraph.cmake instead of
17783 the Findosg*.cmake modules.
17784 Locate osgAnimation This module defines
17787 OSGANIMATION_FOUND - Was osgAnimation found? OSGANIMA‐
17790 TION_INCLUDE_DIR - Where to find the headers OSGANIMA‐
17791 TION_LIBRARIES - The libraries to link against for the OSG (use
17792 this)
17793 OSGANIMATION_LIBRARY - The OSG library OSGANIMA‐
17796 TION_LIBRARY_DEBUG - The OSG debug library
17797 $OSGDIR is an environment variable that would correspond to the
17800 ./configure --prefix=$OSGDIR used in building osg.
17801 Created by Eric Wing.
17804 FindosgDB
17807 This is part of the Findosg* suite used to find OpenSceneGraph
17810 components. Each component is separate and you must opt in to
17811 each module. You must also opt into OpenGL and OpenThreads (and
17812 Producer if needed) as these modules won't do it for you. This
17813 is to allow you control over your own system piece by piece in
17814 case you need to opt out of certain components or change the
17815 Find behavior for a particular module (perhaps because the
17816 default FindOpenGL.cmake module doesn't work with your system as
17817 an example). If you want to use a more convenient module that
17818 includes everything, use the FindOpenSceneGraph.cmake instead of
17819 the Findosg*.cmake modules.
17820 Locate osgDB This module defines
17823 OSGDB_FOUND - Was osgDB found? OSGDB_INCLUDE_DIR - Where to find
17826 the headers OSGDB_LIBRARIES - The libraries to link against for
17827 the osgDB (use this)
17828 OSGDB_LIBRARY - The osgDB library OSGDB_LIBRARY_DEBUG - The
17831 osgDB debug library
17832 $OSGDIR is an environment variable that would correspond to the
17835 ./configure --prefix=$OSGDIR used in building osg.
17836 Created by Eric Wing.
17839 FindosgFX
17842 This is part of the Findosg* suite used to find OpenSceneGraph
17845 components. Each component is separate and you must opt in to
17846 each module. You must also opt into OpenGL and OpenThreads (and
17847 Producer if needed) as these modules won't do it for you. This
17848 is to allow you control over your own system piece by piece in
17849 case you need to opt out of certain components or change the
17850 Find behavior for a particular module (perhaps because the
17851 default FindOpenGL.cmake module doesn't work with your system as
17852 an example). If you want to use a more convenient module that
17853 includes everything, use the FindOpenSceneGraph.cmake instead of
17854 the Findosg*.cmake modules.
17855 Locate osgFX This module defines
17858 OSGFX_FOUND - Was osgFX found? OSGFX_INCLUDE_DIR - Where to find
17861 the headers OSGFX_LIBRARIES - The libraries to link against for
17862 the osgFX (use this)
17863 OSGFX_LIBRARY - The osgFX library OSGFX_LIBRARY_DEBUG - The
17866 osgFX debug library
17867 $OSGDIR is an environment variable that would correspond to the
17870 ./configure --prefix=$OSGDIR used in building osg.
17871 Created by Eric Wing.
17874 FindosgGA
17877 This is part of the Findosg* suite used to find OpenSceneGraph
17880 components. Each component is separate and you must opt in to
17881 each module. You must also opt into OpenGL and OpenThreads (and
17882 Producer if needed) as these modules won't do it for you. This
17883 is to allow you control over your own system piece by piece in
17884 case you need to opt out of certain components or change the
17885 Find behavior for a particular module (perhaps because the
17886 default FindOpenGL.cmake module doesn't work with your system as
17887 an example). If you want to use a more convenient module that
17888 includes everything, use the FindOpenSceneGraph.cmake instead of
17889 the Findosg*.cmake modules.
17890 Locate osgGA This module defines
17893 OSGGA_FOUND - Was osgGA found? OSGGA_INCLUDE_DIR - Where to find
17896 the headers OSGGA_LIBRARIES - The libraries to link against for
17897 the osgGA (use this)
17898 OSGGA_LIBRARY - The osgGA library OSGGA_LIBRARY_DEBUG - The
17901 osgGA debug library
17902 $OSGDIR is an environment variable that would correspond to the
17905 ./configure --prefix=$OSGDIR used in building osg.
17906 Created by Eric Wing.
17909 FindosgIntrospection
17912 This is part of the Findosg* suite used to find OpenSceneGraph
17915 components. Each component is separate and you must opt in to
17916 each module. You must also opt into OpenGL and OpenThreads (and
17917 Producer if needed) as these modules won't do it for you. This
17918 is to allow you control over your own system piece by piece in
17919 case you need to opt out of certain components or change the
17920 Find behavior for a particular module (perhaps because the
17921 default FindOpenGL.cmake module doesn't work with your system as
17922 an example). If you want to use a more convenient module that
17923 includes everything, use the FindOpenSceneGraph.cmake instead of
17924 the Findosg*.cmake modules.
17925 Locate osgINTROSPECTION This module defines
17928 OSGINTROSPECTION_FOUND - Was osgIntrospection found? OSGINTRO‐
17931 SPECTION_INCLUDE_DIR - Where to find the headers OSGINTROSPEC‐
17932 TION_LIBRARIES - The libraries to link for osgIntrospection (use
17933 this)
17934 OSGINTROSPECTION_LIBRARY - The osgIntrospection library OSGIN‐
17937 TROSPECTION_LIBRARY_DEBUG - The osgIntrospection debug library
17938 $OSGDIR is an environment variable that would correspond to the
17941 ./configure --prefix=$OSGDIR used in building osg.
17942 Created by Eric Wing.
17945 FindosgManipulator
17948 This is part of the Findosg* suite used to find OpenSceneGraph
17951 components. Each component is separate and you must opt in to
17952 each module. You must also opt into OpenGL and OpenThreads (and
17953 Producer if needed) as these modules won't do it for you. This
17954 is to allow you control over your own system piece by piece in
17955 case you need to opt out of certain components or change the
17956 Find behavior for a particular module (perhaps because the
17957 default FindOpenGL.cmake module doesn't work with your system as
17958 an example). If you want to use a more convenient module that
17959 includes everything, use the FindOpenSceneGraph.cmake instead of
17960 the Findosg*.cmake modules.
17961 Locate osgManipulator This module defines
17964 OSGMANIPULATOR_FOUND - Was osgManipulator found? OSGMANIPULA‐
17967 TOR_INCLUDE_DIR - Where to find the headers OSGMANIPULA‐
17968 TOR_LIBRARIES - The libraries to link for osgManipulator (use
17969 this)
17970 OSGMANIPULATOR_LIBRARY - The osgManipulator library OSGMANIPULA‐
17973 TOR_LIBRARY_DEBUG - The osgManipulator debug library
17974 $OSGDIR is an environment variable that would correspond to the
17977 ./configure --prefix=$OSGDIR used in building osg.
17978 Created by Eric Wing.
17981 FindosgParticle
17984 This is part of the Findosg* suite used to find OpenSceneGraph
17987 components. Each component is separate and you must opt in to
17988 each module. You must also opt into OpenGL and OpenThreads (and
17989 Producer if needed) as these modules won't do it for you. This
17990 is to allow you control over your own system piece by piece in
17991 case you need to opt out of certain components or change the
17992 Find behavior for a particular module (perhaps because the
17993 default FindOpenGL.cmake module doesn't work with your system as
17994 an example). If you want to use a more convenient module that
17995 includes everything, use the FindOpenSceneGraph.cmake instead of
17996 the Findosg*.cmake modules.
17997 Locate osgParticle This module defines
18000 OSGPARTICLE_FOUND - Was osgParticle found? OSGPARTI‐
18003 CLE_INCLUDE_DIR - Where to find the headers OSGPARTI‐
18004 CLE_LIBRARIES - The libraries to link for osgParticle (use this)
18005 OSGPARTICLE_LIBRARY - The osgParticle library OSGPARTI‐
18008 CLE_LIBRARY_DEBUG - The osgParticle debug library
18009 $OSGDIR is an environment variable that would correspond to the
18012 ./configure --prefix=$OSGDIR used in building osg.
18013 Created by Eric Wing.
18016 FindosgPresentation
18019 This is part of the Findosg* suite used to find OpenSceneGraph
18022 components. Each component is separate and you must opt in to
18023 each module. You must also opt into OpenGL and OpenThreads (and
18024 Producer if needed) as these modules won't do it for you. This
18025 is to allow you control over your own system piece by piece in
18026 case you need to opt out of certain components or change the
18027 Find behavior for a particular module (perhaps because the
18028 default FindOpenGL.cmake module doesn't work with your system as
18029 an example). If you want to use a more convenient module that
18030 includes everything, use the FindOpenSceneGraph.cmake instead of
18031 the Findosg*.cmake modules.
18032 Locate osgPresentation This module defines
18035 OSGPRESENTATION_FOUND - Was osgPresentation found? OSGPRESENTA‐
18038 TION_INCLUDE_DIR - Where to find the headers OSGPRESENTA‐
18039 TION_LIBRARIES - The libraries to link for osgPresentation (use
18040 this)
18041 OSGPRESENTATION_LIBRARY - The osgPresentation library OSGPRESEN‐
18044 TATION_LIBRARY_DEBUG - The osgPresentation debug library
18045 $OSGDIR is an environment variable that would correspond to the
18048 ./configure --prefix=$OSGDIR used in building osg.
18049 Created by Eric Wing. Modified to work with osgPresentation by
18052 Robert Osfield, January 2012.
18053 FindosgProducer
18056 This is part of the Findosg* suite used to find OpenSceneGraph
18059 components. Each component is separate and you must opt in to
18060 each module. You must also opt into OpenGL and OpenThreads (and
18061 Producer if needed) as these modules won't do it for you. This
18062 is to allow you control over your own system piece by piece in
18063 case you need to opt out of certain components or change the
18064 Find behavior for a particular module (perhaps because the
18065 default FindOpenGL.cmake module doesn't work with your system as
18066 an example). If you want to use a more convenient module that
18067 includes everything, use the FindOpenSceneGraph.cmake instead of
18068 the Findosg*.cmake modules.
18069 Locate osgProducer This module defines
18072 OSGPRODUCER_FOUND - Was osgProducer found? OSGPRO‐
18075 DUCER_INCLUDE_DIR - Where to find the headers OSGPRO‐
18076 DUCER_LIBRARIES - The libraries to link for osgProducer (use
18077 this)
18078 OSGPRODUCER_LIBRARY - The osgProducer library OSGPRO‐
18081 DUCER_LIBRARY_DEBUG - The osgProducer debug library
18082 $OSGDIR is an environment variable that would correspond to the
18085 ./configure --prefix=$OSGDIR used in building osg.
18086 Created by Eric Wing.
18089 FindosgQt
18092 This is part of the Findosg* suite used to find OpenSceneGraph
18095 components. Each component is separate and you must opt in to
18096 each module. You must also opt into OpenGL and OpenThreads (and
18097 Producer if needed) as these modules won't do it for you. This
18098 is to allow you control over your own system piece by piece in
18099 case you need to opt out of certain components or change the
18100 Find behavior for a particular module (perhaps because the
18101 default FindOpenGL.cmake module doesn't work with your system as
18102 an example). If you want to use a more convenient module that
18103 includes everything, use the FindOpenSceneGraph.cmake instead of
18104 the Findosg*.cmake modules.
18105 Locate osgQt This module defines
18108 OSGQT_FOUND - Was osgQt found? OSGQT_INCLUDE_DIR - Where to find
18111 the headers OSGQT_LIBRARIES - The libraries to link for osgQt
18112 (use this)
18113 OSGQT_LIBRARY - The osgQt library OSGQT_LIBRARY_DEBUG - The
18116 osgQt debug library
18117 $OSGDIR is an environment variable that would correspond to the
18120 ./configure --prefix=$OSGDIR used in building osg.
18121 Created by Eric Wing. Modified to work with osgQt by Robert
18124 Osfield, January 2012.
18125 FindosgShadow
18128 This is part of the Findosg* suite used to find OpenSceneGraph
18131 components. Each component is separate and you must opt in to
18132 each module. You must also opt into OpenGL and OpenThreads (and
18133 Producer if needed) as these modules won't do it for you. This
18134 is to allow you control over your own system piece by piece in
18135 case you need to opt out of certain components or change the
18136 Find behavior for a particular module (perhaps because the
18137 default FindOpenGL.cmake module doesn't work with your system as
18138 an example). If you want to use a more convenient module that
18139 includes everything, use the FindOpenSceneGraph.cmake instead of
18140 the Findosg*.cmake modules.
18141 Locate osgShadow This module defines
18144 OSGSHADOW_FOUND - Was osgShadow found? OSGSHADOW_INCLUDE_DIR -
18147 Where to find the headers OSGSHADOW_LIBRARIES - The libraries to
18148 link for osgShadow (use this)
18149 OSGSHADOW_LIBRARY - The osgShadow library
18152 OSGSHADOW_LIBRARY_DEBUG - The osgShadow debug library
18153 $OSGDIR is an environment variable that would correspond to the
18156 ./configure --prefix=$OSGDIR used in building osg.
18157 Created by Eric Wing.
18160 FindosgSim
18163 This is part of the Findosg* suite used to find OpenSceneGraph
18166 components. Each component is separate and you must opt in to
18167 each module. You must also opt into OpenGL and OpenThreads (and
18168 Producer if needed) as these modules won't do it for you. This
18169 is to allow you control over your own system piece by piece in
18170 case you need to opt out of certain components or change the
18171 Find behavior for a particular module (perhaps because the
18172 default FindOpenGL.cmake module doesn't work with your system as
18173 an example). If you want to use a more convenient module that
18174 includes everything, use the FindOpenSceneGraph.cmake instead of
18175 the Findosg*.cmake modules.
18176 Locate osgSim This module defines
18179 OSGSIM_FOUND - Was osgSim found? OSGSIM_INCLUDE_DIR - Where to
18182 find the headers OSGSIM_LIBRARIES - The libraries to link for
18183 osgSim (use this)
18184 OSGSIM_LIBRARY - The osgSim library OSGSIM_LIBRARY_DEBUG - The
18187 osgSim debug library
18188 $OSGDIR is an environment variable that would correspond to the
18191 ./configure --prefix=$OSGDIR used in building osg.
18192 Created by Eric Wing.
18195 FindosgTerrain
18198 This is part of the Findosg* suite used to find OpenSceneGraph
18201 components. Each component is separate and you must opt in to
18202 each module. You must also opt into OpenGL and OpenThreads (and
18203 Producer if needed) as these modules won't do it for you. This
18204 is to allow you control over your own system piece by piece in
18205 case you need to opt out of certain components or change the
18206 Find behavior for a particular module (perhaps because the
18207 default FindOpenGL.cmake module doesn't work with your system as
18208 an example). If you want to use a more convenient module that
18209 includes everything, use the FindOpenSceneGraph.cmake instead of
18210 the Findosg*.cmake modules.
18211 Locate osgTerrain This module defines
18214 OSGTERRAIN_FOUND - Was osgTerrain found? OSGTERRAIN_INCLUDE_DIR
18217 - Where to find the headers OSGTERRAIN_LIBRARIES - The libraries
18218 to link for osgTerrain (use this)
18219 OSGTERRAIN_LIBRARY - The osgTerrain library OSGTER‐
18222 RAIN_LIBRARY_DEBUG - The osgTerrain debug library
18223 $OSGDIR is an environment variable that would correspond to the
18226 ./configure --prefix=$OSGDIR used in building osg.
18227 Created by Eric Wing.
18230 FindosgText
18233 This is part of the Findosg* suite used to find OpenSceneGraph
18236 components. Each component is separate and you must opt in to
18237 each module. You must also opt into OpenGL and OpenThreads (and
18238 Producer if needed) as these modules won't do it for you. This
18239 is to allow you control over your own system piece by piece in
18240 case you need to opt out of certain components or change the
18241 Find behavior for a particular module (perhaps because the
18242 default FindOpenGL.cmake module doesn't work with your system as
18243 an example). If you want to use a more convenient module that
18244 includes everything, use the FindOpenSceneGraph.cmake instead of
18245 the Findosg*.cmake modules.
18246 Locate osgText This module defines
18249 OSGTEXT_FOUND - Was osgText found? OSGTEXT_INCLUDE_DIR - Where
18252 to find the headers OSGTEXT_LIBRARIES - The libraries to link
18253 for osgText (use this)
18254 OSGTEXT_LIBRARY - The osgText library OSGTEXT_LIBRARY_DEBUG -
18257 The osgText debug library
18258 $OSGDIR is an environment variable that would correspond to the
18261 ./configure --prefix=$OSGDIR used in building osg.
18262 Created by Eric Wing.
18265 FindosgUtil
18268 This is part of the Findosg* suite used to find OpenSceneGraph
18271 components. Each component is separate and you must opt in to
18272 each module. You must also opt into OpenGL and OpenThreads (and
18273 Producer if needed) as these modules won't do it for you. This
18274 is to allow you control over your own system piece by piece in
18275 case you need to opt out of certain components or change the
18276 Find behavior for a particular module (perhaps because the
18277 default FindOpenGL.cmake module doesn't work with your system as
18278 an example). If you want to use a more convenient module that
18279 includes everything, use the FindOpenSceneGraph.cmake instead of
18280 the Findosg*.cmake modules.
18281 Locate osgUtil This module defines
18284 OSGUTIL_FOUND - Was osgUtil found? OSGUTIL_INCLUDE_DIR - Where
18287 to find the headers OSGUTIL_LIBRARIES - The libraries to link
18288 for osgUtil (use this)
18289 OSGUTIL_LIBRARY - The osgUtil library OSGUTIL_LIBRARY_DEBUG -
18292 The osgUtil debug library
18293 $OSGDIR is an environment variable that would correspond to the
18296 ./configure --prefix=$OSGDIR used in building osg.
18297 Created by Eric Wing.
18300 FindosgViewer
18303 This is part of the Findosg* suite used to find OpenSceneGraph
18306 components. Each component is separate and you must opt in to
18307 each module. You must also opt into OpenGL and OpenThreads (and
18308 Producer if needed) as these modules won't do it for you. This
18309 is to allow you control over your own system piece by piece in
18310 case you need to opt out of certain components or change the
18311 Find behavior for a particular module (perhaps because the
18312 default FindOpenGL.cmake module doesn't work with your system as
18313 an example). If you want to use a more convenient module that
18314 includes everything, use the FindOpenSceneGraph.cmake instead of
18315 the Findosg*.cmake modules.
18316 Locate osgViewer This module defines
18319 OSGVIEWER_FOUND - Was osgViewer found? OSGVIEWER_INCLUDE_DIR -
18322 Where to find the headers OSGVIEWER_LIBRARIES - The libraries to
18323 link for osgViewer (use this)
18324 OSGVIEWER_LIBRARY - The osgViewer library
18327 OSGVIEWER_LIBRARY_DEBUG - The osgViewer debug library
18328 $OSGDIR is an environment variable that would correspond to the
18331 ./configure --prefix=$OSGDIR used in building osg.
18332 Created by Eric Wing.
18335 FindosgVolume
18338 This is part of the Findosg* suite used to find OpenSceneGraph
18341 components. Each component is separate and you must opt in to
18342 each module. You must also opt into OpenGL and OpenThreads (and
18343 Producer if needed) as these modules won't do it for you. This
18344 is to allow you control over your own system piece by piece in
18345 case you need to opt out of certain components or change the
18346 Find behavior for a particular module (perhaps because the
18347 default FindOpenGL.cmake module doesn't work with your system as
18348 an example). If you want to use a more convenient module that
18349 includes everything, use the FindOpenSceneGraph.cmake instead of
18350 the Findosg*.cmake modules.
18351 Locate osgVolume This module defines
18354 OSGVOLUME_FOUND - Was osgVolume found? OSGVOLUME_INCLUDE_DIR -
18357 Where to find the headers OSGVOLUME_LIBRARIES - The libraries to
18358 link for osgVolume (use this)
18359 OSGVOLUME_LIBRARY - The osgVolume library OSGVOL‐
18362 UME_LIBRARY_DEBUG - The osgVolume debug library
18363 $OSGDIR is an environment variable that would correspond to the
18366 ./configure --prefix=$OSGDIR used in building osg.
18367 Created by Eric Wing.
18370 FindosgWidget
18373 This is part of the Findosg* suite used to find OpenSceneGraph
18376 components. Each component is separate and you must opt in to
18377 each module. You must also opt into OpenGL and OpenThreads (and
18378 Producer if needed) as these modules won't do it for you. This
18379 is to allow you control over your own system piece by piece in
18380 case you need to opt out of certain components or change the
18381 Find behavior for a particular module (perhaps because the
18382 default FindOpenGL.cmake module doesn't work with your system as
18383 an example). If you want to use a more convenient module that
18384 includes everything, use the FindOpenSceneGraph.cmake instead of
18385 the Findosg*.cmake modules.
18386 Locate osgWidget This module defines
18389 OSGWIDGET_FOUND - Was osgWidget found? OSGWIDGET_INCLUDE_DIR -
18392 Where to find the headers OSGWIDGET_LIBRARIES - The libraries to
18393 link for osgWidget (use this)
18394 OSGWIDGET_LIBRARY - The osgWidget library OSGWID‐
18397 GET_LIBRARY_DEBUG - The osgWidget debug library
18398 $OSGDIR is an environment variable that would correspond to the
18401 ./configure --prefix=$OSGDIR used in building osg.
18402 FindosgWidget.cmake tweaked from Findosg* suite as created by
18405 Eric Wing.
18406 Findosg_functions
18409 This CMake file contains two macros to assist with searching for
18415 OSG libraries and nodekits. Please see FindOpenSceneGraph.cmake
18416 for full documentation.
18417 FindwxWidgets
18421 Find a wxWidgets (a.k.a., wxWindows) installation.
18422 This module finds if wxWidgets is installed and selects a
18424 default configuration to use. wxWidgets is a modular library. To
18425 specify the modules that you will use, you need to name them as
18426 components to the package:
18427 find_package(wxWidgets COMPONENTS core base ...)
18430 There are two search branches: a windows style and a unix style.
18433 For windows, the following variables are searched for and set to
18434 defaults in case of multiple choices. Change them if the
18435 defaults are not desired (i.e., these are the only variables you
18436 should change to select a configuration):
18437 wxWidgets_ROOT_DIR - Base wxWidgets directory
18440 (e.g., C:/wxWidgets-2.6.3).
18441 wxWidgets_LIB_DIR - Path to wxWidgets libraries
18442 (e.g., C:/wxWidgets-2.6.3/lib/vc_lib).
18443 wxWidgets_CONFIGURATION - Configuration to use
18444 (e.g., msw, mswd, mswu, mswunivud, etc.)
18445 wxWidgets_EXCLUDE_COMMON_LIBRARIES
18446 - Set to TRUE to exclude linking of
18447 commonly required libs (e.g., png tiff
18448 jpeg zlib regex expat).
18449 For unix style it uses the wx-config utility. You can select
18454 between debug/release, unicode/ansi, universal/non-universal,
18455 and static/shared in the QtDialog or ccmake interfaces by turn‐
18456 ing ON/OFF the following variables:
18457 wxWidgets_USE_DEBUG
18460 wxWidgets_USE_UNICODE
18461 wxWidgets_USE_UNIVERSAL
18462 wxWidgets_USE_STATIC
18463 There is also a wxWidgets_CONFIG_OPTIONS variable for all other
18468 options that need to be passed to the wx-config utility. For
18469 example, to use the base toolkit found in the /usr/local path,
18470 set the variable (before calling the FIND_PACKAGE command) as
18471 such:
18472 set(wxWidgets_CONFIG_OPTIONS --toolkit=base --prefix=/usr)
18475 The following are set after the configuration is done for both
18480 windows and unix style:
18481 wxWidgets_FOUND - Set to TRUE if wxWidgets was found.
18484 wxWidgets_INCLUDE_DIRS - Include directories for WIN32
18485 i.e., where to find "wx/wx.h" and
18486 "wx/setup.h"; possibly empty for unices.
18487 wxWidgets_LIBRARIES - Path to the wxWidgets libraries.
18488 wxWidgets_LIBRARY_DIRS - compile time link dirs, useful for
18489 rpath on UNIX. Typically an empty string
18490 in WIN32 environment.
18491 wxWidgets_DEFINITIONS - Contains defines required to compile/link
18492 against WX, e.g. WXUSINGDLL
18493 wxWidgets_DEFINITIONS_DEBUG- Contains defines required to compile/link
18494 against WX debug builds, e.g. __WXDEBUG__
18495 wxWidgets_CXX_FLAGS - Include dirs and compiler flags for
18496 unices, empty on WIN32. Essentially
18497 "`wx-config --cxxflags`".
18498 wxWidgets_USE_FILE - Convenience include file.
18499 Sample usage:
18504 # Note that for MinGW users the order of libs is important!
18507 find_package(wxWidgets COMPONENTS net gl core base)
18508 if(wxWidgets_FOUND)
18509 include(${wxWidgets_USE_FILE})
18510 # and for each of your dependent executable/library targets:
18511 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
18512 endif()
18513 If wxWidgets is required (i.e., not an optional part):
18518 find_package(wxWidgets REQUIRED net gl core base)
18521 include(${wxWidgets_USE_FILE})
18522 # and for each of your dependent executable/library targets:
18523 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
18524 FindwxWindows
18527 Find wxWindows (wxWidgets) installation
18528 This module finds if wxWindows/wxWidgets is installed and deter‐
18530 mines where the include files and libraries are. It also deter‐
18531 mines what the name of the library is. Please note this file is
18532 DEPRECATED and replaced by FindwxWidgets.cmake. This code sets
18533 the following variables:
18534 WXWINDOWS_FOUND = system has WxWindows
18537 WXWINDOWS_LIBRARIES = path to the wxWindows libraries
18538 on Unix/Linux with additional
18539 linker flags from
18540 "wx-config --libs"
18541 CMAKE_WXWINDOWS_CXX_FLAGS = Compiler flags for wxWindows,
18542 essentially "`wx-config --cxxflags`"
18543 on Linux
18544 WXWINDOWS_INCLUDE_DIR = where to find "wx/wx.h" and "wx/setup.h"
18545 WXWINDOWS_LINK_DIRECTORIES = link directories, useful for rpath on
18546 Unix
18547 WXWINDOWS_DEFINITIONS = extra defines
18548 OPTIONS If you need OpenGL support please
18553 set(WXWINDOWS_USE_GL 1)
18556 in your CMakeLists.txt *before* you include this file.
18558 HAVE_ISYSTEM - true required to replace -I by -isystem on g++
18561 For convenience include Use_wxWindows.cmake in your project's
18566 CMakeLists.txt using include(${CMAKE_CUR‐
18567 RENT_LIST_DIR}/Use_wxWindows.cmake).
18568 USAGE
18571 set(WXWINDOWS_USE_GL 1)
18574 find_package(wxWindows)
18575 NOTES wxWidgets 2.6.x is supported for monolithic builds e.g.
18580 compiled in wx/build/msw dir as:
18581 nmake -f makefile.vc BUILD=debug SHARED=0 USE_OPENGL=1 MONOLITHIC=1
18584 DEPRECATED
18589 CMAKE_WX_CAN_COMPILE
18592 WXWINDOWS_LIBRARY
18593 CMAKE_WX_CXX_FLAGS
18594 WXWINDOWS_INCLUDE_PATH
18595 AUTHOR Jan Woetzel <http://www.mip.informatik.uni-kiel.de/~jw>
18600 (07/2003-01/2006)
18601 FortranCInterface
18604 Fortran/C Interface Detection
18605 This module automatically detects the API by which C and Fortran
18607 languages interact. Variables indicate if the mangling is
18608 found:
18609 FortranCInterface_GLOBAL_FOUND = Global subroutines and functions
18612 FortranCInterface_MODULE_FOUND = Module subroutines and functions
18613 (declared by "MODULE PROCEDURE")
18614 A function is provided to generate a C header file containing
18616 macros to mangle symbol names:
18617 FortranCInterface_HEADER(<file>
18620 [MACRO_NAMESPACE <macro-ns>]
18621 [SYMBOL_NAMESPACE <ns>]
18622 [SYMBOLS [<module>:]<function> ...])
18623 It generates in <file> definitions of the following macros:
18625 #define FortranCInterface_GLOBAL (name,NAME) ...
18628 #define FortranCInterface_GLOBAL_(name,NAME) ...
18629 #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
18630 #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
18631 These macros mangle four categories of Fortran symbols, respec‐
18633 tively:
18634 - Global symbols without '_': call mysub()
18637 - Global symbols with '_' : call my_sub()
18638 - Module symbols without '_': use mymod; call mysub()
18639 - Module symbols with '_' : use mymod; call my_sub()
18640 If mangling for a category is not known, its macro is left unde‐
18642 fined. All macros require raw names in both lower case and upper
18643 case. The MACRO_NAMESPACE option replaces the default "FortranC‐
18644 Interface_" prefix with a given namespace "<macro-ns>".
18645 The SYMBOLS option lists symbols to mangle automatically with C
18648 preprocessor definitions:
18649 <function> ==> #define <ns><function> ...
18652 <module>:<function> ==> #define <ns><module>_<function> ...
18653 If the mangling for some symbol is not known then no preproces‐
18655 sor definition is created, and a warning is displayed. The SYM‐
18656 BOL_NAMESPACE option prefixes all preprocessor definitions gen‐
18657 erated by the SYMBOLS option with a given namespace "<ns>".
18658 Example usage:
18661 include(FortranCInterface)
18664 FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
18665 This creates a "FC.h" header that defines mangling macros
18667 FC_GLOBAL(), FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
18668 Example usage:
18671 include(FortranCInterface)
18674 FortranCInterface_HEADER(FCMangle.h
18675 MACRO_NAMESPACE "FC_"
18676 SYMBOL_NAMESPACE "FC_"
18677 SYMBOLS mysub mymod:my_sub)
18678 This creates a "FCMangle.h" header that defines the same FC_*()
18680 mangling macros as the previous example plus preprocessor sym‐
18681 bols FC_mysub and FC_mymod_my_sub.
18682 Another function is provided to verify that the Fortran and
18685 C/C++ compilers work together:
18686 FortranCInterface_VERIFY([CXX] [QUIET])
18689 It tests whether a simple test executable using Fortran and C
18691 (and C++ when the CXX option is given) compiles and links suc‐
18692 cessfully. The result is stored in the cache entry FortranCIn‐
18693 terface_VERIFIED_C (or FortranCInterface_VERIFIED_CXX if CXX is
18694 given) as a boolean. If the check fails and QUIET is not given
18695 the function terminates with a FATAL_ERROR message describing
18696 the problem. The purpose of this check is to stop a build early
18697 for incompatible compiler combinations. The test is built in
18698 the Release configuration.
18699 FortranCInterface is aware of possible GLOBAL and MODULE man‐
18702 glings for many Fortran compilers, but it also provides an
18703 interface to specify new possible manglings. Set the variables
18704 FortranCInterface_GLOBAL_SYMBOLS
18707 FortranCInterface_MODULE_SYMBOLS
18708 before including FortranCInterface to specify manglings of the
18710 symbols "MySub", "My_Sub", "MyModule:MySub", and "My_Mod‐
18711 ule:My_Sub". For example, the code:
18712 set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
18715 # ^^^^^ ^^^^^^ ^^^^^
18716 set(FortranCInterface_MODULE_SYMBOLS
18717 __mymodule_MOD_mysub __my_module_MOD_my_sub)
18718 # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^
18719 include(FortranCInterface)
18720 tells FortranCInterface to try given GLOBAL and MODULE man‐
18722 glings. (The carets point at raw symbol names for clarity in
18723 this example but are not needed.)
18724 GNUInstallDirs
18727 Define GNU standard installation directories
18728 Provides install directory variables as defined for GNU soft‐
18730 ware:
18731 http://www.gnu.org/prep/standards/html_node/Directory-Variables.html
18734 Inclusion of this module defines the following variables:
18736 CMAKE_INSTALL_<dir> - destination for files of a given type
18739 CMAKE_INSTALL_FULL_<dir> - corresponding absolute path
18740 where <dir> is one of:
18742 BINDIR - user executables (bin)
18745 SBINDIR - system admin executables (sbin)
18746 LIBEXECDIR - program executables (libexec)
18747 SYSCONFDIR - read-only single-machine data (etc)
18748 SHAREDSTATEDIR - modifiable architecture-independent data (com)
18749 LOCALSTATEDIR - modifiable single-machine data (var)
18750 LIBDIR - object code libraries (lib or lib64 or lib/<multiarch-tuple> on Debian)
18751 INCLUDEDIR - C header files (include)
18752 OLDINCLUDEDIR - C header files for non-gcc (/usr/include)
18753 DATAROOTDIR - read-only architecture-independent data root (share)
18754 DATADIR - read-only architecture-independent data (DATAROOTDIR)
18755 INFODIR - info documentation (DATAROOTDIR/info)
18756 LOCALEDIR - locale-dependent data (DATAROOTDIR/locale)
18757 MANDIR - man documentation (DATAROOTDIR/man)
18758 DOCDIR - documentation root (DATAROOTDIR/doc/PROJECT_NAME)
18759 Each CMAKE_INSTALL_<dir> value may be passed to the DESTINATION
18761 options of install() commands for the corresponding file type.
18762 If the includer does not define a value the above-shown default
18763 will be used and the value will appear in the cache for editing
18764 by the user. Each CMAKE_INSTALL_FULL_<dir> value contains an
18765 absolute path constructed from the corresponding destination by
18766 prepending (if necessary) the value of CMAKE_INSTALL_PREFIX.
18767 GenerateExportHeader
18770 Function for generation of export macros for libraries
18771 This module provides the function GENERATE_EXPORT_HEADER() and
18773 the accompanying ADD_COMPILER_EXPORT_FLAGS() function.
18774 The GENERATE_EXPORT_HEADER function can be used to generate a
18777 file suitable for preprocessor inclusion which contains EXPORT
18778 macros to be used in library classes.
18779 GENERATE_EXPORT_HEADER( LIBRARY_TARGET
18782 [BASE_NAME <base_name>]
18785 [EXPORT_MACRO_NAME <export_macro_name>]
18786 [EXPORT_FILE_NAME <export_file_name>]
18787 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
18788 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
18789 [STATIC_DEFINE <static_define>]
18790 [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
18791 [DEFINE_NO_DEPRECATED]
18792 [PREFIX_NAME <prefix_name>]
18793 )
18795 ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
18798 By default GENERATE_EXPORT_HEADER() generates macro names in a
18801 file name determined by the name of the library. The ADD_COM‐
18802 PILER_EXPORT_FLAGS function adds -fvisibility=hidden to
18803 CMAKE_CXX_FLAGS if supported, and is a no-op on Windows which
18804 does not need extra compiler flags for exporting support. You
18805 may optionally pass a single argument to ADD_COM‐
18806 PILER_EXPORT_FLAGS that will be populated with the required
18807 CXX_FLAGS required to enable visibility support for the com‐
18808 piler/architecture in use.
18809 This means that in the simplest case, users of these functions
18812 will be equivalent to:
18813 add_compiler_export_flags()
18816 add_library(somelib someclass.cpp)
18817 generate_export_header(somelib)
18818 install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR})
18819 install(FILES
18820 someclass.h
18821 ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${INCLUDE_INSTALL_DIR}
18822 )
18823 And in the ABI header files:
18828 #include "somelib_export.h"
18831 class SOMELIB_EXPORT SomeClass {
18832 ...
18833 };
18834 The CMake fragment will generate a file in the ${CMAKE_CUR‐
18839 RENT_BINARY_DIR} called somelib_export.h containing the macros
18840 SOMELIB_EXPORT, SOMELIB_NO_EXPORT, SOMELIB_DEPRECATED,
18841 SOMELIB_DEPRECATED_EXPORT and SOMELIB_DEPRECATED_NO_EXPORT. The
18842 resulting file should be installed with other headers in the
18843 library.
18844 The BASE_NAME argument can be used to override the file name and
18847 the names used for the macros
18848 add_library(somelib someclass.cpp)
18851 generate_export_header(somelib
18852 BASE_NAME other_name
18853 )
18854 Generates a file called other_name_export.h containing the
18859 macros OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT and
18860 OTHER_NAME_DEPRECATED etc.
18861 The BASE_NAME may be overridden by specifiying other options in
18864 the function. For example:
18865 add_library(somelib someclass.cpp)
18868 generate_export_header(somelib
18869 EXPORT_MACRO_NAME OTHER_NAME_EXPORT
18870 )
18871 creates the macro OTHER_NAME_EXPORT instead of SOMELIB_EXPORT,
18876 but other macros and the generated file name is as default.
18877 add_library(somelib someclass.cpp)
18880 generate_export_header(somelib
18881 DEPRECATED_MACRO_NAME KDE_DEPRECATED
18882 )
18883 creates the macro KDE_DEPRECATED instead of SOMELIB_DEPRECATED.
18888 If LIBRARY_TARGET is a static library, macros are defined with‐
18891 out values.
18892 If the same sources are used to create both a shared and a
18895 static library, the uppercased symbol ${BASE_NAME}_STATIC_DEFINE
18896 should be used when building the static library
18897 add_library(shared_variant SHARED ${lib_SRCS})
18900 add_library(static_variant ${lib_SRCS})
18901 generate_export_header(shared_variant BASE_NAME libshared_and_static)
18902 set_target_properties(static_variant PROPERTIES
18903 COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)
18904 This will cause the export macros to expand to nothing when
18909 building the static library.
18910 If DEFINE_NO_DEPRECATED is specified, then a macro
18913 ${BASE_NAME}_NO_DEPRECATED will be defined This macro can be
18914 used to remove deprecated code from preprocessor output.
18915 option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
18918 if (EXCLUDE_DEPRECATED)
18919 set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED)
18920 endif()
18921 generate_export_header(somelib ${NO_BUILD_DEPRECATED})
18922 And then in somelib:
18927 class SOMELIB_EXPORT SomeClass
18930 {
18931 public:
18932 #ifndef SOMELIB_NO_DEPRECATED
18933 SOMELIB_DEPRECATED void oldMethod();
18934 #endif
18935 };
18936 #ifndef SOMELIB_NO_DEPRECATED
18941 void SomeClass::oldMethod() { }
18942 #endif
18943 If PREFIX_NAME is specified, the argument will be used as a pre‐
18948 fix to all generated macros.
18949 For example:
18952 generate_export_header(somelib PREFIX_NAME VTK_)
18955 Generates the macros VTK_SOMELIB_EXPORT etc.
18960 GetPrerequisites
18963 Functions to analyze and list executable file prerequisites.
18964 This module provides functions to list the .dll, .dylib or .so
18966 files that an executable or shared library file depends on. (Its
18967 prerequisites.)
18968 It uses various tools to obtain the list of required shared
18971 library files:
18972 dumpbin (Windows)
18975 objdump (MinGW on Windows)
18976 ldd (Linux/Unix)
18977 otool (Mac OSX)
18978 The following functions are provided by this module:
18980 get_prerequisites
18983 list_prerequisites
18984 list_prerequisites_by_glob
18985 gp_append_unique
18986 is_file_executable
18987 gp_item_default_embedded_path
18988 (projects can override with gp_item_default_embedded_path_override)
18989 gp_resolve_item
18990 (projects can override with gp_resolve_item_override)
18991 gp_resolved_file_type
18992 (projects can override with gp_resolved_file_type_override)
18993 gp_file_type
18994 Requires CMake 2.6 or greater because it uses function, break,
18996 return and PARENT_SCOPE.
18997 GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse>
19000 <exepath> <dirs>)
19001 Get the list of shared library files required by <target>. The
19003 list in the variable named <prerequisites_var> should be empty
19004 on first entry to this function. On exit, <prerequisites_var>
19005 will contain the list of required shared library files.
19006 <target> is the full path to an executable file. <prerequi‐
19009 sites_var> is the name of a CMake variable to contain the
19010 results. <exclude_system> must be 0 or 1 indicating whether to
19011 include or exclude "system" prerequisites. If <recurse> is set
19012 to 1 all prerequisites will be found recursively, if set to 0
19013 only direct prerequisites are listed. <exepath> is the path to
19014 the top level executable used for @executable_path replacment on
19015 the Mac. <dirs> is a list of paths where libraries might be
19016 found: these paths are searched first when a target without any
19017 path info is given. Then standard system locations are also
19018 searched: PATH, Framework locations, /usr/lib...
19019 LIST_PREREQUISITES(<target> [<recurse> [<exclude_system> [<verbose>]]])
19022 Print a message listing the prerequisites of <target>.
19024 <target> is the name of a shared library or executable target or
19027 the full path to a shared library or executable file. If
19028 <recurse> is set to 1 all prerequisites will be found recur‐
19029 sively, if set to 0 only direct prerequisites are listed.
19030 <exclude_system> must be 0 or 1 indicating whether to include or
19031 exclude "system" prerequisites. With <verbose> set to 0 only the
19032 full path names of the prerequisites are printed, set to 1 extra
19033 informatin will be displayed.
19034 LIST_PREREQUISITES_BY_GLOB(<glob_arg> <glob_exp>)
19037 Print the prerequisites of shared library and executable files
19039 matching a globbing pattern. <glob_arg> is GLOB or GLOB_RECURSE
19040 and <glob_exp> is a globbing expression used with "file(GLOB" or
19041 "file(GLOB_RECURSE" to retrieve a list of matching files. If a
19042 matching file is executable, its prerequisites are listed.
19043 Any additional (optional) arguments provided are passed along as
19046 the optional arguments to the list_prerequisites calls.
19047 GP_APPEND_UNIQUE(<list_var> <value>)
19050 Append <value> to the list variable <list_var> only if the value
19052 is not already in the list.
19053 IS_FILE_EXECUTABLE(<file> <result_var>)
19056 Return 1 in <result_var> if <file> is a binary executable, 0
19058 otherwise.
19059 GP_ITEM_DEFAULT_EMBEDDED_PATH(<item> <default_embedded_path_var>)
19062 Return the path that others should refer to the item by when the
19064 item is embedded inside a bundle.
19065 Override on a per-project basis by providing a project-specific
19068 gp_item_default_embedded_path_override function.
19069 GP_RESOLVE_ITEM(<context> <item> <exepath> <dirs> <resolved_item_var>)
19072 Resolve an item into an existing full path file.
19074 Override on a per-project basis by providing a project-specific
19077 gp_resolve_item_override function.
19078 GP_RESOLVED_FILE_TYPE(<original_file> <file> <exepath> <dirs> <type_var>)
19081 Return the type of <file> with respect to <original_file>.
19083 String describing type of prerequisite is returned in variable
19084 named <type_var>.
19085 Use <exepath> and <dirs> if necessary to resolve non-absolute
19088 <file> values -- but only for non-embedded items.
19089 Possible types are:
19092 system
19095 local
19096 embedded
19097 other
19098 Override on a per-project basis by providing a project-specific
19100 gp_resolved_file_type_override function.
19101 GP_FILE_TYPE(<original_file> <file> <type_var>)
19104 Return the type of <file> with respect to <original_file>.
19106 String describing type of prerequisite is returned in variable
19107 named <type_var>.
19108 Possible types are:
19111 system
19114 local
19115 embedded
19116 other
19117 InstallRequiredSystemLibraries
19120 By including this file, all library files listed in the variable
19123 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS will be installed with
19124 install(PROGRAMS ...) into bin for WIN32 and lib for non-WIN32.
19125 If CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP is set to TRUE before
19126 including this file, then the INSTALL command is not called. The
19127 user can use the variable CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS to
19128 use a custom install command and install them however they want.
19129 If it is the MSVC compiler, then the microsoft run time
19130 libraries will be found and automatically added to the
19131 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS, and installed. If
19132 CMAKE_INSTALL_DEBUG_LIBRARIES is set and it is the MSVC com‐
19133 piler, then the debug libraries are installed when available. If
19134 CMAKE_INSTALL_DEBUG_LIBRARIES_ONLY is set then only the debug
19135 libraries are installed when both debug and release are avail‐
19136 able. If CMAKE_INSTALL_MFC_LIBRARIES is set then the MFC run
19137 time libraries are installed as well as the CRT run time
19138 libraries. If CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION is set
19139 then the libraries are installed to that directory rather than
19140 the default. If CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_NO_WARNINGS is
19141 NOT set, then this file warns about required files that do not
19142 exist. You can set this variable to ON before including this
19143 file to avoid the warning. For example, the Visual Studio
19144 Express editions do not include the redistributable files, so if
19145 you include this file on a machine with only VS Express
19146 installed, you'll get the warning.
19147 MacroAddFileDependencies
19150 MACRO_ADD_FILE_DEPENDENCIES(<_file> depend_files...)
19151 Using the macro MACRO_ADD_FILE_DEPENDENCIES() is discouraged.
19153 There are usually better ways to specify the correct dependen‐
19154 cies.
19155 MACRO_ADD_FILE_DEPENDENCIES(<_file> depend_files...) is just a
19158 convenience wrapper around the OBJECT_DEPENDS source file prop‐
19159 erty. You can just use set_property(SOURCE <file> APPEND PROP‐
19160 ERTY OBJECT_DEPENDS depend_files) instead.
19161 ProcessorCount
19164 ProcessorCount(var)
19165 Determine the number of processors/cores and save value in
19167 ${var}
19168 Sets the variable named ${var} to the number of physical cores
19171 available on the machine if the information can be determined.
19172 Otherwise it is set to 0. Currently this functionality is imple‐
19173 mented for AIX, cygwin, FreeBSD, HPUX, IRIX, Linux, Mac OS X,
19174 QNX, Sun and Windows.
19175 This function is guaranteed to return a positive integer (>=1)
19178 if it succeeds. It returns 0 if there's a problem determining
19179 the processor count.
19180 Example use, in a ctest -S dashboard script:
19183 include(ProcessorCount)
19186 ProcessorCount(N)
19187 if(NOT N EQUAL 0)
19188 set(CTEST_BUILD_FLAGS -j${N})
19189 set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N})
19190 endif()
19191 This function is intended to offer an approximation of the value
19196 of the number of compute cores available on the current machine,
19197 such that you may use that value for parallel building and par‐
19198 allel testing. It is meant to help utilize as much of the
19199 machine as seems reasonable. Of course, knowledge of what else
19200 might be running on the machine simultaneously should be used
19201 when deciding whether to request a machine's full capacity all
19202 for yourself.
19203 Qt4ConfigDependentSettings
19206 This file is included by FindQt4.cmake, don't include it
19209 directly.
19210 Qt4Macros
19213 This file is included by FindQt4.cmake, don't include it
19216 directly.
19217 SelectLibraryConfigurations
19220 select_library_configurations( basename )
19223 This macro takes a library base name as an argument, and will
19226 choose good values for basename_LIBRARY, basename_LIBRARIES,
19227 basename_LIBRARY_DEBUG, and basename_LIBRARY_RELEASE depending
19228 on what has been found and set. If only base‐
19229 name_LIBRARY_RELEASE is defined, basename_LIBRARY will be set to
19230 the release value, and basename_LIBRARY_DEBUG will be set to
19231 basename_LIBRARY_DEBUG-NOTFOUND. If only basename_LIBRARY_DEBUG
19232 is defined, then basename_LIBRARY will take the debug value, and
19233 basename_LIBRARY_RELEASE will be set to base‐
19234 name_LIBRARY_RELEASE-NOTFOUND.
19235 If the generator supports configuration types, then base‐
19238 name_LIBRARY and basename_LIBRARIES will be set with debug and
19239 optimized flags specifying the library to be used for the given
19240 configuration. If no build type has been set or the generator
19241 in use does not support configuration types, then base‐
19242 name_LIBRARY and basename_LIBRARIES will take only the release
19243 value, or the debug value if the release one is not set.
19244 SquishTestScript
19247 This script launches a GUI test using Squish. You should not
19253 call the script directly; instead, you should access it via the
19254 SQUISH_ADD_TEST macro that is defined in FindSquish.cmake.
19255 This script starts the Squish server, launches the test on the
19258 client, and finally stops the squish server. If any of these
19259 steps fail (including if the tests do not pass) then a fatal
19260 error is raised.
19261 TestBigEndian
19265 Define macro to determine endian type
19266 Check if the system is big endian or little endian
19268 TEST_BIG_ENDIAN(VARIABLE)
19271 VARIABLE - variable to store the result to
19272 TestCXXAcceptsFlag
19278 Test CXX compiler for a flag
19279 Check if the CXX compiler accepts a flag
19281 Macro CHECK_CXX_ACCEPTS_FLAG(FLAGS VARIABLE) -
19284 checks if the function exists
19285 FLAGS - the flags to try
19286 VARIABLE - variable to store the result
19287 TestForANSIForScope
19293 Check for ANSI for scope support
19294 Check if the compiler restricts the scope of variables declared
19296 in a for-init-statement to the loop body.
19297 CMAKE_NO_ANSI_FOR_SCOPE - holds result
19300 TestForANSIStreamHeaders
19306 Test for compiler support of ANSI stream headers iostream, etc.
19307 check if the compiler supports the standard ANSI iostream header
19309 (without the .h)
19310 CMAKE_NO_ANSI_STREAM_HEADERS - defined by the results
19313 TestForSSTREAM
19319 Test for compiler support of ANSI sstream header
19320 check if the compiler supports the standard ANSI sstream header
19322 CMAKE_NO_ANSI_STRING_STREAM - defined by the results
19325 TestForSTDNamespace
19331 Test for std:: namespace support
19332 check if the compiler supports std:: on stl classes
19334 CMAKE_NO_STD_NAMESPACE - defined by the results
19337 UseEcos
19343 This module defines variables and macros required to build eCos
19344 application.
19345 This file contains the following macros: ECOS_ADD_INCLUDE_DIREC‐
19347 TORIES() - add the eCos include dirs ECOS_ADD_EXECUTABLE(name
19348 source1 ... sourceN ) - create an eCos executable
19349 ECOS_ADJUST_DIRECTORY(VAR source1 ... sourceN ) - adjusts the
19350 path of the source files and puts the result into VAR
19351 Macros for selecting the toolchain: ECOS_USE_ARM_ELF_TOOLS()
19354 - enable the ARM ELF toolchain for the directory where it is
19355 called ECOS_USE_I386_ELF_TOOLS() - enable the i386 ELF
19356 toolchain for the directory where it is called
19357 ECOS_USE_PPC_EABI_TOOLS() - enable the PowerPC toolchain
19358 for the directory where it is called
19359 It contains the following variables: ECOS_DEFINITIONS ECOSCON‐
19362 FIG_EXECUTABLE ECOS_CONFIG_FILE - defaults to
19363 ecos.ecc, if your eCos configuration file has a different name,
19364 adjust this variable for internal use only:
19365 ECOS_ADD_TARGET_LIB
19368 UseJava
19371 Use Module for Java
19372 This file provides functions for Java. It is assumed that Find‐
19374 Java.cmake has already been loaded. See FindJava.cmake for
19375 information on how to load Java into your CMake project.
19376 add_jar(target_name
19379 [SOURCES] source1 [source2 ...] [resource1 ...]
19382 [INCLUDE_JARS jar1 [jar2 ...]]
19383 [ENTRY_POINT entry]
19384 [VERSION version]
19385 [OUTPUT_NAME name]
19386 [OUTPUT_DIR dir]
19387 )
19388 This command creates a <target_name>.jar. It compiles the given
19393 source files (source) and adds the given resource files
19394 (resource) to the jar file. If only resource files are given
19395 then just a jar file is created. The list of include jars are
19396 added to the classpath when compiling the java sources and also
19397 to the dependencies of the target. INCLUDE_JARS also accepts
19398 other target names created by add_jar. For backwards compatibil‐
19399 ity, jar files listed as sources are ignored (as they have been
19400 since the first version of this module).
19401 The default OUTPUT_DIR can also be changed by setting the vari‐
19404 able CMAKE_JAVA_TARGET_OUTPUT_DIR.
19405 Additional instructions:
19408 To add compile flags to the target you can set these flags with
19411 the following variable:
19412 set(CMAKE_JAVA_COMPILE_FLAGS -nowarn)
19417 To add a path or a jar file to the class path you can do this
19422 with the CMAKE_JAVA_INCLUDE_PATH variable.
19423 set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar)
19428 To use a different output name for the target you can set it with:
19433 add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar)
19438 To use a different output directory than CMAKE_CURRENT_BINARY_DIR
19443 you can set it with:
19444 add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin)
19449 To define an entry point in your jar you can set it with the ENTRY_POINT
19454 named argument:
19455 add_jar(example ENTRY_POINT com/examples/MyProject/Main)
19460 To add a VERSION to the target output name you can set it using
19465 the VERSION named argument to add_jar. This will create a jar file with the
19466 name shibboleet-1.0.0.jar and will create a symlink shibboleet.jar
19467 pointing to the jar with the version information.
19468 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
19473 If the target is a JNI library, utilize the following commands to
19478 create a JNI symbolic link:
19479 set(CMAKE_JNI_TARGET TRUE)
19484 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
19485 install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
19486 install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})
19487 If a single target needs to produce more than one jar from its
19492 java source code, to prevent the accumulation of duplicate class
19493 files in subsequent jars, set/reset CMAKE_JAR_CLASSES_PREFIX prior
19494 to calling the add_jar() function:
19495 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
19500 add_jar(foo foo.java)
19501 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
19506 add_jar(bar bar.java)
19507 Target Properties:
19512 The add_jar() functions sets some target properties. You can get these
19515 properties with the
19516 get_property(TARGET <target_name> PROPERTY <propery_name>)
19517 command.
19518 INSTALL_FILES The files which should be installed. This is used by
19523 install_jar().
19524 JNI_SYMLINK The JNI symlink which should be installed.
19525 This is used by install_jni_symlink().
19526 JAR_FILE The location of the jar file so that you can include
19527 it.
19528 CLASS_DIR The directory where the class files can be found. For
19529 example to use them with javah.
19530 find_jar(<VAR>
19535 name | NAMES name1 [name2 ...]
19538 [PATHS path1 [path2 ... ENV var]]
19539 [VERSIONS version1 [version2]]
19540 [DOC "cache documentation string"]
19541 )
19542 This command is used to find a full path to the named jar. A
19547 cache entry named by <VAR> is created to stor the result of this
19548 command. If the full path to a jar is found the result is stored
19549 in the variable and the search will not repeated unless the
19550 variable is cleared. If nothing is found, the result will be
19551 <VAR>-NOTFOUND, and the search will be attempted again next time
19552 find_jar is invoked with the same variable. The name of the full
19553 path to a file that is searched for is specified by the names
19554 listed after NAMES argument. Additional search locations can be
19555 specified after the PATHS argument. If you require special a
19556 version of a jar file you can specify it with the VERSIONS argu‐
19557 ment. The argument after DOC will be used for the documentation
19558 string in the cache.
19559 install_jar(TARGET_NAME DESTINATION)
19562 This command installs the TARGET_NAME files to the given DESTI‐
19565 NATION. It should be called in the same scope as add_jar() or it
19566 will fail.
19567 install_jni_symlink(TARGET_NAME DESTINATION)
19570 This command installs the TARGET_NAME JNI symlinks to the given
19573 DESTINATION. It should be called in the same scope as add_jar()
19574 or it will fail.
19575 create_javadoc(<VAR>
19578 PACKAGES pkg1 [pkg2 ...]
19581 [SOURCEPATH <sourcepath>]
19582 [CLASSPATH <classpath>]
19583 [INSTALLPATH <install path>]
19584 [DOCTITLE "the documentation title"]
19585 [WINDOWTITLE "the title of the document"]
19586 [AUTHOR TRUE|FALSE]
19587 [USE TRUE|FALSE]
19588 [VERSION TRUE|FALSE]
19589 )
19590 Create java documentation based on files or packages. For more
19595 details please read the javadoc manpage.
19596 There are two main signatures for create_javadoc. The first sig‐
19599 nature works with package names on a path with source files:
19600 Example:
19603 create_javadoc(my_example_doc
19604 PACKAGES com.exmaple.foo com.example.bar
19605 SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
19606 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
19607 WINDOWTITLE "My example"
19608 DOCTITLE "<h1>My example</h1>"
19609 AUTHOR TRUE
19610 USE TRUE
19611 VERSION TRUE
19612 )
19613 The second signature for create_javadoc works on a given list of
19618 files.
19619 create_javadoc(<VAR>
19622 FILES file1 [file2 ...]
19623 [CLASSPATH <classpath>]
19624 [INSTALLPATH <install path>]
19625 [DOCTITLE "the documentation title"]
19626 [WINDOWTITLE "the title of the document"]
19627 [AUTHOR TRUE|FALSE]
19628 [USE TRUE|FALSE]
19629 [VERSION TRUE|FALSE]
19630 )
19631 Example:
19636 create_javadoc(my_example_doc
19639 FILES ${example_SRCS}
19640 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
19641 WINDOWTITLE "My example"
19642 DOCTITLE "<h1>My example</h1>"
19643 AUTHOR TRUE
19644 USE TRUE
19645 VERSION TRUE
19646 )
19647 Both signatures share most of the options. These options are the
19652 same as what you can find in the javadoc manpage. Please look at
19653 the manpage for CLASSPATH, DOCTITLE, WINDOWTITLE, AUTHOR, USE
19654 and VERSION.
19655 The documentation will be by default installed to
19658 ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>
19661 if you don't set the INSTALLPATH.
19666 UseJavaClassFilelist
19670 This script create a list of compiled Java class files to be
19676 added to a jar file. This avoids including cmake files which get
19677 created in the binary directory.
19678 UseJavaSymlinks
19682 Helper script for UseJava.cmake
19688 UsePkgConfig
19692 Obsolete pkg-config module for CMake, use FindPkgConfig instead.
19693 This module defines the following macro:
19698 PKGCONFIG(package includedir libdir linkflags cflags)
19701 Calling PKGCONFIG will fill the desired information into the 4
19704 given arguments, e.g. PKGCONFIG(libart-2.0 LIBART_INCLUDE_DIR
19705 LIBART_LINK_DIR LIBART_LINK_FLAGS LIBART_CFLAGS) if pkg-config
19706 was NOT found or the specified software package doesn't exist,
19707 the variable will be empty when the function returns, otherwise
19708 they will contain the respective information
19709 UseQt4 Use Module for QT4
19713 Sets up C and C++ to use Qt 4. It is assumed that FindQt.cmake
19715 has already been loaded. See FindQt.cmake for information on
19716 how to load Qt 4 into your CMake project.
19717 UseSWIG
19720 SWIG module for CMake
19721 Defines the following macros:
19723 SWIG_ADD_MODULE(name language [ files ])
19726 - Define swig module with given name and specified language
19727 SWIG_LINK_LIBRARIES(name [ libraries ])
19728 - Link libraries to swig module
19729 All other macros are for internal use only. To get the actual
19731 name of the swig module, use: ${SWIG_MODULE_${name}_REAL_NAME}.
19732 Set Source files properties such as CPLUSPLUS and SWIG_FLAGS to
19733 specify special behavior of SWIG. Also global CMAKE_SWIG_FLAGS
19734 can be used to add special flags to all swig calls. Another spe‐
19735 cial variable is CMAKE_SWIG_OUTDIR, it allows one to specify
19736 where to write all the swig generated module (swig -outdir
19737 option) The name-specific variable SWIG_MODULE_<name>_EXTRA_DEPS
19738 may be used to specify extra dependencies for the generated mod‐
19739 ules. If the source file generated by swig need some special
19740 flag you can use set_source_files_properties( ${swig_gener‐
19741 ated_file_fullname}
19742 PROPERTIES COMPILE_FLAGS "-bla")
19745 Use_wxWindows
19748 ---------------------------------------------------
19749 This convenience include finds if wxWindows is installed and set
19754 the appropriate libs, incdirs, flags etc. author Jan Woetzel <jw
19755 -at- mip.informatik.uni-kiel.de> (07/2003) USAGE:
19756 just include Use_wxWindows.cmake
19759 in your projects CMakeLists.txt
19760 include( ${CMAKE_MODULE_PATH}/Use_wxWindows.cmake)
19762 if you are sure you need GL then
19765 set(WXWINDOWS_USE_GL 1)
19767 *before* you include this file.
19770 UsewxWidgets
19773 Convenience include for using wxWidgets library.
19774 Determines if wxWidgets was FOUND and sets the appropriate libs,
19776 incdirs, flags, etc. INCLUDE_DIRECTORIES and LINK_DIRECTORIES
19777 are called.
19778 USAGE
19781 # Note that for MinGW users the order of libs is important!
19784 find_package(wxWidgets REQUIRED net gl core base)
19785 include(${wxWidgets_USE_FILE})
19786 # and for each of your dependent executable/library targets:
19787 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
19788 DEPRECATED
19793 LINK_LIBRARIES is not called in favor of adding dependencies per target.
19796 AUTHOR
19801 Jan Woetzel <jw -at- mip.informatik.uni-kiel.de>
19804 WriteBasicConfigVersionFile
19807 WRITE_BASIC_CONFIG_VERSION_FILE( filename VERSION major.minor.patch COMPATIBILITY (AnyNewerVersion|SameMajorVersion) )
19810 Deprecated, see WRITE_BASIC_PACKAGE_VERSION_FILE(), it is iden‐
19815 tical.
19816
19819 CMP0000
19820 A minimum required CMake version must be specified.
19821 CMake requires that projects specify the version of CMake to
19823 which they have been written. This policy has been put in place
19824 so users trying to build the project may be told when they need
19825 to update their CMake. Specifying a version also helps the
19826 project build with CMake versions newer than that specified.
19827 Use the cmake_minimum_required command at the top of your main
19828 CMakeLists.txt file:
19829 cmake_minimum_required(VERSION <major>.<minor>)
19832 where "<major>.<minor>" is the version of CMake you want to sup‐
19834 port (such as "2.6"). The command will ensure that at least the
19835 given version of CMake is running and help newer versions be
19836 compatible with the project. See documentation of cmake_mini‐
19837 mum_required for details.
19838 Note that the command invocation must appear in the CMake‐
19841 Lists.txt file itself; a call in an included file is not suffi‐
19842 cient. However, the cmake_policy command may be called to set
19843 policy CMP0000 to OLD or NEW behavior explicitly. The OLD
19844 behavior is to silently ignore the missing invocation. The NEW
19845 behavior is to issue an error instead of a warning. An included
19846 file may set CMP0000 explicitly to affect how this policy is
19847 enforced for the main CMakeLists.txt file.
19848 This policy was introduced in CMake version 2.6.0.
19851 CMP0001
19854 CMAKE_BACKWARDS_COMPATIBILITY should no longer be used.
19855 The OLD behavior is to check CMAKE_BACKWARDS_COMPATIBILITY and
19857 present it to the user. The NEW behavior is to ignore
19858 CMAKE_BACKWARDS_COMPATIBILITY completely.
19859 In CMake 2.4 and below the variable CMAKE_BACKWARDS_COMPATIBIL‐
19862 ITY was used to request compatibility with earlier versions of
19863 CMake. In CMake 2.6 and above all compatibility issues are han‐
19864 dled by policies and the cmake_policy command. However, CMake
19865 must still check CMAKE_BACKWARDS_COMPATIBILITY for projects
19866 written for CMake 2.4 and below.
19867 This policy was introduced in CMake version 2.6.0. CMake ver‐
19870 sion 2.8.12.2 warns when the policy is not set and uses OLD
19871 behavior. Use the cmake_policy command to set it to OLD or NEW
19872 explicitly.
19873 CMP0002
19876 Logical target names must be globally unique.
19877 Targets names created with add_executable, add_library, or
19879 add_custom_target are logical build target names. Logical tar‐
19880 get names must be globally unique because:
19881 - Unique names may be referenced unambiguously both in CMake
19884 code and on make tool command lines.
19885 - Logical names are used by Xcode and VS IDE generators
19886 to produce meaningful project names for the targets.
19887 The logical name of executable and library targets does not have
19889 to correspond to the physical file names built. Consider using
19890 the OUTPUT_NAME target property to create two targets with the
19891 same physical name while keeping logical names distinct. Custom
19892 targets must simply have globally unique names (unless one uses
19893 the global property ALLOW_DUPLICATE_CUSTOM_TARGETS with a Make‐
19894 files generator).
19895 This policy was introduced in CMake version 2.6.0. CMake ver‐
19898 sion 2.8.12.2 warns when the policy is not set and uses OLD
19899 behavior. Use the cmake_policy command to set it to OLD or NEW
19900 explicitly.
19901 CMP0003
19904 Libraries linked via full path no longer produce linker search
19905 paths.
19906 This policy affects how libraries whose full paths are NOT known
19908 are found at link time, but was created due to a change in how
19909 CMake deals with libraries whose full paths are known. Consider
19910 the code
19911 target_link_libraries(myexe /path/to/libA.so)
19914 CMake 2.4 and below implemented linking to libraries whose full
19916 paths are known by splitting them on the link line into separate
19917 components consisting of the linker search path and the library
19918 name. The example code might have produced something like
19919 ... -L/path/to -lA ...
19922 in order to link to library A. An analysis was performed to
19924 order multiple link directories such that the linker would find
19925 library A in the desired location, but there are cases in which
19926 this does not work. CMake versions 2.6 and above use the more
19927 reliable approach of passing the full path to libraries directly
19928 to the linker in most cases. The example code now produces
19929 something like
19930 ... /path/to/libA.so ....
19933 Unfortunately this change can break code like
19935 target_link_libraries(myexe /path/to/libA.so B)
19938 where "B" is meant to find "/path/to/libB.so". This code is
19940 wrong because the user is asking the linker to find library B
19941 but has not provided a linker search path (which may be added
19942 with the link_directories command). However, with the old link‐
19943 ing implementation the code would work accidentally because the
19944 linker search path added for library A allowed library B to be
19945 found.
19946 In order to support projects depending on linker search paths
19949 added by linking to libraries with known full paths, the OLD
19950 behavior for this policy will add the linker search paths even
19951 though they are not needed for their own libraries. When this
19952 policy is set to OLD, CMake will produce a link line such as
19953 ... -L/path/to /path/to/libA.so -lB ...
19956 which will allow library B to be found as it was previously.
19958 When this policy is set to NEW, CMake will produce a link line
19959 such as
19960 ... /path/to/libA.so -lB ...
19963 which more accurately matches what the project specified.
19965 The setting for this policy used when generating the link line
19968 is that in effect when the target is created by an add_exe‐
19969 cutable or add_library command. For the example described
19970 above, the code
19971 cmake_policy(SET CMP0003 OLD) # or cmake_policy(VERSION 2.4)
19974 add_executable(myexe myexe.c)
19975 target_link_libraries(myexe /path/to/libA.so B)
19976 will work and suppress the warning for this policy. It may also
19978 be updated to work with the corrected linking approach:
19979 cmake_policy(SET CMP0003 NEW) # or cmake_policy(VERSION 2.6)
19982 link_directories(/path/to) # needed to find library B
19983 add_executable(myexe myexe.c)
19984 target_link_libraries(myexe /path/to/libA.so B)
19985 Even better, library B may be specified with a full path:
19987 add_executable(myexe myexe.c)
19990 target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)
19991 When all items on the link line have known paths CMake does not
19993 check this policy so it has no effect.
19994 Note that the warning for this policy will be issued for at most
19997 one target. This avoids flooding users with messages for every
19998 target when setting the policy once will probably fix all tar‐
19999 gets.
20000 This policy was introduced in CMake version 2.6.0. CMake ver‐
20003 sion 2.8.12.2 warns when the policy is not set and uses OLD
20004 behavior. Use the cmake_policy command to set it to OLD or NEW
20005 explicitly.
20006 CMP0004
20009 Libraries linked may not have leading or trailing whitespace.
20010 CMake versions 2.4 and below silently removed leading and trail‐
20012 ing whitespace from libraries linked with code like
20013 target_link_libraries(myexe " A ")
20016 This could lead to subtle errors in user projects.
20018 The OLD behavior for this policy is to silently remove leading
20021 and trailing whitespace. The NEW behavior for this policy is to
20022 diagnose the existence of such whitespace as an error. The set‐
20023 ting for this policy used when checking the library names is
20024 that in effect when the target is created by an add_executable
20025 or add_library command.
20026 This policy was introduced in CMake version 2.6.0. CMake ver‐
20029 sion 2.8.12.2 warns when the policy is not set and uses OLD
20030 behavior. Use the cmake_policy command to set it to OLD or NEW
20031 explicitly.
20032 CMP0005
20035 Preprocessor definition values are now escaped automatically.
20036 This policy determines whether or not CMake should generate
20038 escaped preprocessor definition values added via add_defini‐
20039 tions. CMake versions 2.4 and below assumed that only trivial
20040 values would be given for macros in add_definitions calls. It
20041 did not attempt to escape non-trivial values such as string lit‐
20042 erals in generated build rules. CMake versions 2.6 and above
20043 support escaping of most values, but cannot assume the user has
20044 not added escapes already in an attempt to work around limita‐
20045 tions in earlier versions.
20046 The OLD behavior for this policy is to place definition values
20049 given to add_definitions directly in the generated build rules
20050 without attempting to escape anything. The NEW behavior for
20051 this policy is to generate correct escapes for all native build
20052 tools automatically. See documentation of the COMPILE_DEFINI‐
20053 TIONS target property for limitations of the escaping implemen‐
20054 tation.
20055 This policy was introduced in CMake version 2.6.0. CMake ver‐
20058 sion 2.8.12.2 warns when the policy is not set and uses OLD
20059 behavior. Use the cmake_policy command to set it to OLD or NEW
20060 explicitly.
20061 CMP0006
20064 Installing MACOSX_BUNDLE targets requires a BUNDLE DESTINATION.
20065 This policy determines whether the install(TARGETS) command must
20067 be given a BUNDLE DESTINATION when asked to install a target
20068 with the MACOSX_BUNDLE property set. CMake 2.4 and below did
20069 not distinguish application bundles from normal executables when
20070 installing targets. CMake 2.6 provides a BUNDLE option to the
20071 install(TARGETS) command that specifies rules specific to appli‐
20072 cation bundles on the Mac. Projects should use this option when
20073 installing a target with the MACOSX_BUNDLE property set.
20074 The OLD behavior for this policy is to fall back to the RUNTIME
20077 DESTINATION if a BUNDLE DESTINATION is not given. The NEW
20078 behavior for this policy is to produce an error if a bundle tar‐
20079 get is installed without a BUNDLE DESTINATION.
20080 This policy was introduced in CMake version 2.6.0. CMake ver‐
20083 sion 2.8.12.2 warns when the policy is not set and uses OLD
20084 behavior. Use the cmake_policy command to set it to OLD or NEW
20085 explicitly.
20086 CMP0007
20089 list command no longer ignores empty elements.
20090 This policy determines whether the list command will ignore
20092 empty elements in the list. CMake 2.4 and below list commands
20093 ignored all empty elements in the list. For example, a;b;;c
20094 would have length 3 and not 4. The OLD behavior for this policy
20095 is to ignore empty list elements. The NEW behavior for this pol‐
20096 icy is to correctly count empty elements in a list.
20097 This policy was introduced in CMake version 2.6.0. CMake ver‐
20100 sion 2.8.12.2 warns when the policy is not set and uses OLD
20101 behavior. Use the cmake_policy command to set it to OLD or NEW
20102 explicitly.
20103 CMP0008
20106 Libraries linked by full-path must have a valid library file
20107 name.
20108 In CMake 2.4 and below it is possible to write code like
20110 target_link_libraries(myexe /full/path/to/somelib)
20113 where "somelib" is supposed to be a valid library file name such
20115 as "libsomelib.a" or "somelib.lib". For Makefile generators
20116 this produces an error at build time because the dependency on
20117 the full path cannot be found. For VS IDE and Xcode generators
20118 this used to work by accident because CMake would always split
20119 off the library directory and ask the linker to search for the
20120 library by name (-lsomelib or somelib.lib). Despite the failure
20121 with Makefiles, some projects have code like this and build only
20122 with VS and/or Xcode. This version of CMake prefers to pass the
20123 full path directly to the native build tool, which will fail in
20124 this case because it does not name a valid library file.
20125 This policy determines what to do with full paths that do not
20128 appear to name a valid library file. The OLD behavior for this
20129 policy is to split the library name from the path and ask the
20130 linker to search for it. The NEW behavior for this policy is to
20131 trust the given path and pass it directly to the native build
20132 tool unchanged.
20133 This policy was introduced in CMake version 2.6.1. CMake ver‐
20136 sion 2.8.12.2 warns when the policy is not set and uses OLD
20137 behavior. Use the cmake_policy command to set it to OLD or NEW
20138 explicitly.
20139 CMP0009
20142 FILE GLOB_RECURSE calls should not follow symlinks by default.
20143 In CMake 2.6.1 and below, FILE GLOB_RECURSE calls would follow
20145 through symlinks, sometimes coming up with unexpectedly large
20146 result sets because of symlinks to top level directories that
20147 contain hundreds of thousands of files.
20148 This policy determines whether or not to follow symlinks encoun‐
20151 tered during a FILE GLOB_RECURSE call. The OLD behavior for this
20152 policy is to follow the symlinks. The NEW behavior for this pol‐
20153 icy is not to follow the symlinks by default, but only if FOL‐
20154 LOW_SYMLINKS is given as an additional argument to the FILE com‐
20155 mand.
20156 This policy was introduced in CMake version 2.6.2. CMake ver‐
20159 sion 2.8.12.2 warns when the policy is not set and uses OLD
20160 behavior. Use the cmake_policy command to set it to OLD or NEW
20161 explicitly.
20162 CMP0010
20165 Bad variable reference syntax is an error.
20166 In CMake 2.6.2 and below, incorrect variable reference syntax
20168 such as a missing close-brace ("${FOO") was reported but did not
20169 stop processing of CMake code. This policy determines whether a
20170 bad variable reference is an error. The OLD behavior for this
20171 policy is to warn about the error, leave the string untouched,
20172 and continue. The NEW behavior for this policy is to report an
20173 error.
20174 This policy was introduced in CMake version 2.6.3. CMake ver‐
20177 sion 2.8.12.2 warns when the policy is not set and uses OLD
20178 behavior. Use the cmake_policy command to set it to OLD or NEW
20179 explicitly.
20180 CMP0011
20183 Included scripts do automatic cmake_policy PUSH and POP.
20184 In CMake 2.6.2 and below, CMake Policy settings in scripts
20186 loaded by the include() and find_package() commands would affect
20187 the includer. Explicit invocations of cmake_policy(PUSH) and
20188 cmake_policy(POP) were required to isolate policy changes and
20189 protect the includer. While some scripts intend to affect the
20190 policies of their includer, most do not. In CMake 2.6.3 and
20191 above, include() and find_package() by default PUSH and POP an
20192 entry on the policy stack around an included script, but provide
20193 a NO_POLICY_SCOPE option to disable it. This policy determines
20194 whether or not to imply NO_POLICY_SCOPE for compatibility. The
20195 OLD behavior for this policy is to imply NO_POLICY_SCOPE for
20196 include() and find_package() commands. The NEW behavior for
20197 this policy is to allow the commands to do their default
20198 cmake_policy PUSH and POP.
20199 This policy was introduced in CMake version 2.6.3. CMake ver‐
20202 sion 2.8.12.2 warns when the policy is not set and uses OLD
20203 behavior. Use the cmake_policy command to set it to OLD or NEW
20204 explicitly.
20205 CMP0012
20208 if() recognizes numbers and boolean constants.
20209 In CMake versions 2.6.4 and lower the if() command implicitly
20211 dereferenced arguments corresponding to variables, even those
20212 named like numbers or boolean constants, except for 0 and 1.
20213 Numbers and boolean constants such as true, false, yes, no, on,
20214 off, y, n, notfound, ignore (all case insensitive) were recog‐
20215 nized in some cases but not all. For example, the code
20216 "if(TRUE)" might have evaluated as false. Numbers such as 2
20217 were recognized only in boolean expressions like "if(NOT 2)"
20218 (leading to false) but not as a single-argument like "if(2)"
20219 (also leading to false). Later versions of CMake prefer to treat
20220 numbers and boolean constants literally, so they should not be
20221 used as variable names.
20222 The OLD behavior for this policy is to implicitly dereference
20225 variables named like numbers and boolean constants. The NEW
20226 behavior for this policy is to recognize numbers and boolean
20227 constants without dereferencing variables with such names.
20228 This policy was introduced in CMake version 2.8.0. CMake ver‐
20231 sion 2.8.12.2 warns when the policy is not set and uses OLD
20232 behavior. Use the cmake_policy command to set it to OLD or NEW
20233 explicitly.
20234 CMP0013
20237 Duplicate binary directories are not allowed.
20238 CMake 2.6.3 and below silently permitted add_subdirectory()
20240 calls to create the same binary directory multiple times. Dur‐
20241 ing build system generation files would be written and then
20242 overwritten in the build tree and could lead to strange behav‐
20243 ior. CMake 2.6.4 and above explicitly detect duplicate binary
20244 directories. CMake 2.6.4 always considers this case an error.
20245 In CMake 2.8.0 and above this policy determines whether or not
20246 the case is an error. The OLD behavior for this policy is to
20247 allow duplicate binary directories. The NEW behavior for this
20248 policy is to disallow duplicate binary directories with an
20249 error.
20250 This policy was introduced in CMake version 2.8.0. CMake ver‐
20253 sion 2.8.12.2 warns when the policy is not set and uses OLD
20254 behavior. Use the cmake_policy command to set it to OLD or NEW
20255 explicitly.
20256 CMP0014
20259 Input directories must have CMakeLists.txt.
20260 CMake versions before 2.8 silently ignored missing CMake‐
20262 Lists.txt files in directories referenced by add_subdirectory()
20263 or subdirs(), treating them as if present but empty. In CMake
20264 2.8.0 and above this policy determines whether or not the case
20265 is an error. The OLD behavior for this policy is to silently
20266 ignore the problem. The NEW behavior for this policy is to
20267 report an error.
20268 This policy was introduced in CMake version 2.8.0. CMake ver‐
20271 sion 2.8.12.2 warns when the policy is not set and uses OLD
20272 behavior. Use the cmake_policy command to set it to OLD or NEW
20273 explicitly.
20274 CMP0015
20277 link_directories() treats paths relative to the source dir.
20278 In CMake 2.8.0 and lower the link_directories() command passed
20280 relative paths unchanged to the linker. In CMake 2.8.1 and
20281 above the link_directories() command prefers to interpret rela‐
20282 tive paths with respect to CMAKE_CURRENT_SOURCE_DIR, which is
20283 consistent with include_directories() and other commands. The
20284 OLD behavior for this policy is to use relative paths verbatim
20285 in the linker command. The NEW behavior for this policy is to
20286 convert relative paths to absolute paths by appending the rela‐
20287 tive path to CMAKE_CURRENT_SOURCE_DIR.
20288 This policy was introduced in CMake version 2.8.1. CMake ver‐
20291 sion 2.8.12.2 warns when the policy is not set and uses OLD
20292 behavior. Use the cmake_policy command to set it to OLD or NEW
20293 explicitly.
20294 CMP0016
20297 target_link_libraries() reports error if its only argument is
20298 not a target.
20299 In CMake 2.8.2 and lower the target_link_libraries() command
20301 silently ignored if it was called with only one argument, and
20302 this argument wasn't a valid target. In CMake 2.8.3 and above it
20303 reports an error in this case.
20304 This policy was introduced in CMake version 2.8.3. CMake ver‐
20307 sion 2.8.12.2 warns when the policy is not set and uses OLD
20308 behavior. Use the cmake_policy command to set it to OLD or NEW
20309 explicitly.
20310 CMP0017
20313 Prefer files from the CMake module directory when including from
20314 there.
20315 Starting with CMake 2.8.4, if a cmake-module shipped with CMake
20317 (i.e. located in the CMake module directory) calls include() or
20318 find_package(), the files located in the CMake module directory
20319 are preferred over the files in CMAKE_MODULE_PATH. This makes
20320 sure that the modules belonging to CMake always get those files
20321 included which they expect, and against which they were devel‐
20322 oped and tested. In all other cases, the files found in
20323 CMAKE_MODULE_PATH still take precedence over the ones in the
20324 CMake module directory. The OLD behaviour is to always prefer
20325 files from CMAKE_MODULE_PATH over files from the CMake modules
20326 directory.
20327 This policy was introduced in CMake version 2.8.4. CMake ver‐
20330 sion 2.8.12.2 warns when the policy is not set and uses OLD
20331 behavior. Use the cmake_policy command to set it to OLD or NEW
20332 explicitly.
20333 CMP0018
20336 Ignore CMAKE_SHARED_LIBRARY_<Lang>_FLAGS variable.
20337 CMake 2.8.8 and lower compiled sources in SHARED and MODULE
20339 libraries using the value of the undocumented
20340 CMAKE_SHARED_LIBRARY_<Lang>_FLAGS platform variable. The vari‐
20341 able contained platform-specific flags needed to compile objects
20342 for shared libraries. Typically it included a flag such as
20343 -fPIC for position independent code but also included other
20344 flags needed on certain platforms. CMake 2.8.9 and higher pre‐
20345 fer instead to use the POSITION_INDEPENDENT_CODE target property
20346 to determine what targets should be position independent, and
20347 new undocumented platform variables to select flags while ignor‐
20348 ing CMAKE_SHARED_LIBRARY_<Lang>_FLAGS completely.
20349 The default for either approach produces identical compilation
20352 flags, but if a project modifies
20353 CMAKE_SHARED_LIBRARY_<Lang>_FLAGS from its original value this
20354 policy determines which approach to use.
20355 The OLD behavior for this policy is to ignore the POSITION_INDE‐
20358 PENDENT_CODE property for all targets and use the modified value
20359 of CMAKE_SHARED_LIBRARY_<Lang>_FLAGS for SHARED and MODULE
20360 libraries.
20361 The NEW behavior for this policy is to ignore
20364 CMAKE_SHARED_LIBRARY_<Lang>_FLAGS whether it is modified or not
20365 and honor the POSITION_INDEPENDENT_CODE target property.
20366 This policy was introduced in CMake version 2.8.9. CMake ver‐
20369 sion 2.8.12.2 warns when the policy is not set and uses OLD
20370 behavior. Use the cmake_policy command to set it to OLD or NEW
20371 explicitly.
20372 CMP0019
20375 Do not re-expand variables in include and link information.
20376 CMake 2.8.10 and lower re-evaluated values given to the
20378 include_directories, link_directories, and link_libraries com‐
20379 mands to expand any leftover variable references at the end of
20380 the configuration step. This was for strict compatibility with
20381 VERY early CMake versions because all variable references are
20382 now normally evaluated during CMake language processing. CMake
20383 2.8.11 and higher prefer to skip the extra evaluation.
20384 The OLD behavior for this policy is to re-evaluate the values
20387 for strict compatibility. The NEW behavior for this policy is
20388 to leave the values untouched.
20389 This policy was introduced in CMake version 2.8.11. CMake ver‐
20392 sion 2.8.12.2 warns when the policy is not set and uses OLD
20393 behavior. Use the cmake_policy command to set it to OLD or NEW
20394 explicitly.
20395 CMP0020
20398 Automatically link Qt executables to qtmain target on Windows.
20399 CMake 2.8.10 and lower required users of Qt to always specify a
20401 link dependency to the qtmain.lib static library manually on
20402 Windows. CMake 2.8.11 gained the ability to evaluate generator
20403 expressions while determining the link dependencies from
20404 IMPORTED targets. This allows CMake itself to automatically
20405 link executables which link to Qt to the qtmain.lib library when
20406 using IMPORTED Qt targets. For applications already linking to
20407 qtmain.lib, this should have little impact. For applications
20408 which supply their own alternative WinMain implementation and
20409 for applications which use the QAxServer library, this automatic
20410 linking will need to be disabled as per the documentation.
20411 The OLD behavior for this policy is not to link executables to
20414 qtmain.lib automatically when they link to the QtCore IMPORTED‐
20415 target. The NEW behavior for this policy is to link executables
20416 to qtmain.lib automatically when they link to QtCore IMPORTED
20417 target.
20418 This policy was introduced in CMake version 2.8.11. CMake ver‐
20421 sion 2.8.12.2 warns when the policy is not set and uses OLD
20422 behavior. Use the cmake_policy command to set it to OLD or NEW
20423 explicitly.
20424 CMP0021
20427 Fatal error on relative paths in INCLUDE_DIRECTORIES target
20428 property.
20429 CMake 2.8.10.2 and lower allowed the INCLUDE_DIRECTORIES target
20431 property to contain relative paths. The base path for such rel‐
20432 ative entries is not well defined. CMake 2.8.12 issues a
20433 FATAL_ERROR if the INCLUDE_DIRECTORIES property contains a rela‐
20434 tive path.
20435 The OLD behavior for this policy is not to warn about relative
20438 paths in the INCLUDE_DIRECTORIES target property. The NEW
20439 behavior for this policy is to issue a FATAL_ERROR if
20440 INCLUDE_DIRECTORIES contains a relative path.
20441 This policy was introduced in CMake version 2.8.12. CMake ver‐
20444 sion 2.8.12.2 warns when the policy is not set and uses OLD
20445 behavior. Use the cmake_policy command to set it to OLD or NEW
20446 explicitly.
20447 CMP0022
20450 INTERFACE_LINK_LIBRARIES defines the link interface.
20451 CMake 2.8.11 constructed the 'link interface' of a target from
20453 properties matching (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CON‐
20454 FIG>)?. The modern way to specify config-sensitive content is
20455 to use generator expressions and the IMPORTED_ prefix makes uni‐
20456 form processing of the link interface with generator expressions
20457 impossible. The INTERFACE_LINK_LIBRARIES target property was
20458 introduced as a replacement in CMake 2.8.12. This new property
20459 is named consistently with the INTERFACE_COMPILE_DEFINITIONS,
20460 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_OPTIONS
20461 properties. For in-build targets, CMake will use the INTER‐
20462 FACE_LINK_LIBRARIES property as the source of the link interface
20463 only if policy CMP0022 is NEW. When exporting a target which
20464 has this policy set to NEW, only the INTERFACE_LINK_LIBRARIES
20465 property will be processed and generated for the IMPORTED target
20466 by default. A new option to the install(EXPORT) and export com‐
20467 mands allows export of the old-style properties for compatibil‐
20468 ity with downstream users of CMake versions older than 2.8.12.
20469 The target_link_libraries command will no longer populate the
20470 properties matching LINK_INTERFACE_LIBRARIES(_<CONFIG>)? if this
20471 policy is NEW.
20472 The OLD behavior for this policy is to ignore the INTER‐
20475 FACE_LINK_LIBRARIES property for in-build targets. The NEW
20476 behavior for this policy is to use the INTERFACE_LINK_LIBRARIES
20477 property for in-build targets, and ignore the old properties
20478 matching (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?.
20479 This policy was introduced in CMake version 2.8.12. CMake ver‐
20482 sion 2.8.12.2 warns when the policy is not set and uses OLD
20483 behavior. Use the cmake_policy command to set it to OLD or NEW
20484 explicitly.
20485 CMP0023
20488 Plain and keyword target_link_libraries signatures cannot be
20489 mixed.
20490 CMake 2.8.12 introduced the target_link_libraries signature
20492 using the PUBLIC, PRIVATE, and INTERFACE keywords to generalize
20493 the LINK_PUBLIC and LINK_PRIVATE keywords introduced in CMake
20494 2.8.7. Use of signatures with any of these keywords sets the
20495 link interface of a target explicitly, even if empty. This pro‐
20496 duces confusing behavior when used in combination with the his‐
20497 torical behavior of the plain target_link_libraries signature.
20498 For example, consider the code:
20499 target_link_libraries(mylib A)
20502 target_link_libraries(mylib PRIVATE B)
20503 After the first line the link interface has not been set explic‐
20505 itly so CMake would use the link implementation, A, as the link
20506 interface. However, the second line sets the link interface to
20507 empty. In order to avoid this subtle behavior CMake now prefers
20508 to disallow mixing the plain and keyword signatures of tar‐
20509 get_link_libraries for a single target.
20510 The OLD behavior for this policy is to allow keyword and plain
20513 target_link_libraries signatures to be mixed. The NEW behavior
20514 for this policy is to not to allow mixing of the keyword and
20515 plain signatures.
20516 This policy was introduced in CMake version 2.8.12. CMake ver‐
20519 sion 2.8.12.2 warns when the policy is not set and uses OLD
20520 behavior. Use the cmake_policy command to set it to OLD or NEW
20521 explicitly.
20522
20526 BUILD_SHARED_LIBS
20527 Global flag to cause add_library to create shared libraries if
20528 on.
20529 If present and true, this will cause all libraries to be built
20531 shared unless the library was explicitly added as a static
20532 library. This variable is often added to projects as an OPTION
20533 so that each user of a project can decide if they want to build
20534 the project using shared or static libraries.
20535 CMAKE_ABSOLUTE_DESTINATION_FILES
20538 List of files which have been installed using an ABSOLUTE DES‐
20539 TINATION path.
20540 This variable is defined by CMake-generated cmake_install.cmake
20542 scripts. It can be used (read-only) by programs or scripts that
20543 source those install scripts. This is used by some CPack genera‐
20544 tors (e.g. RPM).
20545 CMAKE_AUTOMOC_RELAXED_MODE
20548 Switch between strict and relaxed automoc mode.
20549 By default, automoc behaves exactly as described in the documen‐
20551 tation of the AUTOMOC target property. When set to TRUE, it
20552 accepts more input and tries to find the correct input file for
20553 moc even if it differs from the documented behaviour. In this
20554 mode it e.g. also checks whether a header file is intended to be
20555 processed by moc when a "foo.moc" file has been included.
20556 Relaxed mode has to be enabled for KDE4 compatibility.
20559 CMAKE_BACKWARDS_COMPATIBILITY
20562 Version of cmake required to build project
20563 From the point of view of backwards compatibility, this speci‐
20565 fies what version of CMake should be supported. By default this
20566 value is the version number of CMake that you are running. You
20567 can set this to an older version of CMake to support deprecated
20568 commands of CMake in projects that were written to use older
20569 versions of CMake. This can be set by the user or set at the
20570 beginning of a CMakeLists file.
20571 CMAKE_BUILD_TYPE
20574 Specifies the build type on single-configuration generators.
20575 This statically specifies what build type (configuration) will
20577 be built in this build tree. Possible values are empty, Debug,
20578 Release, RelWithDebInfo and MinSizeRel. This variable is only
20579 meaningful to single-configuration generators (such as make and
20580 Ninja) i.e. those which choose a single configuration when CMake
20581 runs to generate a build tree as opposed to multi-configuration
20582 generators which offer selection of the build configuration
20583 within the generated build environment. There are many per-con‐
20584 fig properties and variables (usually following clean
20585 SOME_VAR_<CONFIG> order conventions), such as
20586 CMAKE_C_FLAGS_<CONFIG>, specified as uppercase:
20587 CMAKE_C_FLAGS_[DEBUG|RELEASE|RELWITHDEBINFO|MINSIZEREL]. For
20588 example, in a build tree configured to build type Debug, CMake
20589 will see to having CMAKE_C_FLAGS_DEBUG settings get added to the
20590 CMAKE_C_FLAGS settings. See also CMAKE_CONFIGURATION_TYPES.
20591 CMAKE_COLOR_MAKEFILE
20594 Enables color output when using the Makefile generator.
20595 When enabled, the generated Makefiles will produce colored out‐
20597 put. Default is ON.
20598 CMAKE_CONFIGURATION_TYPES
20601 Specifies the available build types on multi-config generators.
20602 This specifies what build types (configurations) will be avail‐
20604 able such as Debug, Release, RelWithDebInfo etc. This has rea‐
20605 sonable defaults on most platforms, but can be extended to pro‐
20606 vide other build types. See also CMAKE_BUILD_TYPE for details
20607 of managing configuration data, and CMAKE_CFG_INTDIR.
20608 CMAKE_DEBUG_TARGET_PROPERTIES
20611 Enables tracing output for target properties.
20612 This variable can be populated with a list of properties to gen‐
20614 erate debug output for when evaluating target properties. Cur‐
20615 rently it can only be used when evaluating the INCLUDE_DIRECTO‐
20616 RIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS target properties.
20617 In that case, it outputs a backtrace for each entry in the tar‐
20618 get property. Default is unset.
20619 CMAKE_DISABLE_FIND_PACKAGE_<PackageName>
20622 Variable for disabling find_package() calls.
20623 Every non-REQUIRED find_package() call in a project can be dis‐
20625 abled by setting the variable CMAKE_DISABLE_FIND_PACKAGE_<Packa‐
20626 geName> to TRUE. This can be used to build a project without an
20627 optional package, although that package is installed.
20628 This switch should be used during the initial CMake run. Other‐
20631 wise if the package has already been found in a previous CMake
20632 run, the variables which have been stored in the cache will
20633 still be there. In that case it is recommended to remove the
20634 cache variables for this package from the cache using the cache
20635 editor or cmake -U
20636 CMAKE_ERROR_DEPRECATED
20639 Whether to issue deprecation errors for macros and functions.
20640 If TRUE, this can be used by macros and functions to issue fatal
20642 errors when deprecated macros or functions are used. This vari‐
20643 able is FALSE by default.
20644 CMAKE_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION
20647 Ask cmake_install.cmake script to error out as soon as a file
20648 with absolute INSTALL DESTINATION is encountered.
20649 The fatal error is emitted before the installation of the
20651 offending file takes place. This variable is used by CMake-gen‐
20652 erated cmake_install.cmake scripts. If one sets this variable to
20653 ON while running the script, it may get fatal error messages
20654 from the script.
20655 CMAKE_FIND_LIBRARY_PREFIXES
20658 Prefixes to prepend when looking for libraries.
20659 This specifies what prefixes to add to library names when the
20661 find_library command looks for libraries. On UNIX systems this
20662 is typically lib, meaning that when trying to find the foo
20663 library it will look for libfoo.
20664 CMAKE_FIND_LIBRARY_SUFFIXES
20667 Suffixes to append when looking for libraries.
20668 This specifies what suffixes to add to library names when the
20670 find_library command looks for libraries. On Windows systems
20671 this is typically .lib and .dll, meaning that when trying to
20672 find the foo library it will look for foo.dll etc.
20673 CMAKE_FIND_PACKAGE_WARN_NO_MODULE
20676 Tell find_package to warn if called without an explicit mode.
20677 If find_package is called without an explicit mode option (MOD‐
20679 ULE, CONFIG or NO_MODULE) and no Find<pkg>.cmake module is in
20680 CMAKE_MODULE_PATH then CMake implicitly assumes that the caller
20681 intends to search for a package configuration file. If no pack‐
20682 age configuration file is found then the wording of the failure
20683 message must account for both the case that the package is
20684 really missing and the case that the project has a bug and
20685 failed to provide the intended Find module. If instead the
20686 caller specifies an explicit mode option then the failure mes‐
20687 sage can be more specific.
20688 Set CMAKE_FIND_PACKAGE_WARN_NO_MODULE to TRUE to tell find_pack‐
20691 age to warn when it implicitly assumes Config mode. This helps
20692 developers enforce use of an explicit mode in all calls to
20693 find_package within a project.
20694 CMAKE_IGNORE_PATH
20697 Path to be ignored by FIND_XXX() commands.
20698 Specifies directories to be ignored by searches in FIND_XXX()
20700 commands. This is useful in cross-compiled environments where
20701 some system directories contain incompatible but possibly link‐
20702 able libraries. For example, on cross-compiled cluster environ‐
20703 ments, this allows a user to ignore directories containing
20704 libraries meant for the front-end machine that modules like
20705 FindX11 (and others) would normally search. By default this is
20706 empty; it is intended to be set by the project. Note that
20707 CMAKE_IGNORE_PATH takes a list of directory names, NOT a list of
20708 prefixes. If you want to ignore paths under prefixes (bin,
20709 include, lib, etc.), you'll need to specify them explicitly.
20710 See also CMAKE_PREFIX_PATH, CMAKE_LIBRARY_PATH,
20711 CMAKE_INCLUDE_PATH, CMAKE_PROGRAM_PATH.
20712 CMAKE_INCLUDE_PATH
20715 Path used for searching by FIND_FILE() and FIND_PATH().
20716 Specifies a path which will be used both by FIND_FILE() and
20718 FIND_PATH(). Both commands will check each of the contained
20719 directories for the existence of the file which is currently
20720 searched. By default it is empty, it is intended to be set by
20721 the project. See also CMAKE_SYSTEM_INCLUDE_PATH, CMAKE_PRE‐
20722 FIX_PATH.
20723 CMAKE_INSTALL_DEFAULT_COMPONENT_NAME
20726 Default component used in install() commands.
20727 If an install() command is used without the COMPONENT argument,
20729 these files will be grouped into a default component. The name
20730 of this default install component will be taken from this vari‐
20731 able. It defaults to "Unspecified".
20732 CMAKE_INSTALL_PREFIX
20735 Install directory used by install.
20736 If "make install" is invoked or INSTALL is built, this directory
20738 is prepended onto all install directories. This variable
20739 defaults to /usr/local on UNIX and c:/Program Files on Windows.
20740 On UNIX one can use the DESTDIR mechanism in order to relocate
20743 the whole installation. DESTDIR means DESTination DIRectory. It
20744 is commonly used by makefile users in order to install software
20745 at non-default location. It is usually invoked like this:
20746 make DESTDIR=/home/john install
20749 which will install the concerned software using the installation
20751 prefix, e.g. "/usr/local" prepended with the DESTDIR value which
20752 finally gives "/home/john/usr/local".
20753 WARNING: DESTDIR may not be used on Windows because installation
20756 prefix usually contains a drive letter like in "C:/Program
20757 Files" which cannot be prepended with some other prefix.
20758 The installation prefix is also added to CMAKE_SYSTEM_PRE‐
20761 FIX_PATH so that find_package, find_program, find_library,
20762 find_path, and find_file will search the prefix for other soft‐
20763 ware.
20764 CMAKE_LIBRARY_PATH
20767 Path used for searching by FIND_LIBRARY().
20768 Specifies a path which will be used by FIND_LIBRARY().
20770 FIND_LIBRARY() will check each of the contained directories for
20771 the existence of the library which is currently searched. By
20772 default it is empty, it is intended to be set by the project.
20773 See also CMAKE_SYSTEM_LIBRARY_PATH, CMAKE_PREFIX_PATH.
20774 CMAKE_MFC_FLAG
20777 Tell cmake to use MFC for an executable or dll.
20778 This can be set in a CMakeLists.txt file and will enable MFC in
20780 the application. It should be set to 1 for the static MFC
20781 library, and 2 for the shared MFC library. This is used in Vis‐
20782 ual Studio 6 and 7 project files. The CMakeSetup dialog used
20783 MFC and the CMakeLists.txt looks like this:
20784 add_definitions(-D_AFXDLL)
20787 set(CMAKE_MFC_FLAG 2)
20788 add_executable(CMakeSetup WIN32 ${SRCS})
20789 CMAKE_MODULE_PATH
20792 List of directories to search for CMake modules.
20793 Commands like include() and find_package() search for files in
20795 directories listed by this variable before checking the default
20796 modules that come with CMake.
20797 CMAKE_NOT_USING_CONFIG_FLAGS
20800 Skip _BUILD_TYPE flags if true.
20801 This is an internal flag used by the generators in CMake to tell
20803 CMake to skip the _BUILD_TYPE flags.
20804 CMAKE_POLICY_DEFAULT_CMP<NNNN>
20807 Default for CMake Policy CMP<NNNN> when it is otherwise left
20808 unset.
20809 Commands cmake_minimum_required(VERSION) and cmake_policy(VER‐
20811 SION) by default leave policies introduced after the given ver‐
20812 sion unset. Set CMAKE_POLICY_DEFAULT_CMP<NNNN> to OLD or NEW to
20813 specify the default for policy CMP<NNNN>, where <NNNN> is the
20814 policy number.
20815 This variable should not be set by a project in CMake code; use
20818 cmake_policy(SET) instead. Users running CMake may set this
20819 variable in the cache (e.g. -DCMAKE_POL‐
20820 ICY_DEFAULT_CMP<NNNN>=<OLD|NEW>) to set a policy not otherwise
20821 set by the project. Set to OLD to quiet a policy warning while
20822 using old behavior or to NEW to try building the project with
20823 new behavior.
20824 CMAKE_PREFIX_PATH
20827 Path used for searching by FIND_XXX(), with appropriate suffixes
20828 added.
20829 Specifies a path which will be used by the FIND_XXX() commands.
20831 It contains the "base" directories, the FIND_XXX() commands
20832 append appropriate subdirectories to the base directories. So
20833 FIND_PROGRAM() adds /bin to each of the directories in the path,
20834 FIND_LIBRARY() appends /lib to each of the directories, and
20835 FIND_PATH() and FIND_FILE() append /include . By default it is
20836 empty, it is intended to be set by the project. See also
20837 CMAKE_SYSTEM_PREFIX_PATH, CMAKE_INCLUDE_PATH,
20838 CMAKE_LIBRARY_PATH, CMAKE_PROGRAM_PATH.
20839 CMAKE_PROGRAM_PATH
20842 Path used for searching by FIND_PROGRAM().
20843 Specifies a path which will be used by FIND_PROGRAM(). FIND_PRO‐
20845 GRAM() will check each of the contained directories for the
20846 existence of the program which is currently searched. By default
20847 it is empty, it is intended to be set by the project. See also
20848 CMAKE_SYSTEM_PROGRAM_PATH, CMAKE_PREFIX_PATH.
20849 CMAKE_SKIP_INSTALL_ALL_DEPENDENCY
20852 Don't make the install target depend on the all target.
20853 By default, the "install" target depends on the "all" target.
20855 This has the effect, that when "make install" is invoked or
20856 INSTALL is built, first the "all" target is built, then the
20857 installation starts. If CMAKE_SKIP_INSTALL_ALL_DEPENDENCY is
20858 set to TRUE, this dependency is not created, so the installation
20859 process will start immediately, independent from whether the
20860 project has been completely built or not.
20861 CMAKE_SYSTEM_IGNORE_PATH
20864 Path to be ignored by FIND_XXX() commands.
20865 Specifies directories to be ignored by searches in FIND_XXX()
20867 commands. This is useful in cross-compiled environments where
20868 some system directories contain incompatible but possibly link‐
20869 able libraries. For example, on cross-compiled cluster environ‐
20870 ments, this allows a user to ignore directories containing
20871 libraries meant for the front-end machine that modules like
20872 FindX11 (and others) would normally search. By default this
20873 contains a list of directories containing incompatible binaries
20874 for the host system. See also CMAKE_SYSTEM_PREFIX_PATH,
20875 CMAKE_SYSTEM_LIBRARY_PATH, CMAKE_SYSTEM_INCLUDE_PATH, and
20876 CMAKE_SYSTEM_PROGRAM_PATH.
20877 CMAKE_SYSTEM_INCLUDE_PATH
20880 Path used for searching by FIND_FILE() and FIND_PATH().
20881 Specifies a path which will be used both by FIND_FILE() and
20883 FIND_PATH(). Both commands will check each of the contained
20884 directories for the existence of the file which is currently
20885 searched. By default it contains the standard directories for
20886 the current system. It is NOT intended to be modified by the
20887 project, use CMAKE_INCLUDE_PATH for this. See also CMAKE_SYS‐
20888 TEM_PREFIX_PATH.
20889 CMAKE_SYSTEM_LIBRARY_PATH
20892 Path used for searching by FIND_LIBRARY().
20893 Specifies a path which will be used by FIND_LIBRARY().
20895 FIND_LIBRARY() will check each of the contained directories for
20896 the existence of the library which is currently searched. By
20897 default it contains the standard directories for the current
20898 system. It is NOT intended to be modified by the project, use
20899 CMAKE_LIBRARY_PATH for this. See also CMAKE_SYSTEM_PREFIX_PATH.
20900 CMAKE_SYSTEM_PREFIX_PATH
20903 Path used for searching by FIND_XXX(), with appropriate suffixes
20904 added.
20905 Specifies a path which will be used by the FIND_XXX() commands.
20907 It contains the "base" directories, the FIND_XXX() commands
20908 append appropriate subdirectories to the base directories. So
20909 FIND_PROGRAM() adds /bin to each of the directories in the path,
20910 FIND_LIBRARY() appends /lib to each of the directories, and
20911 FIND_PATH() and FIND_FILE() append /include . By default this
20912 contains the standard directories for the current system and the
20913 CMAKE_INSTALL_PREFIX. It is NOT intended to be modified by the
20914 project, use CMAKE_PREFIX_PATH for this. See also CMAKE_SYS‐
20915 TEM_INCLUDE_PATH, CMAKE_SYSTEM_LIBRARY_PATH, CMAKE_SYSTEM_PRO‐
20916 GRAM_PATH, and CMAKE_SYSTEM_IGNORE_PATH.
20917 CMAKE_SYSTEM_PROGRAM_PATH
20920 Path used for searching by FIND_PROGRAM().
20921 Specifies a path which will be used by FIND_PROGRAM(). FIND_PRO‐
20923 GRAM() will check each of the contained directories for the
20924 existence of the program which is currently searched. By default
20925 it contains the standard directories for the current system. It
20926 is NOT intended to be modified by the project, use CMAKE_PRO‐
20927 GRAM_PATH for this. See also CMAKE_SYSTEM_PREFIX_PATH.
20928 CMAKE_USER_MAKE_RULES_OVERRIDE
20931 Specify a CMake file that overrides platform information.
20932 CMake loads the specified file while enabling support for each
20934 language from either the project() or enable_language() com‐
20935 mands. It is loaded after CMake's builtin compiler and platform
20936 information modules have been loaded but before the information
20937 is used. The file may set platform information variables to
20938 override CMake's defaults.
20939 This feature is intended for use only in overriding information
20942 variables that must be set before CMake builds its first test
20943 project to check that the compiler for a language works. It
20944 should not be used to load a file in cases that a normal
20945 include() will work. Use it only as a last resort for behavior
20946 that cannot be achieved any other way. For example, one may set
20947 CMAKE_C_FLAGS_INIT to change the default value used to initial‐
20948 ize CMAKE_C_FLAGS before it is cached. The override file should
20949 NOT be used to set anything that could be set after languages
20950 are enabled, such as variables like CMAKE_RUNTIME_OUTPUT_DIREC‐
20951 TORY that affect the placement of binaries. Information set in
20952 the file will be used for try_compile and try_run builds too.
20953 CMAKE_WARN_DEPRECATED
20956 Whether to issue deprecation warnings for macros and functions.
20957 If TRUE, this can be used by macros and functions to issue dep‐
20959 recation warnings. This variable is FALSE by default.
20960 CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
20963 Ask cmake_install.cmake script to warn each time a file with
20964 absolute INSTALL DESTINATION is encountered.
20965 This variable is used by CMake-generated cmake_install.cmake
20967 scripts. If one sets this variable to ON while running the
20968 script, it may get warning messages from the script.
20969
20972 APPLE True if running on Mac OS X.
20973 Set to true on Mac OS X.
20975 BORLAND
20978 True if the Borland compiler is being used.
20979 This is set to true if the Borland compiler is being used.
20981 CMAKE_CL_64
20984 Using the 64 bit compiler from Microsoft
20985 Set to true when using the 64 bit cl compiler from Microsoft.
20987 CMAKE_COMPILER_2005
20990 Using the Visual Studio 2005 compiler from Microsoft
20991 Set to true when using the Visual Studio 2005 compiler from Mi‐
20993 crosoft.
20994 CMAKE_HOST_APPLE
20997 True for Apple OS X operating systems.
20998 Set to true when the host system is Apple OS X.
21000 CMAKE_HOST_SYSTEM
21003 Name of system cmake is being run on.
21004 The same as CMAKE_SYSTEM but for the host system instead of the
21006 target system when cross compiling.
21007 CMAKE_HOST_SYSTEM_NAME
21010 Name of the OS CMake is running on.
21011 The same as CMAKE_SYSTEM_NAME but for the host system instead of
21013 the target system when cross compiling.
21014 CMAKE_HOST_SYSTEM_PROCESSOR
21017 The name of the CPU CMake is running on.
21018 The same as CMAKE_SYSTEM_PROCESSOR but for the host system
21020 instead of the target system when cross compiling.
21021 CMAKE_HOST_SYSTEM_VERSION
21024 OS version CMake is running on.
21025 The same as CMAKE_SYSTEM_VERSION but for the host system instead
21027 of the target system when cross compiling.
21028 CMAKE_HOST_UNIX
21031 True for UNIX and UNIX like operating systems.
21032 Set to true when the host system is UNIX or UNIX like (i.e.
21034 APPLE and CYGWIN).
21035 CMAKE_HOST_WIN32
21038 True on windows systems, including win64.
21039 Set to true when the host system is Windows and on Cygwin.
21041 CMAKE_LIBRARY_ARCHITECTURE
21044 Target architecture library directory name, if detected.
21045 This is the value of CMAKE_<lang>_LIBRARY_ARCHITECTURE as
21047 detected for one of the enabled languages.
21048 CMAKE_LIBRARY_ARCHITECTURE_REGEX
21051 Regex matching possible target architecture library directory
21052 names.
21053 This is used to detect CMAKE_<lang>_LIBRARY_ARCHITECTURE from
21055 the implicit linker search path by matching the <arch> name.
21056 CMAKE_OBJECT_PATH_MAX
21059 Maximum object file full-path length allowed by native build
21060 tools.
21061 CMake computes for every source file an object file name that is
21063 unique to the source file and deterministic with respect to the
21064 full path to the source file. This allows multiple source files
21065 in a target to share the same name if they lie in different
21066 directories without rebuilding when one is added or removed.
21067 However, it can produce long full paths in a few cases, so CMake
21068 shortens the path using a hashing scheme when the full path to
21069 an object file exceeds a limit. CMake has a built-in limit for
21070 each platform that is sufficient for common tools, but some
21071 native tools may have a lower limit. This variable may be set
21072 to specify the limit explicitly. The value must be an integer
21073 no less than 128.
21074 CMAKE_SYSTEM
21077 Name of system cmake is compiling for.
21078 This variable is the composite of CMAKE_SYSTEM_NAME and
21080 CMAKE_SYSTEM_VERSION, like this ${CMAKE_SYS‐
21081 TEM_NAME}-${CMAKE_SYSTEM_VERSION}. If CMAKE_SYSTEM_VERSION is
21082 not set, then CMAKE_SYSTEM is the same as CMAKE_SYSTEM_NAME.
21083 CMAKE_SYSTEM_NAME
21086 Name of the OS CMake is building for.
21087 This is the name of the operating system on which CMake is tar‐
21089 geting. On systems that have the uname command, this variable
21090 is set to the output of uname -s. Linux, Windows, and Darwin
21091 for Mac OS X are the values found on the big three operating
21092 systems.
21093 CMAKE_SYSTEM_PROCESSOR
21096 The name of the CPU CMake is building for.
21097 On systems that support uname, this variable is set to the out‐
21099 put of uname -p, on windows it is set to the value of the envi‐
21100 ronment variable PROCESSOR_ARCHITECTURE
21101 CMAKE_SYSTEM_VERSION
21104 OS version CMake is building for.
21105 A numeric version string for the system, on systems that support
21107 uname, this variable is set to the output of uname -r. On other
21108 systems this is set to major-minor version numbers.
21109 CYGWIN True for Cygwin.
21112 Set to true when using Cygwin.
21114 ENV Access environment variables.
21117 Use the syntax $ENV{VAR} to read environment variable VAR. See
21119 also the set() command to set ENV{VAR}.
21120 MSVC True when using Microsoft Visual C
21123 Set to true when the compiler is some version of Microsoft Vis‐
21125 ual C.
21126 MSVC10 True when using Microsoft Visual C 10.0
21129 Set to true when the compiler is version 10.0 of Microsoft Vis‐
21131 ual C.
21132 MSVC11 True when using Microsoft Visual C 11.0
21135 Set to true when the compiler is version 11.0 of Microsoft Vis‐
21137 ual C.
21138 MSVC12 True when using Microsoft Visual C 12.0
21141 Set to true when the compiler is version 12.0 of Microsoft Vis‐
21143 ual C.
21144 MSVC60 True when using Microsoft Visual C 6.0
21147 Set to true when the compiler is version 6.0 of Microsoft Visual
21149 C.
21150 MSVC70 True when using Microsoft Visual C 7.0
21153 Set to true when the compiler is version 7.0 of Microsoft Visual
21155 C.
21156 MSVC71 True when using Microsoft Visual C 7.1
21159 Set to true when the compiler is version 7.1 of Microsoft Visual
21161 C.
21162 MSVC80 True when using Microsoft Visual C 8.0
21165 Set to true when the compiler is version 8.0 of Microsoft Visual
21167 C.
21168 MSVC90 True when using Microsoft Visual C 9.0
21171 Set to true when the compiler is version 9.0 of Microsoft Visual
21173 C.
21174 MSVC_IDE
21177 True when using the Microsoft Visual C IDE
21178 Set to true when the target platform is the Microsoft Visual C
21180 IDE, as opposed to the command line compiler.
21181 MSVC_VERSION
21184 The version of Microsoft Visual C/C++ being used if any.
21185 Known version numbers are:
21187 1200 = VS 6.0
21190 1300 = VS 7.0
21191 1310 = VS 7.1
21192 1400 = VS 8.0
21193 1500 = VS 9.0
21194 1600 = VS 10.0
21195 1700 = VS 11.0
21196 1800 = VS 12.0
21197 UNIX True for UNIX and UNIX like operating systems.
21200 Set to true when the target system is UNIX or UNIX like (i.e.
21202 APPLE and CYGWIN).
21203 WIN32 True on windows systems, including win64.
21206 Set to true when the target system is Windows.
21208 XCODE_VERSION
21211 Version of Xcode (Xcode generator only).
21212 Under the Xcode generator, this is the version of Xcode as spec‐
21214 ified in "Xcode.app/Contents/version.plist" (such as "3.1.2").
21215
21218 CMAKE_<LANG>_ARCHIVE_APPEND
21219 Rule variable to append to a static archive.
21220 This is a rule variable that tells CMake how to append to a
21222 static archive. It is used in place of CMAKE_<LANG>_CRE‐
21223 ATE_STATIC_LIBRARY on some platforms in order to support large
21224 object counts. See also CMAKE_<LANG>_ARCHIVE_CREATE and
21225 CMAKE_<LANG>_ARCHIVE_FINISH.
21226 CMAKE_<LANG>_ARCHIVE_CREATE
21229 Rule variable to create a new static archive.
21230 This is a rule variable that tells CMake how to create a static
21232 archive. It is used in place of CMAKE_<LANG>_CRE‐
21233 ATE_STATIC_LIBRARY on some platforms in order to support large
21234 object counts. See also CMAKE_<LANG>_ARCHIVE_APPEND and
21235 CMAKE_<LANG>_ARCHIVE_FINISH.
21236 CMAKE_<LANG>_ARCHIVE_FINISH
21239 Rule variable to finish an existing static archive.
21240 This is a rule variable that tells CMake how to finish a static
21242 archive. It is used in place of CMAKE_<LANG>_CRE‐
21243 ATE_STATIC_LIBRARY on some platforms in order to support large
21244 object counts. See also CMAKE_<LANG>_ARCHIVE_CREATE and
21245 CMAKE_<LANG>_ARCHIVE_APPEND.
21246 CMAKE_<LANG>_COMPILER
21249 The full path to the compiler for LANG.
21250 This is the command that will be used as the <LANG> compiler.
21252 Once set, you can not change this variable.
21253 CMAKE_<LANG>_COMPILER_ABI
21256 An internal variable subject to change.
21257 This is used in determining the compiler ABI and is subject to
21259 change.
21260 CMAKE_<LANG>_COMPILER_ID
21263 Compiler identification string.
21264 A short string unique to the compiler vendor. Possible values
21266 include:
21267 Absoft = Absoft Fortran (absoft.com)
21270 ADSP = Analog VisualDSP++ (analog.com)
21271 Clang = LLVM Clang (clang.llvm.org)
21272 Cray = Cray Compiler (cray.com)
21273 Embarcadero, Borland = Embarcadero (embarcadero.com)
21274 G95 = G95 Fortran (g95.org)
21275 GNU = GNU Compiler Collection (gcc.gnu.org)
21276 HP = Hewlett-Packard Compiler (hp.com)
21277 Intel = Intel Compiler (intel.com)
21278 MIPSpro = SGI MIPSpro (sgi.com)
21279 MSVC = Microsoft Visual Studio (microsoft.com)
21280 PGI = The Portland Group (pgroup.com)
21281 PathScale = PathScale (pathscale.com)
21282 SDCC = Small Device C Compiler (sdcc.sourceforge.net)
21283 SunPro = Oracle Solaris Studio (oracle.com)
21284 TI = Texas Instruments (ti.com)
21285 TinyCC = Tiny C Compiler (tinycc.org)
21286 Watcom = Open Watcom (openwatcom.org)
21287 XL, VisualAge, zOS = IBM XL (ibm.com)
21288 This variable is not guaranteed to be defined for all compilers
21290 or languages.
21291 CMAKE_<LANG>_COMPILER_LOADED
21294 Defined to true if the language is enabled.
21295 When language <LANG> is enabled by project() or enable_lan‐
21297 guage() this variable is defined to 1.
21298 CMAKE_<LANG>_COMPILER_VERSION
21301 Compiler version string.
21302 Compiler version in major[.minor[.patch[.tweak]]] format. This
21304 variable is not guaranteed to be defined for all compilers or
21305 languages.
21306 CMAKE_<LANG>_COMPILE_OBJECT
21309 Rule variable to compile a single object file.
21310 This is a rule variable that tells CMake how to compile a single
21312 object file for the language <LANG>.
21313 CMAKE_<LANG>_CREATE_SHARED_LIBRARY
21316 Rule variable to create a shared library.
21317 This is a rule variable that tells CMake how to create a shared
21319 library for the language <LANG>.
21320 CMAKE_<LANG>_CREATE_SHARED_MODULE
21323 Rule variable to create a shared module.
21324 This is a rule variable that tells CMake how to create a shared
21326 library for the language <LANG>.
21327 CMAKE_<LANG>_CREATE_STATIC_LIBRARY
21330 Rule variable to create a static library.
21331 This is a rule variable that tells CMake how to create a static
21333 library for the language <LANG>.
21334 CMAKE_<LANG>_FLAGS
21337 Flags for all build types.
21338 <LANG> flags used regardless of the value of CMAKE_BUILD_TYPE.
21340 CMAKE_<LANG>_FLAGS_DEBUG
21343 Flags for Debug build type or configuration.
21344 <LANG> flags used when CMAKE_BUILD_TYPE is Debug.
21346 CMAKE_<LANG>_FLAGS_MINSIZEREL
21349 Flags for MinSizeRel build type or configuration.
21350 <LANG> flags used when CMAKE_BUILD_TYPE is MinSizeRel.Short for
21352 minimum size release.
21353 CMAKE_<LANG>_FLAGS_RELEASE
21356 Flags for Release build type or configuration.
21357 <LANG> flags used when CMAKE_BUILD_TYPE is Release
21359 CMAKE_<LANG>_FLAGS_RELWITHDEBINFO
21362 Flags for RelWithDebInfo type or configuration.
21363 <LANG> flags used when CMAKE_BUILD_TYPE is RelWithDebInfo.
21365 Short for Release With Debug Information.
21366 CMAKE_<LANG>_IGNORE_EXTENSIONS
21369 File extensions that should be ignored by the build.
21370 This is a list of file extensions that may be part of a project
21372 for a given language but are not compiled.
21373 CMAKE_<LANG>_IMPLICIT_INCLUDE_DIRECTORIES
21376 Directories implicitly searched by the compiler for header
21377 files.
21378 CMake does not explicitly specify these directories on compiler
21380 command lines for language <LANG>. This prevents system include
21381 directories from being treated as user include directories on
21382 some compilers.
21383 CMAKE_<LANG>_IMPLICIT_LINK_DIRECTORIES
21386 Implicit linker search path detected for language <LANG>.
21387 Compilers typically pass directories containing language runtime
21389 libraries and default library search paths when they invoke a
21390 linker. These paths are implicit linker search directories for
21391 the compiler's language. CMake automatically detects these
21392 directories for each language and reports the results in this
21393 variable.
21394 When a library in one of these directories is given by full path
21397 to target_link_libraries() CMake will generate the -l<name> form
21398 on link lines to ensure the linker searches its implicit direc‐
21399 tories for the library. Note that some toolchains read implicit
21400 directories from an environment variable such as LIBRARY_PATH so
21401 keep its value consistent when operating in a given build tree.
21402 CMAKE_<LANG>_IMPLICIT_LINK_FRAMEWORK_DIRECTORIES
21405 Implicit linker framework search path detected for language
21406 <LANG>.
21407 These paths are implicit linker framework search directories for
21409 the compiler's language. CMake automatically detects these
21410 directories for each language and reports the results in this
21411 variable.
21412 CMAKE_<LANG>_IMPLICIT_LINK_LIBRARIES
21415 Implicit link libraries and flags detected for language <LANG>.
21416 Compilers typically pass language runtime library names and
21418 other flags when they invoke a linker. These flags are implicit
21419 link options for the compiler's language. CMake automatically
21420 detects these libraries and flags for each language and reports
21421 the results in this variable.
21422 CMAKE_<LANG>_LIBRARY_ARCHITECTURE
21425 Target architecture library directory name detected for <lang>.
21426 If the <lang> compiler passes to the linker an architecture-spe‐
21428 cific system library search directory such as <pre‐
21429 fix>/lib/<arch> this variable contains the <arch> name if/as
21430 detected by CMake.
21431 CMAKE_<LANG>_LINKER_PREFERENCE
21434 Preference value for linker language selection.
21435 The "linker language" for executable, shared library, and module
21437 targets is the language whose compiler will invoke the linker.
21438 The LINKER_LANGUAGE target property sets the language explic‐
21439 itly. Otherwise, the linker language is that whose linker pref‐
21440 erence value is highest among languages compiled and linked into
21441 the target. See also the CMAKE_<LANG>_LINKER_PREFERENCE_PROPA‐
21442 GATES variable.
21443 CMAKE_<LANG>_LINKER_PREFERENCE_PROPAGATES
21446 True if CMAKE_<LANG>_LINKER_PREFERENCE propagates across tar‐
21447 gets.
21448 This is used when CMake selects a linker language for a target.
21450 Languages compiled directly into the target are always consid‐
21451 ered. A language compiled into static libraries linked by the
21452 target is considered if this variable is true.
21453 CMAKE_<LANG>_LINK_EXECUTABLE
21456 Rule variable to link an executable.
21457 Rule variable to link an executable for the given language.
21459 CMAKE_<LANG>_OUTPUT_EXTENSION
21462 Extension for the output of a compile for a single file.
21463 This is the extension for an object file for the given <LANG>.
21465 For example .obj for C on Windows.
21466 CMAKE_<LANG>_PLATFORM_ID
21469 An internal variable subject to change.
21470 This is used in determining the platform and is subject to
21472 change.
21473 CMAKE_<LANG>_SIZEOF_DATA_PTR
21476 Size of pointer-to-data types for language <LANG>.
21477 This holds the size (in bytes) of pointer-to-data types in the
21479 target platform ABI. It is defined for languages C and CXX
21480 (C++).
21481 CMAKE_<LANG>_SOURCE_FILE_EXTENSIONS
21484 Extensions of source files for the given language.
21485 This is the list of extensions for a given language's source
21487 files.
21488 CMAKE_COMPILER_IS_GNU<LANG>
21491 True if the compiler is GNU.
21492 If the selected <LANG> compiler is the GNU compiler then this is
21494 TRUE, if not it is FALSE. Unlike the other per-language vari‐
21495 ables, this uses the GNU syntax for identifying languages
21496 instead of the CMake syntax. Recognized values of the <LANG>
21497 suffix are:
21498 CC = C compiler
21501 CXX = C++ compiler
21502 G77 = Fortran compiler
21503 CMAKE_Fortran_MODDIR_DEFAULT
21506 Fortran default module output directory.
21507 Most Fortran compilers write .mod files to the current working
21509 directory. For those that do not, this is set to "." and used
21510 when the Fortran_MODULE_DIRECTORY target property is not set.
21511 CMAKE_Fortran_MODDIR_FLAG
21514 Fortran flag for module output directory.
21515 This stores the flag needed to pass the value of the For‐
21517 tran_MODULE_DIRECTORY target property to the compiler.
21518 CMAKE_Fortran_MODOUT_FLAG
21521 Fortran flag to enable module output.
21522 Most Fortran compilers write .mod files out by default. For
21524 others, this stores the flag needed to enable module output.
21525 CMAKE_INTERNAL_PLATFORM_ABI
21528 An internal variable subject to change.
21529 This is used in determining the compiler ABI and is subject to
21531 change.
21532 CMAKE_USER_MAKE_RULES_OVERRIDE_<LANG>
21535 Specify a CMake file that overrides platform information for
21536 <LANG>.
21537 This is a language-specific version of
21539 CMAKE_USER_MAKE_RULES_OVERRIDE loaded only when enabling lan‐
21540 guage <LANG>.
21541
21544 CMAKE_<CONFIG>_POSTFIX
21545 Default filename postfix for libraries under configuration <CON‐
21546 FIG>.
21547 When a non-executable target is created its <CONFIG>_POSTFIX
21549 target property is initialized with the value of this variable
21550 if it is set.
21551 CMAKE_<LANG>_VISIBILITY_PRESET
21554 Default value for <LANG>_VISIBILITY_PRESET of targets.
21555 This variable is used to initialize the <LANG>_VISIBILITY_PRESET
21557 property on all the targets. See that target property for addi‐
21558 tional information.
21559 CMAKE_ARCHIVE_OUTPUT_DIRECTORY
21562 Where to put all the ARCHIVE targets when built.
21563 This variable is used to initialize the ARCHIVE_OUTPUT_DIRECTORY
21565 property on all the targets. See that target property for addi‐
21566 tional information.
21567 CMAKE_AUTOMOC
21570 Whether to handle moc automatically for Qt targets.
21571 This variable is used to initialize the AUTOMOC property on all
21573 the targets. See that target property for additional informa‐
21574 tion.
21575 CMAKE_AUTOMOC_MOC_OPTIONS
21578 Additional options for moc when using automoc (see CMAKE_AUTO‐
21579 MOC).
21580 This variable is used to initialize the AUTOMOC_MOC_OPTIONS
21582 property on all the targets. See that target property for addi‐
21583 tional information.
21584 CMAKE_BUILD_WITH_INSTALL_RPATH
21587 Use the install path for the RPATH
21588 Normally CMake uses the build tree for the RPATH when building
21590 executables etc on systems that use RPATH. When the software is
21591 installed the executables etc are relinked by CMake to have the
21592 install RPATH. If this variable is set to true then the software
21593 is always built with the install path for the RPATH and does not
21594 need to be relinked when installed.
21595 CMAKE_DEBUG_POSTFIX
21598 See variable CMAKE_<CONFIG>_POSTFIX.
21599 This variable is a special case of the more-general CMAKE_<CON‐
21601 FIG>_POSTFIX variable for the DEBUG configuration.
21602 CMAKE_EXE_LINKER_FLAGS
21605 Linker flags to be used to create executables.
21606 These flags will be used by the linker when creating an exe‐
21608 cutable.
21609 CMAKE_EXE_LINKER_FLAGS_<CONFIG>
21612 Flags to be used when linking an executable.
21613 Same as CMAKE_C_FLAGS_* but used by the linker when creating
21615 executables.
21616 CMAKE_Fortran_FORMAT
21619 Set to FIXED or FREE to indicate the Fortran source layout.
21620 This variable is used to initialize the Fortran_FORMAT property
21622 on all the targets. See that target property for additional
21623 information.
21624 CMAKE_Fortran_MODULE_DIRECTORY
21627 Fortran module output directory.
21628 This variable is used to initialize the Fortran_MODULE_DIRECTORY
21630 property on all the targets. See that target property for addi‐
21631 tional information.
21632 CMAKE_GNUtoMS
21635 Convert GNU import libraries (.dll.a) to MS format (.lib).
21636 This variable is used to initialize the GNUtoMS property on tar‐
21638 gets when they are created. See that target property for addi‐
21639 tional information.
21640 CMAKE_INCLUDE_CURRENT_DIR
21643 Automatically add the current source- and build directories to
21644 the include path.
21645 If this variable is enabled, CMake automatically adds in each
21647 directory ${CMAKE_CURRENT_SOURCE_DIR} and ${CMAKE_CUR‐
21648 RENT_BINARY_DIR} to the include path for this directory. These
21649 additional include directories do not propagate down to subdi‐
21650 rectories. This is useful mainly for out-of-source builds, where
21651 files generated into the build tree are included by files
21652 located in the source tree.
21653 By default CMAKE_INCLUDE_CURRENT_DIR is OFF.
21656 CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE
21659 Automatically add the current source- and build directories to
21660 the INTERFACE_INCLUDE_DIRECTORIES.
21661 If this variable is enabled, CMake automatically adds for each
21663 shared library target, static library target, module target and
21664 executable target, ${CMAKE_CURRENT_SOURCE_DIR} and ${CMAKE_CUR‐
21665 RENT_BINARY_DIR} to the INTERFACE_INCLUDE_DIRECTORIES.By default
21666 CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE is OFF.
21667 CMAKE_INSTALL_NAME_DIR
21670 Mac OS X directory name for installed targets.
21671 CMAKE_INSTALL_NAME_DIR is used to initialize the
21673 INSTALL_NAME_DIR property on all targets. See that target prop‐
21674 erty for more information.
21675 CMAKE_INSTALL_RPATH
21678 The rpath to use for installed targets.
21679 A semicolon-separated list specifying the rpath to use in
21681 installed targets (for platforms that support it). This is used
21682 to initialize the target property INSTALL_RPATH for all targets.
21683 CMAKE_INSTALL_RPATH_USE_LINK_PATH
21686 Add paths to linker search and installed rpath.
21687 CMAKE_INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to
21689 true will append directories in the linker search path and out‐
21690 side the project to the INSTALL_RPATH. This is used to initial‐
21691 ize the target property INSTALL_RPATH_USE_LINK_PATH for all tar‐
21692 gets.
21693 CMAKE_LIBRARY_OUTPUT_DIRECTORY
21696 Where to put all the LIBRARY targets when built.
21697 This variable is used to initialize the LIBRARY_OUTPUT_DIRECTORY
21699 property on all the targets. See that target property for addi‐
21700 tional information.
21701 CMAKE_LIBRARY_PATH_FLAG
21704 The flag to be used to add a library search path to a compiler.
21705 The flag will be used to specify a library directory to the com‐
21707 piler. On most compilers this is "-L".
21708 CMAKE_LINK_DEF_FILE_FLAG
21711 Linker flag to be used to specify a .def file for dll creation.
21712 The flag will be used to add a .def file when creating a dll on
21714 Windows; this is only defined on Windows.
21715 CMAKE_LINK_DEPENDS_NO_SHARED
21718 Whether to skip link dependencies on shared library files.
21719 This variable initializes the LINK_DEPENDS_NO_SHARED property on
21721 targets when they are created. See that target property for
21722 additional information.
21723 CMAKE_LINK_INTERFACE_LIBRARIES
21726 Default value for LINK_INTERFACE_LIBRARIES of targets.
21727 This variable is used to initialize the LINK_INTERFACE_LIBRARIES
21729 property on all the targets. See that target property for addi‐
21730 tional information.
21731 CMAKE_LINK_LIBRARY_FILE_FLAG
21734 Flag to be used to link a library specified by a path to its
21735 file.
21736 The flag will be used before a library file path is given to the
21738 linker. This is needed only on very few platforms.
21739 CMAKE_LINK_LIBRARY_FLAG
21742 Flag to be used to link a library into an executable.
21743 The flag will be used to specify a library to link to an exe‐
21745 cutable. On most compilers this is "-l".
21746 CMAKE_MACOSX_BUNDLE
21749 Default value for MACOSX_BUNDLE of targets.
21750 This variable is used to initialize the MACOSX_BUNDLE property
21752 on all the targets. See that target property for additional
21753 information.
21754 CMAKE_MODULE_LINKER_FLAGS
21757 Linker flags to be used to create modules.
21758 These flags will be used by the linker when creating a module.
21760 CMAKE_MODULE_LINKER_FLAGS_<CONFIG>
21763 Flags to be used when linking a module.
21764 Same as CMAKE_C_FLAGS_* but used by the linker when creating
21766 modules.
21767 CMAKE_NO_BUILTIN_CHRPATH
21770 Do not use the builtin ELF editor to fix RPATHs on installation.
21771 When an ELF binary needs to have a different RPATH after instal‐
21773 lation than it does in the build tree, CMake uses a builtin edi‐
21774 tor to change the RPATH in the installed copy. If this variable
21775 is set to true then CMake will relink the binary before instal‐
21776 lation instead of using its builtin editor.
21777 CMAKE_PDB_OUTPUT_DIRECTORY
21780 Where to put all the MS debug symbol files from linker.
21781 This variable is used to initialize the PDB_OUTPUT_DIRECTORY
21783 property on all the targets. See that target property for addi‐
21784 tional information.
21785 CMAKE_POSITION_INDEPENDENT_CODE
21788 Default value for POSITION_INDEPENDENT_CODE of targets.
21789 This variable is used to initialize the POSITION_INDEPEN‐
21791 DENT_CODE property on all the targets. See that target property
21792 for additional information.
21793 CMAKE_RUNTIME_OUTPUT_DIRECTORY
21796 Where to put all the RUNTIME targets when built.
21797 This variable is used to initialize the RUNTIME_OUTPUT_DIRECTORY
21799 property on all the targets. See that target property for addi‐
21800 tional information.
21801 CMAKE_SHARED_LINKER_FLAGS
21804 Linker flags to be used to create shared libraries.
21805 These flags will be used by the linker when creating a shared
21807 library.
21808 CMAKE_SHARED_LINKER_FLAGS_<CONFIG>
21811 Flags to be used when linking a shared library.
21812 Same as CMAKE_C_FLAGS_* but used by the linker when creating
21814 shared libraries.
21815 CMAKE_SKIP_BUILD_RPATH
21818 Do not include RPATHs in the build tree.
21819 Normally CMake uses the build tree for the RPATH when building
21821 executables etc on systems that use RPATH. When the software is
21822 installed the executables etc are relinked by CMake to have the
21823 install RPATH. If this variable is set to true then the software
21824 is always built with no RPATH.
21825 CMAKE_SKIP_INSTALL_RPATH
21828 Do not include RPATHs in the install tree.
21829 Normally CMake uses the build tree for the RPATH when building
21831 executables etc on systems that use RPATH. When the software is
21832 installed the executables etc are relinked by CMake to have the
21833 install RPATH. If this variable is set to true then the software
21834 is always installed without RPATH, even if RPATH is enabled when
21835 building. This can be useful for example to allow running tests
21836 from the build directory with RPATH enabled before the installa‐
21837 tion step. To omit RPATH in both the build and install steps,
21838 use CMAKE_SKIP_RPATH instead.
21839 CMAKE_STATIC_LINKER_FLAGS
21842 Linker flags to be used to create static libraries.
21843 These flags will be used by the linker when creating a static
21845 library.
21846 CMAKE_STATIC_LINKER_FLAGS_<CONFIG>
21849 Flags to be used when linking a static library.
21850 Same as CMAKE_C_FLAGS_* but used by the linker when creating
21852 static libraries.
21853 CMAKE_TRY_COMPILE_CONFIGURATION
21856 Build configuration used for try_compile and try_run projects.
21857 Projects built by try_compile and try_run are built syn‐
21859 chronously during the CMake configuration step. Therefore a
21860 specific build configuration must be chosen even if the gener‐
21861 ated build system supports multiple configurations.
21862 CMAKE_USE_RELATIVE_PATHS
21865 Use relative paths (May not work!).
21866 If this is set to TRUE, then CMake will use relative paths
21868 between the source and binary tree. This option does not work
21869 for more complicated projects, and relative paths are used when
21870 possible. In general, it is not possible to move CMake gener‐
21871 ated makefiles to a different location regardless of the value
21872 of this variable.
21873 CMAKE_VISIBILITY_INLINES_HIDDEN
21876 Default value for VISIBILITY_INLINES_HIDDEN of targets.
21877 This variable is used to initialize the VISIBILITY_INLINES_HID‐
21879 DEN property on all the targets. See that target property for
21880 additional information.
21881 CMAKE_WIN32_EXECUTABLE
21884 Default value for WIN32_EXECUTABLE of targets.
21885 This variable is used to initialize the WIN32_EXECUTABLE prop‐
21887 erty on all the targets. See that target property for addi‐
21888 tional information.
21889 EXECUTABLE_OUTPUT_PATH
21892 Old executable location variable.
21893 The target property RUNTIME_OUTPUT_DIRECTORY supercedes this
21895 variable for a target if it is set. Executable targets are oth‐
21896 erwise placed in this directory.
21897 LIBRARY_OUTPUT_PATH
21900 Old library location variable.
21901 The target properties ARCHIVE_OUTPUT_DIRECTORY, LIBRARY_OUT‐
21903 PUT_DIRECTORY, and RUNTIME_OUTPUT_DIRECTORY supercede this vari‐
21904 able for a target if they are set. Library targets are other‐
21905 wise placed in this directory.
21906
21909 variables defined by cmake, that give information about the project,
21910 and cmake
21911 CMAKE_AR
21914 Name of archiving tool for static libraries.
21915 This specifies the name of the program that creates archive or
21917 static libraries.
21918 CMAKE_ARGC
21921 Number of command line arguments passed to CMake in script mode.
21922 When run in -P script mode, CMake sets this variable to the num‐
21924 ber of command line arguments. See also CMAKE_ARGV0, 1, 2 ...
21925 CMAKE_ARGV0
21928 Command line argument passed to CMake in script mode.
21929 When run in -P script mode, CMake sets this variable to the
21931 first command line argument. It then also sets CMAKE_ARGV1,
21932 CMAKE_ARGV2, ... and so on, up to the number of command line
21933 arguments given. See also CMAKE_ARGC.
21934 CMAKE_BINARY_DIR
21937 The path to the top level of the build tree.
21938 This is the full path to the top level of the current CMake
21940 build tree. For an in-source build, this would be the same as
21941 CMAKE_SOURCE_DIR.
21942 CMAKE_BUILD_TOOL
21945 Tool used for the actual build process.
21946 This variable is set to the program that will be needed to build
21948 the output of CMake. If the generator selected was Visual Stu‐
21949 dio 6, the CMAKE_BUILD_TOOL will be set to msdev, for Unix Make‐
21950 files it will be set to make or gmake, and for Visual Studio 7
21951 it set to devenv. For NMake Makefiles the value is nmake. This
21952 can be useful for adding special flags and commands based on the
21953 final build environment.
21954 CMAKE_CACHEFILE_DIR
21957 The directory with the CMakeCache.txt file.
21958 This is the full path to the directory that has the CMake‐
21960 Cache.txt file in it. This is the same as CMAKE_BINARY_DIR.
21961 CMAKE_CACHE_MAJOR_VERSION
21964 Major version of CMake used to create the CMakeCache.txt file
21965 This stores the major version of CMake used to write a CMake
21967 cache file. It is only different when a different version of
21968 CMake is run on a previously created cache file.
21969 CMAKE_CACHE_MINOR_VERSION
21972 Minor version of CMake used to create the CMakeCache.txt file
21973 This stores the minor version of CMake used to write a CMake
21975 cache file. It is only different when a different version of
21976 CMake is run on a previously created cache file.
21977 CMAKE_CACHE_PATCH_VERSION
21980 Patch version of CMake used to create the CMakeCache.txt file
21981 This stores the patch version of CMake used to write a CMake
21983 cache file. It is only different when a different version of
21984 CMake is run on a previously created cache file.
21985 CMAKE_CFG_INTDIR
21988 Build-time reference to per-configuration output subdirectory.
21989 For native build systems supporting multiple configurations in
21991 the build tree (such as Visual Studio and Xcode), the value is a
21992 reference to a build-time variable specifying the name of the
21993 per-configuration output subdirectory. On Makefile generators
21994 this evaluates to "." because there is only one configuration in
21995 a build tree. Example values:
21996 $(IntDir) = Visual Studio 6
21999 $(OutDir) = Visual Studio 7, 8, 9
22000 $(Configuration) = Visual Studio 10
22001 $(CONFIGURATION) = Xcode
22002 . = Make-based tools
22003 Since these values are evaluated by the native build system,
22005 this variable is suitable only for use in command lines that
22006 will be evaluated at build time. Example of intended usage:
22007 add_executable(mytool mytool.c)
22010 add_custom_command(
22011 OUTPUT out.txt
22012 COMMAND ${CMAKE_CURRENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool
22013 ${CMAKE_CURRENT_SOURCE_DIR}/in.txt out.txt
22014 DEPENDS mytool in.txt
22015 )
22016 add_custom_target(drive ALL DEPENDS out.txt)
22017 Note that CMAKE_CFG_INTDIR is no longer necessary for this pur‐
22019 pose but has been left for compatibility with existing projects.
22020 Instead add_custom_command() recognizes executable target names
22021 in its COMMAND option, so "${CMAKE_CUR‐
22022 RENT_BINARY_DIR}/${CMAKE_CFG_INTDIR}/mytool" can be replaced by
22023 just "mytool".
22024 This variable is read-only. Setting it is undefined behavior.
22027 In multi-configuration build systems the value of this variable
22028 is passed as the value of preprocessor symbol "CMAKE_INTDIR" to
22029 the compilation of all source files.
22030 CMAKE_COMMAND
22033 The full path to the cmake executable.
22034 This is the full path to the CMake executable cmake which is
22036 useful from custom commands that want to use the cmake -E option
22037 for portable system commands. (e.g. /usr/local/bin/cmake
22038 CMAKE_CROSSCOMPILING
22041 Is CMake currently cross compiling.
22042 This variable will be set to true by CMake if CMake is cross
22044 compiling. Specifically if the build platform is different from
22045 the target platform.
22046 CMAKE_CTEST_COMMAND
22049 Full path to ctest command installed with cmake.
22050 This is the full path to the CTest executable ctest which is
22052 useful from custom commands that want to use the cmake -E option
22053 for portable system commands.
22054 CMAKE_CURRENT_BINARY_DIR
22057 The path to the binary directory currently being processed.
22058 This the full path to the build directory that is currently
22060 being processed by cmake. Each directory added by add_subdirec‐
22061 tory will create a binary directory in the build tree, and as it
22062 is being processed this variable will be set. For in-source
22063 builds this is the current source directory being processed.
22064 CMAKE_CURRENT_LIST_DIR
22067 Full directory of the listfile currently being processed.
22068 As CMake processes the listfiles in your project this variable
22070 will always be set to the directory where the listfile which is
22071 currently being processed (CMAKE_CURRENT_LIST_FILE) is located.
22072 The value has dynamic scope. When CMake starts processing com‐
22073 mands in a source file it sets this variable to the directory
22074 where this file is located. When CMake finishes processing com‐
22075 mands from the file it restores the previous value. Therefore
22076 the value of the variable inside a macro or function is the
22077 directory of the file invoking the bottom-most entry on the call
22078 stack, not the directory of the file containing the macro or
22079 function definition.
22080 See also CMAKE_CURRENT_LIST_FILE.
22083 CMAKE_CURRENT_LIST_FILE
22086 Full path to the listfile currently being processed.
22087 As CMake processes the listfiles in your project this variable
22089 will always be set to the one currently being processed. The
22090 value has dynamic scope. When CMake starts processing commands
22091 in a source file it sets this variable to the location of the
22092 file. When CMake finishes processing commands from the file it
22093 restores the previous value. Therefore the value of the vari‐
22094 able inside a macro or function is the file invoking the bot‐
22095 tom-most entry on the call stack, not the file containing the
22096 macro or function definition.
22097 See also CMAKE_PARENT_LIST_FILE.
22100 CMAKE_CURRENT_LIST_LINE
22103 The line number of the current file being processed.
22104 This is the line number of the file currently being processed by
22106 cmake.
22107 CMAKE_CURRENT_SOURCE_DIR
22110 The path to the source directory currently being processed.
22111 This the full path to the source directory that is currently
22113 being processed by cmake.
22114 CMAKE_DL_LIBS
22117 Name of library containing dlopen and dlcose.
22118 The name of the library that has dlopen and dlclose in it, usu‐
22120 ally -ldl on most UNIX machines.
22121 CMAKE_EDIT_COMMAND
22124 Full path to cmake-gui or ccmake.
22125 This is the full path to the CMake executable that can graphi‐
22127 cally edit the cache. For example, cmake-gui, ccmake, or cmake
22128 -i.
22129 CMAKE_EXECUTABLE_SUFFIX
22132 The suffix for executables on this platform.
22133 The suffix to use for the end of an executable filename if any,
22135 .exe on Windows.
22136 CMAKE_EXECUTABLE_SUFFIX_<LANG> overrides this for language
22139 <LANG>.
22140 CMAKE_EXTRA_GENERATOR
22143 The extra generator used to build the project.
22144 When using the Eclipse, CodeBlocks or KDevelop generators, CMake
22146 generates Makefiles (CMAKE_GENERATOR) and additionally project
22147 files for the respective IDE. This IDE project file generator is
22148 stored in CMAKE_EXTRA_GENERATOR (e.g. "Eclipse CDT4").
22149 CMAKE_EXTRA_SHARED_LIBRARY_SUFFIXES
22152 Additional suffixes for shared libraries.
22153 Extensions for shared libraries other than that specified by
22155 CMAKE_SHARED_LIBRARY_SUFFIX, if any. CMake uses this to recog‐
22156 nize external shared library files during analysis of libraries
22157 linked by a target.
22158 CMAKE_GENERATOR
22161 The generator used to build the project.
22162 The name of the generator that is being used to generate the
22164 build files. (e.g. "Unix Makefiles", "Visual Studio 6", etc.)
22165 CMAKE_GENERATOR_TOOLSET
22168 Native build system toolset name specified by user.
22169 Some CMake generators support a toolset name to be given to the
22171 native build system to choose a compiler. If the user specifies
22172 a toolset name (e.g. via the cmake -T option) the value will be
22173 available in this variable.
22174 CMAKE_HOME_DIRECTORY
22177 Path to top of source tree.
22178 This is the path to the top level of the source tree.
22180 CMAKE_IMPORT_LIBRARY_PREFIX
22183 The prefix for import libraries that you link to.
22184 The prefix to use for the name of an import library if used on
22186 this platform.
22187 CMAKE_IMPORT_LIBRARY_PREFIX_<LANG> overrides this for language
22190 <LANG>.
22191 CMAKE_IMPORT_LIBRARY_SUFFIX
22194 The suffix for import libraries that you link to.
22195 The suffix to use for the end of an import library filename if
22197 used on this platform.
22198 CMAKE_IMPORT_LIBRARY_SUFFIX_<LANG> overrides this for language
22201 <LANG>.
22202 CMAKE_LINK_LIBRARY_SUFFIX
22205 The suffix for libraries that you link to.
22206 The suffix to use for the end of a library filename, .lib on
22208 Windows.
22209 CMAKE_MAJOR_VERSION
22212 The Major version of cmake (i.e. the 2 in 2.X.X)
22213 This specifies the major version of the CMake executable being
22215 run.
22216 CMAKE_MAKE_PROGRAM
22219 See CMAKE_BUILD_TOOL.
22220 This variable is around for backwards compatibility, see
22222 CMAKE_BUILD_TOOL.
22223 CMAKE_MINIMUM_REQUIRED_VERSION
22226 Version specified to cmake_minimum_required command
22227 Variable containing the VERSION component specified in the
22229 cmake_minimum_required command.
22230 CMAKE_MINOR_VERSION
22233 The Minor version of cmake (i.e. the 4 in X.4.X).
22234 This specifies the minor version of the CMake executable being
22236 run.
22237 CMAKE_PARENT_LIST_FILE
22240 Full path to the CMake file that included the current one.
22241 While processing a CMake file loaded by include() or find_pack‐
22243 age() this variable contains the full path to the file including
22244 it. The top of the include stack is always the CMakeLists.txt
22245 for the current directory. See also CMAKE_CURRENT_LIST_FILE.
22246 CMAKE_PATCH_VERSION
22249 The patch version of cmake (i.e. the 3 in X.X.3).
22250 This specifies the patch version of the CMake executable being
22252 run.
22253 CMAKE_PROJECT_NAME
22256 The name of the current project.
22257 This specifies name of the current project from the closest
22259 inherited PROJECT command.
22260 CMAKE_RANLIB
22263 Name of randomizing tool for static libraries.
22264 This specifies name of the program that randomizes libraries on
22266 UNIX, not used on Windows, but may be present.
22267 CMAKE_ROOT
22270 Install directory for running cmake.
22271 This is the install root for the running CMake and the Modules
22273 directory can be found here. This is commonly used in this for‐
22274 mat: ${CMAKE_ROOT}/Modules
22275 CMAKE_SCRIPT_MODE_FILE
22278 Full path to the -P script file currently being processed.
22279 When run in -P script mode, CMake sets this variable to the full
22281 path of the script file. When run to configure a CMakeLists.txt
22282 file, this variable is not set.
22283 CMAKE_SHARED_LIBRARY_PREFIX
22286 The prefix for shared libraries that you link to.
22287 The prefix to use for the name of a shared library, lib on UNIX.
22289 CMAKE_SHARED_LIBRARY_PREFIX_<LANG> overrides this for language
22292 <LANG>.
22293 CMAKE_SHARED_LIBRARY_SUFFIX
22296 The suffix for shared libraries that you link to.
22297 The suffix to use for the end of a shared library filename, .dll
22299 on Windows.
22300 CMAKE_SHARED_LIBRARY_SUFFIX_<LANG> overrides this for language
22303 <LANG>.
22304 CMAKE_SHARED_MODULE_PREFIX
22307 The prefix for loadable modules that you link to.
22308 The prefix to use for the name of a loadable module on this
22310 platform.
22311 CMAKE_SHARED_MODULE_PREFIX_<LANG> overrides this for language
22314 <LANG>.
22315 CMAKE_SHARED_MODULE_SUFFIX
22318 The suffix for shared libraries that you link to.
22319 The suffix to use for the end of a loadable module filename on
22321 this platform
22322 CMAKE_SHARED_MODULE_SUFFIX_<LANG> overrides this for language
22325 <LANG>.
22326 CMAKE_SIZEOF_VOID_P
22329 Size of a void pointer.
22330 This is set to the size of a pointer on the machine, and is
22332 determined by a try compile. If a 64 bit size is found, then the
22333 library search path is modified to look for 64 bit libraries
22334 first.
22335 CMAKE_SKIP_RPATH
22338 If true, do not add run time path information.
22339 If this is set to TRUE, then the rpath information is not added
22341 to compiled executables. The default is to add rpath informa‐
22342 tion if the platform supports it. This allows for easy running
22343 from the build tree. To omit RPATH in the install step, but not
22344 the build step, use CMAKE_SKIP_INSTALL_RPATH instead.
22345 CMAKE_SOURCE_DIR
22348 The path to the top level of the source tree.
22349 This is the full path to the top level of the current CMake
22351 source tree. For an in-source build, this would be the same as
22352 CMAKE_BINARY_DIR.
22353 CMAKE_STANDARD_LIBRARIES
22356 Libraries linked into every executable and shared library.
22357 This is the list of libraries that are linked into all executa‐
22359 bles and libraries.
22360 CMAKE_STATIC_LIBRARY_PREFIX
22363 The prefix for static libraries that you link to.
22364 The prefix to use for the name of a static library, lib on UNIX.
22366 CMAKE_STATIC_LIBRARY_PREFIX_<LANG> overrides this for language
22369 <LANG>.
22370 CMAKE_STATIC_LIBRARY_SUFFIX
22373 The suffix for static libraries that you link to.
22374 The suffix to use for the end of a static library filename, .lib
22376 on Windows.
22377 CMAKE_STATIC_LIBRARY_SUFFIX_<LANG> overrides this for language
22380 <LANG>.
22381 CMAKE_TWEAK_VERSION
22384 The tweak version of cmake (i.e. the 1 in X.X.X.1).
22385 This specifies the tweak version of the CMake executable being
22387 run. Releases use tweak < 20000000 and development versions use
22388 the date format CCYYMMDD for the tweak level.
22389 CMAKE_VERBOSE_MAKEFILE
22392 Create verbose makefiles if on.
22393 This variable defaults to false. You can set this variable to
22395 true to make CMake produce verbose makefiles that show each com‐
22396 mand line as it is used.
22397 CMAKE_VERSION
22400 The full version of cmake in major.minor.patch[.tweak[-id]] for‐
22401 mat.
22402 This specifies the full version of the CMake executable being
22404 run. This variable is defined by versions 2.6.3 and higher.
22405 See variables CMAKE_MAJOR_VERSION, CMAKE_MINOR_VERSION,
22406 CMAKE_PATCH_VERSION, and CMAKE_TWEAK_VERSION for individual ver‐
22407 sion components. The [-id] component appears in non-release
22408 versions and may be arbitrary text.
22409 CMAKE_VS_PLATFORM_TOOLSET
22412 Visual Studio Platform Toolset name.
22413 VS 10 and above use MSBuild under the hood and support multiple
22415 compiler toolchains. CMake may specify a toolset explicitly,
22416 such as "v110" for VS 11 or "Windows7.1SDK" for 64-bit support
22417 in VS 10 Express. CMake provides the name of the chosen toolset
22418 in this variable.
22419 CMAKE_XCODE_PLATFORM_TOOLSET
22422 Xcode compiler selection.
22423 Xcode supports selection of a compiler from one of the installed
22425 toolsets. CMake provides the name of the chosen toolset in this
22426 variable, if any is explicitly selected (e.g. via the cmake -T
22427 option).
22428 PROJECT_BINARY_DIR
22431 Full path to build directory for project.
22432 This is the binary directory of the most recent PROJECT command.
22434 PROJECT_NAME
22437 Name of the project given to the project command.
22438 This is the name given to the most recent PROJECT command.
22440 PROJECT_SOURCE_DIR
22443 Top level source directory for the current project.
22444 This is the source directory of the most recent PROJECT command.
22446 [Project name]_BINARY_DIR
22449 Top level binary directory for the named project.
22450 A variable is created with the name used in the PROJECT command,
22452 and is the binary directory for the project. This can be use‐
22453 ful when SUBDIR is used to connect several projects.
22454 [Project name]_SOURCE_DIR
22457 Top level source directory for the named project.
22458 A variable is created with the name used in the PROJECT command,
22460 and is the source directory for the project. This can be use‐
22461 ful when add_subdirectory is used to connect several projects.
22462
22465 Copyright 2000-2012 Kitware, Inc., Insight Software Consortium. All
22466 rights reserved.
22467 Redistribution and use in source and binary forms, with or without mod‐
22470 ification, are permitted provided that the following conditions are
22471 met:
22472 Redistributions of source code must retain the above copyright notice,
22475 this list of conditions and the following disclaimer.
22476 Redistributions in binary form must reproduce the above copyright
22479 notice, this list of conditions and the following disclaimer in the
22480 documentation and/or other materials provided with the distribution.
22481 Neither the names of Kitware, Inc., the Insight Software Consortium,
22484 nor the names of their contributors may be used to endorse or promote
22485 products derived from this software without specific prior written per‐
22486 mission.
22487 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
22490 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
22491 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
22492 ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
22493 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
22494 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
22495 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
22496 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
22497 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
22498 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
22499 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
22500
22503 ccmake(1), cpack(1), ctest(1), cmakecommands(1), cmakecompat(1), cmake‐
22504 modules(1), cmakeprops(1), cmakevars(1)
22505 The following resources are available to get help using CMake:
22508 Home Page
22511 http://www.cmake.org
22512 The primary starting point for learning about CMake.
22514 Frequently Asked Questions
22517 http://www.cmake.org/Wiki/CMake_FAQ
22518 A Wiki is provided containing answers to frequently asked ques‐
22520 tions.
22521 Online Documentation
22524 http://www.cmake.org/HTML/Documentation.html
22525 Links to available documentation may be found on this web page.
22527 Mailing List
22530 http://www.cmake.org/HTML/MailingLists.html
22531 For help and discussion about using cmake, a mailing list is
22533 provided at cmake@cmake.org. The list is member-post-only but
22534 one may sign up on the CMake web page. Please first read the
22535 full documentation at http://www.cmake.org before posting ques‐
22536 tions to the list.
22537
22540 This manual page was generated by the "--help-man" option.
22541cmake 2.8.12.2 October 15, 2014 cmake(1)