1CMAKE-MODULES(7) CMake CMAKE-MODULES(7)
2
6 cmake-modules - CMake Modules Reference
7 The modules listed here are part of the CMake distribution. Projects
9 may provide further modules; their location(s) can be specified in the
10 CMAKE_MODULE_PATH variable.
11
13 These modules are loaded using the include() command.
14 AndroidTestUtilities
16 New in version 3.7.
17 Create a test that automatically loads specified data onto an Android
20 device.
21 Introduction
23 Use this module to push data needed for testing an Android device be‐
24 havior onto a connected Android device. The module will accept files
25 and libraries as well as separate destinations for each. It will create
26 a test that loads the files into a device object store and link to them
27 from the specified destination. The files are only uploaded if they are
28 not already in the object store.
29 For example:
31 include(AndroidTestUtilities)
33 android_add_test_data(
34 example_setup_test
35 FILES <files>...
36 LIBS <libs>...
37 DEVICE_TEST_DIR "/data/local/tests/example"
38 DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA"
39 )
40 At build time a test named "example_setup_test" will be created. Run
42 this test on the command line with ctest(1) to load the data onto the
43 Android device.
44 Module Functions
46 android_add_test_data
47 android_add_test_data(<test-name>
49 [FILES <files>...] [FILES_DEST <device-dir>]
50 [LIBS <libs>...] [LIBS_DEST <device-dir>]
51 [DEVICE_OBJECT_STORE <device-dir>]
52 [DEVICE_TEST_DIR <device-dir>]
53 [NO_LINK_REGEX <strings>...]
54 )
55 The android_add_test_data function is used to copy files and li‐
57 braries needed to run project-specific tests. On the host oper‐
58 ating system, this is done at build time. For on-device testing,
59 the files are loaded onto the device by the manufactured test at
60 run time.
61 This function accepts the following named parameters:
63 FILES <files>...
65 zero or more files needed for testing
66 LIBS <libs>...
68 zero or more libraries needed for testing
69 FILES_DEST <device-dir>
71 absolute path where the data files are expected to be
72 LIBS_DEST <device-dir>
74 absolute path where the libraries are expected to be
75 DEVICE_OBJECT_STORE <device-dir>
77 absolute path to the location where the data is stored
78 on-device
79 DEVICE_TEST_DIR <device-dir>
81 absolute path to the root directory of the on-device test
82 location
83 NO_LINK_REGEX <strings>...
85 list of regex strings matching the names of files that
86 should be copied from the object store to the testing di‐
87 rectory
88 BundleUtilities
90 Functions to help assemble a standalone bundle application.
91 A collection of CMake utility functions useful for dealing with .app
93 bundles on the Mac and bundle-like directories on any OS.
94 The following functions are provided by this module:
96 fixup_bundle
98 copy_and_fixup_bundle
99 verify_app
100 get_bundle_main_executable
101 get_dotapp_dir
102 get_bundle_and_executable
103 get_bundle_all_executables
104 get_item_key
105 get_item_rpaths
106 clear_bundle_keys
107 set_bundle_key_values
108 get_bundle_keys
109 copy_resolved_item_into_bundle
110 copy_resolved_framework_into_bundle
111 fixup_bundle_item
112 verify_bundle_prerequisites
113 verify_bundle_symlinks
114 Requires CMake 2.6 or greater because it uses function, break and PAR‐
116 ENT_SCOPE. Also depends on GetPrerequisites.cmake.
117 DO NOT USE THESE FUNCTIONS AT CONFIGURE TIME (from CMakeLists.txt)!
119 Instead, invoke them from an install(CODE) or install(SCRIPT) rule.
120 fixup_bundle(<app> <libs> <dirs>)
122 Fix up <app> bundle in-place and make it standalone, such that it can
124 be drag-n-drop copied to another machine and run on that machine as
125 long as all of the system libraries are compatible.
126 If you pass plugins to fixup_bundle as the libs parameter, you should
128 install them or copy them into the bundle before calling fixup_bundle.
129 The <libs> parameter is a list of libraries that must be fixed up, but
130 that cannot be determined by otool output analysis (i.e. plugins).
131 Gather all the keys for all the executables and libraries in a bundle,
133 and then, for each key, copy each prerequisite into the bundle. Then
134 fix each one up according to its own list of prerequisites.
135 Then clear all the keys and call verify_app on the final bundle to en‐
137 sure that it is truly standalone.
138 New in version 3.6: As an optional parameter (IGNORE_ITEM) a list of
140 file names can be passed, which are then ignored (e.g. IGNORE_ITEM
141 "vcredist_x86.exe;vcredist_x64.exe").
142 copy_and_fixup_bundle(<src> <dst> <libs> <dirs>)
145 Makes a copy of the bundle <src> at location <dst> and then fixes up
147 the new copied bundle in-place at <dst>.
148 verify_app(<app>)
150 Verifies that an application <app> appears valid based on running
152 analysis tools on it. Calls message(FATAL_ERROR) if the application is
153 not verified.
154 New in version 3.6: As an optional parameter (IGNORE_ITEM) a list of
156 file names can be passed, which are then ignored (e.g. IGNORE_ITEM
157 "vcredist_x86.exe;vcredist_x64.exe")
158 get_bundle_main_executable(<bundle> <result_var>)
161 The result will be the full path name of the bundle's main executable
163 file or an error: prefixed string if it could not be determined.
164 get_dotapp_dir(<exe> <dotapp_dir_var>)
166 Returns the nearest parent dir whose name ends with .app given the full
168 path to an executable. If there is no such parent dir, then simply re‐
169 turn the dir containing the executable.
170 The returned directory may or may not exist.
172 get_bundle_and_executable(<app> <bundle_var> <executable_var> <valid_var>)
174 Takes either a .app directory name or the name of an executable nested
176 inside a .app directory and returns the path to the .app directory in
177 <bundle_var> and the path to its main executable in <executable_var>.
178 get_bundle_all_executables(<bundle> <exes_var>)
180 Scans <bundle> bundle recursively for all <exes_var> executable files
182 and accumulates them into a variable.
183 get_item_key(<item> <key_var>)
185 Given <item> file name, generate <key_var> key that should be unique
187 considering the set of libraries that need copying or fixing up to make
188 a bundle standalone. This is essentially the file name including ex‐
189 tension with . replaced by _
190 This key is used as a prefix for CMake variables so that we can asso‐
192 ciate a set of variables with a given item based on its key.
193 clear_bundle_keys(<keys_var>)
195 Loop over the <keys_var> list of keys, clearing all the variables asso‐
197 ciated with each key. After the loop, clear the list of keys itself.
198 Caller of get_bundle_keys should call clear_bundle_keys when done with
200 list of keys.
201 set_bundle_key_values(<keys_var> <context> <item> <exepath> <dirs>
203 <copyflag> [<rpaths>])
204 Add <keys_var> key to the list (if necessary) for the given item. If
206 added, also set all the variables associated with that key.
207 get_bundle_keys(<app> <libs> <dirs> <keys_var>)
209 Loop over all the executable and library files within <app> bundle (and
211 given as extra <libs>) and accumulate a list of keys representing them.
212 Set values associated with each key such that we can loop over all of
213 them and copy prerequisite libs into the bundle and then do appropriate
214 install_name_tool fixups.
215 New in version 3.6: As an optional parameter (IGNORE_ITEM) a list of
217 file names can be passed, which are then ignored (e.g. IGNORE_ITEM
218 "vcredist_x86.exe;vcredist_x64.exe")
219 copy_resolved_item_into_bundle(<resolved_item> <resolved_embedded_item>)
222 Copy a resolved item into the bundle if necessary. Copy is not neces‐
224 sary, if the <resolved_item> is "the same as" the <resolved_embed‐
225 ded_item>.
226 copy_resolved_framework_into_bundle(<resolved_item> <resolved_embedded_item>)
228 Copy a resolved framework into the bundle if necessary. Copy is not
230 necessary, if the <resolved_item> is "the same as" the <resolved_embed‐
231 ded_item>.
232 By default, BU_COPY_FULL_FRAMEWORK_CONTENTS is not set. If you want
234 full frameworks embedded in your bundles, set BU_COPY_FULL_FRAME‐
235 WORK_CONTENTS to ON before calling fixup_bundle. By default, COPY_RE‐
236 SOLVED_FRAMEWORK_INTO_BUNDLE copies the framework dylib itself plus the
237 framework Resources directory.
238 fixup_bundle_item(<resolved_embedded_item> <exepath> <dirs>)
240 Get the direct/non-system prerequisites of the <resolved_embed‐
242 ded_item>. For each prerequisite, change the way it is referenced to
243 the value of the _EMBEDDED_ITEM keyed variable for that prerequisite.
244 (Most likely changing to an @executable_path style reference.)
245 This function requires that the <resolved_embedded_item> be inside the
247 bundle already. In other words, if you pass plugins to fixup_bundle as
248 the libs parameter, you should install them or copy them into the bun‐
249 dle before calling fixup_bundle. The libs parameter is a list of li‐
250 braries that must be fixed up, but that cannot be determined by otool
251 output analysis. (i.e., plugins)
252 Also, change the id of the item being fixed up to its own _EMBED‐
254 DED_ITEM value.
255 Accumulate changes in a local variable and make one call to in‐
257 stall_name_tool at the end of the function with all the changes at
258 once.
259 If the BU_CHMOD_BUNDLE_ITEMS variable is set then bundle items will be
261 marked writable before install_name_tool tries to change them.
262 verify_bundle_prerequisites(<bundle> <result_var> <info_var>)
264 Verifies that the sum of all prerequisites of all files inside the bun‐
266 dle are contained within the bundle or are system libraries, presumed
267 to exist everywhere.
268 New in version 3.6: As an optional parameter (IGNORE_ITEM) a list of
270 file names can be passed, which are then ignored (e.g. IGNORE_ITEM
271 "vcredist_x86.exe;vcredist_x64.exe")
272 verify_bundle_symlinks(<bundle> <result_var> <info_var>)
275 Verifies that any symlinks found in the <bundle> bundle point to other
277 files that are already also in the bundle... Anything that points to
278 an external file causes this function to fail the verification.
279 CheckCCompilerFlag
281 Check whether the C compiler supports a given flag.
282 check_c_compiler_flag
284 check_c_compiler_flag(<flag> <resultVar>)
286 Check that the <flag> is accepted by the compiler without a di‐
288 agnostic. Stores the result in an internal cache entry named
289 <resultVar>.
290 A positive result from this check indicates only that the compiler did
292 not issue a diagnostic message when given the flag. Whether the flag
293 has any effect or even a specific one is beyond the scope of this mod‐
294 ule.
295 The check is only performed once, with the result cached in the vari‐
297 able named by <resultVar>. Every subsequent CMake run will re-use this
298 cached value rather than performing the check again, even if the <code>
299 changes. In order to force the check to be re-evaluated, the variable
300 named by <resultVar> must be manually removed from the cache.
301 The compile and link commands can be influenced by setting any of the
303 following variables prior to calling check_c_compiler_flag()
304 CMAKE_REQUIRED_FLAGS
306 String of additional flags to pass to the compiler. The
307 string must be space-delimited--a ;-list will not work. The
308 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
309 tion-specific variable are automatically added to the com‐
310 piler command before the contents of CMAKE_REQUIRED_FLAGS.
311 CMAKE_REQUIRED_DEFINITIONS
313 A ;-list of compiler definitions of the form -DFOO or
314 -DFOO=bar. A definition for the name specified by <resultVar>
315 will also be added automatically.
316 CMAKE_REQUIRED_INCLUDES
318 A ;-list of header search paths to pass to the compiler.
319 These will be the only header search paths used--the contents
320 of the INCLUDE_DIRECTORIES directory property will be ig‐
321 nored.
322 CMAKE_REQUIRED_LINK_OPTIONS
324 New in version 3.14.
325 A ;-list of options to add to the link command (see
328 try_compile() for further details).
329 CMAKE_REQUIRED_LIBRARIES
331 A ;-list of libraries to add to the link command. These can
332 be the name of system libraries or they can be Imported Tar‐
333 gets (see try_compile() for further details).
334 CMAKE_REQUIRED_QUIET
336 New in version 3.1.
337 If this variable evaluates to a boolean true value, all sta‐
340 tus messages associated with the check will be suppressed.
341 CheckCompilerFlag
343 New in version 3.19.
344 Check whether the compiler supports a given flag.
347 check_compiler_flag
349 check_compiler_flag(<lang> <flag> <resultVar>)
351 Check that the <flag> is accepted by the compiler without a diagnostic.
353 Stores the result in an internal cache entry named <resultVar>.
354 A positive result from this check indicates only that the compiler did
356 not issue a diagnostic message when given the flag. Whether the flag
357 has any effect or even a specific one is beyond the scope of this mod‐
358 ule.
359 The check is only performed once, with the result cached in the vari‐
361 able named by <resultVar>. Every subsequent CMake run will re-use this
362 cached value rather than performing the check again, even if the <code>
363 changes. In order to force the check to be re-evaluated, the variable
364 named by <resultVar> must be manually removed from the cache.
365 The compile and link commands can be influenced by setting any of the
367 following variables prior to calling check_compiler_flag()
368 CMAKE_REQUIRED_FLAGS
370 String of additional flags to pass to the compiler. The
371 string must be space-delimited--a ;-list will not work. The
372 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
373 tion-specific variable are automatically added to the com‐
374 piler command before the contents of CMAKE_REQUIRED_FLAGS.
375 CMAKE_REQUIRED_DEFINITIONS
377 A ;-list of compiler definitions of the form -DFOO or
378 -DFOO=bar. A definition for the name specified by <resultVar>
379 will also be added automatically.
380 CMAKE_REQUIRED_INCLUDES
382 A ;-list of header search paths to pass to the compiler.
383 These will be the only header search paths used--the contents
384 of the INCLUDE_DIRECTORIES directory property will be ig‐
385 nored.
386 CMAKE_REQUIRED_LINK_OPTIONS
388 New in version 3.14.
389 A ;-list of options to add to the link command (see
392 try_compile() for further details).
393 CMAKE_REQUIRED_LIBRARIES
395 A ;-list of libraries to add to the link command. These can
396 be the name of system libraries or they can be Imported Tar‐
397 gets (see try_compile() for further details).
398 CMAKE_REQUIRED_QUIET
400 New in version 3.1.
401 If this variable evaluates to a boolean true value, all sta‐
404 tus messages associated with the check will be suppressed.
405 CheckCSourceCompiles
407 Check if given C source compiles and links into an executable.
408 check_c_source_compiles
410 check_c_source_compiles(<code> <resultVar>
412 [FAIL_REGEX <regex1> [<regex2>...]])
413 Check that the source supplied in <code> can be compiled as a C
415 source file and linked as an executable (so it must contain at
416 least a main() function). The result will be stored in the in‐
417 ternal cache variable specified by <resultVar>, with a boolean
418 true value for success and boolean false for failure. If
419 FAIL_REGEX is provided, then failure is determined by checking
420 if anything in the output matches any of the specified regular
421 expressions.
422 The check is only performed once, with the result cached in the
424 variable named by <resultVar>. Every subsequent CMake run will
425 re-use this cached value rather than performing the check again,
426 even if the <code> changes. In order to force the check to be
427 re-evaluated, the variable named by <resultVar> must be manually
428 removed from the cache.
429 The compile and link commands can be influenced by setting any
431 of the following variables prior to calling check_c_source_com‐
432 piles():
433 CMAKE_REQUIRED_FLAGS
435 String of additional flags to pass to the compiler. The
436 string must be space-delimited--a ;-list will not work. The
437 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
438 tion-specific variable are automatically added to the com‐
439 piler command before the contents of CMAKE_REQUIRED_FLAGS.
440 CMAKE_REQUIRED_DEFINITIONS
442 A ;-list of compiler definitions of the form -DFOO or
443 -DFOO=bar. A definition for the name specified by <resultVar>
444 will also be added automatically.
445 CMAKE_REQUIRED_INCLUDES
447 A ;-list of header search paths to pass to the compiler.
448 These will be the only header search paths used--the contents
449 of the INCLUDE_DIRECTORIES directory property will be ig‐
450 nored.
451 CMAKE_REQUIRED_LINK_OPTIONS
453 New in version 3.14.
454 A ;-list of options to add to the link command (see
457 try_compile() for further details).
458 CMAKE_REQUIRED_LIBRARIES
460 A ;-list of libraries to add to the link command. These can
461 be the name of system libraries or they can be Imported Tar‐
462 gets (see try_compile() for further details).
463 CMAKE_REQUIRED_QUIET
465 New in version 3.1.
466 If this variable evaluates to a boolean true value, all sta‐
469 tus messages associated with the check will be suppressed.
470 CheckCSourceRuns
472 Check if given C source compiles and links into an executable and can
473 subsequently be run.
474 check_c_source_runs
476 check_c_source_runs(<code> <resultVar>)
478 Check that the source supplied in <code> can be compiled as a C
480 source file, linked as an executable and then run. The <code>
481 must contain at least a main() function. If the <code> could be
482 built and run successfully, the internal cache variable speci‐
483 fied by <resultVar> will be set to 1, otherwise it will be set
484 to an value that evaluates to boolean false (e.g. an empty
485 string or an error message).
486 The check is only performed once, with the result cached in the
488 variable named by <resultVar>. Every subsequent CMake run will
489 re-use this cached value rather than performing the check again,
490 even if the <code> changes. In order to force the check to be
491 re-evaluated, the variable named by <resultVar> must be manually
492 removed from the cache.
493 The compile and link commands can be influenced by setting any
495 of the following variables prior to calling
496 check_c_source_runs():
497 CMAKE_REQUIRED_FLAGS
499 String of additional flags to pass to the compiler. The
500 string must be space-delimited--a ;-list will not work. The
501 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
502 tion-specific variable are automatically added to the com‐
503 piler command before the contents of CMAKE_REQUIRED_FLAGS.
504 CMAKE_REQUIRED_DEFINITIONS
506 A ;-list of compiler definitions of the form -DFOO or
507 -DFOO=bar. A definition for the name specified by <resultVar>
508 will also be added automatically.
509 CMAKE_REQUIRED_INCLUDES
511 A ;-list of header search paths to pass to the compiler.
512 These will be the only header search paths used--the contents
513 of the INCLUDE_DIRECTORIES directory property will be ig‐
514 nored.
515 CMAKE_REQUIRED_LINK_OPTIONS
517 New in version 3.14.
518 A ;-list of options to add to the link command (see
521 try_compile() for further details).
522 CMAKE_REQUIRED_LIBRARIES
524 A ;-list of libraries to add to the link command. These can
525 be the name of system libraries or they can be Imported Tar‐
526 gets (see try_compile() for further details).
527 CMAKE_REQUIRED_QUIET
529 New in version 3.1.
530 If this variable evaluates to a boolean true value, all sta‐
533 tus messages associated with the check will be suppressed.
534 CheckCXXCompilerFlag
536 Check whether the CXX compiler supports a given flag.
537 check_cxx_compiler_flag
539 check_cxx_compiler_flag(<flag> <var>)
541 Check that the <flag> is accepted by the compiler without a di‐
543 agnostic. Stores the result in an internal cache entry named
544 <var>.
545 A positive result from this check indicates only that the compiler did
547 not issue a diagnostic message when given the flag. Whether the flag
548 has any effect or even a specific one is beyond the scope of this mod‐
549 ule.
550 NOTE:
552 Since the try_compile() command forwards flags from variables like
553 CMAKE_CXX_FLAGS, unknown flags in such variables may cause a false
554 negative for this check.
555 CheckCXXSourceCompiles
557 Check if given C++ source compiles and links into an executable.
558 check_cxx_source_compiles
560 check_cxx_source_compiles(<code> <resultVar>
562 [FAIL_REGEX <regex1> [<regex2>...]])
563 Check that the source supplied in <code> can be compiled as a
565 C++ source file and linked as an executable (so it must contain
566 at least a main() function). The result will be stored in the
567 internal cache variable specified by <resultVar>, with a boolean
568 true value for success and boolean false for failure. If
569 FAIL_REGEX is provided, then failure is determined by checking
570 if anything in the output matches any of the specified regular
571 expressions.
572 The check is only performed once, with the result cached in the
574 variable named by <resultVar>. Every subsequent CMake run will
575 re-use this cached value rather than performing the check again,
576 even if the <code> changes. In order to force the check to be
577 re-evaluated, the variable named by <resultVar> must be manually
578 removed from the cache.
579 The compile and link commands can be influenced by setting any
581 of the following variables prior to calling
582 check_cxx_source_compiles():
583 CMAKE_REQUIRED_FLAGS
585 String of additional flags to pass to the compiler. The
586 string must be space-delimited--a ;-list will not work. The
587 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
588 tion-specific variable are automatically added to the com‐
589 piler command before the contents of CMAKE_REQUIRED_FLAGS.
590 CMAKE_REQUIRED_DEFINITIONS
592 A ;-list of compiler definitions of the form -DFOO or
593 -DFOO=bar. A definition for the name specified by <resultVar>
594 will also be added automatically.
595 CMAKE_REQUIRED_INCLUDES
597 A ;-list of header search paths to pass to the compiler.
598 These will be the only header search paths used--the contents
599 of the INCLUDE_DIRECTORIES directory property will be ig‐
600 nored.
601 CMAKE_REQUIRED_LINK_OPTIONS
603 New in version 3.14.
604 A ;-list of options to add to the link command (see
607 try_compile() for further details).
608 CMAKE_REQUIRED_LIBRARIES
610 A ;-list of libraries to add to the link command. These can
611 be the name of system libraries or they can be Imported Tar‐
612 gets (see try_compile() for further details).
613 CMAKE_REQUIRED_QUIET
615 New in version 3.1.
616 If this variable evaluates to a boolean true value, all sta‐
619 tus messages associated with the check will be suppressed.
620 CheckCXXSourceRuns
622 Check if given C++ source compiles and links into an executable and can
623 subsequently be run.
624 check_cxx_source_runs
626 check_cxx_source_runs(<code> <resultVar>)
628 Check that the source supplied in <code> can be compiled as a
630 C++ source file, linked as an executable and then run. The
631 <code> must contain at least a main() function. If the <code>
632 could be built and run successfully, the internal cache variable
633 specified by <resultVar> will be set to 1, otherwise it will be
634 set to an value that evaluates to boolean false (e.g. an empty
635 string or an error message).
636 The check is only performed once, with the result cached in the
638 variable named by <resultVar>. Every subsequent CMake run will
639 re-use this cached value rather than performing the check again,
640 even if the <code> changes. In order to force the check to be
641 re-evaluated, the variable named by <resultVar> must be manually
642 removed from the cache.
643 The compile and link commands can be influenced by setting any
645 of the following variables prior to calling
646 check_cxx_source_runs():
647 CMAKE_REQUIRED_FLAGS
649 String of additional flags to pass to the compiler. The
650 string must be space-delimited--a ;-list will not work. The
651 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
652 tion-specific variable are automatically added to the com‐
653 piler command before the contents of CMAKE_REQUIRED_FLAGS.
654 CMAKE_REQUIRED_DEFINITIONS
656 A ;-list of compiler definitions of the form -DFOO or
657 -DFOO=bar. A definition for the name specified by <resultVar>
658 will also be added automatically.
659 CMAKE_REQUIRED_INCLUDES
661 A ;-list of header search paths to pass to the compiler.
662 These will be the only header search paths used--the contents
663 of the INCLUDE_DIRECTORIES directory property will be ig‐
664 nored.
665 CMAKE_REQUIRED_LINK_OPTIONS
667 New in version 3.14.
668 A ;-list of options to add to the link command (see
671 try_compile() for further details).
672 CMAKE_REQUIRED_LIBRARIES
674 A ;-list of libraries to add to the link command. These can
675 be the name of system libraries or they can be Imported Tar‐
676 gets (see try_compile() for further details).
677 CMAKE_REQUIRED_QUIET
679 New in version 3.1.
680 If this variable evaluates to a boolean true value, all sta‐
683 tus messages associated with the check will be suppressed.
684 CheckCXXSymbolExists
686 Check if a symbol exists as a function, variable, or macro in C++.
687 check_cxx_symbol_exists
689 check_cxx_symbol_exists(<symbol> <files> <variable>)
691 Check that the <symbol> is available after including given
693 header <files> and store the result in a <variable>. Specify
694 the list of files in one argument as a semicolon-separated list.
695 check_cxx_symbol_exists() can be used to check for symbols as
696 seen by the C++ compiler, as opposed to check_symbol_exists(),
697 which always uses the C compiler.
698 If the header files define the symbol as a macro it is consid‐
700 ered available and assumed to work. If the header files declare
701 the symbol as a function or variable then the symbol must also
702 be available for linking. If the symbol is a type, enum value,
703 or C++ template it will not be recognized: consider using the
704 CheckTypeSize or CheckSourceCompiles module instead.
705 NOTE:
707 This command is unreliable when <symbol> is (potentially) an over‐
708 loaded function. Since there is no reliable way to predict whether a
709 given function in the system environment may be defined as an over‐
710 loaded function or may be an overloaded function on other systems or
711 will become so in the future, it is generally advised to use the
712 CheckCXXSourceCompiles module for checking any function symbol (un‐
713 less somehow you surely know the checked function is not overloaded
714 on other systems or will not be so in the future).
715 The following variables may be set before calling this macro to modify
717 the way the check is run:
718 CMAKE_REQUIRED_FLAGS
720 String of additional flags to pass to the compiler. The
721 string must be space-delimited--a ;-list will not work. The
722 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
723 tion-specific variable are automatically added to the com‐
724 piler command before the contents of CMAKE_REQUIRED_FLAGS.
725 CMAKE_REQUIRED_DEFINITIONS
727 A ;-list of compiler definitions of the form -DFOO or
728 -DFOO=bar. A definition for the name specified by <resultVar>
729 will also be added automatically.
730 CMAKE_REQUIRED_INCLUDES
732 A ;-list of header search paths to pass to the compiler.
733 These will be the only header search paths used--the contents
734 of the INCLUDE_DIRECTORIES directory property will be ig‐
735 nored.
736 CMAKE_REQUIRED_LINK_OPTIONS
738 New in version 3.14.
739 A ;-list of options to add to the link command (see
742 try_compile() for further details).
743 CMAKE_REQUIRED_LIBRARIES
745 A ;-list of libraries to add to the link command. These can
746 be the name of system libraries or they can be Imported Tar‐
747 gets (see try_compile() for further details).
748 CMAKE_REQUIRED_QUIET
750 New in version 3.1.
751 If this variable evaluates to a boolean true value, all sta‐
754 tus messages associated with the check will be suppressed.
755 For example:
757 include(CheckCXXSymbolExists)
759 # Check for macro SEEK_SET
761 check_cxx_symbol_exists(SEEK_SET "cstdio" HAVE_SEEK_SET)
762 # Check for function std::fopen
763 check_cxx_symbol_exists(std::fopen "cstdio" HAVE_STD_FOPEN)
764 CheckFortranCompilerFlag
766 New in version 3.3.
767 Check whether the Fortran compiler supports a given flag.
770 check_fortran_compiler_flag
772 check_fortran_compiler_flag(<flag> <resultVar>)
774 Check that the <flag> is accepted by the compiler without a di‐
776 agnostic. Stores the result in an internal cache entry named
777 <resultVar>.
778 A positive result from this check indicates only that the compiler did
780 not issue a diagnostic message when given the flag. Whether the flag
781 has any effect or even a specific one is beyond the scope of this mod‐
782 ule.
783 The check is only performed once, with the result cached in the vari‐
785 able named by <resultVar>. Every subsequent CMake run will re-use this
786 cached value rather than performing the check again, even if the <code>
787 changes. In order to force the check to be re-evaluated, the variable
788 named by <resultVar> must be manually removed from the cache.
789 The compile and link commands can be influenced by setting any of the
791 following variables prior to calling check_fortran_compiler_flag()
792 CMAKE_REQUIRED_FLAGS
794 String of additional flags to pass to the compiler. The
795 string must be space-delimited--a ;-list will not work. The
796 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
797 tion-specific variable are automatically added to the com‐
798 piler command before the contents of CMAKE_REQUIRED_FLAGS.
799 CMAKE_REQUIRED_DEFINITIONS
801 A ;-list of compiler definitions of the form -DFOO or
802 -DFOO=bar. A definition for the name specified by <resultVar>
803 will also be added automatically.
804 CMAKE_REQUIRED_INCLUDES
806 A ;-list of header search paths to pass to the compiler.
807 These will be the only header search paths used--the contents
808 of the INCLUDE_DIRECTORIES directory property will be ig‐
809 nored.
810 CMAKE_REQUIRED_LINK_OPTIONS
812 New in version 3.14.
813 A ;-list of options to add to the link command (see
816 try_compile() for further details).
817 CMAKE_REQUIRED_LIBRARIES
819 A ;-list of libraries to add to the link command. These can
820 be the name of system libraries or they can be Imported Tar‐
821 gets (see try_compile() for further details).
822 CMAKE_REQUIRED_QUIET
824 New in version 3.1.
825 If this variable evaluates to a boolean true value, all sta‐
828 tus messages associated with the check will be suppressed.
829 CheckFortranFunctionExists
831 Check if a Fortran function exists.
832 CHECK_FORTRAN_FUNCTION_EXISTS
834 CHECK_FORTRAN_FUNCTION_EXISTS(<function> <result>)
836 where
838 <function>
840 the name of the Fortran function
841 <result>
843 variable to store the result; will be created as an in‐
844 ternal cache variable.
845 NOTE:
847 This command does not detect functions in Fortran modules. In gen‐
848 eral it is recommended to use CheckSourceCompiles instead to deter‐
849 mine if a Fortran function or subroutine is available.
850 The following variables may be set before calling this macro to modify
852 the way the check is run:
853 CMAKE_REQUIRED_LINK_OPTIONS
855 New in version 3.14: A ;-list of options to add to the link com‐
856 mand (see try_compile() for further details).
857 CMAKE_REQUIRED_LIBRARIES
860 A ;-list of libraries to add to the link command. These can be
861 the name of system libraries or they can be Imported Targets
862 (see try_compile() for further details).
863 CheckFortranSourceCompiles
865 New in version 3.1.
866 Check if given Fortran source compiles and links into an executable.
869 check_fortran_source_compiles
871 check_fortran_source_compiles(<code> <resultVar>
873 [FAIL_REGEX <regex>...]
874 [SRC_EXT <extension>]
875 )
876 Checks that the source supplied in <code> can be compiled as a
878 Fortran source file and linked as an executable. The <code> must
879 be a Fortran program.
880 check_fortran_source_compiles("program test
882 error stop
883 end program"
884 HAVE_ERROR_STOP
885 SRC_EXT .F90)
886 This command can help avoid costly build processes when a com‐
888 piler lacks support for a necessary feature, or a particular
889 vendor library is not compatible with the Fortran compiler ver‐
890 sion being used. This generate-time check may advise the user of
891 such before the main build process. See also the
892 check_fortran_source_runs() command to run the compiled code.
893 The result will be stored in the internal cache variable <re‐
895 sultVar>, with a boolean true value for success and boolean
896 false for failure.
897 If FAIL_REGEX is provided, then failure is determined by check‐
899 ing if anything in the output matches any of the specified regu‐
900 lar expressions.
901 By default, the test source file will be given a .F file exten‐
903 sion. The SRC_EXT option can be used to override this with .<ex‐
904 tension> instead-- .F90 is a typical choice.
905 The check is only performed once, with the result cached in the
907 variable named by <resultVar>. Every subsequent CMake run will
908 re-use this cached value rather than performing the check again,
909 even if the <code> changes. In order to force the check to be
910 re-evaluated, the variable named by <resultVar> must be manually
911 removed from the cache.
912 The compile and link commands can be influenced by setting any
914 of the following variables prior to calling check_for‐
915 tran_source_compiles():
916 CMAKE_REQUIRED_FLAGS
918 String of additional flags to pass to the compiler. The
919 string must be space-delimited--a ;-list will not work. The
920 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
921 tion-specific variable are automatically added to the com‐
922 piler command before the contents of CMAKE_REQUIRED_FLAGS.
923 CMAKE_REQUIRED_DEFINITIONS
925 A ;-list of compiler definitions of the form -DFOO or
926 -DFOO=bar. A definition for the name specified by <resultVar>
927 will also be added automatically.
928 CMAKE_REQUIRED_INCLUDES
930 A ;-list of header search paths to pass to the compiler.
931 These will be the only header search paths used--the contents
932 of the INCLUDE_DIRECTORIES directory property will be ig‐
933 nored.
934 CMAKE_REQUIRED_LINK_OPTIONS
936 New in version 3.14.
937 A ;-list of options to add to the link command (see
940 try_compile() for further details).
941 CMAKE_REQUIRED_LIBRARIES
943 A ;-list of libraries to add to the link command. These can
944 be the name of system libraries or they can be Imported Tar‐
945 gets (see try_compile() for further details).
946 CMAKE_REQUIRED_QUIET
948 New in version 3.1.
949 If this variable evaluates to a boolean true value, all sta‐
952 tus messages associated with the check will be suppressed.
953 CheckFortranSourceRuns
955 New in version 3.14.
956 Check if given Fortran source compiles and links into an executable and
959 can subsequently be run.
960 check_fortran_source_runs
962 check_fortran_source_runs(<code> <resultVar>
964 [SRC_EXT <extension>])
965 Check that the source supplied in <code> can be compiled as a
967 Fortran source file, linked as an executable and then run. The
968 <code> must be a Fortran program.
969 check_fortran_source_runs("program test
971 real :: x[*]
972 call co_sum(x)
973 end program"
974 HAVE_COARRAY)
975 This command can help avoid costly build processes when a com‐
977 piler lacks support for a necessary feature, or a particular
978 vendor library is not compatible with the Fortran compiler ver‐
979 sion being used. Some of these failures only occur at runtime
980 instead of linktime, and a trivial runtime example can catch the
981 issue before the main build process.
982 If the <code> could be built and run successfully, the internal
984 cache variable specified by <resultVar> will be set to 1, other‐
985 wise it will be set to an value that evaluates to boolean false
986 (e.g. an empty string or an error message).
987 By default, the test source file will be given a .F90 file ex‐
989 tension. The SRC_EXT option can be used to override this with
990 .<extension> instead.
991 The check is only performed once, with the result cached in the
993 variable named by <resultVar>. Every subsequent CMake run will
994 re-use this cached value rather than performing the check again,
995 even if the <code> changes. In order to force the check to be
996 re-evaluated, the variable named by <resultVar> must be manually
997 removed from the cache.
998 The compile and link commands can be influenced by setting any
1000 of the following variables prior to calling check_for‐
1001 tran_source_runs():
1002 CMAKE_REQUIRED_FLAGS
1004 String of additional flags to pass to the compiler. The
1005 string must be space-delimited--a ;-list will not work. The
1006 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
1007 tion-specific variable are automatically added to the com‐
1008 piler command before the contents of CMAKE_REQUIRED_FLAGS.
1009 CMAKE_REQUIRED_DEFINITIONS
1011 A ;-list of compiler definitions of the form -DFOO or
1012 -DFOO=bar. A definition for the name specified by <resultVar>
1013 will also be added automatically.
1014 CMAKE_REQUIRED_INCLUDES
1016 A ;-list of header search paths to pass to the compiler.
1017 These will be the only header search paths used--the contents
1018 of the INCLUDE_DIRECTORIES directory property will be ig‐
1019 nored.
1020 CMAKE_REQUIRED_LINK_OPTIONS
1022 New in version 3.14.
1023 A ;-list of options to add to the link command (see
1026 try_compile() for further details).
1027 CMAKE_REQUIRED_LIBRARIES
1029 A ;-list of libraries to add to the link command. These can
1030 be the name of system libraries or they can be Imported Tar‐
1031 gets (see try_compile() for further details).
1032 CMAKE_REQUIRED_QUIET
1034 New in version 3.1.
1035 If this variable evaluates to a boolean true value, all sta‐
1038 tus messages associated with the check will be suppressed.
1039 CheckFunctionExists
1041 Check if a C function can be linked
1042 check_function_exists
1044 check_function_exists(<function> <variable>)
1046 Checks that the <function> is provided by libraries on the sys‐
1048 tem and store the result in a <variable>, which will be created
1049 as an internal cache variable.
1050 The following variables may be set before calling this macro to modify
1052 the way the check is run:
1053 CMAKE_REQUIRED_FLAGS
1055 String of additional flags to pass to the compiler. The
1056 string must be space-delimited--a ;-list will not work. The
1057 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
1058 tion-specific variable are automatically added to the com‐
1059 piler command before the contents of CMAKE_REQUIRED_FLAGS.
1060 CMAKE_REQUIRED_DEFINITIONS
1062 A ;-list of compiler definitions of the form -DFOO or
1063 -DFOO=bar. A definition for the name specified by <resultVar>
1064 will also be added automatically.
1065 CMAKE_REQUIRED_INCLUDES
1067 A ;-list of header search paths to pass to the compiler.
1068 These will be the only header search paths used--the contents
1069 of the INCLUDE_DIRECTORIES directory property will be ig‐
1070 nored.
1071 CMAKE_REQUIRED_LINK_OPTIONS
1073 New in version 3.14.
1074 A ;-list of options to add to the link command (see
1077 try_compile() for further details).
1078 CMAKE_REQUIRED_LIBRARIES
1080 A ;-list of libraries to add to the link command. These can
1081 be the name of system libraries or they can be Imported Tar‐
1082 gets (see try_compile() for further details).
1083 CMAKE_REQUIRED_QUIET
1085 New in version 3.1.
1086 If this variable evaluates to a boolean true value, all sta‐
1089 tus messages associated with the check will be suppressed.
1090 NOTE:
1092 Prefer using CheckSymbolExists instead of this module, for the fol‐
1093 lowing reasons:
1094 • check_function_exists() can't detect functions that are inlined in
1096 headers or specified as a macro.
1097 • check_function_exists() can't detect anything in the 32-bit ver‐
1099 sions of the Win32 API, because of a mismatch in calling conven‐
1100 tions.
1101 • check_function_exists() only verifies linking, it does not verify
1103 that the function is declared in system headers.
1104 CheckIncludeFileCXX
1106 Provides a macro to check if a header file can be included in CXX.
1107 CHECK_INCLUDE_FILE_CXX
1109 CHECK_INCLUDE_FILE_CXX(<include> <variable> [<flags>])
1111 Check if the given <include> file may be included in a CXX
1113 source file and store the result in an internal cache entry
1114 named <variable>. The optional third argument may be used to
1115 add compilation flags to the check (or use CMAKE_REQUIRED_FLAGS
1116 below).
1117 The following variables may be set before calling this macro to modify
1119 the way the check is run:
1120 CMAKE_REQUIRED_FLAGS
1122 String of additional flags to pass to the compiler. The
1123 string must be space-delimited--a ;-list will not work. The
1124 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
1125 tion-specific variable are automatically added to the com‐
1126 piler command before the contents of CMAKE_REQUIRED_FLAGS.
1127 CMAKE_REQUIRED_DEFINITIONS
1129 A ;-list of compiler definitions of the form -DFOO or
1130 -DFOO=bar. A definition for the name specified by <resultVar>
1131 will also be added automatically.
1132 CMAKE_REQUIRED_INCLUDES
1134 A ;-list of header search paths to pass to the compiler.
1135 These will be the only header search paths used--the contents
1136 of the INCLUDE_DIRECTORIES directory property will be ig‐
1137 nored.
1138 CMAKE_REQUIRED_LINK_OPTIONS
1140 New in version 3.14.
1141 A ;-list of options to add to the link command (see
1144 try_compile() for further details).
1145 CMAKE_REQUIRED_LIBRARIES
1147 A ;-list of libraries to add to the link command. These can
1148 be the name of system libraries or they can be Imported Tar‐
1149 gets (see try_compile() for further details).
1150 CMAKE_REQUIRED_QUIET
1152 New in version 3.1.
1153 If this variable evaluates to a boolean true value, all sta‐
1156 tus messages associated with the check will be suppressed.
1157 See modules CheckIncludeFile and CheckIncludeFiles to check for one or
1159 more C headers.
1160 CheckIncludeFile
1162 Provides a macro to check if a header file can be included in C.
1163 CHECK_INCLUDE_FILE
1165 CHECK_INCLUDE_FILE(<include> <variable> [<flags>])
1167 Check if the given <include> file may be included in a C source
1169 file and store the result in an internal cache entry named
1170 <variable>. The optional third argument may be used to add com‐
1171 pilation flags to the check (or use CMAKE_REQUIRED_FLAGS below).
1172 The following variables may be set before calling this macro to modify
1174 the way the check is run:
1175 CMAKE_REQUIRED_FLAGS
1177 String of additional flags to pass to the compiler. The
1178 string must be space-delimited--a ;-list will not work. The
1179 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
1180 tion-specific variable are automatically added to the com‐
1181 piler command before the contents of CMAKE_REQUIRED_FLAGS.
1182 CMAKE_REQUIRED_DEFINITIONS
1184 A ;-list of compiler definitions of the form -DFOO or
1185 -DFOO=bar. A definition for the name specified by <resultVar>
1186 will also be added automatically.
1187 CMAKE_REQUIRED_INCLUDES
1189 A ;-list of header search paths to pass to the compiler.
1190 These will be the only header search paths used--the contents
1191 of the INCLUDE_DIRECTORIES directory property will be ig‐
1192 nored.
1193 CMAKE_REQUIRED_LINK_OPTIONS
1195 New in version 3.14.
1196 A ;-list of options to add to the link command (see
1199 try_compile() for further details).
1200 CMAKE_REQUIRED_LIBRARIES
1202 A ;-list of libraries to add to the link command. These can
1203 be the name of system libraries or they can be Imported Tar‐
1204 gets (see try_compile() for further details).
1205 CMAKE_REQUIRED_QUIET
1207 New in version 3.1.
1208 If this variable evaluates to a boolean true value, all sta‐
1211 tus messages associated with the check will be suppressed.
1212 See the CheckIncludeFiles module to check for multiple headers at once.
1214 See the CheckIncludeFileCXX module to check for headers using the CXX
1215 language.
1216 CheckIncludeFiles
1218 Provides a macro to check if a list of one or more header files can be
1219 included together.
1220 CHECK_INCLUDE_FILES
1222 CHECK_INCLUDE_FILES("<includes>" <variable> [LANGUAGE <language>])
1224 Check if the given <includes> list may be included together in a
1226 source file and store the result in an internal cache entry
1227 named <variable>. Specify the <includes> argument as a ;-list
1228 of header file names.
1229 If LANGUAGE is set, the specified compiler will be used to per‐
1231 form the check. Acceptable values are C and CXX. If not set, the
1232 C compiler will be used if enabled. If the C compiler is not en‐
1233 abled, the C++ compiler will be used if enabled.
1234 The following variables may be set before calling this macro to modify
1236 the way the check is run:
1237 CMAKE_REQUIRED_FLAGS
1239 String of additional flags to pass to the compiler. The
1240 string must be space-delimited--a ;-list will not work. The
1241 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
1242 tion-specific variable are automatically added to the com‐
1243 piler command before the contents of CMAKE_REQUIRED_FLAGS.
1244 CMAKE_REQUIRED_DEFINITIONS
1246 A ;-list of compiler definitions of the form -DFOO or
1247 -DFOO=bar. A definition for the name specified by <resultVar>
1248 will also be added automatically.
1249 CMAKE_REQUIRED_INCLUDES
1251 A ;-list of header search paths to pass to the compiler.
1252 These will be the only header search paths used--the contents
1253 of the INCLUDE_DIRECTORIES directory property will be ig‐
1254 nored.
1255 CMAKE_REQUIRED_LINK_OPTIONS
1257 New in version 3.14.
1258 A ;-list of options to add to the link command (see
1261 try_compile() for further details).
1262 CMAKE_REQUIRED_LIBRARIES
1264 A ;-list of libraries to add to the link command. These can
1265 be the name of system libraries or they can be Imported Tar‐
1266 gets (see try_compile() for further details).
1267 CMAKE_REQUIRED_QUIET
1269 New in version 3.1.
1270 If this variable evaluates to a boolean true value, all sta‐
1273 tus messages associated with the check will be suppressed.
1274 See modules CheckIncludeFile and CheckIncludeFileCXX to check for a
1276 single header file in C or CXX languages.
1277 CheckIPOSupported
1279 New in version 3.9.
1280 Check whether the compiler supports an interprocedural optimization
1283 (IPO/LTO). Use this before enabling the INTERPROCEDURAL_OPTIMIZATION
1284 target property.
1285 check_ipo_supported
1287 check_ipo_supported([RESULT <result>] [OUTPUT <output>]
1289 [LANGUAGES <lang>...])
1290 Options are:
1292 RESULT <result>
1294 Set <result> variable to YES if IPO is supported by the
1295 compiler and NO otherwise. If this option is not given
1296 then the command will issue a fatal error if IPO is not
1297 supported.
1298 OUTPUT <output>
1300 Set <output> variable with details about any error.
1301 LANGUAGES <lang>...
1303 Specify languages whose compilers to check. Languages C,
1304 CXX, and Fortran are supported.
1305 It makes no sense to use this module when CMP0069 is set to OLD so mod‐
1307 ule will return error in this case. See policy CMP0069 for details.
1308 New in version 3.13: Add support for Visual Studio generators.
1310 New in version 3.24: The check uses the caller's CMAKE_<LANG>_FLAGS and
1313 CMAKE_<LANG>_FLAGS_<CONFIG> values. See policy CMP0138.
1314 Examples
1317 check_ipo_supported() # fatal error if IPO is not supported
1318 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
1319 # Optional IPO. Do not use IPO if it's not supported by compiler.
1321 check_ipo_supported(RESULT result OUTPUT output)
1322 if(result)
1323 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
1324 else()
1325 message(WARNING "IPO is not supported: ${output}")
1326 endif()
1327 CheckLanguage
1329 Check if a language can be enabled
1330 Usage:
1332 check_language(<lang>)
1334 where <lang> is a language that may be passed to enable_language() such
1336 as Fortran. If CMAKE_<LANG>_COMPILER is already defined the check does
1337 nothing. Otherwise it tries enabling the language in a test project.
1338 The result is cached in CMAKE_<LANG>_COMPILER as the compiler that was
1339 found, or NOTFOUND if the language cannot be enabled. For CUDA which
1340 can have an explicit host compiler, the cache CMAKE_CUDA_HOST_COMPILER
1341 variable will be set if it was required for compilation (and cleared if
1342 it was not).
1343 Example:
1345 check_language(Fortran)
1347 if(CMAKE_Fortran_COMPILER)
1348 enable_language(Fortran)
1349 else()
1350 message(STATUS "No Fortran support")
1351 endif()
1352 CheckLibraryExists
1354 Check if the function exists.
1355 CHECK_LIBRARY_EXISTS
1357 CHECK_LIBRARY_EXISTS(LIBRARY FUNCTION LOCATION VARIABLE)
1359 LIBRARY - the name of the library you are looking for
1361 FUNCTION - the name of the function
1362 LOCATION - location where the library should be found
1363 VARIABLE - variable to store the result
1364 Will be created as an internal cache variable.
1365 The following variables may be set before calling this macro to modify
1367 the way the check is run:
1368 CMAKE_REQUIRED_FLAGS
1370 String of additional flags to pass to the compiler. The
1371 string must be space-delimited--a ;-list will not work. The
1372 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
1373 tion-specific variable are automatically added to the com‐
1374 piler command before the contents of CMAKE_REQUIRED_FLAGS.
1375 CMAKE_REQUIRED_DEFINITIONS
1377 A ;-list of compiler definitions of the form -DFOO or
1378 -DFOO=bar. A definition for the name specified by <resultVar>
1379 will also be added automatically.
1380 CMAKE_REQUIRED_LINK_OPTIONS
1382 New in version 3.14.
1383 A ;-list of options to add to the link command (see
1386 try_compile() for further details).
1387 CMAKE_REQUIRED_LIBRARIES
1389 A ;-list of libraries to add to the link command. These can
1390 be the name of system libraries or they can be Imported Tar‐
1391 gets (see try_compile() for further details).
1392 CMAKE_REQUIRED_QUIET
1394 New in version 3.1.
1395 If this variable evaluates to a boolean true value, all sta‐
1398 tus messages associated with the check will be suppressed.
1399 CheckLinkerFlag
1401 New in version 3.18.
1402 Check whether the compiler supports a given link flag.
1405 check_linker_flag
1407 check_linker_flag(<lang> <flag> <var>)
1409 Check that the link <flag> is accepted by the <lang> compiler without a
1411 diagnostic. Stores the result in an internal cache entry named <var>.
1412 This command temporarily sets the CMAKE_REQUIRED_LINK_OPTIONS variable
1414 and calls the check_source_compiles() command from the
1415 CheckSourceCompiles module. See that module's documentation for a
1416 listing of variables that can otherwise modify the build.
1417 The underlying implementation relies on the LINK_OPTIONS property to
1419 check the specified flag. The LINKER: prefix, as described in the
1420 target_link_options() command, can be used as well.
1421 A positive result from this check indicates only that the compiler did
1423 not issue a diagnostic message when given the link flag. Whether the
1424 flag has any effect or even a specific one is beyond the scope of this
1425 module.
1426 NOTE:
1428 Since the try_compile() command forwards flags from variables like
1429 CMAKE_<LANG>_FLAGS, unknown flags in such variables may cause a
1430 false negative for this check.
1431 CheckOBJCCompilerFlag
1433 New in version 3.16.
1434 Check whether the Objective-C compiler supports a given flag.
1437 check_objc_compiler_flag
1439 check_objc_compiler_flag(<flag> <resultVar>)
1441 Check that the <flag> is accepted by the compiler without a di‐
1443 agnostic. Stores the result in an internal cache entry named
1444 <resultVar>.
1445 A positive result from this check indicates only that the compiler did
1447 not issue a diagnostic message when given the flag. Whether the flag
1448 has any effect or even a specific one is beyond the scope of this mod‐
1449 ule.
1450 The check is only performed once, with the result cached in the vari‐
1452 able named by <resultVar>. Every subsequent CMake run will re-use this
1453 cached value rather than performing the check again, even if the <code>
1454 changes. In order to force the check to be re-evaluated, the variable
1455 named by <resultVar> must be manually removed from the cache.
1456 The compile and link commands can be influenced by setting any of the
1458 following variables prior to calling check_objc_compiler_flag()
1459 CMAKE_REQUIRED_FLAGS
1461 String of additional flags to pass to the compiler. The
1462 string must be space-delimited--a ;-list will not work. The
1463 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
1464 tion-specific variable are automatically added to the com‐
1465 piler command before the contents of CMAKE_REQUIRED_FLAGS.
1466 CMAKE_REQUIRED_DEFINITIONS
1468 A ;-list of compiler definitions of the form -DFOO or
1469 -DFOO=bar. A definition for the name specified by <resultVar>
1470 will also be added automatically.
1471 CMAKE_REQUIRED_INCLUDES
1473 A ;-list of header search paths to pass to the compiler.
1474 These will be the only header search paths used--the contents
1475 of the INCLUDE_DIRECTORIES directory property will be ig‐
1476 nored.
1477 CMAKE_REQUIRED_LINK_OPTIONS
1479 New in version 3.14.
1480 A ;-list of options to add to the link command (see
1483 try_compile() for further details).
1484 CMAKE_REQUIRED_LIBRARIES
1486 A ;-list of libraries to add to the link command. These can
1487 be the name of system libraries or they can be Imported Tar‐
1488 gets (see try_compile() for further details).
1489 CMAKE_REQUIRED_QUIET
1491 New in version 3.1.
1492 If this variable evaluates to a boolean true value, all sta‐
1495 tus messages associated with the check will be suppressed.
1496 CheckOBJCSourceCompiles
1498 New in version 3.16.
1499 Check if given Objective-C source compiles and links into an exe‐
1502 cutable.
1503 check_objc_source_compiles
1505 check_objc_source_compiles(<code> <resultVar>
1507 [FAIL_REGEX <regex1> [<regex2>...]])
1508 Check that the source supplied in <code> can be compiled as a
1510 Objectie-C source file and linked as an executable (so it must
1511 contain at least a main() function). The result will be stored
1512 in the internal cache variable specified by <resultVar>, with a
1513 boolean true value for success and boolean false for failure. If
1514 FAIL_REGEX is provided, then failure is determined by checking
1515 if anything in the output matches any of the specified regular
1516 expressions.
1517 The check is only performed once, with the result cached in the
1519 variable named by <resultVar>. Every subsequent CMake run will
1520 re-use this cached value rather than performing the check again,
1521 even if the <code> changes. In order to force the check to be
1522 re-evaluated, the variable named by <resultVar> must be manually
1523 removed from the cache.
1524 The compile and link commands can be influenced by setting any
1526 of the following variables prior to calling
1527 check_objc_source_compiles()
1528 CMAKE_REQUIRED_FLAGS
1530 String of additional flags to pass to the compiler. The
1531 string must be space-delimited--a ;-list will not work. The
1532 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
1533 tion-specific variable are automatically added to the com‐
1534 piler command before the contents of CMAKE_REQUIRED_FLAGS.
1535 CMAKE_REQUIRED_DEFINITIONS
1537 A ;-list of compiler definitions of the form -DFOO or
1538 -DFOO=bar. A definition for the name specified by <resultVar>
1539 will also be added automatically.
1540 CMAKE_REQUIRED_INCLUDES
1542 A ;-list of header search paths to pass to the compiler.
1543 These will be the only header search paths used--the contents
1544 of the INCLUDE_DIRECTORIES directory property will be ig‐
1545 nored.
1546 CMAKE_REQUIRED_LINK_OPTIONS
1548 New in version 3.14.
1549 A ;-list of options to add to the link command (see
1552 try_compile() for further details).
1553 CMAKE_REQUIRED_LIBRARIES
1555 A ;-list of libraries to add to the link command. These can
1556 be the name of system libraries or they can be Imported Tar‐
1557 gets (see try_compile() for further details).
1558 CMAKE_REQUIRED_QUIET
1560 New in version 3.1.
1561 If this variable evaluates to a boolean true value, all sta‐
1564 tus messages associated with the check will be suppressed.
1565 CheckOBJCSourceRuns
1567 New in version 3.16.
1568 Check if given Objective-C source compiles and links into an executable
1571 and can subsequently be run.
1572 check_objc_source_runs
1574 check_objc_source_runs(<code> <resultVar>)
1576 Check that the source supplied in <code> can be compiled as a
1578 Objective-C source file, linked as an executable and then run.
1579 The <code> must contain at least a main() function. If the
1580 <code> could be built and run successfully, the internal cache
1581 variable specified by <resultVar> will be set to 1, otherwise it
1582 will be set to an value that evaluates to boolean false (e.g. an
1583 empty string or an error message).
1584 The check is only performed once, with the result cached in the
1586 variable named by <resultVar>. Every subsequent CMake run will
1587 re-use this cached value rather than performing the check again,
1588 even if the <code> changes. In order to force the check to be
1589 re-evaluated, the variable named by <resultVar> must be manually
1590 removed from the cache.
1591 The compile and link commands can be influenced by setting any
1593 of the following variables prior to calling
1594 check_objc_source_runs()
1595 CMAKE_REQUIRED_FLAGS
1597 String of additional flags to pass to the compiler. The
1598 string must be space-delimited--a ;-list will not work. The
1599 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
1600 tion-specific variable are automatically added to the com‐
1601 piler command before the contents of CMAKE_REQUIRED_FLAGS.
1602 CMAKE_REQUIRED_DEFINITIONS
1604 A ;-list of compiler definitions of the form -DFOO or
1605 -DFOO=bar. A definition for the name specified by <resultVar>
1606 will also be added automatically.
1607 CMAKE_REQUIRED_INCLUDES
1609 A ;-list of header search paths to pass to the compiler.
1610 These will be the only header search paths used--the contents
1611 of the INCLUDE_DIRECTORIES directory property will be ig‐
1612 nored.
1613 CMAKE_REQUIRED_LINK_OPTIONS
1615 New in version 3.14.
1616 A ;-list of options to add to the link command (see
1619 try_compile() for further details).
1620 CMAKE_REQUIRED_LIBRARIES
1622 A ;-list of libraries to add to the link command. These can
1623 be the name of system libraries or they can be Imported Tar‐
1624 gets (see try_compile() for further details).
1625 CMAKE_REQUIRED_QUIET
1627 New in version 3.1.
1628 If this variable evaluates to a boolean true value, all sta‐
1631 tus messages associated with the check will be suppressed.
1632 CheckOBJCXXCompilerFlag
1634 New in version 3.16.
1635 Check whether the Objective-C++ compiler supports a given flag.
1638 check_objcxx_compiler_flag
1640 check_objcxx_compiler_flag(<flag> <resultVar>)
1642 Check that the <flag> is accepted by the compiler without a di‐
1644 agnostic. Stores the result in an internal cache entry named
1645 <resultVar>.
1646 A positive result from this check indicates only that the compiler did
1648 not issue a diagnostic message when given the flag. Whether the flag
1649 has any effect or even a specific one is beyond the scope of this mod‐
1650 ule.
1651 The check is only performed once, with the result cached in the vari‐
1653 able named by <resultVar>. Every subsequent CMake run will re-use this
1654 cached value rather than performing the check again, even if the <code>
1655 changes. In order to force the check to be re-evaluated, the variable
1656 named by <resultVar> must be manually removed from the cache.
1657 The compile and link commands can be influenced by setting any of the
1659 following variables prior to calling check_objcxx_compiler_flag()
1660 CMAKE_REQUIRED_FLAGS
1662 String of additional flags to pass to the compiler. The
1663 string must be space-delimited--a ;-list will not work. The
1664 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
1665 tion-specific variable are automatically added to the com‐
1666 piler command before the contents of CMAKE_REQUIRED_FLAGS.
1667 CMAKE_REQUIRED_DEFINITIONS
1669 A ;-list of compiler definitions of the form -DFOO or
1670 -DFOO=bar. A definition for the name specified by <resultVar>
1671 will also be added automatically.
1672 CMAKE_REQUIRED_INCLUDES
1674 A ;-list of header search paths to pass to the compiler.
1675 These will be the only header search paths used--the contents
1676 of the INCLUDE_DIRECTORIES directory property will be ig‐
1677 nored.
1678 CMAKE_REQUIRED_LINK_OPTIONS
1680 New in version 3.14.
1681 A ;-list of options to add to the link command (see
1684 try_compile() for further details).
1685 CMAKE_REQUIRED_LIBRARIES
1687 A ;-list of libraries to add to the link command. These can
1688 be the name of system libraries or they can be Imported Tar‐
1689 gets (see try_compile() for further details).
1690 CMAKE_REQUIRED_QUIET
1692 New in version 3.1.
1693 If this variable evaluates to a boolean true value, all sta‐
1696 tus messages associated with the check will be suppressed.
1697 CheckOBJCXXSourceCompiles
1699 New in version 3.16.
1700 Check if given Objective-C++ source compiles and links into an exe‐
1703 cutable.
1704 check_objcxx_source_compiles
1706 check_objcxx_source_compiles(<code> <resultVar>
1708 [FAIL_REGEX <regex1> [<regex2>...]])
1709 Check that the source supplied in <code> can be compiled as a
1711 Objective-C++ source file and linked as an executable (so it
1712 must contain at least a main() function). The result will be
1713 stored in the internal cache variable specified by <resultVar>,
1714 with a boolean true value for success and boolean false for
1715 failure. If FAIL_REGEX is provided, then failure is determined
1716 by checking if anything in the output matches any of the speci‐
1717 fied regular expressions.
1718 The check is only performed once, with the result cached in the
1720 variable named by <resultVar>. Every subsequent CMake run will
1721 re-use this cached value rather than performing the check again,
1722 even if the <code> changes. In order to force the check to be
1723 re-evaluated, the variable named by <resultVar> must be manually
1724 removed from the cache.
1725 The compile and link commands can be influenced by setting any
1727 of the following variables prior to calling check_ob‐
1728 jcxx_source_compiles()
1729 CMAKE_REQUIRED_FLAGS
1731 String of additional flags to pass to the compiler. The
1732 string must be space-delimited--a ;-list will not work. The
1733 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
1734 tion-specific variable are automatically added to the com‐
1735 piler command before the contents of CMAKE_REQUIRED_FLAGS.
1736 CMAKE_REQUIRED_DEFINITIONS
1738 A ;-list of compiler definitions of the form -DFOO or
1739 -DFOO=bar. A definition for the name specified by <resultVar>
1740 will also be added automatically.
1741 CMAKE_REQUIRED_INCLUDES
1743 A ;-list of header search paths to pass to the compiler.
1744 These will be the only header search paths used--the contents
1745 of the INCLUDE_DIRECTORIES directory property will be ig‐
1746 nored.
1747 CMAKE_REQUIRED_LINK_OPTIONS
1749 New in version 3.14.
1750 A ;-list of options to add to the link command (see
1753 try_compile() for further details).
1754 CMAKE_REQUIRED_LIBRARIES
1756 A ;-list of libraries to add to the link command. These can
1757 be the name of system libraries or they can be Imported Tar‐
1758 gets (see try_compile() for further details).
1759 CMAKE_REQUIRED_QUIET
1761 New in version 3.1.
1762 If this variable evaluates to a boolean true value, all sta‐
1765 tus messages associated with the check will be suppressed.
1766 CheckOBJCXXSourceRuns
1768 New in version 3.16.
1769 Check if given Objective-C++ source compiles and links into an exe‐
1772 cutable and can subsequently be run.
1773 check_objcxx_source_runs
1775 check_objcxx_source_runs(<code> <resultVar>)
1777 Check that the source supplied in <code> can be compiled as a
1779 Objective-C++ source file, linked as an executable and then run.
1780 The <code> must contain at least a main() function. If the
1781 <code> could be built and run successfully, the internal cache
1782 variable specified by <resultVar> will be set to 1, otherwise it
1783 will be set to an value that evaluates to boolean false (e.g. an
1784 empty string or an error message).
1785 The check is only performed once, with the result cached in the
1787 variable named by <resultVar>. Every subsequent CMake run will
1788 re-use this cached value rather than performing the check again,
1789 even if the <code> changes. In order to force the check to be
1790 re-evaluated, the variable named by <resultVar> must be manually
1791 removed from the cache.
1792 The compile and link commands can be influenced by setting any
1794 of the following variables prior to calling check_ob‐
1795 jcxx_source_runs()
1796 CMAKE_REQUIRED_FLAGS
1798 String of additional flags to pass to the compiler. The
1799 string must be space-delimited--a ;-list will not work. The
1800 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
1801 tion-specific variable are automatically added to the com‐
1802 piler command before the contents of CMAKE_REQUIRED_FLAGS.
1803 CMAKE_REQUIRED_DEFINITIONS
1805 A ;-list of compiler definitions of the form -DFOO or
1806 -DFOO=bar. A definition for the name specified by <resultVar>
1807 will also be added automatically.
1808 CMAKE_REQUIRED_INCLUDES
1810 A ;-list of header search paths to pass to the compiler.
1811 These will be the only header search paths used--the contents
1812 of the INCLUDE_DIRECTORIES directory property will be ig‐
1813 nored.
1814 CMAKE_REQUIRED_LINK_OPTIONS
1816 New in version 3.14.
1817 A ;-list of options to add to the link command (see
1820 try_compile() for further details).
1821 CMAKE_REQUIRED_LIBRARIES
1823 A ;-list of libraries to add to the link command. These can
1824 be the name of system libraries or they can be Imported Tar‐
1825 gets (see try_compile() for further details).
1826 CMAKE_REQUIRED_QUIET
1828 New in version 3.1.
1829 If this variable evaluates to a boolean true value, all sta‐
1832 tus messages associated with the check will be suppressed.
1833 CheckPIESupported
1835 New in version 3.14.
1836 Check whether the linker supports Position Independent Code (PIE) or No
1839 Position Independent Code (NO_PIE) for executables. Use this to ensure
1840 that the POSITION_INDEPENDENT_CODE target property for executables will
1841 be honored at link time.
1842 check_pie_supported
1844 check_pie_supported([OUTPUT_VARIABLE <output>]
1846 [LANGUAGES <lang>...])
1847 Options are:
1849 OUTPUT_VARIABLE <output>
1851 Set <output> variable with details about any error. If
1852 the check is bypassed because it uses cached results from
1853 a previous call, the output will be empty even if errors
1854 were present in the previous call.
1855 LANGUAGES <lang>...
1857 Check the linkers used for each of the specified lan‐
1858 guages. If this option is not provided, the command
1859 checks all enabled languages.
1860 C, CXX, Fortran are supported.
1862 New in version 3.23: OBJC, OBJCXX, CUDA, and HIP are sup‐
1864 ported.
1865 It makes no sense to use this module when CMP0083 is set to OLD, so the
1868 command will return an error in this case. See policy CMP0083 for de‐
1869 tails.
1870 Variables
1872 For each language checked, two boolean cache variables are defined.
1873 CMAKE_<lang>_LINK_PIE_SUPPORTED
1875 Set to true if PIE is supported by the linker and false oth‐
1876 erwise.
1877 CMAKE_<lang>_LINK_NO_PIE_SUPPORTED
1879 Set to true if NO_PIE is supported by the linker and false
1880 otherwise.
1881 Examples
1883 check_pie_supported()
1884 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1885 # Retrieve any error message.
1887 check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C)
1888 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1889 if(NOT CMAKE_C_LINK_PIE_SUPPORTED)
1890 message(WARNING "PIE is not supported at link time: ${output}.\n"
1891 "PIE link options will not be passed to linker.")
1892 endif()
1893 CheckPrototypeDefinition
1895 Check if the prototype we expect is correct.
1896 check_prototype_definition
1898 check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER VARIABLE)
1900 FUNCTION - The name of the function (used to check if prototype exists)
1902 PROTOTYPE- The prototype to check.
1903 RETURN - The return value of the function.
1904 HEADER - The header files required.
1905 VARIABLE - The variable to store the result.
1906 Will be created as an internal cache variable.
1907 Example:
1909 check_prototype_definition(getpwent_r
1911 "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)"
1912 "NULL"
1913 "unistd.h;pwd.h"
1914 SOLARIS_GETPWENT_R)
1915 The following variables may be set before calling this function to mod‐
1917 ify the way the check is run:
1918 CMAKE_REQUIRED_FLAGS
1920 String of additional flags to pass to the compiler. The
1921 string must be space-delimited--a ;-list will not work. The
1922 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
1923 tion-specific variable are automatically added to the com‐
1924 piler command before the contents of CMAKE_REQUIRED_FLAGS.
1925 CMAKE_REQUIRED_DEFINITIONS
1927 A ;-list of compiler definitions of the form -DFOO or
1928 -DFOO=bar. A definition for the name specified by <resultVar>
1929 will also be added automatically.
1930 CMAKE_REQUIRED_INCLUDES
1932 A ;-list of header search paths to pass to the compiler.
1933 These will be the only header search paths used--the contents
1934 of the INCLUDE_DIRECTORIES directory property will be ig‐
1935 nored.
1936 CMAKE_REQUIRED_LINK_OPTIONS
1938 New in version 3.14.
1939 A ;-list of options to add to the link command (see
1942 try_compile() for further details).
1943 CMAKE_REQUIRED_LIBRARIES
1945 A ;-list of libraries to add to the link command. These can
1946 be the name of system libraries or they can be Imported Tar‐
1947 gets (see try_compile() for further details).
1948 CMAKE_REQUIRED_QUIET
1950 New in version 3.1.
1951 If this variable evaluates to a boolean true value, all sta‐
1954 tus messages associated with the check will be suppressed.
1955 CheckSourceCompiles
1957 New in version 3.19.
1958 Check if given source compiles and links into an executable.
1961 check_source_compiles
1963 check_source_compiles(<lang> <code> <resultVar>
1965 [FAIL_REGEX <regex1> [<regex2>...]]
1966 [SRC_EXT <extension>])
1967 Check that the source supplied in <code> can be compiled as a
1969 source file for the requested language and linked as an exe‐
1970 cutable. The result will be stored in the internal cache vari‐
1971 able specified by <resultVar>, with a boolean true value for
1972 success and boolean false for failure. If FAIL_REGEX is pro‐
1973 vided, then failure is determined by checking if anything in the
1974 compiler output matches any of the specified regular expres‐
1975 sions.
1976 By default, the test source file will be given a file extension
1978 that matches the requested language. The SRC_EXT option can be
1979 used to override this with .<extension> instead.
1980 The <code> must contain a valid main program. For example:
1982 check_source_compiles(C
1984 "#include <stdlib.h>
1985 #include <stdnoreturn.h>
1986 noreturn void f(){ exit(0); }
1987 int main(void) { f(); return 1; }"
1988 HAVE_NORETURN)
1989 check_source_compiles(Fortran
1991 "program test
1992 error stop
1993 end program"
1994 HAVE_ERROR_STOP)
1995 The check is only performed once, with the result cached in the
1997 variable named by <resultVar>. Every subsequent CMake run will
1998 re-use this cached value rather than performing the check again,
1999 even if the <code> changes. In order to force the check to be
2000 re-evaluated, the variable named by <resultVar> must be manually
2001 removed from the cache.
2002 The compile and link commands can be influenced by setting any
2004 of the following variables prior to calling check_source_com‐
2005 piles():
2006 CMAKE_REQUIRED_FLAGS
2008 String of additional flags to pass to the compiler. The
2009 string must be space-delimited--a ;-list will not work. The
2010 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
2011 tion-specific variable are automatically added to the com‐
2012 piler command before the contents of CMAKE_REQUIRED_FLAGS.
2013 CMAKE_REQUIRED_DEFINITIONS
2015 A ;-list of compiler definitions of the form -DFOO or
2016 -DFOO=bar. A definition for the name specified by <resultVar>
2017 will also be added automatically.
2018 CMAKE_REQUIRED_INCLUDES
2020 A ;-list of header search paths to pass to the compiler.
2021 These will be the only header search paths used--the contents
2022 of the INCLUDE_DIRECTORIES directory property will be ig‐
2023 nored.
2024 CMAKE_REQUIRED_LINK_OPTIONS
2026 New in version 3.14.
2027 A ;-list of options to add to the link command (see
2030 try_compile() for further details).
2031 CMAKE_REQUIRED_LIBRARIES
2033 A ;-list of libraries to add to the link command. These can
2034 be the name of system libraries or they can be Imported Tar‐
2035 gets (see try_compile() for further details).
2036 CMAKE_REQUIRED_QUIET
2038 New in version 3.1.
2039 If this variable evaluates to a boolean true value, all sta‐
2042 tus messages associated with the check will be suppressed.
2043 CheckSourceRuns
2045 New in version 3.19.
2046 Check if given source compiles and links into an executable and can
2049 subsequently be run.
2050 check_source_runs
2052 check_source_runs(<lang> <code> <resultVar>
2054 [SRC_EXT <extension>])
2055 Check that the source supplied in <code> can be compiled as a
2057 source file for the requested language, linked as an executable
2058 and then run. If the <code> could be built and run success‐
2059 fully, the internal cache variable specified by <resultVar> will
2060 be set to 1, otherwise it will be set to a value that evaluates
2061 to boolean false (e.g. an empty string or an error message).
2062 By default, the test source file will be given a file extension
2064 that matches the requested language. The SRC_EXT option can be
2065 used to override this with .<extension> instead.
2066 The <code> must contain a valid main program. For example:
2068 check_source_runs(C
2070 "#include <stdlib.h>
2071 #include <stdnoreturn.h>
2072 noreturn void f(){ exit(0); }
2073 int main(void) { f(); return 1; }"
2074 HAVE_NORETURN)
2075 check_source_runs(Fortran
2077 "program test
2078 real :: x[*]
2079 call co_sum(x)
2080 end program"
2081 HAVE_COARRAY)
2082 The check is only performed once, with the result cached in the
2084 variable named by <resultVar>. Every subsequent CMake run will
2085 re-use this cached value rather than performing the check again,
2086 even if the <code> changes. In order to force the check to be
2087 re-evaluated, the variable named by <resultVar> must be manually
2088 removed from the cache.
2089 The compile and link commands can be influenced by setting any
2091 of the following variables prior to calling check_source_runs()
2092 CMAKE_REQUIRED_FLAGS
2094 String of additional flags to pass to the compiler. The
2095 string must be space-delimited--a ;-list will not work. The
2096 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
2097 tion-specific variable are automatically added to the com‐
2098 piler command before the contents of CMAKE_REQUIRED_FLAGS.
2099 CMAKE_REQUIRED_DEFINITIONS
2101 A ;-list of compiler definitions of the form -DFOO or
2102 -DFOO=bar. A definition for the name specified by <resultVar>
2103 will also be added automatically.
2104 CMAKE_REQUIRED_INCLUDES
2106 A ;-list of header search paths to pass to the compiler.
2107 These will be the only header search paths used--the contents
2108 of the INCLUDE_DIRECTORIES directory property will be ig‐
2109 nored.
2110 CMAKE_REQUIRED_LINK_OPTIONS
2112 New in version 3.14.
2113 A ;-list of options to add to the link command (see
2116 try_compile() for further details).
2117 CMAKE_REQUIRED_LIBRARIES
2119 A ;-list of libraries to add to the link command. These can
2120 be the name of system libraries or they can be Imported Tar‐
2121 gets (see try_compile() for further details).
2122 CMAKE_REQUIRED_QUIET
2124 New in version 3.1.
2125 If this variable evaluates to a boolean true value, all sta‐
2128 tus messages associated with the check will be suppressed.
2129 CheckStructHasMember
2131 Check if the given struct or class has the specified member variable
2132 CHECK_STRUCT_HAS_MEMBER
2134 CHECK_STRUCT_HAS_MEMBER(<struct> <member> <header> <variable>
2136 [LANGUAGE <language>])
2137 <struct> - the name of the struct or class you are interested in
2139 <member> - the member which existence you want to check
2140 <header> - the header(s) where the prototype should be declared
2141 <variable> - variable to store the result
2142 <language> - the compiler to use (C or CXX)
2143 The following variables may be set before calling this macro to modify
2145 the way the check is run:
2146 CMAKE_REQUIRED_FLAGS
2148 String of additional flags to pass to the compiler. The
2149 string must be space-delimited--a ;-list will not work. The
2150 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
2151 tion-specific variable are automatically added to the com‐
2152 piler command before the contents of CMAKE_REQUIRED_FLAGS.
2153 CMAKE_REQUIRED_DEFINITIONS
2155 A ;-list of compiler definitions of the form -DFOO or
2156 -DFOO=bar. A definition for the name specified by <resultVar>
2157 will also be added automatically.
2158 CMAKE_REQUIRED_INCLUDES
2160 A ;-list of header search paths to pass to the compiler.
2161 These will be the only header search paths used--the contents
2162 of the INCLUDE_DIRECTORIES directory property will be ig‐
2163 nored.
2164 CMAKE_REQUIRED_LINK_OPTIONS
2166 New in version 3.14.
2167 A ;-list of options to add to the link command (see
2170 try_compile() for further details).
2171 CMAKE_REQUIRED_LIBRARIES
2173 A ;-list of libraries to add to the link command. These can
2174 be the name of system libraries or they can be Imported Tar‐
2175 gets (see try_compile() for further details).
2176 CMAKE_REQUIRED_QUIET
2178 New in version 3.1.
2179 If this variable evaluates to a boolean true value, all sta‐
2182 tus messages associated with the check will be suppressed.
2183 Example:
2185 CHECK_STRUCT_HAS_MEMBER("struct timeval" tv_sec sys/select.h
2187 HAVE_TIMEVAL_TV_SEC LANGUAGE C)
2188 CheckSymbolExists
2190 Provides a macro to check if a symbol exists as a function, variable,
2191 or macro in C.
2192 check_symbol_exists
2194 check_symbol_exists(<symbol> <files> <variable>)
2196 Check that the <symbol> is available after including given
2198 header <files> and store the result in a <variable>. Specify
2199 the list of files in one argument as a semicolon-separated list.
2200 <variable> will be created as an internal cache variable.
2201 If the header files define the symbol as a macro it is considered
2203 available and assumed to work. If the header files declare the symbol
2204 as a function or variable then the symbol must also be available for
2205 linking (so intrinsics may not be detected). If the symbol is a type,
2206 enum value, or intrinsic it will not be recognized (consider using
2207 CheckTypeSize or CheckSourceCompiles). If the check needs to be done
2208 in C++, consider using CheckCXXSymbolExists instead.
2209 The following variables may be set before calling this macro to modify
2211 the way the check is run:
2212 CMAKE_REQUIRED_FLAGS
2214 String of additional flags to pass to the compiler. The
2215 string must be space-delimited--a ;-list will not work. The
2216 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
2217 tion-specific variable are automatically added to the com‐
2218 piler command before the contents of CMAKE_REQUIRED_FLAGS.
2219 CMAKE_REQUIRED_DEFINITIONS
2221 A ;-list of compiler definitions of the form -DFOO or
2222 -DFOO=bar. A definition for the name specified by <resultVar>
2223 will also be added automatically.
2224 CMAKE_REQUIRED_INCLUDES
2226 A ;-list of header search paths to pass to the compiler.
2227 These will be the only header search paths used--the contents
2228 of the INCLUDE_DIRECTORIES directory property will be ig‐
2229 nored.
2230 CMAKE_REQUIRED_LINK_OPTIONS
2232 New in version 3.14.
2233 A ;-list of options to add to the link command (see
2236 try_compile() for further details).
2237 CMAKE_REQUIRED_LIBRARIES
2239 A ;-list of libraries to add to the link command. These can
2240 be the name of system libraries or they can be Imported Tar‐
2241 gets (see try_compile() for further details).
2242 CMAKE_REQUIRED_QUIET
2244 New in version 3.1.
2245 If this variable evaluates to a boolean true value, all sta‐
2248 tus messages associated with the check will be suppressed.
2249 For example:
2251 include(CheckSymbolExists)
2253 # Check for macro SEEK_SET
2255 check_symbol_exists(SEEK_SET "stdio.h" HAVE_SEEK_SET)
2256 # Check for function fopen
2257 check_symbol_exists(fopen "stdio.h" HAVE_FOPEN)
2258 CheckTypeSize
2260 Check sizeof a type
2261 check_type_size
2263 check_type_size(<type> <variable> [BUILTIN_TYPES_ONLY]
2265 [LANGUAGE <language>])
2266 Check if the type exists and determine its size. Results are
2268 reported in the following variables:
2269 HAVE_<variable>
2271 Holds a true or false value indicating whether the type
2272 exists.
2273 <variable>
2275 Holds one of the following values:
2276 <size> Type has non-zero size <size>.
2278 0 Type has architecture-dependent size. This may
2280 occur when CMAKE_OSX_ARCHITECTURES has multiple
2281 architectures. In this case <variable>_CODE con‐
2282 tains C preprocessor tests mapping from each ar‐
2283 chitecture macro to the corresponding type size.
2284 The list of architecture macros is stored in
2285 <variable>_KEYS, and the value for each key is
2286 stored in <variable>-<key>.
2287 "" (empty string)
2289 Type does not exist.
2290 <variable>_CODE
2292 Holds C preprocessor code to define the macro <variable>
2293 to the size of the type, or to leave the macro undefined
2294 if the type does not exist.
2295 The options are:
2297 BUILTIN_TYPES_ONLY
2299 Support only compiler-builtin types. If not given, the macro
2300 checks for headers <sys/types.h>, <stdint.h>, and <stddef.h>,
2301 and saves results in HAVE_SYS_TYPES_H, HAVE_STDINT_H, and
2302 HAVE_STDDEF_H. The type size check automatically includes
2303 the available headers, thus supporting checks of types de‐
2304 fined in the headers.
2305 LANGUAGE <language>
2307 Use the <language> compiler to perform the check. Ac‐
2308 ceptable values are C and CXX.
2309 Despite the name of the macro you may use it to check the size of more
2311 complex expressions, too. To check e.g. for the size of a struct mem‐
2312 ber you can do something like this:
2313 check_type_size("((struct something*)0)->member" SIZEOF_MEMBER)
2315 The following variables may be set before calling this macro to modify
2317 the way the check is run:
2318 CMAKE_REQUIRED_FLAGS
2320 String of additional flags to pass to the compiler. The
2321 string must be space-delimited--a ;-list will not work. The
2322 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
2323 tion-specific variable are automatically added to the com‐
2324 piler command before the contents of CMAKE_REQUIRED_FLAGS.
2325 CMAKE_REQUIRED_DEFINITIONS
2327 A ;-list of compiler definitions of the form -DFOO or
2328 -DFOO=bar. A definition for the name specified by <resultVar>
2329 will also be added automatically.
2330 CMAKE_REQUIRED_INCLUDES
2332 A ;-list of header search paths to pass to the compiler.
2333 These will be the only header search paths used--the contents
2334 of the INCLUDE_DIRECTORIES directory property will be ig‐
2335 nored.
2336 CMAKE_REQUIRED_LINK_OPTIONS
2338 New in version 3.14.
2339 A ;-list of options to add to the link command (see
2342 try_compile() for further details).
2343 CMAKE_REQUIRED_LIBRARIES
2345 A ;-list of libraries to add to the link command. These can
2346 be the name of system libraries or they can be Imported Tar‐
2347 gets (see try_compile() for further details).
2348 CMAKE_REQUIRED_QUIET
2350 New in version 3.1.
2351 If this variable evaluates to a boolean true value, all sta‐
2354 tus messages associated with the check will be suppressed.
2355 CMAKE_EXTRA_INCLUDE_FILES
2357 list of extra headers to include.
2358 CheckVariableExists
2360 Check if the variable exists.
2361 CHECK_VARIABLE_EXISTS
2363 CHECK_VARIABLE_EXISTS(VAR VARIABLE)
2365 VAR - the name of the variable
2367 VARIABLE - variable to store the result
2368 Will be created as an internal cache variable.
2369 This macro is only for C variables.
2371 The following variables may be set before calling this macro to modify
2373 the way the check is run:
2374 CMAKE_REQUIRED_FLAGS
2376 String of additional flags to pass to the compiler. The
2377 string must be space-delimited--a ;-list will not work. The
2378 contents of CMAKE_<LANG>_FLAGS and its associated configura‐
2379 tion-specific variable are automatically added to the com‐
2380 piler command before the contents of CMAKE_REQUIRED_FLAGS.
2381 CMAKE_REQUIRED_DEFINITIONS
2383 A ;-list of compiler definitions of the form -DFOO or
2384 -DFOO=bar. A definition for the name specified by <resultVar>
2385 will also be added automatically.
2386 CMAKE_REQUIRED_LINK_OPTIONS
2388 New in version 3.14.
2389 A ;-list of options to add to the link command (see
2392 try_compile() for further details).
2393 CMAKE_REQUIRED_LIBRARIES
2395 A ;-list of libraries to add to the link command. These can
2396 be the name of system libraries or they can be Imported Tar‐
2397 gets (see try_compile() for further details).
2398 CMAKE_REQUIRED_QUIET
2400 New in version 3.1.
2401 If this variable evaluates to a boolean true value, all sta‐
2404 tus messages associated with the check will be suppressed.
2405 CMakeAddFortranSubdirectory
2407 Add a fortran-only subdirectory, find a fortran compiler, and build.
2408 The cmake_add_fortran_subdirectory function adds a subdirectory to a
2410 project that contains a fortran-only subproject. The module will check
2411 the current compiler and see if it can support fortran. If no fortran
2412 compiler is found and the compiler is MSVC, then this module will find
2413 the MinGW gfortran. It will then use an external project to build with
2414 the MinGW tools. It will also create imported targets for the li‐
2415 braries created. This will only work if the fortran code is built into
2416 a dll, so BUILD_SHARED_LIBS is turned on in the project. In addition
2417 the CMAKE_GNUtoMS option is set to on, so that Microsoft .lib files are
2418 created. Usage is as follows:
2419 cmake_add_fortran_subdirectory(
2421 <subdir> # name of subdirectory
2422 PROJECT <project_name> # project name in subdir top CMakeLists.txt
2423 ARCHIVE_DIR <dir> # dir where project places .lib files
2424 RUNTIME_DIR <dir> # dir where project places .dll files
2425 LIBRARIES <lib>... # names of library targets to import
2426 LINK_LIBRARIES # link interface libraries for LIBRARIES
2427 [LINK_LIBS <lib> <dep>...]...
2428 CMAKE_COMMAND_LINE ... # extra command line flags to pass to cmake
2429 NO_EXTERNAL_INSTALL # skip installation of external project
2430 )
2431 Relative paths in ARCHIVE_DIR and RUNTIME_DIR are interpreted with re‐
2433 spect to the build directory corresponding to the source directory in
2434 which the function is invoked.
2435 Limitations:
2437 NO_EXTERNAL_INSTALL is required for forward compatibility with a future
2439 version that supports installation of the external project binaries
2440 during make install.
2441 CMakeBackwardCompatibilityCXX
2443 define a bunch of backwards compatibility variables
2444 CMAKE_ANSI_CXXFLAGS - flag for ansi c++
2446 CMAKE_HAS_ANSI_STRING_STREAM - has <strstream>
2447 include(TestForANSIStreamHeaders)
2448 include(CheckIncludeFileCXX)
2449 include(TestForSTDNamespace)
2450 include(TestForANSIForScope)
2451 CMakeDependentOption
2453 Macro to provide an option dependent on other options.
2454 This macro presents an option to the user only if a set of other condi‐
2456 tions are true.
2457 cmake_dependent_option
2459 cmake_dependent_option(<option> "<help_text>" <value> <depends> <force>)
2461 Makes <option> available to the user if the semicolon-separated
2463 list of conditions in <depends> are all true. Otherwise, a lo‐
2464 cal variable named <option> is set to <force>.
2465 When <option> is available, the given <help_text> and initial
2467 <value> are used. Otherwise, any value set by the user is pre‐
2468 served for when <depends> is satisfied in the future.
2469 Note that the <option> variable only has a value which satisfies
2471 the <depends> condition within the scope of the caller because
2472 it is a local variable.
2473 Example invocation:
2475 cmake_dependent_option(USE_FOO "Use Foo" ON "USE_BAR;NOT USE_ZOT" OFF)
2477 If USE_BAR is true and USE_ZOT is false, this provides an option called
2479 USE_FOO that defaults to ON. Otherwise, it sets USE_FOO to OFF and
2480 hides the option from the user. If the status of USE_BAR or USE_ZOT
2481 ever changes, any value for the USE_FOO option is saved so that when
2482 the option is re-enabled it retains its old value.
2483 New in version 3.22: Full Condition Syntax is now supported. See pol‐
2485 icy CMP0127.
2486 CMakeFindDependencyMacro
2489 find_dependency
2490 The find_dependency() macro wraps a find_package() call for a
2491 package dependency:
2492 find_dependency(<dep> [...])
2494 It is designed to be used in a Package Configuration File
2496 (<PackageName>Config.cmake). find_dependency forwards the cor‐
2497 rect parameters for QUIET and REQUIRED which were passed to the
2498 original find_package() call. Any additional arguments speci‐
2499 fied are forwarded to find_package().
2500 If the dependency could not be found it sets an informative di‐
2502 agnostic message and calls return() to end processing of the
2503 calling package configuration file and return to the
2504 find_package() command that loaded it.
2505 NOTE:
2507 The call to return() makes this macro unsuitable to call from
2508 Find Modules.
2509 Package Dependency Search Optimizations
2511 If find_dependency is called with arguments identical to a previous
2512 call in the same directory, perhaps due to diamond-shaped package de‐
2513 pendencies, the underlying call to find_package() is optimized out.
2514 This optimization is important to support large package dependency
2515 graphs while avoiding a combinatorial explosion of repeated searches.
2516 However, the heuristic cannot account for ambient variables that affect
2517 package behavior, such as <PackageName>_USE_STATIC_LIBS, offered by
2518 some packages. Therefore package configuration files should avoid set‐
2519 ting such variables before their calls to find_dependency.
2520 Changed in version 3.15: Previously, the underlying call to
2522 find_package() was always optimized out if the package had already been
2523 found. CMake 3.15 removed the optimization to support cases in which
2524 find_dependency call arguments request different components.
2525 Changed in version 3.26: The pre-3.15 optimization was restored, but
2528 with the above-described heuristic to account for varying find_depen‐
2529 dency call arguments.
2530 CMakeFindFrameworks
2533 helper module to find OSX frameworks
2534 This module reads hints about search locations from variables:
2536 CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS - Extra directories
2538 CMakeFindPackageMode
2540 This file is executed by cmake when invoked with --find-package. It
2541 expects that the following variables are set using -D:
2542 NAME name of the package
2544 COMPILER_ID
2546 the CMake compiler ID for which the result is, i.e. GNU/In‐
2547 tel/Clang/MSVC, etc.
2548 LANGUAGE
2550 language for which the result will be used, i.e. C/CXX/For‐
2551 tran/ASM
2552 MODE
2554 EXIST only check for existence of the given package
2556 COMPILE
2558 print the flags needed for compiling an object file which
2559 uses the given package
2560 LINK print the flags needed for linking when using the given
2562 package
2563 QUIET if TRUE, don't print anything
2565 CMakeGraphVizOptions
2567 The builtin Graphviz support of CMake.
2568 Generating Graphviz files
2570 CMake can generate Graphviz files showing the dependencies between the
2571 targets in a project, as well as external libraries which are linked
2572 against.
2573 When running CMake with the --graphviz=foo.dot option, it produces:
2575 • a foo.dot file, showing all dependencies in the project
2577 • a foo.dot.<target> file for each target, showing on which other tar‐
2579 gets it depends
2580 • a foo.dot.<target>.dependers file for each target, showing which
2582 other targets depend on it
2583 Those .dot files can be converted to images using the dot command from
2585 the Graphviz package:
2586 dot -Tpng -o foo.png foo.dot
2588 New in version 3.10: The different dependency types PUBLIC, INTERFACE
2590 and PRIVATE are represented as solid, dashed and dotted edges.
2591 Variables specific to the Graphviz support
2594 The resulting graphs can be huge. The look and content of the gener‐
2595 ated graphs can be controlled using the file CMakeGraphVizOp‐
2596 tions.cmake. This file is first searched in CMAKE_BINARY_DIR, and then
2597 in CMAKE_SOURCE_DIR. If found, the variables set in it are used to ad‐
2598 just options for the generated Graphviz files.
2599 GRAPHVIZ_GRAPH_NAME
2601 The graph name.
2602 • Mandatory: NO
2604 • Default: value of CMAKE_PROJECT_NAME
2606 GRAPHVIZ_GRAPH_HEADER
2608 The header written at the top of the Graphviz files.
2609 • Mandatory: NO
2611 • Default: "node [ fontsize = "12" ];"
2613 GRAPHVIZ_NODE_PREFIX
2615 The prefix for each node in the Graphviz files.
2616 • Mandatory: NO
2618 • Default: "node"
2620 GRAPHVIZ_EXECUTABLES
2622 Set to FALSE to exclude executables from the generated graphs.
2623 • Mandatory: NO
2625 • Default: TRUE
2627 GRAPHVIZ_STATIC_LIBS
2629 Set to FALSE to exclude static libraries from the generated
2630 graphs.
2631 • Mandatory: NO
2633 • Default: TRUE
2635 GRAPHVIZ_SHARED_LIBS
2637 Set to FALSE to exclude shared libraries from the generated
2638 graphs.
2639 • Mandatory: NO
2641 • Default: TRUE
2643 GRAPHVIZ_MODULE_LIBS
2645 Set to FALSE to exclude module libraries from the generated
2646 graphs.
2647 • Mandatory: NO
2649 • Default: TRUE
2651 GRAPHVIZ_INTERFACE_LIBS
2653 Set to FALSE to exclude interface libraries from the generated
2654 graphs.
2655 • Mandatory: NO
2657 • Default: TRUE
2659 GRAPHVIZ_OBJECT_LIBS
2661 Set to FALSE to exclude object libraries from the generated
2662 graphs.
2663 • Mandatory: NO
2665 • Default: TRUE
2667 GRAPHVIZ_UNKNOWN_LIBS
2669 Set to FALSE to exclude unknown libraries from the generated
2670 graphs.
2671 • Mandatory: NO
2673 • Default: TRUE
2675 GRAPHVIZ_EXTERNAL_LIBS
2677 Set to FALSE to exclude external libraries from the generated
2678 graphs.
2679 • Mandatory: NO
2681 • Default: TRUE
2683 GRAPHVIZ_CUSTOM_TARGETS
2685 Set to TRUE to include custom targets in the generated graphs.
2686 • Mandatory: NO
2688 • Default: FALSE
2690 GRAPHVIZ_IGNORE_TARGETS
2692 A list of regular expressions for names of targets to exclude
2693 from the generated graphs.
2694 • Mandatory: NO
2696 • Default: empty
2698 GRAPHVIZ_GENERATE_PER_TARGET
2700 Set to FALSE to not generate per-target graphs foo.dot.<target>.
2701 • Mandatory: NO
2703 • Default: TRUE
2705 GRAPHVIZ_GENERATE_DEPENDERS
2707 Set to FALSE to not generate depender graphs foo.dot.<tar‐
2708 get>.dependers.
2709 • Mandatory: NO
2711 • Default: TRUE
2713 CMakePackageConfigHelpers
2715 Helpers functions for creating config files that can be included by
2716 other projects to find and use a package.
2717 Adds the configure_package_config_file() and
2719 write_basic_package_version_file() commands.
2720 Generating a Package Configuration File
2722 configure_package_config_file
2723 Create a config file for a project:
2724 configure_package_config_file(<input> <output>
2726 INSTALL_DESTINATION <path>
2727 [PATH_VARS <var1> <var2> ... <varN>]
2728 [NO_SET_AND_CHECK_MACRO]
2729 [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
2730 [INSTALL_PREFIX <path>]
2731 )
2732 configure_package_config_file() should be used instead of the plain
2734 configure_file() command when creating the <PackageName>Config.cmake or
2735 <PackageName>-config.cmake file for installing a project or library.
2736 It helps making the resulting package relocatable by avoiding hardcoded
2737 paths in the installed Config.cmake file.
2738 In a FooConfig.cmake file there may be code like this to make the in‐
2740 stall destinations know to the using project:
2741 set(FOO_INCLUDE_DIR "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
2743 set(FOO_DATA_DIR "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
2744 set(FOO_ICONS_DIR "@CMAKE_INSTALL_PREFIX@/share/icons" )
2745 #...logic to determine installedPrefix from the own location...
2746 set(FOO_CONFIG_DIR "${installedPrefix}/@CONFIG_INSTALL_DIR@" )
2747 All 4 options shown above are not sufficient, since the first 3 hard‐
2749 code the absolute directory locations, and the 4th case works only if
2750 the logic to determine the installedPrefix is correct, and if CON‐
2751 FIG_INSTALL_DIR contains a relative path, which in general cannot be
2752 guaranteed. This has the effect that the resulting FooConfig.cmake
2753 file would work poorly under Windows and OSX, where users are used to
2754 choose the install location of a binary package at install time, inde‐
2755 pendent from how CMAKE_INSTALL_PREFIX was set at build/cmake time.
2756 Using configure_package_config_file helps. If used correctly, it makes
2758 the resulting FooConfig.cmake file relocatable. Usage:
2759 1. write a FooConfig.cmake.in file as you are used to
2761 2. insert a line containing only the string @PACKAGE_INIT@
2763 3. instead of set(FOO_DIR "@SOME_INSTALL_DIR@"), use set(FOO_DIR
2765 "@PACKAGE_SOME_INSTALL_DIR@") (this must be after the @PACKAGE_INIT@
2766 line)
2767 4. instead of using the normal configure_file(), use configure_pack‐
2769 age_config_file()
2770 The <input> and <output> arguments are the input and output file, the
2772 same way as in configure_file().
2773 The <path> given to INSTALL_DESTINATION must be the destination where
2775 the FooConfig.cmake file will be installed to. This path can either be
2776 absolute, or relative to the INSTALL_PREFIX path.
2777 The variables <var1> to <varN> given as PATH_VARS are the variables
2779 which contain install destinations. For each of them the macro will
2780 create a helper variable PACKAGE_<var...>. These helper variables must
2781 be used in the FooConfig.cmake.in file for setting the installed loca‐
2782 tion. They are calculated by configure_package_config_file so that
2783 they are always relative to the installed location of the package.
2784 This works both for relative and also for absolute locations. For ab‐
2785 solute locations it works only if the absolute location is a subdirec‐
2786 tory of INSTALL_PREFIX.
2787 New in version 3.1: If the INSTALL_PREFIX argument is passed, this is
2789 used as base path to calculate all the relative paths. The <path> ar‐
2790 gument must be an absolute path. If this argument is not passed, the
2791 CMAKE_INSTALL_PREFIX variable will be used instead. The default value
2792 is good when generating a FooConfig.cmake file to use your package from
2793 the install tree. When generating a FooConfig.cmake file to use your
2794 package from the build tree this option should be used.
2795 By default configure_package_config_file also generates two helper
2798 macros, set_and_check() and check_required_components() into the
2799 FooConfig.cmake file.
2800 set_and_check() should be used instead of the normal set() command for
2802 setting directories and file locations. Additionally to setting the
2803 variable it also checks that the referenced file or directory actually
2804 exists and fails with a FATAL_ERROR otherwise. This makes sure that
2805 the created FooConfig.cmake file does not contain wrong references.
2806 When using the NO_SET_AND_CHECK_MACRO, this macro is not generated into
2807 the FooConfig.cmake file.
2808 check_required_components(<PackageName>) should be called at the end of
2810 the FooConfig.cmake file. This macro checks whether all requested,
2811 non-optional components have been found, and if this is not the case,
2812 sets the Foo_FOUND variable to FALSE, so that the package is considered
2813 to be not found. It does that by testing the Foo_<Component>_FOUND
2814 variables for all requested required components. This macro should be
2815 called even if the package doesn't provide any components to make sure
2816 users are not specifying components erroneously. When using the
2817 NO_CHECK_REQUIRED_COMPONENTS_MACRO option, this macro is not generated
2818 into the FooConfig.cmake file.
2819 For an example see below the documentation for
2821 write_basic_package_version_file().
2822 Generating a Package Version File
2824 write_basic_package_version_file
2825 Create a version file for a project:
2826 write_basic_package_version_file(<filename>
2828 [VERSION <major.minor.patch>]
2829 COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion>
2830 [ARCH_INDEPENDENT] )
2831 Writes a file for use as <PackageName>ConfigVersion.cmake file to
2833 <filename>. See the documentation of find_package() for details on
2834 this.
2835 <filename> is the output filename, it should be in the build tree.
2837 <major.minor.patch> is the version number of the project to be in‐
2838 stalled.
2839 If no VERSION is given, the PROJECT_VERSION variable is used. If this
2841 hasn't been set, it errors out.
2842 The COMPATIBILITY mode AnyNewerVersion means that the installed package
2844 version will be considered compatible if it is newer or exactly the
2845 same as the requested version. This mode should be used for packages
2846 which are fully backward compatible, also across major versions. If
2847 SameMajorVersion is used instead, then the behavior differs from
2848 AnyNewerVersion in that the major version number must be the same as
2849 requested, e.g. version 2.0 will not be considered compatible if 1.0
2850 is requested. This mode should be used for packages which guarantee
2851 backward compatibility within the same major version. If SameMinorVer‐
2852 sion is used, the behavior is the same as SameMajorVersion, but both
2853 major and minor version must be the same as requested, e.g version 0.2
2854 will not be compatible if 0.1 is requested. If ExactVersion is used,
2855 then the package is only considered compatible if the requested version
2856 matches exactly its own version number (not considering the tweak ver‐
2857 sion). For example, version 1.2.3 of a package is only considered com‐
2858 patible to requested version 1.2.3. This mode is for packages without
2859 compatibility guarantees. If your project has more elaborated version
2860 matching rules, you will need to write your own custom ConfigVer‐
2861 sion.cmake file instead of using this macro.
2862 New in version 3.11: The SameMinorVersion compatibility mode.
2864 New in version 3.14: If ARCH_INDEPENDENT is given, the installed pack‐
2867 age version will be considered compatible even if it was built for a
2868 different architecture than the requested architecture. Otherwise, an
2869 architecture check will be performed, and the package will be consid‐
2870 ered compatible only if the architecture matches exactly. For example,
2871 if the package is built for a 32-bit architecture, the package is only
2872 considered compatible if it is used on a 32-bit architecture, unless
2873 ARCH_INDEPENDENT is given, in which case the package is considered com‐
2874 patible on any architecture.
2875 NOTE:
2878 ARCH_INDEPENDENT is intended for header-only libraries or similar
2879 packages with no binaries.
2880 New in version 3.19: The version file generated by AnyNewerVersion,
2882 SameMajorVersion and SameMinorVersion arguments of COMPATIBILITY handle
2883 the version range if any is specified (see find_package() command for
2884 the details). ExactVersion mode is incompatible with version ranges
2885 and will display an author warning if one is specified.
2886 Internally, this macro executes configure_file() to create the result‐
2889 ing version file. Depending on the COMPATIBILITY, the corresponding
2890 BasicConfigVersion-<COMPATIBILITY>.cmake.in file is used. Please note
2891 that these files are internal to CMake and you should not call
2892 configure_file() on them yourself, but they can be used as starting
2893 point to create more sophisticated custom ConfigVersion.cmake files.
2894 Example Generating Package Files
2896 Example using both configure_package_config_file() and write_ba‐
2897 sic_package_version_file():
2898 CMakeLists.txt:
2900 include(GNUInstallDirs)
2902 set(INCLUDE_INSTALL_DIR ${CMAKE_INSTALL_INCLUDEDIR}/Foo
2903 CACHE PATH "Location of header files" )
2904 set(SYSCONFIG_INSTALL_DIR ${CMAKE_INSTALL_SYSCONFDIR}/foo
2905 CACHE PATH "Location of configuration files" )
2906 #...
2907 include(CMakePackageConfigHelpers)
2908 configure_package_config_file(FooConfig.cmake.in
2909 ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2910 INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Foo
2911 PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
2912 write_basic_package_version_file(
2913 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2914 VERSION 1.2.3
2915 COMPATIBILITY SameMajorVersion )
2916 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2917 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2918 DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Foo )
2919 FooConfig.cmake.in:
2921 set(FOO_VERSION x.y.z)
2923 ...
2924 @PACKAGE_INIT@
2925 ...
2926 set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
2927 set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")
2928 check_required_components(Foo)
2930 CMakePrintHelpers
2932 Convenience functions for printing properties and variables, useful
2933 e.g. for debugging.
2934 cmake_print_properties(<TARGETS [<target1> ...] |
2936 SOURCES [<source1> ...] |
2937 DIRECTORIES [<dir1> ...] |
2938 TESTS [<test1> ...] |
2939 CACHE_ENTRIES [<entry1> ...] >
2940 PROPERTIES [<prop1> ...] )
2941 This function prints the values of the properties of the given targets,
2943 source files, directories, tests or cache entries. Exactly one of the
2944 scope keywords must be used. The scope keyword and its arguments must
2945 come before the PROPERTIES keyword, in the arguments list.
2946 Example:
2948 cmake_print_properties(TARGETS foo bar PROPERTIES
2950 LOCATION INTERFACE_INCLUDE_DIRECTORIES)
2951 This will print the LOCATION and INTERFACE_INCLUDE_DIRECTORIES proper‐
2953 ties for both targets foo and bar.
2954 cmake_print_variables(var1 var2 .. varN)
2956 This function will print the name of each variable followed by its
2958 value. Example:
2959 cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION DOES_NOT_EXIST)
2961 Gives:
2963 -- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; DOES_NOT_EXIST=""
2965 CMakePrintSystemInformation
2967 Print system information.
2968 This module serves diagnostic purposes. Just include it in a project to
2970 see various internal CMake variables.
2971 CMakePushCheckState
2973 This module defines three macros: CMAKE_PUSH_CHECK_STATE()
2974 CMAKE_POP_CHECK_STATE() and CMAKE_RESET_CHECK_STATE() These macros can
2975 be used to save, restore and reset (i.e., clear contents) the state of
2976 the variables CMAKE_REQUIRED_FLAGS, CMAKE_REQUIRED_DEFINITIONS,
2977 CMAKE_REQUIRED_LINK_OPTIONS, CMAKE_REQUIRED_LIBRARIES, CMAKE_RE‐
2978 QUIRED_INCLUDES and CMAKE_EXTRA_INCLUDE_FILES used by the various
2979 Check-files coming with CMake, like e.g. check_function_exists() etc.
2980 The variable contents are pushed on a stack, pushing multiple times is
2981 supported. This is useful e.g. when executing such tests in a
2982 Find-module, where they have to be set, but after the Find-module has
2983 been executed they should have the same value as they had before.
2984 CMAKE_PUSH_CHECK_STATE() macro receives optional argument RESET.
2986 Whether it's specified, CMAKE_PUSH_CHECK_STATE() will set all CMAKE_RE‐
2987 QUIRED_* variables to empty values, same as CMAKE_RESET_CHECK_STATE()
2988 call will do.
2989 Usage:
2991 cmake_push_check_state(RESET)
2993 set(CMAKE_REQUIRED_DEFINITIONS -DSOME_MORE_DEF)
2994 check_function_exists(...)
2995 cmake_reset_check_state()
2996 set(CMAKE_REQUIRED_DEFINITIONS -DANOTHER_DEF)
2997 check_function_exists(...)
2998 cmake_pop_check_state()
2999 CMakeVerifyManifest
3001 CMakeVerifyManifest.cmake
3002 This script is used to verify that embedded manifests and side by side
3004 manifests for a project match. To run this script, cd to a directory
3005 and run the script with cmake -P. On the command line you can pass in
3006 versions that are OK even if not found in the .manifest files. For ex‐
3007 ample, cmake -Dallow_versions=8.0.50608.0 -PCmakeVerifyManifest.cmake
3008 could be used to allow an embedded manifest of 8.0.50608.0 to be used
3009 in a project even if that version was not found in the .manifest file.
3010 CPack
3012 Configure generators for binary installers and source packages.
3013 Introduction
3015 The CPack module generates the configuration files CPackConfig.cmake
3016 and CPackSourceConfig.cmake. They are intended for use in a subsequent
3017 run of the cpack program where they steer the generation of installers
3018 or/and source packages.
3019 Depending on the CMake generator, the CPack module may also add two new
3021 build targets, package and package_source. See the packaging targets
3022 section below for details.
3023 The generated binary installers will contain all files that have been
3025 installed via CMake's install() command (and the deprecated commands
3026 install_files(), install_programs(), and install_targets()). Note that
3027 the DESTINATION option of the install() command must be a relative
3028 path; otherwise installed files are ignored by CPack.
3029 Certain kinds of binary installers can be configured such that users
3031 can select individual application components to install. See the
3032 CPackComponent module for further details.
3033 Source packages (configured through CPackSourceConfig.cmake and gener‐
3035 ated by the CPack Archive Generator) will contain all source files in
3036 the project directory except those specified in
3037 CPACK_SOURCE_IGNORE_FILES.
3038 CPack Generators
3040 The CPACK_GENERATOR variable has different meanings in different con‐
3041 texts. In a CMakeLists.txt file, CPACK_GENERATOR is a list of genera‐
3042 tors: and when cpack is run with no other arguments, it will iterate
3043 over that list and produce one package for each generator. In a
3044 CPACK_PROJECT_CONFIG_FILE, CPACK_GENERATOR is a string naming a single
3045 generator. If you need per-cpack-generator logic to control other
3046 cpack settings, then you need a CPACK_PROJECT_CONFIG_FILE. If set, the
3047 CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator
3048 basis. It only need contain overrides.
3049 Here's how it works:
3051 • cpack runs
3053 • it includes CPackConfig.cmake
3055 • it iterates over the generators given by the -G command line option,
3057 or if no such option was specified, over the list of generators given
3058 by the CPACK_GENERATOR variable set in the CPackConfig.cmake input
3059 file.
3060 • foreach generator, it then
3062 • sets CPACK_GENERATOR to the one currently being iterated
3064 • includes the CPACK_PROJECT_CONFIG_FILE
3066 • produces the package for that generator
3068 This is the key: For each generator listed in CPACK_GENERATOR in CPack‐
3070 Config.cmake, cpack will reset CPACK_GENERATOR internally to the one
3071 currently being used and then include the CPACK_PROJECT_CONFIG_FILE.
3072 For a list of available generators, see cpack-generators(7).
3074 Targets package and package_source
3076 If CMake is run with the Makefile, Ninja, or Xcode generator, then in‐
3077 clude(CPack) generates a target package. This makes it possible to
3078 build a binary installer from CMake, Make, or Ninja: Instead of cpack,
3079 one may call cmake --build . --target package or make package or ninja
3080 package. The VS generator creates an uppercase target PACKAGE.
3081 If CMake is run with the Makefile or Ninja generator, then in‐
3083 clude(CPack) also generates a target package_source. To build a source
3084 package, instead of cpack -G TGZ --config CPackSourceConfig.cmake one
3085 may call cmake --build . --target package_source, make package_source,
3086 or ninja package_source.
3087 Variables common to all CPack Generators
3089 Before including this CPack module in your CMakeLists.txt file, there
3090 are a variety of variables that can be set to customize the resulting
3091 installers. The most commonly-used variables are:
3092 CPACK_PACKAGE_NAME
3094 The name of the package (or application). If not specified, it
3095 defaults to the project name.
3096 CPACK_PACKAGE_VENDOR
3098 The name of the package vendor. (e.g., "Kitware"). The default
3099 is "Humanity".
3100 CPACK_PACKAGE_DIRECTORY
3102 The directory in which CPack is doing its packaging. If it is
3103 not set then this will default (internally) to the build dir.
3104 This variable may be defined in a CPack config file or from the
3105 cpack command line option -B. If set, the command line option
3106 overrides the value found in the config file.
3107 CPACK_PACKAGE_VERSION_MAJOR
3109 Package major version. This variable will always be set, but
3110 its default value depends on whether or not version details were
3111 given to the project() command in the top level CMakeLists.txt
3112 file. If version details were given, the default value will be
3113 CMAKE_PROJECT_VERSION_MAJOR. If no version details were given,
3114 a default version of 0.1.1 will be assumed, leading to
3115 CPACK_PACKAGE_VERSION_MAJOR having a default value of 0.
3116 CPACK_PACKAGE_VERSION_MINOR
3118 Package minor version. The default value is determined based on
3119 whether or not version details were given to the project() com‐
3120 mand in the top level CMakeLists.txt file. If version details
3121 were given, the default value will be
3122 CMAKE_PROJECT_VERSION_MINOR, but if no minor version component
3123 was specified then CPACK_PACKAGE_VERSION_MINOR will be left un‐
3124 set. If no project version was given at all, a default version
3125 of 0.1.1 will be assumed, leading to CPACK_PACKAGE_VERSION_MINOR
3126 having a default value of 1.
3127 CPACK_PACKAGE_VERSION_PATCH
3129 Package patch version. The default value is determined based on
3130 whether or not version details were given to the project() com‐
3131 mand in the top level CMakeLists.txt file. If version details
3132 were given, the default value will be
3133 CMAKE_PROJECT_VERSION_PATCH, but if no patch version component
3134 was specified then CPACK_PACKAGE_VERSION_PATCH will be left un‐
3135 set. If no project version was given at all, a default version
3136 of 0.1.1 will be assumed, leading to CPACK_PACKAGE_VERSION_PATCH
3137 having a default value of 1.
3138 CPACK_PACKAGE_DESCRIPTION
3140 A description of the project, used in places such as the intro‐
3141 duction screen of CPack-generated Windows installers. If not
3142 set, the value of this variable is populated from the file named
3143 by CPACK_PACKAGE_DESCRIPTION_FILE.
3144 CPACK_PACKAGE_DESCRIPTION_FILE
3146 A text file used to describe the project when
3147 CPACK_PACKAGE_DESCRIPTION is not explicitly set. The default
3148 value for CPACK_PACKAGE_DESCRIPTION_FILE points to a built-in
3149 template file Templates/CPack.GenericDescription.txt.
3150 CPACK_PACKAGE_DESCRIPTION_SUMMARY
3152 Short description of the project (only a few words). If the
3153 CMAKE_PROJECT_DESCRIPTION variable is set, it is used as the de‐
3154 fault value, otherwise the default will be a string generated by
3155 CMake based on CMAKE_PROJECT_NAME.
3156 CPACK_PACKAGE_HOMEPAGE_URL
3158 Project homepage URL. The default value is taken from the
3159 CMAKE_PROJECT_HOMEPAGE_URL variable, which is set by the top
3160 level project() command, or else the default will be empty if no
3161 URL was provided to project().
3162 CPACK_PACKAGE_FILE_NAME
3164 The name of the package file to generate, not including the ex‐
3165 tension. For example, cmake-2.6.1-Linux-i686. The default
3166 value is:
3167 ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}
3169 CPACK_PACKAGE_INSTALL_DIRECTORY
3171 Installation directory on the target system. This may be used by
3172 some CPack generators like NSIS to create an installation direc‐
3173 tory e.g., "CMake 2.5" below the installation prefix. All in‐
3174 stalled elements will be put inside this directory.
3175 CPACK_PACKAGE_ICON
3177 A branding image that will be displayed inside the installer
3178 (used by GUI installers).
3179 CPACK_PACKAGE_CHECKSUM
3181 New in version 3.7.
3182 An algorithm that will be used to generate an additional file
3185 with the checksum of the package. The output file name will be:
3186 ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}
3188 Supported algorithms are those listed by the string(<HASH>) com‐
3190 mand.
3191 CPACK_PROJECT_CONFIG_FILE
3193 CPack-time project CPack configuration file. This file is in‐
3194 cluded at cpack time, once per generator after CPack has set
3195 CPACK_GENERATOR to the actual generator being used. It allows
3196 per-generator setting of CPACK_* variables at cpack time.
3197 CPACK_RESOURCE_FILE_LICENSE
3199 License to be embedded in the installer. It will typically be
3200 displayed to the user by the produced installer (often with an
3201 explicit "Accept" button, for graphical installers) prior to in‐
3202 stallation. This license file is NOT added to the installed
3203 files but is used by some CPack generators like NSIS. If you
3204 want to use UTF-8 characters, the file needs to be encoded in
3205 UTF-8 BOM. If you want to install a license file (may be the
3206 same as this one) along with your project, you must add an ap‐
3207 propriate CMake install() command in your CMakeLists.txt.
3208 CPACK_RESOURCE_FILE_README
3210 ReadMe file to be embedded in the installer. It typically de‐
3211 scribes in some detail the purpose of the project during the in‐
3212 stallation. Not all CPack generators use this file.
3213 CPACK_RESOURCE_FILE_WELCOME
3215 Welcome file to be embedded in the installer. It welcomes users
3216 to this installer. Typically used in the graphical installers
3217 on Windows and Mac OS X.
3218 CPACK_MONOLITHIC_INSTALL
3220 Disables the component-based installation mechanism. When set,
3221 the component specification is ignored and all installed items
3222 are put in a single "MONOLITHIC" package. Some CPack generators
3223 do monolithic packaging by default and may be asked to do compo‐
3224 nent packaging by setting CPACK_<GENNAME>_COMPONENT_INSTALL to
3225 TRUE.
3226 CPACK_GENERATOR
3228 List of CPack generators to use. If not specified, CPack will
3229 create a set of options following the naming pattern
3230 CPACK_BINARY_<GENNAME> (e.g. CPACK_BINARY_NSIS) allowing the
3231 user to enable/disable individual generators. If the -G option
3232 is given on the cpack command line, it will override this vari‐
3233 able and any CPACK_BINARY_<GENNAME> options.
3234 CPACK_OUTPUT_CONFIG_FILE
3236 The name of the CPack binary configuration file. This file is
3237 the CPack configuration generated by the CPack module for binary
3238 installers. Defaults to CPackConfig.cmake.
3239 CPACK_PACKAGE_EXECUTABLES
3241 Lists each of the executables and associated text label to be
3242 used to create Start Menu shortcuts. For example, setting this
3243 to the list ccmake;CMake will create a shortcut named "CMake"
3244 that will execute the installed executable ccmake. Not all CPack
3245 generators use it (at least NSIS, Inno Setup and WIX do).
3246 CPACK_STRIP_FILES
3248 List of files to be stripped. Starting with CMake 2.6.0,
3249 CPACK_STRIP_FILES will be a boolean variable which enables
3250 stripping of all files (a list of files evaluates to TRUE in
3251 CMake, so this change is compatible).
3252 CPACK_VERBATIM_VARIABLES
3254 New in version 3.4.
3255 If set to TRUE, values of variables prefixed with CPACK_ will be
3258 escaped before being written to the configuration files, so that
3259 the cpack program receives them exactly as they were specified.
3260 If not, characters like quotes and backslashes can cause parsing
3261 errors or alter the value received by the cpack program. De‐
3262 faults to FALSE for backwards compatibility.
3263 CPACK_THREADS
3265 New in version 3.20.
3266 Number of threads to use when performing parallelized opera‐
3269 tions, such as compressing the installer package.
3270 Some compression methods used by CPack generators such as Debian
3272 or Archive may take advantage of multiple CPU cores to speed up
3273 compression. CPACK_THREADS can be set to specify how many
3274 threads will be used for compression.
3275 A positive integer can be used to specify an exact desired
3277 thread count.
3278 When given a negative integer CPack will use the absolute value
3280 as the upper limit but may choose a lower value based on the
3281 available hardware concurrency.
3282 Given 0 CPack will try to use all available CPU cores.
3284 By default CPACK_THREADS is set to 1.
3286 The following compression methods may take advantage of multiple
3288 cores:
3289 xz Supported if CMake is built with a liblzma that supports
3291 parallel compression.
3292 New in version 3.21: Official CMake binaries available on
3294 cmake.org now ship with a liblzma that supports parallel
3295 compression. Older versions did not.
3296 zstd New in version 3.24.
3299 Supported if CMake is built with libarchive 3.6 or
3302 higher. Official CMake binaries available on cmake.org
3303 support it.
3304 Other compression methods ignore this value and use only one
3306 thread.
3307 Variables for Source Package Generators
3309 The following CPack variables are specific to source packages, and will
3310 not affect binary packages:
3311 CPACK_SOURCE_PACKAGE_FILE_NAME
3313 The name of the source package. For example cmake-2.6.1.
3314 CPACK_SOURCE_STRIP_FILES
3316 List of files in the source tree that will be stripped. Start‐
3317 ing with CMake 2.6.0, CPACK_SOURCE_STRIP_FILES will be a boolean
3318 variable which enables stripping of all files (a list of files
3319 evaluates to TRUE in CMake, so this change is compatible).
3320 CPACK_SOURCE_GENERATOR
3322 List of generators used for the source packages. As with
3323 CPACK_GENERATOR, if this is not specified then CPack will create
3324 a set of options (e.g. CPACK_SOURCE_ZIP) allowing users to se‐
3325 lect which packages will be generated.
3326 CPACK_SOURCE_OUTPUT_CONFIG_FILE
3328 The name of the CPack source configuration file. This file is
3329 the CPack configuration generated by the CPack module for source
3330 installers. Defaults to CPackSourceConfig.cmake.
3331 CPACK_SOURCE_IGNORE_FILES
3333 Pattern of files in the source tree that won't be packaged when
3334 building a source package. This is a list of regular expression
3335 patterns (that must be properly escaped), e.g.,
3336 /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
3337 Variables for Advanced Use
3339 The following variables are for advanced uses of CPack:
3340 CPACK_CMAKE_GENERATOR
3342 What CMake generator should be used if the project is a CMake
3343 project. Defaults to the value of CMAKE_GENERATOR. Few users
3344 will want to change this setting.
3345 CPACK_INSTALL_CMAKE_PROJECTS
3347 List of four values that specify what project to install. The
3348 four values are: Build directory, Project Name, Project Compo‐
3349 nent, Directory. If omitted, CPack will build an installer that
3350 installs everything.
3351 CPACK_SYSTEM_NAME
3353 System name, defaults to the value of CMAKE_SYSTEM_NAME, except
3354 on Windows where it will be win32 or win64.
3355 CPACK_PACKAGE_VERSION
3357 Package full version, used internally. By default, this is
3358 built from CPACK_PACKAGE_VERSION_MAJOR,
3359 CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH.
3360 CPACK_TOPLEVEL_TAG
3362 Directory for the installed files.
3363 CPACK_INSTALL_COMMANDS
3365 Extra commands to install components. The environment variable
3366 CMAKE_INSTALL_PREFIX is set to the temporary install directory
3367 during execution.
3368 CPACK_INSTALL_SCRIPTS
3370 New in version 3.16.
3371 Extra CMake scripts executed by CPack during its local staging
3374 installation. They are executed before installing the files to
3375 be packaged. The scripts are not called by a standalone install
3376 (e.g.: make install). For every script, the following variables
3377 will be set: CMAKE_CURRENT_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR
3378 and CMAKE_INSTALL_PREFIX (which is set to the staging install
3379 directory). The singular form CMAKE_INSTALL_SCRIPT is supported
3380 as an alternative variable for historical reasons, but its value
3381 is ignored if CMAKE_INSTALL_SCRIPTS is set and a warning will be
3382 issued.
3383 See also CPACK_PRE_BUILD_SCRIPTS and CPACK_POST_BUILD_SCRIPTS
3385 which can be used to specify scripts to be executed later in the
3386 packaging process.
3387 CPACK_PRE_BUILD_SCRIPTS
3389 New in version 3.19.
3390 List of CMake scripts to execute after CPack has installed the
3393 files to be packaged into a staging directory and before produc‐
3394 ing the package(s) from those files. See also
3395 CPACK_INSTALL_SCRIPTS and CPACK_POST_BUILD_SCRIPTS.
3396 CPACK_POST_BUILD_SCRIPTS
3398 New in version 3.19.
3399 List of CMake scripts to execute after CPack has produced the
3402 resultant packages and before copying them back to the build di‐
3403 rectory. See also CPACK_INSTALL_SCRIPTS,
3404 CPACK_PRE_BUILD_SCRIPTS and CPACK_PACKAGE_FILES.
3405 CPACK_PACKAGE_FILES
3407 New in version 3.19.
3408 List of package files created in the staging directory, with
3411 each file provided as a full absolute path. This variable is
3412 populated by CPack just before invoking the post-build scripts
3413 listed in CPACK_POST_BUILD_SCRIPTS. It is the preferred way for
3414 the post-build scripts to know the set of package files to oper‐
3415 ate on. Projects should not try to set this variable them‐
3416 selves.
3417 CPACK_INSTALLED_DIRECTORIES
3419 Extra directories to install.
3420 CPACK_PACKAGE_INSTALL_REGISTRY_KEY
3422 Registry key used when installing this project. This is only
3423 used by installers for Windows. The default value is based on
3424 the installation directory.
3425 CPACK_CREATE_DESKTOP_LINKS
3427 List of desktop links to create. Each desktop link requires a
3428 corresponding start menu shortcut as created by
3429 CPACK_PACKAGE_EXECUTABLES.
3430 CPACK_BINARY_<GENNAME>
3432 CPack generated options for binary generators. The CPack.cmake
3433 module generates (when CPACK_GENERATOR is not set) a set of
3434 CMake options (see CMake option() command) which may then be
3435 used to select the CPack generator(s) to be used when building
3436 the package target or when running cpack without the -G option.
3437 CPACK_READELF_EXECUTABLE
3439 New in version 3.25.
3440 Specify the readelf executable path used by CPack. The default
3443 value will be CMAKE_READELF when set. Otherwise, the default
3444 value will be empty and CPack will use find_program() to deter‐
3445 mine the readelf path when needed.
3446 CPACK_OBJCOPY_EXECUTABLE
3448 New in version 3.25.
3449 Specify the objcopy executable path used by CPack. The default
3452 value will be CMAKE_OBJCOPY when set. Otherwise, the default
3453 value will be empty and CPack will use find_program() to deter‐
3454 mine the objcopy path when needed.
3455 CPACK_OBJDUMP_EXECUTABLE
3457 New in version 3.25.
3458 Specify the objdump executable path used by CPack. The default
3461 value will be CMAKE_OBJDUMP when set. Otherwise, the default
3462 value will be empty and CPack will use find_program() to deter‐
3463 mine the objdump path when needed.
3464 CPackComponent
3466 Configure components for binary installers and source packages.
3467 Introduction
3469 This module is automatically included by CPack.
3470 Certain binary installers (especially the graphical installers) gener‐
3472 ated by CPack allow users to select individual application components
3473 to install. This module allows developers to configure the packaging
3474 of such components.
3475 Contents is assigned to components by the COMPONENT argument of CMake's
3477 install() command. Components can be annotated with user-friendly
3478 names and descriptions, inter-component dependencies, etc., and grouped
3479 in various ways to customize the resulting installer, using the com‐
3480 mands described below.
3481 To specify different groupings for different CPack generators use a
3483 CPACK_PROJECT_CONFIG_FILE.
3484 Variables
3486 The following variables influence the component-specific packaging:
3487 CPACK_COMPONENTS_ALL
3489 The list of component to install.
3490 The default value of this variable is computed by CPack and con‐
3492 tains all components defined by the project. The user may set
3493 it to only include the specified components.
3494 Instead of specifying all the desired components, it is possible
3496 to obtain a list of all defined components and then remove the
3497 unwanted ones from the list. The get_cmake_property() command
3498 can be used to obtain the COMPONENTS property, then the
3499 list(REMOVE_ITEM) command can be used to remove the unwanted
3500 ones. For example, to use all defined components except foo and
3501 bar:
3502 get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS)
3504 list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar")
3505 CPACK_<GENNAME>_COMPONENT_INSTALL
3507 Enable/Disable component install for CPack generator <GENNAME>.
3508 Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc...) has
3510 a legacy default behavior. e.g. RPM builds monolithic whereas
3511 NSIS builds component. One can change the default behavior by
3512 setting this variable to 0/1 or OFF/ON.
3513 CPACK_COMPONENTS_GROUPING
3515 Specify how components are grouped for multi-package compo‐
3516 nent-aware CPack generators.
3517 Some generators like RPM or ARCHIVE (TGZ, ZIP, ...) may generate
3519 several packages files when there are components, depending on
3520 the value of this variable:
3521 • ONE_PER_GROUP (default): create one package per component
3523 group
3524 • IGNORE : create one package per component (ignore the groups)
3526 • ALL_COMPONENTS_IN_ONE : create a single package with all re‐
3528 quested components
3529 CPACK_COMPONENT_<compName>_DISPLAY_NAME
3531 The name to be displayed for a component.
3532 CPACK_COMPONENT_<compName>_DESCRIPTION
3534 The description of a component.
3535 CPACK_COMPONENT_<compName>_GROUP
3537 The group of a component.
3538 CPACK_COMPONENT_<compName>_DEPENDS
3540 The dependencies (list of components) on which this component
3541 depends.
3542 CPACK_COMPONENT_<compName>_HIDDEN
3544 True if this component is hidden from the user.
3545 CPACK_COMPONENT_<compName>_REQUIRED
3547 True if this component is required.
3548 CPACK_COMPONENT_<compName>_DISABLED
3550 True if this component is not selected to be installed by de‐
3551 fault.
3552 Commands
3554 Add component
3555 cpack_add_component
3556 Describe an installation component.
3558 cpack_add_component(compname
3560 [DISPLAY_NAME name]
3561 [DESCRIPTION description]
3562 [HIDDEN | REQUIRED | DISABLED ]
3563 [GROUP group]
3564 [DEPENDS comp1 comp2 ... ]
3565 [INSTALL_TYPES type1 type2 ... ]
3566 [DOWNLOADED]
3567 [ARCHIVE_FILE filename]
3568 [PLIST filename])
3569 compname is the name of an installation component, as defined by the
3571 COMPONENT argument of one or more CMake install() commands. With the
3572 cpack_add_component command one can set a name, a description, and
3573 other attributes of an installation component. One can also assign a
3574 component to a component group.
3575 DISPLAY_NAME is the displayed name of the component, used in graphical
3577 installers to display the component name. This value can be any
3578 string.
3579 DESCRIPTION is an extended description of the component, used in graph‐
3581 ical installers to give the user additional information about the com‐
3582 ponent. Descriptions can span multiple lines using \n as the line sep‐
3583 arator. Typically, these descriptions should be no more than a few
3584 lines long.
3585 HIDDEN indicates that this component will be hidden in the graphical
3587 installer, so that the user cannot directly change whether it is in‐
3588 stalled or not.
3589 REQUIRED indicates that this component is required, and therefore will
3591 always be installed. It will be visible in the graphical installer,
3592 but it cannot be unselected. (Typically, required components are shown
3593 grayed out).
3594 DISABLED indicates that this component should be disabled (unselected)
3596 by default. The user is free to select this component for installa‐
3597 tion, unless it is also HIDDEN.
3598 DEPENDS lists the components on which this component depends. If this
3600 component is selected, then each of the components listed must also be
3601 selected. The dependency information is encoded within the installer
3602 itself, so that users cannot install inconsistent sets of components.
3603 GROUP names the component group of which this component is a part. If
3605 not provided, the component will be a standalone component, not part of
3606 any component group. Component groups are described with the
3607 cpack_add_component_group command, detailed below.
3608 INSTALL_TYPES lists the installation types of which this component is a
3610 part. When one of these installations types is selected, this compo‐
3611 nent will automatically be selected. Installation types are described
3612 with the cpack_add_install_type command, detailed below.
3613 DOWNLOADED indicates that this component should be downloaded
3615 on-the-fly by the installer, rather than packaged in with the installer
3616 itself. For more information, see the cpack_configure_downloads com‐
3617 mand.
3618 ARCHIVE_FILE provides a name for the archive file created by CPack to
3620 be used for downloaded components. If not supplied, CPack will create
3621 a file with some name based on CPACK_PACKAGE_FILE_NAME and the name of
3622 the component. See cpack_configure_downloads for more information.
3623 PLIST gives a filename that is passed to pkgbuild with the --compo‐
3625 nent-plist argument when using the productbuild generator.
3626 Add component group
3628 cpack_add_component_group
3629 Describes a group of related CPack installation components.
3631 cpack_add_component_group(groupname
3633 [DISPLAY_NAME name]
3634 [DESCRIPTION description]
3635 [PARENT_GROUP parent]
3636 [EXPANDED]
3637 [BOLD_TITLE])
3638 The cpack_add_component_group describes a group of installation compo‐
3640 nents, which will be placed together within the listing of options.
3641 Typically, component groups allow the user to select/deselect all of
3642 the components within a single group via a single group-level option.
3643 Use component groups to reduce the complexity of installers with many
3644 options. groupname is an arbitrary name used to identify the group in
3645 the GROUP argument of the cpack_add_component command, which is used to
3646 place a component in a group. The name of the group must not conflict
3647 with the name of any component.
3648 DISPLAY_NAME is the displayed name of the component group, used in
3650 graphical installers to display the component group name. This value
3651 can be any string.
3652 DESCRIPTION is an extended description of the component group, used in
3654 graphical installers to give the user additional information about the
3655 components within that group. Descriptions can span multiple lines us‐
3656 ing \n as the line separator. Typically, these descriptions should be
3657 no more than a few lines long.
3658 PARENT_GROUP, if supplied, names the parent group of this group. Par‐
3660 ent groups are used to establish a hierarchy of groups, providing an
3661 arbitrary hierarchy of groups.
3662 EXPANDED indicates that, by default, the group should show up as "ex‐
3664 panded", so that the user immediately sees all of the components within
3665 the group. Otherwise, the group will initially show up as a single en‐
3666 try.
3667 BOLD_TITLE indicates that the group title should appear in bold, to
3669 call the user's attention to the group.
3670 Add installation type
3672 cpack_add_install_type
3673 Add a new installation type containing a set of predefined component
3675 selections to the graphical installer.
3676 cpack_add_install_type(typename
3678 [DISPLAY_NAME name])
3679 The cpack_add_install_type command identifies a set of preselected com‐
3681 ponents that represents a common use case for an application. For ex‐
3682 ample, a "Developer" install type might include an application along
3683 with its header and library files, while an "End user" install type
3684 might just include the application's executable. Each component iden‐
3685 tifies itself with one or more install types via the INSTALL_TYPES ar‐
3686 gument to cpack_add_component.
3687 DISPLAY_NAME is the displayed name of the install type, which will typ‐
3689 ically show up in a drop-down box within a graphical installer. This
3690 value can be any string.
3691 Configure downloads
3693 cpack_configure_downloads
3694 Configure CPack to download selected components on-the-fly as part of
3696 the installation process.
3697 cpack_configure_downloads(site
3699 [UPLOAD_DIRECTORY dirname]
3700 [ALL]
3701 [ADD_REMOVE|NO_ADD_REMOVE])
3702 The cpack_configure_downloads command configures installation-time
3704 downloads of selected components. For each downloadable component,
3705 CPack will create an archive containing the contents of that component,
3706 which should be uploaded to the given site. When the user selects that
3707 component for installation, the installer will download and extract the
3708 component in place. This feature is useful for creating small install‐
3709 ers that only download the requested components, saving bandwidth. Ad‐
3710 ditionally, the installers are small enough that they will be installed
3711 as part of the normal installation process, and the "Change" button in
3712 Windows Add/Remove Programs control panel will allow one to add or re‐
3713 move parts of the application after the original installation. On Win‐
3714 dows, the downloaded-components functionality requires the ZipDLL
3715 plug-in for NSIS, available at:
3716 http://nsis.sourceforge.net/ZipDLL_plug-in
3718 On macOS, installers that download components on-the-fly can only be
3720 built and installed on system using macOS 10.5 or later.
3721 The site argument is a URL where the archives for downloadable compo‐
3723 nents will reside, e.g., https://cmake.org/files/v3.25/ All of the ar‐
3724 chives produced by CPack should be uploaded to that location.
3725 UPLOAD_DIRECTORY is the local directory where CPack will create the
3727 various archives for each of the components. The contents of this di‐
3728 rectory should be uploaded to a location accessible by the URL given in
3729 the site argument. If omitted, CPack will use the directory CPackU‐
3730 ploads inside the CMake binary directory to store the generated ar‐
3731 chives.
3732 The ALL flag indicates that all components be downloaded. Otherwise,
3734 only those components explicitly marked as DOWNLOADED or that have a
3735 specified ARCHIVE_FILE will be downloaded. Additionally, the ALL op‐
3736 tion implies ADD_REMOVE (unless NO_ADD_REMOVE is specified).
3737 ADD_REMOVE indicates that CPack should install a copy of the installer
3739 that can be called from Windows' Add/Remove Programs dialog (via the
3740 "Modify" button) to change the set of installed components. NO_ADD_RE‐
3741 MOVE turns off this behavior. This option is ignored on Mac OS X.
3742 CPackIFW
3744 New in version 3.1.
3745 This module looks for the location of the command-line utilities sup‐
3748 plied with the Qt Installer Framework (QtIFW).
3749 The module also defines several commands to control the behavior of the
3751 CPack IFW Generator.
3752 Commands
3754 The module defines the following commands:
3755 cpack_ifw_configure_component
3757 Sets the arguments specific to the CPack IFW generator.
3758 cpack_ifw_configure_component(<compname> [COMMON] [ESSENTIAL] [VIRTUAL]
3760 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
3761 [NAME <name>]
3762 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
3763 [DESCRIPTION <description>] # Note: Internationalization supported
3764 [UPDATE_TEXT <update_text>]
3765 [VERSION <version>]
3766 [RELEASE_DATE <release_date>]
3767 [SCRIPT <script>]
3768 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
3769 [DEPENDS|DEPENDENCIES <com_id> ...]
3770 [AUTO_DEPEND_ON <comp_id> ...]
3771 [LICENSES <display_name> <file_path> ...]
3772 [DEFAULT <value>]
3773 [USER_INTERFACES <file_path> <file_path> ...]
3774 [TRANSLATIONS <file_path> <file_path> ...]
3775 [REPLACES <comp_id> ...]
3776 [CHECKABLE <value>])
3777 This command should be called after cpack_add_component() com‐
3779 mand.
3780 COMMON if set, then the component will be packaged and installed
3782 as part of a group to which it belongs.
3783 ESSENTIAL
3785 New in version 3.6.
3786 if set, then the package manager stays disabled until
3789 that component is updated.
3790 VIRTUAL
3792 New in version 3.8.
3793 if set, then the component will be hidden from the in‐
3796 staller. It is a equivalent of the HIDDEN option from
3797 the cpack_add_component() command.
3798 FORCED_INSTALLATION
3800 New in version 3.8.
3801 if set, then the component must always be installed. It
3804 is a equivalent of the REQUIRED option from the
3805 cpack_add_component() command.
3806 REQUIRES_ADMIN_RIGHTS
3808 New in version 3.8.
3809 set it if the component needs to be installed with ele‐
3812 vated permissions.
3813 NAME is used to create domain-like identification for this
3815 component. By default used origin component name.
3816 DISPLAY_NAME
3818 New in version 3.8.
3819 set to rewrite original name configured by
3822 cpack_add_component() command.
3823 DESCRIPTION
3825 New in version 3.8.
3826 set to rewrite original description configured by
3829 cpack_add_component() command.
3830 UPDATE_TEXT
3832 New in version 3.8.
3833 will be added to the component description if this is an
3836 update to the component.
3837 VERSION
3839 is version of component. By default used
3840 CPACK_PACKAGE_VERSION.
3841 RELEASE_DATE
3843 New in version 3.8.
3844 keep empty to auto generate.
3847 SCRIPT is a relative or absolute path to operations script for
3849 this component.
3850 SORTING_PRIORITY
3852 New in version 3.8.
3853 is priority of the component in the tree.
3856 PRIORITY
3858 Deprecated since version 3.8: Old name for SORTING_PRIOR‐
3859 ITY.
3860 DEPENDS, DEPENDENCIES
3863 New in version 3.8.
3864 list of dependency component or component group identi‐
3867 fiers in QtIFW style.
3868 New in version 3.21.
3870 Component or group names listed as dependencies may con‐
3873 tain hyphens. This requires QtIFW 3.1 or later.
3874 AUTO_DEPEND_ON
3876 New in version 3.8.
3877 list of identifiers of component or component group in
3880 QtIFW style that this component has an automatic depen‐
3881 dency on.
3882 LICENSES
3884 pair of <display_name> and <file_path> of license text
3885 for this component. You can specify more then one li‐
3886 cense.
3887 DEFAULT
3889 New in version 3.8.
3890 Possible values are: TRUE, FALSE, and SCRIPT. Set to
3893 FALSE to disable the component in the installer or to
3894 SCRIPT to resolved during runtime (don't forget add the
3895 file of the script as a value of the SCRIPT option).
3896 USER_INTERFACES
3898 New in version 3.7.
3899 is a list of <file_path> ('.ui' files) representing pages
3902 to load.
3903 TRANSLATIONS
3905 New in version 3.8.
3906 is a list of <file_path> ('.qm' files) representing
3909 translations to load.
3910 REPLACES
3912 New in version 3.10.
3913 list of identifiers of component or component group to
3916 replace.
3917 CHECKABLE
3919 New in version 3.10.
3920 Possible values are: TRUE, FALSE. Set to FALSE if you
3923 want to hide the checkbox for an item. This is useful
3924 when only a few subcomponents should be selected instead
3925 of all.
3926 cpack_ifw_configure_component_group
3928 Sets the arguments specific to the CPack IFW generator.
3929 cpack_ifw_configure_component_group(<groupname> [VIRTUAL]
3931 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
3932 [NAME <name>]
3933 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
3934 [DESCRIPTION <description>] # Note: Internationalization supported
3935 [UPDATE_TEXT <update_text>]
3936 [VERSION <version>]
3937 [RELEASE_DATE <release_date>]
3938 [SCRIPT <script>]
3939 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
3940 [DEPENDS|DEPENDENCIES <com_id> ...]
3941 [AUTO_DEPEND_ON <comp_id> ...]
3942 [LICENSES <display_name> <file_path> ...]
3943 [DEFAULT <value>]
3944 [USER_INTERFACES <file_path> <file_path> ...]
3945 [TRANSLATIONS <file_path> <file_path> ...]
3946 [REPLACES <comp_id> ...]
3947 [CHECKABLE <value>])
3948 This command should be called after cpack_add_component_group()
3950 command.
3951 VIRTUAL
3953 New in version 3.8.
3954 if set, then the group will be hidden from the installer.
3957 Note that setting this on a root component does not work.
3958 FORCED_INSTALLATION
3960 New in version 3.8.
3961 if set, then the group must always be installed.
3964 REQUIRES_ADMIN_RIGHTS
3966 New in version 3.8.
3967 set it if the component group needs to be installed with
3970 elevated permissions.
3971 NAME is used to create domain-like identification for this
3973 component group. By default used origin component group
3974 name.
3975 DISPLAY_NAME
3977 New in version 3.8.
3978 set to rewrite original name configured by
3981 cpack_add_component_group() command.
3982 DESCRIPTION
3984 New in version 3.8.
3985 set to rewrite original description configured by
3988 cpack_add_component_group() command.
3989 UPDATE_TEXT
3991 New in version 3.8.
3992 will be added to the component group description if this
3995 is an update to the component group.
3996 VERSION
3998 is version of component group. By default used
3999 CPACK_PACKAGE_VERSION.
4000 RELEASE_DATE
4002 New in version 3.8.
4003 keep empty to auto generate.
4006 SCRIPT is a relative or absolute path to operations script for
4008 this component group.
4009 SORTING_PRIORITY
4011 is priority of the component group in the tree.
4012 PRIORITY
4014 Deprecated since version 3.8: Old name for SORTING_PRIOR‐
4015 ITY.
4016 DEPENDS, DEPENDENCIES
4019 New in version 3.8.
4020 list of dependency component or component group identi‐
4023 fiers in QtIFW style.
4024 New in version 3.21.
4026 Component or group names listed as dependencies may con‐
4029 tain hyphens. This requires QtIFW 3.1 or later.
4030 AUTO_DEPEND_ON
4032 New in version 3.8.
4033 list of identifiers of component or component group in
4036 QtIFW style that this component group has an automatic
4037 dependency on.
4038 LICENSES
4040 pair of <display_name> and <file_path> of license text
4041 for this component group. You can specify more then one
4042 license.
4043 DEFAULT
4045 New in version 3.8.
4046 Possible values are: TRUE, FALSE, and SCRIPT. Set to
4049 TRUE to preselect the group in the installer (this takes
4050 effect only on groups that have no visible child compo‐
4051 nents) or to SCRIPT to resolved during runtime (don't
4052 forget add the file of the script as a value of the
4053 SCRIPT option).
4054 USER_INTERFACES
4056 New in version 3.7.
4057 is a list of <file_path> ('.ui' files) representing pages
4060 to load.
4061 TRANSLATIONS
4063 New in version 3.8.
4064 is a list of <file_path> ('.qm' files) representing
4067 translations to load.
4068 REPLACES
4070 New in version 3.10.
4071 list of identifiers of component or component group to
4074 replace.
4075 CHECKABLE
4077 New in version 3.10.
4078 Possible values are: TRUE, FALSE. Set to FALSE if you
4081 want to hide the checkbox for an item. This is useful
4082 when only a few subcomponents should be selected instead
4083 of all.
4084 cpack_ifw_add_repository
4086 Add QtIFW specific remote repository to binary installer.
4087 cpack_ifw_add_repository(<reponame> [DISABLED]
4089 URL <url>
4090 [USERNAME <username>]
4091 [PASSWORD <password>]
4092 [DISPLAY_NAME <display_name>])
4093 This command will also add the <reponame> repository to a vari‐
4095 able CPACK_IFW_REPOSITORIES_ALL.
4096 DISABLED
4098 if set, then the repository will be disabled by default.
4099 URL is points to a list of available components.
4101 USERNAME
4103 is used as user on a protected repository.
4104 PASSWORD
4106 is password to use on a protected repository.
4107 DISPLAY_NAME
4109 is string to display instead of the URL.
4110 cpack_ifw_update_repository
4112 New in version 3.6.
4113 Update QtIFW specific repository from remote repository.
4116 cpack_ifw_update_repository(<reponame>
4118 [[ADD|REMOVE] URL <url>]|
4119 [REPLACE OLD_URL <old_url> NEW_URL <new_url>]]
4120 [USERNAME <username>]
4121 [PASSWORD <password>]
4122 [DISPLAY_NAME <display_name>])
4123 This command will also add the <reponame> repository to a vari‐
4125 able CPACK_IFW_REPOSITORIES_ALL.
4126 URL is points to a list of available components.
4128 OLD_URL
4130 is points to a list that will replaced.
4131 NEW_URL
4133 is points to a list that will replace to.
4134 USERNAME
4136 is used as user on a protected repository.
4137 PASSWORD
4139 is password to use on a protected repository.
4140 DISPLAY_NAME
4142 is string to display instead of the URL.
4143 cpack_ifw_add_package_resources
4145 New in version 3.7.
4146 Add additional resources in the installer binary.
4149 cpack_ifw_add_package_resources(<file_path> <file_path> ...)
4151 This command will also add the specified files to a variable
4153 CPACK_IFW_PACKAGE_RESOURCES.
4154 CPackIFWConfigureFile
4156 New in version 3.8.
4157 The module defines configure_file() similar command to configure file
4160 templates prepared in QtIFW/SDK/Creator style.
4161 Commands
4163 The module defines the following commands:
4164 cpack_ifw_configure_file
4166 Copy a file to another location and modify its contents.
4167 cpack_ifw_configure_file(<input> <output>)
4169 Copies an <input> file to an <output> file and substitutes vari‐
4171 able values referenced as %{VAR} or %VAR% in the input file con‐
4172 tent. Each variable reference will be replaced with the current
4173 value of the variable, or the empty string if the variable is
4174 not defined.
4175 CSharpUtilities
4177 New in version 3.8.
4178 Functions to make configuration of CSharp/.NET targets easier.
4181 A collection of CMake utility functions useful for dealing with CSharp
4183 targets for Visual Studio generators from version 2010 and later.
4184 The following functions are provided by this module:
4186 Main functions
4188 • csharp_set_windows_forms_properties()
4190 • csharp_set_designer_cs_properties()
4192 • csharp_set_xaml_cs_properties()
4194 Helper functions
4196 • csharp_get_filename_keys()
4198 • csharp_get_filename_key_base()
4200 • csharp_get_dependentupon_name()
4202 Main functions provided by the module
4204 csharp_set_windows_forms_properties
4205 Sets source file properties for use of Windows Forms. Use this,
4206 if your CSharp target uses Windows Forms:
4207 csharp_set_windows_forms_properties([<file1> [<file2> [...]]])
4209 <fileN>
4211 List of all source files which are relevant for setting
4212 the VS_CSHARP_<tagname> properties (including .cs, .resx
4213 and .Designer.cs extensions).
4214 In the list of all given files for all files ending with .De‐
4216 signer.cs and .resx is searched. For every designer or resource
4217 file a file with the same base name but only .cs as extension is
4218 searched. If this is found, the VS_CSHARP_<tagname> properties
4219 are set as follows:
4220 for the .cs file:
4222 • VS_CSHARP_SubType "Form"
4224 for the .Designer.cs file (if it exists):
4226 • VS_CSHARP_DependentUpon <cs-filename>
4228 • VS_CSHARP_DesignTime "" (delete tag if previously de‐
4230 fined)
4231 • VS_CSHARP_AutoGen ""(delete tag if previously defined)
4233 for the .resx file (if it exists):
4235 • VS_RESOURCE_GENERATOR "" (delete tag if previously de‐
4237 fined)
4238 • VS_CSHARP_DependentUpon <cs-filename>
4240 • VS_CSHARP_SubType "Designer"
4242 csharp_set_designer_cs_properties
4244 Sets source file properties of .Designer.cs files depending on
4245 sibling filenames. Use this, if your CSharp target does not use
4246 Windows Forms (for Windows Forms use
4247 csharp_set_designer_cs_properties() instead):
4248 csharp_set_designer_cs_properties([<file1> [<file2> [...]]])
4250 <fileN>
4252 List of all source files which are relevant for setting
4253 the VS_CSHARP_<tagname> properties (including .cs, .resx,
4254 .settings and .Designer.cs extensions).
4255 In the list of all given files for all files ending with .De‐
4257 signer.cs is searched. For every designer file all files with
4258 the same base name but different extensions are searched. If a
4259 match is found, the source file properties of the designer file
4260 are set depending on the extension of the matched file:
4261 if match is .resx file:
4263 • VS_CSHARP_AutoGen "True"
4265 • VS_CSHARP_DesignTime "True"
4267 • VS_CSHARP_DependentUpon <resx-filename>
4269 if match is .cs file:
4271 • VS_CSHARP_DependentUpon <cs-filename>
4273 if match is .settings file:
4275 • VS_CSHARP_AutoGen "True"
4277 • VS_CSHARP_DesignTimeSharedInput "True"
4279 • VS_CSHARP_DependentUpon <settings-filename>
4281 NOTE:
4283 Because the source file properties of the .Designer.cs file are set
4284 according to the found matches and every match sets the
4285 VS_CSHARP_DependentUpon property, there should only be one match for
4286 each Designer.cs file.
4287 csharp_set_xaml_cs_properties
4289 Sets source file properties for use of Windows Presentation
4290 Foundation (WPF) and XAML. Use this, if your CSharp target uses
4291 WPF/XAML:
4292 csharp_set_xaml_cs_properties([<file1> [<file2> [...]]])
4294 <fileN>
4296 List of all source files which are relevant for setting
4297 the VS_CSHARP_<tagname> properties (including .cs, .xaml,
4298 and .xaml.cs extensions).
4299 In the list of all given files for all files ending with
4301 .xaml.cs is searched. For every xaml-cs file, a file with the
4302 same base name but extension .xaml is searched. If a match is
4303 found, the source file properties of the .xaml.cs file are set:
4304 • VS_CSHARP_DependentUpon <xaml-filename>
4306 Helper functions which are used by the above ones
4308 csharp_get_filename_keys
4309 Helper function which computes a list of key values to identify
4310 source files independently of relative/absolute paths given in
4311 cmake and eliminates case sensitivity:
4312 csharp_get_filename_keys(OUT [<file1> [<file2> [...]]])
4314 OUT Name of the variable in which the list of keys is stored
4316 <fileN>
4318 filename(s) as given to to CSharp target using
4319 add_library() or add_executable()
4320 In some way the function applies a canonicalization to the
4322 source names. This is necessary to find file matches if the
4323 files have been added to the target with different directory
4324 prefixes:
4325 add_library(lib
4327 myfile.cs
4328 ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs)
4329 set_source_files_properties(myfile.Designer.cs PROPERTIES
4331 VS_CSHARP_DependentUpon myfile.cs)
4332 # this will fail, because in cmake
4334 # - ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs
4335 # - myfile.Designer.cs
4336 # are not the same source file. The source file property is not set.
4337 csharp_get_filename_key_base
4339 Returns the full filepath and name without extension of a key.
4340 KEY is expected to be a key from csharp_get_filename_keys. In
4341 BASE the value of KEY without the file extension is returned:
4342 csharp_get_filename_key_base(BASE KEY)
4344 BASE Name of the variable with the computed "base" of KEY.
4346 KEY The key of which the base will be computed. Expected to
4348 be a upper case full filename.
4349 csharp_get_dependentupon_name
4351 Computes a string which can be used as value for the source file
4352 property VS_CSHARP_<tagname> with target being DependentUpon:
4353 csharp_get_dependentupon_name(NAME FILE)
4355 NAME Name of the variable with the result value
4357 FILE Filename to convert to <DependentUpon> value
4359 Actually this is only the filename without any path given at the
4361 moment.
4362 CTest
4364 Configure a project for testing with CTest/CDash
4365 Include this module in the top CMakeLists.txt file of a project to en‐
4367 able testing with CTest and dashboard submissions to CDash:
4368 project(MyProject)
4370 ...
4371 include(CTest)
4372 The module automatically creates a BUILD_TESTING option that selects
4374 whether to enable testing support (ON by default). After including the
4375 module, use code like:
4376 if(BUILD_TESTING)
4378 # ... CMake code to create tests ...
4379 endif()
4380 to creating tests when testing is enabled.
4382 To enable submissions to a CDash server, create a CTestConfig.cmake
4384 file at the top of the project with content such as:
4385 set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
4387 set(CTEST_SUBMIT_URL "http://my.cdash.org/submit.php?project=MyProject")
4388 (the CDash server can provide the file to a project administrator who
4390 configures MyProject). Settings in the config file are shared by both
4391 this CTest module and the ctest(1) command-line Dashboard Client mode
4392 (ctest -S).
4393 While building a project for submission to CDash, CTest scans the build
4395 output for errors and warnings and reports them with surrounding con‐
4396 text from the build log. This generic approach works for all build
4397 tools, but does not give details about the command invocation that pro‐
4398 duced a given problem. One may get more detailed reports by setting
4399 the CTEST_USE_LAUNCHERS variable:
4400 set(CTEST_USE_LAUNCHERS 1)
4402 in the CTestConfig.cmake file.
4404 CTestCoverageCollectGCOV
4406 New in version 3.2.
4407 This module provides the ctest_coverage_collect_gcov function.
4410 This function runs gcov on all .gcda files found in the binary tree and
4412 packages the resulting .gcov files into a tar file. This tarball also
4413 contains the following:
4414 • data.json defines the source and build directories for use by CDash.
4416 • Labels.json indicates any LABELS that have been set on the source
4418 files.
4419 • The uncovered directory holds any uncovered files found by
4421 CTEST_EXTRA_COVERAGE_GLOB.
4422 After generating this tar file, it can be sent to CDash for display
4424 with the ctest_submit(CDASH_UPLOAD) command.
4425 ctest_coverage_collect_gcov
4427 ctest_coverage_collect_gcov(TARBALL <tarfile>
4429 [SOURCE <source_dir>][BUILD <build_dir>]
4430 [GCOV_COMMAND <gcov_command>]
4431 [GCOV_OPTIONS <options>...]
4432 )
4433 Run gcov and package a tar file for CDash. The options are:
4435 TARBALL <tarfile>
4437 Specify the location of the .tar file to be created for
4438 later upload to CDash. Relative paths will be inter‐
4439 preted with respect to the top-level build directory.
4440 TARBALL_COMPRESSION <option>
4442 New in version 3.18.
4443 Specify a compression algorithm for the TARBALL data
4446 file. Using this option reduces the size of the data
4447 file before it is submitted to CDash. <option> must be
4448 one of GZIP, BZIP2, XZ, ZSTD, FROM_EXT, or an expression
4449 that CMake evaluates as FALSE. The default value is
4450 BZIP2.
4451 If FROM_EXT is specified, the resulting file will be com‐
4453 pressed based on the file extension of the <tarfile>
4454 (i.e. .tar.gz will use GZIP compression). File extensions
4455 that will produce compressed output include .tar.gz,
4456 .tgz, .tar.bzip2, .tbz, .tar.xz, and .txz.
4457 SOURCE <source_dir>
4459 Specify the top-level source directory for the build.
4460 Default is the value of CTEST_SOURCE_DIRECTORY.
4461 BUILD <build_dir>
4463 Specify the top-level build directory for the build. De‐
4464 fault is the value of CTEST_BINARY_DIRECTORY.
4465 GCOV_COMMAND <gcov_command>
4467 Specify the full path to the gcov command on the machine.
4468 Default is the value of CTEST_COVERAGE_COMMAND.
4469 GCOV_OPTIONS <options>...
4471 Specify options to be passed to gcov. The gcov command
4472 is run as gcov <options>... -o <gcov-dir> <file>.gcda.
4473 If not specified, the default option is just -b -x.
4474 GLOB New in version 3.6.
4476 Recursively search for .gcda files in build_dir rather
4479 than determining search locations by reading TargetDirec‐
4480 tories.txt.
4481 DELETE New in version 3.6.
4483 Delete coverage files after they've been packaged into
4486 the .tar.
4487 QUIET Suppress non-error messages that otherwise would have
4489 been printed out by this function.
4490 New in version 3.3: Added support for the
4492 CTEST_CUSTOM_COVERAGE_EXCLUDE variable.
4493 CTestScriptMode
4496 This file is read by ctest in script mode (-S)
4497 CTestUseLaunchers
4499 Set the RULE_LAUNCH_* global properties when CTEST_USE_LAUNCHERS is on.
4500 CTestUseLaunchers is automatically included when you include(CTest).
4502 However, it is split out into its own module file so projects can use
4503 the CTEST_USE_LAUNCHERS functionality independently.
4504 To use launchers, set CTEST_USE_LAUNCHERS to ON in a ctest -S dashboard
4506 script, and then also set it in the cache of the configured project.
4507 Both cmake and ctest need to know the value of it for the launchers to
4508 work properly. CMake needs to know in order to generate proper build
4509 rules, and ctest, in order to produce the proper error and warning
4510 analysis.
4511 For convenience, you may set the ENV variable CTEST_USE_LAUNCHERS_DE‐
4513 FAULT in your ctest -S script, too. Then, as long as your CMakeLists
4514 uses include(CTest) or include(CTestUseLaunchers), it will use the
4515 value of the ENV variable to initialize a CTEST_USE_LAUNCHERS cache
4516 variable. This cache variable initialization only occurs if
4517 CTEST_USE_LAUNCHERS is not already defined.
4518 New in version 3.8: If CTEST_USE_LAUNCHERS is on in a ctest -S script
4520 the ctest_configure command will add -DCTEST_USE_LAUNCHERS:BOOL=TRUE to
4521 the cmake command used to configure the project.
4522 Dart
4525 Deprecated since version 3.27: This module is available only if policy
4526 CMP0145 is not set to NEW. Do not use it in new code. Use the CTest
4527 module instead.
4528 Configure a project for testing with CTest or old Dart Tcl Client
4531 This file is the backwards-compatibility version of the CTest module.
4533 It supports using the old Dart 1 Tcl client for driving dashboard sub‐
4534 missions as well as testing with CTest. This module should be included
4535 in the CMakeLists.txt file at the top of a project. Typical usage:
4536 include(Dart)
4538 if(BUILD_TESTING)
4539 # ... testing related CMake code ...
4540 endif()
4541 The BUILD_TESTING option is created by the Dart module to determine
4543 whether testing support should be enabled. The default is ON.
4544 DeployQt4
4546 Functions to help assemble a standalone Qt4 executable.
4547 A collection of CMake utility functions useful for deploying Qt4 exe‐
4549 cutables.
4550 The following functions are provided by this module:
4552 write_qt4_conf
4554 resolve_qt4_paths
4555 fixup_qt4_executable
4556 install_qt4_plugin_path
4557 install_qt4_plugin
4558 install_qt4_executable
4559 Requires CMake 2.6 or greater because it uses function and PAR‐
4561 ENT_SCOPE. Also depends on BundleUtilities.cmake.
4562 write_qt4_conf(<qt_conf_dir> <qt_conf_contents>)
4564 Writes a qt.conf file with the <qt_conf_contents> into <qt_conf_dir>.
4566 resolve_qt4_paths(<paths_var> [<executable_path>])
4568 Loop through <paths_var> list and if any don't exist resolve them rela‐
4570 tive to the <executable_path> (if supplied) or the CMAKE_INSTALL_PRE‐
4571 FIX.
4572 fixup_qt4_executable(<executable>
4574 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>])
4575 Copies Qt plugins, writes a Qt configuration file (if needed) and fixes
4577 up a Qt4 executable using BundleUtilities so it is standalone and can
4578 be drag-and-drop copied to another machine as long as all of the system
4579 libraries are compatible.
4580 <executable> should point to the executable to be fixed-up.
4582 <qtplugins> should contain a list of the names or paths of any Qt plug‐
4584 ins to be installed.
4585 <libs> will be passed to BundleUtilities and should be a list of any
4587 already installed plugins, libraries or executables to also be
4588 fixed-up.
4589 <dirs> will be passed to BundleUtilities and should contain and direc‐
4591 tories to be searched to find library dependencies.
4592 <plugins_dir> allows an custom plugins directory to be used.
4594 <request_qt_conf> will force a qt.conf file to be written even if not
4596 needed.
4597 install_qt4_plugin_path(plugin executable copy installed_plugin_path_var
4599 <plugins_dir> <component> <configurations>)
4600 Install (or copy) a resolved <plugin> to the default plugins directory
4602 (or <plugins_dir>) relative to <executable> and store the result in
4603 <installed_plugin_path_var>.
4604 If <copy> is set to TRUE then the plugins will be copied rather than
4606 installed. This is to allow this module to be used at CMake time
4607 rather than install time.
4608 If <component> is set then anything installed will use this COMPONENT.
4610 install_qt4_plugin(plugin executable copy installed_plugin_path_var
4612 <plugins_dir> <component>)
4613 Install (or copy) an unresolved <plugin> to the default plugins direc‐
4615 tory (or <plugins_dir>) relative to <executable> and store the result
4616 in <installed_plugin_path_var>. See documentation of IN‐
4617 STALL_QT4_PLUGIN_PATH.
4618 install_qt4_executable(<executable>
4620 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>])
4621 Installs Qt plugins, writes a Qt configuration file (if needed) and
4623 fixes up a Qt4 executable using BundleUtilities so it is standalone and
4624 can be drag-and-drop copied to another machine as long as all of the
4625 system libraries are compatible. The executable will be fixed-up at
4626 install time. <component> is the COMPONENT used for bundle fixup and
4627 plugin installation. See documentation of FIXUP_QT4_BUNDLE.
4628 ExternalData
4630 Manage data files stored outside source tree
4631 Introduction
4633 Use this module to unambiguously reference data files stored outside
4634 the source tree and fetch them at build time from arbitrary local and
4635 remote content-addressed locations. Functions provided by this module
4636 recognize arguments with the syntax DATA{<name>} as references to ex‐
4637 ternal data, replace them with full paths to local copies of those
4638 data, and create build rules to fetch and update the local copies.
4639 For example:
4641 include(ExternalData)
4643 set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
4644 "file:////host/share/%(algo)/%(hash)"
4645 "http://data.org/%(algo)/%(hash)")
4646 ExternalData_Add_Test(MyData
4647 NAME MyTest
4648 COMMAND MyExe DATA{MyInput.png}
4649 )
4650 ExternalData_Add_Target(MyData)
4651 When test MyTest runs the DATA{MyInput.png} argument will be replaced
4653 by the full path to a real instance of the data file MyInput.png on
4654 disk. If the source tree contains a content link such as MyIn‐
4655 put.png.md5 then the MyData target creates a real MyInput.png in the
4656 build tree.
4657 Module Functions
4659 ExternalData_Expand_Arguments
4660 The ExternalData_Expand_Arguments function evaluates DATA{} ref‐
4661 erences in its arguments and constructs a new list of arguments:
4662 ExternalData_Expand_Arguments(
4664 <target> # Name of data management target
4665 <outVar> # Output variable
4666 [args...] # Input arguments, DATA{} allowed
4667 )
4668 It replaces each DATA{} reference in an argument with the full
4670 path of a real data file on disk that will exist after the <tar‐
4671 get> builds.
4672 ExternalData_Add_Test
4674 The ExternalData_Add_Test function wraps around the CMake
4675 add_test() command but supports DATA{} references in its argu‐
4676 ments:
4677 ExternalData_Add_Test(
4679 <target> # Name of data management target
4680 ... # Arguments of add_test(), DATA{} allowed
4681 )
4682 It passes its arguments through ExternalData_Expand_Arguments
4684 and then invokes the add_test() command using the results.
4685 ExternalData_Add_Target
4687 The ExternalData_Add_Target function creates a custom target to
4688 manage local instances of data files stored externally:
4689 ExternalData_Add_Target(
4691 <target> # Name of data management target
4692 [SHOW_PROGRESS <ON|OFF>] # Show progress during the download
4693 )
4694 It creates custom commands in the target as necessary to make
4696 data files available for each DATA{} reference previously evalu‐
4697 ated by other functions provided by this module. Data files may
4698 be fetched from one of the URL templates specified in the Exter‐
4699 nalData_URL_TEMPLATES variable, or may be found locally in one
4700 of the paths specified in the ExternalData_OBJECT_STORES vari‐
4701 able.
4702 New in version 3.20: The SHOW_PROGRESS argument may be passed to
4704 suppress progress information during the download of objects. If
4705 not provided, it defaults to OFF for Ninja and Ninja Multi-Con‐
4706 fig generators and ON otherwise.
4707 Typically only one target is needed to manage all external data
4710 within a project. Call this function once at the end of config‐
4711 uration after all data references have been processed.
4712 Module Variables
4714 The following variables configure behavior. They should be set before
4715 calling any of the functions provided by this module.
4716 ExternalData_BINARY_ROOT
4718 The ExternalData_BINARY_ROOT variable may be set to the direc‐
4719 tory to hold the real data files named by expanded DATA{} refer‐
4720 ences. The default is CMAKE_BINARY_DIR. The directory layout
4721 will mirror that of content links under External‐
4722 Data_SOURCE_ROOT.
4723 ExternalData_CUSTOM_SCRIPT_<key>
4725 New in version 3.2.
4726 Specify a full path to a .cmake custom fetch script identified
4729 by <key> in entries of the ExternalData_URL_TEMPLATES list. See
4730 Custom Fetch Scripts.
4731 ExternalData_LINK_CONTENT
4733 The ExternalData_LINK_CONTENT variable may be set to the name of
4734 a supported hash algorithm to enable automatic conversion of
4735 real data files referenced by the DATA{} syntax into content
4736 links. For each such <file> a content link named <file><ext> is
4737 created. The original file is renamed to the form .External‐
4738 Data_<algo>_<hash> to stage it for future transmission to one of
4739 the locations in the list of URL templates (by means outside the
4740 scope of this module). The data fetch rule created for the con‐
4741 tent link will use the staged object if it cannot be found using
4742 any URL template.
4743 ExternalData_NO_SYMLINKS
4745 New in version 3.3.
4746 The real data files named by expanded DATA{} references may be
4749 made available under ExternalData_BINARY_ROOT using symbolic
4750 links on some platforms. The ExternalData_NO_SYMLINKS variable
4751 may be set to disable use of symbolic links and enable use of
4752 copies instead.
4753 ExternalData_OBJECT_STORES
4755 The ExternalData_OBJECT_STORES variable may be set to a list of
4756 local directories that store objects using the layout
4757 <dir>/%(algo)/%(hash). These directories will be searched first
4758 for a needed object. If the object is not available in any
4759 store then it will be fetched remotely using the URL templates
4760 and added to the first local store listed. If no stores are
4761 specified the default is a location inside the build tree.
4762 ExternalData_SERIES_PARSE
4764 ExternalData_SERIES_PARSE_PREFIX
4766 ExternalData_SERIES_PARSE_NUMBER
4768 ExternalData_SERIES_PARSE_SUFFIX
4770 ExternalData_SERIES_MATCH
4772 See Referencing File Series.
4773 ExternalData_SOURCE_ROOT
4775 The ExternalData_SOURCE_ROOT variable may be set to the highest
4776 source directory containing any path named by a DATA{} refer‐
4777 ence. The default is CMAKE_SOURCE_DIR. External‐
4778 Data_SOURCE_ROOT and CMAKE_SOURCE_DIR must refer to directories
4779 within a single source distribution (e.g. they come together in
4780 one tarball).
4781 ExternalData_TIMEOUT_ABSOLUTE
4783 The ExternalData_TIMEOUT_ABSOLUTE variable sets the download ab‐
4784 solute timeout, in seconds, with a default of 300 seconds. Set
4785 to 0 to disable enforcement.
4786 ExternalData_TIMEOUT_INACTIVITY
4788 The ExternalData_TIMEOUT_INACTIVITY variable sets the download
4789 inactivity timeout, in seconds, with a default of 60 seconds.
4790 Set to 0 to disable enforcement.
4791 ExternalData_URL_ALGO_<algo>_<key>
4793 New in version 3.3.
4794 Specify a custom URL component to be substituted for URL tem‐
4797 plate placeholders of the form %(algo:<key>), where <key> is a
4798 valid C identifier, when fetching an object referenced via hash
4799 algorithm <algo>. If not defined, the default URL component is
4800 just <algo> for any <key>.
4801 ExternalData_URL_TEMPLATES
4803 The ExternalData_URL_TEMPLATES may be set to provide a list of
4804 URL templates using the placeholders %(algo) and %(hash) in each
4805 template. Data fetch rules try each URL template in order by
4806 substituting the hash algorithm name for %(algo) and the hash
4807 value for %(hash). Alternatively one may use %(algo:<key>) with
4808 ExternalData_URL_ALGO_<algo>_<key> variables to gain more flexi‐
4809 bility in remote URLs.
4810 Referencing Files
4812 Referencing Single Files
4813 The DATA{} syntax is literal and the <name> is a full or relative path
4814 within the source tree. The source tree must contain either a real
4815 data file at <name> or a "content link" at <name><ext> containing a
4816 hash of the real file using a hash algorithm corresponding to <ext>.
4817 For example, the argument DATA{img.png} may be satisfied by either a
4818 real img.png file in the current source directory or a img.png.md5 file
4819 containing its MD5 sum.
4820 New in version 3.8: Multiple content links of the same name with dif‐
4822 ferent hash algorithms are supported (e.g. img.png.sha256 and
4823 img.png.sha1) so long as they all correspond to the same real file.
4824 This allows objects to be fetched from sources indexed by different
4825 hash algorithms.
4826 Referencing File Series
4829 The DATA{} syntax can be told to fetch a file series using the form
4830 DATA{<name>,:}, where the : is literal. If the source tree contains a
4831 group of files or content links named like a series then a reference to
4832 one member adds rules to fetch all of them. Although all members of a
4833 series are fetched, only the file originally named by the DATA{} argu‐
4834 ment is substituted for it. The default configuration recognizes file
4835 series names ending with #.ext, _#.ext, .#.ext, or -#.ext where # is a
4836 sequence of decimal digits and .ext is any single extension. Configure
4837 it with a regex that parses <number> and <suffix> parts from the end of
4838 <name>:
4839 ExternalData_SERIES_PARSE = regex of the form (<number>)(<suffix>)$
4841 For more complicated cases set:
4843 ExternalData_SERIES_PARSE = regex with at least two () groups
4845 ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
4846 ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
4847 ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number
4848 Configure series number matching with a regex that matches the <number>
4850 part of series members named <prefix><number><suffix>:
4851 ExternalData_SERIES_MATCH = regex matching <number> in all series members
4853 Note that the <suffix> of a series does not include a hash-algorithm
4855 extension.
4856 Referencing Associated Files
4858 The DATA{} syntax can alternatively match files associated with the
4859 named file and contained in the same directory. Associated files may
4860 be specified by options using the syntax
4861 DATA{<name>,<opt1>,<opt2>,...}. Each option may specify one file by
4862 name or specify a regular expression to match file names using the syn‐
4863 tax REGEX:<regex>. For example, the arguments:
4864 DATA{MyData/MyInput.mhd,MyInput.img} # File pair
4866 DATA{MyData/MyFrames00.png,REGEX:MyFrames[0-9]+\\.png} # Series
4867 will pass MyInput.mha and MyFrames00.png on the command line but ensure
4869 that the associated files are present next to them.
4870 Referencing Directories
4872 The DATA{} syntax may reference a directory using a trailing slash and
4873 a list of associated files. The form DATA{<name>/,<opt1>,<opt2>,...}
4874 adds rules to fetch any files in the directory that match one of the
4875 associated file options. For example, the argument DATA{My‐
4876 DataDir/,REGEX:.*} will pass the full path to a MyDataDir directory on
4877 the command line and ensure that the directory contains files corre‐
4878 sponding to every file or content link in the MyDataDir source direc‐
4879 tory.
4880 New in version 3.3: In order to match associated files in subdirecto‐
4882 ries, specify a RECURSE: option, e.g. DATA{MyDataDir/,RE‐
4883 CURSE:,REGEX:.*}.
4884 Hash Algorithms
4887 The following hash algorithms are supported:
4888 %(algo) <ext> Description
4890 ------- ----- -----------
4891 MD5 .md5 Message-Digest Algorithm 5, RFC 1321
4892 SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174
4893 SHA224 .sha224 US Secure Hash Algorithms, RFC 4634
4894 SHA256 .sha256 US Secure Hash Algorithms, RFC 4634
4895 SHA384 .sha384 US Secure Hash Algorithms, RFC 4634
4896 SHA512 .sha512 US Secure Hash Algorithms, RFC 4634
4897 SHA3_224 .sha3-224 Keccak SHA-3
4898 SHA3_256 .sha3-256 Keccak SHA-3
4899 SHA3_384 .sha3-384 Keccak SHA-3
4900 SHA3_512 .sha3-512 Keccak SHA-3
4901 New in version 3.8: Added the SHA3_* hash algorithms.
4903 Note that the hashes are used only for unique data identification and
4906 download verification.
4907 Custom Fetch Scripts
4909 New in version 3.2.
4910 When a data file must be fetched from one of the URL templates speci‐
4913 fied in the ExternalData_URL_TEMPLATES variable, it is normally down‐
4914 loaded using the file(DOWNLOAD) command. One may specify usage of a
4915 custom fetch script by using a URL template of the form ExternalData‐
4916 CustomScript://<key>/<loc>. The <key> must be a C identifier, and the
4917 <loc> must contain the %(algo) and %(hash) placeholders. A variable
4918 corresponding to the key, ExternalData_CUSTOM_SCRIPT_<key>, must be set
4919 to the full path to a .cmake script file. The script will be included
4920 to perform the actual fetch, and provided with the following variables:
4921 ExternalData_CUSTOM_LOCATION
4923 When a custom fetch script is loaded, this variable is set to
4924 the location part of the URL, which will contain the substituted
4925 hash algorithm name and content hash value.
4926 ExternalData_CUSTOM_FILE
4928 When a custom fetch script is loaded, this variable is set to
4929 the full path to a file in which the script must store the
4930 fetched content. The name of the file is unspecified and should
4931 not be interpreted in any way.
4932 The custom fetch script is expected to store fetched content in the
4934 file or set a variable:
4935 ExternalData_CUSTOM_ERROR
4937 When a custom fetch script fails to fetch the requested content,
4938 it must set this variable to a short one-line message describing
4939 the reason for failure.
4940 ExternalProject
4942 Commands
4943 External Project Definition
4944 ExternalProject_Add
4945 The ExternalProject_Add() function creates a custom target to
4946 drive download, update/patch, configure, build, install and test
4947 steps of an external project:
4948 ExternalProject_Add(<name> [<option>...])
4950 The individual steps within the process can be driven indepen‐
4952 dently if required (e.g. for CDash submission) and extra custom
4953 steps can be defined, along with the ability to control the step
4954 dependencies. The directory structure used for the management of
4955 the external project can also be customized. The function sup‐
4956 ports a large number of options which can be used to tailor the
4957 external project behavior.
4958 Directory Options:
4960 Most of the time, the default directory layout is suffi‐
4961 cient. It is largely an implementation detail that the
4962 main project usually doesn't need to change. In some cir‐
4963 cumstances, however, control over the directory layout
4964 can be useful or necessary. The directory options are po‐
4965 tentially more useful from the point of view that the
4966 main build can use the ExternalProject_Get_Property()
4967 command to retrieve their values, thereby allowing the
4968 main project to refer to build artifacts of the external
4969 project.
4970 PREFIX <dir>
4972 Root directory for the external project. Unless
4973 otherwise noted below, all other directories asso‐
4974 ciated with the external project will be created
4975 under here.
4976 TMP_DIR <dir>
4978 Directory in which to store temporary files.
4979 STAMP_DIR <dir>
4981 Directory in which to store the timestamps of each
4982 step. Log files from individual steps are also
4983 created in here unless overridden by LOG_DIR (see
4984 Logging Options below).
4985 LOG_DIR <dir>
4987 New in version 3.14.
4988 Directory in which to store the logs of each step.
4991 DOWNLOAD_DIR <dir>
4993 Directory in which to store downloaded files be‐
4994 fore unpacking them. This directory is only used
4995 by the URL download method, all other download
4996 methods use SOURCE_DIR directly instead.
4997 SOURCE_DIR <dir>
4999 Source directory into which downloaded contents
5000 will be unpacked, or for non-URL download methods,
5001 the directory in which the repository should be
5002 checked out, cloned, etc. If no download method is
5003 specified, this must point to an existing direc‐
5004 tory where the external project has already been
5005 unpacked or cloned/checked out.
5006 NOTE:
5008 If a download method is specified, any existing
5009 contents of the source directory may be
5010 deleted. Only the URL download method checks
5011 whether this directory is either missing or
5012 empty before initiating the download, stopping
5013 with an error if it is not empty. All other
5014 download methods silently discard any previous
5015 contents of the source directory.
5016 BINARY_DIR <dir>
5018 Specify the build directory location. This option
5019 is ignored if BUILD_IN_SOURCE is enabled.
5020 INSTALL_DIR <dir>
5022 Installation prefix to be placed in the <IN‐
5023 STALL_DIR> placeholder. This does not actually
5024 configure the external project to install to the
5025 given prefix. That must be done by passing appro‐
5026 priate arguments to the external project configu‐
5027 ration step, e.g. using <INSTALL_DIR>.
5028 If any of the above ..._DIR options are not specified,
5030 their defaults are computed as follows. If the PREFIX op‐
5031 tion is given or the EP_PREFIX directory property is set,
5032 then an external project is built and installed under the
5033 specified prefix:
5034 TMP_DIR = <prefix>/tmp
5036 STAMP_DIR = <prefix>/src/<name>-stamp
5037 DOWNLOAD_DIR = <prefix>/src
5038 SOURCE_DIR = <prefix>/src/<name>
5039 BINARY_DIR = <prefix>/src/<name>-build
5040 INSTALL_DIR = <prefix>
5041 LOG_DIR = <STAMP_DIR>
5042 Otherwise, if the EP_BASE directory property is set then
5044 components of an external project are stored under the
5045 specified base:
5046 TMP_DIR = <base>/tmp/<name>
5048 STAMP_DIR = <base>/Stamp/<name>
5049 DOWNLOAD_DIR = <base>/Download/<name>
5050 SOURCE_DIR = <base>/Source/<name>
5051 BINARY_DIR = <base>/Build/<name>
5052 INSTALL_DIR = <base>/Install/<name>
5053 LOG_DIR = <STAMP_DIR>
5054 If no PREFIX, EP_PREFIX, or EP_BASE is specified, then
5056 the default is to set PREFIX to <name>-prefix. Relative
5057 paths are interpreted with respect to
5058 CMAKE_CURRENT_BINARY_DIR at the point where ExternalPro‐
5059 ject_Add() is called.
5060 Download Step Options:
5062 A download method can be omitted if the SOURCE_DIR option
5063 is used to point to an existing non-empty directory. Oth‐
5064 erwise, one of the download methods below must be speci‐
5065 fied (multiple download methods should not be given) or a
5066 custom DOWNLOAD_COMMAND provided.
5067 DOWNLOAD_COMMAND <cmd>...
5069 Overrides the command used for the download step
5070 (generator expressions are supported). If this op‐
5071 tion is specified, all other download options will
5072 be ignored. Providing an empty string for <cmd>
5073 effectively disables the download step.
5074 URL Download
5076 URL <url1> [<url2>...]
5078 List of paths and/or URL(s) of the external
5079 project's source. When more than one URL is
5080 given, they are tried in turn until one
5081 succeeds. A URL may be an ordinary path in
5082 the local file system (in which case it
5083 must be the only URL provided) or any down‐
5084 loadable URL supported by the
5085 file(DOWNLOAD) command. A local filesystem
5086 path may refer to either an existing direc‐
5087 tory or to an archive file, whereas a URL
5088 is expected to point to a file which can be
5089 treated as an archive. When an archive is
5090 used, it will be unpacked automatically un‐
5091 less the DOWNLOAD_NO_EXTRACT option is set
5092 to prevent it. The archive type is deter‐
5093 mined by inspecting the actual content
5094 rather than using logic based on the file
5095 extension.
5096 Changed in version 3.7: Multiple URLs are
5098 allowed.
5099 URL_HASH <algo>=<hashValue>
5102 Hash of the archive file to be downloaded.
5103 The argument should be of the form
5104 <algo>=<hashValue> where algo can be any of
5105 the hashing algorithms supported by the
5106 file() command. Specifying this option is
5107 strongly recommended for URL downloads, as
5108 it ensures the integrity of the downloaded
5109 content. It is also used as a check for a
5110 previously downloaded file, allowing con‐
5111 nection to the remote location to be
5112 avoided altogether if the local directory
5113 already has a file from an earlier download
5114 that matches the specified hash.
5115 URL_MD5 <md5>
5117 Equivalent to URL_HASH MD5=<md5>.
5118 DOWNLOAD_NAME <fname>
5120 File name to use for the downloaded file.
5121 If not given, the end of the URL is used to
5122 determine the file name. This option is
5123 rarely needed, the default name is gener‐
5124 ally suitable and is not normally used out‐
5125 side of code internal to the ExternalPro‐
5126 ject module.
5127 DOWNLOAD_EXTRACT_TIMESTAMP <bool>
5129 New in version 3.24.
5130 When specified with a true value, the time‐
5133 stamps of the extracted files will match
5134 those in the archive. When false, the time‐
5135 stamps of the extracted files will reflect
5136 the time at which the extraction was per‐
5137 formed. If the download URL changes, time‐
5138 stamps based off those in the archive can
5139 result in dependent targets not being re‐
5140 built when they potentially should have
5141 been. Therefore, unless the file timestamps
5142 are significant to the project in some way,
5143 use a false value for this option. If DOWN‐
5144 LOAD_EXTRACT_TIMESTAMP is not given, the
5145 default is false. See policy CMP0135.
5146 DOWNLOAD_NO_EXTRACT <bool>
5148 New in version 3.6.
5149 Allows the extraction part of the download
5152 step to be disabled by passing a boolean
5153 true value for this option. If this option
5154 is not given, the downloaded contents will
5155 be unpacked automatically if required. If
5156 extraction has been disabled, the full path
5157 to the downloaded file is available as
5158 <DOWNLOADED_FILE> in subsequent steps or as
5159 the property DOWNLOADED_FILE with the
5160 ExternalProject_Get_Property() command.
5161 DOWNLOAD_NO_PROGRESS <bool>
5163 Can be used to disable logging the download
5164 progress. If this option is not given,
5165 download progress messages will be logged.
5166 TIMEOUT <seconds>
5168 Maximum time allowed for file download op‐
5169 erations.
5170 INACTIVITY_TIMEOUT <seconds>
5172 New in version 3.19.
5173 Terminate the operation after a period of
5176 inactivity.
5177 HTTP_USERNAME <username>
5179 New in version 3.7.
5180 Username for the download operation if au‐
5183 thentication is required.
5184 HTTP_PASSWORD <password>
5186 New in version 3.7.
5187 Password for the download operation if au‐
5190 thentication is required.
5191 HTTP_HEADER <header1> [<header2>...]
5193 New in version 3.7.
5194 Provides an arbitrary list of HTTP headers
5197 for the download operation. This can be
5198 useful for accessing content in systems
5199 like AWS, etc.
5200 TLS_VERIFY <bool>
5202 Specifies whether certificate verification
5203 should be performed for https URLs. If this
5204 option is not provided, the default behav‐
5205 ior is determined by the CMAKE_TLS_VERIFY
5206 variable (see file(DOWNLOAD)). If that is
5207 also not set, certificate verification will
5208 not be performed. In situations where
5209 URL_HASH cannot be provided, this option
5210 can be an alternative verification measure.
5211 Changed in version 3.6: This option also
5213 applies to git clone invocations, although
5214 the default behavior is different. If
5215 TLS_VERIFY is not given and
5216 CMAKE_TLS_VERIFY is not set, the behavior
5217 will be determined by git's defaults. Nor‐
5218 mally, the sslVerify git config setting de‐
5219 faults to true, but the user may have over‐
5220 ridden this at a global level.
5221 TLS_CAINFO <file>
5224 Specify a custom certificate authority file
5225 to use if TLS_VERIFY is enabled. If this
5226 option is not specified, the value of the
5227 CMAKE_TLS_CAINFO variable will be used in‐
5228 stead (see file(DOWNLOAD))
5229 NETRC <level>
5231 New in version 3.11.
5232 Specify whether the .netrc file is to be
5235 used for operation. If this option is not
5236 specified, the value of the CMAKE_NETRC
5237 variable will be used instead (see
5238 file(DOWNLOAD)). Valid levels are:
5239 IGNORED
5241 The .netrc file is ignored. This is
5242 the default.
5243 OPTIONAL
5245 The .netrc file is optional, and in‐
5246 formation in the URL is preferred.
5247 The file will be scanned to find
5248 which ever information is not speci‐
5249 fied in the URL.
5250 REQUIRED
5252 The .netrc file is required, and in‐
5253 formation in the URL is ignored.
5254 NETRC_FILE <file>
5256 New in version 3.11.
5257 Specify an alternative .netrc file to the
5260 one in your home directory if the NETRC
5261 level is OPTIONAL or REQUIRED. If this op‐
5262 tion is not specified, the value of the
5263 CMAKE_NETRC_FILE variable will be used in‐
5264 stead (see file(DOWNLOAD))
5265 New in version 3.1: Added support for tbz2,
5267 .tar.xz, .txz, and .7z extensions.
5268 Git NOTE: A git version of 1.6.5 or later is required
5271 if this download method is used.
5272 GIT_REPOSITORY <url>
5274 URL of the git repository. Any URL under‐
5275 stood by the git command may be used.
5276 Changed in version 3.27: A relative URL
5278 will be resolved based on the parent
5279 project's remote, subject to CMP0150. See
5280 the policy documentation for how the remote
5281 is selected, including conditions where the
5282 remote selection can fail. Local filesys‐
5283 tem remotes should always use absolute
5284 paths.
5285 GIT_TAG <tag>
5288 Git branch name, tag or commit hash. Note
5289 that branch names and tags should generally
5290 be specified as remote names (i.e. ori‐
5291 gin/myBranch rather than simply myBranch).
5292 This ensures that if the remote end has its
5293 tag moved or branch rebased or history
5294 rewritten, the local clone will still be
5295 updated correctly. In general, however,
5296 specifying a commit hash should be pre‐
5297 ferred for a number of reasons:
5298 • If the local clone already has the commit
5300 corresponding to the hash, no git fetch
5301 needs to be performed to check for
5302 changes each time CMake is re-run. This
5303 can result in a significant speed up if
5304 many external projects are being used.
5305 • Using a specific git hash ensures that
5307 the main project's own history is fully
5308 traceable to a specific point in the ex‐
5309 ternal project's evolution. If a branch
5310 or tag name is used instead, then check‐
5311 ing out a specific commit of the main
5312 project doesn't necessarily pin the whole
5313 build to a specific point in the life of
5314 the external project. The lack of such
5315 deterministic behavior makes the main
5316 project lose traceability and repeatabil‐
5317 ity.
5318 If GIT_SHALLOW is enabled then GIT_TAG
5320 works only with branch names and tags. A
5321 commit hash is not allowed.
5322 Note that if not provided, GIT_TAG defaults
5324 to master, not the default Git branch name.
5325 GIT_REMOTE_NAME <name>
5327 The optional name of the remote. If this
5328 option is not specified, it defaults to
5329 origin.
5330 GIT_SUBMODULES <module>...
5332 Specific git submodules that should also be
5333 updated. If this option is not provided,
5334 all git submodules will be updated.
5335 Changed in version 3.16: When CMP0097 is
5337 set to NEW, if this value is set to an
5338 empty string then no submodules are ini‐
5339 tialized or updated.
5340 GIT_SUBMODULES_RECURSE <bool>
5343 New in version 3.17.
5344 Specify whether git submodules (if any)
5347 should update recursively by passing the
5348 --recursive flag to git submodule update.
5349 If not specified, the default is on.
5350 GIT_SHALLOW <bool>
5352 New in version 3.6.
5353 When this option is enabled, the git clone
5356 operation will be given the --depth 1 op‐
5357 tion. This performs a shallow clone, which
5358 avoids downloading the whole history and
5359 instead retrieves just the commit denoted
5360 by the GIT_TAG option.
5361 GIT_PROGRESS <bool>
5363 New in version 3.8.
5364 When enabled, this option instructs the git
5367 clone operation to report its progress by
5368 passing it the --progress option. Without
5369 this option, the clone step for large
5370 projects may appear to make the build
5371 stall, since nothing will be logged until
5372 the clone operation finishes. While this
5373 option can be used to provide progress to
5374 prevent the appearance of the build having
5375 stalled, it may also make the build overly
5376 noisy if lots of external projects are
5377 used.
5378 GIT_CONFIG <option1> [<option2>...]
5380 New in version 3.8.
5381 Specify a list of config options to pass to
5384 git clone. Each option listed will be
5385 transformed into its own --config <option>
5386 on the git clone command line, with each
5387 option required to be in the form
5388 key=value.
5389 GIT_REMOTE_UPDATE_STRATEGY <strategy>
5391 New in version 3.18.
5392 When GIT_TAG refers to a remote branch,
5395 this option can be used to specify how the
5396 update step behaves. The <strategy> must
5397 be one of the following:
5398 CHECKOUT
5400 Ignore the local branch and always
5401 checkout the branch specified by
5402 GIT_TAG.
5403 REBASE Try to rebase the current branch to
5405 the one specified by GIT_TAG. If
5406 there are local uncommitted changes,
5407 they will be stashed first and
5408 popped again after rebasing. If re‐
5409 basing or popping stashed changes
5410 fail, abort the rebase and halt with
5411 an error. When GIT_REMOTE_UP‐
5412 DATE_STRATEGY is not present, this
5413 is the default strategy unless the
5414 default has been overridden with
5415 CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY
5416 (see below). Note that if the
5417 branch specified in GIT_TAG is dif‐
5418 ferent to the upstream branch cur‐
5419 rently being tracked, it is not safe
5420 to perform a rebase. In that situa‐
5421 tion, REBASE will silently be
5422 treated as CHECKOUT instead.
5423 REBASE_CHECKOUT
5425 Same as REBASE except if the rebase
5426 fails, an annotated tag will be cre‐
5427 ated at the original HEAD position
5428 from before the rebase and then
5429 checkout GIT_TAG just like the
5430 CHECKOUT strategy. The message
5431 stored on the annotated tag will
5432 give information about what was at‐
5433 tempted and the tag name will in‐
5434 clude a timestamp so that each
5435 failed run will add a new tag. This
5436 strategy ensures no changes will be
5437 lost, but updates should always suc‐
5438 ceed if GIT_TAG refers to a valid
5439 ref unless there are uncommitted
5440 changes that cannot be popped suc‐
5441 cessfully.
5442 The variable CMAKE_EP_GIT_REMOTE_UP‐
5444 DATE_STRATEGY can be set to override the
5445 default strategy. This variable should not
5446 be set by a project, it is intended for the
5447 user to set. It is primarily intended for
5448 use in continuous integration scripts to
5449 ensure that when history is rewritten on a
5450 remote branch, the build doesn't end up
5451 with unintended changes or failed builds
5452 resulting from conflicts during rebase op‐
5453 erations.
5454 Subversion
5456 SVN_REPOSITORY <url>
5458 URL of the Subversion repository.
5459 SVN_REVISION -r<rev>
5461 Revision to checkout from the Subversion
5462 repository.
5463 SVN_USERNAME <username>
5465 Username for the Subversion checkout and
5466 update.
5467 SVN_PASSWORD <password>
5469 Password for the Subversion checkout and
5470 update.
5471 SVN_TRUST_CERT <bool>
5473 Specifies whether to trust the Subversion
5474 server site certificate. If enabled, the
5475 --trust-server-cert option is passed to the
5476 svn checkout and update commands.
5477 Mercurial
5479 HG_REPOSITORY <url>
5481 URL of the mercurial repository.
5482 HG_TAG <tag>
5484 Mercurial branch name, tag or commit id.
5485 CVS
5487 CVS_REPOSITORY <cvsroot>
5489 CVSROOT of the CVS repository.
5490 CVS_MODULE <mod>
5492 Module to checkout from the CVS repository.
5493 CVS_TAG <tag>
5495 Tag to checkout from the CVS repository.
5496 Update Step Options:
5498 Whenever CMake is re-run, by default the external
5499 project's sources will be updated if the download method
5500 supports updates (e.g. a git repository would be checked
5501 if the GIT_TAG does not refer to a specific commit).
5502 UPDATE_COMMAND <cmd>...
5504 Overrides the download method's update step with a
5505 custom command. The command may use generator ex‐
5506 pressions.
5507 UPDATE_DISCONNECTED <bool>
5509 New in version 3.2.
5510 When enabled, this option causes the update step
5513 to be skipped (but see below for changed behavior
5514 where this is not the case). It does not prevent
5515 the download step. The update step can still be
5516 added as a step target (see
5517 ExternalProject_Add_StepTargets()) and called man‐
5518 ually. This is useful if you want to allow devel‐
5519 opers to build the project when disconnected from
5520 the network (the network may still be needed for
5521 the download step though).
5522 Changed in version 3.27: When UPDATE_DISCONNECTED
5524 is true, the update step will be executed if any
5525 details about the update or download step are
5526 changed. Furthermore, if using the git down‐
5527 load/update method, the update logic will be modi‐
5528 fied to skip attempts to contact the remote. If
5529 the GIT_TAG mentions a ref that is not known lo‐
5530 cally, the update step will halt with a fatal er‐
5531 ror.
5532 When this option is present, it is generally ad‐
5535 visable to make the value a cache variable under
5536 the developer's control rather than hard-coding
5537 it. If this option is not present, the default
5538 value is taken from the EP_UPDATE_DISCONNECTED di‐
5539 rectory property. If that is also not defined, up‐
5540 dates are performed as normal. The EP_UPDATE_DIS‐
5541 CONNECTED directory property is intended as a con‐
5542 venience for controlling the UPDATE_DISCONNECTED
5543 behavior for an entire section of a project's di‐
5544 rectory hierarchy and may be a more convenient
5545 method of giving developers control over whether
5546 or not to perform updates (assuming the project
5547 also provides a cache variable or some other con‐
5548 venient method for setting the directory prop‐
5549 erty).
5550 This may cause a step target to be created auto‐
5552 matically for the download step. See policy
5553 CMP0114.
5554 Patch Step Options:
5556 PATCH_COMMAND <cmd>...
5558 Specifies a custom command to patch the sources
5559 after an update. By default, no patch command is
5560 defined. Note that it can be quite difficult to
5561 define an appropriate patch command that performs
5562 robustly, especially for download methods such as
5563 git where changing the GIT_TAG will not discard
5564 changes from a previous patch, but the patch com‐
5565 mand will be called again after updating to the
5566 new tag.
5567 Configure Step Options:
5569 The configure step is run after the download and update
5570 steps. By default, the external project is assumed to be
5571 a CMake project, but this can be overridden if required.
5572 CONFIGURE_COMMAND <cmd>...
5574 The default configure command runs CMake with a
5575 few options based on the main project. The op‐
5576 tions added are typically only those needed to use
5577 the same generator as the main project, but the
5578 CMAKE_GENERATOR option can be given to override
5579 this. The project is responsible for adding any
5580 toolchain details, flags or other settings it
5581 wants to re-use from the main project or otherwise
5582 specify (see CMAKE_ARGS, CMAKE_CACHE_ARGS and
5583 CMAKE_CACHE_DEFAULT_ARGS below).
5584 For non-CMake external projects, the CONFIG‐
5586 URE_COMMAND option must be used to override the
5587 default configure command (generator expressions
5588 are supported). For projects that require no con‐
5589 figure step, specify this option with an empty
5590 string as the command to execute.
5591 CMAKE_COMMAND /.../cmake
5593 Specify an alternative cmake executable for the
5594 configure step (use an absolute path). This is
5595 generally not recommended, since it is usually de‐
5596 sirable to use the same CMake version throughout
5597 the whole build. This option is ignored if a cus‐
5598 tom configure command has been specified with CON‐
5599 FIGURE_COMMAND.
5600 CMAKE_GENERATOR <gen>
5602 Override the CMake generator used for the config‐
5603 ure step. Without this option, the same generator
5604 as the main build will be used. This option is ig‐
5605 nored if a custom configure command has been spec‐
5606 ified with the CONFIGURE_COMMAND option.
5607 CMAKE_GENERATOR_PLATFORM <platform>
5609 New in version 3.1.
5610 Pass a generator-specific platform name to the
5613 CMake command (see CMAKE_GENERATOR_PLATFORM). It
5614 is an error to provide this option without the
5615 CMAKE_GENERATOR option.
5616 CMAKE_GENERATOR_TOOLSET <toolset>
5618 Pass a generator-specific toolset name to the
5619 CMake command (see CMAKE_GENERATOR_TOOLSET). It is
5620 an error to provide this option without the
5621 CMAKE_GENERATOR option.
5622 CMAKE_GENERATOR_INSTANCE <instance>
5624 New in version 3.11.
5625 Pass a generator-specific instance selection to
5628 the CMake command (see CMAKE_GENERATOR_INSTANCE).
5629 It is an error to provide this option without the
5630 CMAKE_GENERATOR option.
5631 CMAKE_ARGS <arg>...
5633 The specified arguments are passed to the cmake
5634 command line. They can be any argument the cmake
5635 command understands, not just cache values defined
5636 by -D... arguments (see also CMake Options).
5637 New in version 3.3: Arguments may use generator
5639 expressions.
5640 CMAKE_CACHE_ARGS <arg>...
5643 This is an alternate way of specifying cache vari‐
5644 ables where command line length issues may become
5645 a problem. The arguments are expected to be in the
5646 form -Dvar:STRING=value, which are then trans‐
5647 formed into CMake set() commands with the FORCE
5648 option used. These set() commands are written to a
5649 pre-load script which is then applied using the
5650 cmake -C command line option.
5651 New in version 3.3: Arguments may use generator
5653 expressions.
5654 CMAKE_CACHE_DEFAULT_ARGS <arg>...
5657 New in version 3.2.
5658 This is the same as the CMAKE_CACHE_ARGS option
5661 except the set() commands do not include the FORCE
5662 keyword. This means the values act as initial de‐
5663 faults only and will not override any variables
5664 already set from a previous run. Use this option
5665 with care, as it can lead to different behavior
5666 depending on whether the build starts from a fresh
5667 build directory or re-uses previous build con‐
5668 tents.
5669 New in version 3.15: If the CMake generator is the
5671 Green Hills MULTI and not overridden, the original
5672 project's settings for the GHS toolset and target
5673 system customization cache variables are propa‐
5674 gated into the external project.
5675 SOURCE_SUBDIR <dir>
5678 New in version 3.7.
5679 When no CONFIGURE_COMMAND option is specified, the
5682 configure step assumes the external project has a
5683 CMakeLists.txt file at the top of its source tree
5684 (i.e. in SOURCE_DIR). The SOURCE_SUBDIR option can
5685 be used to point to an alternative directory
5686 within the source tree to use as the top of the
5687 CMake source tree instead. This must be a relative
5688 path and it will be interpreted as being relative
5689 to SOURCE_DIR.
5690 New in version 3.14: When BUILD_IN_SOURCE option
5692 is enabled, the BUILD_COMMAND is used to point to
5693 an alternative directory within the source tree.
5694 CONFIGURE_HANDLED_BY_BUILD <bool>
5697 New in version 3.20.
5698 Enabling this option relaxes the dependencies of
5701 the configure step on other external projects to
5702 order-only. This means the configure step will be
5703 executed after its external project dependencies
5704 are built but it will not be marked dirty when one
5705 of its external project dependencies is rebuilt.
5706 This option can be enabled when the build step is
5707 smart enough to figure out if the configure step
5708 needs to be rerun. CMake and Meson are examples of
5709 build systems whose build step is smart enough to
5710 know if the configure step needs to be rerun.
5711 Build Step Options:
5713 If the configure step assumed the external project uses
5714 CMake as its build system, the build step will also. Oth‐
5715 erwise, the build step will assume a Makefile-based build
5716 and simply run make with no arguments as the default
5717 build step. This can be overridden with custom build com‐
5718 mands if required.
5719 If both the main project and the external project use
5721 make as their build tool, the build step of the external
5722 project is invoked as a recursive make using $(MAKE).
5723 This will communicate some build tool settings from the
5724 main project to the external project. If either the main
5725 project or external project is not using make, no build
5726 tool settings will be passed to the external project
5727 other than those established by the configure step (i.e.
5728 running ninja -v in the main project will not pass -v to
5729 the external project's build step, even if it also uses
5730 ninja as its build tool).
5731 BUILD_COMMAND <cmd>...
5733 Overrides the default build command (generator ex‐
5734 pressions are supported). If this option is not
5735 given, the default build command will be chosen to
5736 integrate with the main build in the most appro‐
5737 priate way (e.g. using recursive make for Makefile
5738 generators or cmake --build if the project uses a
5739 CMake build). This option can be specified with an
5740 empty string as the command to make the build step
5741 do nothing.
5742 BUILD_IN_SOURCE <bool>
5744 When this option is enabled, the build will be
5745 done directly within the external project's source
5746 tree. This should generally be avoided, the use of
5747 a separate build directory is usually preferred,
5748 but it can be useful when the external project as‐
5749 sumes an in-source build. The BINARY_DIR option
5750 should not be specified if building in-source.
5751 BUILD_ALWAYS <bool>
5753 Enabling this option forces the build step to al‐
5754 ways be run. This can be the easiest way to ro‐
5755 bustly ensure that the external project's own
5756 build dependencies are evaluated rather than rely‐
5757 ing on the default success timestamp-based method.
5758 This option is not normally needed unless develop‐
5759 ers are expected to modify something the external
5760 project's build depends on in a way that is not
5761 detectable via the step target dependencies (e.g.
5762 SOURCE_DIR is used without a download method and
5763 developers might modify the sources in
5764 SOURCE_DIR).
5765 BUILD_BYPRODUCTS <file>...
5767 New in version 3.2.
5768 Specifies files that will be generated by the
5771 build command but which might or might not have
5772 their modification time updated by subsequent
5773 builds. This may also be required to explicitly
5774 declare dependencies when using the Ninja genera‐
5775 tor. These ultimately get passed through as
5776 BYPRODUCTS to the build step's own underlying call
5777 to add_custom_command(), which has additional doc‐
5778 umentation.
5779 Install Step Options:
5781 If the configure step assumed the external project uses
5782 CMake as its build system, the install step will also.
5783 Otherwise, the install step will assume a Makefile-based
5784 build and simply run make install as the default build
5785 step. This can be overridden with custom install commands
5786 if required.
5787 INSTALL_COMMAND <cmd>...
5789 The external project's own install step is invoked
5790 as part of the main project's build. It is done
5791 after the external project's build step and may be
5792 before or after the external project's test step
5793 (see the TEST_BEFORE_INSTALL option below). The
5794 external project's install rules are not part of
5795 the main project's install rules, so if anything
5796 from the external project should be installed as
5797 part of the main build, these need to be specified
5798 in the main build as additional install() com‐
5799 mands. The default install step builds the install
5800 target of the external project, but this can be
5801 overridden with a custom command using this option
5802 (generator expressions are supported). Passing an
5803 empty string as the <cmd> makes the install step
5804 do nothing.
5805 INSTALL_BYPRODUCTS <file>...
5807 New in version 3.26.
5808 Specifies files that will be generated by the in‐
5811 stall command but which might or might not have
5812 their modification time updated by subsequent in‐
5813 stalls. This may also be required to explicitly
5814 declare dependencies when using the Ninja genera‐
5815 tor. These ultimately get passed through as
5816 BYPRODUCTS to the install step's own underlying
5817 call to add_custom_command(), which has additional
5818 documentation.
5819 NOTE:
5821 If the CMAKE_INSTALL_MODE environment variable is set
5822 when the main project is built, it will only have an
5823 effect if the following conditions are met:
5824 • The main project's configure step assumed the exter‐
5826 nal project uses CMake as its build system.
5827 • The external project's install command actually
5829 runs. Note that due to the way ExternalProject may
5830 use timestamps internally, if nothing the install
5831 step depends on needs to be re-executed, the install
5832 command might also not need to run.
5833 Note also that ExternalProject does not check whether
5835 the CMAKE_INSTALL_MODE environment variable changes
5836 from one run to another.
5837 Test Step Options:
5839 The test step is only defined if at least one of the fol‐
5840 lowing TEST_... options are provided.
5841 TEST_COMMAND <cmd>...
5843 Overrides the default test command (generator ex‐
5844 pressions are supported). If this option is not
5845 given, the default behavior of the test step is to
5846 build the external project's own test target. This
5847 option can be specified with <cmd> as an empty
5848 string, which allows the test step to still be de‐
5849 fined, but it will do nothing. Do not specify any
5850 of the other TEST_... options if providing an
5851 empty string as the test command, but prefer to
5852 omit all TEST_... options altogether if the test
5853 step target is not needed.
5854 TEST_BEFORE_INSTALL <bool>
5856 When this option is enabled, the test step will be
5857 executed before the install step. The default be‐
5858 havior is for the test step to run after the in‐
5859 stall step.
5860 TEST_AFTER_INSTALL <bool>
5862 This option is mainly useful as a way to indicate
5863 that the test step is desired but all default be‐
5864 havior is sufficient. Specifying this option with
5865 a boolean true value ensures the test step is de‐
5866 fined and that it comes after the install step. If
5867 both TEST_BEFORE_INSTALL and TEST_AFTER_INSTALL
5868 are enabled, the latter is silently ignored.
5869 TEST_EXCLUDE_FROM_MAIN <bool>
5871 New in version 3.2.
5872 If enabled, the main build's default ALL target
5875 will not depend on the test step. This can be a
5876 useful way of ensuring the test step is defined
5877 but only gets invoked when manually requested.
5878 This may cause a step target to be created auto‐
5879 matically for either the install or build step.
5880 See policy CMP0114.
5881 Output Logging Options:
5883 Each of the following LOG_... options can be used to wrap
5884 the relevant step in a script to capture its output to
5885 files. The log files will be created in LOG_DIR if sup‐
5886 plied or otherwise the STAMP_DIR directory with step-spe‐
5887 cific file names.
5888 LOG_DOWNLOAD <bool>
5890 When enabled, the output of the download step is
5891 logged to files.
5892 LOG_UPDATE <bool>
5894 When enabled, the output of the update step is
5895 logged to files.
5896 LOG_PATCH <bool>
5898 New in version 3.14.
5899 When enabled, the output of the patch step is
5902 logged to files.
5903 LOG_CONFIGURE <bool>
5905 When enabled, the output of the configure step is
5906 logged to files.
5907 LOG_BUILD <bool>
5909 When enabled, the output of the build step is
5910 logged to files.
5911 LOG_INSTALL <bool>
5913 When enabled, the output of the install step is
5914 logged to files.
5915 LOG_TEST <bool>
5917 When enabled, the output of the test step is
5918 logged to files.
5919 LOG_MERGED_STDOUTERR <bool>
5921 New in version 3.14.
5922 When enabled, stdout and stderr will be merged for
5925 any step whose output is being logged to files.
5926 LOG_OUTPUT_ON_FAILURE <bool>
5928 New in version 3.14.
5929 This option only has an effect if at least one of
5932 the other LOG_<step> options is enabled. If an
5933 error occurs for a step which has logging to file
5934 enabled, that step's output will be printed to the
5935 console if LOG_OUTPUT_ON_FAILURE is set to true.
5936 For cases where a large amount of output is
5937 recorded, just the end of that output may be
5938 printed to the console.
5939 Terminal Access Options:
5941 New in version 3.4.
5942 Steps can be given direct access to the terminal in some
5945 cases. Giving a step access to the terminal may allow it
5946 to receive terminal input if required, such as for au‐
5947 thentication details not provided by other options. With
5948 the Ninja generator, these options place the steps in the
5949 console job pool. Each step can be given access to the
5950 terminal individually via the following options:
5951 USES_TERMINAL_DOWNLOAD <bool>
5953 Give the download step access to the terminal.
5954 USES_TERMINAL_UPDATE <bool>
5956 Give the update step access to the terminal.
5957 USES_TERMINAL_PATCH <bool>
5959 New in version 3.23.
5960 Give the patch step access to the terminal.
5963 USES_TERMINAL_CONFIGURE <bool>
5965 Give the configure step access to the terminal.
5966 USES_TERMINAL_BUILD <bool>
5968 Give the build step access to the terminal.
5969 USES_TERMINAL_INSTALL <bool>
5971 Give the install step access to the terminal.
5972 USES_TERMINAL_TEST <bool>
5974 Give the test step access to the terminal.
5975 Target Options:
5977 DEPENDS <targets>...
5979 Specify other targets on which the external
5980 project depends. The other targets will be brought
5981 up to date before any of the external project's
5982 steps are executed. Because the external project
5983 uses additional custom targets internally for each
5984 step, the DEPENDS option is the most convenient
5985 way to ensure all of those steps depend on the
5986 other targets. Simply doing
5987 add_dependencies(<name> <targets>) will not make
5988 any of the steps dependent on <targets>.
5989 EXCLUDE_FROM_ALL <bool>
5991 When enabled, this option excludes the external
5992 project from the default ALL target of the main
5993 build.
5994 STEP_TARGETS <step-target>...
5996 Generate custom targets for the specified steps.
5997 This is required if the steps need to be triggered
5998 manually or if they need to be used as dependen‐
5999 cies of other targets. If this option is not spec‐
6000 ified, the default value is taken from the
6001 EP_STEP_TARGETS directory property. See
6002 ExternalProject_Add_StepTargets() below for fur‐
6003 ther discussion of the effects of this option.
6004 INDEPENDENT_STEP_TARGETS <step-target>...
6006 Deprecated since version 3.19: This is allowed
6007 only if policy CMP0114 is not set to NEW.
6008 Generates custom targets for the specified steps
6011 and prevent these targets from having the usual
6012 dependencies applied to them. If this option is
6013 not specified, the default value is taken from the
6014 EP_INDEPENDENT_STEP_TARGETS directory property.
6015 This option is mostly useful for allowing individ‐
6016 ual steps to be driven independently, such as for
6017 a CDash setup where each step should be initiated
6018 and reported individually rather than as one whole
6019 build. See ExternalProject_Add_StepTargets() below
6020 for further discussion of the effects of this op‐
6021 tion.
6022 Miscellaneous Options:
6024 LIST_SEPARATOR <sep>
6026 For any of the various ..._COMMAND options, and
6027 CMAKE_ARGS, replace ; with <sep> in the specified
6028 command lines. This can be useful where list
6029 variables may be given in commands where they
6030 should end up as space-separated arguments (<sep>
6031 would be a single space character string in this
6032 case).
6033 COMMAND <cmd>...
6035 Any of the other ..._COMMAND options can have ad‐
6036 ditional commands appended to them by following
6037 them with as many COMMAND ... options as needed (‐
6038 generator expressions are supported). For example:
6039 ExternalProject_Add(example
6041 ... # Download options, etc.
6042 BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
6043 COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
6044 COMMAND ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
6045 )
6046 It should also be noted that each build step is created via a
6048 call to ExternalProject_Add_Step(). See that command's documen‐
6049 tation for the automatic substitutions that are supported for
6050 some options.
6051 Obtaining Project Properties
6053 ExternalProject_Get_Property
6054 The ExternalProject_Get_Property() function retrieves external
6055 project target properties:
6056 ExternalProject_Get_Property(<name> <prop1> [<prop2>...])
6058 The function stores property values in variables of the same
6060 name. Property names correspond to the keyword argument names of
6061 ExternalProject_Add(). For example, the source directory might
6062 be retrieved like so:
6063 ExternalProject_Get_property(myExtProj SOURCE_DIR)
6065 message("Source dir of myExtProj = ${SOURCE_DIR}")
6066 Explicit Step Management
6068 The ExternalProject_Add() function on its own is often sufficient for
6069 incorporating an external project into the main build. Certain scenar‐
6070 ios require additional work to implement desired behavior, such as
6071 adding in a custom step or making steps available as manually trigger‐
6072 able targets. The ExternalProject_Add_Step(), ExternalProject_Add_Step‐
6073 Targets() and ExternalProject_Add_StepDependencies functions provide
6074 the lower level control needed to implement such step-level capabili‐
6075 ties.
6076 ExternalProject_Add_Step
6078 The ExternalProject_Add_Step() function specifies an additional
6079 custom step for an external project defined by an earlier call
6080 to ExternalProject_Add():
6081 ExternalProject_Add_Step(<name> <step> [<option>...])
6083 <name> is the same as the name passed to the original call to
6085 ExternalProject_Add(). The specified <step> must not be one of
6086 the pre-defined steps (mkdir, download, update, patch, config‐
6087 ure, build, install or test). The supported options are:
6088 COMMAND <cmd>...
6090 The command line to be executed by this custom step (‐
6091 generator expressions are supported). This option can be
6092 repeated multiple times to specify multiple commands to
6093 be executed in order.
6094 COMMENT "<text>..."
6096 Text to be printed when the custom step executes.
6097 DEPENDEES <step>...
6099 Other steps (custom or pre-defined) on which this step
6100 depends.
6101 DEPENDERS <step>...
6103 Other steps (custom or pre-defined) that depend on this
6104 new custom step.
6105 DEPENDS <file>...
6107 Files on which this custom step depends.
6108 INDEPENDENT <bool>
6110 New in version 3.19.
6111 Specifies whether this step is independent of the exter‐
6114 nal dependencies specified by the ExternalProject_Add()'s
6115 DEPENDS option. The default is FALSE. Steps marked as
6116 independent may depend only on other steps marked inde‐
6117 pendent. See policy CMP0114.
6118 Note that this use of the term "independent" refers only
6120 to independence from external targets specified by the
6121 DEPENDS option and is orthogonal to a step's dependencies
6122 on other steps.
6123 If a step target is created for an independent step by
6125 the ExternalProject_Add() STEP_TARGETS option or by the
6126 ExternalProject_Add_StepTargets() function, it will not
6127 depend on the external targets, but may depend on targets
6128 for other steps.
6129 BYPRODUCTS <file>...
6131 New in version 3.2.
6132 Files that will be generated by this custom step but
6135 which might or might not have their modification time up‐
6136 dated by subsequent builds. This may also be required to
6137 explicitly declare dependencies when using the Ninja gen‐
6138 erator. This list of files will ultimately be passed
6139 through as the BYPRODUCTS option to the
6140 add_custom_command() used to implement the custom step
6141 internally, which has additional documentation.
6142 ALWAYS <bool>
6144 When enabled, this option specifies that the custom step
6145 should always be run (i.e. that it is always considered
6146 out of date).
6147 EXCLUDE_FROM_MAIN <bool>
6149 When enabled, this option specifies that the external
6150 project's main target does not depend on the custom step.
6151 This may cause step targets to be created automatically
6152 for the steps on which this step depends. See policy
6153 CMP0114.
6154 WORKING_DIRECTORY <dir>
6156 Specifies the working directory to set before running the
6157 custom step's command. If this option is not specified,
6158 the directory will be the value of the
6159 CMAKE_CURRENT_BINARY_DIR at the point where ExternalPro‐
6160 ject_Add_Step() was called.
6161 LOG <bool>
6163 If set, this causes the output from the custom step to be
6164 captured to files in the external project's LOG_DIR if
6165 supplied or STAMP_DIR.
6166 USES_TERMINAL <bool>
6168 If enabled, this gives the custom step direct access to
6169 the terminal if possible.
6170 The command line, comment, working directory and byproducts of
6172 every standard and custom step are processed to replace the to‐
6173 kens <SOURCE_DIR>, <SOURCE_SUBDIR>, <BINARY_DIR>, <INSTALL_DIR>
6174 <TMP_DIR>, <DOWNLOAD_DIR> and <DOWNLOADED_FILE> with their cor‐
6175 responding property values defined in the original call to
6176 ExternalProject_Add().
6177 New in version 3.3: Token replacement is extended to byproducts.
6179 New in version 3.11: The <DOWNLOAD_DIR> substitution token.
6182 ExternalProject_Add_StepTargets
6185 The ExternalProject_Add_StepTargets() function generates targets
6186 for the steps listed. The name of each created target will be of
6187 the form <name>-<step>:
6188 ExternalProject_Add_StepTargets(<name> <step1> [<step2>...])
6190 Creating a target for a step allows it to be used as a depen‐
6192 dency of another target or to be triggered manually. Having tar‐
6193 gets for specific steps also allows them to be driven indepen‐
6194 dently of each other by specifying targets on build command
6195 lines. For example, you may be submitting to a sub-project based
6196 dashboard where you want to drive the configure portion of the
6197 build, then submit to the dashboard, followed by the build por‐
6198 tion, followed by tests. If you invoke a custom target that de‐
6199 pends on a step halfway through the step dependency chain, then
6200 all the previous steps will also run to ensure everything is up
6201 to date.
6202 Internally, ExternalProject_Add() calls
6204 ExternalProject_Add_Step() to create each step. If any STEP_TAR‐
6205 GETS were specified, then ExternalProject_Add_StepTargets() will
6206 also be called after ExternalProject_Add_Step(). Even if a step
6207 is not mentioned in the STEP_TARGETS option, ExternalPro‐
6208 ject_Add_StepTargets() can still be called later to manually de‐
6209 fine a target for the step.
6210 The STEP_TARGETS option for ExternalProject_Add() is generally
6212 the easiest way to ensure targets are created for specific steps
6213 of interest. For custom steps, ExternalProject_Add_StepTar‐
6214 gets() must be called explicitly if a target should also be cre‐
6215 ated for that custom step. An alternative to these two options
6216 is to populate the EP_STEP_TARGETS directory property. It acts
6217 as a default for the step target options and can save having to
6218 repeatedly specify the same set of step targets when multiple
6219 external projects are being defined.
6220 New in version 3.19: If CMP0114 is set to NEW, step targets are
6222 fully responsible for holding the custom commands implementing
6223 their steps. The primary target created by ExternalProject_Add
6224 depends on the step targets, and the step targets depend on each
6225 other. The target-level dependencies match the file-level de‐
6226 pendencies used by the custom commands for each step. The tar‐
6227 gets for steps created with ExternalProject_Add_Step()'s INDE‐
6228 PENDENT option do not depend on the external targets specified
6229 by ExternalProject_Add()'s DEPENDS option. The predefined steps
6230 mkdir, download, update, and patch are independent.
6231 If CMP0114 is not NEW, the following deprecated behavior is
6234 available:
6235 • A deprecated NO_DEPENDS option may be specified immediately
6237 after the <name> and before the first step. If the NO_DEPENDS
6238 option is specified, the step target will not depend on the
6239 dependencies of the external project (i.e. on any dependencies
6240 of the <name> custom target created by ExternalProject_Add()).
6241 This is usually safe for the download, update and patch steps,
6242 since they do not typically require that the dependencies are
6243 updated and built. Using NO_DEPENDS for any of the other
6244 pre-defined steps, however, may break parallel builds. Only
6245 use NO_DEPENDS where it is certain that the named steps gen‐
6246 uinely do not have dependencies. For custom steps, consider
6247 whether or not the custom commands require the dependencies to
6248 be configured, built and installed.
6249 • The INDEPENDENT_STEP_TARGETS option for ExternalProject_Add(),
6251 or the EP_INDEPENDENT_STEP_TARGETS directory property, tells
6252 the function to call ExternalProject_Add_StepTargets() inter‐
6253 nally using the NO_DEPENDS option for the specified steps.
6254 ExternalProject_Add_StepDependencies
6256 New in version 3.2.
6257 The ExternalProject_Add_StepDependencies() function can be used
6260 to add dependencies to a step. The dependencies added must be
6261 targets CMake already knows about (these can be ordinary exe‐
6262 cutable or library targets, custom targets or even step targets
6263 of another external project):
6264 ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])
6266 This function takes care to set both target and file level de‐
6268 pendencies and will ensure that parallel builds will not break.
6269 It should be used instead of add_dependencies() whenever adding
6270 a dependency for some of the step targets generated by the Ex‐
6271 ternalProject module.
6272 Examples
6274 The following example shows how to download and build a hypothetical
6275 project called FooBar from github:
6276 include(ExternalProject)
6278 ExternalProject_Add(foobar
6279 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
6280 GIT_TAG origin/release/1.2.3
6281 )
6282 For the sake of the example, also define a second hypothetical external
6284 project called SecretSauce, which is downloaded from a web server. Two
6285 URLs are given to take advantage of a faster internal network if avail‐
6286 able, with a fallback to a slower external server. The project is a
6287 typical Makefile project with no configure step, so some of the default
6288 commands are overridden. The build is only required to build the sauce
6289 target:
6290 find_program(MAKE_EXE NAMES gmake nmake make)
6292 ExternalProject_Add(secretsauce
6293 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
6294 https://www.somecompany.com/downloads/sauce-2.7.zip
6295 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
6296 CONFIGURE_COMMAND ""
6297 BUILD_COMMAND ${MAKE_EXE} sauce
6298 )
6299 Suppose the build step of secretsauce requires that foobar must already
6301 be built. This could be enforced like so:
6302 ExternalProject_Add_StepDependencies(secretsauce build foobar)
6304 Another alternative would be to create a custom target for foobar's
6306 build step and make secretsauce depend on that rather than the whole
6307 foobar project. This would mean foobar only needs to be built, it
6308 doesn't need to run its install or test steps before secretsauce can be
6309 built. The dependency can also be defined along with the secretsauce
6310 project:
6311 ExternalProject_Add_StepTargets(foobar build)
6313 ExternalProject_Add(secretsauce
6314 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
6315 https://www.somecompany.com/downloads/sauce-2.7.zip
6316 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
6317 CONFIGURE_COMMAND ""
6318 BUILD_COMMAND ${MAKE_EXE} sauce
6319 DEPENDS foobar-build
6320 )
6321 Instead of calling ExternalProject_Add_StepTargets(), the target could
6323 be defined along with the foobar project itself:
6324 ExternalProject_Add(foobar
6326 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
6327 GIT_TAG origin/release/1.2.3
6328 STEP_TARGETS build
6329 )
6330 If many external projects should have the same set of step targets,
6332 setting a directory property may be more convenient. The build step
6333 target could be created automatically by setting the EP_STEP_TARGETS
6334 directory property before creating the external projects with
6335 ExternalProject_Add():
6336 set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)
6338 Lastly, suppose that secretsauce provides a script called makedoc which
6340 can be used to generate its own documentation. Further suppose that the
6341 script expects the output directory to be provided as the only parame‐
6342 ter and that it should be run from the secretsauce source directory. A
6343 custom step and a custom target to trigger the script can be defined
6344 like so:
6345 ExternalProject_Add_Step(secretsauce docs
6347 COMMAND <SOURCE_DIR>/makedoc <BINARY_DIR>
6348 WORKING_DIRECTORY <SOURCE_DIR>
6349 COMMENT "Building secretsauce docs"
6350 ALWAYS TRUE
6351 EXCLUDE_FROM_MAIN TRUE
6352 )
6353 ExternalProject_Add_StepTargets(secretsauce docs)
6354 The custom step could then be triggered from the main build like so:
6356 cmake --build . --target secretsauce-docs
6358 FeatureSummary
6360 Functions for generating a summary of enabled/disabled features.
6361 These functions can be used to generate a summary of enabled and dis‐
6363 abled packages and/or feature for a build tree such as:
6364 -- The following OPTIONAL packages have been found:
6366 LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
6367 * Enables HTML-import in MyWordProcessor
6368 * Enables odt-export in MyWordProcessor
6369 PNG, A PNG image library., <http://www.libpng.org/pub/png/>
6370 * Enables saving screenshots
6371 -- The following OPTIONAL packages have not been found:
6372 Lua51, The Lua scripting language., <http://www.lua.org>
6373 * Enables macros in MyWordProcessor
6374 Foo, Foo provides cool stuff.
6375 Global Properties
6377 FeatureSummary_PKG_TYPES
6378 The global property FeatureSummary_PKG_TYPES defines the type of pack‐
6380 ages used by FeatureSummary.
6381 The order in this list is important, the first package type in the list
6383 is the least important, the last is the most important. the of a pack‐
6384 age can only be changed to higher types.
6385 The default package types are , RUNTIME, OPTIONAL, RECOMMENDED and RE‐
6387 QUIRED, and their importance is RUNTIME < OPTIONAL < RECOMMENDED < RE‐
6388 QUIRED.
6389 FeatureSummary_REQUIRED_PKG_TYPES
6391 The global property FeatureSummary_REQUIRED_PKG_TYPES defines which
6393 package types are required.
6394 If one or more package in this categories has not been found, CMake
6396 will abort when calling feature_summary() with the 'FATAL_ON_MISS‐
6397 ING_REQUIRED_PACKAGES' option enabled.
6398 The default value for this global property is REQUIRED.
6400 FeatureSummary_DEFAULT_PKG_TYPE
6402 The global property FeatureSummary_DEFAULT_PKG_TYPE defines which pack‐
6404 age type is the default one. When calling feature_summary(), if the
6405 user did not set the package type explicitly, the package will be as‐
6406 signed to this category.
6407 This value must be one of the types defined in the
6409 FeatureSummary_PKG_TYPES global property unless the package type is set
6410 for all the packages.
6411 The default value for this global property is OPTIONAL.
6413 FeatureSummary_<TYPE>_DESCRIPTION
6415 New in version 3.9.
6417 The global property FeatureSummary_<TYPE>_DESCRIPTION can be defined
6420 for each type to replace the type name with the specified string when‐
6421 ever the package type is used in an output string.
6422 If not set, the string "<TYPE> packages" is used.
6424 Functions
6426 feature_summary
6427 feature_summary( [FILENAME <file>]
6429 [APPEND]
6430 [VAR <variable_name>]
6431 [INCLUDE_QUIET_PACKAGES]
6432 [FATAL_ON_MISSING_REQUIRED_PACKAGES]
6433 [DESCRIPTION "<description>" | DEFAULT_DESCRIPTION]
6434 [QUIET_ON_EMPTY]
6435 WHAT (ALL
6436 | PACKAGES_FOUND | PACKAGES_NOT_FOUND
6437 | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
6438 | ENABLED_FEATURES | DISABLED_FEATURES)
6439 )
6440 The feature_summary() macro can be used to print information
6442 about enabled or disabled packages or features of a project. By
6443 default, only the names of the features/packages will be printed
6444 and their required version when one was specified. Use
6445 set_package_properties() to add more useful information, like
6446 e.g. a download URL for the respective package or their purpose
6447 in the project.
6448 The WHAT option is the only mandatory option. Here you specify
6450 what information will be printed:
6451 ALL print everything
6453 ENABLED_FEATURES
6455 the list of all features which are enabled
6456 DISABLED_FEATURES
6458 the list of all features which are disabled
6459 PACKAGES_FOUND
6461 the list of all packages which have been found
6462 PACKAGES_NOT_FOUND
6464 the list of all packages which have not been found
6465 For each package type <TYPE> defined by the
6467 FeatureSummary_PKG_TYPES global property, the following informa‐
6468 tion can also be used:
6469 <TYPE>_PACKAGES_FOUND
6471 only those packages which have been found which have the
6472 type <TYPE>
6473 <TYPE>_PACKAGES_NOT_FOUND
6475 only those packages which have not been found which have
6476 the type <TYPE>
6477 Changed in version 3.1: With the exception of the ALL value,
6479 these values can be combined in order to customize the output.
6480 For example:
6481 feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
6483 If a FILENAME is given, the information is printed into this
6486 file. If APPEND is used, it is appended to this file, otherwise
6487 the file is overwritten if it already existed. If the VAR op‐
6488 tion is used, the information is "printed" into the specified
6489 variable. If FILENAME is not used, the information is printed
6490 to the terminal. Using the DESCRIPTION option a description or
6491 headline can be set which will be printed above the actual con‐
6492 tent. If only one type of package was requested, no title is
6493 printed, unless it is explicitly set using either DESCRIPTION to
6494 use a custom string, or DEFAULT_DESCRIPTION to use a default ti‐
6495 tle for the requested type. If INCLUDE_QUIET_PACKAGES is given,
6496 packages which have been searched with find_package(... QUIET)
6497 will also be listed. By default they are skipped. If FA‐
6498 TAL_ON_MISSING_REQUIRED_PACKAGES is given, CMake will abort if a
6499 package which is marked as one of the package types listed in
6500 the FeatureSummary_REQUIRED_PKG_TYPES global property has not
6501 been found. The default value for the
6502 FeatureSummary_REQUIRED_PKG_TYPES global property is REQUIRED.
6503 New in version 3.9: The DEFAULT_DESCRIPTION option.
6505 The FeatureSummary_DEFAULT_PKG_TYPE global property can be modi‐
6508 fied to change the default package type assigned when not ex‐
6509 plicitly assigned by the user.
6510 New in version 3.8: If the QUIET_ON_EMPTY option is used, if
6512 only one type of package was requested, and no packages belong‐
6513 ing to that category were found, then no output (including the
6514 DESCRIPTION) is printed or added to the VAR variable.
6515 Example 1, append everything to a file:
6518 include(FeatureSummary)
6520 feature_summary(WHAT ALL
6521 FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
6522 Example 2, print the enabled features into the variable enabled‐
6524 FeaturesText, including QUIET packages:
6525 include(FeatureSummary)
6527 feature_summary(WHAT ENABLED_FEATURES
6528 INCLUDE_QUIET_PACKAGES
6529 DESCRIPTION "Enabled Features:"
6530 VAR enabledFeaturesText)
6531 message(STATUS "${enabledFeaturesText}")
6532 Example 3, change default package types and print only the cate‐
6534 gories that are not empty:
6535 include(FeatureSummary)
6537 set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
6538 find_package(FOO)
6539 set_package_properties(FOO PROPERTIES TYPE BUILD)
6540 feature_summary(WHAT BUILD_PACKAGES_FOUND
6541 Description "Build tools found:"
6542 QUIET_ON_EMPTY)
6543 feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
6544 Description "Build tools not found:"
6545 QUIET_ON_EMPTY)
6546 set_package_properties
6548 set_package_properties(<name> PROPERTIES
6550 [ URL <url> ]
6551 [ DESCRIPTION <description> ]
6552 [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
6553 [ PURPOSE <purpose> ]
6554 )
6555 Use this macro to set up information about the named package,
6557 which can then be displayed via FEATURE_SUMMARY(). This can be
6558 done either directly in the Find-module or in the project which
6559 uses the module after the find_package() call. The features for
6560 which information can be set are added automatically by the
6561 find_package() command.
6562 URL <url>
6564 This should be the homepage of the package, or something
6565 similar. Ideally this is set already directly in the
6566 Find-module.
6567 DESCRIPTION <description>
6569 A short description what that package is, at most one
6570 sentence. Ideally this is set already directly in the
6571 Find-module.
6572 TYPE <type>
6574 What type of dependency has the using project on that
6575 package. Default is OPTIONAL. In this case it is a
6576 package which can be used by the project when available
6577 at buildtime, but it also work without. RECOMMENDED is
6578 similar to OPTIONAL, i.e. the project will build if the
6579 package is not present, but the functionality of the re‐
6580 sulting binaries will be severely limited. If a REQUIRED
6581 package is not available at buildtime, the project may
6582 not even build. This can be combined with the FA‐
6583 TAL_ON_MISSING_REQUIRED_PACKAGES argument for fea‐
6584 ture_summary(). Last, a RUNTIME package is a package
6585 which is actually not used at all during the build, but
6586 which is required for actually running the resulting bi‐
6587 naries. So if such a package is missing, the project can
6588 still be built, but it may not work later on. If
6589 set_package_properties() is called multiple times for the
6590 same package with different TYPEs, the TYPE is only
6591 changed to higher TYPEs (RUNTIME < OPTIONAL < RECOMMENDED
6592 < REQUIRED), lower TYPEs are ignored. The TYPE property
6593 is project-specific, so it cannot be set by the Find-mod‐
6594 ule, but must be set in the project. Type accepted can
6595 be changed by setting the FeatureSummary_PKG_TYPES global
6596 property.
6597 PURPOSE <purpose>
6599 This describes which features this package enables in the
6600 project, i.e. it tells the user what functionality he
6601 gets in the resulting binaries. If set_package_proper‐
6602 ties() is called multiple times for a package, all PUR‐
6603 POSE properties are appended to a list of purposes of the
6604 package in the project. As the TYPE property, also the
6605 PURPOSE property is project-specific, so it cannot be set
6606 by the Find-module, but must be set in the project.
6607 Example for setting the info for a package:
6609 find_package(LibXml2)
6611 set_package_properties(LibXml2 PROPERTIES
6612 DESCRIPTION "A XML processing library."
6613 URL "http://xmlsoft.org/")
6614 # or
6615 set_package_properties(LibXml2 PROPERTIES
6616 TYPE RECOMMENDED
6617 PURPOSE "Enables HTML-import in MyWordProcessor")
6618 # or
6619 set_package_properties(LibXml2 PROPERTIES
6620 TYPE OPTIONAL
6621 PURPOSE "Enables odt-export in MyWordProcessor")
6622 find_package(DBUS)
6624 set_package_properties(DBUS PROPERTIES
6625 TYPE RUNTIME
6626 PURPOSE "Necessary to disable the screensaver during a presentation")
6627 add_feature_info
6629 add_feature_info(<name> <enabled> <description>)
6631 Use this macro to add information about a feature with the given
6633 <name>. <enabled> contains whether this feature is enabled or
6634 not. It can be a variable or a list of conditions. <descrip‐
6635 tion> is a text describing the feature. The information can be
6636 displayed using feature_summary() for ENABLED_FEATURES and DIS‐
6637 ABLED_FEATURES respectively.
6638 Changed in version 3.8: <enabled> can be a list of conditions.
6640 Example for setting the info for a feature:
6643 option(WITH_FOO "Help for foo" ON)
6645 add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
6646 Legacy Macros
6648 The following macros are provided for compatibility with previous CMake
6649 versions:
6650 set_package_info
6652 set_package_info(<name> <description> [ <url> [<purpose>] ])
6654 Use this macro to set up information about the named package,
6656 which can then be displayed via feature_summary(). This can be
6657 done either directly in the Find-module or in the project which
6658 uses the module after the find_package() call. The features for
6659 which information can be set are added automatically by the
6660 find_package() command.
6661 set_feature_info
6663 set_feature_info(<name> <description> [<url>])
6665 Does the same as:
6667 set_package_info(<name> <description> <url>)
6669 print_enabled_features
6671 print_enabled_features()
6673 Does the same as
6675 feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
6677 print_disabled_features
6679 print_disabled_features()
6681 Does the same as
6683 feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
6685 FetchContent
6687 New in version 3.11.
6688 NOTE:
6691 The Using Dependencies Guide provides a high-level introduction to
6692 this general topic. It provides a broader overview of where the
6693 FetchContent module fits into the bigger picture, including its re‐
6694 lationship to the find_package() command. The guide is recommended
6695 pre-reading before moving on to the details below.
6696 Overview
6698 This module enables populating content at configure time via any method
6699 supported by the ExternalProject module. Whereas ExternalProject_Add()
6700 downloads at build time, the FetchContent module makes content avail‐
6701 able immediately, allowing the configure step to use the content in
6702 commands like add_subdirectory(), include() or file() operations.
6703 Content population details should be defined separately from the com‐
6705 mand that performs the actual population. This separation ensures that
6706 all the dependency details are defined before anything might try to use
6707 them to populate content. This is particularly important in more com‐
6708 plex project hierarchies where dependencies may be shared between mul‐
6709 tiple projects.
6710 The following shows a typical example of declaring content details for
6712 some dependencies and then ensuring they are populated with a separate
6713 call:
6714 FetchContent_Declare(
6716 googletest
6717 GIT_REPOSITORY https://github.com/google/googletest.git
6718 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
6719 )
6720 FetchContent_Declare(
6721 myCompanyIcons
6722 URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
6723 URL_HASH MD5=5588a7b18261c20068beabfb4f530b87
6724 )
6725 FetchContent_MakeAvailable(googletest myCompanyIcons)
6727 The FetchContent_MakeAvailable() command ensures the named dependencies
6729 have been populated, either by an earlier call or by populating them
6730 itself. When performing the population, it will also add them to the
6731 main build, if possible, so that the main build can use the populated
6732 projects' targets, etc. See the command's documentation for how these
6733 steps are performed.
6734 When using a hierarchical project arrangement, projects at higher lev‐
6736 els in the hierarchy are able to override the declared details of con‐
6737 tent specified anywhere lower in the project hierarchy. The first de‐
6738 tails to be declared for a given dependency take precedence, regardless
6739 of where in the project hierarchy that occurs. Similarly, the first
6740 call that tries to populate a dependency "wins", with subsequent popu‐
6741 lations reusing the result of the first instead of repeating the popu‐
6742 lation again. See the Examples which demonstrate this scenario.
6743 In some cases, the main project may need to have more precise control
6745 over the population, or it may be required to explicitly define the
6746 population steps in a way that cannot be captured by the declared de‐
6747 tails alone. For such situations, the lower level
6748 FetchContent_GetProperties() and FetchContent_Populate() commands can
6749 be used. These lack the richer features provided by
6750 FetchContent_MakeAvailable() though, so their direct use should be con‐
6751 sidered a last resort. The typical pattern of such custom steps looks
6752 like this:
6753 # NOTE: Where possible, prefer to use FetchContent_MakeAvailable()
6755 # instead of custom logic like this
6756 # Check if population has already been performed
6758 FetchContent_GetProperties(depname)
6759 if(NOT depname_POPULATED)
6760 # Fetch the content using previously declared details
6761 FetchContent_Populate(depname)
6762 # Set custom variables, policies, etc.
6764 # ...
6765 # Bring the populated content into the build
6767 add_subdirectory(${depname_SOURCE_DIR} ${depname_BINARY_DIR})
6768 endif()
6769 The FetchContent module also supports defining and populating content
6771 in a single call, with no check for whether the content has been popu‐
6772 lated elsewhere already. This should not be done in projects, but may
6773 be appropriate for populating content in CMake's script mode. See
6774 FetchContent_Populate() for details.
6775 Commands
6777 FetchContent_Declare
6778 FetchContent_Declare(
6780 <name>
6781 <contentOptions>...
6782 [SYSTEM]
6783 [OVERRIDE_FIND_PACKAGE |
6784 FIND_PACKAGE_ARGS args...]
6785 )
6786 The FetchContent_Declare() function records the options that de‐
6788 scribe how to populate the specified content. If such details
6789 have already been recorded earlier in this project (regardless
6790 of where in the project hierarchy), this and all later calls for
6791 the same content <name> are ignored. This "first to record,
6792 wins" approach is what allows hierarchical projects to have par‐
6793 ent projects override content details of child projects.
6794 The content <name> can be any string without spaces, but good
6796 practice would be to use only letters, numbers and underscores.
6797 The name will be treated case-insensitively and it should be ob‐
6798 vious for the content it represents, often being the name of the
6799 child project or the value given to its top level project() com‐
6800 mand (if it is a CMake project). For well-known public
6801 projects, the name should generally be the official name of the
6802 project. Choosing an unusual name makes it unlikely that other
6803 projects needing that same content will use the same name, lead‐
6804 ing to the content being populated multiple times.
6805 The <contentOptions> can be any of the download, update or patch
6807 options that the ExternalProject_Add() command understands. The
6808 configure, build, install and test steps are explicitly disabled
6809 and therefore options related to them will be ignored. The
6810 SOURCE_SUBDIR option is an exception, see
6811 FetchContent_MakeAvailable() for details on how that affects be‐
6812 havior.
6813 In most cases, <contentOptions> will just be a couple of options
6815 defining the download method and method-specific details like a
6816 commit tag or archive hash. For example:
6817 FetchContent_Declare(
6819 googletest
6820 GIT_REPOSITORY https://github.com/google/googletest.git
6821 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
6822 )
6823 FetchContent_Declare(
6825 myCompanyIcons
6826 URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
6827 URL_HASH MD5=5588a7b18261c20068beabfb4f530b87
6828 )
6829 FetchContent_Declare(
6831 myCompanyCertificates
6832 SVN_REPOSITORY svn+ssh://svn.mycompany.com/srv/svn/trunk/certs
6833 SVN_REVISION -r12345
6834 )
6835 Where contents are being fetched from a remote location and you
6837 do not control that server, it is advisable to use a hash for
6838 GIT_TAG rather than a branch or tag name. A commit hash is more
6839 secure and helps to confirm that the downloaded contents are
6840 what you expected.
6841 Changed in version 3.14: Commands for the download, update or
6843 patch steps can access the terminal. This may be needed for
6844 things like password prompts or real-time display of command
6845 progress.
6846 New in version 3.22: The CMAKE_TLS_VERIFY, CMAKE_TLS_CAINFO,
6849 CMAKE_NETRC and CMAKE_NETRC_FILE variables now provide the de‐
6850 faults for their corresponding content options, just like they
6851 do for ExternalProject_Add(). Previously, these variables were
6852 ignored by the FetchContent module.
6853 New in version 3.24:
6856 FIND_PACKAGE_ARGS
6858 This option is for scenarios where the
6859 FetchContent_MakeAvailable() command may first try a call
6860 to find_package() to satisfy the dependency for <name>.
6861 By default, such a call would be simply find_pack‐
6862 age(<name>), but FIND_PACKAGE_ARGS can be used to provide
6863 additional arguments to be appended after the <name>.
6864 FIND_PACKAGE_ARGS can also be given with nothing after
6865 it, which indicates that find_package() can still be
6866 called if FETCHCONTENT_TRY_FIND_PACKAGE_MODE is set to
6867 OPT_IN or is not set.
6868 Everything after the FIND_PACKAGE_ARGS keyword is ap‐
6870 pended to the find_package() call, so all other <con‐
6871 tentOptions> must come before the FIND_PACKAGE_ARGS key‐
6872 word. If the CMAKE_FIND_PACKAGE_TARGETS_GLOBAL variable
6873 is set to true at the time FetchContent_Declare() is
6874 called, a GLOBAL keyword will be appended to the
6875 find_package() arguments if it was not already specified.
6876 It will also be appended if FIND_PACKAGE_ARGS was not
6877 given, but FETCHCONTENT_TRY_FIND_PACKAGE_MODE was set to
6878 ALWAYS.
6879 OVERRIDE_FIND_PACKAGE cannot be used when FIND_PACK‐
6881 AGE_ARGS is given.
6882 Dependency Providers discusses another way that
6884 FetchContent_MakeAvailable() calls can be redirected.
6885 FIND_PACKAGE_ARGS is intended for project control,
6886 whereas dependency providers allow users to override
6887 project behavior.
6888 OVERRIDE_FIND_PACKAGE
6890 When a FetchContent_Declare(<name> ...) call includes
6891 this option, subsequent calls to find_package(<name> ...)
6892 will ensure that FetchContent_MakeAvailable(<name>) has
6893 been called, then use the config package files in the
6894 CMAKE_FIND_PACKAGE_REDIRECTS_DIR directory (which are
6895 usually created by FetchContent_MakeAvailable()). This
6896 effectively makes FetchContent_MakeAvailable() override
6897 find_package() for the named dependency, allowing the
6898 former to satisfy the package requirements of the latter.
6899 FIND_PACKAGE_ARGS cannot be used when OVERRIDE_FIND_PACK‐
6900 AGE is given.
6901 If a dependency provider has been set and the project
6903 calls find_package() for the <name> dependency, OVER‐
6904 RIDE_FIND_PACKAGE will not prevent the provider from see‐
6905 ing that call. Dependency providers always have the op‐
6906 portunity to intercept any direct call to find_package(),
6907 except if that call contains the BYPASS_PROVIDER option.
6908 New in version 3.25:
6911 SYSTEM If the SYSTEM argument is provided, the SYSTEM directory
6913 property of a subdirectory added by
6914 FetchContent_MakeAvailable() will be set to true. This
6915 will affect non-imported targets created as part of that
6916 command. See the SYSTEM target property documentation
6917 for a more detailed discussion of the effects.
6918 FetchContent_MakeAvailable
6921 New in version 3.14.
6922 FetchContent_MakeAvailable(<name1> [<name2>...])
6925 This command ensures that each of the named dependencies are
6927 made available to the project by the time it returns. There
6928 must have been a call to FetchContent_Declare() for each depen‐
6929 dency, and the first such call will control how that dependency
6930 will be made available, as described below.
6931 If <lowercaseName>_SOURCE_DIR is not set:
6933 • New in version 3.24: If a dependency provider is set, call the
6935 provider's command with FETCHCONTENT_MAKEAVAILABLE_SERIAL as
6936 the first argument, followed by the arguments of the first
6937 call to FetchContent_Declare() for <name>. If SOURCE_DIR or
6938 BINARY_DIR were not part of the original declared arguments,
6939 they will be added with their default values. If
6940 FETCHCONTENT_TRY_FIND_PACKAGE_MODE was set to NEVER when the
6941 details were declared, any FIND_PACKAGE_ARGS will be omitted.
6942 The OVERRIDE_FIND_PACKAGE keyword is also always omitted. If
6943 the provider fulfilled the request, FetchContent_MakeAvail‐
6944 able() will consider that dependency handled, skip the remain‐
6945 ing steps below and move on to the next dependency in the
6946 list.
6947 • New in version 3.24: If permitted, find_package(<name>
6950 [<args>...]) will be called, where <args>... may be provided
6951 by the FIND_PACKAGE_ARGS option in FetchContent_Declare().
6952 The value of the FETCHCONTENT_TRY_FIND_PACKAGE_MODE variable
6953 at the time FetchContent_Declare() was called determines
6954 whether FetchContent_MakeAvailable() can call find_package().
6955 If the CMAKE_FIND_PACKAGE_TARGETS_GLOBAL variable is set to
6956 true when FetchContent_MakeAvailable() is called, it still af‐
6957 fects any imported targets created when that in turn calls
6958 find_package(), even if that variable was false when the cor‐
6959 responding details were declared.
6960 If the dependency was not satisfied by a provider or a
6963 find_package() call, FetchContent_MakeAvailable() then uses the
6964 following logic to make the dependency available:
6965 • If the dependency has already been populated earlier in this
6967 run, set the <lowercaseName>_POPULATED, <lowercase‐
6968 Name>_SOURCE_DIR and <lowercaseName>_BINARY_DIR variables in
6969 the same way as a call to FetchContent_GetProperties(), then
6970 skip the remaining steps below and move on to the next depen‐
6971 dency in the list.
6972 • Call FetchContent_Populate() to populate the dependency using
6974 the details recorded by an earlier call to
6975 FetchContent_Declare(). Halt with a fatal error if no such
6976 details have been recorded.
6977 FETCHCONTENT_SOURCE_DIR_<uppercaseName> can be used to over‐
6978 ride the declared details and use content provided at the
6979 specified location instead.
6980 • New in version 3.24: Ensure the
6982 CMAKE_FIND_PACKAGE_REDIRECTS_DIR directory contains a <lower‐
6983 caseName>-config.cmake and a <lowercaseName>-config-ver‐
6984 sion.cmake file (or equivalently <name>Config.cmake and
6985 <name>ConfigVersion.cmake). The directory that the
6986 CMAKE_FIND_PACKAGE_REDIRECTS_DIR variable points to is cleared
6987 at the start of every CMake run. If no config file exists
6988 when FetchContent_Populate() returns, a minimal one will be
6989 written which includes any <lowercaseName>-extra.cmake or
6990 <name>Extra.cmake file with the OPTIONAL flag (so the files
6991 can be missing and won't generate a warning). Similarly, if
6992 no config version file exists, a very simple one will be writ‐
6993 ten which sets PACKAGE_VERSION_COMPATIBLE and PACKAGE_VER‐
6994 SION_EXACT to true. This ensures all future calls to
6995 find_package() for the dependency will use the redirected con‐
6996 fig file, regardless of any version requirements. CMake can‐
6997 not automatically determine an arbitrary dependency's version,
6998 so it cannot set PACKAGE_VERSION. When a dependency is pulled
6999 in via add_subdirectory() in the next step, it may choose to
7000 overwrite the generated config version file in
7001 CMAKE_FIND_PACKAGE_REDIRECTS_DIR with one that also sets PACK‐
7002 AGE_VERSION. The dependency may also write a <lowercase‐
7003 Name>-extra.cmake or <name>Extra.cmake file to perform custom
7004 processing or define any variables that their normal (in‐
7005 stalled) package config file would otherwise usually define
7006 (many projects don't do any custom processing or set any vari‐
7007 ables and therefore have no need to do this). If required,
7008 the main project can write these files instead if the depen‐
7009 dency project doesn't do so. This allows the main project to
7010 add missing details from older dependencies that haven't or
7011 can't be updated to support this functionality. See
7012 Integrating With find_package() for examples.
7013 • If the top directory of the populated content contains a
7016 CMakeLists.txt file, call add_subdirectory() to add it to the
7017 main build. It is not an error for there to be no CMake‐
7018 Lists.txt file, which allows the command to be used for depen‐
7019 dencies that make downloaded content available at a known lo‐
7020 cation, but which do not need or support being added directly
7021 to the build.
7022 New in version 3.18: The SOURCE_SUBDIR option can be given in
7024 the declared details to look somewhere below the top directory
7025 instead (i.e. the same way that SOURCE_SUBDIR is used by the
7026 ExternalProject_Add() command). The path provided with
7027 SOURCE_SUBDIR must be relative and will be treated as relative
7028 to the top directory. It can also point to a directory that
7029 does not contain a CMakeLists.txt file or even to a directory
7030 that doesn't exist. This can be used to avoid adding a
7031 project that contains a CMakeLists.txt file in its top direc‐
7032 tory.
7033 New in version 3.25: If the SYSTEM keyword was included in the
7036 call to FetchContent_Declare(), the SYSTEM keyword will be
7037 added to the add_subdirectory() command as well.
7038 Projects should aim to declare the details of all dependencies
7041 they might use before they call FetchContent_MakeAvailable() for
7042 any of them. This ensures that if any of the dependencies are
7043 also sub-dependencies of one or more of the others, the main
7044 project still controls the details that will be used (because it
7045 will declare them first before the dependencies get a chance
7046 to). In the following code samples, assume that the uses_other
7047 dependency also uses FetchContent to add the other dependency
7048 internally:
7049 # WRONG: Should declare all details first
7051 FetchContent_Declare(uses_other ...)
7052 FetchContent_MakeAvailable(uses_other)
7053 FetchContent_Declare(other ...) # Will be ignored, uses_other beat us to it
7055 FetchContent_MakeAvailable(other) # Would use details declared by uses_other
7056 # CORRECT: All details declared first, so they will take priority
7058 FetchContent_Declare(uses_other ...)
7059 FetchContent_Declare(other ...)
7060 FetchContent_MakeAvailable(uses_other other)
7061 Note that CMAKE_VERIFY_INTERFACE_HEADER_SETS is explicitly set
7063 to false upon entry to FetchContent_MakeAvailable(), and is re‐
7064 stored to its original value before the command returns. Devel‐
7065 opers typically only want to verify header sets from the main
7066 project, not those from any dependencies. This local manipula‐
7067 tion of the CMAKE_VERIFY_INTERFACE_HEADER_SETS variable provides
7068 that intuitive behavior. You can use variables like
7069 CMAKE_PROJECT_INCLUDE or CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE to
7070 turn verification back on for all or some dependencies. You can
7071 also set the VERIFY_INTERFACE_HEADER_SETS property of individual
7072 targets.
7073 FetchContent_Populate
7075 NOTE:
7076 Where possible, prefer to use FetchContent_MakeAvailable()
7077 instead of implementing population manually with this com‐
7078 mand.
7079 FetchContent_Populate(<name>)
7081 In most cases, the only argument given to FetchContent_Popu‐
7083 late() is the <name>. When used this way, the command assumes
7084 the content details have been recorded by an earlier call to
7085 FetchContent_Declare(). The details are stored in a global
7086 property, so they are unaffected by things like variable or di‐
7087 rectory scope. Therefore, it doesn't matter where in the
7088 project the details were previously declared, as long as they
7089 have been declared before the call to FetchContent_Populate().
7090 Those saved details are then used to construct a call to
7091 ExternalProject_Add() in a private sub-build to perform the con‐
7092 tent population immediately. The implementation of ExternalPro‐
7093 ject_Add() ensures that if the content has already been popu‐
7094 lated in a previous CMake run, that content will be reused
7095 rather than repopulating them again. For the common case where
7096 population involves downloading content, the cost of the down‐
7097 load is only paid once.
7098 An internal global property records when a particular content
7100 population request has been processed. If FetchContent_Popu‐
7101 late() is called more than once for the same content name within
7102 a configure run, the second call will halt with an error.
7103 Projects can and should check whether content population has al‐
7104 ready been processed with the FetchContent_GetProperties() com‐
7105 mand before calling FetchContent_Populate().
7106 FetchContent_Populate() will set three variables in the scope of
7108 the caller:
7109 <lowercaseName>_POPULATED
7111 This will always be set to TRUE by the call.
7112 <lowercaseName>_SOURCE_DIR
7114 The location where the populated content can be found
7115 upon return.
7116 <lowercaseName>_BINARY_DIR
7118 A directory intended for use as a corresponding build di‐
7119 rectory.
7120 The main use case for the <lowercaseName>_SOURCE_DIR and <lower‐
7122 caseName>_BINARY_DIR variables is to call add_subdirectory() im‐
7123 mediately after population:
7124 FetchContent_Populate(FooBar)
7126 add_subdirectory(${foobar_SOURCE_DIR} ${foobar_BINARY_DIR})
7127 The values of the three variables can also be retrieved from
7129 anywhere in the project hierarchy using the
7130 FetchContent_GetProperties() command.
7131 The FetchContent_Populate() command also supports a syntax al‐
7133 lowing the content details to be specified directly rather than
7134 using any saved details. This is more low-level and use of this
7135 form is generally to be avoided in favor of using saved content
7136 details as outlined above. Nevertheless, in certain situations
7137 it can be useful to invoke the content population as an isolated
7138 operation (typically as part of implementing some other higher
7139 level feature or when using CMake in script mode):
7140 FetchContent_Populate(
7142 <name>
7143 [QUIET]
7144 [SUBBUILD_DIR <subBuildDir>]
7145 [SOURCE_DIR <srcDir>]
7146 [BINARY_DIR <binDir>]
7147 ...
7148 )
7149 This form has a number of key differences to that where only
7151 <name> is provided:
7152 • All required population details are assumed to have been pro‐
7154 vided directly in the call to FetchContent_Populate(). Any
7155 saved details for <name> are ignored.
7156 • No check is made for whether content for <name> has already
7158 been populated.
7159 • No global property is set to record that the population has
7161 occurred.
7162 • No global properties record the source or binary directories
7164 used for the populated content.
7165 • The FETCHCONTENT_FULLY_DISCONNECTED and FETCHCONTENT_UP‐
7167 DATES_DISCONNECTED cache variables are ignored.
7168 The <lowercaseName>_SOURCE_DIR and <lowercaseName>_BINARY_DIR
7170 variables are still returned to the caller, but since these lo‐
7171 cations are not stored as global properties when this form is
7172 used, they are only available to the calling scope and below
7173 rather than the entire project hierarchy. No <lowercase‐
7174 Name>_POPULATED variable is set in the caller's scope with this
7175 form.
7176 The supported options for FetchContent_Populate() are the same
7178 as those for FetchContent_Declare(). Those few options shown
7179 just above are either specific to FetchContent_Populate() or
7180 their behavior is slightly modified from how
7181 ExternalProject_Add() treats them:
7182 QUIET The QUIET option can be given to hide the output associ‐
7184 ated with populating the specified content. If the popu‐
7185 lation fails, the output will be shown regardless of
7186 whether this option was given or not so that the cause of
7187 the failure can be diagnosed. The global FETCHCON‐
7188 TENT_QUIET cache variable has no effect on FetchCon‐
7189 tent_Populate() calls where the content details are pro‐
7190 vided directly.
7191 SUBBUILD_DIR
7193 The SUBBUILD_DIR argument can be provided to change the
7194 location of the sub-build created to perform the popula‐
7195 tion. The default value is ${CMAKE_CURRENT_BI‐
7196 NARY_DIR}/<lowercaseName>-subbuild and it would be un‐
7197 usual to need to override this default. If a relative
7198 path is specified, it will be interpreted as relative to
7199 CMAKE_CURRENT_BINARY_DIR. This option should not be con‐
7200 fused with the SOURCE_SUBDIR option which only affects
7201 the FetchContent_MakeAvailable() command.
7202 SOURCE_DIR, BINARY_DIR
7204 The SOURCE_DIR and BINARY_DIR arguments are supported by
7205 ExternalProject_Add(), but different default values are
7206 used by FetchContent_Populate(). SOURCE_DIR defaults to
7207 ${CMAKE_CURRENT_BINARY_DIR}/<lowercaseName>-src and BI‐
7208 NARY_DIR defaults to ${CMAKE_CURRENT_BINARY_DIR}/<lower‐
7209 caseName>-build. If a relative path is specified, it
7210 will be interpreted as relative to
7211 CMAKE_CURRENT_BINARY_DIR.
7212 In addition to the above explicit options, any other unrecog‐
7214 nized options are passed through unmodified to
7215 ExternalProject_Add() to perform the download, patch and update
7216 steps. The following options are explicitly prohibited (they
7217 are disabled by the FetchContent_Populate() command):
7218 • CONFIGURE_COMMAND
7220 • BUILD_COMMAND
7222 • INSTALL_COMMAND
7224 • TEST_COMMAND
7226 If using FetchContent_Populate() within CMake's script mode, be
7228 aware that the implementation sets up a sub-build which there‐
7229 fore requires a CMake generator and build tool to be available.
7230 If these cannot be found by default, then the CMAKE_GENERATOR
7231 and/or CMAKE_MAKE_PROGRAM variables will need to be set appro‐
7232 priately on the command line invoking the script.
7233 New in version 3.18: Added support for the DOWNLOAD_NO_EXTRACT
7235 option.
7236 FetchContent_GetProperties
7239 When using saved content details, a call to
7240 FetchContent_MakeAvailable() or FetchContent_Populate() records
7241 information in global properties which can be queried at any
7242 time. This information may include the source and binary direc‐
7243 tories associated with the content and also whether or not the
7244 content population has been processed during the current config‐
7245 ure run.
7246 FetchContent_GetProperties(
7248 <name>
7249 [SOURCE_DIR <srcDirVar>]
7250 [BINARY_DIR <binDirVar>]
7251 [POPULATED <doneVar>]
7252 )
7253 The SOURCE_DIR, BINARY_DIR and POPULATED options can be used to
7255 specify which properties should be retrieved. Each option ac‐
7256 cepts a value which is the name of the variable in which to
7257 store that property. Most of the time though, only <name> is
7258 given, in which case the call will then set the same variables
7259 as a call to FetchContent_MakeAvailable(name) or
7260 FetchContent_Populate(name). Note that the SOURCE_DIR and BI‐
7261 NARY_DIR values can be empty if the call is fulfilled by a
7262 dependency provider.
7263 This command is rarely needed when using
7265 FetchContent_MakeAvailable(). It is more commonly used as part
7266 of implementing the following pattern with
7267 FetchContent_Populate(), which ensures that the relevant vari‐
7268 ables will always be defined regardless of whether or not the
7269 population has been performed elsewhere in the project already:
7270 # Check if population has already been performed
7272 FetchContent_GetProperties(depname)
7273 if(NOT depname_POPULATED)
7274 # Fetch the content using previously declared details
7275 FetchContent_Populate(depname)
7276 # Set custom variables, policies, etc.
7278 # ...
7279 # Bring the populated content into the build
7281 add_subdirectory(${depname_SOURCE_DIR} ${depname_BINARY_DIR})
7282 endif()
7283 FetchContent_SetPopulated
7285 New in version 3.24.
7286 NOTE:
7289 This command should only be called by dependency providers.
7290 Calling it in any other context is unsupported and future
7291 CMake versions may halt with a fatal error in such cases.
7292 FetchContent_SetPopulated(
7294 <name>
7295 [SOURCE_DIR <srcDir>]
7296 [BINARY_DIR <binDir>]
7297 )
7298 If a provider command fulfills a FETCHCONTENT_MAKEAVAILABLE_SE‐
7300 RIAL request, it must call this function before returning. The
7301 SOURCE_DIR and BINARY_DIR arguments can be used to specify the
7302 values that FetchContent_GetProperties() should return for its
7303 corresponding arguments. Only provide SOURCE_DIR and BINARY_DIR
7304 if they have the same meaning as if they had been populated by
7305 the built-in FetchContent_MakeAvailable() implementation.
7306 Variables
7308 A number of cache variables can influence the behavior where details
7309 from a FetchContent_Declare() call are used to populate content.
7310 NOTE:
7312 All of these variables are intended for the developer to customize
7313 behavior. They should not normally be set by the project.
7314 FETCHCONTENT_BASE_DIR
7316 In most cases, the saved details do not specify any options re‐
7317 lating to the directories to use for the internal sub-build, fi‐
7318 nal source and build areas. It is generally best to leave these
7319 decisions up to the FetchContent module to handle on the
7320 project's behalf. The FETCHCONTENT_BASE_DIR cache variable con‐
7321 trols the point under which all content population directories
7322 are collected, but in most cases, developers would not need to
7323 change this. The default location is ${CMAKE_BINARY_DIR}/_deps,
7324 but if developers change this value, they should aim to keep the
7325 path short and just below the top level of the build tree to
7326 avoid running into path length problems on Windows.
7327 FETCHCONTENT_QUIET
7329 The logging output during population can be quite verbose, mak‐
7330 ing the configure stage quite noisy. This cache option (ON by
7331 default) hides all population output unless an error is encoun‐
7332 tered. If experiencing problems with hung downloads, temporar‐
7333 ily switching this option off may help diagnose which content
7334 population is causing the issue.
7335 FETCHCONTENT_FULLY_DISCONNECTED
7337 When this option is enabled, no attempt is made to download or
7338 update any content. It is assumed that all content has already
7339 been populated in a previous run or the source directories have
7340 been pointed at existing contents the developer has provided
7341 manually (using options described further below). When the de‐
7342 veloper knows that no changes have been made to any content de‐
7343 tails, turning this option ON can significantly speed up the
7344 configure stage. It is OFF by default.
7345 FETCHCONTENT_UPDATES_DISCONNECTED
7347 This is a less severe download/update control compared to
7348 FETCHCONTENT_FULLY_DISCONNECTED. Instead of bypassing all down‐
7349 load and update logic, FETCHCONTENT_UPDATES_DISCONNECTED only
7350 prevents the update step from making connections to remote
7351 servers when using the git or hg download methods. Updates
7352 still occur if details about the update step change, but the up‐
7353 date is attempted with only the information already available
7354 locally (so switching to a different tag or commit that is al‐
7355 ready fetched locally will succeed, but switching to an unknown
7356 commit hash will fail). The download step is not affected, so
7357 if content has not been downloaded previously, it will still be
7358 downloaded when this option is enabled. This can speed up the
7359 configure step, but not as much as
7360 FETCHCONTENT_FULLY_DISCONNECTED. FETCHCONTENT_UPDATES_DISCON‐
7361 NECTED is OFF by default.
7362 FETCHCONTENT_TRY_FIND_PACKAGE_MODE
7364 New in version 3.24.
7365 This variable modifies the details that FetchContent_Declare()
7368 records for a given dependency. While it ultimately controls
7369 the behavior of FetchContent_MakeAvailable(), it is the vari‐
7370 able's value when FetchContent_Declare() is called that gets
7371 used. It makes no difference what the variable is set to when
7372 FetchContent_MakeAvailable() is called. Since the variable
7373 should only be set by the user and not by projects directly, it
7374 will typically have the same value throughout anyway, so this
7375 distinction is not usually noticeable.
7376 FETCHCONTENT_TRY_FIND_PACKAGE_MODE ultimately controls whether
7378 FetchContent_MakeAvailable() is allowed to call find_package()
7379 to satisfy a dependency. The variable can be set to one of the
7380 following values:
7381 OPT_IN FetchContent_MakeAvailable() will only call
7383 find_package() if the FetchContent_Declare() call in‐
7384 cluded a FIND_PACKAGE_ARGS keyword. This is also the de‐
7385 fault behavior if FETCHCONTENT_TRY_FIND_PACKAGE_MODE is
7386 not set.
7387 ALWAYS find_package() can be called by
7389 FetchContent_MakeAvailable() regardless of whether the
7390 FetchContent_Declare() call included a FIND_PACKAGE_ARGS
7391 keyword or not. If no FIND_PACKAGE_ARGS keyword was
7392 given, the behavior will be as though FIND_PACKAGE_ARGS
7393 had been provided, with no additional arguments after it.
7394 NEVER FetchContent_MakeAvailable() will not call
7396 find_package(). Any FIND_PACKAGE_ARGS given to the
7397 FetchContent_Declare() call will be ignored.
7398 As a special case, if the
7400 FETCHCONTENT_SOURCE_DIR_<uppercaseName> variable has a non-empty
7401 value for a dependency, it is assumed that the user is overrid‐
7402 ing all other methods of making that dependency available.
7403 FETCHCONTENT_TRY_FIND_PACKAGE_MODE will have no effect on that
7404 dependency and FetchContent_MakeAvailable() will not try to call
7405 find_package() for it.
7406 In addition to the above, the following variables are also defined for
7408 each content name:
7409 FETCHCONTENT_SOURCE_DIR_<uppercaseName>
7411 If this is set, no download or update steps are performed for
7412 the specified content and the <lowercaseName>_SOURCE_DIR vari‐
7413 able returned to the caller is pointed at this location. This
7414 gives developers a way to have a separate checkout of the con‐
7415 tent that they can modify freely without interference from the
7416 build. The build simply uses that existing source, but it still
7417 defines <lowercaseName>_BINARY_DIR to point inside its own build
7418 area. Developers are strongly encouraged to use this mechanism
7419 rather than editing the sources populated in the default loca‐
7420 tion, as changes to sources in the default location can be lost
7421 when content population details are changed by the project.
7422 FETCHCONTENT_UPDATES_DISCONNECTED_<uppercaseName>
7424 This is the per-content equivalent of
7425 FETCHCONTENT_UPDATES_DISCONNECTED. If the global option or this
7426 option is ON, then updates for the git and hg methods will not
7427 contact any remote for the named content. They will only use
7428 information already available locally. Disabling updates for
7429 individual content can be useful for content whose details
7430 rarely change, while still leaving other frequently changing
7431 content with updates enabled.
7432 Examples
7434 Typical Case
7435 This first fairly straightforward example ensures that some popular
7436 testing frameworks are available to the main build:
7437 include(FetchContent)
7439 FetchContent_Declare(
7440 googletest
7441 GIT_REPOSITORY https://github.com/google/googletest.git
7442 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
7443 )
7444 FetchContent_Declare(
7445 Catch2
7446 GIT_REPOSITORY https://github.com/catchorg/Catch2.git
7447 GIT_TAG 605a34765aa5d5ecbf476b4598a862ada971b0cc # v3.0.1
7448 )
7449 # After the following call, the CMake targets defined by googletest and
7451 # Catch2 will be available to the rest of the build
7452 FetchContent_MakeAvailable(googletest Catch2)
7453 Integrating With find_package()
7455 For the previous example, if the user wanted to try to find googletest
7456 and Catch2 via find_package() first before trying to download and build
7457 them from source, they could set the FETCHCONTENT_TRY_FIND_PACKAGE_MODE
7458 variable to ALWAYS. This would also affect any other calls to
7459 FetchContent_Declare() throughout the project, which might not be ac‐
7460 ceptable. The behavior can be enabled for just these two dependencies
7461 instead by adding FIND_PACKAGE_ARGS to the declared details and leaving
7462 FETCHCONTENT_TRY_FIND_PACKAGE_MODE unset, or set to OPT_IN:
7463 include(FetchContent)
7465 FetchContent_Declare(
7466 googletest
7467 GIT_REPOSITORY https://github.com/google/googletest.git
7468 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
7469 FIND_PACKAGE_ARGS NAMES GTest
7470 )
7471 FetchContent_Declare(
7472 Catch2
7473 GIT_REPOSITORY https://github.com/catchorg/Catch2.git
7474 GIT_TAG 605a34765aa5d5ecbf476b4598a862ada971b0cc # v3.0.1
7475 FIND_PACKAGE_ARGS
7476 )
7477 # This will try calling find_package() first for both dependencies
7479 FetchContent_MakeAvailable(googletest Catch2)
7480 For Catch2, no additional arguments to find_package() are needed, so no
7482 additional arguments are provided after the FIND_PACKAGE_ARGS keyword.
7483 For googletest, its package is more commonly called GTest, so arguments
7484 are added to support it being found by that name.
7485 If the user wanted to disable FetchContent_MakeAvailable() from calling
7487 find_package() for any dependency, even if it provided FIND_PACK‐
7488 AGE_ARGS in its declared details, they could set
7489 FETCHCONTENT_TRY_FIND_PACKAGE_MODE to NEVER.
7490 If the project wanted to indicate that these two dependencies should be
7492 downloaded and built from source and that find_package() calls should
7493 be redirected to use the built dependencies, the OVERRIDE_FIND_PACKAGE
7494 option should be used when declaring the content details:
7495 include(FetchContent)
7497 FetchContent_Declare(
7498 googletest
7499 GIT_REPOSITORY https://github.com/google/googletest.git
7500 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
7501 OVERRIDE_FIND_PACKAGE
7502 )
7503 FetchContent_Declare(
7504 Catch2
7505 GIT_REPOSITORY https://github.com/catchorg/Catch2.git
7506 GIT_TAG 605a34765aa5d5ecbf476b4598a862ada971b0cc # v3.0.1
7507 OVERRIDE_FIND_PACKAGE
7508 )
7509 # The following will automatically forward through to FetchContent_MakeAvailable()
7511 find_package(googletest)
7512 find_package(Catch2)
7513 CMake provides a FindGTest module which defines some variables that
7515 older projects may use instead of linking to the imported targets. To
7516 support those cases, we can provide an extra file. In keeping with the
7517 "first to define, wins" philosophy of FetchContent, we only write out
7518 that file if something else hasn't already done so.
7519 FetchContent_MakeAvailable(googletest)
7521 if(NOT EXISTS ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/googletest-extra.cmake AND
7523 NOT EXISTS ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/googletestExtra.cmake)
7524 file(WRITE ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/googletest-extra.cmake
7525 [=[
7526 if("${GTEST_LIBRARIES}" STREQUAL "" AND TARGET GTest::gtest)
7527 set(GTEST_LIBRARIES GTest::gtest)
7528 endif()
7529 if("${GTEST_MAIN_LIBRARIES}" STREQUAL "" AND TARGET GTest::gtest_main)
7530 set(GTEST_MAIN_LIBRARIES GTest::gtest_main)
7531 endif()
7532 if("${GTEST_BOTH_LIBRARIES}" STREQUAL "")
7533 set(GTEST_BOTH_LIBRARIES ${GTEST_LIBRARIES} ${GTEST_MAIN_LIBRARIES})
7534 endif()
7535 ]=])
7536 endif()
7537 Projects will also likely be using find_package(GTest) rather than
7539 find_package(googletest), but it is possible to make use of the
7540 CMAKE_FIND_PACKAGE_REDIRECTS_DIR area to pull in the latter as a depen‐
7541 dency of the former. This is likely to be sufficient to satisfy a typ‐
7542 ical find_package(GTest) call.
7543 FetchContent_MakeAvailable(googletest)
7545 if(NOT EXISTS ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/gtest-config.cmake AND
7547 NOT EXISTS ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/GTestConfig.cmake)
7548 file(WRITE ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/gtest-config.cmake
7549 [=[
7550 include(CMakeFindDependencyMacro)
7551 find_dependency(googletest)
7552 ]=])
7553 endif()
7554 if(NOT EXISTS ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/gtest-config-version.cmake AND
7556 NOT EXISTS ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/GTestConfigVersion.cmake)
7557 file(WRITE ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/gtest-config-version.cmake
7558 [=[
7559 include(${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/googletest-config-version.cmake OPTIONAL)
7560 if(NOT PACKAGE_VERSION_COMPATIBLE)
7561 include(${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/googletestConfigVersion.cmake OPTIONAL)
7562 endif()
7563 ]=])
7564 endif()
7565 Overriding Where To Find CMakeLists.txt
7567 If the sub-project's CMakeLists.txt file is not at the top level of its
7568 source tree, the SOURCE_SUBDIR option can be used to tell FetchContent
7569 where to find it. The following example shows how to use that option,
7570 and it also sets a variable which is meaningful to the subproject be‐
7571 fore pulling it into the main build (set as an INTERNAL cache variable
7572 to avoid problems with policy CMP0077):
7573 include(FetchContent)
7575 FetchContent_Declare(
7576 protobuf
7577 GIT_REPOSITORY https://github.com/protocolbuffers/protobuf.git
7578 GIT_TAG ae50d9b9902526efd6c7a1907d09739f959c6297 # v3.15.0
7579 SOURCE_SUBDIR cmake
7580 )
7581 set(protobuf_BUILD_TESTS OFF CACHE INTERNAL "")
7582 FetchContent_MakeAvailable(protobuf)
7583 Complex Dependency Hierarchies
7585 In more complex project hierarchies, the dependency relationships can
7586 be more complicated. Consider a hierarchy where projA is the top level
7587 project and it depends directly on projects projB and projC. Both
7588 projB and projC can be built standalone and they also both depend on
7589 another project projD. projB additionally depends on projE. This ex‐
7590 ample assumes that all five projects are available on a company git
7591 server. The CMakeLists.txt of each project might have sections like
7592 the following:
7593 projA
7595 include(FetchContent)
7597 FetchContent_Declare(
7598 projB
7599 GIT_REPOSITORY git@mycompany.com:git/projB.git
7600 GIT_TAG 4a89dc7e24ff212a7b5167bef7ab079d
7601 )
7602 FetchContent_Declare(
7603 projC
7604 GIT_REPOSITORY git@mycompany.com:git/projC.git
7605 GIT_TAG 4ad4016bd1d8d5412d135cf8ceea1bb9
7606 )
7607 FetchContent_Declare(
7608 projD
7609 GIT_REPOSITORY git@mycompany.com:git/projD.git
7610 GIT_TAG origin/integrationBranch
7611 )
7612 FetchContent_Declare(
7613 projE
7614 GIT_REPOSITORY git@mycompany.com:git/projE.git
7615 GIT_TAG v2.3-rc1
7616 )
7617 # Order is important, see notes in the discussion further below
7619 FetchContent_MakeAvailable(projD projB projC)
7620 projB
7622 include(FetchContent)
7624 FetchContent_Declare(
7625 projD
7626 GIT_REPOSITORY git@mycompany.com:git/projD.git
7627 GIT_TAG 20b415f9034bbd2a2e8216e9a5c9e632
7628 )
7629 FetchContent_Declare(
7630 projE
7631 GIT_REPOSITORY git@mycompany.com:git/projE.git
7632 GIT_TAG 68e20f674a48be38d60e129f600faf7d
7633 )
7634 FetchContent_MakeAvailable(projD projE)
7636 projC
7638 include(FetchContent)
7640 FetchContent_Declare(
7641 projD
7642 GIT_REPOSITORY git@mycompany.com:git/projD.git
7643 GIT_TAG 7d9a17ad2c962aa13e2fbb8043fb6b8a
7644 )
7645 # This particular version of projD requires workarounds
7647 FetchContent_GetProperties(projD)
7648 if(NOT projd_POPULATED)
7649 FetchContent_Populate(projD)
7650 # Copy an additional/replacement file into the populated source
7652 file(COPY someFile.c DESTINATION ${projd_SOURCE_DIR}/src)
7653 add_subdirectory(${projd_SOURCE_DIR} ${projd_BINARY_DIR})
7655 endif()
7656 A few key points should be noted in the above:
7658 • projB and projC define different content details for projD, but projA
7660 also defines a set of content details for projD. Because projA will
7661 define them first, the details from projB and projC will not be used.
7662 The override details defined by projA are not required to match ei‐
7663 ther of those from projB or projC, but it is up to the higher level
7664 project to ensure that the details it does define still make sense
7665 for the child projects.
7666 • In the projA call to FetchContent_MakeAvailable(), projD is listed
7668 ahead of projB and projC to ensure that projA is in control of how
7669 projD is populated.
7670 • While projA defines content details for projE, it does not need to
7672 explicitly call FetchContent_MakeAvailable(projE) or FetchCon‐
7673 tent_Populate(projD) itself. Instead, it leaves that to the child
7674 projB. For higher level projects, it is often enough to just define
7675 the override content details and leave the actual population to the
7676 child projects. This saves repeating the same thing at each level of
7677 the project hierarchy unnecessarily.
7678 Populating Content Without Adding It To The Build
7680 Projects don't always need to add the populated content to the build.
7681 Sometimes the project just wants to make the downloaded content avail‐
7682 able at a predictable location. The next example ensures that a set of
7683 standard company toolchain files (and potentially even the toolchain
7684 binaries themselves) is available early enough to be used for that same
7685 build.
7686 cmake_minimum_required(VERSION 3.14)
7688 include(FetchContent)
7690 FetchContent_Declare(
7691 mycom_toolchains
7692 URL https://intranet.mycompany.com//toolchains_1.3.2.tar.gz
7693 )
7694 FetchContent_MakeAvailable(mycom_toolchains)
7695 project(CrossCompileExample)
7697 The project could be configured to use one of the downloaded toolchains
7699 like so:
7700 cmake -DCMAKE_TOOLCHAIN_FILE=_deps/mycom_toolchains-src/toolchain_arm.cmake /path/to/src
7702 When CMake processes the CMakeLists.txt file, it will download and un‐
7704 pack the tarball into _deps/mycompany_toolchains-src relative to the
7705 build directory. The CMAKE_TOOLCHAIN_FILE variable is not used until
7706 the project() command is reached, at which point CMake looks for the
7707 named toolchain file relative to the build directory. Because the tar‐
7708 ball has already been downloaded and unpacked by then, the toolchain
7709 file will be in place, even the very first time that cmake is run in
7710 the build directory.
7711 Populating Content In CMake Script Mode
7713 This last example demonstrates how one might download and unpack a
7714 firmware tarball using CMake's script mode. The call to
7715 FetchContent_Populate() specifies all the content details and the un‐
7716 packed firmware will be placed in a firmware directory below the cur‐
7717 rent working directory.
7718 getFirmware.cmake
7720 # NOTE: Intended to be run in script mode with cmake -P
7722 include(FetchContent)
7723 FetchContent_Populate(
7724 firmware
7725 URL https://mycompany.com/assets/firmware-1.23-arm.tar.gz
7726 URL_HASH MD5=68247684da89b608d466253762b0ff11
7727 SOURCE_DIR firmware
7728 )
7729 FindPackageHandleStandardArgs
7731 This module provides functions intended to be used in Find Modules im‐
7732 plementing find_package(<PackageName>) calls.
7733 find_package_handle_standard_args
7735 This command handles the REQUIRED, QUIET and version-related ar‐
7736 guments of find_package(). It also sets the <PackageName>_FOUND
7737 variable. The package is considered found if all variables
7738 listed contain valid results, e.g. valid filepaths.
7739 There are two signatures:
7741 find_package_handle_standard_args(<PackageName>
7743 (DEFAULT_MSG|<custom-failure-message>)
7744 <required-var>...
7745 )
7746 find_package_handle_standard_args(<PackageName>
7748 [FOUND_VAR <result-var>]
7749 [REQUIRED_VARS <required-var>...]
7750 [VERSION_VAR <version-var>]
7751 [HANDLE_VERSION_RANGE]
7752 [HANDLE_COMPONENTS]
7753 [CONFIG_MODE]
7754 [NAME_MISMATCHED]
7755 [REASON_FAILURE_MESSAGE <reason-failure-message>]
7756 [FAIL_MESSAGE <custom-failure-message>]
7757 )
7758 The <PackageName>_FOUND variable will be set to TRUE if all the
7760 variables <required-var>... are valid and any optional con‐
7761 straints are satisfied, and FALSE otherwise. A success or fail‐
7762 ure message may be displayed based on the results and on whether
7763 the REQUIRED and/or QUIET option was given to the find_package()
7764 call.
7765 The options are:
7767 (DEFAULT_MSG|<custom-failure-message>)
7769 In the simple signature this specifies the failure mes‐
7770 sage. Use DEFAULT_MSG to ask for a default message to be
7771 computed (recommended). Not valid in the full signature.
7772 FOUND_VAR <result-var>
7774 Deprecated since version 3.3.
7775 Specifies either <PackageName>_FOUND or <PACKAGE‐
7778 NAME>_FOUND as the result variable. This exists only for
7779 compatibility with older versions of CMake and is now ig‐
7780 nored. Result variables of both names are always set for
7781 compatibility.
7782 REQUIRED_VARS <required-var>...
7784 Specify the variables which are required for this pack‐
7785 age. These may be named in the generated failure message
7786 asking the user to set the missing variable values.
7787 Therefore these should typically be cache entries such as
7788 FOO_LIBRARY and not output variables like FOO_LIBRARIES.
7789 Changed in version 3.18: If HANDLE_COMPONENTS is speci‐
7791 fied, this option can be omitted.
7792 VERSION_VAR <version-var>
7795 Specify the name of a variable that holds the version of
7796 the package that has been found. This version will be
7797 checked against the (potentially) specified required ver‐
7798 sion given to the find_package() call, including its EX‐
7799 ACT option. The default messages include information
7800 about the required version and the version which has been
7801 actually found, both if the version is ok or not.
7802 HANDLE_VERSION_RANGE
7804 New in version 3.19.
7805 Enable handling of a version range, if one is specified.
7808 Without this option, a developer warning will be dis‐
7809 played if a version range is specified.
7810 HANDLE_COMPONENTS
7812 Enable handling of package components. In this case, the
7813 command will report which components have been found and
7814 which are missing, and the <PackageName>_FOUND variable
7815 will be set to FALSE if any of the required components
7816 (i.e. not the ones listed after the OPTIONAL_COMPONENTS
7817 option of find_package()) are missing.
7818 CONFIG_MODE
7820 Specify that the calling find module is a wrapper around
7821 a call to find_package(<PackageName> NO_MODULE). This
7822 implies a VERSION_VAR value of <PackageName>_VERSION.
7823 The command will automatically check whether the package
7824 configuration file was found.
7825 REASON_FAILURE_MESSAGE <reason-failure-message>
7827 New in version 3.16.
7828 Specify a custom message of the reason for the failure
7831 which will be appended to the default generated message.
7832 FAIL_MESSAGE <custom-failure-message>
7834 Specify a custom failure message instead of using the de‐
7835 fault generated message. Not recommended.
7836 NAME_MISMATCHED
7838 New in version 3.17.
7839 Indicate that the <PackageName> does not match
7842 ${CMAKE_FIND_PACKAGE_NAME}. This is usually a mistake and
7843 raises a warning, but it may be intentional for usage of
7844 the command for components of a larger package.
7845 Example for the simple signature:
7847 find_package_handle_standard_args(LibXml2 DEFAULT_MSG
7849 LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
7850 The LibXml2 package is considered to be found if both LIBXML2_LIBRARY
7852 and LIBXML2_INCLUDE_DIR are valid. Then also LibXml2_FOUND is set to
7853 TRUE. If it is not found and REQUIRED was used, it fails with a
7854 message(FATAL_ERROR), independent whether QUIET was used or not. If it
7855 is found, success will be reported, including the content of the first
7856 <required-var>. On repeated CMake runs, the same message will not be
7857 printed again.
7858 NOTE:
7860 If <PackageName> does not match CMAKE_FIND_PACKAGE_NAME for the
7861 calling module, a warning that there is a mismatch is given. The
7862 FPHSA_NAME_MISMATCHED variable may be set to bypass the warning if
7863 using the old signature and the NAME_MISMATCHED argument using the
7864 new signature. To avoid forcing the caller to require newer versions
7865 of CMake for usage, the variable's value will be used if defined
7866 when the NAME_MISMATCHED argument is not passed for the new signa‐
7867 ture (but using both is an error)..
7868 Example for the full signature:
7870 find_package_handle_standard_args(LibArchive
7872 REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
7873 VERSION_VAR LibArchive_VERSION)
7874 In this case, the LibArchive package is considered to be found if both
7876 LibArchive_LIBRARY and LibArchive_INCLUDE_DIR are valid. Also the ver‐
7877 sion of LibArchive will be checked by using the version contained in
7878 LibArchive_VERSION. Since no FAIL_MESSAGE is given, the default mes‐
7879 sages will be printed.
7880 Another example for the full signature:
7882 find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
7884 find_package_handle_standard_args(Automoc4 CONFIG_MODE)
7885 In this case, a FindAutmoc4.cmake module wraps a call to find_pack‐
7887 age(Automoc4 NO_MODULE) and adds an additional search directory for au‐
7888 tomoc4. Then the call to find_package_handle_standard_args produces a
7889 proper success/failure message.
7890 find_package_check_version
7892 New in version 3.19.
7893 Helper function which can be used to check if a <version> is
7896 valid against version-related arguments of find_package().
7897 find_package_check_version(<version> <result-var>
7899 [HANDLE_VERSION_RANGE]
7900 [RESULT_MESSAGE_VARIABLE <message-var>]
7901 )
7902 The <result-var> will hold a boolean value giving the result of
7904 the check.
7905 The options are:
7907 HANDLE_VERSION_RANGE
7909 Enable handling of a version range, if one is specified.
7910 Without this option, a developer warning will be dis‐
7911 played if a version range is specified.
7912 RESULT_MESSAGE_VARIABLE <message-var>
7914 Specify a variable to get back a message describing the
7915 result of the check.
7916 Example for the usage:
7918 find_package_check_version(1.2.3 result HANDLE_VERSION_RANGE
7920 RESULT_MESSAGE_VARIABLE reason)
7921 if (result)
7922 message (STATUS "${reason}")
7923 else()
7924 message (FATAL_ERROR "${reason}")
7925 endif()
7926 FindPackageMessage
7928 find_package_message(<name> "message for user" "find result details")
7929 This function is intended to be used in FindXXX.cmake modules files.
7931 It will print a message once for each unique find result. This is use‐
7932 ful for telling the user where a package was found. The first argument
7933 specifies the name (XXX) of the package. The second argument specifies
7934 the message to display. The third argument lists details about the
7935 find result so that if they change the message will be displayed again.
7936 The macro also obeys the QUIET argument to the find_package command.
7937 Example:
7939 if(X11_FOUND)
7941 find_package_message(X11 "Found X11: ${X11_X11_LIB}"
7942 "[${X11_X11_LIB}][${X11_INCLUDE_DIR}]")
7943 else()
7944 ...
7945 endif()
7946 FortranCInterface
7948 Fortran/C Interface Detection
7949 This module automatically detects the API by which C and Fortran lan‐
7951 guages interact.
7952 Module Variables
7954 Variables that indicate if the mangling is found:
7955 FortranCInterface_GLOBAL_FOUND
7957 Global subroutines and functions.
7958 FortranCInterface_MODULE_FOUND
7960 Module subroutines and functions (declared by "MODULE PROCE‐
7961 DURE").
7962 This module also provides the following variables to specify the de‐
7964 tected mangling, though a typical use case does not need to reference
7965 them and can use the Module Functions below.
7966 FortranCInterface_GLOBAL_PREFIX
7968 Prefix for a global symbol without an underscore.
7969 FortranCInterface_GLOBAL_SUFFIX
7971 Suffix for a global symbol without an underscore.
7972 FortranCInterface_GLOBAL_CASE
7974 The case for a global symbol without an underscore, either UPPER
7975 or LOWER.
7976 FortranCInterface_GLOBAL__PREFIX
7978 Prefix for a global symbol with an underscore.
7979 FortranCInterface_GLOBAL__SUFFIX
7981 Suffix for a global symbol with an underscore.
7982 FortranCInterface_GLOBAL__CASE
7984 The case for a global symbol with an underscore, either UPPER or
7985 LOWER.
7986 FortranCInterface_MODULE_PREFIX
7988 Prefix for a module symbol without an underscore.
7989 FortranCInterface_MODULE_MIDDLE
7991 Middle of a module symbol without an underscore that appears be‐
7992 tween the name of the module and the name of the symbol.
7993 FortranCInterface_MODULE_SUFFIX
7995 Suffix for a module symbol without an underscore.
7996 FortranCInterface_MODULE_CASE
7998 The case for a module symbol without an underscore, either UPPER
7999 or LOWER.
8000 FortranCInterface_MODULE__PREFIX
8002 Prefix for a module symbol with an underscore.
8003 FortranCInterface_MODULE__MIDDLE
8005 Middle of a module symbol with an underscore that appears be‐
8006 tween the name of the module and the name of the symbol.
8007 FortranCInterface_MODULE__SUFFIX
8009 Suffix for a module symbol with an underscore.
8010 FortranCInterface_MODULE__CASE
8012 The case for a module symbol with an underscore, either UPPER or
8013 LOWER.
8014 Module Functions
8016 FortranCInterface_HEADER
8017 The FortranCInterface_HEADER function is provided to generate a
8018 C header file containing macros to mangle symbol names:
8019 FortranCInterface_HEADER(<file>
8021 [MACRO_NAMESPACE <macro-ns>]
8022 [SYMBOL_NAMESPACE <ns>]
8023 [SYMBOLS [<module>:]<function> ...])
8024 It generates in <file> definitions of the following macros:
8026 #define FortranCInterface_GLOBAL (name,NAME) ...
8028 #define FortranCInterface_GLOBAL_(name,NAME) ...
8029 #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
8030 #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
8031 These macros mangle four categories of Fortran symbols, respec‐
8033 tively:
8034 • Global symbols without '_': call mysub()
8036 • Global symbols with '_' : call my_sub()
8038 • Module symbols without '_': use mymod; call mysub()
8040 • Module symbols with '_' : use mymod; call my_sub()
8042 If mangling for a category is not known, its macro is left unde‐
8044 fined. All macros require raw names in both lower case and up‐
8045 per case.
8046 The options are:
8048 MACRO_NAMESPACE
8050 Replace the default FortranCInterface_ prefix with a
8051 given namespace <macro-ns>.
8052 SYMBOLS
8054 List symbols to mangle automatically with C preprocessor
8055 definitions:
8056 <function> ==> #define <ns><function> ...
8058 <module>:<function> ==> #define <ns><module>_<function> ...
8059 If the mangling for some symbol is not known then no pre‐
8061 processor definition is created, and a warning is dis‐
8062 played.
8063 SYMBOL_NAMESPACE
8065 Prefix all preprocessor definitions generated by the SYM‐
8066 BOLS option with a given namespace <ns>.
8067 FortranCInterface_VERIFY
8069 The FortranCInterface_VERIFY function is provided to verify that
8070 the Fortran and C/C++ compilers work together:
8071 FortranCInterface_VERIFY([CXX] [QUIET])
8073 It tests whether a simple test executable using Fortran and C
8075 (and C++ when the CXX option is given) compiles and links suc‐
8076 cessfully. The result is stored in the cache entry FortranCIn‐
8077 terface_VERIFIED_C (or FortranCInterface_VERIFIED_CXX if CXX is
8078 given) as a boolean. If the check fails and QUIET is not given
8079 the function terminates with a fatal error message describing
8080 the problem. The purpose of this check is to stop a build early
8081 for incompatible compiler combinations. The test is built in
8082 the Release configuration.
8083 Example Usage
8085 include(FortranCInterface)
8086 FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
8087 This creates a "FC.h" header that defines mangling macros FC_GLOBAL(),
8089 FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
8090 include(FortranCInterface)
8092 FortranCInterface_HEADER(FCMangle.h
8093 MACRO_NAMESPACE "FC_"
8094 SYMBOL_NAMESPACE "FC_"
8095 SYMBOLS mysub mymod:my_sub)
8096 This creates a "FCMangle.h" header that defines the same FC_*() man‐
8098 gling macros as the previous example plus preprocessor symbols FC_mysub
8099 and FC_mymod_my_sub.
8100 Additional Manglings
8102 FortranCInterface is aware of possible GLOBAL and MODULE manglings for
8103 many Fortran compilers, but it also provides an interface to specify
8104 new possible manglings. Set the variables:
8105 FortranCInterface_GLOBAL_SYMBOLS
8107 FortranCInterface_MODULE_SYMBOLS
8108 before including FortranCInterface to specify manglings of the symbols
8110 MySub, My_Sub, MyModule:MySub, and My_Module:My_Sub. For example, the
8111 code:
8112 set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
8114 # ^^^^^ ^^^^^^ ^^^^^
8115 set(FortranCInterface_MODULE_SYMBOLS
8116 __mymodule_MOD_mysub __my_module_MOD_my_sub)
8117 # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^
8118 include(FortranCInterface)
8119 tells FortranCInterface to try given GLOBAL and MODULE manglings. (The
8121 carets point at raw symbol names for clarity in this example but are
8122 not needed.)
8123 GenerateExportHeader
8125 Function for generation of export macros for libraries
8126 This module provides the function GENERATE_EXPORT_HEADER().
8128 New in version 3.12: Added support for C projects. Previous versions
8130 supported C++ project only.
8131 The GENERATE_EXPORT_HEADER function can be used to generate a file
8134 suitable for preprocessor inclusion which contains EXPORT macros to be
8135 used in library classes:
8136 GENERATE_EXPORT_HEADER( LIBRARY_TARGET
8138 [BASE_NAME <base_name>]
8139 [EXPORT_MACRO_NAME <export_macro_name>]
8140 [EXPORT_FILE_NAME <export_file_name>]
8141 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
8142 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
8143 [INCLUDE_GUARD_NAME <include_guard_name>]
8144 [STATIC_DEFINE <static_define>]
8145 [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
8146 [DEFINE_NO_DEPRECATED]
8147 [PREFIX_NAME <prefix_name>]
8148 [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
8149 )
8150 The target properties CXX_VISIBILITY_PRESET and
8152 VISIBILITY_INLINES_HIDDEN can be used to add the appropriate compile
8153 flags for targets. See the documentation of those target properties,
8154 and the convenience variables CMAKE_CXX_VISIBILITY_PRESET and
8155 CMAKE_VISIBILITY_INLINES_HIDDEN.
8156 By default GENERATE_EXPORT_HEADER() generates macro names in a file
8158 name determined by the name of the library. This means that in the
8159 simplest case, users of GenerateExportHeader will be equivalent to:
8160 set(CMAKE_CXX_VISIBILITY_PRESET hidden)
8162 set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
8163 add_library(somelib someclass.cpp)
8164 generate_export_header(somelib)
8165 install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR})
8166 install(FILES
8167 someclass.h
8168 ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${INCLUDE_INSTALL_DIR}
8169 )
8170 And in the ABI header files:
8172 #include "somelib_export.h"
8174 class SOMELIB_EXPORT SomeClass {
8175 ...
8176 };
8177 The CMake fragment will generate a file in the ${CMAKE_CURRENT_BI‐
8179 NARY_DIR} called somelib_export.h containing the macros SOMELIB_EXPORT,
8180 SOMELIB_NO_EXPORT, SOMELIB_DEPRECATED, SOMELIB_DEPRECATED_EXPORT and
8181 SOMELIB_DEPRECATED_NO_EXPORT. They will be followed by content taken
8182 from the variable specified by the CUSTOM_CONTENT_FROM_VARIABLE option,
8183 if any. The resulting file should be installed with other headers in
8184 the library.
8185 The BASE_NAME argument can be used to override the file name and the
8187 names used for the macros:
8188 add_library(somelib someclass.cpp)
8190 generate_export_header(somelib
8191 BASE_NAME other_name
8192 )
8193 Generates a file called other_name_export.h containing the macros
8195 OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT and OTHER_NAME_DEPRECATED etc.
8196 The BASE_NAME may be overridden by specifying other options in the
8198 function. For example:
8199 add_library(somelib someclass.cpp)
8201 generate_export_header(somelib
8202 EXPORT_MACRO_NAME OTHER_NAME_EXPORT
8203 )
8204 creates the macro OTHER_NAME_EXPORT instead of SOMELIB_EXPORT, but
8206 other macros and the generated file name is as default:
8207 add_library(somelib someclass.cpp)
8209 generate_export_header(somelib
8210 DEPRECATED_MACRO_NAME KDE_DEPRECATED
8211 )
8212 creates the macro KDE_DEPRECATED instead of SOMELIB_DEPRECATED.
8214 If LIBRARY_TARGET is a static library, macros are defined without val‐
8216 ues.
8217 If the same sources are used to create both a shared and a static li‐
8219 brary, the uppercased symbol ${BASE_NAME}_STATIC_DEFINE should be used
8220 when building the static library:
8221 add_library(shared_variant SHARED ${lib_SRCS})
8223 add_library(static_variant ${lib_SRCS})
8224 generate_export_header(shared_variant BASE_NAME libshared_and_static)
8225 set_target_properties(static_variant PROPERTIES
8226 COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)
8227 This will cause the export macros to expand to nothing when building
8229 the static library.
8230 If DEFINE_NO_DEPRECATED is specified, then a macro ${BASE_NAME}_NO_DEP‐
8232 RECATED will be defined This macro can be used to remove deprecated
8233 code from preprocessor output:
8234 option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
8236 if (EXCLUDE_DEPRECATED)
8237 set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED)
8238 endif()
8239 generate_export_header(somelib ${NO_BUILD_DEPRECATED})
8240 And then in somelib:
8242 class SOMELIB_EXPORT SomeClass
8244 {
8245 public:
8246 #ifndef SOMELIB_NO_DEPRECATED
8247 SOMELIB_DEPRECATED void oldMethod();
8248 #endif
8249 };
8250 #ifndef SOMELIB_NO_DEPRECATED
8252 void SomeClass::oldMethod() { }
8253 #endif
8254 If PREFIX_NAME is specified, the argument will be used as a prefix to
8256 all generated macros.
8257 For example:
8259 generate_export_header(somelib PREFIX_NAME VTK_)
8261 Generates the macros VTK_SOMELIB_EXPORT etc.
8263 New in version 3.1: Library target can be an OBJECT library.
8265 New in version 3.7: Added the CUSTOM_CONTENT_FROM_VARIABLE option.
8268 New in version 3.11: Added the INCLUDE_GUARD_NAME option.
8271 ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
8274 Deprecated since version 3.0: Set the target properties
8276 CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HIDDEN instead.
8277 The ADD_COMPILER_EXPORT_FLAGS function adds -fvisibility=hidden to
8280 CMAKE_CXX_FLAGS if supported, and is a no-op on Windows which does not
8281 need extra compiler flags for exporting support. You may optionally
8282 pass a single argument to ADD_COMPILER_EXPORT_FLAGS that will be popu‐
8283 lated with the CXX_FLAGS required to enable visibility support for the
8284 compiler/architecture in use.
8285 GetPrerequisites
8287 Deprecated since version 3.16: Use file(GET_RUNTIME_DEPENDENCIES) in‐
8288 stead.
8289 Functions to analyze and list executable file prerequisites.
8292 This module provides functions to list the .dll, .dylib or .so files
8294 that an executable or shared library file depends on. (Its prerequi‐
8295 sites.)
8296 It uses various tools to obtain the list of required shared library
8298 files:
8299 dumpbin (Windows)
8301 objdump (MinGW on Windows)
8302 ldd (Linux/Unix)
8303 otool (Mac OSX)
8304 Changed in version 3.16: The tool specified by CMAKE_OBJDUMP will be
8306 used, if set.
8307 The following functions are provided by this module:
8310 get_prerequisites
8312 list_prerequisites
8313 list_prerequisites_by_glob
8314 gp_append_unique
8315 is_file_executable
8316 gp_item_default_embedded_path
8317 (projects can override with gp_item_default_embedded_path_override)
8318 gp_resolve_item
8319 (projects can override with gp_resolve_item_override)
8320 gp_resolved_file_type
8321 (projects can override with gp_resolved_file_type_override)
8322 gp_file_type
8323 GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse>
8325 <exepath> <dirs> [<rpaths>])
8326 Get the list of shared library files required by <target>. The list in
8328 the variable named <prerequisites_var> should be empty on first entry
8329 to this function. On exit, <prerequisites_var> will contain the list
8330 of required shared library files.
8331 <target> is the full path to an executable file. <prerequisites_var>
8333 is the name of a CMake variable to contain the results. <exclude_sys‐
8334 tem> must be 0 or 1 indicating whether to include or exclude "system"
8335 prerequisites. If <recurse> is set to 1 all prerequisites will be
8336 found recursively, if set to 0 only direct prerequisites are listed.
8337 <exepath> is the path to the top level executable used for @exe‐
8338 cutable_path replacement on the Mac. <dirs> is a list of paths where
8339 libraries might be found: these paths are searched first when a target
8340 without any path info is given. Then standard system locations are
8341 also searched: PATH, Framework locations, /usr/lib...
8342 New in version 3.14: The variable GET_PREREQUISITES_VERBOSE can be set
8344 to true to enable verbose output.
8345 LIST_PREREQUISITES(<target> [<recurse> [<exclude_system> [<verbose>]]])
8348 Print a message listing the prerequisites of <target>.
8350 <target> is the name of a shared library or executable target or the
8352 full path to a shared library or executable file. If <recurse> is set
8353 to 1 all prerequisites will be found recursively, if set to 0 only di‐
8354 rect prerequisites are listed. <exclude_system> must be 0 or 1 indi‐
8355 cating whether to include or exclude "system" prerequisites. With
8356 <verbose> set to 0 only the full path names of the prerequisites are
8357 printed, set to 1 extra information will be displayed.
8358 LIST_PREREQUISITES_BY_GLOB(<glob_arg> <glob_exp>)
8360 Print the prerequisites of shared library and executable files matching
8362 a globbing pattern. <glob_arg> is GLOB or GLOB_RECURSE and <glob_exp>
8363 is a globbing expression used with "file(GLOB" or "file(GLOB_RECURSE"
8364 to retrieve a list of matching files. If a matching file is exe‐
8365 cutable, its prerequisites are listed.
8366 Any additional (optional) arguments provided are passed along as the
8368 optional arguments to the list_prerequisites calls.
8369 GP_APPEND_UNIQUE(<list_var> <value>)
8371 Append <value> to the list variable <list_var> only if the value is not
8373 already in the list.
8374 IS_FILE_EXECUTABLE(<file> <result_var>)
8376 Return 1 in <result_var> if <file> is a binary executable, 0 otherwise.
8378 GP_ITEM_DEFAULT_EMBEDDED_PATH(<item> <default_embedded_path_var>)
8380 Return the path that others should refer to the item by when the item
8382 is embedded inside a bundle.
8383 Override on a per-project basis by providing a project-specific
8385 gp_item_default_embedded_path_override function.
8386 GP_RESOLVE_ITEM(<context> <item> <exepath> <dirs> <resolved_item_var>
8388 [<rpaths>])
8389 Resolve an item into an existing full path file.
8391 Override on a per-project basis by providing a project-specific gp_re‐
8393 solve_item_override function.
8394 GP_RESOLVED_FILE_TYPE(<original_file> <file> <exepath> <dirs> <type_var>
8396 [<rpaths>])
8397 Return the type of <file> with respect to <original_file>. String de‐
8399 scribing type of prerequisite is returned in variable named <type_var>.
8400 Use <exepath> and <dirs> if necessary to resolve non-absolute <file>
8402 values -- but only for non-embedded items.
8403 Possible types are:
8405 system
8407 local
8408 embedded
8409 other
8410 Override on a per-project basis by providing a project-specific gp_re‐
8412 solved_file_type_override function.
8413 GP_FILE_TYPE(<original_file> <file> <type_var>)
8415 Return the type of <file> with respect to <original_file>. String de‐
8417 scribing type of prerequisite is returned in variable named <type_var>.
8418 Possible types are:
8420 system
8422 local
8423 embedded
8424 other
8425 GNUInstallDirs
8427 Define GNU standard installation directories
8428 Provides install directory variables as defined by the GNU Coding Stan‐
8430 dards.
8431 Result Variables
8433 Inclusion of this module defines the following variables:
8434 CMAKE_INSTALL_<dir>
8436 Destination for files of a given type. This value may be passed to
8437 the DESTINATION options of install() commands for the corresponding
8438 file type. It should typically be a path relative to the installa‐
8439 tion prefix so that it can be converted to an absolute path in a re‐
8440 locatable way (see CMAKE_INSTALL_FULL_<dir>). However, an absolute
8441 path is also allowed.
8442 CMAKE_INSTALL_FULL_<dir>
8444 The absolute path generated from the corresponding CMAKE_IN‐
8445 STALL_<dir> value. If the value is not already an absolute path, an
8446 absolute path is constructed typically by prepending the value of
8447 the CMAKE_INSTALL_PREFIX variable. However, there are some special
8448 cases as documented below.
8449 where <dir> is one of:
8451 BINDIR user executables (bin)
8453 SBINDIR
8455 system admin executables (sbin)
8456 LIBEXECDIR
8458 program executables (libexec)
8459 SYSCONFDIR
8461 read-only single-machine data (etc)
8462 SHAREDSTATEDIR
8464 modifiable architecture-independent data (com)
8465 LOCALSTATEDIR
8467 modifiable single-machine data (var)
8468 RUNSTATEDIR
8470 New in version 3.9: run-time variable data (LOCALSTATEDIR/run)
8471 LIBDIR object code libraries (lib or lib64)
8474 On Debian, this may be lib/<multiarch-tuple> when
8476 CMAKE_INSTALL_PREFIX is /usr.
8477 INCLUDEDIR
8479 C header files (include)
8480 OLDINCLUDEDIR
8482 C header files for non-gcc (/usr/include)
8483 DATAROOTDIR
8485 read-only architecture-independent data root (share)
8486 DATADIR
8488 read-only architecture-independent data (DATAROOTDIR)
8489 INFODIR
8491 info documentation (DATAROOTDIR/info)
8492 LOCALEDIR
8494 locale-dependent data (DATAROOTDIR/locale)
8495 MANDIR man documentation (DATAROOTDIR/man)
8497 DOCDIR documentation root (DATAROOTDIR/doc/PROJECT_NAME)
8499 If the includer does not define a value the above-shown default will be
8501 used and the value will appear in the cache for editing by the user.
8502 Special Cases
8504 New in version 3.4.
8505 The following values of CMAKE_INSTALL_PREFIX are special:
8508 /
8510 For <dir> other than the SYSCONFDIR, LOCALSTATEDIR and RUNSTATEDIR,
8511 the value of CMAKE_INSTALL_<dir> is prefixed with usr/ if it is not
8512 user-specified as an absolute path. For example, the INCLUDEDIR
8513 value include becomes usr/include. This is required by the GNU Cod‐
8514 ing Standards, which state:
8515 When building the complete GNU system, the prefix will be empty
8516 and /usr will be a symbolic link to /.
8517 /usr
8519 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
8520 CMAKE_INSTALL_FULL_<dir> is computed by prepending just / to the
8521 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
8522 lute path. For example, the SYSCONFDIR value etc becomes /etc.
8523 This is required by the GNU Coding Standards.
8524 /opt/...
8526 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
8527 CMAKE_INSTALL_FULL_<dir> is computed by appending the prefix to the
8528 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
8529 lute path. For example, the SYSCONFDIR value etc becomes
8530 /etc/opt/.... This is defined by the Filesystem Hierarchy Standard.
8531 This behavior does not apply to paths under /opt/homebrew/....
8533 Macros
8535 GNUInstallDirs_get_absolute_install_dir
8536 GNUInstallDirs_get_absolute_install_dir(absvar var dirname)
8538 New in version 3.7.
8540 Set the given variable absvar to the absolute path contained
8543 within the variable var. This is to allow the computation of an
8544 absolute path, accounting for all the special cases documented
8545 above. While this macro is used to compute the various
8546 CMAKE_INSTALL_FULL_<dir> variables, it is exposed publicly to
8547 allow users who create additional path variables to also compute
8548 absolute paths where necessary, using the same logic. dirname
8549 is the directory name to get, e.g. BINDIR.
8550 Changed in version 3.20: Added the <dirname> parameter. Previ‐
8552 ous versions of CMake passed this value through the variable
8553 ${dir}.
8554 GoogleTest
8557 New in version 3.9.
8558 This module defines functions to help use the Google Test infrastruc‐
8561 ture. Two mechanisms for adding tests are provided. gtest_add_tests()
8562 has been around for some time, originally via find_package(GTest).
8563 gtest_discover_tests() was introduced in CMake 3.10.
8564 The (older) gtest_add_tests() scans source files to identify tests.
8566 This is usually effective, with some caveats, including in cross-com‐
8567 piling environments, and makes setting additional properties on tests
8568 more convenient. However, its handling of parameterized tests is less
8569 comprehensive, and it requires re-running CMake to detect changes to
8570 the list of tests.
8571 The (newer) gtest_discover_tests() discovers tests by asking the com‐
8573 piled test executable to enumerate its tests. This is more robust and
8574 provides better handling of parameterized tests, and does not require
8575 CMake to be re-run when tests change. However, it may not work in a
8576 cross-compiling environment, and setting test properties is less conve‐
8577 nient.
8578 More details can be found in the documentation of the respective func‐
8580 tions.
8581 Both commands are intended to replace use of add_test() to register
8583 tests, and will create a separate CTest test for each Google Test test
8584 case. Note that this is in some cases less efficient, as common set-up
8585 and tear-down logic cannot be shared by multiple test cases executing
8586 in the same instance. However, it provides more fine-grained pass/fail
8587 information to CTest, which is usually considered as more beneficial.
8588 By default, the CTest test name is the same as the Google Test name
8589 (i.e. suite.testcase); see also TEST_PREFIX and TEST_SUFFIX.
8590 gtest_add_tests
8592 Automatically add tests with CTest by scanning source code for
8593 Google Test macros:
8594 gtest_add_tests(TARGET target
8596 [SOURCES src1...]
8597 [EXTRA_ARGS arg1...]
8598 [WORKING_DIRECTORY dir]
8599 [TEST_PREFIX prefix]
8600 [TEST_SUFFIX suffix]
8601 [SKIP_DEPENDENCY]
8602 [TEST_LIST outVar]
8603 )
8604 gtest_add_tests attempts to identify tests by scanning source
8606 files. Although this is generally effective, it uses only a ba‐
8607 sic regular expression match, which can be defeated by atypical
8608 test declarations, and is unable to fully "split" parameterized
8609 tests. Additionally, it requires that CMake be re-run to dis‐
8610 cover any newly added, removed or renamed tests (by default,
8611 this means that CMake is re-run when any test source file is
8612 changed, but see SKIP_DEPENDENCY). However, it has the advan‐
8613 tage of declaring tests at CMake time, which somewhat simplifies
8614 setting additional properties on tests, and always works in a
8615 cross-compiling environment.
8616 The options are:
8618 TARGET target
8620 Specifies the Google Test executable, which must be a
8621 known CMake executable target. CMake will substitute the
8622 location of the built executable when running the test.
8623 SOURCES src1...
8625 When provided, only the listed files will be scanned for
8626 test cases. If this option is not given, the SOURCES
8627 property of the specified target will be used to obtain
8628 the list of sources.
8629 EXTRA_ARGS arg1...
8631 Any extra arguments to pass on the command line to each
8632 test case.
8633 WORKING_DIRECTORY dir
8635 Specifies the directory in which to run the discovered
8636 test cases. If this option is not provided, the current
8637 binary directory is used.
8638 TEST_PREFIX prefix
8640 Specifies a prefix to be prepended to the name of each
8641 discovered test case. This can be useful when the same
8642 source files are being used in multiple calls to
8643 gtest_add_test() but with different EXTRA_ARGS.
8644 TEST_SUFFIX suffix
8646 Similar to TEST_PREFIX except the suffix is appended to
8647 the name of every discovered test case. Both TEST_PREFIX
8648 and TEST_SUFFIX may be specified.
8649 SKIP_DEPENDENCY
8651 Normally, the function creates a dependency which will
8652 cause CMake to be re-run if any of the sources being
8653 scanned are changed. This is to ensure that the list of
8654 discovered tests is updated. If this behavior is not de‐
8655 sired (as may be the case while actually writing the test
8656 cases), this option can be used to prevent the dependency
8657 from being added.
8658 TEST_LIST outVar
8660 The variable named by outVar will be populated in the
8661 calling scope with the list of discovered test cases.
8662 This allows the caller to do things like manipulate test
8663 properties of the discovered tests.
8664 Usage example:
8666 include(GoogleTest)
8668 add_executable(FooTest FooUnitTest.cxx)
8669 gtest_add_tests(TARGET FooTest
8670 TEST_SUFFIX .noArgs
8671 TEST_LIST noArgsTests
8672 )
8673 gtest_add_tests(TARGET FooTest
8674 EXTRA_ARGS --someArg someValue
8675 TEST_SUFFIX .withArgs
8676 TEST_LIST withArgsTests
8677 )
8678 set_tests_properties(${noArgsTests} PROPERTIES TIMEOUT 10)
8679 set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20)
8680 For backward compatibility, the following form is also sup‐
8682 ported:
8683 gtest_add_tests(exe args files...)
8685 exe The path to the test executable or the name of a CMake
8687 target.
8688 args A ;-list of extra arguments to be passed to executable.
8690 The entire list must be passed as a single argument. En‐
8691 close it in quotes, or pass "" for no arguments.
8692 files...
8694 A list of source files to search for tests and test fix‐
8695 tures. Alternatively, use AUTO to specify that exe is
8696 the name of a CMake executable target whose sources
8697 should be scanned.
8698 include(GoogleTest)
8700 set(FooTestArgs --foo 1 --bar 2)
8701 add_executable(FooTest FooUnitTest.cxx)
8702 gtest_add_tests(FooTest "${FooTestArgs}" AUTO)
8703 gtest_discover_tests
8705 Automatically add tests with CTest by querying the compiled test
8706 executable for available tests:
8707 gtest_discover_tests(target
8709 [EXTRA_ARGS arg1...]
8710 [WORKING_DIRECTORY dir]
8711 [TEST_PREFIX prefix]
8712 [TEST_SUFFIX suffix]
8713 [TEST_FILTER expr]
8714 [NO_PRETTY_TYPES] [NO_PRETTY_VALUES]
8715 [PROPERTIES name1 value1...]
8716 [TEST_LIST var]
8717 [DISCOVERY_TIMEOUT seconds]
8718 [XML_OUTPUT_DIR dir]
8719 [DISCOVERY_MODE <POST_BUILD|PRE_TEST>]
8720 )
8721 New in version 3.10.
8723 gtest_discover_tests() sets up a post-build command on the test
8726 executable that generates the list of tests by parsing the out‐
8727 put from running the test with the --gtest_list_tests argument.
8728 Compared to the source parsing approach of gtest_add_tests(),
8729 this ensures that the full list of tests, including instantia‐
8730 tions of parameterized tests, is obtained. Since test discovery
8731 occurs at build time, it is not necessary to re-run CMake when
8732 the list of tests changes. However, it requires that
8733 CROSSCOMPILING_EMULATOR is properly set in order to function in
8734 a cross-compiling environment.
8735 Additionally, setting properties on tests is somewhat less con‐
8737 venient, since the tests are not available at CMake time. Addi‐
8738 tional test properties may be assigned to the set of tests as a
8739 whole using the PROPERTIES option. If more fine-grained test
8740 control is needed, custom content may be provided through an ex‐
8741 ternal CTest script using the TEST_INCLUDE_FILES directory prop‐
8742 erty. The set of discovered tests is made accessible to such a
8743 script via the <target>_TESTS variable.
8744 The options are:
8746 target Specifies the Google Test executable, which must be a
8748 known CMake executable target. CMake will substitute the
8749 location of the built executable when running the test.
8750 EXTRA_ARGS arg1...
8752 Any extra arguments to pass on the command line to each
8753 test case.
8754 WORKING_DIRECTORY dir
8756 Specifies the directory in which to run the discovered
8757 test cases. If this option is not provided, the current
8758 binary directory is used.
8759 TEST_PREFIX prefix
8761 Specifies a prefix to be prepended to the name of each
8762 discovered test case. This can be useful when the same
8763 test executable is being used in multiple calls to
8764 gtest_discover_tests() but with different EXTRA_ARGS.
8765 TEST_SUFFIX suffix
8767 Similar to TEST_PREFIX except the suffix is appended to
8768 the name of every discovered test case. Both TEST_PREFIX
8769 and TEST_SUFFIX may be specified.
8770 TEST_FILTER expr
8772 New in version 3.22.
8773 Filter expression to pass as a --gtest_filter argument
8776 during test discovery. Note that the expression is a
8777 wildcard-based format that matches against the original
8778 test names as used by gtest. For type or value-parame‐
8779 terized tests, these names may be different to the poten‐
8780 tially pretty-printed test names that ctest uses.
8781 NO_PRETTY_TYPES
8783 By default, the type index of type-parameterized tests is
8784 replaced by the actual type name in the CTest test name.
8785 If this behavior is undesirable (e.g. because the type
8786 names are unwieldy), this option will suppress this be‐
8787 havior.
8788 NO_PRETTY_VALUES
8790 By default, the value index of value-parameterized tests
8791 is replaced by the actual value in the CTest test name.
8792 If this behavior is undesirable (e.g. because the value
8793 strings are unwieldy), this option will suppress this be‐
8794 havior.
8795 PROPERTIES name1 value1...
8797 Specifies additional properties to be set on all tests
8798 discovered by this invocation of gtest_discover_tests().
8799 TEST_LIST var
8801 Make the list of tests available in the variable var,
8802 rather than the default <target>_TESTS. This can be use‐
8803 ful when the same test executable is being used in multi‐
8804 ple calls to gtest_discover_tests(). Note that this
8805 variable is only available in CTest.
8806 DISCOVERY_TIMEOUT num
8808 New in version 3.10.3.
8809 Specifies how long (in seconds) CMake will wait for the
8812 test to enumerate available tests. If the test takes
8813 longer than this, discovery (and your build) will fail.
8814 Most test executables will enumerate their tests very
8815 quickly, but under some exceptional circumstances, a test
8816 may require a longer timeout. The default is 5. See
8817 also the TIMEOUT option of execute_process().
8818 NOTE:
8820 In CMake versions 3.10.1 and 3.10.2, this option was
8821 called TIMEOUT. This clashed with the TIMEOUT test
8822 property, which is one of the common properties that
8823 would be set with the PROPERTIES keyword, usually
8824 leading to legal but unintended behavior. The keyword
8825 was changed to DISCOVERY_TIMEOUT in CMake 3.10.3 to
8826 address this problem. The ambiguous behavior of the
8827 TIMEOUT keyword in 3.10.1 and 3.10.2 has not been pre‐
8828 served.
8829 XML_OUTPUT_DIR dir
8831 New in version 3.18.
8832 If specified, the parameter is passed along with
8835 --gtest_output=xml: to test executable. The actual file
8836 name is the same as the test target, including prefix and
8837 suffix. This should be used instead of EXTRA_ARGS
8838 --gtest_output=xml to avoid race conditions writing the
8839 XML result output when using parallel test execution.
8840 DISCOVERY_MODE
8842 New in version 3.18.
8843 Provides greater control over when gtest_discover_tests()
8846 performs test discovery. By default, POST_BUILD sets up a
8847 post-build command to perform test discovery at build
8848 time. In certain scenarios, like cross-compiling, this
8849 POST_BUILD behavior is not desirable. By contrast,
8850 PRE_TEST delays test discovery until just prior to test
8851 execution. This way test discovery occurs in the target
8852 environment where the test has a better chance at finding
8853 appropriate runtime dependencies.
8854 DISCOVERY_MODE defaults to the value of the
8856 CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE variable if it
8857 is not passed when calling gtest_discover_tests(). This
8858 provides a mechanism for globally selecting a preferred
8859 test discovery behavior without having to modify each
8860 call site.
8861 InstallRequiredSystemLibraries
8863 Include this module to search for compiler-provided system runtime li‐
8864 braries and add install rules for them. Some optional variables may be
8865 set prior to including the module to adjust behavior:
8866 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS
8868 Specify additional runtime libraries that may not be detected.
8869 After inclusion any detected libraries will be appended to this.
8870 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP
8872 Set to TRUE to skip calling the install(PROGRAMS) command to al‐
8873 low the includer to specify its own install rule, using the
8874 value of CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS to get the list of
8875 libraries.
8876 CMAKE_INSTALL_DEBUG_LIBRARIES
8878 Set to TRUE to install the debug runtime libraries when avail‐
8879 able with MSVC tools.
8880 CMAKE_INSTALL_DEBUG_LIBRARIES_ONLY
8882 Set to TRUE to install only the debug runtime libraries with
8883 MSVC tools even if the release runtime libraries are also avail‐
8884 able.
8885 CMAKE_INSTALL_UCRT_LIBRARIES
8887 New in version 3.6.
8888 Set to TRUE to install the Windows Universal CRT libraries for
8891 app-local deployment (e.g. to Windows XP). This is meaningful
8892 only with MSVC from Visual Studio 2015 or higher.
8893 New in version 3.9: One may set a CMAKE_WINDOWS_KITS_10_DIR en‐
8895 vironment variable to an absolute path to tell CMake to look for
8896 Windows 10 SDKs in a custom location. The specified directory
8897 is expected to contain Redist/ucrt/DLLs/* directories.
8898 CMAKE_INSTALL_MFC_LIBRARIES
8901 Set to TRUE to install the MSVC MFC runtime libraries.
8902 CMAKE_INSTALL_OPENMP_LIBRARIES
8904 Set to TRUE to install the MSVC OpenMP runtime libraries
8905 CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION
8907 Specify the install(PROGRAMS) command DESTINATION option. If
8908 not specified, the default is bin on Windows and lib elsewhere.
8909 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_NO_WARNINGS
8911 Set to TRUE to disable warnings about required library files
8912 that do not exist. (For example, Visual Studio Express editions
8913 may not provide the redistributable files.)
8914 CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT
8916 New in version 3.3.
8917 Specify the install(PROGRAMS) command COMPONENT option. If not
8920 specified, no such option will be used.
8921 New in version 3.10: Support for installing Intel compiler runtimes.
8923 ProcessorCount
8926 ProcessorCount(var)
8927 Determine the number of processors/cores and save value in ${var}
8929 Sets the variable named ${var} to the number of physical cores avail‐
8931 able on the machine if the information can be determined. Otherwise it
8932 is set to 0. Currently this functionality is implemented for AIX, cyg‐
8933 win, FreeBSD, HPUX, Linux, macOS, QNX, Sun and Windows.
8934 Changed in version 3.15: On Linux, returns the container CPU count in‐
8936 stead of the host CPU count.
8937 This function is guaranteed to return a positive integer (>=1) if it
8940 succeeds. It returns 0 if there's a problem determining the processor
8941 count.
8942 More generally accurate physical CPU count can be obtained via
8944 cmake_host_system_information():
8945 cmake_host_system_information(RESULT N
8947 QUERY NUMBER_OF_PHYSICAL_CORES)
8948 Example use, in a ctest -S dashboard script:
8950 include(ProcessorCount)
8952 ProcessorCount(N)
8953 if(NOT N EQUAL 0)
8954 set(CTEST_BUILD_FLAGS -j${N})
8955 set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N})
8956 endif()
8957 This function is intended to offer an approximation of the value of the
8959 number of compute cores available on the current machine, such that you
8960 may use that value for parallel building and parallel testing. It is
8961 meant to help utilize as much of the machine as seems reasonable. Of
8962 course, knowledge of what else might be running on the machine simulta‐
8963 neously should be used when deciding whether to request a machine's
8964 full capacity all for yourself.
8965 SelectLibraryConfigurations
8967 select_library_configurations(basename)
8968 This macro takes a library base name as an argument, and will choose
8970 good values for the variables
8971 basename_LIBRARY
8973 basename_LIBRARIES
8974 basename_LIBRARY_DEBUG
8975 basename_LIBRARY_RELEASE
8976 depending on what has been found and set.
8978 If only basename_LIBRARY_RELEASE is defined, basename_LIBRARY will be
8980 set to the release value, and basename_LIBRARY_DEBUG will be set to
8981 basename_LIBRARY_DEBUG-NOTFOUND. If only basename_LIBRARY_DEBUG is de‐
8982 fined, then basename_LIBRARY will take the debug value, and base‐
8983 name_LIBRARY_RELEASE will be set to basename_LIBRARY_RELEASE-NOTFOUND.
8984 If the generator supports configuration types, then basename_LIBRARY
8986 and basename_LIBRARIES will be set with debug and optimized flags spec‐
8987 ifying the library to be used for the given configuration. If no build
8988 type has been set or the generator in use does not support configura‐
8989 tion types, then basename_LIBRARY and basename_LIBRARIES will take only
8990 the release value, or the debug value if the release one is not set.
8991 SquishTestScript
8993 This script launches a GUI test using Squish. You should not call the
8994 script directly; instead, you should access it via the SQUISH_ADD_TEST
8995 macro that is defined in FindSquish.cmake.
8996 This script starts the Squish server, launches the test on the client,
8998 and finally stops the squish server. If any of these steps fail (in‐
8999 cluding if the tests do not pass) then a fatal error is raised.
9000 TestBigEndian
9002 Deprecated since version 3.20: Supserseded by the
9003 CMAKE_<LANG>_BYTE_ORDER variable.
9004 Check if the target architecture is big endian or little endian.
9007 test_big_endian
9009 test_big_endian(<var>)
9011 Stores in variable <var> either 1 or 0 indicating whether the
9013 target architecture is big or little endian.
9014 TestForANSIForScope
9016 Check for ANSI for scope support
9017 Check if the compiler restricts the scope of variables declared in a
9019 for-init-statement to the loop body.
9020 CMAKE_NO_ANSI_FOR_SCOPE - holds result
9022 TestForANSIStreamHeaders
9024 Test for compiler support of ANSI stream headers iostream, etc.
9025 check if the compiler supports the standard ANSI iostream header (with‐
9027 out the .h)
9028 CMAKE_NO_ANSI_STREAM_HEADERS - defined by the results
9030 TestForSSTREAM
9032 Test for compiler support of ANSI sstream header
9033 check if the compiler supports the standard ANSI sstream header
9035 CMAKE_NO_ANSI_STRING_STREAM - defined by the results
9037 TestForSTDNamespace
9039 Test for std:: namespace support
9040 check if the compiler supports std:: on stl classes
9042 CMAKE_NO_STD_NAMESPACE - defined by the results
9044 UseEcos
9046 This module defines variables and macros required to build eCos appli‐
9047 cation.
9048 This file contains the following macros: ECOS_ADD_INCLUDE_DIRECTORIES()
9050 - add the eCos include dirs ECOS_ADD_EXECUTABLE(name source1 ...
9051 sourceN ) - create an eCos executable ECOS_ADJUST_DIRECTORY(VAR source1
9052 ... sourceN ) - adjusts the path of the source files and puts the re‐
9053 sult into VAR
9054 Macros for selecting the toolchain: ECOS_USE_ARM_ELF_TOOLS() - enable
9056 the ARM ELF toolchain for the directory where it is called
9057 ECOS_USE_I386_ELF_TOOLS() - enable the i386 ELF toolchain for the di‐
9058 rectory where it is called ECOS_USE_PPC_EABI_TOOLS() - enable the Pow‐
9059 erPC toolchain for the directory where it is called
9060 It contains the following variables: ECOS_DEFINITIONS ECOSCONFIG_EXE‐
9062 CUTABLE ECOS_CONFIG_FILE - defaults to ecos.ecc, if your eCos configu‐
9063 ration file has a different name, adjust this variable for internal use
9064 only:
9065 ECOS_ADD_TARGET_LIB
9067 UseJava
9069 This file provides support for Java. It is assumed that FindJava has
9070 already been loaded. See FindJava for information on how to load Java
9071 into your CMake project.
9072 Synopsis
9074 Creating and Installing JARS
9075 add_jar (<target_name> [SOURCES] <source1> [<source2>...] ...)
9076 install_jar (<target_name> DESTINATION <destination> [COMPONENT <component>])
9077 install_jni_symlink (<target_name> DESTINATION <destination> [COMPONENT <component>])
9078 Header Generation
9080 create_javah ((TARGET <target> | GENERATED_FILES <VAR>) CLASSES <class>... ...)
9081 Exporting JAR Targets
9083 install_jar_exports (TARGETS <jars>... FILE <filename> DESTINATION <destination> ...)
9084 export_jars (TARGETS <jars>... [NAMESPACE <namespace>] FILE <filename>)
9085 Finding JARs
9087 find_jar (<VAR> NAMES <name1> [<name2>...] [PATHS <path1> [<path2>... ENV <var>]] ...)
9088 Creating Java Documentation
9090 create_javadoc (<VAR> (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...]) ...)
9091 Creating And Installing JARs
9093 add_jar
9094 Creates a jar file containing java objects and, optionally, re‐
9095 sources:
9096 add_jar(<target_name>
9098 [SOURCES] <source1> [<source2>...] [<resource1>...]
9099 [RESOURCES NAMESPACE <ns1> <resource1>... [NAMESPACE <nsX> <resourceX>...]... ]
9100 [INCLUDE_JARS <jar1> [<jar2>...]]
9101 [ENTRY_POINT <entry>]
9102 [VERSION <version>]
9103 [MANIFEST <manifest>]
9104 [OUTPUT_NAME <name>]
9105 [OUTPUT_DIR <dir>]
9106 [GENERATE_NATIVE_HEADERS <target>
9107 [DESTINATION (<dir>|INSTALL <dir> [BUILD <dir>])]]
9108 )
9109 This command creates a <target_name>.jar. It compiles the given
9111 <source> files and adds the given <resource> files to the jar
9112 file. Source files can be java files or listing files (prefixed
9113 by @). If only resource files are given then just a jar file is
9114 created.
9115 SOURCES
9117 Compiles the specified source files and adds the result
9118 in the jar file.
9119 New in version 3.4: Support for response files, prefixed
9121 by @.
9122 RESOURCES
9125 New in version 3.21.
9126 Adds the named <resource> files to the jar by stripping
9129 the source file path and placing the file beneath <ns>
9130 within the jar.
9131 For example:
9133 RESOURCES NAMESPACE "/com/my/namespace" "a/path/to/resource.txt"
9135 results in a resource accessible via /com/my/name‐
9137 space/resource.txt within the jar.
9138 Resources may be added without adjusting the namespace by
9140 adding them to the list of SOURCES (original behavior),
9141 in this case, resource paths must be relative to
9142 CMAKE_CURRENT_SOURCE_DIR. Adding resources without using
9143 the RESOURCES parameter in out of source builds will al‐
9144 most certainly result in confusion.
9145 NOTE:
9147 Adding resources via the SOURCES parameter relies upon
9148 a hard-coded list of file extensions which are tested
9149 to determine whether they compile (e.g. File.java).
9150 SOURCES files which match the extensions are compiled.
9151 Files which do not match are treated as resources. To
9152 include uncompiled resources matching those file ex‐
9153 tensions use the RESOURCES parameter.
9154 INCLUDE_JARS
9156 The list of jars are added to the classpath when compil‐
9157 ing the java sources and also to the dependencies of the
9158 target. INCLUDE_JARS also accepts other target names cre‐
9159 ated by add_jar(). For backwards compatibility, jar files
9160 listed as sources are ignored (as they have been since
9161 the first version of this module).
9162 ENTRY_POINT
9164 Defines an entry point in the jar file.
9165 VERSION
9167 Adds a version to the target output name.
9168 The following example will create a jar file with the
9170 name shibboleet-1.2.0.jar and will create a symlink shib‐
9171 boleet.jar pointing to the jar with the version informa‐
9172 tion.
9173 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
9175 MANIFEST
9177 Defines a custom manifest for the jar.
9178 OUTPUT_NAME
9180 Specify a different output name for the target.
9181 OUTPUT_DIR
9183 Sets the directory where the jar file will be generated.
9184 If not specified, CMAKE_CURRENT_BINARY_DIR is used as the
9185 output directory.
9186 GENERATE_NATIVE_HEADERS
9188 New in version 3.11.
9189 Generates native header files for methods declared as na‐
9192 tive. These files provide the connective glue that allow
9193 your Java and C code to interact. An INTERFACE target
9194 will be created for an easy usage of generated files.
9195 Sub-option DESTINATION can be used to specify the output
9196 directory for generated header files.
9197 This option requires, at least, version 1.8 of the JDK.
9199 For an optimum usage of this option, it is recommended to
9201 include module JNI before any call to add_jar(). The pro‐
9202 duced target for native headers can then be used to com‐
9203 pile C/C++ sources with the target_link_libraries() com‐
9204 mand.
9205 find_package(JNI)
9207 add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native)
9208 add_library(bar bar.cpp)
9209 target_link_libraries(bar PRIVATE foo-native)
9210 New in version 3.20: DESTINATION sub-option now supports
9212 the possibility to specify different output directories
9213 for BUILD and INSTALL steps. If BUILD directory is not
9214 specified, a default directory will be used.
9215 To export the interface target generated by GENERATE_NA‐
9217 TIVE_HEADERS option, sub-option INSTALL of DESTINATION is
9218 required:
9219 add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native
9221 DESTINATION INSTALL include)
9222 install(TARGETS foo-native EXPORT native)
9223 install(DIRECTORY "$<TARGET_PROPERTY:foo-native,NATIVE_HEADERS_DIRECTORY>/"
9224 DESTINATION include)
9225 install(EXPORT native DESTINATION /to/export NAMESPACE foo)
9226 Some variables can be set to customize the behavior of add_jar()
9229 as well as the java compiler:
9230 CMAKE_JAVA_COMPILE_FLAGS
9232 Specify additional flags to java compiler.
9233 CMAKE_JAVA_INCLUDE_PATH
9235 Specify additional paths to the class path.
9236 CMAKE_JNI_TARGET
9238 If the target is a JNI library, sets this boolean vari‐
9239 able to TRUE to enable creation of a JNI symbolic link
9240 (see also install_jni_symlink()).
9241 CMAKE_JAR_CLASSES_PREFIX
9243 If multiple jars should be produced from the same java
9244 source filetree, to prevent the accumulation of duplicate
9245 class files in subsequent jars, set/reset
9246 CMAKE_JAR_CLASSES_PREFIX prior to calling the add_jar():
9247 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
9249 add_jar(foo foo.java)
9250 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
9252 add_jar(bar bar.java)
9253 The add_jar() function sets the following target properties on
9255 <target_name>:
9256 INSTALL_FILES
9258 The files which should be installed. This is used by
9259 install_jar().
9260 JNI_SYMLINK
9262 The JNI symlink which should be installed. This is used
9263 by install_jni_symlink().
9264 JAR_FILE
9266 The location of the jar file so that you can include it.
9267 CLASSDIR
9269 The directory where the class files can be found. For
9270 example to use them with javah.
9271 NATIVE_HEADERS_DIRECTORY
9273 New in version 3.20.
9274 The directory where native headers are generated. Defined
9277 when option GENERATE_NATIVE_HEADERS is specified.
9278 install_jar
9280 This command installs the jar file to the given destination:
9281 install_jar(<target_name> <destination>)
9283 install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>])
9284 This command installs the <target_name> file to the given <des‐
9286 tination>. It should be called in the same scope as add_jar()
9287 or it will fail.
9288 New in version 3.4: The second signature with DESTINATION and
9290 COMPONENT options.
9291 DESTINATION
9294 Specify the directory on disk to which a file will be in‐
9295 stalled.
9296 COMPONENT
9298 Specify an installation component name with which the in‐
9299 stall rule is associated, such as "runtime" or "develop‐
9300 ment".
9301 The install_jar() command sets the following target properties
9303 on <target_name>:
9304 INSTALL_DESTINATION
9306 Holds the <destination> as described above, and is used
9307 by install_jar_exports().
9308 install_jni_symlink
9310 Installs JNI symlinks for target generated by add_jar():
9311 install_jni_symlink(<target_name> <destination>)
9313 install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>])
9314 This command installs the <target_name> JNI symlinks to the
9316 given <destination>. It should be called in the same scope as
9317 add_jar() or it will fail.
9318 New in version 3.4: The second signature with DESTINATION and
9320 COMPONENT options.
9321 DESTINATION
9324 Specify the directory on disk to which a file will be in‐
9325 stalled.
9326 COMPONENT
9328 Specify an installation component name with which the in‐
9329 stall rule is associated, such as "runtime" or "develop‐
9330 ment".
9331 Utilize the following commands to create a JNI symbolic link:
9333 set(CMAKE_JNI_TARGET TRUE)
9335 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
9336 install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
9337 install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})
9338 Header Generation
9340 create_javah
9341 New in version 3.4.
9342 Generates C header files for java classes:
9345 create_javah(TARGET <target> | GENERATED_FILES <VAR>
9347 CLASSES <class>...
9348 [CLASSPATH <classpath>...]
9349 [DEPENDS <depend>...]
9350 [OUTPUT_NAME <path>|OUTPUT_DIR <path>]
9351 )
9352 Deprecated since version 3.11: This command will no longer be
9354 supported starting with version 10 of the JDK due to the
9355 suppression of javah tool. The add_jar(GENERATE_NATIVE_HEADERS)
9356 command should be used instead.
9357 Create C header files from java classes. These files provide the
9360 connective glue that allow your Java and C code to interact.
9361 There are two main signatures for create_javah(). The first
9363 signature returns generated files through variable specified by
9364 the GENERATED_FILES option. For example:
9365 create_javah(GENERATED_FILES files_headers
9367 CLASSES org.cmake.HelloWorld
9368 CLASSPATH hello.jar
9369 )
9370 The second signature for create_javah() creates a target which
9372 encapsulates header files generation. E.g.
9373 create_javah(TARGET target_headers
9375 CLASSES org.cmake.HelloWorld
9376 CLASSPATH hello.jar
9377 )
9378 Both signatures share same options.
9380 CLASSES
9382 Specifies Java classes used to generate headers.
9383 CLASSPATH
9385 Specifies various paths to look up classes. Here .class
9386 files, jar files or targets created by command add_jar
9387 can be used.
9388 DEPENDS
9390 Targets on which the javah target depends.
9391 OUTPUT_NAME
9393 Concatenates the resulting header files for all the
9394 classes listed by option CLASSES into <path>. Same be‐
9395 havior as option -o of javah tool.
9396 OUTPUT_DIR
9398 Sets the directory where the header files will be gener‐
9399 ated. Same behavior as option -d of javah tool. If not
9400 specified, CMAKE_CURRENT_BINARY_DIR is used as the output
9401 directory.
9402 Exporting JAR Targets
9404 install_jar_exports
9405 New in version 3.7.
9406 Installs a target export file:
9409 install_jar_exports(TARGETS <jars>...
9411 [NAMESPACE <namespace>]
9412 FILE <filename>
9413 DESTINATION <destination> [COMPONENT <component>])
9414 This command installs a target export file <filename> for the
9416 named jar targets to the given <destination> directory. Its
9417 function is similar to that of install(EXPORT).
9418 TARGETS
9420 List of targets created by add_jar() command.
9421 NAMESPACE
9423 New in version 3.9.
9424 The <namespace> value will be prepend to the target names
9427 as they are written to the import file.
9428 FILE Specify name of the export file.
9430 DESTINATION
9432 Specify the directory on disk to which a file will be in‐
9433 stalled.
9434 COMPONENT
9436 Specify an installation component name with which the in‐
9437 stall rule is associated, such as "runtime" or "develop‐
9438 ment".
9439 export_jars
9441 New in version 3.7.
9442 Writes a target export file:
9445 export_jars(TARGETS <jars>...
9447 [NAMESPACE <namespace>]
9448 FILE <filename>)
9449 This command writes a target export file <filename> for the
9451 named <jars> targets. Its function is similar to that of
9452 export().
9453 TARGETS
9455 List of targets created by add_jar() command.
9456 NAMESPACE
9458 New in version 3.9.
9459 The <namespace> value will be prepend to the target names
9462 as they are written to the import file.
9463 FILE Specify name of the export file.
9465 Finding JARs
9467 find_jar
9468 Finds the specified jar file:
9469 find_jar(<VAR>
9471 <name> | NAMES <name1> [<name2>...]
9472 [PATHS <path1> [<path2>... ENV <var>]]
9473 [VERSIONS <version1> [<version2>]]
9474 [DOC "cache documentation string"]
9475 )
9476 This command is used to find a full path to the named jar. A
9478 cache entry named by <VAR> is created to store the result of
9479 this command. If the full path to a jar is found the result is
9480 stored in the variable and the search will not repeated unless
9481 the variable is cleared. If nothing is found, the result will
9482 be <VAR>-NOTFOUND, and the search will be attempted again next
9483 time find_jar() is invoked with the same variable.
9484 NAMES Specify one or more possible names for the jar file.
9486 PATHS Specify directories to search in addition to the default
9488 locations. The ENV var sub-option reads paths from a
9489 system environment variable.
9490 VERSIONS
9492 Specify jar versions.
9493 DOC Specify the documentation string for the <VAR> cache en‐
9495 try.
9496 Creating Java Documentation
9498 create_javadoc
9499 Creates java documentation based on files and packages:
9500 create_javadoc(<VAR>
9502 (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...])
9503 [SOURCEPATH <sourcepath>]
9504 [CLASSPATH <classpath>]
9505 [INSTALLPATH <install path>]
9506 [DOCTITLE <the documentation title>]
9507 [WINDOWTITLE <the title of the document>]
9508 [AUTHOR (TRUE|FALSE)]
9509 [USE (TRUE|FALSE)]
9510 [VERSION (TRUE|FALSE)]
9511 )
9512 The create_javadoc() command can be used to create java documen‐
9514 tation. There are two main signatures for create_javadoc().
9515 The first signature works with package names on a path with
9517 source files:
9518 create_javadoc(my_example_doc
9520 PACKAGES com.example.foo com.example.bar
9521 SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
9522 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
9523 WINDOWTITLE "My example"
9524 DOCTITLE "<h1>My example</h1>"
9525 AUTHOR TRUE
9526 USE TRUE
9527 VERSION TRUE
9528 )
9529 The second signature for create_javadoc() works on a given list
9531 of files:
9532 create_javadoc(my_example_doc
9534 FILES java/A.java java/B.java
9535 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
9536 WINDOWTITLE "My example"
9537 DOCTITLE "<h1>My example</h1>"
9538 AUTHOR TRUE
9539 USE TRUE
9540 VERSION TRUE
9541 )
9542 Both signatures share most of the options. For more details
9544 please read the javadoc manpage.
9545 PACKAGES
9547 Specify java packages.
9548 FILES Specify java source files. If relative paths are speci‐
9550 fied, they are relative to CMAKE_CURRENT_SOURCE_DIR.
9551 SOURCEPATH
9553 Specify the directory where to look for packages. By de‐
9554 fault, CMAKE_CURRENT_SOURCE_DIR directory is used.
9555 CLASSPATH
9557 Specify where to find user class files. Same behavior as
9558 option -classpath of javadoc tool.
9559 INSTALLPATH
9561 Specify where to install the java documentation. If you
9562 specified, the documentation will be installed to
9563 ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>.
9564 DOCTITLE
9566 Specify the title to place near the top of the overview
9567 summary file. Same behavior as option -doctitle of
9568 javadoc tool.
9569 WINDOWTITLE
9571 Specify the title to be placed in the HTML <title> tag.
9572 Same behavior as option -windowtitle of javadoc tool.
9573 AUTHOR When value TRUE is specified, includes the @author text
9575 in the generated docs. Same behavior as option -author
9576 of javadoc tool.
9577 USE When value TRUE is specified, creates class and package
9579 usage pages. Includes one Use page for each documented
9580 class and package. Same behavior as option -use of
9581 javadoc tool.
9582 VERSION
9584 When value TRUE is specified, includes the version text
9585 in the generated docs. Same behavior as option -version
9586 of javadoc tool.
9587 UseSWIG
9589 This file provides support for SWIG. It is assumed that FindSWIG module
9590 has already been loaded.
9591 CMake Commands
9593 The following command is defined for use with SWIG:
9594 swig_add_library
9596 New in version 3.8.
9597 Define swig module with given name and specified language:
9600 swig_add_library(<name>
9602 [TYPE <SHARED|MODULE|STATIC|USE_BUILD_SHARED_LIBS>]
9603 LANGUAGE <language>
9604 [NO_PROXY]
9605 [OUTPUT_DIR <directory>]
9606 [OUTFILE_DIR <directory>]
9607 SOURCES <file>...
9608 )
9609 Targets created with the swig_add_library command have the same
9611 capabilities as targets created with the add_library() command,
9612 so those targets can be used with any command expecting a target
9613 (e.g. target_link_libraries()).
9614 Changed in version 3.13: This command creates a target with the
9616 specified <name> when policy CMP0078 is set to NEW. Otherwise,
9617 the legacy behavior will choose a different target name and
9618 store it in the SWIG_MODULE_<name>_REAL_NAME variable.
9619 Changed in version 3.15: Alternate library name (set with the
9622 OUTPUT_NAME property, for example) will be passed on to Python
9623 and CSharp wrapper libraries.
9624 Changed in version 3.21: Generated library use standard naming
9627 conventions for CSharp language when policy CMP0122 is set to
9628 NEW. Otherwise, the legacy behavior is applied.
9629 NOTE:
9632 For multi-config generators, this module does not support
9633 configuration-specific files generated by SWIG. All build
9634 configurations must result in the same generated source file.
9635 NOTE:
9637 For Makefile Generators, if, for some sources, the
9638 USE_SWIG_DEPENDENCIES property is FALSE, swig_add_library
9639 does not track file dependencies, so depending on the
9640 <name>_swig_compilation custom target is required for targets
9641 which require the swig-generated files to exist. Other gener‐
9642 ators may depend on the source files that would be generated
9643 by SWIG.
9644 TYPE SHARED, MODULE and STATIC have the same semantic as for
9646 the add_library() command. If USE_BUILD_SHARED_LIBS is
9647 specified, the library type will be STATIC or SHARED
9648 based on whether the current value of the
9649 BUILD_SHARED_LIBS variable is ON. If no type is speci‐
9650 fied, MODULE will be used.
9651 LANGUAGE
9653 Specify the target language.
9654 New in version 3.1: Go and Lua language support.
9656 New in version 3.2: R language support.
9659 New in version 3.18: Fortran language support.
9662 NO_PROXY
9665 New in version 3.12.
9666 Prevent the generation of the wrapper layer (swig -no‐
9669 proxy option).
9670 OUTPUT_DIR
9672 New in version 3.12.
9673 Specify where to write the language specific files (swig
9676 -outdir option). If not given, the CMAKE_SWIG_OUTDIR
9677 variable will be used. If neither is specified, the de‐
9678 fault depends on the value of the UseSWIG_MODULE_VERSION
9679 variable as follows:
9680 • If UseSWIG_MODULE_VERSION is 1 or is undefined, output
9682 is written to the CMAKE_CURRENT_BINARY_DIR directory.
9683 • If UseSWIG_MODULE_VERSION is 2, a dedicated directory
9685 will be used. The path of this directory can be re‐
9686 trieved from the SWIG_SUPPORT_FILES_DIRECTORY target
9687 property.
9688 OUTFILE_DIR
9690 New in version 3.12.
9691 Specify an output directory name where the generated
9694 source file will be placed (swig -o option). If not spec‐
9695 ified, the SWIG_OUTFILE_DIR variable will be used. If
9696 neither is specified, OUTPUT_DIR or CMAKE_SWIG_OUTDIR is
9697 used instead.
9698 SOURCES
9700 List of sources for the library. Files with extension .i
9701 will be identified as sources for the SWIG tool. Other
9702 files will be handled in the standard way.
9703 New in version 3.14: This behavior can be overridden by
9705 specifying the variable SWIG_SOURCE_FILE_EXTENSIONS.
9706 NOTE:
9709 If UseSWIG_MODULE_VERSION is set to 2, it is strongly recom‐
9710 mended to use a dedicated directory unique to the target when
9711 either the OUTPUT_DIR option or the CMAKE_SWIG_OUTDIR vari‐
9712 able are specified. The output directory contents are erased
9713 as part of the target build, so to prevent interference be‐
9714 tween targets or losing other important files, each target
9715 should have its own dedicated output directory.
9716 Properties on Source Files
9718 Source file properties on module files must be set before the invoca‐
9719 tion of the swig_add_library command to specify special behavior of
9720 SWIG and ensure generated files will receive the required settings.
9721 CPLUSPLUS
9723 Call SWIG in c++ mode. For example:
9724 set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON)
9726 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
9727 SWIG_FLAGS
9729 Deprecated since version 3.12: Replaced with the fine-grained
9730 properties that follow.
9731 Pass custom flags to the SWIG executable.
9734 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS
9736 New in version 3.12.
9737 Add custom flags to SWIG compiler and have same semantic as
9740 properties INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and
9741 COMPILE_OPTIONS.
9742 USE_TARGET_INCLUDE_DIRECTORIES
9744 New in version 3.13.
9745 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
9748 will be forwarded to SWIG compiler. If set to FALSE target
9749 property INCLUDE_DIRECTORIES will be ignored. If not set, target
9750 property SWIG_USE_TARGET_INCLUDE_DIRECTORIES will be considered.
9751 GENERATED_INCLUDE_DIRECTORIES, GENERATED_COMPILE_DEFINITIONS and GENER‐
9753 ATED_COMPILE_OPTIONS
9754 New in version 3.12.
9755 Add custom flags to the C/C++ generated source. They will fill,
9758 respectively, properties INCLUDE_DIRECTORIES,
9759 COMPILE_DEFINITIONS and COMPILE_OPTIONS of generated C/C++ file.
9760 DEPENDS
9762 New in version 3.12.
9763 Specify additional dependencies to the source file.
9766 USE_SWIG_DEPENDENCIES
9768 New in version 3.20.
9769 If set to TRUE, implicit dependencies are generated by the swig
9772 tool itself. This property is only meaningful for Makefile,
9773 Ninja, Xcode, and Visual Studio (Visual Studio 11 2012 and
9774 above) generators. Default value is FALSE.
9775 New in version 3.21: Added the support of Xcode generator.
9777 New in version 3.22: Added the support of Visual Studio Genera‐
9780 tors.
9781 SWIG_MODULE_NAME
9784 Specify the actual import name of the module in the target lan‐
9785 guage. This is required if it cannot be scanned automatically
9786 from source or different from the module file basename. For ex‐
9787 ample:
9788 set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)
9790 Changed in version 3.14: If policy CMP0086 is set to NEW, -mod‐
9792 ule <module_name> is passed to SWIG compiler.
9793 OUTPUT_DIR
9796 New in version 3.19.
9797 Specify where to write the language specific files (swig -outdir
9800 option) for the considered source file. If not specified, the
9801 other ways to define the output directory applies (see OUT‐
9802 PUT_DIR option of swig_add_library() command).
9803 OUTFILE_DIR
9805 New in version 3.19.
9806 Specify an output directory where the generated source file will
9809 be placed (swig -o option) for the considered source file. If
9810 not specified, OUTPUT_DIR source property will be used. If nei‐
9811 ther are specified, the other ways to define output file direc‐
9812 tory applies (see OUTFILE_DIR option of swig_add_library() com‐
9813 mand).
9814 Properties on Targets
9816 Target library properties can be set to apply same configuration to all
9817 SWIG input files.
9818 SWIG_INCLUDE_DIRECTORIES, SWIG_COMPILE_DEFINITIONS and SWIG_COMPILE_OP‐
9820 TIONS
9821 New in version 3.12.
9822 These properties will be applied to all SWIG input files and
9825 have same semantic as target properties INCLUDE_DIRECTORIES,
9826 COMPILE_DEFINITIONS and COMPILE_OPTIONS.
9827 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
9829 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
9830 set_property(TARGET mymod PROPERTY SWIG_COMPILE_DEFINITIONS MY_DEF1 MY_DEF2)
9831 set_property(TARGET mymod PROPERTY SWIG_COMPILE_OPTIONS -bla -blb)
9832 SWIG_USE_TARGET_INCLUDE_DIRECTORIES
9834 New in version 3.13.
9835 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
9838 will be forwarded to SWIG compiler. If set to FALSE or not de‐
9839 fined, target property INCLUDE_DIRECTORIES will be ignored. This
9840 behavior can be overridden by specifying source property
9841 USE_TARGET_INCLUDE_DIRECTORIES.
9842 SWIG_GENERATED_INCLUDE_DIRECTORIES, SWIG_GENERATED_COMPILE_DEFINITIONS
9844 and SWIG_GENERATED_COMPILE_OPTIONS
9845 New in version 3.12.
9846 These properties will populate, respectively, properties
9849 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_FLAGS of
9850 all generated C/C++ files.
9851 SWIG_DEPENDS
9853 New in version 3.12.
9854 Add dependencies to all SWIG input files.
9857 Read-only Target Properties
9859 The following target properties are output properties and can be used
9860 to get information about support files generated by SWIG interface com‐
9861 pilation.
9862 SWIG_SUPPORT_FILES
9864 New in version 3.12.
9865 This output property list of wrapper files generated during SWIG
9868 compilation.
9869 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
9871 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
9872 get_property(support_files TARGET mymod PROPERTY SWIG_SUPPORT_FILES)
9873 NOTE:
9875 Only most principal support files are listed. In case some
9876 advanced features of SWIG are used (for example %template),
9877 associated support files may not be listed. Prefer to use the
9878 SWIG_SUPPORT_FILES_DIRECTORY property to handle support
9879 files.
9880 SWIG_SUPPORT_FILES_DIRECTORY
9882 New in version 3.12.
9883 This output property specifies the directory where support files
9886 will be generated.
9887 NOTE:
9889 When source property OUTPUT_DIR is defined, multiple directo‐
9890 ries can be specified as part of SWIG_SUPPORT_FILES_DIREC‐
9891 TORY.
9892 CMake Variables
9894 Some variables can be set to customize the behavior of swig_add_library
9895 as well as SWIG:
9896 UseSWIG_MODULE_VERSION
9898 New in version 3.12.
9899 Specify different behaviors for UseSWIG module.
9902 • Set to 1 or undefined: Legacy behavior is applied.
9904 • Set to 2: A new strategy is applied regarding support files:
9906 the output directory of support files is erased before SWIG
9907 interface compilation.
9908 CMAKE_SWIG_FLAGS
9910 Add flags to all swig calls.
9911 CMAKE_SWIG_OUTDIR
9913 Specify where to write the language specific files (swig -outdir
9914 option).
9915 SWIG_OUTFILE_DIR
9917 New in version 3.8.
9918 Specify an output directory name where the generated source file
9921 will be placed. If not specified, CMAKE_SWIG_OUTDIR is used.
9922 SWIG_MODULE_<name>_EXTRA_DEPS
9924 Specify extra dependencies for the generated module for <name>.
9925 SWIG_SOURCE_FILE_EXTENSIONS
9927 New in version 3.14.
9928 Specify a list of source file extensions to override the default
9931 behavior of considering only .i files as sources for the SWIG
9932 tool. For example:
9933 set(SWIG_SOURCE_FILE_EXTENSIONS ".i" ".swg")
9935 SWIG_USE_SWIG_DEPENDENCIES
9937 New in version 3.20.
9938 If set to TRUE, implicit dependencies are generated by the swig
9941 tool itself. This variable is only meaningful for Makefile,
9942 Ninja, Xcode, and Visual Studio (Visual Studio 11 2012 and
9943 above) generators. Default value is FALSE.
9944 Source file property USE_SWIG_DEPENDENCIES, if not defined, will
9946 be initialized with the value of this variable.
9947 New in version 3.21: Added the support of Xcode generator.
9949 New in version 3.22: Added the support of Visual Studio Genera‐
9952 tors.
9953 Deprecated Commands
9956 swig_link_libraries
9957 Deprecated since version 3.13: Use target_link_libraries() with
9958 the standard target name, or with ${SWIG_MOD‐
9959 ULE_<name>_REAL_NAME} for legacy target naming.
9960 Link libraries to swig module:
9963 swig_link_libraries(<name> <item>...)
9965 This command has same capabilities as target_link_libraries()
9967 command.
9968 NOTE:
9970 When policy CMP0078 is set to NEW, swig_add_library() creates
9971 a standard target with the specified <name> and
9972 target_link_libraries() must be used instead of this command.
9973 With the legacy behavior (when CMP0078 is set to OLD and the
9975 UseSWIG_TARGET_NAME_PREFERENCE variable is set to "LEGACY",
9976 or in CMake versions prior to 3.12), it is preferable to use
9977 target_link_libraries(${SWIG_MODULE_<name>_REAL_NAME} ...)
9978 instead of this command.
9979 UsewxWidgets
9981 Convenience include for using wxWidgets library.
9982 Determines if wxWidgets was FOUND and sets the appropriate libs, in‐
9984 cdirs, flags, etc. INCLUDE_DIRECTORIES and LINK_DIRECTORIES are
9985 called.
9986 USAGE
9988 # Note that for MinGW users the order of libs is important!
9990 find_package(wxWidgets REQUIRED net gl core base)
9991 include(${wxWidgets_USE_FILE})
9992 # and for each of your dependent executable/library targets:
9993 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
9994 DEPRECATED
9996 LINK_LIBRARIES is not called in favor of adding dependencies per target.
9998 AUTHOR
10000 Jan Woetzel <jw -at- mip.informatik.uni-kiel.de>
10002
10004 These modules search for third-party software. They are normally
10005 called through the find_package() command.
10006 FindALSA
10008 Find Advanced Linux Sound Architecture (ALSA)
10009 Find the alsa libraries (asound)
10011 IMPORTED Targets
10013 New in version 3.12.
10014 This module defines IMPORTED target ALSA::ALSA, if ALSA has been found.
10017 Result Variables
10019 This module defines the following variables:
10020 ALSA_FOUND
10022 True if ALSA_INCLUDE_DIR & ALSA_LIBRARY are found
10023 ALSA_LIBRARIES
10025 List of libraries when using ALSA.
10026 ALSA_INCLUDE_DIRS
10028 Where to find the ALSA headers.
10029 Cache variables
10031 The following cache variables may also be set:
10032 ALSA_INCLUDE_DIR
10034 the ALSA include directory
10035 ALSA_LIBRARY
10037 the absolute path of the asound library
10038 FindArmadillo
10040 Find the Armadillo C++ library. Armadillo is a library for linear al‐
10041 gebra & scientific computing.
10042 New in version 3.18: Support for linking wrapped libraries directly
10044 (ARMA_DONT_USE_WRAPPER).
10045 Using Armadillo:
10048 find_package(Armadillo REQUIRED)
10050 include_directories(${ARMADILLO_INCLUDE_DIRS})
10051 add_executable(foo foo.cc)
10052 target_link_libraries(foo ${ARMADILLO_LIBRARIES})
10053 This module sets the following variables:
10055 ARMADILLO_FOUND - set to true if the library is found
10057 ARMADILLO_INCLUDE_DIRS - list of required include directories
10058 ARMADILLO_LIBRARIES - list of libraries to be linked
10059 ARMADILLO_VERSION_MAJOR - major version number
10060 ARMADILLO_VERSION_MINOR - minor version number
10061 ARMADILLO_VERSION_PATCH - patch version number
10062 ARMADILLO_VERSION_STRING - version number as a string (ex: "1.0.4")
10063 ARMADILLO_VERSION_NAME - name of the version (ex: "Antipodean Antileech")
10064 FindASPELL
10066 Try to find ASPELL
10067 Once done this will define
10069 ASPELL_FOUND - system has ASPELL
10071 ASPELL_EXECUTABLE - the ASPELL executable
10072 ASPELL_INCLUDE_DIR - the ASPELL include directory
10073 ASPELL_LIBRARIES - The libraries needed to use ASPELL
10074 ASPELL_DEFINITIONS - Compiler switches required for using ASPELL
10075 FindAVIFile
10077 Locate AVIFILE library and include paths
10078 AVIFILE (https://avifile.sourceforge.net/) is a set of libraries for
10080 i386 machines to use various AVI codecs. Support is limited beyond
10081 Linux. Windows provides native AVI support, and so doesn't need this
10082 library. This module defines
10083 AVIFILE_INCLUDE_DIR, where to find avifile.h , etc.
10085 AVIFILE_LIBRARIES, the libraries to link against
10086 AVIFILE_DEFINITIONS, definitions to use when compiling
10087 AVIFILE_FOUND, If false, don't try to use AVIFILE
10088 FindBacktrace
10090 Find provider for backtrace(3).
10091 Checks if OS supports backtrace(3) via either libc or custom library.
10093 This module defines the following variables:
10094 Backtrace_HEADER
10096 The header file needed for backtrace(3). Cached. Could be
10097 forcibly set by user.
10098 Backtrace_INCLUDE_DIRS
10100 The include directories needed to use backtrace(3) header.
10101 Backtrace_LIBRARIES
10103 The libraries (linker flags) needed to use backtrace(3), if any.
10104 Backtrace_FOUND
10106 Is set if and only if backtrace(3) support detected.
10107 The following cache variables are also available to set or use:
10109 Backtrace_LIBRARY
10111 The external library providing backtrace, if any.
10112 Backtrace_INCLUDE_DIR
10114 The directory holding the backtrace(3) header.
10115 Typical usage is to generate of header file using configure_file() with
10117 the contents like the following:
10118 #cmakedefine01 Backtrace_FOUND
10120 #if Backtrace_FOUND
10121 # include <${Backtrace_HEADER}>
10122 #endif
10123 And then reference that generated header file in actual source.
10125 FindBISON
10127 Find bison executable and provide a macro to generate custom build
10128 rules.
10129 The module defines the following variables:
10131 BISON_EXECUTABLE
10133 path to the bison program
10134 BISON_VERSION
10136 version of bison
10137 BISON_FOUND
10139 "True" if the program was found
10140 The minimum required version of bison can be specified using the stan‐
10142 dard CMake syntax, e.g. find_package(BISON 2.1.3).
10143 If bison is found, the module defines the macro:
10145 BISON_TARGET(<Name> <YaccInput> <CodeOutput>
10147 [COMPILE_FLAGS <flags>]
10148 [DEFINES_FILE <file>]
10149 [VERBOSE [<file>]]
10150 [REPORT_FILE <file>]
10151 )
10152 which will create a custom rule to generate a parser. <YaccInput> is
10154 the path to a yacc file. <CodeOutput> is the name of the source file
10155 generated by bison. A header file is also be generated, and contains
10156 the token list.
10157 Changed in version 3.14: When CMP0088 is set to NEW, bison runs in the
10159 CMAKE_CURRENT_BINARY_DIR directory.
10160 The options are:
10163 COMPILE_FLAGS <flags>
10165 Specify flags to be added to the bison command line.
10166 DEFINES_FILE <file>
10168 New in version 3.4.
10169 Specify a non-default header <file> to be generated by bison.
10172 VERBOSE [<file>]
10174 Tell bison to write a report file of the grammar and parser.
10175 Deprecated since version 3.7: If <file> is given, it specifies
10177 path the report file is copied to. [<file>] is left for back‐
10178 ward compatibility of this module. Use VERBOSE REPORT_FILE
10179 <file>.
10180 REPORT_FILE <file>
10183 New in version 3.7.
10184 Specify a non-default report <file>, if generated.
10187 The macro defines the following variables:
10189 BISON_<Name>_DEFINED
10191 True is the macro ran successfully
10192 BISON_<Name>_INPUT
10194 The input source file, an alias for <YaccInput>
10195 BISON_<Name>_OUTPUT_SOURCE
10197 The source file generated by bison
10198 BISON_<Name>_OUTPUT_HEADER
10200 The header file generated by bison
10201 BISON_<Name>_OUTPUTS
10203 All files generated by bison including the source, the header
10204 and the report
10205 BISON_<Name>_COMPILE_FLAGS
10207 Options used in the bison command line
10208 Example usage:
10210 find_package(BISON)
10212 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp
10213 DEFINES_FILE ${CMAKE_CURRENT_BINARY_DIR}/parser.h)
10214 add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
10215 FindBLAS
10217 Find Basic Linear Algebra Subprograms (BLAS) library
10218 This module finds an installed Fortran library that implements the BLAS
10220 linear-algebra interface.
10221 At least one of the C, CXX, or Fortran languages must be enabled.
10223 Input Variables
10225 The following variables may be set to influence this module's behavior:
10226 BLA_STATIC
10228 if ON use static linkage
10229 BLA_VENDOR
10231 Set to one of the BLAS/LAPACK Vendors to search for BLAS only
10232 from the specified vendor. If not set, all vendors are consid‐
10233 ered.
10234 BLA_F95
10236 if ON tries to find the BLAS95 interfaces
10237 BLA_PREFER_PKGCONFIG
10239 New in version 3.11.
10240 if set pkg-config will be used to search for a BLAS library
10243 first and if one is found that is preferred
10244 BLA_PKGCONFIG_BLAS
10246 New in version 3.25.
10247 If set, the pkg-config method will look for this module name in‐
10250 stead of just blas.
10251 BLA_SIZEOF_INTEGER
10253 New in version 3.22.
10254 Specify the BLAS/LAPACK library integer size:
10257 4 Search for a BLAS/LAPACK with 32-bit integer interfaces.
10259 8 Search for a BLAS/LAPACK with 64-bit integer interfaces.
10261 ANY Search for any BLAS/LAPACK. Most likely, a BLAS/LAPACK
10263 with 32-bit integer interfaces will be found.
10264 Imported targets
10266 This module defines the following IMPORTED targets:
10267 BLAS::BLAS
10269 New in version 3.18.
10270 The libraries to use for BLAS, if found.
10273 Result Variables
10275 This module defines the following variables:
10276 BLAS_FOUND
10278 library implementing the BLAS interface is found
10279 BLAS_LINKER_FLAGS
10281 uncached list of required linker flags (excluding -l and -L).
10282 BLAS_LIBRARIES
10284 uncached list of libraries (using full path name) to link
10285 against to use BLAS (may be empty if compiler implicitly links
10286 BLAS)
10287 BLAS95_LIBRARIES
10289 uncached list of libraries (using full path name) to link
10290 against to use BLAS95 interface
10291 BLAS95_FOUND
10293 library implementing the BLAS95 interface is found
10294 BLAS/LAPACK Vendors
10296 Generic
10297 Generic reference implementation
10298 ACML, ACML_MP, ACML_GPU
10300 AMD Core Math Library
10301 AOCL, AOCL_mt
10303 New in version 3.27.
10304 AMD Optimizing CPU Libraries
10307 Apple, NAS
10309 Apple BLAS (Accelerate), and Apple NAS (vecLib)
10310 Arm, Arm_mp, Arm_ilp64, Arm_ilp64_mp
10312 New in version 3.18.
10313 Arm Performance Libraries
10316 ATLAS Automatically Tuned Linear Algebra Software
10318 CXML, DXML
10320 Compaq/Digital Extended Math Library
10321 EML, EML_mt
10323 New in version 3.20.
10324 Elbrus Math Library
10327 FLAME New in version 3.11.
10329 BLIS Framework
10332 FlexiBLAS
10334 New in version 3.19.
10335 Fujitsu_SSL2, Fujitsu_SSL2BLAMP, Fujitsu_SSL2SVE, Fujitsu_SSL2BLAMPSVE
10338 New in version 3.20.
10339 Fujitsu SSL2 serial and parallel blas/lapack with SVE instruc‐
10342 tions
10343 Goto GotoBLAS
10345 IBMESSL, IBMESSL_SMP
10347 IBM Engineering and Scientific Subroutine Library
10348 Intel Intel MKL 32 bit and 64 bit obsolete versions
10350 Intel10_32
10352 Intel MKL v10 32 bit, threaded code
10353 Intel10_64lp
10355 Intel MKL v10+ 64 bit, threaded code, lp64 model
10356 Intel10_64lp_seq
10358 Intel MKL v10+ 64 bit, sequential code, lp64 model
10359 Intel10_64ilp
10361 New in version 3.13.
10362 Intel MKL v10+ 64 bit, threaded code, ilp64 model
10365 Intel10_64ilp_seq
10367 New in version 3.13.
10368 Intel MKL v10+ 64 bit, sequential code, ilp64 model
10371 Intel10_64_dyn
10373 New in version 3.17.
10374 Intel MKL v10+ 64 bit, single dynamic library
10377 NVHPC New in version 3.21.
10379 NVIDIA HPC SDK
10382 OpenBLAS
10384 New in version 3.6.
10385 PhiPACK
10388 Portable High Performance ANSI C (PHiPAC)
10389 SCSL, SCSL_mp
10391 Scientific Computing Software Library
10392 SGIMATH
10394 SGI Scientific Mathematical Library
10395 SunPerf
10397 Sun Performance Library
10398 Intel MKL
10400 To use the Intel MKL implementation of BLAS, a project must enable at
10401 least one of the C or CXX languages. Set BLA_VENDOR to an Intel MKL
10402 variant either on the command-line as -DBLA_VENDOR=Intel10_64lp or in
10403 project code:
10404 set(BLA_VENDOR Intel10_64lp)
10406 find_package(BLAS)
10407 In order to build a project using Intel MKL, and end user must first
10409 establish an Intel MKL environment:
10410 Intel oneAPI
10412 Source the full Intel environment script:
10413 . /opt/intel/oneapi/setvars.sh
10415 Or, source the MKL component environment script:
10417 . /opt/intel/oneapi/mkl/latest/env/vars.sh
10419 Intel Classic
10421 Source the full Intel environment script:
10422 . /opt/intel/bin/compilervars.sh intel64
10424 Or, source the MKL component environment script:
10426 . /opt/intel/mkl/bin/mklvars.sh intel64
10428 The above environment scripts set the MKLROOT environment variable to
10430 the top of the MKL installation. They also add the location of the
10431 runtime libraries to the dynamic library loader environment variable
10432 for your platform (e.g. LD_LIBRARY_PATH). This is necessary for pro‐
10433 grams linked against MKL to run.
10434 NOTE:
10436 As of Intel oneAPI 2021.2, loading only the MKL component does not
10437 make all of its dependencies available. In particular, the iomp5
10438 library must be available separately, or provided by also loading
10439 the compiler component environment:
10440 . /opt/intel/oneapi/compiler/latest/env/vars.sh
10442 FindBoost
10444 Find Boost include dirs and libraries
10445 Use this module by invoking find_package() with the form:
10447 find_package(Boost
10449 [version] [EXACT] # Minimum or EXACT version e.g. 1.67.0
10450 [REQUIRED] # Fail with error if Boost is not found
10451 [COMPONENTS <libs>...] # Boost libraries by their canonical name
10452 # e.g. "date_time" for "libboost_date_time"
10453 [OPTIONAL_COMPONENTS <libs>...]
10454 # Optional Boost libraries by their canonical name)
10455 ) # e.g. "date_time" for "libboost_date_time"
10456 This module finds headers and requested component libraries OR a CMake
10458 package configuration file provided by a "Boost CMake" build. For the
10459 latter case skip to the Boost CMake section below.
10460 New in version 3.7: bzip2 and zlib components (Windows only).
10462 New in version 3.11: The OPTIONAL_COMPONENTS option.
10465 New in version 3.13: stacktrace_* components.
10468 New in version 3.19: bzip2 and zlib components on all platforms.
10471 Result Variables
10474 This module defines the following variables:
10475 Boost_FOUND
10477 True if headers and requested libraries were found.
10478 Boost_INCLUDE_DIRS
10480 Boost include directories.
10481 Boost_LIBRARY_DIRS
10483 Link directories for Boost libraries.
10484 Boost_LIBRARIES
10486 Boost component libraries to be linked.
10487 Boost_<COMPONENT>_FOUND
10489 True if component <COMPONENT> was found (<COMPONENT> name is up‐
10490 per-case).
10491 Boost_<COMPONENT>_LIBRARY
10493 Libraries to link for component <COMPONENT> (may include
10494 target_link_libraries() debug/optimized keywords).
10495 Boost_VERSION_MACRO
10497 BOOST_VERSION value from boost/version.hpp.
10498 Boost_VERSION_STRING
10500 Boost version number in X.Y.Z format.
10501 Boost_VERSION
10503 Boost version number in X.Y.Z format (same as Boost_VER‐
10504 SION_STRING).
10505 Changed in version 3.15: In previous CMake versions, this vari‐
10507 able used the raw version string from the Boost header (same as
10508 Boost_VERSION_MACRO). See policy CMP0093.
10509 Boost_LIB_VERSION
10512 Version string appended to library filenames.
10513 Boost_VERSION_MAJOR, Boost_MAJOR_VERSION
10515 Boost major version number (X in X.Y.Z).
10516 Boost_VERSION_MINOR, Boost_MINOR_VERSION
10518 Boost minor version number (Y in X.Y.Z).
10519 Boost_VERSION_PATCH, Boost_SUBMINOR_VERSION
10521 Boost subminor version number (Z in X.Y.Z).
10522 Boost_VERSION_COUNT
10524 Amount of version components (3).
10525 Boost_LIB_DIAGNOSTIC_DEFINITIONS (Windows-specific)
10527 Pass to add_definitions() to have diagnostic information about
10528 Boost's automatic linking displayed during compilation
10529 New in version 3.15: The Boost_VERSION_<PART> variables.
10531 Cache variables
10534 Search results are saved persistently in CMake cache entries:
10535 Boost_INCLUDE_DIR
10537 Directory containing Boost headers.
10538 Boost_LIBRARY_DIR_RELEASE
10540 Directory containing release Boost libraries.
10541 Boost_LIBRARY_DIR_DEBUG
10543 Directory containing debug Boost libraries.
10544 Boost_<COMPONENT>_LIBRARY_DEBUG
10546 Component <COMPONENT> library debug variant.
10547 Boost_<COMPONENT>_LIBRARY_RELEASE
10549 Component <COMPONENT> library release variant.
10550 New in version 3.3: Per-configuration variables Boost_LIBRARY_DIR_RE‐
10552 LEASE and Boost_LIBRARY_DIR_DEBUG.
10553 Hints
10556 This module reads hints about search locations from variables:
10557 BOOST_ROOT, BOOSTROOT
10559 Preferred installation prefix.
10560 BOOST_INCLUDEDIR
10562 Preferred include directory e.g. <prefix>/include.
10563 BOOST_LIBRARYDIR
10565 Preferred library directory e.g. <prefix>/lib.
10566 Boost_NO_SYSTEM_PATHS
10568 Set to ON to disable searching in locations not specified by
10569 these hint variables. Default is OFF.
10570 Boost_ADDITIONAL_VERSIONS
10572 List of Boost versions not known to this module. (Boost install
10573 locations may contain the version).
10574 Users may set these hints or results as CACHE entries. Projects should
10576 not read these entries directly but instead use the above result vari‐
10577 ables. Note that some hint names start in upper-case BOOST. One may
10578 specify these as environment variables if they are not specified as
10579 CMake variables or cache entries.
10580 This module first searches for the Boost header files using the above
10582 hint variables (excluding BOOST_LIBRARYDIR) and saves the result in
10583 Boost_INCLUDE_DIR. Then it searches for requested component libraries
10584 using the above hints (excluding BOOST_INCLUDEDIR and Boost_ADDI‐
10585 TIONAL_VERSIONS), "lib" directories near Boost_INCLUDE_DIR, and the li‐
10586 brary name configuration settings below. It saves the library directo‐
10587 ries in Boost_LIBRARY_DIR_DEBUG and Boost_LIBRARY_DIR_RELEASE and indi‐
10588 vidual library locations in Boost_<COMPONENT>_LIBRARY_DEBUG and
10589 Boost_<COMPONENT>_LIBRARY_RELEASE. When one changes settings used by
10590 previous searches in the same build tree (excluding environment vari‐
10591 ables) this module discards previous search results affected by the
10592 changes and searches again.
10593 Imported Targets
10595 New in version 3.5.
10596 This module defines the following IMPORTED targets:
10599 Boost::boost
10601 Target for header-only dependencies. (Boost include directory).
10602 Boost::headers
10604 New in version 3.15: Alias for Boost::boost.
10605 Boost::<component>
10608 Target for specific component dependency (shared or static li‐
10609 brary); <component> name is lower-case.
10610 Boost::diagnostic_definitions
10612 Interface target to enable diagnostic information about Boost's
10613 automatic linking during compilation (adds -DBOOST_LIB_DIAGNOS‐
10614 TIC).
10615 Boost::disable_autolinking
10617 Interface target to disable automatic linking with MSVC (adds
10618 -DBOOST_ALL_NO_LIB).
10619 Boost::dynamic_linking
10621 Interface target to enable dynamic linking with MSVC (adds
10622 -DBOOST_ALL_DYN_LINK).
10623 Implicit dependencies such as Boost::filesystem requiring Boost::system
10625 will be automatically detected and satisfied, even if system is not
10626 specified when using find_package() and if Boost::system is not added
10627 to target_link_libraries(). If using Boost::thread, then
10628 Threads::Threads will also be added automatically.
10629 It is important to note that the imported targets behave differently
10631 than variables created by this module: multiple calls to
10632 find_package(Boost) in the same directory or sub-directories with dif‐
10633 ferent options (e.g. static or shared) will not override the values of
10634 the targets created by the first call.
10635 Other Variables
10637 Boost libraries come in many variants encoded in their file name.
10638 Users or projects may tell this module which variant to find by setting
10639 variables:
10640 Boost_USE_DEBUG_LIBS
10642 New in version 3.10.
10643 Set to ON or OFF to specify whether to search and use the debug
10646 libraries. Default is ON.
10647 Boost_USE_RELEASE_LIBS
10649 New in version 3.10.
10650 Set to ON or OFF to specify whether to search and use the re‐
10653 lease libraries. Default is ON.
10654 Boost_USE_MULTITHREADED
10656 Set to OFF to use the non-multithreaded libraries ("mt" tag).
10657 Default is ON.
10658 Boost_USE_STATIC_LIBS
10660 Set to ON to force the use of the static libraries. Default is
10661 OFF.
10662 Boost_USE_STATIC_RUNTIME
10664 Set to ON or OFF to specify whether to use libraries linked
10665 statically to the C++ runtime ("s" tag). Default is platform
10666 dependent.
10667 Boost_USE_DEBUG_RUNTIME
10669 Set to ON or OFF to specify whether to use libraries linked to
10670 the MS debug C++ runtime ("g" tag). Default is ON.
10671 Boost_USE_DEBUG_PYTHON
10673 Set to ON to use libraries compiled with a debug Python build
10674 ("y" tag). Default is OFF.
10675 Boost_USE_STLPORT
10677 Set to ON to use libraries compiled with STLPort ("p" tag). De‐
10678 fault is OFF.
10679 Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
10681 Set to ON to use libraries compiled with STLPort deprecated "na‐
10682 tive iostreams" ("n" tag). Default is OFF.
10683 Boost_COMPILER
10685 Set to the compiler-specific library suffix (e.g. -gcc43). De‐
10686 fault is auto-computed for the C++ compiler in use.
10687 Changed in version 3.9: A list may be used if multiple compati‐
10689 ble suffixes should be tested for, in decreasing order of pref‐
10690 erence.
10691 Boost_LIB_PREFIX
10694 New in version 3.18.
10695 Set to the platform-specific library name prefix (e.g. lib) used
10698 by Boost static libs. This is needed only on platforms where
10699 CMake does not know the prefix by default.
10700 Boost_ARCHITECTURE
10702 New in version 3.13.
10703 Set to the architecture-specific library suffix (e.g. -x64).
10706 Default is auto-computed for the C++ compiler in use.
10707 Boost_THREADAPI
10709 Suffix for thread component library name, such as pthread or
10710 win32. Names with and without this suffix will both be tried.
10711 Boost_NAMESPACE
10713 Alternate namespace used to build boost with e.g. if set to my‐
10714 boost, will search for myboost_thread instead of boost_thread.
10715 Other variables one may set to control this module are:
10717 Boost_DEBUG
10719 Set to ON to enable debug output from FindBoost. Please enable
10720 this before filing any bug report.
10721 Boost_REALPATH
10723 Set to ON to resolve symlinks for discovered libraries to assist
10724 with packaging. For example, the "system" component library may
10725 be resolved to /usr/lib/libboost_system.so.1.67.0 instead of
10726 /usr/lib/libboost_system.so. This does not affect linking and
10727 should not be enabled unless the user needs this information.
10728 Boost_LIBRARY_DIR
10730 Default value for Boost_LIBRARY_DIR_RELEASE and Boost_LI‐
10731 BRARY_DIR_DEBUG.
10732 Boost_NO_WARN_NEW_VERSIONS
10734 New in version 3.20.
10735 Set to ON to suppress the warning about unknown dependencies for
10738 new Boost versions.
10739 On Visual Studio and Borland compilers Boost headers request automatic
10741 linking to corresponding libraries. This requires matching libraries
10742 to be linked explicitly or available in the link library search path.
10743 In this case setting Boost_USE_STATIC_LIBS to OFF may not achieve dy‐
10744 namic linking. Boost automatic linking typically requests static li‐
10745 braries with a few exceptions (such as Boost.Python). Use:
10746 add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})
10748 to ask Boost to report information about automatic linking requests.
10750 Examples
10752 Find Boost headers only:
10753 find_package(Boost 1.36.0)
10755 if(Boost_FOUND)
10756 include_directories(${Boost_INCLUDE_DIRS})
10757 add_executable(foo foo.cc)
10758 endif()
10759 Find Boost libraries and use imported targets:
10761 find_package(Boost 1.56 REQUIRED COMPONENTS
10763 date_time filesystem iostreams)
10764 add_executable(foo foo.cc)
10765 target_link_libraries(foo Boost::date_time Boost::filesystem
10766 Boost::iostreams)
10767 Find Boost Python 3.6 libraries and use imported targets:
10769 find_package(Boost 1.67 REQUIRED COMPONENTS
10771 python36 numpy36)
10772 add_executable(foo foo.cc)
10773 target_link_libraries(foo Boost::python36 Boost::numpy36)
10774 Find Boost headers and some static (release only) libraries:
10776 set(Boost_USE_STATIC_LIBS ON) # only find static libs
10778 set(Boost_USE_DEBUG_LIBS OFF) # ignore debug libs and
10779 set(Boost_USE_RELEASE_LIBS ON) # only find release libs
10780 set(Boost_USE_MULTITHREADED ON)
10781 set(Boost_USE_STATIC_RUNTIME OFF)
10782 find_package(Boost 1.66.0 COMPONENTS date_time filesystem system ...)
10783 if(Boost_FOUND)
10784 include_directories(${Boost_INCLUDE_DIRS})
10785 add_executable(foo foo.cc)
10786 target_link_libraries(foo ${Boost_LIBRARIES})
10787 endif()
10788 Boost CMake
10790 If Boost was built using the boost-cmake project or from Boost 1.70.0
10791 on it provides a package configuration file for use with find_package's
10792 config mode. This module looks for the package configuration file
10793 called BoostConfig.cmake or boost-config.cmake and stores the result in
10794 CACHE entry Boost_DIR. If found, the package configuration file is
10795 loaded and this module returns with no further action. See documenta‐
10796 tion of the Boost CMake package configuration for details on what it
10797 provides.
10798 Set Boost_NO_BOOST_CMAKE to ON, to disable the search for boost-cmake.
10800 FindBullet
10802 Try to find the Bullet physics engine
10803 This module defines the following variables
10805 BULLET_FOUND - Was bullet found
10807 BULLET_INCLUDE_DIRS - the Bullet include directories
10808 BULLET_LIBRARIES - Link to this, by default it includes
10809 all bullet components (Dynamics,
10810 Collision, LinearMath, & SoftBody)
10811 This module accepts the following variables
10813 BULLET_ROOT - Can be set to bullet install path or Windows build path
10815 FindBZip2
10817 Try to find BZip2
10818 IMPORTED Targets
10820 New in version 3.12.
10821 This module defines IMPORTED target BZip2::BZip2, if BZip2 has been
10824 found.
10825 Result Variables
10827 This module defines the following variables:
10828 BZIP2_FOUND
10830 system has BZip2
10831 BZIP2_INCLUDE_DIRS
10833 New in version 3.12: the BZip2 include directories
10834 BZIP2_LIBRARIES
10837 Link these to use BZip2
10838 BZIP2_NEED_PREFIX
10840 this is set if the functions are prefixed with BZ2_
10841 BZIP2_VERSION
10843 New in version 3.26: the version of BZip2 found.
10844 See also legacy variable BZIP2_VERSION_STRING.
10847 Cache variables
10849 The following cache variables may also be set:
10850 BZIP2_INCLUDE_DIR
10852 the BZip2 include directory
10853 Legacy Variables
10855 The following variables are provided for backward compatibility:
10856 BZIP2_VERSION_STRING
10858 the version of BZip2 found.
10859 Changed in version 3.26: Superseded by BZIP2_VERSION.
10861 FindCABLE
10864 Find CABLE
10865 This module finds if CABLE is installed and determines where the in‐
10867 clude files and libraries are. This code sets the following variables:
10868 CABLE the path to the cable executable
10870 CABLE_TCL_LIBRARY the path to the Tcl wrapper library
10871 CABLE_INCLUDE_DIR the path to the include directory
10872 To build Tcl wrappers, you should add shared library and link it to
10874 ${CABLE_TCL_LIBRARY}. You should also add ${CABLE_INCLUDE_DIR} as an
10875 include directory.
10876 FindCoin3D
10878 Find Coin3D (Open Inventor)
10879 Coin3D is an implementation of the Open Inventor API. It provides data
10881 structures and algorithms for 3D visualization.
10882 This module defines the following variables
10884 COIN3D_FOUND - system has Coin3D - Open Inventor
10886 COIN3D_INCLUDE_DIRS - where the Inventor include directory can be found
10887 COIN3D_LIBRARIES - Link to this to use Coin3D
10888 FindCUDAToolkit
10890 New in version 3.17.
10891 This script locates the NVIDIA CUDA toolkit and the associated li‐
10894 braries, but does not require the CUDA language be enabled for a given
10895 project. This module does not search for the NVIDIA CUDA Samples.
10896 New in version 3.19: QNX support.
10898 Search Behavior
10901 The CUDA Toolkit search behavior uses the following order:
10902 1. If the CUDA language has been enabled we will use the directory con‐
10904 taining the compiler as the first search location for nvcc.
10905 2. If the CUDAToolkit_ROOT cmake configuration variable (e.g., -DCUDA‐
10907 Toolkit_ROOT=/some/path) or environment variable is defined, it will
10908 be searched. If both an environment variable and a configuration
10909 variable are specified, the configuration variable takes precedence.
10910 The directory specified here must be such that the executable nvcc
10912 or the appropriate version.txt or version.json file can be found un‐
10913 derneath the specified directory.
10914 3. If the CUDA_PATH environment variable is defined, it will be
10916 searched for nvcc.
10917 4. The user's path is searched for nvcc using find_program(). If this
10919 is found, no subsequent search attempts are performed. Users are
10920 responsible for ensuring that the first nvcc to show up in the path
10921 is the desired path in the event that multiple CUDA Toolkits are in‐
10922 stalled.
10923 5. On Unix systems, if the symbolic link /usr/local/cuda exists, this
10925 is used. No subsequent search attempts are performed. No default
10926 symbolic link location exists for the Windows platform.
10927 6. The platform specific default install locations are searched. If
10929 exactly one candidate is found, this is used. The default CUDA
10930 Toolkit install locations searched are:
10931 ┌───────────┬────────────────────────────┐
10933 │Platform │ Search Pattern │
10934 ├───────────┼────────────────────────────┤
10935 │macOS │ /Developer/NVIDIA/CUDA-X.Y │
10936 ├───────────┼────────────────────────────┤
10937 │Other Unix │ /usr/local/cuda-X.Y │
10938 ├───────────┼────────────────────────────┤
10939 │Windows │ C:\Program Files\NVIDIA │
10940 │ │ GPU Computing Tool‐ │
10941 │ │ kit\CUDA\vX.Y │
10942 └───────────┴────────────────────────────┘
10943 Where X.Y would be a specific version of the CUDA Toolkit, such as
10945 /usr/local/cuda-9.0 or C:\Program Files\NVIDIA GPU Computing Tool‐
10946 kit\CUDA\v9.0
10947 NOTE:
10949 When multiple CUDA Toolkits are installed in the default location
10950 of a system (e.g., both /usr/local/cuda-9.0 and /usr/lo‐
10951 cal/cuda-10.0 exist but the /usr/local/cuda symbolic link does
10952 not exist), this package is marked as not found.
10953 There are too many factors involved in making an automatic deci‐
10955 sion in the presence of multiple CUDA Toolkits being installed.
10956 In this situation, users are encouraged to either (1) set CUDA‐
10957 Toolkit_ROOT [22mor (2) ensure that the correct nvcc executable shows
10958 up in $PATH for find_program() to find.
10959 Arguments
10961 [<version>]
10962 The [<version>] argument requests a version with which the pack‐
10963 age found should be compatible. See find_package version format
10964 for more details.
10965 Options
10967 REQUIRED
10968 If specified, configuration will error if a suitable CUDA Tool‐
10969 kit is not found.
10970 QUIET If specified, the search for a suitable CUDA Toolkit will not
10972 produce any messages.
10973 EXACT If specified, the CUDA Toolkit is considered found only if the
10975 exact VERSION specified is recovered.
10976 Imported targets
10978 An imported target named CUDA::toolkit is provided.
10979 This module defines IMPORTED targets for each of the following li‐
10981 braries that are part of the CUDAToolkit:
10982 • CUDA Runtime Library
10984 • CUDA Driver Library
10986 • cuBLAS
10988 • cuDLA
10990 • cuFile
10992 • cuFFT
10994 • cuRAND
10996 • cuSOLVER
10998 • cuSPARSE
11000 • cuPTI
11002 • NPP
11004 • nvBLAS
11006 • nvGRAPH
11008 • nvJPEG
11010 • nvidia-ML
11012 • nvPTX Compiler
11014 • nvRTC
11016 • nvToolsExt
11018 • nvtx3
11020 • OpenCL
11022 • cuLIBOS
11024 CUDA Runtime Library
11026 The CUDA Runtime library (cudart) are what most applications will typi‐
11027 cally need to link against to make any calls such as cudaMalloc, and
11028 cudaFree.
11029 Targets Created:
11031 • CUDA::cudart
11033 • CUDA::cudart_static
11035 CUDA Driver Library
11037 The CUDA Driver library (cuda) are used by applications that use calls
11038 such as cuMemAlloc, and cuMemFree.
11039 Targets Created:
11041 • CUDA::cuda_driver
11043 cuBLAS
11045 The cuBLAS library.
11046 Targets Created:
11048 • CUDA::cublas
11050 • CUDA::cublas_static
11052 • CUDA::cublasLt starting in CUDA 10.1
11054 • CUDA::cublasLt_static starting in CUDA 10.1
11056 cuDLA
11058 New in version 3.27.
11059 The NVIDIA Tegra Deep Learning Accelerator cuDLA library.
11062 Targets Created:
11064 • CUDA::cudla starting in CUDA 11.6
11066 cuFile
11068 New in version 3.25.
11069 The NVIDIA GPUDirect Storage cuFile library.
11072 Targets Created:
11074 • CUDA::cuFile starting in CUDA 11.4
11076 • CUDA::cuFile_static starting in CUDA 11.4
11078 • CUDA::cuFile_rdma starting in CUDA 11.4
11080 • CUDA::cuFile_rdma_static starting in CUDA 11.4
11082 cuFFT
11084 The cuFFT library.
11085 Targets Created:
11087 • CUDA::cufft
11089 • CUDA::cufftw
11091 • CUDA::cufft_static
11093 • CUDA::cufft_static_nocallback starting in CUDA 9.2, requires CMake
11095 3.23+
11096 • CUDA::cufftw_static
11098 cuRAND
11100 The cuRAND library.
11101 Targets Created:
11103 • CUDA::curand
11105 • CUDA::curand_static
11107 cuSOLVER
11109 The cuSOLVER library.
11110 Targets Created:
11112 • CUDA::cusolver
11114 • CUDA::cusolver_static
11116 cuSPARSE
11118 The cuSPARSE library.
11119 Targets Created:
11121 • CUDA::cusparse
11123 • CUDA::cusparse_static
11125 cupti
11127 The NVIDIA CUDA Profiling Tools Interface.
11128 Targets Created:
11130 • CUDA::cupti
11132 • CUDA::cupti_static
11134 New in version 3.27:
11136 • CUDA::nvperf_host starting in CUDA 10.2
11138 • CUDA::nvperf_host_static starting in CUDA 10.2
11140 • CUDA::nvperf_target starting in CUDA 10.2
11142 • CUDA::pcsamplingutil starting in CUDA 11.3
11144 NPP
11147 The NPP libraries.
11148 Targets Created:
11150 • nppc:
11152 • CUDA::nppc
11154 • CUDA::nppc_static
11156 • nppial: Arithmetic and logical operation functions in nppi_arith‐
11158 metic_and_logical_operations.h
11159 • CUDA::nppial
11161 • CUDA::nppial_static
11163 • nppicc: Color conversion and sampling functions in nppi_color_conver‐
11165 sion.h
11166 • CUDA::nppicc
11168 • CUDA::nppicc_static
11170 • nppicom: JPEG compression and decompression functions in nppi_com‐
11172 pression_functions.h Removed starting in CUDA 11.0, use nvJPEG in‐
11173 stead.
11174 • CUDA::nppicom
11176 • CUDA::nppicom_static
11178 • nppidei: Data exchange and initialization functions in nppi_data_ex‐
11180 change_and_initialization.h
11181 • CUDA::nppidei
11183 • CUDA::nppidei_static
11185 • nppif: Filtering and computer vision functions in nppi_filter_func‐
11187 tions.h
11188 • CUDA::nppif
11190 • CUDA::nppif_static
11192 • nppig: Geometry transformation functions found in nppi_geome‐
11194 try_transforms.h
11195 • CUDA::nppig
11197 • CUDA::nppig_static
11199 • nppim: Morphological operation functions found in nppi_morphologi‐
11201 cal_operations.h
11202 • CUDA::nppim
11204 • CUDA::nppim_static
11206 • nppist: Statistics and linear transform in nppi_statistics_func‐
11208 tions.h and nppi_linear_transforms.h
11209 • CUDA::nppist
11211 • CUDA::nppist_static
11213 • nppisu: Memory support functions in nppi_support_functions.h
11215 • CUDA::nppisu
11217 • CUDA::nppisu_static
11219 • nppitc: Threshold and compare operation functions in nppi_thresh‐
11221 old_and_compare_operations.h
11222 • CUDA::nppitc
11224 • CUDA::nppitc_static
11226 • npps:
11228 • CUDA::npps
11230 • CUDA::npps_static
11232 nvBLAS
11234 The nvBLAS libraries. This is a shared library only.
11235 Targets Created:
11237 • CUDA::nvblas
11239 nvGRAPH
11241 The nvGRAPH library. Removed starting in CUDA 11.0
11242 Targets Created:
11244 • CUDA::nvgraph
11246 • CUDA::nvgraph_static
11248 nvJPEG
11250 The nvJPEG library. Introduced in CUDA 10.
11251 Targets Created:
11253 • CUDA::nvjpeg
11255 • CUDA::nvjpeg_static
11257 nvPTX Compiler
11259 New in version 3.25.
11260 The nvPTX (PTX Compilation) library. The PTX Compiler APIs are a set
11263 of APIs which can be used to compile a PTX program into GPU assembly
11264 code. Introduced in CUDA 11.1 This is a static library only.
11265 Targets Created:
11267 • CUDA::nvptxcompiler_static starting in CUDA 11.1
11269 nvRTC
11271 The nvRTC (Runtime Compilation) library.
11272 Targets Created:
11274 • CUDA::nvrtc
11276 New in version 3.26:
11278 • CUDA::nvrtc_builtins
11280 • CUDA::nvrtc_static starting in CUDA 11.5
11282 • CUDA::nvrtc_builtins_static starting in CUDA 11.5
11284 nvJitLink
11287 The nvJItLink (Runtime LTO Linking) library.
11288 Targets Created:
11290 • CUDA::nvJitLink starting in CUDA 12.0
11292 • CUDA::nvJitLink_static starting in CUDA 12.0
11294 nvidia-ML
11296 The NVIDIA Management Library. This is a shared library only.
11297 Targets Created:
11299 • CUDA::nvml
11301 nvToolsExt
11303 Deprecated since version 3.25: With CUDA 10.0+, use nvtx3.
11304 The NVIDIA Tools Extension. This is a shared library only.
11307 Targets Created:
11309 • CUDA::nvToolsExt
11311 nvtx3
11313 New in version 3.25.
11314 The header-only NVIDIA Tools Extension Library. Introduced in CUDA
11317 10.0.
11318 Targets created:
11320 • CUDA::nvtx3
11322 OpenCL
11324 The NVIDIA OpenCL Library. This is a shared library only.
11325 Targets Created:
11327 • CUDA::OpenCL
11329 cuLIBOS
11331 The cuLIBOS library is a backend thread abstraction layer library which
11332 is static only. The CUDA::cublas_static, CUDA::cusparse_static,
11333 CUDA::cufft_static, CUDA::curand_static, and (when implemented) NPP li‐
11334 braries all automatically have this dependency linked.
11335 Target Created:
11337 • CUDA::culibos
11339 Note: direct usage of this target by consumers should not be necessary.
11341 Result variables
11343 CUDAToolkit_FOUND
11344 A boolean specifying whether or not the CUDA Toolkit was found.
11345 CUDAToolkit_VERSION
11347 The exact version of the CUDA Toolkit found (as reported by nvcc
11348 --version, version.txt, or version.json).
11349 CUDAToolkit_VERSION_MAJOR
11351 The major version of the CUDA Toolkit.
11352 CUDAToolkit_VERSION_MINOR
11354 The minor version of the CUDA Toolkit.
11355 CUDAToolkit_VERSION_PATCH
11357 The patch version of the CUDA Toolkit.
11358 CUDAToolkit_BIN_DIR
11360 The path to the CUDA Toolkit library directory that contains the
11361 CUDA executable nvcc.
11362 CUDAToolkit_INCLUDE_DIRS
11364 The path to the CUDA Toolkit include folder containing the
11365 header files required to compile a project linking against CUDA.
11366 CUDAToolkit_LIBRARY_DIR
11368 The path to the CUDA Toolkit library directory that contains the
11369 CUDA Runtime library cudart.
11370 CUDAToolkit_LIBRARY_ROOT
11372 New in version 3.18.
11373 The path to the CUDA Toolkit directory containing the nvvm di‐
11376 rectory and either version.txt or version.json.
11377 CUDAToolkit_TARGET_DIR
11379 The path to the CUDA Toolkit directory including the target ar‐
11380 chitecture when cross-compiling. When not cross-compiling this
11381 will be equivalent to the parent directory of CUDA‐
11382 Toolkit_BIN_DIR.
11383 CUDAToolkit_NVCC_EXECUTABLE
11385 The path to the NVIDIA CUDA compiler nvcc. Note that this path
11386 may not be the same as CMAKE_CUDA_COMPILER. nvcc must be found
11387 to determine the CUDA Toolkit version as well as determining
11388 other features of the Toolkit. This variable is set for the
11389 convenience of modules that depend on this one.
11390 FindCups
11392 Find the Common UNIX Printing System (CUPS).
11393 Set CUPS_REQUIRE_IPP_DELETE_ATTRIBUTE to TRUE if you need a version
11395 which features this function (i.e. at least 1.1.19)
11396 Imported targets
11398 New in version 3.15.
11399 This module defines IMPORTED target Cups::Cups, if Cups has been found.
11402 Result variables
11404 This module will set the following variables in your project:
11405 CUPS_FOUND
11407 true if CUPS headers and libraries were found
11408 CUPS_INCLUDE_DIRS
11410 the directory containing the Cups headers
11411 CUPS_LIBRARIES
11413 the libraries to link against to use CUPS.
11414 CUPS_VERSION_STRING
11416 the version of CUPS found (since CMake 2.8.8)
11417 Cache variables
11419 The following cache variables may also be set:
11420 CUPS_INCLUDE_DIR
11422 the directory containing the Cups headers
11423 FindCURL
11425 Find the native CURL headers and libraries.
11426 New in version 3.14: This module accept optional COMPONENTS to check
11428 supported features and protocols:
11429 PROTOCOLS: ICT FILE FTP FTPS GOPHER HTTP HTTPS IMAP IMAPS LDAP LDAPS POP3
11432 POP3S RTMP RTSP SCP SFTP SMB SMBS SMTP SMTPS TELNET TFTP
11433 FEATURES: SSL IPv6 UnixSockets libz AsynchDNS IDN GSS-API PSL SPNEGO
11434 Kerberos NTLM NTLM_WB TLS-SRP HTTP2 HTTPS-proxy
11435 IMPORTED Targets
11437 New in version 3.12.
11438 This module defines IMPORTED target CURL::libcurl, if curl has been
11441 found.
11442 Result Variables
11444 This module defines the following variables:
11445 CURL_FOUND
11447 "True" if curl found.
11448 CURL_INCLUDE_DIRS
11450 where to find curl/curl.h, etc.
11451 CURL_LIBRARIES
11453 List of libraries when using curl.
11454 CURL_VERSION_STRING
11456 The version of curl found.
11457 New in version 3.13: Debug and Release variants are found separately.
11459 CURL CMake
11462 New in version 3.17.
11463 If CURL was built using the CMake buildsystem then it provides its own
11466 CURLConfig.cmake file for use with the find_package() command's config
11467 mode. This module looks for this file and, if found, returns its re‐
11468 sults with no further action.
11469 Set CURL_NO_CURL_CMAKE to ON to disable this search.
11471 FindCurses
11473 Find the curses or ncurses include file and library.
11474 Result Variables
11476 This module defines the following variables:
11477 CURSES_FOUND
11479 True if Curses is found.
11480 CURSES_INCLUDE_DIRS
11482 The include directories needed to use Curses.
11483 CURSES_LIBRARIES
11485 The libraries needed to use Curses.
11486 CURSES_CFLAGS
11488 New in version 3.16.
11489 Parameters which ought be given to C/C++ compilers when using
11492 Curses.
11493 CURSES_HAVE_CURSES_H
11495 True if curses.h is available.
11496 CURSES_HAVE_NCURSES_H
11498 True if ncurses.h is available.
11499 CURSES_HAVE_NCURSES_NCURSES_H
11501 True if ncurses/ncurses.h is available.
11502 CURSES_HAVE_NCURSES_CURSES_H
11504 True if ncurses/curses.h is available.
11505 Set CURSES_NEED_NCURSES to TRUE before the find_package(Curses) call if
11507 NCurses functionality is required.
11508 New in version 3.10: Set CURSES_NEED_WIDE to TRUE before the find_pack‐
11510 age(Curses) call if unicode functionality is required.
11511 Backward Compatibility
11514 The following variable are provided for backward compatibility:
11515 CURSES_INCLUDE_DIR
11517 Path to Curses include. Use CURSES_INCLUDE_DIRS instead.
11518 CURSES_LIBRARY
11520 Path to Curses library. Use CURSES_LIBRARIES instead.
11521 FindCVS
11523 Find the Concurrent Versions System (CVS).
11524 The module defines the following variables:
11526 CVS_EXECUTABLE - path to cvs command line client
11528 CVS_FOUND - true if the command line client was found
11529 Example usage:
11531 find_package(CVS)
11533 if(CVS_FOUND)
11534 message("CVS found: ${CVS_EXECUTABLE}")
11535 endif()
11536 FindCxxTest
11538 Find CxxTest unit testing framework.
11539 Find the CxxTest suite and declare a helper macro for creating unit
11541 tests and integrating them with CTest.
11542 Input Variables
11544 CXXTEST_USE_PYTHON
11545 Deprecated since version 1.3.
11546 Only used in the case both Python & Perl are detected on the
11549 system to control which CxxTest code generator is used. Valid
11550 only for CxxTest version 3.
11551 In older versions of this Find Module, this variable controlled
11553 if the Python test generator was used instead of the Perl one,
11554 regardless of which scripting language the user had installed.
11555 CXXTEST_TESTGEN_ARGS
11557 New in version 2.8.3.
11558 Specify a list of options to pass to the CxxTest code generator.
11561 If not defined, --error-printer is passed.
11562 Result Variables
11564 CXXTEST_FOUND
11565 True if the CxxTest framework was found
11566 CXXTEST_INCLUDE_DIRS
11568 Where to find the CxxTest include directory
11569 CXXTEST_PERL_TESTGEN_EXECUTABLE
11571 The perl-based test generator
11572 CXXTEST_PYTHON_TESTGEN_EXECUTABLE
11574 The python-based test generator
11575 CXXTEST_TESTGEN_EXECUTABLE
11577 New in version 2.8.3.
11578 The test generator that is actually used (chosen using user
11581 preferences and interpreters found in the system)
11582 CXXTEST_TESTGEN_INTERPRETER
11584 New in version 2.8.3.
11585 The full path to the Perl or Python executable on the system, on
11588 platforms where the script cannot be executed using its shebang
11589 line.
11590 Module Commands
11592 cxxtest_add_test
11593 Create a CxxTest runner and adds it to the CTest testing suite:
11594 CXXTEST_ADD_TEST(<test_name> <gen_source_file>
11596 <input_files_to_testgen>...)
11597 Parameters:
11599 test_name
11601 The name of the test
11602 gen_source_file
11604 The generated source filename to be generated by CxxTest
11605 input_files_to_testgen
11607 The list of header files containing the CxxTest::Test‐
11608 Suite's to be included in this runner
11609 Example Usage
11611 The following example, if CxxTest is found, will:
11612 • Invoke the testgen executable to autogenerate foo_test.cc in the bi‐
11614 nary tree from "foo_test.h" in the current source directory.
11615 • Create an executable and test called unittest_foo.
11617 find_package(CxxTest)
11619 if(CXXTEST_FOUND)
11620 include_directories(${CXXTEST_INCLUDE_DIR})
11621 enable_testing()
11622 CXXTEST_ADD_TEST(unittest_foo foo_test.cc
11623 ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h)
11624 target_link_libraries(unittest_foo foo) # as needed
11625 endif()
11626 foo_test.h contains:
11628 #include <cxxtest/TestSuite.h>
11630 class MyTestSuite : public CxxTest::TestSuite
11631 {
11632 public:
11633 void testAddition( void )
11634 {
11635 TS_ASSERT( 1 + 1 > 1 );
11636 TS_ASSERT_EQUALS( 1 + 1, 2 );
11637 }
11638 };
11639 FindCygwin
11641 Find Cygwin, a POSIX-compatible environment that runs natively on Mi‐
11642 crosoft Windows
11643 FindDart
11645 Deprecated since version 3.27: This module is available only if policy
11646 CMP0145 is not set to NEW.
11647 Find DART
11650 This module looks for the dart testing software and sets DART_ROOT to
11652 point to where it found it.
11653 FindDCMTK
11655 Find DICOM ToolKit (DCMTK) libraries and applications
11656 The module defines the following variables:
11658 DCMTK_INCLUDE_DIRS - Directories to include to use DCMTK
11660 DCMTK_LIBRARIES - Files to link against to use DCMTK
11661 DCMTK_FOUND - If false, don't try to use DCMTK
11662 DCMTK_DIR - (optional) Source directory for DCMTK
11663 Compatibility
11665 This module is able to find a version of DCMTK that does or does not
11666 export a DCMTKConfig.cmake file. It applies a two step process:
11667 • Step 1: Attempt to find DCMTK version providing a DCMTKConfig.cmake
11669 file.
11670 • Step 2: If step 1 failed, rely on FindDCMTK.cmake to set DCMTK_*
11672 variables details below.
11673 Recent DCMTK provides a DCMTKConfig.cmake package configuration file.
11675 To exclusively use the package configuration file (recommended when
11676 possible), pass the NO_MODULE option to find_package(). For example,
11677 find_package(DCMTK NO_MODULE). This requires official DCMTK snapshot
11678 3.6.1_20140617 or newer.
11679 Until all clients update to the more recent DCMTK, build systems will
11681 need to support different versions of DCMTK.
11682 On any given system, the following combinations of DCMTK versions could
11684 be considered:
11685 ┌───────┬─────────────────┬─────────────────┬─────────────┐
11687 │ │ SYSTEM DCMTK │ LOCAL DCMTK │ Supported ? │
11688 ├───────┼─────────────────┼─────────────────┼─────────────┤
11689 │Case A │ NA │ [ ] DCMTKConfig │ YES │
11690 └───────┴─────────────────┴─────────────────┴─────────────┘
11691 │Case B │ NA │ [X] DCMTKConfig │ YES │
11693 ├───────┼─────────────────┼─────────────────┼─────────────┤
11694 │Case C │ [ ] DCMTKConfig │ NA │ YES │
11695 ├───────┼─────────────────┼─────────────────┼─────────────┤
11696 │Case D │ [X] DCMTKConfig │ NA │ YES │
11697 ├───────┼─────────────────┼─────────────────┼─────────────┤
11698 │Case E │ [ ] DCMTKConfig │ [ ] DCMTKConfig │ YES (*) │
11699 ├───────┼─────────────────┼─────────────────┼─────────────┤
11700 │Case F │ [X] DCMTKConfig │ [ ] DCMTKConfig │ NO │
11701 ├───────┼─────────────────┼─────────────────┼─────────────┤
11702 │Case G │ [ ] DCMTKConfig │ [X] DCMTKConfig │ YES │
11703 ├───────┼─────────────────┼─────────────────┼─────────────┤
11704 │Case H │ [X] DCMTKConfig │ [X] DCMTKConfig │ YES │
11705 └───────┴─────────────────┴─────────────────┴─────────────┘
11706 (*) See Troubleshooting section.
11707 Legend:
11709 NA ...............: Means that no System or Local DCMTK is available
11710 [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export
11712 a DCMTKConfig.cmake file.
11713 [X] DCMTKConfig ..: Means that the version of DCMTK exports a DCMTK‐
11715 Config.cmake file.
11716 Troubleshooting
11718 What to do if my project finds a different version of DCMTK?
11719 Remove DCMTK entry from the CMake cache per find_package() documenta‐
11721 tion.
11722 FindDevIL
11724 This module locates the developer's image library.
11725 https://openil.sourceforge.net/
11726 IMPORTED Targets
11728 New in version 3.21.
11729 This module defines the IMPORTED targets:
11732 DevIL::IL
11734 Defined if the system has DevIL.
11735 DevIL::ILU
11737 Defined if the system has DevIL Utilities.
11738 DevIL::ILUT
11740 Defined if the system has DevIL Utility Toolkit.
11741 Result Variables
11743 This module sets:
11744 IL_LIBRARIES
11746 The name of the IL library. These include the full path to the
11747 core DevIL library. This one has to be linked into the applica‐
11748 tion.
11749 ILU_LIBRARIES
11751 The name of the ILU library. Again, the full path. This library
11752 is for filters and effects, not actual loading. It doesn't have
11753 to be linked if the functionality it provides is not used.
11754 ILUT_LIBRARIES
11756 The name of the ILUT library. Full path. This part of the li‐
11757 brary interfaces with OpenGL. It is not strictly needed in ap‐
11758 plications.
11759 IL_INCLUDE_DIR
11761 where to find the il.h, ilu.h and ilut.h files.
11762 DevIL_FOUND
11764 This is set to TRUE if all the above variables were set. This
11765 will be set to false if ILU or ILUT are not found, even if they
11766 are not needed. In most systems, if one library is found all the
11767 others are as well. That's the way the DevIL developers release
11768 it.
11769 DevIL_ILUT_FOUND
11771 New in version 3.21.
11772 This is set to TRUE if the ILUT library is found.
11775 FindDoxygen
11777 Doxygen is a documentation generation tool (see
11778 https://www.doxygen.nl). This module looks for Doxygen and some op‐
11779 tional tools it supports:
11780 dot Graphviz dot utility used to render various graphs.
11782 mscgen Message Chart Generator utility used by Doxygen's \msc and \msc‐
11784 file commands.
11785 dia Dia the diagram editor used by Doxygen's \diafile command.
11787 New in version 3.9: These tools are available as components in the
11789 find_package() command. For example:
11790 # Require dot, treat the other components as optional
11793 find_package(Doxygen
11794 REQUIRED dot
11795 OPTIONAL_COMPONENTS mscgen dia)
11796 The following variables are defined by this module:
11798 DOXYGEN_FOUND
11800 True if the doxygen executable was found.
11801 DOXYGEN_VERSION
11803 The version reported by doxygen --version.
11804 New in version 3.9: The module defines IMPORTED targets for Doxygen and
11806 each component found. These can be used as part of custom commands,
11807 etc. and should be preferred over old-style (and now deprecated) vari‐
11808 ables like DOXYGEN_EXECUTABLE. The following import targets are defined
11809 if their corresponding executable could be found (the component import
11810 targets will only be defined if that component was requested):
11811 Doxygen::doxygen
11814 Doxygen::dot
11815 Doxygen::mscgen
11816 Doxygen::dia
11817 Functions
11819 doxygen_add_docs
11820 New in version 3.9.
11821 This function is intended as a convenience for adding a target
11824 for generating documentation with Doxygen. It aims to provide
11825 sensible defaults so that projects can generally just provide
11826 the input files and directories and that will be sufficient to
11827 give sensible results. The function supports the ability to cus‐
11828 tomize the Doxygen configuration used to build the documenta‐
11829 tion.
11830 doxygen_add_docs(targetName
11832 [filesOrDirs...]
11833 [ALL]
11834 [USE_STAMP_FILE]
11835 [WORKING_DIRECTORY dir]
11836 [COMMENT comment]
11837 [CONFIG_FILE filename])
11838 The function constructs a Doxyfile and defines a custom target
11840 that runs Doxygen on that generated file. The listed files and
11841 directories are used as the INPUT of the generated Doxyfile and
11842 they can contain wildcards. Any files that are listed explic‐
11843 itly will also be added as SOURCES of the custom target so they
11844 will show up in an IDE project's source list.
11845 So that relative input paths work as expected, by default the
11847 working directory of the Doxygen command will be the current
11848 source directory (i.e. CMAKE_CURRENT_SOURCE_DIR). This can be
11849 overridden with the WORKING_DIRECTORY option to change the di‐
11850 rectory used as the relative base point. Note also that Doxy‐
11851 gen's default behavior is to strip the working directory from
11852 relative paths in the generated documentation (see the
11853 STRIP_FROM_PATH Doxygen config option for details).
11854 If provided, the optional comment will be passed as the COMMENT
11856 for the add_custom_target() command used to create the custom
11857 target internally.
11858 New in version 3.27: If CONFIG_FILE is set, the given file pro‐
11860 vided with full-path will be used as doxygen configuration file
11861 New in version 3.12: If ALL is set, the target will be added to
11864 the default build target.
11865 New in version 3.16: If USE_STAMP_FILE is set, the custom com‐
11868 mand defined by this function will create a stamp file with the
11869 name <targetName>.stamp in the current binary directory whenever
11870 doxygen is re-run. With this option present, all items in
11871 <filesOrDirs> must be files (i.e. no directories, symlinks or
11872 wildcards) and each of the files must exist at the time doxy‐
11873 gen_add_docs() is called. An error will be raised if any of the
11874 items listed is missing or is not a file when USE_STAMP_FILE is
11875 given. A dependency will be created on each of the files so
11876 that doxygen will only be re-run if one of the files is updated.
11877 Without the USE_STAMP_FILE option, doxygen will always be re-run
11878 if the <targetName> target is built regardless of whether any‐
11879 thing listed in <filesOrDirs> has changed.
11880 The contents of the generated Doxyfile can be customized by set‐
11883 ting CMake variables before calling doxygen_add_docs(). Any
11884 variable with a name of the form DOXYGEN_<tag> will have its
11885 value substituted for the corresponding <tag> configuration op‐
11886 tion in the Doxyfile. See the Doxygen documentation for the full
11887 list of supported configuration options.
11888 Some of Doxygen's defaults are overridden to provide more appro‐
11890 priate behavior for a CMake project. Each of the following will
11891 be explicitly set unless the variable already has a value before
11892 doxygen_add_docs() is called (with some exceptions noted):
11893 DOXYGEN_HAVE_DOT
11895 Set to YES if the dot component was requested and it was
11896 found, NO otherwise. Any existing value of DOXY‐
11897 GEN_HAVE_DOT is ignored.
11898 DOXYGEN_DOT_MULTI_TARGETS
11900 Set to YES by this module (note that this requires a dot
11901 version newer than 1.8.10). This option is only meaning‐
11902 ful if DOXYGEN_HAVE_DOT is also set to YES.
11903 DOXYGEN_GENERATE_LATEX
11905 Set to NO by this module.
11906 DOXYGEN_WARN_FORMAT
11908 For Visual Studio based generators, this is set to the
11909 form recognized by the Visual Studio IDE: $file($line) :
11910 $text. For all other generators, Doxygen's default value
11911 is not overridden.
11912 DOXYGEN_PROJECT_NAME
11914 Populated with the name of the current project (i.e.
11915 PROJECT_NAME).
11916 DOXYGEN_PROJECT_NUMBER
11918 Populated with the version of the current project (i.e.
11919 PROJECT_VERSION).
11920 DOXYGEN_PROJECT_BRIEF
11922 Populated with the description of the current project
11923 (i.e. PROJECT_DESCRIPTION).
11924 DOXYGEN_INPUT
11926 Projects should not set this variable. It will be popu‐
11927 lated with the set of files and directories passed to
11928 doxygen_add_docs(), thereby providing consistent behavior
11929 with the other built-in commands like add_executable(),
11930 add_library() and add_custom_target(). If a variable
11931 named DOXYGEN_INPUT is set by the project, it will be ig‐
11932 nored and a warning will be issued.
11933 DOXYGEN_RECURSIVE
11935 Set to YES by this module.
11936 DOXYGEN_EXCLUDE_PATTERNS
11938 If the set of inputs includes directories, this variable
11939 will specify patterns used to exclude files from them.
11940 The following patterns are added by doxygen_add_docs() to
11941 ensure CMake-specific files and directories are not in‐
11942 cluded in the input. If the project sets DOXYGEN_EX‐
11943 CLUDE_PATTERNS, those contents are merged with these ad‐
11944 ditional patterns rather than replacing them:
11945 */.git/*
11947 */.svn/*
11948 */.hg/*
11949 */CMakeFiles/*
11950 */_CPack_Packages/*
11951 DartConfiguration.tcl
11952 CMakeLists.txt
11953 CMakeCache.txt
11954 DOXYGEN_OUTPUT_DIRECTORY
11956 Set to CMAKE_CURRENT_BINARY_DIR by this module. Note that
11957 if the project provides its own value for this and it is
11958 a relative path, it will be converted to an absolute path
11959 relative to the current binary directory. This is neces‐
11960 sary because doxygen will normally be run from a direc‐
11961 tory within the source tree so that relative source paths
11962 work as expected. If this directory does not exist, it
11963 will be recursively created prior to executing the doxy‐
11964 gen commands.
11965 To change any of these defaults or override any other Doxygen config
11967 option, set relevant variables before calling doxygen_add_docs(). For
11968 example:
11969 set(DOXYGEN_GENERATE_HTML NO)
11971 set(DOXYGEN_GENERATE_MAN YES)
11972 doxygen_add_docs(
11974 doxygen
11975 ${PROJECT_SOURCE_DIR}
11976 COMMENT "Generate man pages"
11977 )
11978 A number of Doxygen config options accept lists of values, but Doxygen
11980 requires them to be separated by whitespace. CMake variables hold lists
11981 as a string with items separated by semi-colons, so a conversion needs
11982 to be performed. The doxygen_add_docs() command specifically checks the
11983 following Doxygen config options and will convert their associated
11984 CMake variable's contents into the required form if set. CMake vari‐
11985 ables are named DOXYGEN_<name> for the Doxygen settings specified here.
11986 ABBREVIATE_BRIEF
11988 ALIASES
11989 CITE_BIB_FILES
11990 DIAFILE_DIRS
11991 DOTFILE_DIRS
11992 DOT_FONTPATH
11993 ENABLED_SECTIONS
11994 EXAMPLE_PATH
11995 EXAMPLE_PATTERNS
11996 EXCLUDE
11997 EXCLUDE_PATTERNS
11998 EXCLUDE_SYMBOLS
11999 EXPAND_AS_DEFINED
12000 EXTENSION_MAPPING
12001 EXTRA_PACKAGES
12002 EXTRA_SEARCH_MAPPINGS
12003 FILE_PATTERNS
12004 FILTER_PATTERNS
12005 FILTER_SOURCE_PATTERNS
12006 HTML_EXTRA_FILES
12007 HTML_EXTRA_STYLESHEET
12008 IGNORE_PREFIX
12009 IMAGE_PATH
12010 INCLUDE_FILE_PATTERNS
12011 INCLUDE_PATH
12012 INPUT
12013 LATEX_EXTRA_FILES
12014 LATEX_EXTRA_STYLESHEET
12015 MATHJAX_EXTENSIONS
12016 MSCFILE_DIRS
12017 PLANTUML_INCLUDE_PATH
12018 PREDEFINED
12019 QHP_CUST_FILTER_ATTRS
12020 QHP_SECT_FILTER_ATTRS
12021 STRIP_FROM_INC_PATH
12022 STRIP_FROM_PATH
12023 TAGFILES
12024 TCL_SUBST
12025 The following single value Doxygen options will be quoted automatically
12027 if they contain at least one space:
12028 CHM_FILE
12030 DIA_PATH
12031 DOCBOOK_OUTPUT
12032 DOCSET_FEEDNAME
12033 DOCSET_PUBLISHER_NAME
12034 DOT_FONTNAME
12035 DOT_PATH
12036 EXTERNAL_SEARCH_ID
12037 FILE_VERSION_FILTER
12038 GENERATE_TAGFILE
12039 HHC_LOCATION
12040 HTML_FOOTER
12041 HTML_HEADER
12042 HTML_OUTPUT
12043 HTML_STYLESHEET
12044 INPUT_FILTER
12045 LATEX_FOOTER
12046 LATEX_HEADER
12047 LATEX_OUTPUT
12048 LAYOUT_FILE
12049 MAN_OUTPUT
12050 MAN_SUBDIR
12051 MATHJAX_CODEFILE
12052 MSCGEN_PATH
12053 OUTPUT_DIRECTORY
12054 PERL_PATH
12055 PLANTUML_JAR_PATH
12056 PROJECT_BRIEF
12057 PROJECT_LOGO
12058 PROJECT_NAME
12059 QCH_FILE
12060 QHG_LOCATION
12061 QHP_CUST_FILTER_NAME
12062 QHP_VIRTUAL_FOLDER
12063 RTF_EXTENSIONS_FILE
12064 RTF_OUTPUT
12065 RTF_STYLESHEET_FILE
12066 SEARCHDATA_FILE
12067 USE_MDFILE_AS_MAINPAGE
12068 WARN_FORMAT
12069 WARN_LOGFILE
12070 XML_OUTPUT
12071 New in version 3.11: There are situations where it may be undesirable
12073 for a particular config option to be automatically quoted by doxy‐
12074 gen_add_docs(), such as ALIASES which may need to include its own em‐
12075 bedded quoting. The DOXYGEN_VERBATIM_VARS variable can be used to
12076 specify a list of Doxygen variables (including the leading DOXYGEN_
12077 prefix) which should not be quoted. The project is then responsible
12078 for ensuring that those variables' values make sense when placed di‐
12079 rectly in the Doxygen input file. In the case of list variables, list
12080 items are still separated by spaces, it is only the automatic quoting
12081 that is skipped. For example, the following allows doxygen_add_docs()
12082 to apply quoting to DOXYGEN_PROJECT_BRIEF, but not each item in the
12083 DOXYGEN_ALIASES list (bracket syntax can also be used to make working
12084 with embedded quotes easier):
12085 set(DOXYGEN_PROJECT_BRIEF "String with spaces")
12088 set(DOXYGEN_ALIASES
12089 [[somealias="@some_command param"]]
12090 "anotherAlias=@foobar"
12091 )
12092 set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)
12093 The resultant Doxyfile will contain the following lines:
12095 PROJECT_BRIEF = "String with spaces"
12097 ALIASES = somealias="@some_command param" anotherAlias=@foobar
12098 Deprecated Result Variables
12100 Deprecated since version 3.9.
12101 For compatibility with previous versions of CMake, the following vari‐
12104 ables are also defined but they are deprecated and should no longer be
12105 used:
12106 DOXYGEN_EXECUTABLE
12108 The path to the doxygen command. If projects need to refer to
12109 the doxygen executable directly, they should use the Doxy‐
12110 gen::doxygen import target instead.
12111 DOXYGEN_DOT_FOUND
12113 True if the dot executable was found.
12114 DOXYGEN_DOT_EXECUTABLE
12116 The path to the dot command. If projects need to refer to the
12117 dot executable directly, they should use the Doxygen::dot import
12118 target instead.
12119 DOXYGEN_DOT_PATH
12121 The path to the directory containing the dot executable as re‐
12122 ported in DOXYGEN_DOT_EXECUTABLE. The path may have forward
12123 slashes even on Windows and is not suitable for direct substitu‐
12124 tion into a Doxyfile.in template. If you need this value, get
12125 the IMPORTED_LOCATION property of the Doxygen::dot target and
12126 use get_filename_component() to extract the directory part of
12127 that path. You may also want to consider using
12128 file(TO_NATIVE_PATH) to prepare the path for a Doxygen configu‐
12129 ration file.
12130 Deprecated Hint Variables
12132 Deprecated since version 3.9.
12133 DOXYGEN_SKIP_DOT
12136 This variable has no effect for the component form of find_pack‐
12137 age. In backward compatibility mode (i.e. without components
12138 list) it prevents the finder module from searching for
12139 Graphviz's dot utility.
12140 FindEnvModules
12142 New in version 3.15.
12143 Locate an environment module implementation and make commands available
12146 to CMake scripts to use them. This is compatible with both Lua-based
12147 Lmod and TCL-based EnvironmentModules.
12148 This module is intended for the use case of setting up the compiler and
12150 library environment within a CTest Script (ctest -S). It can also be
12151 used in a CMake Script (cmake -P).
12152 NOTE:
12154 The loaded environment will not survive past the end of the calling
12155 process. Do not use this module in project code (CMakeLists.txt
12156 files) to load a compiler environment; it will not be available dur‐
12157 ing the build. Instead load the environment manually before running
12158 CMake or using the generated build system.
12159 Example Usage
12161 set(CTEST_BUILD_NAME "CrayLinux-CrayPE-Cray-dynamic")
12162 set(CTEST_BUILD_CONFIGURATION Release)
12163 set(CTEST_BUILD_FLAGS "-k -j8")
12164 set(CTEST_CMAKE_GENERATOR "Unix Makefiles")
12165 ...
12167 find_package(EnvModules REQUIRED)
12169 env_module(purge)
12171 env_module(load modules)
12172 env_module(load craype)
12173 env_module(load PrgEnv-cray)
12174 env_module(load craype-knl)
12175 env_module(load cray-mpich)
12176 env_module(load cray-libsci)
12177 set(ENV{CRAYPE_LINK_TYPE} dynamic)
12179 ...
12181 Result Variables
12183 This module will set the following variables in your project:
12184 EnvModules_FOUND
12186 True if a compatible environment modules framework was found.
12187 Cache Variables
12189 The following cache variable will be set:
12190 EnvModules_COMMAND
12192 The low level module command to use. Currently supported imple‐
12193 mentations are the Lua based Lmod and TCL based EnvironmentMod‐
12194 ules.
12195 Environment Variables
12197 ENV{MODULESHOME}
12198 Usually set by the module environment implementation, used as a
12199 hint to locate the module command to execute.
12200 Provided Functions
12202 This defines the following CMake functions for interacting with envi‐
12203 ronment modules:
12204 env_module
12206 Execute an aribitrary module command:
12207 env_module(cmd arg1 ... argN)
12209 env_module(
12210 COMMAND cmd arg1 ... argN
12211 [OUTPUT_VARIABLE <out-var>]
12212 [RESULT_VARIABLE <ret-var>]
12213 )
12214 The options are:
12216 cmd arg1 ... argN
12218 The module sub-command and arguments to execute as if
12219 they were passed directly to the module command in your
12220 shell environment.
12221 OUTPUT_VARIABLE <out-var>
12223 The standard output from executing the module command.
12224 RESULT_VARIABLE <ret-var>
12226 The return code from executing the module command.
12227 env_module_swap
12229 Swap one module for another:
12230 env_module_swap(out_mod in_mod
12232 [OUTPUT_VARIABLE <out-var>]
12233 [RESULT_VARIABLE <ret-var>]
12234 )
12235 This is functionally equivalent to the module swap out_mod
12237 in_mod shell command. The options are:
12238 OUTPUT_VARIABLE <out-var>
12240 The standard output from executing the module command.
12241 RESULT_VARIABLE <ret-var>
12243 The return code from executing the module command.
12244 env_module_list
12246 Retrieve the list of currently loaded modules:
12247 env_module_list(<out-var>)
12249 This is functionally equivalent to the module list shell com‐
12251 mand. The result is stored in <out-var> as a properly formatted
12252 CMake semicolon-separated list variable.
12253 env_module_avail
12255 Retrieve the list of available modules:
12256 env_module_avail([<mod-prefix>] <out-var>)
12258 This is functionally equivalent to the module avail <mod-prefix>
12260 shell command. The result is stored in <out-var> as a properly
12261 formatted CMake semicolon-separated list variable.
12262 FindEXPAT
12264 Find the native Expat headers and library. Expat is a stream-oriented
12265 XML parser library written in C.
12266 Imported Targets
12268 New in version 3.10.
12269 This module defines the following IMPORTED targets:
12272 EXPAT::EXPAT
12274 The Expat expat library, if found.
12275 Result Variables
12277 This module will set the following variables in your project:
12278 EXPAT_INCLUDE_DIRS
12280 where to find expat.h, etc.
12281 EXPAT_LIBRARIES
12283 the libraries to link against to use Expat.
12284 EXPAT_FOUND
12286 true if the Expat headers and libraries were found.
12287 FindFLEX
12289 Find Fast Lexical Analyzer (Flex) executable and provides a macro to
12290 generate custom build rules
12291 The module defines the following variables:
12293 FLEX_FOUND - True is flex executable is found
12295 FLEX_EXECUTABLE - the path to the flex executable
12296 FLEX_VERSION - the version of flex
12297 FLEX_LIBRARIES - The flex libraries
12298 FLEX_INCLUDE_DIRS - The path to the flex headers
12299 The minimum required version of flex can be specified using the stan‐
12301 dard syntax, e.g. find_package(FLEX 2.5.13)
12302 If flex is found on the system, the module provides the macro:
12304 FLEX_TARGET(Name FlexInput FlexOutput
12306 [COMPILE_FLAGS <string>]
12307 [DEFINES_FILE <string>]
12308 )
12309 which creates a custom command to generate the FlexOutput file from the
12311 FlexInput file. Name is an alias used to get details of this custom
12312 command. If COMPILE_FLAGS option is specified, the next parameter is
12313 added to the flex command line.
12314 New in version 3.5: If flex is configured to output a header file, the
12316 DEFINES_FILE option may be used to specify its name.
12317 Changed in version 3.17: When CMP0098 is set to NEW, flex runs in the
12320 CMAKE_CURRENT_BINARY_DIR directory.
12321 The macro defines the following variables:
12324 FLEX_${Name}_DEFINED - true is the macro ran successfully
12326 FLEX_${Name}_OUTPUTS - the source file generated by the custom rule, an
12327 alias for FlexOutput
12328 FLEX_${Name}_INPUT - the flex source file, an alias for ${FlexInput}
12329 FLEX_${Name}_OUTPUT_HEADER - the header flex output, if any.
12330 Flex scanners often use tokens defined by Bison: the code generated by
12332 Flex depends of the header generated by Bison. This module also de‐
12333 fines a macro:
12334 ADD_FLEX_BISON_DEPENDENCY(FlexTarget BisonTarget)
12336 which adds the required dependency between a scanner and a parser where
12338 FlexTarget and BisonTarget are the first parameters of respectively
12339 FLEX_TARGET and BISON_TARGET macros.
12340 ====================================================================
12342 Example:
12343 find_package(BISON)
12345 find_package(FLEX)
12346 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
12348 FLEX_TARGET(MyScanner lexer.l ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp)
12349 ADD_FLEX_BISON_DEPENDENCY(MyScanner MyParser)
12350 include_directories(${CMAKE_CURRENT_BINARY_DIR})
12352 add_executable(Foo
12353 Foo.cc
12354 ${BISON_MyParser_OUTPUTS}
12355 ${FLEX_MyScanner_OUTPUTS}
12356 )
12357 target_link_libraries(Foo ${FLEX_LIBRARIES})
12358 ====================================================================
12359 FindFLTK
12361 Find the Fast Light Toolkit (FLTK) library
12362 Input Variables
12364 By default this module will search for all of the FLTK components and
12365 add them to the FLTK_LIBRARIES variable. You can limit the components
12366 which get placed in FLTK_LIBRARIES by defining one or more of the fol‐
12367 lowing three options:
12368 FLTK_SKIP_OPENGL
12370 Set to true to disable searching for the FLTK GL library
12371 FLTK_SKIP_FORMS
12373 Set to true to disable searching for the FLTK Forms library
12374 FLTK_SKIP_IMAGES
12376 Set to true to disable searching for the FLTK Images library
12377 FLTK is composed also by a binary tool. You can set the following op‐
12379 tion:
12380 FLTK_SKIP_FLUID
12382 Set to true to not look for the FLUID binary
12383 Result Variables
12385 The following variables will be defined:
12386 FLTK_FOUND
12388 True if all components not skipped were found
12389 FLTK_INCLUDE_DIR
12391 Path to the include directory for FLTK header files
12392 FLTK_LIBRARIES
12394 List of the FLTK libraries found
12395 FLTK_FLUID_EXECUTABLE
12397 Path to the FLUID binary tool
12398 FLTK_WRAP_UI
12400 True if FLUID is found, used to enable the FLTK_WRAP_UI command
12401 Cache Variables
12403 The following cache variables are also available to set or use:
12404 FLTK_BASE_LIBRARY_RELEASE
12406 The FLTK base library (optimized)
12407 FLTK_BASE_LIBRARY_DEBUG
12409 The FLTK base library (debug)
12410 FLTK_GL_LIBRARY_RELEASE
12412 The FLTK GL library (optimized)
12413 FLTK_GL_LIBRARY_DEBUG
12415 The FLTK GL library (debug)
12416 FLTK_FORMS_LIBRARY_RELEASE
12418 The FLTK Forms library (optimized)
12419 FLTK_FORMS_LIBRARY_DEBUG
12421 The FLTK Forms library (debug)
12422 FLTK_IMAGES_LIBRARY_RELEASE
12424 The FLTK Images protobuf library (optimized)
12425 FLTK_IMAGES_LIBRARY_DEBUG
12427 The FLTK Images library (debug)
12428 New in version 3.11: Debug and Release variants are found separately
12430 and use per-configuration variables.
12431 FindFLTK2
12434 Find the native FLTK 2.0 includes and library
12435 The following settings are defined
12437 FLTK2_FLUID_EXECUTABLE, where to find the Fluid tool
12439 FLTK2_WRAP_UI, This enables the FLTK2_WRAP_UI command
12440 FLTK2_INCLUDE_DIR, where to find include files
12441 FLTK2_LIBRARIES, list of fltk2 libraries
12442 FLTK2_FOUND, Don't use FLTK2 if false.
12443 The following settings should not be used in general.
12445 FLTK2_BASE_LIBRARY = the full path to fltk2.lib
12447 FLTK2_GL_LIBRARY = the full path to fltk2_gl.lib
12448 FLTK2_IMAGES_LIBRARY = the full path to fltk2_images.lib
12449 FindFontconfig
12451 New in version 3.14.
12452 Find Fontconfig headers and library.
12455 Imported Targets
12457 Fontconfig::Fontconfig
12458 The Fontconfig library, if found.
12459 Result Variables
12461 This will define the following variables in your project:
12462 Fontconfig_FOUND
12464 true if (the requested version of) Fontconfig is available.
12465 Fontconfig_VERSION
12467 the version of Fontconfig.
12468 Fontconfig_LIBRARIES
12470 the libraries to link against to use Fontconfig.
12471 Fontconfig_INCLUDE_DIRS
12473 where to find the Fontconfig headers.
12474 Fontconfig_COMPILE_OPTIONS
12476 this should be passed to target_compile_options(), if the target
12477 is not used for linking
12478 FindFreetype
12480 Find the FreeType font renderer includes and library.
12481 Imported Targets
12483 New in version 3.10.
12484 This module defines the following IMPORTED target:
12487 Freetype::Freetype
12489 The Freetype freetype library, if found
12490 Result Variables
12492 This module will set the following variables in your project:
12493 FREETYPE_FOUND
12495 true if the Freetype headers and libraries were found
12496 FREETYPE_INCLUDE_DIRS
12498 directories containing the Freetype headers. This is the con‐
12499 catenation of the variables:
12500 FREETYPE_INCLUDE_DIR_ft2build
12502 directory holding the main Freetype API configuration
12503 header
12504 FREETYPE_INCLUDE_DIR_freetype2
12506 directory holding Freetype public headers
12507 FREETYPE_LIBRARIES
12509 the library to link against
12510 FREETYPE_VERSION_STRING
12512 the version of freetype found
12513 New in version 3.7: Debug and Release variants are found separately.
12515 Hints
12518 The user may set the environment variable FREETYPE_DIR to the root di‐
12519 rectory of a Freetype installation.
12520 FindGCCXML
12522 Find the GCC-XML front-end executable.
12523 This module will define the following variables:
12525 GCCXML - the GCC-XML front-end executable.
12527 FindGDAL
12529 Find Geospatial Data Abstraction Library (GDAL).
12530 IMPORTED Targets
12532 New in version 3.14.
12533 This module defines IMPORTED target GDAL::GDAL if GDAL has been found.
12536 Result Variables
12538 This module will set the following variables in your project:
12539 GDAL_FOUND
12541 True if GDAL is found.
12542 GDAL_INCLUDE_DIRS
12544 Include directories for GDAL headers.
12545 GDAL_LIBRARIES
12547 Libraries to link to GDAL.
12548 GDAL_VERSION
12550 New in version 3.14: The version of GDAL found.
12551 Cache variables
12554 The following cache variables may also be set:
12555 GDAL_LIBRARY
12557 The libgdal library file.
12558 GDAL_INCLUDE_DIR
12560 The directory containing gdal.h.
12561 Hints
12563 Set GDAL_DIR or GDAL_ROOT in the environment to specify the GDAL in‐
12564 stallation prefix.
12565 The following variables may be set to modify the search strategy:
12567 FindGDAL_SKIP_GDAL_CONFIG
12569 If set, gdal-config will not be used. This can be useful if
12570 there are GDAL libraries built with autotools (which provide the
12571 tool) and CMake (which do not) in the same environment.
12572 GDAL_ADDITIONAL_LIBRARY_VERSIONS
12574 Extra versions of library names to search for.
12575 FindGettext
12577 Find GNU gettext tools
12578 This module looks for the GNU gettext tools. This module defines the
12580 following values:
12581 GETTEXT_MSGMERGE_EXECUTABLE: the full path to the msgmerge tool.
12583 GETTEXT_MSGFMT_EXECUTABLE: the full path to the msgfmt tool.
12584 GETTEXT_FOUND: True if gettext has been found.
12585 GETTEXT_VERSION_STRING: the version of gettext found (since CMake 2.8.8)
12586 Additionally it provides the following macros:
12588 GETTEXT_CREATE_TRANSLATIONS ( outputFile [ALL] file1 ... fileN )
12590 This will create a target "translations" which will convert the
12592 given input po files into the binary output mo file. If the
12593 ALL option is used, the translations will also be created when
12594 building the default target.
12595 GETTEXT_PROCESS_POT_FILE( <potfile> [ALL] [INSTALL_DESTINATION <dest‐
12597 dir>] LANGUAGES <lang1> <lang2> ... )
12598 Process the given pot file to mo files.
12600 If INSTALL_DESTINATION is given then automatically install rules will
12601 be created, the language subdirectory will be taken into account
12602 (by default use share/locale/).
12603 If ALL is specified, the pot file is processed when building the all target.
12604 It creates a custom target "potfile".
12605 GETTEXT_PROCESS_PO_FILES( <lang> [ALL] [INSTALL_DESTINATION <dir>]
12607 PO_FILES <po1> <po2> ... )
12608 Process the given po files to mo files for the given language.
12610 If INSTALL_DESTINATION is given then automatically install rules will
12611 be created, the language subdirectory will be taken into account
12612 (by default use share/locale/).
12613 If ALL is specified, the po files are processed when building the all target.
12614 It creates a custom target "pofiles".
12615 New in version 3.2: If you wish to use the Gettext library (libintl),
12617 use FindIntl.
12618 FindGIF
12621 This finds the Graphics Interchange Format (GIF) library (giflib)
12622 Imported targets
12624 This module defines the following IMPORTED target:
12625 GIF::GIF
12627 The giflib library, if found.
12628 Result variables
12630 This module will set the following variables in your project:
12631 GIF_FOUND
12633 If false, do not try to use GIF.
12634 GIF_INCLUDE_DIRS
12636 where to find gif_lib.h, etc.
12637 GIF_LIBRARIES
12639 the libraries needed to use GIF.
12640 GIF_VERSION
12642 3, 4 or a full version string (eg 5.1.4) for versions >= 4.1.6.
12643 Cache variables
12645 The following cache variables may also be set:
12646 GIF_INCLUDE_DIR
12648 where to find the GIF headers.
12649 GIF_LIBRARY
12651 where to find the GIF library.
12652 Hints
12654 GIF_DIR is an environment variable that would correspond to the ./con‐
12655 figure --prefix=$GIF_DIR.
12656 FindGit
12658 The module defines the following variables:
12659 GIT_EXECUTABLE
12661 Path to Git command-line client.
12662 Git_FOUND, GIT_FOUND
12664 True if the Git command-line client was found.
12665 GIT_VERSION_STRING
12667 The version of Git found.
12668 New in version 3.14: The module defines the following IMPORTED targets
12670 (when CMAKE_ROLE is PROJECT):
12671 Git::Git
12674 Executable of the Git command-line client.
12675 Example usage:
12677 find_package(Git)
12679 if(Git_FOUND)
12680 message("Git found: ${GIT_EXECUTABLE}")
12681 endif()
12682 FindGLEW
12684 Find the OpenGL Extension Wrangler Library (GLEW)
12685 Input Variables
12687 The following variables may be set to influence this module's behavior:
12688 GLEW_USE_STATIC_LIBS
12690 to find and create IMPORTED target for static linkage.
12691 GLEW_VERBOSE
12693 to output a detailed log of this module.
12694 Imported Targets
12696 New in version 3.1.
12697 This module defines the following Imported Targets:
12700 GLEW::glew
12702 The GLEW shared library.
12703 GLEW::glew_s
12705 The GLEW static library, if GLEW_USE_STATIC_LIBS is set to TRUE.
12706 GLEW::GLEW
12708 Duplicates either GLEW::glew or GLEW::glew_s based on availabil‐
12709 ity.
12710 Result Variables
12712 This module defines the following variables:
12713 GLEW_INCLUDE_DIRS
12715 include directories for GLEW
12716 GLEW_LIBRARIES
12718 libraries to link against GLEW
12719 GLEW_SHARED_LIBRARIES
12721 libraries to link against shared GLEW
12722 GLEW_STATIC_LIBRARIES
12724 libraries to link against static GLEW
12725 GLEW_FOUND
12727 true if GLEW has been found and can be used
12728 GLEW_VERSION
12730 GLEW version
12731 GLEW_VERSION_MAJOR
12733 GLEW major version
12734 GLEW_VERSION_MINOR
12736 GLEW minor version
12737 GLEW_VERSION_MICRO
12739 GLEW micro version
12740 New in version 3.7: Debug and Release variants are found separately.
12742 FindGLUT
12745 Find OpenGL Utility Toolkit (GLUT) library and include files.
12746 IMPORTED Targets
12748 New in version 3.1.
12749 This module defines the IMPORTED targets:
12752 GLUT::GLUT
12754 Defined if the system has GLUT.
12755 Result Variables
12757 This module defines the following variables:
12758 GLUT_FOUND
12760 True if glut was found.
12761 GLUT_INCLUDE_DIRS
12763 New in version 3.23.
12764 Where to find GL/glut.h, etc.
12767 GLUT_LIBRARIES
12769 List of libraries for using glut.
12770 Cache Variables
12772 This module may set the following variables depending on platform.
12773 These variables may optionally be set to help this module find the cor‐
12774 rect files, but clients should not use these as results:
12775 GLUT_INCLUDE_DIR
12777 The full path to the directory containing GL/glut.h, not includ‐
12778 ing GL/.
12779 GLUT_glut_LIBRARY
12781 The full path to the glut library.
12782 GLUT_Xmu_LIBRARY
12784 The full path to the Xmu library.
12785 GLUT_Xi_LIBRARY
12787 The full path to the Xi Library.
12788 Obsolete Variables
12790 The following variables may also be provided, for backwards compatibil‐
12791 ity:
12792 GLUT_INCLUDE_DIR
12794 This is one of above Cache Variables, but prior to CMake 3.23
12795 was also a result variable. Prefer to use GLUT_INCLUDE_DIRS in‐
12796 stead in CMake 3.23 and above.
12797 FindGnuplot
12799 this module looks for gnuplot
12800 Once done this will define
12802 GNUPLOT_FOUND - system has Gnuplot
12804 GNUPLOT_EXECUTABLE - the Gnuplot executable
12805 GNUPLOT_VERSION_STRING - the version of Gnuplot found (since CMake 2.8.8)
12806 GNUPLOT_VERSION_STRING will not work for old versions like 3.7.1.
12808 FindGnuTLS
12810 Find the GNU Transport Layer Security library (gnutls)
12811 IMPORTED Targets
12813 New in version 3.16.
12814 This module defines IMPORTED target GnuTLS::GnuTLS, if gnutls has been
12817 found.
12818 Result Variables
12820 GNUTLS_FOUND
12821 System has gnutls
12822 GNUTLS_INCLUDE_DIR
12824 The gnutls include directory
12825 GNUTLS_LIBRARIES
12827 The libraries needed to use gnutls
12828 GNUTLS_DEFINITIONS
12830 Compiler switches required for using gnutls
12831 GNUTLS_VERSION
12833 version of gnutls.
12834 FindGSL
12836 New in version 3.2.
12837 Find the native GNU Scientific Library (GSL) includes and libraries.
12840 The GNU Scientific Library (GSL) is a numerical library for C and C++
12842 programmers. It is free software under the GNU General Public License.
12843 Imported Targets
12845 If GSL is found, this module defines the following IMPORTED targets:
12846 GSL::gsl - The main GSL library.
12848 GSL::gslcblas - The CBLAS support library used by GSL.
12849 Result Variables
12851 This module will set the following variables in your project:
12852 GSL_FOUND - True if GSL found on the local system
12854 GSL_INCLUDE_DIRS - Location of GSL header files.
12855 GSL_LIBRARIES - The GSL libraries.
12856 GSL_VERSION - The version of the discovered GSL install.
12857 Hints
12859 Set GSL_ROOT_DIR to a directory that contains a GSL installation.
12860 This script expects to find libraries at $GSL_ROOT_DIR/lib and the GSL
12862 headers at $GSL_ROOT_DIR/include/gsl. The library directory may op‐
12863 tionally provide Release and Debug folders. If available, the libraries
12864 named gsld, gslblasd or cblasd are recognized as debug libraries. For
12865 Unix-like systems, this script will use $GSL_ROOT_DIR/bin/gsl-config
12866 (if found) to aid in the discovery of GSL.
12867 Cache Variables
12869 This module may set the following variables depending on platform and
12870 type of GSL installation discovered. These variables may optionally be
12871 set to help this module find the correct files:
12872 GSL_CBLAS_LIBRARY - Location of the GSL CBLAS library.
12874 GSL_CBLAS_LIBRARY_DEBUG - Location of the debug GSL CBLAS library (if any).
12875 GSL_CONFIG_EXECUTABLE - Location of the ``gsl-config`` script (if any).
12876 GSL_LIBRARY - Location of the GSL library.
12877 GSL_LIBRARY_DEBUG - Location of the debug GSL library (if any).
12878 FindGTest
12880 Locate the Google C++ Testing Framework.
12881 New in version 3.20: Upstream GTestConfig.cmake is used if possible.
12883 Imported targets
12886 New in version 3.20: This module defines the following IMPORTED tar‐
12887 gets:
12888 GTest::gtest
12891 The Google Test gtest library, if found; adds Thread::Thread au‐
12892 tomatically
12893 GTest::gtest_main
12895 The Google Test gtest_main library, if found
12896 New in version 3.23.
12898 GTest::gmock
12901 The Google Mock gmock library, if found; adds Thread::Thread au‐
12902 tomatically
12903 GTest::gmock_main
12905 The Google Mock gmock_main library, if found
12906 Deprecated since version 3.20: For backwards compatibility, this module
12908 defines additionally the following deprecated IMPORTED targets (avail‐
12909 able since 3.5):
12910 GTest::GTest
12913 The Google Test gtest library, if found; adds Thread::Thread au‐
12914 tomatically
12915 GTest::Main
12917 The Google Test gtest_main library, if found
12918 Result variables
12920 This module will set the following variables in your project:
12921 GTest_FOUND
12923 Found the Google Testing framework
12924 GTEST_INCLUDE_DIRS
12926 the directory containing the Google Test headers
12927 The library variables below are set as normal variables. These contain
12929 debug/optimized keywords when a debugging library is found.
12930 GTEST_LIBRARIES
12932 The Google Test gtest library; note it also requires linking
12933 with an appropriate thread library
12934 GTEST_MAIN_LIBRARIES
12936 The Google Test gtest_main library
12937 GTEST_BOTH_LIBRARIES
12939 Both gtest and gtest_main
12940 Cache variables
12942 The following cache variables may also be set:
12943 GTEST_ROOT
12945 The root directory of the Google Test installation (may also be
12946 set as an environment variable)
12947 GTEST_MSVC_SEARCH
12949 If compiling with MSVC, this variable can be set to MT or MD
12950 (the default) to enable searching a GTest build tree
12951 Example usage
12953 enable_testing()
12954 find_package(GTest REQUIRED)
12955 add_executable(foo foo.cc)
12957 target_link_libraries(foo GTest::gtest GTest::gtest_main)
12958 add_test(AllTestsInFoo foo)
12960 Deeper integration with CTest
12962 See GoogleTest for information on the gtest_add_tests() and
12963 gtest_discover_tests() commands.
12964 Changed in version 3.9: Previous CMake versions defined
12966 gtest_add_tests() macro in this module.
12967 FindGTK
12970 Find GTK, glib and GTKGLArea
12971 GTK_INCLUDE_DIR - Directories to include to use GTK
12973 GTK_LIBRARIES - Files to link against to use GTK
12974 GTK_FOUND - GTK was found
12975 GTK_GL_FOUND - GTK's GL features were found
12976 FindGTK2
12978 Find the GTK2 widget libraries and several of its other optional compo‐
12979 nents like gtkmm, glade, and glademm.
12980 Specify one or more of the following components as you call this find
12982 module. See example below.
12983 • gtk
12985 • gtkmm
12987 • glade
12989 • glademm
12991 Imported Targets
12993 This module defines the following IMPORTED targets (subject to compo‐
12994 nent selection):
12995 GTK2::atk, GTK2::atkmm, GTK2::cairo, GTK2::cairomm, GTK2::gdk_pixbuf,
12997 GTK2::gdk, GTK2::gdkmm, GTK2::gio, GTK2::giomm, GTK2::glade,
12998 GTK2::glademm, GTK2::glib, GTK2::glibmm, GTK2::gmodule, GTK2::gobject,
12999 GTK2::gthread, GTK2::gtk, GTK2::gtkmm, GTK2::harfbuzz, GTK2::pango,
13000 GTK2::pangocairo, GTK2::pangoft2, GTK2::pangomm, GTK2::pangoxft,
13001 GTK2::sigc.
13002 New in version 3.16.7: Added the GTK2::harfbuzz target.
13004 Result Variables
13007 The following variables will be defined for your use
13008 GTK2_FOUND
13010 Were all of your specified components found?
13011 GTK2_INCLUDE_DIRS
13013 All include directories
13014 GTK2_LIBRARIES
13016 All libraries
13017 GTK2_TARGETS
13019 New in version 3.5: All imported targets
13020 GTK2_DEFINITIONS
13023 Additional compiler flags
13024 GTK2_VERSION
13026 The version of GTK2 found (x.y.z)
13027 GTK2_MAJOR_VERSION
13029 The major version of GTK2
13030 GTK2_MINOR_VERSION
13032 The minor version of GTK2
13033 GTK2_PATCH_VERSION
13035 The patch version of GTK2
13036 New in version 3.5: When GTK2_USE_IMPORTED_TARGETS is set to TRUE,
13038 GTK2_LIBRARIES will list imported targets instead of library paths.
13039 Input Variables
13042 Optional variables you can define prior to calling this module:
13043 GTK2_DEBUG
13045 Enables verbose debugging of the module
13046 GTK2_ADDITIONAL_SUFFIXES
13048 Allows defining additional directories to search for include
13049 files
13050 Example Usage
13052 Call find_package() once. Here are some examples to pick from:
13053 Require GTK 2.6 or later:
13055 find_package(GTK2 2.6 REQUIRED gtk)
13057 Require GTK 2.10 or later and Glade:
13059 find_package(GTK2 2.10 REQUIRED gtk glade)
13061 Search for GTK/GTKMM 2.8 or later:
13063 find_package(GTK2 2.8 COMPONENTS gtk gtkmm)
13065 Use the results:
13067 if(GTK2_FOUND)
13069 include_directories(${GTK2_INCLUDE_DIRS})
13070 add_executable(mygui mygui.cc)
13071 target_link_libraries(mygui ${GTK2_LIBRARIES})
13072 endif()
13073 FindHDF5
13075 Find Hierarchical Data Format (HDF5), a library for reading and writing
13076 self describing array data.
13077 This module invokes the HDF5 wrapper compiler that should be installed
13079 alongside HDF5. Depending upon the HDF5 Configuration, the wrapper
13080 compiler is called either h5cc or h5pcc. If this succeeds, the module
13081 will then call the compiler with the show argument to see what flags
13082 are used when compiling an HDF5 client application.
13083 The module will optionally accept the COMPONENTS argument. If no COM‐
13085 PONENTS are specified, then the find module will default to finding
13086 only the HDF5 C library. If one or more COMPONENTS are specified, the
13087 module will attempt to find the language bindings for the specified
13088 components. The valid components are C, CXX, Fortran, HL. HL refers
13089 to the "high-level" HDF5 functions for C and Fortran. If the COMPO‐
13090 NENTS argument is not given, the module will attempt to find only the C
13091 bindings. For example, to use Fortran HDF5 and HDF5-HL functions, do:
13092 find_package(HDF5 COMPONENTS Fortran HL).
13093 This module will read the variable HDF5_USE_STATIC_LIBRARIES to deter‐
13095 mine whether or not to prefer a static link to a dynamic link for HDF5
13096 and all of it's dependencies. To use this feature, make sure that the
13097 HDF5_USE_STATIC_LIBRARIES variable is set before the call to find_pack‐
13098 age.
13099 New in version 3.10: Support for HDF5_USE_STATIC_LIBRARIES on Windows.
13101 Both the serial and parallel HDF5 wrappers are considered and the first
13104 directory to contain either one will be used. In the event that both
13105 appear in the same directory the serial version is preferentially se‐
13106 lected. This behavior can be reversed by setting the variable HDF5_PRE‐
13107 FER_PARALLEL to TRUE.
13108 In addition to finding the includes and libraries required to compile
13110 an HDF5 client application, this module also makes an effort to find
13111 tools that come with the HDF5 distribution that may be useful for re‐
13112 gression testing.
13113 Result Variables
13115 This module will set the following variables in your project:
13116 HDF5_FOUND
13118 HDF5 was found on the system
13119 HDF5_VERSION
13121 New in version 3.3: HDF5 library version
13122 HDF5_INCLUDE_DIRS
13125 Location of the HDF5 header files
13126 HDF5_DEFINITIONS
13128 Required compiler definitions for HDF5
13129 HDF5_LIBRARIES
13131 Required libraries for all requested bindings
13132 HDF5_HL_LIBRARIES
13134 Required libraries for the HDF5 high level API for all bindings,
13135 if the HL component is enabled
13136 Available components are: C CXX Fortran and HL. For each enabled lan‐
13138 guage binding, a corresponding HDF5_${LANG}_LIBRARIES variable, and po‐
13139 tentially HDF5_${LANG}_DEFINITIONS, will be defined. If the HL compo‐
13140 nent is enabled, then an HDF5_${LANG}_HL_LIBRARIES will also be de‐
13141 fined. With all components enabled, the following variables will be
13142 defined:
13143 HDF5_C_DEFINITIONS
13145 Required compiler definitions for HDF5 C bindings
13146 HDF5_CXX_DEFINITIONS
13148 Required compiler definitions for HDF5 C++ bindings
13149 HDF5_Fortran_DEFINITIONS
13151 Required compiler definitions for HDF5 Fortran bindings
13152 HDF5_C_INCLUDE_DIRS
13154 Required include directories for HDF5 C bindings
13155 HDF5_CXX_INCLUDE_DIRS
13157 Required include directories for HDF5 C++ bindings
13158 HDF5_Fortran_INCLUDE_DIRS
13160 Required include directories for HDF5 Fortran bindings
13161 HDF5_C_LIBRARIES
13163 Required libraries for the HDF5 C bindings
13164 HDF5_CXX_LIBRARIES
13166 Required libraries for the HDF5 C++ bindings
13167 HDF5_Fortran_LIBRARIES
13169 Required libraries for the HDF5 Fortran bindings
13170 HDF5_C_HL_LIBRARIES
13172 Required libraries for the high level C bindings
13173 HDF5_CXX_HL_LIBRARIES
13175 Required libraries for the high level C++ bindings
13176 HDF5_Fortran_HL_LIBRARIES
13178 Required libraries for the high level Fortran bindings.
13179 HDF5_IS_PARALLEL
13181 HDF5 library has parallel IO support
13182 HDF5_C_COMPILER_EXECUTABLE
13184 path to the HDF5 C wrapper compiler
13185 HDF5_CXX_COMPILER_EXECUTABLE
13187 path to the HDF5 C++ wrapper compiler
13188 HDF5_Fortran_COMPILER_EXECUTABLE
13190 path to the HDF5 Fortran wrapper compiler
13191 HDF5_C_COMPILER_EXECUTABLE_NO_INTERROGATE
13193 path to the primary C compiler which is also the HDF5 wrapper
13194 HDF5_CXX_COMPILER_EXECUTABLE_NO_INTERROGATE
13196 path to the primary C++ compiler which is also the HDF5 wrapper
13197 HDF5_Fortran_COMPILER_EXECUTABLE_NO_INTERROGATE
13199 path to the primary Fortran compiler which is also the HDF5
13200 wrapper
13201 HDF5_DIFF_EXECUTABLE
13203 path to the HDF5 dataset comparison tool
13204 With all components enabled, the following targets will be defined:
13206 HDF5::HDF5
13208 All detected HDF5_LIBRARIES.
13209 hdf5::hdf5
13211 C library.
13212 hdf5::hdf5_cpp
13214 C++ library.
13215 hdf5::hdf5_fortran
13217 Fortran library.
13218 hdf5::hdf5_hl
13220 High-level C library.
13221 hdf5::hdf5_hl_cpp
13223 High-level C++ library.
13224 hdf5::hdf5_hl_fortran
13226 High-level Fortran library.
13227 hdf5::h5diff
13229 h5diff executable.
13230 Hints
13232 The following variables can be set to guide the search for HDF5 li‐
13233 braries and includes:
13234 HDF5_PREFER_PARALLEL
13236 New in version 3.4.
13237 set true to prefer parallel HDF5 (by default, serial is pre‐
13240 ferred)
13241 HDF5_FIND_DEBUG
13243 New in version 3.9.
13244 Set true to get extra debugging output.
13247 HDF5_NO_FIND_PACKAGE_CONFIG_FILE
13249 New in version 3.8.
13250 Set true to skip trying to find hdf5-config.cmake.
13253 FindHg
13255 Extract information from a mercurial working copy.
13256 The module defines the following variables:
13258 HG_EXECUTABLE - path to mercurial command line client (hg)
13260 HG_FOUND - true if the command line client was found
13261 HG_VERSION_STRING - the version of mercurial found
13262 New in version 3.1: If the command line client executable is found the
13264 following macro is defined:
13265 HG_WC_INFO(<dir> <var-prefix>)
13268 Hg_WC_INFO extracts information of a mercurial working copy at a given
13270 location. This macro defines the following variables:
13271 <var-prefix>_WC_CHANGESET - current changeset
13273 <var-prefix>_WC_REVISION - current revision
13274 Example usage:
13276 find_package(Hg)
13278 if(HG_FOUND)
13279 message("hg found: ${HG_EXECUTABLE}")
13280 HG_WC_INFO(${PROJECT_SOURCE_DIR} Project)
13281 message("Current revision is ${Project_WC_REVISION}")
13282 message("Current changeset is ${Project_WC_CHANGESET}")
13283 endif()
13284 FindHSPELL
13286 Try to find Hebrew spell-checker (Hspell) and morphology engine.
13287 Once done this will define
13289 HSPELL_FOUND - system has Hspell
13291 HSPELL_INCLUDE_DIR - the Hspell include directory
13292 HSPELL_LIBRARIES - The libraries needed to use Hspell
13293 HSPELL_DEFINITIONS - Compiler switches required for using Hspell
13294 HSPELL_VERSION_STRING - The version of Hspell found (x.y)
13296 HSPELL_MAJOR_VERSION - the major version of Hspell
13297 HSPELL_MINOR_VERSION - The minor version of Hspell
13298 FindHTMLHelp
13300 This module looks for Microsoft HTML Help Compiler
13301 It defines:
13303 HTML_HELP_COMPILER : full path to the Compiler (hhc.exe)
13305 HTML_HELP_INCLUDE_PATH : include path to the API (htmlhelp.h)
13306 HTML_HELP_LIBRARY : full path to the library (htmlhelp.lib)
13307 FindIce
13309 New in version 3.1.
13310 Find the ZeroC Internet Communication Engine (ICE) programs, libraries
13313 and datafiles.
13314 This module supports multiple components. Components can include any
13316 of: Freeze, Glacier2, Ice, IceBox, IceDB, IceDiscovery, IceGrid, IceLo‐
13317 catorDiscovery, IcePatch, IceSSL, IceStorm, IceUtil, IceXML, or Slice.
13318 Ice 3.7 and later also include C++11-specific components: Glacier2++11,
13320 Ice++11, IceBox++11, IceDiscovery++11 IceGrid, IceLocatorDiscovery++11,
13321 IceSSL++11, IceStorm++11
13322 Note that the set of supported components is Ice version-specific.
13324 New in version 3.4: Imported targets for components and most EXECUTABLE
13326 variables.
13327 New in version 3.7: Debug and Release variants are found separately.
13330 New in version 3.10: Ice 3.7 support, including new components, pro‐
13333 grams and the Nuget package.
13334 This module reports information about the Ice installation in several
13337 variables. General variables:
13338 Ice_VERSION - Ice release version
13340 Ice_FOUND - true if the main programs and libraries were found
13341 Ice_LIBRARIES - component libraries to be linked
13342 Ice_INCLUDE_DIRS - the directories containing the Ice headers
13343 Ice_SLICE_DIRS - the directories containing the Ice slice interface
13344 definitions
13345 Imported targets:
13347 Ice::<C>
13349 Where <C> is the name of an Ice component, for example Ice::Glacier2 or
13351 Ice++11.
13352 Ice slice programs are reported in:
13354 Ice_SLICE2CONFLUENCE_EXECUTABLE - path to slice2confluence executable
13356 Ice_SLICE2CPP_EXECUTABLE - path to slice2cpp executable
13357 Ice_SLICE2CS_EXECUTABLE - path to slice2cs executable
13358 Ice_SLICE2FREEZEJ_EXECUTABLE - path to slice2freezej executable
13359 Ice_SLICE2FREEZE_EXECUTABLE - path to slice2freeze executable
13360 Ice_SLICE2HTML_EXECUTABLE - path to slice2html executable
13361 Ice_SLICE2JAVA_EXECUTABLE - path to slice2java executable
13362 Ice_SLICE2JS_EXECUTABLE - path to slice2js executable
13363 Ice_SLICE2MATLAB_EXECUTABLE - path to slice2matlab executable
13364 Ice_SLICE2OBJC_EXECUTABLE - path to slice2objc executable
13365 Ice_SLICE2PHP_EXECUTABLE - path to slice2php executable
13366 Ice_SLICE2PY_EXECUTABLE - path to slice2py executable
13367 Ice_SLICE2RB_EXECUTABLE - path to slice2rb executable
13368 New in version 3.14: Variables for slice2confluence and slice2matlab.
13370 Ice programs are reported in:
13373 Ice_GLACIER2ROUTER_EXECUTABLE - path to glacier2router executable
13375 Ice_ICEBOX_EXECUTABLE - path to icebox executable
13376 Ice_ICEBOXXX11_EXECUTABLE - path to icebox++11 executable
13377 Ice_ICEBOXADMIN_EXECUTABLE - path to iceboxadmin executable
13378 Ice_ICEBOXD_EXECUTABLE - path to iceboxd executable
13379 Ice_ICEBOXNET_EXECUTABLE - path to iceboxnet executable
13380 Ice_ICEBRIDGE_EXECUTABLE - path to icebridge executable
13381 Ice_ICEGRIDADMIN_EXECUTABLE - path to icegridadmin executable
13382 Ice_ICEGRIDDB_EXECUTABLE - path to icegriddb executable
13383 Ice_ICEGRIDNODE_EXECUTABLE - path to icegridnode executable
13384 Ice_ICEGRIDNODED_EXECUTABLE - path to icegridnoded executable
13385 Ice_ICEGRIDREGISTRY_EXECUTABLE - path to icegridregistry executable
13386 Ice_ICEGRIDREGISTRYD_EXECUTABLE - path to icegridregistryd executable
13387 Ice_ICEPATCH2CALC_EXECUTABLE - path to icepatch2calc executable
13388 Ice_ICEPATCH2CLIENT_EXECUTABLE - path to icepatch2client executable
13389 Ice_ICEPATCH2SERVER_EXECUTABLE - path to icepatch2server executable
13390 Ice_ICESERVICEINSTALL_EXECUTABLE - path to iceserviceinstall executable
13391 Ice_ICESTORMADMIN_EXECUTABLE - path to icestormadmin executable
13392 Ice_ICESTORMDB_EXECUTABLE - path to icestormdb executable
13393 Ice_ICESTORMMIGRATE_EXECUTABLE - path to icestormmigrate executable
13394 Ice db programs (Windows only; standard system versions on all other
13396 platforms) are reported in:
13397 Ice_DB_ARCHIVE_EXECUTABLE - path to db_archive executable
13399 Ice_DB_CHECKPOINT_EXECUTABLE - path to db_checkpoint executable
13400 Ice_DB_DEADLOCK_EXECUTABLE - path to db_deadlock executable
13401 Ice_DB_DUMP_EXECUTABLE - path to db_dump executable
13402 Ice_DB_HOTBACKUP_EXECUTABLE - path to db_hotbackup executable
13403 Ice_DB_LOAD_EXECUTABLE - path to db_load executable
13404 Ice_DB_LOG_VERIFY_EXECUTABLE - path to db_log_verify executable
13405 Ice_DB_PRINTLOG_EXECUTABLE - path to db_printlog executable
13406 Ice_DB_RECOVER_EXECUTABLE - path to db_recover executable
13407 Ice_DB_STAT_EXECUTABLE - path to db_stat executable
13408 Ice_DB_TUNER_EXECUTABLE - path to db_tuner executable
13409 Ice_DB_UPGRADE_EXECUTABLE - path to db_upgrade executable
13410 Ice_DB_VERIFY_EXECUTABLE - path to db_verify executable
13411 Ice_DUMPDB_EXECUTABLE - path to dumpdb executable
13412 Ice_TRANSFORMDB_EXECUTABLE - path to transformdb executable
13413 Ice component libraries are reported in:
13415 Ice_<C>_FOUND - ON if component was found
13417 Ice_<C>_LIBRARIES - libraries for component
13418 Note that <C> is the uppercased name of the component.
13420 This module reads hints about search results from:
13422 Ice_HOME - the root of the Ice installation
13424 The environment variable ICE_HOME may also be used; the Ice_HOME vari‐
13426 able takes precedence.
13427 NOTE:
13429 On Windows, Ice 3.7.0 and later provide libraries via the NuGet
13430 package manager. Appropriate NuGet packages will be searched for
13431 using CMAKE_PREFIX_PATH, or alternatively Ice_HOME may be set to the
13432 location of a specific NuGet package to restrict the search.
13433 The following cache variables may also be set:
13435 Ice_<P>_EXECUTABLE - the path to executable <P>
13437 Ice_INCLUDE_DIR - the directory containing the Ice headers
13438 Ice_SLICE_DIR - the directory containing the Ice slice interface
13439 definitions
13440 Ice_<C>_LIBRARY - the library for component <C>
13441 NOTE:
13443 In most cases none of the above variables will require setting, un‐
13444 less multiple Ice versions are available and a specific version is
13445 required. On Windows, the most recent version of Ice will be found
13446 through the registry. On Unix, the programs, headers and libraries
13447 will usually be in standard locations, but Ice_SLICE_DIRS might not
13448 be automatically detected (commonly known locations are searched).
13449 All the other variables are defaulted using Ice_HOME, if set. It's
13450 possible to set Ice_HOME and selectively specify alternative loca‐
13451 tions for the other components; this might be required for e.g.
13452 newer versions of Visual Studio if the heuristics are not sufficient
13453 to identify the correct programs and libraries for the specific Vis‐
13454 ual Studio version.
13455 Other variables one may set to control this module are:
13457 Ice_DEBUG - Set to ON to enable debug output from FindIce.
13459 FindIconv
13461 New in version 3.11.
13462 This module finds the iconv() POSIX.1 functions on the system. These
13465 functions might be provided in the regular C library or externally in
13466 the form of an additional library.
13467 The following variables are provided to indicate iconv support:
13469 Iconv_FOUND
13471 Variable indicating if the iconv support was found.
13472 Iconv_INCLUDE_DIRS
13474 The directories containing the iconv headers.
13475 Iconv_LIBRARIES
13477 The iconv libraries to be linked.
13478 Iconv_VERSION
13480 New in version 3.21.
13481 The version of iconv found (x.y)
13484 Iconv_VERSION_MAJOR
13486 New in version 3.21.
13487 The major version of iconv
13490 Iconv_VERSION_MINOR
13492 New in version 3.21.
13493 The minor version of iconv
13496 Iconv_IS_BUILT_IN
13498 A variable indicating whether iconv support is stemming from the
13499 C library or not. Even if the C library provides iconv(), the
13500 presence of an external libiconv implementation might lead to
13501 this being false.
13502 Additionally, the following IMPORTED target is being provided:
13504 Iconv::Iconv
13506 Imported target for using iconv.
13507 The following cache variables may also be set:
13509 Iconv_INCLUDE_DIR
13511 The directory containing the iconv headers.
13512 Iconv_LIBRARY
13514 The iconv library (if not implicitly given in the C library).
13515 NOTE:
13517 On POSIX platforms, iconv might be part of the C library and the
13518 cache variables Iconv_INCLUDE_DIR and Iconv_LIBRARY might be empty.
13519 NOTE:
13521 Some libiconv implementations don't embed the version number in
13522 their header files. In this case the variables Iconv_VERSION* will
13523 be empty.
13524 FindIcotool
13526 Find icotool
13527 This module looks for icotool. Convert and create Win32 icon and cursor
13529 files. This module defines the following values:
13530 ICOTOOL_EXECUTABLE: the full path to the icotool tool.
13532 ICOTOOL_FOUND: True if icotool has been found.
13533 ICOTOOL_VERSION_STRING: the version of icotool found.
13534 FindICU
13536 New in version 3.7.
13537 Find the International Components for Unicode (ICU) libraries and pro‐
13540 grams.
13541 This module supports multiple components. Components can include any
13543 of: data, i18n, io, le, lx, test, tu and uc.
13544 Note that on Windows data is named dt and i18n is named in; any of the
13546 names may be used, and the appropriate platform-specific library name
13547 will be automatically selected.
13548 New in version 3.11: Added support for static libraries on Windows.
13550 This module reports information about the ICU installation in several
13553 variables. General variables:
13554 ICU_VERSION - ICU release version
13556 ICU_FOUND - true if the main programs and libraries were found
13557 ICU_LIBRARIES - component libraries to be linked
13558 ICU_INCLUDE_DIRS - the directories containing the ICU headers
13559 Imported targets:
13561 ICU::<C>
13563 Where <C> is the name of an ICU component, for example ICU::i18n; <C>
13565 is lower-case.
13566 ICU programs are reported in:
13568 ICU_GENCNVAL_EXECUTABLE - path to gencnval executable
13570 ICU_ICUINFO_EXECUTABLE - path to icuinfo executable
13571 ICU_GENBRK_EXECUTABLE - path to genbrk executable
13572 ICU_ICU-CONFIG_EXECUTABLE - path to icu-config executable
13573 ICU_GENRB_EXECUTABLE - path to genrb executable
13574 ICU_GENDICT_EXECUTABLE - path to gendict executable
13575 ICU_DERB_EXECUTABLE - path to derb executable
13576 ICU_PKGDATA_EXECUTABLE - path to pkgdata executable
13577 ICU_UCONV_EXECUTABLE - path to uconv executable
13578 ICU_GENCFU_EXECUTABLE - path to gencfu executable
13579 ICU_MAKECONV_EXECUTABLE - path to makeconv executable
13580 ICU_GENNORM2_EXECUTABLE - path to gennorm2 executable
13581 ICU_GENCCODE_EXECUTABLE - path to genccode executable
13582 ICU_GENSPREP_EXECUTABLE - path to gensprep executable
13583 ICU_ICUPKG_EXECUTABLE - path to icupkg executable
13584 ICU_GENCMN_EXECUTABLE - path to gencmn executable
13585 ICU component libraries are reported in:
13587 ICU_<C>_FOUND - ON if component was found; ``<C>`` is upper-case.
13589 ICU_<C>_LIBRARIES - libraries for component; ``<C>`` is upper-case.
13590 ICU datafiles are reported in:
13592 ICU_MAKEFILE_INC - Makefile.inc
13594 ICU_PKGDATA_INC - pkgdata.inc
13595 This module reads hints about search results from:
13597 ICU_ROOT - the root of the ICU installation
13599 The environment variable ICU_ROOT may also be used; the ICU_ROOT vari‐
13601 able takes precedence.
13602 The following cache variables may also be set:
13604 ICU_<P>_EXECUTABLE - the path to executable <P>; ``<P>`` is upper-case.
13606 ICU_INCLUDE_DIR - the directory containing the ICU headers
13607 ICU_<C>_LIBRARY - the library for component <C>; ``<C>`` is upper-case.
13608 NOTE:
13610 In most cases none of the above variables will require setting, un‐
13611 less multiple ICU versions are available and a specific version is
13612 required.
13613 Other variables one may set to control this module are:
13615 ICU_DEBUG - Set to ON to enable debug output from FindICU.
13617 FindImageMagick
13619 Find ImageMagick, software suite for displaying, converting and manipu‐
13620 lating raster images.
13621 New in version 3.9: Added support for ImageMagick 7.
13623 This module will search for a set of ImageMagick tools specified as
13626 components in the find_package() call. Typical components include, but
13627 are not limited to (future versions of ImageMagick might have addi‐
13628 tional components not listed here):
13629 • animate
13631 • compare
13633 • composite
13635 • conjure
13637 • convert
13639 • display
13641 • identify
13643 • import
13645 • mogrify
13647 • montage
13649 • stream
13651 If no component is specified in the find_package() call, then it only
13653 searches for the ImageMagick executable directory.
13654 There are also components for the following ImageMagick APIs:
13656 • Magick++: ImageMagick C++ API, if found.
13658 • MagickWand: ImageMagick MagickWand C API, if found.
13660 • MagickCore: ImageMagick MagickCore low-level C API, if found.
13662 Imported targets
13664 New in version 3.26.
13665 This module defines the following IMPORTED targets:
13668 ImageMagick::Magick++
13670 ImageMagick C++ API, if found.
13671 ImageMagick::MagickWand
13673 ImageMagick MagickWand C API, if found.
13674 ImageMagick::MagickCore
13676 ImageMagick MagickCore low-level C API, if found.
13677 Result Variables
13679 ImageMagick_FOUND
13680 TRUE if all components are found.
13681 ImageMagick_EXECUTABLE_DIR
13683 Full path to executables directory.
13684 ImageMagick_INCLUDE_DIRS
13686 Full paths to all include dirs.
13687 ImageMagick_LIBRARIES
13689 Full paths to all libraries.
13690 ImageMagick_COMPILE_OPTIONS
13692 Compile options of all libraries.
13693 ImageMagick_VERSION_STRING
13695 The version of ImageMagick found (since CMake 2.8.8). Will not
13696 work for old versions like 5.2.3.
13697 ImageMagick_<component>_FOUND
13699 TRUE if <component> is found.
13700 ImageMagick_<component>_EXECUTABLE
13702 Full path to <component> executable.
13703 ImageMagick_<component>_INCLUDE_DIRS
13705 Full path to <component> include dirs.
13706 ImageMagick_<component>_COMPILE_OPTIONS
13708 New in version 3.26.
13709 Compile options of <component>.
13712 ImageMagick_<component>_LIBRARIES
13714 Full path to <component> libraries.
13715 Example Usage
13717 find_package(ImageMagick COMPONENTS Magick++)
13718 target_link_libraries(example PRIVATE ImageMagick::Magick++)
13719 FindIntl
13721 New in version 3.2.
13722 Find the Gettext libintl headers and libraries.
13725 This module reports information about the Gettext libintl installation
13727 in several variables.
13728 Intl_FOUND
13730 True if libintl is found.
13731 Intl_INCLUDE_DIRS
13733 The directory containing the libintl headers.
13734 Intl_LIBRARIES
13736 The intl libraries to be linked.
13737 Intl_VERSION
13739 New in version 3.21.
13740 The version of intl found (x.y.z)
13743 Intl_VERSION_MAJOR
13745 New in version 3.21.
13746 The major version of intl
13749 Intl_VERSION_MINOR
13751 New in version 3.21.
13752 The minor version of intl
13755 Intl_VERSION_PATCH
13757 New in version 3.21.
13758 The patch version of intl
13761 New in version 3.20: This module defines IMPORTED target Intl::Intl.
13763 The following cache variables may also be set:
13766 Intl_INCLUDE_DIR
13768 The directory containing the libintl headers
13769 Intl_LIBRARY
13771 The libintl library (if any)
13772 Intl_IS_BUILT_IN
13774 New in version 3.20.
13775 whether intl is a part of the C library.
13778 NOTE:
13780 On some platforms, such as Linux with GNU libc, the gettext func‐
13781 tions are present in the C standard library and libintl is not re‐
13782 quired. Intl_LIBRARIES will be empty in this case.
13783 NOTE:
13785 Some libintl implementations don't embed the version number in their
13786 header files. In this case the variables Intl_VERSION* will be
13787 empty.
13788 NOTE:
13790 If you wish to use the Gettext tools (msgmerge, msgfmt, etc.), use
13791 FindGettext.
13792 FindJasper
13794 Find the Jasper JPEG2000 library.
13795 IMPORTED Targets
13797 Jasper::Jasper
13798 The jasper library, if found.
13799 Result Variables
13801 This module defines the following variables:
13802 JASPER_FOUND
13804 system has Jasper
13805 JASPER_INCLUDE_DIRS
13807 New in version 3.22.
13808 the Jasper include directory
13811 JASPER_LIBRARIES
13813 the libraries needed to use Jasper
13814 JASPER_VERSION_STRING
13816 the version of Jasper found
13817 Cache variables
13819 The following cache variables may also be set:
13820 JASPER_INCLUDE_DIR
13822 where to find jasper/jasper.h, etc.
13823 JASPER_LIBRARY_RELEASE
13825 where to find the Jasper library (optimized).
13826 JASPER_LIBARRY_DEBUG
13828 where to find the Jasper library (debug).
13829 FindJava
13831 Find Java
13832 This module finds if Java is installed and determines where the include
13834 files and libraries are. The caller may set variable JAVA_HOME to
13835 specify a Java installation prefix explicitly.
13836 See also the FindJNI module to find Java Native Interface (JNI).
13838 New in version 3.10: Added support for Java 9+ version parsing.
13840 Specify one or more of the following components as you call this find
13843 module. See example below.
13844 Runtime = Java Runtime Environment used to execute Java byte-compiled applications
13846 Development = Development tools (java, javac, javah, jar and javadoc), includes Runtime component
13847 IdlJ = Interface Description Language (IDL) to Java compiler
13848 JarSigner = Signer and verifier tool for Java Archive (JAR) files
13849 This module sets the following result variables:
13851 Java_JAVA_EXECUTABLE = the full path to the Java runtime
13853 Java_JAVAC_EXECUTABLE = the full path to the Java compiler
13854 Java_JAVAH_EXECUTABLE = the full path to the Java header generator
13855 Java_JAVADOC_EXECUTABLE = the full path to the Java documentation generator
13856 Java_IDLJ_EXECUTABLE = the full path to the Java idl compiler
13857 Java_JAR_EXECUTABLE = the full path to the Java archiver
13858 Java_JARSIGNER_EXECUTABLE = the full path to the Java jar signer
13859 Java_VERSION_STRING = Version of java found, eg. 1.6.0_12
13860 Java_VERSION_MAJOR = The major version of the package found.
13861 Java_VERSION_MINOR = The minor version of the package found.
13862 Java_VERSION_PATCH = The patch version of the package found.
13863 Java_VERSION_TWEAK = The tweak version of the package found (after '_')
13864 Java_VERSION = This is set to: $major[.$minor[.$patch[.$tweak]]]
13865 New in version 3.4: Added the Java_IDLJ_EXECUTABLE and Java_JAR‐
13867 SIGNER_EXECUTABLE variables.
13868 The minimum required version of Java can be specified using the
13871 find_package() syntax, e.g.
13872 find_package(Java 1.8)
13874 NOTE: ${Java_VERSION} and ${Java_VERSION_STRING} are not guaranteed to
13876 be identical. For example some java version may return: Java_VER‐
13877 SION_STRING = 1.8.0_17 and Java_VERSION = 1.8.0.17
13878 another example is the Java OEM, with: Java_VERSION_STRING = 1.8.0-oem
13880 and Java_VERSION = 1.8.0
13881 For these components the following variables are set:
13883 Java_FOUND - TRUE if all components are found.
13885 Java_<component>_FOUND - TRUE if <component> is found.
13886 Example Usages:
13888 find_package(Java)
13890 find_package(Java 1.8 REQUIRED)
13891 find_package(Java COMPONENTS Runtime)
13892 find_package(Java COMPONENTS Development)
13893 FindJNI
13895 Find Java Native Interface (JNI) headers and libraries.
13896 JNI enables Java code running in a Java Virtual Machine (JVM) or Dalvik
13898 Virtual Machine (DVM) on Android to call and be called by native appli‐
13899 cations and libraries written in other languages such as C and C++.
13900 This module finds if Java is installed and determines where the include
13902 files and libraries are. It also determines what the name of the li‐
13903 brary is. The caller may set variable JAVA_HOME to specify a Java in‐
13904 stallation prefix explicitly.
13905 New in version 3.24: Added imported targets, components AWT, JVM, and
13907 Android NDK support. If no components are specified, the module de‐
13908 faults to an empty components list while targeting Android, and all
13909 available components otherwise.
13910 When using Android NDK, the corresponding package version is reported
13912 and a specific release can be requested. At Android API level 31 and
13913 above, the additional NativeHelper component can be requested. Native‐
13914 Helper is also exposed as an implicit dependency of the JVM component
13915 (only if this does not cause a conflict) which provides a uniform ac‐
13916 cess to JVM functions.
13917 Imported Targets
13920 New in version 3.24.
13921 JNI::JNI
13924 Main JNI target, defined only if jni.h was found.
13925 JNI::AWT
13927 Java AWT Native Interface (JAWT) library, defined only if compo‐
13928 nent AWT was found.
13929 JNI::JVM
13931 Java Virtual Machine (JVM) library, defined only if component
13932 JVM was found.
13933 JNI::NativeHelper
13935 When targeting Android API level 31 and above, the import target
13936 will provide access to libnativehelper.so that exposes JVM func‐
13937 tions such as JNI_CreateJavaVM.
13938 Result Variables
13940 This module sets the following result variables:
13941 JNI_INCLUDE_DIRS
13943 The include directories to use.
13944 JNI_LIBRARIES
13946 The libraries to use (JAWT and JVM).
13947 JNI_FOUND
13949 TRUE if JNI headers and libraries were found.
13950 JNI_<component>_FOUND
13952 New in version 3.24.
13953 TRUE if <component> was found.
13956 JNI_VERSION
13958 Full Android NDK package version (including suffixes such as
13959 -beta3 and -rc1) or undefined otherwise.
13960 JNI_VERSION_MAJOR
13962 New in version 3.24.
13963 Android NDK major version or undefined otherwise.
13966 JNI_VERSION_MINOR
13968 New in version 3.24.
13969 Android NDK minor version or undefined otherwise.
13972 JNI_VERSION_PATCH
13974 New in version 3.24.
13975 Android NDK patch version or undefined otherwise.
13978 Cache Variables
13980 The following cache variables are also available to set or use:
13981 JAVA_AWT_LIBRARY
13983 The path to the Java AWT Native Interface (JAWT) library.
13984 JAVA_JVM_LIBRARY
13986 The path to the Java Virtual Machine (JVM) library.
13987 JAVA_INCLUDE_PATH
13989 The include path to jni.h.
13990 JAVA_INCLUDE_PATH2
13992 The include path to machine-dependant headers jni_md.h and jni‐
13993 port.h. The variable is defined only if jni.h depends on one of
13994 these headers. In contrast, Android NDK jni.h can be typically
13995 used standalone.
13996 JAVA_AWT_INCLUDE_PATH
13998 The include path to jawt.h.
13999 FindJPEG
14001 Find the Joint Photographic Experts Group (JPEG) library (libjpeg)
14002 Imported targets
14004 New in version 3.12.
14005 This module defines the following IMPORTED targets:
14008 JPEG::JPEG
14010 The JPEG library, if found.
14011 Result variables
14013 This module will set the following variables in your project:
14014 JPEG_FOUND
14016 If false, do not try to use JPEG.
14017 JPEG_INCLUDE_DIRS
14019 where to find jpeglib.h, etc.
14020 JPEG_LIBRARIES
14022 the libraries needed to use JPEG.
14023 JPEG_VERSION
14025 New in version 3.12: the version of the JPEG library found
14026 Cache variables
14029 The following cache variables may also be set:
14030 JPEG_INCLUDE_DIRS
14032 where to find jpeglib.h, etc.
14033 JPEG_LIBRARY_RELEASE
14035 where to find the JPEG library (optimized).
14036 JPEG_LIBRARY_DEBUG
14038 where to find the JPEG library (debug).
14039 New in version 3.12: Debug and Release variand are found separately.
14041 Obsolete variables
14044 JPEG_INCLUDE_DIR
14045 where to find jpeglib.h, etc. (same as JPEG_INCLUDE_DIRS)
14046 JPEG_LIBRARY
14048 where to find the JPEG library.
14049 FindKDE3
14051 Find the KDE3 include and library dirs, KDE preprocessors and define a
14052 some macros
14053 This module defines the following variables:
14055 KDE3_DEFINITIONS
14057 compiler definitions required for compiling KDE software
14058 KDE3_INCLUDE_DIR
14060 the KDE include directory
14061 KDE3_INCLUDE_DIRS
14063 the KDE and the Qt include directory, for use with include_di‐
14064 rectories()
14065 KDE3_LIB_DIR
14067 the directory where the KDE libraries are installed, for use
14068 with link_directories()
14069 QT_AND_KDECORE_LIBS
14071 this contains both the Qt and the kdecore library
14072 KDE3_DCOPIDL_EXECUTABLE
14074 the dcopidl executable
14075 KDE3_DCOPIDL2CPP_EXECUTABLE
14077 the dcopidl2cpp executable
14078 KDE3_KCFGC_EXECUTABLE
14080 the kconfig_compiler executable
14081 KDE3_FOUND
14083 set to TRUE if all of the above has been found
14084 The following user adjustable options are provided:
14086 KDE3_BUILD_TESTS
14088 enable this to build KDE testcases
14089 It also adds the following macros (from KDE3Macros.cmake) SRCS_VAR is
14091 always the variable which contains the list of source files for your
14092 application or library.
14093 KDE3_AUTOMOC(file1 ... fileN)
14095 Call this if you want to have automatic moc file handling.
14097 This means if you include "foo.moc" in the source file foo.cpp
14098 a moc file for the header foo.h will be created automatically.
14099 You can set the property SKIP_AUTOMAKE using set_source_files_properties()
14100 to exclude some files in the list from being processed.
14101 KDE3_ADD_MOC_FILES(SRCS_VAR file1 ... fileN )
14103 If you don't use the KDE3_AUTOMOC() macro, for the files
14105 listed here moc files will be created (named "foo.moc.cpp")
14106 KDE3_ADD_DCOP_SKELS(SRCS_VAR header1.h ... headerN.h )
14108 Use this to generate DCOP skeletions from the listed headers.
14110 KDE3_ADD_DCOP_STUBS(SRCS_VAR header1.h ... headerN.h )
14112 Use this to generate DCOP stubs from the listed headers.
14114 KDE3_ADD_UI_FILES(SRCS_VAR file1.ui ... fileN.ui )
14116 Use this to add the Qt designer ui files to your application/library.
14118 KDE3_ADD_KCFG_FILES(SRCS_VAR file1.kcfgc ... fileN.kcfgc )
14120 Use this to add KDE kconfig compiler files to your application/library.
14122 KDE3_INSTALL_LIBTOOL_FILE(target)
14124 This will create and install a simple libtool file for the given target.
14126 KDE3_ADD_EXECUTABLE(name file1 ... fileN )
14128 Currently identical to add_executable(), may provide some advanced
14130 features in the future.
14131 KDE3_ADD_KPART(name [WITH_PREFIX] file1 ... fileN )
14133 Create a KDE plugin (KPart, kioslave, etc.) from the given source files.
14135 If WITH_PREFIX is given, the resulting plugin will have the prefix "lib",
14136 otherwise it won't.
14137 It creates and installs an appropriate libtool la-file.
14138 KDE3_ADD_KDEINIT_EXECUTABLE(name file1 ... fileN )
14140 Create a KDE application in the form of a module loadable via kdeinit.
14142 A library named kdeinit_<name> will be created and a small executable
14143 which links to it.
14144 The option KDE3_ENABLE_FINAL to enable all-in-one compilation is no
14146 longer supported.
14147 Author: Alexander Neundorf <neundorf@kde.org>
14149 FindKDE4
14151 Find KDE4 and provide all necessary variables and macros to compile
14152 software for it. It looks for KDE 4 in the following directories in
14153 the given order:
14154 CMAKE_INSTALL_PREFIX
14156 KDEDIRS
14157 /opt/kde4
14158 Please look in FindKDE4Internal.cmake and KDE4Macros.cmake for more in‐
14160 formation. They are installed with the KDE 4 libraries in
14161 $KDEDIRS/share/apps/cmake/modules/.
14162 Author: Alexander Neundorf <neundorf@kde.org>
14164 FindLAPACK
14166 Find Linear Algebra PACKage (LAPACK) library
14167 This module finds an installed Fortran library that implements the
14169 LAPACK linear-algebra interface.
14170 At least one of the C, CXX, or Fortran languages must be enabled.
14172 Input Variables
14174 The following variables may be set to influence this module's behavior:
14175 BLA_STATIC
14177 if ON use static linkage
14178 BLA_VENDOR
14180 Set to one of the BLAS/LAPACK Vendors to search for BLAS only
14181 from the specified vendor. If not set, all vendors are consid‐
14182 ered.
14183 BLA_F95
14185 if ON tries to find the BLAS95/LAPACK95 interfaces
14186 BLA_PREFER_PKGCONFIG
14188 New in version 3.20.
14189 if set pkg-config will be used to search for a LAPACK library
14192 first and if one is found that is preferred
14193 BLA_PKGCONFIG_LAPACK
14195 New in version 3.25.
14196 If set, the pkg-config method will look for this module name in‐
14199 stead of just lapack.
14200 BLA_SIZEOF_INTEGER
14202 New in version 3.22.
14203 Specify the BLAS/LAPACK library integer size:
14206 4 Search for a BLAS/LAPACK with 32-bit integer interfaces.
14208 8 Search for a BLAS/LAPACK with 64-bit integer interfaces.
14210 ANY Search for any BLAS/LAPACK. Most likely, a BLAS/LAPACK
14212 with 32-bit integer interfaces will be found.
14213 Imported targets
14215 This module defines the following IMPORTED targets:
14216 LAPACK::LAPACK
14218 New in version 3.18.
14219 The libraries to use for LAPACK, if found.
14222 Result Variables
14224 This module defines the following variables:
14225 LAPACK_FOUND
14227 library implementing the LAPACK interface is found
14228 LAPACK_LINKER_FLAGS
14230 uncached list of required linker flags (excluding -l and -L).
14231 LAPACK_LIBRARIES
14233 uncached list of libraries (using full path name) to link
14234 against to use LAPACK
14235 LAPACK95_LIBRARIES
14237 uncached list of libraries (using full path name) to link
14238 against to use LAPACK95
14239 LAPACK95_FOUND
14241 library implementing the LAPACK95 interface is found
14242 Intel MKL
14244 To use the Intel MKL implementation of LAPACK, a project must enable at
14245 least one of the C or CXX languages. Set BLA_VENDOR to an Intel MKL
14246 variant either on the command-line as -DBLA_VENDOR=Intel10_64lp or in
14247 project code:
14248 set(BLA_VENDOR Intel10_64lp)
14250 find_package(LAPACK)
14251 In order to build a project using Intel MKL, and end user must first
14253 establish an Intel MKL environment. See the FindBLAS module section on
14254 Intel MKL for details.
14255 FindLATEX
14257 Find LaTeX
14258 This module finds an installed LaTeX and determines the location of the
14260 compiler. Additionally the module looks for Latex-related software
14261 like BibTeX.
14262 New in version 3.2: Component processing; support for htlatex, pdftops,
14264 Biber, xindy, XeLaTeX, LuaLaTeX.
14265 This module sets the following result variables:
14268 LATEX_FOUND: whether found Latex and requested components
14270 LATEX_<component>_FOUND: whether found <component>
14271 LATEX_COMPILER: path to the LaTeX compiler
14272 PDFLATEX_COMPILER: path to the PdfLaTeX compiler
14273 XELATEX_COMPILER: path to the XeLaTeX compiler
14274 LUALATEX_COMPILER: path to the LuaLaTeX compiler
14275 BIBTEX_COMPILER: path to the BibTeX compiler
14276 BIBER_COMPILER: path to the Biber compiler
14277 MAKEINDEX_COMPILER: path to the MakeIndex compiler
14278 XINDY_COMPILER: path to the xindy compiler
14279 DVIPS_CONVERTER: path to the DVIPS converter
14280 DVIPDF_CONVERTER: path to the DVIPDF converter
14281 PS2PDF_CONVERTER: path to the PS2PDF converter
14282 PDFTOPS_CONVERTER: path to the pdftops converter
14283 LATEX2HTML_CONVERTER: path to the LaTeX2Html converter
14284 HTLATEX_COMPILER: path to the htlatex compiler
14285 Possible components are:
14287 PDFLATEX
14289 XELATEX
14290 LUALATEX
14291 BIBTEX
14292 BIBER
14293 MAKEINDEX
14294 XINDY
14295 DVIPS
14296 DVIPDF
14297 PS2PDF
14298 PDFTOPS
14299 LATEX2HTML
14300 HTLATEX
14301 Example Usages:
14303 find_package(LATEX)
14305 find_package(LATEX COMPONENTS PDFLATEX)
14306 find_package(LATEX COMPONENTS BIBTEX PS2PDF)
14307 FindLibArchive
14309 Find libarchive library and headers. Libarchive is multi-format ar‐
14310 chive and compression library.
14311 The module defines the following variables:
14313 LibArchive_FOUND - true if libarchive was found
14315 LibArchive_INCLUDE_DIRS - include search path
14316 LibArchive_LIBRARIES - libraries to link
14317 LibArchive_VERSION - libarchive 3-component version number
14318 The module defines the following IMPORTED targets:
14320 LibArchive::LibArchive - target for linking against libarchive
14322 New in version 3.6: Support for new libarchive 3.2 version string for‐
14324 mat.
14325 New in version 3.17: Provides an imported target.
14328 FindLibinput
14331 New in version 3.14.
14332 Find libinput headers and library.
14335 Imported Targets
14337 Libinput::Libinput
14338 The libinput library, if found.
14339 Result Variables
14341 This will define the following variables in your project:
14342 Libinput_FOUND
14344 true if (the requested version of) libinput is available.
14345 Libinput_VERSION
14347 the version of libinput.
14348 Libinput_LIBRARIES
14350 the libraries to link against to use libinput.
14351 Libinput_INCLUDE_DIRS
14353 where to find the libinput headers.
14354 Libinput_COMPILE_OPTIONS
14356 this should be passed to target_compile_options(), if the target
14357 is not used for linking
14358 FindLibLZMA
14360 Find LZMA compression algorithm headers and library.
14361 Imported Targets
14363 New in version 3.14.
14364 This module defines IMPORTED target LibLZMA::LibLZMA, if liblzma has
14367 been found.
14368 Result variables
14370 This module will set the following variables in your project:
14371 LIBLZMA_FOUND
14373 True if liblzma headers and library were found.
14374 LIBLZMA_INCLUDE_DIRS
14376 Directory where liblzma headers are located.
14377 LIBLZMA_LIBRARIES
14379 Lzma libraries to link against.
14380 LIBLZMA_HAS_AUTO_DECODER
14382 True if lzma_auto_decoder() is found (required).
14383 LIBLZMA_HAS_EASY_ENCODER
14385 True if lzma_easy_encoder() is found (required).
14386 LIBLZMA_HAS_LZMA_PRESET
14388 True if lzma_lzma_preset() is found (required).
14389 LIBLZMA_VERSION
14391 New in version 3.26: the version of LZMA found.
14392 See also legacy variable LIBLZMA_VERSION_STRING.
14395 Legacy Variables
14397 The following variables are provided for backward compatibility:
14398 LIBLZMA_VERSION_MAJOR
14400 The major version of lzma
14401 LIBLZMA_VERSION_MINOR
14403 The minor version of lzma
14404 LIBLZMA_VERSION_PATCH
14406 The patch version of lzma
14407 LIBLZMA_VERSION_STRING
14409 version number as a string (ex: "5.0.3")
14410 Changed in version 3.26: Superseded by LIBLZMA_VERSION.
14412 FindLibXml2
14415 Find the XML processing library (libxml2).
14416 IMPORTED Targets
14418 New in version 3.12.
14419 The following IMPORTED targets may be defined:
14422 LibXml2::LibXml2
14424 libxml2 library.
14425 LibXml2::xmllint
14427 New in version 3.17.
14428 xmllint command-line executable.
14431 Result variables
14433 This module will set the following variables in your project:
14434 LibXml2_FOUND
14436 true if libxml2 headers and libraries were found
14437 LIBXML2_INCLUDE_DIR
14439 the directory containing LibXml2 headers
14440 LIBXML2_INCLUDE_DIRS
14442 list of the include directories needed to use LibXml2
14443 LIBXML2_LIBRARIES
14445 LibXml2 libraries to be linked
14446 LIBXML2_DEFINITIONS
14448 the compiler switches required for using LibXml2
14449 LIBXML2_XMLLINT_EXECUTABLE
14451 path to the XML checking tool xmllint coming with LibXml2
14452 LIBXML2_VERSION_STRING
14454 the version of LibXml2 found (since CMake 2.8.8)
14455 Cache variables
14457 The following cache variables may also be set:
14458 LIBXML2_INCLUDE_DIR
14460 the directory containing LibXml2 headers
14461 LIBXML2_LIBRARY
14463 path to the LibXml2 library
14464 FindLibXslt
14466 Find the XSL Transformations, Extensible Stylesheet Language Transfor‐
14467 mations (XSLT) library (LibXslt)
14468 IMPORTED Targets
14470 New in version 3.18.
14471 The following IMPORTED targets may be defined:
14474 LibXslt::LibXslt
14476 If the libxslt library has been found
14477 LibXslt::LibExslt
14479 If the libexslt library has been found
14480 LibXslt::xsltproc
14482 If the xsltproc command-line executable has been found
14483 Result variables
14485 This module will set the following variables in your project:
14486 LIBXSLT_FOUND - system has LibXslt LIBXSLT_INCLUDE_DIR - the LibXslt
14487 include directory LIBXSLT_LIBRARIES - Link these to LibXslt
14488 LIBXSLT_DEFINITIONS - Compiler switches required for using LibXslt
14489 LIBXSLT_VERSION_STRING - version of LibXslt found (since CMake
14490 2.8.8)
14491 Additionally, the following two variables are set (but not required for
14493 using xslt):
14494 LIBXSLT_EXSLT_INCLUDE_DIR
14496 New in version 3.18: The include directory for exslt.
14497 LIBXSLT_EXSLT_LIBRARIES
14500 Link to these if you need to link against the exslt library.
14501 LIBXSLT_XSLTPROC_EXECUTABLE
14503 Contains the full path to the xsltproc executable if found.
14504 FindLTTngUST
14506 New in version 3.6.
14507 Find Linux Trace Toolkit Next Generation (LTTng-UST) library.
14510 Imported target
14512 This module defines the following IMPORTED target:
14513 LTTng::UST
14515 The LTTng-UST library, if found
14516 Result variables
14518 This module sets the following
14519 LTTNGUST_FOUND
14521 TRUE if system has LTTng-UST
14522 LTTNGUST_INCLUDE_DIRS
14524 The LTTng-UST include directories
14525 LTTNGUST_LIBRARIES
14527 The libraries needed to use LTTng-UST
14528 LTTNGUST_VERSION_STRING
14530 The LTTng-UST version
14531 LTTNGUST_HAS_TRACEF
14533 TRUE if the tracef() API is available in the system's LTTng-UST
14534 LTTNGUST_HAS_TRACELOG
14536 TRUE if the tracelog() API is available in the system's LT‐
14537 Tng-UST
14538 FindLua
14540 Locate Lua library.
14541 New in version 3.18: Support for Lua 5.4.
14543 This module defines:
14546 LUA_FOUND
14548 if false, do not try to link to Lua
14549 LUA_LIBRARIES
14551 both lua and lualib
14552 LUA_INCLUDE_DIR
14554 where to find lua.h
14555 LUA_VERSION_STRING
14557 the version of Lua found
14558 LUA_VERSION_MAJOR
14560 the major version of Lua
14561 LUA_VERSION_MINOR
14563 the minor version of Lua
14564 LUA_VERSION_PATCH
14566 the patch version of Lua
14567 Note that the expected include convention is
14569 #include "lua.h"
14571 and not
14573 #include <lua/lua.h>
14575 This is because, the lua location is not standardized and may exist in
14577 locations other than lua/
14578 FindLua50
14580 Locate Lua library. This module defines:
14581 ::
14583 LUA50_FOUND, if false, do not try to link to Lua LUA_LIBRARIES, both
14584 lua and lualib LUA_INCLUDE_DIR, where to find lua.h and lualib.h
14585 (and probably lauxlib.h)
14586 Note that the expected include convention is
14588 #include "lua.h"
14590 and not
14592 #include <lua/lua.h>
14594 This is because, the lua location is not standardized and may exist in
14596 locations other than lua/
14597 FindLua51
14599 Locate Lua library. This module defines:
14600 ::
14602 LUA51_FOUND, if false, do not try to link to Lua LUA_LIBRARIES
14603 LUA_INCLUDE_DIR, where to find lua.h LUA_VERSION_STRING, the version
14604 of Lua found (since CMake 2.8.8)
14605 Note that the expected include convention is
14607 #include "lua.h"
14609 and not
14611 #include <lua/lua.h>
14613 This is because, the lua location is not standardized and may exist in
14615 locations other than lua/
14616 FindMatlab
14618 Finds Matlab or Matlab Compiler Runtime (MCR) and provides Matlab
14619 tools, libraries and compilers to CMake.
14620 This package primary purpose is to find the libraries associated with
14622 Matlab or the MCR in order to be able to build Matlab extensions (mex
14623 files). It can also be used:
14624 • to run specific commands in Matlab in case Matlab is available
14626 • for declaring Matlab unit test
14628 • to retrieve various information from Matlab (mex extensions, versions
14630 and release queries, ...)
14631 New in version 3.12: Added Matlab Compiler Runtime (MCR) support.
14633 The module supports the following components:
14636 • ENG_LIBRARY and MAT_LIBRARY: respectively the ENG and MAT libraries
14638 of Matlab
14639 • MAIN_PROGRAM the Matlab binary program. Note that this component is
14641 not available on the MCR version, and will yield an error if the MCR
14642 is found instead of the regular Matlab installation.
14643 • MEX_COMPILER the MEX compiler.
14645 • MCC_COMPILER the MCC compiler, included with the Matlab Compiler
14647 add-on.
14648 • SIMULINK the Simulink environment.
14650 New in version 3.7: Added the MAT_LIBRARY component.
14652 New in version 3.13: Added the ENGINE_LIBRARY, DATAARRAY_LIBRARY and
14655 MCC_COMPILER components.
14656 Changed in version 3.14: Removed the MX_LIBRARY, ENGINE_LIBRARY and
14659 DATAARRAY_LIBRARY components. These libraries are found uncondition‐
14660 ally.
14661 NOTE:
14664 The version given to the find_package() directive is the Matlab ver‐
14665 sion, which should not be confused with the Matlab release name (eg.
14666 R2014). The matlab_get_version_from_release_name() and
14667 matlab_get_release_name_from_version() provide a mapping between the
14668 release name and the version.
14669 The variable Matlab_ROOT_DIR may be specified in order to give the path
14671 of the desired Matlab version. Otherwise, the behavior is platform spe‐
14672 cific:
14673 • Windows: The installed versions of Matlab/MCR are retrieved from the
14675 Windows registry
14676 • OS X: The installed versions of Matlab/MCR are given by the MATLAB
14678 default installation paths in /Application. If no such application is
14679 found, it falls back to the one that might be accessible from the
14680 PATH.
14681 • Unix: The desired Matlab should be accessible from the PATH. This
14683 does not work for MCR installation and Matlab_ROOT_DIR should be
14684 specified on this platform.
14685 Additional information is provided when MATLAB_FIND_DEBUG is set. When
14687 a Matlab/MCR installation is found automatically and the MATLAB_VERSION
14688 is not given, the version is queried from Matlab directly (on Windows
14689 this may pop up a Matlab window) or from the MCR installation.
14690 The mapping of the release names and the version of Matlab is performed
14692 by defining pairs (name, version). The variable
14693 MATLAB_ADDITIONAL_VERSIONS may be provided before the call to the
14694 find_package() in order to handle additional versions.
14695 A Matlab scripts can be added to the set of tests using the
14697 matlab_add_unit_test(). By default, the Matlab unit test framework will
14698 be used (>= 2013a) to run this script, but regular .m files returning
14699 an exit code can be used as well (0 indicating a success).
14700 Module Input Variables
14702 Users or projects may set the following variables to configure the mod‐
14703 ule behavior:
14704 Matlab_ROOT
14706 New in version 3.25.
14707 Default value for Matlab_ROOT_DIR, the root of the Matlab in‐
14710 stallation.
14711 Matlab_ROOT_DIR
14713 The root of the Matlab installation.
14714 MATLAB_FIND_DEBUG
14716 outputs debug information
14717 MATLAB_ADDITIONAL_VERSIONS
14719 additional versions of Matlab for the automatic retrieval of the
14720 installed versions.
14721 Imported targets
14723 New in version 3.22.
14724 This module defines the following IMPORTED targets:
14727 Matlab::mex
14729 The mex library, always available.
14730 Matlab::mx
14732 The mx library of Matlab (arrays), always available.
14733 Matlab::eng
14735 Matlab engine library. Available only if the ENG_LIBRARY compo‐
14736 nent is requested.
14737 Matlab::mat
14739 Matlab matrix library. Available only if the MAT_LIBRARY compo‐
14740 nent is requested.
14741 Matlab::MatlabEngine
14743 Matlab C++ engine library, always available for R2018a and
14744 newer.
14745 Matlab::MatlabDataArray
14747 Matlab C++ data array library, always available for R2018a and
14748 newer.
14749 Variables defined by the module
14751 Result variables
14752 Matlab_FOUND
14753 TRUE if the Matlab installation is found, FALSE otherwise. All
14754 variable below are defined if Matlab is found.
14755 Matlab_VERSION
14757 New in version 3.27.
14758 the numerical version (e.g. 9.13) of Matlab found. Not to be
14761 confused with Matlab release name (e.g. R2022b) that can be ob‐
14762 tained with matlab_get_release_name_from_version().
14763 Matlab_ROOT_DIR
14765 the final root of the Matlab installation determined by the
14766 FindMatlab module.
14767 Matlab_MAIN_PROGRAM
14769 the Matlab binary program. Available only if the component
14770 MAIN_PROGRAM is given in the find_package() directive.
14771 Matlab_INCLUDE_DIRS
14773 the path of the Matlab libraries headers
14774 Matlab_MEX_LIBRARY
14776 library for mex, always available.
14777 Matlab_MX_LIBRARY
14779 mx library of Matlab (arrays), always available.
14780 Matlab_ENG_LIBRARY
14782 Matlab engine library. Available only if the component ENG_LI‐
14783 BRARY is requested.
14784 Matlab_MAT_LIBRARY
14786 Matlab matrix library. Available only if the component MAT_LI‐
14787 BRARY is requested.
14788 Matlab_ENGINE_LIBRARY
14790 New in version 3.13.
14791 Matlab C++ engine library, always available for R2018a and
14794 newer.
14795 Matlab_DATAARRAY_LIBRARY
14797 New in version 3.13.
14798 Matlab C++ data array library, always available for R2018a and
14801 newer.
14802 Matlab_LIBRARIES
14804 the whole set of libraries of Matlab
14805 Matlab_MEX_COMPILER
14807 the mex compiler of Matlab. Currently not used. Available only
14808 if the component MEX_COMPILER is requested.
14809 Matlab_MCC_COMPILER
14811 New in version 3.13.
14812 the mcc compiler of Matlab. Included with the Matlab Compiler
14815 add-on. Available only if the component MCC_COMPILER is re‐
14816 quested.
14817 Cached variables
14819 Matlab_MEX_EXTENSION
14820 the extension of the mex files for the current platform (given
14821 by Matlab).
14822 Matlab_ROOT_DIR
14824 the location of the root of the Matlab installation found. If
14825 this value is changed by the user, the result variables are re‐
14826 computed.
14827 Provided macros
14829 matlab_get_version_from_release_name()
14830 returns the version from the release name
14831 matlab_get_release_name_from_version()
14833 returns the release name from the Matlab version
14834 Provided functions
14836 matlab_add_mex()
14837 adds a target compiling a MEX file.
14838 matlab_add_unit_test()
14840 adds a Matlab unit test file as a test to the project.
14841 matlab_extract_all_installed_versions_from_registry()
14843 parses the registry for all Matlab versions. Available on Win‐
14844 dows only. The part of the registry parsed is dependent on the
14845 host processor
14846 matlab_get_all_valid_matlab_roots_from_registry()
14848 returns all the possible Matlab or MCR paths, according to a
14849 previously given list. Only the existing/accessible paths are
14850 kept. This is mainly useful for the searching all possible Mat‐
14851 lab installation.
14852 matlab_get_mex_suffix()
14854 returns the suffix to be used for the mex files (platform/archi‐
14855 tecture dependent)
14856 matlab_get_version_from_matlab_run()
14858 returns the version of Matlab/MCR, given the full directory of
14859 the Matlab/MCR installation path.
14860 Known issues
14862 Symbol clash in a MEX target
14863 By default, every symbols inside a MEX file defined with the
14864 command matlab_add_mex() have hidden visibility, except for the
14865 entry point. This is the default behavior of the MEX compiler,
14866 which lowers the risk of symbol collision between the libraries
14867 shipped with Matlab, and the libraries to which the MEX file is
14868 linking to. This is also the default on Windows platforms.
14869 However, this is not sufficient in certain case, where for in‐
14871 stance your MEX file is linking against libraries that are al‐
14872 ready loaded by Matlab, even if those libraries have different
14873 SONAMES. A possible solution is to hide the symbols of the li‐
14874 braries to which the MEX target is linking to. This can be
14875 achieved in GNU GCC compilers with the linker option -Wl,--ex‐
14876 clude-libs,ALL.
14877 Tests using GPU resources
14879 in case your MEX file is using the GPU and in order to be able
14880 to run unit tests on this MEX file, the GPU resources should be
14881 properly released by Matlab. A possible solution is to make Mat‐
14882 lab aware of the use of the GPU resources in the session, which
14883 can be performed by a command such as D = gpuDevice() at the be‐
14884 ginning of the test script (or via a fixture).
14885 Reference
14887 Matlab_ROOT_DIR
14888 The root folder of the Matlab installation. If set before the
14889 call to find_package(), the module will look for the components
14890 in that path. If not set, then an automatic search of Matlab
14891 will be performed. If set, it should point to a valid version of
14892 Matlab.
14893 MATLAB_FIND_DEBUG
14895 If set, the lookup of Matlab and the intermediate configuration
14896 steps are outputted to the console.
14897 MATLAB_ADDITIONAL_VERSIONS
14899 If set, specifies additional versions of Matlab that may be
14900 looked for. The variable should be a list of strings, organized
14901 by pairs of release name and versions, such as follows:
14902 set(MATLAB_ADDITIONAL_VERSIONS
14904 "release_name1=corresponding_version1"
14905 "release_name2=corresponding_version2"
14906 ...
14907 )
14908 Example:
14910 set(MATLAB_ADDITIONAL_VERSIONS
14912 "R2013b=8.2"
14913 "R2013a=8.1"
14914 "R2012b=8.0")
14915 The order of entries in this list matters when several versions
14917 of Matlab are installed. The priority is set according to the
14918 ordering in this list.
14919 matlab_get_version_from_release_name
14921 matlab_get_version_from_release_name(release version)
14923 • Input: release is the release name (R2022b)
14925 • Output: version is the version of Matlab (9.13)
14927 Returns the version of Matlab from a release name
14929 matlab_get_release_name_from_version
14931 matlab_get_release_name_from_version(version release_name)
14933 • Input: version is the version of Matlab (9.13)
14935 • Output: release_name is the release name (R2022b)
14937 Returns the release name from the version of Matlab
14939 matlab_extract_all_installed_versions_from_registry
14941 matlab_extract_all_installed_versions_from_registry(win64 matlab_versions)
14943 • Input: win64 is a boolean to search for the 64 bit version of
14945 Matlab
14946 • Output: matlab_versions is a list of all the versions of Mat‐
14948 lab found
14949 This function parses the Windows registry and founds the Matlab
14951 versions that are installed. The found versions are returned in
14952 matlab_versions. Set win64 to TRUE if the 64 bit version of
14953 Matlab should be looked for The returned list contains all ver‐
14954 sions under HKLM\\SOFTWARE\\Mathworks\\MATLAB and HKLM\\SOFT‐
14955 WARE\\Mathworks\\MATLAB Runtime or an empty list in case an er‐
14956 ror occurred (or nothing found).
14957 NOTE:
14959 Only the versions are provided. No check is made over the ex‐
14960 istence of the installation referenced in the registry,
14961 matlab_get_all_valid_matlab_roots_from_registry
14963 Populates the Matlab root with valid versions of Matlab or Mat‐
14964 lab Runtime (MCR). The returned matlab_roots is organized in
14965 triplets (type,version_number,matlab_root_path), where type in‐
14966 dicates either MATLAB or MCR.
14967 matlab_get_all_valid_matlab_roots_from_registry(matlab_versions matlab_roots)
14969 • Input: matlab_versions of each of the Matlab or MCR installa‐
14971 tions
14972 • Output: matlab_roots location of each of the Matlab or MCR in‐
14974 stallations
14975 matlab_get_mex_suffix
14977 Returns the extension of the mex files (the suffixes). This
14978 function should not be called before the appropriate Matlab root
14979 has been found.
14980 matlab_get_mex_suffix(matlab_root mex_suffix)
14982 • Input: matlab_root root of Matlab/MCR install e.g. Mat‐
14984 lab_ROOT_DIR
14985 • Output: mex_suffix variable name in which the suffix will be
14987 returned.
14988 matlab_get_version_from_matlab_run
14990 This function runs Matlab program specified on arguments and ex‐
14991 tracts its version. If the path provided for the Matlab instal‐
14992 lation points to an MCR installation, the version is extracted
14993 from the installed files.
14994 matlab_get_version_from_matlab_run(matlab_binary_path matlab_list_versions)
14996 • Input: matlab_binary_path path of the matlab binary executable
14998 • Output: matlab_list_versions the version extracted from Matlab
15000 matlab_add_unit_test
15002 Adds a Matlab unit test to the test set of cmake/ctest. This
15003 command requires the component MAIN_PROGRAM and hence is not
15004 available for an MCR installation.
15005 The unit test uses the Matlab unittest framework (default,
15007 available starting Matlab 2013b+) except if the option
15008 NO_UNITTEST_FRAMEWORK is given.
15009 The function expects one Matlab test script file to be given.
15011 In the case NO_UNITTEST_FRAMEWORK is given, the unittest script
15012 file should contain the script to be run, plus an exit command
15013 with the exit value. This exit value will be passed to the ctest
15014 framework (0 success, non 0 failure). Additional arguments ac‐
15015 cepted by add_test() can be passed through TEST_ARGS (eg. CON‐
15016 FIGURATION <config> ...).
15017 matlab_add_unit_test(
15019 NAME <name>
15020 UNITTEST_FILE matlab_file_containing_unittest.m
15021 [CUSTOM_TEST_COMMAND matlab_command_to_run_as_test]
15022 [UNITTEST_PRECOMMAND matlab_command_to_run]
15023 [TIMEOUT timeout]
15024 [ADDITIONAL_PATH path1 [path2 ...]]
15025 [MATLAB_ADDITIONAL_STARTUP_OPTIONS option1 [option2 ...]]
15026 [TEST_ARGS arg1 [arg2 ...]]
15027 [NO_UNITTEST_FRAMEWORK]
15028 )
15029 Function Parameters:
15031 NAME name of the unittest in ctest.
15033 UNITTEST_FILE
15035 the matlab unittest file. Its path will be automatically
15036 added to the Matlab path.
15037 CUSTOM_TEST_COMMAND
15039 Matlab script command to run as the test. If this is not
15040 set, then the following is run: runtests('mat‐
15041 lab_file_name'), exit(max([ans(1,:).Failed])) where mat‐
15042 lab_file_name is the UNITTEST_FILE without the extension.
15043 UNITTEST_PRECOMMAND
15045 Matlab script command to be ran before the file contain‐
15046 ing the test (eg. GPU device initialization based on
15047 CMake variables).
15048 TIMEOUT
15050 the test timeout in seconds. Defaults to 180 seconds as
15051 the Matlab unit test may hang.
15052 ADDITIONAL_PATH
15054 a list of paths to add to the Matlab path prior to run‐
15055 ning the unit test.
15056 MATLAB_ADDITIONAL_STARTUP_OPTIONS
15058 a list of additional option in order to run Matlab from
15059 the command line. -nosplash -nodesktop -nodisplay are
15060 always added.
15061 TEST_ARGS
15063 Additional options provided to the add_test command.
15064 These options are added to the default options (eg. "CON‐
15065 FIGURATIONS Release")
15066 NO_UNITTEST_FRAMEWORK
15068 when set, indicates that the test should not use the
15069 unittest framework of Matlab (available for versions >=
15070 R2013a).
15071 WORKING_DIRECTORY
15073 This will be the working directory for the test. If spec‐
15074 ified it will also be the output directory used for the
15075 log file of the test run. If not specified the temporary
15076 directory ${CMAKE_BINARY_DIR}/Matlab will be used as the
15077 working directory and the log location.
15078 matlab_add_mex
15080 Adds a Matlab MEX target. This commands compiles the given
15081 sources with the current tool-chain in order to produce a MEX
15082 file. The final name of the produced output may be specified, as
15083 well as additional link libraries, and a documentation entry for
15084 the MEX file. Remaining arguments of the call are passed to the
15085 add_library() or add_executable() command.
15086 matlab_add_mex(
15088 NAME <name>
15089 [EXECUTABLE | MODULE | SHARED]
15090 SRC src1 [src2 ...]
15091 [OUTPUT_NAME output_name]
15092 [DOCUMENTATION file.txt]
15093 [LINK_TO target1 target2 ...]
15094 [R2017b | R2018a]
15095 [EXCLUDE_FROM_ALL]
15096 [NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES]
15097 [...]
15098 )
15099 Function Parameters:
15101 NAME name of the target.
15103 SRC list of source files.
15105 LINK_TO
15107 a list of additional link dependencies. The target links
15108 to libmex and libmx by default, unless the NO_IM‐
15109 PLICIT_LINK_TO_MATLAB_LIBRARIES option is passed.
15110 OUTPUT_NAME
15112 if given, overrides the default name. The default name is
15113 the name of the target without any prefix and with Mat‐
15114 lab_MEX_EXTENSION suffix.
15115 DOCUMENTATION
15117 if given, the file file.txt will be considered as being
15118 the documentation file for the MEX file. This file is
15119 copied into the same folder without any processing, with
15120 the same name as the final mex file, and with extension
15121 .m. In that case, typing help <name> in Matlab prints the
15122 documentation contained in this file.
15123 R2017b or R2018a
15125 New in version 3.14.
15126 May be given to specify the version of the C API to use:
15129 R2017b specifies the traditional (separate complex) C
15130 API, and corresponds to the -R2017b flag for the mex com‐
15131 mand. R2018a specifies the new interleaved complex C API,
15132 and corresponds to the -R2018a flag for the mex command.
15133 Ignored if MATLAB version prior to R2018a. Defaults to
15134 R2017b.
15135 MODULE or SHARED
15137 New in version 3.7.
15138 May be given to specify the type of library to be cre‐
15141 ated.
15142 EXECUTABLE
15144 New in version 3.7.
15145 May be given to create an executable instead of a li‐
15148 brary. If no type is given explicitly, the type is
15149 SHARED.
15150 EXCLUDE_FROM_ALL
15152 This option has the same meaning as for EXCLUDE_FROM_ALL
15153 and is forwarded to add_library() or add_executable()
15154 commands.
15155 NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES
15157 New in version 3.24.
15158 This option permits to disable the automatic linking of
15161 MATLAB libraries, so that only the libraries that are ac‐
15162 tually required can be linked via the LINK_TO option.
15163 The documentation file is not processed and should be in the
15165 following format:
15166 % This is the documentation
15168 function ret = mex_target_output_name(input1)
15169 FindMFC
15171 Find Microsoft Foundation Class Library (MFC) on Windows
15172 Find the native MFC - i.e. decide if an application can link to the
15174 MFC libraries.
15175 MFC_FOUND - Was MFC support found
15177 You don't need to include anything or link anything to use it.
15179 FindMotif
15181 Try to find Motif (or lesstif)
15182 Once done this will define:
15184 MOTIF_FOUND - system has MOTIF
15186 MOTIF_INCLUDE_DIR - include paths to use Motif
15187 MOTIF_LIBRARIES - Link these to use Motif
15188 FindMPEG
15190 Find the native MPEG includes and library
15191 This module defines
15193 MPEG_INCLUDE_DIR, where to find MPEG.h, etc.
15195 MPEG_LIBRARIES, the libraries required to use MPEG.
15196 MPEG_FOUND, If false, do not try to use MPEG.
15197 also defined, but not for general use are
15199 MPEG_mpeg2_LIBRARY, where to find the MPEG library.
15201 MPEG_vo_LIBRARY, where to find the vo library.
15202 FindMPEG2
15204 Find the native MPEG2 includes and library
15205 This module defines
15207 MPEG2_INCLUDE_DIR, path to mpeg2dec/mpeg2.h, etc.
15209 MPEG2_LIBRARIES, the libraries required to use MPEG2.
15210 MPEG2_FOUND, If false, do not try to use MPEG2.
15211 also defined, but not for general use are
15213 MPEG2_mpeg2_LIBRARY, where to find the MPEG2 library.
15215 MPEG2_vo_LIBRARY, where to find the vo library.
15216 FindMPI
15218 Find a Message Passing Interface (MPI) implementation.
15219 The Message Passing Interface (MPI) is a library used to write
15221 high-performance distributed-memory parallel applications, and is typi‐
15222 cally deployed on a cluster. MPI is a standard interface (defined by
15223 the MPI forum) for which many implementations are available.
15224 New in version 3.10: Major overhaul of the module: many new variables,
15226 per-language components, support for a wider variety of runtimes.
15227 Variables for using MPI
15230 The module exposes the components C, CXX, MPICXX and Fortran. Each of
15231 these controls the various MPI languages to search for. The difference
15232 between CXX and MPICXX is that CXX refers to the MPI C API being usable
15233 from C++, whereas MPICXX refers to the MPI-2 C++ API that was removed
15234 again in MPI-3.
15235 Depending on the enabled components the following variables will be
15237 set:
15238 MPI_FOUND
15240 Variable indicating that MPI settings for all requested lan‐
15241 guages have been found. If no components are specified, this is
15242 true if MPI settings for all enabled languages were detected.
15243 Note that the MPICXX component does not affect this variable.
15244 MPI_VERSION
15246 Minimal version of MPI detected among the requested languages,
15247 or all enabled languages if no components were specified.
15248 This module will set the following variables per language in your
15250 project, where <lang> is one of C, CXX, or Fortran:
15251 MPI_<lang>_FOUND
15253 Variable indicating the MPI settings for <lang> were found and
15254 that simple MPI test programs compile with the provided set‐
15255 tings.
15256 MPI_<lang>_COMPILER
15258 MPI compiler for <lang> if such a program exists.
15259 MPI_<lang>_COMPILE_OPTIONS
15261 Compilation options for MPI programs in <lang>, given as a
15262 ;-list.
15263 MPI_<lang>_COMPILE_DEFINITIONS
15265 Compilation definitions for MPI programs in <lang>, given as a
15266 ;-list.
15267 MPI_<lang>_INCLUDE_DIRS
15269 Include path(s) for MPI header.
15270 MPI_<lang>_LINK_FLAGS
15272 Linker flags for MPI programs.
15273 MPI_<lang>_LIBRARIES
15275 All libraries to link MPI programs against.
15276 New in version 3.9: Additionally, the following IMPORTED targets are
15278 defined:
15279 MPI::MPI_<lang>
15282 Target for using MPI from <lang>.
15283 The following variables indicating which bindings are present will be
15285 defined:
15286 MPI_MPICXX_FOUND
15288 Variable indicating whether the MPI-2 C++ bindings are present
15289 (introduced in MPI-2, removed with MPI-3).
15290 MPI_Fortran_HAVE_F77_HEADER
15292 True if the Fortran 77 header mpif.h is available.
15293 MPI_Fortran_HAVE_F90_MODULE
15295 True if the Fortran 90 module mpi can be used for accessing MPI
15296 (MPI-2 and higher only).
15297 MPI_Fortran_HAVE_F08_MODULE
15299 True if the Fortran 2008 mpi_f08 is available to MPI programs
15300 (MPI-3 and higher only).
15301 If possible, the MPI version will be determined by this module. The fa‐
15303 cilities to detect the MPI version were introduced with MPI-1.2, and
15304 therefore cannot be found for older MPI versions.
15305 MPI_<lang>_VERSION_MAJOR
15307 Major version of MPI implemented for <lang> by the MPI distribu‐
15308 tion.
15309 MPI_<lang>_VERSION_MINOR
15311 Minor version of MPI implemented for <lang> by the MPI distribu‐
15312 tion.
15313 MPI_<lang>_VERSION
15315 MPI version implemented for <lang> by the MPI distribution.
15316 Note that there's no variable for the C bindings being accessible
15318 through mpi.h, since the MPI standards always have required this bind‐
15319 ing to work in both C and C++ code.
15320 For running MPI programs, the module sets the following variables
15322 MPIEXEC_EXECUTABLE
15324 Executable for running MPI programs, if such exists.
15325 MPIEXEC_NUMPROC_FLAG
15327 Flag to pass to mpiexec before giving it the number of proces‐
15328 sors to run on.
15329 MPIEXEC_MAX_NUMPROCS
15331 Number of MPI processors to utilize. Defaults to the number of
15332 processors detected on the host system.
15333 MPIEXEC_PREFLAGS
15335 Flags to pass to mpiexec directly before the executable to run.
15336 MPIEXEC_POSTFLAGS
15338 Flags to pass to mpiexec after other flags.
15339 Variables for locating MPI
15341 This module performs a four step search for an MPI implementation:
15342 1. Search for MPIEXEC_EXECUTABLE and, if found, use its base directory.
15344 2. Check if the compiler has MPI support built-in. This is the case if
15346 the user passed a compiler wrapper as CMAKE_<LANG>_COMPILER or if
15347 they use Cray system compiler wrappers.
15348 3. Attempt to find an MPI compiler wrapper and determine the compiler
15350 information from it.
15351 4. Try to find an MPI implementation that does not ship such a wrapper
15353 by guessing settings. Currently, only Microsoft MPI and MPICH2 on
15354 Windows are supported.
15355 For controlling the MPIEXEC_EXECUTABLE step, the following variables
15357 may be set:
15358 MPIEXEC_EXECUTABLE
15360 Manually specify the location of mpiexec.
15361 MPI_HOME
15363 Specify the base directory of the MPI installation.
15364 ENV{MPI_HOME}
15366 Environment variable to specify the base directory of the MPI
15367 installation.
15368 ENV{I_MPI_ROOT}
15370 Environment variable to specify the base directory of the MPI
15371 installation.
15372 For controlling the compiler wrapper step, the following variables may
15374 be set:
15375 MPI_<lang>_COMPILER
15377 Search for the specified compiler wrapper and use it.
15378 MPI_<lang>_COMPILER_FLAGS
15380 Flags to pass to the MPI compiler wrapper during interrogation.
15381 Some compiler wrappers support linking debug or tracing li‐
15382 braries if a specific flag is passed and this variable may be
15383 used to obtain them.
15384 MPI_COMPILER_FLAGS
15386 Used to initialize MPI_<lang>_COMPILER_FLAGS if no language spe‐
15387 cific flag has been given. Empty by default.
15388 MPI_EXECUTABLE_SUFFIX
15390 A suffix which is appended to all names that are being looked
15391 for. For instance you may set this to .mpich or .openmpi to pre‐
15392 fer the one or the other on Debian and its derivatives.
15393 In order to control the guessing step, the following variable may be
15395 set:
15396 MPI_GUESS_LIBRARY_NAME
15398 Valid values are MSMPI and MPICH2. If set, only the given li‐
15399 brary will be searched for. By default, MSMPI will be preferred
15400 over MPICH2 if both are available. This also sets MPI_SKIP_COM‐
15401 PILER_WRAPPER to true, which may be overridden.
15402 Each of the search steps may be skipped with the following control
15404 variables:
15405 MPI_ASSUME_NO_BUILTIN_MPI
15407 If true, the module assumes that the compiler itself does not
15408 provide an MPI implementation and skips to step 2.
15409 MPI_SKIP_COMPILER_WRAPPER
15411 If true, no compiler wrapper will be searched for.
15412 MPI_SKIP_GUESSING
15414 If true, the guessing step will be skipped.
15415 Additionally, the following control variable is available to change
15417 search behavior:
15418 MPI_CXX_SKIP_MPICXX
15420 Add some definitions that will disable the MPI-2 C++ bindings.
15421 Currently supported are MPICH, Open MPI, Platform MPI and deriv‐
15422 atives thereof, for example MVAPICH or Intel MPI.
15423 If the find procedure fails for a variable MPI_<lang>_WORKS, then the
15425 settings detected by or passed to the module did not work and even a
15426 simple MPI test program failed to compile.
15427 If all of these parameters were not sufficient to find the right MPI
15429 implementation, a user may disable the entire autodetection process by
15430 specifying both a list of libraries in MPI_<lang>_LIBRARIES and a list
15431 of include directories in MPI_<lang>_ADDITIONAL_INCLUDE_DIRS. Any
15432 other variable may be set in addition to these two. The module will
15433 then validate the MPI settings and store the settings in the cache.
15434 Cache variables for MPI
15436 The variable MPI_<lang>_INCLUDE_DIRS will be assembled from the follow‐
15437 ing variables. For C and CXX:
15438 MPI_<lang>_HEADER_DIR
15440 Location of the mpi.h header on disk.
15441 For Fortran:
15443 MPI_Fortran_F77_HEADER_DIR
15445 Location of the Fortran 77 header mpif.h, if it exists.
15446 MPI_Fortran_MODULE_DIR
15448 Location of the mpi or mpi_f08 modules, if available.
15449 For all languages the following variables are additionally considered:
15451 MPI_<lang>_ADDITIONAL_INCLUDE_DIRS
15453 A ;-list of paths needed in addition to the normal include di‐
15454 rectories.
15455 MPI_<include_name>_INCLUDE_DIR
15457 Path variables for include folders referred to by <in‐
15458 clude_name>.
15459 MPI_<lang>_ADDITIONAL_INCLUDE_VARS
15461 A ;-list of <include_name> that will be added to the include lo‐
15462 cations of <lang>.
15463 The variable MPI_<lang>_LIBRARIES will be assembled from the following
15465 variables:
15466 MPI_<lib_name>_LIBRARY
15468 The location of a library called <lib_name> for use with MPI.
15469 MPI_<lang>_LIB_NAMES
15471 A ;-list of <lib_name> that will be added to the include loca‐
15472 tions of <lang>.
15473 Usage of mpiexec
15475 When using MPIEXEC_EXECUTABLE to execute MPI applications, you should
15476 typically use all of the MPIEXEC_EXECUTABLE flags as follows:
15477 ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS}
15479 ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS
15480 where EXECUTABLE is the MPI program, and ARGS are the arguments to pass
15482 to the MPI program.
15483 Advanced variables for using MPI
15485 The module can perform some advanced feature detections upon explicit
15486 request.
15487 Important notice: The following checks cannot be performed without exe‐
15489 cuting an MPI test program. Consider the special considerations for
15490 the behavior of try_run() during cross compilation. Moreover, running
15491 an MPI program can cause additional issues, like a firewall notifica‐
15492 tion on some systems. You should only enable these detections if you
15493 absolutely need the information.
15494 If the following variables are set to true, the respective search will
15496 be performed:
15497 MPI_DETERMINE_Fortran_CAPABILITIES
15499 Determine for all available Fortran bindings what the values of
15500 MPI_SUBARRAYS_SUPPORTED and MPI_ASYNC_PROTECTS_NONBLOCKING are
15501 and make their values available as MPI_Fortran_<binding>_SUBAR‐
15502 RAYS and MPI_Fortran_<binding>_ASYNCPROT, where <binding> is one
15503 of F77_HEADER, F90_MODULE and F08_MODULE.
15504 MPI_DETERMINE_LIBRARY_VERSION
15506 For each language, find the output of MPI_Get_library_version
15507 and make it available as MPI_<lang>_LIBRARY_VERSION_STRING.
15508 This information is usually tied to the runtime component of an
15509 MPI implementation and might differ depending on <lang>. Note
15510 that the return value is entirely implementation defined. This
15511 information might be used to identify the MPI vendor and for ex‐
15512 ample pick the correct one of multiple third party binaries that
15513 matches the MPI vendor.
15514 Backward Compatibility
15516 Deprecated since version 3.10.
15517 For backward compatibility with older versions of FindMPI, these vari‐
15520 ables are set:
15521 MPI_COMPILER MPI_LIBRARY MPI_EXTRA_LIBRARY
15523 MPI_COMPILE_FLAGS MPI_INCLUDE_PATH MPI_LINK_FLAGS
15524 MPI_LIBRARIES
15525 In new projects, please use the MPI_<lang>_XXX equivalents. Addition‐
15527 ally, the following variables are deprecated:
15528 MPI_<lang>_COMPILE_FLAGS
15530 Use MPI_<lang>_COMPILE_OPTIONS and MPI_<lang>_COMPILE_DEFINI‐
15531 TIONS instead.
15532 MPI_<lang>_INCLUDE_PATH
15534 For consumption use MPI_<lang>_INCLUDE_DIRS and for specifying
15535 folders use MPI_<lang>_ADDITIONAL_INCLUDE_DIRS instead.
15536 MPIEXEC
15538 Use MPIEXEC_EXECUTABLE instead.
15539 FindMsys
15541 New in version 3.21.
15542 Find MSYS, a POSIX-compatible environment that runs natively on Micro‐
15545 soft Windows
15546 FindODBC
15548 New in version 3.12.
15549 Find an Open Database Connectivity (ODBC) include directory and li‐
15552 brary.
15553 On Windows, when building with Visual Studio, this module assumes the
15555 ODBC library is provided by the available Windows SDK.
15556 On Unix, this module allows to search for ODBC library provided by
15558 unixODBC or iODBC implementations of ODBC API. This module reads hint
15559 about location of the config program:
15560 ODBC_CONFIG
15562 Location of odbc_config or iodbc-config program
15563 Otherwise, this module tries to find the config program, first from
15565 unixODBC, then from iODBC. If no config program found, this module
15566 searches for ODBC header and library in list of known locations.
15567 Imported targets
15569 This module defines the following IMPORTED targets:
15570 ODBC::ODBC
15572 Imported target for using the ODBC library, if found.
15573 Result variables
15575 ODBC_FOUND
15576 Set to true if ODBC library found, otherwise false or undefined.
15577 ODBC_INCLUDE_DIRS
15579 Paths to include directories listed in one variable for use by
15580 ODBC client. May be empty on Windows, where the include direc‐
15581 tory corresponding to the expected Windows SDK is already avail‐
15582 able in the compilation environment.
15583 ODBC_LIBRARIES
15585 Paths to libraries to linked against to use ODBC. May just a
15586 library name on Windows, where the library directory correspond‐
15587 ing to the expected Windows SDK is already available in the com‐
15588 pilation environment.
15589 ODBC_CONFIG
15591 Path to unixODBC or iODBC config program, if found or specified.
15592 Cache variables
15594 For users who wish to edit and control the module behavior, this module
15595 reads hints about search locations from the following variables:
15596 ODBC_INCLUDE_DIR
15598 Path to ODBC include directory with sql.h header.
15599 ODBC_LIBRARY
15601 Path to ODBC library to be linked.
15602 These variables should not be used directly by project code.
15604 Limitations
15606 On Windows, this module does not search for iODBC. On Unix, there is
15607 no way to prefer unixODBC over iODBC, or vice versa, other than provid‐
15608 ing the config program location using the ODBC_CONFIG. This module
15609 does not allow to search for a specific ODBC driver.
15610 FindOpenACC
15612 New in version 3.10.
15613 Detect OpenACC support by the compiler.
15616 This module can be used to detect OpenACC support in a compiler. If
15618 the compiler supports OpenACC, the flags required to compile with Ope‐
15619 nACC support are returned in variables for the different languages.
15620 Currently, only NVHPC, PGI, GNU and Cray compilers are supported.
15621 Imported Targets
15623 New in version 3.16.
15624 The module provides IMPORTED targets:
15627 OpenACC::OpenACC_<lang>
15629 Target for using OpenACC from <lang>.
15630 Variables
15632 The module defines the following variables:
15633 OpenACC_FOUND
15635 New in version 3.25.
15636 Variable indicating that OpenACC flags for at least one lan‐
15639 guages have been found.
15640 This module will set the following variables per language in your
15642 project, where <lang> is one of C, CXX, or Fortran:
15643 OpenACC_<lang>_FOUND
15645 Variable indicating if OpenACC support for <lang> was detected.
15646 OpenACC_<lang>_FLAGS
15648 OpenACC compiler flags for <lang>, separated by spaces.
15649 OpenACC_<lang>_OPTIONS
15651 New in version 3.16.
15652 OpenACC compiler flags for <lang>, as a list. Suitable for usage
15655 with target_compile_options or target_link_options.
15656 The module will also try to provide the OpenACC version variables:
15658 OpenACC_<lang>_SPEC_DATE
15660 Date of the OpenACC specification implemented by the <lang> com‐
15661 piler.
15662 OpenACC_<lang>_VERSION_MAJOR
15664 Major version of OpenACC implemented by the <lang> compiler.
15665 OpenACC_<lang>_VERSION_MINOR
15667 Minor version of OpenACC implemented by the <lang> compiler.
15668 OpenACC_<lang>_VERSION
15670 OpenACC version implemented by the <lang> compiler.
15671 The specification date is formatted as given in the OpenACC standard:
15673 yyyymm where yyyy and mm represents the year and month of the OpenACC
15674 specification implemented by the <lang> compiler.
15675 Input Variables
15677 OpenACC_ACCEL_TARGET=<target> If set, will the correct target accelera‐
15678 tor flag set to the <target> will be returned with Ope‐
15679 nACC_<lang>_FLAGS.
15680 FindOpenAL
15682 Finds Open Audio Library (OpenAL).
15683 Projects using this module should use #include "al.h" to include the
15685 OpenAL header file, not #include <AL/al.h>. The reason for this is
15686 that the latter is not entirely portable. Windows/Creative Labs does
15687 not by default put their headers in AL/ and macOS uses the convention
15688 <OpenAL/al.h>.
15689 Hints
15691 Environment variable $OPENALDIR can be used to set the prefix of OpenAL
15692 installation to be found.
15693 By default on macOS, system framework is search first. In other words,
15695 OpenAL is searched in the following order:
15696 1. System framework: /System/Library/Frameworks, whose priority can be
15698 changed via setting the CMAKE_FIND_FRAMEWORK variable.
15699 2. Environment variable $OPENALDIR.
15701 3. System paths.
15703 4. User-compiled framework: ~/Library/Frameworks.
15705 5. Manually compiled framework: /Library/Frameworks.
15707 6. Add-on package: /opt.
15709 IMPORTED Targets
15711 New in version 3.25.
15712 This module defines the IMPORTED target:
15715 OpenAL::OpenAL
15717 The OpenAL library, if found.
15718 Result Variables
15720 This module defines the following variables:
15721 OPENAL_FOUND
15723 If false, do not try to link to OpenAL
15724 OPENAL_INCLUDE_DIR
15726 OpenAL include directory
15727 OPENAL_LIBRARY
15729 Path to the OpenAL library
15730 OPENAL_VERSION_STRING
15732 Human-readable string containing the version of OpenAL
15733 FindOpenCL
15735 New in version 3.1.
15736 Finds Open Computing Language (OpenCL)
15739 New in version 3.10: Detection of OpenCL 2.1 and 2.2.
15741 IMPORTED Targets
15744 New in version 3.7.
15745 This module defines IMPORTED target OpenCL::OpenCL, if OpenCL has been
15748 found.
15749 Result Variables
15751 This module defines the following variables:
15752 OpenCL_FOUND - True if OpenCL was found
15754 OpenCL_INCLUDE_DIRS - include directories for OpenCL
15755 OpenCL_LIBRARIES - link against this library to use OpenCL
15756 OpenCL_VERSION_STRING - Highest supported OpenCL version (eg. 1.2)
15757 OpenCL_VERSION_MAJOR - The major version of the OpenCL implementation
15758 OpenCL_VERSION_MINOR - The minor version of the OpenCL implementation
15759 The module will also define two cache variables:
15761 OpenCL_INCLUDE_DIR - the OpenCL include directory
15763 OpenCL_LIBRARY - the path to the OpenCL library
15764 FindOpenGL
15766 FindModule for OpenGL and OpenGL Utility Library (GLU).
15767 Changed in version 3.2: X11 is no longer added as a dependency on
15769 Unix/Linux systems.
15770 New in version 3.10: GLVND support on Linux. See the Linux-specific
15773 section below.
15774 Optional COMPONENTS
15777 New in version 3.10.
15778 This module respects several optional COMPONENTS:
15781 EGL The EGL interface between OpenGL, OpenGL ES and the underlying
15783 windowing system.
15784 GLX An extension to X that interfaces OpenGL, OpenGL ES with X win‐
15786 dow system.
15787 OpenGL The cross platform API for 3D graphics.
15789 GLES2 New in version 3.27.
15791 A subset of OpenGL API for embedded systems with limited capa‐
15794 bilities.
15795 GLES3 New in version 3.27.
15797 A subset of OpenGL API for embedded systems with more capabili‐
15800 ties.
15801 IMPORTED Targets
15803 New in version 3.8.
15804 This module defines the IMPORTED targets:
15807 OpenGL::GL
15809 Defined to the platform-specific OpenGL libraries if the system
15810 has OpenGL.
15811 OpenGL::GLU
15813 Defined if the system has OpenGL Utility Library (GLU).
15814 New in version 3.10: Additionally, the following GLVND-specific library
15816 targets are defined:
15817 OpenGL::OpenGL
15820 Defined to libOpenGL if the system is GLVND-based.
15821 OpenGL::GLX
15823 Defined if the system has OpenGL Extension to the X Window Sys‐
15824 tem (GLX).
15825 OpenGL::EGL
15827 Defined if the system has EGL.
15828 OpenGL::GLES2
15830 New in version 3.27.
15831 Defined if the system has GLES2.
15834 OpenGL::GLES3
15836 New in version 3.27.
15837 Defined if the system has GLES3.
15840 Result Variables
15842 This module sets the following variables:
15843 OPENGL_FOUND
15845 True, if the system has OpenGL and all components are found.
15846 OPENGL_XMESA_FOUND
15848 True, if the system has XMESA.
15849 OPENGL_GLU_FOUND
15851 True, if the system has GLU.
15852 OpenGL_OpenGL_FOUND
15854 True, if the system has an OpenGL library.
15855 OpenGL_GLX_FOUND
15857 True, if the system has GLX.
15858 OpenGL_EGL_FOUND
15860 True, if the system has EGL.
15861 OpenGL::GLES2
15863 Defined if the system has GLES2.
15864 OpenGL::GLES3
15866 Defined if the system has GLES3.
15867 OPENGL_INCLUDE_DIR
15869 Path to the OpenGL include directory.
15870 OPENGL_EGL_INCLUDE_DIRS
15872 Path to the EGL include directory.
15873 OPENGL_LIBRARIES
15875 Paths to the OpenGL library, windowing system libraries, and GLU
15876 libraries. On Linux, this assumes GLX and is never correct for
15877 EGL-based targets. Clients are encouraged to use the OpenGL::*
15878 import targets instead.
15879 New in version 3.10: Variables for GLVND-specific libraries OpenGL, EGL
15881 and GLX.
15882 Cache variables
15885 The following cache variables may also be set:
15886 OPENGL_egl_LIBRARY
15888 Path to the EGL library.
15889 OPENGL_glu_LIBRARY
15891 Path to the GLU library.
15892 OPENGL_glx_LIBRARY
15894 Path to the GLVND 'GLX' library.
15895 OPENGL_opengl_LIBRARY
15897 Path to the GLVND 'OpenGL' library
15898 OPENGL_gl_LIBRARY
15900 Path to the OpenGL library. New code should prefer the
15901 OpenGL::* import targets.
15902 OPENGL_gles2_LIBRARY
15904 New in version 3.27.
15905 Path to the OpenGL GLES2 library.
15908 OPENGL_gles3_LIBRARY
15910 New in version 3.27.
15911 Path to the OpenGL GLES3 library.
15914 New in version 3.10: Variables for GLVND-specific libraries OpenGL, EGL
15916 and GLX.
15917 Linux-specific
15920 Some Linux systems utilize GLVND as a new ABI for OpenGL. GLVND sepa‐
15921 rates context libraries from OpenGL itself; OpenGL lives in "li‐
15922 bOpenGL", and contexts are defined in "libGLX" or "libEGL". GLVND is
15923 currently the only way to get OpenGL 3+ functionality via EGL in a man‐
15924 ner portable across vendors. Projects may use GLVND explicitly with
15925 target OpenGL::OpenGL and either OpenGL::GLX or OpenGL::EGL.
15926 Projects may use the OpenGL::GL target (or OPENGL_LIBRARIES variable)
15928 to use legacy GL interfaces. These will use the legacy GL library lo‐
15929 cated by OPENGL_gl_LIBRARY, if available. If OPENGL_gl_LIBRARY is
15930 empty or not found and GLVND is available, the OpenGL::GL target will
15931 use GLVND OpenGL::OpenGL and OpenGL::GLX (and the OPENGL_LIBRARIES
15932 variable will use the corresponding libraries). Thus, for
15933 non-EGL-based Linux targets, the OpenGL::GL target is most portable.
15934 A OpenGL_GL_PREFERENCE variable may be set to specify the preferred way
15936 to provide legacy GL interfaces in case multiple choices are available.
15937 The value may be one of:
15938 GLVND If the GLVND OpenGL and GLX libraries are available, prefer
15940 them. This forces OPENGL_gl_LIBRARY to be empty.
15941 Changed in version 3.11: This is the default, unless policy
15943 CMP0072 is set to OLD and no components are requested (since
15944 components correspond to GLVND libraries).
15945 LEGACY Prefer to use the legacy libGL library, if available.
15948 For EGL targets the client must rely on GLVND support on the user's
15950 system. Linking should use the OpenGL::OpenGL OpenGL::EGL targets.
15951 Using GLES* libraries is theoretically possible in place of
15952 OpenGL::OpenGL, but this module does not currently support that; con‐
15953 tributions welcome.
15954 OPENGL_egl_LIBRARY and OPENGL_EGL_INCLUDE_DIRS are defined in the case
15956 of GLVND. For non-GLVND Linux and other systems these are left unde‐
15957 fined.
15958 macOS-Specific
15960 On OSX FindOpenGL defaults to using the framework version of OpenGL.
15961 People will have to change the cache values of OPENGL_glu_LIBRARY and
15962 OPENGL_gl_LIBRARY to use OpenGL with X11 on OSX.
15963 FindOpenMP
15965 Finds Open Multi-Processing (OpenMP) support.
15966 This module can be used to detect OpenMP support in a compiler. If the
15968 compiler supports OpenMP, the flags required to compile with OpenMP
15969 support are returned in variables for the different languages. The
15970 variables may be empty if the compiler does not need a special flag to
15971 support OpenMP.
15972 New in version 3.5: Clang support.
15974 Variables
15977 New in version 3.10: The module exposes the components C, CXX, and For‐
15978 tran. Each of these controls the various languages to search OpenMP
15979 support for.
15980 Depending on the enabled components the following variables will be
15983 set:
15984 OpenMP_FOUND
15986 Variable indicating that OpenMP flags for all requested lan‐
15987 guages have been found. If no components are specified, this is
15988 true if OpenMP settings for all enabled languages were detected.
15989 OpenMP_VERSION
15991 Minimal version of the OpenMP standard detected among the re‐
15992 quested languages, or all enabled languages if no components
15993 were specified.
15994 This module will set the following variables per language in your
15996 project, where <lang> is one of C, CXX, or Fortran:
15997 OpenMP_<lang>_FOUND
15999 Variable indicating if OpenMP support for <lang> was detected.
16000 OpenMP_<lang>_FLAGS
16002 OpenMP compiler flags for <lang>, separated by spaces.
16003 OpenMP_<lang>_INCLUDE_DIRS
16005 Directories that must be added to the header search path for
16006 <lang> when using OpenMP.
16007 For linking with OpenMP code written in <lang>, the following variables
16009 are provided:
16010 OpenMP_<lang>_LIB_NAMES
16012 ;-list of libraries for OpenMP programs for <lang>.
16013 OpenMP_<libname>_LIBRARY
16015 Location of the individual libraries needed for OpenMP support
16016 in <lang>.
16017 OpenMP_<lang>_LIBRARIES
16019 A list of libraries needed to link with OpenMP code written in
16020 <lang>.
16021 Additionally, the module provides IMPORTED targets:
16023 OpenMP::OpenMP_<lang>
16025 Target for using OpenMP from <lang>.
16026 Specifically for Fortran, the module sets the following variables:
16028 OpenMP_Fortran_HAVE_OMPLIB_HEADER
16030 Boolean indicating if OpenMP is accessible through omp_lib.h.
16031 OpenMP_Fortran_HAVE_OMPLIB_MODULE
16033 Boolean indicating if OpenMP is accessible through the omp_lib
16034 Fortran module.
16035 The module will also try to provide the OpenMP version variables:
16037 OpenMP_<lang>_SPEC_DATE
16039 New in version 3.7.
16040 Date of the OpenMP specification implemented by the <lang> com‐
16043 piler.
16044 OpenMP_<lang>_VERSION_MAJOR
16046 Major version of OpenMP implemented by the <lang> compiler.
16047 OpenMP_<lang>_VERSION_MINOR
16049 Minor version of OpenMP implemented by the <lang> compiler.
16050 OpenMP_<lang>_VERSION
16052 OpenMP version implemented by the <lang> compiler.
16053 The specification date is formatted as given in the OpenMP standard:
16055 yyyymm where yyyy and mm represents the year and month of the OpenMP
16056 specification implemented by the <lang> compiler.
16057 For some compilers, it may be necessary to add a header search path to
16059 find the relevant OpenMP headers. This location may be language-spe‐
16060 cific. Where this is needed, the module may attempt to find the loca‐
16061 tion, but it can be provided directly by setting the OpenMP_<lang>_IN‐
16062 CLUDE_DIR cache variable. Note that this variable is an _input_ con‐
16063 trol to the module. Project code should use the OpenMP_<lang>_IN‐
16064 CLUDE_DIRS _output_ variable if it needs to know what include directo‐
16065 ries are needed.
16066 FindOpenSceneGraph
16068 Find OpenSceneGraph (3D graphics application programming interface)
16069 This module searches for the OpenSceneGraph core "osg" library as well
16071 as FindOpenThreads, and whatever additional COMPONENTS (nodekits) that
16072 you specify.
16073 See http://www.openscenegraph.org
16075 NOTE: To use this module effectively you must either require CMake >=
16077 2.6.3 with cmake_minimum_required(VERSION 2.6.3) or download and place
16078 FindOpenThreads, Findosg functions, Findosg and Find<etc>.cmake files
16079 into your CMAKE_MODULE_PATH.
16080 ----
16083 This module accepts the following variables (note mixed case)
16087 OpenSceneGraph_DEBUG - Enable debugging output
16089 OpenSceneGraph_MARK_AS_ADVANCED - Mark cache variables as advanced
16091 automatically
16092 The following environment variables are also respected for finding the
16094 OSG and it's various components. CMAKE_PREFIX_PATH can also be used
16095 for this (see find_library() CMake documentation).
16096 <MODULE>_DIR
16098 (where MODULE is of the form "OSGVOLUME" and there is a
16099 FindosgVolume.cmake` file)
16100 OSG_DIR
16102 OSGDIR
16104 OSG_ROOT
16106 [CMake 2.8.10]: The CMake variable OSG_DIR can now be used as well to
16108 influence detection, instead of needing to specify an environment vari‐
16109 able.
16110 This module defines the following output variables:
16112 OPENSCENEGRAPH_FOUND - Was the OSG and all of the specified components found?
16114 OPENSCENEGRAPH_VERSION - The version of the OSG which was found
16116 OPENSCENEGRAPH_INCLUDE_DIRS - Where to find the headers
16118 OPENSCENEGRAPH_LIBRARIES - The OSG libraries
16120 ================================== Example Usage:
16122 find_package(OpenSceneGraph 2.0.0 REQUIRED osgDB osgUtil)
16124 # libOpenThreads & libosg automatically searched
16125 include_directories(${OPENSCENEGRAPH_INCLUDE_DIRS})
16126 add_executable(foo foo.cc)
16128 target_link_libraries(foo ${OPENSCENEGRAPH_LIBRARIES})
16129 FindOpenSP
16131 New in version 3.25.
16132 Try to find the OpenSP library.
16135 Result Variables
16137 This will define the following variables:
16138 OpenSP_FOUND
16140 True if (the requested version of) OpenSP is available
16141 OpenSP_VERSION
16143 The version of OpenSP
16144 OpenSP_VERSION_MAJOR
16146 The major version of OpenSP
16147 OpenSP_VERSION_MINOR
16149 The minor version of OpenSP
16150 OpenSP_VERSION_PATCH
16152 The patch version of OpenSP
16153 OpenSP_INCLUDE_DIRS
16155 The include dirs of OpenSP with its headers
16156 OpenSP_LIBRARIES
16158 The OpenSP library for use with target_link_libraries(). This
16159 can be passed to target_link_libraries() instead of the IMPORTED
16160 OpenSP::OpenSP target
16161 OpenSP_MULTI_BYTE
16163 True if SP_MULTI_BYTE was found to be defined in OpenSP's con‐
16164 fig.h header file, which indicates that the OpenSP library was
16165 compiled with support for multi-byte characters. The consuming
16166 target needs to define the SP_MULTI_BYTE to match this value in
16167 order to avoid issues with character decoding.
16168 IMPORTED Targets
16170 This module defines the IMPORTED target OpenSP::OpenSP, if OpenSP has
16171 been found.
16172 Cache variables
16174 The following cache variables may also be set:
16175 OpenSP_INCLUDE_DIR
16177 the OpenSP include directory
16178 OpenSP_LIBRARY
16180 the absolute path of the osp library
16181 FindOpenSSL
16183 Find the OpenSSL encryption library.
16184 This module finds an installed OpenSSL library and determines its ver‐
16186 sion.
16187 New in version 3.19: When a version is requested, it can be specified
16189 as a simple value or as a range. For a detailed description of version
16190 range usage and capabilities, refer to the find_package() command.
16191 New in version 3.18: Support for OpenSSL 3.0.
16194 Optional COMPONENTS
16197 New in version 3.12.
16198 This module supports two optional COMPONENTS: Crypto and SSL. Both
16201 components have associated imported targets, as described below.
16202 Imported Targets
16204 New in version 3.4.
16205 This module defines the following IMPORTED targets:
16208 OpenSSL::SSL
16210 The OpenSSL ssl library, if found.
16211 OpenSSL::Crypto
16213 The OpenSSL crypto library, if found.
16214 OpenSSL::applink
16216 New in version 3.18.
16217 The OpenSSL applink components that might be need to be compiled
16220 into projects under MSVC. This target is available only if found
16221 OpenSSL version is not less than 0.9.8. By linking this target
16222 the above OpenSSL targets can be linked even if the project has
16223 different MSVC runtime configurations with the above OpenSSL
16224 targets. This target has no effect on platforms other than MSVC.
16225 NOTE: Due to how INTERFACE_SOURCES are consumed by the consuming tar‐
16227 get, unless you certainly know what you are doing, it is always pre‐
16228 ferred to link OpenSSL::applink target as PRIVATE and to make sure that
16229 this target is linked at most once for the whole dependency graph of
16230 any library or executable:
16231 target_link_libraries(myTarget PRIVATE OpenSSL::applink)
16233 Otherwise you would probably encounter unexpected random problems when
16235 building and linking, as both the ISO C and the ISO C++ standard claims
16236 almost nothing about what a link process should be.
16237 Result Variables
16239 This module will set the following variables in your project:
16240 OPENSSL_FOUND
16242 System has the OpenSSL library. If no components are requested
16243 it only requires the crypto library.
16244 OPENSSL_INCLUDE_DIR
16246 The OpenSSL include directory.
16247 OPENSSL_CRYPTO_LIBRARY
16249 The OpenSSL crypto library.
16250 OPENSSL_CRYPTO_LIBRARIES
16252 The OpenSSL crypto library and its dependencies.
16253 OPENSSL_SSL_LIBRARY
16255 The OpenSSL SSL library.
16256 OPENSSL_SSL_LIBRARIES
16258 The OpenSSL SSL library and its dependencies.
16259 OPENSSL_LIBRARIES
16261 All OpenSSL libraries and their dependencies.
16262 OPENSSL_VERSION
16264 This is set to $major.$minor.$revision$patch (e.g. 0.9.8s).
16265 OPENSSL_APPLINK_SOURCE
16267 The sources in the target OpenSSL::applink that is mentioned
16268 above. This variable shall always be undefined if found openssl
16269 version is less than 0.9.8 or if platform is not MSVC.
16270 Hints
16272 The following variables may be set to control search behavior:
16273 OPENSSL_ROOT_DIR
16275 Set to the root directory of an OpenSSL installation.
16276 OPENSSL_USE_STATIC_LIBS
16278 New in version 3.4.
16279 Set to TRUE to look for static libraries.
16282 OPENSSL_MSVC_STATIC_RT
16284 New in version 3.5.
16285 Set to TRUE to choose the MT version of the lib.
16288 ENV{PKG_CONFIG_PATH}
16290 On UNIX-like systems, pkg-config is used to locate the system
16291 OpenSSL. Set the PKG_CONFIG_PATH environment variable to look
16292 in alternate locations. Useful on multi-lib systems.
16293 FindOpenThreads
16295 OpenThreads is a C++ based threading library. Its largest userbase
16296 seems to OpenSceneGraph so you might notice I accept OSGDIR as an envi‐
16297 ronment path. I consider this part of the Findosg* suite used to find
16298 OpenSceneGraph components. Each component is separate and you must opt
16299 in to each module.
16300 Locate OpenThreads This module defines OPENTHREADS_LIBRARY
16302 OPENTHREADS_FOUND, if false, do not try to link to OpenThreads
16303 OPENTHREADS_INCLUDE_DIR, where to find the headers
16304 $OPENTHREADS_DIR is an environment variable that would correspond to
16306 the ./configure --prefix=$OPENTHREADS_DIR used in building osg.
16307 [CMake 2.8.10]: The CMake variables OPENTHREADS_DIR or OSG_DIR can now
16309 be used as well to influence detection, instead of needing to specify
16310 an environment variable.
16311 Created by Eric Wing.
16313 Findosg
16315 NOTE: It is highly recommended that you use the new FindOpenScene‐
16316 Graph.cmake introduced in CMake 2.6.3 and not use this Find module di‐
16317 rectly.
16318 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16320 nents. Each component is separate and you must opt in to each module.
16321 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16322 as these modules won't do it for you. This is to allow you control
16323 over your own system piece by piece in case you need to opt out of cer‐
16324 tain components or change the Find behavior for a particular module
16325 (perhaps because the default FindOpenGL.cmake module doesn't work with
16326 your system as an example). If you want to use a more convenient mod‐
16327 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16328 of the Findosg*.cmake modules.
16329 Locate osg This module defines
16331 OSG_FOUND - Was the Osg found? OSG_INCLUDE_DIR - Where to find the
16333 headers OSG_LIBRARIES - The libraries to link against for the OSG (use
16334 this)
16335 OSG_LIBRARY - The OSG library OSG_LIBRARY_DEBUG - The OSG debug library
16337 $OSGDIR is an environment variable that would correspond to the ./con‐
16339 figure --prefix=$OSGDIR used in building osg.
16340 Created by Eric Wing.
16342 Findosg_functions
16344 This CMake file contains two macros to assist with searching for OSG
16345 libraries and nodekits. Please see FindOpenSceneGraph.cmake for full
16346 documentation.
16347 FindosgAnimation
16349 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16350 nents. Each component is separate and you must opt in to each module.
16351 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16352 as these modules won't do it for you. This is to allow you control
16353 over your own system piece by piece in case you need to opt out of cer‐
16354 tain components or change the Find behavior for a particular module
16355 (perhaps because the default FindOpenGL.cmake module doesn't work with
16356 your system as an example). If you want to use a more convenient mod‐
16357 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16358 of the Findosg*.cmake modules.
16359 Locate osgAnimation This module defines
16361 OSGANIMATION_FOUND - Was osgAnimation found? OSGANIMATION_INCLUDE_DIR -
16363 Where to find the headers OSGANIMATION_LIBRARIES - The libraries to
16364 link against for the OSG (use this)
16365 OSGANIMATION_LIBRARY - The OSG library OSGANIMATION_LIBRARY_DEBUG - The
16367 OSG debug library
16368 $OSGDIR is an environment variable that would correspond to the ./con‐
16370 figure --prefix=$OSGDIR used in building osg.
16371 Created by Eric Wing.
16373 FindosgDB
16375 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16376 nents. Each component is separate and you must opt in to each module.
16377 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16378 as these modules won't do it for you. This is to allow you control
16379 over your own system piece by piece in case you need to opt out of cer‐
16380 tain components or change the Find behavior for a particular module
16381 (perhaps because the default FindOpenGL module doesn't work with your
16382 system as an example). If you want to use a more convenient module
16383 that includes everything, use the FindOpenSceneGraph instead of the
16384 Findosg*.cmake modules.
16385 Locate osgDB This module defines:
16387 OSGDB_FOUND
16389 Was osgDB found?
16390 OSGDB_INCLUDE_DIR
16392 Where to find the headers
16393 OSGDB_LIBRARIES
16395 The libraries to link against for the osgDB
16396 OSGDB_LIBRARY
16398 The osgDB library
16399 OSGDB_LIBRARY_DEBUG
16401 The osgDB debug library
16402 $OSGDIR is an environment variable that would correspond to:
16404 ./configure --prefix=$OSGDIR used in building osg.
16406 FindosgFX
16408 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16409 nents. Each component is separate and you must opt in to each module.
16410 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16411 as these modules won't do it for you. This is to allow you control
16412 over your own system piece by piece in case you need to opt out of cer‐
16413 tain components or change the Find behavior for a particular module
16414 (perhaps because the default FindOpenGL.cmake module doesn't work with
16415 your system as an example). If you want to use a more convenient mod‐
16416 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16417 of the Findosg*.cmake modules.
16418 Locate osgFX This module defines
16420 OSGFX_FOUND - Was osgFX found? OSGFX_INCLUDE_DIR - Where to find the
16422 headers OSGFX_LIBRARIES - The libraries to link against for the osgFX
16423 (use this)
16424 OSGFX_LIBRARY - The osgFX library OSGFX_LIBRARY_DEBUG - The osgFX debug
16426 library
16427 $OSGDIR is an environment variable that would correspond to the ./con‐
16429 figure --prefix=$OSGDIR used in building osg.
16430 Created by Eric Wing.
16432 FindosgGA
16434 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16435 nents. Each component is separate and you must opt in to each module.
16436 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16437 as these modules won't do it for you. This is to allow you control
16438 over your own system piece by piece in case you need to opt out of cer‐
16439 tain components or change the Find behavior for a particular module
16440 (perhaps because the default FindOpenGL.cmake module doesn't work with
16441 your system as an example). If you want to use a more convenient mod‐
16442 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16443 of the Findosg*.cmake modules.
16444 Locate osgGA This module defines
16446 OSGGA_FOUND - Was osgGA found? OSGGA_INCLUDE_DIR - Where to find the
16448 headers OSGGA_LIBRARIES - The libraries to link against for the osgGA
16449 (use this)
16450 OSGGA_LIBRARY - The osgGA library OSGGA_LIBRARY_DEBUG - The osgGA debug
16452 library
16453 $OSGDIR is an environment variable that would correspond to the ./con‐
16455 figure --prefix=$OSGDIR used in building osg.
16456 Created by Eric Wing.
16458 FindosgIntrospection
16460 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16461 nents. Each component is separate and you must opt in to each module.
16462 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16463 as these modules won't do it for you. This is to allow you control
16464 over your own system piece by piece in case you need to opt out of cer‐
16465 tain components or change the Find behavior for a particular module
16466 (perhaps because the default FindOpenGL.cmake module doesn't work with
16467 your system as an example). If you want to use a more convenient mod‐
16468 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16469 of the Findosg*.cmake modules.
16470 Locate osgINTROSPECTION This module defines
16472 OSGINTROSPECTION_FOUND - Was osgIntrospection found? OSGINTROSPEC‐
16474 TION_INCLUDE_DIR - Where to find the headers OSGINTROSPECTION_LIBRARIES
16475 - The libraries to link for osgIntrospection (use this)
16476 OSGINTROSPECTION_LIBRARY - The osgIntrospection library OSGINTROSPEC‐
16478 TION_LIBRARY_DEBUG - The osgIntrospection debug library
16479 $OSGDIR is an environment variable that would correspond to the ./con‐
16481 figure --prefix=$OSGDIR used in building osg.
16482 Created by Eric Wing.
16484 FindosgManipulator
16486 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16487 nents. Each component is separate and you must opt in to each module.
16488 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16489 as these modules won't do it for you. This is to allow you control
16490 over your own system piece by piece in case you need to opt out of cer‐
16491 tain components or change the Find behavior for a particular module
16492 (perhaps because the default FindOpenGL.cmake module doesn't work with
16493 your system as an example). If you want to use a more convenient mod‐
16494 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16495 of the Findosg*.cmake modules.
16496 Locate osgManipulator This module defines
16498 OSGMANIPULATOR_FOUND - Was osgManipulator found? OSGMANIPULATOR_IN‐
16500 CLUDE_DIR - Where to find the headers OSGMANIPULATOR_LIBRARIES - The
16501 libraries to link for osgManipulator (use this)
16502 OSGMANIPULATOR_LIBRARY - The osgManipulator library OSGMANIPULATOR_LI‐
16504 BRARY_DEBUG - The osgManipulator debug library
16505 $OSGDIR is an environment variable that would correspond to the ./con‐
16507 figure --prefix=$OSGDIR used in building osg.
16508 Created by Eric Wing.
16510 FindosgParticle
16512 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16513 nents. Each component is separate and you must opt in to each module.
16514 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16515 as these modules won't do it for you. This is to allow you control
16516 over your own system piece by piece in case you need to opt out of cer‐
16517 tain components or change the Find behavior for a particular module
16518 (perhaps because the default FindOpenGL.cmake module doesn't work with
16519 your system as an example). If you want to use a more convenient mod‐
16520 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16521 of the Findosg*.cmake modules.
16522 Locate osgParticle This module defines
16524 OSGPARTICLE_FOUND - Was osgParticle found? OSGPARTICLE_INCLUDE_DIR -
16526 Where to find the headers OSGPARTICLE_LIBRARIES - The libraries to link
16527 for osgParticle (use this)
16528 OSGPARTICLE_LIBRARY - The osgParticle library OSGPARTICLE_LIBRARY_DEBUG
16530 - The osgParticle debug library
16531 $OSGDIR is an environment variable that would correspond to the ./con‐
16533 figure --prefix=$OSGDIR used in building osg.
16534 Created by Eric Wing.
16536 FindosgPresentation
16538 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16539 nents. Each component is separate and you must opt in to each module.
16540 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16541 as these modules won't do it for you. This is to allow you control
16542 over your own system piece by piece in case you need to opt out of cer‐
16543 tain components or change the Find behavior for a particular module
16544 (perhaps because the default FindOpenGL.cmake module doesn't work with
16545 your system as an example). If you want to use a more convenient mod‐
16546 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16547 of the Findosg*.cmake modules.
16548 Locate osgPresentation This module defines
16550 OSGPRESENTATION_FOUND - Was osgPresentation found? OSGPRESENTATION_IN‐
16552 CLUDE_DIR - Where to find the headers OSGPRESENTATION_LIBRARIES - The
16553 libraries to link for osgPresentation (use this)
16554 OSGPRESENTATION_LIBRARY - The osgPresentation library OSGPRESENTA‐
16556 TION_LIBRARY_DEBUG - The osgPresentation debug library
16557 $OSGDIR is an environment variable that would correspond to the ./con‐
16559 figure --prefix=$OSGDIR used in building osg.
16560 Created by Eric Wing. Modified to work with osgPresentation by Robert
16562 Osfield, January 2012.
16563 FindosgProducer
16565 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16566 nents. Each component is separate and you must opt in to each module.
16567 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16568 as these modules won't do it for you. This is to allow you control
16569 over your own system piece by piece in case you need to opt out of cer‐
16570 tain components or change the Find behavior for a particular module
16571 (perhaps because the default FindOpenGL.cmake module doesn't work with
16572 your system as an example). If you want to use a more convenient mod‐
16573 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16574 of the Findosg*.cmake modules.
16575 Locate osgProducer This module defines
16577 OSGPRODUCER_FOUND - Was osgProducer found? OSGPRODUCER_INCLUDE_DIR -
16579 Where to find the headers OSGPRODUCER_LIBRARIES - The libraries to link
16580 for osgProducer (use this)
16581 OSGPRODUCER_LIBRARY - The osgProducer library OSGPRODUCER_LIBRARY_DEBUG
16583 - The osgProducer debug library
16584 $OSGDIR is an environment variable that would correspond to the ./con‐
16586 figure --prefix=$OSGDIR used in building osg.
16587 Created by Eric Wing.
16589 FindosgQt
16591 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16592 nents. Each component is separate and you must opt in to each module.
16593 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16594 as these modules won't do it for you. This is to allow you control
16595 over your own system piece by piece in case you need to opt out of cer‐
16596 tain components or change the Find behavior for a particular module
16597 (perhaps because the default FindOpenGL.cmake module doesn't work with
16598 your system as an example). If you want to use a more convenient mod‐
16599 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16600 of the Findosg*.cmake modules.
16601 Locate osgQt This module defines
16603 OSGQT_FOUND - Was osgQt found? OSGQT_INCLUDE_DIR - Where to find the
16605 headers OSGQT_LIBRARIES - The libraries to link for osgQt (use this)
16606 OSGQT_LIBRARY - The osgQt library OSGQT_LIBRARY_DEBUG - The osgQt debug
16608 library
16609 $OSGDIR is an environment variable that would correspond to the ./con‐
16611 figure --prefix=$OSGDIR used in building osg.
16612 Created by Eric Wing. Modified to work with osgQt by Robert Osfield,
16614 January 2012.
16615 FindosgShadow
16617 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16618 nents. Each component is separate and you must opt in to each module.
16619 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16620 as these modules won't do it for you. This is to allow you control
16621 over your own system piece by piece in case you need to opt out of cer‐
16622 tain components or change the Find behavior for a particular module
16623 (perhaps because the default FindOpenGL.cmake module doesn't work with
16624 your system as an example). If you want to use a more convenient mod‐
16625 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16626 of the Findosg*.cmake modules.
16627 Locate osgShadow This module defines
16629 OSGSHADOW_FOUND - Was osgShadow found? OSGSHADOW_INCLUDE_DIR - Where to
16631 find the headers OSGSHADOW_LIBRARIES - The libraries to link for os‐
16632 gShadow (use this)
16633 OSGSHADOW_LIBRARY - The osgShadow library OSGSHADOW_LIBRARY_DEBUG - The
16635 osgShadow debug library
16636 $OSGDIR is an environment variable that would correspond to the ./con‐
16638 figure --prefix=$OSGDIR used in building osg.
16639 Created by Eric Wing.
16641 FindosgSim
16643 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16644 nents. Each component is separate and you must opt in to each module.
16645 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16646 as these modules won't do it for you. This is to allow you control
16647 over your own system piece by piece in case you need to opt out of cer‐
16648 tain components or change the Find behavior for a particular module
16649 (perhaps because the default FindOpenGL.cmake module doesn't work with
16650 your system as an example). If you want to use a more convenient mod‐
16651 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16652 of the Findosg*.cmake modules.
16653 Locate osgSim This module defines
16655 OSGSIM_FOUND - Was osgSim found? OSGSIM_INCLUDE_DIR - Where to find the
16657 headers OSGSIM_LIBRARIES - The libraries to link for osgSim (use this)
16658 OSGSIM_LIBRARY - The osgSim library OSGSIM_LIBRARY_DEBUG - The osgSim
16660 debug library
16661 $OSGDIR is an environment variable that would correspond to the ./con‐
16663 figure --prefix=$OSGDIR used in building osg.
16664 Created by Eric Wing.
16666 FindosgTerrain
16668 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16669 nents. Each component is separate and you must opt in to each module.
16670 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16671 as these modules won't do it for you. This is to allow you control
16672 over your own system piece by piece in case you need to opt out of cer‐
16673 tain components or change the Find behavior for a particular module
16674 (perhaps because the default FindOpenGL.cmake module doesn't work with
16675 your system as an example). If you want to use a more convenient mod‐
16676 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16677 of the Findosg*.cmake modules.
16678 Locate osgTerrain This module defines
16680 OSGTERRAIN_FOUND - Was osgTerrain found? OSGTERRAIN_INCLUDE_DIR - Where
16682 to find the headers OSGTERRAIN_LIBRARIES - The libraries to link for
16683 osgTerrain (use this)
16684 OSGTERRAIN_LIBRARY - The osgTerrain library OSGTERRAIN_LIBRARY_DEBUG -
16686 The osgTerrain debug library
16687 $OSGDIR is an environment variable that would correspond to the ./con‐
16689 figure --prefix=$OSGDIR used in building osg.
16690 Created by Eric Wing.
16692 FindosgText
16694 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16695 nents. Each component is separate and you must opt in to each module.
16696 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16697 as these modules won't do it for you. This is to allow you control
16698 over your own system piece by piece in case you need to opt out of cer‐
16699 tain components or change the Find behavior for a particular module
16700 (perhaps because the default FindOpenGL.cmake module doesn't work with
16701 your system as an example). If you want to use a more convenient mod‐
16702 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16703 of the Findosg*.cmake modules.
16704 Locate osgText This module defines
16706 OSGTEXT_FOUND - Was osgText found? OSGTEXT_INCLUDE_DIR - Where to find
16708 the headers OSGTEXT_LIBRARIES - The libraries to link for osgText (use
16709 this)
16710 OSGTEXT_LIBRARY - The osgText library OSGTEXT_LIBRARY_DEBUG - The osg‐
16712 Text debug library
16713 $OSGDIR is an environment variable that would correspond to the ./con‐
16715 figure --prefix=$OSGDIR used in building osg.
16716 Created by Eric Wing.
16718 FindosgUtil
16720 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16721 nents. Each component is separate and you must opt in to each module.
16722 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16723 as these modules won't do it for you. This is to allow you control
16724 over your own system piece by piece in case you need to opt out of cer‐
16725 tain components or change the Find behavior for a particular module
16726 (perhaps because the default FindOpenGL.cmake module doesn't work with
16727 your system as an example). If you want to use a more convenient mod‐
16728 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16729 of the Findosg*.cmake modules.
16730 Locate osgUtil This module defines
16732 OSGUTIL_FOUND - Was osgUtil found? OSGUTIL_INCLUDE_DIR - Where to find
16734 the headers OSGUTIL_LIBRARIES - The libraries to link for osgUtil (use
16735 this)
16736 OSGUTIL_LIBRARY - The osgUtil library OSGUTIL_LIBRARY_DEBUG - The
16738 osgUtil debug library
16739 $OSGDIR is an environment variable that would correspond to the ./con‐
16741 figure --prefix=$OSGDIR used in building osg.
16742 Created by Eric Wing.
16744 FindosgViewer
16746 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16747 nents. Each component is separate and you must opt in to each module.
16748 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16749 as these modules won't do it for you. This is to allow you control
16750 over your own system piece by piece in case you need to opt out of cer‐
16751 tain components or change the Find behavior for a particular module
16752 (perhaps because the default FindOpenGL.cmake module doesn't work with
16753 your system as an example). If you want to use a more convenient mod‐
16754 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16755 of the Findosg*.cmake modules.
16756 Locate osgViewer This module defines
16758 OSGVIEWER_FOUND - Was osgViewer found? OSGVIEWER_INCLUDE_DIR - Where to
16760 find the headers OSGVIEWER_LIBRARIES - The libraries to link for os‐
16761 gViewer (use this)
16762 OSGVIEWER_LIBRARY - The osgViewer library OSGVIEWER_LIBRARY_DEBUG - The
16764 osgViewer debug library
16765 $OSGDIR is an environment variable that would correspond to the ./con‐
16767 figure --prefix=$OSGDIR used in building osg.
16768 Created by Eric Wing.
16770 FindosgVolume
16772 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16773 nents. Each component is separate and you must opt in to each module.
16774 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16775 as these modules won't do it for you. This is to allow you control
16776 over your own system piece by piece in case you need to opt out of cer‐
16777 tain components or change the Find behavior for a particular module
16778 (perhaps because the default FindOpenGL.cmake module doesn't work with
16779 your system as an example). If you want to use a more convenient mod‐
16780 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16781 of the Findosg*.cmake modules.
16782 Locate osgVolume This module defines
16784 OSGVOLUME_FOUND - Was osgVolume found? OSGVOLUME_INCLUDE_DIR - Where to
16786 find the headers OSGVOLUME_LIBRARIES - The libraries to link for os‐
16787 gVolume (use this)
16788 OSGVOLUME_LIBRARY - The osgVolume library OSGVOLUME_LIBRARY_DEBUG - The
16790 osgVolume debug library
16791 $OSGDIR is an environment variable that would correspond to the ./con‐
16793 figure --prefix=$OSGDIR used in building osg.
16794 Created by Eric Wing.
16796 FindosgWidget
16798 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16799 nents. Each component is separate and you must opt in to each module.
16800 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16801 as these modules won't do it for you. This is to allow you control
16802 over your own system piece by piece in case you need to opt out of cer‐
16803 tain components or change the Find behavior for a particular module
16804 (perhaps because the default FindOpenGL.cmake module doesn't work with
16805 your system as an example). If you want to use a more convenient mod‐
16806 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16807 of the Findosg*.cmake modules.
16808 Locate osgWidget This module defines
16810 OSGWIDGET_FOUND - Was osgWidget found? OSGWIDGET_INCLUDE_DIR - Where to
16812 find the headers OSGWIDGET_LIBRARIES - The libraries to link for osg‐
16813 Widget (use this)
16814 OSGWIDGET_LIBRARY - The osgWidget library OSGWIDGET_LIBRARY_DEBUG - The
16816 osgWidget debug library
16817 $OSGDIR is an environment variable that would correspond to the ./con‐
16819 figure --prefix=$OSGDIR used in building osg.
16820 FindosgWidget.cmake tweaked from Findosg* suite as created by Eric
16822 Wing.
16823 FindPatch
16825 New in version 3.10.
16826 The module defines the following variables:
16829 Patch_EXECUTABLE
16831 Path to patch command-line executable.
16832 Patch_FOUND
16834 True if the patch command-line executable was found.
16835 The following IMPORTED targets are also defined:
16837 Patch::patch
16839 The command-line executable.
16840 Example usage:
16842 find_package(Patch)
16844 if(Patch_FOUND)
16845 message("Patch found: ${Patch_EXECUTABLE}")
16846 endif()
16847 FindPerl
16849 Find perl
16850 this module looks for Perl
16852 PERL_EXECUTABLE - the full path to perl
16854 PERL_FOUND - If false, don't attempt to use perl.
16855 PERL_VERSION_STRING - version of perl found (since CMake 2.8.8)
16856 FindPerlLibs
16858 Find Perl libraries
16859 This module finds if PERL is installed and determines where the include
16861 files and libraries are. It also determines what the name of the li‐
16862 brary is. This code sets the following variables:
16863 PERLLIBS_FOUND = True if perl.h & libperl were found
16865 PERL_INCLUDE_PATH = path to where perl.h is found
16866 PERL_LIBRARY = path to libperl
16867 PERL_EXECUTABLE = full path to the perl binary
16868 The minimum required version of Perl can be specified using the stan‐
16870 dard syntax, e.g. find_package(PerlLibs 6.0)
16871 The following variables are also available if needed
16873 (introduced after CMake 2.6.4)
16874 PERL_SITESEARCH = path to the sitesearch install dir (-V:installsitesearch)
16876 PERL_SITEARCH = path to the sitelib install directory (-V:installsitearch)
16877 PERL_SITELIB = path to the sitelib install directory (-V:installsitelib)
16878 PERL_VENDORARCH = path to the vendor arch install directory (-V:installvendorarch)
16879 PERL_VENDORLIB = path to the vendor lib install directory (-V:installvendorlib)
16880 PERL_ARCHLIB = path to the core arch lib install directory (-V:archlib)
16881 PERL_PRIVLIB = path to the core priv lib install directory (-V:privlib)
16882 PERL_UPDATE_ARCHLIB = path to the update arch lib install directory (-V:installarchlib)
16883 PERL_UPDATE_PRIVLIB = path to the update priv lib install directory (-V:installprivlib)
16884 PERL_EXTRA_C_FLAGS = Compilation flags used to build perl
16885 FindPHP4
16887 Find PHP4
16888 This module finds if PHP4 is installed and determines where the include
16890 files and libraries are. It also determines what the name of the li‐
16891 brary is. This code sets the following variables:
16892 PHP4_INCLUDE_PATH = path to where php.h can be found
16894 PHP4_EXECUTABLE = full path to the php4 binary
16895 FindPhysFS
16897 Locate PhysFS library This module defines PHYSFS_LIBRARY, the name of
16898 the library to link against PHYSFS_FOUND, if false, do not try to link
16899 to PHYSFS PHYSFS_INCLUDE_DIR, where to find physfs.h
16900 $PHYSFSDIR is an environment variable that would correspond to the
16902 ./configure --prefix=$PHYSFSDIR used in building PHYSFS.
16903 Created by Eric Wing.
16905 FindPike
16907 Find Pike
16908 This module finds if PIKE is installed and determines where the include
16910 files and libraries are. It also determines what the name of the li‐
16911 brary is. This code sets the following variables:
16912 PIKE_INCLUDE_PATH = path to where program.h is found
16914 PIKE_EXECUTABLE = full path to the pike binary
16915 FindPkgConfig
16917 A pkg-config module for CMake.
16918 Finds the pkg-config executable and adds the pkg_get_variable(),
16920 pkg_check_modules() and pkg_search_module() commands. The following
16921 variables will also be set:
16922 PKG_CONFIG_FOUND
16924 True if a pkg-config executable was found.
16925 PKG_CONFIG_VERSION_STRING
16927 New in version 2.8.8.
16928 The version of pkg-config that was found.
16931 PKG_CONFIG_EXECUTABLE
16933 The pathname of the pkg-config program.
16934 PKG_CONFIG_ARGN
16936 New in version 3.22.
16937 A list of arguments to pass to pkg-config.
16940 Both PKG_CONFIG_EXECUTABLE and PKG_CONFIG_ARGN are initialized by the
16942 module, but may be overridden by the user. See Variables Affecting Be‐
16943 havior for how these variables are initialized.
16944 pkg_check_modules
16946 Checks for all the given modules, setting a variety of result
16947 variables in the calling scope.
16948 pkg_check_modules(<prefix>
16950 [REQUIRED] [QUIET]
16951 [NO_CMAKE_PATH]
16952 [NO_CMAKE_ENVIRONMENT_PATH]
16953 [IMPORTED_TARGET [GLOBAL]]
16954 <moduleSpec> [<moduleSpec>...])
16955 When the REQUIRED argument is given, the command will fail with
16957 an error if module(s) could not be found.
16958 When the QUIET argument is given, no status messages will be
16960 printed.
16961 New in version 3.1: The CMAKE_PREFIX_PATH, CMAKE_FRAMEWORK_PATH,
16963 and CMAKE_APPBUNDLE_PATH cache and environment variables will be
16964 added to the pkg-config search path. The NO_CMAKE_PATH and
16965 NO_CMAKE_ENVIRONMENT_PATH arguments disable this behavior for
16966 the cache variables and environment variables respectively. The
16967 PKG_CONFIG_USE_CMAKE_PREFIX_PATH variable set to FALSE disables
16968 this behavior globally.
16969 New in version 3.6: The IMPORTED_TARGET argument will create an
16972 imported target named PkgConfig::<prefix> that can be passed di‐
16973 rectly as an argument to target_link_libraries().
16974 New in version 3.13: The GLOBAL argument will make the imported
16977 target available in global scope.
16978 New in version 3.15: Non-library linker options reported by
16981 pkg-config are stored in the INTERFACE_LINK_OPTIONS target prop‐
16982 erty.
16983 Changed in version 3.18: Include directories specified with
16986 -isystem are stored in the INTERFACE_INCLUDE_DIRECTORIES target
16987 property. Previous versions of CMake left them in the
16988 INTERFACE_COMPILE_OPTIONS property.
16989 Each <moduleSpec> can be either a bare module name or it can be
16992 a module name with a version constraint (operators =, <, >, <=
16993 and >= are supported). The following are examples for a module
16994 named foo with various constraints:
16995 • foo matches any version.
16997 • foo<2 only matches versions before 2.
16999 • foo>=3.1 matches any version from 3.1 or later.
17001 • foo=1.2.3 requires that foo must be exactly version 1.2.3.
17003 The following variables may be set upon return. Two sets of
17005 values exist: One for the common case (<XXX> = <prefix>) and an‐
17006 other for the information pkg-config provides when called with
17007 the --static option (<XXX> = <prefix>_STATIC).
17008 <XXX>_FOUND
17010 set to 1 if module(s) exist
17011 <XXX>_LIBRARIES
17013 only the libraries (without the '-l')
17014 <XXX>_LINK_LIBRARIES
17016 the libraries and their absolute paths
17017 <XXX>_LIBRARY_DIRS
17019 the paths of the libraries (without the '-L')
17020 <XXX>_LDFLAGS
17022 all required linker flags
17023 <XXX>_LDFLAGS_OTHER
17025 all other linker flags
17026 <XXX>_INCLUDE_DIRS
17028 the '-I' preprocessor flags (without the '-I')
17029 <XXX>_CFLAGS
17031 all required cflags
17032 <XXX>_CFLAGS_OTHER
17034 the other compiler flags
17035 All but <XXX>_FOUND may be a ;-list if the associated variable
17037 returned from pkg-config has multiple values.
17038 Changed in version 3.18: Include directories specified with
17040 -isystem are stored in the <XXX>_INCLUDE_DIRS variable. Previ‐
17041 ous versions of CMake left them in <XXX>_CFLAGS_OTHER.
17042 There are some special variables whose prefix depends on the
17045 number of <moduleSpec> given. When there is only one <module‐
17046 Spec>, <YYY> will simply be <prefix>, but if two or more <mod‐
17047 uleSpec> items are given, <YYY> will be <prefix>_<moduleName>.
17048 <YYY>_VERSION
17050 version of the module
17051 <YYY>_PREFIX
17053 prefix directory of the module
17054 <YYY>_INCLUDEDIR
17056 include directory of the module
17057 <YYY>_LIBDIR
17059 lib directory of the module
17060 Changed in version 3.8: For any given <prefix>, pkg_check_mod‐
17062 ules() can be called multiple times with different parameters.
17063 Previous versions of CMake cached and returned the first suc‐
17064 cessful result.
17065 Changed in version 3.16: If a full path to the found library
17068 can't be determined, but it's still visible to the linker, pass
17069 it through as -l<name>. Previous versions of CMake failed in
17070 this case.
17071 Examples:
17074 pkg_check_modules (GLIB2 glib-2.0)
17076 Looks for any version of glib2. If found, the output variable
17078 GLIB2_VERSION will hold the actual version found.
17079 pkg_check_modules (GLIB2 glib-2.0>=2.10)
17081 Looks for at least version 2.10 of glib2. If found, the output
17083 variable GLIB2_VERSION will hold the actual version found.
17084 pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0)
17086 Looks for both glib2-2.0 (at least version 2.10) and any version
17088 of gtk2+-2.0. Only if both are found will FOO be considered
17089 found. The FOO_glib-2.0_VERSION and FOO_gtk+-2.0_VERSION vari‐
17090 ables will be set to their respective found module versions.
17091 pkg_check_modules (XRENDER REQUIRED xrender)
17093 Requires any version of xrender. Example output variables set
17095 by a successful call:
17096 XRENDER_LIBRARIES=Xrender;X11
17098 XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp
17099 pkg_search_module
17101 The behavior of this command is the same as pkg_check_modules(),
17102 except that rather than checking for all the specified modules,
17103 it searches for just the first successful match.
17104 pkg_search_module(<prefix>
17106 [REQUIRED] [QUIET]
17107 [NO_CMAKE_PATH]
17108 [NO_CMAKE_ENVIRONMENT_PATH]
17109 [IMPORTED_TARGET [GLOBAL]]
17110 <moduleSpec> [<moduleSpec>...])
17111 New in version 3.16: If a module is found, the <prefix>_MOD‐
17113 ULE_NAME variable will contain the name of the matching module.
17114 This variable can be used if you need to run pkg_get_variable().
17115 Example:
17118 pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2)
17120 pkg_get_variable
17122 New in version 3.4.
17123 Retrieves the value of a pkg-config variable varName and stores
17126 it in the result variable resultVar in the calling scope.
17127 pkg_get_variable(<resultVar> <moduleName> <varName>)
17129 If pkg-config returns multiple values for the specified vari‐
17131 able, resultVar will contain a ;-list.
17132 For example:
17134 pkg_get_variable(GI_GIRDIR gobject-introspection-1.0 girdir)
17136 Variables Affecting Behavior
17138 PKG_CONFIG_EXECUTABLE
17139 This cache variable can be set to the path of the pkg-config ex‐
17140 ecutable. find_program() is called internally by the module
17141 with this variable.
17142 New in version 3.1: The PKG_CONFIG environment variable can be
17144 used as a hint if PKG_CONFIG_EXECUTABLE has not yet been set.
17145 Changed in version 3.22: If the PKG_CONFIG environment variable
17148 is set, only the first argument is taken from it when using it
17149 as a hint.
17150 PKG_CONFIG_ARGN
17153 New in version 3.22.
17154 This cache variable can be set to a list of arguments to addi‐
17157 tionally pass to pkg-config if needed. If not provided, it will
17158 be initialized from the PKG_CONFIG environment variable, if set.
17159 The first argument in that environment variable is assumed to be
17160 the pkg-config program, while all remaining arguments after that
17161 are used to initialize PKG_CONFIG_ARGN. If no such environment
17162 variable is defined, PKG_CONFIG_ARGN is initialized to an empty
17163 string. The module does not update the variable once it has been
17164 set in the cache.
17165 PKG_CONFIG_USE_CMAKE_PREFIX_PATH
17167 New in version 3.1.
17168 Specifies whether pkg_check_modules() and pkg_search_module()
17171 should add the paths in the CMAKE_PREFIX_PATH,
17172 CMAKE_FRAMEWORK_PATH and CMAKE_APPBUNDLE_PATH cache and environ‐
17173 ment variables to the pkg-config search path.
17174 If this variable is not set, this behavior is enabled by default
17176 if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later, disabled oth‐
17177 erwise.
17178 FindPNG
17180 Find libpng, the official reference library for the PNG image format.
17181 Imported targets
17183 New in version 3.5.
17184 This module defines the following IMPORTED target:
17187 PNG::PNG
17189 The libpng library, if found.
17190 Result variables
17192 This module will set the following variables in your project:
17193 PNG_INCLUDE_DIRS
17195 where to find png.h, etc.
17196 PNG_LIBRARIES
17198 the libraries to link against to use PNG.
17199 PNG_DEFINITIONS
17201 You should add_definitions(${PNG_DEFINITIONS}) before compiling
17202 code that includes png library files.
17203 PNG_FOUND
17205 If false, do not try to use PNG.
17206 PNG_VERSION_STRING
17208 the version of the PNG library found (since CMake 2.8.8)
17209 Obsolete variables
17211 The following variables may also be set, for backwards compatibility:
17212 PNG_LIBRARY
17214 where to find the PNG library.
17215 PNG_INCLUDE_DIR
17217 where to find the PNG headers (same as PNG_INCLUDE_DIRS)
17218 Since PNG depends on the ZLib compression library, none of the above
17220 will be defined unless ZLib can be found.
17221 FindPostgreSQL
17223 Find the PostgreSQL installation.
17224 IMPORTED Targets
17226 New in version 3.14.
17227 This module defines IMPORTED target PostgreSQL::PostgreSQL if Post‐
17230 greSQL has been found.
17231 Result Variables
17233 This module will set the following variables in your project:
17234 PostgreSQL_FOUND
17236 True if PostgreSQL is found.
17237 PostgreSQL_LIBRARIES
17239 the PostgreSQL libraries needed for linking
17240 PostgreSQL_INCLUDE_DIRS
17242 the directories of the PostgreSQL headers
17243 PostgreSQL_LIBRARY_DIRS
17245 the link directories for PostgreSQL libraries
17246 PostgreSQL_VERSION_STRING
17248 the version of PostgreSQL found
17249 PostgreSQL_TYPE_INCLUDE_DIR
17251 the directories of the PostgreSQL server headers
17252 Components
17254 This module contains additional Server component, that forcibly checks
17255 for the presence of server headers. Note that PostgreSQL_TYPE_IN‐
17256 CLUDE_DIR is set regardless of the presence of the Server component in
17257 find_package call.
17258 FindProducer
17260 Though Producer isn't directly part of OpenSceneGraph, its primary user
17261 is OSG so I consider this part of the Findosg* suite used to find Open‐
17262 SceneGraph components. You'll notice that I accept OSGDIR as an envi‐
17263 ronment path.
17264 Each component is separate and you must opt in to each module. You
17266 must also opt into OpenGL (and OpenThreads?) as these modules won't do
17267 it for you. This is to allow you control over your own system piece by
17268 piece in case you need to opt out of certain components or change the
17269 Find behavior for a particular module (perhaps because the default
17270 FindOpenGL.cmake module doesn't work with your system as an example).
17271 If you want to use a more convenient module that includes everything,
17272 use the FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules.
17273 Locate Producer This module defines PRODUCER_LIBRARY PRODUCER_FOUND, if
17275 false, do not try to link to Producer PRODUCER_INCLUDE_DIR, where to
17276 find the headers
17277 $PRODUCER_DIR is an environment variable that would correspond to the
17279 ./configure --prefix=$PRODUCER_DIR used in building osg.
17280 Created by Eric Wing.
17282 FindProtobuf
17284 Locate and configure the Google Protocol Buffers library.
17285 New in version 3.6: Support for find_package() version checks.
17287 Changed in version 3.6: All input and output variables use the Proto‐
17290 buf_ prefix. Variables with PROTOBUF_ prefix are still supported for
17291 compatibility.
17292 The following variables can be set and are optional:
17295 Protobuf_SRC_ROOT_FOLDER
17297 When compiling with MSVC, if this cache variable is set the pro‐
17298 tobuf-default VS project build locations (vsprojects/Debug and
17299 vsprojects/Release or vsprojects/x64/Debug and vspro‐
17300 jects/x64/Release) will be searched for libraries and binaries.
17301 Protobuf_IMPORT_DIRS
17303 List of additional directories to be searched for imported
17304 .proto files.
17305 Protobuf_DEBUG
17307 New in version 3.6.
17308 Show debug messages.
17311 Protobuf_USE_STATIC_LIBS
17313 New in version 3.9.
17314 Set to ON to force the use of the static libraries. Default is
17317 OFF.
17318 Defines the following variables:
17320 Protobuf_FOUND
17322 Found the Google Protocol Buffers library (libprotobuf & header
17323 files)
17324 Protobuf_VERSION
17326 New in version 3.6.
17327 Version of package found.
17330 Protobuf_INCLUDE_DIRS
17332 Include directories for Google Protocol Buffers
17333 Protobuf_LIBRARIES
17335 The protobuf libraries
17336 Protobuf_PROTOC_LIBRARIES
17338 The protoc libraries
17339 Protobuf_LITE_LIBRARIES
17341 The protobuf-lite libraries
17342 New in version 3.9: The following IMPORTED targets are also defined:
17344 protobuf::libprotobuf
17347 The protobuf library.
17348 protobuf::libprotobuf-lite
17350 The protobuf lite library.
17351 protobuf::libprotoc
17353 The protoc library.
17354 protobuf::protoc
17356 New in version 3.10: The protoc compiler.
17357 The following cache variables are also available to set or use:
17360 Protobuf_LIBRARY
17362 The protobuf library
17363 Protobuf_PROTOC_LIBRARY
17365 The protoc library
17366 Protobuf_INCLUDE_DIR
17368 The include directory for protocol buffers
17369 Protobuf_PROTOC_EXECUTABLE
17371 The protoc compiler
17372 Protobuf_LIBRARY_DEBUG
17374 The protobuf library (debug)
17375 Protobuf_PROTOC_LIBRARY_DEBUG
17377 The protoc library (debug)
17378 Protobuf_LITE_LIBRARY
17380 The protobuf lite library
17381 Protobuf_LITE_LIBRARY_DEBUG
17383 The protobuf lite library (debug)
17384 Example:
17386 find_package(Protobuf REQUIRED)
17388 include_directories(${Protobuf_INCLUDE_DIRS})
17389 include_directories(${CMAKE_CURRENT_BINARY_DIR})
17390 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS foo.proto)
17391 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS EXPORT_MACRO DLL_EXPORT foo.proto)
17392 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS DESCRIPTORS PROTO_DESCS foo.proto)
17393 protobuf_generate_python(PROTO_PY foo.proto)
17394 add_executable(bar bar.cc ${PROTO_SRCS} ${PROTO_HDRS})
17395 target_link_libraries(bar ${Protobuf_LIBRARIES})
17396 NOTE:
17398 The protobuf_generate_cpp and protobuf_generate_python functions and
17399 add_executable() or add_library() calls only work properly within
17400 the same directory.
17401 protobuf_generate_cpp
17403 Add custom commands to process .proto files to C++:
17404 protobuf_generate_cpp (<SRCS> <HDRS>
17406 [DESCRIPTORS <DESC>] [EXPORT_MACRO <MACRO>] [<ARGN>...])
17407 SRCS Variable to define with autogenerated source files
17409 HDRS Variable to define with autogenerated header files
17411 DESCRIPTORS
17413 New in version 3.10: Variable to define with autogener‐
17414 ated descriptor files, if requested.
17415 EXPORT_MACRO
17418 is a macro which should expand to __declspec(dllexport)
17419 or __declspec(dllimport) depending on what is being com‐
17420 piled.
17421 ARGN .proto files
17423 protobuf_generate_python
17425 New in version 3.4.
17426 Add custom commands to process .proto files to Python:
17429 protobuf_generate_python (<PY> [<ARGN>...])
17431 PY Variable to define with autogenerated Python files
17433 ARGN .proto files
17435 FindPython
17437 New in version 3.12.
17438 Find Python interpreter, compiler and development environment (include
17441 directories and libraries).
17442 New in version 3.19: When a version is requested, it can be specified
17444 as a simple value or as a range. For a detailed description of version
17445 range usage and capabilities, refer to the find_package() command.
17446 The following components are supported:
17449 • Interpreter: search for Python interpreter.
17451 • Compiler: search for Python compiler. Only offered by IronPython.
17453 • Development: search for development artifacts (include directories
17455 and libraries).
17456 New in version 3.18: This component includes two sub-components which
17458 can be specified independently:
17459 • Development.Module: search for artifacts for Python module develop‐
17461 ments.
17462 • Development.Embed: search for artifacts for Python embedding devel‐
17464 opments.
17465 New in version 3.26:
17468 • Development.SABIModule: search for artifacts for Python module de‐
17470 velopments using the Stable Application Binary Interface. This
17471 component is available only for version 3.2 and upper.
17472 • NumPy: search for NumPy include directories.
17475 New in version 3.14: Added the NumPy component.
17477 If no COMPONENTS are specified, Interpreter is assumed.
17480 If component Development is specified, it implies sub-components Devel‐
17482 opment.Module and Development.Embed.
17483 To ensure consistent versions between components Interpreter, Compiler,
17485 Development (or one of its sub-components) and NumPy, specify all com‐
17486 ponents at the same time:
17487 find_package (Python COMPONENTS Interpreter Development)
17489 This module looks preferably for version 3 of Python. If not found,
17491 version 2 is searched. To manage concurrent versions 3 and 2 of
17492 Python, use FindPython3 and FindPython2 modules rather than this one.
17493 NOTE:
17495 If components Interpreter and Development (or one of its sub-compo‐
17496 nents) are both specified, this module search only for interpreter
17497 with same platform architecture as the one defined by CMake configu‐
17498 ration. This constraint does not apply if only Interpreter component
17499 is specified.
17500 Imported Targets
17502 This module defines the following Imported Targets:
17503 Changed in version 3.14: Imported Targets are only created when
17505 CMAKE_ROLE is PROJECT.
17506 Python::Interpreter
17509 Python interpreter. Target defined if component Interpreter is
17510 found.
17511 Python::Compiler
17513 Python compiler. Target defined if component Compiler is found.
17514 Python::Module
17516 New in version 3.15.
17517 Python library for Python module. Target defined if component
17520 Development.Module is found.
17521 Python::SABIModule
17523 New in version 3.26.
17524 Python library for Python module using the Stable Application
17527 Binary Interface. Target defined if component Development.SABI‐
17528 Module is found.
17529 Python::Python
17531 Python library for Python embedding. Target defined if component
17532 Development.Embed is found.
17533 Python::NumPy
17535 New in version 3.14.
17536 NumPy Python library. Target defined if component NumPy is
17539 found.
17540 Result Variables
17542 This module will set the following variables in your project (see
17543 Standard Variable Names):
17544 Python_FOUND
17546 System has the Python requested components.
17547 Python_Interpreter_FOUND
17549 System has the Python interpreter.
17550 Python_EXECUTABLE
17552 Path to the Python interpreter.
17553 Python_INTERPRETER_ID
17555 A short string unique to the interpreter. Possible values in‐
17557 clude:
17558 • Python
17560 • ActivePython
17562 • Anaconda
17564 • Canopy
17566 • IronPython
17568 • PyPy
17570 Python_STDLIB
17572 Standard platform independent installation directory.
17573 Information returned by sysconfig.get_path('stdlib').
17575 Python_STDARCH
17577 Standard platform dependent installation directory.
17578 Information returned by sysconfig.get_path('platstdlib').
17580 Python_SITELIB
17582 Third-party platform independent installation directory.
17583 Information returned by sysconfig.get_path('purelib').
17585 Python_SITEARCH
17587 Third-party platform dependent installation directory.
17588 Information returned by sysconfig.get_path('platlib').
17590 Python_SOABI
17592 New in version 3.17.
17593 Extension suffix for modules.
17596 Information computed from sysconfig.get_config_var('EXT_SUFFIX')
17598 or sysconfig.get_config_var('SOABI') or python3-config --exten‐
17599 sion-suffix.
17600 Python_SOSABI
17602 New in version 3.26.
17603 Extension suffix for modules using the Stable Application Binary
17606 Interface.
17607 Information computed from importlib.machinery.EXTENSION_SUFFIXES
17609 if the COMPONENT Interpreter was specified. Otherwise, the ex‐
17610 tension is abi3 except for Windows, MSYS and CYGWIN for which
17611 this is an empty string.
17612 Python_Compiler_FOUND
17614 System has the Python compiler.
17615 Python_COMPILER
17617 Path to the Python compiler. Only offered by IronPython.
17618 Python_COMPILER_ID
17620 A short string unique to the compiler. Possible values include:
17622 • IronPython
17624 Python_DOTNET_LAUNCHER
17626 New in version 3.18.
17627 The .Net interpreter. Only used by IronPython implementation.
17630 Python_Development_FOUND
17632 System has the Python development artifacts.
17633 Python_Development.Module_FOUND
17635 New in version 3.18.
17636 System has the Python development artifacts for Python module.
17639 Python_Development.SABIModule_FOUND
17641 New in version 3.26.
17642 System has the Python development artifacts for Python module
17645 using the Stable Application Binary Interface.
17646 Python_Development.Embed_FOUND
17648 New in version 3.18.
17649 System has the Python development artifacts for Python embed‐
17652 ding.
17653 Python_INCLUDE_DIRS
17655 The Python include directories.
17656 Python_LINK_OPTIONS
17658 New in version 3.19.
17659 The Python link options. Some configurations require specific
17662 link options for a correct build and execution.
17663 Python_LIBRARIES
17665 The Python libraries.
17666 Python_LIBRARY_DIRS
17668 The Python library directories.
17669 Python_RUNTIME_LIBRARY_DIRS
17671 The Python runtime library directories.
17672 Python_SABI_LIBRARIES
17674 New in version 3.26.
17675 The Python libraries for the Stable Application Binary Inter‐
17678 face.
17679 Python_SABI_LIBRARY_DIRS
17681 New in version 3.26.
17682 The Python SABI library directories.
17685 Python_RUNTIME_SABI_LIBRARY_DIRS
17687 New in version 3.26.
17688 The Python runtime SABI library directories.
17691 Python_VERSION
17693 Python version.
17694 Python_VERSION_MAJOR
17696 Python major version.
17697 Python_VERSION_MINOR
17699 Python minor version.
17700 Python_VERSION_PATCH
17702 Python patch version.
17703 Python_PyPy_VERSION
17705 New in version 3.18.
17706 Python PyPy version.
17709 Python_NumPy_FOUND
17711 New in version 3.14.
17712 System has the NumPy.
17715 Python_NumPy_INCLUDE_DIRS
17717 New in version 3.14.
17718 The NumPy include directories.
17721 Python_NumPy_VERSION
17723 New in version 3.14.
17724 The NumPy version.
17727 Hints
17729 Python_ROOT_DIR
17730 Define the root directory of a Python installation.
17731 Python_USE_STATIC_LIBS
17733 • If not defined, search for shared libraries and static li‐
17735 braries in that order.
17736 • If set to TRUE, search only for static libraries.
17738 • If set to FALSE, search only for shared libraries.
17740 NOTE:
17742 This hint will be ignored on Windows because static libraries
17743 are not available on this platform.
17744 Python_FIND_ABI
17746 New in version 3.16.
17747 This variable defines which ABIs, as defined in PEP 3149, should
17750 be searched.
17751 NOTE:
17753 This hint will be honored only when searched for Python ver‐
17754 sion 3.
17755 NOTE:
17757 If Python_FIND_ABI is not defined, any ABI will be searched.
17758 The Python_FIND_ABI variable is a 3-tuple specifying, in that
17760 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
17761 element can be set to one of the following:
17762 • ON: Corresponding flag is selected.
17764 • OFF: Corresponding flag is not selected.
17766 • ANY: The two possibilities (ON and OFF) will be searched.
17768 From this 3-tuple, various ABIs will be searched starting from
17770 the most specialized to the most general. Moreover, debug ver‐
17771 sions will be searched after non-debug ones.
17772 For example, if we have:
17774 set (Python_FIND_ABI "ON" "ANY" "ANY")
17776 The following flags combinations will be appended, in that or‐
17778 der, to the artifact names: dmu, dm, du, and d.
17779 And to search any possible ABIs:
17781 set (Python_FIND_ABI "ANY" "ANY" "ANY")
17783 The following combinations, in that order, will be used: mu, m,
17785 u, <empty>, dmu, dm, du and d.
17786 NOTE:
17788 This hint is useful only on POSIX systems. So, on Windows
17789 systems, when Python_FIND_ABI is defined, Python distribu‐
17790 tions from python.org will be found only if value for each
17791 flag is OFF or ANY.
17792 Python_FIND_STRATEGY
17794 New in version 3.15.
17795 This variable defines how lookup will be done. The
17798 Python_FIND_STRATEGY variable can be set to one of the follow‐
17799 ing:
17800 • VERSION: Try to find the most recent version in all specified
17802 locations. This is the default if policy CMP0094 is undefined
17803 or set to OLD.
17804 • LOCATION: Stops lookup as soon as a version satisfying version
17806 constraints is founded. This is the default if policy CMP0094
17807 is set to NEW.
17808 See also Python_FIND_UNVERSIONED_NAMES.
17810 Python_FIND_REGISTRY
17812 New in version 3.13.
17813 On Windows the Python_FIND_REGISTRY variable determine the order
17816 of preference between registry and environment variables. the
17817 Python_FIND_REGISTRY variable can be set to one of the follow‐
17818 ing:
17819 • FIRST: Try to use registry before environment variables. This
17821 is the default.
17822 • LAST: Try to use registry after environment variables.
17824 • NEVER: Never try to use registry.
17826 Python_FIND_FRAMEWORK
17828 New in version 3.15.
17829 On macOS the Python_FIND_FRAMEWORK variable determine the order
17832 of preference between Apple-style and unix-style package compo‐
17833 nents. This variable can take same values as
17834 CMAKE_FIND_FRAMEWORK variable.
17835 NOTE:
17837 Value ONLY is not supported so FIRST will be used instead.
17838 If Python_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
17840 variable will be used, if any.
17841 Python_FIND_VIRTUALENV
17843 New in version 3.15.
17844 This variable defines the handling of virtual environments man‐
17847 aged by virtualenv or conda. It is meaningful only when a vir‐
17848 tual environment is active (i.e. the activate script has been
17849 evaluated). In this case, it takes precedence over
17850 Python_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
17851 Python_FIND_VIRTUALENV variable can be set to one of the follow‐
17852 ing:
17853 • FIRST: The virtual environment is used before any other stan‐
17855 dard paths to look-up for the interpreter. This is the de‐
17856 fault.
17857 • ONLY: Only the virtual environment is used to look-up for the
17859 interpreter.
17860 • STANDARD: The virtual environment is not used to look-up for
17862 the interpreter but environment variable PATH is always con‐
17863 sidered. In this case, variable Python_FIND_REGISTRY (Win‐
17864 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
17865 LAST or NEVER to select preferably the interpreter from the
17866 virtual environment.
17867 New in version 3.17: Added support for conda environments.
17869 NOTE:
17872 If the component Development is requested, it is strongly
17873 recommended to also include the component Interpreter to get
17874 expected result.
17875 Python_FIND_IMPLEMENTATIONS
17877 New in version 3.18.
17878 This variable defines, in an ordered list, the different imple‐
17881 mentations which will be searched. The Python_FIND_IMPLEMENTA‐
17882 TIONS variable can hold the following values:
17883 • CPython: this is the standard implementation. Various prod‐
17885 ucts, like Anaconda or ActivePython, rely on this implementa‐
17886 tion.
17887 • IronPython: This implementation use the CSharp language for
17889 .NET Framework on top of the Dynamic Language Runtime (DLR).
17890 See IronPython.
17891 • PyPy: This implementation use RPython language and RPython
17893 translation toolchain to produce the python interpreter. See
17894 PyPy.
17895 The default value is:
17897 • Windows platform: CPython, IronPython
17899 • Other platforms: CPython
17901 NOTE:
17903 This hint has the lowest priority of all hints, so even if,
17904 for example, you specify IronPython first and CPython in sec‐
17905 ond, a python product based on CPython can be selected be‐
17906 cause, for example with Python_FIND_STRATEGY=LOCATION, each
17907 location will be search first for IronPython and second for
17908 CPython.
17909 NOTE:
17911 When IronPython is specified, on platforms other than Win‐
17912 dows, the .Net interpreter (i.e. mono command) is expected to
17913 be available through the PATH variable.
17914 Python_FIND_UNVERSIONED_NAMES
17916 New in version 3.20.
17917 This variable defines how the generic names will be searched.
17920 Currently, it only applies to the generic names of the inter‐
17921 preter, namely, python3 or python2 and python. The
17922 Python_FIND_UNVERSIONED_NAMES variable can be set to one of the
17923 following values:
17924 • FIRST: The generic names are searched before the more special‐
17926 ized ones (such as python2.5 for example).
17927 • LAST: The generic names are searched after the more special‐
17929 ized ones. This is the default.
17930 • NEVER: The generic name are not searched at all.
17932 See also Python_FIND_STRATEGY.
17934 Artifacts Specification
17936 New in version 3.16.
17937 To solve special cases, it is possible to specify directly the arti‐
17940 facts by setting the following variables:
17941 Python_EXECUTABLE
17943 The path to the interpreter.
17944 Python_COMPILER
17946 The path to the compiler.
17947 Python_DOTNET_LAUNCHER
17949 New in version 3.18.
17950 The .Net interpreter. Only used by IronPython implementation.
17953 Python_LIBRARY
17955 The path to the library. It will be used to compute the vari‐
17956 ables Python_LIBRARIES, Python_LIBRARY_DIRS and Python_RUN‐
17957 TIME_LIBRARY_DIRS.
17958 Python_SABI_LIBRARY
17960 New in version 3.26.
17961 The path to the library for Stable Application Binary Interface.
17964 It will be used to compute the variables Python_SABI_LIBRARIES,
17965 Python_SABI_LIBRARY_DIRS and Python_RUNTIME_SABI_LIBRARY_DIRS.
17966 Python_INCLUDE_DIR
17968 The path to the directory of the Python headers. It will be used
17969 to compute the variable Python_INCLUDE_DIRS.
17970 Python_NumPy_INCLUDE_DIR
17972 The path to the directory of the NumPy headers. It will be used
17973 to compute the variable Python_NumPy_INCLUDE_DIRS.
17974 NOTE:
17976 All paths must be absolute. Any artifact specified with a relative
17977 path will be ignored.
17978 NOTE:
17980 When an artifact is specified, all HINTS will be ignored and no
17981 search will be performed for this artifact.
17982 If more than one artifact is specified, it is the user's responsi‐
17984 bility to ensure the consistency of the various artifacts.
17985 By default, this module supports multiple calls in different directo‐
17987 ries of a project with different version/component requirements while
17988 providing correct and consistent results for each call. To support this
17989 behavior, CMake cache is not used in the traditional way which can be
17990 problematic for interactive specification. So, to enable also interac‐
17991 tive specification, module behavior can be controlled with the follow‐
17992 ing variable:
17993 Python_ARTIFACTS_INTERACTIVE
17995 New in version 3.18.
17996 Selects the behavior of the module. This is a boolean variable:
17999 • If set to TRUE: Create CMake cache entries for the above arti‐
18001 fact specification variables so that users can edit them in‐
18002 teractively. This disables support for multiple version/com‐
18003 ponent requirements.
18004 • If set to FALSE or undefined: Enable multiple version/compo‐
18006 nent requirements.
18007 Commands
18009 This module defines the command Python_add_library (when CMAKE_ROLE is
18010 PROJECT), which has the same semantics as add_library() and adds a de‐
18011 pendency to target Python::Python or, when library type is MODULE, to
18012 target Python::Module or Python::SABIModule (when USE_SABI option is
18013 specified) and takes care of Python module naming rules:
18014 Python_add_library (<name> [STATIC | SHARED | MODULE [USE_SABI <version>] [WITH_SOABI]]
18016 <source1> [<source2> ...])
18017 If the library type is not specified, MODULE is assumed.
18019 New in version 3.17: For MODULE library type, if option WITH_SOABI is
18021 specified, the module suffix will include the Python_SOABI value, if
18022 any.
18023 New in version 3.26: For MODULE type, if the option USE_SABI is speci‐
18026 fied, the preprocessor definition Py_LIMITED_API will be specified, as
18027 PRIVATE, for the target <name> with the value computed from <version>
18028 argument. The expected format for <version> is major[.minor], where
18029 each component is a numeric value. If minor component is specified, the
18030 version should be, at least, 3.2 which is the version where the Stable
18031 Application Binary Interface was introduced. Specifying only major ver‐
18032 sion 3 is equivalent to 3.2.
18033 When option WITH_SOABI is also specified, the module suffix will in‐
18035 clude the Python_SOSABI value, if any.
18036 FindPython2
18039 New in version 3.12.
18040 Find Python 2 interpreter, compiler and development environment (in‐
18043 clude directories and libraries).
18044 New in version 3.19: When a version is requested, it can be specified
18046 as a simple value or as a range. For a detailed description of version
18047 range usage and capabilities, refer to the find_package() command.
18048 The following components are supported:
18051 • Interpreter: search for Python 2 interpreter
18053 • Compiler: search for Python 2 compiler. Only offered by IronPython.
18055 • Development: search for development artifacts (include directories
18057 and libraries).
18058 New in version 3.18: This component includes two sub-components which
18060 can be specified independently:
18061 • Development.Module: search for artifacts for Python 2 module devel‐
18063 opments.
18064 • Development.Embed: search for artifacts for Python 2 embedding de‐
18066 velopments.
18067 • NumPy: search for NumPy include directories.
18070 New in version 3.14: Added the NumPy component.
18072 If no COMPONENTS are specified, Interpreter is assumed.
18075 If component Development is specified, it implies sub-components Devel‐
18077 opment.Module and Development.Embed.
18078 To ensure consistent versions between components Interpreter, Compiler,
18080 Development (or one of its sub-components) and NumPy, specify all com‐
18081 ponents at the same time:
18082 find_package (Python2 COMPONENTS Interpreter Development)
18084 This module looks only for version 2 of Python. This module can be used
18086 concurrently with FindPython3 module to use both Python versions.
18087 The FindPython module can be used if Python version does not matter for
18089 you.
18090 NOTE:
18092 If components Interpreter and Development (or one of its sub-compo‐
18093 nents) are both specified, this module search only for interpreter
18094 with same platform architecture as the one defined by CMake configu‐
18095 ration. This constraint does not apply if only Interpreter component
18096 is specified.
18097 Imported Targets
18099 This module defines the following Imported Targets:
18100 Changed in version 3.14: Imported Targets are only created when
18102 CMAKE_ROLE is PROJECT.
18103 Python2::Interpreter
18106 Python 2 interpreter. Target defined if component Interpreter is
18107 found.
18108 Python2::Compiler
18110 Python 2 compiler. Target defined if component Compiler is
18111 found.
18112 Python2::Module
18114 New in version 3.15.
18115 Python 2 library for Python module. Target defined if component
18118 Development.Module is found.
18119 Python2::Python
18121 Python 2 library for Python embedding. Target defined if compo‐
18122 nent Development.Embed is found.
18123 Python2::NumPy
18125 New in version 3.14.
18126 NumPy library for Python 2. Target defined if component NumPy is
18129 found.
18130 Result Variables
18132 This module will set the following variables in your project (see
18133 Standard Variable Names):
18134 Python2_FOUND
18136 System has the Python 2 requested components.
18137 Python2_Interpreter_FOUND
18139 System has the Python 2 interpreter.
18140 Python2_EXECUTABLE
18142 Path to the Python 2 interpreter.
18143 Python2_INTERPRETER_ID
18145 A short string unique to the interpreter. Possible values in‐
18147 clude:
18148 • Python
18150 • ActivePython
18152 • Anaconda
18154 • Canopy
18156 • IronPython
18158 • PyPy
18160 Python2_STDLIB
18162 Standard platform independent installation directory.
18163 Information returned by sysconfig.get_path('stdlib') or else
18165 distutils.sysconfig.get_python_lib(plat_specific=False,stan‐
18166 dard_lib=True).
18167 Python2_STDARCH
18169 Standard platform dependent installation directory.
18170 Information returned by sysconfig.get_path('platstdlib') or else
18172 distutils.sysconfig.get_python_lib(plat_specific=True,stan‐
18173 dard_lib=True).
18174 Python2_SITELIB
18176 Third-party platform independent installation directory.
18177 Information returned by sysconfig.get_path('purelib') or else
18179 distutils.sysconfig.get_python_lib(plat_specific=False,stan‐
18180 dard_lib=False).
18181 Python2_SITEARCH
18183 Third-party platform dependent installation directory.
18184 Information returned by sysconfig.get_path('platlib') or else
18186 distutils.sysconfig.get_python_lib(plat_specific=True,stan‐
18187 dard_lib=False).
18188 Python2_Compiler_FOUND
18190 System has the Python 2 compiler.
18191 Python2_COMPILER
18193 Path to the Python 2 compiler. Only offered by IronPython.
18194 Python2_COMPILER_ID
18196 A short string unique to the compiler. Possible values include:
18198 • IronPython
18200 Python2_DOTNET_LAUNCHER
18202 New in version 3.18.
18203 The .Net interpreter. Only used by IronPython implementation.
18206 Python2_Development_FOUND
18208 System has the Python 2 development artifacts.
18209 Python2_Development.Module_FOUND
18211 New in version 3.18.
18212 System has the Python 2 development artifacts for Python module.
18215 Python2_Development.Embed_FOUND
18217 New in version 3.18.
18218 System has the Python 2 development artifacts for Python embed‐
18221 ding.
18222 Python2_INCLUDE_DIRS
18224 The Python 2 include directories.
18225 Python2_LINK_OPTIONS
18227 New in version 3.19.
18228 The Python 2 link options. Some configurations require specific
18231 link options for a correct build and execution.
18232 Python2_LIBRARIES
18234 The Python 2 libraries.
18235 Python2_LIBRARY_DIRS
18237 The Python 2 library directories.
18238 Python2_RUNTIME_LIBRARY_DIRS
18240 The Python 2 runtime library directories.
18241 Python2_VERSION
18243 Python 2 version.
18244 Python2_VERSION_MAJOR
18246 Python 2 major version.
18247 Python2_VERSION_MINOR
18249 Python 2 minor version.
18250 Python2_VERSION_PATCH
18252 Python 2 patch version.
18253 Python2_PyPy_VERSION
18255 New in version 3.18.
18256 Python 2 PyPy version.
18259 Python2_NumPy_FOUND
18261 New in version 3.14.
18262 System has the NumPy.
18265 Python2_NumPy_INCLUDE_DIRS
18267 New in version 3.14.
18268 The NumPy include directories.
18271 Python2_NumPy_VERSION
18273 New in version 3.14.
18274 The NumPy version.
18277 Hints
18279 Python2_ROOT_DIR
18280 Define the root directory of a Python 2 installation.
18281 Python2_USE_STATIC_LIBS
18283 • If not defined, search for shared libraries and static li‐
18285 braries in that order.
18286 • If set to TRUE, search only for static libraries.
18288 • If set to FALSE, search only for shared libraries.
18290 NOTE:
18292 This hint will be ignored on Windows because static libraries
18293 are not available on this platform.
18294 Python2_FIND_STRATEGY
18296 New in version 3.15.
18297 This variable defines how lookup will be done. The
18300 Python2_FIND_STRATEGY variable can be set to one of the follow‐
18301 ing:
18302 • VERSION: Try to find the most recent version in all specified
18304 locations. This is the default if policy CMP0094 is undefined
18305 or set to OLD.
18306 • LOCATION: Stops lookup as soon as a version satisfying version
18308 constraints is founded. This is the default if policy CMP0094
18309 is set to NEW.
18310 See also Python2_FIND_UNVERSIONED_NAMES.
18312 Python2_FIND_REGISTRY
18314 New in version 3.13.
18315 On Windows the Python2_FIND_REGISTRY variable determine the or‐
18318 der of preference between registry and environment variables.
18319 the Python2_FIND_REGISTRY variable can be set to one of the fol‐
18320 lowing:
18321 • FIRST: Try to use registry before environment variables. This
18323 is the default.
18324 • LAST: Try to use registry after environment variables.
18326 • NEVER: Never try to use registry.
18328 Python2_FIND_FRAMEWORK
18330 New in version 3.15.
18331 On macOS the Python2_FIND_FRAMEWORK variable determine the order
18334 of preference between Apple-style and unix-style package compo‐
18335 nents. This variable can take same values as
18336 CMAKE_FIND_FRAMEWORK variable.
18337 NOTE:
18339 Value ONLY is not supported so FIRST will be used instead.
18340 If Python2_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
18342 variable will be used, if any.
18343 Python2_FIND_VIRTUALENV
18345 New in version 3.15.
18346 This variable defines the handling of virtual environments man‐
18349 aged by virtualenv or conda. It is meaningful only when a vir‐
18350 tual environment is active (i.e. the activate script has been
18351 evaluated). In this case, it takes precedence over
18352 Python2_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
18353 Python2_FIND_VIRTUALENV variable can be set to one of the fol‐
18354 lowing:
18355 • FIRST: The virtual environment is used before any other stan‐
18357 dard paths to look-up for the interpreter. This is the de‐
18358 fault.
18359 • ONLY: Only the virtual environment is used to look-up for the
18361 interpreter.
18362 • STANDARD: The virtual environment is not used to look-up for
18364 the interpreter but environment variable PATH is always con‐
18365 sidered. In this case, variable Python2_FIND_REGISTRY (Win‐
18366 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
18367 LAST or NEVER to select preferably the interpreter from the
18368 virtual environment.
18369 New in version 3.17: Added support for conda environments.
18371 NOTE:
18374 If the component Development is requested, it is strongly
18375 recommended to also include the component Interpreter to get
18376 expected result.
18377 Python2_FIND_IMPLEMENTATIONS
18379 New in version 3.18.
18380 This variable defines, in an ordered list, the different imple‐
18383 mentations which will be searched. The Python2_FIND_IMPLEMENTA‐
18384 TIONS variable can hold the following values:
18385 • CPython: this is the standard implementation. Various prod‐
18387 ucts, like Anaconda or ActivePython, rely on this implementa‐
18388 tion.
18389 • IronPython: This implementation use the CSharp language for
18391 .NET Framework on top of the Dynamic Language Runtime (DLR).
18392 See IronPython.
18393 • PyPy: This implementation use RPython language and RPython
18395 translation toolchain to produce the python interpreter. See
18396 PyPy.
18397 The default value is:
18399 • Windows platform: CPython, IronPython
18401 • Other platforms: CPython
18403 NOTE:
18405 This hint has the lowest priority of all hints, so even if,
18406 for example, you specify IronPython first and CPython in sec‐
18407 ond, a python product based on CPython can be selected be‐
18408 cause, for example with Python2_FIND_STRATEGY=LOCATION, each
18409 location will be search first for IronPython and second for
18410 CPython.
18411 NOTE:
18413 When IronPython is specified, on platforms other than Win‐
18414 dows, the .Net interpreter (i.e. mono command) is expected to
18415 be available through the PATH variable.
18416 Python2_FIND_UNVERSIONED_NAMES
18418 New in version 3.20.
18419 This variable defines how the generic names will be searched.
18422 Currently, it only applies to the generic names of the inter‐
18423 preter, namely, python2 and python. The Python2_FIND_UNVER‐
18424 SIONED_NAMES variable can be set to one of the following values:
18425 • FIRST: The generic names are searched before the more special‐
18427 ized ones (such as python2.5 for example).
18428 • LAST: The generic names are searched after the more special‐
18430 ized ones. This is the default.
18431 • NEVER: The generic name are not searched at all.
18433 See also Python2_FIND_STRATEGY.
18435 Artifacts Specification
18437 New in version 3.16.
18438 To solve special cases, it is possible to specify directly the arti‐
18441 facts by setting the following variables:
18442 Python2_EXECUTABLE
18444 The path to the interpreter.
18445 Python2_COMPILER
18447 The path to the compiler.
18448 Python2_DOTNET_LAUNCHER
18450 New in version 3.18.
18451 The .Net interpreter. Only used by IronPython implementation.
18454 Python2_LIBRARY
18456 The path to the library. It will be used to compute the vari‐
18457 ables Python2_LIBRARIES, Python2_LIBRARY_DIRS and Python2_RUN‐
18458 TIME_LIBRARY_DIRS.
18459 Python2_INCLUDE_DIR
18461 The path to the directory of the Python headers. It will be used
18462 to compute the variable Python2_INCLUDE_DIRS.
18463 Python2_NumPy_INCLUDE_DIR
18465 The path to the directory of the NumPy headers. It will be used
18466 to compute the variable Python2_NumPy_INCLUDE_DIRS.
18467 NOTE:
18469 All paths must be absolute. Any artifact specified with a relative
18470 path will be ignored.
18471 NOTE:
18473 When an artifact is specified, all HINTS will be ignored and no
18474 search will be performed for this artifact.
18475 If more than one artifact is specified, it is the user's responsi‐
18477 bility to ensure the consistency of the various artifacts.
18478 By default, this module supports multiple calls in different directo‐
18480 ries of a project with different version/component requirements while
18481 providing correct and consistent results for each call. To support this
18482 behavior, CMake cache is not used in the traditional way which can be
18483 problematic for interactive specification. So, to enable also interac‐
18484 tive specification, module behavior can be controlled with the follow‐
18485 ing variable:
18486 Python2_ARTIFACTS_INTERACTIVE
18488 New in version 3.18.
18489 Selects the behavior of the module. This is a boolean variable:
18492 • If set to TRUE: Create CMake cache entries for the above arti‐
18494 fact specification variables so that users can edit them in‐
18495 teractively. This disables support for multiple version/com‐
18496 ponent requirements.
18497 • If set to FALSE or undefined: Enable multiple version/compo‐
18499 nent requirements.
18500 Commands
18502 This module defines the command Python2_add_library (when CMAKE_ROLE is
18503 PROJECT), which has the same semantics as add_library() and adds a de‐
18504 pendency to target Python2::Python or, when library type is MODULE, to
18505 target Python2::Module and takes care of Python module naming rules:
18506 Python2_add_library (<name> [STATIC | SHARED | MODULE]
18508 <source1> [<source2> ...])
18509 If library type is not specified, MODULE is assumed.
18511 FindPython3
18513 New in version 3.12.
18514 Find Python 3 interpreter, compiler and development environment (in‐
18517 clude directories and libraries).
18518 New in version 3.19: When a version is requested, it can be specified
18520 as a simple value or as a range. For a detailed description of version
18521 range usage and capabilities, refer to the find_package() command.
18522 The following components are supported:
18525 • Interpreter: search for Python 3 interpreter
18527 • Compiler: search for Python 3 compiler. Only offered by IronPython.
18529 • Development: search for development artifacts (include directories
18531 and libraries).
18532 New in version 3.18: This component includes two sub-components which
18534 can be specified independently:
18535 • Development.Module: search for artifacts for Python 3 module devel‐
18537 opments.
18538 • Development.Embed: search for artifacts for Python 3 embedding de‐
18540 velopments.
18541 New in version 3.26:
18544 • Development.SABIModule: search for artifacts for Python 3 module
18546 developments using the Stable Application Binary Interface. This
18547 component is available only for version 3.2 and upper.
18548 • NumPy: search for NumPy include directories.
18551 New in version 3.14: Added the NumPy component.
18553 If no COMPONENTS are specified, Interpreter is assumed.
18556 If component Development is specified, it implies sub-components Devel‐
18558 opment.Module and Development.Embed.
18559 To ensure consistent versions between components Interpreter, Compiler,
18561 Development (or one of its sub-components) and NumPy, specify all com‐
18562 ponents at the same time:
18563 find_package (Python3 COMPONENTS Interpreter Development)
18565 This module looks only for version 3 of Python. This module can be used
18567 concurrently with FindPython2 module to use both Python versions.
18568 The FindPython module can be used if Python version does not matter for
18570 you.
18571 NOTE:
18573 If components Interpreter and Development (or one of its sub-compo‐
18574 nents) are both specified, this module search only for interpreter
18575 with same platform architecture as the one defined by CMake configu‐
18576 ration. This constraint does not apply if only Interpreter component
18577 is specified.
18578 Imported Targets
18580 This module defines the following Imported Targets:
18581 Changed in version 3.14: Imported Targets are only created when
18583 CMAKE_ROLE is PROJECT.
18584 Python3::Interpreter
18587 Python 3 interpreter. Target defined if component Interpreter is
18588 found.
18589 Python3::Compiler
18591 Python 3 compiler. Target defined if component Compiler is
18592 found.
18593 Python3::Module
18595 New in version 3.15.
18596 Python 3 library for Python module. Target defined if component
18599 Development.Module is found.
18600 Python3::SABIModule
18602 New in version 3.26.
18603 Python 3 library for Python module using the Stable Application
18606 Binary Interface. Target defined if component Development.SABI‐
18607 Module is found.
18608 Python3::Python
18610 Python 3 library for Python embedding. Target defined if compo‐
18611 nent Development.Embed is found.
18612 Python3::NumPy
18614 New in version 3.14.
18615 NumPy library for Python 3. Target defined if component NumPy is
18618 found.
18619 Result Variables
18621 This module will set the following variables in your project (see
18622 Standard Variable Names):
18623 Python3_FOUND
18625 System has the Python 3 requested components.
18626 Python3_Interpreter_FOUND
18628 System has the Python 3 interpreter.
18629 Python3_EXECUTABLE
18631 Path to the Python 3 interpreter.
18632 Python3_INTERPRETER_ID
18634 A short string unique to the interpreter. Possible values in‐
18636 clude:
18637 • Python
18639 • ActivePython
18641 • Anaconda
18643 • Canopy
18645 • IronPython
18647 • PyPy
18649 Python3_STDLIB
18651 Standard platform independent installation directory.
18652 Information returned by sysconfig.get_path('stdlib').
18654 Python3_STDARCH
18656 Standard platform dependent installation directory.
18657 Information returned by sysconfig.get_path('platstdlib').
18659 Python3_SITELIB
18661 Third-party platform independent installation directory.
18662 Information returned by sysconfig.get_path('purelib').
18664 Python3_SITEARCH
18666 Third-party platform dependent installation directory.
18667 Information returned by sysconfig.get_path('platlib').
18669 Python3_SOABI
18671 New in version 3.17.
18672 Extension suffix for modules.
18675 Information computed from sysconfig.get_config_var('EXT_SUFFIX')
18677 or sysconfig.get_config_var('SOABI') or python3-config --exten‐
18678 sion-suffix.
18679 Python3_SOSABI
18681 New in version 3.26.
18682 Extension suffix for modules using the Stable Application Binary
18685 Interface.
18686 Information computed from importlib.machinery.EXTENSION_SUFFIXES
18688 if the COMPONENT Interpreter was specified. Otherwise, the ex‐
18689 tension is abi3 except for Windows, MSYS and CYGWIN for which
18690 this is an empty string.
18691 Python3_Compiler_FOUND
18693 System has the Python 3 compiler.
18694 Python3_COMPILER
18696 Path to the Python 3 compiler. Only offered by IronPython.
18697 Python3_COMPILER_ID
18699 A short string unique to the compiler. Possible values include:
18701 • IronPython
18703 Python3_DOTNET_LAUNCHER
18705 New in version 3.18.
18706 The .Net interpreter. Only used by IronPython implementation.
18709 Python3_Development_FOUND
18711 System has the Python 3 development artifacts.
18712 Python3_Development.Module_FOUND
18714 New in version 3.18.
18715 System has the Python 3 development artifacts for Python module.
18718 Python3_Development.SABIModule_FOUND
18720 New in version 3.26.
18721 System has the Python 3 development artifacts for Python module
18724 using the Stable Application Binary Interface.
18725 Python3_Development.Embed_FOUND
18727 New in version 3.18.
18728 System has the Python 3 development artifacts for Python embed‐
18731 ding.
18732 Python3_INCLUDE_DIRS
18734 The Python 3 include directories.
18735 Python3_LINK_OPTIONS
18737 New in version 3.19.
18738 The Python 3 link options. Some configurations require specific
18741 link options for a correct build and execution.
18742 Python3_LIBRARIES
18744 The Python 3 libraries.
18745 Python3_LIBRARY_DIRS
18747 The Python 3 library directories.
18748 Python3_RUNTIME_LIBRARY_DIRS
18750 The Python 3 runtime library directories.
18751 Python3_SABI_LIBRARIES
18753 New in version 3.26.
18754 The Python 3 libraries for the Stable Application Binary Inter‐
18757 face.
18758 Python3_SABI_LIBRARY_DIRS
18760 New in version 3.26.
18761 The Python 3 SABI library directories.
18764 Python3_RUNTIME_SABI_LIBRARY_DIRS
18766 New in version 3.26.
18767 The Python 3 runtime SABI library directories.
18770 Python3_VERSION
18772 Python 3 version.
18773 Python3_VERSION_MAJOR
18775 Python 3 major version.
18776 Python3_VERSION_MINOR
18778 Python 3 minor version.
18779 Python3_VERSION_PATCH
18781 Python 3 patch version.
18782 Python3_PyPy_VERSION
18784 New in version 3.18.
18785 Python 3 PyPy version.
18788 Python3_NumPy_FOUND
18790 New in version 3.14.
18791 System has the NumPy.
18794 Python3_NumPy_INCLUDE_DIRS
18796 New in version 3.14.
18797 The NumPy include directories.
18800 Python3_NumPy_VERSION
18802 New in version 3.14.
18803 The NumPy version.
18806 Hints
18808 Python3_ROOT_DIR
18809 Define the root directory of a Python 3 installation.
18810 Python3_USE_STATIC_LIBS
18812 • If not defined, search for shared libraries and static li‐
18814 braries in that order.
18815 • If set to TRUE, search only for static libraries.
18817 • If set to FALSE, search only for shared libraries.
18819 NOTE:
18821 This hint will be ignored on Windows because static libraries
18822 are not available on this platform.
18823 Python3_FIND_ABI
18825 New in version 3.16.
18826 This variable defines which ABIs, as defined in PEP 3149, should
18829 be searched.
18830 NOTE:
18832 If Python3_FIND_ABI is not defined, any ABI will be searched.
18833 The Python3_FIND_ABI variable is a 3-tuple specifying, in that
18835 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
18836 element can be set to one of the following:
18837 • ON: Corresponding flag is selected.
18839 • OFF: Corresponding flag is not selected.
18841 • ANY: The two possibilities (ON and OFF) will be searched.
18843 From this 3-tuple, various ABIs will be searched starting from
18845 the most specialized to the most general. Moreover, debug ver‐
18846 sions will be searched after non-debug ones.
18847 For example, if we have:
18849 set (Python3_FIND_ABI "ON" "ANY" "ANY")
18851 The following flags combinations will be appended, in that or‐
18853 der, to the artifact names: dmu, dm, du, and d.
18854 And to search any possible ABIs:
18856 set (Python3_FIND_ABI "ANY" "ANY" "ANY")
18858 The following combinations, in that order, will be used: mu, m,
18860 u, <empty>, dmu, dm, du and d.
18861 NOTE:
18863 This hint is useful only on POSIX systems. So, on Windows
18864 systems, when Python3_FIND_ABI is defined, Python distribu‐
18865 tions from python.org will be found only if value for each
18866 flag is OFF or ANY.
18867 Python3_FIND_STRATEGY
18869 New in version 3.15.
18870 This variable defines how lookup will be done. The
18873 Python3_FIND_STRATEGY variable can be set to one of the follow‐
18874 ing:
18875 • VERSION: Try to find the most recent version in all specified
18877 locations. This is the default if policy CMP0094 is undefined
18878 or set to OLD.
18879 • LOCATION: Stops lookup as soon as a version satisfying version
18881 constraints is founded. This is the default if policy CMP0094
18882 is set to NEW.
18883 See also Python3_FIND_UNVERSIONED_NAMES.
18885 Python3_FIND_REGISTRY
18887 New in version 3.13.
18888 On Windows the Python3_FIND_REGISTRY variable determine the or‐
18891 der of preference between registry and environment variables.
18892 The Python3_FIND_REGISTRY variable can be set to one of the fol‐
18893 lowing:
18894 • FIRST: Try to use registry before environment variables. This
18896 is the default.
18897 • LAST: Try to use registry after environment variables.
18899 • NEVER: Never try to use registry.
18901 Python3_FIND_FRAMEWORK
18903 New in version 3.15.
18904 On macOS the Python3_FIND_FRAMEWORK variable determine the order
18907 of preference between Apple-style and unix-style package compo‐
18908 nents. This variable can take same values as
18909 CMAKE_FIND_FRAMEWORK variable.
18910 NOTE:
18912 Value ONLY is not supported so FIRST will be used instead.
18913 If Python3_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
18915 variable will be used, if any.
18916 Python3_FIND_VIRTUALENV
18918 New in version 3.15.
18919 This variable defines the handling of virtual environments man‐
18922 aged by virtualenv or conda. It is meaningful only when a vir‐
18923 tual environment is active (i.e. the activate script has been
18924 evaluated). In this case, it takes precedence over
18925 Python3_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
18926 Python3_FIND_VIRTUALENV variable can be set to one of the fol‐
18927 lowing:
18928 • FIRST: The virtual environment is used before any other stan‐
18930 dard paths to look-up for the interpreter. This is the de‐
18931 fault.
18932 • ONLY: Only the virtual environment is used to look-up for the
18934 interpreter.
18935 • STANDARD: The virtual environment is not used to look-up for
18937 the interpreter but environment variable PATH is always con‐
18938 sidered. In this case, variable Python3_FIND_REGISTRY (Win‐
18939 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
18940 LAST or NEVER to select preferably the interpreter from the
18941 virtual environment.
18942 New in version 3.17: Added support for conda environments.
18944 NOTE:
18947 If the component Development is requested, it is strongly
18948 recommended to also include the component Interpreter to get
18949 expected result.
18950 Python3_FIND_IMPLEMENTATIONS
18952 New in version 3.18.
18953 This variable defines, in an ordered list, the different imple‐
18956 mentations which will be searched. The Python3_FIND_IMPLEMENTA‐
18957 TIONS variable can hold the following values:
18958 • CPython: this is the standard implementation. Various prod‐
18960 ucts, like Anaconda or ActivePython, rely on this implementa‐
18961 tion.
18962 • IronPython: This implementation use the CSharp language for
18964 .NET Framework on top of the Dynamic Language Runtime (DLR).
18965 See IronPython.
18966 • PyPy: This implementation use RPython language and RPython
18968 translation toolchain to produce the python interpreter. See
18969 PyPy.
18970 The default value is:
18972 • Windows platform: CPython, IronPython
18974 • Other platforms: CPython
18976 NOTE:
18978 This hint has the lowest priority of all hints, so even if,
18979 for example, you specify IronPython first and CPython in sec‐
18980 ond, a python product based on CPython can be selected be‐
18981 cause, for example with Python3_FIND_STRATEGY=LOCATION, each
18982 location will be search first for IronPython and second for
18983 CPython.
18984 NOTE:
18986 When IronPython is specified, on platforms other than Win‐
18987 dows, the .Net interpreter (i.e. mono command) is expected to
18988 be available through the PATH variable.
18989 Python3_FIND_UNVERSIONED_NAMES
18991 New in version 3.20.
18992 This variable defines how the generic names will be searched.
18995 Currently, it only applies to the generic names of the inter‐
18996 preter, namely, python3 and python. The Python3_FIND_UNVER‐
18997 SIONED_NAMES variable can be set to one of the following values:
18998 • FIRST: The generic names are searched before the more special‐
19000 ized ones (such as python3.5 for example).
19001 • LAST: The generic names are searched after the more special‐
19003 ized ones. This is the default.
19004 • NEVER: The generic name are not searched at all.
19006 See also Python3_FIND_STRATEGY.
19008 Artifacts Specification
19010 New in version 3.16.
19011 To solve special cases, it is possible to specify directly the arti‐
19014 facts by setting the following variables:
19015 Python3_EXECUTABLE
19017 The path to the interpreter.
19018 Python3_COMPILER
19020 The path to the compiler.
19021 Python3_DOTNET_LAUNCHER
19023 New in version 3.18.
19024 The .Net interpreter. Only used by IronPython implementation.
19027 Python3_LIBRARY
19029 The path to the library. It will be used to compute the vari‐
19030 ables Python3_LIBRARIES, Python3_LIBRARY_DIRS and Python3_RUN‐
19031 TIME_LIBRARY_DIRS.
19032 Python3_SABI_LIBRARY
19034 New in version 3.26.
19035 The path to the library for Stable Application Binary Interface.
19038 It will be used to compute the variables Python3_SABI_LIBRARIES,
19039 Python3_SABI_LIBRARY_DIRS and Python3_RUNTIME_SABI_LIBRARY_DIRS.
19040 Python3_INCLUDE_DIR
19042 The path to the directory of the Python headers. It will be used
19043 to compute the variable Python3_INCLUDE_DIRS.
19044 Python3_NumPy_INCLUDE_DIR
19046 The path to the directory of the NumPy headers. It will be used
19047 to compute the variable Python3_NumPy_INCLUDE_DIRS.
19048 NOTE:
19050 All paths must be absolute. Any artifact specified with a relative
19051 path will be ignored.
19052 NOTE:
19054 When an artifact is specified, all HINTS will be ignored and no
19055 search will be performed for this artifact.
19056 If more than one artifact is specified, it is the user's responsi‐
19058 bility to ensure the consistency of the various artifacts.
19059 By default, this module supports multiple calls in different directo‐
19061 ries of a project with different version/component requirements while
19062 providing correct and consistent results for each call. To support this
19063 behavior, CMake cache is not used in the traditional way which can be
19064 problematic for interactive specification. So, to enable also interac‐
19065 tive specification, module behavior can be controlled with the follow‐
19066 ing variable:
19067 Python3_ARTIFACTS_INTERACTIVE
19069 New in version 3.18.
19070 Selects the behavior of the module. This is a boolean variable:
19073 • If set to TRUE: Create CMake cache entries for the above arti‐
19075 fact specification variables so that users can edit them in‐
19076 teractively. This disables support for multiple version/com‐
19077 ponent requirements.
19078 • If set to FALSE or undefined: Enable multiple version/compo‐
19080 nent requirements.
19081 Commands
19083 This module defines the command Python3_add_library (when CMAKE_ROLE is
19084 PROJECT), which has the same semantics as add_library() and adds a de‐
19085 pendency to target Python3::Python or, when library type is MODULE, to
19086 target Python3::Module or Python3::SABIModule (when USE_SABI option is
19087 specified) and takes care of Python module naming rules:
19088 Python3_add_library (<name> [STATIC | SHARED | MODULE [USE_SABI <version>] [WITH_SOABI]]
19090 <source1> [<source2> ...])
19091 If the library type is not specified, MODULE is assumed.
19093 New in version 3.17: For MODULE library type, if option WITH_SOABI is
19095 specified, the module suffix will include the Python3_SOABI value, if
19096 any.
19097 New in version 3.26: For MODULE type, if the option USE_SABI is speci‐
19100 fied, the preprocessor definition Py_LIMITED_API will be specified, as
19101 PRIVATE, for the target <name> with the value computed from <version>
19102 argument. The expected format for <version> is major[.minor], where
19103 each component is a numeric value. If minor component is specified, the
19104 version should be, at least, 3.2 which is the version where the Stable
19105 Application Binary Interface was introduced. Specifying only major ver‐
19106 sion 3 is equivalent to 3.2.
19107 When option WITH_SOABI is also specified, the module suffix will in‐
19109 clude the Python3_SOSABI value, if any.
19110 FindQt3
19113 Locate Qt include paths and libraries
19114 This module defines:
19116 QT_INCLUDE_DIR - where to find qt.h, etc.
19118 QT_LIBRARIES - the libraries to link against to use Qt.
19119 QT_DEFINITIONS - definitions to use when
19120 compiling code that uses Qt.
19121 QT_FOUND - If false, don't try to use Qt.
19122 QT_VERSION_STRING - the version of Qt found
19123 If you need the multithreaded version of Qt, set QT_MT_REQUIRED to TRUE
19125 Also defined, but not for general use are:
19127 QT_MOC_EXECUTABLE, where to find the moc tool.
19129 QT_UIC_EXECUTABLE, where to find the uic tool.
19130 QT_QT_LIBRARY, where to find the Qt library.
19131 QT_QTMAIN_LIBRARY, where to find the qtmain
19132 library. This is only required by Qt3 on Windows.
19133 FindQt4
19135 Finding and Using Qt4
19136 This module can be used to find Qt4. The most important issue is that
19137 the Qt4 qmake is available via the system path. This qmake is then
19138 used to detect basically everything else. This module defines a number
19139 of IMPORTED targets, macros and variables.
19140 Typical usage could be something like:
19142 set(CMAKE_AUTOMOC ON)
19144 set(CMAKE_INCLUDE_CURRENT_DIR ON)
19145 find_package(Qt4 4.4.3 REQUIRED QtGui QtXml)
19146 add_executable(myexe main.cpp)
19147 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
19148 NOTE:
19150 When using IMPORTED targets, the qtmain.lib static library is auto‐
19151 matically linked on Windows for WIN32 executables. To disable that
19152 globally, set the QT4_NO_LINK_QTMAIN variable before finding Qt4. To
19153 disable that for a particular executable, set the QT4_NO_LINK_QTMAIN
19154 target property to TRUE on the executable.
19155 Qt Build Tools
19157 Qt relies on some bundled tools for code generation, such as moc for
19158 meta-object code generation,``uic`` for widget layout and population,
19159 and rcc for virtual filesystem content generation. These tools may be
19160 automatically invoked by cmake(1) if the appropriate conditions are
19161 met. See cmake-qt(7) for more.
19162 Qt Macros
19164 In some cases it can be necessary or useful to invoke the Qt build
19165 tools in a more-manual way. Several macros are available to add targets
19166 for such uses.
19167 macro QT4_WRAP_CPP(outfiles inputfile ... [TARGET tgt] OPTIONS ...)
19169 create moc code from a list of files containing Qt class with
19170 the Q_OBJECT declaration. Per-directory preprocessor definitions
19171 are also added. If the <tgt> is specified, the
19172 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
19173 the <tgt> are passed to moc. Options may be given to moc, such as
19174 those found when executing "moc -help".
19175 macro QT4_WRAP_UI(outfiles inputfile ... OPTIONS ...)
19177 create code from a list of Qt designer ui files.
19178 Options may be given to uic, such as those found
19179 when executing "uic -help"
19180 macro QT4_ADD_RESOURCES(outfiles inputfile ... OPTIONS ...)
19182 create code from a list of Qt resource files.
19183 Options may be given to rcc, such as those found
19184 when executing "rcc -help"
19185 macro QT4_GENERATE_MOC(inputfile outputfile [TARGET tgt])
19187 creates a rule to run moc on infile and create outfile.
19188 Use this if for some reason QT4_WRAP_CPP() isn't appropriate, e.g.
19189 because you need a custom filename for the moc file or something
19190 similar. If the <tgt> is specified, the
19191 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
19192 the <tgt> are passed to moc.
19193 macro QT4_ADD_DBUS_INTERFACE(outfiles interface basename)
19195 Create the interface header and implementation files with the
19196 given basename from the given interface xml file and add it to
19197 the list of sources.
19198 You can pass additional parameters to the qdbusxml2cpp call by setting
19200 properties on the input file:
19201 INCLUDE the given file will be included in the generate interface header
19203 CLASSNAME the generated class is named accordingly
19205 NO_NAMESPACE the generated class is not wrapped in a namespace
19207 macro QT4_ADD_DBUS_INTERFACES(outfiles inputfile ... )
19209 Create the interface header and implementation files
19210 for all listed interface xml files.
19211 The basename will be automatically determined from the name
19212 of the xml file.
19213 The source file properties described for
19215 QT4_ADD_DBUS_INTERFACE also apply here.
19216 macro QT4_ADD_DBUS_ADAPTOR(outfiles xmlfile parentheader parentclassname
19218 [basename] [classname])
19219 create a dbus adaptor (header and implementation file) from the xml file
19220 describing the interface, and add it to the list of sources. The adaptor
19221 forwards the calls to a parent class, defined in parentheader and named
19222 parentclassname. The name of the generated files will be
19223 <basename>adaptor.{cpp,h} where basename defaults to the basename of the
19224 xml file.
19225 If <classname> is provided, then it will be used as the classname of the
19226 adaptor itself.
19227 macro QT4_GENERATE_DBUS_INTERFACE( header [interfacename] OPTIONS ...)
19229 generate the xml interface file from the given header.
19230 If the optional argument interfacename is omitted, the name of the
19231 interface file is constructed from the basename of the header with
19232 the suffix .xml appended.
19233 Options may be given to qdbuscpp2xml, such as those found when
19234 executing "qdbuscpp2xml --help"
19235 macro QT4_CREATE_TRANSLATION( qm_files directories ... sources ...
19237 ts_files ... OPTIONS ...)
19238 out: qm_files
19239 in: directories sources ts_files
19240 options: flags to pass to lupdate, such as -extensions to specify
19241 extensions for a directory scan.
19242 generates commands to create .ts (via lupdate) and .qm
19243 (via lrelease) - files from directories and/or sources. The ts files are
19244 created and/or updated in the source tree (unless given with full paths).
19245 The qm files are generated in the build tree.
19246 Updating the translations can be done by adding the qm_files
19247 to the source list of your library/executable, so they are
19248 always updated, or by adding a custom target to control when
19249 they get updated/generated.
19250 macro QT4_ADD_TRANSLATION( qm_files ts_files ... )
19252 out: qm_files
19253 in: ts_files
19254 generates commands to create .qm from .ts - files. The generated
19255 filenames can be found in qm_files. The ts_files
19256 must exist and are not updated in any way.
19257 macro QT4_AUTOMOC(sourcefile1 sourcefile2 ... [TARGET tgt])
19259 The qt4_automoc macro is obsolete. Use the CMAKE_AUTOMOC feature instead.
19260 This macro is still experimental.
19261 It can be used to have moc automatically handled.
19262 So if you have the files foo.h and foo.cpp, and in foo.h a
19263 a class uses the Q_OBJECT macro, moc has to run on it. If you don't
19264 want to use QT4_WRAP_CPP() (which is reliable and mature), you can insert
19265 #include "foo.moc"
19266 in foo.cpp and then give foo.cpp as argument to QT4_AUTOMOC(). This will
19267 scan all listed files at cmake-time for such included moc files and if it
19268 finds them cause a rule to be generated to run moc at build time on the
19269 accompanying header file foo.h.
19270 If a source file has the SKIP_AUTOMOC property set it will be ignored by
19271 this macro.
19272 If the <tgt> is specified, the INTERFACE_INCLUDE_DIRECTORIES and
19273 INTERFACE_COMPILE_DEFINITIONS from the <tgt> are passed to moc.
19274 function QT4_USE_MODULES( target [link_type] modules...)
19276 This function is obsolete. Use target_link_libraries with IMPORTED targets
19277 instead.
19278 Make <target> use the <modules> from Qt. Using a Qt module means
19279 to link to the library, add the relevant include directories for the
19280 module, and add the relevant compiler defines for using the module.
19281 Modules are roughly equivalent to components of Qt4, so usage would be
19282 something like:
19283 qt4_use_modules(myexe Core Gui Declarative)
19284 to use QtCore, QtGui and QtDeclarative. The optional <link_type> argument
19285 can be specified as either LINK_PUBLIC or LINK_PRIVATE to specify the
19286 same argument to the target_link_libraries call.
19287 IMPORTED Targets
19289 A particular Qt library may be used by using the corresponding IMPORTED
19290 target with the target_link_libraries() command:
19291 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
19293 Using a target in this way causes :cmake(1)` to use the appropriate in‐
19295 clude directories and compile definitions for the target when compiling
19296 myexe.
19297 Targets are aware of their dependencies, so for example it is not nec‐
19299 essary to list Qt4::QtCore if another Qt library is listed, and it is
19300 not necessary to list Qt4::QtGui if Qt4::QtDeclarative is listed. Tar‐
19301 gets may be tested for existence in the usual way with the if(TARGET)
19302 command.
19303 The Qt toolkit may contain both debug and release libraries. cmake(1)
19305 will choose the appropriate version based on the build configuration.
19306 Qt4::QtCore
19308 The QtCore target
19309 Qt4::QtGui
19311 The QtGui target
19312 Qt4::Qt3Support
19314 The Qt3Support target
19315 Qt4::QtAssistant
19317 The QtAssistant target
19318 Qt4::QtAssistantClient
19320 The QtAssistantClient target
19321 Qt4::QAxContainer
19323 The QAxContainer target (Windows only)
19324 Qt4::QAxServer
19326 The QAxServer target (Windows only)
19327 Qt4::QtDBus
19329 The QtDBus target
19330 Qt4::QtDeclarative
19332 The QtDeclarative target
19333 Qt4::QtDesigner
19335 The QtDesigner target
19336 Qt4::QtDesignerComponents
19338 The QtDesignerComponents target
19339 Qt4::QtHelp
19341 The QtHelp target
19342 Qt4::QtMotif
19344 The QtMotif target
19345 Qt4::QtMultimedia
19347 The QtMultimedia target
19348 Qt4::QtNetwork
19350 The QtNetwork target
19351 Qt4::QtNsPLugin
19353 The QtNsPLugin target
19354 Qt4::QtOpenGL
19356 The QtOpenGL target
19357 Qt4::QtScript
19359 The QtScript target
19360 Qt4::QtScriptTools
19362 The QtScriptTools target
19363 Qt4::QtSql
19365 The QtSql target
19366 Qt4::QtSvg
19368 The QtSvg target
19369 Qt4::QtTest
19371 The QtTest target
19372 Qt4::QtUiTools
19374 The QtUiTools target
19375 Qt4::QtWebKit
19377 The QtWebKit target
19378 Qt4::QtXml
19380 The QtXml target
19381 Qt4::QtXmlPatterns
19383 The QtXmlPatterns target
19384 Qt4::phonon
19386 The phonon target
19387 Result Variables
19389 Below is a detailed list of variables that FindQt4.cmake sets.
19390 Qt4_FOUND
19392 If false, don't try to use Qt 4.
19393 QT_FOUND
19395 If false, don't try to use Qt. This variable is for compatibil‐
19396 ity only.
19397 QT4_FOUND
19399 If false, don't try to use Qt 4. This variable is for compati‐
19400 bility only.
19401 QT_VERSION_MAJOR
19403 The major version of Qt found.
19404 QT_VERSION_MINOR
19406 The minor version of Qt found.
19407 QT_VERSION_PATCH
19409 The patch version of Qt found.
19410 FindQuickTime
19412 Locate QuickTime This module defines QUICKTIME_LIBRARY QUICKTIME_FOUND,
19413 if false, do not try to link to gdal QUICKTIME_INCLUDE_DIR, where to
19414 find the headers
19415 $QUICKTIME_DIR is an environment variable that would correspond to the
19417 ./configure --prefix=$QUICKTIME_DIR
19418 Created by Eric Wing.
19420 FindRTI
19422 Try to find M&S HLA RTI libraries
19423 This module finds if any HLA RTI is installed and locates the standard
19425 RTI include files and libraries.
19426 RTI is a simulation infrastructure standardized by IEEE and SISO. It
19428 has a well defined C++ API that assures that simulation applications
19429 are independent on a particular RTI implementation.
19430 http://en.wikipedia.org/wiki/Run-Time_Infrastructure_(simulation)
19432 This code sets the following variables:
19434 RTI_INCLUDE_DIR = the directory where RTI includes file are found
19436 RTI_LIBRARIES = The libraries to link against to use RTI
19437 RTI_DEFINITIONS = -DRTI_USES_STD_FSTREAM
19438 RTI_FOUND = Set to FALSE if any HLA RTI was not found
19439 Report problems to <certi-devel@nongnu.org>
19441 FindRuby
19443 Find Ruby
19444 This module finds if Ruby is installed and determines where the include
19446 files and libraries are. Ruby 1.8 through 3.1 are supported.
19447 The minimum required version of Ruby can be specified using the stan‐
19449 dard syntax, e.g.
19450 find_package(Ruby 2.5.1 EXACT REQUIRED)
19452 # OR
19453 find_package(Ruby 2.4)
19454 It also determines what the name of the library is.
19456 Virtual environments such as RVM are handled as well, by passing the
19458 argument Ruby_FIND_VIRTUALENV
19459 Result Variables
19461 This module will set the following variables in your project:
19462 Ruby_FOUND
19464 set to true if ruby was found successfully
19465 Ruby_EXECUTABLE
19467 full path to the ruby binary
19468 Ruby_INCLUDE_DIRS
19470 include dirs to be used when using the ruby library
19471 Ruby_LIBRARIES
19473 New in version 3.18: libraries needed to use ruby from C.
19474 Ruby_VERSION
19477 the version of ruby which was found, e.g. "1.8.7"
19478 Ruby_VERSION_MAJOR
19480 Ruby major version.
19481 Ruby_VERSION_MINOR
19483 Ruby minor version.
19484 Ruby_VERSION_PATCH
19486 Ruby patch version.
19487 Changed in version 3.18: Previous versions of CMake used the RUBY_ pre‐
19489 fix for all variables. The following variables are provided for com‐
19490 patibility reasons, don't use them in new code:
19491 RUBY_EXECUTABLE
19494 same as Ruby_EXECUTABLE.
19495 RUBY_INCLUDE_DIRS
19497 same as Ruby_INCLUDE_DIRS.
19498 RUBY_INCLUDE_PATH
19500 same as Ruby_INCLUDE_DIRS.
19501 RUBY_LIBRARY
19503 same as Ruby_LIBRARY.
19504 RUBY_VERSION
19506 same as Ruby_VERSION.
19507 RUBY_FOUND
19509 same as Ruby_FOUND.
19510 Hints
19512 New in version 3.18.
19513 Ruby_FIND_VIRTUALENV
19516 This variable defines the handling of virtual environments man‐
19517 aged by rvm. It is meaningful only when a virtual environment is
19518 active (i.e. the rvm script has been evaluated or at least the
19519 MY_RUBY_HOME environment variable is set). The Ruby_FIND_VIR‐
19520 TUALENV variable can be set to empty or one of the following:
19521 • FIRST: The virtual environment is used before any other stan‐
19523 dard paths to look-up for the interpreter. This is the de‐
19524 fault.
19525 • ONLY: Only the virtual environment is used to look-up for the
19527 interpreter.
19528 • STANDARD: The virtual environment is not used to look-up for
19530 the interpreter (assuming it isn't still in the PATH...)
19531 FindSDL
19533 Locate the SDL library
19534 Imported targets
19536 New in version 3.19.
19537 This module defines the following IMPORTED target:
19540 SDL::SDL
19542 The SDL library, if found
19543 Result variables
19545 This module will set the following variables in your project:
19546 SDL_INCLUDE_DIRS
19548 where to find SDL.h
19549 SDL_LIBRARIES
19551 the name of the library to link against
19552 SDL_FOUND
19554 if false, do not try to link to SDL
19555 SDL_VERSION
19557 the human-readable string containing the version of SDL if found
19558 SDL_VERSION_MAJOR
19560 SDL major version
19561 SDL_VERSION_MINOR
19563 SDL minor version
19564 SDL_VERSION_PATCH
19566 SDL patch version
19567 New in version 3.19: Added the SDL_INCLUDE_DIRS, SDL_LIBRARIES and
19569 SDL_VERSION[_<PART>] variables.
19570 Cache variables
19573 These variables may optionally be set to help this module find the cor‐
19574 rect files:
19575 SDL_INCLUDE_DIR
19577 where to find SDL.h
19578 SDL_LIBRARY
19580 the name of the library to link against
19581 Variables for locating SDL
19583 This module responds to the flag:
19584 SDL_BUILDING_LIBRARY
19586 If this is defined, then no SDL_main will be linked in because
19587 only applications need main(). Otherwise, it is assumed you are
19588 building an application and this module will attempt to locate
19589 and set the proper link flags as part of the returned SDL_LI‐
19590 BRARY variable.
19591 Obsolete variables
19593 Deprecated since version 3.19.
19594 These variables are obsolete and provided for backwards compatibility:
19597 SDL_VERSION_STRING
19599 the human-readable string containing the version of SDL if
19600 found. Identical to SDL_VERSION
19601 Don't forget to include SDLmain.h and SDLmain.m your project for the OS
19603 X framework based version. (Other versions link to -lSDLmain which
19604 this module will try to find on your behalf.) Also for OS X, this mod‐
19605 ule will automatically add the -framework Cocoa on your behalf.
19606 Additional Note: If you see an empty SDL_LIBRARY_TEMP in your configu‐
19608 ration and no SDL_LIBRARY, it means CMake did not find your SDL library
19609 (SDL.dll, libsdl.so, SDL.framework, etc). Set SDL_LIBRARY_TEMP to
19610 point to your SDL library, and configure again. Similarly, if you see
19611 an empty SDLMAIN_LIBRARY, you should set this value as appropriate.
19612 These values are used to generate the final SDL_LIBRARY variable, but
19613 when these values are unset, SDL_LIBRARY does not get created.
19614 $SDLDIR is an environment variable that would correspond to the ./con‐
19616 figure --prefix=$SDLDIR used in building SDL. l.e.galup 9-20-02
19617 On OSX, this will prefer the Framework version (if found) over others.
19619 People will have to manually change the cache values of SDL_LIBRARY to
19620 override this selection or set the CMake environment CMAKE_INCLUDE_PATH
19621 to modify the search paths.
19622 Note that the header path has changed from SDL/SDL.h to just SDL.h This
19624 needed to change because "proper" SDL convention is #include "SDL.h",
19625 not <SDL/SDL.h>. This is done for portability reasons because not all
19626 systems place things in SDL/ (see FreeBSD).
19627 FindSDL_image
19629 Locate SDL_image library
19630 This module defines:
19632 SDL_IMAGE_LIBRARIES, the name of the library to link against
19634 SDL_IMAGE_INCLUDE_DIRS, where to find the headers
19635 SDL_IMAGE_FOUND, if false, do not try to link against
19636 SDL_IMAGE_VERSION_STRING - human-readable string containing the
19637 version of SDL_image
19638 For backward compatibility the following variables are also set:
19640 SDLIMAGE_LIBRARY (same value as SDL_IMAGE_LIBRARIES)
19642 SDLIMAGE_INCLUDE_DIR (same value as SDL_IMAGE_INCLUDE_DIRS)
19643 SDLIMAGE_FOUND (same value as SDL_IMAGE_FOUND)
19644 $SDLDIR is an environment variable that would correspond to the ./con‐
19646 figure --prefix=$SDLDIR used in building SDL.
19647 FindSDL_gfx
19649 New in version 3.25.
19650 Locate SDL_gfx library
19653 This module defines:
19655 SDL::SDL_gfx, the name of the target to use with target_*() commands
19657 SDL_GFX_LIBRARIES, the name of the library to link against
19658 SDL_GFX_INCLUDE_DIRS, where to find the headers
19659 SDL_GFX_FOUND, if false, do not try to link against
19660 SDL_GFX_VERSION_STRING - human-readable string containing the
19661 version of SDL_gfx
19662 $SDLDIR is an environment variable that would correspond to the ./con‐
19664 figure --prefix=$SDLDIR used in building SDL.
19665 FindSDL_mixer
19667 Locate SDL_mixer library
19668 This module defines:
19670 SDL_MIXER_LIBRARIES, the name of the library to link against
19672 SDL_MIXER_INCLUDE_DIRS, where to find the headers
19673 SDL_MIXER_FOUND, if false, do not try to link against
19674 SDL_MIXER_VERSION_STRING - human-readable string containing the
19675 version of SDL_mixer
19676 For backward compatibility the following variables are also set:
19678 SDLMIXER_LIBRARY (same value as SDL_MIXER_LIBRARIES)
19680 SDLMIXER_INCLUDE_DIR (same value as SDL_MIXER_INCLUDE_DIRS)
19681 SDLMIXER_FOUND (same value as SDL_MIXER_FOUND)
19682 $SDLDIR is an environment variable that would correspond to the ./con‐
19684 figure --prefix=$SDLDIR used in building SDL.
19685 FindSDL_net
19687 Locate SDL_net library
19688 This module defines:
19690 SDL_NET_LIBRARIES, the name of the library to link against
19692 SDL_NET_INCLUDE_DIRS, where to find the headers
19693 SDL_NET_FOUND, if false, do not try to link against
19694 SDL_NET_VERSION_STRING - human-readable string containing the version of SDL_net
19695 For backward compatibility the following variables are also set:
19697 SDLNET_LIBRARY (same value as SDL_NET_LIBRARIES)
19699 SDLNET_INCLUDE_DIR (same value as SDL_NET_INCLUDE_DIRS)
19700 SDLNET_FOUND (same value as SDL_NET_FOUND)
19701 $SDLDIR is an environment variable that would correspond to the ./con‐
19703 figure --prefix=$SDLDIR used in building SDL.
19704 FindSDL_sound
19706 Locates the SDL_sound library
19707 This module depends on SDL being found and must be called AFTER Find‐
19709 SDL.cmake is called.
19710 This module defines
19712 SDL_SOUND_INCLUDE_DIR, where to find SDL_sound.h
19714 SDL_SOUND_FOUND, if false, do not try to link to SDL_sound
19715 SDL_SOUND_LIBRARIES, this contains the list of libraries that you need
19716 to link against.
19717 SDL_SOUND_EXTRAS, this is an optional variable for you to add your own
19718 flags to SDL_SOUND_LIBRARIES. This is prepended to SDL_SOUND_LIBRARIES.
19719 This is available mostly for cases this module failed to anticipate for
19720 and you must add additional flags. This is marked as ADVANCED.
19721 SDL_SOUND_VERSION_STRING, human-readable string containing the
19722 version of SDL_sound
19723 This module also defines (but you shouldn't need to use directly)
19725 SDL_SOUND_LIBRARY, the name of just the SDL_sound library you would link
19727 against. Use SDL_SOUND_LIBRARIES for you link instructions and not this one.
19728 And might define the following as needed
19730 MIKMOD_LIBRARY
19732 MODPLUG_LIBRARY
19733 OGG_LIBRARY
19734 VORBIS_LIBRARY
19735 SMPEG_LIBRARY
19736 FLAC_LIBRARY
19737 SPEEX_LIBRARY
19738 Typically, you should not use these variables directly, and you should
19740 use SDL_SOUND_LIBRARIES which contains SDL_SOUND_LIBRARY and the other
19741 audio libraries (if needed) to successfully compile on your system.
19742 Responds to the $SDLDIR and $SDLSOUNDDIR environmental variable that
19744 would correspond to the ./configure --prefix=$SDLDIR used in building
19745 SDL.
19746 On OSX, this will prefer the Framework version (if found) over others.
19748 People will have to manually change the cache values of SDL_LIBRARY to
19749 override this selectionor set the CMake environment CMAKE_INCLUDE_PATH
19750 to modify the search paths.
19751 FindSDL_ttf
19753 Locate SDL_ttf library
19754 This module defines:
19756 SDL_TTF_LIBRARIES, the name of the library to link against
19758 SDL_TTF_INCLUDE_DIRS, where to find the headers
19759 SDL_TTF_FOUND, if false, do not try to link against
19760 SDL_TTF_VERSION_STRING - human-readable string containing the version of SDL_ttf
19761 For backward compatibility the following variables are also set:
19763 SDLTTF_LIBRARY (same value as SDL_TTF_LIBRARIES)
19765 SDLTTF_INCLUDE_DIR (same value as SDL_TTF_INCLUDE_DIRS)
19766 SDLTTF_FOUND (same value as SDL_TTF_FOUND)
19767 $SDLDIR is an environment variable that would correspond to the ./con‐
19769 figure --prefix=$SDLDIR used in building SDL.
19770 FindSelfPackers
19772 Find upx
19773 This module looks for some executable packers (i.e. software that com‐
19775 press executables or shared libs into on-the-fly self-extracting exe‐
19776 cutables or shared libs. Examples:
19777 UPX: http://wildsau.idv.uni-linz.ac.at/mfx/upx.html
19779 FindSquish
19781 -- Typical Use
19782 This module can be used to find Squish.
19784 SQUISH_FOUND If false, don't try to use Squish
19786 SQUISH_VERSION The full version of Squish found
19787 SQUISH_VERSION_MAJOR The major version of Squish found
19788 SQUISH_VERSION_MINOR The minor version of Squish found
19789 SQUISH_VERSION_PATCH The patch version of Squish found
19790 SQUISH_INSTALL_DIR The Squish installation directory
19792 (containing bin, lib, etc)
19793 SQUISH_SERVER_EXECUTABLE The squishserver executable
19794 SQUISH_CLIENT_EXECUTABLE The squishrunner executable
19795 SQUISH_INSTALL_DIR_FOUND Was the install directory found?
19797 SQUISH_SERVER_EXECUTABLE_FOUND Was the server executable found?
19798 SQUISH_CLIENT_EXECUTABLE_FOUND Was the client executable found?
19799 It provides the function squish_add_test() for adding a squish test to
19801 cmake using Squish >= 4.x:
19802 squish_add_test(cmakeTestName
19804 AUT targetName SUITE suiteName TEST squishTestName
19805 [SETTINGSGROUP group] [PRE_COMMAND command] [POST_COMMAND command] )
19806 Changed in version 3.18: In previous CMake versions, this function was
19808 named squish_v4_add_test.
19809 The arguments have the following meaning:
19812 cmakeTestName
19814 this will be used as the first argument for add_test()
19815 AUT targetName
19817 the name of the cmake target which will be used as AUT, i.e. the
19818 executable which will be tested.
19819 SUITE suiteName
19821 this is either the full path to the squish suite, or just the
19822 last directory of the suite, i.e. the suite name. In this case
19823 the CMakeLists.txt which calls squish_add_test() must be located
19824 in the parent directory of the suite directory.
19825 TEST squishTestName
19827 the name of the squish test, i.e. the name of the subdirectory
19828 of the test inside the suite directory.
19829 SETTINGSGROUP group
19831 deprecated, this argument will be ignored.
19832 PRE_COMMAND command
19834 if specified, the given command will be executed before starting
19835 the squish test.
19836 POST_COMMAND command
19838 same as PRE_COMMAND, but after the squish test has been exe‐
19839 cuted.
19840 enable_testing()
19842 find_package(Squish 6.5)
19843 if (SQUISH_FOUND)
19844 squish_add_test(myTestName
19845 AUT myApp
19846 SUITE ${CMAKE_SOURCE_DIR}/tests/mySuite
19847 TEST someSquishTest
19848 )
19849 endif ()
19850 For users of Squish version 3.x the macro squish_v3_add_test() is pro‐
19852 vided:
19853 squish_v3_add_test(testName applicationUnderTest testCase envVars testWrapper)
19855 Use this macro to add a test using Squish 3.x.
19856 enable_testing()
19858 find_package(Squish 3.0)
19859 if (SQUISH_FOUND)
19860 squish_v3_add_test(myTestName myApplication testCase envVars testWrapper)
19861 endif ()
19862 FindSQLite3
19864 New in version 3.14.
19865 Find the SQLite libraries, v3
19868 IMPORTED targets
19870 This module defines the following IMPORTED target:
19871 SQLite::SQLite3
19873 Result variables
19875 This module will set the following variables if found:
19876 SQLite3_INCLUDE_DIRS
19878 where to find sqlite3.h, etc.
19879 SQLite3_LIBRARIES
19881 the libraries to link against to use SQLite3.
19882 SQLite3_VERSION
19884 version of the SQLite3 library found
19885 SQLite3_FOUND
19887 TRUE if found
19888 FindSubversion
19890 Extract information from a subversion working copy
19891 The module defines the following variables:
19893 Subversion_SVN_EXECUTABLE - path to svn command line client
19895 Subversion_VERSION_SVN - version of svn command line client
19896 Subversion_FOUND - true if the command line client was found
19897 SUBVERSION_FOUND - same as Subversion_FOUND, set for compatibility reasons
19898 The minimum required version of Subversion can be specified using the
19900 standard syntax, e.g. find_package(Subversion 1.4).
19901 If the command line client executable is found two macros are defined:
19903 Subversion_WC_INFO(<dir> <var-prefix> [IGNORE_SVN_FAILURE])
19905 Subversion_WC_LOG(<dir> <var-prefix>)
19906 Subversion_WC_INFO extracts information of a subversion working copy at
19908 a given location. This macro defines the following variables if run‐
19909 ning Subversion's info command on <dir> succeeds; otherwise a SEND_ER‐
19910 ROR message is generated.
19911 New in version 3.13: The error can be ignored by providing the IG‐
19913 NORE_SVN_FAILURE option, which causes these variables to remain unde‐
19914 fined.
19915 <var-prefix>_WC_URL - url of the repository (at <dir>)
19918 <var-prefix>_WC_ROOT - root url of the repository
19919 <var-prefix>_WC_REVISION - current revision
19920 <var-prefix>_WC_LAST_CHANGED_AUTHOR - author of last commit
19921 <var-prefix>_WC_LAST_CHANGED_DATE - date of last commit
19922 <var-prefix>_WC_LAST_CHANGED_REV - revision of last commit
19923 <var-prefix>_WC_INFO - output of command `svn info <dir>'
19924 Subversion_WC_LOG retrieves the log message of the base revision of a
19926 subversion working copy at a given location. This macro defines the
19927 variable:
19928 <var-prefix>_LAST_CHANGED_LOG - last log of base revision
19930 Example usage:
19932 find_package(Subversion)
19934 if(SUBVERSION_FOUND)
19935 Subversion_WC_INFO(${PROJECT_SOURCE_DIR} Project)
19936 message("Current revision is ${Project_WC_REVISION}")
19937 Subversion_WC_LOG(${PROJECT_SOURCE_DIR} Project)
19938 message("Last changed log is ${Project_LAST_CHANGED_LOG}")
19939 endif()
19940 FindSWIG
19942 Find the Simplified Wrapper and Interface Generator (SWIG) executable.
19943 This module finds an installed SWIG and determines its version.
19945 New in version 3.18: If a COMPONENTS or OPTIONAL_COMPONENTS argument is
19947 given to the find_package() command, it will also determine supported
19948 target languages.
19949 New in version 3.19: When a version is requested, it can be specified
19952 as a simple value or as a range. For a detailed description of version
19953 range usage and capabilities, refer to the find_package() command.
19954 The module defines the following variables:
19957 SWIG_FOUND
19959 Whether SWIG and any required components were found on the sys‐
19960 tem.
19961 SWIG_EXECUTABLE
19963 Path to the SWIG executable.
19964 SWIG_DIR
19966 Path to the installed SWIG Lib directory (result of swig
19967 -swiglib).
19968 SWIG_VERSION
19970 SWIG executable version (result of swig -version).
19971 SWIG_<lang>_FOUND
19973 If COMPONENTS or OPTIONAL_COMPONENTS are requested, each avail‐
19974 able target language <lang> (lowercase) will be set to TRUE.
19975 Any COMPONENTS given to find_package should be the names of supported
19977 target languages as provided to the LANGUAGE argument of swig_add_li‐
19978 brary, such as python or perl5. Language names must be lowercase.
19979 All information is collected from the SWIG_EXECUTABLE, so the version
19981 to be found can be changed from the command line by means of setting
19982 SWIG_EXECUTABLE.
19983 Example usage requiring SWIG 4.0 or higher and Python language support,
19985 with optional Fortran support:
19986 find_package(SWIG 4.0 COMPONENTS python OPTIONAL_COMPONENTS fortran)
19988 if(SWIG_FOUND)
19989 message("SWIG found: ${SWIG_EXECUTABLE}")
19990 if(NOT SWIG_fortran_FOUND)
19991 message(WARNING "SWIG Fortran bindings cannot be generated")
19992 endif()
19993 endif()
19994 FindTCL
19996 TK_INTERNAL_PATH was removed.
19997 This module finds if Tcl is installed and determines where the include
19999 files and libraries are. It also determines what the name of the li‐
20000 brary is. This code sets the following variables:
20001 TCL_FOUND = Tcl was found
20003 TK_FOUND = Tk was found
20004 TCLTK_FOUND = Tcl and Tk were found
20005 TCL_LIBRARY = path to Tcl library (tcl tcl80)
20006 TCL_INCLUDE_PATH = path to where tcl.h can be found
20007 TCL_TCLSH = path to tclsh binary (tcl tcl80)
20008 TK_LIBRARY = path to Tk library (tk tk80 etc)
20009 TK_INCLUDE_PATH = path to where tk.h can be found
20010 TK_WISH = full path to the wish executable
20011 In an effort to remove some clutter and clear up some issues for people
20013 who are not necessarily Tcl/Tk gurus/developers, some variables were
20014 moved or removed. Changes compared to CMake 2.4 are:
20015 => they were only useful for people writing Tcl/Tk extensions.
20017 => these libs are not packaged by default with Tcl/Tk distributions.
20018 Even when Tcl/Tk is built from source, several flavors of debug libs
20019 are created and there is no real reason to pick a single one
20020 specifically (say, amongst tcl84g, tcl84gs, or tcl84sgx).
20021 Let's leave that choice to the user by allowing him to assign
20022 TCL_LIBRARY to any Tcl library, debug or not.
20023 => this ended up being only a Win32 variable, and there is a lot of
20024 confusion regarding the location of this file in an installed Tcl/Tk
20025 tree anyway (see 8.5 for example). If you need the internal path at
20026 this point it is safer you ask directly where the *source* tree is
20027 and dig from there.
20028 FindTclsh
20030 Find tclsh
20031 This module finds if TCL is installed and determines where the include
20033 files and libraries are. It also determines what the name of the li‐
20034 brary is. This code sets the following variables:
20035 TCLSH_FOUND = TRUE if tclsh has been found
20037 TCL_TCLSH = the path to the tclsh executable
20038 FindTclStub
20040 TCL_STUB_LIBRARY_DEBUG and TK_STUB_LIBRARY_DEBUG were removed.
20041 This module finds Tcl stub libraries. It first finds Tcl include files
20043 and libraries by calling FindTCL.cmake. How to Use the Tcl Stubs Li‐
20044 brary:
20045 http://tcl.activestate.com/doc/howto/stubs.html
20047 Using Stub Libraries:
20049 http://safari.oreilly.com/0130385603/ch48lev1sec3
20051 This code sets the following variables:
20053 TCL_STUB_LIBRARY = path to Tcl stub library
20055 TK_STUB_LIBRARY = path to Tk stub library
20056 TTK_STUB_LIBRARY = path to ttk stub library
20057 In an effort to remove some clutter and clear up some issues for people
20059 who are not necessarily Tcl/Tk gurus/developers, some variables were
20060 moved or removed. Changes compared to CMake 2.4 are:
20061 => these libs are not packaged by default with Tcl/Tk distributions.
20063 Even when Tcl/Tk is built from source, several flavors of debug libs
20064 are created and there is no real reason to pick a single one
20065 specifically (say, amongst tclstub84g, tclstub84gs, or tclstub84sgx).
20066 Let's leave that choice to the user by allowing him to assign
20067 TCL_STUB_LIBRARY to any Tcl library, debug or not.
20068 FindThreads
20070 This module determines the thread library of the system.
20071 Imported Targets
20073 New in version 3.1.
20074 This module defines the following IMPORTED target:
20077 Threads::Threads
20079 The thread library, if found.
20080 Result Variables
20082 The following variables are set:
20083 Threads_FOUND
20085 If a supported thread library was found.
20086 CMAKE_THREAD_LIBS_INIT
20088 The thread library to use. This may be empty if the thread func‐
20089 tions are provided by the system libraries and no special flags
20090 are needed to use them.
20091 CMAKE_USE_WIN32_THREADS_INIT
20093 If the found thread library is the win32 one.
20094 CMAKE_USE_PTHREADS_INIT
20096 If the found thread library is pthread compatible.
20097 CMAKE_HP_PTHREADS_INIT
20099 If the found thread library is the HP thread library.
20100 Variables Affecting Behavior
20102 THREADS_PREFER_PTHREAD_FLAG
20103 New in version 3.1.
20104 If the use of the -pthread compiler and linker flag is preferred
20107 then the caller can set this variable to TRUE. The compiler flag
20108 can only be used with the imported target. Use of both the im‐
20109 ported target as well as this switch is highly recommended for
20110 new code.
20111 This variable has no effect if the system libraries provide the
20113 thread functions, i.e. when CMAKE_THREAD_LIBS_INIT will be
20114 empty.
20115 FindTIFF
20117 Find the TIFF library (libtiff, https://libtiff.gitlab.io/libtiff/).
20118 Optional COMPONENTS
20120 This module supports the optional component CXX, for use with the COM‐
20121 PONENTS argument of the find_package() command. This component has an
20122 associated imported target, as described below.
20123 Imported targets
20125 New in version 3.5.
20126 This module defines the following IMPORTED targets:
20129 TIFF::TIFF
20131 The TIFF library, if found.
20132 TIFF::CXX
20134 New in version 3.19.
20135 The C++ wrapper libtiffxx, if requested by the COMPONENTS CXX
20138 option, if the compiler is not MSVC (which includes the C++
20139 wrapper in libtiff), and if found.
20140 Result variables
20142 This module will set the following variables in your project:
20143 TIFF_FOUND
20145 true if the TIFF headers and libraries were found
20146 TIFF_INCLUDE_DIR
20148 the directory containing the TIFF headers
20149 TIFF_INCLUDE_DIRS
20151 the directory containing the TIFF headers
20152 TIFF_LIBRARIES
20154 TIFF libraries to be linked
20155 Cache variables
20157 The following cache variables may also be set:
20158 TIFF_INCLUDE_DIR
20160 the directory containing the TIFF headers
20161 TIFF_LIBRARY_RELEASE
20163 the path to the TIFF library for release configurations
20164 TIFF_LIBRARY_DEBUG
20166 the path to the TIFF library for debug configurations
20167 TIFFXX_LIBRARY_RELEASE
20169 the path to the TIFFXX library for release configurations
20170 TIFFXX_LIBRARY_DEBUG
20172 the path to the TIFFXX library for debug configurations
20173 New in version 3.4: Debug and Release variants are found separately.
20175 FindVulkan
20178 New in version 3.7.
20179 Find Vulkan, which is a low-overhead, cross-platform 3D graphics and
20182 computing API.
20183 Optional COMPONENTS
20185 New in version 3.24.
20186 This module respects several optional COMPONENTS. There are corre‐
20189 sponding imported targets for each of these.
20190 glslc The SPIR-V compiler.
20192 glslangValidator
20194 The glslangValidator tool.
20195 glslang
20197 The SPIR-V generator library.
20198 shaderc_combined
20200 The static library for Vulkan shader compilation.
20201 SPIRV-Tools
20203 Tools to process SPIR-V modules.
20204 MoltenVK
20206 On macOS, an additional component MoltenVK is available.
20207 dxc New in version 3.25.
20209 The DirectX Shader Compiler.
20212 The glslc and glslangValidator components are provided even if not ex‐
20214 plicitly requested (for backward compatibility).
20215 IMPORTED Targets
20217 This module defines IMPORTED targets if Vulkan has been found:
20218 Vulkan::Vulkan
20220 The main Vulkan library.
20221 Vulkan::glslc
20223 New in version 3.19.
20224 The GLSLC SPIR-V compiler, if it has been found.
20227 Vulkan::Headers
20229 New in version 3.21.
20230 Provides just Vulkan headers include paths, if found. No li‐
20233 brary is included in this target. This can be useful for appli‐
20234 cations that load Vulkan library dynamically.
20235 Vulkan::glslangValidator
20237 New in version 3.21.
20238 The glslangValidator tool, if found. It is used to compile GLSL
20241 and HLSL shaders into SPIR-V.
20242 Vulkan::glslang
20244 New in version 3.24.
20245 Defined if SDK has the Khronos-reference front-end shader parser
20248 and SPIR-V generator library (glslang).
20249 Vulkan::shaderc_combined
20251 New in version 3.24.
20252 Defined if SDK has the Google static library for Vulkan shader
20255 compilation (shaderc_combined).
20256 Vulkan::SPIRV-Tools
20258 New in version 3.24.
20259 Defined if SDK has the Khronos library to process SPIR-V modules
20262 (SPIRV-Tools).
20263 Vulkan::MoltenVK
20265 New in version 3.24.
20266 Defined if SDK has the Khronos library which implement a subset
20269 of Vulkan API over Apple Metal graphics framework. (MoltenVK).
20270 Vulkan::volk
20272 New in version 3.25.
20273 Defined if SDK has the Vulkan meta-loader (volk).
20276 Vulkan::dxc_lib
20278 New in version 3.25.
20279 Defined if SDK has the DirectX shader compiler library.
20282 Vulkan::dxc_exe
20284 New in version 3.25.
20285 Defined if SDK has the DirectX shader compiler CLI tool.
20288 Result Variables
20290 This module defines the following variables:
20291 Vulkan_FOUND
20293 set to true if Vulkan was found
20294 Vulkan_INCLUDE_DIRS
20296 include directories for Vulkan
20297 Vulkan_LIBRARIES
20299 link against this library to use Vulkan
20300 Vulkan_VERSION
20302 New in version 3.23.
20303 value from vulkan/vulkan_core.h
20306 Vulkan_glslc_FOUND
20308 New in version 3.24.
20309 True, if the SDK has the glslc executable.
20312 Vulkan_glslangValidator_FOUND
20314 New in version 3.24.
20315 True, if the SDK has the glslangValidator executable.
20318 Vulkan_glslang_FOUND
20320 New in version 3.24.
20321 True, if the SDK has the glslang library.
20324 Vulkan_shaderc_combined_FOUND
20326 New in version 3.24.
20327 True, if the SDK has the shaderc_combined library.
20330 Vulkan_SPIRV-Tools_FOUND
20332 New in version 3.24.
20333 True, if the SDK has the SPIRV-Tools library.
20336 Vulkan_MoltenVK_FOUND
20338 New in version 3.24.
20339 True, if the SDK has the MoltenVK library.
20342 Vulkan_volk_FOUND
20344 New in version 3.25.
20345 True, if the SDK has the volk library.
20348 Vulkan_dxc_lib_FOUND
20350 New in version 3.25.
20351 True, if the SDK has the DirectX shader compiler library.
20354 Vulkan_dxc_exe_FOUND
20356 New in version 3.25.
20357 True, if the SDK has the DirectX shader compiler CLI tool.
20360 The module will also defines these cache variables:
20362 Vulkan_INCLUDE_DIR
20364 the Vulkan include directory
20365 Vulkan_LIBRARY
20367 the path to the Vulkan library
20368 Vulkan_GLSLC_EXECUTABLE
20370 the path to the GLSL SPIR-V compiler
20371 Vulkan_GLSLANG_VALIDATOR_EXECUTABLE
20373 the path to the glslangValidator tool
20374 Vulkan_glslang_LIBRARY
20376 New in version 3.24.
20377 Path to the glslang library.
20380 Vulkan_shaderc_combined_LIBRARY
20382 New in version 3.24.
20383 Path to the shaderc_combined library.
20386 Vulkan_SPIRV-Tools_LIBRARY
20388 New in version 3.24.
20389 Path to the SPIRV-Tools library.
20392 Vulkan_MoltenVK_LIBRARY
20394 New in version 3.24.
20395 Path to the MoltenVK library.
20398 Vulkan_volk_LIBRARY
20400 New in version 3.25.
20401 Path to the volk library.
20404 Vulkan_dxc_LIBRARY
20406 New in version 3.25.
20407 Path to the DirectX shader compiler library.
20410 Vulkan_dxc_EXECUTABLE
20412 New in version 3.25.
20413 Path to the DirectX shader compiler CLI tool.
20416 Hints
20418 New in version 3.18.
20419 The VULKAN_SDK environment variable optionally specifies the location
20422 of the Vulkan SDK root directory for the given architecture. It is typ‐
20423 ically set by sourcing the toplevel setup-env.sh script of the Vulkan
20424 SDK directory into the shell environment.
20425 FindWget
20427 Find wget
20428 This module looks for wget. This module defines the following values:
20430 WGET_EXECUTABLE: the full path to the wget tool.
20432 WGET_FOUND: True if wget has been found.
20433 FindWish
20435 Find wish installation
20436 This module finds if TCL is installed and determines where the include
20438 files and libraries are. It also determines what the name of the li‐
20439 brary is. This code sets the following variables:
20440 TK_WISH = the path to the wish executable
20442 if UNIX is defined, then it will look for the cygwin version first
20444 FindwxWidgets
20446 Find a wxWidgets (a.k.a., wxWindows) installation.
20447 This module finds if wxWidgets is installed and selects a default con‐
20449 figuration to use. wxWidgets is a modular library. To specify the
20450 modules that you will use, you need to name them as components to the
20451 package:
20452 find_package(wxWidgets COMPONENTS core base ... OPTIONAL_COMPONENTS net
20454 ...)
20455 New in version 3.4: Support for find_package() version argument; web‐
20457 view component.
20458 New in version 3.14: OPTIONAL_COMPONENTS support.
20461 There are two search branches: a windows style and a unix style. For
20464 windows, the following variables are searched for and set to defaults
20465 in case of multiple choices. Change them if the defaults are not de‐
20466 sired (i.e., these are the only variables you should change to select a
20467 configuration):
20468 wxWidgets_ROOT_DIR - Base wxWidgets directory
20470 (e.g., C:/wxWidgets-3.2.0).
20471 wxWidgets_LIB_DIR - Path to wxWidgets libraries
20472 (e.g., C:/wxWidgets-3.2.0/lib/vc_x64_lib).
20473 wxWidgets_CONFIGURATION - Configuration to use
20474 (e.g., msw, mswd, mswu, mswunivud, etc.)
20475 wxWidgets_EXCLUDE_COMMON_LIBRARIES
20476 - Set to TRUE to exclude linking of
20477 commonly required libs (e.g., png tiff
20478 jpeg zlib regex expat).
20479 For unix style it uses the wx-config utility. You can select between
20481 debug/release, unicode/ansi, universal/non-universal, and static/shared
20482 in the QtDialog or ccmake interfaces by turning ON/OFF the following
20483 variables:
20484 wxWidgets_USE_DEBUG
20486 wxWidgets_USE_UNICODE
20487 wxWidgets_USE_UNIVERSAL
20488 wxWidgets_USE_STATIC
20489 There is also a wxWidgets_CONFIG_OPTIONS variable for all other options
20491 that need to be passed to the wx-config utility. For example, to use
20492 the base toolkit found in the /usr/local path, set the variable (before
20493 calling the FIND_PACKAGE command) as such:
20494 set(wxWidgets_CONFIG_OPTIONS --toolkit=base --prefix=/usr)
20496 The following are set after the configuration is done for both windows
20498 and unix style:
20499 wxWidgets_FOUND - Set to TRUE if wxWidgets was found.
20501 wxWidgets_INCLUDE_DIRS - Include directories for WIN32
20502 i.e., where to find "wx/wx.h" and
20503 "wx/setup.h"; possibly empty for unices.
20504 wxWidgets_LIBRARIES - Path to the wxWidgets libraries.
20505 wxWidgets_LIBRARY_DIRS - compile time link dirs, useful for
20506 rpath on UNIX. Typically an empty string
20507 in WIN32 environment.
20508 wxWidgets_DEFINITIONS - Contains defines required to compile/link
20509 against WX, e.g. WXUSINGDLL
20510 wxWidgets_DEFINITIONS_DEBUG- Contains defines required to compile/link
20511 against WX debug builds, e.g. __WXDEBUG__
20512 wxWidgets_CXX_FLAGS - Include dirs and compiler flags for
20513 unices, empty on WIN32. Essentially
20514 "`wx-config --cxxflags`".
20515 wxWidgets_USE_FILE - Convenience include file.
20516 New in version 3.11: The following environment variables can be used as
20518 hints: WX_CONFIG, WXRC_CMD.
20519 Sample usage:
20522 # Note that for MinGW users the order of libs is important!
20524 find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net)
20525 if(wxWidgets_FOUND)
20526 include(${wxWidgets_USE_FILE})
20527 # and for each of your dependent executable/library targets:
20528 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
20529 endif()
20530 If wxWidgets is required (i.e., not an optional part):
20532 find_package(wxWidgets REQUIRED gl core base OPTIONAL_COMPONENTS net)
20534 include(${wxWidgets_USE_FILE})
20535 # and for each of your dependent executable/library targets:
20536 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
20537 Imported targets
20539 New in version 3.27.
20540 This module defines the following IMPORTED targets:
20543 wxWidgets::wxWidgets
20545 An interface library providing usage requirements for the found
20546 components.
20547 FindX11
20549 Find X11 installation
20550 Try to find X11 on UNIX systems. The following values are defined
20552 X11_FOUND - True if X11 is available
20554 X11_INCLUDE_DIR - include directories to use X11
20555 X11_LIBRARIES - link against these to use X11
20556 and also the following more fine grained variables and targets:
20558 New in version 3.14: Imported targets.
20560 X11_ICE_INCLUDE_PATH, X11_ICE_LIB, X11_ICE_FOUND, X11::ICE
20563 X11_SM_INCLUDE_PATH, X11_SM_LIB, X11_SM_FOUND, X11::SM
20564 X11_X11_INCLUDE_PATH, X11_X11_LIB, X11::X11
20565 X11_Xaccessrules_INCLUDE_PATH,
20566 X11_Xaccessstr_INCLUDE_PATH, X11_Xaccess_FOUND
20567 X11_Xau_INCLUDE_PATH, X11_Xau_LIB, X11_Xau_FOUND, X11::Xau
20568 X11_xcb_INCLUDE_PATH, X11_xcb_LIB, X11_xcb_FOUND, X11::xcb
20569 X11_X11_xcb_INCLUDE_PATH, X11_X11_xcb_LIB, X11_X11_xcb_FOUND, X11::X11_xcb
20570 X11_xcb_composite_INCLUDE_PATH, X11_xcb_composite_LIB, X11_xcb_composite_FOUND, X11::xcb_composite
20571 X11_xcb_cursor_INCLUDE_PATH, X11_xcb_cursor_LIB, X11_xcb_cursor_FOUND, X11::xcb_cursor
20572 X11_xcb_damage_INCLUDE_PATH, X11_xcb_damage_LIB, X11_xcb_damage_FOUND, X11::xcb_damage
20573 X11_xcb_dpms_INCLUDE_PATH, X11_xcb_dpms_LIB, X11_xcb_dpms_FOUND, X11::xcb_dpms
20574 X11_xcb_dri2_INCLUDE_PATH, X11_xcb_dri2_LIB, X11_xcb_dri2_FOUND, X11::xcb_dri2
20575 X11_xcb_dri3_INCLUDE_PATH, X11_xcb_dri3_LIB, X11_xcb_dri3_FOUND, X11::xcb_dri3
20576 X11_xcb_errors_INCLUDE_PATH, X11_xcb_errors_LIB, X11_xcb_errors_FOUND, X11::xcb_errors
20577 X11_xcb_ewmh_INCLUDE_PATH, X11_xcb_ewmh_LIB, X11_xcb_ewmh_FOUND, X11::xcb_ewmh
20578 X11_xcb_glx_INCLUDE_PATH, X11_xcb_glx_LIB, X11_xcb_glx_FOUND, X11::xcb_glx
20579 X11_xcb_icccm_INCLUDE_PATH, X11_xcb_icccm_LIB, X11_xcb_icccm_FOUND, X11::xcb_icccm
20580 X11_xcb_image_INCLUDE_PATH, X11_xcb_image_LIB, X11_xcb_image_FOUND, X11::xcb_image
20581 X11_xcb_keysyms_INCLUDE_PATH, X11_xcb_keysyms_LIB, X11_xcb_keysyms_FOUND, X11::xcb_keysyms
20582 X11_xcb_present_INCLUDE_PATH, X11_xcb_present_LIB, X11_xcb_present_FOUND, X11::xcb_present
20583 X11_xcb_randr_INCLUDE_PATH, X11_xcb_randr_LIB, X11_xcb_randr_FOUND, X11::xcb_randr
20584 X11_xcb_record_INCLUDE_PATH, X11_xcb_record_LIB, X11_xcb_record_FOUND, X11::xcb_record
20585 X11_xcb_render_INCLUDE_PATH, X11_xcb_render_LIB, X11_xcb_render_FOUND, X11::xcb_render
20586 X11_xcb_render_util_INCLUDE_PATH,X11_xcb_render_util_LIB,X11_xcb_render_util_FOUND,X11::xcb_render_util
20587 X11_xcb_res_INCLUDE_PATH, X11_xcb_res_LIB, X11_xcb_res_FOUND, X11::xcb_res
20588 X11_xcb_screensaver_INCLUDE_PATH,X11_xcb_screensaver_LIB,X11_xcb_screensaver_FOUND,X11::xcb_screensaver
20589 X11_xcb_shape_INCLUDE_PATH, X11_xcb_shape_LIB, X11_xcb_shape_FOUND, X11::xcb_shape
20590 X11_xcb_shm_INCLUDE_PATH, X11_xcb_shm_LIB, X11_xcb_shm_FOUND, X11::xcb_shm
20591 X11_xcb_sync_INCLUDE_PATH, X11_xcb_sync_LIB, X11_xcb_sync_FOUND, X11::xcb_sync
20592 X11_xcb_util_INCLUDE_PATH, X11_xcb_util_LIB, X11_xcb_util_FOUND, X11::xcb_util
20593 X11_xcb_xf86dri_INCLUDE_PATH, X11_xcb_xf86dri_LIB, X11_xcb_xf86dri_FOUND, X11::xcb_xf86dri
20594 X11_xcb_xfixes_INCLUDE_PATH, X11_xcb_xfixes_LIB, X11_xcb_xfixes_FOUND, X11::xcb_xfixes
20595 X11_xcb_xinerama_INCLUDE_PATH, X11_xcb_xinerama_LIB, X11_xcb_xinerama_FOUND, X11::xcb_xinerama
20596 X11_xcb_xinput_INCLUDE_PATH, X11_xcb_xinput_LIB, X11_xcb_xinput_FOUND, X11::xcb_xinput
20597 X11_xcb_xkb_INCLUDE_PATH, X11_xcb_xkb_LIB, X11_xcb_xkb_FOUND, X11::xcb_xkb
20598 X11_xcb_xrm_INCLUDE_PATH, X11_xcb_xrm_LIB, X11_xcb_xrm_FOUND, X11::xcb_xrm
20599 X11_xcb_xtest_INCLUDE_PATH, X11_xcb_xtest_LIB, X11_xcb_xtest_FOUND, X11::xcb_xtest
20600 X11_xcb_xvmc_INCLUDE_PATH, X11_xcb_xvmc_LIB, X11_xcb_xvmc_FOUND, X11::xcb_xvmc
20601 X11_xcb_xv_INCLUDE_PATH, X11_xcb_xv_LIB, X11_xcb_xv_FOUND X11::xcb_xv
20602 X11_Xcomposite_INCLUDE_PATH, X11_Xcomposite_LIB, X11_Xcomposite_FOUND, X11::Xcomposite
20603 X11_Xcursor_INCLUDE_PATH, X11_Xcursor_LIB, X11_Xcursor_FOUND, X11::Xcursor
20604 X11_Xdamage_INCLUDE_PATH, X11_Xdamage_LIB, X11_Xdamage_FOUND, X11::Xdamage
20605 X11_Xdmcp_INCLUDE_PATH, X11_Xdmcp_LIB, X11_Xdmcp_FOUND, X11::Xdmcp
20606 X11_Xext_INCLUDE_PATH, X11_Xext_LIB, X11_Xext_FOUND, X11::Xext
20607 X11_Xxf86misc_INCLUDE_PATH, X11_Xxf86misc_LIB, X11_Xxf86misc_FOUND, X11::Xxf86misc
20608 X11_Xxf86vm_INCLUDE_PATH, X11_Xxf86vm_LIB X11_Xxf86vm_FOUND, X11::Xxf86vm
20609 X11_Xfixes_INCLUDE_PATH, X11_Xfixes_LIB, X11_Xfixes_FOUND, X11::Xfixes
20610 X11_Xft_INCLUDE_PATH, X11_Xft_LIB, X11_Xft_FOUND, X11::Xft
20611 X11_Xi_INCLUDE_PATH, X11_Xi_LIB, X11_Xi_FOUND, X11::Xi
20612 X11_Xinerama_INCLUDE_PATH, X11_Xinerama_LIB, X11_Xinerama_FOUND, X11::Xinerama
20613 X11_Xkb_INCLUDE_PATH,
20614 X11_Xkblib_INCLUDE_PATH, X11_Xkb_FOUND, X11::Xkb
20615 X11_xkbcommon_INCLUDE_PATH, X11_xkbcommon_LIB, X11_xkbcommon_FOUND, X11::xkbcommon
20616 X11_xkbcommon_X11_INCLUDE_PATH, X11_xkbcommon_X11_LIB, X11_xkbcommon_X11_FOUND, X11::xkbcommon_X11
20617 X11_xkbfile_INCLUDE_PATH, X11_xkbfile_LIB, X11_xkbfile_FOUND, X11::xkbfile
20618 X11_Xmu_INCLUDE_PATH, X11_Xmu_LIB, X11_Xmu_FOUND, X11::Xmu
20619 X11_Xpm_INCLUDE_PATH, X11_Xpm_LIB, X11_Xpm_FOUND, X11::Xpm
20620 X11_Xtst_INCLUDE_PATH, X11_Xtst_LIB, X11_Xtst_FOUND, X11::Xtst
20621 X11_Xrandr_INCLUDE_PATH, X11_Xrandr_LIB, X11_Xrandr_FOUND, X11::Xrandr
20622 X11_Xrender_INCLUDE_PATH, X11_Xrender_LIB, X11_Xrender_FOUND, X11::Xrender
20623 X11_XRes_INCLUDE_PATH, X11_XRes_LIB, X11_XRes_FOUND, X11::XRes
20624 X11_Xss_INCLUDE_PATH, X11_Xss_LIB, X11_Xss_FOUND, X11::Xss
20625 X11_Xt_INCLUDE_PATH, X11_Xt_LIB, X11_Xt_FOUND, X11::Xt
20626 X11_Xutil_INCLUDE_PATH, X11_Xutil_FOUND, X11::Xutil
20627 X11_Xv_INCLUDE_PATH, X11_Xv_LIB, X11_Xv_FOUND, X11::Xv
20628 X11_dpms_INCLUDE_PATH, (in X11_Xext_LIB), X11_dpms_FOUND
20629 X11_XShm_INCLUDE_PATH, (in X11_Xext_LIB), X11_XShm_FOUND
20630 X11_Xshape_INCLUDE_PATH, (in X11_Xext_LIB), X11_Xshape_FOUND
20631 X11_XSync_INCLUDE_PATH, (in X11_Xext_LIB), X11_XSync_FOUND
20632 X11_Xaw_INCLUDE_PATH, X11_Xaw_LIB X11_Xaw_FOUND X11::Xaw
20633 New in version 3.14: Renamed Xxf86misc, X11_Xxf86misc, X11_Xxf86vm,
20635 X11_xkbfile, X11_Xtst, and X11_Xss libraries to match their file names.
20636 Deprecated the X11_Xinput library. Old names are still available for
20637 compatibility.
20638 New in version 3.14: Added the X11_Xext_INCLUDE_PATH variable.
20641 New in version 3.18: Added the xcb, X11-xcb, xcb-icccm, xcb-xkb, xkb‐
20644 common, and xkbcommon-X11 libraries.
20645 New in version 3.19: Added the Xaw, xcb_util, and xcb_xfixes libraries.
20648 New in version 3.24: Added the xcb_randr, xcb_xtext, and xcb_keysyms
20651 libraries.
20652 New in version 3.27: Added the xcb_composite, xcb_cursor, xcb_damage,
20655 xcb_dpms, xcb_dri2, xcb_dri3, xcb_errors, xcb_ewmh, xcb_glx, xcb_image,
20656 xcb_present, xcb_record, xcb_render, xcb_render_util, xcb_res,
20657 xcb_screensaver, xcb_shape, xcb_shm, xcb_sync, xcb_xf86dri, xcb_xin‐
20658 erama, xcb_xinput, xcb_xrm, xcb_xvmc, and xcb_xv libraries.
20659 FindXalanC
20662 New in version 3.5.
20663 Find the Apache Xalan-C++ XSL transform processor headers and li‐
20666 braries.
20667 Imported targets
20669 This module defines the following IMPORTED targets:
20670 XalanC::XalanC
20672 The Xalan-C++ xalan-c library, if found.
20673 Result variables
20675 This module will set the following variables in your project:
20676 XalanC_FOUND
20678 true if the Xalan headers and libraries were found
20679 XalanC_VERSION
20681 Xalan release version
20682 XalanC_INCLUDE_DIRS
20684 the directory containing the Xalan headers; note XercesC_IN‐
20685 CLUDE_DIRS is also required
20686 XalanC_LIBRARIES
20688 Xalan libraries to be linked; note XercesC_LIBRARIES is also re‐
20689 quired
20690 Cache variables
20692 The following cache variables may also be set:
20693 XalanC_INCLUDE_DIR
20695 the directory containing the Xalan headers
20696 XalanC_LIBRARY
20698 the Xalan library
20699 FindXCTest
20701 New in version 3.3.
20702 Functions to help creating and executing XCTest bundles.
20705 An XCTest bundle is a CFBundle with a special product-type and bundle
20707 extension. The Mac Developer Library provides more information in the
20708 Testing with Xcode document.
20709 Module Functions
20711 xctest_add_bundle
20712 The xctest_add_bundle function creates a XCTest bundle named
20713 <target> which will test the target <testee>. Supported target
20714 types for testee are Frameworks and App Bundles:
20715 xctest_add_bundle(
20717 <target> # Name of the XCTest bundle
20718 <testee> # Target name of the testee
20719 )
20720 xctest_add_test
20722 The xctest_add_test function adds an XCTest bundle to the
20723 project to be run by ctest(1). The test will be named <name> and
20724 tests <bundle>:
20725 xctest_add_test(
20727 <name> # Test name
20728 <bundle> # Target name of XCTest bundle
20729 )
20730 Module Variables
20732 The following variables are set by including this module:
20733 XCTest_FOUND
20735 True if the XCTest Framework and executable were found.
20736 XCTest_EXECUTABLE
20738 The path to the xctest command line tool used to execute XCTest
20739 bundles.
20740 XCTest_INCLUDE_DIRS
20742 The directory containing the XCTest Framework headers.
20743 XCTest_LIBRARIES
20745 The location of the XCTest Framework.
20746 FindXercesC
20748 New in version 3.1.
20749 Find the Apache Xerces-C++ validating XML parser headers and libraries.
20752 Imported targets
20754 New in version 3.5.
20755 This module defines the following IMPORTED targets:
20758 XercesC::XercesC
20760 The Xerces-C++ xerces-c library, if found.
20761 Result variables
20763 This module will set the following variables in your project:
20764 XercesC_FOUND
20766 true if the Xerces headers and libraries were found
20767 XercesC_VERSION
20769 Xerces release version
20770 XercesC_INCLUDE_DIRS
20772 the directory containing the Xerces headers
20773 XercesC_LIBRARIES
20775 Xerces libraries to be linked
20776 Cache variables
20778 The following cache variables may also be set:
20779 XercesC_INCLUDE_DIR
20781 the directory containing the Xerces headers
20782 XercesC_LIBRARY
20784 the Xerces library
20785 New in version 3.4: Debug and Release variants are found separately.
20787 FindXMLRPC
20790 Find xmlrpc
20791 Find the native XMLRPC headers and libraries.
20793 XMLRPC_INCLUDE_DIRS - where to find xmlrpc.h, etc.
20795 XMLRPC_LIBRARIES - List of libraries when using xmlrpc.
20796 XMLRPC_FOUND - True if xmlrpc found.
20797 XMLRPC modules may be specified as components for this find module.
20799 Modules may be listed by running "xmlrpc-c-config". Modules include:
20800 c++ C++ wrapper code
20802 libwww-client libwww-based client
20803 cgi-server CGI-based server
20804 abyss-server ABYSS-based server
20805 Typical usage:
20807 find_package(XMLRPC REQUIRED libwww-client)
20809 FindZLIB
20811 Find the native ZLIB includes and library.
20812 IMPORTED Targets
20814 New in version 3.1.
20815 This module defines IMPORTED target ZLIB::ZLIB, if ZLIB has been found.
20818 Result Variables
20820 This module defines the following variables:
20821 ZLIB_INCLUDE_DIRS
20823 where to find zlib.h, etc.
20824 ZLIB_LIBRARIES
20826 List of libraries when using zlib.
20827 ZLIB_FOUND
20829 True if zlib found.
20830 ZLIB_VERSION
20832 New in version 3.26: the version of Zlib found.
20833 See also legacy variable ZLIB_VERSION_STRING.
20836 New in version 3.4: Debug and Release variants are found separately.
20838 Legacy Variables
20841 The following variables are provided for backward compatibility:
20842 ZLIB_VERSION_MAJOR
20844 The major version of zlib.
20845 Changed in version 3.26: Superseded by ZLIB_VERSION.
20847 ZLIB_VERSION_MINOR
20850 The minor version of zlib.
20851 Changed in version 3.26: Superseded by ZLIB_VERSION.
20853 ZLIB_VERSION_PATCH
20856 The patch version of zlib.
20857 Changed in version 3.26: Superseded by ZLIB_VERSION.
20859 ZLIB_VERSION_TWEAK
20862 The tweak version of zlib.
20863 Changed in version 3.26: Superseded by ZLIB_VERSION.
20865 ZLIB_VERSION_STRING
20868 The version of zlib found (x.y.z)
20869 Changed in version 3.26: Superseded by ZLIB_VERSION.
20871 ZLIB_MAJOR_VERSION
20874 The major version of zlib. Superseded by ZLIB_VERSION_MAJOR.
20875 ZLIB_MINOR_VERSION
20877 The minor version of zlib. Superseded by ZLIB_VERSION_MINOR.
20878 ZLIB_PATCH_VERSION
20880 The patch version of zlib. Superseded by ZLIB_VERSION_PATCH.
20881 Hints
20883 A user may set ZLIB_ROOT to a zlib installation root to tell this mod‐
20884 ule where to look.
20885 New in version 3.24: Set ZLIB_USE_STATIC_LIBS to ON to look for static
20887 libraries. Default is OFF.
20888
20891 Deprecated Utility Modules
20892 AddFileDependencies
20893 Deprecated since version 3.20.
20894 Add dependencies to a source file.
20897 add_file_dependencies(<source> <files>...)
20899 Adds the given <files> to the dependencies of file <source>.
20901 Do not use this command in new code. It is just a wrapper around:
20903 set_property(SOURCE <source> APPEND PROPERTY OBJECT_DEPENDS <files>...)
20905 Instead use the set_property() command to append to the OBJECT_DEPENDS
20907 source file property directly.
20908 CMakeDetermineVSServicePack
20910 Deprecated since version 3.0: Do not use.
20911 The functionality of this module has been superseded by the
20914 CMAKE_<LANG>_COMPILER_VERSION variable that contains the compiler ver‐
20915 sion number.
20916 Determine the Visual Studio service pack of the 'cl' in use.
20918 Usage:
20920 if(MSVC)
20922 include(CMakeDetermineVSServicePack)
20923 DetermineVSServicePack( my_service_pack )
20924 if( my_service_pack )
20925 message(STATUS "Detected: ${my_service_pack}")
20926 endif()
20927 endif()
20928 Function DetermineVSServicePack sets the given variable to one of the
20930 following values or an empty string if unknown:
20931 vc80, vc80sp1
20933 vc90, vc90sp1
20934 vc100, vc100sp1
20935 vc110, vc110sp1, vc110sp2, vc110sp3, vc110sp4
20936 CMakeExpandImportedTargets
20938 Deprecated since version 3.4: Do not use.
20939 This module was once needed to expand imported targets to the underly‐
20942 ing libraries they reference on disk for use with the try_compile() and
20943 try_run() commands. These commands now support imported libraries in
20944 their LINK_LIBRARIES options (since CMake 2.8.11 for try_compile() and
20945 since CMake 3.2 for try_run()).
20946 This module does not support the policy CMP0022 NEW behavior or use of
20948 the INTERFACE_LINK_LIBRARIES property because generator expressions
20949 cannot be evaluated during configuration.
20950 CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
20952 [CONFIGURATION <config>])
20953 CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces
20955 all imported targets contained in this list with their actual file
20956 paths of the referenced libraries on disk, including the libraries from
20957 their link interfaces. If a CONFIGURATION is given, it uses the re‐
20958 spective configuration of the imported targets if it exists. If no
20959 CONFIGURATION is given, it uses the first configuration from
20960 ${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}.
20961 cmake_expand_imported_targets(expandedLibs
20963 LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
20964 CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
20965 CMakeForceCompiler
20967 Deprecated since version 3.6: Do not use.
20968 The macros provided by this module were once intended for use by
20971 cross-compiling toolchain files when CMake was not able to automati‐
20972 cally detect the compiler identification. Since the introduction of
20973 this module, CMake's compiler identification capabilities have improved
20974 and can now be taught to recognize any compiler. Furthermore, the
20975 suite of information CMake detects from a compiler is now too extensive
20976 to be provided by toolchain files using these macros.
20977 One common use case for this module was to skip CMake's checks for a
20979 working compiler when using a cross-compiler that cannot link binaries
20980 without special flags or custom linker scripts. This case is now sup‐
20981 ported by setting the CMAKE_TRY_COMPILE_TARGET_TYPE variable in the
20982 toolchain file instead.
20983 ----
20986 Macro CMAKE_FORCE_C_COMPILER has the following signature:
20990 CMAKE_FORCE_C_COMPILER(<compiler> <compiler-id>)
20992 It sets CMAKE_C_COMPILER to the given compiler and the cmake internal
20994 variable CMAKE_C_COMPILER_ID to the given compiler-id. It also by‐
20995 passes the check for working compiler and basic compiler information
20996 tests.
20997 Macro CMAKE_FORCE_CXX_COMPILER has the following signature:
20999 CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler-id>)
21001 It sets CMAKE_CXX_COMPILER to the given compiler and the cmake internal
21003 variable CMAKE_CXX_COMPILER_ID to the given compiler-id. It also by‐
21004 passes the check for working compiler and basic compiler information
21005 tests.
21006 Macro CMAKE_FORCE_Fortran_COMPILER has the following signature:
21008 CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler-id>)
21010 It sets CMAKE_Fortran_COMPILER to the given compiler and the cmake in‐
21012 ternal variable CMAKE_Fortran_COMPILER_ID to the given compiler-id. It
21013 also bypasses the check for working compiler and basic compiler infor‐
21014 mation tests.
21015 So a simple toolchain file could look like this:
21017 include (CMakeForceCompiler)
21019 set(CMAKE_SYSTEM_NAME Generic)
21020 CMAKE_FORCE_C_COMPILER (chc12 MetrowerksHicross)
21021 CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross)
21022 CMakeParseArguments
21024 This module once implemented the cmake_parse_arguments() command that
21025 is now implemented natively by CMake. It is now an empty placeholder
21026 for compatibility with projects that include it to get the command from
21027 CMake 3.4 and lower.
21028 Documentation
21030 Deprecated since version 3.18: This module does nothing, unless policy
21031 CMP0106 is set to OLD.
21032 This module provides support for the VTK documentation framework. It
21035 relies on several tools (Doxygen, Perl, etc).
21036 MacroAddFileDependencies
21038 Deprecated since version 3.14.
21039 MACRO_ADD_FILE_DEPENDENCIES(<source> <files>...)
21042 Do not use this command in new code. It is just a wrapper around:
21044 set_property(SOURCE <source> APPEND PROPERTY OBJECT_DEPENDS <files>...)
21046 Instead use the set_property() command to append to the OBJECT_DEPENDS
21048 source file property directly.
21049 TestCXXAcceptsFlag
21051 Deprecated since version 3.0: See CheckCXXCompilerFlag.
21052 Check if the CXX compiler accepts a flag.
21055 CHECK_CXX_ACCEPTS_FLAG(<flags> <variable>)
21057 <flags>
21059 the flags to try
21060 <variable>
21062 variable to store the result
21063 UseJavaClassFilelist
21065 Changed in version 3.20: This module was previously documented by mis‐
21066 take and was never meant for direct inclusion by project code. See the
21067 UseJava module.
21068 UseJavaSymlinks
21071 Changed in version 3.20: This module was previously documented by mis‐
21072 take and was never meant for direct inclusion by project code. See the
21073 UseJava module.
21074 UsePkgConfig
21077 Obsolete pkg-config module for CMake, use FindPkgConfig instead.
21078 This module defines the following macro:
21080 PKGCONFIG(package includedir libdir linkflags cflags)
21082 Calling PKGCONFIG will fill the desired information into the 4 given
21084 arguments, e.g. PKGCONFIG(libart-2.0 LIBART_INCLUDE_DIR
21085 LIBART_LINK_DIR LIBART_LINK_FLAGS LIBART_CFLAGS) if pkg-config was NOT
21086 found or the specified software package doesn't exist, the variable
21087 will be empty when the function returns, otherwise they will contain
21088 the respective information
21089 Use_wxWindows
21091 Deprecated since version 2.8.10: Use find_package(wxWidgets) and in‐
21092 clude(${wxWidgets_USE_FILE}) instead.
21093 This convenience include finds if wxWindows is installed and set the
21096 appropriate libs, incdirs, flags etc. author Jan Woetzel <jw -at-
21097 mip.informatik.uni-kiel.de> (07/2003)
21098 USAGE:
21100 just include Use_wxWindows.cmake
21102 in your projects CMakeLists.txt
21103 include( ${CMAKE_MODULE_PATH}/Use_wxWindows.cmake)
21105 if you are sure you need GL then
21107 set(WXWINDOWS_USE_GL 1)
21109 *before* you include this file.
21111 WriteBasicConfigVersionFile
21113 Deprecated since version 3.0: Use the identical command
21114 write_basic_package_version_file() from module
21115 CMakePackageConfigHelpers.
21116 WRITE_BASIC_CONFIG_VERSION_FILE( filename
21119 [VERSION major.minor.patch]
21120 COMPATIBILITY (AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion)
21121 [ARCH_INDEPENDENT]
21122 )
21123 WriteCompilerDetectionHeader
21125 Deprecated since version 3.20: This module is available only if policy
21126 CMP0120 is not set to NEW. Do not use it in new code.
21127 New in version 3.1.
21130 This module provides the function write_compiler_detection_header().
21133 This function can be used to generate a file suitable for preprocessor
21135 inclusion which contains macros to be used in source code:
21136 write_compiler_detection_header(
21138 FILE <file>
21139 PREFIX <prefix>
21140 [OUTPUT_FILES_VAR <output_files_var> OUTPUT_DIR <output_dir>]
21141 COMPILERS <compiler> [...]
21142 FEATURES <feature> [...]
21143 [BARE_FEATURES <feature> [...]]
21144 [VERSION <version>]
21145 [PROLOG <prolog>]
21146 [EPILOG <epilog>]
21147 [ALLOW_UNKNOWN_COMPILERS]
21148 [ALLOW_UNKNOWN_COMPILER_VERSIONS]
21149 )
21150 This generates the file <file> with macros which all have the prefix
21152 <prefix>.
21153 By default, all content is written directly to the <file>. The OUT‐
21155 PUT_FILES_VAR may be specified to cause the compiler-specific content
21156 to be written to separate files. The separate files are then available
21157 in the <output_files_var> and may be consumed by the caller for instal‐
21158 lation for example. The OUTPUT_DIR specifies a relative path from the
21159 main <file> to the compiler-specific files. For example:
21160 write_compiler_detection_header(
21162 FILE climbingstats_compiler_detection.h
21163 PREFIX ClimbingStats
21164 OUTPUT_FILES_VAR support_files
21165 OUTPUT_DIR compilers
21166 COMPILERS GNU Clang MSVC Intel
21167 FEATURES cxx_variadic_templates
21168 )
21169 install(FILES
21170 ${CMAKE_CURRENT_BINARY_DIR}/climbingstats_compiler_detection.h
21171 DESTINATION include
21172 )
21173 install(FILES
21174 ${support_files}
21175 DESTINATION include/compilers
21176 )
21177 VERSION may be used to specify the API version to be generated. Future
21179 versions of CMake may introduce alternative APIs. A given API is se‐
21180 lected by any <version> value greater than or equal to the version of
21181 CMake that introduced the given API and less than the version of CMake
21182 that introduced its succeeding API. The value of the
21183 CMAKE_MINIMUM_REQUIRED_VERSION variable is used if no explicit version
21184 is specified. (As of CMake version 3.27.7 there is only one API ver‐
21185 sion.)
21186 PROLOG may be specified as text content to write at the start of the
21188 header. EPILOG may be specified as text content to write at the end of
21189 the header
21190 At least one <compiler> and one <feature> must be listed. Compilers
21192 which are known to CMake, but not specified are detected and a pre‐
21193 processor #error is generated for them. A preprocessor macro matching
21194 <PREFIX>_COMPILER_IS_<compiler> is generated for each compiler known to
21195 CMake to contain the value 0 or 1.
21196 Possible compiler identifiers are documented with the
21198 CMAKE_<LANG>_COMPILER_ID variable. Available features in this version
21199 of CMake are listed in the CMAKE_C_KNOWN_FEATURES and
21200 CMAKE_CXX_KNOWN_FEATURES global properties. See the
21201 cmake-compile-features(7) manual for information on compile features.
21202 New in version 3.2: Added MSVC and AppleClang compiler support.
21204 New in version 3.6: Added Intel compiler support.
21207 Changed in version 3.8: The {c,cxx}_std_* meta-features are ignored if
21210 requested.
21211 New in version 3.8: ALLOW_UNKNOWN_COMPILERS and ALLOW_UNKNOWN_COM‐
21214 PILER_VERSIONS cause the module to generate conditions that treat un‐
21215 known compilers as simply lacking all features. Without these options
21216 the default behavior is to generate a #error for unknown compilers and
21217 versions.
21218 New in version 3.12: BARE_FEATURES will define the compatibility macros
21221 with the name used in newer versions of the language standard, so the
21222 code can use the new feature name unconditionally.
21223 Feature Test Macros
21226 For each compiler, a preprocessor macro is generated matching <PRE‐
21227 FIX>_COMPILER_IS_<compiler> which has the content either 0 or 1, de‐
21228 pending on the compiler in use. Preprocessor macros for compiler ver‐
21229 sion components are generated matching <PREFIX>_COMPILER_VERSION_MAJOR
21230 <PREFIX>_COMPILER_VERSION_MINOR and <PREFIX>_COMPILER_VERSION_PATCH
21231 containing decimal values for the corresponding compiler version compo‐
21232 nents, if defined.
21233 A preprocessor test is generated based on the compiler version denoting
21235 whether each feature is enabled. A preprocessor macro matching <PRE‐
21236 FIX>_COMPILER_<FEATURE>, where <FEATURE> is the upper-case <feature>
21237 name, is generated to contain the value 0 or 1 depending on whether the
21238 compiler in use supports the feature:
21239 write_compiler_detection_header(
21241 FILE climbingstats_compiler_detection.h
21242 PREFIX ClimbingStats
21243 COMPILERS GNU Clang AppleClang MSVC Intel
21244 FEATURES cxx_variadic_templates
21245 )
21246 #if ClimbingStats_COMPILER_CXX_VARIADIC_TEMPLATES
21248 template<typename... T>
21249 void someInterface(T t...) { /* ... */ }
21250 #else
21251 // Compatibility versions
21252 template<typename T1>
21253 void someInterface(T1 t1) { /* ... */ }
21254 template<typename T1, typename T2>
21255 void someInterface(T1 t1, T2 t2) { /* ... */ }
21256 template<typename T1, typename T2, typename T3>
21257 void someInterface(T1 t1, T2 t2, T3 t3) { /* ... */ }
21258 #endif
21259 Symbol Macros
21261 Some additional symbol-defines are created for particular features for
21262 use as symbols which may be conditionally defined empty:
21263 class MyClass ClimbingStats_FINAL
21265 {
21266 ClimbingStats_CONSTEXPR int someInterface() { return 42; }
21267 };
21268 The ClimbingStats_FINAL macro will expand to final if the compiler (and
21270 its flags) support the cxx_final feature, and the ClimbingStats_CONST‐
21271 EXPR macro will expand to constexpr if cxx_constexpr is supported.
21272 If BARE_FEATURES cxx_final was given as argument the final keyword will
21274 be defined for old compilers, too.
21275 The following features generate corresponding symbol defines and if
21277 they are available as BARE_FEATURES:
21278 ┌──────────────────┬────────────────────┬─────────────┬──────┐
21280 │Feature │ Define │ Symbol │ bare │
21281 ├──────────────────┼────────────────────┼─────────────┼──────┤
21282 │c_restrict │ <PREFIX>_RE‐ │ restrict │ yes │
21283 │ │ STRICT │ │ │
21284 ├──────────────────┼────────────────────┼─────────────┼──────┤
21285 │cxx_constexpr │ <PREFIX>_CONST‐ │ constexpr │ yes │
21286 │ │ EXPR │ │ │
21287 ├──────────────────┼────────────────────┼─────────────┼──────┤
21288 │cxx_deleted_func‐ │ <PRE‐ │ = delete │ │
21289 │tions │ FIX>_DELETED_FUNC‐ │ │ │
21290 │ │ TION │ │ │
21291 ├──────────────────┼────────────────────┼─────────────┼──────┤
21292 │cxx_extern_tem‐ │ <PREFIX>_EX‐ │ extern │ │
21293 │plates │ TERN_TEMPLATE │ │ │
21294 ├──────────────────┼────────────────────┼─────────────┼──────┤
21295 │cxx_final │ <PREFIX>_FINAL │ final │ yes │
21296 ├──────────────────┼────────────────────┼─────────────┼──────┤
21297 │cxx_noexcept │ <PREFIX>_NOEXCEPT │ noexcept │ yes │
21298 ├──────────────────┼────────────────────┼─────────────┼──────┤
21299 │cxx_noexcept │ <PREFIX>_NOEX‐ │ noexcept(X) │ │
21300 │ │ CEPT_EXPR(X) │ │ │
21301 ├──────────────────┼────────────────────┼─────────────┼──────┤
21302 │cxx_override │ <PREFIX>_OVERRIDE │ override │ yes │
21303 └──────────────────┴────────────────────┴─────────────┴──────┘
21304 Compatibility Implementation Macros
21306 Some features are suitable for wrapping in a macro with a backward com‐
21307 patibility implementation if the compiler does not support the feature.
21308 When the cxx_static_assert feature is not provided by the compiler, a
21310 compatibility implementation is available via the <PREFIX>_STATIC_AS‐
21311 SERT(COND) and <PREFIX>_STATIC_ASSERT_MSG(COND, MSG) function-like
21312 macros. The macros expand to static_assert where that compiler feature
21313 is available, and to a compatibility implementation otherwise. In the
21314 first form, the condition is stringified in the message field of
21315 static_assert. In the second form, the message MSG is passed to the
21316 message field of static_assert, or ignored if using the backward com‐
21317 patibility implementation.
21318 The cxx_attribute_deprecated feature provides a macro definition <PRE‐
21320 FIX>_DEPRECATED, which expands to either the standard [[deprecated]]
21321 attribute or a compiler-specific decorator such as __attri‐
21322 bute__((__deprecated__)) used by GNU compilers.
21323 The cxx_alignas feature provides a macro definition <PREFIX>_ALIGNAS
21325 which expands to either the standard alignas decorator or a com‐
21326 piler-specific decorator such as __attribute__ ((__aligned__)) used by
21327 GNU compilers.
21328 The cxx_alignof feature provides a macro definition <PREFIX>_ALIGNOF
21330 which expands to either the standard alignof decorator or a com‐
21331 piler-specific decorator such as __alignof__ used by GNU compilers.
21332 ┌─────────────────┬──────────────────┬────────────────┬──────┐
21334 │Feature │ Define │ Symbol │ bare │
21335 ├─────────────────┼──────────────────┼────────────────┼──────┤
21336 │cxx_alignas │ <PREFIX>_ALIGNAS │ alignas │ │
21337 ├─────────────────┼──────────────────┼────────────────┼──────┤
21338 │cxx_alignof │ <PREFIX>_ALIGNOF │ alignof │ │
21339 ├─────────────────┼──────────────────┼────────────────┼──────┤
21340 │cxx_nullptr │ <PREFIX>_NULLPTR │ nullptr │ yes │
21341 ├─────────────────┼──────────────────┼────────────────┼──────┤
21342 │cxx_static_as‐ │ <PRE‐ │ static_assert │ │
21343 │sert │ FIX>_STATIC_AS‐ │ │ │
21344 │ │ SERT │ │ │
21345 ├─────────────────┼──────────────────┼────────────────┼──────┤
21346 │cxx_static_as‐ │ <PRE‐ │ static_assert │ │
21347 │sert │ FIX>_STATIC_AS‐ │ │ │
21348 │ │ SERT_MSG │ │ │
21349 ├─────────────────┼──────────────────┼────────────────┼──────┤
21350 │cxx_attri‐ │ <PREFIX>_DEPRE‐ │ [[deprecated]] │ │
21351 │bute_deprecated │ CATED │ │ │
21352 ├─────────────────┼──────────────────┼────────────────┼──────┤
21353 │cxx_attri‐ │ <PREFIX>_DEPRE‐ │ [[deprecated]] │ │
21354 │bute_deprecated │ CATED_MSG │ │ │
21355 ├─────────────────┼──────────────────┼────────────────┼──────┤
21356 │cxx_thread_local │ <PRE‐ │ thread_local │ │
21357 │ │ FIX>_THREAD_LO‐ │ │ │
21358 │ │ CAL │ │ │
21359 └─────────────────┴──────────────────┴────────────────┴──────┘
21360 A use-case which arises with such deprecation macros is the deprecation
21362 of an entire library. In that case, all public API in the library may
21363 be decorated with the <PREFIX>_DEPRECATED macro. This results in very
21364 noisy build output when building the library itself, so the macro may
21365 be may be defined to empty in that case when building the deprecated
21366 library:
21367 add_library(compat_support ${srcs})
21369 target_compile_definitions(compat_support
21370 PRIVATE
21371 CompatSupport_DEPRECATED=
21372 )
21373 Example Usage
21375 NOTE:
21376 This section was migrated from the cmake-compile-features(7) manual
21377 since it relies on the WriteCompilerDetectionHeader module which is
21378 removed by policy CMP0120.
21379 Compile features may be preferred if available, without creating a hard
21381 requirement. For example, a library may provide alternative implemen‐
21382 tations depending on whether the cxx_variadic_templates feature is
21383 available:
21384 #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES
21386 template<int I, int... Is>
21387 struct Interface;
21388 template<int I>
21390 struct Interface<I>
21391 {
21392 static int accumulate()
21393 {
21394 return I;
21395 }
21396 };
21397 template<int I, int... Is>
21399 struct Interface
21400 {
21401 static int accumulate()
21402 {
21403 return I + Interface<Is...>::accumulate();
21404 }
21405 };
21406 #else
21407 template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
21408 struct Interface
21409 {
21410 static int accumulate() { return I1 + I2 + I3 + I4; }
21411 };
21412 #endif
21413 Such an interface depends on using the correct preprocessor defines for
21415 the compiler features. CMake can generate a header file containing
21416 such defines using the WriteCompilerDetectionHeader module. The module
21417 contains the write_compiler_detection_header function which accepts pa‐
21418 rameters to control the content of the generated header file:
21419 write_compiler_detection_header(
21421 FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
21422 PREFIX Foo
21423 COMPILERS GNU
21424 FEATURES
21425 cxx_variadic_templates
21426 )
21427 Such a header file may be used internally in the source code of a
21429 project, and it may be installed and used in the interface of library
21430 code.
21431 For each feature listed in FEATURES, a preprocessor definition is cre‐
21433 ated in the header file, and defined to either 1 or 0.
21434 Additionally, some features call for additional defines, such as the
21436 cxx_final and cxx_override features. Rather than being used in #ifdef
21437 code, the final keyword is abstracted by a symbol which is defined to
21438 either final, a compiler-specific equivalent, or to empty. That way,
21439 C++ code can be written to unconditionally use the symbol, and compiler
21440 support determines what it is expanded to:
21441 struct Interface {
21443 virtual void Execute() = 0;
21444 };
21445 struct Concrete Foo_FINAL {
21447 void Execute() Foo_OVERRIDE;
21448 };
21449 In this case, Foo_FINAL will expand to final if the compiler supports
21451 the keyword, or to empty otherwise.
21452 In this use-case, the project code may wish to enable a particular lan‐
21454 guage standard if available from the compiler. The CXX_STANDARD target
21455 property may be set to the desired language standard for a particular
21456 target, and the CMAKE_CXX_STANDARD variable may be set to influence all
21457 following targets:
21458 write_compiler_detection_header(
21460 FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
21461 PREFIX Foo
21462 COMPILERS GNU
21463 FEATURES
21464 cxx_final cxx_override
21465 )
21466 # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
21468 # which will expand to 'final' if the compiler supports the requested
21469 # CXX_STANDARD.
21470 add_library(foo foo.cpp)
21471 set_property(TARGET foo PROPERTY CXX_STANDARD 11)
21472 # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
21474 # which will expand to 'final' if the compiler supports the feature,
21475 # even though CXX_STANDARD is not set explicitly. The requirement of
21476 # cxx_constexpr causes CMake to set CXX_STANDARD internally, which
21477 # affects the compile flags.
21478 add_library(foo_impl foo_impl.cpp)
21479 target_compile_features(foo_impl PRIVATE cxx_constexpr)
21480 The write_compiler_detection_header function also creates compatibility
21482 code for other features which have standard equivalents. For example,
21483 the cxx_static_assert feature is emulated with a template and ab‐
21484 stracted via the <PREFIX>_STATIC_ASSERT and <PREFIX>_STATIC_ASSERT_MSG
21485 function-macros.
21486 Deprecated Find Modules
21488 FindCUDA
21489 Changed in version 3.27: This module is available only if policy
21490 CMP0146 is not set to NEW. Port projects to CMake's first-class CUDA
21491 language support.
21492 Deprecated since version 3.10: Do not use this module in new code.
21495 It is no longer necessary to use this module or call find_package(CUDA)
21498 for compiling CUDA code. Instead, list CUDA among the languages named
21499 in the top-level call to the project() command, or call the
21500 enable_language() command with CUDA. Then one can add CUDA (.cu)
21501 sources directly to targets similar to other languages.
21502 New in version 3.17: To find and use the CUDA toolkit libraries manu‐
21504 ally, use the FindCUDAToolkit module instead. It works regardless of
21505 the CUDA language being enabled.
21506 Documentation of Deprecated Usage
21509 Tools for building CUDA C files: libraries and build dependencies.
21510 This script locates the NVIDIA CUDA C tools. It should work on Linux,
21512 Windows, and macOS and should be reasonably up to date with CUDA C re‐
21513 leases.
21514 New in version 3.19: QNX support.
21516 This script makes use of the standard find_package() arguments of <VER‐
21519 SION>, REQUIRED and QUIET. CUDA_FOUND will report if an acceptable
21520 version of CUDA was found.
21521 The script will prompt the user to specify CUDA_TOOLKIT_ROOT_DIR if the
21523 prefix cannot be determined by the location of nvcc in the system path
21524 and REQUIRED is specified to find_package(). To use a different in‐
21525 stalled version of the toolkit set the environment variable
21526 CUDA_BIN_PATH before running cmake (e.g. CUDA_BIN_PATH=/usr/lo‐
21527 cal/cuda1.0 instead of the default /usr/local/cuda) or set CUDA_TOOL‐
21528 KIT_ROOT_DIR after configuring. If you change the value of CUDA_TOOL‐
21529 KIT_ROOT_DIR, various components that depend on the path will be relo‐
21530 cated.
21531 It might be necessary to set CUDA_TOOLKIT_ROOT_DIR manually on certain
21533 platforms, or to use a CUDA runtime not installed in the default loca‐
21534 tion. In newer versions of the toolkit the CUDA library is included
21535 with the graphics driver -- be sure that the driver version matches
21536 what is needed by the CUDA runtime version.
21537 Input Variables
21539 The following variables affect the behavior of the macros in the script
21540 (in alphabetical order). Note that any of these flags can be changed
21541 multiple times in the same directory before calling cuda_add_exe‐
21542 cutable(), cuda_add_library(), cuda_compile(), cuda_compile_ptx(),
21543 cuda_compile_fatbin(), cuda_compile_cubin() or cuda_wrap_srcs():
21544 CUDA_64_BIT_DEVICE_CODE (Default: host bit size)
21546 Set to ON to compile for 64 bit device code, OFF for 32 bit de‐
21547 vice code. Note that making this different from the host code
21548 when generating object or C files from CUDA code just won't
21549 work, because size_t gets defined by nvcc in the generated
21550 source. If you compile to PTX and then load the file yourself,
21551 you can mix bit sizes between device and host.
21552 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE (Default: ON)
21554 Set to ON if you want the custom build rule to be attached to
21555 the source file in Visual Studio. Turn OFF if you add the same
21556 cuda file to multiple targets.
21557 This allows the user to build the target from the CUDA file;
21559 however, bad things can happen if the CUDA source file is added
21560 to multiple targets. When performing parallel builds it is pos‐
21561 sible for the custom build command to be run more than once and
21562 in parallel causing cryptic build errors. VS runs the rules for
21563 every source file in the target, and a source can have only one
21564 rule no matter how many projects it is added to. When the rule
21565 is run from multiple targets race conditions can occur on the
21566 generated file. Eventually everything will get built, but if
21567 the user is unaware of this behavior, there may be confusion.
21568 It would be nice if this script could detect the reuse of source
21569 files across multiple targets and turn the option off for the
21570 user, but no good solution could be found.
21571 CUDA_BUILD_CUBIN (Default: OFF)
21573 Set to ON to enable and extra compilation pass with the -cubin
21574 option in Device mode. The output is parsed and register, shared
21575 memory usage is printed during build.
21576 CUDA_BUILD_EMULATION (Default: OFF for device mode)
21578 Set to ON for Emulation mode. -D_DEVICEEMU is defined for CUDA C
21579 files when CUDA_BUILD_EMULATION is TRUE.
21580 CUDA_LINK_LIBRARIES_KEYWORD (Default: "")
21582 New in version 3.9.
21583 The <PRIVATE|PUBLIC|INTERFACE> keyword to use for internal
21586 target_link_libraries() calls. The default is to use no keyword
21587 which uses the old "plain" form of target_link_libraries(). Note
21588 that is matters because whatever is used inside the FindCUDA
21589 module must also be used outside - the two forms of
21590 target_link_libraries() cannot be mixed.
21591 CUDA_GENERATED_OUTPUT_DIR (Default: CMAKE_CURRENT_BINARY_DIR)
21593 Set to the path you wish to have the generated files placed. If
21594 it is blank output files will be placed in
21595 CMAKE_CURRENT_BINARY_DIR. Intermediate files will always be
21596 placed in CMAKE_CURRENT_BINARY_DIR/CMakeFiles.
21597 CUDA_HOST_COMPILATION_CPP (Default: ON)
21599 Set to OFF for C compilation of host code.
21600 CUDA_HOST_COMPILER (Default: CMAKE_C_COMPILER)
21602 Set the host compiler to be used by nvcc. Ignored if -ccbin or
21603 --compiler-bindir is already present in the CUDA_NVCC_FLAGS or
21604 CUDA_NVCC_FLAGS_<CONFIG> variables. For Visual Studio targets,
21605 the host compiler is constructed with one or more visual studio
21606 macros such as $(VCInstallDir), that expands out to the path
21607 when the command is run from within VS.
21608 New in version 3.13: If the CUDAHOSTCXX environment variable is
21610 set it will be used as the default.
21611 CUDA_NVCC_FLAGS, CUDA_NVCC_FLAGS_<CONFIG>
21614 Additional NVCC command line arguments. NOTE: multiple argu‐
21615 ments must be semi-colon delimited (e.g. --compiler-op‐
21616 tions;-Wall)
21617 New in version 3.6: Contents of these variables may use
21619 generator expressions.
21620 CUDA_PROPAGATE_HOST_FLAGS (Default: ON)
21623 Set to ON to propagate CMAKE_{C,CXX}_FLAGS and their configura‐
21624 tion dependent counterparts (e.g. CMAKE_C_FLAGS_DEBUG) automati‐
21625 cally to the host compiler through nvcc's -Xcompiler flag. This
21626 helps make the generated host code match the rest of the system
21627 better. Sometimes certain flags give nvcc problems, and this
21628 will help you turn the flag propagation off. This does not af‐
21629 fect the flags supplied directly to nvcc via CUDA_NVCC_FLAGS or
21630 through the OPTION flags specified through cuda_add_library(),
21631 cuda_add_executable(), or cuda_wrap_srcs(). Flags used for
21632 shared library compilation are not affected by this flag.
21633 CUDA_SEPARABLE_COMPILATION (Default: OFF)
21635 If set this will enable separable compilation for all CUDA run‐
21636 time object files. If used outside of cuda_add_executable() and
21637 cuda_add_library() (e.g. calling cuda_wrap_srcs() directly),
21638 cuda_compute_separable_compilation_object_file_name() and
21639 cuda_link_separable_compilation_objects() should be called.
21640 CUDA_SOURCE_PROPERTY_FORMAT
21642 New in version 3.3.
21643 If this source file property is set, it can override the format
21646 specified to cuda_wrap_srcs() (OBJ, PTX, CUBIN, or FATBIN). If
21647 an input source file is not a .cu file, setting this file will
21648 cause it to be treated as a .cu file. See documentation for
21649 set_source_files_properties on how to set this property.
21650 CUDA_USE_STATIC_CUDA_RUNTIME (Default: ON)
21652 New in version 3.3.
21653 When enabled the static version of the CUDA runtime library will
21656 be used in CUDA_LIBRARIES. If the version of CUDA configured
21657 doesn't support this option, then it will be silently disabled.
21658 CUDA_VERBOSE_BUILD (Default: OFF)
21660 Set to ON to see all the commands used when building the CUDA
21661 file. When using a Makefile generator the value defaults to
21662 VERBOSE (run make VERBOSE=1 to see output), although setting
21663 CUDA_VERBOSE_BUILD to ON will always print the output.
21664 Commands
21666 The script creates the following functions and macros (in alphabetical
21667 order):
21668 cuda_add_cufft_to_target(<cuda_target>)
21670 Adds the cufft library to the target (can be any target). Handles
21672 whether you are in emulation mode or not.
21673 cuda_add_cublas_to_target(<cuda_target>)
21675 Adds the cublas library to the target (can be any target). Handles
21677 whether you are in emulation mode or not.
21678 cuda_add_executable(<cuda_target> <file>...
21680 [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [OPTIONS ...])
21681 Creates an executable <cuda_target> which is made up of the files spec‐
21683 ified. All of the non CUDA C files are compiled using the standard
21684 build rules specified by CMake and the CUDA files are compiled to ob‐
21685 ject files using nvcc and the host compiler. In addition CUDA_IN‐
21686 CLUDE_DIRS is added automatically to include_directories(). Some stan‐
21687 dard CMake target calls can be used on the target after calling this
21688 macro (e.g. set_target_properties() and target_link_libraries()), but
21689 setting properties that adjust compilation flags will not affect code
21690 compiled by nvcc. Such flags should be modified before calling
21691 cuda_add_executable(), cuda_add_library() or cuda_wrap_srcs().
21692 cuda_add_library(<cuda_target> <file>...
21694 [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [OPTIONS ...])
21695 Same as cuda_add_executable() except that a library is created.
21697 cuda_build_clean_target()
21699 Creates a convenience target that deletes all the dependency files gen‐
21701 erated. You should make clean after running this target to ensure the
21702 dependency files get regenerated.
21703 cuda_compile(<generated_files> <file>... [STATIC | SHARED | MODULE]
21705 [OPTIONS ...])
21706 Returns a list of generated files from the input source files to be
21708 used with add_library() or add_executable().
21709 cuda_compile_ptx(<generated_files> <file>... [OPTIONS ...])
21711 Returns a list of PTX files generated from the input source files.
21713 cuda_compile_fatbin(<generated_files> <file>... [OPTIONS ...])
21715 New in version 3.1.
21717 Returns a list of FATBIN files generated from the input source files.
21720 cuda_compile_cubin(<generated_files> <file>... [OPTIONS ...])
21722 New in version 3.1.
21724 Returns a list of CUBIN files generated from the input source files.
21727 cuda_compute_separable_compilation_object_file_name(<output_file_var>
21729 <cuda_target>
21730 <object_files>)
21731 Compute the name of the intermediate link file used for separable com‐
21733 pilation. This file name is typically passed into CUDA_LINK_SEPARA‐
21734 BLE_COMPILATION_OBJECTS. output_file_var is produced based on
21735 cuda_target the list of objects files that need separable compilation
21736 as specified by <object_files>. If the <object_files> list is empty,
21737 then <output_file_var> will be empty. This function is called automat‐
21738 ically for cuda_add_library() and cuda_add_executable(). Note that
21739 this is a function and not a macro.
21740 cuda_include_directories(path0 path1 ...)
21742 Sets the directories that should be passed to nvcc (e.g. nvcc -Ipath0
21744 -Ipath1 ...). These paths usually contain other .cu files.
21745 cuda_link_separable_compilation_objects(<output_file_var> <cuda_target>
21747 <nvcc_flags> <object_files>)
21748 Generates the link object required by separable compilation from the
21750 given object files. This is called automatically for cuda_add_exe‐
21751 cutable() and cuda_add_library(), but can be called manually when using
21752 cuda_wrap_srcs() directly. When called from cuda_add_library() or
21753 cuda_add_executable() the <nvcc_flags> passed in are the same as the
21754 flags passed in via the OPTIONS argument. The only nvcc flag added au‐
21755 tomatically is the bitness flag as specified by CUDA_64_BIT_DE‐
21756 VICE_CODE. Note that this is a function instead of a macro.
21757 cuda_select_nvcc_arch_flags(<out_variable> [<target_CUDA_architecture> ...])
21759 Selects GPU arch flags for nvcc based on target_CUDA_architecture.
21761 Values for target_CUDA_architecture:
21763 • Auto: detects local machine GPU compute arch at runtime.
21765 • Common and All: cover common and entire subsets of architectures.
21767 • <name>: one of Fermi, Kepler, Maxwell, Kepler+Tegra, Kepler+Tesla,
21769 Maxwell+Tegra, Pascal.
21770 • <ver>, <ver>(<ver>), <ver>+PTX, where <ver> is one of 2.0, 2.1, 3.0,
21772 3.2, 3.5, 3.7, 5.0, 5.2, 5.3, 6.0, 6.2.
21773 Returns list of flags to be added to CUDA_NVCC_FLAGS in <out_variable>.
21775 Additionally, sets <out_variable>_readable to the resulting numeric
21776 list.
21777 Example:
21779 cuda_select_nvcc_arch_flags(ARCH_FLAGS 3.0 3.5+PTX 5.2(5.0) Maxwell)
21781 list(APPEND CUDA_NVCC_FLAGS ${ARCH_FLAGS})
21782 More info on CUDA architectures: https://en.wikipedia.org/wiki/CUDA.
21784 Note that this is a function instead of a macro.
21785 cuda_wrap_srcs(<cuda_target> <format> <generated_files> <file>...
21787 [STATIC | SHARED | MODULE] [OPTIONS ...])
21788 This is where all the magic happens. cuda_add_executable(),
21790 cuda_add_library(), cuda_compile(), and cuda_compile_ptx() all call
21791 this function under the hood.
21792 Given the list of files <file>... this macro generates custom commands
21794 that generate either PTX or linkable objects (use PTX or OBJ for the
21795 <format> argument to switch). Files that don't end with .cu or have
21796 the HEADER_FILE_ONLY property are ignored.
21797 The arguments passed in after OPTIONS are extra command line options to
21799 give to nvcc. You can also specify per configuration options by speci‐
21800 fying the name of the configuration followed by the options. General
21801 options must precede configuration specific options. Not all configu‐
21802 rations need to be specified, only the ones provided will be used. For
21803 example:
21804 cuda_add_executable(...
21806 OPTIONS -DFLAG=2 "-DFLAG_OTHER=space in flag"
21807 DEBUG -g
21808 RELEASE --use_fast_math
21809 RELWITHDEBINFO --use_fast_math;-g
21810 MINSIZEREL --use_fast_math)
21811 For certain configurations (namely VS generating object files with
21813 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE set to ON), no generated file
21814 will be produced for the given cuda file. This is because when you add
21815 the cuda file to Visual Studio it knows that this file produces an ob‐
21816 ject file and will link in the resulting object file automatically.
21817 This script will also generate a separate cmake script that is used at
21819 build time to invoke nvcc. This is for several reasons:
21820 • nvcc can return negative numbers as return values which confuses Vis‐
21822 ual Studio into thinking that the command succeeded. The script now
21823 checks the error codes and produces errors when there was a problem.
21824 • nvcc has been known to not delete incomplete results when it encoun‐
21826 ters problems. This confuses build systems into thinking the target
21827 was generated when in fact an unusable file exists. The script now
21828 deletes the output files if there was an error.
21829 • By putting all the options that affect the build into a file and then
21831 make the build rule dependent on the file, the output files will be
21832 regenerated when the options change.
21833 This script also looks at optional arguments STATIC, SHARED, or MODULE
21835 to determine when to target the object compilation for a shared li‐
21836 brary. BUILD_SHARED_LIBS is ignored in cuda_wrap_srcs(), but it is re‐
21837 spected in cuda_add_library(). On some systems special flags are added
21838 for building objects intended for shared libraries. A preprocessor
21839 macro, <target_name>_EXPORTS is defined when a shared library compila‐
21840 tion is detected.
21841 Flags passed into add_definitions with -D or /D are passed along to
21843 nvcc.
21844 Result Variables
21846 The script defines the following variables:
21847 CUDA_VERSION_MAJOR
21849 The major version of cuda as reported by nvcc.
21850 CUDA_VERSION_MINOR
21852 The minor version.
21853 CUDA_VERSION, CUDA_VERSION_STRING
21855 Full version in the X.Y format.
21856 CUDA_HAS_FP16
21858 New in version 3.6: Whether a short float (float16, fp16) is
21859 supported.
21860 CUDA_TOOLKIT_ROOT_DIR
21863 Path to the CUDA Toolkit (defined if not set).
21864 CUDA_SDK_ROOT_DIR
21866 Path to the CUDA SDK. Use this to find files in the SDK. This
21867 script will not directly support finding specific libraries or
21868 headers, as that isn't supported by NVIDIA. If you want to
21869 change libraries when the path changes see the FindCUDA.cmake
21870 script for an example of how to clear these variables. There
21871 are also examples of how to use the CUDA_SDK_ROOT_DIR to locate
21872 headers or libraries, if you so choose (at your own risk).
21873 CUDA_INCLUDE_DIRS
21875 Include directory for cuda headers. Added automatically for
21876 cuda_add_executable() and cuda_add_library().
21877 CUDA_LIBRARIES
21879 Cuda RT library.
21880 CUDA_CUFFT_LIBRARIES
21882 Device or emulation library for the Cuda FFT implementation (al‐
21883 ternative to cuda_add_cufft_to_target() macro)
21884 CUDA_CUBLAS_LIBRARIES
21886 Device or emulation library for the Cuda BLAS implementation
21887 (alternative to cuda_add_cublas_to_target() macro).
21888 CUDA_cudart_static_LIBRARY
21890 Statically linkable cuda runtime library. Only available for
21891 CUDA version 5.5+.
21892 CUDA_cudadevrt_LIBRARY
21894 New in version 3.7: Device runtime library. Required for sepa‐
21895 rable compilation.
21896 CUDA_cupti_LIBRARY
21899 CUDA Profiling Tools Interface library. Only available for CUDA
21900 version 4.0+.
21901 CUDA_curand_LIBRARY
21903 CUDA Random Number Generation library. Only available for CUDA
21904 version 3.2+.
21905 CUDA_cusolver_LIBRARY
21907 New in version 3.2: CUDA Direct Solver library. Only available
21908 for CUDA version 7.0+.
21909 CUDA_cusparse_LIBRARY
21912 CUDA Sparse Matrix library. Only available for CUDA version
21913 3.2+.
21914 CUDA_npp_LIBRARY
21916 NVIDIA Performance Primitives lib. Only available for CUDA ver‐
21917 sion 4.0+.
21918 CUDA_nppc_LIBRARY
21920 NVIDIA Performance Primitives lib (core). Only available for
21921 CUDA version 5.5+.
21922 CUDA_nppi_LIBRARY
21924 NVIDIA Performance Primitives lib (image processing). Only
21925 available for CUDA version 5.5 - 8.0.
21926 CUDA_nppial_LIBRARY
21928 NVIDIA Performance Primitives lib (image processing). Only
21929 available for CUDA version 9.0.
21930 CUDA_nppicc_LIBRARY
21932 NVIDIA Performance Primitives lib (image processing). Only
21933 available for CUDA version 9.0.
21934 CUDA_nppicom_LIBRARY
21936 NVIDIA Performance Primitives lib (image processing). Only
21937 available for CUDA version 9.0 - 10.2. Replaced by nvjpeg.
21938 CUDA_nppidei_LIBRARY
21940 NVIDIA Performance Primitives lib (image processing). Only
21941 available for CUDA version 9.0.
21942 CUDA_nppif_LIBRARY
21944 NVIDIA Performance Primitives lib (image processing). Only
21945 available for CUDA version 9.0.
21946 CUDA_nppig_LIBRARY
21948 NVIDIA Performance Primitives lib (image processing). Only
21949 available for CUDA version 9.0.
21950 CUDA_nppim_LIBRARY
21952 NVIDIA Performance Primitives lib (image processing). Only
21953 available for CUDA version 9.0.
21954 CUDA_nppist_LIBRARY
21956 NVIDIA Performance Primitives lib (image processing). Only
21957 available for CUDA version 9.0.
21958 CUDA_nppisu_LIBRARY
21960 NVIDIA Performance Primitives lib (image processing). Only
21961 available for CUDA version 9.0.
21962 CUDA_nppitc_LIBRARY
21964 NVIDIA Performance Primitives lib (image processing). Only
21965 available for CUDA version 9.0.
21966 CUDA_npps_LIBRARY
21968 NVIDIA Performance Primitives lib (signal processing). Only
21969 available for CUDA version 5.5+.
21970 CUDA_nvcuvenc_LIBRARY
21972 CUDA Video Encoder library. Only available for CUDA version
21973 3.2+. Windows only.
21974 CUDA_nvcuvid_LIBRARY
21976 CUDA Video Decoder library. Only available for CUDA version
21977 3.2+. Windows only.
21978 CUDA_nvToolsExt_LIBRARY
21980 New in version 3.16: NVIDA CUDA Tools Extension library. Avail‐
21981 able for CUDA version 5+.
21982 CUDA_OpenCL_LIBRARY
21985 New in version 3.16: NVIDA CUDA OpenCL library. Available for
21986 CUDA version 5+.
21987 FindITK
21990 This module no longer exists.
21991 This module existed in versions of CMake prior to 3.1, but became only
21993 a thin wrapper around find_package(ITK NO_MODULE) to provide compati‐
21994 bility for projects using long-outdated conventions. Now find_pack‐
21995 age(ITK) will search for ITKConfig.cmake directly.
21996 FindPythonInterp
21998 Changed in version 3.27: This module is available only if policy
21999 CMP0148 is not set to NEW.
22000 Deprecated since version 3.12: Use FindPython3, FindPython2 or
22003 FindPython instead.
22004 Find python interpreter
22007 This module finds if Python interpreter is installed and determines
22009 where the executables are. This code sets the following variables:
22010 PYTHONINTERP_FOUND - Was the Python executable found
22012 PYTHON_EXECUTABLE - path to the Python interpreter
22013 PYTHON_VERSION_STRING - Python version found e.g. 2.5.2
22015 PYTHON_VERSION_MAJOR - Python major version found e.g. 2
22016 PYTHON_VERSION_MINOR - Python minor version found e.g. 5
22017 PYTHON_VERSION_PATCH - Python patch version found e.g. 2
22018 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
22020 of version numbers that should be taken into account when searching for
22021 Python. You need to set this variable before calling find_pack‐
22022 age(PythonInterp).
22023 If calling both find_package(PythonInterp) and find_package(Python‐
22025 Libs), call find_package(PythonInterp) first to get the currently ac‐
22026 tive Python version by default with a consistent version of PYTHON_LI‐
22027 BRARIES.
22028 NOTE:
22030 A call to find_package(PythonInterp ${V}) for python version V may
22031 find a python executable with no version suffix. In this case no
22032 attempt is made to avoid python executables from other versions.
22033 Use FindPython3, FindPython2 or FindPython instead.
22034 FindPythonLibs
22036 Changed in version 3.27: This module is available only if policy
22037 CMP0148 is not set to NEW.
22038 Deprecated since version 3.12: Use FindPython3, FindPython2 or
22041 FindPython instead.
22042 Find python libraries
22045 This module finds if Python is installed and determines where the in‐
22047 clude files and libraries are. It also determines what the name of the
22048 library is. This code sets the following variables:
22049 PYTHONLIBS_FOUND - have the Python libs been found
22051 PYTHON_LIBRARIES - path to the python library
22052 PYTHON_INCLUDE_PATH - path to where Python.h is found (deprecated)
22053 PYTHON_INCLUDE_DIRS - path to where Python.h is found
22054 PYTHON_DEBUG_LIBRARIES - path to the debug library (deprecated)
22055 PYTHONLIBS_VERSION_STRING - version of the Python libs found (since CMake 2.8.8)
22056 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
22058 of version numbers that should be taken into account when searching for
22059 Python. You need to set this variable before calling find_pack‐
22060 age(PythonLibs).
22061 If you'd like to specify the installation of Python to use, you should
22063 modify the following cache variables:
22064 PYTHON_LIBRARY - path to the python library
22066 PYTHON_INCLUDE_DIR - path to where Python.h is found
22067 If calling both find_package(PythonInterp) and find_package(Python‐
22069 Libs), call find_package(PythonInterp) first to get the currently ac‐
22070 tive Python version by default with a consistent version of PYTHON_LI‐
22071 BRARIES.
22072 FindQt
22074 Deprecated since version 3.14: This module is available only if policy
22075 CMP0084 is not set to NEW.
22076 Searches for all installed versions of Qt3 or Qt4.
22079 This module cannot handle Qt5 or any later versions. For those, see
22081 cmake-qt(7).
22082 This module should only be used if your project can work with multiple
22084 versions of Qt. If not, you should just directly use FindQt4 or
22085 FindQt3. If multiple versions of Qt are found on the machine, then The
22086 user must set the option DESIRED_QT_VERSION to the version they want to
22087 use. If only one version of qt is found on the machine, then the DE‐
22088 SIRED_QT_VERSION is set to that version and the matching FindQt3 or
22089 FindQt4 module is included. Once the user sets DESIRED_QT_VERSION,
22090 then the FindQt3 or FindQt4 module is included.
22091 QT_REQUIRED if this is set to TRUE then if CMake can
22093 not find Qt4 or Qt3 an error is raised
22094 and a message is sent to the user.
22095 DESIRED_QT_VERSION OPTION is created
22097 QT4_INSTALLED is set to TRUE if qt4 is found.
22098 QT3_INSTALLED is set to TRUE if qt3 is found.
22099 FindUnixCommands
22101 Deprecated since version 3.26: Use ${CMAKE_COMMAND} -E subcommands in‐
22102 stead.
22103 Find Unix commands, including the ones from Cygwin
22106 This module looks for the Unix commands bash, cp, gzip, mv, rm, and tar
22108 and stores the result in the variables BASH, CP, GZIP, MV, RM, and TAR.
22109 FindVTK
22111 This module no longer exists.
22112 This module existed in versions of CMake prior to 3.1, but became only
22114 a thin wrapper around find_package(VTK NO_MODULE) to provide compati‐
22115 bility for projects using long-outdated conventions. Now find_pack‐
22116 age(VTK) will search for VTKConfig.cmake directly.
22117 FindwxWindows
22119 Deprecated since version 3.0: Replaced by FindwxWidgets.
22120 Find wxWindows (wxWidgets) installation
22123 This module finds if wxWindows/wxWidgets is installed and determines
22125 where the include files and libraries are. It also determines what the
22126 name of the library is. This code sets the following variables:
22127 WXWINDOWS_FOUND = system has WxWindows
22129 WXWINDOWS_LIBRARIES = path to the wxWindows libraries
22130 on Unix/Linux with additional
22131 linker flags from
22132 "wx-config --libs"
22133 CMAKE_WXWINDOWS_CXX_FLAGS = Compiler flags for wxWindows,
22134 essentially "`wx-config --cxxflags`"
22135 on Linux
22136 WXWINDOWS_INCLUDE_DIR = where to find "wx/wx.h" and "wx/setup.h"
22137 WXWINDOWS_LINK_DIRECTORIES = link directories, useful for rpath on
22138 Unix
22139 WXWINDOWS_DEFINITIONS = extra defines
22140 OPTIONS If you need OpenGL support please
22142 set(WXWINDOWS_USE_GL 1)
22144 in your CMakeLists.txt before you include this file.
22146 HAVE_ISYSTEM - true required to replace -I by -isystem on g++
22148 For convenience include Use_wxWindows.cmake in your project's CMake‐
22150 Lists.txt using include(${CMAKE_CURRENT_LIST_DIR}/Use_wxWindows.cmake).
22151 USAGE
22153 set(WXWINDOWS_USE_GL 1)
22155 find_package(wxWindows)
22156 NOTES wxWidgets 2.6.x is supported for monolithic builds e.g. compiled
22158 in wx/build/msw dir as:
22159 nmake -f makefile.vc BUILD=debug SHARED=0 USE_OPENGL=1 MONOLITHIC=1
22161 DEPRECATED
22163 CMAKE_WX_CAN_COMPILE
22165 WXWINDOWS_LIBRARY
22166 CMAKE_WX_CXX_FLAGS
22167 WXWINDOWS_INCLUDE_PATH
22168 AUTHOR Jan Woetzel (07/2003-01/2006)
22170 Legacy CPack Modules
22172 These modules used to be mistakenly exposed to the user, and have been
22173 moved out of user visibility. They are for CPack internal use, and
22174 should never be used directly.
22175 CPackArchive
22177 New in version 3.9.
22178 The documentation for the CPack Archive generator has moved here: CPack
22181 Archive Generator
22182 CPackBundle
22184 The documentation for the CPack Bundle generator has moved here: CPack
22185 Bundle Generator
22186 CPackCygwin
22188 The documentation for the CPack Cygwin generator has moved here: CPack
22189 Cygwin Generator
22190 CPackDeb
22192 The documentation for the CPack DEB generator has moved here: CPack DEB
22193 Generator
22194 CPackDMG
22196 The documentation for the CPack DragNDrop generator has moved here:
22197 CPack DragNDrop Generator
22198 CPackFreeBSD
22200 New in version 3.10.
22201 The documentation for the CPack FreeBSD generator has moved here: CPack
22204 FreeBSD Generator
22205 CPackNSIS
22207 The documentation for the CPack NSIS generator has moved here: CPack
22208 NSIS Generator
22209 CPackNuGet
22211 New in version 3.12.
22212 The documentation for the CPack NuGet generator has moved here: CPack
22215 NuGet Generator
22216 CPackProductBuild
22218 New in version 3.7.
22219 The documentation for the CPack productbuild generator has moved here:
22222 CPack productbuild Generator
22223 CPackRPM
22225 The documentation for the CPack RPM generator has moved here: CPack RPM
22226 Generator
22227 CPackWIX
22229 The documentation for the CPack WIX generator has moved here: CPack WIX
22230 Generator
22231
22233 2000-2023 Kitware, Inc. and Contributors
222343.27.7 Oct 07, 2023 CMAKE-MODULES(7)