1cmakecommands(1) General Commands Manual cmakecommands(1)
2
6 cmakecommands - Reference of available CMake commands.
7
10 add_custom_command
11 Add a custom build rule to the generated build system.
12 There are two main signatures for add_custom_command The first
14 signature is for adding a custom command to produce an output.
15 add_custom_command(OUTPUT output1 [output2 ...]
18 COMMAND command1 [ARGS] [args1...]
19 [COMMAND command2 [ARGS] [args2...] ...]
20 [MAIN_DEPENDENCY depend]
21 [DEPENDS [depends...]]
22 [IMPLICIT_DEPENDS <lang1> depend1 ...]
23 [WORKING_DIRECTORY dir]
24 [COMMENT comment] [VERBATIM] [APPEND])
25 This defines a command to generate specified OUTPUT file(s). A
27 target created in the same directory (CMakeLists.txt file) that
28 specifies any output of the custom command as a source file is
29 given a rule to generate the file using the command at build
30 time. If an output name is a relative path it will be inter‐
31 preted relative to the build tree directory corresponding to the
32 current source directory. Note that MAIN_DEPENDENCY is com‐
33 pletely optional and is used as a suggestion to visual studio
34 about where to hang the custom command. In makefile terms this
35 creates a new target in the following form:
36 OUTPUT: MAIN_DEPENDENCY DEPENDS
39 COMMAND
40 If more than one command is specified they will be executed in
42 order. The optional ARGS argument is for backward compatibility
43 and will be ignored.
44 The second signature adds a custom command to a target such as a
47 library or executable. This is useful for performing an opera‐
48 tion before or after building the target. The command becomes
49 part of the target and will only execute when the target itself
50 is built. If the target is already built, the command will not
51 execute.
52 add_custom_command(TARGET target
55 PRE_BUILD | PRE_LINK | POST_BUILD
56 COMMAND command1 [ARGS] [args1...]
57 [COMMAND command2 [ARGS] [args2...] ...]
58 [WORKING_DIRECTORY dir]
59 [COMMENT comment] [VERBATIM])
60 This defines a new command that will be associated with building
62 the specified target. When the command will happen is determined
63 by which of the following is specified:
64 PRE_BUILD - run before all other dependencies
67 PRE_LINK - run after other dependencies
68 POST_BUILD - run after the target has been built
69 Note that the PRE_BUILD option is only supported on Visual Stu‐
71 dio 7 or later. For all other generators PRE_BUILD will be
72 treated as PRE_LINK.
73 If WORKING_DIRECTORY is specified the command will be executed
76 in the directory given. If COMMENT is set, the value will be
77 displayed as a message before the commands are executed at build
78 time. If APPEND is specified the COMMAND and DEPENDS option val‐
79 ues are appended to the custom command for the first output
80 specified. There must have already been a previous call to this
81 command with the same output. The COMMENT, WORKING_DIRECTORY,
82 and MAIN_DEPENDENCY options are currently ignored when APPEND is
83 given, but may be used in the future.
84 If VERBATIM is given then all arguments to the commands will be
87 escaped properly for the build tool so that the invoked command
88 receives each argument unchanged. Note that one level of
89 escapes is still used by the CMake language processor before
90 add_custom_command even sees the arguments. Use of VERBATIM is
91 recommended as it enables correct behavior. When VERBATIM is not
92 given the behavior is platform specific because there is no pro‐
93 tection of tool-specific special characters.
94 If the output of the custom command is not actually created as a
97 file on disk it should be marked as SYMBOLIC with
98 SET_SOURCE_FILES_PROPERTIES.
99 The IMPLICIT_DEPENDS option requests scanning of implicit depen‐
102 dencies of an input file. The language given specifies the pro‐
103 gramming language whose corresponding dependency scanner should
104 be used. Currently only C and CXX language scanners are sup‐
105 ported. Dependencies discovered from the scanning are added to
106 those of the custom command at build time. Note that the
107 IMPLICIT_DEPENDS option is currently supported only for Makefile
108 generators and will be ignored by other generators.
109 If COMMAND specifies an executable target (created by ADD_EXE‐
112 CUTABLE) it will automatically be replaced by the location of
113 the executable created at build time. Additionally a tar‐
114 get-level dependency will be added so that the executable target
115 will be built before any target using this custom command. How‐
116 ever this does NOT add a file-level dependency that would cause
117 the custom command to re-run whenever the executable is recom‐
118 piled.
119 Arguments to COMMAND may use "generator expressions" with the
122 syntax "$<...>". Generator expressions are evaluted during
123 build system generation to produce information specific to each
124 build configuration. Valid expressions are:
125 $<CONFIGURATION> = configuration name
128 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
129 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
130 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
131 where "tgt" is the name of a target. Target file expressions
133 produce a full path, but _DIR and _NAME versions can produce the
134 directory and file name components:
135 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
138 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
139 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
140 References to target names in generator expressions imply tar‐
142 get-level dependencies, but NOT file-level dependencies. List
143 target names with the DEPENDS option to add file dependencies.
144 The DEPENDS option specifies files on which the command depends.
147 If any dependency is an OUTPUT of another custom command in the
148 same directory (CMakeLists.txt file) CMake automatically brings
149 the other custom command into the target in which this command
150 is built. If DEPENDS is not specified the command will run
151 whenever the OUTPUT is missing; if the command does not actually
152 create the OUTPUT then the rule will always run. If DEPENDS
153 specifies any target (created by an ADD_* command) a tar‐
154 get-level dependency is created to make sure the target is built
155 before any target using this custom command. Additionally, if
156 the target is an executable or library a file-level dependency
157 is created to cause the custom command to re-run whenever the
158 target is recompiled.
159 add_custom_target
163 Add a target with no output so it will always be built.
164 add_custom_target(Name [ALL] [command1 [args1...]]
166 [COMMAND command2 [args2...] ...]
167 [DEPENDS depend depend depend ... ]
168 [WORKING_DIRECTORY dir]
169 [COMMENT comment] [VERBATIM]
170 [SOURCES src1 [src2...]])
171 Adds a target with the given name that executes the given com‐
173 mands. The target has no output file and is ALWAYS CONSIDERED
174 OUT OF DATE even if the commands try to create a file with the
175 name of the target. Use ADD_CUSTOM_COMMAND to generate a file
176 with dependencies. By default nothing depends on the custom tar‐
177 get. Use ADD_DEPENDENCIES to add dependencies to or from other
178 targets. If the ALL option is specified it indicates that this
179 target should be added to the default build target so that it
180 will be run every time (the command cannot be called ALL). The
181 command and arguments are optional and if not specified an empty
182 target will be created. If WORKING_DIRECTORY is set, then the
183 command will be run in that directory. If COMMENT is set, the
184 value will be displayed as a message before the commands are
185 executed at build time. Dependencies listed with the DEPENDS
186 argument may reference files and outputs of custom commands cre‐
187 ated with add_custom_command() in the same directory (CMake‐
188 Lists.txt file).
189 If VERBATIM is given then all arguments to the commands will be
192 escaped properly for the build tool so that the invoked command
193 receives each argument unchanged. Note that one level of
194 escapes is still used by the CMake language processor before
195 add_custom_target even sees the arguments. Use of VERBATIM is
196 recommended as it enables correct behavior. When VERBATIM is not
197 given the behavior is platform specific because there is no pro‐
198 tection of tool-specific special characters.
199 The SOURCES option specifies additional source files to be
202 included in the custom target. Specified source files will be
203 added to IDE project files for convenience in editing even if
204 they have not build rules.
205 add_definitions
208 Adds -D define flags to the compilation of source files.
209 add_definitions(-DFOO -DBAR ...)
211 Adds flags to the compiler command line for sources in the cur‐
213 rent directory and below. This command can be used to add any
214 flags, but it was originally intended to add preprocessor defi‐
215 nitions. Flags beginning in -D or /D that look like preproces‐
216 sor definitions are automatically added to the COMPILE_DEFINI‐
217 TIONS property for the current directory. Definitions with
218 non-trival values may be left in the set of flags instead of
219 being converted for reasons of backwards compatibility. See
220 documentation of the directory, target, and source file COM‐
221 PILE_DEFINITIONS properties for details on adding preprocessor
222 definitions to specific scopes and configurations.
223 add_dependencies
226 Add a dependency between top-level targets.
227 add_dependencies(target-name depend-target1
229 depend-target2 ...)
230 Make a top-level target depend on other top-level targets. A
232 top-level target is one created by ADD_EXECUTABLE, ADD_LIBRARY,
233 or ADD_CUSTOM_TARGET. Adding dependencies with this command can
234 be used to make sure one target is built before another target.
235 Dependencies added to an IMPORTED target are followed transi‐
236 tively in its place since the target itself does not build. See
237 the DEPENDS option of ADD_CUSTOM_TARGET and ADD_CUSTOM_COMMAND
238 for adding file-level dependencies in custom rules. See the
239 OBJECT_DEPENDS option in SET_SOURCE_FILES_PROPERTIES to add
240 file-level dependencies to object files.
241 add_executable
244 Add an executable to the project using the specified source
245 files.
246 add_executable(<name> [WIN32] [MACOSX_BUNDLE]
248 [EXCLUDE_FROM_ALL]
249 source1 source2 ... sourceN)
250 Adds an executable target called <name> to be built from the
252 source files listed in the command invocation. The <name> cor‐
253 responds to the logical target name and must be globally unique
254 within a project. The actual file name of the executable built
255 is constructed based on conventions of the native platform (such
256 as <name>.exe or just <name>).
257 By default the executable file will be created in the build tree
260 directory corresponding to the source tree directory in which
261 the command was invoked. See documentation of the RUNTIME_OUT‐
262 PUT_DIRECTORY target property to change this location. See doc‐
263 umentation of the OUTPUT_NAME target property to change the
264 <name> part of the final file name.
265 If WIN32 is given the property WIN32_EXECUTABLE will be set on
268 the target created. See documentation of that target property
269 for details.
270 If MACOSX_BUNDLE is given the corresponding property will be set
273 on the created target. See documentation of the MACOSX_BUNDLE
274 target property for details.
275 If EXCLUDE_FROM_ALL is given the corresponding property will be
278 set on the created target. See documentation of the
279 EXCLUDE_FROM_ALL target property for details.
280 The add_executable command can also create IMPORTED executable
283 targets using this signature:
284 add_executable(<name> IMPORTED)
287 An IMPORTED executable target references an executable file
289 located outside the project. No rules are generated to build
290 it. The target name has scope in the directory in which it is
291 created and below. It may be referenced like any target built
292 within the project. IMPORTED executables are useful for conve‐
293 nient reference from commands like add_custom_command. Details
294 about the imported executable are specified by setting proper‐
295 ties whose names begin in "IMPORTED_". The most important such
296 property is IMPORTED_LOCATION (and its per-configuration version
297 IMPORTED_LOCATION_<CONFIG>) which specifies the location of the
298 main executable file on disk. See documentation of the
299 IMPORTED_* properties for more information.
300 add_library
303 Add a library to the project using the specified source files.
304 add_library(<name> [STATIC | SHARED | MODULE]
306 [EXCLUDE_FROM_ALL]
307 source1 source2 ... sourceN)
308 Adds a library target called <name> to be built from the source
310 files listed in the command invocation. The <name> corresponds
311 to the logical target name and must be globally unique within a
312 project. The actual file name of the library built is con‐
313 structed based on conventions of the native platform (such as
314 lib<name>.a or <name>.lib).
315 STATIC, SHARED, or MODULE may be given to specify the type of
318 library to be created. STATIC libraries are archives of object
319 files for use when linking other targets. SHARED libraries are
320 linked dynamically and loaded at runtime. MODULE libraries are
321 plugins that are not linked into other targets but may be loaded
322 dynamically at runtime using dlopen-like functionality. If no
323 type is given explicitly the type is STATIC or SHARED based on
324 whether the current value of the variable BUILD_SHARED_LIBS is
325 true.
326 By default the library file will be created in the build tree
329 directory corresponding to the source tree directory in which
330 the command was invoked. See documentation of the ARCHIVE_OUT‐
331 PUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUT‐
332 PUT_DIRECTORY target properties to change this location. See
333 documentation of the OUTPUT_NAME target property to change the
334 <name> part of the final file name.
335 If EXCLUDE_FROM_ALL is given the corresponding property will be
338 set on the created target. See documentation of the
339 EXCLUDE_FROM_ALL target property for details.
340 The add_library command can also create IMPORTED library targets
343 using this signature:
344 add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED)
347 An IMPORTED library target references a library file located
349 outside the project. No rules are generated to build it. The
350 target name has scope in the directory in which it is created
351 and below. It may be referenced like any target built within
352 the project. IMPORTED libraries are useful for convenient ref‐
353 erence from commands like target_link_libraries. Details about
354 the imported library are specified by setting properties whose
355 names begin in "IMPORTED_". The most important such property is
356 IMPORTED_LOCATION (and its per-configuration version
357 IMPORTED_LOCATION_<CONFIG>) which specifies the location of the
358 main library file on disk. See documentation of the IMPORTED_*
359 properties for more information.
360 add_subdirectory
363 Add a subdirectory to the build.
364 add_subdirectory(source_dir [binary_dir]
366 [EXCLUDE_FROM_ALL])
367 Add a subdirectory to the build. The source_dir specifies the
369 directory in which the source CmakeLists.txt and code files are
370 located. If it is a relative path it will be evaluated with
371 respect to the current directory (the typical usage), but it may
372 also be an absolute path. The binary_dir specifies the directory
373 in which to place the output files. If it is a relative path it
374 will be evaluated with respect to the current output directory,
375 but it may also be an absolute path. If binary_dir is not speci‐
376 fied, the value of source_dir, before expanding any relative
377 path, will be used (the typical usage). The CMakeLists.txt file
378 in the specified source directory will be processed immediately
379 by CMake before processing in the current input file continues
380 beyond this command.
381 If the EXCLUDE_FROM_ALL argument is provided then targets in the
384 subdirectory will not be included in the ALL target of the par‐
385 ent directory by default, and will be excluded from IDE project
386 files. Users must explicitly build targets in the subdirectory.
387 This is meant for use when the subdirectory contains a separate
388 part of the project that is useful but not necessary, such as a
389 set of examples. Typically the subdirectory should contain its
390 own project() command invocation so that a full build system
391 will be generated in the subdirectory (such as a VS IDE solution
392 file). Note that inter-target dependencies supercede this
393 exclusion. If a target built by the parent project depends on a
394 target in the subdirectory, the dependee target will be included
395 in the parent project build system to satisfy the dependency.
396 add_test
399 Add a test to the project with the specified arguments.
400 add_test(testname Exename arg1 arg2 ... )
402 If the ENABLE_TESTING command has been run, this command adds a
404 test target to the current directory. If ENABLE_TESTING has not
405 been run, this command does nothing. The tests are run by the
406 testing subsystem by executing Exename with the specified argu‐
407 ments. Exename can be either an executable built by this
408 project or an arbitrary executable on the system (like tclsh).
409 The test will be run with the current working directory set to
410 the CMakeList.txt files corresponding directory in the binary
411 tree.
412 add_test(NAME <name> [CONFIGURATIONS [Debug|Release|...]]
418 [WORKING_DIRECTORY dir]
419 COMMAND <command> [arg1 [arg2 ...]])
420 If COMMAND specifies an executable target (created by add_exe‐
422 cutable) it will automatically be replaced by the location of
423 the executable created at build time. If a CONFIGURATIONS
424 option is given then the test will be executed only when testing
425 under one of the named configurations. If a WORKING_DIRECTORY
426 option is given then the test will be executed in the given
427 directory.
428 Arguments after COMMAND may use "generator expressions" with the
431 syntax "$<...>". Generator expressions are evaluted during
432 build system generation to produce information specific to each
433 build configuration. Valid expressions are:
434 $<CONFIGURATION> = configuration name
437 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
438 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
439 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
440 where "tgt" is the name of a target. Target file expressions
442 produce a full path, but _DIR and _NAME versions can produce the
443 directory and file name components:
444 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
447 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
448 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
449 Example usage:
451 add_test(NAME mytest
454 COMMAND testDriver --config $<CONFIGURATION>
455 --exe $<TARGET_FILE:myexe>)
456 This creates a test "mytest" whose command runs a testDriver
458 tool passing the configuration name and the full path to the
459 executable file produced by target "myexe".
460 aux_source_directory
463 Find all source files in a directory.
464 aux_source_directory(<dir> <variable>)
466 Collects the names of all the source files in the specified
468 directory and stores the list in the <variable> provided. This
469 command is intended to be used by projects that use explicit
470 template instantiation. Template instantiation files can be
471 stored in a "Templates" subdirectory and collected automatically
472 using this command to avoid manually listing all instantiations.
473 It is tempting to use this command to avoid writing the list of
476 source files for a library or executable target. While this
477 seems to work, there is no way for CMake to generate a build
478 system that knows when a new source file has been added. Nor‐
479 mally the generated build system knows when it needs to rerun
480 CMake because the CMakeLists.txt file is modified to add a new
481 source. When the source is just added to the directory without
482 modifying this file, one would have to manually rerun CMake to
483 generate a build system incorporating the new file.
484 break Break from an enclosing foreach or while loop.
487 break()
489 Breaks from an enclosing foreach loop or while loop
491 build_command
494 Get the command line to build this project.
495 build_command(<variable>
497 [CONFIGURATION <config>]
498 [PROJECT_NAME <projname>]
499 [TARGET <target>])
500 Sets the given <variable> to a string containing the command
502 line for building one configuration of a target in a project
503 using the build tool appropriate for the current CMAKE_GENERA‐
504 TOR.
505 If CONFIGURATION is omitted, CMake chooses a reasonable default
508 value for multi-configuration generators. CONFIGURATION is
509 ignored for single-configuration generators.
510 If PROJECT_NAME is omitted, the resulting command line will
513 build the top level PROJECT in the current build tree.
514 If TARGET is omitted, the resulting command line will build
517 everything, effectively using build target 'all' or 'ALL_BUILD'.
518 build_command(<cachevariable> <makecommand>)
521 This second signature is deprecated, but still available for
523 backwards compatibility. Use the first signature instead.
524 Sets the given <cachevariable> to a string containing the com‐
527 mand to build this project from the root of the build tree using
528 the build tool given by <makecommand>. <makecommand> should be
529 the full path to msdev, devenv, nmake, make or one of the end
530 user build tools.
531 cmake_minimum_required
534 Set the minimum required version of cmake for a project.
535 cmake_minimum_required(VERSION major[.minor[.patch[.tweak]]]
537 [FATAL_ERROR])
538 If the current version of CMake is lower than that required it
540 will stop processing the project and report an error. When a
541 version higher than 2.4 is specified the command implicitly
542 invokes
543 cmake_policy(VERSION major[.minor[.patch[.tweak]]])
546 which sets the cmake policy version level to the version speci‐
548 fied. When version 2.4 or lower is given the command implicitly
549 invokes
550 cmake_policy(VERSION 2.4)
553 which enables compatibility features for CMake 2.4 and lower.
555 The FATAL_ERROR option is accepted but ignored by CMake 2.6 and
558 higher. It should be specified so CMake versions 2.4 and lower
559 fail with an error instead of just a warning.
560 cmake_policy
563 Manage CMake Policy settings.
564 As CMake evolves it is sometimes necessary to change existing
566 behavior in order to fix bugs or improve implementations of
567 existing features. The CMake Policy mechanism is designed to
568 help keep existing projects building as new versions of CMake
569 introduce changes in behavior. Each new policy (behavioral
570 change) is given an identifier of the form "CMP<NNNN>" where
571 "<NNNN>" is an integer index. Documentation associated with
572 each policy describes the OLD and NEW behavior and the reason
573 the policy was introduced. Projects may set each policy to
574 select the desired behavior. When CMake needs to know which
575 behavior to use it checks for a setting specified by the
576 project. If no setting is available the OLD behavior is assumed
577 and a warning is produced requesting that the policy be set.
578 The cmake_policy command is used to set policies to OLD or NEW
581 behavior. While setting policies individually is supported, we
582 encourage projects to set policies based on CMake versions.
583 cmake_policy(VERSION major.minor[.patch[.tweak]])
586 Specify that the current CMake list file is written for the
588 given version of CMake. All policies introduced in the speci‐
589 fied version or earlier will be set to use NEW behavior. All
590 policies introduced after the specified version will be unset
591 (unless variable CMAKE_POLICY_DEFAULT_CMP<NNNN> sets a default).
592 This effectively requests behavior preferred as of a given CMake
593 version and tells newer CMake versions to warn about their new
594 policies. The policy version specified must be at least 2.4 or
595 the command will report an error. In order to get compatibility
596 features supporting versions earlier than 2.4 see documentation
597 of policy CMP0001.
598 cmake_policy(SET CMP<NNNN> NEW)
601 cmake_policy(SET CMP<NNNN> OLD)
602 Tell CMake to use the OLD or NEW behavior for a given policy.
604 Projects depending on the old behavior of a given policy may
605 silence a policy warning by setting the policy state to OLD.
606 Alternatively one may fix the project to work with the new
607 behavior and set the policy state to NEW.
608 cmake_policy(GET CMP<NNNN> <variable>)
611 Check whether a given policy is set to OLD or NEW behavior. The
613 output variable value will be "OLD" or "NEW" if the policy is
614 set, and empty otherwise.
615 CMake keeps policy settings on a stack, so changes made by the
618 cmake_policy command affect only the top of the stack. A new
619 entry on the policy stack is managed automatically for each sub‐
620 directory to protect its parents and siblings. CMake also man‐
621 ages a new entry for scripts loaded by include() and find_pack‐
622 age() commands except when invoked with the NO_POLICY_SCOPE
623 option (see also policy CMP0011). The cmake_policy command pro‐
624 vides an interface to manage custom entries on the policy stack:
625 cmake_policy(PUSH)
628 cmake_policy(POP)
629 Each PUSH must have a matching POP to erase any changes. This
631 is useful to make temporary changes to policy settings.
632 Functions and macros record policy settings when they are cre‐
635 ated and use the pre-record policies when they are invoked. If
636 the function or macro implementation sets policies, the changes
637 automatically propagate up through callers until they reach the
638 closest nested policy stack entry.
639 configure_file
642 Copy a file to another location and modify its contents.
643 configure_file(<input> <output>
645 [COPYONLY] [ESCAPE_QUOTES] [@ONLY])
646 Copies a file <input> to file <output> and substitutes variable
648 values referenced in the file content. If <input> is a relative
649 path it is evaluated with respect to the current source direc‐
650 tory. The <input> must be a file, not a directory. If <output>
651 is a relative path it is evaluated with respect to the current
652 binary directory. If <output> names an existing directory the
653 input file is placed in that directory with its original name.
654 This command replaces any variables in the input file referenced
657 as ${VAR} or @VAR@ with their values as determined by CMake. If
658 a variable is not defined, it will be replaced with nothing. If
659 COPYONLY is specified, then no variable expansion will take
660 place. If ESCAPE_QUOTES is specified then any substituted
661 quotes will be C-style escaped. The file will be configured
662 with the current values of CMake variables. If @ONLY is speci‐
663 fied, only variables of the form @VAR@ will be replaces and
664 ${VAR} will be ignored. This is useful for configuring scripts
665 that use ${VAR}. Any occurrences of #cmakedefine VAR will be
666 replaced with either #define VAR or /* #undef VAR */ depending
667 on the setting of VAR in CMake. Any occurrences of #cmakede‐
668 fine01 VAR will be replaced with either #define VAR 1 or #define
669 VAR 0 depending on whether VAR evaluates to TRUE or FALSE in
670 CMake
671 create_test_sourcelist
674 Create a test driver and source list for building test programs.
675 create_test_sourcelist(sourceListName driverName
677 test1 test2 test3
678 EXTRA_INCLUDE include.h
679 FUNCTION function)
680 A test driver is a program that links together many small tests
682 into a single executable. This is useful when building static
683 executables with large libraries to shrink the total required
684 size. The list of source files needed to build the test driver
685 will be in sourceListName. DriverName is the name of the test
686 driver program. The rest of the arguments consist of a list of
687 test source files, can be semicolon separated. Each test source
688 file should have a function in it that is the same name as the
689 file with no extension (foo.cxx should have int foo(int,
690 char*[]);) DriverName will be able to call each of the tests by
691 name on the command line. If EXTRA_INCLUDE is specified, then
692 the next argument is included into the generated file. If FUNC‐
693 TION is specified, then the next argument is taken as a function
694 name that is passed a pointer to ac and av. This can be used to
695 add extra command line processing to each test. The cmake vari‐
696 able CMAKE_TESTDRIVER_BEFORE_TESTMAIN can be set to have code
697 that will be placed directly before calling the test main func‐
698 tion. CMAKE_TESTDRIVER_AFTER_TESTMAIN can be set to have code
699 that will be placed directly after the call to the test main
700 function.
701 define_property
704 Define and document custom properties.
705 define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
707 TEST | VARIABLE | CACHED_VARIABLE>
708 PROPERTY <name> [INHERITED]
709 BRIEF_DOCS <brief-doc> [docs...]
710 FULL_DOCS <full-doc> [docs...])
711 Define one property in a scope for use with the set_property and
713 get_property commands. This is primarily useful to associate
714 documentation with property names that may be retrieved with the
715 get_property command. The first argument determines the kind of
716 scope in which the property should be used. It must be one of
717 the following:
718 GLOBAL = associated with the global namespace
721 DIRECTORY = associated with one directory
722 TARGET = associated with one target
723 SOURCE = associated with one source file
724 TEST = associated with a test named with add_test
725 VARIABLE = documents a CMake language variable
726 CACHED_VARIABLE = documents a CMake cache variable
727 Note that unlike set_property and get_property no actual scope
729 needs to be given; only the kind of scope is important.
730 The required PROPERTY option is immediately followed by the name
733 of the property being defined.
734 If the INHERITED option then the get_property command will chain
737 up to the next higher scope when the requested property is not
738 set in the scope given to the command. DIRECTORY scope chains
739 to GLOBAL. TARGET, SOURCE, and TEST chain to DIRECTORY.
740 The BRIEF_DOCS and FULL_DOCS options are followed by strings to
743 be associated with the property as its brief and full documenta‐
744 tion. Corresponding options to the get_property command will
745 retrieve the documentation.
746 else Starts the else portion of an if block.
749 else(expression)
751 See the if command.
753 elseif Starts the elseif portion of an if block.
756 elseif(expression)
758 See the if command.
760 enable_language
763 Enable a language (CXX/C/Fortran/etc)
764 enable_language(languageName [OPTIONAL] )
766 This command enables support for the named language in CMake.
768 This is the same as the project command but does not create any
769 of the extra variables that are created by the project command.
770 Example languages are CXX, C, Fortran. If OPTIONAL is used, use
771 the CMAKE_<languageName>_COMPILER_WORKS variable to check
772 whether the language has been enabled successfully.
773 enable_testing
776 Enable testing for current directory and below.
777 enable_testing()
779 Enables testing for this directory and below. See also the
781 add_test command. Note that ctest expects to find a test file
782 in the build directory root. Therefore, this command should be
783 in the source directory root.
784 endforeach
787 Ends a list of commands in a FOREACH block.
788 endforeach(expression)
790 See the FOREACH command.
792 endfunction
795 Ends a list of commands in a function block.
796 endfunction(expression)
798 See the function command.
800 endif Ends a list of commands in an if block.
803 endif(expression)
805 See the if command.
807 endmacro
810 Ends a list of commands in a macro block.
811 endmacro(expression)
813 See the macro command.
815 endwhile
818 Ends a list of commands in a while block.
819 endwhile(expression)
821 See the while command.
823 execute_process
826 Execute one or more child processes.
827 execute_process(COMMAND <cmd1> [args1...]]
829 [COMMAND <cmd2> [args2...] [...]]
830 [WORKING_DIRECTORY <directory>]
831 [TIMEOUT <seconds>]
832 [RESULT_VARIABLE <variable>]
833 [OUTPUT_VARIABLE <variable>]
834 [ERROR_VARIABLE <variable>]
835 [INPUT_FILE <file>]
836 [OUTPUT_FILE <file>]
837 [ERROR_FILE <file>]
838 [OUTPUT_QUIET]
839 [ERROR_QUIET]
840 [OUTPUT_STRIP_TRAILING_WHITESPACE]
841 [ERROR_STRIP_TRAILING_WHITESPACE])
842 Runs the given sequence of one or more commands with the stan‐
844 dard output of each process piped to the standard input of the
845 next. A single standard error pipe is used for all processes.
846 If WORKING_DIRECTORY is given the named directory will be set as
847 the current working directory of the child processes. If TIME‐
848 OUT is given the child processes will be terminated if they do
849 not finish in the specified number of seconds (fractions are
850 allowed). If RESULT_VARIABLE is given the variable will be set
851 to contain the result of running the processes. This will be an
852 integer return code from the last child or a string describing
853 an error condition. If OUTPUT_VARIABLE or ERROR_VARIABLE are
854 given the variable named will be set with the contents of the
855 standard output and standard error pipes respectively. If the
856 same variable is named for both pipes their output will be
857 merged in the order produced. If INPUT_FILE, OUTPUT_FILE, or
858 ERROR_FILE is given the file named will be attached to the stan‐
859 dard input of the first process, standard output of the last
860 process, or standard error of all processes respectively. If
861 OUTPUT_QUIET or ERROR_QUIET is given then the standard output or
862 standard error results will be quietly ignored. If more than
863 one OUTPUT_* or ERROR_* option is given for the same pipe the
864 precedence is not specified. If no OUTPUT_* or ERROR_* options
865 are given the output will be shared with the corresponding pipes
866 of the CMake process itself.
867 The execute_process command is a newer more powerful version of
870 exec_program, but the old command has been kept for compatibil‐
871 ity.
872 export Export targets from the build tree for use by outside projects.
875 export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
877 [APPEND] FILE <filename>)
878 Create a file <filename> that may be included by outside
880 projects to import targets from the current project's build
881 tree. This is useful during cross-compiling to build utility
882 executables that can run on the host platform in one project and
883 then import them into another project being compiled for the
884 target platform. If the NAMESPACE option is given the <names‐
885 pace> string will be prepended to all target names written to
886 the file. If the APPEND option is given the generated code will
887 be appended to the file instead of overwriting it. If a library
888 target is included in the export but a target to which it links
889 is not included the behavior is unspecified.
890 The file created by this command is specific to the build tree
893 and should never be installed. See the install(EXPORT) command
894 to export targets from an installation tree.
895 export(PACKAGE <name>)
898 Store the current build directory in the CMake user package reg‐
900 istry for package <name>. The find_package command may consider
901 the directory while searching for package <name>. This helps
902 dependent projects find and use a package from the current
903 project's build tree without help from the user. Note that the
904 entry in the package registry that this command creates works
905 only in conjunction with a package configuration file
906 (<name>Config.cmake) that works with the build tree.
907 file File manipulation command.
910 file(WRITE filename "message to write"... )
912 file(APPEND filename "message to write"... )
913 file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX])
914 file(STRINGS filename variable [LIMIT_COUNT num]
915 [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes]
916 [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes]
917 [NEWLINE_CONSUME] [REGEX regex]
918 [NO_HEX_CONVERSION])
919 file(GLOB variable [RELATIVE path] [globbing expressions]...)
920 file(GLOB_RECURSE variable [RELATIVE path]
921 [FOLLOW_SYMLINKS] [globbing expressions]...)
922 file(RENAME <oldname> <newname>)
923 file(REMOVE [file1 ...])
924 file(REMOVE_RECURSE [file1 ...])
925 file(MAKE_DIRECTORY [directory1 directory2 ...])
926 file(RELATIVE_PATH variable directory file)
927 file(TO_CMAKE_PATH path result)
928 file(TO_NATIVE_PATH path result)
929 file(DOWNLOAD url file [TIMEOUT timeout] [STATUS status] [LOG log]
930 [EXPECTED_MD5 sum] [SHOW_PROGRESS])
931 WRITE will write a message into a file called 'filename'. It
933 overwrites the file if it already exists, and creates the file
934 if it does not exist.
935 APPEND will write a message into a file same as WRITE, except it
938 will append it to the end of the file
939 READ will read the content of a file and store it into the vari‐
942 able. It will start at the given offset and read up to numBytes.
943 If the argument HEX is given, the binary data will be converted
944 to hexadecimal representation and this will be stored in the
945 variable.
946 STRINGS will parse a list of ASCII strings from a file and store
949 it in a variable. Binary data in the file are ignored. Carriage
950 return (CR) characters are ignored. It works also for Intel Hex
951 and Motorola S-record files, which are automatically converted
952 to binary format when reading them. Disable this using
953 NO_HEX_CONVERSION.
954 LIMIT_COUNT sets the maximum number of strings to return.
957 LIMIT_INPUT sets the maximum number of bytes to read from the
958 input file. LIMIT_OUTPUT sets the maximum number of bytes to
959 store in the output variable. LENGTH_MINIMUM sets the minimum
960 length of a string to return. Shorter strings are ignored.
961 LENGTH_MAXIMUM sets the maximum length of a string to return.
962 Longer strings are split into strings no longer than the maximum
963 length. NEWLINE_CONSUME allows newlines to be included in
964 strings instead of terminating them.
965 REGEX specifies a regular expression that a string must match to
968 be returned. Typical usage
969 file(STRINGS myfile.txt myfile)
972 stores a list in the variable "myfile" in which each item is a
974 line from the input file.
975 GLOB will generate a list of all files that match the globbing
978 expressions and store it into the variable. Globbing expressions
979 are similar to regular expressions, but much simpler. If RELA‐
980 TIVE flag is specified for an expression, the results will be
981 returned as a relative path to the given path. (We do not rec‐
982 ommend using GLOB to collect a list of source files from your
983 source tree. If no CMakeLists.txt file changes when a source is
984 added or removed then the generated build system cannot know
985 when to ask CMake to regenerate.)
986 Examples of globbing expressions include:
989 *.cxx - match all files with extension cxx
992 *.vt? - match all files with extension vta,...,vtz
993 f[3-5].txt - match files f3.txt, f4.txt, f5.txt
994 GLOB_RECURSE will generate a list similar to the regular GLOB,
996 except it will traverse all the subdirectories of the matched
997 directory and match the files. Subdirectories that are symlinks
998 are only traversed if FOLLOW_SYMLINKS is given or cmake policy
999 CMP0009 is not set to NEW. See cmake --help-policy CMP0009 for
1000 more information.
1001 Examples of recursive globbing include:
1004 /dir/*.py - match all python files in /dir and subdirectories
1007 MAKE_DIRECTORY will create the given directories, also if their
1009 parent directories don't exist yet
1010 RENAME moves a file or directory within a filesystem, replacing
1013 the destination atomically.
1014 REMOVE will remove the given files, also in subdirectories
1017 REMOVE_RECURSE will remove the given files and directories, also
1020 non-empty directories
1021 RELATIVE_PATH will determine relative path from directory to the
1024 given file.
1025 TO_CMAKE_PATH will convert path into a cmake style path with
1028 unix /. The input can be a single path or a system path like
1029 "$ENV{PATH}". Note the double quotes around the ENV call
1030 TO_CMAKE_PATH only takes one argument.
1031 TO_NATIVE_PATH works just like TO_CMAKE_PATH, but will convert
1034 from a cmake style path into the native path style \ for win‐
1035 dows and / for UNIX.
1036 DOWNLOAD will download the given URL to the given file. If LOG
1039 var is specified a log of the download will be put in var. If
1040 STATUS var is specified the status of the operation will be put
1041 in var. The status is returned in a list of length 2. The first
1042 element is the numeric return value for the operation, and the
1043 second element is a string value for the error. A 0 numeric
1044 error means no error in the operation. If TIMEOUT time is speci‐
1045 fied, the operation will timeout after time seconds, time should
1046 be specified as an integer. If EXPECTED_MD5 sum is specified,
1047 the operation will verify that the downloaded file's actual md5
1048 sum matches the expected value. If it does not match, the opera‐
1049 tion fails with an error. If SHOW_PROGRESS is specified,
1050 progress information will be printed as status messages until
1051 the operation is complete.
1052 The file() command also provides COPY and INSTALL signatures:
1055 file(<COPY|INSTALL> files... DESTINATION <dir>
1058 [FILE_PERMISSIONS permissions...]
1059 [DIRECTORY_PERMISSIONS permissions...]
1060 [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
1061 [FILES_MATCHING]
1062 [[PATTERN <pattern> | REGEX <regex>]
1063 [EXCLUDE] [PERMISSIONS permissions...]] [...])
1064 The COPY signature copies files, directories, and symlinks to a
1066 destination folder. Relative input paths are evaluated with
1067 respect to the current source directory, and a relative destina‐
1068 tion is evaluated with respect to the current build directory.
1069 Copying preserves input file timestamps, and optimizes out a
1070 file if it exists at the destination with the same timestamp.
1071 Copying preserves input permissions unless explicit permissions
1072 or NO_SOURCE_PERMISSIONS are given (default is USE_SOURCE_PER‐
1073 MISSIONS). See the install(DIRECTORY) command for documentation
1074 of permissions, PATTERN, REGEX, and EXCLUDE options.
1075 The INSTALL signature differs slightly from COPY: it prints sta‐
1078 tus messages, and NO_SOURCE_PERMISSIONS is default. Installa‐
1079 tion scripts generated by the install() command use this signa‐
1080 ture (with some undocumented options for internal use).
1081 find_file
1084 Find the full path to a file.
1085 find_file(<VAR> name1 [path1 path2 ...])
1087 This is the short-hand signature for the command that is suffi‐
1089 cient in many cases. It is the same as find_file(<VAR> name1
1090 [PATHS path1 path2 ...])
1091 find_file(
1094 <VAR>
1095 name | NAMES name1 [name2 ...]
1096 [HINTS path1 [path2 ... ENV var]]
1097 [PATHS path1 [path2 ... ENV var]]
1098 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1099 [DOC "cache documentation string"]
1100 [NO_DEFAULT_PATH]
1101 [NO_CMAKE_ENVIRONMENT_PATH]
1102 [NO_CMAKE_PATH]
1103 [NO_SYSTEM_ENVIRONMENT_PATH]
1104 [NO_CMAKE_SYSTEM_PATH]
1105 [CMAKE_FIND_ROOT_PATH_BOTH |
1106 ONLY_CMAKE_FIND_ROOT_PATH |
1107 NO_CMAKE_FIND_ROOT_PATH]
1108 )
1109 This command is used to find a full path to named file. A cache
1111 entry named by <VAR> is created to store the result of this com‐
1112 mand. If the full path to a file is found the result is stored
1113 in the variable and the search will not be repeated unless the
1114 variable is cleared. If nothing is found, the result will be
1115 <VAR>-NOTFOUND, and the search will be attempted again the next
1116 time find_file is invoked with the same variable. The name of
1117 the full path to a file that is searched for is specified by the
1118 names listed after the NAMES argument. Additional search loca‐
1119 tions can be specified after the PATHS argument. If ENV var is
1120 found in the HINTS or PATHS section the environment variable var
1121 will be read and converted from a system environment variable to
1122 a cmake style list of paths. For example ENV PATH would be a
1123 way to list the system path variable. The argument after DOC
1124 will be used for the documentation string in the cache.
1125 PATH_SUFFIXES specifies additional subdirectories to check below
1126 each search path.
1127 If NO_DEFAULT_PATH is specified, then no additional paths are
1130 added to the search. If NO_DEFAULT_PATH is not specified, the
1131 search process is as follows:
1132 1. Search paths specified in cmake-specific cache variables.
1135 These are intended to be used on the command line with a
1136 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1137 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1140 CMAKE_INCLUDE_PATH
1141 CMAKE_FRAMEWORK_PATH
1142 2. Search paths specified in cmake-specific environment vari‐
1144 ables. These are intended to be set in the user's shell config‐
1145 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1146 passed.
1147 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1150 CMAKE_INCLUDE_PATH
1151 CMAKE_FRAMEWORK_PATH
1152 3. Search the paths specified by the HINTS option. These should
1154 be paths computed by system introspection, such as a hint pro‐
1155 vided by the location of another item already found. Hard-coded
1156 guesses should be specified with the PATHS option.
1157 4. Search the standard system environment variables. This can be
1160 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1161 PATH
1164 INCLUDE
1165 5. Search cmake variables defined in the Platform files for the
1167 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1168 passed.
1169 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1172 CMAKE_SYSTEM_INCLUDE_PATH
1173 CMAKE_SYSTEM_FRAMEWORK_PATH
1174 6. Search the paths specified by the PATHS option or in the
1176 short-hand version of the command. These are typically
1177 hard-coded guesses.
1178 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1181 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1182 following:
1183 "FIRST" - Try to find frameworks before standard
1186 libraries or headers. This is the default on Darwin.
1187 "LAST" - Try to find frameworks after standard
1188 libraries or headers.
1189 "ONLY" - Only try to find frameworks.
1190 "NEVER" - Never try to find frameworks.
1191 On Darwin or systems supporting OS X Application Bundles, the
1193 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
1194 of the following:
1195 "FIRST" - Try to find application bundles before standard
1198 programs. This is the default on Darwin.
1199 "LAST" - Try to find application bundles after standard
1200 programs.
1201 "ONLY" - Only try to find application bundles.
1202 "NEVER" - Never try to find application bundles.
1203 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
1205 directories to be prepended to all other search directories.
1206 This effectively "re-roots" the entire search under given loca‐
1207 tions. By default it is empty. It is especially useful when
1208 cross-compiling to point to the root directory of the target
1209 environment and CMake will search there too. By default at first
1210 the directories listed in CMAKE_FIND_ROOT_PATH and then the
1211 non-rooted directories will be searched. The default behavior
1212 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
1213 This behavior can be manually overridden on a per-call basis. By
1214 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
1215 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
1216 CMAKE_FIND_ROOT_PATH will not be used. If
1217 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1218 tories will be searched.
1219 The default search order is designed to be most-specific to
1222 least-specific for common use cases. Projects may override the
1223 order by simply calling the command multiple times and using the
1224 NO_* options:
1225 find_file(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1228 find_file(<VAR> NAMES name)
1229 Once one of the calls succeeds the result variable will be set
1231 and stored in the cache so that no call will search again.
1232 find_library
1235 Find a library.
1236 find_library(<VAR> name1 [path1 path2 ...])
1238 This is the short-hand signature for the command that is suffi‐
1240 cient in many cases. It is the same as find_library(<VAR> name1
1241 [PATHS path1 path2 ...])
1242 find_library(
1245 <VAR>
1246 name | NAMES name1 [name2 ...]
1247 [HINTS path1 [path2 ... ENV var]]
1248 [PATHS path1 [path2 ... ENV var]]
1249 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1250 [DOC "cache documentation string"]
1251 [NO_DEFAULT_PATH]
1252 [NO_CMAKE_ENVIRONMENT_PATH]
1253 [NO_CMAKE_PATH]
1254 [NO_SYSTEM_ENVIRONMENT_PATH]
1255 [NO_CMAKE_SYSTEM_PATH]
1256 [CMAKE_FIND_ROOT_PATH_BOTH |
1257 ONLY_CMAKE_FIND_ROOT_PATH |
1258 NO_CMAKE_FIND_ROOT_PATH]
1259 )
1260 This command is used to find a library. A cache entry named by
1262 <VAR> is created to store the result of this command. If the
1263 library is found the result is stored in the variable and the
1264 search will not be repeated unless the variable is cleared. If
1265 nothing is found, the result will be <VAR>-NOTFOUND, and the
1266 search will be attempted again the next time find_library is
1267 invoked with the same variable. The name of the library that is
1268 searched for is specified by the names listed after the NAMES
1269 argument. Additional search locations can be specified after
1270 the PATHS argument. If ENV var is found in the HINTS or PATHS
1271 section the environment variable var will be read and converted
1272 from a system environment variable to a cmake style list of
1273 paths. For example ENV PATH would be a way to list the system
1274 path variable. The argument after DOC will be used for the docu‐
1275 mentation string in the cache. PATH_SUFFIXES specifies addi‐
1276 tional subdirectories to check below each search path.
1277 If NO_DEFAULT_PATH is specified, then no additional paths are
1280 added to the search. If NO_DEFAULT_PATH is not specified, the
1281 search process is as follows:
1282 1. Search paths specified in cmake-specific cache variables.
1285 These are intended to be used on the command line with a
1286 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1287 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1290 CMAKE_LIBRARY_PATH
1291 CMAKE_FRAMEWORK_PATH
1292 2. Search paths specified in cmake-specific environment vari‐
1294 ables. These are intended to be set in the user's shell config‐
1295 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1296 passed.
1297 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1300 CMAKE_LIBRARY_PATH
1301 CMAKE_FRAMEWORK_PATH
1302 3. Search the paths specified by the HINTS option. These should
1304 be paths computed by system introspection, such as a hint pro‐
1305 vided by the location of another item already found. Hard-coded
1306 guesses should be specified with the PATHS option.
1307 4. Search the standard system environment variables. This can be
1310 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1311 PATH
1314 LIB
1315 5. Search cmake variables defined in the Platform files for the
1317 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1318 passed.
1319 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1322 CMAKE_SYSTEM_LIBRARY_PATH
1323 CMAKE_SYSTEM_FRAMEWORK_PATH
1324 6. Search the paths specified by the PATHS option or in the
1326 short-hand version of the command. These are typically
1327 hard-coded guesses.
1328 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1331 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1332 following:
1333 "FIRST" - Try to find frameworks before standard
1336 libraries or headers. This is the default on Darwin.
1337 "LAST" - Try to find frameworks after standard
1338 libraries or headers.
1339 "ONLY" - Only try to find frameworks.
1340 "NEVER" - Never try to find frameworks.
1341 On Darwin or systems supporting OS X Application Bundles, the
1343 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
1344 of the following:
1345 "FIRST" - Try to find application bundles before standard
1348 programs. This is the default on Darwin.
1349 "LAST" - Try to find application bundles after standard
1350 programs.
1351 "ONLY" - Only try to find application bundles.
1352 "NEVER" - Never try to find application bundles.
1353 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
1355 directories to be prepended to all other search directories.
1356 This effectively "re-roots" the entire search under given loca‐
1357 tions. By default it is empty. It is especially useful when
1358 cross-compiling to point to the root directory of the target
1359 environment and CMake will search there too. By default at first
1360 the directories listed in CMAKE_FIND_ROOT_PATH and then the
1361 non-rooted directories will be searched. The default behavior
1362 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.
1363 This behavior can be manually overridden on a per-call basis. By
1364 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
1365 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
1366 CMAKE_FIND_ROOT_PATH will not be used. If
1367 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1368 tories will be searched.
1369 The default search order is designed to be most-specific to
1372 least-specific for common use cases. Projects may override the
1373 order by simply calling the command multiple times and using the
1374 NO_* options:
1375 find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1378 find_library(<VAR> NAMES name)
1379 Once one of the calls succeeds the result variable will be set
1381 and stored in the cache so that no call will search again.
1382 If the library found is a framework, then VAR will be set to the
1385 full path to the framework <fullPath>/A.framework. When a full
1386 path to a framework is used as a library, CMake will use a
1387 -framework A, and a -F<fullPath> to link the framework to the
1388 target.
1389 find_package
1392 Load settings for an external project.
1393 find_package(<package> [version] [EXACT] [QUIET]
1395 [[REQUIRED|COMPONENTS] [components...]]
1396 [NO_POLICY_SCOPE])
1397 Finds and loads settings from an external project. <pack‐
1399 age>_FOUND will be set to indicate whether the package was
1400 found. When the package is found package-specific information
1401 is provided through variables documented by the package itself.
1402 The QUIET option disables messages if the package cannot be
1403 found. The REQUIRED option stops processing with an error mes‐
1404 sage if the package cannot be found. A package-specific list of
1405 components may be listed after the REQUIRED option or after the
1406 COMPONENTS option if no REQUIRED option is given. The [version]
1407 argument requests a version with which the package found should
1408 be compatible (format is major[.minor[.patch[.tweak]]]). The
1409 EXACT option requests that the version be matched exactly. If
1410 no [version] is given to a recursive invocation inside a
1411 find-module, the [version] and EXACT arguments are forwarded
1412 automatically from the outer call. Version support is currently
1413 provided only on a package-by-package basis (details below).
1414 User code should generally look for packages using the above
1417 simple signature. The remainder of this command documentation
1418 specifies the full command signature and details of the search
1419 process. Project maintainers wishing to provide a package to be
1420 found by this command are encouraged to read on.
1421 The command has two modes by which it searches for packages:
1424 "Module" mode and "Config" mode. Module mode is available when
1425 the command is invoked with the above reduced signature. CMake
1426 searches for a file called "Find<package>.cmake" in the
1427 CMAKE_MODULE_PATH followed by the CMake installation. If the
1428 file is found, it is read and processed by CMake. It is respon‐
1429 sible for finding the package, checking the version, and produc‐
1430 ing any needed messages. Many find-modules provide limited or
1431 no support for versioning; check the module documentation. If
1432 no module is found the command proceeds to Config mode.
1433 The complete Config mode command signature is:
1436 find_package(<package> [version] [EXACT] [QUIET]
1439 [[REQUIRED|COMPONENTS] [components...]] [NO_MODULE]
1440 [NO_POLICY_SCOPE]
1441 [NAMES name1 [name2 ...]]
1442 [CONFIGS config1 [config2 ...]]
1443 [HINTS path1 [path2 ... ]]
1444 [PATHS path1 [path2 ... ]]
1445 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1446 [NO_DEFAULT_PATH]
1447 [NO_CMAKE_ENVIRONMENT_PATH]
1448 [NO_CMAKE_PATH]
1449 [NO_SYSTEM_ENVIRONMENT_PATH]
1450 [NO_CMAKE_PACKAGE_REGISTRY]
1451 [NO_CMAKE_BUILDS_PATH]
1452 [NO_CMAKE_SYSTEM_PATH]
1453 [CMAKE_FIND_ROOT_PATH_BOTH |
1454 ONLY_CMAKE_FIND_ROOT_PATH |
1455 NO_CMAKE_FIND_ROOT_PATH])
1456 The NO_MODULE option may be used to skip Module mode explicitly.
1458 It is also implied by use of options not specified in the
1459 reduced signature.
1460 Config mode attempts to locate a configuration file provided by
1463 the package to be found. A cache entry called <package>_DIR is
1464 created to hold the directory containing the file. By default
1465 the command searches for a package with the name <package>. If
1466 the NAMES option is given the names following it are used
1467 instead of <package>. The command searches for a file called
1468 "<name>Config.cmake" or "<lower-case-name>-config.cmake" for
1469 each name specified. A replacement set of possible configura‐
1470 tion file names may be given using the CONFIGS option. The
1471 search procedure is specified below. Once found, the configura‐
1472 tion file is read and processed by CMake. Since the file is
1473 provided by the package it already knows the location of package
1474 contents. The full path to the configuration file is stored in
1475 the cmake variable <package>_CONFIG.
1476 All configuration files which have been considered by CMake
1479 while searching for an installation of the package with an
1480 appropriate version are stored in the cmake variable <pack‐
1481 age>_CONSIDERED_CONFIGS, the associated versions in <pack‐
1482 age>_CONSIDERED_VERSIONS.
1483 If the package configuration file cannot be found CMake will
1486 generate an error describing the problem unless the QUIET argu‐
1487 ment is specified. If REQUIRED is specified and the package is
1488 not found a fatal error is generated and the configure step
1489 stops executing. If <package>_DIR has been set to a directory
1490 not containing a configuration file CMake will ignore it and
1491 search from scratch.
1492 When the [version] argument is given Config mode will only find
1495 a version of the package that claims compatibility with the
1496 requested version (format is major[.minor[.patch[.tweak]]]). If
1497 the EXACT option is given only a version of the package claiming
1498 an exact match of the requested version may be found. CMake
1499 does not establish any convention for the meaning of version
1500 numbers. Package version numbers are checked by "version" files
1501 provided by the packages themselves. For a candidate package
1502 configuration file "<config-file>.cmake" the corresponding ver‐
1503 sion file is located next to it and named either "<con‐
1504 fig-file>-version.cmake" or "<config-file>Version.cmake". If no
1505 such version file is available then the configuration file is
1506 assumed to not be compatible with any requested version. When a
1507 version file is found it is loaded to check the requested ver‐
1508 sion number. The version file is loaded in a nested scope in
1509 which the following variables have been defined:
1510 PACKAGE_FIND_NAME = the <package> name
1513 PACKAGE_FIND_VERSION = full requested version string
1514 PACKAGE_FIND_VERSION_MAJOR = major version if requested, else 0
1515 PACKAGE_FIND_VERSION_MINOR = minor version if requested, else 0
1516 PACKAGE_FIND_VERSION_PATCH = patch version if requested, else 0
1517 PACKAGE_FIND_VERSION_TWEAK = tweak version if requested, else 0
1518 PACKAGE_FIND_VERSION_COUNT = number of version components, 0 to 4
1519 The version file checks whether it satisfies the requested ver‐
1521 sion and sets these variables:
1522 PACKAGE_VERSION = full provided version string
1525 PACKAGE_VERSION_EXACT = true if version is exact match
1526 PACKAGE_VERSION_COMPATIBLE = true if version is compatible
1527 PACKAGE_VERSION_UNSUITABLE = true if unsuitable as any version
1528 These variables are checked by the find_package command to
1530 determine whether the configuration file provides an acceptable
1531 version. They are not available after the find_package call
1532 returns. If the version is acceptable the following variables
1533 are set:
1534 <package>_VERSION = full provided version string
1537 <package>_VERSION_MAJOR = major version if provided, else 0
1538 <package>_VERSION_MINOR = minor version if provided, else 0
1539 <package>_VERSION_PATCH = patch version if provided, else 0
1540 <package>_VERSION_TWEAK = tweak version if provided, else 0
1541 <package>_VERSION_COUNT = number of version components, 0 to 4
1542 and the corresponding package configuration file is loaded.
1544 When multiple package configuration files are available whose
1545 version files claim compatibility with the version requested it
1546 is unspecified which one is chosen. No attempt is made to
1547 choose a highest or closest version number.
1548 Config mode provides an elaborate interface and search proce‐
1551 dure. Much of the interface is provided for completeness and
1552 for use internally by find-modules loaded by Module mode. Most
1553 user code should simply call
1554 find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
1557 in order to find a package. Package maintainers providing CMake
1559 package configuration files are encouraged to name and install
1560 them such that the procedure outlined below will find them with‐
1561 out requiring use of additional options.
1562 CMake constructs a set of possible installation prefixes for the
1565 package. Under each prefix several directories are searched for
1566 a configuration file. The tables below show the directories
1567 searched. Each entry is meant for installation trees following
1568 Windows (W), UNIX (U), or Apple (A) conventions.
1569 <prefix>/ (W)
1572 <prefix>/(cmake|CMake)/ (W)
1573 <prefix>/<name>*/ (W)
1574 <prefix>/<name>*/(cmake|CMake)/ (W)
1575 <prefix>/(share|lib)/cmake/<name>*/ (U)
1576 <prefix>/(share|lib)/<name>*/ (U)
1577 <prefix>/(share|lib)/<name>*/(cmake|CMake)/ (U)
1578 On systems supporting OS X Frameworks and Application Bundles
1580 the following directories are searched for frameworks or bundles
1581 containing a configuration file:
1582 <prefix>/<name>.framework/Resources/ (A)
1585 <prefix>/<name>.framework/Resources/CMake/ (A)
1586 <prefix>/<name>.framework/Versions/*/Resources/ (A)
1587 <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
1588 <prefix>/<name>.app/Contents/Resources/ (A)
1589 <prefix>/<name>.app/Contents/Resources/CMake/ (A)
1590 In all cases the <name> is treated as case-insensitive and cor‐
1592 responds to any of the names specified (<package> or names given
1593 by NAMES). If PATH_SUFFIXES is specified the suffixes are
1594 appended to each (W) or (U) directory entry one-by-one.
1595 This set of directories is intended to work in cooperation with
1598 projects that provide configuration files in their installation
1599 trees. Directories above marked with (W) are intended for
1600 installations on Windows where the prefix may point at the top
1601 of an application's installation directory. Those marked with
1602 (U) are intended for installations on UNIX platforms where the
1603 prefix is shared by multiple packages. This is merely a conven‐
1604 tion, so all (W) and (U) directories are still searched on all
1605 platforms. Directories marked with (A) are intended for instal‐
1606 lations on Apple platforms. The cmake variables
1607 CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE determine the
1608 order of preference as specified below.
1609 The set of installation prefixes is constructed using the fol‐
1612 lowing steps. If NO_DEFAULT_PATH is specified all NO_* options
1613 are enabled.
1614 1. Search paths specified in cmake-specific cache variables.
1617 These are intended to be used on the command line with a
1618 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1619 CMAKE_PREFIX_PATH
1622 CMAKE_FRAMEWORK_PATH
1623 CMAKE_APPBUNDLE_PATH
1624 2. Search paths specified in cmake-specific environment vari‐
1626 ables. These are intended to be set in the user's shell config‐
1627 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1628 passed.
1629 <package>_DIR
1632 CMAKE_PREFIX_PATH
1633 CMAKE_FRAMEWORK_PATH
1634 CMAKE_APPBUNDLE_PATH
1635 3. Search paths specified by the HINTS option. These should be
1637 paths computed by system introspection, such as a hint provided
1638 by the location of another item already found. Hard-coded
1639 guesses should be specified with the PATHS option.
1640 4. Search the standard system environment variables. This can be
1643 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed. Path entries
1644 ending in "/bin" or "/sbin" are automatically converted to their
1645 parent directories.
1646 PATH
1649 5. Search project build trees recently configured in a CMake
1651 GUI. This can be skipped if NO_CMAKE_BUILDS_PATH is passed. It
1652 is intended for the case when a user is building multiple depen‐
1653 dent projects one after another.
1654 6. Search paths stored in the CMake user package registry. This
1657 can be skipped if NO_CMAKE_PACKAGE_REGISTRY is passed. Paths
1658 are stored in the registry when CMake configures a project that
1659 invokes export(PACKAGE <name>). See the export(PACKAGE) command
1660 documentation for more details.
1661 7. Search cmake variables defined in the Platform files for the
1664 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1665 passed.
1666 CMAKE_SYSTEM_PREFIX_PATH
1669 CMAKE_SYSTEM_FRAMEWORK_PATH
1670 CMAKE_SYSTEM_APPBUNDLE_PATH
1671 8. Search paths specified by the PATHS option. These are typi‐
1673 cally hard-coded guesses.
1674 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1677 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1678 following:
1679 "FIRST" - Try to find frameworks before standard
1682 libraries or headers. This is the default on Darwin.
1683 "LAST" - Try to find frameworks after standard
1684 libraries or headers.
1685 "ONLY" - Only try to find frameworks.
1686 "NEVER" - Never try to find frameworks.
1687 On Darwin or systems supporting OS X Application Bundles, the
1689 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
1690 of the following:
1691 "FIRST" - Try to find application bundles before standard
1694 programs. This is the default on Darwin.
1695 "LAST" - Try to find application bundles after standard
1696 programs.
1697 "ONLY" - Only try to find application bundles.
1698 "NEVER" - Never try to find application bundles.
1699 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
1701 directories to be prepended to all other search directories.
1702 This effectively "re-roots" the entire search under given loca‐
1703 tions. By default it is empty. It is especially useful when
1704 cross-compiling to point to the root directory of the target
1705 environment and CMake will search there too. By default at first
1706 the directories listed in CMAKE_FIND_ROOT_PATH and then the
1707 non-rooted directories will be searched. The default behavior
1708 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.
1709 This behavior can be manually overridden on a per-call basis. By
1710 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
1711 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
1712 CMAKE_FIND_ROOT_PATH will not be used. If
1713 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1714 tories will be searched.
1715 The default search order is designed to be most-specific to
1718 least-specific for common use cases. Projects may override the
1719 order by simply calling the command multiple times and using the
1720 NO_* options:
1721 find_package(<package> PATHS paths... NO_DEFAULT_PATH)
1724 find_package(<package>)
1725 Once one of the calls succeeds the result variable will be set
1727 and stored in the cache so that no call will search again.
1728 See the cmake_policy() command documentation for discussion of
1731 the NO_POLICY_SCOPE option.
1732 find_path
1735 Find the directory containing a file.
1736 find_path(<VAR> name1 [path1 path2 ...])
1738 This is the short-hand signature for the command that is suffi‐
1740 cient in many cases. It is the same as find_path(<VAR> name1
1741 [PATHS path1 path2 ...])
1742 find_path(
1745 <VAR>
1746 name | NAMES name1 [name2 ...]
1747 [HINTS path1 [path2 ... ENV var]]
1748 [PATHS path1 [path2 ... ENV var]]
1749 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1750 [DOC "cache documentation string"]
1751 [NO_DEFAULT_PATH]
1752 [NO_CMAKE_ENVIRONMENT_PATH]
1753 [NO_CMAKE_PATH]
1754 [NO_SYSTEM_ENVIRONMENT_PATH]
1755 [NO_CMAKE_SYSTEM_PATH]
1756 [CMAKE_FIND_ROOT_PATH_BOTH |
1757 ONLY_CMAKE_FIND_ROOT_PATH |
1758 NO_CMAKE_FIND_ROOT_PATH]
1759 )
1760 This command is used to find a directory containing the named
1762 file. A cache entry named by <VAR> is created to store the
1763 result of this command. If the file in a directory is found the
1764 result is stored in the variable and the search will not be
1765 repeated unless the variable is cleared. If nothing is found,
1766 the result will be <VAR>-NOTFOUND, and the search will be
1767 attempted again the next time find_path is invoked with the same
1768 variable. The name of the file in a directory that is searched
1769 for is specified by the names listed after the NAMES argument.
1770 Additional search locations can be specified after the PATHS
1771 argument. If ENV var is found in the HINTS or PATHS section the
1772 environment variable var will be read and converted from a sys‐
1773 tem environment variable to a cmake style list of paths. For
1774 example ENV PATH would be a way to list the system path vari‐
1775 able. The argument after DOC will be used for the documentation
1776 string in the cache. PATH_SUFFIXES specifies additional subdi‐
1777 rectories to check below each search path.
1778 If NO_DEFAULT_PATH is specified, then no additional paths are
1781 added to the search. If NO_DEFAULT_PATH is not specified, the
1782 search process is as follows:
1783 1. Search paths specified in cmake-specific cache variables.
1786 These are intended to be used on the command line with a
1787 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1788 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1791 CMAKE_INCLUDE_PATH
1792 CMAKE_FRAMEWORK_PATH
1793 2. Search paths specified in cmake-specific environment vari‐
1795 ables. These are intended to be set in the user's shell config‐
1796 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1797 passed.
1798 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1801 CMAKE_INCLUDE_PATH
1802 CMAKE_FRAMEWORK_PATH
1803 3. Search the paths specified by the HINTS option. These should
1805 be paths computed by system introspection, such as a hint pro‐
1806 vided by the location of another item already found. Hard-coded
1807 guesses should be specified with the PATHS option.
1808 4. Search the standard system environment variables. This can be
1811 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1812 PATH
1815 INCLUDE
1816 5. Search cmake variables defined in the Platform files for the
1818 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1819 passed.
1820 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1823 CMAKE_SYSTEM_INCLUDE_PATH
1824 CMAKE_SYSTEM_FRAMEWORK_PATH
1825 6. Search the paths specified by the PATHS option or in the
1827 short-hand version of the command. These are typically
1828 hard-coded guesses.
1829 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1832 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1833 following:
1834 "FIRST" - Try to find frameworks before standard
1837 libraries or headers. This is the default on Darwin.
1838 "LAST" - Try to find frameworks after standard
1839 libraries or headers.
1840 "ONLY" - Only try to find frameworks.
1841 "NEVER" - Never try to find frameworks.
1842 On Darwin or systems supporting OS X Application Bundles, the
1844 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
1845 of the following:
1846 "FIRST" - Try to find application bundles before standard
1849 programs. This is the default on Darwin.
1850 "LAST" - Try to find application bundles after standard
1851 programs.
1852 "ONLY" - Only try to find application bundles.
1853 "NEVER" - Never try to find application bundles.
1854 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
1856 directories to be prepended to all other search directories.
1857 This effectively "re-roots" the entire search under given loca‐
1858 tions. By default it is empty. It is especially useful when
1859 cross-compiling to point to the root directory of the target
1860 environment and CMake will search there too. By default at first
1861 the directories listed in CMAKE_FIND_ROOT_PATH and then the
1862 non-rooted directories will be searched. The default behavior
1863 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
1864 This behavior can be manually overridden on a per-call basis. By
1865 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
1866 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
1867 CMAKE_FIND_ROOT_PATH will not be used. If
1868 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1869 tories will be searched.
1870 The default search order is designed to be most-specific to
1873 least-specific for common use cases. Projects may override the
1874 order by simply calling the command multiple times and using the
1875 NO_* options:
1876 find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1879 find_path(<VAR> NAMES name)
1880 Once one of the calls succeeds the result variable will be set
1882 and stored in the cache so that no call will search again.
1883 When searching for frameworks, if the file is specified as
1886 A/b.h, then the framework search will look for A.framework/Head‐
1887 ers/b.h. If that is found the path will be set to the path to
1888 the framework. CMake will convert this to the correct -F option
1889 to include the file.
1890 find_program
1893 Find an executable program.
1894 find_program(<VAR> name1 [path1 path2 ...])
1896 This is the short-hand signature for the command that is suffi‐
1898 cient in many cases. It is the same as find_program(<VAR> name1
1899 [PATHS path1 path2 ...])
1900 find_program(
1903 <VAR>
1904 name | NAMES name1 [name2 ...]
1905 [HINTS path1 [path2 ... ENV var]]
1906 [PATHS path1 [path2 ... ENV var]]
1907 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1908 [DOC "cache documentation string"]
1909 [NO_DEFAULT_PATH]
1910 [NO_CMAKE_ENVIRONMENT_PATH]
1911 [NO_CMAKE_PATH]
1912 [NO_SYSTEM_ENVIRONMENT_PATH]
1913 [NO_CMAKE_SYSTEM_PATH]
1914 [CMAKE_FIND_ROOT_PATH_BOTH |
1915 ONLY_CMAKE_FIND_ROOT_PATH |
1916 NO_CMAKE_FIND_ROOT_PATH]
1917 )
1918 This command is used to find a program. A cache entry named by
1920 <VAR> is created to store the result of this command. If the
1921 program is found the result is stored in the variable and the
1922 search will not be repeated unless the variable is cleared. If
1923 nothing is found, the result will be <VAR>-NOTFOUND, and the
1924 search will be attempted again the next time find_program is
1925 invoked with the same variable. The name of the program that is
1926 searched for is specified by the names listed after the NAMES
1927 argument. Additional search locations can be specified after
1928 the PATHS argument. If ENV var is found in the HINTS or PATHS
1929 section the environment variable var will be read and converted
1930 from a system environment variable to a cmake style list of
1931 paths. For example ENV PATH would be a way to list the system
1932 path variable. The argument after DOC will be used for the docu‐
1933 mentation string in the cache. PATH_SUFFIXES specifies addi‐
1934 tional subdirectories to check below each search path.
1935 If NO_DEFAULT_PATH is specified, then no additional paths are
1938 added to the search. If NO_DEFAULT_PATH is not specified, the
1939 search process is as follows:
1940 1. Search paths specified in cmake-specific cache variables.
1943 These are intended to be used on the command line with a
1944 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1945 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
1948 CMAKE_PROGRAM_PATH
1949 CMAKE_APPBUNDLE_PATH
1950 2. Search paths specified in cmake-specific environment vari‐
1952 ables. These are intended to be set in the user's shell config‐
1953 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1954 passed.
1955 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
1958 CMAKE_PROGRAM_PATH
1959 CMAKE_APPBUNDLE_PATH
1960 3. Search the paths specified by the HINTS option. These should
1962 be paths computed by system introspection, such as a hint pro‐
1963 vided by the location of another item already found. Hard-coded
1964 guesses should be specified with the PATHS option.
1965 4. Search the standard system environment variables. This can be
1968 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1969 PATH
1972 5. Search cmake variables defined in the Platform files for the
1975 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1976 passed.
1977 <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1980 CMAKE_SYSTEM_PROGRAM_PATH
1981 CMAKE_SYSTEM_APPBUNDLE_PATH
1982 6. Search the paths specified by the PATHS option or in the
1984 short-hand version of the command. These are typically
1985 hard-coded guesses.
1986 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1989 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1990 following:
1991 "FIRST" - Try to find frameworks before standard
1994 libraries or headers. This is the default on Darwin.
1995 "LAST" - Try to find frameworks after standard
1996 libraries or headers.
1997 "ONLY" - Only try to find frameworks.
1998 "NEVER" - Never try to find frameworks.
1999 On Darwin or systems supporting OS X Application Bundles, the
2001 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
2002 of the following:
2003 "FIRST" - Try to find application bundles before standard
2006 programs. This is the default on Darwin.
2007 "LAST" - Try to find application bundles after standard
2008 programs.
2009 "ONLY" - Only try to find application bundles.
2010 "NEVER" - Never try to find application bundles.
2011 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
2013 directories to be prepended to all other search directories.
2014 This effectively "re-roots" the entire search under given loca‐
2015 tions. By default it is empty. It is especially useful when
2016 cross-compiling to point to the root directory of the target
2017 environment and CMake will search there too. By default at first
2018 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2019 non-rooted directories will be searched. The default behavior
2020 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.
2021 This behavior can be manually overridden on a per-call basis. By
2022 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2023 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2024 CMAKE_FIND_ROOT_PATH will not be used. If
2025 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2026 tories will be searched.
2027 The default search order is designed to be most-specific to
2030 least-specific for common use cases. Projects may override the
2031 order by simply calling the command multiple times and using the
2032 NO_* options:
2033 find_program(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2036 find_program(<VAR> NAMES name)
2037 Once one of the calls succeeds the result variable will be set
2039 and stored in the cache so that no call will search again.
2040 fltk_wrap_ui
2043 Create FLTK user interfaces Wrappers.
2044 fltk_wrap_ui(resultingLibraryName source1
2046 source2 ... sourceN )
2047 Produce .h and .cxx files for all the .fl and .fld files listed.
2049 The resulting .h and .cxx files will be added to a variable
2050 named resultingLibraryName_FLTK_UI_SRCS which should be added to
2051 your library.
2052 foreach
2055 Evaluate a group of commands for each value in a list.
2056 foreach(loop_var arg1 arg2 ...)
2058 COMMAND1(ARGS ...)
2059 COMMAND2(ARGS ...)
2060 ...
2061 endforeach(loop_var)
2062 All commands between foreach and the matching endforeach are
2064 recorded without being invoked. Once the endforeach is evalu‐
2065 ated, the recorded list of commands is invoked once for each
2066 argument listed in the original foreach command. Before each
2067 iteration of the loop "${loop_var}" will be set as a variable
2068 with the current value in the list.
2069 foreach(loop_var RANGE total)
2072 foreach(loop_var RANGE start stop [step])
2073 Foreach can also iterate over a generated range of numbers.
2075 There are three types of this iteration:
2076 * When specifying single number, the range will have elements 0
2079 to "total".
2080 * When specifying two numbers, the range will have elements from
2083 the first number to the second number.
2084 * The third optional number is the increment used to iterate
2087 from the first number to the second number.
2088 foreach(loop_var IN [LISTS [list1 [...]]]
2091 [ITEMS [item1 [...]]])
2092 Iterates over a precise list of items. The LISTS option names
2094 list-valued variables to be traversed, including empty elements
2095 (an empty string is a zero-length list). The ITEMS option ends
2096 argument parsing and includes all arguments following it in the
2097 iteration.
2098 function
2101 Start recording a function for later invocation as a command.
2102 function(<name> [arg1 [arg2 [arg3 ...]]])
2104 COMMAND1(ARGS ...)
2105 COMMAND2(ARGS ...)
2106 ...
2107 endfunction(<name>)
2108 Define a function named <name> that takes arguments named arg1
2110 arg2 arg3 (...). Commands listed after function, but before the
2111 matching endfunction, are not invoked until the function is
2112 invoked. When it is invoked, the commands recorded in the func‐
2113 tion are first modified by replacing formal parameters (${arg1})
2114 with the arguments passed, and then invoked as normal commands.
2115 In addition to referencing the formal parameters you can refer‐
2116 ence the variable ARGC which will be set to the number of argu‐
2117 ments passed into the function as well as ARGV0 ARGV1 ARGV2 ...
2118 which will have the actual values of the arguments passed in.
2119 This facilitates creating functions with optional arguments.
2120 Additionally ARGV holds the list of all arguments given to the
2121 function and ARGN holds the list of argument past the last
2122 expected argument.
2123 See the cmake_policy() command documentation for the behavior of
2126 policies inside functions.
2127 get_cmake_property
2130 Get a property of the CMake instance.
2131 get_cmake_property(VAR property)
2133 Get a property from the CMake instance. The value of the prop‐
2135 erty is stored in the variable VAR. If the property is not
2136 found, VAR will be set to "NOTFOUND". Some supported properties
2137 include: VARIABLES, CACHE_VARIABLES, COMMANDS, MACROS, and COM‐
2138 PONENTS.
2139 See also the more general get_property() command.
2142 get_directory_property
2145 Get a property of DIRECTORY scope.
2146 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
2148 Store a property of directory scope in the named variable. If
2150 the property is not defined the empty-string is returned. The
2151 DIRECTORY argument specifies another directory from which to
2152 retrieve the property value. The specified directory must have
2153 already been traversed by CMake.
2154 get_directory_property(<variable> [DIRECTORY <dir>]
2157 DEFINITION <var-name>)
2158 Get a variable definition from a directory. This form is useful
2160 to get a variable definition from another directory.
2161 See also the more general get_property() command.
2164 get_filename_component
2167 Get a specific component of a full filename.
2168 get_filename_component(<VAR> FileName
2170 PATH|ABSOLUTE|NAME|EXT|NAME_WE|REALPATH
2171 [CACHE])
2172 Set <VAR> to be the path (PATH), file name (NAME), file exten‐
2174 sion (EXT), file name without extension (NAME_WE) of FileName,
2175 the full path (ABSOLUTE), or the full path with all symlinks
2176 resolved (REALPATH). Note that the path is converted to Unix
2177 slashes format and has no trailing slashes. The longest file
2178 extension is always considered. If the optional CACHE argument
2179 is specified, the result variable is added to the cache.
2180 get_filename_component(<VAR> FileName
2183 PROGRAM [PROGRAM_ARGS <ARG_VAR>]
2184 [CACHE])
2185 The program in FileName will be found in the system search path
2187 or left as a full path. If PROGRAM_ARGS is present with PRO‐
2188 GRAM, then any command-line arguments present in the FileName
2189 string are split from the program name and stored in <ARG_VAR>.
2190 This is used to separate a program name from its arguments in a
2191 command line string.
2192 get_property
2195 Get a property.
2196 get_property(<variable>
2198 <GLOBAL |
2199 DIRECTORY [dir] |
2200 TARGET <target> |
2201 SOURCE <source> |
2202 TEST <test> |
2203 CACHE <entry> |
2204 VARIABLE>
2205 PROPERTY <name>
2206 [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
2207 Get one property from one object in a scope. The first argument
2209 specifies the variable in which to store the result. The second
2210 argument determines the scope from which to get the property.
2211 It must be one of the following:
2212 GLOBAL scope is unique and does not accept a name.
2215 DIRECTORY scope defaults to the current directory but another
2218 directory (already processed by CMake) may be named by full or
2219 relative path.
2220 TARGET scope must name one existing target.
2223 SOURCE scope must name one source file.
2226 TEST scope must name one existing test.
2229 CACHE scope must name one cache entry.
2232 VARIABLE scope is unique and does not accept a name.
2235 The required PROPERTY option is immediately followed by the name
2238 of the property to get. If the property is not set an empty
2239 value is returned. If the SET option is given the variable is
2240 set to a boolean value indicating whether the property has been
2241 set. If the DEFINED option is given the variable is set to a
2242 boolean value indicating whether the property has been defined
2243 such as with define_property. If BRIEF_DOCS or FULL_DOCS is
2244 given then the variable is set to a string containing documenta‐
2245 tion for the requested property. If documentation is requested
2246 for a property that has not been defined NOTFOUND is returned.
2247 get_source_file_property
2250 Get a property for a source file.
2251 get_source_file_property(VAR file property)
2253 Get a property from a source file. The value of the property is
2255 stored in the variable VAR. If the property is not found, VAR
2256 will be set to "NOTFOUND". Use set_source_files_properties to
2257 set property values. Source file properties usually control how
2258 the file is built. One property that is always there is LOCATION
2259 See also the more general get_property() command.
2262 get_target_property
2265 Get a property from a target.
2266 get_target_property(VAR target property)
2268 Get a property from a target. The value of the property is
2270 stored in the variable VAR. If the property is not found, VAR
2271 will be set to "NOTFOUND". Use set_target_properties to set
2272 property values. Properties are usually used to control how a
2273 target is built, but some query the target instead. This com‐
2274 mand can get properties for any target so far created. The tar‐
2275 gets do not need to be in the current CMakeLists.txt file.
2276 See also the more general get_property() command.
2279 get_test_property
2282 Get a property of the test.
2283 get_test_property(test property VAR)
2285 Get a property from the Test. The value of the property is
2287 stored in the variable VAR. If the property is not found, VAR
2288 will be set to "NOTFOUND". For a list of standard properties you
2289 can type cmake --help-property-list
2290 See also the more general get_property() command.
2293 if Conditionally execute a group of commands.
2296 if(expression)
2298 # then section.
2299 COMMAND1(ARGS ...)
2300 COMMAND2(ARGS ...)
2301 ...
2302 elseif(expression2)
2303 # elseif section.
2304 COMMAND1(ARGS ...)
2305 COMMAND2(ARGS ...)
2306 ...
2307 else(expression)
2308 # else section.
2309 COMMAND1(ARGS ...)
2310 COMMAND2(ARGS ...)
2311 ...
2312 endif(expression)
2313 Evaluates the given expression. If the result is true, the com‐
2315 mands in the THEN section are invoked. Otherwise, the commands
2316 in the else section are invoked. The elseif and else sections
2317 are optional. You may have multiple elseif clauses. Note that
2318 the expression in the else and endif clause is optional. Long
2319 expressions can be used and there is a traditional order of
2320 precedence. Parenthetical expressions are evaluated first fol‐
2321 lowed by unary operators such as EXISTS, COMMAND, and DEFINED.
2322 Then any EQUAL, LESS, GREATER, STRLESS, STRGREATER, STREQUAL,
2323 MATCHES will be evaluated. Then NOT operators and finally AND,
2324 OR operators will be evaluated. Possible expressions are:
2325 if(<constant>)
2328 True if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
2330 ber. False if the constant is 0, OFF, NO, FALSE, N, IGNORE, "",
2331 or ends in the suffix '-NOTFOUND'. Named boolean constants are
2332 case-insensitive. If the argument is not one of these con‐
2333 stants, it is treated as a variable:
2334 if(<variable>)
2337 True if the variable is defined to a value that is not a false
2339 constant. False otherwise.
2340 if(NOT <expression>)
2343 True if the expression is not true.
2345 if(<expr1> AND <expr2>)
2348 True if both expressions would be considered true individually.
2350 if(<expr1> OR <expr2>)
2353 True if either expression would be considered true individually.
2355 if(COMMAND command-name)
2358 True if the given name is a command, macro or function that can
2360 be invoked.
2361 if(POLICY policy-id)
2364 True if the given name is an existing policy (of the form
2366 CMP<NNNN>).
2367 if(TARGET target-name)
2370 True if the given name is an existing target, built or imported.
2372 if(EXISTS file-name)
2375 if(EXISTS directory-name)
2376 True if the named file or directory exists. Behavior is
2378 well-defined only for full paths.
2379 if(file1 IS_NEWER_THAN file2)
2382 True if file1 is newer than file2 or if one of the two files
2384 doesn't exist. Behavior is well-defined only for full paths.
2385 if(IS_DIRECTORY directory-name)
2388 True if the given name is a directory. Behavior is well-defined
2390 only for full paths.
2391 if(IS_SYMLINK file-name)
2394 True if the given name is a symbolic link. Behavior is
2396 well-defined only for full paths.
2397 if(IS_ABSOLUTE path)
2400 True if the given path is an absolute path.
2402 if(<variable|string> MATCHES regex)
2405 True if the given string or variable's value matches the given
2407 regular expression.
2408 if(<variable|string> LESS <variable|string>)
2411 if(<variable|string> GREATER <variable|string>)
2412 if(<variable|string> EQUAL <variable|string>)
2413 True if the given string or variable's value is a valid number
2415 and the inequality or equality is true.
2416 if(<variable|string> STRLESS <variable|string>)
2419 if(<variable|string> STRGREATER <variable|string>)
2420 if(<variable|string> STREQUAL <variable|string>)
2421 True if the given string or variable's value is lexicographi‐
2423 cally less (or greater, or equal) than the string or variable on
2424 the right.
2425 if(<variable|string> VERSION_LESS <variable|string>)
2428 if(<variable|string> VERSION_EQUAL <variable|string>)
2429 if(<variable|string> VERSION_GREATER <variable|string>)
2430 Component-wise integer version number comparison (version format
2432 is major[.minor[.patch[.tweak]]]).
2433 if(DEFINED <variable>)
2436 True if the given variable is defined. It does not matter if the
2438 variable is true or false just if it has been set.
2439 if((expression) AND (expression OR (expression)))
2442 The expressions inside the parenthesis are evaluated first and
2444 then the remaining expression is evaluated as in the previous
2445 examples. Where there are nested parenthesis the innermost are
2446 evaluated as part of evaluating the expression that contains
2447 them.
2448 The if command was written very early in CMake's history, pre‐
2451 dating the ${} variable evaluation syntax, and for convenience
2452 evaluates variables named by its arguments as shown in the above
2453 signatures. Note that normal variable evaluation with ${}
2454 applies before the if command even receives the arguments.
2455 Therefore code like
2456 set(var1 OFF)
2459 set(var2 "var1")
2460 if(${var2})
2461 appears to the if command as
2463 if(var1)
2466 and is evaluated according to the if(<variable>) case documented
2468 above. The result is OFF which is false. However, if we remove
2469 the ${} from the example then the command sees
2470 if(var2)
2473 which is true because var2 is defined to "var1" which is not a
2475 false constant.
2476 Automatic evaluation applies in the other cases whenever the
2479 above-documented signature accepts <variable|string>:
2480 1) The left hand argument to MATCHES is first checked to see if
2483 it is a defined variable, if so the variable's value is used,
2484 otherwise the original value is used.
2485 2) If the left hand argument to MATCHES is missing it returns
2488 false without error
2489 3) Both left and right hand arguments to LESS GREATER EQUAL are
2492 independently tested to see if they are defined variables, if so
2493 their defined values are used otherwise the original value is
2494 used.
2495 4) Both left and right hand arguments to STRLESS STREQUAL STR‐
2498 GREATER are independently tested to see if they are defined
2499 variables, if so their defined values are used otherwise the
2500 original value is used.
2501 5) Both left and right hand argumemnts to VERSION_LESS VER‐
2504 SION_EQUAL VERSION_GREATER are independently tested to see if
2505 they are defined variables, if so their defined values are used
2506 otherwise the original value is used.
2507 6) The right hand argument to NOT is tested to see if it is a
2510 boolean constant, if so the value is used, otherwise it is
2511 assumed to be a variable and it is dereferenced.
2512 7) The left and right hand arguments to AND OR are independently
2515 tested to see if they are boolean constants, if so they are used
2516 as such, otherwise they are assumed to be variables and are
2517 dereferenced.
2518 include
2522 Read CMake listfile code from the given file.
2523 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
2525 [NO_POLICY_SCOPE])
2526 Reads CMake listfile code from the given file. Commands in the
2528 file are processed immediately as if they were written in place
2529 of the include command. If OPTIONAL is present, then no error
2530 is raised if the file does not exist. If RESULT_VARIABLE is
2531 given the variable will be set to the full filename which has
2532 been included or NOTFOUND if it failed.
2533 If a module is specified instead of a file, the file with name
2536 <modulename>.cmake is searched first in CMAKE_MODULE_PATH, then
2537 in the CMake module directory. There is one exception to this:
2538 if the file which calls include() is located itself in the CMake
2539 module directory, then first the CMake module directory is
2540 searched and CMAKE_MODULE_PATH afterwards. See also policy
2541 CMP0017.
2542 See the cmake_policy() command documentation for discussion of
2545 the NO_POLICY_SCOPE option.
2546 include_directories
2549 Add include directories to the build.
2550 include_directories([AFTER|BEFORE] [SYSTEM] dir1 dir2 ...)
2552 Add the given directories to those searched by the compiler for
2554 include files. By default the directories are appended onto the
2555 current list of directories. This default behavior can be
2556 changed by setting CMAKE_include_directories_BEFORE to ON. By
2557 using BEFORE or AFTER you can select between appending and
2558 prepending, independent from the default. If the SYSTEM option
2559 is given the compiler will be told that the directories are
2560 meant as system include directories on some platforms.
2561 include_external_msproject
2564 Include an external Microsoft project file in a workspace.
2565 include_external_msproject(projectname location
2567 dep1 dep2 ...)
2568 Includes an external Microsoft project in the generated
2570 workspace file. Currently does nothing on UNIX. This will cre‐
2571 ate a target named [projectname]. This can be used in the
2572 add_dependencies command to make things depend on the external
2573 project.
2574 include_regular_expression
2577 Set the regular expression used for dependency checking.
2578 include_regular_expression(regex_match [regex_complain])
2580 Set the regular expressions used in dependency checking. Only
2582 files matching regex_match will be traced as dependencies. Only
2583 files matching regex_complain will generate warnings if they
2584 cannot be found (standard header paths are not searched). The
2585 defaults are:
2586 regex_match = "^.*$" (match everything)
2589 regex_complain = "^$" (match empty string only)
2590 install
2593 Specify rules to run at install time.
2594 This command generates installation rules for a project. Rules
2596 specified by calls to this command within a source directory are
2597 executed in order during installation. The order across direc‐
2598 tories is not defined.
2599 There are multiple signatures for this command. Some of them
2602 define installation properties for files and targets. Proper‐
2603 ties common to multiple signatures are covered here but they are
2604 valid only for signatures that specify them.
2605 DESTINATION arguments specify the directory on disk to which a
2608 file will be installed. If a full path (with a leading slash or
2609 drive letter) is given it is used directly. If a relative path
2610 is given it is interpreted relative to the value of
2611 CMAKE_INSTALL_PREFIX.
2612 PERMISSIONS arguments specify permissions for installed files.
2615 Valid permissions are OWNER_READ, OWNER_WRITE, OWNER_EXECUTE,
2616 GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE,
2617 WORLD_EXECUTE, SETUID, and SETGID. Permissions that do not make
2618 sense on certain platforms are ignored on those platforms.
2619 The CONFIGURATIONS argument specifies a list of build configura‐
2622 tions for which the install rule applies (Debug, Release, etc.).
2623 The COMPONENT argument specifies an installation component name
2626 with which the install rule is associated, such as "runtime" or
2627 "development". During component-specific installation only
2628 install rules associated with the given component name will be
2629 executed. During a full installation all components are
2630 installed.
2631 The RENAME argument specifies a name for an installed file that
2634 may be different from the original file. Renaming is allowed
2635 only when a single file is installed by the command.
2636 The OPTIONAL argument specifies that it is not an error if the
2639 file to be installed does not exist.
2640 The TARGETS signature:
2643 install(TARGETS targets... [EXPORT <export-name>]
2646 [[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE|
2647 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
2648 [DESTINATION <dir>]
2649 [PERMISSIONS permissions...]
2650 [CONFIGURATIONS [Debug|Release|...]]
2651 [COMPONENT <component>]
2652 [OPTIONAL] [NAMELINK_ONLY|NAMELINK_SKIP]
2653 ] [...])
2654 The TARGETS form specifies rules for installing targets from a
2656 project. There are five kinds of target files that may be
2657 installed: ARCHIVE, LIBRARY, RUNTIME, FRAMEWORK, and BUNDLE.
2658 Executables are treated as RUNTIME targets, except that those
2659 marked with the MACOSX_BUNDLE property are treated as BUNDLE
2660 targets on OS X. Static libraries are always treated as ARCHIVE
2661 targets. Module libraries are always treated as LIBRARY targets.
2662 For non-DLL platforms shared libraries are treated as LIBRARY
2663 targets, except that those marked with the FRAMEWORK property
2664 are treated as FRAMEWORK targets on OS X. For DLL platforms the
2665 DLL part of a shared library is treated as a RUNTIME target and
2666 the corresponding import library is treated as an ARCHIVE tar‐
2667 get. All Windows-based systems including Cygwin are DLL plat‐
2668 forms. The ARCHIVE, LIBRARY, RUNTIME, and FRAMEWORK arguments
2669 change the type of target to which the subsequent properties
2670 apply. If none is given the installation properties apply to
2671 all target types. If only one is given then only targets of
2672 that type will be installed (which can be used to install just a
2673 DLL or just an import library).
2674 The PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE arguments cause
2677 subsequent properties to be applied to installing a FRAMEWORK
2678 shared library target's associated files on non-Apple platforms.
2679 Rules defined by these arguments are ignored on Apple platforms
2680 because the associated files are installed into the appropriate
2681 locations inside the framework folder. See documentation of the
2682 PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE target properties
2683 for details.
2684 Either NAMELINK_ONLY or NAMELINK_SKIP may be specified as a
2687 LIBRARY option. On some platforms a versioned shared library
2688 has a symbolic link such as
2689 lib<name>.so -> lib<name>.so.1
2692 where "lib<name>.so.1" is the soname of the library and
2694 "lib<name>.so" is a "namelink" allowing linkers to find the
2695 library when given "-l<name>". The NAMELINK_ONLY option causes
2696 installation of only the namelink when a library target is
2697 installed. The NAMELINK_SKIP option causes installation of
2698 library files other than the namelink when a library target is
2699 installed. When neither option is given both portions are
2700 installed. On platforms where versioned shared libraries do not
2701 have namelinks or when a library is not versioned the
2702 NAMELINK_SKIP option installs the library and the NAMELINK_ONLY
2703 option installs nothing. See the VERSION and SOVERSION target
2704 properties for details on creating versioned shared libraries.
2705 One or more groups of properties may be specified in a single
2708 call to the TARGETS form of this command. A target may be
2709 installed more than once to different locations. Consider hypo‐
2710 thetical targets "myExe", "mySharedLib", and "myStaticLib". The
2711 code
2712 install(TARGETS myExe mySharedLib myStaticLib
2715 RUNTIME DESTINATION bin
2716 LIBRARY DESTINATION lib
2717 ARCHIVE DESTINATION lib/static)
2718 install(TARGETS mySharedLib DESTINATION /some/full/path)
2719 will install myExe to <prefix>/bin and myStaticLib to <pre‐
2721 fix>/lib/static. On non-DLL platforms mySharedLib will be
2722 installed to <prefix>/lib and /some/full/path. On DLL platforms
2723 the mySharedLib DLL will be installed to <prefix>/bin and
2724 /some/full/path and its import library will be installed to
2725 <prefix>/lib/static and /some/full/path. On non-DLL platforms
2726 mySharedLib will be installed to <prefix>/lib and
2727 /some/full/path.
2728 The EXPORT option associates the installed target files with an
2731 export called <export-name>. It must appear before any RUNTIME,
2732 LIBRARY, or ARCHIVE options. To actually install the export
2733 file itself, call install(EXPORT). See documentation of the
2734 install(EXPORT ...) signature below for details.
2735 Installing a target with EXCLUDE_FROM_ALL set to true has unde‐
2738 fined behavior.
2739 The FILES signature:
2742 install(FILES files... DESTINATION <dir>
2745 [PERMISSIONS permissions...]
2746 [CONFIGURATIONS [Debug|Release|...]]
2747 [COMPONENT <component>]
2748 [RENAME <name>] [OPTIONAL])
2749 The FILES form specifies rules for installing files for a
2751 project. File names given as relative paths are interpreted
2752 with respect to the current source directory. Files installed
2753 by this form are by default given permissions OWNER_WRITE,
2754 OWNER_READ, GROUP_READ, and WORLD_READ if no PERMISSIONS argu‐
2755 ment is given.
2756 The PROGRAMS signature:
2759 install(PROGRAMS files... DESTINATION <dir>
2762 [PERMISSIONS permissions...]
2763 [CONFIGURATIONS [Debug|Release|...]]
2764 [COMPONENT <component>]
2765 [RENAME <name>] [OPTIONAL])
2766 The PROGRAMS form is identical to the FILES form except that the
2768 default permissions for the installed file also include
2769 OWNER_EXECUTE, GROUP_EXECUTE, and WORLD_EXECUTE. This form is
2770 intended to install programs that are not targets, such as shell
2771 scripts. Use the TARGETS form to install targets built within
2772 the project.
2773 The DIRECTORY signature:
2776 install(DIRECTORY dirs... DESTINATION <dir>
2779 [FILE_PERMISSIONS permissions...]
2780 [DIRECTORY_PERMISSIONS permissions...]
2781 [USE_SOURCE_PERMISSIONS] [OPTIONAL]
2782 [CONFIGURATIONS [Debug|Release|...]]
2783 [COMPONENT <component>] [FILES_MATCHING]
2784 [[PATTERN <pattern> | REGEX <regex>]
2785 [EXCLUDE] [PERMISSIONS permissions...]] [...])
2786 The DIRECTORY form installs contents of one or more directories
2788 to a given destination. The directory structure is copied ver‐
2789 batim to the destination. The last component of each directory
2790 name is appended to the destination directory but a trailing
2791 slash may be used to avoid this because it leaves the last com‐
2792 ponent empty. Directory names given as relative paths are
2793 interpreted with respect to the current source directory. If no
2794 input directory names are given the destination directory will
2795 be created but nothing will be installed into it. The FILE_PER‐
2796 MISSIONS and DIRECTORY_PERMISSIONS options specify permissions
2797 given to files and directories in the destination. If
2798 USE_SOURCE_PERMISSIONS is specified and FILE_PERMISSIONS is not,
2799 file permissions will be copied from the source directory struc‐
2800 ture. If no permissions are specified files will be given the
2801 default permissions specified in the FILES form of the command,
2802 and the directories will be given the default permissions speci‐
2803 fied in the PROGRAMS form of the command.
2804 Installation of directories may be controlled with fine granu‐
2807 larity using the PATTERN or REGEX options. These "match"
2808 options specify a globbing pattern or regular expression to
2809 match directories or files encountered within input directories.
2810 They may be used to apply certain options (see below) to a sub‐
2811 set of the files and directories encountered. The full path to
2812 each input file or directory (with forward slashes) is matched
2813 against the expression. A PATTERN will match only complete file
2814 names: the portion of the full path matching the pattern must
2815 occur at the end of the file name and be preceded by a slash. A
2816 REGEX will match any portion of the full path but it may use '/'
2817 and '$' to simulate the PATTERN behavior. By default all files
2818 and directories are installed whether or not they are matched.
2819 The FILES_MATCHING option may be given before the first match
2820 option to disable installation of files (but not directories)
2821 not matched by any expression. For example, the code
2822 install(DIRECTORY src/ DESTINATION include/myproj
2825 FILES_MATCHING PATTERN "*.h")
2826 will extract and install header files from a source tree.
2828 Some options may follow a PATTERN or REGEX expression and are
2831 applied only to files or directories matching them. The EXCLUDE
2832 option will skip the matched file or directory. The PERMISSIONS
2833 option overrides the permissions setting for the matched file or
2834 directory. For example the code
2835 install(DIRECTORY icons scripts/ DESTINATION share/myproj
2838 PATTERN "CVS" EXCLUDE
2839 PATTERN "scripts/*"
2840 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
2841 GROUP_EXECUTE GROUP_READ)
2842 will install the icons directory to share/myproj/icons and the
2844 scripts directory to share/myproj. The icons will get default
2845 file permissions, the scripts will be given specific permis‐
2846 sions, and any CVS directories will be excluded.
2847 The SCRIPT and CODE signature:
2850 install([[SCRIPT <file>] [CODE <code>]] [...])
2853 The SCRIPT form will invoke the given CMake script files during
2855 installation. If the script file name is a relative path it
2856 will be interpreted with respect to the current source direc‐
2857 tory. The CODE form will invoke the given CMake code during
2858 installation. Code is specified as a single argument inside a
2859 double-quoted string. For example, the code
2860 install(CODE "MESSAGE(\"Sample install message.\")")
2863 will print a message during installation.
2865 The EXPORT signature:
2868 install(EXPORT <export-name> DESTINATION <dir>
2871 [NAMESPACE <namespace>] [FILE <name>.cmake]
2872 [PERMISSIONS permissions...]
2873 [CONFIGURATIONS [Debug|Release|...]]
2874 [COMPONENT <component>])
2875 The EXPORT form generates and installs a CMake file containing
2877 code to import targets from the installation tree into another
2878 project. Target installations are associated with the export
2879 <export-name> using the EXPORT option of the install(TARGETS
2880 ...) signature documented above. The NAMESPACE option will
2881 prepend <namespace> to the target names as they are written to
2882 the import file. By default the generated file will be called
2883 <export-name>.cmake but the FILE option may be used to specify a
2884 different name. The value given to the FILE option must be a
2885 file name with the ".cmake" extension. If a CONFIGURATIONS
2886 option is given then the file will only be installed when one of
2887 the named configurations is installed. Additionally, the gener‐
2888 ated import file will reference only the matching target config‐
2889 urations. If a COMPONENT option is specified that does not
2890 match that given to the targets associated with <export-name>
2891 the behavior is undefined. If a library target is included in
2892 the export but a target to which it links is not included the
2893 behavior is unspecified.
2894 The EXPORT form is useful to help outside projects use targets
2897 built and installed by the current project. For example, the
2898 code
2899 install(TARGETS myexe EXPORT myproj DESTINATION bin)
2902 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
2903 will install the executable myexe to <prefix>/bin and code to
2905 import it in the file "<prefix>/lib/myproj/myproj.cmake". An
2906 outside project may load this file with the include command and
2907 reference the myexe executable from the installation tree using
2908 the imported target name mp_myexe as if the target were built in
2909 its own tree.
2910 NOTE: This command supercedes the INSTALL_TARGETS command and
2913 the target properties PRE_INSTALL_SCRIPT and
2914 POST_INSTALL_SCRIPT. It also replaces the FILES forms of the
2915 INSTALL_FILES and INSTALL_PROGRAMS commands. The processing
2916 order of these install rules relative to those generated by
2917 INSTALL_TARGETS, INSTALL_FILES, and INSTALL_PROGRAMS commands is
2918 not defined.
2919 link_directories
2923 Specify directories in which the linker will look for libraries.
2924 link_directories(directory1 directory2 ...)
2926 Specify the paths in which the linker should search for
2928 libraries. The command will apply only to targets created after
2929 it is called. For historical reasons, relative paths given to
2930 this command are passed to the linker unchanged (unlike many
2931 CMake commands which interpret them relative to the current
2932 source directory).
2933 list List operations.
2936 list(LENGTH <list> <output variable>)
2938 list(GET <list> <element index> [<element index> ...]
2939 <output variable>)
2940 list(APPEND <list> <element> [<element> ...])
2941 list(FIND <list> <value> <output variable>)
2942 list(INSERT <list> <element_index> <element> [<element> ...])
2943 list(REMOVE_ITEM <list> <value> [<value> ...])
2944 list(REMOVE_AT <list> <index> [<index> ...])
2945 list(REMOVE_DUPLICATES <list>)
2946 list(REVERSE <list>)
2947 list(SORT <list>)
2948 LENGTH will return a given list's length.
2950 GET will return list of elements specified by indices from the
2953 list.
2954 APPEND will append elements to the list.
2957 FIND will return the index of the element specified in the list
2960 or -1 if it wasn't found.
2961 INSERT will insert elements to the list to the specified loca‐
2964 tion.
2965 REMOVE_AT and REMOVE_ITEM will remove items from the list. The
2968 difference is that REMOVE_ITEM will remove the given items,
2969 while REMOVE_AT will remove the items at the given indices.
2970 REMOVE_DUPLICATES will remove duplicated items in the list.
2973 REVERSE reverses the contents of the list in-place.
2976 SORT sorts the list in-place alphabetically.
2979 NOTES: A list in cmake is a ; separated group of strings. To
2982 create a list the set command can be used. For example, set(var
2983 a b c d e) creates a list with a;b;c;d;e, and set(var "a b c d
2984 e") creates a string or a list with one item in it.
2985 When specifying index values, if <element index> is 0 or
2988 greater, it is indexed from the beginning of the list, with 0
2989 representing the first list element. If <element index> is -1 or
2990 lesser, it is indexed from the end of the list, with -1 repre‐
2991 senting the last list element. Be careful when counting with
2992 negative indices: they do not start from 0. -0 is equivalent to
2993 0, the first list element.
2994 load_cache
2998 Load in the values from another project's CMake cache.
2999 load_cache(pathToCacheFile READ_WITH_PREFIX
3001 prefix entry1...)
3002 Read the cache and store the requested entries in variables with
3004 their name prefixed with the given prefix. This only reads the
3005 values, and does not create entries in the local project's
3006 cache.
3007 load_cache(pathToCacheFile [EXCLUDE entry1...]
3010 [INCLUDE_INTERNALS entry1...])
3011 Load in the values from another cache and store them in the
3013 local project's cache as internal entries. This is useful for a
3014 project that depends on another project built in a different
3015 tree. EXCLUDE option can be used to provide a list of entries
3016 to be excluded. INCLUDE_INTERNALS can be used to provide a list
3017 of internal entries to be included. Normally, no internal
3018 entries are brought in. Use of this form of the command is
3019 strongly discouraged, but it is provided for backward compati‐
3020 bility.
3021 load_command
3024 Load a command into a running CMake.
3025 load_command(COMMAND_NAME <loc1> [loc2 ...])
3027 The given locations are searched for a library whose name is
3029 cmCOMMAND_NAME. If found, it is loaded as a module and the com‐
3030 mand is added to the set of available CMake commands. Usually,
3031 TRY_COMPILE is used before this command to compile the module.
3032 If the command is successfully loaded a variable named
3033 CMAKE_LOADED_COMMAND_<COMMAND_NAME>
3036 will be set to the full path of the module that was loaded.
3038 Otherwise the variable will not be set.
3039 macro Start recording a macro for later invocation as a command.
3042 macro(<name> [arg1 [arg2 [arg3 ...]]])
3044 COMMAND1(ARGS ...)
3045 COMMAND2(ARGS ...)
3046 ...
3047 endmacro(<name>)
3048 Define a macro named <name> that takes arguments named arg1 arg2
3050 arg3 (...). Commands listed after macro, but before the match‐
3051 ing endmacro, are not invoked until the macro is invoked. When
3052 it is invoked, the commands recorded in the macro are first mod‐
3053 ified by replacing formal parameters (${arg1}) with the argu‐
3054 ments passed, and then invoked as normal commands. In addition
3055 to referencing the formal parameters you can reference the val‐
3056 ues ${ARGC} which will be set to the number of arguments passed
3057 into the function as well as ${ARGV0} ${ARGV1} ${ARGV2} ...
3058 which will have the actual values of the arguments passed in.
3059 This facilitates creating macros with optional arguments. Addi‐
3060 tionally ${ARGV} holds the list of all arguments given to the
3061 macro and ${ARGN} holds the list of argument past the last
3062 expected argument. Note that the parameters to a macro and val‐
3063 ues such as ARGN are not variables in the usual CMake sense.
3064 They are string replacements much like the c preprocessor would
3065 do with a macro. If you want true CMake variables you should
3066 look at the function command.
3067 See the cmake_policy() command documentation for the behavior of
3070 policies inside macros.
3071 mark_as_advanced
3074 Mark cmake cached variables as advanced.
3075 mark_as_advanced([CLEAR|FORCE] VAR VAR2 VAR...)
3077 Mark the named cached variables as advanced. An advanced vari‐
3079 able will not be displayed in any of the cmake GUIs unless the
3080 show advanced option is on. If CLEAR is the first argument
3081 advanced variables are changed back to unadvanced. If FORCE is
3082 the first argument, then the variable is made advanced. If nei‐
3083 ther FORCE nor CLEAR is specified, new values will be marked as
3084 advanced, but if the variable already has an
3085 advanced/non-advanced state, it will not be changed.
3086 It does nothing in script mode.
3089 math Mathematical expressions.
3092 math(EXPR <output variable> <math expression>)
3094 EXPR evaluates mathematical expression and return result in the
3096 output variable. Example mathematical expression is '5 * ( 10 +
3097 13 )'. Supported operators are + - * / % | & ^ ~ << >> * / %.
3098 They have the same meaning as they do in c code.
3099 message
3102 Display a message to the user.
3103 message([STATUS|WARNING|AUTHOR_WARNING|FATAL_ERROR|SEND_ERROR]
3105 "message to display" ...)
3106 The optional keyword determines the type of message:
3108 (none) = Important information
3111 STATUS = Incidental information
3112 WARNING = CMake Warning, continue processing
3113 AUTHOR_WARNING = CMake Warning (dev), continue processing
3114 SEND_ERROR = CMake Error, continue but skip generation
3115 FATAL_ERROR = CMake Error, stop all processing
3116 The CMake command-line tool displays STATUS messages on stdout
3118 and all other message types on stderr. The CMake GUI displays
3119 all messages in its log area. The interactive dialogs (ccmake
3120 and CMakeSetup) show STATUS messages one at a time on a status
3121 line and other messages in interactive pop-up boxes.
3122 CMake Warning and Error message text displays using a simple
3125 markup language. Non-indented text is formatted in line-wrapped
3126 paragraphs delimited by newlines. Indented text is considered
3127 pre-formatted.
3128 option Provides an option that the user can optionally select.
3131 option(<option_variable> "help string describing option"
3133 [initial value])
3134 Provide an option for the user to select as ON or OFF. If no
3136 initial value is provided, OFF is used.
3137 If you have options that depend on the values of other options,
3140 see the module help for CMakeDependentOption.
3141 output_required_files
3144 Output a list of required source files for a specified source
3145 file.
3146 output_required_files(srcfile outputfile)
3148 Outputs a list of all the source files that are required by the
3150 specified srcfile. This list is written into outputfile. This is
3151 similar to writing out the dependencies for srcfile except that
3152 it jumps from .h files into .cxx, .c and .cpp files if possible.
3153 project
3156 Set a name for the entire project.
3157 project(<projectname> [languageName1 languageName2 ... ] )
3159 Sets the name of the project. Additionally this sets the vari‐
3161 ables <projectName>_BINARY_DIR and <projectName>_SOURCE_DIR to
3162 the respective values.
3163 Optionally you can specify which languages your project sup‐
3166 ports. Example languages are CXX (i.e. C++), C, Fortran, etc.
3167 By default C and CXX are enabled. E.g. if you do not have a C++
3168 compiler, you can disable the check for it by explicitly listing
3169 the languages you want to support, e.g. C. By using the special
3170 language "NONE" all checks for any language can be disabled.
3171 qt_wrap_cpp
3174 Create Qt Wrappers.
3175 qt_wrap_cpp(resultingLibraryName DestName
3177 SourceLists ...)
3178 Produce moc files for all the .h files listed in the
3180 SourceLists. The moc files will be added to the library using
3181 the DestName source list.
3182 qt_wrap_ui
3185 Create Qt user interfaces Wrappers.
3186 qt_wrap_ui(resultingLibraryName HeadersDestName
3188 SourcesDestName SourceLists ...)
3189 Produce .h and .cxx files for all the .ui files listed in the
3191 SourceLists. The .h files will be added to the library using
3192 the HeadersDestNamesource list. The .cxx files will be added to
3193 the library using the SourcesDestNamesource list.
3194 remove_definitions
3197 Removes -D define flags added by add_definitions.
3198 remove_definitions(-DFOO -DBAR ...)
3200 Removes flags (added by add_definitions) from the compiler com‐
3202 mand line for sources in the current directory and below.
3203 return Return from a file, directory or function.
3206 return()
3208 Returns from a file, directory or function. When this command is
3210 encountered in an included file (via include() or find_pack‐
3211 age()), it causes processing of the current file to stop and
3212 control is returned to the including file. If it is encountered
3213 in a file which is not included by another file, e.g. a CMake‐
3214 Lists.txt, control is returned to the parent directory if there
3215 is one. If return is called in a function, control is returned
3216 to the caller of the function. Note that a macro is not a func‐
3217 tion and does not handle return like a function does.
3218 separate_arguments
3221 Parse space-separated arguments into a semicolon-separated list.
3222 separate_arguments(<var> <UNIX|WINDOWS>_COMMAND "<args>")
3224 Parses a unix- or windows-style command-line string "<args>" and
3226 stores a semicolon-separated list of the arguments in <var>.
3227 The entire command line must be given in one "<args>" argument.
3228 The UNIX_COMMAND mode separates arguments by unquoted white‐
3231 space. It recognizes both single-quote and double-quote pairs.
3232 A backslash escapes the next literal character (\" is "); there
3233 are no special escapes (\n is just n).
3234 The WINDOWS_COMMAND mode parses a windows command-line using the
3237 same syntax the runtime library uses to construct argv at
3238 startup. It separates arguments by whitespace that is not dou‐
3239 ble-quoted. Backslashes are literal unless they precede dou‐
3240 ble-quotes. See the MSDN article "Parsing C Command-Line Argu‐
3241 ments" for details.
3242 separate_arguments(VARIABLE)
3245 Convert the value of VARIABLE to a semi-colon separated list.
3247 All spaces are replaced with ';'. This helps with generating
3248 command lines.
3249 set Set a CMAKE variable to a given value.
3252 set(<variable> <value>
3254 [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])
3255 Within CMake sets <variable> to the value <value>. <value> is
3257 expanded before <variable> is set to it. If CACHE is present,
3258 then the <variable> is put in the cache. <type> and <docstring>
3259 are then required. <type> is used by the CMake GUI to choose a
3260 widget with which the user sets a value. The value for <type>
3261 may be one of
3262 FILEPATH = File chooser dialog.
3265 PATH = Directory chooser dialog.
3266 STRING = Arbitrary string.
3267 BOOL = Boolean ON/OFF checkbox.
3268 INTERNAL = No GUI entry (used for persistent variables).
3269 If <type> is INTERNAL, then the <value> is always written into
3271 the cache, replacing any values existing in the cache. If it is
3272 not a cache variable, then this always writes into the current
3273 makefile. The FORCE option will overwrite the cache value remov‐
3274 ing any changes by the user.
3275 If PARENT_SCOPE is present, the variable will be set in the
3278 scope above the current scope. Each new directory or function
3279 creates a new scope. This command will set the value of a vari‐
3280 able into the parent directory or calling function (whichever is
3281 applicable to the case at hand).
3282 If <value> is not specified then the variable is removed instead
3285 of set. See also: the unset() command.
3286 set(<variable> <value1> ... <valueN>)
3289 In this case <variable> is set to a semicolon separated list of
3291 values.
3292 <variable> can be an environment variable such as:
3295 set( ENV{PATH} /home/martink )
3298 in which case the environment variable will be set.
3300 set_directory_properties
3303 Set a property of the directory.
3304 set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
3306 Set a property for the current directory and subdirectories. If
3308 the property is not found, CMake will report an error. The prop‐
3309 erties include: INCLUDE_DIRECTORIES, LINK_DIRECTORIES,
3310 INCLUDE_REGULAR_EXPRESSION, and ADDITIONAL_MAKE_CLEAN_FILES.
3311 ADDITIONAL_MAKE_CLEAN_FILES is a list of files that will be
3312 cleaned as a part of "make clean" stage.
3313 set_property
3316 Set a named property in a given scope.
3317 set_property(<GLOBAL |
3319 DIRECTORY [dir] |
3320 TARGET [target1 [target2 ...]] |
3321 SOURCE [src1 [src2 ...]] |
3322 TEST [test1 [test2 ...]] |
3323 CACHE [entry1 [entry2 ...]]>
3324 [APPEND]
3325 PROPERTY <name> [value1 [value2 ...]])
3326 Set one property on zero or more objects of a scope. The first
3328 argument determines the scope in which the property is set. It
3329 must be one of the following:
3330 GLOBAL scope is unique and does not accept a name.
3333 DIRECTORY scope defaults to the current directory but another
3336 directory (already processed by CMake) may be named by full or
3337 relative path.
3338 TARGET scope may name zero or more existing targets.
3341 SOURCE scope may name zero or more source files. Note that
3344 source file properties are visible only to targets added in the
3345 same directory (CMakeLists.txt).
3346 TEST scope may name zero or more existing tests.
3349 CACHE scope must name zero or more cache existing entries.
3352 The required PROPERTY option is immediately followed by the name
3355 of the property to set. Remaining arguments are used to compose
3356 the property value in the form of a semicolon-separated list.
3357 If the APPEND option is given the list is appended to any exist‐
3358 ing property value.
3359 set_source_files_properties
3362 Source files can have properties that affect how they are built.
3363 set_source_files_properties([file1 [file2 [...]]]
3365 PROPERTIES prop1 value1
3366 [prop2 value2 [...]])
3367 Set properties associated with source files using a key/value
3369 paired list. See properties documentation for those known to
3370 CMake. Unrecognized properties are ignored. Source file prop‐
3371 erties are visible only to targets added in the same directory
3372 (CMakeLists.txt).
3373 set_target_properties
3376 Targets can have properties that affect how they are built.
3377 set_target_properties(target1 target2 ...
3379 PROPERTIES prop1 value1
3380 prop2 value2 ...)
3381 Set properties on a target. The syntax for the command is to
3383 list all the files you want to change, and then provide the val‐
3384 ues you want to set next. You can use any prop value pair you
3385 want and extract it later with the GET_TARGET_PROPERTY command.
3386 Properties that affect the name of a target's output file are as
3389 follows. The PREFIX and SUFFIX properties override the default
3390 target name prefix (such as "lib") and suffix (such as ".so").
3391 IMPORT_PREFIX and IMPORT_SUFFIX are the equivalent properties
3392 for the import library corresponding to a DLL (for SHARED
3393 library targets). OUTPUT_NAME sets the real name of a target
3394 when it is built and can be used to help create two targets of
3395 the same name even though CMake requires unique logical target
3396 names. There is also a <CONFIG>_OUTPUT_NAME that can set the
3397 output name on a per-configuration basis. <CONFIG>_POSTFIX sets
3398 a postfix for the real name of the target when it is built under
3399 the configuration named by <CONFIG> (in upper-case, such as
3400 "DEBUG_POSTFIX"). The value of this property is initialized
3401 when the target is created to the value of the variable
3402 CMAKE_<CONFIG>_POSTFIX (except for executable targets because
3403 earlier CMake versions which did not use this variable for exe‐
3404 cutables).
3405 The LINK_FLAGS property can be used to add extra flags to the
3408 link step of a target. LINK_FLAGS_<CONFIG> will add to the con‐
3409 figuration <CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL,
3410 RELWITHDEBINFO. DEFINE_SYMBOL sets the name of the preprocessor
3411 symbol defined when compiling sources in a shared library. If
3412 not set here then it is set to target_EXPORTS by default (with
3413 some substitutions if the target is not a valid C identifier).
3414 This is useful for headers to know whether they are being
3415 included from inside their library our outside to properly setup
3416 dllexport/dllimport decorations. The COMPILE_FLAGS property sets
3417 additional compiler flags used to build sources within the tar‐
3418 get. It may also be used to pass additional preprocessor defi‐
3419 nitions.
3420 The LINKER_LANGUAGE property is used to change the tool used to
3423 link an executable or shared library. The default is set the
3424 language to match the files in the library. CXX and C are common
3425 values for this property.
3426 For shared libraries VERSION and SOVERSION can be used to spec‐
3429 ify the build version and api version respectively. When build‐
3430 ing or installing appropriate symlinks are created if the plat‐
3431 form supports symlinks and the linker supports so-names. If only
3432 one of both is specified the missing is assumed to have the same
3433 version number. For executables VERSION can be used to specify
3434 the build version. When building or installing appropriate sym‐
3435 links are created if the platform supports symlinks. For shared
3436 libraries and executables on Windows the VERSION attribute is
3437 parsed to extract a "major.minor" version number. These numbers
3438 are used as the image version of the binary.
3439 There are a few properties used to specify RPATH rules.
3442 INSTALL_RPATH is a semicolon-separated list specifying the rpath
3443 to use in installed targets (for platforms that support it).
3444 INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to true
3445 will append directories in the linker search path and outside
3446 the project to the INSTALL_RPATH. SKIP_BUILD_RPATH is a boolean
3447 specifying whether to skip automatic generation of an rpath
3448 allowing the target to run from the build tree.
3449 BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link
3450 the target in the build tree with the INSTALL_RPATH. This takes
3451 precedence over SKIP_BUILD_RPATH and avoids the need for relink‐
3452 ing before installation. INSTALL_NAME_DIR is a string specify‐
3453 ing the directory portion of the "install_name" field of shared
3454 libraries on Mac OSX to use in the installed targets. When the
3455 target is created the values of the variables
3456 CMAKE_INSTALL_RPATH, CMAKE_INSTALL_RPATH_USE_LINK_PATH,
3457 CMAKE_SKIP_BUILD_RPATH, CMAKE_BUILD_WITH_INSTALL_RPATH, and
3458 CMAKE_INSTALL_NAME_DIR are used to initialize these properties.
3459 PROJECT_LABEL can be used to change the name of the target in an
3462 IDE like visual studio. VS_KEYWORD can be set to change the
3463 visual studio keyword, for example QT integration works better
3464 if this is set to Qt4VSv1.0.
3465 VS_SCC_PROJECTNAME, VS_SCC_LOCALPATH, VS_SCC_PROVIDER can be set
3468 to add support for source control bindings in a Visual Studio
3469 project file.
3470 The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are
3473 the old way to specify CMake scripts to run before and after
3474 installing a target. They are used only when the old
3475 INSTALL_TARGETS command is used to install the target. Use the
3476 INSTALL command instead.
3477 The EXCLUDE_FROM_DEFAULT_BUILD property is used by the visual
3480 studio generators. If it is set to 1 the target will not be
3481 part of the default build when you select "Build Solution".
3482 set_tests_properties
3485 Set a property of the tests.
3486 set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
3488 Set a property for the tests. If the property is not found,
3490 CMake will report an error. The properties include:
3491 WILL_FAIL: If set to true, this will invert the pass/fail flag
3494 of the test.
3495 PASS_REGULAR_EXPRESSION: If set, the test output will be checked
3498 against the specified regular expressions and at least one of
3499 the regular expressions has to match, otherwise the test will
3500 fail.
3501 Example: PASS_REGULAR_EXPRESSION "TestPassed;All ok"
3504 FAIL_REGULAR_EXPRESSION: If set, if the output will match to one
3506 of specified regular expressions, the test will fail.
3507 Example: PASS_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed"
3510 Both PASS_REGULAR_EXPRESSION and FAIL_REGULAR_EXPRESSION expect
3512 a list of regular expressions.
3513 TIMEOUT: Setting this will limit the test runtime to the number
3516 of seconds specified.
3517 site_name
3521 Set the given variable to the name of the computer.
3522 site_name(variable)
3524 source_group
3527 Define a grouping for sources in the makefile.
3528 source_group(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])
3530 Defines a group into which sources will be placed in project
3532 files. This is mainly used to setup file tabs in Visual Studio.
3533 Any file whose name is listed or matches the regular expression
3534 will be placed in this group. If a file matches multiple
3535 groups, the LAST group that explicitly lists the file will be
3536 favored, if any. If no group explicitly lists the file, the
3537 LAST group whose regular expression matches the file will be
3538 favored.
3539 The name of the group may contain backslashes to specify sub‐
3542 groups:
3543 source_group(outer\\inner ...)
3546 For backwards compatibility, this command is also supports the
3548 format:
3549 source_group(name regex)
3552 string String operations.
3555 string(REGEX MATCH <regular_expression>
3557 <output variable> <input> [<input>...])
3558 string(REGEX MATCHALL <regular_expression>
3559 <output variable> <input> [<input>...])
3560 string(REGEX REPLACE <regular_expression>
3561 <replace_expression> <output variable>
3562 <input> [<input>...])
3563 string(REPLACE <match_string>
3564 <replace_string> <output variable>
3565 <input> [<input>...])
3566 string(COMPARE EQUAL <string1> <string2> <output variable>)
3567 string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
3568 string(COMPARE LESS <string1> <string2> <output variable>)
3569 string(COMPARE GREATER <string1> <string2> <output variable>)
3570 string(ASCII <number> [<number> ...] <output variable>)
3571 string(CONFIGURE <string1> <output variable>
3572 [@ONLY] [ESCAPE_QUOTES])
3573 string(TOUPPER <string1> <output variable>)
3574 string(TOLOWER <string1> <output variable>)
3575 string(LENGTH <string> <output variable>)
3576 string(SUBSTRING <string> <begin> <length> <output variable>)
3577 string(STRIP <string> <output variable>)
3578 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
3579 [RANDOM_SEED <seed>] <output variable>)
3580 REGEX MATCH will match the regular expression once and store the
3582 match in the output variable.
3583 REGEX MATCHALL will match the regular expression as many times
3586 as possible and store the matches in the output variable as a
3587 list.
3588 REGEX REPLACE will match the regular expression as many times as
3591 possible and substitute the replacement expression for the match
3592 in the output. The replace expression may refer to paren-delim‐
3593 ited subexpressions of the match using \1, \2, ..., \9. Note
3594 that two backslashes (\\1) are required in CMake code to get a
3595 backslash through argument parsing.
3596 REPLACE will replace all occurrences of match_string in the
3599 input with replace_string and store the result in the output.
3600 COMPARE EQUAL/NOTEQUAL/LESS/GREATER will compare the strings and
3603 store true or false in the output variable.
3604 ASCII will convert all numbers into corresponding ASCII charac‐
3607 ters.
3608 CONFIGURE will transform a string like CONFIGURE_FILE transforms
3611 a file.
3612 TOUPPER/TOLOWER will convert string to upper/lower characters.
3615 LENGTH will return a given string's length.
3618 SUBSTRING will return a substring of a given string.
3621 STRIP will return a substring of a given string with leading and
3624 trailing spaces removed.
3625 RANDOM will return a random string of given length consisting of
3628 characters from the given alphabet. Default length is 5 charac‐
3629 ters and default alphabet is all numbers and upper and lower
3630 case letters. If an integer RANDOM_SEED is given, its value
3631 will be used to seed the random number generator.
3632 The following characters have special meaning in regular expres‐
3635 sions:
3636 ^ Matches at beginning of a line
3639 $ Matches at end of a line
3640 . Matches any single character
3641 [ ] Matches any character(s) inside the brackets
3642 [^ ] Matches any character(s) not inside the brackets
3643 - Matches any character in range on either side of a dash
3644 * Matches preceding pattern zero or more times
3645 + Matches preceding pattern one or more times
3646 ? Matches preceding pattern zero or once only
3647 | Matches a pattern on either side of the |
3648 () Saves a matched subexpression, which can be referenced
3649 in the REGEX REPLACE operation. Additionally it is saved
3650 by all regular expression-related commands, including
3651 e.g. if( MATCHES ), in the variables CMAKE_MATCH_(0..9).
3652 target_link_libraries
3655 Link a target to given libraries.
3656 target_link_libraries(<target> [item1 [item2 [...]]]
3658 [[debug|optimized|general] <item>] ...)
3659 Specify libraries or flags to use when linking a given target.
3661 The named <target> must have been created in the current direc‐
3662 tory by a command such as add_executable or add_library. The
3663 remaining arguments specify library names or flags.
3664 If a library name matches that of another target in the project
3667 a dependency will automatically be added in the build system to
3668 make sure the library being linked is up-to-date before the tar‐
3669 get links. Item names starting with '-', but not '-l' or
3670 '-framework', are treated as linker flags.
3671 A "debug", "optimized", or "general" keyword indicates that the
3674 library immediately following it is to be used only for the cor‐
3675 responding build configuration. The "debug" keyword corresponds
3676 to the Debug configuration (or to configurations named in the
3677 DEBUG_CONFIGURATIONS global property if it is set). The "opti‐
3678 mized" keyword corresponds to all other configurations. The
3679 "general" keyword corresponds to all configurations, and is
3680 purely optional (assumed if omitted). Higher granularity may be
3681 achieved for per-configuration rules by creating and linking to
3682 IMPORTED library targets. See the IMPORTED mode of the
3683 add_library command for more information.
3684 Library dependencies are transitive by default. When this tar‐
3687 get is linked into another target then the libraries linked to
3688 this target will appear on the link line for the other target
3689 too. See the LINK_INTERFACE_LIBRARIES target property to over‐
3690 ride the set of transitive link dependencies for a target.
3691 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES
3694 [[debug|optimized|general] <lib>] ...)
3695 The LINK_INTERFACE_LIBRARIES mode appends the libraries to the
3697 LINK_INTERFACE_LIBRARIES and its per-configuration equivalent
3698 target properties instead of using them for linking. Libraries
3699 specified as "debug" are appended to the the LINK_INTER‐
3700 FACE_LIBRARIES_DEBUG property (or to the properties correspond‐
3701 ing to configurations listed in the DEBUG_CONFIGURATIONS global
3702 property if it is set). Libraries specified as "optimized" are
3703 appended to the the LINK_INTERFACE_LIBRARIES property.
3704 Libraries specified as "general" (or without any keyword) are
3705 treated as if specified for both "debug" and "optimized".
3706 The library dependency graph is normally acyclic (a DAG), but in
3709 the case of mutually-dependent STATIC libraries CMake allows the
3710 graph to contain cycles (strongly connected components). When
3711 another target links to one of the libraries CMake repeats the
3712 entire connected component. For example, the code
3713 add_library(A STATIC a.c)
3716 add_library(B STATIC b.c)
3717 target_link_libraries(A B)
3718 target_link_libraries(B A)
3719 add_executable(main main.c)
3720 target_link_libraries(main A)
3721 links 'main' to 'A B A B'. (While one repetition is usually
3723 sufficient, pathological object file and symbol arrangements can
3724 require more. One may handle such cases by manually repeating
3725 the component in the last target_link_libraries call. However,
3726 if two archives are really so interdependent they should proba‐
3727 bly be combined into a single archive.)
3728 try_compile
3731 Try building some code.
3732 try_compile(RESULT_VAR <bindir> <srcdir>
3734 <projectName> [targetName] [CMAKE_FLAGS flags...]
3735 [OUTPUT_VARIABLE <var>])
3736 Try building a project. In this form, srcdir should contain a
3738 complete CMake project with a CMakeLists.txt file and all
3739 sources. The bindir and srcdir will not be deleted after this
3740 command is run. Specify targetName to build a specific target
3741 instead of the 'all' or 'ALL_BUILD' target.
3742 try_compile(RESULT_VAR <bindir> <srcfile>
3745 [CMAKE_FLAGS flags...]
3746 [COMPILE_DEFINITIONS flags...]
3747 [OUTPUT_VARIABLE <var>]
3748 [COPY_FILE <fileName>])
3749 Try building a source file into an executable. In this form the
3751 user need only supply a source file that defines a 'main'.
3752 CMake will create a CMakeLists.txt file to build the source as
3753 an executable. Specify COPY_FILE to get a copy of the linked
3754 executable at the given fileName.
3755 In this version all files in bindir/CMakeFiles/CMakeTmp, will be
3758 cleaned automatically, for debugging a --debug-trycompile can be
3759 passed to cmake to avoid the clean. Some extra flags that can
3760 be included are, INCLUDE_DIRECTORIES, LINK_DIRECTORIES, and
3761 LINK_LIBRARIES. COMPILE_DEFINITIONS are -Ddefinition that will
3762 be passed to the compile line. try_compile creates a CMake‐
3763 List.txt file on the fly that looks like this:
3764 add_definitions( <expanded COMPILE_DEFINITIONS from calling cmake>)
3767 include_directories(${INCLUDE_DIRECTORIES})
3768 link_directories(${LINK_DIRECTORIES})
3769 add_executable(cmTryCompileExec sources)
3770 target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
3771 In both versions of the command, if OUTPUT_VARIABLE is speci‐
3773 fied, then the output from the build process is stored in the
3774 given variable. Return the success or failure in RESULT_VAR.
3775 CMAKE_FLAGS can be used to pass -DVAR:TYPE=VALUE flags to the
3776 cmake that is run during the build. Set variable CMAKE_TRY_COM‐
3777 PILE_CONFIGURATION to choose a build configuration.
3778 try_run
3781 Try compiling and then running some code.
3782 try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR
3784 bindir srcfile [CMAKE_FLAGS <Flags>]
3785 [COMPILE_DEFINITIONS <flags>]
3786 [COMPILE_OUTPUT_VARIABLE comp]
3787 [RUN_OUTPUT_VARIABLE run]
3788 [OUTPUT_VARIABLE var]
3789 [ARGS <arg1> <arg2>...])
3790 Try compiling a srcfile. Return TRUE or FALSE for success or
3792 failure in COMPILE_RESULT_VAR. Then if the compile succeeded,
3793 run the executable and return its exit code in RUN_RESULT_VAR.
3794 If the executable was built, but failed to run, then
3795 RUN_RESULT_VAR will be set to FAILED_TO_RUN. COMPILE_OUT‐
3796 PUT_VARIABLE specifies the variable where the output from the
3797 compile step goes. RUN_OUTPUT_VARIABLE specifies the variable
3798 where the output from the running executable goes.
3799 For compatibility reasons OUTPUT_VARIABLE is still supported,
3802 which gives you the output from the compile and run step com‐
3803 bined.
3804 Cross compiling issues
3807 When cross compiling, the executable compiled in the first step
3810 usually cannot be run on the build host. try_run() checks the
3811 CMAKE_CROSSCOMPILING variable to detect whether CMake is in
3812 crosscompiling mode. If that's the case, it will still try to
3813 compile the executable, but it will not try to run the exe‐
3814 cutable. Instead it will create cache variables which must be
3815 filled by the user or by presetting them in some CMake script
3816 file to the values the executable would have produced if it
3817 would have been run on its actual target platform. These vari‐
3818 ables are RUN_RESULT_VAR (explanation see above) and if RUN_OUT‐
3819 PUT_VARIABLE (or OUTPUT_VARIABLE) was used, an additional cache
3820 variable RUN_RESULT_VAR__COMPILE_RESULT_VAR__TRYRUN_OUTPUT.This
3821 is intended to hold stdout and stderr from the executable.
3822 In order to make cross compiling your project easier, use
3825 try_run only if really required. If you use try_run, use
3826 RUN_OUTPUT_VARIABLE (or OUTPUT_VARIABLE) only if really
3827 required. Using them will require that when crosscompiling, the
3828 cache variables will have to be set manually to the output of
3829 the executable. You can also "guard" the calls to try_run with
3830 if(CMAKE_CROSSCOMPILING) and provide an easy-to-preset alterna‐
3831 tive for this case.
3832 Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build
3835 configuration.
3836 unset Unset a variable, cache variable, or environment variable.
3839 unset(<variable> [CACHE])
3841 Removes the specified variable causing it to become undefined.
3843 If CACHE is present then the variable is removed from the cache
3844 instead of the current scope.
3845 <variable> can be an environment variable such as:
3848 unset(ENV{LD_LIBRARY_PATH})
3851 in which case the variable will be removed from the current
3853 environment.
3854 variable_watch
3857 Watch the CMake variable for change.
3858 variable_watch(<variable name> [<command to execute>])
3860 If the specified variable changes, the message will be printed
3862 about the variable being changed. If the command is specified,
3863 the command will be executed. The command will receive the fol‐
3864 lowing arguments: COMMAND(<variable> <access> <value> <current
3865 list file> <stack>)
3866 while Evaluate a group of commands while a condition is true
3869 while(condition)
3871 COMMAND1(ARGS ...)
3872 COMMAND2(ARGS ...)
3873 ...
3874 endwhile(condition)
3875 All commands between while and the matching endwhile are
3877 recorded without being invoked. Once the endwhile is evaluated,
3878 the recorded list of commands is invoked as long as the condi‐
3879 tion is true. The condition is evaluated using the same logic as
3880 the if command.
3881
3884 Copyright 2000-2009 Kitware, Inc., Insight Software Consortium. All
3885 rights reserved.
3886 Redistribution and use in source and binary forms, with or without mod‐
3889 ification, are permitted provided that the following conditions are
3890 met:
3891 Redistributions of source code must retain the above copyright notice,
3894 this list of conditions and the following disclaimer.
3895 Redistributions in binary form must reproduce the above copyright
3898 notice, this list of conditions and the following disclaimer in the
3899 documentation and/or other materials provided with the distribution.
3900 Neither the names of Kitware, Inc., the Insight Software Consortium,
3903 nor the names of their contributors may be used to endorse or promote
3904 products derived from this software without specific prior written per‐
3905 mission.
3906 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
3909 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
3910 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
3911 ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
3912 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
3913 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
3914 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
3915 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
3916 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
3917 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
3918 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
3919
3922 The following resources are available to get help using CMake:
3923 Home Page
3926 http://www.cmake.org
3927 The primary starting point for learning about CMake.
3929 Frequently Asked Questions
3932 http://www.cmake.org/Wiki/CMake_FAQ
3933 A Wiki is provided containing answers to frequently asked ques‐
3935 tions.
3936 Online Documentation
3939 http://www.cmake.org/HTML/Documentation.html
3940 Links to available documentation may be found on this web page.
3942 Mailing List
3945 http://www.cmake.org/HTML/MailingLists.html
3946 For help and discussion about using cmake, a mailing list is
3948 provided at cmake@cmake.org. The list is member-post-only but
3949 one may sign up on the CMake web page. Please first read the
3950 full documentation at http://www.cmake.org before posting ques‐
3951 tions to the list.
3952 Summary of helpful links:
3955 Home: http://www.cmake.org
3958 Docs: http://www.cmake.org/HTML/Documentation.html
3959 Mail: http://www.cmake.org/HTML/MailingLists.html
3960 FAQ: http://www.cmake.org/Wiki/CMake_FAQ
3961cmake 2.8.4 March 31, 2011 cmakecommands(1)