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