1ccmake(1) General Commands Manual ccmake(1)
2
6 ccmake - Curses Interface for CMake.
7
10 ccmake <path-to-source>
11 ccmake <path-to-existing-build>
12
15 The "ccmake" executable is the CMake curses interface. Project config‐
16 uration settings may be specified interactively through this GUI.
17 Brief instructions are provided at the bottom of the terminal when the
18 program is running.
19 CMake is a cross-platform build system generator. Projects specify
22 their build process with platform-independent CMake listfiles included
23 in each directory of a source tree with the name CMakeLists.txt. Users
24 build a project by using CMake to generate a build system for a native
25 tool on their platform.
26
29 -C <initial-cache>
30 Pre-load a script to populate the cache.
31 When cmake is first run in an empty build tree, it creates a
33 CMakeCache.txt file and populates it with customizable settings
34 for the project. This option may be used to specify a file from
35 which to load cache entries before the first pass through the
36 project's cmake listfiles. The loaded entries take priority
37 over the project's default values. The given file should be a
38 CMake script containing SET commands that use the CACHE option,
39 not a cache-format file.
40 -D <var>:<type>=<value>
43 Create a cmake cache entry.
44 When cmake is first run in an empty build tree, it creates a
46 CMakeCache.txt file and populates it with customizable settings
47 for the project. This option may be used to specify a setting
48 that takes priority over the project's default value. The
49 option may be repeated for as many cache entries as desired.
50 -U <globbing_expr>
53 Remove matching entries from CMake cache.
54 This option may be used to remove one or more variables from the
56 CMakeCache.txt file, globbing expressions using * and ? are sup‐
57 ported. The option may be repeated for as many cache entries as
58 desired.
59 Use with care, you can make your CMakeCache.txt non-working.
62 -G <generator-name>
65 Specify a makefile generator.
66 CMake may support multiple native build systems on certain plat‐
68 forms. A makefile generator is responsible for generating a
69 particular build system. Possible generator names are specified
70 in the Generators section.
71 -Wno-dev
74 Suppress developer warnings.
75 Suppress warnings that are meant for the author of the CMake‐
77 Lists.txt files.
78 -Wdev Enable developer warnings.
81 Enable warnings that are meant for the author of the CMake‐
83 Lists.txt files.
84
87 Unix Makefiles
88 Generates standard UNIX makefiles.
89 A hierarchy of UNIX makefiles is generated into the build tree.
91 Any standard UNIX-style make program can build the project
92 through the default make target. A "make install" target is
93 also provided.
94 CodeBlocks - Unix Makefiles
97 Generates CodeBlocks project files.
98 Project files for CodeBlocks will be created in the top direc‐
100 tory and in every subdirectory which features a CMakeLists.txt
101 file containing a PROJECT() call. Additionally a hierarchy of
102 makefiles is generated into the build tree. The appropriate
103 make program can build the project through the default make tar‐
104 get. A "make install" target is also provided.
105 Eclipse CDT4 - Unix Makefiles
108 Generates Eclipse CDT 4.0 project files.
109 Project files for Eclipse will be created in the top directory.
111 In out of source builds, a linked resource to the top level
112 source directory will be created.Additionally a hierarchy of
113 makefiles is generated into the build tree. The appropriate make
114 program can build the project through the default make target. A
115 "make install" target is also provided.
116 KDevelop3
119 Generates KDevelop 3 project files.
120 Project files for KDevelop 3 will be created in the top direc‐
122 tory and in every subdirectory which features a CMakeLists.txt
123 file containing a PROJECT() call. If you change the settings
124 using KDevelop cmake will try its best to keep your changes when
125 regenerating the project files. Additionally a hierarchy of UNIX
126 makefiles is generated into the build tree. Any standard
127 UNIX-style make program can build the project through the
128 default make target. A "make install" target is also provided.
129 KDevelop3 - Unix Makefiles
132 Generates KDevelop 3 project files.
133 Project files for KDevelop 3 will be created in the top direc‐
135 tory and in every subdirectory which features a CMakeLists.txt
136 file containing a PROJECT() call. If you change the settings
137 using KDevelop cmake will try its best to keep your changes when
138 regenerating the project files. Additionally a hierarchy of UNIX
139 makefiles is generated into the build tree. Any standard
140 UNIX-style make program can build the project through the
141 default make target. A "make install" target is also provided.
142
145 CMake Properties - Properties supported by CMake, the Cross-Platform Makefile Generator.
146 This is the documentation for the properties supported by CMake. Prop‐
149 erties can have different scopes. They can either be assigned to a
150 source file, a directory, a target or globally to CMake. By modifying
151 the values of properties the behaviour of the build system can be cus‐
152 tomized.
153
156 add_custom_command
157 Add a custom build rule to the generated build system.
158 There are two main signatures for add_custom_command The first
160 signature is for adding a custom command to produce an output.
161 add_custom_command(OUTPUT output1 [output2 ...]
164 COMMAND command1 [ARGS] [args1...]
165 [COMMAND command2 [ARGS] [args2...] ...]
166 [MAIN_DEPENDENCY depend]
167 [DEPENDS [depends...]]
168 [IMPLICIT_DEPENDS <lang1> depend1 ...]
169 [WORKING_DIRECTORY dir]
170 [COMMENT comment] [VERBATIM] [APPEND])
171 This defines a command to generate specified OUTPUT file(s). A
173 target created in the same directory (CMakeLists.txt file) that
174 specifies any output of the custom command as a source file is
175 given a rule to generate the file using the command at build
176 time. If an output name is a relative path it will be inter‐
177 preted relative to the build tree directory corresponding to the
178 current source directory. Note that MAIN_DEPENDENCY is com‐
179 pletely optional and is used as a suggestion to visual studio
180 about where to hang the custom command. In makefile terms this
181 creates a new target in the following form:
182 OUTPUT: MAIN_DEPENDENCY DEPENDS
185 COMMAND
186 If more than one command is specified they will be executed in
188 order. The optional ARGS argument is for backward compatibility
189 and will be ignored.
190 The second signature adds a custom command to a target such as a
193 library or executable. This is useful for performing an opera‐
194 tion before or after building the target. The command becomes
195 part of the target and will only execute when the target itself
196 is built. If the target is already built, the command will not
197 execute.
198 add_custom_command(TARGET target
201 PRE_BUILD | PRE_LINK | POST_BUILD
202 COMMAND command1 [ARGS] [args1...]
203 [COMMAND command2 [ARGS] [args2...] ...]
204 [WORKING_DIRECTORY dir]
205 [COMMENT comment] [VERBATIM])
206 This defines a new command that will be associated with building
208 the specified target. When the command will happen is determined
209 by which of the following is specified:
210 PRE_BUILD - run before all other dependencies
213 PRE_LINK - run after other dependencies
214 POST_BUILD - run after the target has been built
215 Note that the PRE_BUILD option is only supported on Visual Stu‐
217 dio 7 or later. For all other generators PRE_BUILD will be
218 treated as PRE_LINK.
219 If WORKING_DIRECTORY is specified the command will be executed
222 in the directory given. If COMMENT is set, the value will be
223 displayed as a message before the commands are executed at build
224 time. If APPEND is specified the COMMAND and DEPENDS option val‐
225 ues are appended to the custom command for the first output
226 specified. There must have already been a previous call to this
227 command with the same output. The COMMENT, WORKING_DIRECTORY,
228 and MAIN_DEPENDENCY options are currently ignored when APPEND is
229 given, but may be used in the future.
230 If VERBATIM is given then all arguments to the commands will be
233 escaped properly for the build tool so that the invoked command
234 receives each argument unchanged. Note that one level of
235 escapes is still used by the CMake language processor before
236 add_custom_command even sees the arguments. Use of VERBATIM is
237 recommended as it enables correct behavior. When VERBATIM is not
238 given the behavior is platform specific because there is no pro‐
239 tection of tool-specific special characters.
240 If the output of the custom command is not actually created as a
243 file on disk it should be marked as SYMBOLIC with
244 SET_SOURCE_FILES_PROPERTIES.
245 The IMPLICIT_DEPENDS option requests scanning of implicit depen‐
248 dencies of an input file. The language given specifies the pro‐
249 gramming language whose corresponding dependency scanner should
250 be used. Currently only C and CXX language scanners are sup‐
251 ported. Dependencies discovered from the scanning are added to
252 those of the custom command at build time. Note that the
253 IMPLICIT_DEPENDS option is currently supported only for Makefile
254 generators and will be ignored by other generators.
255 If COMMAND specifies an executable target (created by ADD_EXE‐
258 CUTABLE) it will automatically be replaced by the location of
259 the executable created at build time. Additionally a tar‐
260 get-level dependency will be added so that the executable target
261 will be built before any target using this custom command. How‐
262 ever this does NOT add a file-level dependency that would cause
263 the custom command to re-run whenever the executable is recom‐
264 piled.
265 Arguments to COMMAND may use "generator expressions" with the
268 syntax "$<...>". Generator expressions are evaluted during
269 build system generation to produce information specific to each
270 build configuration. Valid expressions are:
271 $<CONFIGURATION> = configuration name
274 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
275 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
276 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
277 where "tgt" is the name of a target. Target file expressions
279 produce a full path, but _DIR and _NAME versions can produce the
280 directory and file name components:
281 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
284 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
285 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
286 References to target names in generator expressions imply tar‐
288 get-level dependencies, but NOT file-level dependencies. List
289 target names with the DEPENDS option to add file dependencies.
290 The DEPENDS option specifies files on which the command depends.
293 If any dependency is an OUTPUT of another custom command in the
294 same directory (CMakeLists.txt file) CMake automatically brings
295 the other custom command into the target in which this command
296 is built. If DEPENDS is not specified the command will run
297 whenever the OUTPUT is missing; if the command does not actually
298 create the OUTPUT then the rule will always run. If DEPENDS
299 specifies any target (created by an ADD_* command) a tar‐
300 get-level dependency is created to make sure the target is built
301 before any target using this custom command. Additionally, if
302 the target is an executable or library a file-level dependency
303 is created to cause the custom command to re-run whenever the
304 target is recompiled.
305 add_custom_target
309 Add a target with no output so it will always be built.
310 add_custom_target(Name [ALL] [command1 [args1...]]
312 [COMMAND command2 [args2...] ...]
313 [DEPENDS depend depend depend ... ]
314 [WORKING_DIRECTORY dir]
315 [COMMENT comment] [VERBATIM]
316 [SOURCES src1 [src2...]])
317 Adds a target with the given name that executes the given com‐
319 mands. The target has no output file and is ALWAYS CONSIDERED
320 OUT OF DATE even if the commands try to create a file with the
321 name of the target. Use ADD_CUSTOM_COMMAND to generate a file
322 with dependencies. By default nothing depends on the custom tar‐
323 get. Use ADD_DEPENDENCIES to add dependencies to or from other
324 targets. If the ALL option is specified it indicates that this
325 target should be added to the default build target so that it
326 will be run every time (the command cannot be called ALL). The
327 command and arguments are optional and if not specified an empty
328 target will be created. If WORKING_DIRECTORY is set, then the
329 command will be run in that directory. If COMMENT is set, the
330 value will be displayed as a message before the commands are
331 executed at build time. Dependencies listed with the DEPENDS
332 argument may reference files and outputs of custom commands cre‐
333 ated with add_custom_command() in the same directory (CMake‐
334 Lists.txt file).
335 If VERBATIM is given then all arguments to the commands will be
338 escaped properly for the build tool so that the invoked command
339 receives each argument unchanged. Note that one level of
340 escapes is still used by the CMake language processor before
341 add_custom_target even sees the arguments. Use of VERBATIM is
342 recommended as it enables correct behavior. When VERBATIM is not
343 given the behavior is platform specific because there is no pro‐
344 tection of tool-specific special characters.
345 The SOURCES option specifies additional source files to be
348 included in the custom target. Specified source files will be
349 added to IDE project files for convenience in editing even if
350 they have not build rules.
351 add_definitions
354 Adds -D define flags to the compilation of source files.
355 add_definitions(-DFOO -DBAR ...)
357 Adds flags to the compiler command line for sources in the cur‐
359 rent directory and below. This command can be used to add any
360 flags, but it was originally intended to add preprocessor defi‐
361 nitions. Flags beginning in -D or /D that look like preproces‐
362 sor definitions are automatically added to the COMPILE_DEFINI‐
363 TIONS property for the current directory. Definitions with
364 non-trival values may be left in the set of flags instead of
365 being converted for reasons of backwards compatibility. See
366 documentation of the directory, target, and source file COM‐
367 PILE_DEFINITIONS properties for details on adding preprocessor
368 definitions to specific scopes and configurations.
369 add_dependencies
372 Add a dependency between top-level targets.
373 add_dependencies(target-name depend-target1
375 depend-target2 ...)
376 Make a top-level target depend on other top-level targets. A
378 top-level target is one created by ADD_EXECUTABLE, ADD_LIBRARY,
379 or ADD_CUSTOM_TARGET. Adding dependencies with this command can
380 be used to make sure one target is built before another target.
381 Dependencies added to an IMPORTED target are followed transi‐
382 tively in its place since the target itself does not build. See
383 the DEPENDS option of ADD_CUSTOM_TARGET and ADD_CUSTOM_COMMAND
384 for adding file-level dependencies in custom rules. See the
385 OBJECT_DEPENDS option in SET_SOURCE_FILES_PROPERTIES to add
386 file-level dependencies to object files.
387 add_executable
390 Add an executable to the project using the specified source
391 files.
392 add_executable(<name> [WIN32] [MACOSX_BUNDLE]
394 [EXCLUDE_FROM_ALL]
395 source1 source2 ... sourceN)
396 Adds an executable target called <name> to be built from the
398 source files listed in the command invocation. The <name> cor‐
399 responds to the logical target name and must be globally unique
400 within a project. The actual file name of the executable built
401 is constructed based on conventions of the native platform (such
402 as <name>.exe or just <name>).
403 By default the executable file will be created in the build tree
406 directory corresponding to the source tree directory in which
407 the command was invoked. See documentation of the RUNTIME_OUT‐
408 PUT_DIRECTORY target property to change this location. See doc‐
409 umentation of the OUTPUT_NAME target property to change the
410 <name> part of the final file name.
411 If WIN32 is given the property WIN32_EXECUTABLE will be set on
414 the target created. See documentation of that target property
415 for details.
416 If MACOSX_BUNDLE is given the corresponding property will be set
419 on the created target. See documentation of the MACOSX_BUNDLE
420 target property for details.
421 If EXCLUDE_FROM_ALL is given the corresponding property will be
424 set on the created target. See documentation of the
425 EXCLUDE_FROM_ALL target property for details.
426 The add_executable command can also create IMPORTED executable
429 targets using this signature:
430 add_executable(<name> IMPORTED)
433 An IMPORTED executable target references an executable file
435 located outside the project. No rules are generated to build
436 it. The target name has scope in the directory in which it is
437 created and below. It may be referenced like any target built
438 within the project. IMPORTED executables are useful for conve‐
439 nient reference from commands like add_custom_command. Details
440 about the imported executable are specified by setting proper‐
441 ties whose names begin in "IMPORTED_". The most important such
442 property is IMPORTED_LOCATION (and its per-configuration version
443 IMPORTED_LOCATION_<CONFIG>) which specifies the location of the
444 main executable file on disk. See documentation of the
445 IMPORTED_* properties for more information.
446 add_library
449 Add a library to the project using the specified source files.
450 add_library(<name> [STATIC | SHARED | MODULE]
452 [EXCLUDE_FROM_ALL]
453 source1 source2 ... sourceN)
454 Adds a library target called <name> to be built from the source
456 files listed in the command invocation. The <name> corresponds
457 to the logical target name and must be globally unique within a
458 project. The actual file name of the library built is con‐
459 structed based on conventions of the native platform (such as
460 lib<name>.a or <name>.lib).
461 STATIC, SHARED, or MODULE may be given to specify the type of
464 library to be created. STATIC libraries are archives of object
465 files for use when linking other targets. SHARED libraries are
466 linked dynamically and loaded at runtime. MODULE libraries are
467 plugins that are not linked into other targets but may be loaded
468 dynamically at runtime using dlopen-like functionality. If no
469 type is given explicitly the type is STATIC or SHARED based on
470 whether the current value of the variable BUILD_SHARED_LIBS is
471 true.
472 By default the library file will be created in the build tree
475 directory corresponding to the source tree directory in which
476 the command was invoked. See documentation of the ARCHIVE_OUT‐
477 PUT_DIRECTORY, LIBRARY_OUTPUT_DIRECTORY, and RUNTIME_OUT‐
478 PUT_DIRECTORY target properties to change this location. See
479 documentation of the OUTPUT_NAME target property to change the
480 <name> part of the final file name.
481 If EXCLUDE_FROM_ALL is given the corresponding property will be
484 set on the created target. See documentation of the
485 EXCLUDE_FROM_ALL target property for details.
486 The add_library command can also create IMPORTED library targets
489 using this signature:
490 add_library(<name> <SHARED|STATIC|MODULE|UNKNOWN> IMPORTED)
493 An IMPORTED library target references a library file located
495 outside the project. No rules are generated to build it. The
496 target name has scope in the directory in which it is created
497 and below. It may be referenced like any target built within
498 the project. IMPORTED libraries are useful for convenient ref‐
499 erence from commands like target_link_libraries. Details about
500 the imported library are specified by setting properties whose
501 names begin in "IMPORTED_". The most important such property is
502 IMPORTED_LOCATION (and its per-configuration version
503 IMPORTED_LOCATION_<CONFIG>) which specifies the location of the
504 main library file on disk. See documentation of the IMPORTED_*
505 properties for more information.
506 add_subdirectory
509 Add a subdirectory to the build.
510 add_subdirectory(source_dir [binary_dir]
512 [EXCLUDE_FROM_ALL])
513 Add a subdirectory to the build. The source_dir specifies the
515 directory in which the source CmakeLists.txt and code files are
516 located. If it is a relative path it will be evaluated with
517 respect to the current directory (the typical usage), but it may
518 also be an absolute path. The binary_dir specifies the directory
519 in which to place the output files. If it is a relative path it
520 will be evaluated with respect to the current output directory,
521 but it may also be an absolute path. If binary_dir is not speci‐
522 fied, the value of source_dir, before expanding any relative
523 path, will be used (the typical usage). The CMakeLists.txt file
524 in the specified source directory will be processed immediately
525 by CMake before processing in the current input file continues
526 beyond this command.
527 If the EXCLUDE_FROM_ALL argument is provided then targets in the
530 subdirectory will not be included in the ALL target of the par‐
531 ent directory by default, and will be excluded from IDE project
532 files. Users must explicitly build targets in the subdirectory.
533 This is meant for use when the subdirectory contains a separate
534 part of the project that is useful but not necessary, such as a
535 set of examples. Typically the subdirectory should contain its
536 own project() command invocation so that a full build system
537 will be generated in the subdirectory (such as a VS IDE solution
538 file). Note that inter-target dependencies supercede this
539 exclusion. If a target built by the parent project depends on a
540 target in the subdirectory, the dependee target will be included
541 in the parent project build system to satisfy the dependency.
542 add_test
545 Add a test to the project with the specified arguments.
546 add_test(testname Exename arg1 arg2 ... )
548 If the ENABLE_TESTING command has been run, this command adds a
550 test target to the current directory. If ENABLE_TESTING has not
551 been run, this command does nothing. The tests are run by the
552 testing subsystem by executing Exename with the specified argu‐
553 ments. Exename can be either an executable built by this
554 project or an arbitrary executable on the system (like tclsh).
555 The test will be run with the current working directory set to
556 the CMakeList.txt files corresponding directory in the binary
557 tree.
558 add_test(NAME <name> [CONFIGURATIONS [Debug|Release|...]]
564 [WORKING_DIRECTORY dir]
565 COMMAND <command> [arg1 [arg2 ...]])
566 If COMMAND specifies an executable target (created by add_exe‐
568 cutable) it will automatically be replaced by the location of
569 the executable created at build time. If a CONFIGURATIONS
570 option is given then the test will be executed only when testing
571 under one of the named configurations. If a WORKING_DIRECTORY
572 option is given then the test will be executed in the given
573 directory.
574 Arguments after COMMAND may use "generator expressions" with the
577 syntax "$<...>". Generator expressions are evaluted during
578 build system generation to produce information specific to each
579 build configuration. Valid expressions are:
580 $<CONFIGURATION> = configuration name
583 $<TARGET_FILE:tgt> = main file (.exe, .so.1.2, .a)
584 $<TARGET_LINKER_FILE:tgt> = file used to link (.a, .lib, .so)
585 $<TARGET_SONAME_FILE:tgt> = file with soname (.so.3)
586 where "tgt" is the name of a target. Target file expressions
588 produce a full path, but _DIR and _NAME versions can produce the
589 directory and file name components:
590 $<TARGET_FILE_DIR:tgt>/$<TARGET_FILE_NAME:tgt>
593 $<TARGET_LINKER_FILE_DIR:tgt>/$<TARGET_LINKER_FILE_NAME:tgt>
594 $<TARGET_SONAME_FILE_DIR:tgt>/$<TARGET_SONAME_FILE_NAME:tgt>
595 Example usage:
597 add_test(NAME mytest
600 COMMAND testDriver --config $<CONFIGURATION>
601 --exe $<TARGET_FILE:myexe>)
602 This creates a test "mytest" whose command runs a testDriver
604 tool passing the configuration name and the full path to the
605 executable file produced by target "myexe".
606 aux_source_directory
609 Find all source files in a directory.
610 aux_source_directory(<dir> <variable>)
612 Collects the names of all the source files in the specified
614 directory and stores the list in the <variable> provided. This
615 command is intended to be used by projects that use explicit
616 template instantiation. Template instantiation files can be
617 stored in a "Templates" subdirectory and collected automatically
618 using this command to avoid manually listing all instantiations.
619 It is tempting to use this command to avoid writing the list of
622 source files for a library or executable target. While this
623 seems to work, there is no way for CMake to generate a build
624 system that knows when a new source file has been added. Nor‐
625 mally the generated build system knows when it needs to rerun
626 CMake because the CMakeLists.txt file is modified to add a new
627 source. When the source is just added to the directory without
628 modifying this file, one would have to manually rerun CMake to
629 generate a build system incorporating the new file.
630 break Break from an enclosing foreach or while loop.
633 break()
635 Breaks from an enclosing foreach loop or while loop
637 build_command
640 Get the command line to build this project.
641 build_command(<variable>
643 [CONFIGURATION <config>]
644 [PROJECT_NAME <projname>]
645 [TARGET <target>])
646 Sets the given <variable> to a string containing the command
648 line for building one configuration of a target in a project
649 using the build tool appropriate for the current CMAKE_GENERA‐
650 TOR.
651 If CONFIGURATION is omitted, CMake chooses a reasonable default
654 value for multi-configuration generators. CONFIGURATION is
655 ignored for single-configuration generators.
656 If PROJECT_NAME is omitted, the resulting command line will
659 build the top level PROJECT in the current build tree.
660 If TARGET is omitted, the resulting command line will build
663 everything, effectively using build target 'all' or 'ALL_BUILD'.
664 build_command(<cachevariable> <makecommand>)
667 This second signature is deprecated, but still available for
669 backwards compatibility. Use the first signature instead.
670 Sets the given <cachevariable> to a string containing the com‐
673 mand to build this project from the root of the build tree using
674 the build tool given by <makecommand>. <makecommand> should be
675 the full path to msdev, devenv, nmake, make or one of the end
676 user build tools.
677 cmake_minimum_required
680 Set the minimum required version of cmake for a project.
681 cmake_minimum_required(VERSION major[.minor[.patch[.tweak]]]
683 [FATAL_ERROR])
684 If the current version of CMake is lower than that required it
686 will stop processing the project and report an error. When a
687 version higher than 2.4 is specified the command implicitly
688 invokes
689 cmake_policy(VERSION major[.minor[.patch[.tweak]]])
692 which sets the cmake policy version level to the version speci‐
694 fied. When version 2.4 or lower is given the command implicitly
695 invokes
696 cmake_policy(VERSION 2.4)
699 which enables compatibility features for CMake 2.4 and lower.
701 The FATAL_ERROR option is accepted but ignored by CMake 2.6 and
704 higher. It should be specified so CMake versions 2.4 and lower
705 fail with an error instead of just a warning.
706 cmake_policy
709 Manage CMake Policy settings.
710 As CMake evolves it is sometimes necessary to change existing
712 behavior in order to fix bugs or improve implementations of
713 existing features. The CMake Policy mechanism is designed to
714 help keep existing projects building as new versions of CMake
715 introduce changes in behavior. Each new policy (behavioral
716 change) is given an identifier of the form "CMP<NNNN>" where
717 "<NNNN>" is an integer index. Documentation associated with
718 each policy describes the OLD and NEW behavior and the reason
719 the policy was introduced. Projects may set each policy to
720 select the desired behavior. When CMake needs to know which
721 behavior to use it checks for a setting specified by the
722 project. If no setting is available the OLD behavior is assumed
723 and a warning is produced requesting that the policy be set.
724 The cmake_policy command is used to set policies to OLD or NEW
727 behavior. While setting policies individually is supported, we
728 encourage projects to set policies based on CMake versions.
729 cmake_policy(VERSION major.minor[.patch[.tweak]])
732 Specify that the current CMake list file is written for the
734 given version of CMake. All policies introduced in the speci‐
735 fied version or earlier will be set to use NEW behavior. All
736 policies introduced after the specified version will be unset
737 (unless variable CMAKE_POLICY_DEFAULT_CMP<NNNN> sets a default).
738 This effectively requests behavior preferred as of a given CMake
739 version and tells newer CMake versions to warn about their new
740 policies. The policy version specified must be at least 2.4 or
741 the command will report an error. In order to get compatibility
742 features supporting versions earlier than 2.4 see documentation
743 of policy CMP0001.
744 cmake_policy(SET CMP<NNNN> NEW)
747 cmake_policy(SET CMP<NNNN> OLD)
748 Tell CMake to use the OLD or NEW behavior for a given policy.
750 Projects depending on the old behavior of a given policy may
751 silence a policy warning by setting the policy state to OLD.
752 Alternatively one may fix the project to work with the new
753 behavior and set the policy state to NEW.
754 cmake_policy(GET CMP<NNNN> <variable>)
757 Check whether a given policy is set to OLD or NEW behavior. The
759 output variable value will be "OLD" or "NEW" if the policy is
760 set, and empty otherwise.
761 CMake keeps policy settings on a stack, so changes made by the
764 cmake_policy command affect only the top of the stack. A new
765 entry on the policy stack is managed automatically for each sub‐
766 directory to protect its parents and siblings. CMake also man‐
767 ages a new entry for scripts loaded by include() and find_pack‐
768 age() commands except when invoked with the NO_POLICY_SCOPE
769 option (see also policy CMP0011). The cmake_policy command pro‐
770 vides an interface to manage custom entries on the policy stack:
771 cmake_policy(PUSH)
774 cmake_policy(POP)
775 Each PUSH must have a matching POP to erase any changes. This
777 is useful to make temporary changes to policy settings.
778 Functions and macros record policy settings when they are cre‐
781 ated and use the pre-record policies when they are invoked. If
782 the function or macro implementation sets policies, the changes
783 automatically propagate up through callers until they reach the
784 closest nested policy stack entry.
785 configure_file
788 Copy a file to another location and modify its contents.
789 configure_file(<input> <output>
791 [COPYONLY] [ESCAPE_QUOTES] [@ONLY])
792 Copies a file <input> to file <output> and substitutes variable
794 values referenced in the file content. If <input> is a relative
795 path it is evaluated with respect to the current source direc‐
796 tory. The <input> must be a file, not a directory. If <output>
797 is a relative path it is evaluated with respect to the current
798 binary directory. If <output> names an existing directory the
799 input file is placed in that directory with its original name.
800 This command replaces any variables in the input file referenced
803 as ${VAR} or @VAR@ with their values as determined by CMake. If
804 a variable is not defined, it will be replaced with nothing. If
805 COPYONLY is specified, then no variable expansion will take
806 place. If ESCAPE_QUOTES is specified then any substituted
807 quotes will be C-style escaped. The file will be configured
808 with the current values of CMake variables. If @ONLY is speci‐
809 fied, only variables of the form @VAR@ will be replaces and
810 ${VAR} will be ignored. This is useful for configuring scripts
811 that use ${VAR}. Any occurrences of #cmakedefine VAR will be
812 replaced with either #define VAR or /* #undef VAR */ depending
813 on the setting of VAR in CMake. Any occurrences of #cmakede‐
814 fine01 VAR will be replaced with either #define VAR 1 or #define
815 VAR 0 depending on whether VAR evaluates to TRUE or FALSE in
816 CMake
817 create_test_sourcelist
820 Create a test driver and source list for building test programs.
821 create_test_sourcelist(sourceListName driverName
823 test1 test2 test3
824 EXTRA_INCLUDE include.h
825 FUNCTION function)
826 A test driver is a program that links together many small tests
828 into a single executable. This is useful when building static
829 executables with large libraries to shrink the total required
830 size. The list of source files needed to build the test driver
831 will be in sourceListName. DriverName is the name of the test
832 driver program. The rest of the arguments consist of a list of
833 test source files, can be semicolon separated. Each test source
834 file should have a function in it that is the same name as the
835 file with no extension (foo.cxx should have int foo(int,
836 char*[]);) DriverName will be able to call each of the tests by
837 name on the command line. If EXTRA_INCLUDE is specified, then
838 the next argument is included into the generated file. If FUNC‐
839 TION is specified, then the next argument is taken as a function
840 name that is passed a pointer to ac and av. This can be used to
841 add extra command line processing to each test. The cmake vari‐
842 able CMAKE_TESTDRIVER_BEFORE_TESTMAIN can be set to have code
843 that will be placed directly before calling the test main func‐
844 tion. CMAKE_TESTDRIVER_AFTER_TESTMAIN can be set to have code
845 that will be placed directly after the call to the test main
846 function.
847 define_property
850 Define and document custom properties.
851 define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
853 TEST | VARIABLE | CACHED_VARIABLE>
854 PROPERTY <name> [INHERITED]
855 BRIEF_DOCS <brief-doc> [docs...]
856 FULL_DOCS <full-doc> [docs...])
857 Define one property in a scope for use with the set_property and
859 get_property commands. This is primarily useful to associate
860 documentation with property names that may be retrieved with the
861 get_property command. The first argument determines the kind of
862 scope in which the property should be used. It must be one of
863 the following:
864 GLOBAL = associated with the global namespace
867 DIRECTORY = associated with one directory
868 TARGET = associated with one target
869 SOURCE = associated with one source file
870 TEST = associated with a test named with add_test
871 VARIABLE = documents a CMake language variable
872 CACHED_VARIABLE = documents a CMake cache variable
873 Note that unlike set_property and get_property no actual scope
875 needs to be given; only the kind of scope is important.
876 The required PROPERTY option is immediately followed by the name
879 of the property being defined.
880 If the INHERITED option then the get_property command will chain
883 up to the next higher scope when the requested property is not
884 set in the scope given to the command. DIRECTORY scope chains
885 to GLOBAL. TARGET, SOURCE, and TEST chain to DIRECTORY.
886 The BRIEF_DOCS and FULL_DOCS options are followed by strings to
889 be associated with the property as its brief and full documenta‐
890 tion. Corresponding options to the get_property command will
891 retrieve the documentation.
892 else Starts the else portion of an if block.
895 else(expression)
897 See the if command.
899 elseif Starts the elseif portion of an if block.
902 elseif(expression)
904 See the if command.
906 enable_language
909 Enable a language (CXX/C/Fortran/etc)
910 enable_language(languageName [OPTIONAL] )
912 This command enables support for the named language in CMake.
914 This is the same as the project command but does not create any
915 of the extra variables that are created by the project command.
916 Example languages are CXX, C, Fortran. If OPTIONAL is used, use
917 the CMAKE_<languageName>_COMPILER_WORKS variable to check
918 whether the language has been enabled successfully.
919 enable_testing
922 Enable testing for current directory and below.
923 enable_testing()
925 Enables testing for this directory and below. See also the
927 add_test command. Note that ctest expects to find a test file
928 in the build directory root. Therefore, this command should be
929 in the source directory root.
930 endforeach
933 Ends a list of commands in a FOREACH block.
934 endforeach(expression)
936 See the FOREACH command.
938 endfunction
941 Ends a list of commands in a function block.
942 endfunction(expression)
944 See the function command.
946 endif Ends a list of commands in an if block.
949 endif(expression)
951 See the if command.
953 endmacro
956 Ends a list of commands in a macro block.
957 endmacro(expression)
959 See the macro command.
961 endwhile
964 Ends a list of commands in a while block.
965 endwhile(expression)
967 See the while command.
969 execute_process
972 Execute one or more child processes.
973 execute_process(COMMAND <cmd1> [args1...]]
975 [COMMAND <cmd2> [args2...] [...]]
976 [WORKING_DIRECTORY <directory>]
977 [TIMEOUT <seconds>]
978 [RESULT_VARIABLE <variable>]
979 [OUTPUT_VARIABLE <variable>]
980 [ERROR_VARIABLE <variable>]
981 [INPUT_FILE <file>]
982 [OUTPUT_FILE <file>]
983 [ERROR_FILE <file>]
984 [OUTPUT_QUIET]
985 [ERROR_QUIET]
986 [OUTPUT_STRIP_TRAILING_WHITESPACE]
987 [ERROR_STRIP_TRAILING_WHITESPACE])
988 Runs the given sequence of one or more commands with the stan‐
990 dard output of each process piped to the standard input of the
991 next. A single standard error pipe is used for all processes.
992 If WORKING_DIRECTORY is given the named directory will be set as
993 the current working directory of the child processes. If TIME‐
994 OUT is given the child processes will be terminated if they do
995 not finish in the specified number of seconds (fractions are
996 allowed). If RESULT_VARIABLE is given the variable will be set
997 to contain the result of running the processes. This will be an
998 integer return code from the last child or a string describing
999 an error condition. If OUTPUT_VARIABLE or ERROR_VARIABLE are
1000 given the variable named will be set with the contents of the
1001 standard output and standard error pipes respectively. If the
1002 same variable is named for both pipes their output will be
1003 merged in the order produced. If INPUT_FILE, OUTPUT_FILE, or
1004 ERROR_FILE is given the file named will be attached to the stan‐
1005 dard input of the first process, standard output of the last
1006 process, or standard error of all processes respectively. If
1007 OUTPUT_QUIET or ERROR_QUIET is given then the standard output or
1008 standard error results will be quietly ignored. If more than
1009 one OUTPUT_* or ERROR_* option is given for the same pipe the
1010 precedence is not specified. If no OUTPUT_* or ERROR_* options
1011 are given the output will be shared with the corresponding pipes
1012 of the CMake process itself.
1013 The execute_process command is a newer more powerful version of
1016 exec_program, but the old command has been kept for compatibil‐
1017 ity.
1018 export Export targets from the build tree for use by outside projects.
1021 export(TARGETS [target1 [target2 [...]]] [NAMESPACE <namespace>]
1023 [APPEND] FILE <filename>)
1024 Create a file <filename> that may be included by outside
1026 projects to import targets from the current project's build
1027 tree. This is useful during cross-compiling to build utility
1028 executables that can run on the host platform in one project and
1029 then import them into another project being compiled for the
1030 target platform. If the NAMESPACE option is given the <names‐
1031 pace> string will be prepended to all target names written to
1032 the file. If the APPEND option is given the generated code will
1033 be appended to the file instead of overwriting it. If a library
1034 target is included in the export but a target to which it links
1035 is not included the behavior is unspecified.
1036 The file created by this command is specific to the build tree
1039 and should never be installed. See the install(EXPORT) command
1040 to export targets from an installation tree.
1041 export(PACKAGE <name>)
1044 Store the current build directory in the CMake user package reg‐
1046 istry for package <name>. The find_package command may consider
1047 the directory while searching for package <name>. This helps
1048 dependent projects find and use a package from the current
1049 project's build tree without help from the user. Note that the
1050 entry in the package registry that this command creates works
1051 only in conjunction with a package configuration file
1052 (<name>Config.cmake) that works with the build tree.
1053 file File manipulation command.
1056 file(WRITE filename "message to write"... )
1058 file(APPEND filename "message to write"... )
1059 file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX])
1060 file(STRINGS filename variable [LIMIT_COUNT num]
1061 [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes]
1062 [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes]
1063 [NEWLINE_CONSUME] [REGEX regex]
1064 [NO_HEX_CONVERSION])
1065 file(GLOB variable [RELATIVE path] [globbing expressions]...)
1066 file(GLOB_RECURSE variable [RELATIVE path]
1067 [FOLLOW_SYMLINKS] [globbing expressions]...)
1068 file(RENAME <oldname> <newname>)
1069 file(REMOVE [file1 ...])
1070 file(REMOVE_RECURSE [file1 ...])
1071 file(MAKE_DIRECTORY [directory1 directory2 ...])
1072 file(RELATIVE_PATH variable directory file)
1073 file(TO_CMAKE_PATH path result)
1074 file(TO_NATIVE_PATH path result)
1075 file(DOWNLOAD url file [TIMEOUT timeout] [STATUS status] [LOG log]
1076 [EXPECTED_MD5 sum] [SHOW_PROGRESS])
1077 WRITE will write a message into a file called 'filename'. It
1079 overwrites the file if it already exists, and creates the file
1080 if it does not exist.
1081 APPEND will write a message into a file same as WRITE, except it
1084 will append it to the end of the file
1085 READ will read the content of a file and store it into the vari‐
1088 able. It will start at the given offset and read up to numBytes.
1089 If the argument HEX is given, the binary data will be converted
1090 to hexadecimal representation and this will be stored in the
1091 variable.
1092 STRINGS will parse a list of ASCII strings from a file and store
1095 it in a variable. Binary data in the file are ignored. Carriage
1096 return (CR) characters are ignored. It works also for Intel Hex
1097 and Motorola S-record files, which are automatically converted
1098 to binary format when reading them. Disable this using
1099 NO_HEX_CONVERSION.
1100 LIMIT_COUNT sets the maximum number of strings to return.
1103 LIMIT_INPUT sets the maximum number of bytes to read from the
1104 input file. LIMIT_OUTPUT sets the maximum number of bytes to
1105 store in the output variable. LENGTH_MINIMUM sets the minimum
1106 length of a string to return. Shorter strings are ignored.
1107 LENGTH_MAXIMUM sets the maximum length of a string to return.
1108 Longer strings are split into strings no longer than the maximum
1109 length. NEWLINE_CONSUME allows newlines to be included in
1110 strings instead of terminating them.
1111 REGEX specifies a regular expression that a string must match to
1114 be returned. Typical usage
1115 file(STRINGS myfile.txt myfile)
1118 stores a list in the variable "myfile" in which each item is a
1120 line from the input file.
1121 GLOB will generate a list of all files that match the globbing
1124 expressions and store it into the variable. Globbing expressions
1125 are similar to regular expressions, but much simpler. If RELA‐
1126 TIVE flag is specified for an expression, the results will be
1127 returned as a relative path to the given path. (We do not rec‐
1128 ommend using GLOB to collect a list of source files from your
1129 source tree. If no CMakeLists.txt file changes when a source is
1130 added or removed then the generated build system cannot know
1131 when to ask CMake to regenerate.)
1132 Examples of globbing expressions include:
1135 *.cxx - match all files with extension cxx
1138 *.vt? - match all files with extension vta,...,vtz
1139 f[3-5].txt - match files f3.txt, f4.txt, f5.txt
1140 GLOB_RECURSE will generate a list similar to the regular GLOB,
1142 except it will traverse all the subdirectories of the matched
1143 directory and match the files. Subdirectories that are symlinks
1144 are only traversed if FOLLOW_SYMLINKS is given or cmake policy
1145 CMP0009 is not set to NEW. See cmake --help-policy CMP0009 for
1146 more information.
1147 Examples of recursive globbing include:
1150 /dir/*.py - match all python files in /dir and subdirectories
1153 MAKE_DIRECTORY will create the given directories, also if their
1155 parent directories don't exist yet
1156 RENAME moves a file or directory within a filesystem, replacing
1159 the destination atomically.
1160 REMOVE will remove the given files, also in subdirectories
1163 REMOVE_RECURSE will remove the given files and directories, also
1166 non-empty directories
1167 RELATIVE_PATH will determine relative path from directory to the
1170 given file.
1171 TO_CMAKE_PATH will convert path into a cmake style path with
1174 unix /. The input can be a single path or a system path like
1175 "$ENV{PATH}". Note the double quotes around the ENV call
1176 TO_CMAKE_PATH only takes one argument.
1177 TO_NATIVE_PATH works just like TO_CMAKE_PATH, but will convert
1180 from a cmake style path into the native path style \ for win‐
1181 dows and / for UNIX.
1182 DOWNLOAD will download the given URL to the given file. If LOG
1185 var is specified a log of the download will be put in var. If
1186 STATUS var is specified the status of the operation will be put
1187 in var. The status is returned in a list of length 2. The first
1188 element is the numeric return value for the operation, and the
1189 second element is a string value for the error. A 0 numeric
1190 error means no error in the operation. If TIMEOUT time is speci‐
1191 fied, the operation will timeout after time seconds, time should
1192 be specified as an integer. If EXPECTED_MD5 sum is specified,
1193 the operation will verify that the downloaded file's actual md5
1194 sum matches the expected value. If it does not match, the opera‐
1195 tion fails with an error. If SHOW_PROGRESS is specified,
1196 progress information will be printed as status messages until
1197 the operation is complete.
1198 The file() command also provides COPY and INSTALL signatures:
1201 file(<COPY|INSTALL> files... DESTINATION <dir>
1204 [FILE_PERMISSIONS permissions...]
1205 [DIRECTORY_PERMISSIONS permissions...]
1206 [NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
1207 [FILES_MATCHING]
1208 [[PATTERN <pattern> | REGEX <regex>]
1209 [EXCLUDE] [PERMISSIONS permissions...]] [...])
1210 The COPY signature copies files, directories, and symlinks to a
1212 destination folder. Relative input paths are evaluated with
1213 respect to the current source directory, and a relative destina‐
1214 tion is evaluated with respect to the current build directory.
1215 Copying preserves input file timestamps, and optimizes out a
1216 file if it exists at the destination with the same timestamp.
1217 Copying preserves input permissions unless explicit permissions
1218 or NO_SOURCE_PERMISSIONS are given (default is USE_SOURCE_PER‐
1219 MISSIONS). See the install(DIRECTORY) command for documentation
1220 of permissions, PATTERN, REGEX, and EXCLUDE options.
1221 The INSTALL signature differs slightly from COPY: it prints sta‐
1224 tus messages, and NO_SOURCE_PERMISSIONS is default. Installa‐
1225 tion scripts generated by the install() command use this signa‐
1226 ture (with some undocumented options for internal use).
1227 find_file
1230 Find the full path to a file.
1231 find_file(<VAR> name1 [path1 path2 ...])
1233 This is the short-hand signature for the command that is suffi‐
1235 cient in many cases. It is the same as find_file(<VAR> name1
1236 [PATHS path1 path2 ...])
1237 find_file(
1240 <VAR>
1241 name | NAMES name1 [name2 ...]
1242 [HINTS path1 [path2 ... ENV var]]
1243 [PATHS path1 [path2 ... ENV var]]
1244 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1245 [DOC "cache documentation string"]
1246 [NO_DEFAULT_PATH]
1247 [NO_CMAKE_ENVIRONMENT_PATH]
1248 [NO_CMAKE_PATH]
1249 [NO_SYSTEM_ENVIRONMENT_PATH]
1250 [NO_CMAKE_SYSTEM_PATH]
1251 [CMAKE_FIND_ROOT_PATH_BOTH |
1252 ONLY_CMAKE_FIND_ROOT_PATH |
1253 NO_CMAKE_FIND_ROOT_PATH]
1254 )
1255 This command is used to find a full path to named file. A cache
1257 entry named by <VAR> is created to store the result of this com‐
1258 mand. If the full path to a file is found the result is stored
1259 in the variable and the search will not be repeated unless the
1260 variable is cleared. If nothing is found, the result will be
1261 <VAR>-NOTFOUND, and the search will be attempted again the next
1262 time find_file is invoked with the same variable. The name of
1263 the full path to a file that is searched for is specified by the
1264 names listed after the NAMES argument. Additional search loca‐
1265 tions can be specified after the PATHS argument. If ENV var is
1266 found in the HINTS or PATHS section the environment variable var
1267 will be read and converted from a system environment variable to
1268 a cmake style list of paths. For example ENV PATH would be a
1269 way to list the system path variable. The argument after DOC
1270 will be used for the documentation string in the cache.
1271 PATH_SUFFIXES specifies additional subdirectories to check below
1272 each search path.
1273 If NO_DEFAULT_PATH is specified, then no additional paths are
1276 added to the search. If NO_DEFAULT_PATH is not specified, the
1277 search process is as follows:
1278 1. Search paths specified in cmake-specific cache variables.
1281 These are intended to be used on the command line with a
1282 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1283 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1286 CMAKE_INCLUDE_PATH
1287 CMAKE_FRAMEWORK_PATH
1288 2. Search paths specified in cmake-specific environment vari‐
1290 ables. These are intended to be set in the user's shell config‐
1291 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1292 passed.
1293 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1296 CMAKE_INCLUDE_PATH
1297 CMAKE_FRAMEWORK_PATH
1298 3. Search the paths specified by the HINTS option. These should
1300 be paths computed by system introspection, such as a hint pro‐
1301 vided by the location of another item already found. Hard-coded
1302 guesses should be specified with the PATHS option.
1303 4. Search the standard system environment variables. This can be
1306 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1307 PATH
1310 INCLUDE
1311 5. Search cmake variables defined in the Platform files for the
1313 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1314 passed.
1315 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1318 CMAKE_SYSTEM_INCLUDE_PATH
1319 CMAKE_SYSTEM_FRAMEWORK_PATH
1320 6. Search the paths specified by the PATHS option or in the
1322 short-hand version of the command. These are typically
1323 hard-coded guesses.
1324 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1327 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1328 following:
1329 "FIRST" - Try to find frameworks before standard
1332 libraries or headers. This is the default on Darwin.
1333 "LAST" - Try to find frameworks after standard
1334 libraries or headers.
1335 "ONLY" - Only try to find frameworks.
1336 "NEVER" - Never try to find frameworks.
1337 On Darwin or systems supporting OS X Application Bundles, the
1339 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
1340 of the following:
1341 "FIRST" - Try to find application bundles before standard
1344 programs. This is the default on Darwin.
1345 "LAST" - Try to find application bundles after standard
1346 programs.
1347 "ONLY" - Only try to find application bundles.
1348 "NEVER" - Never try to find application bundles.
1349 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
1351 directories to be prepended to all other search directories.
1352 This effectively "re-roots" the entire search under given loca‐
1353 tions. By default it is empty. It is especially useful when
1354 cross-compiling to point to the root directory of the target
1355 environment and CMake will search there too. By default at first
1356 the directories listed in CMAKE_FIND_ROOT_PATH and then the
1357 non-rooted directories will be searched. The default behavior
1358 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
1359 This behavior can be manually overridden on a per-call basis. By
1360 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
1361 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
1362 CMAKE_FIND_ROOT_PATH will not be used. If
1363 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1364 tories will be searched.
1365 The default search order is designed to be most-specific to
1368 least-specific for common use cases. Projects may override the
1369 order by simply calling the command multiple times and using the
1370 NO_* options:
1371 find_file(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1374 find_file(<VAR> NAMES name)
1375 Once one of the calls succeeds the result variable will be set
1377 and stored in the cache so that no call will search again.
1378 find_library
1381 Find a library.
1382 find_library(<VAR> name1 [path1 path2 ...])
1384 This is the short-hand signature for the command that is suffi‐
1386 cient in many cases. It is the same as find_library(<VAR> name1
1387 [PATHS path1 path2 ...])
1388 find_library(
1391 <VAR>
1392 name | NAMES name1 [name2 ...]
1393 [HINTS path1 [path2 ... ENV var]]
1394 [PATHS path1 [path2 ... ENV var]]
1395 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1396 [DOC "cache documentation string"]
1397 [NO_DEFAULT_PATH]
1398 [NO_CMAKE_ENVIRONMENT_PATH]
1399 [NO_CMAKE_PATH]
1400 [NO_SYSTEM_ENVIRONMENT_PATH]
1401 [NO_CMAKE_SYSTEM_PATH]
1402 [CMAKE_FIND_ROOT_PATH_BOTH |
1403 ONLY_CMAKE_FIND_ROOT_PATH |
1404 NO_CMAKE_FIND_ROOT_PATH]
1405 )
1406 This command is used to find a library. A cache entry named by
1408 <VAR> is created to store the result of this command. If the
1409 library is found the result is stored in the variable and the
1410 search will not be repeated unless the variable is cleared. If
1411 nothing is found, the result will be <VAR>-NOTFOUND, and the
1412 search will be attempted again the next time find_library is
1413 invoked with the same variable. The name of the library that is
1414 searched for is specified by the names listed after the NAMES
1415 argument. Additional search locations can be specified after
1416 the PATHS argument. If ENV var is found in the HINTS or PATHS
1417 section the environment variable var will be read and converted
1418 from a system environment variable to a cmake style list of
1419 paths. For example ENV PATH would be a way to list the system
1420 path variable. The argument after DOC will be used for the docu‐
1421 mentation string in the cache. PATH_SUFFIXES specifies addi‐
1422 tional subdirectories to check below each search path.
1423 If NO_DEFAULT_PATH is specified, then no additional paths are
1426 added to the search. If NO_DEFAULT_PATH is not specified, the
1427 search process is as follows:
1428 1. Search paths specified in cmake-specific cache variables.
1431 These are intended to be used on the command line with a
1432 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1433 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1436 CMAKE_LIBRARY_PATH
1437 CMAKE_FRAMEWORK_PATH
1438 2. Search paths specified in cmake-specific environment vari‐
1440 ables. These are intended to be set in the user's shell config‐
1441 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1442 passed.
1443 <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
1446 CMAKE_LIBRARY_PATH
1447 CMAKE_FRAMEWORK_PATH
1448 3. Search the paths specified by the HINTS option. These should
1450 be paths computed by system introspection, such as a hint pro‐
1451 vided by the location of another item already found. Hard-coded
1452 guesses should be specified with the PATHS option.
1453 4. Search the standard system environment variables. This can be
1456 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1457 PATH
1460 LIB
1461 5. Search cmake variables defined in the Platform files for the
1463 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1464 passed.
1465 <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1468 CMAKE_SYSTEM_LIBRARY_PATH
1469 CMAKE_SYSTEM_FRAMEWORK_PATH
1470 6. Search the paths specified by the PATHS option or in the
1472 short-hand version of the command. These are typically
1473 hard-coded guesses.
1474 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1477 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1478 following:
1479 "FIRST" - Try to find frameworks before standard
1482 libraries or headers. This is the default on Darwin.
1483 "LAST" - Try to find frameworks after standard
1484 libraries or headers.
1485 "ONLY" - Only try to find frameworks.
1486 "NEVER" - Never try to find frameworks.
1487 On Darwin or systems supporting OS X Application Bundles, the
1489 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
1490 of the following:
1491 "FIRST" - Try to find application bundles before standard
1494 programs. This is the default on Darwin.
1495 "LAST" - Try to find application bundles after standard
1496 programs.
1497 "ONLY" - Only try to find application bundles.
1498 "NEVER" - Never try to find application bundles.
1499 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
1501 directories to be prepended to all other search directories.
1502 This effectively "re-roots" the entire search under given loca‐
1503 tions. By default it is empty. It is especially useful when
1504 cross-compiling to point to the root directory of the target
1505 environment and CMake will search there too. By default at first
1506 the directories listed in CMAKE_FIND_ROOT_PATH and then the
1507 non-rooted directories will be searched. The default behavior
1508 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_LIBRARY.
1509 This behavior can be manually overridden on a per-call basis. By
1510 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
1511 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
1512 CMAKE_FIND_ROOT_PATH will not be used. If
1513 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1514 tories will be searched.
1515 The default search order is designed to be most-specific to
1518 least-specific for common use cases. Projects may override the
1519 order by simply calling the command multiple times and using the
1520 NO_* options:
1521 find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
1524 find_library(<VAR> NAMES name)
1525 Once one of the calls succeeds the result variable will be set
1527 and stored in the cache so that no call will search again.
1528 If the library found is a framework, then VAR will be set to the
1531 full path to the framework <fullPath>/A.framework. When a full
1532 path to a framework is used as a library, CMake will use a
1533 -framework A, and a -F<fullPath> to link the framework to the
1534 target.
1535 find_package
1538 Load settings for an external project.
1539 find_package(<package> [version] [EXACT] [QUIET]
1541 [[REQUIRED|COMPONENTS] [components...]]
1542 [NO_POLICY_SCOPE])
1543 Finds and loads settings from an external project. <pack‐
1545 age>_FOUND will be set to indicate whether the package was
1546 found. When the package is found package-specific information
1547 is provided through variables documented by the package itself.
1548 The QUIET option disables messages if the package cannot be
1549 found. The REQUIRED option stops processing with an error mes‐
1550 sage if the package cannot be found. A package-specific list of
1551 components may be listed after the REQUIRED option or after the
1552 COMPONENTS option if no REQUIRED option is given. The [version]
1553 argument requests a version with which the package found should
1554 be compatible (format is major[.minor[.patch[.tweak]]]). The
1555 EXACT option requests that the version be matched exactly. If
1556 no [version] is given to a recursive invocation inside a
1557 find-module, the [version] and EXACT arguments are forwarded
1558 automatically from the outer call. Version support is currently
1559 provided only on a package-by-package basis (details below).
1560 User code should generally look for packages using the above
1563 simple signature. The remainder of this command documentation
1564 specifies the full command signature and details of the search
1565 process. Project maintainers wishing to provide a package to be
1566 found by this command are encouraged to read on.
1567 The command has two modes by which it searches for packages:
1570 "Module" mode and "Config" mode. Module mode is available when
1571 the command is invoked with the above reduced signature. CMake
1572 searches for a file called "Find<package>.cmake" in the
1573 CMAKE_MODULE_PATH followed by the CMake installation. If the
1574 file is found, it is read and processed by CMake. It is respon‐
1575 sible for finding the package, checking the version, and produc‐
1576 ing any needed messages. Many find-modules provide limited or
1577 no support for versioning; check the module documentation. If
1578 no module is found the command proceeds to Config mode.
1579 The complete Config mode command signature is:
1582 find_package(<package> [version] [EXACT] [QUIET]
1585 [[REQUIRED|COMPONENTS] [components...]] [NO_MODULE]
1586 [NO_POLICY_SCOPE]
1587 [NAMES name1 [name2 ...]]
1588 [CONFIGS config1 [config2 ...]]
1589 [HINTS path1 [path2 ... ]]
1590 [PATHS path1 [path2 ... ]]
1591 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1592 [NO_DEFAULT_PATH]
1593 [NO_CMAKE_ENVIRONMENT_PATH]
1594 [NO_CMAKE_PATH]
1595 [NO_SYSTEM_ENVIRONMENT_PATH]
1596 [NO_CMAKE_PACKAGE_REGISTRY]
1597 [NO_CMAKE_BUILDS_PATH]
1598 [NO_CMAKE_SYSTEM_PATH]
1599 [CMAKE_FIND_ROOT_PATH_BOTH |
1600 ONLY_CMAKE_FIND_ROOT_PATH |
1601 NO_CMAKE_FIND_ROOT_PATH])
1602 The NO_MODULE option may be used to skip Module mode explicitly.
1604 It is also implied by use of options not specified in the
1605 reduced signature.
1606 Config mode attempts to locate a configuration file provided by
1609 the package to be found. A cache entry called <package>_DIR is
1610 created to hold the directory containing the file. By default
1611 the command searches for a package with the name <package>. If
1612 the NAMES option is given the names following it are used
1613 instead of <package>. The command searches for a file called
1614 "<name>Config.cmake" or "<lower-case-name>-config.cmake" for
1615 each name specified. A replacement set of possible configura‐
1616 tion file names may be given using the CONFIGS option. The
1617 search procedure is specified below. Once found, the configura‐
1618 tion file is read and processed by CMake. Since the file is
1619 provided by the package it already knows the location of package
1620 contents. The full path to the configuration file is stored in
1621 the cmake variable <package>_CONFIG.
1622 All configuration files which have been considered by CMake
1625 while searching for an installation of the package with an
1626 appropriate version are stored in the cmake variable <pack‐
1627 age>_CONSIDERED_CONFIGS, the associated versions in <pack‐
1628 age>_CONSIDERED_VERSIONS.
1629 If the package configuration file cannot be found CMake will
1632 generate an error describing the problem unless the QUIET argu‐
1633 ment is specified. If REQUIRED is specified and the package is
1634 not found a fatal error is generated and the configure step
1635 stops executing. If <package>_DIR has been set to a directory
1636 not containing a configuration file CMake will ignore it and
1637 search from scratch.
1638 When the [version] argument is given Config mode will only find
1641 a version of the package that claims compatibility with the
1642 requested version (format is major[.minor[.patch[.tweak]]]). If
1643 the EXACT option is given only a version of the package claiming
1644 an exact match of the requested version may be found. CMake
1645 does not establish any convention for the meaning of version
1646 numbers. Package version numbers are checked by "version" files
1647 provided by the packages themselves. For a candidate package
1648 configuration file "<config-file>.cmake" the corresponding ver‐
1649 sion file is located next to it and named either "<con‐
1650 fig-file>-version.cmake" or "<config-file>Version.cmake". If no
1651 such version file is available then the configuration file is
1652 assumed to not be compatible with any requested version. When a
1653 version file is found it is loaded to check the requested ver‐
1654 sion number. The version file is loaded in a nested scope in
1655 which the following variables have been defined:
1656 PACKAGE_FIND_NAME = the <package> name
1659 PACKAGE_FIND_VERSION = full requested version string
1660 PACKAGE_FIND_VERSION_MAJOR = major version if requested, else 0
1661 PACKAGE_FIND_VERSION_MINOR = minor version if requested, else 0
1662 PACKAGE_FIND_VERSION_PATCH = patch version if requested, else 0
1663 PACKAGE_FIND_VERSION_TWEAK = tweak version if requested, else 0
1664 PACKAGE_FIND_VERSION_COUNT = number of version components, 0 to 4
1665 The version file checks whether it satisfies the requested ver‐
1667 sion and sets these variables:
1668 PACKAGE_VERSION = full provided version string
1671 PACKAGE_VERSION_EXACT = true if version is exact match
1672 PACKAGE_VERSION_COMPATIBLE = true if version is compatible
1673 PACKAGE_VERSION_UNSUITABLE = true if unsuitable as any version
1674 These variables are checked by the find_package command to
1676 determine whether the configuration file provides an acceptable
1677 version. They are not available after the find_package call
1678 returns. If the version is acceptable the following variables
1679 are set:
1680 <package>_VERSION = full provided version string
1683 <package>_VERSION_MAJOR = major version if provided, else 0
1684 <package>_VERSION_MINOR = minor version if provided, else 0
1685 <package>_VERSION_PATCH = patch version if provided, else 0
1686 <package>_VERSION_TWEAK = tweak version if provided, else 0
1687 <package>_VERSION_COUNT = number of version components, 0 to 4
1688 and the corresponding package configuration file is loaded.
1690 When multiple package configuration files are available whose
1691 version files claim compatibility with the version requested it
1692 is unspecified which one is chosen. No attempt is made to
1693 choose a highest or closest version number.
1694 Config mode provides an elaborate interface and search proce‐
1697 dure. Much of the interface is provided for completeness and
1698 for use internally by find-modules loaded by Module mode. Most
1699 user code should simply call
1700 find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
1703 in order to find a package. Package maintainers providing CMake
1705 package configuration files are encouraged to name and install
1706 them such that the procedure outlined below will find them with‐
1707 out requiring use of additional options.
1708 CMake constructs a set of possible installation prefixes for the
1711 package. Under each prefix several directories are searched for
1712 a configuration file. The tables below show the directories
1713 searched. Each entry is meant for installation trees following
1714 Windows (W), UNIX (U), or Apple (A) conventions.
1715 <prefix>/ (W)
1718 <prefix>/(cmake|CMake)/ (W)
1719 <prefix>/<name>*/ (W)
1720 <prefix>/<name>*/(cmake|CMake)/ (W)
1721 <prefix>/(share|lib)/cmake/<name>*/ (U)
1722 <prefix>/(share|lib)/<name>*/ (U)
1723 <prefix>/(share|lib)/<name>*/(cmake|CMake)/ (U)
1724 On systems supporting OS X Frameworks and Application Bundles
1726 the following directories are searched for frameworks or bundles
1727 containing a configuration file:
1728 <prefix>/<name>.framework/Resources/ (A)
1731 <prefix>/<name>.framework/Resources/CMake/ (A)
1732 <prefix>/<name>.framework/Versions/*/Resources/ (A)
1733 <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A)
1734 <prefix>/<name>.app/Contents/Resources/ (A)
1735 <prefix>/<name>.app/Contents/Resources/CMake/ (A)
1736 In all cases the <name> is treated as case-insensitive and cor‐
1738 responds to any of the names specified (<package> or names given
1739 by NAMES). If PATH_SUFFIXES is specified the suffixes are
1740 appended to each (W) or (U) directory entry one-by-one.
1741 This set of directories is intended to work in cooperation with
1744 projects that provide configuration files in their installation
1745 trees. Directories above marked with (W) are intended for
1746 installations on Windows where the prefix may point at the top
1747 of an application's installation directory. Those marked with
1748 (U) are intended for installations on UNIX platforms where the
1749 prefix is shared by multiple packages. This is merely a conven‐
1750 tion, so all (W) and (U) directories are still searched on all
1751 platforms. Directories marked with (A) are intended for instal‐
1752 lations on Apple platforms. The cmake variables
1753 CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE determine the
1754 order of preference as specified below.
1755 The set of installation prefixes is constructed using the fol‐
1758 lowing steps. If NO_DEFAULT_PATH is specified all NO_* options
1759 are enabled.
1760 1. Search paths specified in cmake-specific cache variables.
1763 These are intended to be used on the command line with a
1764 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1765 CMAKE_PREFIX_PATH
1768 CMAKE_FRAMEWORK_PATH
1769 CMAKE_APPBUNDLE_PATH
1770 2. Search paths specified in cmake-specific environment vari‐
1772 ables. These are intended to be set in the user's shell config‐
1773 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1774 passed.
1775 <package>_DIR
1778 CMAKE_PREFIX_PATH
1779 CMAKE_FRAMEWORK_PATH
1780 CMAKE_APPBUNDLE_PATH
1781 3. Search paths specified by the HINTS option. These should be
1783 paths computed by system introspection, such as a hint provided
1784 by the location of another item already found. Hard-coded
1785 guesses should be specified with the PATHS option.
1786 4. Search the standard system environment variables. This can be
1789 skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed. Path entries
1790 ending in "/bin" or "/sbin" are automatically converted to their
1791 parent directories.
1792 PATH
1795 5. Search project build trees recently configured in a CMake
1797 GUI. This can be skipped if NO_CMAKE_BUILDS_PATH is passed. It
1798 is intended for the case when a user is building multiple depen‐
1799 dent projects one after another.
1800 6. Search paths stored in the CMake user package registry. This
1803 can be skipped if NO_CMAKE_PACKAGE_REGISTRY is passed. Paths
1804 are stored in the registry when CMake configures a project that
1805 invokes export(PACKAGE <name>). See the export(PACKAGE) command
1806 documentation for more details.
1807 7. Search cmake variables defined in the Platform files for the
1810 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1811 passed.
1812 CMAKE_SYSTEM_PREFIX_PATH
1815 CMAKE_SYSTEM_FRAMEWORK_PATH
1816 CMAKE_SYSTEM_APPBUNDLE_PATH
1817 8. Search paths specified by the PATHS option. These are typi‐
1819 cally hard-coded guesses.
1820 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1823 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1824 following:
1825 "FIRST" - Try to find frameworks before standard
1828 libraries or headers. This is the default on Darwin.
1829 "LAST" - Try to find frameworks after standard
1830 libraries or headers.
1831 "ONLY" - Only try to find frameworks.
1832 "NEVER" - Never try to find frameworks.
1833 On Darwin or systems supporting OS X Application Bundles, the
1835 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
1836 of the following:
1837 "FIRST" - Try to find application bundles before standard
1840 programs. This is the default on Darwin.
1841 "LAST" - Try to find application bundles after standard
1842 programs.
1843 "ONLY" - Only try to find application bundles.
1844 "NEVER" - Never try to find application bundles.
1845 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
1847 directories to be prepended to all other search directories.
1848 This effectively "re-roots" the entire search under given loca‐
1849 tions. By default it is empty. It is especially useful when
1850 cross-compiling to point to the root directory of the target
1851 environment and CMake will search there too. By default at first
1852 the directories listed in CMAKE_FIND_ROOT_PATH and then the
1853 non-rooted directories will be searched. The default behavior
1854 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.
1855 This behavior can be manually overridden on a per-call basis. By
1856 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
1857 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
1858 CMAKE_FIND_ROOT_PATH will not be used. If
1859 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
1860 tories will be searched.
1861 The default search order is designed to be most-specific to
1864 least-specific for common use cases. Projects may override the
1865 order by simply calling the command multiple times and using the
1866 NO_* options:
1867 find_package(<package> PATHS paths... NO_DEFAULT_PATH)
1870 find_package(<package>)
1871 Once one of the calls succeeds the result variable will be set
1873 and stored in the cache so that no call will search again.
1874 See the cmake_policy() command documentation for discussion of
1877 the NO_POLICY_SCOPE option.
1878 find_path
1881 Find the directory containing a file.
1882 find_path(<VAR> name1 [path1 path2 ...])
1884 This is the short-hand signature for the command that is suffi‐
1886 cient in many cases. It is the same as find_path(<VAR> name1
1887 [PATHS path1 path2 ...])
1888 find_path(
1891 <VAR>
1892 name | NAMES name1 [name2 ...]
1893 [HINTS path1 [path2 ... ENV var]]
1894 [PATHS path1 [path2 ... ENV var]]
1895 [PATH_SUFFIXES suffix1 [suffix2 ...]]
1896 [DOC "cache documentation string"]
1897 [NO_DEFAULT_PATH]
1898 [NO_CMAKE_ENVIRONMENT_PATH]
1899 [NO_CMAKE_PATH]
1900 [NO_SYSTEM_ENVIRONMENT_PATH]
1901 [NO_CMAKE_SYSTEM_PATH]
1902 [CMAKE_FIND_ROOT_PATH_BOTH |
1903 ONLY_CMAKE_FIND_ROOT_PATH |
1904 NO_CMAKE_FIND_ROOT_PATH]
1905 )
1906 This command is used to find a directory containing the named
1908 file. A cache entry named by <VAR> is created to store the
1909 result of this command. If the file in a directory is found the
1910 result is stored in the variable and the search will not be
1911 repeated unless the variable is cleared. If nothing is found,
1912 the result will be <VAR>-NOTFOUND, and the search will be
1913 attempted again the next time find_path is invoked with the same
1914 variable. The name of the file in a directory that is searched
1915 for is specified by the names listed after the NAMES argument.
1916 Additional search locations can be specified after the PATHS
1917 argument. If ENV var is found in the HINTS or PATHS section the
1918 environment variable var will be read and converted from a sys‐
1919 tem environment variable to a cmake style list of paths. For
1920 example ENV PATH would be a way to list the system path vari‐
1921 able. The argument after DOC will be used for the documentation
1922 string in the cache. PATH_SUFFIXES specifies additional subdi‐
1923 rectories to check below each search path.
1924 If NO_DEFAULT_PATH is specified, then no additional paths are
1927 added to the search. If NO_DEFAULT_PATH is not specified, the
1928 search process is as follows:
1929 1. Search paths specified in cmake-specific cache variables.
1932 These are intended to be used on the command line with a
1933 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
1934 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1937 CMAKE_INCLUDE_PATH
1938 CMAKE_FRAMEWORK_PATH
1939 2. Search paths specified in cmake-specific environment vari‐
1941 ables. These are intended to be set in the user's shell config‐
1942 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
1943 passed.
1944 <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
1947 CMAKE_INCLUDE_PATH
1948 CMAKE_FRAMEWORK_PATH
1949 3. Search the paths specified by the HINTS option. These should
1951 be paths computed by system introspection, such as a hint pro‐
1952 vided by the location of another item already found. Hard-coded
1953 guesses should be specified with the PATHS option.
1954 4. Search the standard system environment variables. This can be
1957 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
1958 PATH
1961 INCLUDE
1962 5. Search cmake variables defined in the Platform files for the
1964 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
1965 passed.
1966 <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
1969 CMAKE_SYSTEM_INCLUDE_PATH
1970 CMAKE_SYSTEM_FRAMEWORK_PATH
1971 6. Search the paths specified by the PATHS option or in the
1973 short-hand version of the command. These are typically
1974 hard-coded guesses.
1975 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
1978 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
1979 following:
1980 "FIRST" - Try to find frameworks before standard
1983 libraries or headers. This is the default on Darwin.
1984 "LAST" - Try to find frameworks after standard
1985 libraries or headers.
1986 "ONLY" - Only try to find frameworks.
1987 "NEVER" - Never try to find frameworks.
1988 On Darwin or systems supporting OS X Application Bundles, the
1990 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
1991 of the following:
1992 "FIRST" - Try to find application bundles before standard
1995 programs. This is the default on Darwin.
1996 "LAST" - Try to find application bundles after standard
1997 programs.
1998 "ONLY" - Only try to find application bundles.
1999 "NEVER" - Never try to find application bundles.
2000 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
2002 directories to be prepended to all other search directories.
2003 This effectively "re-roots" the entire search under given loca‐
2004 tions. By default it is empty. It is especially useful when
2005 cross-compiling to point to the root directory of the target
2006 environment and CMake will search there too. By default at first
2007 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2008 non-rooted directories will be searched. The default behavior
2009 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_INCLUDE.
2010 This behavior can be manually overridden on a per-call basis. By
2011 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2012 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2013 CMAKE_FIND_ROOT_PATH will not be used. If
2014 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2015 tories will be searched.
2016 The default search order is designed to be most-specific to
2019 least-specific for common use cases. Projects may override the
2020 order by simply calling the command multiple times and using the
2021 NO_* options:
2022 find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2025 find_path(<VAR> NAMES name)
2026 Once one of the calls succeeds the result variable will be set
2028 and stored in the cache so that no call will search again.
2029 When searching for frameworks, if the file is specified as
2032 A/b.h, then the framework search will look for A.framework/Head‐
2033 ers/b.h. If that is found the path will be set to the path to
2034 the framework. CMake will convert this to the correct -F option
2035 to include the file.
2036 find_program
2039 Find an executable program.
2040 find_program(<VAR> name1 [path1 path2 ...])
2042 This is the short-hand signature for the command that is suffi‐
2044 cient in many cases. It is the same as find_program(<VAR> name1
2045 [PATHS path1 path2 ...])
2046 find_program(
2049 <VAR>
2050 name | NAMES name1 [name2 ...]
2051 [HINTS path1 [path2 ... ENV var]]
2052 [PATHS path1 [path2 ... ENV var]]
2053 [PATH_SUFFIXES suffix1 [suffix2 ...]]
2054 [DOC "cache documentation string"]
2055 [NO_DEFAULT_PATH]
2056 [NO_CMAKE_ENVIRONMENT_PATH]
2057 [NO_CMAKE_PATH]
2058 [NO_SYSTEM_ENVIRONMENT_PATH]
2059 [NO_CMAKE_SYSTEM_PATH]
2060 [CMAKE_FIND_ROOT_PATH_BOTH |
2061 ONLY_CMAKE_FIND_ROOT_PATH |
2062 NO_CMAKE_FIND_ROOT_PATH]
2063 )
2064 This command is used to find a program. A cache entry named by
2066 <VAR> is created to store the result of this command. If the
2067 program is found the result is stored in the variable and the
2068 search will not be repeated unless the variable is cleared. If
2069 nothing is found, the result will be <VAR>-NOTFOUND, and the
2070 search will be attempted again the next time find_program is
2071 invoked with the same variable. The name of the program that is
2072 searched for is specified by the names listed after the NAMES
2073 argument. Additional search locations can be specified after
2074 the PATHS argument. If ENV var is found in the HINTS or PATHS
2075 section the environment variable var will be read and converted
2076 from a system environment variable to a cmake style list of
2077 paths. For example ENV PATH would be a way to list the system
2078 path variable. The argument after DOC will be used for the docu‐
2079 mentation string in the cache. PATH_SUFFIXES specifies addi‐
2080 tional subdirectories to check below each search path.
2081 If NO_DEFAULT_PATH is specified, then no additional paths are
2084 added to the search. If NO_DEFAULT_PATH is not specified, the
2085 search process is as follows:
2086 1. Search paths specified in cmake-specific cache variables.
2089 These are intended to be used on the command line with a
2090 -DVAR=value. This can be skipped if NO_CMAKE_PATH is passed.
2091 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2094 CMAKE_PROGRAM_PATH
2095 CMAKE_APPBUNDLE_PATH
2096 2. Search paths specified in cmake-specific environment vari‐
2098 ables. These are intended to be set in the user's shell config‐
2099 uration. This can be skipped if NO_CMAKE_ENVIRONMENT_PATH is
2100 passed.
2101 <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
2104 CMAKE_PROGRAM_PATH
2105 CMAKE_APPBUNDLE_PATH
2106 3. Search the paths specified by the HINTS option. These should
2108 be paths computed by system introspection, such as a hint pro‐
2109 vided by the location of another item already found. Hard-coded
2110 guesses should be specified with the PATHS option.
2111 4. Search the standard system environment variables. This can be
2114 skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
2115 PATH
2118 5. Search cmake variables defined in the Platform files for the
2121 current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
2122 passed.
2123 <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
2126 CMAKE_SYSTEM_PROGRAM_PATH
2127 CMAKE_SYSTEM_APPBUNDLE_PATH
2128 6. Search the paths specified by the PATHS option or in the
2130 short-hand version of the command. These are typically
2131 hard-coded guesses.
2132 On Darwin or systems supporting OS X Frameworks, the cmake vari‐
2135 able CMAKE_FIND_FRAMEWORK can be set to empty or one of the
2136 following:
2137 "FIRST" - Try to find frameworks before standard
2140 libraries or headers. This is the default on Darwin.
2141 "LAST" - Try to find frameworks after standard
2142 libraries or headers.
2143 "ONLY" - Only try to find frameworks.
2144 "NEVER" - Never try to find frameworks.
2145 On Darwin or systems supporting OS X Application Bundles, the
2147 cmake variable CMAKE_FIND_APPBUNDLE can be set to empty or one
2148 of the following:
2149 "FIRST" - Try to find application bundles before standard
2152 programs. This is the default on Darwin.
2153 "LAST" - Try to find application bundles after standard
2154 programs.
2155 "ONLY" - Only try to find application bundles.
2156 "NEVER" - Never try to find application bundles.
2157 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
2159 directories to be prepended to all other search directories.
2160 This effectively "re-roots" the entire search under given loca‐
2161 tions. By default it is empty. It is especially useful when
2162 cross-compiling to point to the root directory of the target
2163 environment and CMake will search there too. By default at first
2164 the directories listed in CMAKE_FIND_ROOT_PATH and then the
2165 non-rooted directories will be searched. The default behavior
2166 can be adjusted by setting CMAKE_FIND_ROOT_PATH_MODE_PROGRAM.
2167 This behavior can be manually overridden on a per-call basis. By
2168 using CMAKE_FIND_ROOT_PATH_BOTH the search order will be as
2169 described above. If NO_CMAKE_FIND_ROOT_PATH is used then
2170 CMAKE_FIND_ROOT_PATH will not be used. If
2171 ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted direc‐
2172 tories will be searched.
2173 The default search order is designed to be most-specific to
2176 least-specific for common use cases. Projects may override the
2177 order by simply calling the command multiple times and using the
2178 NO_* options:
2179 find_program(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
2182 find_program(<VAR> NAMES name)
2183 Once one of the calls succeeds the result variable will be set
2185 and stored in the cache so that no call will search again.
2186 fltk_wrap_ui
2189 Create FLTK user interfaces Wrappers.
2190 fltk_wrap_ui(resultingLibraryName source1
2192 source2 ... sourceN )
2193 Produce .h and .cxx files for all the .fl and .fld files listed.
2195 The resulting .h and .cxx files will be added to a variable
2196 named resultingLibraryName_FLTK_UI_SRCS which should be added to
2197 your library.
2198 foreach
2201 Evaluate a group of commands for each value in a list.
2202 foreach(loop_var arg1 arg2 ...)
2204 COMMAND1(ARGS ...)
2205 COMMAND2(ARGS ...)
2206 ...
2207 endforeach(loop_var)
2208 All commands between foreach and the matching endforeach are
2210 recorded without being invoked. Once the endforeach is evalu‐
2211 ated, the recorded list of commands is invoked once for each
2212 argument listed in the original foreach command. Before each
2213 iteration of the loop "${loop_var}" will be set as a variable
2214 with the current value in the list.
2215 foreach(loop_var RANGE total)
2218 foreach(loop_var RANGE start stop [step])
2219 Foreach can also iterate over a generated range of numbers.
2221 There are three types of this iteration:
2222 * When specifying single number, the range will have elements 0
2225 to "total".
2226 * When specifying two numbers, the range will have elements from
2229 the first number to the second number.
2230 * The third optional number is the increment used to iterate
2233 from the first number to the second number.
2234 foreach(loop_var IN [LISTS [list1 [...]]]
2237 [ITEMS [item1 [...]]])
2238 Iterates over a precise list of items. The LISTS option names
2240 list-valued variables to be traversed, including empty elements
2241 (an empty string is a zero-length list). The ITEMS option ends
2242 argument parsing and includes all arguments following it in the
2243 iteration.
2244 function
2247 Start recording a function for later invocation as a command.
2248 function(<name> [arg1 [arg2 [arg3 ...]]])
2250 COMMAND1(ARGS ...)
2251 COMMAND2(ARGS ...)
2252 ...
2253 endfunction(<name>)
2254 Define a function named <name> that takes arguments named arg1
2256 arg2 arg3 (...). Commands listed after function, but before the
2257 matching endfunction, are not invoked until the function is
2258 invoked. When it is invoked, the commands recorded in the func‐
2259 tion are first modified by replacing formal parameters (${arg1})
2260 with the arguments passed, and then invoked as normal commands.
2261 In addition to referencing the formal parameters you can refer‐
2262 ence the variable ARGC which will be set to the number of argu‐
2263 ments passed into the function as well as ARGV0 ARGV1 ARGV2 ...
2264 which will have the actual values of the arguments passed in.
2265 This facilitates creating functions with optional arguments.
2266 Additionally ARGV holds the list of all arguments given to the
2267 function and ARGN holds the list of argument past the last
2268 expected argument.
2269 See the cmake_policy() command documentation for the behavior of
2272 policies inside functions.
2273 get_cmake_property
2276 Get a property of the CMake instance.
2277 get_cmake_property(VAR property)
2279 Get a property from the CMake instance. The value of the prop‐
2281 erty is stored in the variable VAR. If the property is not
2282 found, VAR will be set to "NOTFOUND". Some supported properties
2283 include: VARIABLES, CACHE_VARIABLES, COMMANDS, MACROS, and COM‐
2284 PONENTS.
2285 See also the more general get_property() command.
2288 get_directory_property
2291 Get a property of DIRECTORY scope.
2292 get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
2294 Store a property of directory scope in the named variable. If
2296 the property is not defined the empty-string is returned. The
2297 DIRECTORY argument specifies another directory from which to
2298 retrieve the property value. The specified directory must have
2299 already been traversed by CMake.
2300 get_directory_property(<variable> [DIRECTORY <dir>]
2303 DEFINITION <var-name>)
2304 Get a variable definition from a directory. This form is useful
2306 to get a variable definition from another directory.
2307 See also the more general get_property() command.
2310 get_filename_component
2313 Get a specific component of a full filename.
2314 get_filename_component(<VAR> FileName
2316 PATH|ABSOLUTE|NAME|EXT|NAME_WE|REALPATH
2317 [CACHE])
2318 Set <VAR> to be the path (PATH), file name (NAME), file exten‐
2320 sion (EXT), file name without extension (NAME_WE) of FileName,
2321 the full path (ABSOLUTE), or the full path with all symlinks
2322 resolved (REALPATH). Note that the path is converted to Unix
2323 slashes format and has no trailing slashes. The longest file
2324 extension is always considered. If the optional CACHE argument
2325 is specified, the result variable is added to the cache.
2326 get_filename_component(<VAR> FileName
2329 PROGRAM [PROGRAM_ARGS <ARG_VAR>]
2330 [CACHE])
2331 The program in FileName will be found in the system search path
2333 or left as a full path. If PROGRAM_ARGS is present with PRO‐
2334 GRAM, then any command-line arguments present in the FileName
2335 string are split from the program name and stored in <ARG_VAR>.
2336 This is used to separate a program name from its arguments in a
2337 command line string.
2338 get_property
2341 Get a property.
2342 get_property(<variable>
2344 <GLOBAL |
2345 DIRECTORY [dir] |
2346 TARGET <target> |
2347 SOURCE <source> |
2348 TEST <test> |
2349 CACHE <entry> |
2350 VARIABLE>
2351 PROPERTY <name>
2352 [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
2353 Get one property from one object in a scope. The first argument
2355 specifies the variable in which to store the result. The second
2356 argument determines the scope from which to get the property.
2357 It must be one of the following:
2358 GLOBAL scope is unique and does not accept a name.
2361 DIRECTORY scope defaults to the current directory but another
2364 directory (already processed by CMake) may be named by full or
2365 relative path.
2366 TARGET scope must name one existing target.
2369 SOURCE scope must name one source file.
2372 TEST scope must name one existing test.
2375 CACHE scope must name one cache entry.
2378 VARIABLE scope is unique and does not accept a name.
2381 The required PROPERTY option is immediately followed by the name
2384 of the property to get. If the property is not set an empty
2385 value is returned. If the SET option is given the variable is
2386 set to a boolean value indicating whether the property has been
2387 set. If the DEFINED option is given the variable is set to a
2388 boolean value indicating whether the property has been defined
2389 such as with define_property. If BRIEF_DOCS or FULL_DOCS is
2390 given then the variable is set to a string containing documenta‐
2391 tion for the requested property. If documentation is requested
2392 for a property that has not been defined NOTFOUND is returned.
2393 get_source_file_property
2396 Get a property for a source file.
2397 get_source_file_property(VAR file property)
2399 Get a property from a source file. The value of the property is
2401 stored in the variable VAR. If the property is not found, VAR
2402 will be set to "NOTFOUND". Use set_source_files_properties to
2403 set property values. Source file properties usually control how
2404 the file is built. One property that is always there is LOCATION
2405 See also the more general get_property() command.
2408 get_target_property
2411 Get a property from a target.
2412 get_target_property(VAR target property)
2414 Get a property from a target. The value of the property is
2416 stored in the variable VAR. If the property is not found, VAR
2417 will be set to "NOTFOUND". Use set_target_properties to set
2418 property values. Properties are usually used to control how a
2419 target is built, but some query the target instead. This com‐
2420 mand can get properties for any target so far created. The tar‐
2421 gets do not need to be in the current CMakeLists.txt file.
2422 See also the more general get_property() command.
2425 get_test_property
2428 Get a property of the test.
2429 get_test_property(test property VAR)
2431 Get a property from the Test. The value of the property is
2433 stored in the variable VAR. If the property is not found, VAR
2434 will be set to "NOTFOUND". For a list of standard properties you
2435 can type cmake --help-property-list
2436 See also the more general get_property() command.
2439 if Conditionally execute a group of commands.
2442 if(expression)
2444 # then section.
2445 COMMAND1(ARGS ...)
2446 COMMAND2(ARGS ...)
2447 ...
2448 elseif(expression2)
2449 # elseif section.
2450 COMMAND1(ARGS ...)
2451 COMMAND2(ARGS ...)
2452 ...
2453 else(expression)
2454 # else section.
2455 COMMAND1(ARGS ...)
2456 COMMAND2(ARGS ...)
2457 ...
2458 endif(expression)
2459 Evaluates the given expression. If the result is true, the com‐
2461 mands in the THEN section are invoked. Otherwise, the commands
2462 in the else section are invoked. The elseif and else sections
2463 are optional. You may have multiple elseif clauses. Note that
2464 the expression in the else and endif clause is optional. Long
2465 expressions can be used and there is a traditional order of
2466 precedence. Parenthetical expressions are evaluated first fol‐
2467 lowed by unary operators such as EXISTS, COMMAND, and DEFINED.
2468 Then any EQUAL, LESS, GREATER, STRLESS, STRGREATER, STREQUAL,
2469 MATCHES will be evaluated. Then NOT operators and finally AND,
2470 OR operators will be evaluated. Possible expressions are:
2471 if(<constant>)
2474 True if the constant is 1, ON, YES, TRUE, Y, or a non-zero num‐
2476 ber. False if the constant is 0, OFF, NO, FALSE, N, IGNORE, "",
2477 or ends in the suffix '-NOTFOUND'. Named boolean constants are
2478 case-insensitive. If the argument is not one of these con‐
2479 stants, it is treated as a variable:
2480 if(<variable>)
2483 True if the variable is defined to a value that is not a false
2485 constant. False otherwise.
2486 if(NOT <expression>)
2489 True if the expression is not true.
2491 if(<expr1> AND <expr2>)
2494 True if both expressions would be considered true individually.
2496 if(<expr1> OR <expr2>)
2499 True if either expression would be considered true individually.
2501 if(COMMAND command-name)
2504 True if the given name is a command, macro or function that can
2506 be invoked.
2507 if(POLICY policy-id)
2510 True if the given name is an existing policy (of the form
2512 CMP<NNNN>).
2513 if(TARGET target-name)
2516 True if the given name is an existing target, built or imported.
2518 if(EXISTS file-name)
2521 if(EXISTS directory-name)
2522 True if the named file or directory exists. Behavior is
2524 well-defined only for full paths.
2525 if(file1 IS_NEWER_THAN file2)
2528 True if file1 is newer than file2 or if one of the two files
2530 doesn't exist. Behavior is well-defined only for full paths.
2531 if(IS_DIRECTORY directory-name)
2534 True if the given name is a directory. Behavior is well-defined
2536 only for full paths.
2537 if(IS_SYMLINK file-name)
2540 True if the given name is a symbolic link. Behavior is
2542 well-defined only for full paths.
2543 if(IS_ABSOLUTE path)
2546 True if the given path is an absolute path.
2548 if(<variable|string> MATCHES regex)
2551 True if the given string or variable's value matches the given
2553 regular expression.
2554 if(<variable|string> LESS <variable|string>)
2557 if(<variable|string> GREATER <variable|string>)
2558 if(<variable|string> EQUAL <variable|string>)
2559 True if the given string or variable's value is a valid number
2561 and the inequality or equality is true.
2562 if(<variable|string> STRLESS <variable|string>)
2565 if(<variable|string> STRGREATER <variable|string>)
2566 if(<variable|string> STREQUAL <variable|string>)
2567 True if the given string or variable's value is lexicographi‐
2569 cally less (or greater, or equal) than the string or variable on
2570 the right.
2571 if(<variable|string> VERSION_LESS <variable|string>)
2574 if(<variable|string> VERSION_EQUAL <variable|string>)
2575 if(<variable|string> VERSION_GREATER <variable|string>)
2576 Component-wise integer version number comparison (version format
2578 is major[.minor[.patch[.tweak]]]).
2579 if(DEFINED <variable>)
2582 True if the given variable is defined. It does not matter if the
2584 variable is true or false just if it has been set.
2585 if((expression) AND (expression OR (expression)))
2588 The expressions inside the parenthesis are evaluated first and
2590 then the remaining expression is evaluated as in the previous
2591 examples. Where there are nested parenthesis the innermost are
2592 evaluated as part of evaluating the expression that contains
2593 them.
2594 The if command was written very early in CMake's history, pre‐
2597 dating the ${} variable evaluation syntax, and for convenience
2598 evaluates variables named by its arguments as shown in the above
2599 signatures. Note that normal variable evaluation with ${}
2600 applies before the if command even receives the arguments.
2601 Therefore code like
2602 set(var1 OFF)
2605 set(var2 "var1")
2606 if(${var2})
2607 appears to the if command as
2609 if(var1)
2612 and is evaluated according to the if(<variable>) case documented
2614 above. The result is OFF which is false. However, if we remove
2615 the ${} from the example then the command sees
2616 if(var2)
2619 which is true because var2 is defined to "var1" which is not a
2621 false constant.
2622 Automatic evaluation applies in the other cases whenever the
2625 above-documented signature accepts <variable|string>:
2626 1) The left hand argument to MATCHES is first checked to see if
2629 it is a defined variable, if so the variable's value is used,
2630 otherwise the original value is used.
2631 2) If the left hand argument to MATCHES is missing it returns
2634 false without error
2635 3) Both left and right hand arguments to LESS GREATER EQUAL are
2638 independently tested to see if they are defined variables, if so
2639 their defined values are used otherwise the original value is
2640 used.
2641 4) Both left and right hand arguments to STRLESS STREQUAL STR‐
2644 GREATER are independently tested to see if they are defined
2645 variables, if so their defined values are used otherwise the
2646 original value is used.
2647 5) Both left and right hand argumemnts to VERSION_LESS VER‐
2650 SION_EQUAL VERSION_GREATER are independently tested to see if
2651 they are defined variables, if so their defined values are used
2652 otherwise the original value is used.
2653 6) The right hand argument to NOT is tested to see if it is a
2656 boolean constant, if so the value is used, otherwise it is
2657 assumed to be a variable and it is dereferenced.
2658 7) The left and right hand arguments to AND OR are independently
2661 tested to see if they are boolean constants, if so they are used
2662 as such, otherwise they are assumed to be variables and are
2663 dereferenced.
2664 include
2668 Read CMake listfile code from the given file.
2669 include(<file|module> [OPTIONAL] [RESULT_VARIABLE <VAR>]
2671 [NO_POLICY_SCOPE])
2672 Reads CMake listfile code from the given file. Commands in the
2674 file are processed immediately as if they were written in place
2675 of the include command. If OPTIONAL is present, then no error
2676 is raised if the file does not exist. If RESULT_VARIABLE is
2677 given the variable will be set to the full filename which has
2678 been included or NOTFOUND if it failed.
2679 If a module is specified instead of a file, the file with name
2682 <modulename>.cmake is searched first in CMAKE_MODULE_PATH, then
2683 in the CMake module directory. There is one exception to this:
2684 if the file which calls include() is located itself in the CMake
2685 module directory, then first the CMake module directory is
2686 searched and CMAKE_MODULE_PATH afterwards. See also policy
2687 CMP0017.
2688 See the cmake_policy() command documentation for discussion of
2691 the NO_POLICY_SCOPE option.
2692 include_directories
2695 Add include directories to the build.
2696 include_directories([AFTER|BEFORE] [SYSTEM] dir1 dir2 ...)
2698 Add the given directories to those searched by the compiler for
2700 include files. By default the directories are appended onto the
2701 current list of directories. This default behavior can be
2702 changed by setting CMAKE_include_directories_BEFORE to ON. By
2703 using BEFORE or AFTER you can select between appending and
2704 prepending, independent from the default. If the SYSTEM option
2705 is given the compiler will be told that the directories are
2706 meant as system include directories on some platforms.
2707 include_external_msproject
2710 Include an external Microsoft project file in a workspace.
2711 include_external_msproject(projectname location
2713 dep1 dep2 ...)
2714 Includes an external Microsoft project in the generated
2716 workspace file. Currently does nothing on UNIX. This will cre‐
2717 ate a target named [projectname]. This can be used in the
2718 add_dependencies command to make things depend on the external
2719 project.
2720 include_regular_expression
2723 Set the regular expression used for dependency checking.
2724 include_regular_expression(regex_match [regex_complain])
2726 Set the regular expressions used in dependency checking. Only
2728 files matching regex_match will be traced as dependencies. Only
2729 files matching regex_complain will generate warnings if they
2730 cannot be found (standard header paths are not searched). The
2731 defaults are:
2732 regex_match = "^.*$" (match everything)
2735 regex_complain = "^$" (match empty string only)
2736 install
2739 Specify rules to run at install time.
2740 This command generates installation rules for a project. Rules
2742 specified by calls to this command within a source directory are
2743 executed in order during installation. The order across direc‐
2744 tories is not defined.
2745 There are multiple signatures for this command. Some of them
2748 define installation properties for files and targets. Proper‐
2749 ties common to multiple signatures are covered here but they are
2750 valid only for signatures that specify them.
2751 DESTINATION arguments specify the directory on disk to which a
2754 file will be installed. If a full path (with a leading slash or
2755 drive letter) is given it is used directly. If a relative path
2756 is given it is interpreted relative to the value of
2757 CMAKE_INSTALL_PREFIX.
2758 PERMISSIONS arguments specify permissions for installed files.
2761 Valid permissions are OWNER_READ, OWNER_WRITE, OWNER_EXECUTE,
2762 GROUP_READ, GROUP_WRITE, GROUP_EXECUTE, WORLD_READ, WORLD_WRITE,
2763 WORLD_EXECUTE, SETUID, and SETGID. Permissions that do not make
2764 sense on certain platforms are ignored on those platforms.
2765 The CONFIGURATIONS argument specifies a list of build configura‐
2768 tions for which the install rule applies (Debug, Release, etc.).
2769 The COMPONENT argument specifies an installation component name
2772 with which the install rule is associated, such as "runtime" or
2773 "development". During component-specific installation only
2774 install rules associated with the given component name will be
2775 executed. During a full installation all components are
2776 installed.
2777 The RENAME argument specifies a name for an installed file that
2780 may be different from the original file. Renaming is allowed
2781 only when a single file is installed by the command.
2782 The OPTIONAL argument specifies that it is not an error if the
2785 file to be installed does not exist.
2786 The TARGETS signature:
2789 install(TARGETS targets... [EXPORT <export-name>]
2792 [[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE|
2793 PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
2794 [DESTINATION <dir>]
2795 [PERMISSIONS permissions...]
2796 [CONFIGURATIONS [Debug|Release|...]]
2797 [COMPONENT <component>]
2798 [OPTIONAL] [NAMELINK_ONLY|NAMELINK_SKIP]
2799 ] [...])
2800 The TARGETS form specifies rules for installing targets from a
2802 project. There are five kinds of target files that may be
2803 installed: ARCHIVE, LIBRARY, RUNTIME, FRAMEWORK, and BUNDLE.
2804 Executables are treated as RUNTIME targets, except that those
2805 marked with the MACOSX_BUNDLE property are treated as BUNDLE
2806 targets on OS X. Static libraries are always treated as ARCHIVE
2807 targets. Module libraries are always treated as LIBRARY targets.
2808 For non-DLL platforms shared libraries are treated as LIBRARY
2809 targets, except that those marked with the FRAMEWORK property
2810 are treated as FRAMEWORK targets on OS X. For DLL platforms the
2811 DLL part of a shared library is treated as a RUNTIME target and
2812 the corresponding import library is treated as an ARCHIVE tar‐
2813 get. All Windows-based systems including Cygwin are DLL plat‐
2814 forms. The ARCHIVE, LIBRARY, RUNTIME, and FRAMEWORK arguments
2815 change the type of target to which the subsequent properties
2816 apply. If none is given the installation properties apply to
2817 all target types. If only one is given then only targets of
2818 that type will be installed (which can be used to install just a
2819 DLL or just an import library).
2820 The PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE arguments cause
2823 subsequent properties to be applied to installing a FRAMEWORK
2824 shared library target's associated files on non-Apple platforms.
2825 Rules defined by these arguments are ignored on Apple platforms
2826 because the associated files are installed into the appropriate
2827 locations inside the framework folder. See documentation of the
2828 PRIVATE_HEADER, PUBLIC_HEADER, and RESOURCE target properties
2829 for details.
2830 Either NAMELINK_ONLY or NAMELINK_SKIP may be specified as a
2833 LIBRARY option. On some platforms a versioned shared library
2834 has a symbolic link such as
2835 lib<name>.so -> lib<name>.so.1
2838 where "lib<name>.so.1" is the soname of the library and
2840 "lib<name>.so" is a "namelink" allowing linkers to find the
2841 library when given "-l<name>". The NAMELINK_ONLY option causes
2842 installation of only the namelink when a library target is
2843 installed. The NAMELINK_SKIP option causes installation of
2844 library files other than the namelink when a library target is
2845 installed. When neither option is given both portions are
2846 installed. On platforms where versioned shared libraries do not
2847 have namelinks or when a library is not versioned the
2848 NAMELINK_SKIP option installs the library and the NAMELINK_ONLY
2849 option installs nothing. See the VERSION and SOVERSION target
2850 properties for details on creating versioned shared libraries.
2851 One or more groups of properties may be specified in a single
2854 call to the TARGETS form of this command. A target may be
2855 installed more than once to different locations. Consider hypo‐
2856 thetical targets "myExe", "mySharedLib", and "myStaticLib". The
2857 code
2858 install(TARGETS myExe mySharedLib myStaticLib
2861 RUNTIME DESTINATION bin
2862 LIBRARY DESTINATION lib
2863 ARCHIVE DESTINATION lib/static)
2864 install(TARGETS mySharedLib DESTINATION /some/full/path)
2865 will install myExe to <prefix>/bin and myStaticLib to <pre‐
2867 fix>/lib/static. On non-DLL platforms mySharedLib will be
2868 installed to <prefix>/lib and /some/full/path. On DLL platforms
2869 the mySharedLib DLL will be installed to <prefix>/bin and
2870 /some/full/path and its import library will be installed to
2871 <prefix>/lib/static and /some/full/path. On non-DLL platforms
2872 mySharedLib will be installed to <prefix>/lib and
2873 /some/full/path.
2874 The EXPORT option associates the installed target files with an
2877 export called <export-name>. It must appear before any RUNTIME,
2878 LIBRARY, or ARCHIVE options. To actually install the export
2879 file itself, call install(EXPORT). See documentation of the
2880 install(EXPORT ...) signature below for details.
2881 Installing a target with EXCLUDE_FROM_ALL set to true has unde‐
2884 fined behavior.
2885 The FILES signature:
2888 install(FILES files... DESTINATION <dir>
2891 [PERMISSIONS permissions...]
2892 [CONFIGURATIONS [Debug|Release|...]]
2893 [COMPONENT <component>]
2894 [RENAME <name>] [OPTIONAL])
2895 The FILES form specifies rules for installing files for a
2897 project. File names given as relative paths are interpreted
2898 with respect to the current source directory. Files installed
2899 by this form are by default given permissions OWNER_WRITE,
2900 OWNER_READ, GROUP_READ, and WORLD_READ if no PERMISSIONS argu‐
2901 ment is given.
2902 The PROGRAMS signature:
2905 install(PROGRAMS files... DESTINATION <dir>
2908 [PERMISSIONS permissions...]
2909 [CONFIGURATIONS [Debug|Release|...]]
2910 [COMPONENT <component>]
2911 [RENAME <name>] [OPTIONAL])
2912 The PROGRAMS form is identical to the FILES form except that the
2914 default permissions for the installed file also include
2915 OWNER_EXECUTE, GROUP_EXECUTE, and WORLD_EXECUTE. This form is
2916 intended to install programs that are not targets, such as shell
2917 scripts. Use the TARGETS form to install targets built within
2918 the project.
2919 The DIRECTORY signature:
2922 install(DIRECTORY dirs... DESTINATION <dir>
2925 [FILE_PERMISSIONS permissions...]
2926 [DIRECTORY_PERMISSIONS permissions...]
2927 [USE_SOURCE_PERMISSIONS] [OPTIONAL]
2928 [CONFIGURATIONS [Debug|Release|...]]
2929 [COMPONENT <component>] [FILES_MATCHING]
2930 [[PATTERN <pattern> | REGEX <regex>]
2931 [EXCLUDE] [PERMISSIONS permissions...]] [...])
2932 The DIRECTORY form installs contents of one or more directories
2934 to a given destination. The directory structure is copied ver‐
2935 batim to the destination. The last component of each directory
2936 name is appended to the destination directory but a trailing
2937 slash may be used to avoid this because it leaves the last com‐
2938 ponent empty. Directory names given as relative paths are
2939 interpreted with respect to the current source directory. If no
2940 input directory names are given the destination directory will
2941 be created but nothing will be installed into it. The FILE_PER‐
2942 MISSIONS and DIRECTORY_PERMISSIONS options specify permissions
2943 given to files and directories in the destination. If
2944 USE_SOURCE_PERMISSIONS is specified and FILE_PERMISSIONS is not,
2945 file permissions will be copied from the source directory struc‐
2946 ture. If no permissions are specified files will be given the
2947 default permissions specified in the FILES form of the command,
2948 and the directories will be given the default permissions speci‐
2949 fied in the PROGRAMS form of the command.
2950 Installation of directories may be controlled with fine granu‐
2953 larity using the PATTERN or REGEX options. These "match"
2954 options specify a globbing pattern or regular expression to
2955 match directories or files encountered within input directories.
2956 They may be used to apply certain options (see below) to a sub‐
2957 set of the files and directories encountered. The full path to
2958 each input file or directory (with forward slashes) is matched
2959 against the expression. A PATTERN will match only complete file
2960 names: the portion of the full path matching the pattern must
2961 occur at the end of the file name and be preceded by a slash. A
2962 REGEX will match any portion of the full path but it may use '/'
2963 and '$' to simulate the PATTERN behavior. By default all files
2964 and directories are installed whether or not they are matched.
2965 The FILES_MATCHING option may be given before the first match
2966 option to disable installation of files (but not directories)
2967 not matched by any expression. For example, the code
2968 install(DIRECTORY src/ DESTINATION include/myproj
2971 FILES_MATCHING PATTERN "*.h")
2972 will extract and install header files from a source tree.
2974 Some options may follow a PATTERN or REGEX expression and are
2977 applied only to files or directories matching them. The EXCLUDE
2978 option will skip the matched file or directory. The PERMISSIONS
2979 option overrides the permissions setting for the matched file or
2980 directory. For example the code
2981 install(DIRECTORY icons scripts/ DESTINATION share/myproj
2984 PATTERN "CVS" EXCLUDE
2985 PATTERN "scripts/*"
2986 PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ
2987 GROUP_EXECUTE GROUP_READ)
2988 will install the icons directory to share/myproj/icons and the
2990 scripts directory to share/myproj. The icons will get default
2991 file permissions, the scripts will be given specific permis‐
2992 sions, and any CVS directories will be excluded.
2993 The SCRIPT and CODE signature:
2996 install([[SCRIPT <file>] [CODE <code>]] [...])
2999 The SCRIPT form will invoke the given CMake script files during
3001 installation. If the script file name is a relative path it
3002 will be interpreted with respect to the current source direc‐
3003 tory. The CODE form will invoke the given CMake code during
3004 installation. Code is specified as a single argument inside a
3005 double-quoted string. For example, the code
3006 install(CODE "MESSAGE(\"Sample install message.\")")
3009 will print a message during installation.
3011 The EXPORT signature:
3014 install(EXPORT <export-name> DESTINATION <dir>
3017 [NAMESPACE <namespace>] [FILE <name>.cmake]
3018 [PERMISSIONS permissions...]
3019 [CONFIGURATIONS [Debug|Release|...]]
3020 [COMPONENT <component>])
3021 The EXPORT form generates and installs a CMake file containing
3023 code to import targets from the installation tree into another
3024 project. Target installations are associated with the export
3025 <export-name> using the EXPORT option of the install(TARGETS
3026 ...) signature documented above. The NAMESPACE option will
3027 prepend <namespace> to the target names as they are written to
3028 the import file. By default the generated file will be called
3029 <export-name>.cmake but the FILE option may be used to specify a
3030 different name. The value given to the FILE option must be a
3031 file name with the ".cmake" extension. If a CONFIGURATIONS
3032 option is given then the file will only be installed when one of
3033 the named configurations is installed. Additionally, the gener‐
3034 ated import file will reference only the matching target config‐
3035 urations. If a COMPONENT option is specified that does not
3036 match that given to the targets associated with <export-name>
3037 the behavior is undefined. If a library target is included in
3038 the export but a target to which it links is not included the
3039 behavior is unspecified.
3040 The EXPORT form is useful to help outside projects use targets
3043 built and installed by the current project. For example, the
3044 code
3045 install(TARGETS myexe EXPORT myproj DESTINATION bin)
3048 install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
3049 will install the executable myexe to <prefix>/bin and code to
3051 import it in the file "<prefix>/lib/myproj/myproj.cmake". An
3052 outside project may load this file with the include command and
3053 reference the myexe executable from the installation tree using
3054 the imported target name mp_myexe as if the target were built in
3055 its own tree.
3056 NOTE: This command supercedes the INSTALL_TARGETS command and
3059 the target properties PRE_INSTALL_SCRIPT and
3060 POST_INSTALL_SCRIPT. It also replaces the FILES forms of the
3061 INSTALL_FILES and INSTALL_PROGRAMS commands. The processing
3062 order of these install rules relative to those generated by
3063 INSTALL_TARGETS, INSTALL_FILES, and INSTALL_PROGRAMS commands is
3064 not defined.
3065 link_directories
3069 Specify directories in which the linker will look for libraries.
3070 link_directories(directory1 directory2 ...)
3072 Specify the paths in which the linker should search for
3074 libraries. The command will apply only to targets created after
3075 it is called. For historical reasons, relative paths given to
3076 this command are passed to the linker unchanged (unlike many
3077 CMake commands which interpret them relative to the current
3078 source directory).
3079 list List operations.
3082 list(LENGTH <list> <output variable>)
3084 list(GET <list> <element index> [<element index> ...]
3085 <output variable>)
3086 list(APPEND <list> <element> [<element> ...])
3087 list(FIND <list> <value> <output variable>)
3088 list(INSERT <list> <element_index> <element> [<element> ...])
3089 list(REMOVE_ITEM <list> <value> [<value> ...])
3090 list(REMOVE_AT <list> <index> [<index> ...])
3091 list(REMOVE_DUPLICATES <list>)
3092 list(REVERSE <list>)
3093 list(SORT <list>)
3094 LENGTH will return a given list's length.
3096 GET will return list of elements specified by indices from the
3099 list.
3100 APPEND will append elements to the list.
3103 FIND will return the index of the element specified in the list
3106 or -1 if it wasn't found.
3107 INSERT will insert elements to the list to the specified loca‐
3110 tion.
3111 REMOVE_AT and REMOVE_ITEM will remove items from the list. The
3114 difference is that REMOVE_ITEM will remove the given items,
3115 while REMOVE_AT will remove the items at the given indices.
3116 REMOVE_DUPLICATES will remove duplicated items in the list.
3119 REVERSE reverses the contents of the list in-place.
3122 SORT sorts the list in-place alphabetically.
3125 NOTES: A list in cmake is a ; separated group of strings. To
3128 create a list the set command can be used. For example, set(var
3129 a b c d e) creates a list with a;b;c;d;e, and set(var "a b c d
3130 e") creates a string or a list with one item in it.
3131 When specifying index values, if <element index> is 0 or
3134 greater, it is indexed from the beginning of the list, with 0
3135 representing the first list element. If <element index> is -1 or
3136 lesser, it is indexed from the end of the list, with -1 repre‐
3137 senting the last list element. Be careful when counting with
3138 negative indices: they do not start from 0. -0 is equivalent to
3139 0, the first list element.
3140 load_cache
3144 Load in the values from another project's CMake cache.
3145 load_cache(pathToCacheFile READ_WITH_PREFIX
3147 prefix entry1...)
3148 Read the cache and store the requested entries in variables with
3150 their name prefixed with the given prefix. This only reads the
3151 values, and does not create entries in the local project's
3152 cache.
3153 load_cache(pathToCacheFile [EXCLUDE entry1...]
3156 [INCLUDE_INTERNALS entry1...])
3157 Load in the values from another cache and store them in the
3159 local project's cache as internal entries. This is useful for a
3160 project that depends on another project built in a different
3161 tree. EXCLUDE option can be used to provide a list of entries
3162 to be excluded. INCLUDE_INTERNALS can be used to provide a list
3163 of internal entries to be included. Normally, no internal
3164 entries are brought in. Use of this form of the command is
3165 strongly discouraged, but it is provided for backward compati‐
3166 bility.
3167 load_command
3170 Load a command into a running CMake.
3171 load_command(COMMAND_NAME <loc1> [loc2 ...])
3173 The given locations are searched for a library whose name is
3175 cmCOMMAND_NAME. If found, it is loaded as a module and the com‐
3176 mand is added to the set of available CMake commands. Usually,
3177 TRY_COMPILE is used before this command to compile the module.
3178 If the command is successfully loaded a variable named
3179 CMAKE_LOADED_COMMAND_<COMMAND_NAME>
3182 will be set to the full path of the module that was loaded.
3184 Otherwise the variable will not be set.
3185 macro Start recording a macro for later invocation as a command.
3188 macro(<name> [arg1 [arg2 [arg3 ...]]])
3190 COMMAND1(ARGS ...)
3191 COMMAND2(ARGS ...)
3192 ...
3193 endmacro(<name>)
3194 Define a macro named <name> that takes arguments named arg1 arg2
3196 arg3 (...). Commands listed after macro, but before the match‐
3197 ing endmacro, are not invoked until the macro is invoked. When
3198 it is invoked, the commands recorded in the macro are first mod‐
3199 ified by replacing formal parameters (${arg1}) with the argu‐
3200 ments passed, and then invoked as normal commands. In addition
3201 to referencing the formal parameters you can reference the val‐
3202 ues ${ARGC} which will be set to the number of arguments passed
3203 into the function as well as ${ARGV0} ${ARGV1} ${ARGV2} ...
3204 which will have the actual values of the arguments passed in.
3205 This facilitates creating macros with optional arguments. Addi‐
3206 tionally ${ARGV} holds the list of all arguments given to the
3207 macro and ${ARGN} holds the list of argument past the last
3208 expected argument. Note that the parameters to a macro and val‐
3209 ues such as ARGN are not variables in the usual CMake sense.
3210 They are string replacements much like the c preprocessor would
3211 do with a macro. If you want true CMake variables you should
3212 look at the function command.
3213 See the cmake_policy() command documentation for the behavior of
3216 policies inside macros.
3217 mark_as_advanced
3220 Mark cmake cached variables as advanced.
3221 mark_as_advanced([CLEAR|FORCE] VAR VAR2 VAR...)
3223 Mark the named cached variables as advanced. An advanced vari‐
3225 able will not be displayed in any of the cmake GUIs unless the
3226 show advanced option is on. If CLEAR is the first argument
3227 advanced variables are changed back to unadvanced. If FORCE is
3228 the first argument, then the variable is made advanced. If nei‐
3229 ther FORCE nor CLEAR is specified, new values will be marked as
3230 advanced, but if the variable already has an
3231 advanced/non-advanced state, it will not be changed.
3232 It does nothing in script mode.
3235 math Mathematical expressions.
3238 math(EXPR <output variable> <math expression>)
3240 EXPR evaluates mathematical expression and return result in the
3242 output variable. Example mathematical expression is '5 * ( 10 +
3243 13 )'. Supported operators are + - * / % | & ^ ~ << >> * / %.
3244 They have the same meaning as they do in c code.
3245 message
3248 Display a message to the user.
3249 message([STATUS|WARNING|AUTHOR_WARNING|FATAL_ERROR|SEND_ERROR]
3251 "message to display" ...)
3252 The optional keyword determines the type of message:
3254 (none) = Important information
3257 STATUS = Incidental information
3258 WARNING = CMake Warning, continue processing
3259 AUTHOR_WARNING = CMake Warning (dev), continue processing
3260 SEND_ERROR = CMake Error, continue but skip generation
3261 FATAL_ERROR = CMake Error, stop all processing
3262 The CMake command-line tool displays STATUS messages on stdout
3264 and all other message types on stderr. The CMake GUI displays
3265 all messages in its log area. The interactive dialogs (ccmake
3266 and CMakeSetup) show STATUS messages one at a time on a status
3267 line and other messages in interactive pop-up boxes.
3268 CMake Warning and Error message text displays using a simple
3271 markup language. Non-indented text is formatted in line-wrapped
3272 paragraphs delimited by newlines. Indented text is considered
3273 pre-formatted.
3274 option Provides an option that the user can optionally select.
3277 option(<option_variable> "help string describing option"
3279 [initial value])
3280 Provide an option for the user to select as ON or OFF. If no
3282 initial value is provided, OFF is used.
3283 If you have options that depend on the values of other options,
3286 see the module help for CMakeDependentOption.
3287 output_required_files
3290 Output a list of required source files for a specified source
3291 file.
3292 output_required_files(srcfile outputfile)
3294 Outputs a list of all the source files that are required by the
3296 specified srcfile. This list is written into outputfile. This is
3297 similar to writing out the dependencies for srcfile except that
3298 it jumps from .h files into .cxx, .c and .cpp files if possible.
3299 project
3302 Set a name for the entire project.
3303 project(<projectname> [languageName1 languageName2 ... ] )
3305 Sets the name of the project. Additionally this sets the vari‐
3307 ables <projectName>_BINARY_DIR and <projectName>_SOURCE_DIR to
3308 the respective values.
3309 Optionally you can specify which languages your project sup‐
3312 ports. Example languages are CXX (i.e. C++), C, Fortran, etc.
3313 By default C and CXX are enabled. E.g. if you do not have a C++
3314 compiler, you can disable the check for it by explicitly listing
3315 the languages you want to support, e.g. C. By using the special
3316 language "NONE" all checks for any language can be disabled.
3317 qt_wrap_cpp
3320 Create Qt Wrappers.
3321 qt_wrap_cpp(resultingLibraryName DestName
3323 SourceLists ...)
3324 Produce moc files for all the .h files listed in the
3326 SourceLists. The moc files will be added to the library using
3327 the DestName source list.
3328 qt_wrap_ui
3331 Create Qt user interfaces Wrappers.
3332 qt_wrap_ui(resultingLibraryName HeadersDestName
3334 SourcesDestName SourceLists ...)
3335 Produce .h and .cxx files for all the .ui files listed in the
3337 SourceLists. The .h files will be added to the library using
3338 the HeadersDestNamesource list. The .cxx files will be added to
3339 the library using the SourcesDestNamesource list.
3340 remove_definitions
3343 Removes -D define flags added by add_definitions.
3344 remove_definitions(-DFOO -DBAR ...)
3346 Removes flags (added by add_definitions) from the compiler com‐
3348 mand line for sources in the current directory and below.
3349 return Return from a file, directory or function.
3352 return()
3354 Returns from a file, directory or function. When this command is
3356 encountered in an included file (via include() or find_pack‐
3357 age()), it causes processing of the current file to stop and
3358 control is returned to the including file. If it is encountered
3359 in a file which is not included by another file, e.g. a CMake‐
3360 Lists.txt, control is returned to the parent directory if there
3361 is one. If return is called in a function, control is returned
3362 to the caller of the function. Note that a macro is not a func‐
3363 tion and does not handle return like a function does.
3364 separate_arguments
3367 Parse space-separated arguments into a semicolon-separated list.
3368 separate_arguments(<var> <UNIX|WINDOWS>_COMMAND "<args>")
3370 Parses a unix- or windows-style command-line string "<args>" and
3372 stores a semicolon-separated list of the arguments in <var>.
3373 The entire command line must be given in one "<args>" argument.
3374 The UNIX_COMMAND mode separates arguments by unquoted white‐
3377 space. It recognizes both single-quote and double-quote pairs.
3378 A backslash escapes the next literal character (\" is "); there
3379 are no special escapes (\n is just n).
3380 The WINDOWS_COMMAND mode parses a windows command-line using the
3383 same syntax the runtime library uses to construct argv at
3384 startup. It separates arguments by whitespace that is not dou‐
3385 ble-quoted. Backslashes are literal unless they precede dou‐
3386 ble-quotes. See the MSDN article "Parsing C Command-Line Argu‐
3387 ments" for details.
3388 separate_arguments(VARIABLE)
3391 Convert the value of VARIABLE to a semi-colon separated list.
3393 All spaces are replaced with ';'. This helps with generating
3394 command lines.
3395 set Set a CMAKE variable to a given value.
3398 set(<variable> <value>
3400 [[CACHE <type> <docstring> [FORCE]] | PARENT_SCOPE])
3401 Within CMake sets <variable> to the value <value>. <value> is
3403 expanded before <variable> is set to it. If CACHE is present,
3404 then the <variable> is put in the cache. <type> and <docstring>
3405 are then required. <type> is used by the CMake GUI to choose a
3406 widget with which the user sets a value. The value for <type>
3407 may be one of
3408 FILEPATH = File chooser dialog.
3411 PATH = Directory chooser dialog.
3412 STRING = Arbitrary string.
3413 BOOL = Boolean ON/OFF checkbox.
3414 INTERNAL = No GUI entry (used for persistent variables).
3415 If <type> is INTERNAL, then the <value> is always written into
3417 the cache, replacing any values existing in the cache. If it is
3418 not a cache variable, then this always writes into the current
3419 makefile. The FORCE option will overwrite the cache value remov‐
3420 ing any changes by the user.
3421 If PARENT_SCOPE is present, the variable will be set in the
3424 scope above the current scope. Each new directory or function
3425 creates a new scope. This command will set the value of a vari‐
3426 able into the parent directory or calling function (whichever is
3427 applicable to the case at hand).
3428 If <value> is not specified then the variable is removed instead
3431 of set. See also: the unset() command.
3432 set(<variable> <value1> ... <valueN>)
3435 In this case <variable> is set to a semicolon separated list of
3437 values.
3438 <variable> can be an environment variable such as:
3441 set( ENV{PATH} /home/martink )
3444 in which case the environment variable will be set.
3446 set_directory_properties
3449 Set a property of the directory.
3450 set_directory_properties(PROPERTIES prop1 value1 prop2 value2)
3452 Set a property for the current directory and subdirectories. If
3454 the property is not found, CMake will report an error. The prop‐
3455 erties include: INCLUDE_DIRECTORIES, LINK_DIRECTORIES,
3456 INCLUDE_REGULAR_EXPRESSION, and ADDITIONAL_MAKE_CLEAN_FILES.
3457 ADDITIONAL_MAKE_CLEAN_FILES is a list of files that will be
3458 cleaned as a part of "make clean" stage.
3459 set_property
3462 Set a named property in a given scope.
3463 set_property(<GLOBAL |
3465 DIRECTORY [dir] |
3466 TARGET [target1 [target2 ...]] |
3467 SOURCE [src1 [src2 ...]] |
3468 TEST [test1 [test2 ...]] |
3469 CACHE [entry1 [entry2 ...]]>
3470 [APPEND]
3471 PROPERTY <name> [value1 [value2 ...]])
3472 Set one property on zero or more objects of a scope. The first
3474 argument determines the scope in which the property is set. It
3475 must be one of the following:
3476 GLOBAL scope is unique and does not accept a name.
3479 DIRECTORY scope defaults to the current directory but another
3482 directory (already processed by CMake) may be named by full or
3483 relative path.
3484 TARGET scope may name zero or more existing targets.
3487 SOURCE scope may name zero or more source files. Note that
3490 source file properties are visible only to targets added in the
3491 same directory (CMakeLists.txt).
3492 TEST scope may name zero or more existing tests.
3495 CACHE scope must name zero or more cache existing entries.
3498 The required PROPERTY option is immediately followed by the name
3501 of the property to set. Remaining arguments are used to compose
3502 the property value in the form of a semicolon-separated list.
3503 If the APPEND option is given the list is appended to any exist‐
3504 ing property value.
3505 set_source_files_properties
3508 Source files can have properties that affect how they are built.
3509 set_source_files_properties([file1 [file2 [...]]]
3511 PROPERTIES prop1 value1
3512 [prop2 value2 [...]])
3513 Set properties associated with source files using a key/value
3515 paired list. See properties documentation for those known to
3516 CMake. Unrecognized properties are ignored. Source file prop‐
3517 erties are visible only to targets added in the same directory
3518 (CMakeLists.txt).
3519 set_target_properties
3522 Targets can have properties that affect how they are built.
3523 set_target_properties(target1 target2 ...
3525 PROPERTIES prop1 value1
3526 prop2 value2 ...)
3527 Set properties on a target. The syntax for the command is to
3529 list all the files you want to change, and then provide the val‐
3530 ues you want to set next. You can use any prop value pair you
3531 want and extract it later with the GET_TARGET_PROPERTY command.
3532 Properties that affect the name of a target's output file are as
3535 follows. The PREFIX and SUFFIX properties override the default
3536 target name prefix (such as "lib") and suffix (such as ".so").
3537 IMPORT_PREFIX and IMPORT_SUFFIX are the equivalent properties
3538 for the import library corresponding to a DLL (for SHARED
3539 library targets). OUTPUT_NAME sets the real name of a target
3540 when it is built and can be used to help create two targets of
3541 the same name even though CMake requires unique logical target
3542 names. There is also a <CONFIG>_OUTPUT_NAME that can set the
3543 output name on a per-configuration basis. <CONFIG>_POSTFIX sets
3544 a postfix for the real name of the target when it is built under
3545 the configuration named by <CONFIG> (in upper-case, such as
3546 "DEBUG_POSTFIX"). The value of this property is initialized
3547 when the target is created to the value of the variable
3548 CMAKE_<CONFIG>_POSTFIX (except for executable targets because
3549 earlier CMake versions which did not use this variable for exe‐
3550 cutables).
3551 The LINK_FLAGS property can be used to add extra flags to the
3554 link step of a target. LINK_FLAGS_<CONFIG> will add to the con‐
3555 figuration <CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL,
3556 RELWITHDEBINFO. DEFINE_SYMBOL sets the name of the preprocessor
3557 symbol defined when compiling sources in a shared library. If
3558 not set here then it is set to target_EXPORTS by default (with
3559 some substitutions if the target is not a valid C identifier).
3560 This is useful for headers to know whether they are being
3561 included from inside their library our outside to properly setup
3562 dllexport/dllimport decorations. The COMPILE_FLAGS property sets
3563 additional compiler flags used to build sources within the tar‐
3564 get. It may also be used to pass additional preprocessor defi‐
3565 nitions.
3566 The LINKER_LANGUAGE property is used to change the tool used to
3569 link an executable or shared library. The default is set the
3570 language to match the files in the library. CXX and C are common
3571 values for this property.
3572 For shared libraries VERSION and SOVERSION can be used to spec‐
3575 ify the build version and api version respectively. When build‐
3576 ing or installing appropriate symlinks are created if the plat‐
3577 form supports symlinks and the linker supports so-names. If only
3578 one of both is specified the missing is assumed to have the same
3579 version number. For executables VERSION can be used to specify
3580 the build version. When building or installing appropriate sym‐
3581 links are created if the platform supports symlinks. For shared
3582 libraries and executables on Windows the VERSION attribute is
3583 parsed to extract a "major.minor" version number. These numbers
3584 are used as the image version of the binary.
3585 There are a few properties used to specify RPATH rules.
3588 INSTALL_RPATH is a semicolon-separated list specifying the rpath
3589 to use in installed targets (for platforms that support it).
3590 INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to true
3591 will append directories in the linker search path and outside
3592 the project to the INSTALL_RPATH. SKIP_BUILD_RPATH is a boolean
3593 specifying whether to skip automatic generation of an rpath
3594 allowing the target to run from the build tree.
3595 BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link
3596 the target in the build tree with the INSTALL_RPATH. This takes
3597 precedence over SKIP_BUILD_RPATH and avoids the need for relink‐
3598 ing before installation. INSTALL_NAME_DIR is a string specify‐
3599 ing the directory portion of the "install_name" field of shared
3600 libraries on Mac OSX to use in the installed targets. When the
3601 target is created the values of the variables
3602 CMAKE_INSTALL_RPATH, CMAKE_INSTALL_RPATH_USE_LINK_PATH,
3603 CMAKE_SKIP_BUILD_RPATH, CMAKE_BUILD_WITH_INSTALL_RPATH, and
3604 CMAKE_INSTALL_NAME_DIR are used to initialize these properties.
3605 PROJECT_LABEL can be used to change the name of the target in an
3608 IDE like visual studio. VS_KEYWORD can be set to change the
3609 visual studio keyword, for example QT integration works better
3610 if this is set to Qt4VSv1.0.
3611 VS_SCC_PROJECTNAME, VS_SCC_LOCALPATH, VS_SCC_PROVIDER can be set
3614 to add support for source control bindings in a Visual Studio
3615 project file.
3616 The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are
3619 the old way to specify CMake scripts to run before and after
3620 installing a target. They are used only when the old
3621 INSTALL_TARGETS command is used to install the target. Use the
3622 INSTALL command instead.
3623 The EXCLUDE_FROM_DEFAULT_BUILD property is used by the visual
3626 studio generators. If it is set to 1 the target will not be
3627 part of the default build when you select "Build Solution".
3628 set_tests_properties
3631 Set a property of the tests.
3632 set_tests_properties(test1 [test2...] PROPERTIES prop1 value1 prop2 value2)
3634 Set a property for the tests. If the property is not found,
3636 CMake will report an error. The properties include:
3637 WILL_FAIL: If set to true, this will invert the pass/fail flag
3640 of the test.
3641 PASS_REGULAR_EXPRESSION: If set, the test output will be checked
3644 against the specified regular expressions and at least one of
3645 the regular expressions has to match, otherwise the test will
3646 fail.
3647 Example: PASS_REGULAR_EXPRESSION "TestPassed;All ok"
3650 FAIL_REGULAR_EXPRESSION: If set, if the output will match to one
3652 of specified regular expressions, the test will fail.
3653 Example: PASS_REGULAR_EXPRESSION "[^a-z]Error;ERROR;Failed"
3656 Both PASS_REGULAR_EXPRESSION and FAIL_REGULAR_EXPRESSION expect
3658 a list of regular expressions.
3659 TIMEOUT: Setting this will limit the test runtime to the number
3662 of seconds specified.
3663 site_name
3667 Set the given variable to the name of the computer.
3668 site_name(variable)
3670 source_group
3673 Define a grouping for sources in the makefile.
3674 source_group(name [REGULAR_EXPRESSION regex] [FILES src1 src2 ...])
3676 Defines a group into which sources will be placed in project
3678 files. This is mainly used to setup file tabs in Visual Studio.
3679 Any file whose name is listed or matches the regular expression
3680 will be placed in this group. If a file matches multiple
3681 groups, the LAST group that explicitly lists the file will be
3682 favored, if any. If no group explicitly lists the file, the
3683 LAST group whose regular expression matches the file will be
3684 favored.
3685 The name of the group may contain backslashes to specify sub‐
3688 groups:
3689 source_group(outer\\inner ...)
3692 For backwards compatibility, this command is also supports the
3694 format:
3695 source_group(name regex)
3698 string String operations.
3701 string(REGEX MATCH <regular_expression>
3703 <output variable> <input> [<input>...])
3704 string(REGEX MATCHALL <regular_expression>
3705 <output variable> <input> [<input>...])
3706 string(REGEX REPLACE <regular_expression>
3707 <replace_expression> <output variable>
3708 <input> [<input>...])
3709 string(REPLACE <match_string>
3710 <replace_string> <output variable>
3711 <input> [<input>...])
3712 string(COMPARE EQUAL <string1> <string2> <output variable>)
3713 string(COMPARE NOTEQUAL <string1> <string2> <output variable>)
3714 string(COMPARE LESS <string1> <string2> <output variable>)
3715 string(COMPARE GREATER <string1> <string2> <output variable>)
3716 string(ASCII <number> [<number> ...] <output variable>)
3717 string(CONFIGURE <string1> <output variable>
3718 [@ONLY] [ESCAPE_QUOTES])
3719 string(TOUPPER <string1> <output variable>)
3720 string(TOLOWER <string1> <output variable>)
3721 string(LENGTH <string> <output variable>)
3722 string(SUBSTRING <string> <begin> <length> <output variable>)
3723 string(STRIP <string> <output variable>)
3724 string(RANDOM [LENGTH <length>] [ALPHABET <alphabet>]
3725 [RANDOM_SEED <seed>] <output variable>)
3726 REGEX MATCH will match the regular expression once and store the
3728 match in the output variable.
3729 REGEX MATCHALL will match the regular expression as many times
3732 as possible and store the matches in the output variable as a
3733 list.
3734 REGEX REPLACE will match the regular expression as many times as
3737 possible and substitute the replacement expression for the match
3738 in the output. The replace expression may refer to paren-delim‐
3739 ited subexpressions of the match using \1, \2, ..., \9. Note
3740 that two backslashes (\\1) are required in CMake code to get a
3741 backslash through argument parsing.
3742 REPLACE will replace all occurrences of match_string in the
3745 input with replace_string and store the result in the output.
3746 COMPARE EQUAL/NOTEQUAL/LESS/GREATER will compare the strings and
3749 store true or false in the output variable.
3750 ASCII will convert all numbers into corresponding ASCII charac‐
3753 ters.
3754 CONFIGURE will transform a string like CONFIGURE_FILE transforms
3757 a file.
3758 TOUPPER/TOLOWER will convert string to upper/lower characters.
3761 LENGTH will return a given string's length.
3764 SUBSTRING will return a substring of a given string.
3767 STRIP will return a substring of a given string with leading and
3770 trailing spaces removed.
3771 RANDOM will return a random string of given length consisting of
3774 characters from the given alphabet. Default length is 5 charac‐
3775 ters and default alphabet is all numbers and upper and lower
3776 case letters. If an integer RANDOM_SEED is given, its value
3777 will be used to seed the random number generator.
3778 The following characters have special meaning in regular expres‐
3781 sions:
3782 ^ Matches at beginning of a line
3785 $ Matches at end of a line
3786 . Matches any single character
3787 [ ] Matches any character(s) inside the brackets
3788 [^ ] Matches any character(s) not inside the brackets
3789 - Matches any character in range on either side of a dash
3790 * Matches preceding pattern zero or more times
3791 + Matches preceding pattern one or more times
3792 ? Matches preceding pattern zero or once only
3793 | Matches a pattern on either side of the |
3794 () Saves a matched subexpression, which can be referenced
3795 in the REGEX REPLACE operation. Additionally it is saved
3796 by all regular expression-related commands, including
3797 e.g. if( MATCHES ), in the variables CMAKE_MATCH_(0..9).
3798 target_link_libraries
3801 Link a target to given libraries.
3802 target_link_libraries(<target> [item1 [item2 [...]]]
3804 [[debug|optimized|general] <item>] ...)
3805 Specify libraries or flags to use when linking a given target.
3807 The named <target> must have been created in the current direc‐
3808 tory by a command such as add_executable or add_library. The
3809 remaining arguments specify library names or flags.
3810 If a library name matches that of another target in the project
3813 a dependency will automatically be added in the build system to
3814 make sure the library being linked is up-to-date before the tar‐
3815 get links. Item names starting with '-', but not '-l' or
3816 '-framework', are treated as linker flags.
3817 A "debug", "optimized", or "general" keyword indicates that the
3820 library immediately following it is to be used only for the cor‐
3821 responding build configuration. The "debug" keyword corresponds
3822 to the Debug configuration (or to configurations named in the
3823 DEBUG_CONFIGURATIONS global property if it is set). The "opti‐
3824 mized" keyword corresponds to all other configurations. The
3825 "general" keyword corresponds to all configurations, and is
3826 purely optional (assumed if omitted). Higher granularity may be
3827 achieved for per-configuration rules by creating and linking to
3828 IMPORTED library targets. See the IMPORTED mode of the
3829 add_library command for more information.
3830 Library dependencies are transitive by default. When this tar‐
3833 get is linked into another target then the libraries linked to
3834 this target will appear on the link line for the other target
3835 too. See the LINK_INTERFACE_LIBRARIES target property to over‐
3836 ride the set of transitive link dependencies for a target.
3837 target_link_libraries(<target> LINK_INTERFACE_LIBRARIES
3840 [[debug|optimized|general] <lib>] ...)
3841 The LINK_INTERFACE_LIBRARIES mode appends the libraries to the
3843 LINK_INTERFACE_LIBRARIES and its per-configuration equivalent
3844 target properties instead of using them for linking. Libraries
3845 specified as "debug" are appended to the the LINK_INTER‐
3846 FACE_LIBRARIES_DEBUG property (or to the properties correspond‐
3847 ing to configurations listed in the DEBUG_CONFIGURATIONS global
3848 property if it is set). Libraries specified as "optimized" are
3849 appended to the the LINK_INTERFACE_LIBRARIES property.
3850 Libraries specified as "general" (or without any keyword) are
3851 treated as if specified for both "debug" and "optimized".
3852 The library dependency graph is normally acyclic (a DAG), but in
3855 the case of mutually-dependent STATIC libraries CMake allows the
3856 graph to contain cycles (strongly connected components). When
3857 another target links to one of the libraries CMake repeats the
3858 entire connected component. For example, the code
3859 add_library(A STATIC a.c)
3862 add_library(B STATIC b.c)
3863 target_link_libraries(A B)
3864 target_link_libraries(B A)
3865 add_executable(main main.c)
3866 target_link_libraries(main A)
3867 links 'main' to 'A B A B'. (While one repetition is usually
3869 sufficient, pathological object file and symbol arrangements can
3870 require more. One may handle such cases by manually repeating
3871 the component in the last target_link_libraries call. However,
3872 if two archives are really so interdependent they should proba‐
3873 bly be combined into a single archive.)
3874 try_compile
3877 Try building some code.
3878 try_compile(RESULT_VAR <bindir> <srcdir>
3880 <projectName> [targetName] [CMAKE_FLAGS flags...]
3881 [OUTPUT_VARIABLE <var>])
3882 Try building a project. In this form, srcdir should contain a
3884 complete CMake project with a CMakeLists.txt file and all
3885 sources. The bindir and srcdir will not be deleted after this
3886 command is run. Specify targetName to build a specific target
3887 instead of the 'all' or 'ALL_BUILD' target.
3888 try_compile(RESULT_VAR <bindir> <srcfile>
3891 [CMAKE_FLAGS flags...]
3892 [COMPILE_DEFINITIONS flags...]
3893 [OUTPUT_VARIABLE <var>]
3894 [COPY_FILE <fileName>])
3895 Try building a source file into an executable. In this form the
3897 user need only supply a source file that defines a 'main'.
3898 CMake will create a CMakeLists.txt file to build the source as
3899 an executable. Specify COPY_FILE to get a copy of the linked
3900 executable at the given fileName.
3901 In this version all files in bindir/CMakeFiles/CMakeTmp, will be
3904 cleaned automatically, for debugging a --debug-trycompile can be
3905 passed to cmake to avoid the clean. Some extra flags that can
3906 be included are, INCLUDE_DIRECTORIES, LINK_DIRECTORIES, and
3907 LINK_LIBRARIES. COMPILE_DEFINITIONS are -Ddefinition that will
3908 be passed to the compile line. try_compile creates a CMake‐
3909 List.txt file on the fly that looks like this:
3910 add_definitions( <expanded COMPILE_DEFINITIONS from calling cmake>)
3913 include_directories(${INCLUDE_DIRECTORIES})
3914 link_directories(${LINK_DIRECTORIES})
3915 add_executable(cmTryCompileExec sources)
3916 target_link_libraries(cmTryCompileExec ${LINK_LIBRARIES})
3917 In both versions of the command, if OUTPUT_VARIABLE is speci‐
3919 fied, then the output from the build process is stored in the
3920 given variable. Return the success or failure in RESULT_VAR.
3921 CMAKE_FLAGS can be used to pass -DVAR:TYPE=VALUE flags to the
3922 cmake that is run during the build. Set variable CMAKE_TRY_COM‐
3923 PILE_CONFIGURATION to choose a build configuration.
3924 try_run
3927 Try compiling and then running some code.
3928 try_run(RUN_RESULT_VAR COMPILE_RESULT_VAR
3930 bindir srcfile [CMAKE_FLAGS <Flags>]
3931 [COMPILE_DEFINITIONS <flags>]
3932 [COMPILE_OUTPUT_VARIABLE comp]
3933 [RUN_OUTPUT_VARIABLE run]
3934 [OUTPUT_VARIABLE var]
3935 [ARGS <arg1> <arg2>...])
3936 Try compiling a srcfile. Return TRUE or FALSE for success or
3938 failure in COMPILE_RESULT_VAR. Then if the compile succeeded,
3939 run the executable and return its exit code in RUN_RESULT_VAR.
3940 If the executable was built, but failed to run, then
3941 RUN_RESULT_VAR will be set to FAILED_TO_RUN. COMPILE_OUT‐
3942 PUT_VARIABLE specifies the variable where the output from the
3943 compile step goes. RUN_OUTPUT_VARIABLE specifies the variable
3944 where the output from the running executable goes.
3945 For compatibility reasons OUTPUT_VARIABLE is still supported,
3948 which gives you the output from the compile and run step com‐
3949 bined.
3950 Cross compiling issues
3953 When cross compiling, the executable compiled in the first step
3956 usually cannot be run on the build host. try_run() checks the
3957 CMAKE_CROSSCOMPILING variable to detect whether CMake is in
3958 crosscompiling mode. If that's the case, it will still try to
3959 compile the executable, but it will not try to run the exe‐
3960 cutable. Instead it will create cache variables which must be
3961 filled by the user or by presetting them in some CMake script
3962 file to the values the executable would have produced if it
3963 would have been run on its actual target platform. These vari‐
3964 ables are RUN_RESULT_VAR (explanation see above) and if RUN_OUT‐
3965 PUT_VARIABLE (or OUTPUT_VARIABLE) was used, an additional cache
3966 variable RUN_RESULT_VAR__COMPILE_RESULT_VAR__TRYRUN_OUTPUT.This
3967 is intended to hold stdout and stderr from the executable.
3968 In order to make cross compiling your project easier, use
3971 try_run only if really required. If you use try_run, use
3972 RUN_OUTPUT_VARIABLE (or OUTPUT_VARIABLE) only if really
3973 required. Using them will require that when crosscompiling, the
3974 cache variables will have to be set manually to the output of
3975 the executable. You can also "guard" the calls to try_run with
3976 if(CMAKE_CROSSCOMPILING) and provide an easy-to-preset alterna‐
3977 tive for this case.
3978 Set variable CMAKE_TRY_COMPILE_CONFIGURATION to choose a build
3981 configuration.
3982 unset Unset a variable, cache variable, or environment variable.
3985 unset(<variable> [CACHE])
3987 Removes the specified variable causing it to become undefined.
3989 If CACHE is present then the variable is removed from the cache
3990 instead of the current scope.
3991 <variable> can be an environment variable such as:
3994 unset(ENV{LD_LIBRARY_PATH})
3997 in which case the variable will be removed from the current
3999 environment.
4000 variable_watch
4003 Watch the CMake variable for change.
4004 variable_watch(<variable name> [<command to execute>])
4006 If the specified variable changes, the message will be printed
4008 about the variable being changed. If the command is specified,
4009 the command will be executed. The command will receive the fol‐
4010 lowing arguments: COMMAND(<variable> <access> <value> <current
4011 list file> <stack>)
4012 while Evaluate a group of commands while a condition is true
4015 while(condition)
4017 COMMAND1(ARGS ...)
4018 COMMAND2(ARGS ...)
4019 ...
4020 endwhile(condition)
4021 All commands between while and the matching endwhile are
4023 recorded without being invoked. Once the endwhile is evaluated,
4024 the recorded list of commands is invoked as long as the condi‐
4025 tion is true. The condition is evaluated using the same logic as
4026 the if command.
4027
4030 build_name
4031 Deprecated. Use ${CMAKE_SYSTEM} and ${CMAKE_CXX_COMPILER}
4032 instead.
4033 build_name(variable)
4035 Sets the specified variable to a string representing the plat‐
4037 form and compiler settings. These values are now available
4038 through the CMAKE_SYSTEM and CMAKE_CXX_COMPILER variables.
4039 exec_program
4042 Deprecated. Use the execute_process() command instead.
4043 Run an executable program during the processing of the CMake‐
4045 List.txt file.
4046 exec_program(Executable [directory in which to run]
4049 [ARGS <arguments to executable>]
4050 [OUTPUT_VARIABLE <var>]
4051 [RETURN_VALUE <var>])
4052 The executable is run in the optionally specified directory.
4054 The executable can include arguments if it is double quoted, but
4055 it is better to use the optional ARGS argument to specify argu‐
4056 ments to the program. This is because cmake will then be able
4057 to escape spaces in the executable path. An optional argument
4058 OUTPUT_VARIABLE specifies a variable in which to store the out‐
4059 put. To capture the return value of the execution, provide a
4060 RETURN_VALUE. If OUTPUT_VARIABLE is specified, then no output
4061 will go to the stdout/stderr of the console running cmake.
4062 export_library_dependencies
4066 Deprecated. Use INSTALL(EXPORT) or EXPORT command.
4067 This command generates an old-style library dependencies file.
4069 Projects requiring CMake 2.6 or later should not use the com‐
4070 mand. Use instead the install(EXPORT) command to help export
4071 targets from an installation tree and the export() command to
4072 export targets from a build tree.
4073 The old-style library dependencies file does not take into
4076 account per-configuration names of libraries or the LINK_INTER‐
4077 FACE_LIBRARIES target property.
4078 export_library_dependencies(<file> [APPEND])
4081 Create a file named <file> that can be included into a CMake
4083 listfile with the INCLUDE command. The file will contain a num‐
4084 ber of SET commands that will set all the variables needed for
4085 library dependency information. This should be the last command
4086 in the top level CMakeLists.txt file of the project. If the
4087 APPEND option is specified, the SET commands will be appended to
4088 the given file instead of replacing it.
4089 install_files
4092 Deprecated. Use the install(FILES ) command instead.
4093 This command has been superceded by the install command. It is
4095 provided for compatibility with older CMake code. The FILES
4096 form is directly replaced by the FILES form of the install com‐
4097 mand. The regexp form can be expressed more clearly using the
4098 GLOB form of the file command.
4099 install_files(<dir> extension file file ...)
4102 Create rules to install the listed files with the given exten‐
4104 sion into the given directory. Only files existing in the cur‐
4105 rent source tree or its corresponding location in the binary
4106 tree may be listed. If a file specified already has an exten‐
4107 sion, that extension will be removed first. This is useful for
4108 providing lists of source files such as foo.cxx when you want
4109 the corresponding foo.h to be installed. A typical extension is
4110 '.h'.
4111 install_files(<dir> regexp)
4114 Any files in the current source directory that match the regular
4116 expression will be installed.
4117 install_files(<dir> FILES file file ...)
4120 Any files listed after the FILES keyword will be installed
4122 explicitly from the names given. Full paths are allowed in this
4123 form.
4124 The directory <dir> is relative to the installation prefix,
4127 which is stored in the variable CMAKE_INSTALL_PREFIX.
4128 install_programs
4131 Deprecated. Use the install(PROGRAMS ) command instead.
4132 This command has been superceded by the install command. It is
4134 provided for compatibility with older CMake code. The FILES
4135 form is directly replaced by the PROGRAMS form of the INSTALL
4136 command. The regexp form can be expressed more clearly using
4137 the GLOB form of the FILE command.
4138 install_programs(<dir> file1 file2 [file3 ...])
4141 install_programs(<dir> FILES file1 [file2 ...])
4142 Create rules to install the listed programs into the given
4144 directory. Use the FILES argument to guarantee that the file
4145 list version of the command will be used even when there is only
4146 one argument.
4147 install_programs(<dir> regexp)
4150 In the second form any program in the current source directory
4152 that matches the regular expression will be installed.
4153 This command is intended to install programs that are not built
4156 by cmake, such as shell scripts. See the TARGETS form of the
4157 INSTALL command to create installation rules for targets built
4158 by cmake.
4159 The directory <dir> is relative to the installation prefix,
4162 which is stored in the variable CMAKE_INSTALL_PREFIX.
4163 install_targets
4166 Deprecated. Use the install(TARGETS ) command instead.
4167 This command has been superceded by the install command. It is
4169 provided for compatibility with older CMake code.
4170 install_targets(<dir> [RUNTIME_DIRECTORY dir] target target)
4173 Create rules to install the listed targets into the given direc‐
4175 tory. The directory <dir> is relative to the installation pre‐
4176 fix, which is stored in the variable CMAKE_INSTALL_PREFIX. If
4177 RUNTIME_DIRECTORY is specified, then on systems with special
4178 runtime files (Windows DLL), the files will be copied to that
4179 directory.
4180 link_libraries
4183 Deprecated. Use the target_link_libraries() command instead.
4184 Link libraries to all targets added later.
4186 link_libraries(library1 <debug | optimized> library2 ...)
4189 Specify a list of libraries to be linked into any following tar‐
4191 gets (typically added with the add_executable or add_library
4192 calls). This command is passed down to all subdirectories. The
4193 debug and optimized strings may be used to indicate that the
4194 next library listed is to be used only for that specific type of
4195 build.
4196 make_directory
4199 Deprecated. Use the file(MAKE_DIRECTORY ) command instead.
4200 make_directory(directory)
4202 Creates the specified directory. Full paths should be given.
4204 Any parent directories that do not exist will also be created.
4205 Use with care.
4206 remove Deprecated. Use the list(REMOVE_ITEM ) command instead.
4209 remove(VAR VALUE VALUE ...)
4211 Removes VALUE from the variable VAR. This is typically used to
4213 remove entries from a vector (e.g. semicolon separated list).
4214 VALUE is expanded.
4215 subdir_depends
4218 Deprecated. Does nothing.
4219 subdir_depends(subdir dep1 dep2 ...)
4221 Does not do anything. This command used to help projects order
4223 parallel builds correctly. This functionality is now automatic.
4224 subdirs
4227 Deprecated. Use the add_subdirectory() command instead.
4228 Add a list of subdirectories to the build.
4230 subdirs(dir1 dir2 ...[EXCLUDE_FROM_ALL exclude_dir1 exclude_dir2 ...]
4233 [PREORDER] )
4234 Add a list of subdirectories to the build. The add_subdirectory
4236 command should be used instead of subdirs although subdirs will
4237 still work. This will cause any CMakeLists.txt files in the sub
4238 directories to be processed by CMake. Any directories after the
4239 PREORDER flag are traversed first by makefile builds, the PRE‐
4240 ORDER flag has no effect on IDE projects. Any directories after
4241 the EXCLUDE_FROM_ALL marker will not be included in the top
4242 level makefile or project file. This is useful for having CMake
4243 create makefiles or projects for a set of examples in a project.
4244 You would want CMake to generate makefiles or project files for
4245 all the examples at the same time, but you would not want them
4246 to show up in the top level project or be built each time make
4247 is run from the top.
4248 use_mangled_mesa
4251 Copy mesa headers for use in combination with system GL.
4252 use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
4254 The path to mesa includes, should contain gl_mangle.h. The mesa
4256 headers are copied to the specified output directory. This
4257 allows mangled mesa headers to override other GL headers by
4258 being added to the include directory path earlier.
4259 utility_source
4262 Specify the source tree of a third-party utility.
4263 utility_source(cache_entry executable_name
4265 path_to_source [file1 file2 ...])
4266 When a third-party utility's source is included in the distribu‐
4268 tion, this command specifies its location and name. The cache
4269 entry will not be set unless the path_to_source and all listed
4270 files exist. It is assumed that the source tree of the utility
4271 will have been built before it is needed.
4272 When cross compiling CMake will print a warning if a util‐
4275 ity_source() command is executed, because in many cases it is
4276 used to build an executable which is executed later on. This
4277 doesn't work when cross compiling, since the executable can run
4278 only on their target platform. So in this case the cache entry
4279 has to be adjusted manually so it points to an executable which
4280 is runnable on the build host.
4281 variable_requires
4284 Deprecated. Use the if() command instead.
4285 Assert satisfaction of an option's required variables.
4287 variable_requires(TEST_VARIABLE RESULT_VARIABLE
4290 REQUIRED_VARIABLE1
4291 REQUIRED_VARIABLE2 ...)
4292 The first argument (TEST_VARIABLE) is the name of the variable
4294 to be tested, if that variable is false nothing else is done. If
4295 TEST_VARIABLE is true, then the next argument (RESULT_VARIABLE)
4296 is a variable that is set to true if all the required variables
4297 are set. The rest of the arguments are variables that must be
4298 true or not set to NOTFOUND to avoid an error. If any are not
4299 true, an error is reported.
4300 write_file
4303 Deprecated. Use the file(WRITE ) command instead.
4304 write_file(filename "message to write"... [APPEND])
4306 The first argument is the file name, the rest of the arguments
4308 are messages to write. If the argument APPEND is specified, then
4309 the message will be appended.
4310 NOTE 1: file(WRITE ... and file(APPEND ... do exactly the same
4313 as this one but add some more functionality.
4314 NOTE 2: When using write_file the produced file cannot be used
4317 as an input to CMake (CONFIGURE_FILE, source file ...) because
4318 it will lead to an infinite loop. Use configure_file if you want
4319 to generate input files to CMake.
4320
4324 Copyright 2000-2009 Kitware, Inc., Insight Software Consortium. All
4325 rights reserved.
4326 Redistribution and use in source and binary forms, with or without mod‐
4329 ification, are permitted provided that the following conditions are
4330 met:
4331 Redistributions of source code must retain the above copyright notice,
4334 this list of conditions and the following disclaimer.
4335 Redistributions in binary form must reproduce the above copyright
4338 notice, this list of conditions and the following disclaimer in the
4339 documentation and/or other materials provided with the distribution.
4340 Neither the names of Kitware, Inc., the Insight Software Consortium,
4343 nor the names of their contributors may be used to endorse or promote
4344 products derived from this software without specific prior written per‐
4345 mission.
4346 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
4349 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
4350 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
4351 ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
4352 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
4353 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
4354 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
4355 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
4356 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
4357 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
4358 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
4359
4362 cmake(1), ctest(1)
4363 The following resources are available to get help using CMake:
4366 Home Page
4369 http://www.cmake.org
4370 The primary starting point for learning about CMake.
4372 Frequently Asked Questions
4375 http://www.cmake.org/Wiki/CMake_FAQ
4376 A Wiki is provided containing answers to frequently asked ques‐
4378 tions.
4379 Online Documentation
4382 http://www.cmake.org/HTML/Documentation.html
4383 Links to available documentation may be found on this web page.
4385 Mailing List
4388 http://www.cmake.org/HTML/MailingLists.html
4389 For help and discussion about using cmake, a mailing list is
4391 provided at cmake@cmake.org. The list is member-post-only but
4392 one may sign up on the CMake web page. Please first read the
4393 full documentation at http://www.cmake.org before posting ques‐
4394 tions to the list.
4395 Summary of helpful links:
4398 Home: http://www.cmake.org
4401 Docs: http://www.cmake.org/HTML/Documentation.html
4402 Mail: http://www.cmake.org/HTML/MailingLists.html
4403 FAQ: http://www.cmake.org/Wiki/CMake_FAQ
4404
4407 This manual page was generated by the "--help-man" option.
4408ccmake 2.8.4 March 31, 2011 ccmake(1)