1cmakeprops(1) General Commands Manual cmakeprops(1)
2
3
4
6 cmakeprops - Reference of CMake properties.
7
8
10 CMake Properties - Properties supported by CMake, the Cross-Platform Makefile Generator.
11
12
13 This is the documentation for the properties supported by CMake. Prop‐
14 erties can have different scopes. They can either be assigned to a
15 source file, a directory, a target or globally to CMake. By modifying
16 the values of properties the behaviour of the build system can be cus‐
17 tomized.
18
19
21 ALLOW_DUPLICATE_CUSTOM_TARGETS
22 Allow duplicate custom targets to be created.
23
24 Normally CMake requires that all targets built in a project have
25 globally unique logical names (see policy CMP0002). This is
26 necessary to generate meaningful project file names in Xcode and
27 VS IDE generators. It also allows the target names to be refer‐
28 enced unambiguously.
29
30
31 Makefile generators are capable of supporting duplicate custom
32 target names. For projects that care only about Makefile gener‐
33 ators and do not wish to support Xcode or VS IDE generators, one
34 may set this property to true to allow duplicate custom targets.
35 The property allows multiple add_custom_target command calls in
36 different directories to specify the same target name. However,
37 setting this property will cause non-Makefile generators to pro‐
38 duce an error and refuse to generate the project.
39
40
41 DEBUG_CONFIGURATIONS
42 Specify which configurations are for debugging.
43
44 The value must be a semi-colon separated list of configuration
45 names. Currently this property is used only by the tar‐
46 get_link_libraries command (see its documentation for details).
47 Additional uses may be defined in the future.
48
49
50 This property must be set at the top level of the project and
51 before the first target_link_libraries command invocation. If
52 any entry in the list does not match a valid configuration for
53 the project the behavior is undefined.
54
55
56 DISABLED_FEATURES
57 List of features which are disabled during the CMake run.
58
59 List of features which are disabled during the CMake run. Be
60 default it contains the names of all packages which were not
61 found. This is determined using the <NAME>_FOUND variables.
62 Packages which are searched QUIET are not listed. A project can
63 add its own features to this list.This property is used by the
64 macros in FeatureSummary.cmake.
65
66
67 ENABLED_FEATURES
68 List of features which are enabled during the CMake run.
69
70 List of features which are enabled during the CMake run. Be
71 default it contains the names of all packages which were found.
72 This is determined using the <NAME>_FOUND variables. Packages
73 which are searched QUIET are not listed. A project can add its
74 own features to this list.This property is used by the macros in
75 FeatureSummary.cmake.
76
77
78 ENABLED_LANGUAGES
79 Read-only property that contains the list of currently enabled
80 languages
81
82 Set to list of currently enabled languages.
83
84
85 FIND_LIBRARY_USE_LIB64_PATHS
86 Whether FIND_LIBRARY should automatically search lib64 directo‐
87 ries.
88
89 FIND_LIBRARY_USE_LIB64_PATHS is a boolean specifying whether the
90 FIND_LIBRARY command should automatically search the lib64 vari‐
91 ant of directories called lib in the search path when building
92 64-bit binaries.
93
94
95 FIND_LIBRARY_USE_OPENBSD_VERSIONING
96 Whether FIND_LIBRARY should find OpenBSD-style shared libraries.
97
98 This property is a boolean specifying whether the FIND_LIBRARY
99 command should find shared libraries with OpenBSD-style ver‐
100 sioned extension: ".so.<major>.<minor>". The property is set to
101 true on OpenBSD and false on other platforms.
102
103
104 GLOBAL_DEPENDS_DEBUG_MODE
105 Enable global target dependency graph debug mode.
106
107 CMake automatically analyzes the global inter-target dependency
108 graph at the beginning of native build system generation. This
109 property causes it to display details of its analysis to stderr.
110
111
112 GLOBAL_DEPENDS_NO_CYCLES
113 Disallow global target dependency graph cycles.
114
115 CMake automatically analyzes the global inter-target dependency
116 graph at the beginning of native build system generation. It
117 reports an error if the dependency graph contains a cycle that
118 does not consist of all STATIC library targets. This property
119 tells CMake to disallow all cycles completely, even among static
120 libraries.
121
122
123 IN_TRY_COMPILE
124 Read-only property that is true during a try-compile configura‐
125 tion.
126
127 True when building a project inside a TRY_COMPILE or TRY_RUN
128 command.
129
130
131 PACKAGES_FOUND
132 List of packages which were found during the CMake run.
133
134 List of packages which were found during the CMake run. Whether
135 a package has been found is determined using the <NAME>_FOUND
136 variables.
137
138
139 PACKAGES_NOT_FOUND
140 List of packages which were not found during the CMake run.
141
142 List of packages which were not found during the CMake run.
143 Whether a package has been found is determined using the
144 <NAME>_FOUND variables.
145
146
147 PREDEFINED_TARGETS_FOLDER
148 Name of FOLDER for targets that are added automatically by
149 CMake.
150
151 If not set, CMake uses "CMakePredefinedTargets" as a default
152 value for this property. Targets such as INSTALL, PACKAGE and
153 RUN_TESTS will be organized into this FOLDER. See also the docu‐
154 mentation for the FOLDER target property.
155
156
157 REPORT_UNDEFINED_PROPERTIES
158 If set, report any undefined properties to this file.
159
160 If this property is set to a filename then when CMake runs it
161 will report any properties or variables that were accessed but
162 not defined into the filename specified in this property.
163
164
165 RULE_LAUNCH_COMPILE
166 Specify a launcher for compile rules.
167
168 Makefile generators prefix compiler commands with the given
169 launcher command line. This is intended to allow launchers to
170 intercept build problems with high granularity. Non-Makefile
171 generators currently ignore this property.
172
173
174 RULE_LAUNCH_CUSTOM
175 Specify a launcher for custom rules.
176
177 Makefile generators prefix custom commands with the given
178 launcher command line. This is intended to allow launchers to
179 intercept build problems with high granularity. Non-Makefile
180 generators currently ignore this property.
181
182
183 RULE_LAUNCH_LINK
184 Specify a launcher for link rules.
185
186 Makefile generators prefix link and archive commands with the
187 given launcher command line. This is intended to allow launch‐
188 ers to intercept build problems with high granularity.
189 Non-Makefile generators currently ignore this property.
190
191
192 RULE_MESSAGES
193 Specify whether to report a message for each make rule.
194
195 This property specifies whether Makefile generators should add a
196 progress message describing what each build rule does. If the
197 property is not set the default is ON. Set the property to OFF
198 to disable granular messages and report only as each target com‐
199 pletes. This is intended to allow scripted builds to avoid the
200 build time cost of detailed reports. If a CMAKE_RULE_MESSAGES
201 cache entry exists its value initializes the value of this prop‐
202 erty. Non-Makefile generators currently ignore this property.
203
204
205 TARGET_ARCHIVES_MAY_BE_SHARED_LIBS
206 Set if shared libraries may be named like archives.
207
208 On AIX shared libraries may be named "lib<name>.a". This prop‐
209 erty is set to true on such platforms.
210
211
212 TARGET_SUPPORTS_SHARED_LIBS
213 Does the target platform support shared libraries.
214
215 TARGET_SUPPORTS_SHARED_LIBS is a boolean specifying whether the
216 target platform supports shared libraries. Basically all current
217 general general purpose OS do so, the exception are usually
218 embedded systems with no or special OSs.
219
220
221 USE_FOLDERS
222 Use the FOLDER target property to organize targets into folders.
223
224 If not set, CMake treats this property as OFF by default. CMake
225 generators that are capable of organizing into a hierarchy of
226 folders use the values of the FOLDER target property to name
227 those folders. See also the documentation for the FOLDER target
228 property.
229
230
231 __CMAKE_DELETE_CACHE_CHANGE_VARS_
232 Internal property
233
234 Used to detect compiler changes, Do not set.
235
236
238 ADDITIONAL_MAKE_CLEAN_FILES
239 Additional files to clean during the make clean stage.
240
241 A list of files that will be cleaned as a part of the "make
242 clean" stage.
243
244
245 CACHE_VARIABLES
246 List of cache variables available in the current directory.
247
248 This read-only property specifies the list of CMake cache vari‐
249 ables currently defined. It is intended for debugging purposes.
250
251
252 CLEAN_NO_CUSTOM
253 Should the output of custom commands be left.
254
255 If this is true then the outputs of custom commands for this
256 directory will not be removed during the "make clean" stage.
257
258
259 COMPILE_DEFINITIONS
260 Preprocessor definitions for compiling a directory's sources.
261
262 The COMPILE_DEFINITIONS property may be set to a semicolon-sepa‐
263 rated list of preprocessor definitions using the syntax VAR or
264 VAR=value. Function-style definitions are not supported. CMake
265 will automatically escape the value correctly for the native
266 build system (note that CMake language syntax may require
267 escapes to specify some values). This property may be set on a
268 per-configuration basis using the name COMPILE_DEFINITIONS_<CON‐
269 FIG> where <CONFIG> is an upper-case name (ex. "COMPILE_DEFINI‐
270 TIONS_DEBUG"). This property will be initialized in each direc‐
271 tory by its value in the directory's parent.
272
273
274 CMake will automatically drop some definitions that are not sup‐
275 ported by the native build tool. The VS6 IDE does not support
276 definition values with spaces (but NMake does).
277
278
279 Disclaimer: Most native build tools have poor support for escap‐
280 ing certain values. CMake has work-arounds for many cases but
281 some values may just not be possible to pass correctly. If a
282 value does not seem to be escaped correctly, do not attempt to
283 work-around the problem by adding escape sequences to the value.
284 Your work-around may break in a future version of CMake that has
285 improved escape support. Instead consider defining the macro in
286 a (configured) header file. Then report the limitation. Known
287 limitations include:
288
289
290 # - broken almost everywhere
291 ; - broken in VS IDE and Borland Makefiles
292 , - broken in VS IDE
293 % - broken in some cases in NMake
294 & | - broken in some cases on MinGW
295 ^ < > \" - broken in most Make tools on Windows
296
297 CMake does not reject these values outright because they do work
298 in some cases. Use with caution.
299
300
301 COMPILE_DEFINITIONS_<CONFIG>
302 Per-configuration preprocessor definitions in a directory.
303
304 This is the configuration-specific version of COMPILE_DEFINI‐
305 TIONS. This property will be initialized in each directory by
306 its value in the directory's parent.
307
308
309
310 DEFINITIONS
311 For CMake 2.4 compatibility only. Use COMPILE_DEFINITIONS
312 instead.
313
314 This read-only property specifies the list of flags given so far
315 to the add_definitions command. It is intended for debugging
316 purposes. Use the COMPILE_DEFINITIONS instead.
317
318
319 EXCLUDE_FROM_ALL
320 Exclude the directory from the all target of its parent.
321
322 A property on a directory that indicates if its targets are
323 excluded from the default build target. If it is not, then with
324 a Makefile for example typing make will cause the targets to be
325 built. The same concept applies to the default build of other
326 generators.
327
328
329 IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
330 Specify #include line transforms for dependencies in a direc‐
331 tory.
332
333 This property specifies rules to transform macro-like #include
334 lines during implicit dependency scanning of C and C++ source
335 files. The list of rules must be semicolon-separated with each
336 entry of the form "A_MACRO(%)=value-with-%" (the % must be lit‐
337 eral). During dependency scanning occurrences of A_MACRO(...)
338 on #include lines will be replaced by the value given with the
339 macro argument substituted for '%'. For example, the entry
340
341
342 MYDIR(%)=<mydir/%>
343
344 will convert lines of the form
345
346
347 #include MYDIR(myheader.h)
348
349 to
350
351
352 #include <mydir/myheader.h>
353
354 allowing the dependency to be followed.
355
356
357 This property applies to sources in all targets within a direc‐
358 tory. The property value is initialized in each directory by
359 its value in the directory's parent.
360
361
362 INCLUDE_DIRECTORIES
363 List of preprocessor include file search directories.
364
365 This read-only property specifies the list of directories given
366 so far to the include_directories command. It is intended for
367 debugging purposes.
368
369
370 INCLUDE_REGULAR_EXPRESSION
371 Include file scanning regular expression.
372
373 This read-only property specifies the regular expression used
374 during dependency scanning to match include files that should be
375 followed. See the include_regular_expression command.
376
377
378 INTERPROCEDURAL_OPTIMIZATION
379 Enable interprocedural optimization for targets in a directory.
380
381 If set to true, enables interprocedural optimizations if they
382 are known to be supported by the compiler.
383
384
385 INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
386 Per-configuration interprocedural optimization for a directory.
387
388 This is a per-configuration version of INTERPROCEDURAL_OPTIMIZA‐
389 TION. If set, this property overrides the generic property for
390 the named configuration.
391
392
393 LINK_DIRECTORIES
394 List of linker search directories.
395
396 This read-only property specifies the list of directories given
397 so far to the link_directories command. It is intended for
398 debugging purposes.
399
400
401 LISTFILE_STACK
402 The current stack of listfiles being processed.
403
404 This property is mainly useful when trying to debug errors in
405 your CMake scripts. It returns a list of what list files are
406 currently being processed, in order. So if one listfile does an
407 INCLUDE command then that is effectively pushing the included
408 listfile onto the stack.
409
410
411 MACROS List of macro commands available in the current directory.
412
413 This read-only property specifies the list of CMake macros cur‐
414 rently defined. It is intended for debugging purposes. See the
415 macro command.
416
417
418 PARENT_DIRECTORY
419 Source directory that added current subdirectory.
420
421 This read-only property specifies the source directory that
422 added the current source directory as a subdirectory of the
423 build. In the top-level directory the value is the
424 empty-string.
425
426
427 RULE_LAUNCH_COMPILE
428 Specify a launcher for compile rules.
429
430 See the global property of the same name for details. This
431 overrides the global property for a directory.
432
433
434 RULE_LAUNCH_CUSTOM
435 Specify a launcher for custom rules.
436
437 See the global property of the same name for details. This
438 overrides the global property for a directory.
439
440
441 RULE_LAUNCH_LINK
442 Specify a launcher for link rules.
443
444 See the global property of the same name for details. This
445 overrides the global property for a directory.
446
447
448 TEST_INCLUDE_FILE
449 A cmake file that will be included when ctest is run.
450
451 If you specify TEST_INCLUDE_FILE, that file will be included and
452 processed when ctest is run on the directory.
453
454
455 VARIABLES
456 List of variables defined in the current directory.
457
458 This read-only property specifies the list of CMake variables
459 currently defined. It is intended for debugging purposes.
460
461
463 <CONFIG>_OUTPUT_NAME
464 Old per-configuration target file base name.
465
466 This is a configuration-specific version of OUTPUT_NAME. Use
467 OUTPUT_NAME_<CONFIG> instead.
468
469
470 <CONFIG>_POSTFIX
471 Postfix to append to the target file name for configuration
472 <CONFIG>.
473
474 When building with configuration <CONFIG> the value of this
475 property is appended to the target file name built on disk. For
476 non-executable targets, this property is initialized by the
477 value of the variable CMAKE_<CONFIG>_POSTFIX if it is set when a
478 target is created. This property is ignored on the Mac for
479 Frameworks and App Bundles.
480
481
482 ARCHIVE_OUTPUT_DIRECTORY
483 Output directory in which to build ARCHIVE target files.
484
485 This property specifies the directory into which archive target
486 files should be built. Multi-configuration generators (VS,
487 Xcode) append a per-configuration subdirectory to the specified
488 directory. There are three kinds of target files that may be
489 built: archive, library, and runtime. Executables are always
490 treated as runtime targets. Static libraries are always treated
491 as archive targets. Module libraries are always treated as
492 library targets. For non-DLL platforms shared libraries are
493 treated as library targets. For DLL platforms the DLL part of a
494 shared library is treated as a runtime target and the corre‐
495 sponding import library is treated as an archive target. All
496 Windows-based systems including Cygwin are DLL platforms. This
497 property is initialized by the value of the variable CMAKE_AR‐
498 CHIVE_OUTPUT_DIRECTORY if it is set when a target is created.
499
500
501 ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>
502 Per-configuration output directory for ARCHIVE target files.
503
504 This is a per-configuration version of ARCHIVE_OUTPUT_DIRECTORY,
505 but multi-configuration generators (VS, Xcode) do NOT append a
506 per-configuration subdirectory to the specified directory. This
507 property is initialized by the value of the variable CMAKE_AR‐
508 CHIVE_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is
509 created.
510
511
512 ARCHIVE_OUTPUT_NAME
513 Output name for ARCHIVE target files.
514
515 This property specifies the base name for archive target files.
516 It overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
517 There are three kinds of target files that may be built: ar‐
518 chive, library, and runtime. Executables are always treated as
519 runtime targets. Static libraries are always treated as archive
520 targets. Module libraries are always treated as library targets.
521 For non-DLL platforms shared libraries are treated as library
522 targets. For DLL platforms the DLL part of a shared library is
523 treated as a runtime target and the corresponding import library
524 is treated as an archive target. All Windows-based systems
525 including Cygwin are DLL platforms.
526
527
528 ARCHIVE_OUTPUT_NAME_<CONFIG>
529 Per-configuration output name for ARCHIVE target files.
530
531 This is the configuration-specific version of ARCHIVE_OUT‐
532 PUT_NAME.
533
534
535 BUILD_WITH_INSTALL_RPATH
536 Should build tree targets have install tree rpaths.
537
538 BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link
539 the target in the build tree with the INSTALL_RPATH. This takes
540 precedence over SKIP_BUILD_RPATH and avoids the need for relink‐
541 ing before installation. This property is initialized by the
542 value of the variable CMAKE_BUILD_WITH_INSTALL_RPATH if it is
543 set when a target is created.
544
545
546 COMPILE_DEFINITIONS
547 Preprocessor definitions for compiling a target's sources.
548
549 The COMPILE_DEFINITIONS property may be set to a semicolon-sepa‐
550 rated list of preprocessor definitions using the syntax VAR or
551 VAR=value. Function-style definitions are not supported. CMake
552 will automatically escape the value correctly for the native
553 build system (note that CMake language syntax may require
554 escapes to specify some values). This property may be set on a
555 per-configuration basis using the name COMPILE_DEFINITIONS_<CON‐
556 FIG> where <CONFIG> is an upper-case name (ex. "COMPILE_DEFINI‐
557 TIONS_DEBUG").
558
559
560 CMake will automatically drop some definitions that are not sup‐
561 ported by the native build tool. The VS6 IDE does not support
562 definition values with spaces (but NMake does).
563
564
565 Disclaimer: Most native build tools have poor support for escap‐
566 ing certain values. CMake has work-arounds for many cases but
567 some values may just not be possible to pass correctly. If a
568 value does not seem to be escaped correctly, do not attempt to
569 work-around the problem by adding escape sequences to the value.
570 Your work-around may break in a future version of CMake that has
571 improved escape support. Instead consider defining the macro in
572 a (configured) header file. Then report the limitation. Known
573 limitations include:
574
575
576 # - broken almost everywhere
577 ; - broken in VS IDE and Borland Makefiles
578 , - broken in VS IDE
579 % - broken in some cases in NMake
580 & | - broken in some cases on MinGW
581 ^ < > \" - broken in most Make tools on Windows
582
583 CMake does not reject these values outright because they do work
584 in some cases. Use with caution.
585
586
587 COMPILE_DEFINITIONS_<CONFIG>
588 Per-configuration preprocessor definitions on a target.
589
590 This is the configuration-specific version of COMPILE_DEFINI‐
591 TIONS.
592
593
594 COMPILE_FLAGS
595 Additional flags to use when compiling this target's sources.
596
597 The COMPILE_FLAGS property sets additional compiler flags used
598 to build sources within the target. Use COMPILE_DEFINITIONS to
599 pass additional preprocessor definitions.
600
601
602 DEBUG_POSTFIX
603 See target property <CONFIG>_POSTFIX.
604
605 This property is a special case of the more-general <CON‐
606 FIG>_POSTFIX property for the DEBUG configuration.
607
608
609 DEFINE_SYMBOL
610 Define a symbol when compiling this target's sources.
611
612 DEFINE_SYMBOL sets the name of the preprocessor symbol defined
613 when compiling sources in a shared library. If not set here then
614 it is set to target_EXPORTS by default (with some substitutions
615 if the target is not a valid C identifier). This is useful for
616 headers to know whether they are being included from inside
617 their library our outside to properly setup dllexport/dllimport
618 decorations.
619
620
621 ENABLE_EXPORTS
622 Specify whether an executable exports symbols for loadable mod‐
623 ules.
624
625 Normally an executable does not export any symbols because it is
626 the final program. It is possible for an executable to export
627 symbols to be used by loadable modules. When this property is
628 set to true CMake will allow other targets to "link" to the exe‐
629 cutable with the TARGET_LINK_LIBRARIES command. On all plat‐
630 forms a target-level dependency on the executable is created for
631 targets that link to it. For DLL platforms an import library
632 will be created for the exported symbols and then used for link‐
633 ing. All Windows-based systems including Cygwin are DLL plat‐
634 forms. For non-DLL platforms that require all symbols to be
635 resolved at link time, such as Mac OS X, the module will "link"
636 to the executable using a flag like "-bundle_loader". For other
637 non-DLL platforms the link rule is simply ignored since the
638 dynamic loader will automatically bind symbols when the module
639 is loaded.
640
641
642 EXCLUDE_FROM_ALL
643 Exclude the target from the all target.
644
645 A property on a target that indicates if the target is excluded
646 from the default build target. If it is not, then with a Make‐
647 file for example typing make will cause this target to be built.
648 The same concept applies to the default build of other genera‐
649 tors. Installing a target with EXCLUDE_FROM_ALL set to true has
650 undefined behavior.
651
652
653 EchoString
654 A message to be displayed when the target is built.
655
656 A message to display on some generators (such as makefiles) when
657 the target is built.
658
659
660 FOLDER Set the folder name. Use to organize targets in an IDE.
661
662 Targets with no FOLDER property will appear as top level enti‐
663 ties in IDEs like Visual Studio. Targets with the same FOLDER
664 property value will appear next to each other in a folder of
665 that name. To nest folders, use FOLDER values such as
666 'GUI/Dialogs' with '/' characters separating folder levels.
667
668
669 FRAMEWORK
670 This target is a framework on the Mac.
671
672 If a shared library target has this property set to true it will
673 be built as a framework when built on the mac. It will have the
674 directory structure required for a framework and will be suit‐
675 able to be used with the -framework option
676
677
678 Fortran_MODULE_DIRECTORY
679 Specify output directory for Fortran modules provided by the
680 target.
681
682 If the target contains Fortran source files that provide modules
683 and the compiler supports a module output directory this speci‐
684 fies the directory in which the modules will be placed. When
685 this property is not set the modules will be placed in the build
686 directory corresponding to the target's source directory. If
687 the variable CMAKE_Fortran_MODULE_DIRECTORY is set when a target
688 is created its value is used to initialize this property.
689
690
691 GENERATOR_FILE_NAME
692 Generator's file for this target.
693
694 An internal property used by some generators to record the name
695 of project or dsp file associated with this target.
696
697
698 HAS_CXX
699 Link the target using the C++ linker tool (obsolete).
700
701 This is equivalent to setting the LINKER_LANGUAGE property to
702 CXX. See that property's documentation for details.
703
704
705 IMPLICIT_DEPENDS_INCLUDE_TRANSFORM
706 Specify #include line transforms for dependencies in a target.
707
708 This property specifies rules to transform macro-like #include
709 lines during implicit dependency scanning of C and C++ source
710 files. The list of rules must be semicolon-separated with each
711 entry of the form "A_MACRO(%)=value-with-%" (the % must be lit‐
712 eral). During dependency scanning occurrences of A_MACRO(...)
713 on #include lines will be replaced by the value given with the
714 macro argument substituted for '%'. For example, the entry
715
716
717 MYDIR(%)=<mydir/%>
718
719 will convert lines of the form
720
721
722 #include MYDIR(myheader.h)
723
724 to
725
726
727 #include <mydir/myheader.h>
728
729 allowing the dependency to be followed.
730
731
732 This property applies to sources in the target on which it is
733 set.
734
735
736 IMPORTED
737 Read-only indication of whether a target is IMPORTED.
738
739 The boolean value of this property is true for targets created
740 with the IMPORTED option to add_executable or add_library. It
741 is false for targets built within the project.
742
743
744 IMPORTED_CONFIGURATIONS
745 Configurations provided for an IMPORTED target.
746
747 Lists configuration names available for an IMPORTED target. The
748 names correspond to configurations defined in the project from
749 which the target is imported. If the importing project uses a
750 different set of configurations the names may be mapped using
751 the MAP_IMPORTED_CONFIG_<CONFIG> property. Ignored for
752 non-imported targets.
753
754
755 IMPORTED_IMPLIB
756 Full path to the import library for an IMPORTED target.
757
758 Specifies the location of the ".lib" part of a windows DLL.
759 Ignored for non-imported targets.
760
761
762 IMPORTED_IMPLIB_<CONFIG>
763 Per-configuration version of IMPORTED_IMPLIB property.
764
765 This property is used when loading settings for the <CONFIG>
766 configuration of an imported target. Configuration names corre‐
767 spond to those provided by the project from which the target is
768 imported.
769
770
771 IMPORTED_LINK_DEPENDENT_LIBRARIES
772 Dependent shared libraries of an imported shared library.
773
774 Shared libraries may be linked to other shared libraries as part
775 of their implementation. On some platforms the linker searches
776 for the dependent libraries of shared libraries they are includ‐
777 ing in the link. This property lists the dependent shared
778 libraries of an imported library. The list should be disjoint
779 from the list of interface libraries in the IMPORTED_LINK_INTER‐
780 FACE_LIBRARIES property. On platforms requiring dependent
781 shared libraries to be found at link time CMake uses this list
782 to add appropriate files or paths to the link command line.
783 Ignored for non-imported targets.
784
785
786 IMPORTED_LINK_DEPENDENT_LIBRARIES_<CONFIG>
787 Per-configuration version of IMPORTED_LINK_DEPENDENT_LIBRARIES.
788
789 This property is used when loading settings for the <CONFIG>
790 configuration of an imported target. Configuration names corre‐
791 spond to those provided by the project from which the target is
792 imported. If set, this property completely overrides the
793 generic property for the named configuration.
794
795
796 IMPORTED_LINK_INTERFACE_LANGUAGES
797 Languages compiled into an IMPORTED static library.
798
799 Lists languages of soure files compiled to produce a STATIC
800 IMPORTED library (such as "C" or "CXX"). CMake accounts for
801 these languages when computing how to link a target to the
802 imported library. For example, when a C executable links to an
803 imported C++ static library CMake chooses the C++ linker to sat‐
804 isfy language runtime dependencies of the static library.
805
806
807 This property is ignored for targets that are not STATIC
808 libraries. This property is ignored for non-imported targets.
809
810
811 IMPORTED_LINK_INTERFACE_LANGUAGES_<CONFIG>
812 Per-configuration version of IMPORTED_LINK_INTERFACE_LANGUAGES.
813
814 This property is used when loading settings for the <CONFIG>
815 configuration of an imported target. Configuration names corre‐
816 spond to those provided by the project from which the target is
817 imported. If set, this property completely overrides the
818 generic property for the named configuration.
819
820
821 IMPORTED_LINK_INTERFACE_LIBRARIES
822 Transitive link interface of an IMPORTED target.
823
824 Lists libraries whose interface is included when an IMPORTED
825 library target is linked to another target. The libraries will
826 be included on the link line for the target. Unlike the
827 LINK_INTERFACE_LIBRARIES property, this property applies to all
828 imported target types, including STATIC libraries. This prop‐
829 erty is ignored for non-imported targets.
830
831
832 IMPORTED_LINK_INTERFACE_LIBRARIES_<CONFIG>
833 Per-configuration version of IMPORTED_LINK_INTERFACE_LIBRARIES.
834
835 This property is used when loading settings for the <CONFIG>
836 configuration of an imported target. Configuration names corre‐
837 spond to those provided by the project from which the target is
838 imported. If set, this property completely overrides the
839 generic property for the named configuration.
840
841
842 IMPORTED_LINK_INTERFACE_MULTIPLICITY
843 Repetition count for cycles of IMPORTED static libraries.
844
845 This is LINK_INTERFACE_MULTIPLICITY for IMPORTED targets.
846
847
848 IMPORTED_LINK_INTERFACE_MULTIPLICITY_<CONFIG>
849 Per-configuration repetition count for cycles of IMPORTED ar‐
850 chives.
851
852 This is the configuration-specific version of
853 IMPORTED_LINK_INTERFACE_MULTIPLICITY. If set, this property
854 completely overrides the generic property for the named configu‐
855 ration.
856
857
858 IMPORTED_LOCATION
859 Full path to the main file on disk for an IMPORTED target.
860
861 Specifies the location of an IMPORTED target file on disk. For
862 executables this is the location of the executable file. For
863 bundles on OS X this is the location of the executable file
864 inside Contents/MacOS under the application bundle folder. For
865 static libraries and modules this is the location of the library
866 or module. For shared libraries on non-DLL platforms this is
867 the location of the shared library. For frameworks on OS X this
868 is the location of the library file symlink just inside the
869 framework folder. For DLLs this is the location of the ".dll"
870 part of the library. For UNKNOWN libraries this is the location
871 of the file to be linked. Ignored for non-imported targets.
872
873
874 IMPORTED_LOCATION_<CONFIG>
875 Per-configuration version of IMPORTED_LOCATION property.
876
877 This property is used when loading settings for the <CONFIG>
878 configuration of an imported target. Configuration names corre‐
879 spond to those provided by the project from which the target is
880 imported.
881
882
883 IMPORTED_NO_SONAME
884 Specifies that an IMPORTED shared library target has no "son‐
885 ame".
886
887 Set this property to true for an imported shared library file
888 that has no "soname" field. CMake may adjust generated link
889 commands for some platforms to prevent the linker from using the
890 path to the library in place of its missing soname. Ignored for
891 non-imported targets.
892
893
894 IMPORTED_NO_SONAME_<CONFIG>
895 Per-configuration version of IMPORTED_NO_SONAME property.
896
897 This property is used when loading settings for the <CONFIG>
898 configuration of an imported target. Configuration names corre‐
899 spond to those provided by the project from which the target is
900 imported.
901
902
903 IMPORTED_SONAME
904 The "soname" of an IMPORTED target of shared library type.
905
906 Specifies the "soname" embedded in an imported shared library.
907 This is meaningful only on platforms supporting the feature.
908 Ignored for non-imported targets.
909
910
911 IMPORTED_SONAME_<CONFIG>
912 Per-configuration version of IMPORTED_SONAME property.
913
914 This property is used when loading settings for the <CONFIG>
915 configuration of an imported target. Configuration names corre‐
916 spond to those provided by the project from which the target is
917 imported.
918
919
920 IMPORT_PREFIX
921 What comes before the import library name.
922
923 Similar to the target property PREFIX, but used for import
924 libraries (typically corresponding to a DLL) instead of regular
925 libraries. A target property that can be set to override the
926 prefix (such as "lib") on an import library name.
927
928
929 IMPORT_SUFFIX
930 What comes after the import library name.
931
932 Similar to the target property SUFFIX, but used for import
933 libraries (typically corresponding to a DLL) instead of regular
934 libraries. A target property that can be set to override the
935 suffix (such as ".lib") on an import library name.
936
937
938 INSTALL_NAME_DIR
939 Mac OSX directory name for installed targets.
940
941 INSTALL_NAME_DIR is a string specifying the directory portion of
942 the "install_name" field of shared libraries on Mac OSX to use
943 in the installed targets.
944
945
946 INSTALL_RPATH
947 The rpath to use for installed targets.
948
949 A semicolon-separated list specifying the rpath to use in
950 installed targets (for platforms that support it). This prop‐
951 erty is initialized by the value of the variable
952 CMAKE_INSTALL_RPATH if it is set when a target is created.
953
954
955 INSTALL_RPATH_USE_LINK_PATH
956 Add paths to linker search and installed rpath.
957
958 INSTALL_RPATH_USE_LINK_PATH is a boolean that if set to true
959 will append directories in the linker search path and outside
960 the project to the INSTALL_RPATH. This property is initialized
961 by the value of the variable CMAKE_INSTALL_RPATH_USE_LINK_PATH
962 if it is set when a target is created.
963
964
965 INTERPROCEDURAL_OPTIMIZATION
966 Enable interprocedural optimization for a target.
967
968 If set to true, enables interprocedural optimizations if they
969 are known to be supported by the compiler.
970
971
972 INTERPROCEDURAL_OPTIMIZATION_<CONFIG>
973 Per-configuration interprocedural optimization for a target.
974
975 This is a per-configuration version of INTERPROCEDURAL_OPTIMIZA‐
976 TION. If set, this property overrides the generic property for
977 the named configuration.
978
979
980 LABELS Specify a list of text labels associated with a target.
981
982 Target label semantics are currently unspecified.
983
984
985 LIBRARY_OUTPUT_DIRECTORY
986 Output directory in which to build LIBRARY target files.
987
988 This property specifies the directory into which library target
989 files should be built. Multi-configuration generators (VS,
990 Xcode) append a per-configuration subdirectory to the specified
991 directory. There are three kinds of target files that may be
992 built: archive, library, and runtime. Executables are always
993 treated as runtime targets. Static libraries are always treated
994 as archive targets. Module libraries are always treated as
995 library targets. For non-DLL platforms shared libraries are
996 treated as library targets. For DLL platforms the DLL part of a
997 shared library is treated as a runtime target and the corre‐
998 sponding import library is treated as an archive target. All
999 Windows-based systems including Cygwin are DLL platforms. This
1000 property is initialized by the value of the variable
1001 CMAKE_LIBRARY_OUTPUT_DIRECTORY if it is set when a target is
1002 created.
1003
1004
1005 LIBRARY_OUTPUT_DIRECTORY_<CONFIG>
1006 Per-configuration output directory for LIBRARY target files.
1007
1008 This is a per-configuration version of LIBRARY_OUTPUT_DIRECTORY,
1009 but multi-configuration generators (VS, Xcode) do NOT append a
1010 per-configuration subdirectory to the specified directory. This
1011 property is initialized by the value of the variable
1012 CMAKE_LIBRARY_OUTPUT_DIRECTORY_<CONFIG> if it is set when a tar‐
1013 get is created.
1014
1015
1016 LIBRARY_OUTPUT_NAME
1017 Output name for LIBRARY target files.
1018
1019 This property specifies the base name for library target files.
1020 It overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
1021 There are three kinds of target files that may be built: ar‐
1022 chive, library, and runtime. Executables are always treated as
1023 runtime targets. Static libraries are always treated as archive
1024 targets. Module libraries are always treated as library targets.
1025 For non-DLL platforms shared libraries are treated as library
1026 targets. For DLL platforms the DLL part of a shared library is
1027 treated as a runtime target and the corresponding import library
1028 is treated as an archive target. All Windows-based systems
1029 including Cygwin are DLL platforms.
1030
1031
1032 LIBRARY_OUTPUT_NAME_<CONFIG>
1033 Per-configuration output name for LIBRARY target files.
1034
1035 This is the configuration-specific version of LIBRARY_OUT‐
1036 PUT_NAME.
1037
1038
1039 LINKER_LANGUAGE
1040 Specifies language whose compiler will invoke the linker.
1041
1042 For executables, shared libraries, and modules, this sets the
1043 language whose compiler is used to link the target (such as "C"
1044 or "CXX"). A typical value for an executable is the language of
1045 the source file providing the program entry point (main). If
1046 not set, the language with the highest linker preference value
1047 is the default. See documentation of CMAKE_<LANG>_LINKER_PREF‐
1048 ERENCE variables.
1049
1050
1051 LINK_DEPENDS
1052 Additional files on which a target binary depends for linking.
1053
1054 Specifies a semicolon-separated list of full-paths to files on
1055 which the link rule for this target depends. The target binary
1056 will be linked if any of the named files is newer than it.
1057
1058
1059 This property is ignored by non-Makefile generators. It is
1060 intended to specify dependencies on "linker scripts" for custom
1061 Makefile link rules.
1062
1063
1064 LINK_FLAGS
1065 Additional flags to use when linking this target.
1066
1067 The LINK_FLAGS property can be used to add extra flags to the
1068 link step of a target. LINK_FLAGS_<CONFIG> will add to the con‐
1069 figuration <CONFIG>, for example, DEBUG, RELEASE, MINSIZEREL,
1070 RELWITHDEBINFO.
1071
1072
1073 LINK_FLAGS_<CONFIG>
1074 Per-configuration linker flags for a target.
1075
1076 This is the configuration-specific version of LINK_FLAGS.
1077
1078
1079 LINK_INTERFACE_LIBRARIES
1080 List public interface libraries for a shared library or exe‐
1081 cutable.
1082
1083 By default linking to a shared library target transitively links
1084 to targets with which the library itself was linked. For an
1085 executable with exports (see the ENABLE_EXPORTS property) no
1086 default transitive link dependencies are used. This property
1087 replaces the default transitive link dependencies with an
1088 explict list. When the target is linked into another target the
1089 libraries listed (and recursively their link interface
1090 libraries) will be provided to the other target also. If the
1091 list is empty then no transitive link dependencies will be
1092 incorporated when this target is linked into another target even
1093 if the default set is non-empty. This property is ignored for
1094 STATIC libraries.
1095
1096
1097 LINK_INTERFACE_LIBRARIES_<CONFIG>
1098 Per-configuration list of public interface libraries for a tar‐
1099 get.
1100
1101 This is the configuration-specific version of LINK_INTER‐
1102 FACE_LIBRARIES. If set, this property completely overrides the
1103 generic property for the named configuration.
1104
1105
1106 LINK_INTERFACE_MULTIPLICITY
1107 Repetition count for STATIC libraries with cyclic dependencies.
1108
1109 When linking to a STATIC library target with cyclic dependencies
1110 the linker may need to scan more than once through the archives
1111 in the strongly connected component of the dependency graph.
1112 CMake by default constructs the link line so that the linker
1113 will scan through the component at least twice. This property
1114 specifies the minimum number of scans if it is larger than the
1115 default. CMake uses the largest value specified by any target
1116 in a component.
1117
1118
1119 LINK_INTERFACE_MULTIPLICITY_<CONFIG>
1120 Per-configuration repetition count for cycles of STATIC
1121 libraries.
1122
1123 This is the configuration-specific version of LINK_INTER‐
1124 FACE_MULTIPLICITY. If set, this property completely overrides
1125 the generic property for the named configuration.
1126
1127
1128 LINK_SEARCH_END_STATIC
1129 End a link line such that static system libraries are used.
1130
1131 Some linkers support switches such as -Bstatic and -Bdynamic to
1132 determine whether to use static or shared libraries for -lXXX
1133 options. CMake uses these options to set the link type for
1134 libraries whose full paths are not known or (in some cases) are
1135 in implicit link directories for the platform. By default the
1136 linker search type is left at -Bdynamic by the end of the
1137 library list. This property switches the final linker search
1138 type to -Bstatic.
1139
1140
1141 LOCATION
1142 Read-only location of a target on disk.
1143
1144 For an imported target, this read-only property returns the
1145 value of the LOCATION_<CONFIG> property for an unspecified con‐
1146 figuration <CONFIG> provided by the target.
1147
1148
1149 For a non-imported target, this property is provided for compat‐
1150 ibility with CMake 2.4 and below. It was meant to get the loca‐
1151 tion of an executable target's output file for use in add_cus‐
1152 tom_command. The path may contain a build-system-specific por‐
1153 tion that is replaced at build time with the configuration get‐
1154 ting built (such as "$(ConfigurationName)" in VS). In CMake 2.6
1155 and above add_custom_command automatically recognizes a target
1156 name in its COMMAND and DEPENDS options and computes the target
1157 location. In CMake 2.8.4 and above add_custom_command recog‐
1158 nizes generator expressions to refer to target locations any‐
1159 where in the command. Therefore this property is not needed for
1160 creating custom commands.
1161
1162
1163 Do not set properties that affect the location of the target
1164 after reading this property. These include properties whose
1165 names match "(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIREC‐
1166 TORY)(_<CONFIG>)?" or "(IMPLIB_)?(PREFIX|SUFFIX)". Failure to
1167 follow this rule is not diagnosed and leaves the location of the
1168 target undefined.
1169
1170
1171 LOCATION_<CONFIG>
1172 Read-only property providing a target location on disk.
1173
1174 A read-only property that indicates where a target's main file
1175 is located on disk for the configuration <CONFIG>. The property
1176 is defined only for library and executable targets. An imported
1177 target may provide a set of configurations different from that
1178 of the importing project. By default CMake looks for an
1179 exact-match but otherwise uses an arbitrary available configura‐
1180 tion. Use the MAP_IMPORTED_CONFIG_<CONFIG> property to map
1181 imported configurations explicitly.
1182
1183
1184 Do not set properties that affect the location of the target
1185 after reading this property. These include properties whose
1186 names match "(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIREC‐
1187 TORY)(_<CONFIG>)?" or "(IMPLIB_)?(PREFIX|SUFFIX)". Failure to
1188 follow this rule is not diagnosed and leaves the location of the
1189 target undefined.
1190
1191
1192 MACOSX_BUNDLE
1193 Build an executable as an application bundle on Mac OS X.
1194
1195 When this property is set to true the executable when built on
1196 Mac OS X will be created as an application bundle. This makes
1197 it a GUI executable that can be launched from the Finder. See
1198 the MACOSX_BUNDLE_INFO_PLIST target property for information
1199 about creation of the Info.plist file for the application bun‐
1200 dle.
1201
1202
1203 MACOSX_BUNDLE_INFO_PLIST
1204 Specify a custom Info.plist template for a Mac OS X App Bundle.
1205
1206 An executable target with MACOSX_BUNDLE enabled will be built as
1207 an application bundle on Mac OS X. By default its Info.plist
1208 file is created by configuring a template called MacOSXBundle‐
1209 Info.plist.in located in the CMAKE_MODULE_PATH. This property
1210 specifies an alternative template file name which may be a full
1211 path.
1212
1213
1214 The following target properties may be set to specify content to
1215 be configured into the file:
1216
1217
1218 MACOSX_BUNDLE_INFO_STRING
1219 MACOSX_BUNDLE_ICON_FILE
1220 MACOSX_BUNDLE_GUI_IDENTIFIER
1221 MACOSX_BUNDLE_LONG_VERSION_STRING
1222 MACOSX_BUNDLE_BUNDLE_NAME
1223 MACOSX_BUNDLE_SHORT_VERSION_STRING
1224 MACOSX_BUNDLE_BUNDLE_VERSION
1225 MACOSX_BUNDLE_COPYRIGHT
1226
1227 CMake variables of the same name may be set to affect all tar‐
1228 gets in a directory that do not have each specific property set.
1229 If a custom Info.plist is specified by this property it may of
1230 course hard-code all the settings instead of using the target
1231 properties.
1232
1233
1234 MACOSX_FRAMEWORK_INFO_PLIST
1235 Specify a custom Info.plist template for a Mac OS X Framework.
1236
1237 An library target with FRAMEWORK enabled will be built as a
1238 framework on Mac OS X. By default its Info.plist file is cre‐
1239 ated by configuring a template called MacOSXFramework‐
1240 Info.plist.in located in the CMAKE_MODULE_PATH. This property
1241 specifies an alternative template file name which may be a full
1242 path.
1243
1244
1245 The following target properties may be set to specify content to
1246 be configured into the file:
1247
1248
1249 MACOSX_FRAMEWORK_ICON_FILE
1250 MACOSX_FRAMEWORK_IDENTIFIER
1251 MACOSX_FRAMEWORK_SHORT_VERSION_STRING
1252 MACOSX_FRAMEWORK_BUNDLE_VERSION
1253
1254 CMake variables of the same name may be set to affect all tar‐
1255 gets in a directory that do not have each specific property set.
1256 If a custom Info.plist is specified by this property it may of
1257 course hard-code all the settings instead of using the target
1258 properties.
1259
1260
1261 MAP_IMPORTED_CONFIG_<CONFIG>
1262 Map from project configuration to IMPORTED target's configura‐
1263 tion.
1264
1265 List configurations of an imported target that may be used for
1266 the current project's <CONFIG> configuration. Targets imported
1267 from another project may not provide the same set of configura‐
1268 tion names available in the current project. Setting this prop‐
1269 erty tells CMake what imported configurations are suitable for
1270 use when building the <CONFIG> configuration. The first config‐
1271 uration in the list found to be provided by the imported target
1272 is selected. If no matching configurations are available the
1273 imported target is considered to be not found. This property is
1274 ignored for non-imported targets.
1275
1276
1277 OSX_ARCHITECTURES
1278 Target specific architectures for OS X.
1279
1280 The OSX_ARCHITECTURES property sets the target binary architec‐
1281 ture for targets on OS X. This property is initialized by the
1282 value of the variable CMAKE_OSX_ARCHITECTURES if it is set when
1283 a target is created. Use OSX_ARCHITECTURES_<CONFIG> to set the
1284 binary architectures on a per-configuration basis. <CONFIG> is
1285 an upper-case name (ex: "OSX_ARCHITECTURES_DEBUG").
1286
1287
1288 OSX_ARCHITECTURES_<CONFIG>
1289 Per-configuration OS X binary architectures for a target.
1290
1291 This property is the configuration-specific version of
1292 OSX_ARCHITECTURES.
1293
1294
1295 OUTPUT_NAME
1296 Output name for target files.
1297
1298 This sets the base name for output files created for an exe‐
1299 cutable or library target. If not set, the logical target name
1300 is used by default.
1301
1302
1303 OUTPUT_NAME_<CONFIG>
1304 Per-configuration target file base name.
1305
1306 This is the configuration-specific version of OUTPUT_NAME.
1307
1308
1309 POST_INSTALL_SCRIPT
1310 Deprecated install support.
1311
1312 The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are
1313 the old way to specify CMake scripts to run before and after
1314 installing a target. They are used only when the old
1315 INSTALL_TARGETS command is used to install the target. Use the
1316 INSTALL command instead.
1317
1318
1319 PREFIX What comes before the library name.
1320
1321 A target property that can be set to override the prefix (such
1322 as "lib") on a library name.
1323
1324
1325 PRE_INSTALL_SCRIPT
1326 Deprecated install support.
1327
1328 The PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT properties are
1329 the old way to specify CMake scripts to run before and after
1330 installing a target. They are used only when the old
1331 INSTALL_TARGETS command is used to install the target. Use the
1332 INSTALL command instead.
1333
1334
1335 PRIVATE_HEADER
1336 Specify private header files in a FRAMEWORK shared library tar‐
1337 get.
1338
1339 Shared library targets marked with the FRAMEWORK property gener‐
1340 ate frameworks on OS X and normal shared libraries on other
1341 platforms. This property may be set to a list of header files
1342 to be placed in the PrivateHeaders directory inside the frame‐
1343 work folder. On non-Apple platforms these headers may be
1344 installed using the PRIVATE_HEADER option to the install(TAR‐
1345 GETS) command.
1346
1347
1348 PROJECT_LABEL
1349 Change the name of a target in an IDE.
1350
1351 Can be used to change the name of the target in an IDE like Vis‐
1352 ual Studio.
1353
1354
1355 PUBLIC_HEADER
1356 Specify public header files in a FRAMEWORK shared library tar‐
1357 get.
1358
1359 Shared library targets marked with the FRAMEWORK property gener‐
1360 ate frameworks on OS X and normal shared libraries on other
1361 platforms. This property may be set to a list of header files
1362 to be placed in the Headers directory inside the framework
1363 folder. On non-Apple platforms these headers may be installed
1364 using the PUBLIC_HEADER option to the install(TARGETS) command.
1365
1366
1367 RESOURCE
1368 Specify resource files in a FRAMEWORK shared library target.
1369
1370 Shared library targets marked with the FRAMEWORK property gener‐
1371 ate frameworks on OS X and normal shared libraries on other
1372 platforms. This property may be set to a list of files to be
1373 placed in the Resources directory inside the framework folder.
1374 On non-Apple platforms these files may be installed using the
1375 RESOURCE option to the install(TARGETS) command.
1376
1377
1378 RULE_LAUNCH_COMPILE
1379 Specify a launcher for compile rules.
1380
1381 See the global property of the same name for details. This
1382 overrides the global and directory property for a target.
1383
1384
1385 RULE_LAUNCH_CUSTOM
1386 Specify a launcher for custom rules.
1387
1388 See the global property of the same name for details. This
1389 overrides the global and directory property for a target.
1390
1391
1392 RULE_LAUNCH_LINK
1393 Specify a launcher for link rules.
1394
1395 See the global property of the same name for details. This
1396 overrides the global and directory property for a target.
1397
1398
1399 RUNTIME_OUTPUT_DIRECTORY
1400 Output directory in which to build RUNTIME target files.
1401
1402 This property specifies the directory into which runtime target
1403 files should be built. Multi-configuration generators (VS,
1404 Xcode) append a per-configuration subdirectory to the specified
1405 directory. There are three kinds of target files that may be
1406 built: archive, library, and runtime. Executables are always
1407 treated as runtime targets. Static libraries are always treated
1408 as archive targets. Module libraries are always treated as
1409 library targets. For non-DLL platforms shared libraries are
1410 treated as library targets. For DLL platforms the DLL part of a
1411 shared library is treated as a runtime target and the corre‐
1412 sponding import library is treated as an archive target. All
1413 Windows-based systems including Cygwin are DLL platforms. This
1414 property is initialized by the value of the variable CMAKE_RUN‐
1415 TIME_OUTPUT_DIRECTORY if it is set when a target is created.
1416
1417
1418 RUNTIME_OUTPUT_DIRECTORY_<CONFIG>
1419 Per-configuration output directory for RUNTIME target files.
1420
1421 This is a per-configuration version of RUNTIME_OUTPUT_DIRECTORY,
1422 but multi-configuration generators (VS, Xcode) do NOT append a
1423 per-configuration subdirectory to the specified directory. This
1424 property is initialized by the value of the variable CMAKE_RUN‐
1425 TIME_OUTPUT_DIRECTORY_<CONFIG> if it is set when a target is
1426 created.
1427
1428
1429 RUNTIME_OUTPUT_NAME
1430 Output name for RUNTIME target files.
1431
1432 This property specifies the base name for runtime target files.
1433 It overrides OUTPUT_NAME and OUTPUT_NAME_<CONFIG> properties.
1434 There are three kinds of target files that may be built: ar‐
1435 chive, library, and runtime. Executables are always treated as
1436 runtime targets. Static libraries are always treated as archive
1437 targets. Module libraries are always treated as library targets.
1438 For non-DLL platforms shared libraries are treated as library
1439 targets. For DLL platforms the DLL part of a shared library is
1440 treated as a runtime target and the corresponding import library
1441 is treated as an archive target. All Windows-based systems
1442 including Cygwin are DLL platforms.
1443
1444
1445 RUNTIME_OUTPUT_NAME_<CONFIG>
1446 Per-configuration output name for RUNTIME target files.
1447
1448 This is the configuration-specific version of RUNTIME_OUT‐
1449 PUT_NAME.
1450
1451
1452 SKIP_BUILD_RPATH
1453 Should rpaths be used for the build tree.
1454
1455 SKIP_BUILD_RPATH is a boolean specifying whether to skip auto‐
1456 matic generation of an rpath allowing the target to run from the
1457 build tree. This property is initialized by the value of the
1458 variable CMAKE_SKIP_BUILD_RPATH if it is set when a target is
1459 created.
1460
1461
1462 SOURCES
1463 Source names specified for a target.
1464
1465 Read-only list of sources specified for a target. The names
1466 returned are suitable for passing to the set_source_files_prop‐
1467 erties command.
1468
1469
1470 SOVERSION
1471 What version number is this target.
1472
1473 For shared libraries VERSION and SOVERSION can be used to spec‐
1474 ify the build version and api version respectively. When build‐
1475 ing or installing appropriate symlinks are created if the plat‐
1476 form supports symlinks and the linker supports so-names. If only
1477 one of both is specified the missing is assumed to have the same
1478 version number. For shared libraries and executables on Windows
1479 the VERSION attribute is parsed to extract a "major.minor" ver‐
1480 sion number. These numbers are used as the image version of the
1481 binary.
1482
1483
1484 STATIC_LIBRARY_FLAGS
1485 Extra flags to use when linking static libraries.
1486
1487 Extra flags to use when linking a static library.
1488
1489
1490 STATIC_LIBRARY_FLAGS_<CONFIG>
1491 Per-configuration flags for creating a static library.
1492
1493 This is the configuration-specific version of
1494 STATIC_LIBRARY_FLAGS.
1495
1496
1497 SUFFIX What comes after the library name.
1498
1499 A target property that can be set to override the suffix (such
1500 as ".so") on a library name.
1501
1502
1503 TYPE The type of the target.
1504
1505 This read-only property can be used to test the type of the
1506 given target. It will be one of STATIC_LIBRARY, MODULE_LIBRARY,
1507 SHARED_LIBRARY, EXECUTABLE or one of the internal target types.
1508
1509
1510 VERSION
1511 What version number is this target.
1512
1513 For shared libraries VERSION and SOVERSION can be used to spec‐
1514 ify the build version and api version respectively. When build‐
1515 ing or installing appropriate symlinks are created if the plat‐
1516 form supports symlinks and the linker supports so-names. If only
1517 one of both is specified the missing is assumed to have the same
1518 version number. For executables VERSION can be used to specify
1519 the build version. When building or installing appropriate sym‐
1520 links are created if the platform supports symlinks. For shared
1521 libraries and executables on Windows the VERSION attribute is
1522 parsed to extract a "major.minor" version number. These numbers
1523 are used as the image version of the binary.
1524
1525
1526 VS_KEYWORD
1527 Visual Studio project keyword.
1528
1529 Can be set to change the visual studio keyword, for example QT
1530 integration works better if this is set to Qt4VSv1.0.
1531
1532
1533 VS_SCC_LOCALPATH
1534 Visual Studio Source Code Control Provider.
1535
1536 Can be set to change the visual studio source code control local
1537 path property.
1538
1539
1540 VS_SCC_PROJECTNAME
1541 Visual Studio Source Code Control Project.
1542
1543 Can be set to change the visual studio source code control
1544 project name property.
1545
1546
1547 VS_SCC_PROVIDER
1548 Visual Studio Source Code Control Provider.
1549
1550 Can be set to change the visual studio source code control
1551 provider property.
1552
1553
1554 WIN32_EXECUTABLE
1555 Build an executable with a WinMain entry point on windows.
1556
1557 When this property is set to true the executable when linked on
1558 Windows will be created with a WinMain() entry point instead of
1559 of just main().This makes it a GUI executable instead of a con‐
1560 sole application. See the CMAKE_MFC_FLAG variable documentation
1561 to configure use of MFC for WinMain executables.
1562
1563
1564 XCODE_ATTRIBUTE_<an-attribute>
1565 Set Xcode target attributes directly.
1566
1567 Tell the Xcode generator to set '<an-attribute>' to a given
1568 value in the generated Xcode project. Ignored on other genera‐
1569 tors.
1570
1571
1573 ATTACHED_FILES
1574 Attach a list of files to a dashboard submission.
1575
1576 Set this property to a list of files that will be encoded and
1577 submitted to the dashboard as an addition to the test result.
1578
1579
1580 ATTACHED_FILES_ON_FAIL
1581 Attach a list of files to a dashboard submission if the test
1582 fails.
1583
1584 Same as ATTACHED_FILES, but these files will only be included if
1585 the test does not pass.
1586
1587
1588 COST Set this to a floating point value. Tests in a test set will be
1589 run in descending order of cost.
1590
1591 This property describes the cost of a test. You can explicitly
1592 set this value; tests with higher COST values will run first.
1593
1594
1595 DEPENDS
1596 Specifies that this test should only be run after the specified
1597 list of tests.
1598
1599 Set this to a list of tests that must finish before this test is
1600 run.
1601
1602
1603 ENVIRONMENT
1604 Specify environment variables that should be defined for running
1605 a test.
1606
1607 If set to a list of environment variables and values of the form
1608 MYVAR=value those environment variables will be defined while
1609 running the test. The environment is restored to its previous
1610 state after the test is done.
1611
1612
1613 FAIL_REGULAR_EXPRESSION
1614 If the output matches this regular expression the test will
1615 fail.
1616
1617 If set, if the output matches one of specified regular expres‐
1618 sions, the test will fail.For example: PASS_REGULAR_EXPRESSION
1619 "[^a-z]Error;ERROR;Failed"
1620
1621
1622 LABELS Specify a list of text labels associated with a test.
1623
1624 The list is reported in dashboard submissions.
1625
1626
1627 MEASUREMENT
1628 Specify a CDASH measurement and value to be reported for a test.
1629
1630 If set to a name then that name will be reported to CDASH as a
1631 named measurement with a value of 1. You may also specify a
1632 value by setting MEASUREMENT to "measurement=value".
1633
1634
1635 PASS_REGULAR_EXPRESSION
1636 The output must match this regular expression for the test to
1637 pass.
1638
1639 If set, the test output will be checked against the specified
1640 regular expressions and at least one of the regular expressions
1641 has to match, otherwise the test will fail.
1642
1643
1644 PROCESSORS
1645 How many process slots this test requires
1646
1647 Denotes the number of processors that this test will require.
1648 This is typically used for MPI tests, and should be used in con‐
1649 junction with the ctest_test PARALLEL_LEVEL option.
1650
1651
1652 REQUIRED_FILES
1653 List of files required to run the test.
1654
1655 If set to a list of files, the test will not be run unless all
1656 of the files exist.
1657
1658
1659 RESOURCE_LOCK
1660 Specify a list of resources that are locked by this test.
1661
1662 If multiple tests specify the same resource lock, they are guar‐
1663 anteed not to run concurrently.
1664
1665
1666 RUN_SERIAL
1667 Do not run this test in parallel with any other test.
1668
1669 Use this option in conjunction with the ctest_test PARAL‐
1670 LEL_LEVEL option to specify that this test should not be run in
1671 parallel with any other tests.
1672
1673
1674 TIMEOUT
1675 How many seconds to allow for this test.
1676
1677 This property if set will limit a test to not take more than the
1678 specified number of seconds to run. If it exceeds that the test
1679 process will be killed and ctest will move to the next test.
1680 This setting takes precedence over CTEST_TESTING_TIMEOUT.
1681
1682
1683 WILL_FAIL
1684 If set to true, this will invert the pass/fail flag of the test.
1685
1686 This property can be used for tests that are expected to fail
1687 and return a non zero return code.
1688
1689
1690 WORKING_DIRECTORY
1691 The directory from which the test executable will be called.
1692
1693 If this is not set it is called from the directory the test exe‐
1694 cutable is located in.
1695
1696
1698 ABSTRACT
1699 Is this source file an abstract class.
1700
1701 A property on a source file that indicates if the source file
1702 represents a class that is abstract. This only makes sense for
1703 languages that have a notion of an abstract class and it is only
1704 used by some tools that wrap classes into other languages.
1705
1706
1707 COMPILE_DEFINITIONS
1708 Preprocessor definitions for compiling a source file.
1709
1710 The COMPILE_DEFINITIONS property may be set to a semicolon-sepa‐
1711 rated list of preprocessor definitions using the syntax VAR or
1712 VAR=value. Function-style definitions are not supported. CMake
1713 will automatically escape the value correctly for the native
1714 build system (note that CMake language syntax may require
1715 escapes to specify some values). This property may be set on a
1716 per-configuration basis using the name COMPILE_DEFINITIONS_<CON‐
1717 FIG> where <CONFIG> is an upper-case name (ex. "COMPILE_DEFINI‐
1718 TIONS_DEBUG").
1719
1720
1721 CMake will automatically drop some definitions that are not sup‐
1722 ported by the native build tool. The VS6 IDE does not support
1723 definition values with spaces (but NMake does). Xcode does not
1724 support per-configuration definitions on source files.
1725
1726
1727 Disclaimer: Most native build tools have poor support for escap‐
1728 ing certain values. CMake has work-arounds for many cases but
1729 some values may just not be possible to pass correctly. If a
1730 value does not seem to be escaped correctly, do not attempt to
1731 work-around the problem by adding escape sequences to the value.
1732 Your work-around may break in a future version of CMake that has
1733 improved escape support. Instead consider defining the macro in
1734 a (configured) header file. Then report the limitation. Known
1735 limitations include:
1736
1737
1738 # - broken almost everywhere
1739 ; - broken in VS IDE and Borland Makefiles
1740 , - broken in VS IDE
1741 % - broken in some cases in NMake
1742 & | - broken in some cases on MinGW
1743 ^ < > \" - broken in most Make tools on Windows
1744
1745 CMake does not reject these values outright because they do work
1746 in some cases. Use with caution.
1747
1748
1749 COMPILE_DEFINITIONS_<CONFIG>
1750 Per-configuration preprocessor definitions on a source file.
1751
1752 This is the configuration-specific version of COMPILE_DEFINI‐
1753 TIONS. Note that Xcode does not support per-configuration
1754 source file flags so this property will be ignored by the Xcode
1755 generator.
1756
1757
1758 COMPILE_FLAGS
1759 Additional flags to be added when compiling this source file.
1760
1761 These flags will be added to the list of compile flags when this
1762 source file builds. Use COMPILE_DEFINITIONS to pass additional
1763 preprocessor definitions.
1764
1765
1766 EXTERNAL_OBJECT
1767 If set to true then this is an object file.
1768
1769 If this property is set to true then the source file is really
1770 an object file and should not be compiled. It will still be
1771 linked into the target though.
1772
1773
1774 GENERATED
1775 Is this source file generated as part of the build process.
1776
1777 If a source file is generated by the build process CMake will
1778 handle it differently in terms of dependency checking etc. Oth‐
1779 erwise having a non-existent source file could create problems.
1780
1781
1782 HEADER_FILE_ONLY
1783 Is this source file only a header file.
1784
1785 A property on a source file that indicates if the source file is
1786 a header file with no associated implementation. This is set
1787 automatically based on the file extension and is used by CMake
1788 to determine is certain dependency information should be com‐
1789 puted.
1790
1791
1792 KEEP_EXTENSION
1793 Make the output file have the same extension as the source file.
1794
1795 If this property is set then the file extension of the output
1796 file will be the same as that of the source file. Normally the
1797 output file extension is computed based on the language of the
1798 source file, for example .cxx will go to a .o extension.
1799
1800
1801 LABELS Specify a list of text labels associated with a source file.
1802
1803 This property has meaning only when the source file is listed in
1804 a target whose LABELS property is also set. No other semantics
1805 are currently specified.
1806
1807
1808 LANGUAGE
1809 What programming language is the file.
1810
1811 A property that can be set to indicate what programming language
1812 the source file is. If it is not set the language is determined
1813 based on the file extension. Typical values are CXX C etc. Set‐
1814 ting this property for a file means this file will be compiled.
1815 Do not set this for header or files that should not be compiled.
1816
1817
1818 LOCATION
1819 The full path to a source file.
1820
1821 A read only property on a SOURCE FILE that contains the full
1822 path to the source file.
1823
1824
1825 MACOSX_PACKAGE_LOCATION
1826 Place a source file inside a Mac OS X bundle or framework.
1827
1828 Executable targets with the MACOSX_BUNDLE property set are built
1829 as Mac OS X application bundles on Apple platforms. Shared
1830 library targets with the FRAMEWORK property set are built as Mac
1831 OS X frameworks on Apple platforms. Source files listed in the
1832 target with this property set will be copied to a directory
1833 inside the bundle or framework content folder specified by the
1834 property value. For bundles the content folder is
1835 "<name>.app/Contents". For frameworks the content folder is
1836 "<name>.framework/Versions/<version>". See the PUBLIC_HEADER,
1837 PRIVATE_HEADER, and RESOURCE target properties for specifying
1838 files meant for Headers, PrivateHeaders, or Resources directo‐
1839 ries.
1840
1841
1842 OBJECT_DEPENDS
1843 Additional files on which a compiled object file depends.
1844
1845 Specifies a semicolon-separated list of full-paths to files on
1846 which any object files compiled from this source file depend.
1847 An object file will be recompiled if any of the named files is
1848 newer than it.
1849
1850
1851 This property need not be used to specify the dependency of a
1852 source file on a generated header file that it includes.
1853 Although the property was originally introduced for this pur‐
1854 pose, it is no longer necessary. If the generated header file
1855 is created by a custom command in the same target as the source
1856 file, the automatic dependency scanning process will recognize
1857 the dependency. If the generated header file is created by
1858 another target, an inter-target dependency should be created
1859 with the add_dependencies command (if one does not already exist
1860 due to linking relationships).
1861
1862
1863 OBJECT_OUTPUTS
1864 Additional outputs for a Makefile rule.
1865
1866 Additional outputs created by compilation of this source file.
1867 If any of these outputs is missing the object will be recom‐
1868 piled. This is supported only on Makefile generators and will be
1869 ignored on other generators.
1870
1871
1872 SYMBOLIC
1873 Is this just a name for a rule.
1874
1875 If SYMBOLIC (boolean) is set to true the build system will be
1876 informed that the source file is not actually created on disk
1877 but instead used as a symbolic name for a build rule.
1878
1879
1880 WRAP_EXCLUDE
1881 Exclude this source file from any code wrapping techniques.
1882
1883 Some packages can wrap source files into alternate languages to
1884 provide additional functionality. For example, C++ code can be
1885 wrapped into Java or Python etc using SWIG etc. If WRAP_EXCLUDE
1886 is set to true (1 etc) that indicates then this source file
1887 should not be wrapped.
1888
1889
1891 ADVANCED
1892 True if entry should be hidden by default in GUIs.
1893
1894 This is a boolean value indicating whether the entry is consid‐
1895 ered interesting only for advanced configuration. The
1896 mark_as_advanced() command modifies this property.
1897
1898
1899 HELPSTRING
1900 Help associated with entry in GUIs.
1901
1902 This string summarizes the purpose of an entry to help users set
1903 it through a CMake GUI.
1904
1905
1906 MODIFIED
1907 Internal management property. Do not set or get.
1908
1909 This is an internal cache entry property managed by CMake to
1910 track interactive user modification of entries. Ignore it.
1911
1912
1913 STRINGS
1914 Enumerate possible STRING entry values for GUI selection.
1915
1916 For cache entries with type STRING, this enumerates a set of
1917 values. CMake GUIs may use this to provide a selection widget
1918 instead of a generic string entry field. This is for conve‐
1919 nience only. CMake does not enforce that the value matches one
1920 of those listed.
1921
1922
1923 TYPE Widget type for entry in GUIs.
1924
1925 Cache entry values are always strings, but CMake GUIs present
1926 widgets to help users set values. The GUIs use this property as
1927 a hint to determine the widget type. Valid TYPE values are:
1928
1929
1930 BOOL = Boolean ON/OFF value.
1931 PATH = Path to a directory.
1932 FILEPATH = Path to a file.
1933 STRING = Generic string value.
1934 INTERNAL = Do not present in GUI at all.
1935 STATIC = Value managed by CMake, do not change.
1936 UNINITIALIZED = Type not yet specified.
1937
1938 Generally the TYPE of a cache entry should be set by the command
1939 which creates it (set, option, find_library, etc.).
1940
1941
1942 VALUE Value of a cache entry.
1943
1944 This property maps to the actual value of a cache entry. Set‐
1945 ting this property always sets the value without checking, so
1946 use with care.
1947
1948
1950 Copyright 2000-2009 Kitware, Inc., Insight Software Consortium. All
1951 rights reserved.
1952
1953
1954 Redistribution and use in source and binary forms, with or without mod‐
1955 ification, are permitted provided that the following conditions are
1956 met:
1957
1958
1959 Redistributions of source code must retain the above copyright notice,
1960 this list of conditions and the following disclaimer.
1961
1962
1963 Redistributions in binary form must reproduce the above copyright
1964 notice, this list of conditions and the following disclaimer in the
1965 documentation and/or other materials provided with the distribution.
1966
1967
1968 Neither the names of Kitware, Inc., the Insight Software Consortium,
1969 nor the names of their contributors may be used to endorse or promote
1970 products derived from this software without specific prior written per‐
1971 mission.
1972
1973
1974 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
1975 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
1976 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
1977 ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
1978 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
1979 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
1980 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
1981 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
1982 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
1983 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
1984 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1985
1986
1988 The following resources are available to get help using CMake:
1989
1990
1991 Home Page
1992 http://www.cmake.org
1993
1994 The primary starting point for learning about CMake.
1995
1996
1997 Frequently Asked Questions
1998 http://www.cmake.org/Wiki/CMake_FAQ
1999
2000 A Wiki is provided containing answers to frequently asked ques‐
2001 tions.
2002
2003
2004 Online Documentation
2005 http://www.cmake.org/HTML/Documentation.html
2006
2007 Links to available documentation may be found on this web page.
2008
2009
2010 Mailing List
2011 http://www.cmake.org/HTML/MailingLists.html
2012
2013 For help and discussion about using cmake, a mailing list is
2014 provided at cmake@cmake.org. The list is member-post-only but
2015 one may sign up on the CMake web page. Please first read the
2016 full documentation at http://www.cmake.org before posting ques‐
2017 tions to the list.
2018
2019
2020 Summary of helpful links:
2021
2022
2023 Home: http://www.cmake.org
2024 Docs: http://www.cmake.org/HTML/Documentation.html
2025 Mail: http://www.cmake.org/HTML/MailingLists.html
2026 FAQ: http://www.cmake.org/Wiki/CMake_FAQ
2027
2028
2029
2030
2031cmake 2.8.4 March 31, 2011 cmakeprops(1)