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> <var>)
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 <var>.
290 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
292 and calls the check_c_source_compiles macro from the CheckCSourceCom‐
293 piles module. See documentation of that module for a listing of vari‐
294 ables that can otherwise modify the build.
295 A positive result from this check indicates only that the compiler did
297 not issue a diagnostic message when given the flag. Whether the flag
298 has any effect or even a specific one is beyond the scope of this mod‐
299 ule.
300 NOTE:
302 Since the try_compile() command forwards flags from variables like
303 CMAKE_C_FLAGS, unknown flags in such variables may cause a false
304 negative for this check.
305 CheckCompilerFlag
307 New in version 3.19.
308 Check whether the compiler supports a given flag.
311 check_compiler_flag
313 check_compiler_flag(<lang> <flag> <var>)
315 Check that the <flag> is accepted by the compiler without a diagnostic.
317 Stores the result in an internal cache entry named <var>.
318 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
320 and calls the check_source_compiles(<LANG>) function from the Check‐
321 SourceCompiles module. See documentation of that module for a listing
322 of variables that can otherwise modify the build.
323 A positive result from this check indicates only that the compiler did
325 not issue a diagnostic message when given the flag. Whether the flag
326 has any effect or even a specific one is beyond the scope of this mod‐
327 ule.
328 NOTE:
330 Since the try_compile() command forwards flags from variables like
331 CMAKE_<LANG>_FLAGS, unknown flags in such variables may cause a
332 false negative for this check.
333 CheckCSourceCompiles
335 Check if given C source compiles and links into an executable.
336 check_c_source_compiles
338 check_c_source_compiles(<code> <resultVar>
340 [FAIL_REGEX <regex1> [<regex2>...]])
341 Check that the source supplied in <code> can be compiled as a C
343 source file and linked as an executable (so it must contain at
344 least a main() function). The result will be stored in the in‐
345 ternal cache variable specified by <resultVar>, with a boolean
346 true value for success and boolean false for failure. If
347 FAIL_REGEX is provided, then failure is determined by checking
348 if anything in the output matches any of the specified regular
349 expressions.
350 The underlying check is performed by the try_compile() command.
352 The compile and link commands can be influenced by setting any
353 of the following variables prior to calling check_c_source_com‐
354 piles():
355 CMAKE_REQUIRED_FLAGS
357 Additional flags to pass to the compiler. Note that the
358 contents of CMAKE_C_FLAGS and its associated configura‐
359 tion-specific variable are automatically added to the
360 compiler command before the contents of CMAKE_RE‐
361 QUIRED_FLAGS.
362 CMAKE_REQUIRED_DEFINITIONS
364 A ;-list of compiler definitions of the form -DFOO or
365 -DFOO=bar. A definition for the name specified by <re‐
366 sultVar> will also be added automatically.
367 CMAKE_REQUIRED_INCLUDES
369 A ;-list of header search paths to pass to the compiler.
370 These will be the only header search paths used by
371 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
372 RIES directory property will be ignored.
373 CMAKE_REQUIRED_LINK_OPTIONS
375 New in version 3.14.
376 A ;-list of options to add to the link command (see
379 try_compile() for further details).
380 CMAKE_REQUIRED_LIBRARIES
382 A ;-list of libraries to add to the link command. These
383 can be the name of system libraries or they can be Im‐
384 ported Targets (see try_compile() for further details).
385 CMAKE_REQUIRED_QUIET
387 New in version 3.1.
388 If this variable evaluates to a boolean true value, all
391 status messages associated with the check will be sup‐
392 pressed.
393 The check is only performed once, with the result cached in the
395 variable named by <resultVar>. Every subsequent CMake run will
396 re-use this cached value rather than performing the check again,
397 even if the <code> changes. In order to force the check to be
398 re-evaluated, the variable named by <resultVar> must be manually
399 removed from the cache.
400 CheckCSourceRuns
402 Check if given C source compiles and links into an executable and can
403 subsequently be run.
404 check_c_source_runs
406 check_c_source_runs(<code> <resultVar>)
408 Check that the source supplied in <code> can be compiled as a C
410 source file, linked as an executable and then run. The <code>
411 must contain at least a main() function. If the <code> could be
412 built and run successfully, the internal cache variable speci‐
413 fied by <resultVar> will be set to 1, otherwise it will be set
414 to an value that evaluates to boolean false (e.g. an empty
415 string or an error message).
416 The underlying check is performed by the try_run() command. The
418 compile and link commands can be influenced by setting any of
419 the following variables prior to calling check_c_source_runs():
420 CMAKE_REQUIRED_FLAGS
422 Additional flags to pass to the compiler. Note that the
423 contents of CMAKE_C_FLAGS and its associated configura‐
424 tion-specific variable are automatically added to the
425 compiler command before the contents of CMAKE_RE‐
426 QUIRED_FLAGS.
427 CMAKE_REQUIRED_DEFINITIONS
429 A ;-list of compiler definitions of the form -DFOO or
430 -DFOO=bar. A definition for the name specified by <re‐
431 sultVar> will also be added automatically.
432 CMAKE_REQUIRED_INCLUDES
434 A ;-list of header search paths to pass to the compiler.
435 These will be the only header search paths used by
436 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
437 directory property will be ignored.
438 CMAKE_REQUIRED_LINK_OPTIONS
440 New in version 3.14.
441 A ;-list of options to add to the link command (see
444 try_run() for further details).
445 CMAKE_REQUIRED_LIBRARIES
447 A ;-list of libraries to add to the link command. These
448 can be the name of system libraries or they can be Im‐
449 ported Targets (see try_run() for further details).
450 CMAKE_REQUIRED_QUIET
452 New in version 3.1.
453 If this variable evaluates to a boolean true value, all
456 status messages associated with the check will be sup‐
457 pressed.
458 The check is only performed once, with the result cached in the
460 variable named by <resultVar>. Every subsequent CMake run will
461 re-use this cached value rather than performing the check again,
462 even if the <code> changes. In order to force the check to be
463 re-evaluated, the variable named by <resultVar> must be manually
464 removed from the cache.
465 CheckCXXCompilerFlag
467 Check whether the CXX compiler supports a given flag.
468 check_cxx_compiler_flag
470 check_cxx_compiler_flag(<flag> <var>)
472 Check that the <flag> is accepted by the compiler without a di‐
474 agnostic. Stores the result in an internal cache entry named
475 <var>.
476 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
478 and calls the check_cxx_source_compiles macro from the CheckCXXSource‐
479 Compiles module. See documentation of that module for a listing of
480 variables that can otherwise modify the build.
481 A positive result from this check indicates only that the compiler did
483 not issue a diagnostic message when given the flag. Whether the flag
484 has any effect or even a specific one is beyond the scope of this mod‐
485 ule.
486 NOTE:
488 Since the try_compile() command forwards flags from variables like
489 CMAKE_CXX_FLAGS, unknown flags in such variables may cause a false
490 negative for this check.
491 CheckCXXSourceCompiles
493 Check if given C++ source compiles and links into an executable.
494 check_cxx_source_compiles
496 check_cxx_source_compiles(<code> <resultVar>
498 [FAIL_REGEX <regex1> [<regex2>...]])
499 Check that the source supplied in <code> can be compiled as a
501 C++ source file and linked as an executable (so it must contain
502 at least a main() function). The result will be stored in the
503 internal cache variable specified by <resultVar>, with a boolean
504 true value for success and boolean false for failure. If
505 FAIL_REGEX is provided, then failure is determined by checking
506 if anything in the output matches any of the specified regular
507 expressions.
508 The underlying check is performed by the try_compile() command.
510 The compile and link commands can be influenced by setting any
511 of the following variables prior to calling
512 check_cxx_source_compiles():
513 CMAKE_REQUIRED_FLAGS
515 Additional flags to pass to the compiler. Note that the
516 contents of CMAKE_CXX_FLAGS and its associated configura‐
517 tion-specific variable are automatically added to the
518 compiler command before the contents of CMAKE_RE‐
519 QUIRED_FLAGS.
520 CMAKE_REQUIRED_DEFINITIONS
522 A ;-list of compiler definitions of the form -DFOO or
523 -DFOO=bar. A definition for the name specified by <re‐
524 sultVar> will also be added automatically.
525 CMAKE_REQUIRED_INCLUDES
527 A ;-list of header search paths to pass to the compiler.
528 These will be the only header search paths used by
529 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
530 RIES directory property will be ignored.
531 CMAKE_REQUIRED_LINK_OPTIONS
533 New in version 3.14.
534 A ;-list of options to add to the link command (see
537 try_compile() for further details).
538 CMAKE_REQUIRED_LIBRARIES
540 A ;-list of libraries to add to the link command. These
541 can be the name of system libraries or they can be Im‐
542 ported Targets (see try_compile() for further details).
543 CMAKE_REQUIRED_QUIET
545 New in version 3.1.
546 If this variable evaluates to a boolean true value, all
549 status messages associated with the check will be sup‐
550 pressed.
551 The check is only performed once, with the result cached in the
553 variable named by <resultVar>. Every subsequent CMake run will
554 re-use this cached value rather than performing the check again,
555 even if the <code> changes. In order to force the check to be
556 re-evaluated, the variable named by <resultVar> must be manually
557 removed from the cache.
558 CheckCXXSourceRuns
560 Check if given C++ source compiles and links into an executable and can
561 subsequently be run.
562 check_cxx_source_runs
564 check_cxx_source_runs(<code> <resultVar>)
566 Check that the source supplied in <code> can be compiled as a
568 C++ source file, linked as an executable and then run. The
569 <code> must contain at least a main() function. If the <code>
570 could be built and run successfully, the internal cache variable
571 specified by <resultVar> will be set to 1, otherwise it will be
572 set to an value that evaluates to boolean false (e.g. an empty
573 string or an error message).
574 The underlying check is performed by the try_run() command. The
576 compile and link commands can be influenced by setting any of
577 the following variables prior to calling
578 check_cxx_source_runs():
579 CMAKE_REQUIRED_FLAGS
581 Additional flags to pass to the compiler. Note that the
582 contents of CMAKE_CXX_FLAGS and its associated configura‐
583 tion-specific variable are automatically added to the
584 compiler command before the contents of CMAKE_RE‐
585 QUIRED_FLAGS.
586 CMAKE_REQUIRED_DEFINITIONS
588 A ;-list of compiler definitions of the form -DFOO or
589 -DFOO=bar. A definition for the name specified by <re‐
590 sultVar> will also be added automatically.
591 CMAKE_REQUIRED_INCLUDES
593 A ;-list of header search paths to pass to the compiler.
594 These will be the only header search paths used by
595 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
596 directory property will be ignored.
597 CMAKE_REQUIRED_LINK_OPTIONS
599 New in version 3.14.
600 A ;-list of options to add to the link command (see
603 try_run() for further details).
604 CMAKE_REQUIRED_LIBRARIES
606 A ;-list of libraries to add to the link command. These
607 can be the name of system libraries or they can be Im‐
608 ported Targets (see try_run() for further details).
609 CMAKE_REQUIRED_QUIET
611 New in version 3.1.
612 If this variable evaluates to a boolean true value, all
615 status messages associated with the check will be sup‐
616 pressed.
617 The check is only performed once, with the result cached in the
619 variable named by <resultVar>. Every subsequent CMake run will
620 re-use this cached value rather than performing the check again,
621 even if the <code> changes. In order to force the check to be
622 re-evaluated, the variable named by <resultVar> must be manually
623 removed from the cache.
624 CheckCXXSymbolExists
626 Check if a symbol exists as a function, variable, or macro in C++.
627 check_cxx_symbol_exists
629 check_cxx_symbol_exists(<symbol> <files> <variable>)
631 Check that the <symbol> is available after including given
633 header <files> and store the result in a <variable>. Specify
634 the list of files in one argument as a semicolon-separated list.
635 check_cxx_symbol_exists() can be used to check for symbols as
636 seen by the C++ compiler, as opposed to check_symbol_exists(),
637 which always uses the C compiler.
638 If the header files define the symbol as a macro it is consid‐
640 ered available and assumed to work. If the header files declare
641 the symbol as a function or variable then the symbol must also
642 be available for linking. If the symbol is a type, enum value,
643 or C++ template it will not be recognized: consider using the
644 CheckTypeSize or CheckSourceCompiles module instead.
645 NOTE:
647 This command is unreliable when <symbol> is (potentially) an over‐
648 loaded function. Since there is no reliable way to predict whether a
649 given function in the system environment may be defined as an over‐
650 loaded function or may be an overloaded function on other systems or
651 will become so in the future, it is generally advised to use the
652 CheckCXXSourceCompiles module for checking any function symbol (un‐
653 less somehow you surely know the checked function is not overloaded
654 on other systems or will not be so in the future).
655 The following variables may be set before calling this macro to modify
657 the way the check is run:
658 CMAKE_REQUIRED_FLAGS
660 string of compile command line flags.
661 CMAKE_REQUIRED_DEFINITIONS
663 a ;-list of macros to define (-DFOO=bar).
664 CMAKE_REQUIRED_INCLUDES
666 a ;-list of header search paths to pass to the compiler.
667 CMAKE_REQUIRED_LINK_OPTIONS
669 New in version 3.14: a ;-list of options to add to the link com‐
670 mand.
671 CMAKE_REQUIRED_LIBRARIES
674 a ;-list of libraries to add to the link command. See policy
675 CMP0075.
676 CMAKE_REQUIRED_QUIET
678 New in version 3.1: execute quietly without messages.
679 For example:
682 include(CheckCXXSymbolExists)
684 # Check for macro SEEK_SET
686 check_cxx_symbol_exists(SEEK_SET "cstdio" HAVE_SEEK_SET)
687 # Check for function std::fopen
688 check_cxx_symbol_exists(std::fopen "cstdio" HAVE_STD_FOPEN)
689 CheckFortranCompilerFlag
691 New in version 3.3.
692 Check whether the Fortran compiler supports a given flag.
695 check_fortran_compiler_flag
697 check_fortran_compiler_flag(<flag> <var>)
699 Check that the <flag> is accepted by the compiler without a di‐
701 agnostic. Stores the result in an internal cache entry named
702 <var>.
703 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
705 and calls the check_fortran_source_compiles macro from the CheckFor‐
706 tranSourceCompiles module. See documentation of that module for a
707 listing of variables that can otherwise modify the build.
708 A positive result from this check indicates only that the compiler did
710 not issue a diagnostic message when given the flag. Whether the flag
711 has any effect or even a specific one is beyond the scope of this mod‐
712 ule.
713 NOTE:
715 Since the try_compile() command forwards flags from variables like
716 CMAKE_Fortran_FLAGS, unknown flags in such variables may cause a
717 false negative for this check.
718 CheckFortranFunctionExists
720 Check if a Fortran function exists.
721 CHECK_FORTRAN_FUNCTION_EXISTS
723 CHECK_FORTRAN_FUNCTION_EXISTS(<function> <result>)
725 where
727 <function>
729 the name of the Fortran function
730 <result>
732 variable to store the result; will be created as an in‐
733 ternal cache variable.
734 NOTE:
736 This command does not detect functions in Fortran modules. In gen‐
737 eral it is recommended to use CheckSourceCompiles instead to deter‐
738 mine if a Fortran function or subroutine is available.
739 The following variables may be set before calling this macro to modify
741 the way the check is run:
742 CMAKE_REQUIRED_LINK_OPTIONS
744 New in version 3.14: A ;-list of options to add to the link com‐
745 mand (see try_compile() for further details).
746 CMAKE_REQUIRED_LIBRARIES
749 A ;-list of libraries to add to the link command. These can be
750 the name of system libraries or they can be Imported Targets
751 (see try_compile() for further details).
752 CheckFortranSourceCompiles
754 New in version 3.1.
755 Check if given Fortran source compiles and links into an executable.
758 check_fortran_source_compiles
760 check_fortran_source_compiles(<code> <resultVar>
762 [FAIL_REGEX <regex>...]
763 [SRC_EXT <extension>]
764 )
765 Checks that the source supplied in <code> can be compiled as a
767 Fortran source file and linked as an executable. The <code> must
768 be a Fortran program containing at least an end statement--for
769 example:
770 check_fortran_source_compiles("character :: b; error stop b; end" F2018ESTOPOK SRC_EXT F90)
772 This command can help avoid costly build processes when a com‐
774 piler lacks support for a necessary feature, or a particular
775 vendor library is not compatible with the Fortran compiler ver‐
776 sion being used. This generate-time check may advise the user of
777 such before the main build process. See also the check_for‐
778 tran_source_runs() command to actually run the compiled code.
779 The result will be stored in the internal cache variable <re‐
781 sultVar>, with a boolean true value for success and boolean
782 false for failure.
783 If FAIL_REGEX is provided, then failure is determined by check‐
785 ing if anything in the output matches any of the specified regu‐
786 lar expressions.
787 By default, the test source file will be given a .F file exten‐
789 sion. The SRC_EXT option can be used to override this with .<ex‐
790 tension> instead-- .F90 is a typical choice.
791 The underlying check is performed by the try_compile() command.
793 The compile and link commands can be influenced by setting any
794 of the following variables prior to calling check_for‐
795 tran_source_compiles():
796 CMAKE_REQUIRED_FLAGS
798 Additional flags to pass to the compiler. Note that the
799 contents of CMAKE_Fortran_FLAGS and its associated con‐
800 figuration-specific variable are automatically added to
801 the compiler command before the contents of CMAKE_RE‐
802 QUIRED_FLAGS.
803 CMAKE_REQUIRED_DEFINITIONS
805 A ;-list of compiler definitions of the form -DFOO or
806 -DFOO=bar. A definition for the name specified by <re‐
807 sultVar> will also be added automatically.
808 CMAKE_REQUIRED_INCLUDES
810 A ;-list of header search paths to pass to the compiler.
811 These will be the only header search paths used by
812 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
813 RIES directory property will be ignored.
814 CMAKE_REQUIRED_LINK_OPTIONS
816 New in version 3.14.
817 A ;-list of options to add to the link command (see
820 try_compile() for further details).
821 CMAKE_REQUIRED_LIBRARIES
823 A ;-list of libraries to add to the link command. These
824 can be the name of system libraries or they can be Im‐
825 ported Targets (see try_compile() for further details).
826 CMAKE_REQUIRED_QUIET
828 If this variable evaluates to a boolean true value, all
829 status messages associated with the check will be sup‐
830 pressed.
831 The check is only performed once, with the result cached in the
833 variable named by <resultVar>. Every subsequent CMake run will
834 re-use this cached value rather than performing the check again,
835 even if the <code> changes. In order to force the check to be
836 re-evaluated, the variable named by <resultVar> must be manually
837 removed from the cache.
838 CheckFortranSourceRuns
840 New in version 3.14.
841 Check if given Fortran source compiles and links into an executable and
844 can subsequently be run.
845 check_fortran_source_runs
847 check_fortran_source_runs(<code> <resultVar>
849 [SRC_EXT <extension>])
850 Check that the source supplied in <code> can be compiled as a
852 Fortran source file, linked as an executable and then run. The
853 <code> must be a Fortran program containing at least an end
854 statement--for example:
855 check_fortran_source_runs("real :: x[*]; call co_sum(x); end" F2018coarrayOK)
857 This command can help avoid costly build processes when a com‐
859 piler lacks support for a necessary feature, or a particular
860 vendor library is not compatible with the Fortran compiler ver‐
861 sion being used. Some of these failures only occur at runtime
862 instead of linktime, and a trivial runtime example can catch the
863 issue before the main build process.
864 If the <code> could be built and run successfully, the internal
866 cache variable specified by <resultVar> will be set to 1, other‐
867 wise it will be set to an value that evaluates to boolean false
868 (e.g. an empty string or an error message).
869 By default, the test source file will be given a .F90 file ex‐
871 tension. The SRC_EXT option can be used to override this with
872 .<extension> instead.
873 The underlying check is performed by the try_run() command. The
875 compile and link commands can be influenced by setting any of
876 the following variables prior to calling check_for‐
877 tran_source_runs():
878 CMAKE_REQUIRED_FLAGS
880 Additional flags to pass to the compiler. Note that the
881 contents of CMAKE_Fortran_FLAGS and its associated con‐
882 figuration-specific variable are automatically added to
883 the compiler command before the contents of CMAKE_RE‐
884 QUIRED_FLAGS.
885 CMAKE_REQUIRED_DEFINITIONS
887 A ;-list of compiler definitions of the form -DFOO or
888 -DFOO=bar. A definition for the name specified by <re‐
889 sultVar> will also be added automatically.
890 CMAKE_REQUIRED_INCLUDES
892 A ;-list of header search paths to pass to the compiler.
893 These will be the only header search paths used by
894 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
895 directory property will be ignored.
896 CMAKE_REQUIRED_LINK_OPTIONS
898 A ;-list of options to add to the link command (see
899 try_run() for further details).
900 CMAKE_REQUIRED_LIBRARIES
902 A ;-list of libraries to add to the link command. These
903 can be the name of system libraries or they can be Im‐
904 ported Targets (see try_run() for further details).
905 CMAKE_REQUIRED_QUIET
907 If this variable evaluates to a boolean true value, all
908 status messages associated with the check will be sup‐
909 pressed.
910 The check is only performed once, with the result cached in the
912 variable named by <resultVar>. Every subsequent CMake run will
913 re-use this cached value rather than performing the check again,
914 even if the <code> changes. In order to force the check to be
915 re-evaluated, the variable named by <resultVar> must be manually
916 removed from the cache.
917 CheckFunctionExists
919 Check if a C function can be linked
920 check_function_exists
922 check_function_exists(<function> <variable>)
924 Checks that the <function> is provided by libraries on the sys‐
926 tem and store the result in a <variable>, which will be created
927 as an internal cache variable.
928 The following variables may be set before calling this macro to modify
930 the way the check is run:
931 CMAKE_REQUIRED_FLAGS
933 string of compile command line flags.
934 CMAKE_REQUIRED_DEFINITIONS
936 a ;-list of macros to define (-DFOO=bar).
937 CMAKE_REQUIRED_INCLUDES
939 a ;-list of header search paths to pass to the compiler.
940 CMAKE_REQUIRED_LINK_OPTIONS
942 New in version 3.14: a ;-list of options to add to the link com‐
943 mand.
944 CMAKE_REQUIRED_LIBRARIES
947 a ;-list of libraries to add to the link command. See policy
948 CMP0075.
949 CMAKE_REQUIRED_QUIET
951 New in version 3.1: execute quietly without messages.
952 NOTE:
955 Prefer using CheckSymbolExists instead of this module, for the fol‐
956 lowing reasons:
957 • check_function_exists() can't detect functions that are inlined in
959 headers or specified as a macro.
960 • check_function_exists() can't detect anything in the 32-bit ver‐
962 sions of the Win32 API, because of a mismatch in calling conven‐
963 tions.
964 • check_function_exists() only verifies linking, it does not verify
966 that the function is declared in system headers.
967 CheckIncludeFileCXX
969 Provides a macro to check if a header file can be included in CXX.
970 CHECK_INCLUDE_FILE_CXX
972 CHECK_INCLUDE_FILE_CXX(<include> <variable> [<flags>])
974 Check if the given <include> file may be included in a CXX
976 source file and store the result in an internal cache entry
977 named <variable>. The optional third argument may be used to
978 add compilation flags to the check (or use CMAKE_REQUIRED_FLAGS
979 below).
980 The following variables may be set before calling this macro to modify
982 the way the check is run:
983 CMAKE_REQUIRED_FLAGS
985 string of compile command line flags.
986 CMAKE_REQUIRED_DEFINITIONS
988 a ;-list of macros to define (-DFOO=bar).
989 CMAKE_REQUIRED_INCLUDES
991 a ;-list of header search paths to pass to the compiler.
992 CMAKE_REQUIRED_LINK_OPTIONS
994 New in version 3.14: a ;-list of options to add to the link com‐
995 mand.
996 CMAKE_REQUIRED_LIBRARIES
999 a ;-list of libraries to add to the link command. See policy
1000 CMP0075.
1001 CMAKE_REQUIRED_QUIET
1003 New in version 3.1: execute quietly without messages.
1004 See modules CheckIncludeFile and CheckIncludeFiles to check for one or
1007 more C headers.
1008 CheckIncludeFile
1010 Provides a macro to check if a header file can be included in C.
1011 CHECK_INCLUDE_FILE
1013 CHECK_INCLUDE_FILE(<include> <variable> [<flags>])
1015 Check if the given <include> file may be included in a C source
1017 file and store the result in an internal cache entry named
1018 <variable>. The optional third argument may be used to add com‐
1019 pilation flags to the check (or use CMAKE_REQUIRED_FLAGS below).
1020 The following variables may be set before calling this macro to modify
1022 the way the check is run:
1023 CMAKE_REQUIRED_FLAGS
1025 string of compile command line flags.
1026 CMAKE_REQUIRED_DEFINITIONS
1028 a ;-list of macros to define (-DFOO=bar).
1029 CMAKE_REQUIRED_INCLUDES
1031 a ;-list of header search paths to pass to the compiler.
1032 CMAKE_REQUIRED_LINK_OPTIONS
1034 New in version 3.14: a ;-list of options to add to the link com‐
1035 mand.
1036 CMAKE_REQUIRED_LIBRARIES
1039 a ;-list of libraries to add to the link command. See policy
1040 CMP0075.
1041 CMAKE_REQUIRED_QUIET
1043 New in version 3.1: execute quietly without messages.
1044 See the CheckIncludeFiles module to check for multiple headers at once.
1047 See the CheckIncludeFileCXX module to check for headers using the CXX
1048 language.
1049 CheckIncludeFiles
1051 Provides a macro to check if a list of one or more header files can be
1052 included together.
1053 CHECK_INCLUDE_FILES
1055 CHECK_INCLUDE_FILES("<includes>" <variable> [LANGUAGE <language>])
1057 Check if the given <includes> list may be included together in a
1059 source file and store the result in an internal cache entry
1060 named <variable>. Specify the <includes> argument as a ;-list
1061 of header file names.
1062 If LANGUAGE is set, the specified compiler will be used to per‐
1064 form the check. Acceptable values are C and CXX. If not set, the
1065 C compiler will be used if enabled. If the C compiler is not en‐
1066 abled, the C++ compiler will be used if enabled.
1067 The following variables may be set before calling this macro to modify
1069 the way the check is run:
1070 CMAKE_REQUIRED_FLAGS
1072 string of compile command line flags.
1073 CMAKE_REQUIRED_DEFINITIONS
1075 a ;-list of macros to define (-DFOO=bar).
1076 CMAKE_REQUIRED_INCLUDES
1078 a ;-list of header search paths to pass to the compiler.
1079 CMAKE_REQUIRED_LINK_OPTIONS
1081 New in version 3.14: a ;-list of options to add to the link com‐
1082 mand.
1083 CMAKE_REQUIRED_LIBRARIES
1086 a ;-list of libraries to add to the link command. See policy
1087 CMP0075.
1088 CMAKE_REQUIRED_QUIET
1090 New in version 3.1: execute quietly without messages.
1091 See modules CheckIncludeFile and CheckIncludeFileCXX to check for a
1094 single header file in C or CXX languages.
1095 CheckIPOSupported
1097 New in version 3.9.
1098 Check whether the compiler supports an interprocedural optimization
1101 (IPO/LTO). Use this before enabling the INTERPROCEDURAL_OPTIMIZATION
1102 target property.
1103 check_ipo_supported
1105 check_ipo_supported([RESULT <result>] [OUTPUT <output>]
1107 [LANGUAGES <lang>...])
1108 Options are:
1110 RESULT <result>
1112 Set <result> variable to YES if IPO is supported by the
1113 compiler and NO otherwise. If this option is not given
1114 then the command will issue a fatal error if IPO is not
1115 supported.
1116 OUTPUT <output>
1118 Set <output> variable with details about any error.
1119 LANGUAGES <lang>...
1121 Specify languages whose compilers to check. Languages C,
1122 CXX, and Fortran are supported.
1123 It makes no sense to use this module when CMP0069 is set to OLD so mod‐
1125 ule will return error in this case. See policy CMP0069 for details.
1126 New in version 3.13: Add support for Visual Studio generators.
1128 Examples
1131 check_ipo_supported() # fatal error if IPO is not supported
1132 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
1133 # Optional IPO. Do not use IPO if it's not supported by compiler.
1135 check_ipo_supported(RESULT result OUTPUT output)
1136 if(result)
1137 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
1138 else()
1139 message(WARNING "IPO is not supported: ${output}")
1140 endif()
1141 CheckLanguage
1143 Check if a language can be enabled
1144 Usage:
1146 check_language(<lang>)
1148 where <lang> is a language that may be passed to enable_language() such
1150 as Fortran. If CMAKE_<LANG>_COMPILER is already defined the check does
1151 nothing. Otherwise it tries enabling the language in a test project.
1152 The result is cached in CMAKE_<LANG>_COMPILER as the compiler that was
1153 found, or NOTFOUND if the language cannot be enabled. For CUDA which
1154 can have an explicit host compiler, the cache CMAKE_CUDA_HOST_COMPILER
1155 variable will be set if it was required for compilation (and cleared if
1156 it was not).
1157 Example:
1159 check_language(Fortran)
1161 if(CMAKE_Fortran_COMPILER)
1162 enable_language(Fortran)
1163 else()
1164 message(STATUS "No Fortran support")
1165 endif()
1166 CheckLibraryExists
1168 Check if the function exists.
1169 CHECK_LIBRARY_EXISTS
1171 CHECK_LIBRARY_EXISTS(LIBRARY FUNCTION LOCATION VARIABLE)
1173 LIBRARY - the name of the library you are looking for
1175 FUNCTION - the name of the function
1176 LOCATION - location where the library should be found
1177 VARIABLE - variable to store the result
1178 Will be created as an internal cache variable.
1179 The following variables may be set before calling this macro to modify
1181 the way the check is run:
1182 CMAKE_REQUIRED_FLAGS
1184 string of compile command line flags.
1185 CMAKE_REQUIRED_DEFINITIONS
1187 list of macros to define (-DFOO=bar).
1188 CMAKE_REQUIRED_LINK_OPTIONS
1190 New in version 3.14: list of options to pass to link command.
1191 CMAKE_REQUIRED_LIBRARIES
1194 list of libraries to link.
1195 CMAKE_REQUIRED_QUIET
1197 New in version 3.1: execute quietly without messages.
1198 CheckLinkerFlag
1201 New in version 3.18.
1202 Check whether the compiler supports a given link flag.
1205 check_linker_flag
1207 check_linker_flag(<lang> <flag> <var>)
1209 Check that the link <flag> is accepted by the <lang> compiler without a
1211 diagnostic. Stores the result in an internal cache entry named <var>.
1212 This command temporarily sets the CMAKE_REQUIRED_LINK_OPTIONS variable
1214 and calls the check_source_compiles() command from the CheckSourceCom‐
1215 piles module. See that module's documentation for a listing of vari‐
1216 ables that can otherwise modify the build.
1217 The underlying implementation relies on the LINK_OPTIONS property to
1219 check the specified flag. The LINKER: prefix, as described in the tar‐
1220 get_link_options() command, can be used as well.
1221 A positive result from this check indicates only that the compiler did
1223 not issue a diagnostic message when given the link flag. Whether the
1224 flag has any effect or even a specific one is beyond the scope of this
1225 module.
1226 NOTE:
1228 Since the try_compile() command forwards flags from variables like
1229 CMAKE_<LANG>_FLAGS, unknown flags in such variables may cause a
1230 false negative for this check.
1231 CheckOBJCCompilerFlag
1233 New in version 3.16.
1234 Check whether the Objective-C compiler supports a given flag.
1237 check_objc_compiler_flag
1239 check_objc_compiler_flag(<flag> <var>)
1241 Check that the <flag> is accepted by the compiler without a di‐
1243 agnostic. Stores the result in an internal cache entry named
1244 <var>.
1245 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
1247 and calls the check_objc_source_compiles macro from the CheckOBJC‐
1248 SourceCompiles module. See documentation of that module for a listing
1249 of variables that can otherwise modify the build.
1250 A positive result from this check indicates only that the compiler did
1252 not issue a diagnostic message when given the flag. Whether the flag
1253 has any effect or even a specific one is beyond the scope of this mod‐
1254 ule.
1255 NOTE:
1257 Since the try_compile() command forwards flags from variables like
1258 CMAKE_OBJC_FLAGS, unknown flags in such variables may cause a false
1259 negative for this check.
1260 CheckOBJCSourceCompiles
1262 New in version 3.16.
1263 Check if given Objective-C source compiles and links into an exe‐
1266 cutable.
1267 check_objc_source_compiles
1269 check_objc_source_compiles(<code> <resultVar>
1271 [FAIL_REGEX <regex1> [<regex2>...]])
1272 Check that the source supplied in <code> can be compiled as a
1274 Objectie-C source file and linked as an executable (so it must
1275 contain at least a main() function). The result will be stored
1276 in the internal cache variable specified by <resultVar>, with a
1277 boolean true value for success and boolean false for failure. If
1278 FAIL_REGEX is provided, then failure is determined by checking
1279 if anything in the output matches any of the specified regular
1280 expressions.
1281 The underlying check is performed by the try_compile() command.
1283 The compile and link commands can be influenced by setting any
1284 of the following variables prior to calling
1285 check_objc_source_compiles():
1286 CMAKE_REQUIRED_FLAGS
1288 Additional flags to pass to the compiler. Note that the
1289 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1290 ration-specific variable are automatically added to the
1291 compiler command before the contents of CMAKE_RE‐
1292 QUIRED_FLAGS.
1293 CMAKE_REQUIRED_DEFINITIONS
1295 A ;-list of compiler definitions of the form -DFOO or
1296 -DFOO=bar. A definition for the name specified by <re‐
1297 sultVar> will also be added automatically.
1298 CMAKE_REQUIRED_INCLUDES
1300 A ;-list of header search paths to pass to the compiler.
1301 These will be the only header search paths used by
1302 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1303 RIES directory property will be ignored.
1304 CMAKE_REQUIRED_LINK_OPTIONS
1306 A ;-list of options to add to the link command (see
1307 try_compile() for further details).
1308 CMAKE_REQUIRED_LIBRARIES
1310 A ;-list of libraries to add to the link command. These
1311 can be the name of system libraries or they can be Im‐
1312 ported Targets (see try_compile() for further details).
1313 CMAKE_REQUIRED_QUIET
1315 If this variable evaluates to a boolean true value, all
1316 status messages associated with the check will be sup‐
1317 pressed.
1318 The check is only performed once, with the result cached in the
1320 variable named by <resultVar>. Every subsequent CMake run will
1321 re-use this cached value rather than performing the check again,
1322 even if the <code> changes. In order to force the check to be
1323 re-evaluated, the variable named by <resultVar> must be manually
1324 removed from the cache.
1325 CheckOBJCSourceRuns
1327 New in version 3.16.
1328 Check if given Objective-C source compiles and links into an executable
1331 and can subsequently be run.
1332 check_objc_source_runs
1334 check_objc_source_runs(<code> <resultVar>)
1336 Check that the source supplied in <code> can be compiled as a
1338 Objective-C source file, linked as an executable and then run.
1339 The <code> must contain at least a main() function. If the
1340 <code> could be built and run successfully, the internal cache
1341 variable specified by <resultVar> will be set to 1, otherwise it
1342 will be set to an value that evaluates to boolean false (e.g. an
1343 empty string or an error message).
1344 The underlying check is performed by the try_run() command. The
1346 compile and link commands can be influenced by setting any of
1347 the following variables prior to calling
1348 check_objc_source_runs():
1349 CMAKE_REQUIRED_FLAGS
1351 Additional flags to pass to the compiler. Note that the
1352 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1353 ration-specific variable are automatically added to the
1354 compiler command before the contents of CMAKE_RE‐
1355 QUIRED_FLAGS.
1356 CMAKE_REQUIRED_DEFINITIONS
1358 A ;-list of compiler definitions of the form -DFOO or
1359 -DFOO=bar. A definition for the name specified by <re‐
1360 sultVar> will also be added automatically.
1361 CMAKE_REQUIRED_INCLUDES
1363 A ;-list of header search paths to pass to the compiler.
1364 These will be the only header search paths used by
1365 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1366 directory property will be ignored.
1367 CMAKE_REQUIRED_LINK_OPTIONS
1369 A ;-list of options to add to the link command (see
1370 try_run() for further details).
1371 CMAKE_REQUIRED_LIBRARIES
1373 A ;-list of libraries to add to the link command. These
1374 can be the name of system libraries or they can be Im‐
1375 ported Targets (see try_run() for further details).
1376 CMAKE_REQUIRED_QUIET
1378 If this variable evaluates to a boolean true value, all
1379 status messages associated with the check will be sup‐
1380 pressed.
1381 The check is only performed once, with the result cached in the
1383 variable named by <resultVar>. Every subsequent CMake run will
1384 re-use this cached value rather than performing the check again,
1385 even if the <code> changes. In order to force the check to be
1386 re-evaluated, the variable named by <resultVar> must be manually
1387 removed from the cache.
1388 CheckOBJCXXCompilerFlag
1390 New in version 3.16.
1391 Check whether the Objective-C++ compiler supports a given flag.
1394 check_objcxx_compiler_flag
1396 check_objcxx_compiler_flag(<flag> <var>)
1398 Check that the <flag> is accepted by the compiler without a di‐
1400 agnostic. Stores the result in an internal cache entry named
1401 <var>.
1402 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
1404 and calls the check_objcxx_source_compiles macro from the CheckOB‐
1405 JCXXSourceCompiles module. See documentation of that module for a
1406 listing of variables that can otherwise modify the build.
1407 A positive result from this check indicates only that the compiler did
1409 not issue a diagnostic message when given the flag. Whether the flag
1410 has any effect or even a specific one is beyond the scope of this mod‐
1411 ule.
1412 NOTE:
1414 Since the try_compile() command forwards flags from variables like
1415 CMAKE_OBJCXX_FLAGS, unknown flags in such variables may cause a
1416 false negative for this check.
1417 CheckOBJCXXSourceCompiles
1419 New in version 3.16.
1420 Check if given Objective-C++ source compiles and links into an exe‐
1423 cutable.
1424 check_objcxx_source_compiles
1426 check_objcxx_source_compiles(<code> <resultVar>
1428 [FAIL_REGEX <regex1> [<regex2>...]])
1429 Check that the source supplied in <code> can be compiled as a
1431 Objective-C++ source file and linked as an executable (so it
1432 must contain at least a main() function). The result will be
1433 stored in the internal cache variable specified by <resultVar>,
1434 with a boolean true value for success and boolean false for
1435 failure. If FAIL_REGEX is provided, then failure is determined
1436 by checking if anything in the output matches any of the speci‐
1437 fied regular expressions.
1438 The underlying check is performed by the try_compile() command.
1440 The compile and link commands can be influenced by setting any
1441 of the following variables prior to calling check_ob‐
1442 jcxx_source_compiles():
1443 CMAKE_REQUIRED_FLAGS
1445 Additional flags to pass to the compiler. Note that the
1446 contents of CMAKE_OBJCXX_FLAGS and its associated config‐
1447 uration-specific variable are automatically added to the
1448 compiler command before the contents of CMAKE_RE‐
1449 QUIRED_FLAGS.
1450 CMAKE_REQUIRED_DEFINITIONS
1452 A ;-list of compiler definitions of the form -DFOO or
1453 -DFOO=bar. A definition for the name specified by <re‐
1454 sultVar> will also be added automatically.
1455 CMAKE_REQUIRED_INCLUDES
1457 A ;-list of header search paths to pass to the compiler.
1458 These will be the only header search paths used by
1459 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1460 RIES directory property will be ignored.
1461 CMAKE_REQUIRED_LINK_OPTIONS
1463 A ;-list of options to add to the link command (see
1464 try_compile() for further details).
1465 CMAKE_REQUIRED_LIBRARIES
1467 A ;-list of libraries to add to the link command. These
1468 can be the name of system libraries or they can be Im‐
1469 ported Targets (see try_compile() for further details).
1470 CMAKE_REQUIRED_QUIET
1472 If this variable evaluates to a boolean true value, all
1473 status messages associated with the check will be sup‐
1474 pressed.
1475 The check is only performed once, with the result cached in the
1477 variable named by <resultVar>. Every subsequent CMake run will
1478 re-use this cached value rather than performing the check again,
1479 even if the <code> changes. In order to force the check to be
1480 re-evaluated, the variable named by <resultVar> must be manually
1481 removed from the cache.
1482 CheckOBJCXXSourceRuns
1484 New in version 3.16.
1485 Check if given Objective-C++ source compiles and links into an exe‐
1488 cutable and can subsequently be run.
1489 check_objcxx_source_runs
1491 check_objcxx_source_runs(<code> <resultVar>)
1493 Check that the source supplied in <code> can be compiled as a
1495 Objective-C++ source file, linked as an executable and then run.
1496 The <code> must contain at least a main() function. If the
1497 <code> could be built and run successfully, the internal cache
1498 variable specified by <resultVar> will be set to 1, otherwise it
1499 will be set to an value that evaluates to boolean false (e.g. an
1500 empty string or an error message).
1501 The underlying check is performed by the try_run() command. The
1503 compile and link commands can be influenced by setting any of
1504 the following variables prior to calling check_ob‐
1505 jcxx_source_runs():
1506 CMAKE_REQUIRED_FLAGS
1508 Additional flags to pass to the compiler. Note that the
1509 contents of CMAKE_OBJCXX_FLAGS and its associated config‐
1510 uration-specific variable are automatically added to the
1511 compiler command before the contents of CMAKE_RE‐
1512 QUIRED_FLAGS.
1513 CMAKE_REQUIRED_DEFINITIONS
1515 A ;-list of compiler definitions of the form -DFOO or
1516 -DFOO=bar. A definition for the name specified by <re‐
1517 sultVar> will also be added automatically.
1518 CMAKE_REQUIRED_INCLUDES
1520 A ;-list of header search paths to pass to the compiler.
1521 These will be the only header search paths used by
1522 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1523 directory property will be ignored.
1524 CMAKE_REQUIRED_LINK_OPTIONS
1526 A ;-list of options to add to the link command (see
1527 try_run() for further details).
1528 CMAKE_REQUIRED_LIBRARIES
1530 A ;-list of libraries to add to the link command. These
1531 can be the name of system libraries or they can be Im‐
1532 ported Targets (see try_run() for further details).
1533 CMAKE_REQUIRED_QUIET
1535 If this variable evaluates to a boolean true value, all
1536 status messages associated with the check will be sup‐
1537 pressed.
1538 The check is only performed once, with the result cached in the
1540 variable named by <resultVar>. Every subsequent CMake run will
1541 re-use this cached value rather than performing the check again,
1542 even if the <code> changes. In order to force the check to be
1543 re-evaluated, the variable named by <resultVar> must be manually
1544 removed from the cache.
1545 CheckPIESupported
1547 New in version 3.14.
1548 Check whether the linker supports Position Independent Code (PIE) or No
1551 Position Independent Code (NO_PIE) for executables. Use this to ensure
1552 that the POSITION_INDEPENDENT_CODE target property for executables will
1553 be honored at link time.
1554 check_pie_supported
1556 check_pie_supported([OUTPUT_VARIABLE <output>]
1558 [LANGUAGES <lang>...])
1559 Options are:
1561 OUTPUT_VARIABLE <output>
1563 Set <output> variable with details about any error.
1564 LANGUAGES <lang>...
1566 Check the linkers used for each of the specified lan‐
1567 guages. Supported languages are C, CXX, and Fortran.
1568 It makes no sense to use this module when CMP0083 is set to OLD, so the
1570 command will return an error in this case. See policy CMP0083 for de‐
1571 tails.
1572 Variables
1574 For each language checked, two boolean cache variables are defined.
1575 CMAKE_<lang>_LINK_PIE_SUPPORTED
1577 Set to YES if PIE is supported by the linker and NO other‐
1578 wise.
1579 CMAKE_<lang>_LINK_NO_PIE_SUPPORTED
1581 Set to YES if NO_PIE is supported by the linker and NO other‐
1582 wise.
1583 Examples
1585 check_pie_supported()
1586 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1587 # Retrieve any error message.
1589 check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C)
1590 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1591 if(NOT CMAKE_C_LINK_PIE_SUPPORTED)
1592 message(WARNING "PIE is not supported at link time: ${output}.\n"
1593 "PIE link options will not be passed to linker.")
1594 endif()
1595 CheckPrototypeDefinition
1597 Check if the prototype we expect is correct.
1598 check_prototype_definition
1600 check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER VARIABLE)
1602 FUNCTION - The name of the function (used to check if prototype exists)
1604 PROTOTYPE- The prototype to check.
1605 RETURN - The return value of the function.
1606 HEADER - The header files required.
1607 VARIABLE - The variable to store the result.
1608 Will be created as an internal cache variable.
1609 Example:
1611 check_prototype_definition(getpwent_r
1613 "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)"
1614 "NULL"
1615 "unistd.h;pwd.h"
1616 SOLARIS_GETPWENT_R)
1617 The following variables may be set before calling this function to mod‐
1619 ify the way the check is run:
1620 CMAKE_REQUIRED_FLAGS
1622 string of compile command line flags.
1623 CMAKE_REQUIRED_DEFINITIONS
1625 list of macros to define (-DFOO=bar).
1626 CMAKE_REQUIRED_INCLUDES
1628 list of include directories.
1629 CMAKE_REQUIRED_LINK_OPTIONS
1631 New in version 3.14: list of options to pass to link command.
1632 CMAKE_REQUIRED_LIBRARIES
1635 list of libraries to link.
1636 CMAKE_REQUIRED_QUIET
1638 New in version 3.1: execute quietly without messages.
1639 CheckSourceCompiles
1642 New in version 3.19.
1643 Check if given source compiles and links into an executable.
1646 check_source_compiles
1648 check_source_compiles(<lang> <code> <resultVar>
1650 [FAIL_REGEX <regex1> [<regex2>...]]
1651 [SRC_EXT <extension>])
1652 Check that the source supplied in <code> can be compiled as a
1654 source file for the requested language and linked as an exe‐
1655 cutable (so it must contain at least a main() function). The re‐
1656 sult will be stored in the internal cache variable specified by
1657 <resultVar>, with a boolean true value for success and boolean
1658 false for failure. If FAIL_REGEX is provided, then failure is
1659 determined by checking if anything in the output matches any of
1660 the specified regular expressions.
1661 By default, the test source file will be given a file extension
1663 that matches the requested language. The SRC_EXT option can be
1664 used to override this with .<extension> instead.
1665 The underlying check is performed by the try_compile() command.
1667 The compile and link commands can be influenced by setting any
1668 of the following variables prior to calling check_source_com‐
1669 piles():
1670 CMAKE_REQUIRED_FLAGS
1672 Additional flags to pass to the compiler. Note that the
1673 contents of CMAKE_<LANG>_FLAGS and its associated config‐
1674 uration-specific variable are automatically added to the
1675 compiler command before the contents of CMAKE_RE‐
1676 QUIRED_FLAGS.
1677 CMAKE_REQUIRED_DEFINITIONS
1679 A ;-list of compiler definitions of the form -DFOO or
1680 -DFOO=bar. A definition for the name specified by <re‐
1681 sultVar> will also be added automatically.
1682 CMAKE_REQUIRED_INCLUDES
1684 A ;-list of header search paths to pass to the compiler.
1685 These will be the only header search paths used by
1686 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1687 RIES directory property will be ignored.
1688 CMAKE_REQUIRED_LINK_OPTIONS
1690 A ;-list of options to add to the link command (see
1691 try_compile() for further details).
1692 CMAKE_REQUIRED_LIBRARIES
1694 A ;-list of libraries to add to the link command. These
1695 can be the name of system libraries or they can be Im‐
1696 ported Targets (see try_compile() for further details).
1697 CMAKE_REQUIRED_QUIET
1699 If this variable evaluates to a boolean true value, all
1700 status messages associated with the check will be sup‐
1701 pressed.
1702 The check is only performed once, with the result cached in the
1704 variable named by <resultVar>. Every subsequent CMake run will
1705 re-use this cached value rather than performing the check again,
1706 even if the <code> changes. In order to force the check to be
1707 re-evaluated, the variable named by <resultVar> must be manually
1708 removed from the cache.
1709 CheckSourceRuns
1711 New in version 3.19.
1712 Check if given source compiles and links into an executable and can
1715 subsequently be run.
1716 check_source_runs
1718 check_source_runs(<lang> <code> <resultVar>
1720 [SRC_EXT <extension>])
1721 Check that the source supplied in <code> can be compiled as a
1723 source file for the requested language, linked as an executable
1724 and then run. The <code> must contain at least a main() func‐
1725 tion. If the <code> could be built and run successfully, the in‐
1726 ternal cache variable specified by <resultVar> will be set to 1,
1727 otherwise it will be set to an value that evaluates to boolean
1728 false (e.g. an empty string or an error message).
1729 By default, the test source file will be given a file extension
1731 that matches the requested language. The SRC_EXT option can be
1732 used to override this with .<extension> instead.
1733 The underlying check is performed by the try_run() command. The
1735 compile and link commands can be influenced by setting any of
1736 the following variables prior to calling
1737 check_objc_source_runs():
1738 CMAKE_REQUIRED_FLAGS
1740 Additional flags to pass to the compiler. Note that the
1741 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1742 ration-specific variable are automatically added to the
1743 compiler command before the contents of CMAKE_RE‐
1744 QUIRED_FLAGS.
1745 CMAKE_REQUIRED_DEFINITIONS
1747 A ;-list of compiler definitions of the form -DFOO or
1748 -DFOO=bar. A definition for the name specified by <re‐
1749 sultVar> will also be added automatically.
1750 CMAKE_REQUIRED_INCLUDES
1752 A ;-list of header search paths to pass to the compiler.
1753 These will be the only header search paths used by
1754 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1755 directory property will be ignored.
1756 CMAKE_REQUIRED_LINK_OPTIONS
1758 A ;-list of options to add to the link command (see
1759 try_run() for further details).
1760 CMAKE_REQUIRED_LIBRARIES
1762 A ;-list of libraries to add to the link command. These
1763 can be the name of system libraries or they can be Im‐
1764 ported Targets (see try_run() for further details).
1765 CMAKE_REQUIRED_QUIET
1767 If this variable evaluates to a boolean true value, all
1768 status messages associated with the check will be sup‐
1769 pressed.
1770 The check is only performed once, with the result cached in the
1772 variable named by <resultVar>. Every subsequent CMake run will
1773 re-use this cached value rather than performing the check again,
1774 even if the <code> changes. In order to force the check to be
1775 re-evaluated, the variable named by <resultVar> must be manually
1776 removed from the cache.
1777 CheckStructHasMember
1779 Check if the given struct or class has the specified member variable
1780 CHECK_STRUCT_HAS_MEMBER
1782 CHECK_STRUCT_HAS_MEMBER(<struct> <member> <header> <variable>
1784 [LANGUAGE <language>])
1785 <struct> - the name of the struct or class you are interested in
1787 <member> - the member which existence you want to check
1788 <header> - the header(s) where the prototype should be declared
1789 <variable> - variable to store the result
1790 <language> - the compiler to use (C or CXX)
1791 The following variables may be set before calling this macro to modify
1793 the way the check is run:
1794 CMAKE_REQUIRED_FLAGS
1796 string of compile command line flags.
1797 CMAKE_REQUIRED_DEFINITIONS
1799 list of macros to define (-DFOO=bar).
1800 CMAKE_REQUIRED_INCLUDES
1802 list of include directories.
1803 CMAKE_REQUIRED_LINK_OPTIONS
1805 New in version 3.14: list of options to pass to link command.
1806 CMAKE_REQUIRED_LIBRARIES
1809 list of libraries to link.
1810 CMAKE_REQUIRED_QUIET
1812 New in version 3.1: execute quietly without messages.
1813 Example:
1816 CHECK_STRUCT_HAS_MEMBER("struct timeval" tv_sec sys/select.h
1818 HAVE_TIMEVAL_TV_SEC LANGUAGE C)
1819 CheckSymbolExists
1821 Provides a macro to check if a symbol exists as a function, variable,
1822 or macro in C.
1823 check_symbol_exists
1825 check_symbol_exists(<symbol> <files> <variable>)
1827 Check that the <symbol> is available after including given
1829 header <files> and store the result in a <variable>. Specify
1830 the list of files in one argument as a semicolon-separated list.
1831 <variable> will be created as an internal cache variable.
1832 If the header files define the symbol as a macro it is considered
1834 available and assumed to work. If the header files declare the symbol
1835 as a function or variable then the symbol must also be available for
1836 linking (so intrinsics may not be detected). If the symbol is a type,
1837 enum value, or intrinsic it will not be recognized (consider using
1838 CheckTypeSize or CheckSourceCompiles). If the check needs to be done
1839 in C++, consider using CheckCXXSymbolExists instead.
1840 The following variables may be set before calling this macro to modify
1842 the way the check is run:
1843 CMAKE_REQUIRED_FLAGS
1845 string of compile command line flags.
1846 CMAKE_REQUIRED_DEFINITIONS
1848 a ;-list of macros to define (-DFOO=bar).
1849 CMAKE_REQUIRED_INCLUDES
1851 a ;-list of header search paths to pass to the compiler.
1852 CMAKE_REQUIRED_LINK_OPTIONS
1854 New in version 3.14: a ;-list of options to add to the link com‐
1855 mand.
1856 CMAKE_REQUIRED_LIBRARIES
1859 a ;-list of libraries to add to the link command. See policy
1860 CMP0075.
1861 CMAKE_REQUIRED_QUIET
1863 New in version 3.1: execute quietly without messages.
1864 For example:
1867 include(CheckSymbolExists)
1869 # Check for macro SEEK_SET
1871 check_symbol_exists(SEEK_SET "stdio.h" HAVE_SEEK_SET)
1872 # Check for function fopen
1873 check_symbol_exists(fopen "stdio.h" HAVE_FOPEN)
1874 CheckTypeSize
1876 Check sizeof a type
1877 CHECK_TYPE_SIZE
1879 CHECK_TYPE_SIZE(TYPE VARIABLE [BUILTIN_TYPES_ONLY]
1881 [LANGUAGE <language>])
1882 Check if the type exists and determine its size. On return,
1884 HAVE_${VARIABLE} holds the existence of the type, and ${VARI‐
1885 ABLE} holds one of the following:
1886 <size> = type has non-zero size <size>
1888 "0" = type has arch-dependent size (see below)
1889 "" = type does not exist
1890 Both HAVE_${VARIABLE} and ${VARIABLE} will be created as inter‐
1892 nal cache variables.
1893 Furthermore, the variable ${VARIABLE}_CODE holds C preprocessor
1895 code to define the macro ${VARIABLE} to the size of the type, or
1896 leave the macro undefined if the type does not exist.
1897 The variable ${VARIABLE} may be 0 when CMAKE_OSX_ARCHITECTURES
1899 has multiple architectures for building OS X universal binaries.
1900 This indicates that the type size varies across architectures.
1901 In this case ${VARIABLE}_CODE contains C preprocessor tests map‐
1902 ping from each architecture macro to the corresponding type
1903 size. The list of architecture macros is stored in ${VARI‐
1904 ABLE}_KEYS, and the value for each key is stored in ${VARI‐
1905 ABLE}-${KEY}.
1906 If the BUILTIN_TYPES_ONLY option is not given, the macro checks
1908 for headers <sys/types.h>, <stdint.h>, and <stddef.h>, and saves
1909 results in HAVE_SYS_TYPES_H, HAVE_STDINT_H, and HAVE_STDDEF_H.
1910 The type size check automatically includes the available head‐
1911 ers, thus supporting checks of types defined in the headers.
1912 If LANGUAGE is set, the specified compiler will be used to per‐
1914 form the check. Acceptable values are C and CXX.
1915 Despite the name of the macro you may use it to check the size of more
1917 complex expressions, too. To check e.g. for the size of a struct mem‐
1918 ber you can do something like this:
1919 check_type_size("((struct something*)0)->member" SIZEOF_MEMBER)
1921 The following variables may be set before calling this macro to modify
1923 the way the check is run:
1924 CMAKE_REQUIRED_FLAGS
1926 string of compile command line flags.
1927 CMAKE_REQUIRED_DEFINITIONS
1929 list of macros to define (-DFOO=bar).
1930 CMAKE_REQUIRED_INCLUDES
1932 list of include directories.
1933 CMAKE_REQUIRED_LINK_OPTIONS
1935 New in version 3.14: list of options to pass to link command.
1936 CMAKE_REQUIRED_LIBRARIES
1939 list of libraries to link.
1940 CMAKE_REQUIRED_QUIET
1942 New in version 3.1: execute quietly without messages.
1943 CMAKE_EXTRA_INCLUDE_FILES
1946 list of extra headers to include.
1947 CheckVariableExists
1949 Check if the variable exists.
1950 CHECK_VARIABLE_EXISTS
1952 CHECK_VARIABLE_EXISTS(VAR VARIABLE)
1954 VAR - the name of the variable
1956 VARIABLE - variable to store the result
1957 Will be created as an internal cache variable.
1958 This macro is only for C variables.
1960 The following variables may be set before calling this macro to modify
1962 the way the check is run:
1963 CMAKE_REQUIRED_FLAGS
1965 string of compile command line flags.
1966 CMAKE_REQUIRED_DEFINITIONS
1968 list of macros to define (-DFOO=bar).
1969 CMAKE_REQUIRED_LINK_OPTIONS
1971 New in version 3.14: list of options to pass to link command.
1972 CMAKE_REQUIRED_LIBRARIES
1975 list of libraries to link.
1976 CMAKE_REQUIRED_QUIET
1978 New in version 3.1: execute quietly without messages.
1979 CMakeAddFortranSubdirectory
1982 Add a fortran-only subdirectory, find a fortran compiler, and build.
1983 The cmake_add_fortran_subdirectory function adds a subdirectory to a
1985 project that contains a fortran-only subproject. The module will check
1986 the current compiler and see if it can support fortran. If no fortran
1987 compiler is found and the compiler is MSVC, then this module will find
1988 the MinGW gfortran. It will then use an external project to build with
1989 the MinGW tools. It will also create imported targets for the li‐
1990 braries created. This will only work if the fortran code is built into
1991 a dll, so BUILD_SHARED_LIBS is turned on in the project. In addition
1992 the CMAKE_GNUtoMS option is set to on, so that Microsoft .lib files are
1993 created. Usage is as follows:
1994 cmake_add_fortran_subdirectory(
1996 <subdir> # name of subdirectory
1997 PROJECT <project_name> # project name in subdir top CMakeLists.txt
1998 ARCHIVE_DIR <dir> # dir where project places .lib files
1999 RUNTIME_DIR <dir> # dir where project places .dll files
2000 LIBRARIES <lib>... # names of library targets to import
2001 LINK_LIBRARIES # link interface libraries for LIBRARIES
2002 [LINK_LIBS <lib> <dep>...]...
2003 CMAKE_COMMAND_LINE ... # extra command line flags to pass to cmake
2004 NO_EXTERNAL_INSTALL # skip installation of external project
2005 )
2006 Relative paths in ARCHIVE_DIR and RUNTIME_DIR are interpreted with re‐
2008 spect to the build directory corresponding to the source directory in
2009 which the function is invoked.
2010 Limitations:
2012 NO_EXTERNAL_INSTALL is required for forward compatibility with a future
2014 version that supports installation of the external project binaries
2015 during make install.
2016 CMakeBackwardCompatibilityCXX
2018 define a bunch of backwards compatibility variables
2019 CMAKE_ANSI_CXXFLAGS - flag for ansi c++
2021 CMAKE_HAS_ANSI_STRING_STREAM - has <strstream>
2022 include(TestForANSIStreamHeaders)
2023 include(CheckIncludeFileCXX)
2024 include(TestForSTDNamespace)
2025 include(TestForANSIForScope)
2026 CMakeDependentOption
2028 Macro to provide an option dependent on other options.
2029 This macro presents an option to the user only if a set of other condi‐
2031 tions are true.
2032 cmake_dependent_option
2034 cmake_dependent_option(<option> "<help_text>" <value> <depends> <force>)
2036 Makes <option> available to the user if <depends> is true. When
2038 <option> is available, the given <help_text> and initial <value>
2039 are used. If the <depends> condition is not true, <option> will
2040 not be presented and will always have the value given by
2041 <force>. Any value set by the user is preserved for when the op‐
2042 tion is presented again. In case <depends> is a semicolon-sepa‐
2043 rated list, all elements must be true in order to initialize
2044 <option> with <value>.
2045 Example invocation:
2047 cmake_dependent_option(USE_FOO "Use Foo" ON "USE_BAR;NOT USE_ZOT" OFF)
2049 If USE_BAR is true and USE_ZOT is false, this provides an option called
2051 USE_FOO that defaults to ON. Otherwise, it sets USE_FOO to OFF and
2052 hides the option from the user. If the status of USE_BAR or USE_ZOT
2053 ever changes, any value for the USE_FOO option is saved so that when
2054 the option is re-enabled it retains its old value.
2055 New in version 3.22: Full Condition Syntax is now supported. See pol‐
2057 icy CMP0127.
2058 CMakeFindDependencyMacro
2061 find_dependency
2062 The find_dependency() macro wraps a find_package() call for a
2063 package dependency:
2064 find_dependency(<dep> [...])
2066 It is designed to be used in a Package Configuration File
2068 (<PackageName>Config.cmake). find_dependency forwards the cor‐
2069 rect parameters for QUIET and REQUIRED which were passed to the
2070 original find_package() call. Any additional arguments speci‐
2071 fied are forwarded to find_package().
2072 If the dependency could not be found it sets an informative di‐
2074 agnostic message and calls return() to end processing of the
2075 calling package configuration file and return to the find_pack‐
2076 age() command that loaded it.
2077 NOTE:
2079 The call to return() makes this macro unsuitable to call from
2080 Find Modules.
2081 CMakeFindFrameworks
2083 helper module to find OSX frameworks
2084 This module reads hints about search locations from variables:
2086 CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS - Extra directories
2088 CMakeFindPackageMode
2090 This file is executed by cmake when invoked with --find-package. It
2091 expects that the following variables are set using -D:
2092 NAME name of the package
2094 COMPILER_ID
2096 the CMake compiler ID for which the result is, i.e. GNU/In‐
2097 tel/Clang/MSVC, etc.
2098 LANGUAGE
2100 language for which the result will be used, i.e. C/CXX/For‐
2101 tran/ASM
2102 MODE
2104 EXIST only check for existence of the given package
2106 COMPILE
2108 print the flags needed for compiling an object file which
2109 uses the given package
2110 LINK print the flags needed for linking when using the given
2112 package
2113 QUIET if TRUE, don't print anything
2115 CMakeGraphVizOptions
2117 The builtin Graphviz support of CMake.
2118 Generating Graphviz files
2120 CMake can generate Graphviz files showing the dependencies between the
2121 targets in a project, as well as external libraries which are linked
2122 against.
2123 When running CMake with the --graphviz=foo.dot option, it produces:
2125 • a foo.dot file, showing all dependencies in the project
2127 • a foo.dot.<target> file for each target, showing on which other tar‐
2129 gets it depends
2130 • a foo.dot.<target>.dependers file for each target, showing which
2132 other targets depend on it
2133 Those .dot files can be converted to images using the dot command from
2135 the Graphviz package:
2136 dot -Tpng -o foo.png foo.dot
2138 New in version 3.10: The different dependency types PUBLIC, INTERFACE
2140 and PRIVATE are represented as solid, dashed and dotted edges.
2141 Variables specific to the Graphviz support
2144 The resulting graphs can be huge. The look and content of the gener‐
2145 ated graphs can be controlled using the file CMakeGraphVizOp‐
2146 tions.cmake. This file is first searched in CMAKE_BINARY_DIR, and then
2147 in CMAKE_SOURCE_DIR. If found, the variables set in it are used to ad‐
2148 just options for the generated Graphviz files.
2149 GRAPHVIZ_GRAPH_NAME
2151 The graph name.
2152 • Mandatory: NO
2154 • Default: value of CMAKE_PROJECT_NAME
2156 GRAPHVIZ_GRAPH_HEADER
2158 The header written at the top of the Graphviz files.
2159 • Mandatory: NO
2161 • Default: "node [ fontsize = "12" ];"
2163 GRAPHVIZ_NODE_PREFIX
2165 The prefix for each node in the Graphviz files.
2166 • Mandatory: NO
2168 • Default: "node"
2170 GRAPHVIZ_EXECUTABLES
2172 Set to FALSE to exclude executables from the generated graphs.
2173 • Mandatory: NO
2175 • Default: TRUE
2177 GRAPHVIZ_STATIC_LIBS
2179 Set to FALSE to exclude static libraries from the generated
2180 graphs.
2181 • Mandatory: NO
2183 • Default: TRUE
2185 GRAPHVIZ_SHARED_LIBS
2187 Set to FALSE to exclude shared libraries from the generated
2188 graphs.
2189 • Mandatory: NO
2191 • Default: TRUE
2193 GRAPHVIZ_MODULE_LIBS
2195 Set to FALSE to exclude module libraries from the generated
2196 graphs.
2197 • Mandatory: NO
2199 • Default: TRUE
2201 GRAPHVIZ_INTERFACE_LIBS
2203 Set to FALSE to exclude interface libraries from the generated
2204 graphs.
2205 • Mandatory: NO
2207 • Default: TRUE
2209 GRAPHVIZ_OBJECT_LIBS
2211 Set to FALSE to exclude object libraries from the generated
2212 graphs.
2213 • Mandatory: NO
2215 • Default: TRUE
2217 GRAPHVIZ_UNKNOWN_LIBS
2219 Set to FALSE to exclude unknown libraries from the generated
2220 graphs.
2221 • Mandatory: NO
2223 • Default: TRUE
2225 GRAPHVIZ_EXTERNAL_LIBS
2227 Set to FALSE to exclude external libraries from the generated
2228 graphs.
2229 • Mandatory: NO
2231 • Default: TRUE
2233 GRAPHVIZ_CUSTOM_TARGETS
2235 Set to TRUE to include custom targets in the generated graphs.
2236 • Mandatory: NO
2238 • Default: FALSE
2240 GRAPHVIZ_IGNORE_TARGETS
2242 A list of regular expressions for names of targets to exclude
2243 from the generated graphs.
2244 • Mandatory: NO
2246 • Default: empty
2248 GRAPHVIZ_GENERATE_PER_TARGET
2250 Set to FALSE to not generate per-target graphs foo.dot.<target>.
2251 • Mandatory: NO
2253 • Default: TRUE
2255 GRAPHVIZ_GENERATE_DEPENDERS
2257 Set to FALSE to not generate depender graphs foo.dot.<tar‐
2258 get>.dependers.
2259 • Mandatory: NO
2261 • Default: TRUE
2263 CMakePackageConfigHelpers
2265 Helpers functions for creating config files that can be included by
2266 other projects to find and use a package.
2267 Adds the configure_package_config_file() and
2269 write_basic_package_version_file() commands.
2270 Generating a Package Configuration File
2272 configure_package_config_file
2273 Create a config file for a project:
2274 configure_package_config_file(<input> <output>
2276 INSTALL_DESTINATION <path>
2277 [PATH_VARS <var1> <var2> ... <varN>]
2278 [NO_SET_AND_CHECK_MACRO]
2279 [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
2280 [INSTALL_PREFIX <path>]
2281 )
2282 configure_package_config_file() should be used instead of the plain
2284 configure_file() command when creating the <PackageName>Config.cmake or
2285 <PackageName>-config.cmake file for installing a project or library.
2286 It helps making the resulting package relocatable by avoiding hardcoded
2287 paths in the installed Config.cmake file.
2288 In a FooConfig.cmake file there may be code like this to make the in‐
2290 stall destinations know to the using project:
2291 set(FOO_INCLUDE_DIR "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
2293 set(FOO_DATA_DIR "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
2294 set(FOO_ICONS_DIR "@CMAKE_INSTALL_PREFIX@/share/icons" )
2295 #...logic to determine installedPrefix from the own location...
2296 set(FOO_CONFIG_DIR "${installedPrefix}/@CONFIG_INSTALL_DIR@" )
2297 All 4 options shown above are not sufficient, since the first 3 hard‐
2299 code the absolute directory locations, and the 4th case works only if
2300 the logic to determine the installedPrefix is correct, and if CON‐
2301 FIG_INSTALL_DIR contains a relative path, which in general cannot be
2302 guaranteed. This has the effect that the resulting FooConfig.cmake
2303 file would work poorly under Windows and OSX, where users are used to
2304 choose the install location of a binary package at install time, inde‐
2305 pendent from how CMAKE_INSTALL_PREFIX was set at build/cmake time.
2306 Using configure_package_config_file helps. If used correctly, it makes
2308 the resulting FooConfig.cmake file relocatable. Usage:
2309 1. write a FooConfig.cmake.in file as you are used to
2311 2. insert a line containing only the string @PACKAGE_INIT@
2313 3. instead of set(FOO_DIR "@SOME_INSTALL_DIR@"), use set(FOO_DIR
2315 "@PACKAGE_SOME_INSTALL_DIR@") (this must be after the @PACKAGE_INIT@
2316 line)
2317 4. instead of using the normal configure_file(), use configure_pack‐
2319 age_config_file()
2320 The <input> and <output> arguments are the input and output file, the
2322 same way as in configure_file().
2323 The <path> given to INSTALL_DESTINATION must be the destination where
2325 the FooConfig.cmake file will be installed to. This path can either be
2326 absolute, or relative to the INSTALL_PREFIX path.
2327 The variables <var1> to <varN> given as PATH_VARS are the variables
2329 which contain install destinations. For each of them the macro will
2330 create a helper variable PACKAGE_<var...>. These helper variables must
2331 be used in the FooConfig.cmake.in file for setting the installed loca‐
2332 tion. They are calculated by configure_package_config_file so that
2333 they are always relative to the installed location of the package.
2334 This works both for relative and also for absolute locations. For ab‐
2335 solute locations it works only if the absolute location is a subdirec‐
2336 tory of INSTALL_PREFIX.
2337 New in version 3.1: If the INSTALL_PREFIX argument is passed, this is
2339 used as base path to calculate all the relative paths. The <path> ar‐
2340 gument must be an absolute path. If this argument is not passed, the
2341 CMAKE_INSTALL_PREFIX variable will be used instead. The default value
2342 is good when generating a FooConfig.cmake file to use your package from
2343 the install tree. When generating a FooConfig.cmake file to use your
2344 package from the build tree this option should be used.
2345 By default configure_package_config_file also generates two helper
2348 macros, set_and_check() and check_required_components() into the
2349 FooConfig.cmake file.
2350 set_and_check() should be used instead of the normal set() command for
2352 setting directories and file locations. Additionally to setting the
2353 variable it also checks that the referenced file or directory actually
2354 exists and fails with a FATAL_ERROR otherwise. This makes sure that
2355 the created FooConfig.cmake file does not contain wrong references.
2356 When using the NO_SET_AND_CHECK_MACRO, this macro is not generated into
2357 the FooConfig.cmake file.
2358 check_required_components(<PackageName>) should be called at the end of
2360 the FooConfig.cmake file. This macro checks whether all requested,
2361 non-optional components have been found, and if this is not the case,
2362 sets the Foo_FOUND variable to FALSE, so that the package is considered
2363 to be not found. It does that by testing the Foo_<Component>_FOUND
2364 variables for all requested required components. This macro should be
2365 called even if the package doesn't provide any components to make sure
2366 users are not specifying components erroneously. When using the
2367 NO_CHECK_REQUIRED_COMPONENTS_MACRO option, this macro is not generated
2368 into the FooConfig.cmake file.
2369 For an example see below the documentation for
2371 write_basic_package_version_file().
2372 Generating a Package Version File
2374 write_basic_package_version_file
2375 Create a version file for a project:
2376 write_basic_package_version_file(<filename>
2378 [VERSION <major.minor.patch>]
2379 COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion>
2380 [ARCH_INDEPENDENT] )
2381 Writes a file for use as <PackageName>ConfigVersion.cmake file to
2383 <filename>. See the documentation of find_package() for details on
2384 this.
2385 <filename> is the output filename, it should be in the build tree.
2387 <major.minor.patch> is the version number of the project to be in‐
2388 stalled.
2389 If no VERSION is given, the PROJECT_VERSION variable is used. If this
2391 hasn't been set, it errors out.
2392 The COMPATIBILITY mode AnyNewerVersion means that the installed package
2394 version will be considered compatible if it is newer or exactly the
2395 same as the requested version. This mode should be used for packages
2396 which are fully backward compatible, also across major versions. If
2397 SameMajorVersion is used instead, then the behavior differs from
2398 AnyNewerVersion in that the major version number must be the same as
2399 requested, e.g. version 2.0 will not be considered compatible if 1.0
2400 is requested. This mode should be used for packages which guarantee
2401 backward compatibility within the same major version. If SameMinorVer‐
2402 sion is used, the behavior is the same as SameMajorVersion, but both
2403 major and minor version must be the same as requested, e.g version 0.2
2404 will not be compatible if 0.1 is requested. If ExactVersion is used,
2405 then the package is only considered compatible if the requested version
2406 matches exactly its own version number (not considering the tweak ver‐
2407 sion). For example, version 1.2.3 of a package is only considered com‐
2408 patible to requested version 1.2.3. This mode is for packages without
2409 compatibility guarantees. If your project has more elaborated version
2410 matching rules, you will need to write your own custom ConfigVer‐
2411 sion.cmake file instead of using this macro.
2412 New in version 3.11: The SameMinorVersion compatibility mode.
2414 New in version 3.14: If ARCH_INDEPENDENT is given, the installed pack‐
2417 age version will be considered compatible even if it was built for a
2418 different architecture than the requested architecture. Otherwise, an
2419 architecture check will be performed, and the package will be consid‐
2420 ered compatible only if the architecture matches exactly. For example,
2421 if the package is built for a 32-bit architecture, the package is only
2422 considered compatible if it is used on a 32-bit architecture, unless
2423 ARCH_INDEPENDENT is given, in which case the package is considered com‐
2424 patible on any architecture.
2425 NOTE:
2428 ARCH_INDEPENDENT is intended for header-only libraries or similar
2429 packages with no binaries.
2430 New in version 3.19: COMPATIBILITY_MODE AnyNewerVersion, SameMajorVer‐
2432 sion and SameMinorVersion handle the version range if any is specified
2433 (see find_package() command for the details). ExactVersion mode is in‐
2434 compatible with version ranges and will display an author warning if
2435 one is specified.
2436 Internally, this macro executes configure_file() to create the result‐
2439 ing version file. Depending on the COMPATIBILITY, the corresponding
2440 BasicConfigVersion-<COMPATIBILITY>.cmake.in file is used. Please note
2441 that these files are internal to CMake and you should not call config‐
2442 ure_file() on them yourself, but they can be used as starting point to
2443 create more sophisticted custom ConfigVersion.cmake files.
2444 Example Generating Package Files
2446 Example using both configure_package_config_file() and write_ba‐
2447 sic_package_version_file():
2448 CMakeLists.txt:
2450 set(INCLUDE_INSTALL_DIR include/ ... CACHE )
2452 set(LIB_INSTALL_DIR lib/ ... CACHE )
2453 set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
2454 #...
2455 include(CMakePackageConfigHelpers)
2456 configure_package_config_file(FooConfig.cmake.in
2457 ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2458 INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
2459 PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
2460 write_basic_package_version_file(
2461 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2462 VERSION 1.2.3
2463 COMPATIBILITY SameMajorVersion )
2464 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2465 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2466 DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )
2467 FooConfig.cmake.in:
2469 set(FOO_VERSION x.y.z)
2471 ...
2472 @PACKAGE_INIT@
2473 ...
2474 set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
2475 set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")
2476 check_required_components(Foo)
2478 CMakePrintHelpers
2480 Convenience functions for printing properties and variables, useful
2481 e.g. for debugging.
2482 cmake_print_properties([TARGETS target1 .. targetN]
2484 [SOURCES source1 .. sourceN]
2485 [DIRECTORIES dir1 .. dirN]
2486 [TESTS test1 .. testN]
2487 [CACHE_ENTRIES entry1 .. entryN]
2488 PROPERTIES prop1 .. propN )
2489 This function prints the values of the properties of the given targets,
2491 source files, directories, tests or cache entries. Exactly one of the
2492 scope keywords must be used. Example:
2493 cmake_print_properties(TARGETS foo bar PROPERTIES
2495 LOCATION INTERFACE_INCLUDE_DIRECTORIES)
2496 This will print the LOCATION and INTERFACE_INCLUDE_DIRECTORIES proper‐
2498 ties for both targets foo and bar.
2499 cmake_print_variables(var1 var2 .. varN)
2501 This function will print the name of each variable followed by its
2503 value. Example:
2504 cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION DOES_NOT_EXIST)
2506 Gives:
2508 -- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; DOES_NOT_EXIST=""
2510 CMakePrintSystemInformation
2512 Print system information.
2513 This module serves diagnostic purposes. Just include it in a project to
2515 see various internal CMake variables.
2516 CMakePushCheckState
2518 This module defines three macros: CMAKE_PUSH_CHECK_STATE()
2519 CMAKE_POP_CHECK_STATE() and CMAKE_RESET_CHECK_STATE() These macros can
2520 be used to save, restore and reset (i.e., clear contents) the state of
2521 the variables CMAKE_REQUIRED_FLAGS, CMAKE_REQUIRED_DEFINITIONS,
2522 CMAKE_REQUIRED_LINK_OPTIONS, CMAKE_REQUIRED_LIBRARIES, CMAKE_RE‐
2523 QUIRED_INCLUDES and CMAKE_EXTRA_INCLUDE_FILES used by the various
2524 Check-files coming with CMake, like e.g. check_function_exists() etc.
2525 The variable contents are pushed on a stack, pushing multiple times is
2526 supported. This is useful e.g. when executing such tests in a
2527 Find-module, where they have to be set, but after the Find-module has
2528 been executed they should have the same value as they had before.
2529 CMAKE_PUSH_CHECK_STATE() macro receives optional argument RESET.
2531 Whether it's specified, CMAKE_PUSH_CHECK_STATE() will set all CMAKE_RE‐
2532 QUIRED_* variables to empty values, same as CMAKE_RESET_CHECK_STATE()
2533 call will do.
2534 Usage:
2536 cmake_push_check_state(RESET)
2538 set(CMAKE_REQUIRED_DEFINITIONS -DSOME_MORE_DEF)
2539 check_function_exists(...)
2540 cmake_reset_check_state()
2541 set(CMAKE_REQUIRED_DEFINITIONS -DANOTHER_DEF)
2542 check_function_exists(...)
2543 cmake_pop_check_state()
2544 CMakeVerifyManifest
2546 CMakeVerifyManifest.cmake
2547 This script is used to verify that embedded manifests and side by side
2549 manifests for a project match. To run this script, cd to a directory
2550 and run the script with cmake -P. On the command line you can pass in
2551 versions that are OK even if not found in the .manifest files. For ex‐
2552 ample, cmake -Dallow_versions=8.0.50608.0 -PCmakeVerifyManifest.cmake
2553 could be used to allow an embedded manifest of 8.0.50608.0 to be used
2554 in a project even if that version was not found in the .manifest file.
2555 CPack
2557 Configure generators for binary installers and source packages.
2558 Introduction
2560 The CPack module generates the configuration files CPackConfig.cmake
2561 and CPackSourceConfig.cmake. They are intended for use in a subsequent
2562 run of the cpack program where they steer the generation of installers
2563 or/and source packages.
2564 Depending on the CMake generator, the CPack module may also add two new
2566 build targets, package and package_source. See the packaging targets
2567 section below for details.
2568 The generated binary installers will contain all files that have been
2570 installed via CMake's install() command (and the deprecated commands
2571 install_files(), install_programs(), and install_targets()). Note that
2572 the DESTINATION option of the install() command must be a relative
2573 path; otherwise installed files are ignored by CPack.
2574 Certain kinds of binary installers can be configured such that users
2576 can select individual application components to install. See the
2577 CPackComponent module for further details.
2578 Source packages (configured through CPackSourceConfig.cmake and gener‐
2580 ated by the CPack Archive Generator) will contain all source files in
2581 the project directory except those specified in
2582 CPACK_SOURCE_IGNORE_FILES.
2583 CPack Generators
2585 The CPACK_GENERATOR variable has different meanings in different con‐
2586 texts. In a CMakeLists.txt file, CPACK_GENERATOR is a list of genera‐
2587 tors: and when cpack is run with no other arguments, it will iterate
2588 over that list and produce one package for each generator. In a
2589 CPACK_PROJECT_CONFIG_FILE, CPACK_GENERATOR is a string naming a single
2590 generator. If you need per-cpack-generator logic to control other
2591 cpack settings, then you need a CPACK_PROJECT_CONFIG_FILE. If set, the
2592 CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator
2593 basis. It only need contain overrides.
2594 Here's how it works:
2596 • cpack runs
2598 • it includes CPackConfig.cmake
2600 • it iterates over the generators given by the -G command line option,
2602 or if no such option was specified, over the list of generators given
2603 by the CPACK_GENERATOR variable set in the CPackConfig.cmake input
2604 file.
2605 • foreach generator, it then
2607 • sets CPACK_GENERATOR to the one currently being iterated
2609 • includes the CPACK_PROJECT_CONFIG_FILE
2611 • produces the package for that generator
2613 This is the key: For each generator listed in CPACK_GENERATOR in CPack‐
2615 Config.cmake, cpack will reset CPACK_GENERATOR internally to the one
2616 currently being used and then include the CPACK_PROJECT_CONFIG_FILE.
2617 For a list of available generators, see cpack-generators(7).
2619 Targets package and package_source
2621 If CMake is run with the Makefile, Ninja, or Xcode generator, then in‐
2622 clude(CPack) generates a target package. This makes it possible to
2623 build a binary installer from CMake, Make, or Ninja: Instead of cpack,
2624 one may call cmake --build . --target package or make package or ninja
2625 package. The VS generator creates an uppercase target PACKAGE.
2626 If CMake is run with the Makefile or Ninja generator, then in‐
2628 clude(CPack) also generates a target package_source. To build a source
2629 package, instead of cpack -G TGZ --config CPackSourceConfig.cmake one
2630 may call cmake --build . --target package_source, make package_source,
2631 or ninja package_source.
2632 Variables common to all CPack Generators
2634 Before including this CPack module in your CMakeLists.txt file, there
2635 are a variety of variables that can be set to customize the resulting
2636 installers. The most commonly-used variables are:
2637 CPACK_PACKAGE_NAME
2639 The name of the package (or application). If not specified, it
2640 defaults to the project name.
2641 CPACK_PACKAGE_VENDOR
2643 The name of the package vendor. (e.g., "Kitware"). The default
2644 is "Humanity".
2645 CPACK_PACKAGE_DIRECTORY
2647 The directory in which CPack is doing its packaging. If it is
2648 not set then this will default (internally) to the build dir.
2649 This variable may be defined in a CPack config file or from the
2650 cpack command line option -B. If set, the command line option
2651 overrides the value found in the config file.
2652 CPACK_PACKAGE_VERSION_MAJOR
2654 Package major version. This variable will always be set, but
2655 its default value depends on whether or not version details were
2656 given to the project() command in the top level CMakeLists.txt
2657 file. If version details were given, the default value will be
2658 CMAKE_PROJECT_VERSION_MAJOR. If no version details were given,
2659 a default version of 0.1.1 will be assumed, leading to
2660 CPACK_PACKAGE_VERSION_MAJOR having a default value of 0.
2661 CPACK_PACKAGE_VERSION_MINOR
2663 Package minor version. The default value is determined based on
2664 whether or not version details were given to the project() com‐
2665 mand in the top level CMakeLists.txt file. If version details
2666 were given, the default value will be CMAKE_PROJECT_VERSION_MI‐
2667 NOR, but if no minor version component was specified then
2668 CPACK_PACKAGE_VERSION_MINOR will be left unset. If no project
2669 version was given at all, a default version of 0.1.1 will be as‐
2670 sumed, leading to CPACK_PACKAGE_VERSION_MINOR having a default
2671 value of 1.
2672 CPACK_PACKAGE_VERSION_PATCH
2674 Package patch version. The default value is determined based on
2675 whether or not version details were given to the project() com‐
2676 mand in the top level CMakeLists.txt file. If version details
2677 were given, the default value will be CMAKE_PROJECT_VER‐
2678 SION_PATCH, but if no patch version component was specified then
2679 CPACK_PACKAGE_VERSION_PATCH will be left unset. If no project
2680 version was given at all, a default version of 0.1.1 will be as‐
2681 sumed, leading to CPACK_PACKAGE_VERSION_PATCH having a default
2682 value of 1.
2683 CPACK_PACKAGE_DESCRIPTION
2685 A description of the project, used in places such as the intro‐
2686 duction screen of CPack-generated Windows installers. If not
2687 set, the value of this variable is populated from the file named
2688 by CPACK_PACKAGE_DESCRIPTION_FILE.
2689 CPACK_PACKAGE_DESCRIPTION_FILE
2691 A text file used to describe the project when
2692 CPACK_PACKAGE_DESCRIPTION is not explicitly set. The default
2693 value for CPACK_PACKAGE_DESCRIPTION_FILE points to a built-in
2694 template file Templates/CPack.GenericDescription.txt.
2695 CPACK_PACKAGE_DESCRIPTION_SUMMARY
2697 Short description of the project (only a few words). If the
2698 CMAKE_PROJECT_DESCRIPTION variable is set, it is used as the de‐
2699 fault value, otherwise the default will be a string generated by
2700 CMake based on CMAKE_PROJECT_NAME.
2701 CPACK_PACKAGE_HOMEPAGE_URL
2703 Project homepage URL. The default value is taken from the
2704 CMAKE_PROJECT_HOMEPAGE_URL variable, which is set by the top
2705 level project() command, or else the default will be empty if no
2706 URL was provided to project().
2707 CPACK_PACKAGE_FILE_NAME
2709 The name of the package file to generate, not including the ex‐
2710 tension. For example, cmake-2.6.1-Linux-i686. The default
2711 value is:
2712 ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}
2714 CPACK_PACKAGE_INSTALL_DIRECTORY
2716 Installation directory on the target system. This may be used by
2717 some CPack generators like NSIS to create an installation direc‐
2718 tory e.g., "CMake 2.5" below the installation prefix. All in‐
2719 stalled elements will be put inside this directory.
2720 CPACK_PACKAGE_ICON
2722 A branding image that will be displayed inside the installer
2723 (used by GUI installers).
2724 CPACK_PACKAGE_CHECKSUM
2726 New in version 3.7.
2727 An algorithm that will be used to generate an additional file
2730 with the checksum of the package. The output file name will be:
2731 ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}
2733 Supported algorithms are those listed by the string(<HASH>) com‐
2735 mand.
2736 CPACK_PROJECT_CONFIG_FILE
2738 CPack-time project CPack configuration file. This file is in‐
2739 cluded at cpack time, once per generator after CPack has set
2740 CPACK_GENERATOR to the actual generator being used. It allows
2741 per-generator setting of CPACK_* variables at cpack time.
2742 CPACK_RESOURCE_FILE_LICENSE
2744 License to be embedded in the installer. It will typically be
2745 displayed to the user by the produced installer (often with an
2746 explicit "Accept" button, for graphical installers) prior to in‐
2747 stallation. This license file is NOT added to the installed
2748 files but is used by some CPack generators like NSIS. If you
2749 want to install a license file (may be the same as this one)
2750 along with your project, you must add an appropriate CMake in‐
2751 stall() command in your CMakeLists.txt.
2752 CPACK_RESOURCE_FILE_README
2754 ReadMe file to be embedded in the installer. It typically de‐
2755 scribes in some detail the purpose of the project during the in‐
2756 stallation. Not all CPack generators use this file.
2757 CPACK_RESOURCE_FILE_WELCOME
2759 Welcome file to be embedded in the installer. It welcomes users
2760 to this installer. Typically used in the graphical installers
2761 on Windows and Mac OS X.
2762 CPACK_MONOLITHIC_INSTALL
2764 Disables the component-based installation mechanism. When set,
2765 the component specification is ignored and all installed items
2766 are put in a single "MONOLITHIC" package. Some CPack generators
2767 do monolithic packaging by default and may be asked to do compo‐
2768 nent packaging by setting CPACK_<GENNAME>_COMPONENT_INSTALL to
2769 TRUE.
2770 CPACK_GENERATOR
2772 List of CPack generators to use. If not specified, CPack will
2773 create a set of options following the naming pattern
2774 CPACK_BINARY_<GENNAME> (e.g. CPACK_BINARY_NSIS) allowing the
2775 user to enable/disable individual generators. If the -G option
2776 is given on the cpack command line, it will override this vari‐
2777 able and any CPACK_BINARY_<GENNAME> options.
2778 CPACK_OUTPUT_CONFIG_FILE
2780 The name of the CPack binary configuration file. This file is
2781 the CPack configuration generated by the CPack module for binary
2782 installers. Defaults to CPackConfig.cmake.
2783 CPACK_PACKAGE_EXECUTABLES
2785 Lists each of the executables and associated text label to be
2786 used to create Start Menu shortcuts. For example, setting this
2787 to the list ccmake;CMake will create a shortcut named "CMake"
2788 that will execute the installed executable ccmake. Not all
2789 CPack generators use it (at least NSIS, WIX and OSXX11 do).
2790 CPACK_STRIP_FILES
2792 List of files to be stripped. Starting with CMake 2.6.0,
2793 CPACK_STRIP_FILES will be a boolean variable which enables
2794 stripping of all files (a list of files evaluates to TRUE in
2795 CMake, so this change is compatible).
2796 CPACK_VERBATIM_VARIABLES
2798 New in version 3.4.
2799 If set to TRUE, values of variables prefixed with CPACK_ will be
2802 escaped before being written to the configuration files, so that
2803 the cpack program receives them exactly as they were specified.
2804 If not, characters like quotes and backslashes can cause parsing
2805 errors or alter the value received by the cpack program. De‐
2806 faults to FALSE for backwards compatibility.
2807 CPACK_THREADS
2809 New in version 3.20.
2810 Number of threads to use when performing parallelized opera‐
2813 tions, such as compressing the installer package.
2814 Some compression methods used by CPack generators such as Debian
2816 or Archive may take advantage of multiple CPU cores to speed up
2817 compression. CPACK_THREADS can be set to specify how many
2818 threads will be used for compression.
2819 A positive integer can be used to specify an exact desired
2821 thread count.
2822 When given a negative integer CPack will use the absolute value
2824 as the upper limit but may choose a lower value based on the
2825 available hardware concurrency.
2826 Given 0 CPack will try to use all available CPU cores.
2828 By default CPACK_THREADS is set to 1.
2830 Currently only xz compression may take advantage of multiple
2832 cores. Other compression methods ignore this value and use only
2833 one thread.
2834 New in version 3.21: Official CMake binaries available on
2836 cmake.org now ship with a liblzma that supports parallel com‐
2837 pression. Older versions did not.
2838 Variables for Source Package Generators
2841 The following CPack variables are specific to source packages, and will
2842 not affect binary packages:
2843 CPACK_SOURCE_PACKAGE_FILE_NAME
2845 The name of the source package. For example cmake-2.6.1.
2846 CPACK_SOURCE_STRIP_FILES
2848 List of files in the source tree that will be stripped. Start‐
2849 ing with CMake 2.6.0, CPACK_SOURCE_STRIP_FILES will be a boolean
2850 variable which enables stripping of all files (a list of files
2851 evaluates to TRUE in CMake, so this change is compatible).
2852 CPACK_SOURCE_GENERATOR
2854 List of generators used for the source packages. As with
2855 CPACK_GENERATOR, if this is not specified then CPack will create
2856 a set of options (e.g. CPACK_SOURCE_ZIP) allowing users to se‐
2857 lect which packages will be generated.
2858 CPACK_SOURCE_OUTPUT_CONFIG_FILE
2860 The name of the CPack source configuration file. This file is
2861 the CPack configuration generated by the CPack module for source
2862 installers. Defaults to CPackSourceConfig.cmake.
2863 CPACK_SOURCE_IGNORE_FILES
2865 Pattern of files in the source tree that won't be packaged when
2866 building a source package. This is a list of regular expression
2867 patterns (that must be properly escaped), e.g.,
2868 /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
2869 Variables for Advanced Use
2871 The following variables are for advanced uses of CPack:
2872 CPACK_CMAKE_GENERATOR
2874 What CMake generator should be used if the project is a CMake
2875 project. Defaults to the value of CMAKE_GENERATOR. Few users
2876 will want to change this setting.
2877 CPACK_INSTALL_CMAKE_PROJECTS
2879 List of four values that specify what project to install. The
2880 four values are: Build directory, Project Name, Project Compo‐
2881 nent, Directory. If omitted, CPack will build an installer that
2882 installs everything.
2883 CPACK_SYSTEM_NAME
2885 System name, defaults to the value of CMAKE_SYSTEM_NAME, except
2886 on Windows where it will be win32 or win64.
2887 CPACK_PACKAGE_VERSION
2889 Package full version, used internally. By default, this is
2890 built from CPACK_PACKAGE_VERSION_MAJOR,
2891 CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH.
2892 CPACK_TOPLEVEL_TAG
2894 Directory for the installed files.
2895 CPACK_INSTALL_COMMANDS
2897 Extra commands to install components. The environment variable
2898 CMAKE_INSTALL_PREFIX is set to the temporary install directory
2899 during execution.
2900 CPACK_INSTALL_SCRIPTS
2902 New in version 3.16.
2903 Extra CMake scripts executed by CPack during its local staging
2906 installation. They are executed before installing the files to
2907 be packaged. The scripts are not called by a standalone install
2908 (e.g.: make install). For every script, the following variables
2909 will be set: CMAKE_CURRENT_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR
2910 and CMAKE_INSTALL_PREFIX (which is set to the staging install
2911 directory). The singular form CMAKE_INSTALL_SCRIPT is supported
2912 as an alternative variable for historical reasons, but its value
2913 is ignored if CMAKE_INSTALL_SCRIPTS is set and a warning will be
2914 issued.
2915 See also CPACK_PRE_BUILD_SCRIPTS and CPACK_POST_BUILD_SCRIPTS
2917 which can be used to specify scripts to be executed later in the
2918 packaging process.
2919 CPACK_PRE_BUILD_SCRIPTS
2921 New in version 3.19.
2922 List of CMake scripts to execute after CPack has installed the
2925 files to be packaged into a staging directory and before produc‐
2926 ing the package(s) from those files. See also
2927 CPACK_INSTALL_SCRIPTS and CPACK_POST_BUILD_SCRIPTS.
2928 CPACK_POST_BUILD_SCRIPTS
2930 New in version 3.19.
2931 List of CMake scripts to execute after CPack has produced the
2934 resultant packages and before copying them back to the build di‐
2935 rectory. See also CPACK_INSTALL_SCRIPTS,
2936 CPACK_PRE_BUILD_SCRIPTS and CPACK_PACKAGE_FILES.
2937 CPACK_PACKAGE_FILES
2939 New in version 3.19.
2940 List of package files created in the staging directory, with
2943 each file provided as a full absolute path. This variable is
2944 populated by CPack just before invoking the post-build scripts
2945 listed in CPACK_POST_BUILD_SCRIPTS. It is the preferred way for
2946 the post-build scripts to know the set of package files to oper‐
2947 ate on. Projects should not try to set this variable them‐
2948 selves.
2949 CPACK_INSTALLED_DIRECTORIES
2951 Extra directories to install.
2952 CPACK_PACKAGE_INSTALL_REGISTRY_KEY
2954 Registry key used when installing this project. This is only
2955 used by installers for Windows. The default value is based on
2956 the installation directory.
2957 CPACK_CREATE_DESKTOP_LINKS
2959 List of desktop links to create. Each desktop link requires a
2960 corresponding start menu shortcut as created by
2961 CPACK_PACKAGE_EXECUTABLES.
2962 CPACK_BINARY_<GENNAME>
2964 CPack generated options for binary generators. The CPack.cmake
2965 module generates (when CPACK_GENERATOR is not set) a set of
2966 CMake options (see CMake option() command) which may then be
2967 used to select the CPack generator(s) to be used when building
2968 the package target or when running cpack without the -G option.
2969 CPackComponent
2971 Configure components for binary installers and source packages.
2972 Introduction
2974 This module is automatically included by CPack.
2975 Certain binary installers (especially the graphical installers) gener‐
2977 ated by CPack allow users to select individual application components
2978 to install. This module allows developers to configure the packaging
2979 of such components.
2980 Contents is assigned to components by the COMPONENT argument of CMake's
2982 install() command. Components can be annotated with user-friendly
2983 names and descriptions, inter-component dependencies, etc., and grouped
2984 in various ways to customize the resulting installer, using the com‐
2985 mands described below.
2986 To specify different groupings for different CPack generators use a
2988 CPACK_PROJECT_CONFIG_FILE.
2989 Variables
2991 The following variables influence the component-specific packaging:
2992 CPACK_COMPONENTS_ALL
2994 The list of component to install.
2995 The default value of this variable is computed by CPack and con‐
2997 tains all components defined by the project. The user may set
2998 it to only include the specified components.
2999 Instead of specifying all the desired components, it is possible
3001 to obtain a list of all defined components and then remove the
3002 unwanted ones from the list. The get_cmake_property() command
3003 can be used to obtain the COMPONENTS property, then the list(RE‐
3004 MOVE_ITEM) command can be used to remove the unwanted ones. For
3005 example, to use all defined components except foo and bar:
3006 get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS)
3008 list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar")
3009 CPACK_<GENNAME>_COMPONENT_INSTALL
3011 Enable/Disable component install for CPack generator <GENNAME>.
3012 Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc...) has
3014 a legacy default behavior. e.g. RPM builds monolithic whereas
3015 NSIS builds component. One can change the default behavior by
3016 setting this variable to 0/1 or OFF/ON.
3017 CPACK_COMPONENTS_GROUPING
3019 Specify how components are grouped for multi-package compo‐
3020 nent-aware CPack generators.
3021 Some generators like RPM or ARCHIVE (TGZ, ZIP, ...) may generate
3023 several packages files when there are components, depending on
3024 the value of this variable:
3025 • ONE_PER_GROUP (default): create one package per component
3027 group
3028 • IGNORE : create one package per component (ignore the groups)
3030 • ALL_COMPONENTS_IN_ONE : create a single package with all re‐
3032 quested components
3033 CPACK_COMPONENT_<compName>_DISPLAY_NAME
3035 The name to be displayed for a component.
3036 CPACK_COMPONENT_<compName>_DESCRIPTION
3038 The description of a component.
3039 CPACK_COMPONENT_<compName>_GROUP
3041 The group of a component.
3042 CPACK_COMPONENT_<compName>_DEPENDS
3044 The dependencies (list of components) on which this component
3045 depends.
3046 CPACK_COMPONENT_<compName>_HIDDEN
3048 True if this component is hidden from the user.
3049 CPACK_COMPONENT_<compName>_REQUIRED
3051 True if this component is required.
3052 CPACK_COMPONENT_<compName>_DISABLED
3054 True if this component is not selected to be installed by de‐
3055 fault.
3056 Commands
3058 Add component
3059 cpack_add_component
3060 Describe an installation component.
3062 cpack_add_component(compname
3064 [DISPLAY_NAME name]
3065 [DESCRIPTION description]
3066 [HIDDEN | REQUIRED | DISABLED ]
3067 [GROUP group]
3068 [DEPENDS comp1 comp2 ... ]
3069 [INSTALL_TYPES type1 type2 ... ]
3070 [DOWNLOADED]
3071 [ARCHIVE_FILE filename]
3072 [PLIST filename])
3073 compname is the name of an installation component, as defined by the
3075 COMPONENT argument of one or more CMake install() commands. With the
3076 cpack_add_component command one can set a name, a description, and
3077 other attributes of an installation component. One can also assign a
3078 component to a component group.
3079 DISPLAY_NAME is the displayed name of the component, used in graphical
3081 installers to display the component name. This value can be any
3082 string.
3083 DESCRIPTION is an extended description of the component, used in graph‐
3085 ical installers to give the user additional information about the com‐
3086 ponent. Descriptions can span multiple lines using \n as the line sep‐
3087 arator. Typically, these descriptions should be no more than a few
3088 lines long.
3089 HIDDEN indicates that this component will be hidden in the graphical
3091 installer, so that the user cannot directly change whether it is in‐
3092 stalled or not.
3093 REQUIRED indicates that this component is required, and therefore will
3095 always be installed. It will be visible in the graphical installer,
3096 but it cannot be unselected. (Typically, required components are shown
3097 greyed out).
3098 DISABLED indicates that this component should be disabled (unselected)
3100 by default. The user is free to select this component for installa‐
3101 tion, unless it is also HIDDEN.
3102 DEPENDS lists the components on which this component depends. If this
3104 component is selected, then each of the components listed must also be
3105 selected. The dependency information is encoded within the installer
3106 itself, so that users cannot install inconsistent sets of components.
3107 GROUP names the component group of which this component is a part. If
3109 not provided, the component will be a standalone component, not part of
3110 any component group. Component groups are described with the
3111 cpack_add_component_group command, detailed below.
3112 INSTALL_TYPES lists the installation types of which this component is a
3114 part. When one of these installations types is selected, this compo‐
3115 nent will automatically be selected. Installation types are described
3116 with the cpack_add_install_type command, detailed below.
3117 DOWNLOADED indicates that this component should be downloaded
3119 on-the-fly by the installer, rather than packaged in with the installer
3120 itself. For more information, see the cpack_configure_downloads com‐
3121 mand.
3122 ARCHIVE_FILE provides a name for the archive file created by CPack to
3124 be used for downloaded components. If not supplied, CPack will create
3125 a file with some name based on CPACK_PACKAGE_FILE_NAME and the name of
3126 the component. See cpack_configure_downloads for more information.
3127 PLIST gives a filename that is passed to pkgbuild with the --compo‐
3129 nent-plist argument when using the productbuild generator.
3130 Add component group
3132 cpack_add_component_group
3133 Describes a group of related CPack installation components.
3135 cpack_add_component_group(groupname
3137 [DISPLAY_NAME name]
3138 [DESCRIPTION description]
3139 [PARENT_GROUP parent]
3140 [EXPANDED]
3141 [BOLD_TITLE])
3142 The cpack_add_component_group describes a group of installation compo‐
3144 nents, which will be placed together within the listing of options.
3145 Typically, component groups allow the user to select/deselect all of
3146 the components within a single group via a single group-level option.
3147 Use component groups to reduce the complexity of installers with many
3148 options. groupname is an arbitrary name used to identify the group in
3149 the GROUP argument of the cpack_add_component command, which is used to
3150 place a component in a group. The name of the group must not conflict
3151 with the name of any component.
3152 DISPLAY_NAME is the displayed name of the component group, used in
3154 graphical installers to display the component group name. This value
3155 can be any string.
3156 DESCRIPTION is an extended description of the component group, used in
3158 graphical installers to give the user additional information about the
3159 components within that group. Descriptions can span multiple lines us‐
3160 ing \n as the line separator. Typically, these descriptions should be
3161 no more than a few lines long.
3162 PARENT_GROUP, if supplied, names the parent group of this group. Par‐
3164 ent groups are used to establish a hierarchy of groups, providing an
3165 arbitrary hierarchy of groups.
3166 EXPANDED indicates that, by default, the group should show up as "ex‐
3168 panded", so that the user immediately sees all of the components within
3169 the group. Otherwise, the group will initially show up as a single en‐
3170 try.
3171 BOLD_TITLE indicates that the group title should appear in bold, to
3173 call the user's attention to the group.
3174 Add installation type
3176 cpack_add_install_type
3177 Add a new installation type containing a set of predefined component
3179 selections to the graphical installer.
3180 cpack_add_install_type(typename
3182 [DISPLAY_NAME name])
3183 The cpack_add_install_type command identifies a set of preselected com‐
3185 ponents that represents a common use case for an application. For ex‐
3186 ample, a "Developer" install type might include an application along
3187 with its header and library files, while an "End user" install type
3188 might just include the application's executable. Each component iden‐
3189 tifies itself with one or more install types via the INSTALL_TYPES ar‐
3190 gument to cpack_add_component.
3191 DISPLAY_NAME is the displayed name of the install type, which will typ‐
3193 ically show up in a drop-down box within a graphical installer. This
3194 value can be any string.
3195 Configure downloads
3197 cpack_configure_downloads
3198 Configure CPack to download selected components on-the-fly as part of
3200 the installation process.
3201 cpack_configure_downloads(site
3203 [UPLOAD_DIRECTORY dirname]
3204 [ALL]
3205 [ADD_REMOVE|NO_ADD_REMOVE])
3206 The cpack_configure_downloads command configures installation-time
3208 downloads of selected components. For each downloadable component,
3209 CPack will create an archive containing the contents of that component,
3210 which should be uploaded to the given site. When the user selects that
3211 component for installation, the installer will download and extract the
3212 component in place. This feature is useful for creating small install‐
3213 ers that only download the requested components, saving bandwidth. Ad‐
3214 ditionally, the installers are small enough that they will be installed
3215 as part of the normal installation process, and the "Change" button in
3216 Windows Add/Remove Programs control panel will allow one to add or re‐
3217 move parts of the application after the original installation. On Win‐
3218 dows, the downloaded-components functionality requires the ZipDLL
3219 plug-in for NSIS, available at:
3220 http://nsis.sourceforge.net/ZipDLL_plug-in
3222 On macOS, installers that download components on-the-fly can only be
3224 built and installed on system using macOS 10.5 or later.
3225 The site argument is a URL where the archives for downloadable compo‐
3227 nents will reside, e.g., https://cmake.org/files/2.6.1/installer/ All
3228 of the archives produced by CPack should be uploaded to that location.
3229 UPLOAD_DIRECTORY is the local directory where CPack will create the
3231 various archives for each of the components. The contents of this di‐
3232 rectory should be uploaded to a location accessible by the URL given in
3233 the site argument. If omitted, CPack will use the directory CPackU‐
3234 ploads inside the CMake binary directory to store the generated ar‐
3235 chives.
3236 The ALL flag indicates that all components be downloaded. Otherwise,
3238 only those components explicitly marked as DOWNLOADED or that have a
3239 specified ARCHIVE_FILE will be downloaded. Additionally, the ALL op‐
3240 tion implies ADD_REMOVE (unless NO_ADD_REMOVE is specified).
3241 ADD_REMOVE indicates that CPack should install a copy of the installer
3243 that can be called from Windows' Add/Remove Programs dialog (via the
3244 "Modify" button) to change the set of installed components. NO_ADD_RE‐
3245 MOVE turns off this behavior. This option is ignored on Mac OS X.
3246 CPackIFW
3248 New in version 3.1.
3249 This module looks for the location of the command-line utilities sup‐
3252 plied with the Qt Installer Framework (QtIFW).
3253 The module also defines several commands to control the behavior of the
3255 CPack IFW Generator.
3256 Commands
3258 The module defines the following commands:
3259 cpack_ifw_configure_component
3261 Sets the arguments specific to the CPack IFW generator.
3262 cpack_ifw_configure_component(<compname> [COMMON] [ESSENTIAL] [VIRTUAL]
3264 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
3265 [NAME <name>]
3266 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
3267 [DESCRIPTION <description>] # Note: Internationalization supported
3268 [UPDATE_TEXT <update_text>]
3269 [VERSION <version>]
3270 [RELEASE_DATE <release_date>]
3271 [SCRIPT <script>]
3272 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
3273 [DEPENDS|DEPENDENCIES <com_id> ...]
3274 [AUTO_DEPEND_ON <comp_id> ...]
3275 [LICENSES <display_name> <file_path> ...]
3276 [DEFAULT <value>]
3277 [USER_INTERFACES <file_path> <file_path> ...]
3278 [TRANSLATIONS <file_path> <file_path> ...]
3279 [REPLACES <comp_id> ...]
3280 [CHECKABLE <value>])
3281 This command should be called after cpack_add_component() com‐
3283 mand.
3284 COMMON if set, then the component will be packaged and installed
3286 as part of a group to which it belongs.
3287 ESSENTIAL
3289 New in version 3.6.
3290 if set, then the package manager stays disabled until
3293 that component is updated.
3294 VIRTUAL
3296 New in version 3.8.
3297 if set, then the component will be hidden from the in‐
3300 staller. It is a equivalent of the HIDDEN option from
3301 the cpack_add_component() command.
3302 FORCED_INSTALLATION
3304 New in version 3.8.
3305 if set, then the component must always be installed. It
3308 is a equivalent of the REQUIRED option from the
3309 cpack_add_component() command.
3310 REQUIRES_ADMIN_RIGHTS
3312 New in version 3.8.
3313 set it if the component needs to be installed with ele‐
3316 vated permissions.
3317 NAME is used to create domain-like identification for this
3319 component. By default used origin component name.
3320 DISPLAY_NAME
3322 New in version 3.8.
3323 set to rewrite original name configured by cpack_add_com‐
3326 ponent() command.
3327 DESCRIPTION
3329 New in version 3.8.
3330 set to rewrite original description configured by
3333 cpack_add_component() command.
3334 UPDATE_TEXT
3336 New in version 3.8.
3337 will be added to the component description if this is an
3340 update to the component.
3341 VERSION
3343 is version of component. By default used CPACK_PACK‐
3344 AGE_VERSION.
3345 RELEASE_DATE
3347 New in version 3.8.
3348 keep empty to auto generate.
3351 SCRIPT is a relative or absolute path to operations script for
3353 this component.
3354 SORTING_PRIORITY
3356 New in version 3.8.
3357 is priority of the component in the tree.
3360 PRIORITY
3362 Deprecated since version 3.8: Old name for SORTING_PRIOR‐
3363 ITY.
3364 DEPENDS, DEPENDENCIES
3367 New in version 3.8.
3368 list of dependency component or component group identi‐
3371 fiers in QtIFW style.
3372 New in version 3.21.
3374 Component or group names listed as dependencies may con‐
3377 tain hyphens. This requires QtIFW 3.1 or later.
3378 AUTO_DEPEND_ON
3380 New in version 3.8.
3381 list of identifiers of component or component group in
3384 QtIFW style that this component has an automatic depen‐
3385 dency on.
3386 LICENSES
3388 pair of <display_name> and <file_path> of license text
3389 for this component. You can specify more then one li‐
3390 cense.
3391 DEFAULT
3393 New in version 3.8.
3394 Possible values are: TRUE, FALSE, and SCRIPT. Set to
3397 FALSE to disable the component in the installer or to
3398 SCRIPT to resolved during runtime (don't forget add the
3399 file of the script as a value of the SCRIPT option).
3400 USER_INTERFACES
3402 New in version 3.7.
3403 is a list of <file_path> ('.ui' files) representing pages
3406 to load.
3407 TRANSLATIONS
3409 New in version 3.8.
3410 is a list of <file_path> ('.qm' files) representing
3413 translations to load.
3414 REPLACES
3416 New in version 3.10.
3417 list of identifiers of component or component group to
3420 replace.
3421 CHECKABLE
3423 New in version 3.10.
3424 Possible values are: TRUE, FALSE. Set to FALSE if you
3427 want to hide the checkbox for an item. This is useful
3428 when only a few subcomponents should be selected instead
3429 of all.
3430 cpack_ifw_configure_component_group
3432 Sets the arguments specific to the CPack IFW generator.
3433 cpack_ifw_configure_component_group(<groupname> [VIRTUAL]
3435 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
3436 [NAME <name>]
3437 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
3438 [DESCRIPTION <description>] # Note: Internationalization supported
3439 [UPDATE_TEXT <update_text>]
3440 [VERSION <version>]
3441 [RELEASE_DATE <release_date>]
3442 [SCRIPT <script>]
3443 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
3444 [DEPENDS|DEPENDENCIES <com_id> ...]
3445 [AUTO_DEPEND_ON <comp_id> ...]
3446 [LICENSES <display_name> <file_path> ...]
3447 [DEFAULT <value>]
3448 [USER_INTERFACES <file_path> <file_path> ...]
3449 [TRANSLATIONS <file_path> <file_path> ...]
3450 [REPLACES <comp_id> ...]
3451 [CHECKABLE <value>])
3452 This command should be called after cpack_add_component_group()
3454 command.
3455 VIRTUAL
3457 New in version 3.8.
3458 if set, then the group will be hidden from the installer.
3461 Note that setting this on a root component does not work.
3462 FORCED_INSTALLATION
3464 New in version 3.8.
3465 if set, then the group must always be installed.
3468 REQUIRES_ADMIN_RIGHTS
3470 New in version 3.8.
3471 set it if the component group needs to be installed with
3474 elevated permissions.
3475 NAME is used to create domain-like identification for this
3477 component group. By default used origin component group
3478 name.
3479 DISPLAY_NAME
3481 New in version 3.8.
3482 set to rewrite original name configured by cpack_add_com‐
3485 ponent_group() command.
3486 DESCRIPTION
3488 New in version 3.8.
3489 set to rewrite original description configured by
3492 cpack_add_component_group() command.
3493 UPDATE_TEXT
3495 New in version 3.8.
3496 will be added to the component group description if this
3499 is an update to the component group.
3500 VERSION
3502 is version of component group. By default used
3503 CPACK_PACKAGE_VERSION.
3504 RELEASE_DATE
3506 New in version 3.8.
3507 keep empty to auto generate.
3510 SCRIPT is a relative or absolute path to operations script for
3512 this component group.
3513 SORTING_PRIORITY
3515 is priority of the component group in the tree.
3516 PRIORITY
3518 Deprecated since version 3.8: Old name for SORTING_PRIOR‐
3519 ITY.
3520 DEPENDS, DEPENDENCIES
3523 New in version 3.8.
3524 list of dependency component or component group identi‐
3527 fiers in QtIFW style.
3528 New in version 3.21.
3530 Component or group names listed as dependencies may con‐
3533 tain hyphens. This requires QtIFW 3.1 or later.
3534 AUTO_DEPEND_ON
3536 New in version 3.8.
3537 list of identifiers of component or component group in
3540 QtIFW style that this component group has an automatic
3541 dependency on.
3542 LICENSES
3544 pair of <display_name> and <file_path> of license text
3545 for this component group. You can specify more then one
3546 license.
3547 DEFAULT
3549 New in version 3.8.
3550 Possible values are: TRUE, FALSE, and SCRIPT. Set to
3553 TRUE to preselect the group in the installer (this takes
3554 effect only on groups that have no visible child compo‐
3555 nents) or to SCRIPT to resolved during runtime (don't
3556 forget add the file of the script as a value of the
3557 SCRIPT option).
3558 USER_INTERFACES
3560 New in version 3.7.
3561 is a list of <file_path> ('.ui' files) representing pages
3564 to load.
3565 TRANSLATIONS
3567 New in version 3.8.
3568 is a list of <file_path> ('.qm' files) representing
3571 translations to load.
3572 REPLACES
3574 New in version 3.10.
3575 list of identifiers of component or component group to
3578 replace.
3579 CHECKABLE
3581 New in version 3.10.
3582 Possible values are: TRUE, FALSE. Set to FALSE if you
3585 want to hide the checkbox for an item. This is useful
3586 when only a few subcomponents should be selected instead
3587 of all.
3588 cpack_ifw_add_repository
3590 Add QtIFW specific remote repository to binary installer.
3591 cpack_ifw_add_repository(<reponame> [DISABLED]
3593 URL <url>
3594 [USERNAME <username>]
3595 [PASSWORD <password>]
3596 [DISPLAY_NAME <display_name>])
3597 This command will also add the <reponame> repository to a vari‐
3599 able CPACK_IFW_REPOSITORIES_ALL.
3600 DISABLED
3602 if set, then the repository will be disabled by default.
3603 URL is points to a list of available components.
3605 USERNAME
3607 is used as user on a protected repository.
3608 PASSWORD
3610 is password to use on a protected repository.
3611 DISPLAY_NAME
3613 is string to display instead of the URL.
3614 cpack_ifw_update_repository
3616 New in version 3.6.
3617 Update QtIFW specific repository from remote repository.
3620 cpack_ifw_update_repository(<reponame>
3622 [[ADD|REMOVE] URL <url>]|
3623 [REPLACE OLD_URL <old_url> NEW_URL <new_url>]]
3624 [USERNAME <username>]
3625 [PASSWORD <password>]
3626 [DISPLAY_NAME <display_name>])
3627 This command will also add the <reponame> repository to a vari‐
3629 able CPACK_IFW_REPOSITORIES_ALL.
3630 URL is points to a list of available components.
3632 OLD_URL
3634 is points to a list that will replaced.
3635 NEW_URL
3637 is points to a list that will replace to.
3638 USERNAME
3640 is used as user on a protected repository.
3641 PASSWORD
3643 is password to use on a protected repository.
3644 DISPLAY_NAME
3646 is string to display instead of the URL.
3647 cpack_ifw_add_package_resources
3649 New in version 3.7.
3650 Add additional resources in the installer binary.
3653 cpack_ifw_add_package_resources(<file_path> <file_path> ...)
3655 This command will also add the specified files to a variable
3657 CPACK_IFW_PACKAGE_RESOURCES.
3658 CPackIFWConfigureFile
3660 New in version 3.8.
3661 The module defines configure_file() similar command to configure file
3664 templates prepared in QtIFW/SDK/Creator style.
3665 Commands
3667 The module defines the following commands:
3668 cpack_ifw_configure_file
3670 Copy a file to another location and modify its contents.
3671 cpack_ifw_configure_file(<input> <output>)
3673 Copies an <input> file to an <output> file and substitutes vari‐
3675 able values referenced as %{VAR} or %VAR% in the input file con‐
3676 tent. Each variable reference will be replaced with the current
3677 value of the variable, or the empty string if the variable is
3678 not defined.
3679 CSharpUtilities
3681 New in version 3.8.
3682 Functions to make configuration of CSharp/.NET targets easier.
3685 A collection of CMake utility functions useful for dealing with CSharp
3687 targets for Visual Studio generators from version 2010 and later.
3688 The following functions are provided by this module:
3690 Main functions
3692 • csharp_set_windows_forms_properties()
3694 • csharp_set_designer_cs_properties()
3696 • csharp_set_xaml_cs_properties()
3698 Helper functions
3700 • csharp_get_filename_keys()
3702 • csharp_get_filename_key_base()
3704 • csharp_get_dependentupon_name()
3706 Main functions provided by the module
3708 csharp_set_windows_forms_properties
3709 Sets source file properties for use of Windows Forms. Use this,
3710 if your CSharp target uses Windows Forms:
3711 csharp_set_windows_forms_properties([<file1> [<file2> [...]]])
3713 <fileN>
3715 List of all source files which are relevant for setting
3716 the VS_CSHARP_<tagname> properties (including .cs, .resx
3717 and .Designer.cs extensions).
3718 In the list of all given files for all files ending with .De‐
3720 signer.cs and .resx is searched. For every designer or resource
3721 file a file with the same base name but only .cs as extension is
3722 searched. If this is found, the VS_CSHARP_<tagname> properties
3723 are set as follows:
3724 for the .cs file:
3726 • VS_CSHARP_SubType "Form"
3728 for the .Designer.cs file (if it exists):
3730 • VS_CSHARP_DependentUpon <cs-filename>
3732 • VS_CSHARP_DesignTime "" (delete tag if previously de‐
3734 fined)
3735 • VS_CSHARP_AutoGen ""(delete tag if previously defined)
3737 for the .resx file (if it exists):
3739 • VS_RESOURCE_GENERATOR "" (delete tag if previously de‐
3741 fined)
3742 • VS_CSHARP_DependentUpon <cs-filename>
3744 • VS_CSHARP_SubType "Designer"
3746 csharp_set_designer_cs_properties
3748 Sets source file properties of .Designer.cs files depending on
3749 sibling filenames. Use this, if your CSharp target does not use
3750 Windows Forms (for Windows Forms use
3751 csharp_set_designer_cs_properties() instead):
3752 csharp_set_designer_cs_properties([<file1> [<file2> [...]]])
3754 <fileN>
3756 List of all source files which are relevant for setting
3757 the VS_CSHARP_<tagname> properties (including .cs, .resx,
3758 .settings and .Designer.cs extensions).
3759 In the list of all given files for all files ending with .De‐
3761 signer.cs is searched. For every designer file all files with
3762 the same base name but different extensions are searched. If a
3763 match is found, the source file properties of the designer file
3764 are set depending on the extension of the matched file:
3765 if match is .resx file:
3767 • VS_CSHARP_AutoGen "True"
3769 • VS_CSHARP_DesignTime "True"
3771 • VS_CSHARP_DependentUpon <resx-filename>
3773 if match is .cs file:
3775 • VS_CSHARP_DependentUpon <cs-filename>
3777 if match is .settings file:
3779 • VS_CSHARP_AutoGen "True"
3781 • VS_CSHARP_DesignTimeSharedInput "True"
3783 • VS_CSHARP_DependentUpon <settings-filename>
3785 NOTE:
3787 Because the source file properties of the .Designer.cs file are set
3788 according to the found matches and every match sets the
3789 VS_CSHARP_DependentUpon property, there should only be one match for
3790 each Designer.cs file.
3791 csharp_set_xaml_cs_properties
3793 Sets source file properties for use of Windows Presentation
3794 Foundation (WPF) and XAML. Use this, if your CSharp target uses
3795 WPF/XAML:
3796 csharp_set_xaml_cs_properties([<file1> [<file2> [...]]])
3798 <fileN>
3800 List of all source files which are relevant for setting
3801 the VS_CSHARP_<tagname> properties (including .cs, .xaml,
3802 and .xaml.cs extensions).
3803 In the list of all given files for all files ending with
3805 .xaml.cs is searched. For every xaml-cs file, a file with the
3806 same base name but extension .xaml is searched. If a match is
3807 found, the source file properties of the .xaml.cs file are set:
3808 • VS_CSHARP_DependentUpon <xaml-filename>
3810 Helper functions which are used by the above ones
3812 csharp_get_filename_keys
3813 Helper function which computes a list of key values to identify
3814 source files independently of relative/absolute paths given in
3815 cmake and eliminates case sensitivity:
3816 csharp_get_filename_keys(OUT [<file1> [<file2> [...]]])
3818 OUT Name of the variable in which the list of keys is stored
3820 <fileN>
3822 filename(s) as given to to CSharp target using add_li‐
3823 brary() or add_executable()
3824 In some way the function applies a canonicalization to the
3826 source names. This is necessary to find file matches if the
3827 files have been added to the target with different directory
3828 prefixes:
3829 add_library(lib
3831 myfile.cs
3832 ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs)
3833 set_source_files_properties(myfile.Designer.cs PROPERTIES
3835 VS_CSHARP_DependentUpon myfile.cs)
3836 # this will fail, because in cmake
3838 # - ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs
3839 # - myfile.Designer.cs
3840 # are not the same source file. The source file property is not set.
3841 csharp_get_filename_key_base
3843 Returns the full filepath and name without extension of a key.
3844 KEY is expected to be a key from csharp_get_filename_keys. In
3845 BASE the value of KEY without the file extension is returned:
3846 csharp_get_filename_key_base(BASE KEY)
3848 BASE Name of the variable with the computed "base" of KEY.
3850 KEY The key of which the base will be computed. Expected to
3852 be a upper case full filename.
3853 csharp_get_dependentupon_name
3855 Computes a string which can be used as value for the source file
3856 property VS_CSHARP_<tagname> with target being DependentUpon:
3857 csharp_get_dependentupon_name(NAME FILE)
3859 NAME Name of the variable with the result value
3861 FILE Filename to convert to <DependentUpon> value
3863 Actually this is only the filename without any path given at the
3865 moment.
3866 CTest
3868 Configure a project for testing with CTest/CDash
3869 Include this module in the top CMakeLists.txt file of a project to en‐
3871 able testing with CTest and dashboard submissions to CDash:
3872 project(MyProject)
3874 ...
3875 include(CTest)
3876 The module automatically creates a BUILD_TESTING option that selects
3878 whether to enable testing support (ON by default). After including the
3879 module, use code like:
3880 if(BUILD_TESTING)
3882 # ... CMake code to create tests ...
3883 endif()
3884 to creating tests when testing is enabled.
3886 To enable submissions to a CDash server, create a CTestConfig.cmake
3888 file at the top of the project with content such as:
3889 set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
3891 set(CTEST_SUBMIT_URL "http://my.cdash.org/submit.php?project=MyProject")
3892 (the CDash server can provide the file to a project administrator who
3894 configures MyProject). Settings in the config file are shared by both
3895 this CTest module and the ctest(1) command-line Dashboard Client mode
3896 (ctest -S).
3897 While building a project for submission to CDash, CTest scans the build
3899 output for errors and warnings and reports them with surrounding con‐
3900 text from the build log. This generic approach works for all build
3901 tools, but does not give details about the command invocation that pro‐
3902 duced a given problem. One may get more detailed reports by setting
3903 the CTEST_USE_LAUNCHERS variable:
3904 set(CTEST_USE_LAUNCHERS 1)
3906 in the CTestConfig.cmake file.
3908 CTestCoverageCollectGCOV
3910 New in version 3.2.
3911 This module provides the ctest_coverage_collect_gcov function.
3914 This function runs gcov on all .gcda files found in the binary tree and
3916 packages the resulting .gcov files into a tar file. This tarball also
3917 contains the following:
3918 • data.json defines the source and build directories for use by CDash.
3920 • Labels.json indicates any LABELS that have been set on the source
3922 files.
3923 • The uncovered directory holds any uncovered files found by CTEST_EX‐
3925 TRA_COVERAGE_GLOB.
3926 After generating this tar file, it can be sent to CDash for display
3928 with the ctest_submit(CDASH_UPLOAD) command.
3929 ctest_coverage_collect_gcov
3931 ctest_coverage_collect_gcov(TARBALL <tarfile>
3933 [SOURCE <source_dir>][BUILD <build_dir>]
3934 [GCOV_COMMAND <gcov_command>]
3935 [GCOV_OPTIONS <options>...]
3936 )
3937 Run gcov and package a tar file for CDash. The options are:
3939 TARBALL <tarfile>
3941 Specify the location of the .tar file to be created for
3942 later upload to CDash. Relative paths will be inter‐
3943 preted with respect to the top-level build directory.
3944 TARBALL_COMPRESSION <option>
3946 New in version 3.18.
3947 Specify a compression algorithm for the TARBALL data
3950 file. Using this option reduces the size of the data
3951 file before it is submitted to CDash. <option> must be
3952 one of GZIP, BZIP2, XZ, ZSTD, FROM_EXT, or an expression
3953 that CMake evaluates as FALSE. The default value is
3954 BZIP2.
3955 If FROM_EXT is specified, the resulting file will be com‐
3957 pressed based on the file extension of the <tarfile>
3958 (i.e. .tar.gz will use GZIP compression). File extensions
3959 that will produce compressed output include .tar.gz,
3960 .tgz, .tar.bzip2, .tbz, .tar.xz, and .txz.
3961 SOURCE <source_dir>
3963 Specify the top-level source directory for the build.
3964 Default is the value of CTEST_SOURCE_DIRECTORY.
3965 BUILD <build_dir>
3967 Specify the top-level build directory for the build. De‐
3968 fault is the value of CTEST_BINARY_DIRECTORY.
3969 GCOV_COMMAND <gcov_command>
3971 Specify the full path to the gcov command on the machine.
3972 Default is the value of CTEST_COVERAGE_COMMAND.
3973 GCOV_OPTIONS <options>...
3975 Specify options to be passed to gcov. The gcov command
3976 is run as gcov <options>... -o <gcov-dir> <file>.gcda.
3977 If not specified, the default option is just -b -x.
3978 GLOB New in version 3.6.
3980 Recursively search for .gcda files in build_dir rather
3983 than determining search locations by reading TargetDirec‐
3984 tories.txt.
3985 DELETE New in version 3.6.
3987 Delete coverage files after they've been packaged into
3990 the .tar.
3991 QUIET Suppress non-error messages that otherwise would have
3993 been printed out by this function.
3994 New in version 3.3: Added support for the CTEST_CUSTOM_COVER‐
3996 AGE_EXCLUDE variable.
3997 CTestScriptMode
4000 This file is read by ctest in script mode (-S)
4001 CTestUseLaunchers
4003 Set the RULE_LAUNCH_* global properties when CTEST_USE_LAUNCHERS is on.
4004 CTestUseLaunchers is automatically included when you include(CTest).
4006 However, it is split out into its own module file so projects can use
4007 the CTEST_USE_LAUNCHERS functionality independently.
4008 To use launchers, set CTEST_USE_LAUNCHERS to ON in a ctest -S dashboard
4010 script, and then also set it in the cache of the configured project.
4011 Both cmake and ctest need to know the value of it for the launchers to
4012 work properly. CMake needs to know in order to generate proper build
4013 rules, and ctest, in order to produce the proper error and warning
4014 analysis.
4015 For convenience, you may set the ENV variable CTEST_USE_LAUNCHERS_DE‐
4017 FAULT in your ctest -S script, too. Then, as long as your CMakeLists
4018 uses include(CTest) or include(CTestUseLaunchers), it will use the
4019 value of the ENV variable to initialize a CTEST_USE_LAUNCHERS cache
4020 variable. This cache variable initialization only occurs if
4021 CTEST_USE_LAUNCHERS is not already defined.
4022 New in version 3.8: If CTEST_USE_LAUNCHERS is on in a ctest -S script
4024 the ctest_configure command will add -DCTEST_USE_LAUNCHERS:BOOL=TRUE to
4025 the cmake command used to configure the project.
4026 Dart
4029 Configure a project for testing with CTest or old Dart Tcl Client
4030 This file is the backwards-compatibility version of the CTest module.
4032 It supports using the old Dart 1 Tcl client for driving dashboard sub‐
4033 missions as well as testing with CTest. This module should be included
4034 in the CMakeLists.txt file at the top of a project. Typical usage:
4035 include(Dart)
4037 if(BUILD_TESTING)
4038 # ... testing related CMake code ...
4039 endif()
4040 The BUILD_TESTING option is created by the Dart module to determine
4042 whether testing support should be enabled. The default is ON.
4043 DeployQt4
4045 Functions to help assemble a standalone Qt4 executable.
4046 A collection of CMake utility functions useful for deploying Qt4 exe‐
4048 cutables.
4049 The following functions are provided by this module:
4051 write_qt4_conf
4053 resolve_qt4_paths
4054 fixup_qt4_executable
4055 install_qt4_plugin_path
4056 install_qt4_plugin
4057 install_qt4_executable
4058 Requires CMake 2.6 or greater because it uses function and PAR‐
4060 ENT_SCOPE. Also depends on BundleUtilities.cmake.
4061 write_qt4_conf(<qt_conf_dir> <qt_conf_contents>)
4063 Writes a qt.conf file with the <qt_conf_contents> into <qt_conf_dir>.
4065 resolve_qt4_paths(<paths_var> [<executable_path>])
4067 Loop through <paths_var> list and if any don't exist resolve them rela‐
4069 tive to the <executable_path> (if supplied) or the CMAKE_INSTALL_PRE‐
4070 FIX.
4071 fixup_qt4_executable(<executable>
4073 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>])
4074 Copies Qt plugins, writes a Qt configuration file (if needed) and fixes
4076 up a Qt4 executable using BundleUtilities so it is standalone and can
4077 be drag-and-drop copied to another machine as long as all of the system
4078 libraries are compatible.
4079 <executable> should point to the executable to be fixed-up.
4081 <qtplugins> should contain a list of the names or paths of any Qt plug‐
4083 ins to be installed.
4084 <libs> will be passed to BundleUtilities and should be a list of any
4086 already installed plugins, libraries or executables to also be
4087 fixed-up.
4088 <dirs> will be passed to BundleUtilities and should contain and direc‐
4090 tories to be searched to find library dependencies.
4091 <plugins_dir> allows an custom plugins directory to be used.
4093 <request_qt_conf> will force a qt.conf file to be written even if not
4095 needed.
4096 install_qt4_plugin_path(plugin executable copy installed_plugin_path_var
4098 <plugins_dir> <component> <configurations>)
4099 Install (or copy) a resolved <plugin> to the default plugins directory
4101 (or <plugins_dir>) relative to <executable> and store the result in
4102 <installed_plugin_path_var>.
4103 If <copy> is set to TRUE then the plugins will be copied rather than
4105 installed. This is to allow this module to be used at CMake time
4106 rather than install time.
4107 If <component> is set then anything installed will use this COMPONENT.
4109 install_qt4_plugin(plugin executable copy installed_plugin_path_var
4111 <plugins_dir> <component>)
4112 Install (or copy) an unresolved <plugin> to the default plugins direc‐
4114 tory (or <plugins_dir>) relative to <executable> and store the result
4115 in <installed_plugin_path_var>. See documentation of IN‐
4116 STALL_QT4_PLUGIN_PATH.
4117 install_qt4_executable(<executable>
4119 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>])
4120 Installs Qt plugins, writes a Qt configuration file (if needed) and
4122 fixes up a Qt4 executable using BundleUtilities so it is standalone and
4123 can be drag-and-drop copied to another machine as long as all of the
4124 system libraries are compatible. The executable will be fixed-up at
4125 install time. <component> is the COMPONENT used for bundle fixup and
4126 plugin installation. See documentation of FIXUP_QT4_BUNDLE.
4127 ExternalData
4129 Manage data files stored outside source tree
4130 Introduction
4132 Use this module to unambiguously reference data files stored outside
4133 the source tree and fetch them at build time from arbitrary local and
4134 remote content-addressed locations. Functions provided by this module
4135 recognize arguments with the syntax DATA{<name>} as references to ex‐
4136 ternal data, replace them with full paths to local copies of those
4137 data, and create build rules to fetch and update the local copies.
4138 For example:
4140 include(ExternalData)
4142 set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
4143 "file:////host/share/%(algo)/%(hash)"
4144 "http://data.org/%(algo)/%(hash)")
4145 ExternalData_Add_Test(MyData
4146 NAME MyTest
4147 COMMAND MyExe DATA{MyInput.png}
4148 )
4149 ExternalData_Add_Target(MyData)
4150 When test MyTest runs the DATA{MyInput.png} argument will be replaced
4152 by the full path to a real instance of the data file MyInput.png on
4153 disk. If the source tree contains a content link such as MyIn‐
4154 put.png.md5 then the MyData target creates a real MyInput.png in the
4155 build tree.
4156 Module Functions
4158 ExternalData_Expand_Arguments
4159 The ExternalData_Expand_Arguments function evaluates DATA{} ref‐
4160 erences in its arguments and constructs a new list of arguments:
4161 ExternalData_Expand_Arguments(
4163 <target> # Name of data management target
4164 <outVar> # Output variable
4165 [args...] # Input arguments, DATA{} allowed
4166 )
4167 It replaces each DATA{} reference in an argument with the full
4169 path of a real data file on disk that will exist after the <tar‐
4170 get> builds.
4171 ExternalData_Add_Test
4173 The ExternalData_Add_Test function wraps around the CMake
4174 add_test() command but supports DATA{} references in its argu‐
4175 ments:
4176 ExternalData_Add_Test(
4178 <target> # Name of data management target
4179 ... # Arguments of add_test(), DATA{} allowed
4180 )
4181 It passes its arguments through ExternalData_Expand_Arguments
4183 and then invokes the add_test() command using the results.
4184 ExternalData_Add_Target
4186 The ExternalData_Add_Target function creates a custom target to
4187 manage local instances of data files stored externally:
4188 ExternalData_Add_Target(
4190 <target> # Name of data management target
4191 [SHOW_PROGRESS <ON|OFF>] # Show progress during the download
4192 )
4193 It creates custom commands in the target as necessary to make
4195 data files available for each DATA{} reference previously evalu‐
4196 ated by other functions provided by this module. Data files may
4197 be fetched from one of the URL templates specified in the Exter‐
4198 nalData_URL_TEMPLATES variable, or may be found locally in one
4199 of the paths specified in the ExternalData_OBJECT_STORES vari‐
4200 able.
4201 New in version 3.20: The SHOW_PROGRESS argument may be passed to
4203 suppress progress information during the download of objects. If
4204 not provided, it defaults to OFF for Ninja and Ninja Multi-Con‐
4205 fig generators and ON otherwise.
4206 Typically only one target is needed to manage all external data
4209 within a project. Call this function once at the end of config‐
4210 uration after all data references have been processed.
4211 Module Variables
4213 The following variables configure behavior. They should be set before
4214 calling any of the functions provided by this module.
4215 ExternalData_BINARY_ROOT
4217 The ExternalData_BINARY_ROOT variable may be set to the direc‐
4218 tory to hold the real data files named by expanded DATA{} refer‐
4219 ences. The default is CMAKE_BINARY_DIR. The directory layout
4220 will mirror that of content links under External‐
4221 Data_SOURCE_ROOT.
4222 ExternalData_CUSTOM_SCRIPT_<key>
4224 New in version 3.2.
4225 Specify a full path to a .cmake custom fetch script identified
4228 by <key> in entries of the ExternalData_URL_TEMPLATES list. See
4229 Custom Fetch Scripts.
4230 ExternalData_LINK_CONTENT
4232 The ExternalData_LINK_CONTENT variable may be set to the name of
4233 a supported hash algorithm to enable automatic conversion of
4234 real data files referenced by the DATA{} syntax into content
4235 links. For each such <file> a content link named <file><ext> is
4236 created. The original file is renamed to the form .External‐
4237 Data_<algo>_<hash> to stage it for future transmission to one of
4238 the locations in the list of URL templates (by means outside the
4239 scope of this module). The data fetch rule created for the con‐
4240 tent link will use the staged object if it cannot be found using
4241 any URL template.
4242 ExternalData_NO_SYMLINKS
4244 New in version 3.3.
4245 The real data files named by expanded DATA{} references may be
4248 made available under ExternalData_BINARY_ROOT using symbolic
4249 links on some platforms. The ExternalData_NO_SYMLINKS variable
4250 may be set to disable use of symbolic links and enable use of
4251 copies instead.
4252 ExternalData_OBJECT_STORES
4254 The ExternalData_OBJECT_STORES variable may be set to a list of
4255 local directories that store objects using the layout
4256 <dir>/%(algo)/%(hash). These directories will be searched first
4257 for a needed object. If the object is not available in any
4258 store then it will be fetched remotely using the URL templates
4259 and added to the first local store listed. If no stores are
4260 specified the default is a location inside the build tree.
4261 ExternalData_SERIES_PARSE
4263 ExternalData_SERIES_PARSE_PREFIX
4265 ExternalData_SERIES_PARSE_NUMBER
4267 ExternalData_SERIES_PARSE_SUFFIX
4269 ExternalData_SERIES_MATCH
4271 See Referencing File Series.
4272 ExternalData_SOURCE_ROOT
4274 The ExternalData_SOURCE_ROOT variable may be set to the highest
4275 source directory containing any path named by a DATA{} refer‐
4276 ence. The default is CMAKE_SOURCE_DIR. External‐
4277 Data_SOURCE_ROOT and CMAKE_SOURCE_DIR must refer to directories
4278 within a single source distribution (e.g. they come together in
4279 one tarball).
4280 ExternalData_TIMEOUT_ABSOLUTE
4282 The ExternalData_TIMEOUT_ABSOLUTE variable sets the download ab‐
4283 solute timeout, in seconds, with a default of 300 seconds. Set
4284 to 0 to disable enforcement.
4285 ExternalData_TIMEOUT_INACTIVITY
4287 The ExternalData_TIMEOUT_INACTIVITY variable sets the download
4288 inactivity timeout, in seconds, with a default of 60 seconds.
4289 Set to 0 to disable enforcement.
4290 ExternalData_URL_ALGO_<algo>_<key>
4292 New in version 3.3.
4293 Specify a custom URL component to be substituted for URL tem‐
4296 plate placeholders of the form %(algo:<key>), where <key> is a
4297 valid C identifier, when fetching an object referenced via hash
4298 algorithm <algo>. If not defined, the default URL component is
4299 just <algo> for any <key>.
4300 ExternalData_URL_TEMPLATES
4302 The ExternalData_URL_TEMPLATES may be set to provide a list of
4303 URL templates using the placeholders %(algo) and %(hash) in each
4304 template. Data fetch rules try each URL template in order by
4305 substituting the hash algorithm name for %(algo) and the hash
4306 value for %(hash). Alternatively one may use %(algo:<key>) with
4307 ExternalData_URL_ALGO_<algo>_<key> variables to gain more flexi‐
4308 bility in remote URLs.
4309 Referencing Files
4311 Referencing Single Files
4312 The DATA{} syntax is literal and the <name> is a full or relative path
4313 within the source tree. The source tree must contain either a real
4314 data file at <name> or a "content link" at <name><ext> containing a
4315 hash of the real file using a hash algorithm corresponding to <ext>.
4316 For example, the argument DATA{img.png} may be satisfied by either a
4317 real img.png file in the current source directory or a img.png.md5 file
4318 containing its MD5 sum.
4319 New in version 3.8: Multiple content links of the same name with dif‐
4321 ferent hash algorithms are supported (e.g. img.png.sha256 and
4322 img.png.sha1) so long as they all correspond to the same real file.
4323 This allows objects to be fetched from sources indexed by different
4324 hash algorithms.
4325 Referencing File Series
4328 The DATA{} syntax can be told to fetch a file series using the form
4329 DATA{<name>,:}, where the : is literal. If the source tree contains a
4330 group of files or content links named like a series then a reference to
4331 one member adds rules to fetch all of them. Although all members of a
4332 series are fetched, only the file originally named by the DATA{} argu‐
4333 ment is substituted for it. The default configuration recognizes file
4334 series names ending with #.ext, _#.ext, .#.ext, or -#.ext where # is a
4335 sequence of decimal digits and .ext is any single extension. Configure
4336 it with a regex that parses <number> and <suffix> parts from the end of
4337 <name>:
4338 ExternalData_SERIES_PARSE = regex of the form (<number>)(<suffix>)$
4340 For more complicated cases set:
4342 ExternalData_SERIES_PARSE = regex with at least two () groups
4344 ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
4345 ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
4346 ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number
4347 Configure series number matching with a regex that matches the <number>
4349 part of series members named <prefix><number><suffix>:
4350 ExternalData_SERIES_MATCH = regex matching <number> in all series members
4352 Note that the <suffix> of a series does not include a hash-algorithm
4354 extension.
4355 Referencing Associated Files
4357 The DATA{} syntax can alternatively match files associated with the
4358 named file and contained in the same directory. Associated files may
4359 be specified by options using the syntax
4360 DATA{<name>,<opt1>,<opt2>,...}. Each option may specify one file by
4361 name or specify a regular expression to match file names using the syn‐
4362 tax REGEX:<regex>. For example, the arguments:
4363 DATA{MyData/MyInput.mhd,MyInput.img} # File pair
4365 DATA{MyData/MyFrames00.png,REGEX:MyFrames[0-9]+\\.png} # Series
4366 will pass MyInput.mha and MyFrames00.png on the command line but ensure
4368 that the associated files are present next to them.
4369 Referencing Directories
4371 The DATA{} syntax may reference a directory using a trailing slash and
4372 a list of associated files. The form DATA{<name>/,<opt1>,<opt2>,...}
4373 adds rules to fetch any files in the directory that match one of the
4374 associated file options. For example, the argument DATA{My‐
4375 DataDir/,REGEX:.*} will pass the full path to a MyDataDir directory on
4376 the command line and ensure that the directory contains files corre‐
4377 sponding to every file or content link in the MyDataDir source direc‐
4378 tory.
4379 New in version 3.3: In order to match associated files in subdirecto‐
4381 ries, specify a RECURSE: option, e.g. DATA{MyDataDir/,RE‐
4382 CURSE:,REGEX:.*}.
4383 Hash Algorithms
4386 The following hash algorithms are supported:
4387 %(algo) <ext> Description
4389 ------- ----- -----------
4390 MD5 .md5 Message-Digest Algorithm 5, RFC 1321
4391 SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174
4392 SHA224 .sha224 US Secure Hash Algorithms, RFC 4634
4393 SHA256 .sha256 US Secure Hash Algorithms, RFC 4634
4394 SHA384 .sha384 US Secure Hash Algorithms, RFC 4634
4395 SHA512 .sha512 US Secure Hash Algorithms, RFC 4634
4396 SHA3_224 .sha3-224 Keccak SHA-3
4397 SHA3_256 .sha3-256 Keccak SHA-3
4398 SHA3_384 .sha3-384 Keccak SHA-3
4399 SHA3_512 .sha3-512 Keccak SHA-3
4400 New in version 3.8: Added the SHA3_* hash algorithms.
4402 Note that the hashes are used only for unique data identification and
4405 download verification.
4406 Custom Fetch Scripts
4408 New in version 3.2.
4409 When a data file must be fetched from one of the URL templates speci‐
4412 fied in the ExternalData_URL_TEMPLATES variable, it is normally down‐
4413 loaded using the file(DOWNLOAD) command. One may specify usage of a
4414 custom fetch script by using a URL template of the form ExternalData‐
4415 CustomScript://<key>/<loc>. The <key> must be a C identifier, and the
4416 <loc> must contain the %(algo) and %(hash) placeholders. A variable
4417 corresponding to the key, ExternalData_CUSTOM_SCRIPT_<key>, must be set
4418 to the full path to a .cmake script file. The script will be included
4419 to perform the actual fetch, and provided with the following variables:
4420 ExternalData_CUSTOM_LOCATION
4422 When a custom fetch script is loaded, this variable is set to
4423 the location part of the URL, which will contain the substituted
4424 hash algorithm name and content hash value.
4425 ExternalData_CUSTOM_FILE
4427 When a custom fetch script is loaded, this variable is set to
4428 the full path to a file in which the script must store the
4429 fetched content. The name of the file is unspecified and should
4430 not be interpreted in any way.
4431 The custom fetch script is expected to store fetched content in the
4433 file or set a variable:
4434 ExternalData_CUSTOM_ERROR
4436 When a custom fetch script fails to fetch the requested content,
4437 it must set this variable to a short one-line message describing
4438 the reason for failure.
4439 ExternalProject
4441 Commands
4442 External Project Definition
4443 ExternalProject_Add
4444 The ExternalProject_Add() function creates a custom target to
4445 drive download, update/patch, configure, build, install and test
4446 steps of an external project:
4447 ExternalProject_Add(<name> [<option>...])
4449 The individual steps within the process can be driven indepen‐
4451 dently if required (e.g. for CDash submission) and extra custom
4452 steps can be defined, along with the ability to control the step
4453 dependencies. The directory structure used for the management of
4454 the external project can also be customized. The function sup‐
4455 ports a large number of options which can be used to tailor the
4456 external project behavior.
4457 Directory Options:
4459 Most of the time, the default directory layout is suffi‐
4460 cient. It is largely an implementation detail that the
4461 main project usually doesn't need to change. In some cir‐
4462 cumstances, however, control over the directory layout
4463 can be useful or necessary. The directory options are po‐
4464 tentially more useful from the point of view that the
4465 main build can use the ExternalProject_Get_Property()
4466 command to retrieve their values, thereby allowing the
4467 main project to refer to build artifacts of the external
4468 project.
4469 PREFIX <dir>
4471 Root directory for the external project. Unless
4472 otherwise noted below, all other directories asso‐
4473 ciated with the external project will be created
4474 under here.
4475 TMP_DIR <dir>
4477 Directory in which to store temporary files.
4478 STAMP_DIR <dir>
4480 Directory in which to store the timestamps of each
4481 step. Log files from individual steps are also
4482 created in here unless overridden by LOG_DIR (see
4483 Logging Options below).
4484 LOG_DIR <dir>
4486 New in version 3.14.
4487 Directory in which to store the logs of each step.
4490 DOWNLOAD_DIR <dir>
4492 Directory in which to store downloaded files be‐
4493 fore unpacking them. This directory is only used
4494 by the URL download method, all other download
4495 methods use SOURCE_DIR directly instead.
4496 SOURCE_DIR <dir>
4498 Source directory into which downloaded contents
4499 will be unpacked, or for non-URL download methods,
4500 the directory in which the repository should be
4501 checked out, cloned, etc. If no download method is
4502 specified, this must point to an existing direc‐
4503 tory where the external project has already been
4504 unpacked or cloned/checked out.
4505 NOTE:
4507 If a download method is specified, any existing
4508 contents of the source directory may be
4509 deleted. Only the URL download method checks
4510 whether this directory is either missing or
4511 empty before initiating the download, stopping
4512 with an error if it is not empty. All other
4513 download methods silently discard any previous
4514 contents of the source directory.
4515 BINARY_DIR <dir>
4517 Specify the build directory location. This option
4518 is ignored if BUILD_IN_SOURCE is enabled.
4519 INSTALL_DIR <dir>
4521 Installation prefix to be placed in the <IN‐
4522 STALL_DIR> placeholder. This does not actually
4523 configure the external project to install to the
4524 given prefix. That must be done by passing appro‐
4525 priate arguments to the external project configu‐
4526 ration step, e.g. using <INSTALL_DIR>.
4527 If any of the above ..._DIR options are not specified,
4529 their defaults are computed as follows. If the PREFIX op‐
4530 tion is given or the EP_PREFIX directory property is set,
4531 then an external project is built and installed under the
4532 specified prefix:
4533 TMP_DIR = <prefix>/tmp
4535 STAMP_DIR = <prefix>/src/<name>-stamp
4536 DOWNLOAD_DIR = <prefix>/src
4537 SOURCE_DIR = <prefix>/src/<name>
4538 BINARY_DIR = <prefix>/src/<name>-build
4539 INSTALL_DIR = <prefix>
4540 LOG_DIR = <STAMP_DIR>
4541 Otherwise, if the EP_BASE directory property is set then
4543 components of an external project are stored under the
4544 specified base:
4545 TMP_DIR = <base>/tmp/<name>
4547 STAMP_DIR = <base>/Stamp/<name>
4548 DOWNLOAD_DIR = <base>/Download/<name>
4549 SOURCE_DIR = <base>/Source/<name>
4550 BINARY_DIR = <base>/Build/<name>
4551 INSTALL_DIR = <base>/Install/<name>
4552 LOG_DIR = <STAMP_DIR>
4553 If no PREFIX, EP_PREFIX, or EP_BASE is specified, then
4555 the default is to set PREFIX to <name>-prefix. Relative
4556 paths are interpreted with respect to CMAKE_CURRENT_BI‐
4557 NARY_DIR at the point where ExternalProject_Add() is
4558 called.
4559 Download Step Options:
4561 A download method can be omitted if the SOURCE_DIR option
4562 is used to point to an existing non-empty directory. Oth‐
4563 erwise, one of the download methods below must be speci‐
4564 fied (multiple download methods should not be given) or a
4565 custom DOWNLOAD_COMMAND provided.
4566 DOWNLOAD_COMMAND <cmd>...
4568 Overrides the command used for the download step
4569 (generator expressions are supported). If this op‐
4570 tion is specified, all other download options will
4571 be ignored. Providing an empty string for <cmd>
4572 effectively disables the download step.
4573 URL Download
4575 URL <url1> [<url2>...]
4577 List of paths and/or URL(s) of the external
4578 project's source. When more than one URL is
4579 given, they are tried in turn until one
4580 succeeds. A URL may be an ordinary path in
4581 the local file system (in which case it
4582 must be the only URL provided) or any down‐
4583 loadable URL supported by the file(DOWN‐
4584 LOAD) command. A local filesystem path may
4585 refer to either an existing directory or to
4586 an archive file, whereas a URL is expected
4587 to point to a file which can be treated as
4588 an archive. When an archive is used, it
4589 will be unpacked automatically unless the
4590 DOWNLOAD_NO_EXTRACT option is set to pre‐
4591 vent it. The archive type is determined by
4592 inspecting the actual content rather than
4593 using logic based on the file extension.
4594 Changed in version 3.7: Multiple URLs are
4596 allowed.
4597 URL_HASH <algo>=<hashValue>
4600 Hash of the archive file to be downloaded.
4601 The argument should be of the form
4602 <algo>=<hashValue> where algo can be any of
4603 the hashing algorithms supported by the
4604 file() command. Specifying this option is
4605 strongly recommended for URL downloads, as
4606 it ensures the integrity of the downloaded
4607 content. It is also used as a check for a
4608 previously downloaded file, allowing con‐
4609 nection to the remote location to be
4610 avoided altogether if the local directory
4611 already has a file from an earlier download
4612 that matches the specified hash.
4613 URL_MD5 <md5>
4615 Equivalent to URL_HASH MD5=<md5>.
4616 DOWNLOAD_NAME <fname>
4618 File name to use for the downloaded file.
4619 If not given, the end of the URL is used to
4620 determine the file name. This option is
4621 rarely needed, the default name is gener‐
4622 ally suitable and is not normally used out‐
4623 side of code internal to the ExternalPro‐
4624 ject module.
4625 DOWNLOAD_NO_EXTRACT <bool>
4627 New in version 3.6.
4628 Allows the extraction part of the download
4631 step to be disabled by passing a boolean
4632 true value for this option. If this option
4633 is not given, the downloaded contents will
4634 be unpacked automatically if required. If
4635 extraction has been disabled, the full path
4636 to the downloaded file is available as
4637 <DOWNLOADED_FILE> in subsequent steps or as
4638 the property DOWNLOADED_FILE with the
4639 ExternalProject_Get_Property() command.
4640 DOWNLOAD_NO_PROGRESS <bool>
4642 Can be used to disable logging the download
4643 progress. If this option is not given,
4644 download progress messages will be logged.
4645 TIMEOUT <seconds>
4647 Maximum time allowed for file download op‐
4648 erations.
4649 INACTIVITY_TIMEOUT <seconds>
4651 New in version 3.19.
4652 Terminate the operation after a period of
4655 inactivity.
4656 HTTP_USERNAME <username>
4658 New in version 3.7.
4659 Username for the download operation if au‐
4662 thentication is required.
4663 HTTP_PASSWORD <password>
4665 New in version 3.7.
4666 Password for the download operation if au‐
4669 thentication is required.
4670 HTTP_HEADER <header1> [<header2>...]
4672 New in version 3.7.
4673 Provides an arbitrary list of HTTP headers
4676 for the download operation. This can be
4677 useful for accessing content in systems
4678 like AWS, etc.
4679 TLS_VERIFY <bool>
4681 Specifies whether certificate verification
4682 should be performed for https URLs. If this
4683 option is not provided, the default behav‐
4684 ior is determined by the CMAKE_TLS_VERIFY
4685 variable (see file(DOWNLOAD)). If that is
4686 also not set, certificate verification will
4687 not be performed. In situations where
4688 URL_HASH cannot be provided, this option
4689 can be an alternative verification measure.
4690 Changed in version 3.6: This option also
4692 applies to git clone invocations.
4693 TLS_CAINFO <file>
4696 Specify a custom certificate authority file
4697 to use if TLS_VERIFY is enabled. If this
4698 option is not specified, the value of the
4699 CMAKE_TLS_CAINFO variable will be used in‐
4700 stead (see file(DOWNLOAD))
4701 NETRC <level>
4703 New in version 3.11.
4704 Specify whether the .netrc file is to be
4707 used for operation. If this option is not
4708 specified, the value of the CMAKE_NETRC
4709 variable will be used instead (see
4710 file(DOWNLOAD)) Valid levels are:
4711 IGNORED
4713 The .netrc file is ignored. This is
4714 the default.
4715 OPTIONAL
4717 The .netrc file is optional, and in‐
4718 formation in the URL is preferred.
4719 The file will be scanned to find
4720 which ever information is not speci‐
4721 fied in the URL.
4722 REQUIRED
4724 The .netrc file is required, and in‐
4725 formation in the URL is ignored.
4726 NETRC_FILE <file>
4728 New in version 3.11.
4729 Specify an alternative .netrc file to the
4732 one in your home directory if the NETRC
4733 level is OPTIONAL or REQUIRED. If this op‐
4734 tion is not specified, the value of the
4735 CMAKE_NETRC_FILE variable will be used in‐
4736 stead (see file(DOWNLOAD))
4737 New in version 3.1: Added support for tbz2,
4739 .tar.xz, .txz, and .7z extensions.
4740 Git NOTE: A git version of 1.6.5 or later is required
4743 if this download method is used.
4744 GIT_REPOSITORY <url>
4746 URL of the git repository. Any URL under‐
4747 stood by the git command may be used.
4748 GIT_TAG <tag>
4750 Git branch name, tag or commit hash. Note
4751 that branch names and tags should generally
4752 be specified as remote names (i.e. ori‐
4753 gin/myBranch rather than simply myBranch).
4754 This ensures that if the remote end has its
4755 tag moved or branch rebased or history
4756 rewritten, the local clone will still be
4757 updated correctly. In general, however,
4758 specifying a commit hash should be pre‐
4759 ferred for a number of reasons:
4760 • If the local clone already has the commit
4762 corresponding to the hash, no git fetch
4763 needs to be performed to check for
4764 changes each time CMake is re-run. This
4765 can result in a significant speed up if
4766 many external projects are being used.
4767 • Using a specific git hash ensures that
4769 the main project's own history is fully
4770 traceable to a specific point in the ex‐
4771 ternal project's evolution. If a branch
4772 or tag name is used instead, then check‐
4773 ing out a specific commit of the main
4774 project doesn't necessarily pin the whole
4775 build to a specific point in the life of
4776 the external project. The lack of such
4777 deterministic behavior makes the main
4778 project lose traceability and repeatabil‐
4779 ity.
4780 If GIT_SHALLOW is enabled then GIT_TAG
4782 works only with branch names and tags. A
4783 commit hash is not allowed.
4784 GIT_REMOTE_NAME <name>
4786 The optional name of the remote. If this
4787 option is not specified, it defaults to
4788 origin.
4789 GIT_SUBMODULES <module>...
4791 Specific git submodules that should also be
4792 updated. If this option is not provided,
4793 all git submodules will be updated.
4794 Changed in version 3.16: When CMP0097 is
4796 set to NEW, if this value is set to an
4797 empty string then no submodules are ini‐
4798 tialized or updated.
4799 GIT_SUBMODULES_RECURSE <bool>
4802 New in version 3.17.
4803 Specify whether git submodules (if any)
4806 should update recursively by passing the
4807 --recursive flag to git submodule update.
4808 If not specified, the default is on.
4809 GIT_SHALLOW <bool>
4811 New in version 3.6.
4812 When this option is enabled, the git clone
4815 operation will be given the --depth 1 op‐
4816 tion. This performs a shallow clone, which
4817 avoids downloading the whole history and
4818 instead retrieves just the commit denoted
4819 by the GIT_TAG option.
4820 GIT_PROGRESS <bool>
4822 New in version 3.8.
4823 When enabled, this option instructs the git
4826 clone operation to report its progress by
4827 passing it the --progress option. Without
4828 this option, the clone step for large
4829 projects may appear to make the build
4830 stall, since nothing will be logged until
4831 the clone operation finishes. While this
4832 option can be used to provide progress to
4833 prevent the appearance of the build having
4834 stalled, it may also make the build overly
4835 noisy if lots of external projects are
4836 used.
4837 GIT_CONFIG <option1> [<option2>...]
4839 New in version 3.8.
4840 Specify a list of config options to pass to
4843 git clone. Each option listed will be
4844 transformed into its own --config <option>
4845 on the git clone command line, with each
4846 option required to be in the form
4847 key=value.
4848 GIT_REMOTE_UPDATE_STRATEGY <strategy>
4850 New in version 3.18.
4851 When GIT_TAG refers to a remote branch,
4854 this option can be used to specify how the
4855 update step behaves. The <strategy> must
4856 be one of the following:
4857 CHECKOUT
4859 Ignore the local branch and always
4860 checkout the branch specified by
4861 GIT_TAG.
4862 REBASE Try to rebase the current branch to
4864 the one specified by GIT_TAG. If
4865 there are local uncommitted changes,
4866 they will be stashed first and
4867 popped again after rebasing. If re‐
4868 basing or popping stashed changes
4869 fail, abort the rebase and halt with
4870 an error. When GIT_REMOTE_UP‐
4871 DATE_STRATEGY is not present, this
4872 is the default strategy unless the
4873 default has been overridden with
4874 CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY
4875 (see below).
4876 REBASE_CHECKOUT
4878 Same as REBASE except if the rebase
4879 fails, an annotated tag will be cre‐
4880 ated at the original HEAD position
4881 from before the rebase and then
4882 checkout GIT_TAG just like the
4883 CHECKOUT strategy. The message
4884 stored on the annotated tag will
4885 give information about what was at‐
4886 tempted and the tag name will in‐
4887 clude a timestamp so that each
4888 failed run will add a new tag. This
4889 strategy ensures no changes will be
4890 lost, but updates should always suc‐
4891 ceed if GIT_TAG refers to a valid
4892 ref unless there are uncommitted
4893 changes that cannot be popped suc‐
4894 cessfully.
4895 The variable CMAKE_EP_GIT_REMOTE_UP‐
4897 DATE_STRATEGY can be set to override the
4898 default strategy. This variable should not
4899 be set by a project, it is intended for the
4900 user to set. It is primarily intended for
4901 use in continuous integration scripts to
4902 ensure that when history is rewritten on a
4903 remote branch, the build doesn't end up
4904 with unintended changes or failed builds
4905 resulting from conflicts during rebase op‐
4906 erations.
4907 Subversion
4909 SVN_REPOSITORY <url>
4911 URL of the Subversion repository.
4912 SVN_REVISION -r<rev>
4914 Revision to checkout from the Subversion
4915 repository.
4916 SVN_USERNAME <username>
4918 Username for the Subversion checkout and
4919 update.
4920 SVN_PASSWORD <password>
4922 Password for the Subversion checkout and
4923 update.
4924 SVN_TRUST_CERT <bool>
4926 Specifies whether to trust the Subversion
4927 server site certificate. If enabled, the
4928 --trust-server-cert option is passed to the
4929 svn checkout and update commands.
4930 Mercurial
4932 HG_REPOSITORY <url>
4934 URL of the mercurial repository.
4935 HG_TAG <tag>
4937 Mercurial branch name, tag or commit id.
4938 CVS
4940 CVS_REPOSITORY <cvsroot>
4942 CVSROOT of the CVS repository.
4943 CVS_MODULE <mod>
4945 Module to checkout from the CVS repository.
4946 CVS_TAG <tag>
4948 Tag to checkout from the CVS repository.
4949 Update/Patch Step Options:
4951 Whenever CMake is re-run, by default the external
4952 project's sources will be updated if the download method
4953 supports updates (e.g. a git repository would be checked
4954 if the GIT_TAG does not refer to a specific commit).
4955 UPDATE_COMMAND <cmd>...
4957 Overrides the download method's update step with a
4958 custom command. The command may use generator ex‐
4959 pressions.
4960 UPDATE_DISCONNECTED <bool>
4962 New in version 3.2.
4963 When enabled, this option causes the update step
4966 to be skipped. It does not, however, prevent the
4967 download step. The update step can still be added
4968 as a step target (see
4969 ExternalProject_Add_StepTargets()) and called man‐
4970 ually. This is useful if you want to allow devel‐
4971 opers to build the project when disconnected from
4972 the network (the network may still be needed for
4973 the download step though).
4974 When this option is present, it is generally ad‐
4976 visable to make the value a cache variable under
4977 the developer's control rather than hard-coding
4978 it. If this option is not present, the default
4979 value is taken from the EP_UPDATE_DISCONNECTED di‐
4980 rectory property. If that is also not defined, up‐
4981 dates are performed as normal. The EP_UPDATE_DIS‐
4982 CONNECTED directory property is intended as a con‐
4983 venience for controlling the UPDATE_DISCONNECTED
4984 behavior for an entire section of a project's di‐
4985 rectory hierarchy and may be a more convenient
4986 method of giving developers control over whether
4987 or not to perform updates (assuming the project
4988 also provides a cache variable or some other con‐
4989 venient method for setting the directory prop‐
4990 erty).
4991 This may cause a step target to be created auto‐
4993 matically for the download step. See policy
4994 CMP0114.
4995 PATCH_COMMAND <cmd>...
4997 Specifies a custom command to patch the sources
4998 after an update. By default, no patch command is
4999 defined. Note that it can be quite difficult to
5000 define an appropriate patch command that performs
5001 robustly, especially for download methods such as
5002 git where changing the GIT_TAG will not discard
5003 changes from a previous patch, but the patch com‐
5004 mand will be called again after updating to the
5005 new tag.
5006 Configure Step Options:
5008 The configure step is run after the download and update
5009 steps. By default, the external project is assumed to be
5010 a CMake project, but this can be overridden if required.
5011 CONFIGURE_COMMAND <cmd>...
5013 The default configure command runs CMake with a
5014 few options based on the main project. The op‐
5015 tions added are typically only those needed to use
5016 the same generator as the main project, but the
5017 CMAKE_GENERATOR option can be given to override
5018 this. The project is responsible for adding any
5019 toolchain details, flags or other settings it
5020 wants to re-use from the main project or otherwise
5021 specify (see CMAKE_ARGS, CMAKE_CACHE_ARGS and
5022 CMAKE_CACHE_DEFAULT_ARGS below).
5023 For non-CMake external projects, the CONFIG‐
5025 URE_COMMAND option must be used to override the
5026 default configure command (generator expressions
5027 are supported). For projects that require no con‐
5028 figure step, specify this option with an empty
5029 string as the command to execute.
5030 CMAKE_COMMAND /.../cmake
5032 Specify an alternative cmake executable for the
5033 configure step (use an absolute path). This is
5034 generally not recommended, since it is usually de‐
5035 sirable to use the same CMake version throughout
5036 the whole build. This option is ignored if a cus‐
5037 tom configure command has been specified with CON‐
5038 FIGURE_COMMAND.
5039 CMAKE_GENERATOR <gen>
5041 Override the CMake generator used for the config‐
5042 ure step. Without this option, the same generator
5043 as the main build will be used. This option is ig‐
5044 nored if a custom configure command has been spec‐
5045 ified with the CONFIGURE_COMMAND option.
5046 CMAKE_GENERATOR_PLATFORM <platform>
5048 New in version 3.1.
5049 Pass a generator-specific platform name to the
5052 CMake command (see CMAKE_GENERATOR_PLATFORM). It
5053 is an error to provide this option without the
5054 CMAKE_GENERATOR option.
5055 CMAKE_GENERATOR_TOOLSET <toolset>
5057 Pass a generator-specific toolset name to the
5058 CMake command (see CMAKE_GENERATOR_TOOLSET). It is
5059 an error to provide this option without the
5060 CMAKE_GENERATOR option.
5061 CMAKE_GENERATOR_INSTANCE <instance>
5063 New in version 3.11.
5064 Pass a generator-specific instance selection to
5067 the CMake command (see CMAKE_GENERATOR_INSTANCE).
5068 It is an error to provide this option without the
5069 CMAKE_GENERATOR option.
5070 CMAKE_ARGS <arg>...
5072 The specified arguments are passed to the cmake
5073 command line. They can be any argument the cmake
5074 command understands, not just cache values defined
5075 by -D... arguments (see also CMake Options).
5076 New in version 3.3: Arguments may use generator
5078 expressions.
5079 CMAKE_CACHE_ARGS <arg>...
5082 This is an alternate way of specifying cache vari‐
5083 ables where command line length issues may become
5084 a problem. The arguments are expected to be in the
5085 form -Dvar:STRING=value, which are then trans‐
5086 formed into CMake set() commands with the FORCE
5087 option used. These set() commands are written to a
5088 pre-load script which is then applied using the
5089 cmake -C command line option.
5090 New in version 3.3: Arguments may use generator
5092 expressions.
5093 CMAKE_CACHE_DEFAULT_ARGS <arg>...
5096 New in version 3.2.
5097 This is the same as the CMAKE_CACHE_ARGS option
5100 except the set() commands do not include the FORCE
5101 keyword. This means the values act as initial de‐
5102 faults only and will not override any variables
5103 already set from a previous run. Use this option
5104 with care, as it can lead to different behavior
5105 depending on whether the build starts from a fresh
5106 build directory or re-uses previous build con‐
5107 tents.
5108 New in version 3.15: If the CMake generator is the
5110 Green Hills MULTI and not overridden then the
5111 original project's settings for the GHS toolset
5112 and target system customization cache variables
5113 are propagated into the external project.
5114 SOURCE_SUBDIR <dir>
5117 New in version 3.7.
5118 When no CONFIGURE_COMMAND option is specified, the
5121 configure step assumes the external project has a
5122 CMakeLists.txt file at the top of its source tree
5123 (i.e. in SOURCE_DIR). The SOURCE_SUBDIR option can
5124 be used to point to an alternative directory
5125 within the source tree to use as the top of the
5126 CMake source tree instead. This must be a relative
5127 path and it will be interpreted as being relative
5128 to SOURCE_DIR.
5129 New in version 3.14: When BUILD_IN_SOURCE option
5131 is enabled, the BUILD_COMMAND is used to point to
5132 an alternative directory within the source tree.
5133 CONFIGURE_HANDLED_BY_BUILD <bool>
5136 New in version 3.20.
5137 Enabling this option relaxes the dependencies of
5140 the configure step on other external projects to
5141 order-only. This means the configure step will be
5142 executed after its external project dependencies
5143 are built but it will not be marked dirty when one
5144 of its external project dependencies is rebuilt.
5145 This option can be enabled when the build step is
5146 smart enough to figure out if the configure step
5147 needs to be rerun. CMake and Meson are examples of
5148 build systems whose build step is smart enough to
5149 know if the configure step needs to be rerun.
5150 Build Step Options:
5152 If the configure step assumed the external project uses
5153 CMake as its build system, the build step will also. Oth‐
5154 erwise, the build step will assume a Makefile-based build
5155 and simply run make with no arguments as the default
5156 build step. This can be overridden with custom build com‐
5157 mands if required.
5158 If both the main project and the external project use
5160 make as their build tool, the build step of the external
5161 project is invoked as a recursive make using $(MAKE).
5162 This will communicate some build tool settings from the
5163 main project to the external project. If either the main
5164 project or external project is not using make, no build
5165 tool settings will be passed to the external project
5166 other than those established by the configure step (i.e.
5167 running ninja -v in the main project will not pass -v to
5168 the external project's build step, even if it also uses
5169 ninja as its build tool).
5170 BUILD_COMMAND <cmd>...
5172 Overrides the default build command (generator ex‐
5173 pressions are supported). If this option is not
5174 given, the default build command will be chosen to
5175 integrate with the main build in the most appro‐
5176 priate way (e.g. using recursive make for Makefile
5177 generators or cmake --build if the project uses a
5178 CMake build). This option can be specified with an
5179 empty string as the command to make the build step
5180 do nothing.
5181 BUILD_IN_SOURCE <bool>
5183 When this option is enabled, the build will be
5184 done directly within the external project's source
5185 tree. This should generally be avoided, the use of
5186 a separate build directory is usually preferred,
5187 but it can be useful when the external project as‐
5188 sumes an in-source build. The BINARY_DIR option
5189 should not be specified if building in-source.
5190 BUILD_ALWAYS <bool>
5192 Enabling this option forces the build step to al‐
5193 ways be run. This can be the easiest way to ro‐
5194 bustly ensure that the external project's own
5195 build dependencies are evaluated rather than rely‐
5196 ing on the default success timestamp-based method.
5197 This option is not normally needed unless develop‐
5198 ers are expected to modify something the external
5199 project's build depends on in a way that is not
5200 detectable via the step target dependencies (e.g.
5201 SOURCE_DIR is used without a download method and
5202 developers might modify the sources in
5203 SOURCE_DIR).
5204 BUILD_BYPRODUCTS <file>...
5206 New in version 3.2.
5207 Specifies files that will be generated by the
5210 build command but which might or might not have
5211 their modification time updated by subsequent
5212 builds. These ultimately get passed through as
5213 BYPRODUCTS to the build step's own underlying call
5214 to add_custom_command().
5215 Install Step Options:
5217 If the configure step assumed the external project uses
5218 CMake as its build system, the install step will also.
5219 Otherwise, the install step will assume a Makefile-based
5220 build and simply run make install as the default build
5221 step. This can be overridden with custom install commands
5222 if required.
5223 INSTALL_COMMAND <cmd>...
5225 The external project's own install step is invoked
5226 as part of the main project's build. It is done
5227 after the external project's build step and may be
5228 before or after the external project's test step
5229 (see the TEST_BEFORE_INSTALL option below). The
5230 external project's install rules are not part of
5231 the main project's install rules, so if anything
5232 from the external project should be installed as
5233 part of the main build, these need to be specified
5234 in the main build as additional install() com‐
5235 mands. The default install step builds the install
5236 target of the external project, but this can be
5237 overridden with a custom command using this option
5238 (generator expressions are supported). Passing an
5239 empty string as the <cmd> makes the install step
5240 do nothing.
5241 Test Step Options:
5243 The test step is only defined if at least one of the fol‐
5244 lowing TEST_... options are provided.
5245 TEST_COMMAND <cmd>...
5247 Overrides the default test command (generator ex‐
5248 pressions are supported). If this option is not
5249 given, the default behavior of the test step is to
5250 build the external project's own test target. This
5251 option can be specified with <cmd> as an empty
5252 string, which allows the test step to still be de‐
5253 fined, but it will do nothing. Do not specify any
5254 of the other TEST_... options if providing an
5255 empty string as the test command, but prefer to
5256 omit all TEST_... options altogether if the test
5257 step target is not needed.
5258 TEST_BEFORE_INSTALL <bool>
5260 When this option is enabled, the test step will be
5261 executed before the install step. The default be‐
5262 havior is for the test step to run after the in‐
5263 stall step.
5264 TEST_AFTER_INSTALL <bool>
5266 This option is mainly useful as a way to indicate
5267 that the test step is desired but all default be‐
5268 havior is sufficient. Specifying this option with
5269 a boolean true value ensures the test step is de‐
5270 fined and that it comes after the install step. If
5271 both TEST_BEFORE_INSTALL and TEST_AFTER_INSTALL
5272 are enabled, the latter is silently ignored.
5273 TEST_EXCLUDE_FROM_MAIN <bool>
5275 New in version 3.2.
5276 If enabled, the main build's default ALL target
5279 will not depend on the test step. This can be a
5280 useful way of ensuring the test step is defined
5281 but only gets invoked when manually requested.
5282 This may cause a step target to be created auto‐
5283 matically for either the install or build step.
5284 See policy CMP0114.
5285 Output Logging Options:
5287 Each of the following LOG_... options can be used to wrap
5288 the relevant step in a script to capture its output to
5289 files. The log files will be created in LOG_DIR if sup‐
5290 plied or otherwise the STAMP_DIR directory with step-spe‐
5291 cific file names.
5292 LOG_DOWNLOAD <bool>
5294 When enabled, the output of the download step is
5295 logged to files.
5296 LOG_UPDATE <bool>
5298 When enabled, the output of the update step is
5299 logged to files.
5300 LOG_PATCH <bool>
5302 New in version 3.14.
5303 When enabled, the output of the patch step is
5306 logged to files.
5307 LOG_CONFIGURE <bool>
5309 When enabled, the output of the configure step is
5310 logged to files.
5311 LOG_BUILD <bool>
5313 When enabled, the output of the build step is
5314 logged to files.
5315 LOG_INSTALL <bool>
5317 When enabled, the output of the install step is
5318 logged to files.
5319 LOG_TEST <bool>
5321 When enabled, the output of the test step is
5322 logged to files.
5323 LOG_MERGED_STDOUTERR <bool>
5325 New in version 3.14.
5326 When enabled, stdout and stderr will be merged for
5329 any step whose output is being logged to files.
5330 LOG_OUTPUT_ON_FAILURE <bool>
5332 New in version 3.14.
5333 This option only has an effect if at least one of
5336 the other LOG_<step> options is enabled. If an
5337 error occurs for a step which has logging to file
5338 enabled, that step's output will be printed to the
5339 console if LOG_OUTPUT_ON_FAILURE is set to true.
5340 For cases where a large amount of output is
5341 recorded, just the end of that output may be
5342 printed to the console.
5343 Terminal Access Options:
5345 New in version 3.4.
5346 Steps can be given direct access to the terminal in some
5349 cases. Giving a step access to the terminal may allow it
5350 to receive terminal input if required, such as for au‐
5351 thentication details not provided by other options. With
5352 the Ninja generator, these options place the steps in the
5353 console job pool. Each step can be given access to the
5354 terminal individually via the following options:
5355 USES_TERMINAL_DOWNLOAD <bool>
5357 Give the download step access to the terminal.
5358 USES_TERMINAL_UPDATE <bool>
5360 Give the update step access to the terminal.
5361 USES_TERMINAL_CONFIGURE <bool>
5363 Give the configure step access to the terminal.
5364 USES_TERMINAL_BUILD <bool>
5366 Give the build step access to the terminal.
5367 USES_TERMINAL_INSTALL <bool>
5369 Give the install step access to the terminal.
5370 USES_TERMINAL_TEST <bool>
5372 Give the test step access to the terminal.
5373 Target Options:
5375 DEPENDS <targets>...
5377 Specify other targets on which the external
5378 project depends. The other targets will be brought
5379 up to date before any of the external project's
5380 steps are executed. Because the external project
5381 uses additional custom targets internally for each
5382 step, the DEPENDS option is the most convenient
5383 way to ensure all of those steps depend on the
5384 other targets. Simply doing add_dependen‐
5385 cies(<name> <targets>) will not make any of the
5386 steps dependent on <targets>.
5387 EXCLUDE_FROM_ALL <bool>
5389 When enabled, this option excludes the external
5390 project from the default ALL target of the main
5391 build.
5392 STEP_TARGETS <step-target>...
5394 Generate custom targets for the specified steps.
5395 This is required if the steps need to be triggered
5396 manually or if they need to be used as dependen‐
5397 cies of other targets. If this option is not spec‐
5398 ified, the default value is taken from the
5399 EP_STEP_TARGETS directory property. See
5400 ExternalProject_Add_StepTargets() below for fur‐
5401 ther discussion of the effects of this option.
5402 INDEPENDENT_STEP_TARGETS <step-target>...
5404 Deprecated since version 3.19: This is allowed
5405 only if policy CMP0114 is not set to NEW.
5406 Generates custom targets for the specified steps
5409 and prevent these targets from having the usual
5410 dependencies applied to them. If this option is
5411 not specified, the default value is taken from the
5412 EP_INDEPENDENT_STEP_TARGETS directory property.
5413 This option is mostly useful for allowing individ‐
5414 ual steps to be driven independently, such as for
5415 a CDash setup where each step should be initiated
5416 and reported individually rather than as one whole
5417 build. See ExternalProject_Add_StepTargets() below
5418 for further discussion of the effects of this op‐
5419 tion.
5420 Miscellaneous Options:
5422 LIST_SEPARATOR <sep>
5424 For any of the various ..._COMMAND options, re‐
5425 place ; with <sep> in the specified command lines.
5426 This can be useful where list variables may be
5427 given in commands where they should end up as
5428 space-separated arguments (<sep> would be a single
5429 space character string in this case).
5430 COMMAND <cmd>...
5432 Any of the other ..._COMMAND options can have ad‐
5433 ditional commands appended to them by following
5434 them with as many COMMAND ... options as needed
5435 (generator expressions are supported). For exam‐
5436 ple:
5437 ExternalProject_Add(example
5439 ... # Download options, etc.
5440 BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
5441 COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
5442 COMMAND ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
5443 )
5444 It should also be noted that each build step is created via a
5446 call to ExternalProject_Add_Step(). See that command's documen‐
5447 tation for the automatic substitutions that are supported for
5448 some options.
5449 Obtaining Project Properties
5451 ExternalProject_Get_Property
5452 The ExternalProject_Get_Property() function retrieves external
5453 project target properties:
5454 ExternalProject_Get_Property(<name> <prop1> [<prop2>...])
5456 The function stores property values in variables of the same
5458 name. Property names correspond to the keyword argument names of
5459 ExternalProject_Add(). For example, the source directory might
5460 be retrieved like so:
5461 ExternalProject_Get_property(myExtProj SOURCE_DIR)
5463 message("Source dir of myExtProj = ${SOURCE_DIR}")
5464 Explicit Step Management
5466 The ExternalProject_Add() function on its own is often sufficient for
5467 incorporating an external project into the main build. Certain scenar‐
5468 ios require additional work to implement desired behavior, such as
5469 adding in a custom step or making steps available as manually trigger‐
5470 able targets. The ExternalProject_Add_Step(), ExternalProject_Add_Step‐
5471 Targets() and ExternalProject_Add_StepDependencies functions provide
5472 the lower level control needed to implement such step-level capabili‐
5473 ties.
5474 ExternalProject_Add_Step
5476 The ExternalProject_Add_Step() function specifies an additional
5477 custom step for an external project defined by an earlier call
5478 to ExternalProject_Add():
5479 ExternalProject_Add_Step(<name> <step> [<option>...])
5481 <name> is the same as the name passed to the original call to
5483 ExternalProject_Add(). The specified <step> must not be one of
5484 the pre-defined steps (mkdir, download, update, patch, config‐
5485 ure, build, install or test). The supported options are:
5486 COMMAND <cmd>...
5488 The command line to be executed by this custom step (gen‐
5489 erator expressions are supported). This option can be re‐
5490 peated multiple times to specify multiple commands to be
5491 executed in order.
5492 COMMENT <text>...
5494 Text to be printed when the custom step executes.
5495 DEPENDEES <step>...
5497 Other steps (custom or pre-defined) on which this step
5498 depends.
5499 DEPENDERS <step>...
5501 Other steps (custom or pre-defined) that depend on this
5502 new custom step.
5503 DEPENDS <file>...
5505 Files on which this custom step depends.
5506 INDEPENDENT <bool>
5508 New in version 3.19.
5509 Specifies whether this step is independent of the exter‐
5512 nal dependencies specified by the ExternalProject_Add()'s
5513 DEPENDS option. The default is FALSE. Steps marked as
5514 independent may depend only on other steps marked inde‐
5515 pendent. See policy CMP0114.
5516 Note that this use of the term "independent" refers only
5518 to independence from external targets specified by the
5519 DEPENDS option and is orthogonal to a step's dependencies
5520 on other steps.
5521 If a step target is created for an independent step by
5523 the ExternalProject_Add() STEP_TARGETS option or by the
5524 ExternalProject_Add_StepTargets() function, it will not
5525 depend on the external targets, but may depend on targets
5526 for other steps.
5527 BYPRODUCTS <file>...
5529 New in version 3.2.
5530 Files that will be generated by this custom step but
5533 which might or might not have their modification time up‐
5534 dated by subsequent builds. This list of files will ulti‐
5535 mately be passed through as the BYPRODUCTS option to the
5536 add_custom_command() used to implement the custom step
5537 internally.
5538 ALWAYS <bool>
5540 When enabled, this option specifies that the custom step
5541 should always be run (i.e. that it is always considered
5542 out of date).
5543 EXCLUDE_FROM_MAIN <bool>
5545 When enabled, this option specifies that the external
5546 project's main target does not depend on the custom step.
5547 This may cause step targets to be created automatically
5548 for the steps on which this step depends. See policy
5549 CMP0114.
5550 WORKING_DIRECTORY <dir>
5552 Specifies the working directory to set before running the
5553 custom step's command. If this option is not specified,
5554 the directory will be the value of the CMAKE_CURRENT_BI‐
5555 NARY_DIR at the point where ExternalProject_Add_Step()
5556 was called.
5557 LOG <bool>
5559 If set, this causes the output from the custom step to be
5560 captured to files in the external project's LOG_DIR if
5561 supplied or STAMP_DIR.
5562 USES_TERMINAL <bool>
5564 If enabled, this gives the custom step direct access to
5565 the terminal if possible.
5566 The command line, comment, working directory and byproducts of
5568 every standard and custom step are processed to replace the to‐
5569 kens <SOURCE_DIR>, <SOURCE_SUBDIR>, <BINARY_DIR>, <INSTALL_DIR>
5570 <TMP_DIR>, <DOWNLOAD_DIR> and <DOWNLOADED_FILE> with their cor‐
5571 responding property values defined in the original call to
5572 ExternalProject_Add().
5573 New in version 3.3: Token replacement is extended to byproducts.
5575 New in version 3.11: The <DOWNLOAD_DIR> substitution token.
5578 ExternalProject_Add_StepTargets
5581 The ExternalProject_Add_StepTargets() function generates targets
5582 for the steps listed. The name of each created target will be of
5583 the form <name>-<step>:
5584 ExternalProject_Add_StepTargets(<name> <step1> [<step2>...])
5586 Creating a target for a step allows it to be used as a depen‐
5588 dency of another target or to be triggered manually. Having tar‐
5589 gets for specific steps also allows them to be driven indepen‐
5590 dently of each other by specifying targets on build command
5591 lines. For example, you may be submitting to a sub-project based
5592 dashboard where you want to drive the configure portion of the
5593 build, then submit to the dashboard, followed by the build por‐
5594 tion, followed by tests. If you invoke a custom target that de‐
5595 pends on a step halfway through the step dependency chain, then
5596 all the previous steps will also run to ensure everything is up
5597 to date.
5598 Internally, ExternalProject_Add() calls
5600 ExternalProject_Add_Step() to create each step. If any STEP_TAR‐
5601 GETS were specified, then ExternalProject_Add_StepTargets() will
5602 also be called after ExternalProject_Add_Step(). Even if a step
5603 is not mentioned in the STEP_TARGETS option, ExternalPro‐
5604 ject_Add_StepTargets() can still be called later to manually de‐
5605 fine a target for the step.
5606 The STEP_TARGETS option for ExternalProject_Add() is generally
5608 the easiest way to ensure targets are created for specific steps
5609 of interest. For custom steps, ExternalProject_Add_StepTar‐
5610 gets() must be called explicitly if a target should also be cre‐
5611 ated for that custom step. An alternative to these two options
5612 is to populate the EP_STEP_TARGETS directory property. It acts
5613 as a default for the step target options and can save having to
5614 repeatedly specify the same set of step targets when multiple
5615 external projects are being defined.
5616 New in version 3.19: If CMP0114 is set to NEW, step targets are
5618 fully responsible for holding the custom commands implementing
5619 their steps. The primary target created by ExternalProject_Add
5620 depends on the step targets, and the step targets depend on each
5621 other. The target-level dependencies match the file-level de‐
5622 pendencies used by the custom commands for each step. The tar‐
5623 gets for steps created with ExternalProject_Add_Step()'s INDE‐
5624 PENDENT option do not depend on the external targets specified
5625 by ExternalProject_Add()'s DEPENDS option. The predefined steps
5626 mkdir, download, update, and patch are independent.
5627 If CMP0114 is not NEW, the following deprecated behavior is
5630 available:
5631 • A deprecated NO_DEPENDS option may be specified immediately
5633 after the <name> and before the first step. If the NO_DEPENDS
5634 option is specified, the step target will not depend on the
5635 dependencies of the external project (i.e. on any dependencies
5636 of the <name> custom target created by ExternalProject_Add()).
5637 This is usually safe for the download, update and patch steps,
5638 since they do not typically require that the dependencies are
5639 updated and built. Using NO_DEPENDS for any of the other
5640 pre-defined steps, however, may break parallel builds. Only
5641 use NO_DEPENDS where it is certain that the named steps gen‐
5642 uinely do not have dependencies. For custom steps, consider
5643 whether or not the custom commands require the dependencies to
5644 be configured, built and installed.
5645 • The INDEPENDENT_STEP_TARGETS option for ExternalProject_Add(),
5647 or the EP_INDEPENDENT_STEP_TARGETS directory property, tells
5648 the function to call ExternalProject_Add_StepTargets() inter‐
5649 nally using the NO_DEPENDS option for the specified steps.
5650 ExternalProject_Add_StepDependencies
5652 New in version 3.2.
5653 The ExternalProject_Add_StepDependencies() function can be used
5656 to add dependencies to a step. The dependencies added must be
5657 targets CMake already knows about (these can be ordinary exe‐
5658 cutable or library targets, custom targets or even step targets
5659 of another external project):
5660 ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])
5662 This function takes care to set both target and file level de‐
5664 pendencies and will ensure that parallel builds will not break.
5665 It should be used instead of add_dependencies() whenever adding
5666 a dependency for some of the step targets generated by the Ex‐
5667 ternalProject module.
5668 Examples
5670 The following example shows how to download and build a hypothetical
5671 project called FooBar from github:
5672 include(ExternalProject)
5674 ExternalProject_Add(foobar
5675 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
5676 GIT_TAG origin/release/1.2.3
5677 )
5678 For the sake of the example, also define a second hypothetical external
5680 project called SecretSauce, which is downloaded from a web server. Two
5681 URLs are given to take advantage of a faster internal network if avail‐
5682 able, with a fallback to a slower external server. The project is a
5683 typical Makefile project with no configure step, so some of the default
5684 commands are overridden. The build is only required to build the sauce
5685 target:
5686 find_program(MAKE_EXE NAMES gmake nmake make)
5688 ExternalProject_Add(secretsauce
5689 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
5690 https://www.somecompany.com/downloads/sauce-2.7.zip
5691 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
5692 CONFIGURE_COMMAND ""
5693 BUILD_COMMAND ${MAKE_EXE} sauce
5694 )
5695 Suppose the build step of secretsauce requires that foobar must already
5697 be built. This could be enforced like so:
5698 ExternalProject_Add_StepDependencies(secretsauce build foobar)
5700 Another alternative would be to create a custom target for foobar's
5702 build step and make secretsauce depend on that rather than the whole
5703 foobar project. This would mean foobar only needs to be built, it
5704 doesn't need to run its install or test steps before secretsauce can be
5705 built. The dependency can also be defined along with the secretsauce
5706 project:
5707 ExternalProject_Add_StepTargets(foobar build)
5709 ExternalProject_Add(secretsauce
5710 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
5711 https://www.somecompany.com/downloads/sauce-2.7.zip
5712 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
5713 CONFIGURE_COMMAND ""
5714 BUILD_COMMAND ${MAKE_EXE} sauce
5715 DEPENDS foobar-build
5716 )
5717 Instead of calling ExternalProject_Add_StepTargets(), the target could
5719 be defined along with the foobar project itself:
5720 ExternalProject_Add(foobar
5722 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
5723 GIT_TAG origin/release/1.2.3
5724 STEP_TARGETS build
5725 )
5726 If many external projects should have the same set of step targets,
5728 setting a directory property may be more convenient. The build step
5729 target could be created automatically by setting the EP_STEP_TARGETS
5730 directory property before creating the external projects with
5731 ExternalProject_Add():
5732 set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)
5734 Lastly, suppose that secretsauce provides a script called makedoc which
5736 can be used to generate its own documentation. Further suppose that the
5737 script expects the output directory to be provided as the only parame‐
5738 ter and that it should be run from the secretsauce source directory. A
5739 custom step and a custom target to trigger the script can be defined
5740 like so:
5741 ExternalProject_Add_Step(secretsauce docs
5743 COMMAND <SOURCE_DIR>/makedoc <BINARY_DIR>
5744 WORKING_DIRECTORY <SOURCE_DIR>
5745 COMMENT "Building secretsauce docs"
5746 ALWAYS TRUE
5747 EXCLUDE_FROM_MAIN TRUE
5748 )
5749 ExternalProject_Add_StepTargets(secretsauce docs)
5750 The custom step could then be triggered from the main build like so:
5752 cmake --build . --target secretsauce-docs
5754 FeatureSummary
5756 Functions for generating a summary of enabled/disabled features.
5757 These functions can be used to generate a summary of enabled and dis‐
5759 abled packages and/or feature for a build tree such as:
5760 -- The following OPTIONAL packages have been found:
5762 LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
5763 * Enables HTML-import in MyWordProcessor
5764 * Enables odt-export in MyWordProcessor
5765 PNG, A PNG image library., <http://www.libpng.org/pub/png/>
5766 * Enables saving screenshots
5767 -- The following OPTIONAL packages have not been found:
5768 Lua51, The Lua scripting language., <http://www.lua.org>
5769 * Enables macros in MyWordProcessor
5770 Foo, Foo provides cool stuff.
5771 Global Properties
5773 FeatureSummary_PKG_TYPES
5774 The global property FeatureSummary_PKG_TYPES defines the type of pack‐
5776 ages used by FeatureSummary.
5777 The order in this list is important, the first package type in the list
5779 is the least important, the last is the most important. the of a pack‐
5780 age can only be changed to higher types.
5781 The default package types are , RUNTIME, OPTIONAL, RECOMMENDED and RE‐
5783 QUIRED, and their importance is RUNTIME < OPTIONAL < RECOMMENDED < RE‐
5784 QUIRED.
5785 FeatureSummary_REQUIRED_PKG_TYPES
5787 The global property FeatureSummary_REQUIRED_PKG_TYPES defines which
5789 package types are required.
5790 If one or more package in this categories has not been found, CMake
5792 will abort when calling feature_summary() with the 'FATAL_ON_MISS‐
5793 ING_REQUIRED_PACKAGES' option enabled.
5794 The default value for this global property is REQUIRED.
5796 FeatureSummary_DEFAULT_PKG_TYPE
5798 The global property FeatureSummary_DEFAULT_PKG_TYPE defines which pack‐
5800 age type is the default one. When calling feature_summary(), if the
5801 user did not set the package type explicitly, the package will be as‐
5802 signed to this category.
5803 This value must be one of the types defined in the
5805 FeatureSummary_PKG_TYPES global property unless the package type is set
5806 for all the packages.
5807 The default value for this global property is OPTIONAL.
5809 FeatureSummary_<TYPE>_DESCRIPTION
5811 New in version 3.9.
5813 The global property FeatureSummary_<TYPE>_DESCRIPTION can be defined
5816 for each type to replace the type name with the specified string when‐
5817 ever the package type is used in an output string.
5818 If not set, the string "<TYPE> packages" is used.
5820 Functions
5822 feature_summary
5823 feature_summary( [FILENAME <file>]
5825 [APPEND]
5826 [VAR <variable_name>]
5827 [INCLUDE_QUIET_PACKAGES]
5828 [FATAL_ON_MISSING_REQUIRED_PACKAGES]
5829 [DESCRIPTION "<description>" | DEFAULT_DESCRIPTION]
5830 [QUIET_ON_EMPTY]
5831 WHAT (ALL
5832 | PACKAGES_FOUND | PACKAGES_NOT_FOUND
5833 | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
5834 | ENABLED_FEATURES | DISABLED_FEATURES)
5835 )
5836 The feature_summary() macro can be used to print information
5838 about enabled or disabled packages or features of a project. By
5839 default, only the names of the features/packages will be printed
5840 and their required version when one was specified. Use
5841 set_package_properties() to add more useful information, like
5842 e.g. a download URL for the respective package or their purpose
5843 in the project.
5844 The WHAT option is the only mandatory option. Here you specify
5846 what information will be printed:
5847 ALL print everything
5849 ENABLED_FEATURES
5851 the list of all features which are enabled
5852 DISABLED_FEATURES
5854 the list of all features which are disabled
5855 PACKAGES_FOUND
5857 the list of all packages which have been found
5858 PACKAGES_NOT_FOUND
5860 the list of all packages which have not been found
5861 For each package type <TYPE> defined by the
5863 FeatureSummary_PKG_TYPES global property, the following informa‐
5864 tion can also be used:
5865 <TYPE>_PACKAGES_FOUND
5867 only those packages which have been found which have the
5868 type <TYPE>
5869 <TYPE>_PACKAGES_NOT_FOUND
5871 only those packages which have not been found which have
5872 the type <TYPE>
5873 Changed in version 3.1: With the exception of the ALL value,
5875 these values can be combined in order to customize the output.
5876 For example:
5877 feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
5879 If a FILENAME is given, the information is printed into this
5882 file. If APPEND is used, it is appended to this file, otherwise
5883 the file is overwritten if it already existed. If the VAR op‐
5884 tion is used, the information is "printed" into the specified
5885 variable. If FILENAME is not used, the information is printed
5886 to the terminal. Using the DESCRIPTION option a description or
5887 headline can be set which will be printed above the actual con‐
5888 tent. If only one type of package was requested, no title is
5889 printed, unless it is explicitly set using either DESCRIPTION to
5890 use a custom string, or DEFAULT_DESCRIPTION to use a default ti‐
5891 tle for the requested type. If INCLUDE_QUIET_PACKAGES is given,
5892 packages which have been searched with find_package(... QUIET)
5893 will also be listed. By default they are skipped. If FA‐
5894 TAL_ON_MISSING_REQUIRED_PACKAGES is given, CMake will abort if a
5895 package which is marked as one of the package types listed in
5896 the FeatureSummary_REQUIRED_PKG_TYPES global property has not
5897 been found. The default value for the
5898 FeatureSummary_REQUIRED_PKG_TYPES global property is REQUIRED.
5899 New in version 3.9: The DEFAULT_DESCRIPTION option.
5901 The FeatureSummary_DEFAULT_PKG_TYPE global property can be modi‐
5904 fied to change the default package type assigned when not ex‐
5905 plicitly assigned by the user.
5906 New in version 3.8: If the QUIET_ON_EMPTY option is used, if
5908 only one type of package was requested, and no packages belong‐
5909 ing to that category were found, then no output (including the
5910 DESCRIPTION) is printed or added to the VAR variable.
5911 Example 1, append everything to a file:
5914 include(FeatureSummary)
5916 feature_summary(WHAT ALL
5917 FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
5918 Example 2, print the enabled features into the variable enabled‐
5920 FeaturesText, including QUIET packages:
5921 include(FeatureSummary)
5923 feature_summary(WHAT ENABLED_FEATURES
5924 INCLUDE_QUIET_PACKAGES
5925 DESCRIPTION "Enabled Features:"
5926 VAR enabledFeaturesText)
5927 message(STATUS "${enabledFeaturesText}")
5928 Example 3, change default package types and print only the cate‐
5930 gories that are not empty:
5931 include(FeatureSummary)
5933 set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
5934 find_package(FOO)
5935 set_package_properties(FOO PROPERTIES TYPE BUILD)
5936 feature_summary(WHAT BUILD_PACKAGES_FOUND
5937 Description "Build tools found:"
5938 QUIET_ON_EMPTY)
5939 feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
5940 Description "Build tools not found:"
5941 QUIET_ON_EMPTY)
5942 set_package_properties
5944 set_package_properties(<name> PROPERTIES
5946 [ URL <url> ]
5947 [ DESCRIPTION <description> ]
5948 [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
5949 [ PURPOSE <purpose> ]
5950 )
5951 Use this macro to set up information about the named package,
5953 which can then be displayed via FEATURE_SUMMARY(). This can be
5954 done either directly in the Find-module or in the project which
5955 uses the module after the find_package() call. The features for
5956 which information can be set are added automatically by the
5957 find_package() command.
5958 URL <url>
5960 This should be the homepage of the package, or something
5961 similar. Ideally this is set already directly in the
5962 Find-module.
5963 DESCRIPTION <description>
5965 A short description what that package is, at most one
5966 sentence. Ideally this is set already directly in the
5967 Find-module.
5968 TYPE <type>
5970 What type of dependency has the using project on that
5971 package. Default is OPTIONAL. In this case it is a
5972 package which can be used by the project when available
5973 at buildtime, but it also work without. RECOMMENDED is
5974 similar to OPTIONAL, i.e. the project will build if the
5975 package is not present, but the functionality of the re‐
5976 sulting binaries will be severely limited. If a REQUIRED
5977 package is not available at buildtime, the project may
5978 not even build. This can be combined with the FA‐
5979 TAL_ON_MISSING_REQUIRED_PACKAGES argument for fea‐
5980 ture_summary(). Last, a RUNTIME package is a package
5981 which is actually not used at all during the build, but
5982 which is required for actually running the resulting bi‐
5983 naries. So if such a package is missing, the project can
5984 still be built, but it may not work later on. If
5985 set_package_properties() is called multiple times for the
5986 same package with different TYPEs, the TYPE is only
5987 changed to higher TYPEs (RUNTIME < OPTIONAL < RECOMMENDED
5988 < REQUIRED), lower TYPEs are ignored. The TYPE property
5989 is project-specific, so it cannot be set by the Find-mod‐
5990 ule, but must be set in the project. Type accepted can
5991 be changed by setting the FeatureSummary_PKG_TYPES global
5992 property.
5993 PURPOSE <purpose>
5995 This describes which features this package enables in the
5996 project, i.e. it tells the user what functionality he
5997 gets in the resulting binaries. If set_package_proper‐
5998 ties() is called multiple times for a package, all PUR‐
5999 POSE properties are appended to a list of purposes of the
6000 package in the project. As the TYPE property, also the
6001 PURPOSE property is project-specific, so it cannot be set
6002 by the Find-module, but must be set in the project.
6003 Example for setting the info for a package:
6005 find_package(LibXml2)
6007 set_package_properties(LibXml2 PROPERTIES
6008 DESCRIPTION "A XML processing library."
6009 URL "http://xmlsoft.org/")
6010 # or
6011 set_package_properties(LibXml2 PROPERTIES
6012 TYPE RECOMMENDED
6013 PURPOSE "Enables HTML-import in MyWordProcessor")
6014 # or
6015 set_package_properties(LibXml2 PROPERTIES
6016 TYPE OPTIONAL
6017 PURPOSE "Enables odt-export in MyWordProcessor")
6018 find_package(DBUS)
6020 set_package_properties(DBUS PROPERTIES
6021 TYPE RUNTIME
6022 PURPOSE "Necessary to disable the screensaver during a presentation")
6023 add_feature_info
6025 add_feature_info(<name> <enabled> <description>)
6027 Use this macro to add information about a feature with the given
6029 <name>. <enabled> contains whether this feature is enabled or
6030 not. It can be a variable or a list of conditions. <descrip‐
6031 tion> is a text describing the feature. The information can be
6032 displayed using feature_summary() for ENABLED_FEATURES and DIS‐
6033 ABLED_FEATURES respectively.
6034 Changed in version 3.8: <enabled> can be a list of conditions.
6036 Example for setting the info for a feature:
6039 option(WITH_FOO "Help for foo" ON)
6041 add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
6042 Legacy Macros
6044 The following macros are provided for compatibility with previous CMake
6045 versions:
6046 set_package_info
6048 set_package_info(<name> <description> [ <url> [<purpose>] ])
6050 Use this macro to set up information about the named package,
6052 which can then be displayed via feature_summary(). This can be
6053 done either directly in the Find-module or in the project which
6054 uses the module after the find_package() call. The features for
6055 which information can be set are added automatically by the
6056 find_package() command.
6057 set_feature_info
6059 set_feature_info(<name> <description> [<url>])
6061 Does the same as:
6063 set_package_info(<name> <description> <url>)
6065 print_enabled_features
6067 print_enabled_features()
6069 Does the same as
6071 feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
6073 print_disabled_features
6075 print_disabled_features()
6077 Does the same as
6079 feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
6081 FetchContent
6083 New in version 3.11.
6084 Overview
6087 This module enables populating content at configure time via any method
6088 supported by the ExternalProject module. Whereas ExternalProject_Add()
6089 downloads at build time, the FetchContent module makes content avail‐
6090 able immediately, allowing the configure step to use the content in
6091 commands like add_subdirectory(), include() or file() operations.
6092 Content population details should be defined separately from the com‐
6094 mand that performs the actual population. This separation ensures that
6095 all the dependency details are defined before anything might try to use
6096 them to populate content. This is particularly important in more com‐
6097 plex project hierarchies where dependencies may be shared between mul‐
6098 tiple projects.
6099 The following shows a typical example of declaring content details for
6101 some dependencies and then ensuring they are populated with a separate
6102 call:
6103 FetchContent_Declare(
6105 googletest
6106 GIT_REPOSITORY https://github.com/google/googletest.git
6107 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
6108 )
6109 FetchContent_Declare(
6110 myCompanyIcons
6111 URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
6112 URL_HASH MD5=5588a7b18261c20068beabfb4f530b87
6113 )
6114 FetchContent_MakeAvailable(googletest secret_sauce)
6116 The FetchContent_MakeAvailable() command ensures the named dependencies
6118 have been populated, either by an earlier call or by populating them
6119 itself. When performing the population, it will also add them to the
6120 main build, if possible, so that the main build can use the populated
6121 projects' targets, etc. See the command's documentation for how these
6122 steps are performed.
6123 When using a hierarchical project arrangement, projects at higher lev‐
6125 els in the hierarchy are able to override the declared details of con‐
6126 tent specified anywhere lower in the project hierarchy. The first de‐
6127 tails to be declared for a given dependency take precedence, regardless
6128 of where in the project hierarchy that occurs. Similarly, the first
6129 call that tries to populate a dependency "wins", with subsequent popu‐
6130 lations reusing the result of the first instead of repeating the popu‐
6131 lation again. See the Examples which demonstrate this scenario.
6132 In some cases, the main project may need to have more precise control
6134 over the population, or it may be required to explicitly define the
6135 population steps in a way that cannot be captured by the declared de‐
6136 tails alone. For such situations, the lower level
6137 FetchContent_GetProperties() and FetchContent_Populate() commands can
6138 be used. These lack the richer features provided by
6139 FetchContent_MakeAvailable() though, so their direct use should be con‐
6140 sidered a last resort. The typical pattern of such custom steps looks
6141 like this:
6142 # NOTE: Where possible, prefer to use FetchContent_MakeAvailable()
6144 # instead of custom logic like this
6145 # Check if population has already been performed
6147 FetchContent_GetProperties(depname)
6148 if(NOT depname_POPULATED)
6149 # Fetch the content using previously declared details
6150 FetchContent_Populate(depname)
6151 # Set custom variables, policies, etc.
6153 # ...
6154 # Bring the populated content into the build
6156 add_subdirectory(${depname_SOURCE_DIR} ${depname_BINARY_DIR})
6157 endif()
6158 The FetchContent module also supports defining and populating content
6160 in a single call, with no check for whether the content has been popu‐
6161 lated elsewhere already. This should not be done in projects, but may
6162 be appropriate for populating content in CMake's script mode. See
6163 FetchContent_Populate() for details.
6164 Commands
6166 FetchContent_Declare
6167 FetchContent_Declare(<name> <contentOptions>...)
6169 The FetchContent_Declare() function records the options that de‐
6171 scribe how to populate the specified content. If such details
6172 have already been recorded earlier in this project (regardless
6173 of where in the project hierarchy), this and all later calls for
6174 the same content <name> are ignored. This "first to record,
6175 wins" approach is what allows hierarchical projects to have par‐
6176 ent projects override content details of child projects.
6177 The content <name> can be any string without spaces, but good
6179 practice would be to use only letters, numbers and underscores.
6180 The name will be treated case-insensitively and it should be ob‐
6181 vious for the content it represents, often being the name of the
6182 child project or the value given to its top level project() com‐
6183 mand (if it is a CMake project). For well-known public
6184 projects, the name should generally be the official name of the
6185 project. Choosing an unusual name makes it unlikely that other
6186 projects needing that same content will use the same name, lead‐
6187 ing to the content being populated multiple times.
6188 The <contentOptions> can be any of the download, update or patch
6190 options that the ExternalProject_Add() command understands. The
6191 configure, build, install and test steps are explicitly disabled
6192 and therefore options related to them will be ignored. The
6193 SOURCE_SUBDIR option is an exception, see
6194 FetchContent_MakeAvailable() for details on how that affects be‐
6195 havior.
6196 In most cases, <contentOptions> will just be a couple of options
6198 defining the download method and method-specific details like a
6199 commit tag or archive hash. For example:
6200 FetchContent_Declare(
6202 googletest
6203 GIT_REPOSITORY https://github.com/google/googletest.git
6204 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
6205 )
6206 FetchContent_Declare(
6208 myCompanyIcons
6209 URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
6210 URL_HASH MD5=5588a7b18261c20068beabfb4f530b87
6211 )
6212 FetchContent_Declare(
6214 myCompanyCertificates
6215 SVN_REPOSITORY svn+ssh://svn.mycompany.com/srv/svn/trunk/certs
6216 SVN_REVISION -r12345
6217 )
6218 Where contents are being fetched from a remote location and you
6220 do not control that server, it is advisable to use a hash for
6221 GIT_TAG rather than a branch or tag name. A commit hash is more
6222 secure and helps to confirm that the downloaded contents are
6223 what you expected.
6224 Changed in version 3.14: Commands for the download, update or
6226 patch steps can access the terminal. This may be needed for
6227 things like password prompts or real-time display of command
6228 progress.
6229 New in version 3.22: The CMAKE_TLS_VERIFY, CMAKE_TLS_CAINFO,
6232 CMAKE_NETRC and CMAKE_NETRC_FILE variables now provide the de‐
6233 faults for their corresponding content options, just like they
6234 do for ExternalProject_Add(). Previously, these variables were
6235 ignored by the FetchContent module.
6236 FetchContent_MakeAvailable
6239 New in version 3.14.
6240 FetchContent_MakeAvailable(<name1> [<name2>...])
6243 This command ensures that each of the named dependencies are
6245 populated and potentially added to the build by the time it re‐
6246 turns. It iterates over the list, and for each dependency, the
6247 following logic is applied:
6248 • If the dependency has already been populated earlier in this
6250 run, set the <lowercaseName>_POPULATED, <lowercase‐
6251 Name>_SOURCE_DIR and <lowercaseName>_BINARY_DIR variables in
6252 the same way as a call to FetchContent_GetProperties(), then
6253 skip the remaining steps below and move on to the next depen‐
6254 dency in the list.
6255 • Call FetchContent_Populate() to populate the dependency using
6257 the details recorded by an earlier call to
6258 FetchContent_Declare(). Halt with a fatal error if no such
6259 details have been recorded.
6260 FETCHCONTENT_SOURCE_DIR_<uppercaseName> can be used to over‐
6261 ride the declared details and use content provided at the
6262 specified location instead.
6263 • If the top directory of the populated content contains a
6265 CMakeLists.txt file, call add_subdirectory() to add it to the
6266 main build. It is not an error for there to be no CMake‐
6267 Lists.txt file, which allows the command to be used for depen‐
6268 dencies that make downloaded content available at a known lo‐
6269 cation, but which do not need or support being added directly
6270 to the build.
6271 New in version 3.18: The SOURCE_SUBDIR option can be given in
6273 the declared details to look somewhere below the top directory
6274 instead (i.e. the same way that SOURCE_SUBDIR is used by the
6275 ExternalProject_Add() command). The path provided with
6276 SOURCE_SUBDIR must be relative and will be treated as relative
6277 to the top directory. It can also point to a directory that
6278 does not contain a CMakeLists.txt file or even to a directory
6279 that doesn't exist. This can be used to avoid adding a
6280 project that contains a CMakeLists.txt file in its top direc‐
6281 tory.
6282 Projects should aim to declare the details of all dependencies
6285 they might use before they call FetchContent_MakeAvailable() for
6286 any of them. This ensures that if any of the dependencies are
6287 also sub-dependencies of one or more of the others, the main
6288 project still controls the details that will be used (because it
6289 will declare them first before the dependencies get a chance
6290 to). In the following code samples, assume that the uses_other
6291 dependency also uses FetchContent to add the other dependency
6292 internally:
6293 # WRONG: Should declare all details first
6295 FetchContent_Declare(uses_other ...)
6296 FetchContent_MakeAvailable(uses_other)
6297 FetchContent_Declare(other ...) # Will be ignored, uses_other beat us to it
6299 FetchContent_MakeAvailable(other) # Would use details declared by uses_other
6300 # CORRECT: All details declared first, so they will take priority
6302 FetchContent_Declare(uses_other ...)
6303 FetchContent_Declare(other ...)
6304 FetchContent_MakeAvailable(uses_other other)
6305 FetchContent_Populate
6307 NOTE:
6308 Where possible, prefer to use FetchContent_MakeAvailable()
6309 instead of implementing population manually with this com‐
6310 mand.
6311 FetchContent_Populate(<name>)
6313 In most cases, the only argument given to FetchContent_Popu‐
6315 late() is the <name>. When used this way, the command assumes
6316 the content details have been recorded by an earlier call to
6317 FetchContent_Declare(). The details are stored in a global
6318 property, so they are unaffected by things like variable or di‐
6319 rectory scope. Therefore, it doesn't matter where in the
6320 project the details were previously declared, as long as they
6321 have been declared before the call to FetchContent_Populate().
6322 Those saved details are then used to construct a call to Exter‐
6323 nalProject_Add() in a private sub-build to perform the content
6324 population immediately. The implementation of ExternalPro‐
6325 ject_Add() ensures that if the content has already been popu‐
6326 lated in a previous CMake run, that content will be reused
6327 rather than repopulating them again. For the common case where
6328 population involves downloading content, the cost of the down‐
6329 load is only paid once.
6330 An internal global property records when a particular content
6332 population request has been processed. If FetchContent_Popu‐
6333 late() is called more than once for the same content name within
6334 a configure run, the second call will halt with an error.
6335 Projects can and should check whether content population has al‐
6336 ready been processed with the FetchContent_GetProperties() com‐
6337 mand before calling FetchContent_Populate().
6338 FetchContent_Populate() will set three variables in the scope of
6340 the caller:
6341 <lowercaseName>_POPULATED
6343 This will always be set to TRUE by the call.
6344 <lowercaseName>_SOURCE_DIR
6346 The location where the populated content can be found
6347 upon return.
6348 <lowercaseName>_BINARY_DIR
6350 A directory intended for use as a corresponding build di‐
6351 rectory.
6352 The main use case for the <lowercaseName>_SOURCE_DIR and <lower‐
6354 caseName>_BINARY_DIR variables is to call add_subdirectory() im‐
6355 mediately after population:
6356 FetchContent_Populate(FooBar)
6358 add_subdirectory(${foobar_SOURCE_DIR} ${foobar_BINARY_DIR})
6359 The values of the three variables can also be retrieved from
6361 anywhere in the project hierarchy using the
6362 FetchContent_GetProperties() command.
6363 The FetchContent_Populate() command also supports a syntax al‐
6365 lowing the content details to be specified directly rather than
6366 using any saved details. This is more low-level and use of this
6367 form is generally to be avoided in favor of using saved content
6368 details as outlined above. Nevertheless, in certain situations
6369 it can be useful to invoke the content population as an isolated
6370 operation (typically as part of implementing some other higher
6371 level feature or when using CMake in script mode):
6372 FetchContent_Populate(
6374 <name>
6375 [QUIET]
6376 [SUBBUILD_DIR <subBuildDir>]
6377 [SOURCE_DIR <srcDir>]
6378 [BINARY_DIR <binDir>]
6379 ...
6380 )
6381 This form has a number of key differences to that where only
6383 <name> is provided:
6384 • All required population details are assumed to have been pro‐
6386 vided directly in the call to FetchContent_Populate(). Any
6387 saved details for <name> are ignored.
6388 • No check is made for whether content for <name> has already
6390 been populated.
6391 • No global property is set to record that the population has
6393 occurred.
6394 • No global properties record the source or binary directories
6396 used for the populated content.
6397 • The FETCHCONTENT_FULLY_DISCONNECTED and FETCHCONTENT_UP‐
6399 DATES_DISCONNECTED cache variables are ignored.
6400 The <lowercaseName>_SOURCE_DIR and <lowercaseName>_BINARY_DIR
6402 variables are still returned to the caller, but since these lo‐
6403 cations are not stored as global properties when this form is
6404 used, they are only available to the calling scope and below
6405 rather than the entire project hierarchy. No <lowercase‐
6406 Name>_POPULATED variable is set in the caller's scope with this
6407 form.
6408 The supported options for FetchContent_Populate() are the same
6410 as those for FetchContent_Declare(). Those few options shown
6411 just above are either specific to FetchContent_Populate() or
6412 their behavior is slightly modified from how ExternalPro‐
6413 ject_Add() treats them:
6414 QUIET The QUIET option can be given to hide the output associ‐
6416 ated with populating the specified content. If the popu‐
6417 lation fails, the output will be shown regardless of
6418 whether this option was given or not so that the cause of
6419 the failure can be diagnosed. The global FETCHCON‐
6420 TENT_QUIET cache variable has no effect on FetchCon‐
6421 tent_Populate() calls where the content details are pro‐
6422 vided directly.
6423 SUBBUILD_DIR
6425 The SUBBUILD_DIR argument can be provided to change the
6426 location of the sub-build created to perform the popula‐
6427 tion. The default value is ${CMAKE_CURRENT_BI‐
6428 NARY_DIR}/<lowercaseName>-subbuild and it would be un‐
6429 usual to need to override this default. If a relative
6430 path is specified, it will be interpreted as relative to
6431 CMAKE_CURRENT_BINARY_DIR. This option should not be con‐
6432 fused with the SOURCE_SUBDIR option which only affects
6433 the FetchContent_MakeAvailable() command.
6434 SOURCE_DIR, BINARY_DIR
6436 The SOURCE_DIR and BINARY_DIR arguments are supported by
6437 ExternalProject_Add(), but different default values are
6438 used by FetchContent_Populate(). SOURCE_DIR defaults to
6439 ${CMAKE_CURRENT_BINARY_DIR}/<lowercaseName>-src and BI‐
6440 NARY_DIR defaults to ${CMAKE_CURRENT_BINARY_DIR}/<lower‐
6441 caseName>-build. If a relative path is specified, it
6442 will be interpreted as relative to CMAKE_CURRENT_BI‐
6443 NARY_DIR.
6444 In addition to the above explicit options, any other unrecog‐
6446 nized options are passed through unmodified to ExternalPro‐
6447 ject_Add() to perform the download, patch and update steps. The
6448 following options are explicitly prohibited (they are disabled
6449 by the FetchContent_Populate() command):
6450 • CONFIGURE_COMMAND
6452 • BUILD_COMMAND
6454 • INSTALL_COMMAND
6456 • TEST_COMMAND
6458 If using FetchContent_Populate() within CMake's script mode, be
6460 aware that the implementation sets up a sub-build which there‐
6461 fore requires a CMake generator and build tool to be available.
6462 If these cannot be found by default, then the CMAKE_GENERATOR
6463 and/or CMAKE_MAKE_PROGRAM variables will need to be set appro‐
6464 priately on the command line invoking the script.
6465 New in version 3.18: Added support for the DOWNLOAD_NO_EXTRACT
6467 option.
6468 FetchContent_GetProperties
6471 When using saved content details, a call to
6472 FetchContent_MakeAvailable() or FetchContent_Populate() records
6473 information in global properties which can be queried at any
6474 time. This information includes the source and binary directo‐
6475 ries associated with the content and also whether or not the
6476 content population has been processed during the current config‐
6477 ure run.
6478 FetchContent_GetProperties(
6480 <name>
6481 [SOURCE_DIR <srcDirVar>]
6482 [BINARY_DIR <binDirVar>]
6483 [POPULATED <doneVar>]
6484 )
6485 The SOURCE_DIR, BINARY_DIR and POPULATED options can be used to
6487 specify which properties should be retrieved. Each option ac‐
6488 cepts a value which is the name of the variable in which to
6489 store that property. Most of the time though, only <name> is
6490 given, in which case the call will then set the same variables
6491 as a call to FetchContent_MakeAvailable(name) or
6492 FetchContent_Populate(name).
6493 This command is rarely needed when using
6495 FetchContent_MakeAvailable(). It is more commonly used as part
6496 of implementing the following pattern with
6497 FetchContent_Populate(), which ensures that the relevant vari‐
6498 ables will always be defined regardless of whether or not the
6499 population has been performed elsewhere in the project already:
6500 # Check if population has already been performed
6502 FetchContent_GetProperties(depname)
6503 if(NOT depname_POPULATED)
6504 # Fetch the content using previously declared details
6505 FetchContent_Populate(depname)
6506 # Set custom variables, policies, etc.
6508 # ...
6509 # Bring the populated content into the build
6511 add_subdirectory(${depname_SOURCE_DIR} ${depname_BINARY_DIR})
6512 endif()
6513 Variables
6515 A number of cache variables can influence the behavior where details
6516 from a FetchContent_Declare() call are used to populate content. The
6517 variables are all intended for the developer to customize behavior and
6518 should not normally be set by the project.
6519 FETCHCONTENT_BASE_DIR
6521 In most cases, the saved details do not specify any options re‐
6522 lating to the directories to use for the internal sub-build, fi‐
6523 nal source and build areas. It is generally best to leave these
6524 decisions up to the FetchContent module to handle on the
6525 project's behalf. The FETCHCONTENT_BASE_DIR cache variable con‐
6526 trols the point under which all content population directories
6527 are collected, but in most cases, developers would not need to
6528 change this. The default location is ${CMAKE_BINARY_DIR}/_deps,
6529 but if developers change this value, they should aim to keep the
6530 path short and just below the top level of the build tree to
6531 avoid running into path length problems on Windows.
6532 FETCHCONTENT_QUIET
6534 The logging output during population can be quite verbose, mak‐
6535 ing the configure stage quite noisy. This cache option (ON by
6536 default) hides all population output unless an error is encoun‐
6537 tered. If experiencing problems with hung downloads, temporar‐
6538 ily switching this option off may help diagnose which content
6539 population is causing the issue.
6540 FETCHCONTENT_FULLY_DISCONNECTED
6542 When this option is enabled, no attempt is made to download or
6543 update any content. It is assumed that all content has already
6544 been populated in a previous run or the source directories have
6545 been pointed at existing contents the developer has provided
6546 manually (using options described further below). When the de‐
6547 veloper knows that no changes have been made to any content de‐
6548 tails, turning this option ON can significantly speed up the
6549 configure stage. It is OFF by default.
6550 FETCHCONTENT_UPDATES_DISCONNECTED
6552 This is a less severe download/update control compared to
6553 FETCHCONTENT_FULLY_DISCONNECTED. Instead of bypassing all down‐
6554 load and update logic, FETCHCONTENT_UPDATES_DISCONNECTED only
6555 disables the update stage. Therefore, if content has not been
6556 downloaded previously, it will still be downloaded when this op‐
6557 tion is enabled. This can speed up the configure stage, but not
6558 as much as FETCHCONTENT_FULLY_DISCONNECTED. It is OFF by de‐
6559 fault.
6560 In addition to the above cache variables, the following cache variables
6562 are also defined for each content name:
6563 FETCHCONTENT_SOURCE_DIR_<uppercaseName>
6565 If this is set, no download or update steps are performed for
6566 the specified content and the <lowercaseName>_SOURCE_DIR vari‐
6567 able returned to the caller is pointed at this location. This
6568 gives developers a way to have a separate checkout of the con‐
6569 tent that they can modify freely without interference from the
6570 build. The build simply uses that existing source, but it still
6571 defines <lowercaseName>_BINARY_DIR to point inside its own build
6572 area. Developers are strongly encouraged to use this mechanism
6573 rather than editing the sources populated in the default loca‐
6574 tion, as changes to sources in the default location can be lost
6575 when content population details are changed by the project.
6576 FETCHCONTENT_UPDATES_DISCONNECTED_<uppercaseName>
6578 This is the per-content equivalent of
6579 FETCHCONTENT_UPDATES_DISCONNECTED. If the global option or this
6580 option is ON, then updates will be disabled for the named con‐
6581 tent. Disabling updates for individual content can be useful
6582 for content whose details rarely change, while still leaving
6583 other frequently changing content with updates enabled.
6584 Examples
6586 This first fairly straightforward example ensures that some popular
6587 testing frameworks are available to the main build:
6588 include(FetchContent)
6590 FetchContent_Declare(
6591 googletest
6592 GIT_REPOSITORY https://github.com/google/googletest.git
6593 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
6594 )
6595 FetchContent_Declare(
6596 Catch2
6597 GIT_REPOSITORY https://github.com/catchorg/Catch2.git
6598 GIT_TAG de6fe184a9ac1a06895cdd1c9b437f0a0bdf14ad # v2.13.4
6599 )
6600 # After the following call, the CMake targets defined by googletest and
6602 # Catch2 will be available to the rest of the build
6603 FetchContent_MakeAvailable(googletest Catch2)
6604 If the sub-project's CMakeLists.txt file is not at the top level of its
6606 source tree, the SOURCE_SUBDIR option can be used to tell FetchContent
6607 where to find it. The following example shows how to use that option
6608 and it also sets a variable which is meaningful to the subproject be‐
6609 fore pulling it into the main build:
6610 include(FetchContent)
6612 FetchContent_Declare(
6613 protobuf
6614 GIT_REPOSITORY https://github.com/protocolbuffers/protobuf.git
6615 GIT_TAG ae50d9b9902526efd6c7a1907d09739f959c6297 # v3.15.0
6616 SOURCE_SUBDIR cmake
6617 )
6618 set(protobuf_BUILD_TESTS OFF)
6619 FetchContent_MakeAvailable(protobuf)
6620 In more complex project hierarchies, the dependency relationships can
6622 be more complicated. Consider a hierarchy where projA is the top level
6623 project and it depends directly on projects projB and projC. Both
6624 projB and projC can be built standalone and they also both depend on
6625 another project projD. projB additionally depends on projE. This ex‐
6626 ample assumes that all five projects are available on a company git
6627 server. The CMakeLists.txt of each project might have sections like
6628 the following:
6629 projA:
6631 include(FetchContent)
6633 FetchContent_Declare(
6634 projB
6635 GIT_REPOSITORY git@mycompany.com:git/projB.git
6636 GIT_TAG 4a89dc7e24ff212a7b5167bef7ab079d
6637 )
6638 FetchContent_Declare(
6639 projC
6640 GIT_REPOSITORY git@mycompany.com:git/projC.git
6641 GIT_TAG 4ad4016bd1d8d5412d135cf8ceea1bb9
6642 )
6643 FetchContent_Declare(
6644 projD
6645 GIT_REPOSITORY git@mycompany.com:git/projD.git
6646 GIT_TAG origin/integrationBranch
6647 )
6648 FetchContent_Declare(
6649 projE
6650 GIT_REPOSITORY git@mycompany.com:git/projE.git
6651 GIT_TAG v2.3-rc1
6652 )
6653 # Order is important, see notes in the discussion further below
6655 FetchContent_MakeAvailable(projD projB projC)
6656 projB:
6658 include(FetchContent)
6660 FetchContent_Declare(
6661 projD
6662 GIT_REPOSITORY git@mycompany.com:git/projD.git
6663 GIT_TAG 20b415f9034bbd2a2e8216e9a5c9e632
6664 )
6665 FetchContent_Declare(
6666 projE
6667 GIT_REPOSITORY git@mycompany.com:git/projE.git
6668 GIT_TAG 68e20f674a48be38d60e129f600faf7d
6669 )
6670 FetchContent_MakeAvailable(projD projE)
6672 projC:
6674 include(FetchContent)
6676 FetchContent_Declare(
6677 projD
6678 GIT_REPOSITORY git@mycompany.com:git/projD.git
6679 GIT_TAG 7d9a17ad2c962aa13e2fbb8043fb6b8a
6680 )
6681 # This particular version of projD requires workarounds
6683 FetchContent_GetProperties(projD)
6684 if(NOT projd_POPULATED)
6685 FetchContent_Populate(projD)
6686 # Copy an additional/replacement file into the populated source
6688 file(COPY someFile.c DESTINATION ${projd_SOURCE_DIR}/src)
6689 add_subdirectory(${projd_SOURCE_DIR} ${projd_BINARY_DIR})
6691 endif()
6692 A few key points should be noted in the above:
6694 • projB and projC define different content details for projD, but projA
6696 also defines a set of content details for projD. Because projA will
6697 define them first, the details from projB and projC will not be used.
6698 The override details defined by projA are not required to match ei‐
6699 ther of those from projB or projC, but it is up to the higher level
6700 project to ensure that the details it does define still make sense
6701 for the child projects.
6702 • In the projA call to FetchContent_MakeAvailable(), projD is listed
6704 ahead of projB and projC to ensure that projA is in control of how
6705 projD is populated.
6706 • While projA defines content details for projE, it does not need to
6708 explicitly call FetchContent_MakeAvailable(projE) or FetchCon‐
6709 tent_Populate(projD) itself. Instead, it leaves that to the child
6710 projB. For higher level projects, it is often enough to just define
6711 the override content details and leave the actual population to the
6712 child projects. This saves repeating the same thing at each level of
6713 the project hierarchy unnecessarily.
6714 Projects don't always need to add the populated content to the build.
6716 Sometimes the project just wants to make the downloaded content avail‐
6717 able at a predictable location. The next example ensures that a set of
6718 standard company toolchain files (and potentially even the toolchain
6719 binaries themselves) is available early enough to be used for that same
6720 build.
6721 cmake_minimum_required(VERSION 3.14)
6723 include(FetchContent)
6725 FetchContent_Declare(
6726 mycom_toolchains
6727 URL https://intranet.mycompany.com//toolchains_1.3.2.tar.gz
6728 )
6729 FetchContent_MakeAvailable(mycom_toolchains)
6730 project(CrossCompileExample)
6732 The project could be configured to use one of the downloaded toolchains
6734 like so:
6735 cmake -DCMAKE_TOOLCHAIN_FILE=_deps/mycom_toolchains-src/toolchain_arm.cmake /path/to/src
6737 When CMake processes the CMakeLists.txt file, it will download and un‐
6739 pack the tarball into _deps/mycompany_toolchains-src relative to the
6740 build directory. The CMAKE_TOOLCHAIN_FILE variable is not used until
6741 the project() command is reached, at which point CMake looks for the
6742 named toolchain file relative to the build directory. Because the tar‐
6743 ball has already been downloaded and unpacked by then, the toolchain
6744 file will be in place, even the very first time that cmake is run in
6745 the build directory.
6746 Lastly, the following example demonstrates how one might download and
6748 unpack a firmware tarball using CMake's script mode. The call to
6749 FetchContent_Populate() specifies all the content details and the un‐
6750 packed firmware will be placed in a firmware directory below the cur‐
6751 rent working directory.
6752 getFirmware.cmake:
6754 # NOTE: Intended to be run in script mode with cmake -P
6756 include(FetchContent)
6757 FetchContent_Populate(
6758 firmware
6759 URL https://mycompany.com/assets/firmware-1.23-arm.tar.gz
6760 URL_HASH MD5=68247684da89b608d466253762b0ff11
6761 SOURCE_DIR firmware
6762 )
6763 FindPackageHandleStandardArgs
6765 This module provides functions intended to be used in Find Modules im‐
6766 plementing find_package(<PackageName>) calls.
6767 find_package_handle_standard_args
6769 This command handles the REQUIRED, QUIET and version-related ar‐
6770 guments of find_package(). It also sets the <PackageName>_FOUND
6771 variable. The package is considered found if all variables
6772 listed contain valid results, e.g. valid filepaths.
6773 There are two signatures:
6775 find_package_handle_standard_args(<PackageName>
6777 (DEFAULT_MSG|<custom-failure-message>)
6778 <required-var>...
6779 )
6780 find_package_handle_standard_args(<PackageName>
6782 [FOUND_VAR <result-var>]
6783 [REQUIRED_VARS <required-var>...]
6784 [VERSION_VAR <version-var>]
6785 [HANDLE_VERSION_RANGE]
6786 [HANDLE_COMPONENTS]
6787 [CONFIG_MODE]
6788 [NAME_MISMATCHED]
6789 [REASON_FAILURE_MESSAGE <reason-failure-message>]
6790 [FAIL_MESSAGE <custom-failure-message>]
6791 )
6792 The <PackageName>_FOUND variable will be set to TRUE if all the
6794 variables <required-var>... are valid and any optional con‐
6795 straints are satisfied, and FALSE otherwise. A success or fail‐
6796 ure message may be displayed based on the results and on whether
6797 the REQUIRED and/or QUIET option was given to the find_package()
6798 call.
6799 The options are:
6801 (DEFAULT_MSG|<custom-failure-message>)
6803 In the simple signature this specifies the failure mes‐
6804 sage. Use DEFAULT_MSG to ask for a default message to be
6805 computed (recommended). Not valid in the full signature.
6806 FOUND_VAR <result-var>
6808 Deprecated since version 3.3.
6809 Specifies either <PackageName>_FOUND or <PACKAGE‐
6812 NAME>_FOUND as the result variable. This exists only for
6813 compatibility with older versions of CMake and is now ig‐
6814 nored. Result variables of both names are always set for
6815 compatibility.
6816 REQUIRED_VARS <required-var>...
6818 Specify the variables which are required for this pack‐
6819 age. These may be named in the generated failure message
6820 asking the user to set the missing variable values.
6821 Therefore these should typically be cache entries such as
6822 FOO_LIBRARY and not output variables like FOO_LIBRARIES.
6823 Changed in version 3.18: If HANDLE_COMPONENTS is speci‐
6825 fied, this option can be omitted.
6826 VERSION_VAR <version-var>
6829 Specify the name of a variable that holds the version of
6830 the package that has been found. This version will be
6831 checked against the (potentially) specified required ver‐
6832 sion given to the find_package() call, including its EX‐
6833 ACT option. The default messages include information
6834 about the required version and the version which has been
6835 actually found, both if the version is ok or not.
6836 HANDLE_VERSION_RANGE
6838 New in version 3.19.
6839 Enable handling of a version range, if one is specified.
6842 Without this option, a developer warning will be dis‐
6843 played if a version range is specified.
6844 HANDLE_COMPONENTS
6846 Enable handling of package components. In this case, the
6847 command will report which components have been found and
6848 which are missing, and the <PackageName>_FOUND variable
6849 will be set to FALSE if any of the required components
6850 (i.e. not the ones listed after the OPTIONAL_COMPONENTS
6851 option of find_package()) are missing.
6852 CONFIG_MODE
6854 Specify that the calling find module is a wrapper around
6855 a call to find_package(<PackageName> NO_MODULE). This
6856 implies a VERSION_VAR value of <PackageName>_VERSION.
6857 The command will automatically check whether the package
6858 configuration file was found.
6859 REASON_FAILURE_MESSAGE <reason-failure-message>
6861 New in version 3.16.
6862 Specify a custom message of the reason for the failure
6865 which will be appended to the default generated message.
6866 FAIL_MESSAGE <custom-failure-message>
6868 Specify a custom failure message instead of using the de‐
6869 fault generated message. Not recommended.
6870 NAME_MISMATCHED
6872 New in version 3.17.
6873 Indicate that the <PackageName> does not match
6876 ${CMAKE_FIND_PACKAGE_NAME}. This is usually a mistake and
6877 raises a warning, but it may be intentional for usage of
6878 the command for components of a larger package.
6879 Example for the simple signature:
6881 find_package_handle_standard_args(LibXml2 DEFAULT_MSG
6883 LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
6884 The LibXml2 package is considered to be found if both LIBXML2_LIBRARY
6886 and LIBXML2_INCLUDE_DIR are valid. Then also LibXml2_FOUND is set to
6887 TRUE. If it is not found and REQUIRED was used, it fails with a mes‐
6888 sage(FATAL_ERROR), independent whether QUIET was used or not. If it is
6889 found, success will be reported, including the content of the first
6890 <required-var>. On repeated CMake runs, the same message will not be
6891 printed again.
6892 NOTE:
6894 If <PackageName> does not match CMAKE_FIND_PACKAGE_NAME for the
6895 calling module, a warning that there is a mismatch is given. The
6896 FPHSA_NAME_MISMATCHED variable may be set to bypass the warning if
6897 using the old signature and the NAME_MISMATCHED argument using the
6898 new signature. To avoid forcing the caller to require newer versions
6899 of CMake for usage, the variable's value will be used if defined
6900 when the NAME_MISMATCHED argument is not passed for the new signa‐
6901 ture (but using both is an error)..
6902 Example for the full signature:
6904 find_package_handle_standard_args(LibArchive
6906 REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
6907 VERSION_VAR LibArchive_VERSION)
6908 In this case, the LibArchive package is considered to be found if both
6910 LibArchive_LIBRARY and LibArchive_INCLUDE_DIR are valid. Also the ver‐
6911 sion of LibArchive will be checked by using the version contained in
6912 LibArchive_VERSION. Since no FAIL_MESSAGE is given, the default mes‐
6913 sages will be printed.
6914 Another example for the full signature:
6916 find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
6918 find_package_handle_standard_args(Automoc4 CONFIG_MODE)
6919 In this case, a FindAutmoc4.cmake module wraps a call to find_pack‐
6921 age(Automoc4 NO_MODULE) and adds an additional search directory for au‐
6922 tomoc4. Then the call to find_package_handle_standard_args produces a
6923 proper success/failure message.
6924 find_package_check_version
6926 New in version 3.19.
6927 Helper function which can be used to check if a <version> is
6930 valid against version-related arguments of find_package().
6931 find_package_check_version(<version> <result-var>
6933 [HANDLE_VERSION_RANGE]
6934 [RESULT_MESSAGE_VARIABLE <message-var>]
6935 )
6936 The <result-var> will hold a boolean value giving the result of
6938 the check.
6939 The options are:
6941 HANDLE_VERSION_RANGE
6943 Enable handling of a version range, if one is specified.
6944 Without this option, a developer warning will be dis‐
6945 played if a version range is specified.
6946 RESULT_MESSAGE_VARIABLE <message-var>
6948 Specify a variable to get back a message describing the
6949 result of the check.
6950 Example for the usage:
6952 find_package_check_version(1.2.3 result HANDLE_VERSION_RANGE
6954 RESULT_MESSAGE_VARIABLE reason)
6955 if (result)
6956 message (STATUS "${reason}")
6957 else()
6958 message (FATAL_ERROR "${reason}")
6959 endif()
6960 FindPackageMessage
6962 find_package_message(<name> "message for user" "find result details")
6963 This function is intended to be used in FindXXX.cmake modules files.
6965 It will print a message once for each unique find result. This is use‐
6966 ful for telling the user where a package was found. The first argument
6967 specifies the name (XXX) of the package. The second argument specifies
6968 the message to display. The third argument lists details about the
6969 find result so that if they change the message will be displayed again.
6970 The macro also obeys the QUIET argument to the find_package command.
6971 Example:
6973 if(X11_FOUND)
6975 find_package_message(X11 "Found X11: ${X11_X11_LIB}"
6976 "[${X11_X11_LIB}][${X11_INCLUDE_DIR}]")
6977 else()
6978 ...
6979 endif()
6980 FortranCInterface
6982 Fortran/C Interface Detection
6983 This module automatically detects the API by which C and Fortran lan‐
6985 guages interact.
6986 Module Variables
6988 Variables that indicate if the mangling is found:
6989 FortranCInterface_GLOBAL_FOUND
6991 Global subroutines and functions.
6992 FortranCInterface_MODULE_FOUND
6994 Module subroutines and functions (declared by "MODULE PROCE‐
6995 DURE").
6996 This module also provides the following variables to specify the de‐
6998 tected mangling, though a typical use case does not need to reference
6999 them and can use the Module Functions below.
7000 FortranCInterface_GLOBAL_PREFIX
7002 Prefix for a global symbol without an underscore.
7003 FortranCInterface_GLOBAL_SUFFIX
7005 Suffix for a global symbol without an underscore.
7006 FortranCInterface_GLOBAL_CASE
7008 The case for a global symbol without an underscore, either UPPER
7009 or LOWER.
7010 FortranCInterface_GLOBAL__PREFIX
7012 Prefix for a global symbol with an underscore.
7013 FortranCInterface_GLOBAL__SUFFIX
7015 Suffix for a global symbol with an underscore.
7016 FortranCInterface_GLOBAL__CASE
7018 The case for a global symbol with an underscore, either UPPER or
7019 LOWER.
7020 FortranCInterface_MODULE_PREFIX
7022 Prefix for a module symbol without an underscore.
7023 FortranCInterface_MODULE_MIDDLE
7025 Middle of a module symbol without an underscore that appears be‐
7026 tween the name of the module and the name of the symbol.
7027 FortranCInterface_MODULE_SUFFIX
7029 Suffix for a module symbol without an underscore.
7030 FortranCInterface_MODULE_CASE
7032 The case for a module symbol without an underscore, either UPPER
7033 or LOWER.
7034 FortranCInterface_MODULE__PREFIX
7036 Prefix for a module symbol with an underscore.
7037 FortranCInterface_MODULE__MIDDLE
7039 Middle of a module symbol with an underscore that appears be‐
7040 tween the name of the module and the name of the symbol.
7041 FortranCInterface_MODULE__SUFFIX
7043 Suffix for a module symbol with an underscore.
7044 FortranCInterface_MODULE__CASE
7046 The case for a module symbol with an underscore, either UPPER or
7047 LOWER.
7048 Module Functions
7050 FortranCInterface_HEADER
7051 The FortranCInterface_HEADER function is provided to generate a
7052 C header file containing macros to mangle symbol names:
7053 FortranCInterface_HEADER(<file>
7055 [MACRO_NAMESPACE <macro-ns>]
7056 [SYMBOL_NAMESPACE <ns>]
7057 [SYMBOLS [<module>:]<function> ...])
7058 It generates in <file> definitions of the following macros:
7060 #define FortranCInterface_GLOBAL (name,NAME) ...
7062 #define FortranCInterface_GLOBAL_(name,NAME) ...
7063 #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
7064 #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
7065 These macros mangle four categories of Fortran symbols, respec‐
7067 tively:
7068 • Global symbols without '_': call mysub()
7070 • Global symbols with '_' : call my_sub()
7072 • Module symbols without '_': use mymod; call mysub()
7074 • Module symbols with '_' : use mymod; call my_sub()
7076 If mangling for a category is not known, its macro is left unde‐
7078 fined. All macros require raw names in both lower case and up‐
7079 per case.
7080 The options are:
7082 MACRO_NAMESPACE
7084 Replace the default FortranCInterface_ prefix with a
7085 given namespace <macro-ns>.
7086 SYMBOLS
7088 List symbols to mangle automatically with C preprocessor
7089 definitions:
7090 <function> ==> #define <ns><function> ...
7092 <module>:<function> ==> #define <ns><module>_<function> ...
7093 If the mangling for some symbol is not known then no pre‐
7095 processor definition is created, and a warning is dis‐
7096 played.
7097 SYMBOL_NAMESPACE
7099 Prefix all preprocessor definitions generated by the SYM‐
7100 BOLS option with a given namespace <ns>.
7101 FortranCInterface_VERIFY
7103 The FortranCInterface_VERIFY function is provided to verify that
7104 the Fortran and C/C++ compilers work together:
7105 FortranCInterface_VERIFY([CXX] [QUIET])
7107 It tests whether a simple test executable using Fortran and C
7109 (and C++ when the CXX option is given) compiles and links suc‐
7110 cessfully. The result is stored in the cache entry FortranCIn‐
7111 terface_VERIFIED_C (or FortranCInterface_VERIFIED_CXX if CXX is
7112 given) as a boolean. If the check fails and QUIET is not given
7113 the function terminates with a fatal error message describing
7114 the problem. The purpose of this check is to stop a build early
7115 for incompatible compiler combinations. The test is built in
7116 the Release configuration.
7117 Example Usage
7119 include(FortranCInterface)
7120 FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
7121 This creates a "FC.h" header that defines mangling macros FC_GLOBAL(),
7123 FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
7124 include(FortranCInterface)
7126 FortranCInterface_HEADER(FCMangle.h
7127 MACRO_NAMESPACE "FC_"
7128 SYMBOL_NAMESPACE "FC_"
7129 SYMBOLS mysub mymod:my_sub)
7130 This creates a "FCMangle.h" header that defines the same FC_*() man‐
7132 gling macros as the previous example plus preprocessor symbols FC_mysub
7133 and FC_mymod_my_sub.
7134 Additional Manglings
7136 FortranCInterface is aware of possible GLOBAL and MODULE manglings for
7137 many Fortran compilers, but it also provides an interface to specify
7138 new possible manglings. Set the variables:
7139 FortranCInterface_GLOBAL_SYMBOLS
7141 FortranCInterface_MODULE_SYMBOLS
7142 before including FortranCInterface to specify manglings of the symbols
7144 MySub, My_Sub, MyModule:MySub, and My_Module:My_Sub. For example, the
7145 code:
7146 set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
7148 # ^^^^^ ^^^^^^ ^^^^^
7149 set(FortranCInterface_MODULE_SYMBOLS
7150 __mymodule_MOD_mysub __my_module_MOD_my_sub)
7151 # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^
7152 include(FortranCInterface)
7153 tells FortranCInterface to try given GLOBAL and MODULE manglings. (The
7155 carets point at raw symbol names for clarity in this example but are
7156 not needed.)
7157 GenerateExportHeader
7159 Function for generation of export macros for libraries
7160 This module provides the function GENERATE_EXPORT_HEADER().
7162 New in version 3.12: Added support for C projects. Previous versions
7164 supported C++ project only.
7165 The GENERATE_EXPORT_HEADER function can be used to generate a file
7168 suitable for preprocessor inclusion which contains EXPORT macros to be
7169 used in library classes:
7170 GENERATE_EXPORT_HEADER( LIBRARY_TARGET
7172 [BASE_NAME <base_name>]
7173 [EXPORT_MACRO_NAME <export_macro_name>]
7174 [EXPORT_FILE_NAME <export_file_name>]
7175 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
7176 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
7177 [INCLUDE_GUARD_NAME <include_guard_name>]
7178 [STATIC_DEFINE <static_define>]
7179 [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
7180 [DEFINE_NO_DEPRECATED]
7181 [PREFIX_NAME <prefix_name>]
7182 [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
7183 )
7184 The target properties CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HID‐
7186 DEN can be used to add the appropriate compile flags for targets. See
7187 the documentation of those target properties, and the convenience vari‐
7188 ables CMAKE_CXX_VISIBILITY_PRESET and CMAKE_VISIBILITY_INLINES_HIDDEN.
7189 By default GENERATE_EXPORT_HEADER() generates macro names in a file
7191 name determined by the name of the library. This means that in the
7192 simplest case, users of GenerateExportHeader will be equivalent to:
7193 set(CMAKE_CXX_VISIBILITY_PRESET hidden)
7195 set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
7196 add_library(somelib someclass.cpp)
7197 generate_export_header(somelib)
7198 install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR})
7199 install(FILES
7200 someclass.h
7201 ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${INCLUDE_INSTALL_DIR}
7202 )
7203 And in the ABI header files:
7205 #include "somelib_export.h"
7207 class SOMELIB_EXPORT SomeClass {
7208 ...
7209 };
7210 The CMake fragment will generate a file in the ${CMAKE_CURRENT_BI‐
7212 NARY_DIR} called somelib_export.h containing the macros SOMELIB_EXPORT,
7213 SOMELIB_NO_EXPORT, SOMELIB_DEPRECATED, SOMELIB_DEPRECATED_EXPORT and
7214 SOMELIB_DEPRECATED_NO_EXPORT. They will be followed by content taken
7215 from the variable specified by the CUSTOM_CONTENT_FROM_VARIABLE option,
7216 if any. The resulting file should be installed with other headers in
7217 the library.
7218 The BASE_NAME argument can be used to override the file name and the
7220 names used for the macros:
7221 add_library(somelib someclass.cpp)
7223 generate_export_header(somelib
7224 BASE_NAME other_name
7225 )
7226 Generates a file called other_name_export.h containing the macros
7228 OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT and OTHER_NAME_DEPRECATED etc.
7229 The BASE_NAME may be overridden by specifying other options in the
7231 function. For example:
7232 add_library(somelib someclass.cpp)
7234 generate_export_header(somelib
7235 EXPORT_MACRO_NAME OTHER_NAME_EXPORT
7236 )
7237 creates the macro OTHER_NAME_EXPORT instead of SOMELIB_EXPORT, but
7239 other macros and the generated file name is as default:
7240 add_library(somelib someclass.cpp)
7242 generate_export_header(somelib
7243 DEPRECATED_MACRO_NAME KDE_DEPRECATED
7244 )
7245 creates the macro KDE_DEPRECATED instead of SOMELIB_DEPRECATED.
7247 If LIBRARY_TARGET is a static library, macros are defined without val‐
7249 ues.
7250 If the same sources are used to create both a shared and a static li‐
7252 brary, the uppercased symbol ${BASE_NAME}_STATIC_DEFINE should be used
7253 when building the static library:
7254 add_library(shared_variant SHARED ${lib_SRCS})
7256 add_library(static_variant ${lib_SRCS})
7257 generate_export_header(shared_variant BASE_NAME libshared_and_static)
7258 set_target_properties(static_variant PROPERTIES
7259 COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)
7260 This will cause the export macros to expand to nothing when building
7262 the static library.
7263 If DEFINE_NO_DEPRECATED is specified, then a macro ${BASE_NAME}_NO_DEP‐
7265 RECATED will be defined This macro can be used to remove deprecated
7266 code from preprocessor output:
7267 option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
7269 if (EXCLUDE_DEPRECATED)
7270 set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED)
7271 endif()
7272 generate_export_header(somelib ${NO_BUILD_DEPRECATED})
7273 And then in somelib:
7275 class SOMELIB_EXPORT SomeClass
7277 {
7278 public:
7279 #ifndef SOMELIB_NO_DEPRECATED
7280 SOMELIB_DEPRECATED void oldMethod();
7281 #endif
7282 };
7283 #ifndef SOMELIB_NO_DEPRECATED
7285 void SomeClass::oldMethod() { }
7286 #endif
7287 If PREFIX_NAME is specified, the argument will be used as a prefix to
7289 all generated macros.
7290 For example:
7292 generate_export_header(somelib PREFIX_NAME VTK_)
7294 Generates the macros VTK_SOMELIB_EXPORT etc.
7296 New in version 3.1: Library target can be an OBJECT library.
7298 New in version 3.7: Added the CUSTOM_CONTENT_FROM_VARIABLE option.
7301 New in version 3.11: Added the INCLUDE_GUARD_NAME option.
7304 ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
7307 Deprecated since version 3.0: Set the target properties CXX_VISIBIL‐
7309 ITY_PRESET and VISIBILITY_INLINES_HIDDEN instead.
7310 The ADD_COMPILER_EXPORT_FLAGS function adds -fvisibility=hidden to
7313 CMAKE_CXX_FLAGS if supported, and is a no-op on Windows which does not
7314 need extra compiler flags for exporting support. You may optionally
7315 pass a single argument to ADD_COMPILER_EXPORT_FLAGS that will be popu‐
7316 lated with the CXX_FLAGS required to enable visibility support for the
7317 compiler/architecture in use.
7318 GetPrerequisites
7320 Deprecated since version 3.16: Use file(GET_RUNTIME_DEPENDENCIES) in‐
7321 stead.
7322 Functions to analyze and list executable file prerequisites.
7325 This module provides functions to list the .dll, .dylib or .so files
7327 that an executable or shared library file depends on. (Its prerequi‐
7328 sites.)
7329 It uses various tools to obtain the list of required shared library
7331 files:
7332 dumpbin (Windows)
7334 objdump (MinGW on Windows)
7335 ldd (Linux/Unix)
7336 otool (Mac OSX)
7337 Changed in version 3.16: The tool specified by CMAKE_OBJDUMP will be
7339 used, if set.
7340 The following functions are provided by this module:
7343 get_prerequisites
7345 list_prerequisites
7346 list_prerequisites_by_glob
7347 gp_append_unique
7348 is_file_executable
7349 gp_item_default_embedded_path
7350 (projects can override with gp_item_default_embedded_path_override)
7351 gp_resolve_item
7352 (projects can override with gp_resolve_item_override)
7353 gp_resolved_file_type
7354 (projects can override with gp_resolved_file_type_override)
7355 gp_file_type
7356 GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse>
7358 <exepath> <dirs> [<rpaths>])
7359 Get the list of shared library files required by <target>. The list in
7361 the variable named <prerequisites_var> should be empty on first entry
7362 to this function. On exit, <prerequisites_var> will contain the list
7363 of required shared library files.
7364 <target> is the full path to an executable file. <prerequisites_var>
7366 is the name of a CMake variable to contain the results. <exclude_sys‐
7367 tem> must be 0 or 1 indicating whether to include or exclude "system"
7368 prerequisites. If <recurse> is set to 1 all prerequisites will be
7369 found recursively, if set to 0 only direct prerequisites are listed.
7370 <exepath> is the path to the top level executable used for @exe‐
7371 cutable_path replacement on the Mac. <dirs> is a list of paths where
7372 libraries might be found: these paths are searched first when a target
7373 without any path info is given. Then standard system locations are
7374 also searched: PATH, Framework locations, /usr/lib...
7375 New in version 3.14: The variable GET_PREREQUISITES_VERBOSE can be set
7377 to true to enable verbose output.
7378 LIST_PREREQUISITES(<target> [<recurse> [<exclude_system> [<verbose>]]])
7381 Print a message listing the prerequisites of <target>.
7383 <target> is the name of a shared library or executable target or the
7385 full path to a shared library or executable file. If <recurse> is set
7386 to 1 all prerequisites will be found recursively, if set to 0 only di‐
7387 rect prerequisites are listed. <exclude_system> must be 0 or 1 indi‐
7388 cating whether to include or exclude "system" prerequisites. With
7389 <verbose> set to 0 only the full path names of the prerequisites are
7390 printed, set to 1 extra information will be displayed.
7391 LIST_PREREQUISITES_BY_GLOB(<glob_arg> <glob_exp>)
7393 Print the prerequisites of shared library and executable files matching
7395 a globbing pattern. <glob_arg> is GLOB or GLOB_RECURSE and <glob_exp>
7396 is a globbing expression used with "file(GLOB" or "file(GLOB_RECURSE"
7397 to retrieve a list of matching files. If a matching file is exe‐
7398 cutable, its prerequisites are listed.
7399 Any additional (optional) arguments provided are passed along as the
7401 optional arguments to the list_prerequisites calls.
7402 GP_APPEND_UNIQUE(<list_var> <value>)
7404 Append <value> to the list variable <list_var> only if the value is not
7406 already in the list.
7407 IS_FILE_EXECUTABLE(<file> <result_var>)
7409 Return 1 in <result_var> if <file> is a binary executable, 0 otherwise.
7411 GP_ITEM_DEFAULT_EMBEDDED_PATH(<item> <default_embedded_path_var>)
7413 Return the path that others should refer to the item by when the item
7415 is embedded inside a bundle.
7416 Override on a per-project basis by providing a project-specific
7418 gp_item_default_embedded_path_override function.
7419 GP_RESOLVE_ITEM(<context> <item> <exepath> <dirs> <resolved_item_var>
7421 [<rpaths>])
7422 Resolve an item into an existing full path file.
7424 Override on a per-project basis by providing a project-specific gp_re‐
7426 solve_item_override function.
7427 GP_RESOLVED_FILE_TYPE(<original_file> <file> <exepath> <dirs> <type_var>
7429 [<rpaths>])
7430 Return the type of <file> with respect to <original_file>. String de‐
7432 scribing type of prerequisite is returned in variable named <type_var>.
7433 Use <exepath> and <dirs> if necessary to resolve non-absolute <file>
7435 values -- but only for non-embedded items.
7436 Possible types are:
7438 system
7440 local
7441 embedded
7442 other
7443 Override on a per-project basis by providing a project-specific gp_re‐
7445 solved_file_type_override function.
7446 GP_FILE_TYPE(<original_file> <file> <type_var>)
7448 Return the type of <file> with respect to <original_file>. String de‐
7450 scribing type of prerequisite is returned in variable named <type_var>.
7451 Possible types are:
7453 system
7455 local
7456 embedded
7457 other
7458 GNUInstallDirs
7460 Define GNU standard installation directories
7461 Provides install directory variables as defined by the GNU Coding Stan‐
7463 dards.
7464 Result Variables
7466 Inclusion of this module defines the following variables:
7467 CMAKE_INSTALL_<dir>
7469 Destination for files of a given type. This value may be passed to
7470 the DESTINATION options of install() commands for the corresponding
7471 file type. It should typically be a path relative to the installa‐
7472 tion prefix so that it can be converted to an absolute path in a re‐
7473 locatable way (see CMAKE_INSTALL_FULL_<dir>). However, an absolute
7474 path is also allowed.
7475 CMAKE_INSTALL_FULL_<dir>
7477 The absolute path generated from the corresponding CMAKE_IN‐
7478 STALL_<dir> value. If the value is not already an absolute path, an
7479 absolute path is constructed typically by prepending the value of
7480 the CMAKE_INSTALL_PREFIX variable. However, there are some special
7481 cases as documented below.
7482 where <dir> is one of:
7484 BINDIR user executables (bin)
7486 SBINDIR
7488 system admin executables (sbin)
7489 LIBEXECDIR
7491 program executables (libexec)
7492 SYSCONFDIR
7494 read-only single-machine data (etc)
7495 SHAREDSTATEDIR
7497 modifiable architecture-independent data (com)
7498 LOCALSTATEDIR
7500 modifiable single-machine data (var)
7501 RUNSTATEDIR
7503 New in version 3.9: run-time variable data (LOCALSTATEDIR/run)
7504 LIBDIR object code libraries (lib or lib64 or lib/<multiarch-tuple> on
7507 Debian)
7508 INCLUDEDIR
7510 C header files (include)
7511 OLDINCLUDEDIR
7513 C header files for non-gcc (/usr/include)
7514 DATAROOTDIR
7516 read-only architecture-independent data root (share)
7517 DATADIR
7519 read-only architecture-independent data (DATAROOTDIR)
7520 INFODIR
7522 info documentation (DATAROOTDIR/info)
7523 LOCALEDIR
7525 locale-dependent data (DATAROOTDIR/locale)
7526 MANDIR man documentation (DATAROOTDIR/man)
7528 DOCDIR documentation root (DATAROOTDIR/doc/PROJECT_NAME)
7530 If the includer does not define a value the above-shown default will be
7532 used and the value will appear in the cache for editing by the user.
7533 Special Cases
7535 New in version 3.4.
7536 The following values of CMAKE_INSTALL_PREFIX are special:
7539 /
7541 For <dir> other than the SYSCONFDIR, LOCALSTATEDIR and RUNSTATEDIR,
7542 the value of CMAKE_INSTALL_<dir> is prefixed with usr/ if it is not
7543 user-specified as an absolute path. For example, the INCLUDEDIR
7544 value include becomes usr/include. This is required by the GNU Cod‐
7545 ing Standards, which state:
7546 When building the complete GNU system, the prefix will be empty
7547 and /usr will be a symbolic link to /.
7548 /usr
7550 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
7551 CMAKE_INSTALL_FULL_<dir> is computed by prepending just / to the
7552 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
7553 lute path. For example, the SYSCONFDIR value etc becomes /etc.
7554 This is required by the GNU Coding Standards.
7555 /opt/...
7557 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
7558 CMAKE_INSTALL_FULL_<dir> is computed by appending the prefix to the
7559 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
7560 lute path. For example, the SYSCONFDIR value etc becomes
7561 /etc/opt/.... This is defined by the Filesystem Hierarchy Standard.
7562 Macros
7564 GNUInstallDirs_get_absolute_install_dir
7565 GNUInstallDirs_get_absolute_install_dir(absvar var dirname)
7567 New in version 3.7.
7569 Set the given variable absvar to the absolute path contained
7572 within the variable var. This is to allow the computation of an
7573 absolute path, accounting for all the special cases documented
7574 above. While this macro is used to compute the various
7575 CMAKE_INSTALL_FULL_<dir> variables, it is exposed publicly to
7576 allow users who create additional path variables to also compute
7577 absolute paths where necessary, using the same logic. dirname
7578 is the directory name to get, e.g. BINDIR.
7579 Changed in version 3.20: Added the <dirname> parameter. Previ‐
7581 ous versions of CMake passed this value through the variable
7582 ${dir}.
7583 GoogleTest
7586 New in version 3.9.
7587 This module defines functions to help use the Google Test infrastruc‐
7590 ture. Two mechanisms for adding tests are provided. gtest_add_tests()
7591 has been around for some time, originally via find_package(GTest).
7592 gtest_discover_tests() was introduced in CMake 3.10.
7593 The (older) gtest_add_tests() scans source files to identify tests.
7595 This is usually effective, with some caveats, including in cross-com‐
7596 piling environments, and makes setting additional properties on tests
7597 more convenient. However, its handling of parameterized tests is less
7598 comprehensive, and it requires re-running CMake to detect changes to
7599 the list of tests.
7600 The (newer) gtest_discover_tests() discovers tests by asking the com‐
7602 piled test executable to enumerate its tests. This is more robust and
7603 provides better handling of parameterized tests, and does not require
7604 CMake to be re-run when tests change. However, it may not work in a
7605 cross-compiling environment, and setting test properties is less conve‐
7606 nient.
7607 More details can be found in the documentation of the respective func‐
7609 tions.
7610 Both commands are intended to replace use of add_test() to register
7612 tests, and will create a separate CTest test for each Google Test test
7613 case. Note that this is in some cases less efficient, as common set-up
7614 and tear-down logic cannot be shared by multiple test cases executing
7615 in the same instance. However, it provides more fine-grained pass/fail
7616 information to CTest, which is usually considered as more beneficial.
7617 By default, the CTest test name is the same as the Google Test name
7618 (i.e. suite.testcase); see also TEST_PREFIX and TEST_SUFFIX.
7619 gtest_add_tests
7621 Automatically add tests with CTest by scanning source code for
7622 Google Test macros:
7623 gtest_add_tests(TARGET target
7625 [SOURCES src1...]
7626 [EXTRA_ARGS arg1...]
7627 [WORKING_DIRECTORY dir]
7628 [TEST_PREFIX prefix]
7629 [TEST_SUFFIX suffix]
7630 [SKIP_DEPENDENCY]
7631 [TEST_LIST outVar]
7632 )
7633 gtest_add_tests attempts to identify tests by scanning source
7635 files. Although this is generally effective, it uses only a ba‐
7636 sic regular expression match, which can be defeated by atypical
7637 test declarations, and is unable to fully "split" parameterized
7638 tests. Additionally, it requires that CMake be re-run to dis‐
7639 cover any newly added, removed or renamed tests (by default,
7640 this means that CMake is re-run when any test source file is
7641 changed, but see SKIP_DEPENDENCY). However, it has the advan‐
7642 tage of declaring tests at CMake time, which somewhat simplifies
7643 setting additional properties on tests, and always works in a
7644 cross-compiling environment.
7645 The options are:
7647 TARGET target
7649 Specifies the Google Test executable, which must be a
7650 known CMake executable target. CMake will substitute the
7651 location of the built executable when running the test.
7652 SOURCES src1...
7654 When provided, only the listed files will be scanned for
7655 test cases. If this option is not given, the SOURCES
7656 property of the specified target will be used to obtain
7657 the list of sources.
7658 EXTRA_ARGS arg1...
7660 Any extra arguments to pass on the command line to each
7661 test case.
7662 WORKING_DIRECTORY dir
7664 Specifies the directory in which to run the discovered
7665 test cases. If this option is not provided, the current
7666 binary directory is used.
7667 TEST_PREFIX prefix
7669 Specifies a prefix to be prepended to the name of each
7670 discovered test case. This can be useful when the same
7671 source files are being used in multiple calls to
7672 gtest_add_test() but with different EXTRA_ARGS.
7673 TEST_SUFFIX suffix
7675 Similar to TEST_PREFIX except the suffix is appended to
7676 the name of every discovered test case. Both TEST_PREFIX
7677 and TEST_SUFFIX may be specified.
7678 SKIP_DEPENDENCY
7680 Normally, the function creates a dependency which will
7681 cause CMake to be re-run if any of the sources being
7682 scanned are changed. This is to ensure that the list of
7683 discovered tests is updated. If this behavior is not de‐
7684 sired (as may be the case while actually writing the test
7685 cases), this option can be used to prevent the dependency
7686 from being added.
7687 TEST_LIST outVar
7689 The variable named by outVar will be populated in the
7690 calling scope with the list of discovered test cases.
7691 This allows the caller to do things like manipulate test
7692 properties of the discovered tests.
7693 Usage example:
7695 include(GoogleTest)
7697 add_executable(FooTest FooUnitTest.cxx)
7698 gtest_add_tests(TARGET FooTest
7699 TEST_SUFFIX .noArgs
7700 TEST_LIST noArgsTests
7701 )
7702 gtest_add_tests(TARGET FooTest
7703 EXTRA_ARGS --someArg someValue
7704 TEST_SUFFIX .withArgs
7705 TEST_LIST withArgsTests
7706 )
7707 set_tests_properties(${noArgsTests} PROPERTIES TIMEOUT 10)
7708 set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20)
7709 For backward compatibility, the following form is also sup‐
7711 ported:
7712 gtest_add_tests(exe args files...)
7714 exe The path to the test executable or the name of a CMake
7716 target.
7717 args A ;-list of extra arguments to be passed to executable.
7719 The entire list must be passed as a single argument. En‐
7720 close it in quotes, or pass "" for no arguments.
7721 files...
7723 A list of source files to search for tests and test fix‐
7724 tures. Alternatively, use AUTO to specify that exe is
7725 the name of a CMake executable target whose sources
7726 should be scanned.
7727 include(GoogleTest)
7729 set(FooTestArgs --foo 1 --bar 2)
7730 add_executable(FooTest FooUnitTest.cxx)
7731 gtest_add_tests(FooTest "${FooTestArgs}" AUTO)
7732 gtest_discover_tests
7734 Automatically add tests with CTest by querying the compiled test
7735 executable for available tests:
7736 gtest_discover_tests(target
7738 [EXTRA_ARGS arg1...]
7739 [WORKING_DIRECTORY dir]
7740 [TEST_PREFIX prefix]
7741 [TEST_SUFFIX suffix]
7742 [TEST_FILTER expr]
7743 [NO_PRETTY_TYPES] [NO_PRETTY_VALUES]
7744 [PROPERTIES name1 value1...]
7745 [TEST_LIST var]
7746 [DISCOVERY_TIMEOUT seconds]
7747 [XML_OUTPUT_DIR dir]
7748 [DISCOVERY_MODE <POST_BUILD|PRE_TEST>]
7749 )
7750 New in version 3.10.
7752 gtest_discover_tests() sets up a post-build command on the test
7755 executable that generates the list of tests by parsing the out‐
7756 put from running the test with the --gtest_list_tests argument.
7757 Compared to the source parsing approach of gtest_add_tests(),
7758 this ensures that the full list of tests, including instantia‐
7759 tions of parameterized tests, is obtained. Since test discovery
7760 occurs at build time, it is not necessary to re-run CMake when
7761 the list of tests changes. However, it requires that CROSSCOM‐
7762 PILING_EMULATOR is properly set in order to function in a
7763 cross-compiling environment.
7764 Additionally, setting properties on tests is somewhat less con‐
7766 venient, since the tests are not available at CMake time. Addi‐
7767 tional test properties may be assigned to the set of tests as a
7768 whole using the PROPERTIES option. If more fine-grained test
7769 control is needed, custom content may be provided through an ex‐
7770 ternal CTest script using the TEST_INCLUDE_FILES directory prop‐
7771 erty. The set of discovered tests is made accessible to such a
7772 script via the <target>_TESTS variable.
7773 The options are:
7775 target Specifies the Google Test executable, which must be a
7777 known CMake executable target. CMake will substitute the
7778 location of the built executable when running the test.
7779 EXTRA_ARGS arg1...
7781 Any extra arguments to pass on the command line to each
7782 test case.
7783 WORKING_DIRECTORY dir
7785 Specifies the directory in which to run the discovered
7786 test cases. If this option is not provided, the current
7787 binary directory is used.
7788 TEST_PREFIX prefix
7790 Specifies a prefix to be prepended to the name of each
7791 discovered test case. This can be useful when the same
7792 test executable is being used in multiple calls to
7793 gtest_discover_tests() but with different EXTRA_ARGS.
7794 TEST_SUFFIX suffix
7796 Similar to TEST_PREFIX except the suffix is appended to
7797 the name of every discovered test case. Both TEST_PREFIX
7798 and TEST_SUFFIX may be specified.
7799 TEST_FILTER expr
7801 New in version 3.22.
7802 Filter expression to pass as a --gtest_filter argument
7805 during test discovery. Note that the expression is a
7806 wildcard-based format that matches against the original
7807 test names as used by gtest. For type or value-parame‐
7808 terized tests, these names may be different to the poten‐
7809 tially pretty-printed test names that ctest uses.
7810 NO_PRETTY_TYPES
7812 By default, the type index of type-parameterized tests is
7813 replaced by the actual type name in the CTest test name.
7814 If this behavior is undesirable (e.g. because the type
7815 names are unwieldy), this option will suppress this be‐
7816 havior.
7817 NO_PRETTY_VALUES
7819 By default, the value index of value-parameterized tests
7820 is replaced by the actual value in the CTest test name.
7821 If this behavior is undesirable (e.g. because the value
7822 strings are unwieldy), this option will suppress this be‐
7823 havior.
7824 PROPERTIES name1 value1...
7826 Specifies additional properties to be set on all tests
7827 discovered by this invocation of gtest_discover_tests().
7828 TEST_LIST var
7830 Make the list of tests available in the variable var,
7831 rather than the default <target>_TESTS. This can be use‐
7832 ful when the same test executable is being used in multi‐
7833 ple calls to gtest_discover_tests(). Note that this
7834 variable is only available in CTest.
7835 DISCOVERY_TIMEOUT num
7837 New in version 3.10.3.
7838 Specifies how long (in seconds) CMake will wait for the
7841 test to enumerate available tests. If the test takes
7842 longer than this, discovery (and your build) will fail.
7843 Most test executables will enumerate their tests very
7844 quickly, but under some exceptional circumstances, a test
7845 may require a longer timeout. The default is 5. See
7846 also the TIMEOUT option of execute_process().
7847 NOTE:
7849 In CMake versions 3.10.1 and 3.10.2, this option was
7850 called TIMEOUT. This clashed with the TIMEOUT test
7851 property, which is one of the common properties that
7852 would be set with the PROPERTIES keyword, usually
7853 leading to legal but unintended behavior. The keyword
7854 was changed to DISCOVERY_TIMEOUT in CMake 3.10.3 to
7855 address this problem. The ambiguous behavior of the
7856 TIMEOUT keyword in 3.10.1 and 3.10.2 has not been pre‐
7857 served.
7858 XML_OUTPUT_DIR dir
7860 New in version 3.18.
7861 If specified, the parameter is passed along with
7864 --gtest_output=xml: to test executable. The actual file
7865 name is the same as the test target, including prefix and
7866 suffix. This should be used instead of EXTRA_ARGS
7867 --gtest_output=xml to avoid race conditions writing the
7868 XML result output when using parallel test execution.
7869 DISCOVERY_MODE
7871 New in version 3.18.
7872 Provides greater control over when gtest_discover_tests()
7875 performs test discovery. By default, POST_BUILD sets up a
7876 post-build command to perform test discovery at build
7877 time. In certain scenarios, like cross-compiling, this
7878 POST_BUILD behavior is not desirable. By contrast,
7879 PRE_TEST delays test discovery until just prior to test
7880 execution. This way test discovery occurs in the target
7881 environment where the test has a better chance at finding
7882 appropriate runtime dependencies.
7883 DISCOVERY_MODE defaults to the value of the
7885 CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE variable if it
7886 is not passed when calling gtest_discover_tests(). This
7887 provides a mechanism for globally selecting a preferred
7888 test discovery behavior without having to modify each
7889 call site.
7890 InstallRequiredSystemLibraries
7892 Include this module to search for compiler-provided system runtime li‐
7893 braries and add install rules for them. Some optional variables may be
7894 set prior to including the module to adjust behavior:
7895 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS
7897 Specify additional runtime libraries that may not be detected.
7898 After inclusion any detected libraries will be appended to this.
7899 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP
7901 Set to TRUE to skip calling the install(PROGRAMS) command to al‐
7902 low the includer to specify its own install rule, using the
7903 value of CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS to get the list of
7904 libraries.
7905 CMAKE_INSTALL_DEBUG_LIBRARIES
7907 Set to TRUE to install the debug runtime libraries when avail‐
7908 able with MSVC tools.
7909 CMAKE_INSTALL_DEBUG_LIBRARIES_ONLY
7911 Set to TRUE to install only the debug runtime libraries with
7912 MSVC tools even if the release runtime libraries are also avail‐
7913 able.
7914 CMAKE_INSTALL_UCRT_LIBRARIES
7916 New in version 3.6.
7917 Set to TRUE to install the Windows Universal CRT libraries for
7920 app-local deployment (e.g. to Windows XP). This is meaningful
7921 only with MSVC from Visual Studio 2015 or higher.
7922 New in version 3.9: One may set a CMAKE_WINDOWS_KITS_10_DIR en‐
7924 vironment variable to an absolute path to tell CMake to look for
7925 Windows 10 SDKs in a custom location. The specified directory
7926 is expected to contain Redist/ucrt/DLLs/* directories.
7927 CMAKE_INSTALL_MFC_LIBRARIES
7930 Set to TRUE to install the MSVC MFC runtime libraries.
7931 CMAKE_INSTALL_OPENMP_LIBRARIES
7933 Set to TRUE to install the MSVC OpenMP runtime libraries
7934 CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION
7936 Specify the install(PROGRAMS) command DESTINATION option. If
7937 not specified, the default is bin on Windows and lib elsewhere.
7938 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_NO_WARNINGS
7940 Set to TRUE to disable warnings about required library files
7941 that do not exist. (For example, Visual Studio Express editions
7942 may not provide the redistributable files.)
7943 CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT
7945 New in version 3.3.
7946 Specify the install(PROGRAMS) command COMPONENT option. If not
7949 specified, no such option will be used.
7950 New in version 3.10: Support for installing Intel compiler runtimes.
7952 ProcessorCount
7955 ProcessorCount(var)
7956 Determine the number of processors/cores and save value in ${var}
7958 Sets the variable named ${var} to the number of physical cores avail‐
7960 able on the machine if the information can be determined. Otherwise it
7961 is set to 0. Currently this functionality is implemented for AIX, cyg‐
7962 win, FreeBSD, HPUX, Linux, macOS, QNX, Sun and Windows.
7963 Changed in version 3.15: On Linux, returns the container CPU count in‐
7965 stead of the host CPU count.
7966 This function is guaranteed to return a positive integer (>=1) if it
7969 succeeds. It returns 0 if there's a problem determining the processor
7970 count.
7971 Example use, in a ctest -S dashboard script:
7973 include(ProcessorCount)
7975 ProcessorCount(N)
7976 if(NOT N EQUAL 0)
7977 set(CTEST_BUILD_FLAGS -j${N})
7978 set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N})
7979 endif()
7980 This function is intended to offer an approximation of the value of the
7982 number of compute cores available on the current machine, such that you
7983 may use that value for parallel building and parallel testing. It is
7984 meant to help utilize as much of the machine as seems reasonable. Of
7985 course, knowledge of what else might be running on the machine simulta‐
7986 neously should be used when deciding whether to request a machine's
7987 full capacity all for yourself.
7988 SelectLibraryConfigurations
7990 select_library_configurations(basename)
7991 This macro takes a library base name as an argument, and will choose
7993 good values for the variables
7994 basename_LIBRARY
7996 basename_LIBRARIES
7997 basename_LIBRARY_DEBUG
7998 basename_LIBRARY_RELEASE
7999 depending on what has been found and set.
8001 If only basename_LIBRARY_RELEASE is defined, basename_LIBRARY will be
8003 set to the release value, and basename_LIBRARY_DEBUG will be set to
8004 basename_LIBRARY_DEBUG-NOTFOUND. If only basename_LIBRARY_DEBUG is de‐
8005 fined, then basename_LIBRARY will take the debug value, and base‐
8006 name_LIBRARY_RELEASE will be set to basename_LIBRARY_RELEASE-NOTFOUND.
8007 If the generator supports configuration types, then basename_LIBRARY
8009 and basename_LIBRARIES will be set with debug and optimized flags spec‐
8010 ifying the library to be used for the given configuration. If no build
8011 type has been set or the generator in use does not support configura‐
8012 tion types, then basename_LIBRARY and basename_LIBRARIES will take only
8013 the release value, or the debug value if the release one is not set.
8014 SquishTestScript
8016 This script launches a GUI test using Squish. You should not call the
8017 script directly; instead, you should access it via the SQUISH_ADD_TEST
8018 macro that is defined in FindSquish.cmake.
8019 This script starts the Squish server, launches the test on the client,
8021 and finally stops the squish server. If any of these steps fail (in‐
8022 cluding if the tests do not pass) then a fatal error is raised.
8023 TestBigEndian
8025 Deprecated since version 3.20: Supserseded by the CMAKE_<LANG>_BYTE_OR‐
8026 DER variable.
8027 Check if the target architecture is big endian or little endian.
8030 test_big_endian
8032 test_big_endian(<var>)
8034 Stores in variable <var> either 1 or 0 indicating whether the
8036 target architecture is big or little endian.
8037 TestForANSIForScope
8039 Check for ANSI for scope support
8040 Check if the compiler restricts the scope of variables declared in a
8042 for-init-statement to the loop body.
8043 CMAKE_NO_ANSI_FOR_SCOPE - holds result
8045 TestForANSIStreamHeaders
8047 Test for compiler support of ANSI stream headers iostream, etc.
8048 check if the compiler supports the standard ANSI iostream header (with‐
8050 out the .h)
8051 CMAKE_NO_ANSI_STREAM_HEADERS - defined by the results
8053 TestForSSTREAM
8055 Test for compiler support of ANSI sstream header
8056 check if the compiler supports the standard ANSI sstream header
8058 CMAKE_NO_ANSI_STRING_STREAM - defined by the results
8060 TestForSTDNamespace
8062 Test for std:: namespace support
8063 check if the compiler supports std:: on stl classes
8065 CMAKE_NO_STD_NAMESPACE - defined by the results
8067 UseEcos
8069 This module defines variables and macros required to build eCos appli‐
8070 cation.
8071 This file contains the following macros: ECOS_ADD_INCLUDE_DIRECTORIES()
8073 - add the eCos include dirs ECOS_ADD_EXECUTABLE(name source1 ...
8074 sourceN ) - create an eCos executable ECOS_ADJUST_DIRECTORY(VAR source1
8075 ... sourceN ) - adjusts the path of the source files and puts the re‐
8076 sult into VAR
8077 Macros for selecting the toolchain: ECOS_USE_ARM_ELF_TOOLS() - enable
8079 the ARM ELF toolchain for the directory where it is called
8080 ECOS_USE_I386_ELF_TOOLS() - enable the i386 ELF toolchain for the di‐
8081 rectory where it is called ECOS_USE_PPC_EABI_TOOLS() - enable the Pow‐
8082 erPC toolchain for the directory where it is called
8083 It contains the following variables: ECOS_DEFINITIONS ECOSCONFIG_EXE‐
8085 CUTABLE ECOS_CONFIG_FILE - defaults to ecos.ecc, if your eCos configu‐
8086 ration file has a different name, adjust this variable for internal use
8087 only:
8088 ECOS_ADD_TARGET_LIB
8090 UseJava
8092 This file provides support for Java. It is assumed that FindJava has
8093 already been loaded. See FindJava for information on how to load Java
8094 into your CMake project.
8095 Synopsis
8097 Creating and Installing JARS
8098 add_jar (<target_name> [SOURCES] <source1> [<source2>...] ...)
8099 install_jar (<target_name> DESTINATION <destination> [COMPONENT <component>])
8100 install_jni_symlink (<target_name> DESTINATION <destination> [COMPONENT <component>])
8101 Header Generation
8103 create_javah ((TARGET <target> | GENERATED_FILES <VAR>) CLASSES <class>... ...)
8104 Exporting JAR Targets
8106 install_jar_exports (TARGETS <jars>... FILE <filename> DESTINATION <destination> ...)
8107 export_jars (TARGETS <jars>... [NAMESPACE <namespace>] FILE <filename>)
8108 Finding JARs
8110 find_jar (<VAR> NAMES <name1> [<name2>...] [PATHS <path1> [<path2>... ENV <var>]] ...)
8111 Creating Java Documentation
8113 create_javadoc (<VAR> (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...]) ...)
8114 Creating And Installing JARs
8116 add_jar
8117 Creates a jar file containing java objects and, optionally, re‐
8118 sources:
8119 add_jar(<target_name>
8121 [SOURCES] <source1> [<source2>...] [<resource1>...]
8122 [RESOURCES NAMESPACE <ns1> <resource1>... [NAMESPACE <nsX> <resourceX>...]... ]
8123 [INCLUDE_JARS <jar1> [<jar2>...]]
8124 [ENTRY_POINT <entry>]
8125 [VERSION <version>]
8126 [MANIFEST <manifest>]
8127 [OUTPUT_NAME <name>]
8128 [OUTPUT_DIR <dir>]
8129 [GENERATE_NATIVE_HEADERS <target>
8130 [DESTINATION (<dir>|INSTALL <dir> [BUILD <dir>])]]
8131 )
8132 This command creates a <target_name>.jar. It compiles the given
8134 <source> files and adds the given <resource> files to the jar
8135 file. Source files can be java files or listing files (prefixed
8136 by @). If only resource files are given then just a jar file is
8137 created.
8138 SOURCES
8140 Compiles the specified source files and adds the result
8141 in the jar file.
8142 New in version 3.4: Support for response files, prefixed
8144 by @.
8145 RESOURCES
8148 New in version 3.21.
8149 Adds the named <resource> files to the jar by stripping
8152 the source file path and placing the file beneath <ns>
8153 within the jar.
8154 For example:
8156 RESOURCES NAMESPACE "/com/my/namespace" "a/path/to/resource.txt"
8158 results in a resource accessible via /com/my/name‐
8160 space/resource.txt within the jar.
8161 Resources may be added without adjusting the namespace by
8163 adding them to the list of SOURCES (original behavior),
8164 in this case, resource paths must be relative to
8165 CMAKE_CURRENT_SOURCE_DIR. Adding resources without using
8166 the RESOURCES parameter in out of source builds will al‐
8167 most certainly result in confusion.
8168 NOTE:
8170 Adding resources via the SOURCES parameter relies upon
8171 a hard-coded list of file extensions which are tested
8172 to determine whether they compile (e.g. File.java).
8173 SOURCES files which match the extensions are compiled.
8174 Files which do not match are treated as resources. To
8175 include uncompiled resources matching those file ex‐
8176 tensions use the RESOURCES parameter.
8177 INCLUDE_JARS
8179 The list of jars are added to the classpath when compil‐
8180 ing the java sources and also to the dependencies of the
8181 target. INCLUDE_JARS also accepts other target names cre‐
8182 ated by add_jar(). For backwards compatibility, jar files
8183 listed as sources are ignored (as they have been since
8184 the first version of this module).
8185 ENTRY_POINT
8187 Defines an entry point in the jar file.
8188 VERSION
8190 Adds a version to the target output name.
8191 The following example will create a jar file with the
8193 name shibboleet-1.2.0.jar and will create a symlink shib‐
8194 boleet.jar pointing to the jar with the version informa‐
8195 tion.
8196 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
8198 MANIFEST
8200 Defines a custom manifest for the jar.
8201 OUTPUT_NAME
8203 Specify a different output name for the target.
8204 OUTPUT_DIR
8206 Sets the directory where the jar file will be generated.
8207 If not specified, CMAKE_CURRENT_BINARY_DIR is used as the
8208 output directory.
8209 GENERATE_NATIVE_HEADERS
8211 New in version 3.11.
8212 Generates native header files for methods declared as na‐
8215 tive. These files provide the connective glue that allow
8216 your Java and C code to interact. An INTERFACE target
8217 will be created for an easy usage of generated files.
8218 Sub-option DESTINATION can be used to specify the output
8219 directory for generated header files.
8220 This option requires, at least, version 1.8 of the JDK.
8222 For an optimum usage of this option, it is recommended to
8224 include module JNI before any call to add_jar(). The pro‐
8225 duced target for native headers can then be used to com‐
8226 pile C/C++ sources with the target_link_libraries() com‐
8227 mand.
8228 find_package(JNI)
8230 add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native)
8231 add_library(bar bar.cpp)
8232 target_link_libraries(bar PRIVATE foo-native)
8233 New in version 3.20: DESTINATION sub-option now supports
8235 the possibility to specify different output directories
8236 for BUILD and INSTALL steps. If BUILD directory is not
8237 specified, a default directory will be used.
8238 To export the interface target generated by GENERATE_NA‐
8240 TIVE_HEADERS option, sub-option INSTALL of DESTINATION is
8241 required:
8242 add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native
8244 DESTINATION INSTALL include)
8245 install(TARGETS foo-native EXPORT native)
8246 install(DIRECTORY "$<TARGET_PROPERTY:foo-native,NATIVE_HEADERS_DIRECTORY>/"
8247 DESTINATION include)
8248 install(EXPORT native DESTINATION /to/export NAMESPACE foo)
8249 Some variables can be set to customize the behavior of add_jar()
8252 as well as the java compiler:
8253 CMAKE_JAVA_COMPILE_FLAGS
8255 Specify additional flags to java compiler.
8256 CMAKE_JAVA_INCLUDE_PATH
8258 Specify additional paths to the class path.
8259 CMAKE_JNI_TARGET
8261 If the target is a JNI library, sets this boolean vari‐
8262 able to TRUE to enable creation of a JNI symbolic link
8263 (see also install_jni_symlink()).
8264 CMAKE_JAR_CLASSES_PREFIX
8266 If multiple jars should be produced from the same java
8267 source filetree, to prevent the accumulation of duplicate
8268 class files in subsequent jars, set/reset
8269 CMAKE_JAR_CLASSES_PREFIX prior to calling the add_jar():
8270 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
8272 add_jar(foo foo.java)
8273 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
8275 add_jar(bar bar.java)
8276 The add_jar() function sets the following target properties on
8278 <target_name>:
8279 INSTALL_FILES
8281 The files which should be installed. This is used by
8282 install_jar().
8283 JNI_SYMLINK
8285 The JNI symlink which should be installed. This is used
8286 by install_jni_symlink().
8287 JAR_FILE
8289 The location of the jar file so that you can include it.
8290 CLASSDIR
8292 The directory where the class files can be found. For
8293 example to use them with javah.
8294 NATIVE_HEADERS_DIRECTORY
8296 New in version 3.20.
8297 The directory where native headers are generated. Defined
8300 when option GENERATE_NATIVE_HEADERS is specified.
8301 install_jar
8303 This command installs the jar file to the given destination:
8304 install_jar(<target_name> <destination>)
8306 install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>])
8307 This command installs the <target_name> file to the given <des‐
8309 tination>. It should be called in the same scope as add_jar()
8310 or it will fail.
8311 New in version 3.4: The second signature with DESTINATION and
8313 COMPONENT options.
8314 DESTINATION
8317 Specify the directory on disk to which a file will be in‐
8318 stalled.
8319 COMPONENT
8321 Specify an installation component name with which the in‐
8322 stall rule is associated, such as "runtime" or "develop‐
8323 ment".
8324 The install_jar() command sets the following target properties
8326 on <target_name>:
8327 INSTALL_DESTINATION
8329 Holds the <destination> as described above, and is used
8330 by install_jar_exports().
8331 install_jni_symlink
8333 Installs JNI symlinks for target generated by add_jar():
8334 install_jni_symlink(<target_name> <destination>)
8336 install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>])
8337 This command installs the <target_name> JNI symlinks to the
8339 given <destination>. It should be called in the same scope as
8340 add_jar() or it will fail.
8341 New in version 3.4: The second signature with DESTINATION and
8343 COMPONENT options.
8344 DESTINATION
8347 Specify the directory on disk to which a file will be in‐
8348 stalled.
8349 COMPONENT
8351 Specify an installation component name with which the in‐
8352 stall rule is associated, such as "runtime" or "develop‐
8353 ment".
8354 Utilize the following commands to create a JNI symbolic link:
8356 set(CMAKE_JNI_TARGET TRUE)
8358 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
8359 install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
8360 install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})
8361 Header Generation
8363 create_javah
8364 New in version 3.4.
8365 Generates C header files for java classes:
8368 create_javah(TARGET <target> | GENERATED_FILES <VAR>
8370 CLASSES <class>...
8371 [CLASSPATH <classpath>...]
8372 [DEPENDS <depend>...]
8373 [OUTPUT_NAME <path>|OUTPUT_DIR <path>]
8374 )
8375 Deprecated since version 3.11: This command will no longer be
8377 supported starting with version 10 of the JDK due to the
8378 suppression of javah tool. The add_jar(GENERATE_NATIVE_HEADERS)
8379 command should be used instead.
8380 Create C header files from java classes. These files provide the
8383 connective glue that allow your Java and C code to interact.
8384 There are two main signatures for create_javah(). The first
8386 signature returns generated files through variable specified by
8387 the GENERATED_FILES option. For example:
8388 create_javah(GENERATED_FILES files_headers
8390 CLASSES org.cmake.HelloWorld
8391 CLASSPATH hello.jar
8392 )
8393 The second signature for create_javah() creates a target which
8395 encapsulates header files generation. E.g.
8396 create_javah(TARGET target_headers
8398 CLASSES org.cmake.HelloWorld
8399 CLASSPATH hello.jar
8400 )
8401 Both signatures share same options.
8403 CLASSES
8405 Specifies Java classes used to generate headers.
8406 CLASSPATH
8408 Specifies various paths to look up classes. Here .class
8409 files, jar files or targets created by command add_jar
8410 can be used.
8411 DEPENDS
8413 Targets on which the javah target depends.
8414 OUTPUT_NAME
8416 Concatenates the resulting header files for all the
8417 classes listed by option CLASSES into <path>. Same be‐
8418 havior as option -o of javah tool.
8419 OUTPUT_DIR
8421 Sets the directory where the header files will be gener‐
8422 ated. Same behavior as option -d of javah tool. If not
8423 specified, CMAKE_CURRENT_BINARY_DIR is used as the output
8424 directory.
8425 Exporting JAR Targets
8427 install_jar_exports
8428 New in version 3.7.
8429 Installs a target export file:
8432 install_jar_exports(TARGETS <jars>...
8434 [NAMESPACE <namespace>]
8435 FILE <filename>
8436 DESTINATION <destination> [COMPONENT <component>])
8437 This command installs a target export file <filename> for the
8439 named jar targets to the given <destination> directory. Its
8440 function is similar to that of install(EXPORT).
8441 TARGETS
8443 List of targets created by add_jar() command.
8444 NAMESPACE
8446 New in version 3.9.
8447 The <namespace> value will be prepend to the target names
8450 as they are written to the import file.
8451 FILE Specify name of the export file.
8453 DESTINATION
8455 Specify the directory on disk to which a file will be in‐
8456 stalled.
8457 COMPONENT
8459 Specify an installation component name with which the in‐
8460 stall rule is associated, such as "runtime" or "develop‐
8461 ment".
8462 export_jars
8464 New in version 3.7.
8465 Writes a target export file:
8468 export_jars(TARGETS <jars>...
8470 [NAMESPACE <namespace>]
8471 FILE <filename>)
8472 This command writes a target export file <filename> for the
8474 named <jars> targets. Its function is similar to that of ex‐
8475 port().
8476 TARGETS
8478 List of targets created by add_jar() command.
8479 NAMESPACE
8481 New in version 3.9.
8482 The <namespace> value will be prepend to the target names
8485 as they are written to the import file.
8486 FILE Specify name of the export file.
8488 Finding JARs
8490 find_jar
8491 Finds the specified jar file:
8492 find_jar(<VAR>
8494 <name> | NAMES <name1> [<name2>...]
8495 [PATHS <path1> [<path2>... ENV <var>]]
8496 [VERSIONS <version1> [<version2>]]
8497 [DOC "cache documentation string"]
8498 )
8499 This command is used to find a full path to the named jar. A
8501 cache entry named by <VAR> is created to store the result of
8502 this command. If the full path to a jar is found the result is
8503 stored in the variable and the search will not repeated unless
8504 the variable is cleared. If nothing is found, the result will
8505 be <VAR>-NOTFOUND, and the search will be attempted again next
8506 time find_jar() is invoked with the same variable.
8507 NAMES Specify one or more possible names for the jar file.
8509 PATHS Specify directories to search in addition to the default
8511 locations. The ENV var sub-option reads paths from a
8512 system environment variable.
8513 VERSIONS
8515 Specify jar versions.
8516 DOC Specify the documentation string for the <VAR> cache en‐
8518 try.
8519 Creating Java Documentation
8521 create_javadoc
8522 Creates java documentation based on files and packages:
8523 create_javadoc(<VAR>
8525 (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...])
8526 [SOURCEPATH <sourcepath>]
8527 [CLASSPATH <classpath>]
8528 [INSTALLPATH <install path>]
8529 [DOCTITLE <the documentation title>]
8530 [WINDOWTITLE <the title of the document>]
8531 [AUTHOR (TRUE|FALSE)]
8532 [USE (TRUE|FALSE)]
8533 [VERSION (TRUE|FALSE)]
8534 )
8535 The create_javadoc() command can be used to create java documen‐
8537 tation. There are two main signatures for create_javadoc().
8538 The first signature works with package names on a path with
8540 source files:
8541 create_javadoc(my_example_doc
8543 PACKAGES com.example.foo com.example.bar
8544 SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
8545 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
8546 WINDOWTITLE "My example"
8547 DOCTITLE "<h1>My example</h1>"
8548 AUTHOR TRUE
8549 USE TRUE
8550 VERSION TRUE
8551 )
8552 The second signature for create_javadoc() works on a given list
8554 of files:
8555 create_javadoc(my_example_doc
8557 FILES java/A.java java/B.java
8558 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
8559 WINDOWTITLE "My example"
8560 DOCTITLE "<h1>My example</h1>"
8561 AUTHOR TRUE
8562 USE TRUE
8563 VERSION TRUE
8564 )
8565 Both signatures share most of the options. For more details
8567 please read the javadoc manpage.
8568 PACKAGES
8570 Specify java packages.
8571 FILES Specify java source files. If relative paths are speci‐
8573 fied, they are relative to CMAKE_CURRENT_SOURCE_DIR.
8574 SOURCEPATH
8576 Specify the directory where to look for packages. By de‐
8577 fault, CMAKE_CURRENT_SOURCE_DIR directory is used.
8578 CLASSPATH
8580 Specify where to find user class files. Same behavior as
8581 option -classpath of javadoc tool.
8582 INSTALLPATH
8584 Specify where to install the java documentation. If you
8585 specified, the documentation will be installed to
8586 ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>.
8587 DOCTITLE
8589 Specify the title to place near the top of the overview
8590 summary file. Same behavior as option -doctitle of
8591 javadoc tool.
8592 WINDOWTITLE
8594 Specify the title to be placed in the HTML <title> tag.
8595 Same behavior as option -windowtitle of javadoc tool.
8596 AUTHOR When value TRUE is specified, includes the @author text
8598 in the generated docs. Same behavior as option -author
8599 of javadoc tool.
8600 USE When value TRUE is specified, creates class and package
8602 usage pages. Includes one Use page for each documented
8603 class and package. Same behavior as option -use of
8604 javadoc tool.
8605 VERSION
8607 When value TRUE is specified, includes the version text
8608 in the generated docs. Same behavior as option -version
8609 of javadoc tool.
8610 UseSWIG
8612 This file provides support for SWIG. It is assumed that FindSWIG module
8613 has already been loaded.
8614 Defines the following command for use with SWIG:
8616 swig_add_library
8618 New in version 3.8.
8619 Define swig module with given name and specified language:
8622 swig_add_library(<name>
8624 [TYPE <SHARED|MODULE|STATIC|USE_BUILD_SHARED_LIBS>]
8625 LANGUAGE <language>
8626 [NO_PROXY]
8627 [OUTPUT_DIR <directory>]
8628 [OUTFILE_DIR <directory>]
8629 SOURCES <file>...
8630 )
8631 Targets created with the swig_add_library command have the same
8633 capabilities as targets created with the add_library() command,
8634 so those targets can be used with any command expecting a target
8635 (e.g. target_link_libraries()).
8636 Changed in version 3.13: This command creates a target with the
8638 specified <name> when policy CMP0078 is set to NEW. Otherwise,
8639 the legacy behavior will choose a different target name and
8640 store it in the SWIG_MODULE_<name>_REAL_NAME variable.
8641 Changed in version 3.15: Alternate library name (set with the
8644 OUTPUT_NAME property, for example) will be passed on to Python
8645 and CSharp wrapper libraries.
8646 Changed in version 3.21: Generated library use standard naming
8649 conventions for CSharp language when policy CMP0122 is set to
8650 NEW. Otherwise, the legacy behavior is applied.
8651 NOTE:
8654 For multi-config generators, this module does not support
8655 configuration-specific files generated by SWIG. All build
8656 configurations must result in the same generated source file.
8657 NOTE:
8659 For Makefile Generators, if, for some sources, the
8660 USE_SWIG_DEPENDENCIES property is FALSE, swig_add_library
8661 does not track file dependencies, so depending on the
8662 <name>_swig_compilation custom target is required for targets
8663 which require the swig-generated files to exist. Other gener‐
8664 ators may depend on the source files that would be generated
8665 by SWIG.
8666 TYPE SHARED, MODULE and STATIC have the same semantic as for
8668 the add_library() command. If USE_BUILD_SHARED_LIBS is
8669 specified, the library type will be STATIC or SHARED
8670 based on whether the current value of the
8671 BUILD_SHARED_LIBS variable is ON. If no type is speci‐
8672 fied, MODULE will be used.
8673 LANGUAGE
8675 Specify the target language.
8676 New in version 3.1: Go and Lua language support.
8678 New in version 3.2: R language support.
8681 New in version 3.18: Fortran language support.
8684 NO_PROXY
8687 New in version 3.12.
8688 Prevent the generation of the wrapper layer (swig -no‐
8691 proxy option).
8692 OUTPUT_DIR
8694 New in version 3.12.
8695 Specify where to write the language specific files (swig
8698 -outdir option). If not given, the CMAKE_SWIG_OUTDIR
8699 variable will be used. If neither is specified, the de‐
8700 fault depends on the value of the UseSWIG_MODULE_VERSION
8701 variable as follows:
8702 • If UseSWIG_MODULE_VERSION is 1 or is undefined, output
8704 is written to the CMAKE_CURRENT_BINARY_DIR directory.
8705 • If UseSWIG_MODULE_VERSION is 2, a dedicated directory
8707 will be used. The path of this directory can be re‐
8708 trieved from the SWIG_SUPPORT_FILES_DIRECTORY target
8709 property.
8710 OUTFILE_DIR
8712 New in version 3.12.
8713 Specify an output directory name where the generated
8716 source file will be placed (swig -o option). If not spec‐
8717 ified, the SWIG_OUTFILE_DIR variable will be used. If
8718 neither is specified, OUTPUT_DIR or CMAKE_SWIG_OUTDIR is
8719 used instead.
8720 SOURCES
8722 List of sources for the library. Files with extension .i
8723 will be identified as sources for the SWIG tool. Other
8724 files will be handled in the standard way.
8725 New in version 3.14: This behavior can be overridden by
8727 specifying the variable SWIG_SOURCE_FILE_EXTENSIONS.
8728 NOTE:
8731 If UseSWIG_MODULE_VERSION is set to 2, it is strongly recom‐
8732 mended to use a dedicated directory unique to the target when
8733 either the OUTPUT_DIR option or the CMAKE_SWIG_OUTDIR vari‐
8734 able are specified. The output directory contents are erased
8735 as part of the target build, so to prevent interference be‐
8736 tween targets or losing other important files, each target
8737 should have its own dedicated output directory.
8738 swig_link_libraries
8740 Link libraries to swig module:
8741 swig_link_libraries(<name> <item>...)
8743 This command has same capabilities as target_link_libraries()
8745 command.
8746 NOTE:
8748 If variable UseSWIG_TARGET_NAME_PREFERENCE is set to STAN‐
8749 DARD, this command is deprecated and target_link_libraries()
8750 command must be used instead.
8751 Source file properties on module files must be set before the invoca‐
8753 tion of the swig_add_library command to specify special behavior of
8754 SWIG and ensure generated files will receive the required settings.
8755 CPLUSPLUS
8757 Call SWIG in c++ mode. For example:
8758 set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON)
8760 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
8761 SWIG_FLAGS
8763 Deprecated since version 3.12: Replaced with the fine-grained
8764 properties that follow.
8765 Pass custom flags to the SWIG executable.
8768 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS
8770 New in version 3.12.
8771 Add custom flags to SWIG compiler and have same semantic as
8774 properties INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COM‐
8775 PILE_OPTIONS.
8776 USE_TARGET_INCLUDE_DIRECTORIES
8778 New in version 3.13.
8779 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
8782 will be forwarded to SWIG compiler. If set to FALSE target
8783 property INCLUDE_DIRECTORIES will be ignored. If not set, target
8784 property SWIG_USE_TARGET_INCLUDE_DIRECTORIES will be considered.
8785 GENERATED_INCLUDE_DIRECTORIES, GENERATED_COMPILE_DEFINITIONS and GENER‐
8787 ATED_COMPILE_OPTIONS
8788 New in version 3.12.
8789 Add custom flags to the C/C++ generated source. They will fill,
8792 respectively, properties INCLUDE_DIRECTORIES, COMPILE_DEFINI‐
8793 TIONS and COMPILE_OPTIONS of generated C/C++ file.
8794 DEPENDS
8796 New in version 3.12.
8797 Specify additional dependencies to the source file.
8800 USE_SWIG_DEPENDENCIES
8802 New in version 3.20.
8803 If set to TRUE, implicit dependencies are generated by the swig
8806 tool itself. This property is only meaningful for Makefile,
8807 Ninja, Xcode, and Visual Studio (Visual Studio 11 2012 and
8808 above) generators. Default value is FALSE.
8809 New in version 3.21: Added the support of Xcode generator.
8811 New in version 3.22: Added the support of Visual Studio Genera‐
8814 tors.
8815 SWIG_MODULE_NAME
8818 Specify the actual import name of the module in the target lan‐
8819 guage. This is required if it cannot be scanned automatically
8820 from source or different from the module file basename. For ex‐
8821 ample:
8822 set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)
8824 Changed in version 3.14: If policy CMP0086 is set to NEW, -mod‐
8826 ule <module_name> is passed to SWIG compiler.
8827 OUTPUT_DIR
8830 New in version 3.19.
8831 Specify where to write the language specific files (swig -outdir
8834 option) for the considered source file. If not specified, the
8835 other ways to define the output directory applies (see OUT‐
8836 PUT_DIR option of swig_add_library() command).
8837 OUTFILE_DIR
8839 New in version 3.19.
8840 Specify an output directory where the generated source file will
8843 be placed (swig -o option) for the considered source file. If
8844 not specified, OUTPUT_DIR source property will be used. If nei‐
8845 ther are specified, the other ways to define output file direc‐
8846 tory applies (see OUTFILE_DIR option of swig_add_library() com‐
8847 mand).
8848 Target library properties can be set to apply same configuration to all
8850 SWIG input files.
8851 SWIG_INCLUDE_DIRECTORIES, SWIG_COMPILE_DEFINITIONS and SWIG_COMPILE_OP‐
8853 TIONS
8854 New in version 3.12.
8855 These properties will be applied to all SWIG input files and
8858 have same semantic as target properties INCLUDE_DIRECTORIES,
8859 COMPILE_DEFINITIONS and COMPILE_OPTIONS.
8860 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
8862 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
8863 set_property(TARGET mymod PROPERTY SWIG_COMPILE_DEFINITIONS MY_DEF1 MY_DEF2)
8864 set_property(TARGET mymod PROPERTY SWIG_COMPILE_OPTIONS -bla -blb)
8865 SWIG_USE_TARGET_INCLUDE_DIRECTORIES
8867 New in version 3.13.
8868 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
8871 will be forwarded to SWIG compiler. If set to FALSE or not de‐
8872 fined, target property INCLUDE_DIRECTORIES will be ignored. This
8873 behavior can be overridden by specifying source property
8874 USE_TARGET_INCLUDE_DIRECTORIES.
8875 SWIG_GENERATED_INCLUDE_DIRECTORIES, SWIG_GENERATED_COMPILE_DEFINITIONS
8877 and SWIG_GENERATED_COMPILE_OPTIONS
8878 New in version 3.12.
8879 These properties will populate, respectively, properties IN‐
8882 CLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_FLAGS of all
8883 generated C/C++ files.
8884 SWIG_DEPENDS
8886 New in version 3.12.
8887 Add dependencies to all SWIG input files.
8890 The following target properties are output properties and can be used
8892 to get information about support files generated by SWIG interface com‐
8893 pilation.
8894 SWIG_SUPPORT_FILES
8896 New in version 3.12.
8897 This output property list of wrapper files generated during SWIG
8900 compilation.
8901 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
8903 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
8904 get_property(support_files TARGET mymod PROPERTY SWIG_SUPPORT_FILES)
8905 NOTE:
8907 Only most principal support files are listed. In case some
8908 advanced features of SWIG are used (for example %template),
8909 associated support files may not be listed. Prefer to use the
8910 SWIG_SUPPORT_FILES_DIRECTORY property to handle support
8911 files.
8912 SWIG_SUPPORT_FILES_DIRECTORY
8914 New in version 3.12.
8915 This output property specifies the directory where support files
8918 will be generated.
8919 NOTE:
8921 When source property OUTPUT_DIR is defined, multiple directo‐
8922 ries can be specified as part of SWIG_SUPPORT_FILES_DIREC‐
8923 TORY.
8924 Some variables can be set to customize the behavior of swig_add_library
8926 as well as SWIG:
8927 UseSWIG_MODULE_VERSION
8929 New in version 3.12.
8930 Specify different behaviors for UseSWIG module.
8933 • Set to 1 or undefined: Legacy behavior is applied.
8935 • Set to 2: A new strategy is applied regarding support files:
8937 the output directory of support files is erased before SWIG
8938 interface compilation.
8939 CMAKE_SWIG_FLAGS
8941 Add flags to all swig calls.
8942 CMAKE_SWIG_OUTDIR
8944 Specify where to write the language specific files (swig -outdir
8945 option).
8946 SWIG_OUTFILE_DIR
8948 New in version 3.8.
8949 Specify an output directory name where the generated source file
8952 will be placed. If not specified, CMAKE_SWIG_OUTDIR is used.
8953 SWIG_MODULE_<name>_EXTRA_DEPS
8955 Specify extra dependencies for the generated module for <name>.
8956 SWIG_SOURCE_FILE_EXTENSIONS
8958 New in version 3.14.
8959 Specify a list of source file extensions to override the default
8962 behavior of considering only .i files as sources for the SWIG
8963 tool. For example:
8964 set(SWIG_SOURCE_FILE_EXTENSIONS ".i" ".swg")
8966 SWIG_USE_SWIG_DEPENDENCIES
8968 New in version 3.20.
8969 If set to TRUE, implicit dependencies are generated by the swig
8972 tool itself. This variable is only meaningful for Makefile,
8973 Ninja, Xcode, and Visual Studio (Visual Studio 11 2012 and
8974 above) generators. Default value is FALSE.
8975 Source file property USE_SWIG_DEPENDENCIES, if not defined, will
8977 be initialized with the value of this variable.
8978 New in version 3.21: Added the support of Xcode generator.
8980 New in version 3.22: Added the support of Visual Studio Genera‐
8983 tors.
8984 UsewxWidgets
8987 Convenience include for using wxWidgets library.
8988 Determines if wxWidgets was FOUND and sets the appropriate libs, in‐
8990 cdirs, flags, etc. INCLUDE_DIRECTORIES and LINK_DIRECTORIES are
8991 called.
8992 USAGE
8994 # Note that for MinGW users the order of libs is important!
8996 find_package(wxWidgets REQUIRED net gl core base)
8997 include(${wxWidgets_USE_FILE})
8998 # and for each of your dependent executable/library targets:
8999 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
9000 DEPRECATED
9002 LINK_LIBRARIES is not called in favor of adding dependencies per target.
9004 AUTHOR
9006 Jan Woetzel <jw -at- mip.informatik.uni-kiel.de>
9008
9010 These modules search for third-party software. They are normally
9011 called through the find_package() command.
9012 FindALSA
9014 Find Advanced Linux Sound Architecture (ALSA)
9015 Find the alsa libraries (asound)
9017 IMPORTED Targets
9019 New in version 3.12.
9020 This module defines IMPORTED target ALSA::ALSA, if ALSA has been found.
9023 Result Variables
9025 This module defines the following variables:
9026 ALSA_FOUND
9028 True if ALSA_INCLUDE_DIR & ALSA_LIBRARY are found
9029 ALSA_LIBRARIES
9031 List of libraries when using ALSA.
9032 ALSA_INCLUDE_DIRS
9034 Where to find the ALSA headers.
9035 Cache variables
9037 The following cache variables may also be set:
9038 ALSA_INCLUDE_DIR
9040 the ALSA include directory
9041 ALSA_LIBRARY
9043 the absolute path of the asound library
9044 FindArmadillo
9046 Find the Armadillo C++ library. Armadillo is a library for linear al‐
9047 gebra & scientific computing.
9048 New in version 3.18: Support for linking wrapped libraries directly
9050 (ARMA_DONT_USE_WRAPPER).
9051 Using Armadillo:
9054 find_package(Armadillo REQUIRED)
9056 include_directories(${ARMADILLO_INCLUDE_DIRS})
9057 add_executable(foo foo.cc)
9058 target_link_libraries(foo ${ARMADILLO_LIBRARIES})
9059 This module sets the following variables:
9061 ARMADILLO_FOUND - set to true if the library is found
9063 ARMADILLO_INCLUDE_DIRS - list of required include directories
9064 ARMADILLO_LIBRARIES - list of libraries to be linked
9065 ARMADILLO_VERSION_MAJOR - major version number
9066 ARMADILLO_VERSION_MINOR - minor version number
9067 ARMADILLO_VERSION_PATCH - patch version number
9068 ARMADILLO_VERSION_STRING - version number as a string (ex: "1.0.4")
9069 ARMADILLO_VERSION_NAME - name of the version (ex: "Antipodean Antileech")
9070 FindASPELL
9072 Try to find ASPELL
9073 Once done this will define
9075 ASPELL_FOUND - system has ASPELL
9077 ASPELL_EXECUTABLE - the ASPELL executable
9078 ASPELL_INCLUDE_DIR - the ASPELL include directory
9079 ASPELL_LIBRARIES - The libraries needed to use ASPELL
9080 ASPELL_DEFINITIONS - Compiler switches required for using ASPELL
9081 FindAVIFile
9083 Locate AVIFILE library and include paths
9084 AVIFILE (http://avifile.sourceforge.net/) is a set of libraries for
9086 i386 machines to use various AVI codecs. Support is limited beyond
9087 Linux. Windows provides native AVI support, and so doesn't need this
9088 library. This module defines
9089 AVIFILE_INCLUDE_DIR, where to find avifile.h , etc.
9091 AVIFILE_LIBRARIES, the libraries to link against
9092 AVIFILE_DEFINITIONS, definitions to use when compiling
9093 AVIFILE_FOUND, If false, don't try to use AVIFILE
9094 FindBacktrace
9096 Find provider for backtrace(3).
9097 Checks if OS supports backtrace(3) via either libc or custom library.
9099 This module defines the following variables:
9100 Backtrace_HEADER
9102 The header file needed for backtrace(3). Cached. Could be
9103 forcibly set by user.
9104 Backtrace_INCLUDE_DIRS
9106 The include directories needed to use backtrace(3) header.
9107 Backtrace_LIBRARIES
9109 The libraries (linker flags) needed to use backtrace(3), if any.
9110 Backtrace_FOUND
9112 Is set if and only if backtrace(3) support detected.
9113 The following cache variables are also available to set or use:
9115 Backtrace_LIBRARY
9117 The external library providing backtrace, if any.
9118 Backtrace_INCLUDE_DIR
9120 The directory holding the backtrace(3) header.
9121 Typical usage is to generate of header file using configure_file() with
9123 the contents like the following:
9124 #cmakedefine01 Backtrace_FOUND
9126 #if Backtrace_FOUND
9127 # include <${Backtrace_HEADER}>
9128 #endif
9129 And then reference that generated header file in actual source.
9131 FindBISON
9133 Find bison executable and provide a macro to generate custom build
9134 rules.
9135 The module defines the following variables:
9137 BISON_EXECUTABLE
9139 path to the bison program
9140 BISON_VERSION
9142 version of bison
9143 BISON_FOUND
9145 "True" if the program was found
9146 The minimum required version of bison can be specified using the stan‐
9148 dard CMake syntax, e.g. find_package(BISON 2.1.3).
9149 If bison is found, the module defines the macro:
9151 BISON_TARGET(<Name> <YaccInput> <CodeOutput>
9153 [COMPILE_FLAGS <flags>]
9154 [DEFINES_FILE <file>]
9155 [VERBOSE [<file>]]
9156 [REPORT_FILE <file>]
9157 )
9158 which will create a custom rule to generate a parser. <YaccInput> is
9160 the path to a yacc file. <CodeOutput> is the name of the source file
9161 generated by bison. A header file is also be generated, and contains
9162 the token list.
9163 Changed in version 3.14: When CMP0088 is set to NEW, bison runs in the
9165 CMAKE_CURRENT_BINARY_DIR directory.
9166 The options are:
9169 COMPILE_FLAGS <flags>
9171 Specify flags to be added to the bison command line.
9172 DEFINES_FILE <file>
9174 New in version 3.4.
9175 Specify a non-default header <file> to be generated by bison.
9178 VERBOSE [<file>]
9180 Tell bison to write a report file of the grammar and parser.
9181 Deprecated since version 3.7: If <file> is given, it specifies
9183 path the report file is copied to. [<file>] is left for back‐
9184 ward compatibility of this module. Use VERBOSE REPORT_FILE
9185 <file>.
9186 REPORT_FILE <file>
9189 New in version 3.7.
9190 Specify a non-default report <file>, if generated.
9193 The macro defines the following variables:
9195 BISON_<Name>_DEFINED
9197 True is the macro ran successfully
9198 BISON_<Name>_INPUT
9200 The input source file, an alias for <YaccInput>
9201 BISON_<Name>_OUTPUT_SOURCE
9203 The source file generated by bison
9204 BISON_<Name>_OUTPUT_HEADER
9206 The header file generated by bison
9207 BISON_<Name>_OUTPUTS
9209 All files generated by bison including the source, the header
9210 and the report
9211 BISON_<Name>_COMPILE_FLAGS
9213 Options used in the bison command line
9214 Example usage:
9216 find_package(BISON)
9218 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp
9219 DEFINES_FILE ${CMAKE_CURRENT_BINARY_DIR}/parser.h)
9220 add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
9221 FindBLAS
9223 Find Basic Linear Algebra Subprograms (BLAS) library
9224 This module finds an installed Fortran library that implements the BLAS
9226 linear-algebra interface.
9227 At least one of the C, CXX, or Fortran languages must be enabled.
9229 Input Variables
9231 The following variables may be set to influence this module's behavior:
9232 BLA_STATIC
9234 if ON use static linkage
9235 BLA_VENDOR
9237 Set to one of the BLAS/LAPACK Vendors to search for BLAS only
9238 from the specified vendor. If not set, all vendors are consid‐
9239 ered.
9240 BLA_F95
9242 if ON tries to find the BLAS95 interfaces
9243 BLA_PREFER_PKGCONFIG
9245 New in version 3.11.
9246 if set pkg-config will be used to search for a BLAS library
9249 first and if one is found that is preferred
9250 BLA_SIZEOF_INTEGER
9252 New in version 3.22.
9253 Specify the BLAS/LAPACK library integer size:
9256 4 Search for a BLAS/LAPACK with 32-bit integer interfaces.
9258 8 Search for a BLAS/LAPACK with 64-bit integer interfaces.
9260 ANY Search for any BLAS/LAPACK. Most likely, a BLAS/LAPACK
9262 with 32-bit integer interfaces will be found.
9263 Imported targets
9265 This module defines the following IMPORTED targets:
9266 BLAS::BLAS
9268 New in version 3.18.
9269 The libraries to use for BLAS, if found.
9272 Result Variables
9274 This module defines the following variables:
9275 BLAS_FOUND
9277 library implementing the BLAS interface is found
9278 BLAS_LINKER_FLAGS
9280 uncached list of required linker flags (excluding -l and -L).
9281 BLAS_LIBRARIES
9283 uncached list of libraries (using full path name) to link
9284 against to use BLAS (may be empty if compiler implicitly links
9285 BLAS)
9286 BLAS95_LIBRARIES
9288 uncached list of libraries (using full path name) to link
9289 against to use BLAS95 interface
9290 BLAS95_FOUND
9292 library implementing the BLAS95 interface is found
9293 BLAS/LAPACK Vendors
9295 Generic
9296 Generic reference implementation
9297 ACML, ACML_MP, ACML_GPU
9299 AMD Core Math Library
9300 Apple, NAS
9302 Apple BLAS (Accelerate), and Apple NAS (vecLib)
9303 Arm, Arm_mp, Arm_ilp64, Arm_ilp64_mp
9305 New in version 3.18.
9306 Arm Performance Libraries
9309 ATLAS Automatically Tuned Linear Algebra Software
9311 CXML, DXML
9313 Compaq/Digital Extended Math Library
9314 EML, EML_mt
9316 New in version 3.20.
9317 Elbrus Math Library
9320 FLAME New in version 3.11.
9322 BLIS Framework
9325 FlexiBLAS
9327 New in version 3.19.
9328 Fujitsu_SSL2, Fujitsu_SSL2BLAMP, Fujitsu_SSL2SVE, Fujitsu_SSL2BLAMPSVE
9331 New in version 3.20.
9332 Fujitsu SSL2 serial and parallel blas/lapack with SVE instruc‐
9335 tions
9336 Goto GotoBLAS
9338 IBMESSL, IBMESSL_SMP
9340 IBM Engineering and Scientific Subroutine Library
9341 Intel Intel MKL 32 bit and 64 bit obsolete versions
9343 Intel10_32
9345 Intel MKL v10 32 bit, threaded code
9346 Intel10_64lp
9348 Intel MKL v10+ 64 bit, threaded code, lp64 model
9349 Intel10_64lp_seq
9351 Intel MKL v10+ 64 bit, sequential code, lp64 model
9352 Intel10_64ilp
9354 New in version 3.13.
9355 Intel MKL v10+ 64 bit, threaded code, ilp64 model
9358 Intel10_64ilp_seq
9360 New in version 3.13.
9361 Intel MKL v10+ 64 bit, sequential code, ilp64 model
9364 Intel10_64_dyn
9366 New in version 3.17.
9367 Intel MKL v10+ 64 bit, single dynamic library
9370 NVHPC New in version 3.21.
9372 NVIDIA HPC SDK
9375 OpenBLAS
9377 New in version 3.6.
9378 PhiPACK
9381 Portable High Performance ANSI C (PHiPAC)
9382 SCSL, SCSL_mp
9384 Scientific Computing Software Library
9385 SGIMATH
9387 SGI Scientific Mathematical Library
9388 SunPerf
9390 Sun Performance Library
9391 Intel MKL
9393 To use the Intel MKL implementation of BLAS, a project must enable at
9394 least one of the C or CXX languages. Set BLA_VENDOR to an Intel MKL
9395 variant either on the command-line as -DBLA_VENDOR=Intel10_64lp or in
9396 project code:
9397 set(BLA_VENDOR Intel10_64lp)
9399 find_package(BLAS)
9400 In order to build a project using Intel MKL, and end user must first
9402 establish an Intel MKL environment:
9403 Intel oneAPI
9405 Source the full Intel environment script:
9406 . /opt/intel/oneapi/setvars.sh
9408 Or, source the MKL component environment script:
9410 . /opt/intel/oneapi/mkl/latest/env/vars.sh
9412 Intel Classic
9414 Source the full Intel environment script:
9415 . /opt/intel/bin/compilervars.sh intel64
9417 Or, source the MKL component environment script:
9419 . /opt/intel/mkl/bin/mklvars.sh intel64
9421 The above environment scripts set the MKLROOT environment variable to
9423 the top of the MKL installation. They also add the location of the
9424 runtime libraries to the dynamic library loader environment variable
9425 for your platform (e.g. LD_LIBRARY_PATH). This is necessary for pro‐
9426 grams linked against MKL to run.
9427 NOTE:
9429 As of Intel oneAPI 2021.2, loading only the MKL component does not
9430 make all of its dependencies available. In particular, the iomp5
9431 library must be available separately, or provided by also loading
9432 the compiler component environment:
9433 . /opt/intel/oneapi/compiler/latest/env/vars.sh
9435 FindBoost
9437 Find Boost include dirs and libraries
9438 Use this module by invoking find_package() with the form:
9440 find_package(Boost
9442 [version] [EXACT] # Minimum or EXACT version e.g. 1.67.0
9443 [REQUIRED] # Fail with error if Boost is not found
9444 [COMPONENTS <libs>...] # Boost libraries by their canonical name
9445 # e.g. "date_time" for "libboost_date_time"
9446 [OPTIONAL_COMPONENTS <libs>...]
9447 # Optional Boost libraries by their canonical name)
9448 ) # e.g. "date_time" for "libboost_date_time"
9449 This module finds headers and requested component libraries OR a CMake
9451 package configuration file provided by a "Boost CMake" build. For the
9452 latter case skip to the Boost CMake section below.
9453 New in version 3.7: bzip2 and zlib components (Windows only).
9455 New in version 3.11: The OPTIONAL_COMPONENTS option.
9458 New in version 3.13: stacktrace_* components.
9461 New in version 3.19: bzip2 and zlib components on all platforms.
9464 Result Variables
9467 This module defines the following variables:
9468 Boost_FOUND
9470 True if headers and requested libraries were found.
9471 Boost_INCLUDE_DIRS
9473 Boost include directories.
9474 Boost_LIBRARY_DIRS
9476 Link directories for Boost libraries.
9477 Boost_LIBRARIES
9479 Boost component libraries to be linked.
9480 Boost_<COMPONENT>_FOUND
9482 True if component <COMPONENT> was found (<COMPONENT> name is up‐
9483 per-case).
9484 Boost_<COMPONENT>_LIBRARY
9486 Libraries to link for component <COMPONENT> (may include tar‐
9487 get_link_libraries() debug/optimized keywords).
9488 Boost_VERSION_MACRO
9490 BOOST_VERSION value from boost/version.hpp.
9491 Boost_VERSION_STRING
9493 Boost version number in X.Y.Z format.
9494 Boost_VERSION
9496 Boost version number in X.Y.Z format (same as Boost_VER‐
9497 SION_STRING).
9498 Changed in version 3.15: In previous CMake versions, this vari‐
9500 able used the raw version string from the Boost header (same as
9501 Boost_VERSION_MACRO). See policy CMP0093.
9502 Boost_LIB_VERSION
9505 Version string appended to library filenames.
9506 Boost_VERSION_MAJOR, Boost_MAJOR_VERSION
9508 Boost major version number (X in X.Y.Z).
9509 Boost_VERSION_MINOR, Boost_MINOR_VERSION
9511 Boost minor version number (Y in X.Y.Z).
9512 Boost_VERSION_PATCH, Boost_SUBMINOR_VERSION
9514 Boost subminor version number (Z in X.Y.Z).
9515 Boost_VERSION_COUNT
9517 Amount of version components (3).
9518 Boost_LIB_DIAGNOSTIC_DEFINITIONS (Windows-specific)
9520 Pass to add_definitions() to have diagnostic information about
9521 Boost's automatic linking displayed during compilation
9522 New in version 3.15: The Boost_VERSION_<PART> variables.
9524 Cache variables
9527 Search results are saved persistently in CMake cache entries:
9528 Boost_INCLUDE_DIR
9530 Directory containing Boost headers.
9531 Boost_LIBRARY_DIR_RELEASE
9533 Directory containing release Boost libraries.
9534 Boost_LIBRARY_DIR_DEBUG
9536 Directory containing debug Boost libraries.
9537 Boost_<COMPONENT>_LIBRARY_DEBUG
9539 Component <COMPONENT> library debug variant.
9540 Boost_<COMPONENT>_LIBRARY_RELEASE
9542 Component <COMPONENT> library release variant.
9543 New in version 3.3: Per-configuration variables Boost_LIBRARY_DIR_RE‐
9545 LEASE and Boost_LIBRARY_DIR_DEBUG.
9546 Hints
9549 This module reads hints about search locations from variables:
9550 BOOST_ROOT, BOOSTROOT
9552 Preferred installation prefix.
9553 BOOST_INCLUDEDIR
9555 Preferred include directory e.g. <prefix>/include.
9556 BOOST_LIBRARYDIR
9558 Preferred library directory e.g. <prefix>/lib.
9559 Boost_NO_SYSTEM_PATHS
9561 Set to ON to disable searching in locations not specified by
9562 these hint variables. Default is OFF.
9563 Boost_ADDITIONAL_VERSIONS
9565 List of Boost versions not known to this module. (Boost install
9566 locations may contain the version).
9567 Users may set these hints or results as CACHE entries. Projects should
9569 not read these entries directly but instead use the above result vari‐
9570 ables. Note that some hint names start in upper-case BOOST. One may
9571 specify these as environment variables if they are not specified as
9572 CMake variables or cache entries.
9573 This module first searches for the Boost header files using the above
9575 hint variables (excluding BOOST_LIBRARYDIR) and saves the result in
9576 Boost_INCLUDE_DIR. Then it searches for requested component libraries
9577 using the above hints (excluding BOOST_INCLUDEDIR and Boost_ADDI‐
9578 TIONAL_VERSIONS), "lib" directories near Boost_INCLUDE_DIR, and the li‐
9579 brary name configuration settings below. It saves the library directo‐
9580 ries in Boost_LIBRARY_DIR_DEBUG and Boost_LIBRARY_DIR_RELEASE and indi‐
9581 vidual library locations in Boost_<COMPONENT>_LIBRARY_DEBUG and
9582 Boost_<COMPONENT>_LIBRARY_RELEASE. When one changes settings used by
9583 previous searches in the same build tree (excluding environment vari‐
9584 ables) this module discards previous search results affected by the
9585 changes and searches again.
9586 Imported Targets
9588 New in version 3.5.
9589 This module defines the following IMPORTED targets:
9592 Boost::boost
9594 Target for header-only dependencies. (Boost include directory).
9595 Boost::headers
9597 New in version 3.15: Alias for Boost::boost.
9598 Boost::<component>
9601 Target for specific component dependency (shared or static li‐
9602 brary); <component> name is lower-case.
9603 Boost::diagnostic_definitions
9605 Interface target to enable diagnostic information about Boost's
9606 automatic linking during compilation (adds -DBOOST_LIB_DIAGNOS‐
9607 TIC).
9608 Boost::disable_autolinking
9610 Interface target to disable automatic linking with MSVC (adds
9611 -DBOOST_ALL_NO_LIB).
9612 Boost::dynamic_linking
9614 Interface target to enable dynamic linking with MSVC (adds
9615 -DBOOST_ALL_DYN_LINK).
9616 Implicit dependencies such as Boost::filesystem requiring Boost::system
9618 will be automatically detected and satisfied, even if system is not
9619 specified when using find_package() and if Boost::system is not added
9620 to target_link_libraries(). If using Boost::thread, then
9621 Threads::Threads will also be added automatically.
9622 It is important to note that the imported targets behave differently
9624 than variables created by this module: multiple calls to find_pack‐
9625 age(Boost) in the same directory or sub-directories with different op‐
9626 tions (e.g. static or shared) will not override the values of the tar‐
9627 gets created by the first call.
9628 Other Variables
9630 Boost libraries come in many variants encoded in their file name.
9631 Users or projects may tell this module which variant to find by setting
9632 variables:
9633 Boost_USE_DEBUG_LIBS
9635 New in version 3.10.
9636 Set to ON or OFF to specify whether to search and use the debug
9639 libraries. Default is ON.
9640 Boost_USE_RELEASE_LIBS
9642 New in version 3.10.
9643 Set to ON or OFF to specify whether to search and use the re‐
9646 lease libraries. Default is ON.
9647 Boost_USE_MULTITHREADED
9649 Set to OFF to use the non-multithreaded libraries ("mt" tag).
9650 Default is ON.
9651 Boost_USE_STATIC_LIBS
9653 Set to ON to force the use of the static libraries. Default is
9654 OFF.
9655 Boost_USE_STATIC_RUNTIME
9657 Set to ON or OFF to specify whether to use libraries linked
9658 statically to the C++ runtime ("s" tag). Default is platform
9659 dependent.
9660 Boost_USE_DEBUG_RUNTIME
9662 Set to ON or OFF to specify whether to use libraries linked to
9663 the MS debug C++ runtime ("g" tag). Default is ON.
9664 Boost_USE_DEBUG_PYTHON
9666 Set to ON to use libraries compiled with a debug Python build
9667 ("y" tag). Default is OFF.
9668 Boost_USE_STLPORT
9670 Set to ON to use libraries compiled with STLPort ("p" tag). De‐
9671 fault is OFF.
9672 Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
9674 Set to ON to use libraries compiled with STLPort deprecated "na‐
9675 tive iostreams" ("n" tag). Default is OFF.
9676 Boost_COMPILER
9678 Set to the compiler-specific library suffix (e.g. -gcc43). De‐
9679 fault is auto-computed for the C++ compiler in use.
9680 Changed in version 3.9: A list may be used if multiple compati‐
9682 ble suffixes should be tested for, in decreasing order of pref‐
9683 erence.
9684 Boost_LIB_PREFIX
9687 New in version 3.18.
9688 Set to the platform-specific library name prefix (e.g. lib) used
9691 by Boost static libs. This is needed only on platforms where
9692 CMake does not know the prefix by default.
9693 Boost_ARCHITECTURE
9695 New in version 3.13.
9696 Set to the architecture-specific library suffix (e.g. -x64).
9699 Default is auto-computed for the C++ compiler in use.
9700 Boost_THREADAPI
9702 Suffix for thread component library name, such as pthread or
9703 win32. Names with and without this suffix will both be tried.
9704 Boost_NAMESPACE
9706 Alternate namespace used to build boost with e.g. if set to my‐
9707 boost, will search for myboost_thread instead of boost_thread.
9708 Other variables one may set to control this module are:
9710 Boost_DEBUG
9712 Set to ON to enable debug output from FindBoost. Please enable
9713 this before filing any bug report.
9714 Boost_REALPATH
9716 Set to ON to resolve symlinks for discovered libraries to assist
9717 with packaging. For example, the "system" component library may
9718 be resolved to /usr/lib/libboost_system.so.1.67.0 instead of
9719 /usr/lib/libboost_system.so. This does not affect linking and
9720 should not be enabled unless the user needs this information.
9721 Boost_LIBRARY_DIR
9723 Default value for Boost_LIBRARY_DIR_RELEASE and Boost_LI‐
9724 BRARY_DIR_DEBUG.
9725 Boost_NO_WARN_NEW_VERSIONS
9727 New in version 3.20.
9728 Set to ON to suppress the warning about unknown dependencies for
9731 new Boost versions.
9732 On Visual Studio and Borland compilers Boost headers request automatic
9734 linking to corresponding libraries. This requires matching libraries
9735 to be linked explicitly or available in the link library search path.
9736 In this case setting Boost_USE_STATIC_LIBS to OFF may not achieve dy‐
9737 namic linking. Boost automatic linking typically requests static li‐
9738 braries with a few exceptions (such as Boost.Python). Use:
9739 add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})
9741 to ask Boost to report information about automatic linking requests.
9743 Examples
9745 Find Boost headers only:
9746 find_package(Boost 1.36.0)
9748 if(Boost_FOUND)
9749 include_directories(${Boost_INCLUDE_DIRS})
9750 add_executable(foo foo.cc)
9751 endif()
9752 Find Boost libraries and use imported targets:
9754 find_package(Boost 1.56 REQUIRED COMPONENTS
9756 date_time filesystem iostreams)
9757 add_executable(foo foo.cc)
9758 target_link_libraries(foo Boost::date_time Boost::filesystem
9759 Boost::iostreams)
9760 Find Boost Python 3.6 libraries and use imported targets:
9762 find_package(Boost 1.67 REQUIRED COMPONENTS
9764 python36 numpy36)
9765 add_executable(foo foo.cc)
9766 target_link_libraries(foo Boost::python36 Boost::numpy36)
9767 Find Boost headers and some static (release only) libraries:
9769 set(Boost_USE_STATIC_LIBS ON) # only find static libs
9771 set(Boost_USE_DEBUG_LIBS OFF) # ignore debug libs and
9772 set(Boost_USE_RELEASE_LIBS ON) # only find release libs
9773 set(Boost_USE_MULTITHREADED ON)
9774 set(Boost_USE_STATIC_RUNTIME OFF)
9775 find_package(Boost 1.66.0 COMPONENTS date_time filesystem system ...)
9776 if(Boost_FOUND)
9777 include_directories(${Boost_INCLUDE_DIRS})
9778 add_executable(foo foo.cc)
9779 target_link_libraries(foo ${Boost_LIBRARIES})
9780 endif()
9781 Boost CMake
9783 If Boost was built using the boost-cmake project or from Boost 1.70.0
9784 on it provides a package configuration file for use with find_package's
9785 config mode. This module looks for the package configuration file
9786 called BoostConfig.cmake or boost-config.cmake and stores the result in
9787 CACHE entry Boost_DIR. If found, the package configuration file is
9788 loaded and this module returns with no further action. See documenta‐
9789 tion of the Boost CMake package configuration for details on what it
9790 provides.
9791 Set Boost_NO_BOOST_CMAKE to ON, to disable the search for boost-cmake.
9793 FindBullet
9795 Try to find the Bullet physics engine
9796 This module defines the following variables
9798 BULLET_FOUND - Was bullet found
9800 BULLET_INCLUDE_DIRS - the Bullet include directories
9801 BULLET_LIBRARIES - Link to this, by default it includes
9802 all bullet components (Dynamics,
9803 Collision, LinearMath, & SoftBody)
9804 This module accepts the following variables
9806 BULLET_ROOT - Can be set to bullet install path or Windows build path
9808 FindBZip2
9810 Try to find BZip2
9811 IMPORTED Targets
9813 New in version 3.12.
9814 This module defines IMPORTED target BZip2::BZip2, if BZip2 has been
9817 found.
9818 Result Variables
9820 This module defines the following variables:
9821 BZIP2_FOUND
9823 system has BZip2
9824 BZIP2_INCLUDE_DIRS
9826 New in version 3.12: the BZip2 include directories
9827 BZIP2_LIBRARIES
9830 Link these to use BZip2
9831 BZIP2_NEED_PREFIX
9833 this is set if the functions are prefixed with BZ2_
9834 BZIP2_VERSION_STRING
9836 the version of BZip2 found
9837 Cache variables
9839 The following cache variables may also be set:
9840 BZIP2_INCLUDE_DIR
9842 the BZip2 include directory
9843 FindCABLE
9845 Find CABLE
9846 This module finds if CABLE is installed and determines where the in‐
9848 clude files and libraries are. This code sets the following variables:
9849 CABLE the path to the cable executable
9851 CABLE_TCL_LIBRARY the path to the Tcl wrapper library
9852 CABLE_INCLUDE_DIR the path to the include directory
9853 To build Tcl wrappers, you should add shared library and link it to
9855 ${CABLE_TCL_LIBRARY}. You should also add ${CABLE_INCLUDE_DIR} as an
9856 include directory.
9857 FindCoin3D
9859 Find Coin3D (Open Inventor)
9860 Coin3D is an implementation of the Open Inventor API. It provides data
9862 structures and algorithms for 3D visualization.
9863 This module defines the following variables
9865 COIN3D_FOUND - system has Coin3D - Open Inventor
9867 COIN3D_INCLUDE_DIRS - where the Inventor include directory can be found
9868 COIN3D_LIBRARIES - Link to this to use Coin3D
9869 FindCUDAToolkit
9871 New in version 3.17.
9872 This script locates the NVIDIA CUDA toolkit and the associated li‐
9875 braries, but does not require the CUDA language be enabled for a given
9876 project. This module does not search for the NVIDIA CUDA Samples.
9877 New in version 3.19: QNX support.
9879 Search Behavior
9882 The CUDA Toolkit search behavior uses the following order:
9883 1. If the CUDA language has been enabled we will use the directory con‐
9885 taining the compiler as the first search location for nvcc.
9886 2. If the CUDAToolkit_ROOT cmake configuration variable (e.g., -DCUDA‐
9888 Toolkit_ROOT=/some/path) or environment variable is defined, it will
9889 be searched. If both an environment variable and a configuration
9890 variable are specified, the configuration variable takes precedence.
9891 The directory specified here must be such that the executable nvcc
9893 or the appropriate version.txt file can be found underneath the
9894 specified directory.
9895 3. If the CUDA_PATH environment variable is defined, it will be
9897 searched for nvcc.
9898 4. The user's path is searched for nvcc using find_program(). If this
9900 is found, no subsequent search attempts are performed. Users are
9901 responsible for ensuring that the first nvcc to show up in the path
9902 is the desired path in the event that multiple CUDA Toolkits are in‐
9903 stalled.
9904 5. On Unix systems, if the symbolic link /usr/local/cuda exists, this
9906 is used. No subsequent search attempts are performed. No default
9907 symbolic link location exists for the Windows platform.
9908 6. The platform specific default install locations are searched. If
9910 exactly one candidate is found, this is used. The default CUDA
9911 Toolkit install locations searched are:
9912 ┌───────────┬────────────────────────────┐
9914 │Platform │ Search Pattern │
9915 ├───────────┼────────────────────────────┤
9916 │macOS │ /Developer/NVIDIA/CUDA-X.Y │
9917 ├───────────┼────────────────────────────┤
9918 │Other Unix │ /usr/local/cuda-X.Y │
9919 ├───────────┼────────────────────────────┤
9920 │Windows │ C:\Program Files\NVIDIA │
9921 │ │ GPU Computing Tool‐ │
9922 │ │ kit\CUDA\vX.Y │
9923 └───────────┴────────────────────────────┘
9924 Where X.Y would be a specific version of the CUDA Toolkit, such as
9926 /usr/local/cuda-9.0 or C:\Program Files\NVIDIA GPU Computing Tool‐
9927 kit\CUDA\v9.0
9928 NOTE:
9930 When multiple CUDA Toolkits are installed in the default location
9931 of a system (e.g., both /usr/local/cuda-9.0 and /usr/lo‐
9932 cal/cuda-10.0 exist but the /usr/local/cuda symbolic link does
9933 not exist), this package is marked as not found.
9934 There are too many factors involved in making an automatic deci‐
9936 sion in the presence of multiple CUDA Toolkits being installed.
9937 In this situation, users are encouraged to either (1) set CUDA‐
9938 Toolkit_ROOT [22mor (2) ensure that the correct nvcc executable shows
9939 up in $PATH for find_program() to find.
9940 Arguments
9942 [<version>]
9943 The [<version>] argument requests a version with which the pack‐
9944 age found should be compatible. See find_package version format
9945 for more details.
9946 Options
9948 REQUIRED
9949 If specified, configuration will error if a suitable CUDA Tool‐
9950 kit is not found.
9951 QUIET If specified, the search for a suitable CUDA Toolkit will not
9953 produce any messages.
9954 EXACT If specified, the CUDA Toolkit is considered found only if the
9956 exact VERSION specified is recovered.
9957 Imported targets
9959 An imported target named CUDA::toolkit is provided.
9960 This module defines IMPORTED targets for each of the following li‐
9962 braries that are part of the CUDAToolkit:
9963 • CUDA Runtime Library
9965 • CUDA Driver Library
9967 • cuBLAS
9969 • cuFFT
9971 • cuRAND
9973 • cuSOLVER
9975 • cuSPARSE
9977 • cuPTI
9979 • NPP
9981 • nvBLAS
9983 • nvGRAPH
9985 • nvJPEG
9987 • nvidia-ML
9989 • nvRTC
9991 • nvToolsExt
9993 • OpenCL
9995 • cuLIBOS
9997 CUDA Runtime Library
9999 The CUDA Runtime library (cudart) are what most applications will typi‐
10000 cally need to link against to make any calls such as cudaMalloc, and
10001 cudaFree.
10002 Targets Created:
10004 • CUDA::cudart
10006 • CUDA::cudart_static
10008 CUDA Driver Library
10010 The CUDA Driver library (cuda) are used by applications that use calls
10011 such as cuMemAlloc, and cuMemFree. This is generally used by advanced
10012 Targets Created:
10014 • CUDA::cuda_driver
10016 • CUDA::cuda_driver
10018 cuBLAS
10020 The cuBLAS library.
10021 Targets Created:
10023 • CUDA::cublas
10025 • CUDA::cublas_static
10027 • CUDA::cublasLt starting in CUDA 10.1
10029 • CUDA::cublasLt_static starting in CUDA 10.1
10031 cuFFT
10033 The cuFFT library.
10034 Targets Created:
10036 • CUDA::cufft
10038 • CUDA::cufftw
10040 • CUDA::cufft_static
10042 • CUDA::cufftw_static
10044 cuRAND
10046 The cuRAND library.
10047 Targets Created:
10049 • CUDA::curand
10051 • CUDA::curand_static
10053 cuSOLVER
10055 The cuSOLVER library.
10056 Targets Created:
10058 • CUDA::cusolver
10060 • CUDA::cusolver_static
10062 cuSPARSE
10064 The cuSPARSE library.
10065 Targets Created:
10067 • CUDA::cusparse
10069 • CUDA::cusparse_static
10071 cupti
10073 The NVIDIA CUDA Profiling Tools Interface.
10074 Targets Created:
10076 • CUDA::cupti
10078 • CUDA::cupti_static
10080 NPP
10082 The NPP libraries.
10083 Targets Created:
10085 • nppc:
10087 • CUDA::nppc
10089 • CUDA::nppc_static
10091 • nppial: Arithmetic and logical operation functions in nppi_arith‐
10093 metic_and_logical_operations.h
10094 • CUDA::nppial
10096 • CUDA::nppial_static
10098 • nppicc: Color conversion and sampling functions in nppi_color_conver‐
10100 sion.h
10101 • CUDA::nppicc
10103 • CUDA::nppicc_static
10105 • nppicom: JPEG compression and decompression functions in nppi_com‐
10107 pression_functions.h Removed starting in CUDA 11.0, use nvJPEG in‐
10108 stead.
10109 • CUDA::nppicom
10111 • CUDA::nppicom_static
10113 • nppidei: Data exchange and initialization functions in nppi_data_ex‐
10115 change_and_initialization.h
10116 • CUDA::nppidei
10118 • CUDA::nppidei_static
10120 • nppif: Filtering and computer vision functions in nppi_filter_func‐
10122 tions.h
10123 • CUDA::nppif
10125 • CUDA::nppif_static
10127 • nppig: Geometry transformation functions found in nppi_geome‐
10129 try_transforms.h
10130 • CUDA::nppig
10132 • CUDA::nppig_static
10134 • nppim: Morphological operation functions found in nppi_morphologi‐
10136 cal_operations.h
10137 • CUDA::nppim
10139 • CUDA::nppim_static
10141 • nppist: Statistics and linear transform in nppi_statistics_func‐
10143 tions.h and nppi_linear_transforms.h
10144 • CUDA::nppist
10146 • CUDA::nppist_static
10148 • nppisu: Memory support functions in nppi_support_functions.h
10150 • CUDA::nppisu
10152 • CUDA::nppisu_static
10154 • nppitc: Threshold and compare operation functions in nppi_thresh‐
10156 old_and_compare_operations.h
10157 • CUDA::nppitc
10159 • CUDA::nppitc_static
10161 • npps:
10163 • CUDA::npps
10165 • CUDA::npps_static
10167 nvBLAS
10169 The nvBLAS libraries. This is a shared library only.
10170 Targets Created:
10172 • CUDA::nvblas
10174 nvGRAPH
10176 The nvGRAPH library. Removed starting in CUDA 11.0
10177 Targets Created:
10179 • CUDA::nvgraph
10181 • CUDA::nvgraph_static
10183 nvJPEG
10185 The nvJPEG library. Introduced in CUDA 10.
10186 Targets Created:
10188 • CUDA::nvjpeg
10190 • CUDA::nvjpeg_static
10192 nvRTC
10194 The nvRTC (Runtime Compilation) library. This is a shared library
10195 only.
10196 Targets Created:
10198 • CUDA::nvrtc
10200 nvidia-ML
10202 The NVIDIA Management Library. This is a shared library only.
10203 Targets Created:
10205 • CUDA::nvml
10207 nvToolsExt
10209 The NVIDIA Tools Extension. This is a shared library only.
10210 Targets Created:
10212 • CUDA::nvToolsExt
10214 OpenCL
10216 The NVIDIA OpenCL Library. This is a shared library only.
10217 Targets Created:
10219 • CUDA::OpenCL
10221 cuLIBOS
10223 The cuLIBOS library is a backend thread abstraction layer library which
10224 is static only. The CUDA::cublas_static, CUDA::cusparse_static,
10225 CUDA::cufft_static, CUDA::curand_static, and (when implemented) NPP li‐
10226 braries all automatically have this dependency linked.
10227 Target Created:
10229 • CUDA::culibos
10231 Note: direct usage of this target by consumers should not be necessary.
10233 Result variables
10235 CUDAToolkit_FOUND
10236 A boolean specifying whether or not the CUDA Toolkit was found.
10237 CUDAToolkit_VERSION
10239 The exact version of the CUDA Toolkit found (as reported by nvcc
10240 --version or version.txt).
10241 CUDAToolkit_VERSION_MAJOR
10243 The major version of the CUDA Toolkit.
10244 CUDAToolkit_VERSION_MINOR
10246 The minor version of the CUDA Toolkit.
10247 CUDAToolkit_VERSION_PATCH
10249 The patch version of the CUDA Toolkit.
10250 CUDAToolkit_BIN_DIR
10252 The path to the CUDA Toolkit library directory that contains the
10253 CUDA executable nvcc.
10254 CUDAToolkit_INCLUDE_DIRS
10256 The path to the CUDA Toolkit include folder containing the
10257 header files required to compile a project linking against CUDA.
10258 CUDAToolkit_LIBRARY_DIR
10260 The path to the CUDA Toolkit library directory that contains the
10261 CUDA Runtime library cudart.
10262 CUDAToolkit_LIBRARY_ROOT
10264 New in version 3.18.
10265 The path to the CUDA Toolkit directory containing the nvvm di‐
10268 rectory and version.txt.
10269 CUDAToolkit_TARGET_DIR
10271 The path to the CUDA Toolkit directory including the target ar‐
10272 chitecture when cross-compiling. When not cross-compiling this
10273 will be equivalent to the parent directory of CUDA‐
10274 Toolkit_BIN_DIR.
10275 CUDAToolkit_NVCC_EXECUTABLE
10277 The path to the NVIDIA CUDA compiler nvcc. Note that this path
10278 may not be the same as CMAKE_CUDA_COMPILER. nvcc must be found
10279 to determine the CUDA Toolkit version as well as determining
10280 other features of the Toolkit. This variable is set for the
10281 convenience of modules that depend on this one.
10282 FindCups
10284 Find the Common UNIX Printing System (CUPS).
10285 Set CUPS_REQUIRE_IPP_DELETE_ATTRIBUTE to TRUE if you need a version
10287 which features this function (i.e. at least 1.1.19)
10288 Imported targets
10290 New in version 3.15.
10291 This module defines IMPORTED target Cups::Cups, if Cups has been found.
10294 Result variables
10296 This module will set the following variables in your project:
10297 CUPS_FOUND
10299 true if CUPS headers and libraries were found
10300 CUPS_INCLUDE_DIRS
10302 the directory containing the Cups headers
10303 CUPS_LIBRARIES
10305 the libraries to link against to use CUPS.
10306 CUPS_VERSION_STRING
10308 the version of CUPS found (since CMake 2.8.8)
10309 Cache variables
10311 The following cache variables may also be set:
10312 CUPS_INCLUDE_DIR
10314 the directory containing the Cups headers
10315 FindCURL
10317 Find the native CURL headers and libraries.
10318 New in version 3.14: This module accept optional COMPONENTS to check
10320 supported features and protocols:
10321 PROTOCOLS: ICT FILE FTP FTPS GOPHER HTTP HTTPS IMAP IMAPS LDAP LDAPS POP3
10324 POP3S RTMP RTSP SCP SFTP SMB SMBS SMTP SMTPS TELNET TFTP
10325 FEATURES: SSL IPv6 UnixSockets libz AsynchDNS IDN GSS-API PSL SPNEGO
10326 Kerberos NTLM NTLM_WB TLS-SRP HTTP2 HTTPS-proxy
10327 IMPORTED Targets
10329 New in version 3.12.
10330 This module defines IMPORTED target CURL::libcurl, if curl has been
10333 found.
10334 Result Variables
10336 This module defines the following variables:
10337 CURL_FOUND
10339 "True" if curl found.
10340 CURL_INCLUDE_DIRS
10342 where to find curl/curl.h, etc.
10343 CURL_LIBRARIES
10345 List of libraries when using curl.
10346 CURL_VERSION_STRING
10348 The version of curl found.
10349 New in version 3.13: Debug and Release variants are found separately.
10351 CURL CMake
10354 New in version 3.17.
10355 If CURL was built using the CMake buildsystem then it provides its own
10358 CURLConfig.cmake file for use with the find_package() command's config
10359 mode. This module looks for this file and, if found, returns its re‐
10360 sults with no further action.
10361 Set CURL_NO_CURL_CMAKE to ON to disable this search.
10363 FindCurses
10365 Find the curses or ncurses include file and library.
10366 Result Variables
10368 This module defines the following variables:
10369 CURSES_FOUND
10371 True if Curses is found.
10372 CURSES_INCLUDE_DIRS
10374 The include directories needed to use Curses.
10375 CURSES_LIBRARIES
10377 The libraries needed to use Curses.
10378 CURSES_CFLAGS
10380 New in version 3.16.
10381 Parameters which ought be given to C/C++ compilers when using
10384 Curses.
10385 CURSES_HAVE_CURSES_H
10387 True if curses.h is available.
10388 CURSES_HAVE_NCURSES_H
10390 True if ncurses.h is available.
10391 CURSES_HAVE_NCURSES_NCURSES_H
10393 True if ncurses/ncurses.h is available.
10394 CURSES_HAVE_NCURSES_CURSES_H
10396 True if ncurses/curses.h is available.
10397 Set CURSES_NEED_NCURSES to TRUE before the find_package(Curses) call if
10399 NCurses functionality is required.
10400 New in version 3.10: Set CURSES_NEED_WIDE to TRUE before the find_pack‐
10402 age(Curses) call if unicode functionality is required.
10403 Backward Compatibility
10406 The following variable are provided for backward compatibility:
10407 CURSES_INCLUDE_DIR
10409 Path to Curses include. Use CURSES_INCLUDE_DIRS instead.
10410 CURSES_LIBRARY
10412 Path to Curses library. Use CURSES_LIBRARIES instead.
10413 FindCVS
10415 Find the Concurrent Versions System (CVS).
10416 The module defines the following variables:
10418 CVS_EXECUTABLE - path to cvs command line client
10420 CVS_FOUND - true if the command line client was found
10421 Example usage:
10423 find_package(CVS)
10425 if(CVS_FOUND)
10426 message("CVS found: ${CVS_EXECUTABLE}")
10427 endif()
10428 FindCxxTest
10430 Find CxxTest unit testing framework.
10431 Find the CxxTest suite and declare a helper macro for creating unit
10433 tests and integrating them with CTest. For more details on CxxTest see
10434 http://cxxtest.tigris.org
10435 INPUT Variables
10437 CXXTEST_USE_PYTHON [deprecated since 1.3]
10439 Only used in the case both Python & Perl
10440 are detected on the system to control
10441 which CxxTest code generator is used.
10442 Valid only for CxxTest version 3.
10443 NOTE: In older versions of this Find Module,
10445 this variable controlled if the Python test
10446 generator was used instead of the Perl one,
10447 regardless of which scripting language the
10448 user had installed.
10449 CXXTEST_TESTGEN_ARGS (since CMake 2.8.3)
10451 Specify a list of options to pass to the CxxTest code
10452 generator. If not defined, --error-printer is
10453 passed.
10454 OUTPUT Variables
10456 CXXTEST_FOUND
10458 True if the CxxTest framework was found
10459 CXXTEST_INCLUDE_DIRS
10460 Where to find the CxxTest include directory
10461 CXXTEST_PERL_TESTGEN_EXECUTABLE
10462 The perl-based test generator
10463 CXXTEST_PYTHON_TESTGEN_EXECUTABLE
10464 The python-based test generator
10465 CXXTEST_TESTGEN_EXECUTABLE (since CMake 2.8.3)
10466 The test generator that is actually used (chosen using user preferences
10467 and interpreters found in the system)
10468 CXXTEST_TESTGEN_INTERPRETER (since CMake 2.8.3)
10469 The full path to the Perl or Python executable on the system, on
10470 platforms where the script cannot be executed using its shebang line.
10471 MACROS for optional use by CMake users:
10473 CXXTEST_ADD_TEST(<test_name> <gen_source_file> <input_files_to_testgen...>)
10475 Creates a CxxTest runner and adds it to the CTest testing suite
10476 Parameters:
10477 test_name The name of the test
10478 gen_source_file The generated source filename to be
10479 generated by CxxTest
10480 input_files_to_testgen The list of header files containing the
10481 CxxTest::TestSuite's to be included in
10482 this runner
10483 #==============
10485 Example Usage:
10486 find_package(CxxTest)
10488 if(CXXTEST_FOUND)
10489 include_directories(${CXXTEST_INCLUDE_DIR})
10490 enable_testing()
10491 CXXTEST_ADD_TEST(unittest_foo foo_test.cc
10493 ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h)
10494 target_link_libraries(unittest_foo foo) # as needed
10495 endif()
10496 This will (if CxxTest is found):
10498 1. Invoke the testgen executable to autogenerate foo_test.cc in the
10499 binary tree from "foo_test.h" in the current source directory.
10500 2. Create an executable and test called unittest_foo.
10501 #=============
10503 Example foo_test.h:
10504 #include <cxxtest/TestSuite.h>
10506 class MyTestSuite : public CxxTest::TestSuite
10508 {
10509 public:
10510 void testAddition( void )
10511 {
10512 TS_ASSERT( 1 + 1 > 1 );
10513 TS_ASSERT_EQUALS( 1 + 1, 2 );
10514 }
10515 };
10516 FindCygwin
10518 Find Cygwin, a POSIX-compatible environment that runs natively on Mi‐
10519 crosoft Windows
10520 FindDart
10522 Find DART
10523 This module looks for the dart testing software and sets DART_ROOT to
10525 point to where it found it.
10526 FindDCMTK
10528 Find DICOM ToolKit (DCMTK) libraries and applications
10529 The module defines the following variables:
10531 DCMTK_INCLUDE_DIRS - Directories to include to use DCMTK
10533 DCMTK_LIBRARIES - Files to link against to use DCMTK
10534 DCMTK_FOUND - If false, don't try to use DCMTK
10535 DCMTK_DIR - (optional) Source directory for DCMTK
10536 Compatibility
10538 This module is able to find a version of DCMTK that does or does not
10539 export a DCMTKConfig.cmake file. It applies a two step process:
10540 • Step 1: Attempt to find DCMTK version providing a DCMTKConfig.cmake
10542 file.
10543 • Step 2: If step 1 failed, rely on FindDCMTK.cmake to set DCMTK_*
10545 variables details below.
10546 Recent DCMTK provides a DCMTKConfig.cmake package configuration file.
10548 To exclusively use the package configuration file (recommended when
10549 possible), pass the NO_MODULE option to find_package(). For example,
10550 find_package(DCMTK NO_MODULE). This requires official DCMTK snapshot
10551 3.6.1_20140617 or newer.
10552 Until all clients update to the more recent DCMTK, build systems will
10554 need to support different versions of DCMTK.
10555 On any given system, the following combinations of DCMTK versions could
10557 be considered:
10558 ┌───────┬─────────────────┬─────────────────┬─────────────┐
10560 │ │ SYSTEM DCMTK │ LOCAL DCMTK │ Supported ? │
10561 ├───────┼─────────────────┼─────────────────┼─────────────┤
10562 │Case A │ NA │ [ ] DCMTKConfig │ YES │
10563 ├───────┼─────────────────┼─────────────────┼─────────────┤
10564 │Case B │ NA │ [X] DCMTKConfig │ YES │
10565 ├───────┼─────────────────┼─────────────────┼─────────────┤
10566 │Case C │ [ ] DCMTKConfig │ NA │ YES │
10567 ├───────┼─────────────────┼─────────────────┼─────────────┤
10568 │Case D │ [X] DCMTKConfig │ NA │ YES │
10569 ├───────┼─────────────────┼─────────────────┼─────────────┤
10570 │Case E │ [ ] DCMTKConfig │ [ ] DCMTKConfig │ YES (*) │
10571 ├───────┼─────────────────┼─────────────────┼─────────────┤
10572 │Case F │ [X] DCMTKConfig │ [ ] DCMTKConfig │ NO │
10573 ├───────┼─────────────────┼─────────────────┼─────────────┤
10574 │Case G │ [ ] DCMTKConfig │ [X] DCMTKConfig │ YES │
10575 ├───────┼─────────────────┼─────────────────┼─────────────┤
10576 │Case H │ [X] DCMTKConfig │ [X] DCMTKConfig │ YES │
10577 └───────┴─────────────────┴─────────────────┴─────────────┘
10578 (*) See Troubleshooting section.
10579 Legend:
10581 NA ...............: Means that no System or Local DCMTK is available
10582 [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export
10584 a DCMTKConfig.cmake file.
10585 [X] DCMTKConfig ..: Means that the version of DCMTK exports a DCMTK‐
10587 Config.cmake file.
10588 Troubleshooting
10590 What to do if my project finds a different version of DCMTK?
10591 Remove DCMTK entry from the CMake cache per find_package() documenta‐
10593 tion.
10594 FindDevIL
10596 This module locates the developer's image library.
10597 http://openil.sourceforge.net/
10598 IMPORTED Targets
10600 New in version 3.21.
10601 This module defines the IMPORTED targets:
10604 DevIL::IL
10606 Defined if the system has DevIL.
10607 DevIL::ILU
10609 Defined if the system has DevIL Utilities.
10610 DevIL::ILUT
10612 Defined if the system has DevIL Utility Toolkit.
10613 Result Variables
10615 This module sets:
10616 IL_LIBRARIES
10618 The name of the IL library. These include the full path to the
10619 core DevIL library. This one has to be linked into the applica‐
10620 tion.
10621 ILU_LIBRARIES
10623 The name of the ILU library. Again, the full path. This library
10624 is for filters and effects, not actual loading. It doesn't have
10625 to be linked if the functionality it provides is not used.
10626 ILUT_LIBRARIES
10628 The name of the ILUT library. Full path. This part of the li‐
10629 brary interfaces with OpenGL. It is not strictly needed in ap‐
10630 plications.
10631 IL_INCLUDE_DIR
10633 where to find the il.h, ilu.h and ilut.h files.
10634 DevIL_FOUND
10636 This is set to TRUE if all the above variables were set. This
10637 will be set to false if ILU or ILUT are not found, even if they
10638 are not needed. In most systems, if one library is found all the
10639 others are as well. That's the way the DevIL developers release
10640 it.
10641 DevIL_ILUT_FOUND
10643 New in version 3.21.
10644 This is set to TRUE if the ILUT library is found.
10647 FindDoxygen
10649 Doxygen is a documentation generation tool (see
10650 http://www.doxygen.org). This module looks for Doxygen and some op‐
10651 tional tools it supports:
10652 dot Graphviz dot utility used to render various graphs.
10654 mscgen Message Chart Generator utility used by Doxygen's \msc and \msc‐
10656 file commands.
10657 dia Dia the diagram editor used by Doxygen's \diafile command.
10659 New in version 3.9: These tools are available as components in the
10661 find_package() command. For example:
10662 # Require dot, treat the other components as optional
10665 find_package(Doxygen
10666 REQUIRED dot
10667 OPTIONAL_COMPONENTS mscgen dia)
10668 The following variables are defined by this module:
10670 DOXYGEN_FOUND
10672 True if the doxygen executable was found.
10673 DOXYGEN_VERSION
10675 The version reported by doxygen --version.
10676 New in version 3.9: The module defines IMPORTED targets for Doxygen and
10678 each component found. These can be used as part of custom commands,
10679 etc. and should be preferred over old-style (and now deprecated) vari‐
10680 ables like DOXYGEN_EXECUTABLE. The following import targets are defined
10681 if their corresponding executable could be found (the component import
10682 targets will only be defined if that component was requested):
10683 Doxygen::doxygen
10686 Doxygen::dot
10687 Doxygen::mscgen
10688 Doxygen::dia
10689 Functions
10691 doxygen_add_docs
10692 New in version 3.9.
10693 This function is intended as a convenience for adding a target
10696 for generating documentation with Doxygen. It aims to provide
10697 sensible defaults so that projects can generally just provide
10698 the input files and directories and that will be sufficient to
10699 give sensible results. The function supports the ability to cus‐
10700 tomize the Doxygen configuration used to build the documenta‐
10701 tion.
10702 doxygen_add_docs(targetName
10704 [filesOrDirs...]
10705 [ALL]
10706 [USE_STAMP_FILE]
10707 [WORKING_DIRECTORY dir]
10708 [COMMENT comment])
10709 The function constructs a Doxyfile and defines a custom target
10711 that runs Doxygen on that generated file. The listed files and
10712 directories are used as the INPUT of the generated Doxyfile and
10713 they can contain wildcards. Any files that are listed explic‐
10714 itly will also be added as SOURCES of the custom target so they
10715 will show up in an IDE project's source list.
10716 So that relative input paths work as expected, by default the
10718 working directory of the Doxygen command will be the current
10719 source directory (i.e. CMAKE_CURRENT_SOURCE_DIR). This can be
10720 overridden with the WORKING_DIRECTORY option to change the di‐
10721 rectory used as the relative base point. Note also that Doxy‐
10722 gen's default behavior is to strip the working directory from
10723 relative paths in the generated documentation (see the
10724 STRIP_FROM_PATH Doxygen config option for details).
10725 If provided, the optional comment will be passed as the COMMENT
10727 for the add_custom_target() command used to create the custom
10728 target internally.
10729 New in version 3.12: If ALL is set, the target will be added to
10731 the default build target.
10732 New in version 3.16: If USE_STAMP_FILE is set, the custom com‐
10735 mand defined by this function will create a stamp file with the
10736 name <targetName>.stamp in the current binary directory whenever
10737 doxygen is re-run. With this option present, all items in
10738 <filesOrDirs> must be files (i.e. no directories, symlinks or
10739 wildcards) and each of the files must exist at the time doxy‐
10740 gen_add_docs() is called. An error will be raised if any of the
10741 items listed is missing or is not a file when USE_STAMP_FILE is
10742 given. A dependency will be created on each of the files so
10743 that doxygen will only be re-run if one of the files is updated.
10744 Without the USE_STAMP_FILE option, doxygen will always be re-run
10745 if the <targetName> target is built regardless of whether any‐
10746 thing listed in <filesOrDirs> has changed.
10747 The contents of the generated Doxyfile can be customized by set‐
10750 ting CMake variables before calling doxygen_add_docs(). Any
10751 variable with a name of the form DOXYGEN_<tag> will have its
10752 value substituted for the corresponding <tag> configuration op‐
10753 tion in the Doxyfile. See the Doxygen documentation for the full
10754 list of supported configuration options.
10755 Some of Doxygen's defaults are overridden to provide more appro‐
10757 priate behavior for a CMake project. Each of the following will
10758 be explicitly set unless the variable already has a value before
10759 doxygen_add_docs() is called (with some exceptions noted):
10760 DOXYGEN_HAVE_DOT
10762 Set to YES if the dot component was requested and it was
10763 found, NO otherwise. Any existing value of DOXY‐
10764 GEN_HAVE_DOT is ignored.
10765 DOXYGEN_DOT_MULTI_TARGETS
10767 Set to YES by this module (note that this requires a dot
10768 version newer than 1.8.10). This option is only meaning‐
10769 ful if DOXYGEN_HAVE_DOT is also set to YES.
10770 DOXYGEN_GENERATE_LATEX
10772 Set to NO by this module.
10773 DOXYGEN_WARN_FORMAT
10775 For Visual Studio based generators, this is set to the
10776 form recognized by the Visual Studio IDE: $file($line) :
10777 $text. For all other generators, Doxygen's default value
10778 is not overridden.
10779 DOXYGEN_PROJECT_NAME
10781 Populated with the name of the current project (i.e.
10782 PROJECT_NAME).
10783 DOXYGEN_PROJECT_NUMBER
10785 Populated with the version of the current project (i.e.
10786 PROJECT_VERSION).
10787 DOXYGEN_PROJECT_BRIEF
10789 Populated with the description of the current project
10790 (i.e. PROJECT_DESCRIPTION).
10791 DOXYGEN_INPUT
10793 Projects should not set this variable. It will be popu‐
10794 lated with the set of files and directories passed to
10795 doxygen_add_docs(), thereby providing consistent behavior
10796 with the other built-in commands like add_executable(),
10797 add_library() and add_custom_target(). If a variable
10798 named DOXYGEN_INPUT is set by the project, it will be ig‐
10799 nored and a warning will be issued.
10800 DOXYGEN_RECURSIVE
10802 Set to YES by this module.
10803 DOXYGEN_EXCLUDE_PATTERNS
10805 If the set of inputs includes directories, this variable
10806 will specify patterns used to exclude files from them.
10807 The following patterns are added by doxygen_add_docs() to
10808 ensure CMake-specific files and directories are not in‐
10809 cluded in the input. If the project sets DOXYGEN_EX‐
10810 CLUDE_PATTERNS, those contents are merged with these ad‐
10811 ditional patterns rather than replacing them:
10812 */.git/*
10814 */.svn/*
10815 */.hg/*
10816 */CMakeFiles/*
10817 */_CPack_Packages/*
10818 DartConfiguration.tcl
10819 CMakeLists.txt
10820 CMakeCache.txt
10821 DOXYGEN_OUTPUT_DIRECTORY
10823 Set to CMAKE_CURRENT_BINARY_DIR by this module. Note that
10824 if the project provides its own value for this and it is
10825 a relative path, it will be converted to an absolute path
10826 relative to the current binary directory. This is neces‐
10827 sary because doxygen will normally be run from a direc‐
10828 tory within the source tree so that relative source paths
10829 work as expected. If this directory does not exist, it
10830 will be recursively created prior to executing the doxy‐
10831 gen commands.
10832 To change any of these defaults or override any other Doxygen config
10834 option, set relevant variables before calling doxygen_add_docs(). For
10835 example:
10836 set(DOXYGEN_GENERATE_HTML NO)
10838 set(DOXYGEN_GENERATE_MAN YES)
10839 doxygen_add_docs(
10841 doxygen
10842 ${PROJECT_SOURCE_DIR}
10843 COMMENT "Generate man pages"
10844 )
10845 A number of Doxygen config options accept lists of values, but Doxygen
10847 requires them to be separated by whitespace. CMake variables hold lists
10848 as a string with items separated by semi-colons, so a conversion needs
10849 to be performed. The doxygen_add_docs() command specifically checks the
10850 following Doxygen config options and will convert their associated
10851 CMake variable's contents into the required form if set. CMake vari‐
10852 ables are named DOXYGEN_<name> for the Doxygen settings specified here.
10853 ABBREVIATE_BRIEF
10855 ALIASES
10856 CITE_BIB_FILES
10857 DIAFILE_DIRS
10858 DOTFILE_DIRS
10859 DOT_FONTPATH
10860 ENABLED_SECTIONS
10861 EXAMPLE_PATH
10862 EXAMPLE_PATTERNS
10863 EXCLUDE
10864 EXCLUDE_PATTERNS
10865 EXCLUDE_SYMBOLS
10866 EXPAND_AS_DEFINED
10867 EXTENSION_MAPPING
10868 EXTRA_PACKAGES
10869 EXTRA_SEARCH_MAPPINGS
10870 FILE_PATTERNS
10871 FILTER_PATTERNS
10872 FILTER_SOURCE_PATTERNS
10873 HTML_EXTRA_FILES
10874 HTML_EXTRA_STYLESHEET
10875 IGNORE_PREFIX
10876 IMAGE_PATH
10877 INCLUDE_FILE_PATTERNS
10878 INCLUDE_PATH
10879 INPUT
10880 LATEX_EXTRA_FILES
10881 LATEX_EXTRA_STYLESHEET
10882 MATHJAX_EXTENSIONS
10883 MSCFILE_DIRS
10884 PLANTUML_INCLUDE_PATH
10885 PREDEFINED
10886 QHP_CUST_FILTER_ATTRS
10887 QHP_SECT_FILTER_ATTRS
10888 STRIP_FROM_INC_PATH
10889 STRIP_FROM_PATH
10890 TAGFILES
10891 TCL_SUBST
10892 The following single value Doxygen options will be quoted automatically
10894 if they contain at least one space:
10895 CHM_FILE
10897 DIA_PATH
10898 DOCBOOK_OUTPUT
10899 DOCSET_FEEDNAME
10900 DOCSET_PUBLISHER_NAME
10901 DOT_FONTNAME
10902 DOT_PATH
10903 EXTERNAL_SEARCH_ID
10904 FILE_VERSION_FILTER
10905 GENERATE_TAGFILE
10906 HHC_LOCATION
10907 HTML_FOOTER
10908 HTML_HEADER
10909 HTML_OUTPUT
10910 HTML_STYLESHEET
10911 INPUT_FILTER
10912 LATEX_FOOTER
10913 LATEX_HEADER
10914 LATEX_OUTPUT
10915 LAYOUT_FILE
10916 MAN_OUTPUT
10917 MAN_SUBDIR
10918 MATHJAX_CODEFILE
10919 MSCGEN_PATH
10920 OUTPUT_DIRECTORY
10921 PERL_PATH
10922 PLANTUML_JAR_PATH
10923 PROJECT_BRIEF
10924 PROJECT_LOGO
10925 PROJECT_NAME
10926 QCH_FILE
10927 QHG_LOCATION
10928 QHP_CUST_FILTER_NAME
10929 QHP_VIRTUAL_FOLDER
10930 RTF_EXTENSIONS_FILE
10931 RTF_OUTPUT
10932 RTF_STYLESHEET_FILE
10933 SEARCHDATA_FILE
10934 USE_MDFILE_AS_MAINPAGE
10935 WARN_FORMAT
10936 WARN_LOGFILE
10937 XML_OUTPUT
10938 New in version 3.11: There are situations where it may be undesirable
10940 for a particular config option to be automatically quoted by doxy‐
10941 gen_add_docs(), such as ALIASES which may need to include its own em‐
10942 bedded quoting. The DOXYGEN_VERBATIM_VARS variable can be used to
10943 specify a list of Doxygen variables (including the leading DOXYGEN_
10944 prefix) which should not be quoted. The project is then responsible
10945 for ensuring that those variables' values make sense when placed di‐
10946 rectly in the Doxygen input file. In the case of list variables, list
10947 items are still separated by spaces, it is only the automatic quoting
10948 that is skipped. For example, the following allows doxygen_add_docs()
10949 to apply quoting to DOXYGEN_PROJECT_BRIEF, but not each item in the
10950 DOXYGEN_ALIASES list (bracket syntax can also be used to make working
10951 with embedded quotes easier):
10952 set(DOXYGEN_PROJECT_BRIEF "String with spaces")
10955 set(DOXYGEN_ALIASES
10956 [[somealias="@some_command param"]]
10957 "anotherAlias=@foobar"
10958 )
10959 set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)
10960 The resultant Doxyfile will contain the following lines:
10962 PROJECT_BRIEF = "String with spaces"
10964 ALIASES = somealias="@some_command param" anotherAlias=@foobar
10965 Deprecated Result Variables
10967 Deprecated since version 3.9.
10968 For compatibility with previous versions of CMake, the following vari‐
10971 ables are also defined but they are deprecated and should no longer be
10972 used:
10973 DOXYGEN_EXECUTABLE
10975 The path to the doxygen command. If projects need to refer to
10976 the doxygen executable directly, they should use the Doxy‐
10977 gen::doxygen import target instead.
10978 DOXYGEN_DOT_FOUND
10980 True if the dot executable was found.
10981 DOXYGEN_DOT_EXECUTABLE
10983 The path to the dot command. If projects need to refer to the
10984 dot executable directly, they should use the Doxygen::dot import
10985 target instead.
10986 DOXYGEN_DOT_PATH
10988 The path to the directory containing the dot executable as re‐
10989 ported in DOXYGEN_DOT_EXECUTABLE. The path may have forward
10990 slashes even on Windows and is not suitable for direct substitu‐
10991 tion into a Doxyfile.in template. If you need this value, get
10992 the IMPORTED_LOCATION property of the Doxygen::dot target and
10993 use get_filename_component() to extract the directory part of
10994 that path. You may also want to consider using file(TO_NA‐
10995 TIVE_PATH) to prepare the path for a Doxygen configuration file.
10996 Deprecated Hint Variables
10998 Deprecated since version 3.9.
10999 DOXYGEN_SKIP_DOT
11002 This variable has no effect for the component form of find_pack‐
11003 age. In backward compatibility mode (i.e. without components
11004 list) it prevents the finder module from searching for
11005 Graphviz's dot utility.
11006 FindEnvModules
11008 New in version 3.15.
11009 Locate an environment module implementation and make commands available
11012 to CMake scripts to use them. This is compatible with both Lua-based
11013 Lmod and TCL-based EnvironmentModules.
11014 This module is intended for the use case of setting up the compiler and
11016 library environment within a CTest Script (ctest -S). It can also be
11017 used in a CMake Script (cmake -P).
11018 NOTE:
11020 The loaded environment will not survive past the end of the calling
11021 process. Do not use this module in project code (CMakeLists.txt
11022 files) to load a compiler environment; it will not be available dur‐
11023 ing the build. Instead load the environment manually before running
11024 CMake or using the generated build system.
11025 Example Usage
11027 set(CTEST_BUILD_NAME "CrayLinux-CrayPE-Cray-dynamic")
11028 set(CTEST_BUILD_CONFIGURATION Release)
11029 set(CTEST_BUILD_FLAGS "-k -j8")
11030 set(CTEST_CMAKE_GENERATOR "Unix Makefiles")
11031 ...
11033 find_package(EnvModules REQUIRED)
11035 env_module(purge)
11037 env_module(load modules)
11038 env_module(load craype)
11039 env_module(load PrgEnv-cray)
11040 env_module(load craype-knl)
11041 env_module(load cray-mpich)
11042 env_module(load cray-libsci)
11043 set(ENV{CRAYPE_LINK_TYPE} dynamic)
11045 ...
11047 Result Variables
11049 This module will set the following variables in your project:
11050 EnvModules_FOUND
11052 True if a compatible environment modules framework was found.
11053 Cache Variables
11055 The following cache variable will be set:
11056 EnvModules_COMMAND
11058 The low level module command to use. Currently supported imple‐
11059 mentations are the Lua based Lmod and TCL based EnvironmentMod‐
11060 ules.
11061 Environment Variables
11063 ENV{MODULESHOME}
11064 Usually set by the module environment implementation, used as a
11065 hint to locate the module command to execute.
11066 Provided Functions
11068 This defines the following CMake functions for interacting with envi‐
11069 ronment modules:
11070 env_module
11072 Execute an aribitrary module command:
11073 env_module(cmd arg1 ... argN)
11075 env_module(
11076 COMMAND cmd arg1 ... argN
11077 [OUTPUT_VARIABLE <out-var>]
11078 [RESULT_VARIABLE <ret-var>]
11079 )
11080 The options are:
11082 cmd arg1 ... argN
11084 The module sub-command and arguments to execute as if
11085 they were passed directly to the module command in your
11086 shell environment.
11087 OUTPUT_VARIABLE <out-var>
11089 The standard output from executing the module command.
11090 RESULT_VARIABLE <ret-var>
11092 The return code from executing the module command.
11093 env_module_swap
11095 Swap one module for another:
11096 env_module_swap(out_mod in_mod
11098 [OUTPUT_VARIABLE <out-var>]
11099 [RESULT_VARIABLE <ret-var>]
11100 )
11101 This is functionally equivalent to the module swap out_mod
11103 in_mod shell command. The options are:
11104 OUTPUT_VARIABLE <out-var>
11106 The standard output from executing the module command.
11107 RESULT_VARIABLE <ret-var>
11109 The return code from executing the module command.
11110 env_module_list
11112 Retrieve the list of currently loaded modules:
11113 env_module_list(<out-var>)
11115 This is functionally equivalent to the module list shell com‐
11117 mand. The result is stored in <out-var> as a properly formatted
11118 CMake semicolon-separated list variable.
11119 env_module_avail
11121 Retrieve the list of available modules:
11122 env_module_avail([<mod-prefix>] <out-var>)
11124 This is functionally equivalent to the module avail <mod-prefix>
11126 shell command. The result is stored in <out-var> as a properly
11127 formatted CMake semicolon-separated list variable.
11128 FindEXPAT
11130 Find the native Expat headers and library. Expat is a stream-oriented
11131 XML parser library written in C.
11132 Imported Targets
11134 New in version 3.10.
11135 This module defines the following IMPORTED targets:
11138 EXPAT::EXPAT
11140 The Expat expat library, if found.
11141 Result Variables
11143 This module will set the following variables in your project:
11144 EXPAT_INCLUDE_DIRS
11146 where to find expat.h, etc.
11147 EXPAT_LIBRARIES
11149 the libraries to link against to use Expat.
11150 EXPAT_FOUND
11152 true if the Expat headers and libraries were found.
11153 FindFLEX
11155 Find Fast Lexical Analyzer (Flex) executable and provides a macro to
11156 generate custom build rules
11157 The module defines the following variables:
11159 FLEX_FOUND - True is flex executable is found
11161 FLEX_EXECUTABLE - the path to the flex executable
11162 FLEX_VERSION - the version of flex
11163 FLEX_LIBRARIES - The flex libraries
11164 FLEX_INCLUDE_DIRS - The path to the flex headers
11165 The minimum required version of flex can be specified using the stan‐
11167 dard syntax, e.g. find_package(FLEX 2.5.13)
11168 If flex is found on the system, the module provides the macro:
11170 FLEX_TARGET(Name FlexInput FlexOutput
11172 [COMPILE_FLAGS <string>]
11173 [DEFINES_FILE <string>]
11174 )
11175 which creates a custom command to generate the FlexOutput file from the
11177 FlexInput file. Name is an alias used to get details of this custom
11178 command. If COMPILE_FLAGS option is specified, the next parameter is
11179 added to the flex command line.
11180 New in version 3.5: If flex is configured to output a header file, the
11182 DEFINES_FILE option may be used to specify its name.
11183 Changed in version 3.17: When CMP0098 is set to NEW, flex runs in the
11186 CMAKE_CURRENT_BINARY_DIR directory.
11187 The macro defines the following variables:
11190 FLEX_${Name}_DEFINED - true is the macro ran successfully
11192 FLEX_${Name}_OUTPUTS - the source file generated by the custom rule, an
11193 alias for FlexOutput
11194 FLEX_${Name}_INPUT - the flex source file, an alias for ${FlexInput}
11195 FLEX_${Name}_OUTPUT_HEADER - the header flex output, if any.
11196 Flex scanners often use tokens defined by Bison: the code generated by
11198 Flex depends of the header generated by Bison. This module also de‐
11199 fines a macro:
11200 ADD_FLEX_BISON_DEPENDENCY(FlexTarget BisonTarget)
11202 which adds the required dependency between a scanner and a parser where
11204 FlexTarget and BisonTarget are the first parameters of respectively
11205 FLEX_TARGET and BISON_TARGET macros.
11206 ====================================================================
11208 Example:
11209 find_package(BISON)
11211 find_package(FLEX)
11212 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
11214 FLEX_TARGET(MyScanner lexer.l ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp)
11215 ADD_FLEX_BISON_DEPENDENCY(MyScanner MyParser)
11216 include_directories(${CMAKE_CURRENT_BINARY_DIR})
11218 add_executable(Foo
11219 Foo.cc
11220 ${BISON_MyParser_OUTPUTS}
11221 ${FLEX_MyScanner_OUTPUTS}
11222 )
11223 target_link_libraries(Foo ${FLEX_LIBRARIES})
11224 ====================================================================
11225 FindFLTK
11227 Find the Fast Light Toolkit (FLTK) library
11228 Input Variables
11230 By default this module will search for all of the FLTK components and
11231 add them to the FLTK_LIBRARIES variable. You can limit the components
11232 which get placed in FLTK_LIBRARIES by defining one or more of the fol‐
11233 lowing three options:
11234 FLTK_SKIP_OPENGL
11236 Set to true to disable searching for the FLTK GL library
11237 FLTK_SKIP_FORMS
11239 Set to true to disable searching for the FLTK Forms library
11240 FLTK_SKIP_IMAGES
11242 Set to true to disable searching for the FLTK Images library
11243 FLTK is composed also by a binary tool. You can set the following op‐
11245 tion:
11246 FLTK_SKIP_FLUID
11248 Set to true to not look for the FLUID binary
11249 Result Variables
11251 The following variables will be defined:
11252 FLTK_FOUND
11254 True if all components not skipped were found
11255 FLTK_INCLUDE_DIR
11257 Path to the include directory for FLTK header files
11258 FLTK_LIBRARIES
11260 List of the FLTK libraries found
11261 FLTK_FLUID_EXECUTABLE
11263 Path to the FLUID binary tool
11264 FLTK_WRAP_UI
11266 True if FLUID is found, used to enable the FLTK_WRAP_UI command
11267 Cache Variables
11269 The following cache variables are also available to set or use:
11270 FLTK_BASE_LIBRARY_RELEASE
11272 The FLTK base library (optimized)
11273 FLTK_BASE_LIBRARY_DEBUG
11275 The FLTK base library (debug)
11276 FLTK_GL_LIBRARY_RELEASE
11278 The FLTK GL library (optimized)
11279 FLTK_GL_LIBRARY_DEBUG
11281 The FLTK GL library (debug)
11282 FLTK_FORMS_LIBRARY_RELEASE
11284 The FLTK Forms library (optimized)
11285 FLTK_FORMS_LIBRARY_DEBUG
11287 The FLTK Forms library (debug)
11288 FLTK_IMAGES_LIBRARY_RELEASE
11290 The FLTK Images protobuf library (optimized)
11291 FLTK_IMAGES_LIBRARY_DEBUG
11293 The FLTK Images library (debug)
11294 New in version 3.11: Debug and Release variants are found separately
11296 and use per-configuration variables.
11297 FindFLTK2
11300 Find the native FLTK 2.0 includes and library
11301 The following settings are defined
11303 FLTK2_FLUID_EXECUTABLE, where to find the Fluid tool
11305 FLTK2_WRAP_UI, This enables the FLTK2_WRAP_UI command
11306 FLTK2_INCLUDE_DIR, where to find include files
11307 FLTK2_LIBRARIES, list of fltk2 libraries
11308 FLTK2_FOUND, Don't use FLTK2 if false.
11309 The following settings should not be used in general.
11311 FLTK2_BASE_LIBRARY = the full path to fltk2.lib
11313 FLTK2_GL_LIBRARY = the full path to fltk2_gl.lib
11314 FLTK2_IMAGES_LIBRARY = the full path to fltk2_images.lib
11315 FindFontconfig
11317 New in version 3.14.
11318 Find Fontconfig headers and library.
11321 Imported Targets
11323 Fontconfig::Fontconfig
11324 The Fontconfig library, if found.
11325 Result Variables
11327 This will define the following variables in your project:
11328 Fontconfig_FOUND
11330 true if (the requested version of) Fontconfig is available.
11331 Fontconfig_VERSION
11333 the version of Fontconfig.
11334 Fontconfig_LIBRARIES
11336 the libraries to link against to use Fontconfig.
11337 Fontconfig_INCLUDE_DIRS
11339 where to find the Fontconfig headers.
11340 Fontconfig_COMPILE_OPTIONS
11342 this should be passed to target_compile_options(), if the target
11343 is not used for linking
11344 FindFreetype
11346 Find the FreeType font renderer includes and library.
11347 Imported Targets
11349 New in version 3.10.
11350 This module defines the following IMPORTED target:
11353 Freetype::Freetype
11355 The Freetype freetype library, if found
11356 Result Variables
11358 This module will set the following variables in your project:
11359 FREETYPE_FOUND
11361 true if the Freetype headers and libraries were found
11362 FREETYPE_INCLUDE_DIRS
11364 directories containing the Freetype headers. This is the con‐
11365 catenation of the variables:
11366 FREETYPE_INCLUDE_DIR_ft2build
11368 directory holding the main Freetype API configuration
11369 header
11370 FREETYPE_INCLUDE_DIR_freetype2
11372 directory holding Freetype public headers
11373 FREETYPE_LIBRARIES
11375 the library to link against
11376 FREETYPE_VERSION_STRING
11378 the version of freetype found
11379 New in version 3.7: Debug and Release variants are found separately.
11381 Hints
11384 The user may set the environment variable FREETYPE_DIR to the root di‐
11385 rectory of a Freetype installation.
11386 FindGCCXML
11388 Find the GCC-XML front-end executable.
11389 This module will define the following variables:
11391 GCCXML - the GCC-XML front-end executable.
11393 FindGDAL
11395 Find Geospatial Data Abstraction Library (GDAL).
11396 IMPORTED Targets
11398 New in version 3.14.
11399 This module defines IMPORTED target GDAL::GDAL if GDAL has been found.
11402 Result Variables
11404 This module will set the following variables in your project:
11405 GDAL_FOUND
11407 True if GDAL is found.
11408 GDAL_INCLUDE_DIRS
11410 Include directories for GDAL headers.
11411 GDAL_LIBRARIES
11413 Libraries to link to GDAL.
11414 GDAL_VERSION
11416 New in version 3.14: The version of GDAL found.
11417 Cache variables
11420 The following cache variables may also be set:
11421 GDAL_LIBRARY
11423 The libgdal library file.
11424 GDAL_INCLUDE_DIR
11426 The directory containing gdal.h.
11427 Hints
11429 Set GDAL_DIR or GDAL_ROOT in the environment to specify the GDAL in‐
11430 stallation prefix.
11431 The following variables may be set to modify the search strategy:
11433 FindGDAL_SKIP_GDAL_CONFIG
11435 If set, gdal-config will not be used. This can be useful if
11436 there are GDAL libraries built with autotools (which provide the
11437 tool) and CMake (which do not) in the same environment.
11438 GDAL_ADDITIONAL_LIBRARY_VERSIONS
11440 Extra versions of library names to search for.
11441 FindGettext
11443 Find GNU gettext tools
11444 This module looks for the GNU gettext tools. This module defines the
11446 following values:
11447 GETTEXT_MSGMERGE_EXECUTABLE: the full path to the msgmerge tool.
11449 GETTEXT_MSGFMT_EXECUTABLE: the full path to the msgfmt tool.
11450 GETTEXT_FOUND: True if gettext has been found.
11451 GETTEXT_VERSION_STRING: the version of gettext found (since CMake 2.8.8)
11452 Additionally it provides the following macros:
11454 GETTEXT_CREATE_TRANSLATIONS ( outputFile [ALL] file1 ... fileN )
11456 This will create a target "translations" which will convert the
11458 given input po files into the binary output mo file. If the
11459 ALL option is used, the translations will also be created when
11460 building the default target.
11461 GETTEXT_PROCESS_POT_FILE( <potfile> [ALL] [INSTALL_DESTINATION <dest‐
11463 dir>] LANGUAGES <lang1> <lang2> ... )
11464 Process the given pot file to mo files.
11466 If INSTALL_DESTINATION is given then automatically install rules will
11467 be created, the language subdirectory will be taken into account
11468 (by default use share/locale/).
11469 If ALL is specified, the pot file is processed when building the all target.
11470 It creates a custom target "potfile".
11471 GETTEXT_PROCESS_PO_FILES( <lang> [ALL] [INSTALL_DESTINATION <dir>]
11473 PO_FILES <po1> <po2> ... )
11474 Process the given po files to mo files for the given language.
11476 If INSTALL_DESTINATION is given then automatically install rules will
11477 be created, the language subdirectory will be taken into account
11478 (by default use share/locale/).
11479 If ALL is specified, the po files are processed when building the all target.
11480 It creates a custom target "pofiles".
11481 New in version 3.2: If you wish to use the Gettext library (libintl),
11483 use FindIntl.
11484 FindGIF
11487 This finds the Graphics Interchange Format (GIF) library (giflib)
11488 Imported targets
11490 This module defines the following IMPORTED target:
11491 GIF::GIF
11493 The giflib library, if found.
11494 Result variables
11496 This module will set the following variables in your project:
11497 GIF_FOUND
11499 If false, do not try to use GIF.
11500 GIF_INCLUDE_DIRS
11502 where to find gif_lib.h, etc.
11503 GIF_LIBRARIES
11505 the libraries needed to use GIF.
11506 GIF_VERSION
11508 3, 4 or a full version string (eg 5.1.4) for versions >= 4.1.6.
11509 Cache variables
11511 The following cache variables may also be set:
11512 GIF_INCLUDE_DIR
11514 where to find the GIF headers.
11515 GIF_LIBRARY
11517 where to find the GIF library.
11518 Hints
11520 GIF_DIR is an environment variable that would correspond to the ./con‐
11521 figure --prefix=$GIF_DIR.
11522 FindGit
11524 The module defines the following variables:
11525 GIT_EXECUTABLE
11527 Path to Git command-line client.
11528 Git_FOUND, GIT_FOUND
11530 True if the Git command-line client was found.
11531 GIT_VERSION_STRING
11533 The version of Git found.
11534 New in version 3.14: The module defines the following IMPORTED targets
11536 (when CMAKE_ROLE is PROJECT):
11537 Git::Git
11540 Executable of the Git command-line client.
11541 Example usage:
11543 find_package(Git)
11545 if(Git_FOUND)
11546 message("Git found: ${GIT_EXECUTABLE}")
11547 endif()
11548 FindGLEW
11550 Find the OpenGL Extension Wrangler Library (GLEW)
11551 Input Variables
11553 The following variables may be set to influence this module's behavior:
11554 GLEW_USE_STATIC_LIBS
11556 to find and create IMPORTED target for static linkage.
11557 GLEW_VERBOSE
11559 to output a detailed log of this module.
11560 Imported Targets
11562 New in version 3.1.
11563 This module defines the following Imported Targets:
11566 GLEW::glew
11568 The GLEW shared library.
11569 GLEW::glew_s
11571 The GLEW static library, if GLEW_USE_STATIC_LIBS is set to TRUE.
11572 GLEW::GLEW
11574 Duplicates either GLEW::glew or GLEW::glew_s based on availabil‐
11575 ity.
11576 Result Variables
11578 This module defines the following variables:
11579 GLEW_INCLUDE_DIRS
11581 include directories for GLEW
11582 GLEW_LIBRARIES
11584 libraries to link against GLEW
11585 GLEW_SHARED_LIBRARIES
11587 libraries to link against shared GLEW
11588 GLEW_STATIC_LIBRARIES
11590 libraries to link against static GLEW
11591 GLEW_FOUND
11593 true if GLEW has been found and can be used
11594 GLEW_VERSION
11596 GLEW version
11597 GLEW_VERSION_MAJOR
11599 GLEW major version
11600 GLEW_VERSION_MINOR
11602 GLEW minor version
11603 GLEW_VERSION_MICRO
11605 GLEW micro version
11606 New in version 3.7: Debug and Release variants are found separately.
11608 FindGLUT
11611 Find OpenGL Utility Toolkit (GLUT) library and include files.
11612 IMPORTED Targets
11614 New in version 3.1.
11615 This module defines the IMPORTED targets:
11618 GLUT::GLUT
11620 Defined if the system has GLUT.
11621 Result Variables
11623 This module sets the following variables:
11624 GLUT_INCLUDE_DIR, where to find GL/glut.h, etc.
11626 GLUT_LIBRARIES, the libraries to link against
11627 GLUT_FOUND, If false, do not try to use GLUT.
11628 Also defined, but not for general use are:
11630 GLUT_glut_LIBRARY = the full path to the glut library.
11632 GLUT_Xmu_LIBRARY = the full path to the Xmu library.
11633 GLUT_Xi_LIBRARY = the full path to the Xi Library.
11634 New in version 3.13: Debug and Release variants are found separately.
11636 FindGnuplot
11639 this module looks for gnuplot
11640 Once done this will define
11642 GNUPLOT_FOUND - system has Gnuplot
11644 GNUPLOT_EXECUTABLE - the Gnuplot executable
11645 GNUPLOT_VERSION_STRING - the version of Gnuplot found (since CMake 2.8.8)
11646 GNUPLOT_VERSION_STRING will not work for old versions like 3.7.1.
11648 FindGnuTLS
11650 Find the GNU Transport Layer Security library (gnutls)
11651 IMPORTED Targets
11653 New in version 3.16.
11654 This module defines IMPORTED target GnuTLS::GnuTLS, if gnutls has been
11657 found.
11658 Result Variables
11660 GNUTLS_FOUND
11661 System has gnutls
11662 GNUTLS_INCLUDE_DIR
11664 The gnutls include directory
11665 GNUTLS_LIBRARIES
11667 The libraries needed to use gnutls
11668 GNUTLS_DEFINITIONS
11670 Compiler switches required for using gnutls
11671 GNUTLS_VERSION
11673 version of gnutls.
11674 FindGSL
11676 New in version 3.2.
11677 Find the native GNU Scientific Library (GSL) includes and libraries.
11680 The GNU Scientific Library (GSL) is a numerical library for C and C++
11682 programmers. It is free software under the GNU General Public License.
11683 Imported Targets
11685 If GSL is found, this module defines the following IMPORTED targets:
11686 GSL::gsl - The main GSL library.
11688 GSL::gslcblas - The CBLAS support library used by GSL.
11689 Result Variables
11691 This module will set the following variables in your project:
11692 GSL_FOUND - True if GSL found on the local system
11694 GSL_INCLUDE_DIRS - Location of GSL header files.
11695 GSL_LIBRARIES - The GSL libraries.
11696 GSL_VERSION - The version of the discovered GSL install.
11697 Hints
11699 Set GSL_ROOT_DIR to a directory that contains a GSL installation.
11700 This script expects to find libraries at $GSL_ROOT_DIR/lib and the GSL
11702 headers at $GSL_ROOT_DIR/include/gsl. The library directory may op‐
11703 tionally provide Release and Debug folders. If available, the libraries
11704 named gsld, gslblasd or cblasd are recognized as debug libraries. For
11705 Unix-like systems, this script will use $GSL_ROOT_DIR/bin/gsl-config
11706 (if found) to aid in the discovery of GSL.
11707 Cache Variables
11709 This module may set the following variables depending on platform and
11710 type of GSL installation discovered. These variables may optionally be
11711 set to help this module find the correct files:
11712 GSL_CBLAS_LIBRARY - Location of the GSL CBLAS library.
11714 GSL_CBLAS_LIBRARY_DEBUG - Location of the debug GSL CBLAS library (if any).
11715 GSL_CONFIG_EXECUTABLE - Location of the ``gsl-config`` script (if any).
11716 GSL_LIBRARY - Location of the GSL library.
11717 GSL_LIBRARY_DEBUG - Location of the debug GSL library (if any).
11718 FindGTest
11720 Locate the Google C++ Testing Framework.
11721 New in version 3.20: Upstream GTestConfig.cmake is used if possible.
11723 Imported targets
11726 New in version 3.20: This module defines the following IMPORTED tar‐
11727 gets:
11728 GTest::gtest
11731 The Google Test gtest library, if found; adds Thread::Thread au‐
11732 tomatically
11733 GTest::gtest_main
11735 The Google Test gtest_main library, if found
11736 Deprecated since version 3.20: For backwards compatibility, this module
11738 defines additionally the following deprecated IMPORTED targets (avail‐
11739 able since 3.5):
11740 GTest::GTest
11743 The Google Test gtest library, if found; adds Thread::Thread au‐
11744 tomatically
11745 GTest::Main
11747 The Google Test gtest_main library, if found
11748 Result variables
11750 This module will set the following variables in your project:
11751 GTest_FOUND
11753 Found the Google Testing framework
11754 GTEST_INCLUDE_DIRS
11756 the directory containing the Google Test headers
11757 The library variables below are set as normal variables. These contain
11759 debug/optimized keywords when a debugging library is found.
11760 GTEST_LIBRARIES
11762 The Google Test gtest library; note it also requires linking
11763 with an appropriate thread library
11764 GTEST_MAIN_LIBRARIES
11766 The Google Test gtest_main library
11767 GTEST_BOTH_LIBRARIES
11769 Both gtest and gtest_main
11770 Cache variables
11772 The following cache variables may also be set:
11773 GTEST_ROOT
11775 The root directory of the Google Test installation (may also be
11776 set as an environment variable)
11777 GTEST_MSVC_SEARCH
11779 If compiling with MSVC, this variable can be set to MT or MD
11780 (the default) to enable searching a GTest build tree
11781 Example usage
11783 enable_testing()
11784 find_package(GTest REQUIRED)
11785 add_executable(foo foo.cc)
11787 target_link_libraries(foo GTest::gtest GTest::gtest_main)
11788 add_test(AllTestsInFoo foo)
11790 Deeper integration with CTest
11792 See GoogleTest for information on the gtest_add_tests() and gtest_dis‐
11793 cover_tests() commands.
11794 Changed in version 3.9: Previous CMake versions defined
11796 gtest_add_tests() macro in this module.
11797 FindGTK
11800 Find GTK, glib and GTKGLArea
11801 GTK_INCLUDE_DIR - Directories to include to use GTK
11803 GTK_LIBRARIES - Files to link against to use GTK
11804 GTK_FOUND - GTK was found
11805 GTK_GL_FOUND - GTK's GL features were found
11806 FindGTK2
11808 Find the GTK2 widget libraries and several of its other optional compo‐
11809 nents like gtkmm, glade, and glademm.
11810 Specify one or more of the following components as you call this find
11812 module. See example below.
11813 • gtk
11815 • gtkmm
11817 • glade
11819 • glademm
11821 Imported Targets
11823 This module defines the following IMPORTED targets (subject to compo‐
11824 nent selection):
11825 GTK2::atk, GTK2::atkmm, GTK2::cairo, GTK2::cairomm, GTK2::gdk_pixbuf,
11827 GTK2::gdk, GTK2::gdkmm, GTK2::gio, GTK2::giomm, GTK2::glade,
11828 GTK2::glademm, GTK2::glib, GTK2::glibmm, GTK2::gmodule, GTK2::gobject,
11829 GTK2::gthread, GTK2::gtk, GTK2::gtkmm, GTK2::harfbuzz, GTK2::pango,
11830 GTK2::pangocairo, GTK2::pangoft2, GTK2::pangomm, GTK2::pangoxft,
11831 GTK2::sigc.
11832 New in version 3.16.7: Added the GTK2::harfbuzz target.
11834 Result Variables
11837 The following variables will be defined for your use
11838 GTK2_FOUND
11840 Were all of your specified components found?
11841 GTK2_INCLUDE_DIRS
11843 All include directories
11844 GTK2_LIBRARIES
11846 All libraries
11847 GTK2_TARGETS
11849 New in version 3.5: All imported targets
11850 GTK2_DEFINITIONS
11853 Additional compiler flags
11854 GTK2_VERSION
11856 The version of GTK2 found (x.y.z)
11857 GTK2_MAJOR_VERSION
11859 The major version of GTK2
11860 GTK2_MINOR_VERSION
11862 The minor version of GTK2
11863 GTK2_PATCH_VERSION
11865 The patch version of GTK2
11866 New in version 3.5: When GTK2_USE_IMPORTED_TARGETS is set to TRUE,
11868 GTK2_LIBRARIES will list imported targets instead of library paths.
11869 Input Variables
11872 Optional variables you can define prior to calling this module:
11873 GTK2_DEBUG
11875 Enables verbose debugging of the module
11876 GTK2_ADDITIONAL_SUFFIXES
11878 Allows defining additional directories to search for include
11879 files
11880 Example Usage
11882 Call find_package() once. Here are some examples to pick from:
11883 Require GTK 2.6 or later:
11885 find_package(GTK2 2.6 REQUIRED gtk)
11887 Require GTK 2.10 or later and Glade:
11889 find_package(GTK2 2.10 REQUIRED gtk glade)
11891 Search for GTK/GTKMM 2.8 or later:
11893 find_package(GTK2 2.8 COMPONENTS gtk gtkmm)
11895 Use the results:
11897 if(GTK2_FOUND)
11899 include_directories(${GTK2_INCLUDE_DIRS})
11900 add_executable(mygui mygui.cc)
11901 target_link_libraries(mygui ${GTK2_LIBRARIES})
11902 endif()
11903 FindHDF5
11905 Find Hierarchical Data Format (HDF5), a library for reading and writing
11906 self describing array data.
11907 This module invokes the HDF5 wrapper compiler that should be installed
11909 alongside HDF5. Depending upon the HDF5 Configuration, the wrapper
11910 compiler is called either h5cc or h5pcc. If this succeeds, the module
11911 will then call the compiler with the show argument to see what flags
11912 are used when compiling an HDF5 client application.
11913 The module will optionally accept the COMPONENTS argument. If no COM‐
11915 PONENTS are specified, then the find module will default to finding
11916 only the HDF5 C library. If one or more COMPONENTS are specified, the
11917 module will attempt to find the language bindings for the specified
11918 components. The valid components are C, CXX, Fortran, HL. HL refers
11919 to the "high-level" HDF5 functions for C and Fortran. If the COMPO‐
11920 NENTS argument is not given, the module will attempt to find only the C
11921 bindings. For example, to use Fortran HDF5 and HDF5-HL functions, do:
11922 find_package(HDF5 COMPONENTS Fortran HL).
11923 This module will read the variable HDF5_USE_STATIC_LIBRARIES to deter‐
11925 mine whether or not to prefer a static link to a dynamic link for HDF5
11926 and all of it's dependencies. To use this feature, make sure that the
11927 HDF5_USE_STATIC_LIBRARIES variable is set before the call to find_pack‐
11928 age.
11929 New in version 3.10: Support for HDF5_USE_STATIC_LIBRARIES on Windows.
11931 Both the serial and parallel HDF5 wrappers are considered and the first
11934 directory to contain either one will be used. In the event that both
11935 appear in the same directory the serial version is preferentially se‐
11936 lected. This behavior can be reversed by setting the variable HDF5_PRE‐
11937 FER_PARALLEL to TRUE.
11938 In addition to finding the includes and libraries required to compile
11940 an HDF5 client application, this module also makes an effort to find
11941 tools that come with the HDF5 distribution that may be useful for re‐
11942 gression testing.
11943 Result Variables
11945 This module will set the following variables in your project:
11946 HDF5_FOUND
11948 HDF5 was found on the system
11949 HDF5_VERSION
11951 New in version 3.3: HDF5 library version
11952 HDF5_INCLUDE_DIRS
11955 Location of the HDF5 header files
11956 HDF5_DEFINITIONS
11958 Required compiler definitions for HDF5
11959 HDF5_LIBRARIES
11961 Required libraries for all requested bindings
11962 HDF5_HL_LIBRARIES
11964 Required libraries for the HDF5 high level API for all bindings,
11965 if the HL component is enabled
11966 Available components are: C CXX Fortran and HL. For each enabled lan‐
11968 guage binding, a corresponding HDF5_${LANG}_LIBRARIES variable, and po‐
11969 tentially HDF5_${LANG}_DEFINITIONS, will be defined. If the HL compo‐
11970 nent is enabled, then an HDF5_${LANG}_HL_LIBRARIES will also be de‐
11971 fined. With all components enabled, the following variables will be
11972 defined:
11973 HDF5_C_DEFINITIONS
11975 Required compiler definitions for HDF5 C bindings
11976 HDF5_CXX_DEFINITIONS
11978 Required compiler definitions for HDF5 C++ bindings
11979 HDF5_Fortran_DEFINITIONS
11981 Required compiler definitions for HDF5 Fortran bindings
11982 HDF5_C_INCLUDE_DIRS
11984 Required include directories for HDF5 C bindings
11985 HDF5_CXX_INCLUDE_DIRS
11987 Required include directories for HDF5 C++ bindings
11988 HDF5_Fortran_INCLUDE_DIRS
11990 Required include directories for HDF5 Fortran bindings
11991 HDF5_C_LIBRARIES
11993 Required libraries for the HDF5 C bindings
11994 HDF5_CXX_LIBRARIES
11996 Required libraries for the HDF5 C++ bindings
11997 HDF5_Fortran_LIBRARIES
11999 Required libraries for the HDF5 Fortran bindings
12000 HDF5_C_HL_LIBRARIES
12002 Required libraries for the high level C bindings
12003 HDF5_CXX_HL_LIBRARIES
12005 Required libraries for the high level C++ bindings
12006 HDF5_Fortran_HL_LIBRARIES
12008 Required libraries for the high level Fortran bindings.
12009 HDF5_IS_PARALLEL
12011 HDF5 library has parallel IO support
12012 HDF5_C_COMPILER_EXECUTABLE
12014 path to the HDF5 C wrapper compiler
12015 HDF5_CXX_COMPILER_EXECUTABLE
12017 path to the HDF5 C++ wrapper compiler
12018 HDF5_Fortran_COMPILER_EXECUTABLE
12020 path to the HDF5 Fortran wrapper compiler
12021 HDF5_C_COMPILER_EXECUTABLE_NO_INTERROGATE
12023 path to the primary C compiler which is also the HDF5 wrapper
12024 HDF5_CXX_COMPILER_EXECUTABLE_NO_INTERROGATE
12026 path to the primary C++ compiler which is also the HDF5 wrapper
12027 HDF5_Fortran_COMPILER_EXECUTABLE_NO_INTERROGATE
12029 path to the primary Fortran compiler which is also the HDF5
12030 wrapper
12031 HDF5_DIFF_EXECUTABLE
12033 path to the HDF5 dataset comparison tool
12034 With all components enabled, the following targets will be defined:
12036 HDF5::HDF5
12038 All detected HDF5_LIBRARIES.
12039 hdf5::hdf5
12041 C library.
12042 hdf5::hdf5_cpp
12044 C++ library.
12045 hdf5::hdf5_fortran
12047 Fortran library.
12048 hdf5::hdf5_hl
12050 High-level C library.
12051 hdf5::hdf5_hl_cpp
12053 High-level C++ library.
12054 hdf5::hdf5_hl_fortran
12056 High-level Fortran library.
12057 hdf5::h5diff
12059 h5diff executable.
12060 Hints
12062 The following variables can be set to guide the search for HDF5 li‐
12063 braries and includes:
12064 HDF5_PREFER_PARALLEL
12066 New in version 3.4.
12067 set true to prefer parallel HDF5 (by default, serial is pre‐
12070 ferred)
12071 HDF5_FIND_DEBUG
12073 New in version 3.9.
12074 Set true to get extra debugging output.
12077 HDF5_NO_FIND_PACKAGE_CONFIG_FILE
12079 New in version 3.8.
12080 Set true to skip trying to find hdf5-config.cmake.
12083 FindHg
12085 Extract information from a mercurial working copy.
12086 The module defines the following variables:
12088 HG_EXECUTABLE - path to mercurial command line client (hg)
12090 HG_FOUND - true if the command line client was found
12091 HG_VERSION_STRING - the version of mercurial found
12092 New in version 3.1: If the command line client executable is found the
12094 following macro is defined:
12095 HG_WC_INFO(<dir> <var-prefix>)
12098 Hg_WC_INFO extracts information of a mercurial working copy at a given
12100 location. This macro defines the following variables:
12101 <var-prefix>_WC_CHANGESET - current changeset
12103 <var-prefix>_WC_REVISION - current revision
12104 Example usage:
12106 find_package(Hg)
12108 if(HG_FOUND)
12109 message("hg found: ${HG_EXECUTABLE}")
12110 HG_WC_INFO(${PROJECT_SOURCE_DIR} Project)
12111 message("Current revision is ${Project_WC_REVISION}")
12112 message("Current changeset is ${Project_WC_CHANGESET}")
12113 endif()
12114 FindHSPELL
12116 Try to find Hebrew spell-checker (Hspell) and morphology engine.
12117 Once done this will define
12119 HSPELL_FOUND - system has Hspell
12121 HSPELL_INCLUDE_DIR - the Hspell include directory
12122 HSPELL_LIBRARIES - The libraries needed to use Hspell
12123 HSPELL_DEFINITIONS - Compiler switches required for using Hspell
12124 HSPELL_VERSION_STRING - The version of Hspell found (x.y)
12126 HSPELL_MAJOR_VERSION - the major version of Hspell
12127 HSPELL_MINOR_VERSION - The minor version of Hspell
12128 FindHTMLHelp
12130 This module looks for Microsoft HTML Help Compiler
12131 It defines:
12133 HTML_HELP_COMPILER : full path to the Compiler (hhc.exe)
12135 HTML_HELP_INCLUDE_PATH : include path to the API (htmlhelp.h)
12136 HTML_HELP_LIBRARY : full path to the library (htmlhelp.lib)
12137 FindIce
12139 New in version 3.1.
12140 Find the ZeroC Internet Communication Engine (ICE) programs, libraries
12143 and datafiles.
12144 This module supports multiple components. Components can include any
12146 of: Freeze, Glacier2, Ice, IceBox, IceDB, IceDiscovery, IceGrid, IceLo‐
12147 catorDiscovery, IcePatch, IceSSL, IceStorm, IceUtil, IceXML, or Slice.
12148 Ice 3.7 and later also include C++11-specific components: Glacier2++11,
12150 Ice++11, IceBox++11, IceDiscovery++11 IceGrid, IceLocatorDiscovery++11,
12151 IceSSL++11, IceStorm++11
12152 Note that the set of supported components is Ice version-specific.
12154 New in version 3.4: Imported targets for components and most EXECUTABLE
12156 variables.
12157 New in version 3.7: Debug and Release variants are found separately.
12160 New in version 3.10: Ice 3.7 support, including new components, pro‐
12163 grams and the Nuget package.
12164 This module reports information about the Ice installation in several
12167 variables. General variables:
12168 Ice_VERSION - Ice release version
12170 Ice_FOUND - true if the main programs and libraries were found
12171 Ice_LIBRARIES - component libraries to be linked
12172 Ice_INCLUDE_DIRS - the directories containing the Ice headers
12173 Ice_SLICE_DIRS - the directories containing the Ice slice interface
12174 definitions
12175 Imported targets:
12177 Ice::<C>
12179 Where <C> is the name of an Ice component, for example Ice::Glacier2 or
12181 Ice++11.
12182 Ice slice programs are reported in:
12184 Ice_SLICE2CONFLUENCE_EXECUTABLE - path to slice2confluence executable
12186 Ice_SLICE2CPP_EXECUTABLE - path to slice2cpp executable
12187 Ice_SLICE2CS_EXECUTABLE - path to slice2cs executable
12188 Ice_SLICE2FREEZEJ_EXECUTABLE - path to slice2freezej executable
12189 Ice_SLICE2FREEZE_EXECUTABLE - path to slice2freeze executable
12190 Ice_SLICE2HTML_EXECUTABLE - path to slice2html executable
12191 Ice_SLICE2JAVA_EXECUTABLE - path to slice2java executable
12192 Ice_SLICE2JS_EXECUTABLE - path to slice2js executable
12193 Ice_SLICE2MATLAB_EXECUTABLE - path to slice2matlab executable
12194 Ice_SLICE2OBJC_EXECUTABLE - path to slice2objc executable
12195 Ice_SLICE2PHP_EXECUTABLE - path to slice2php executable
12196 Ice_SLICE2PY_EXECUTABLE - path to slice2py executable
12197 Ice_SLICE2RB_EXECUTABLE - path to slice2rb executable
12198 New in version 3.14: Variables for slice2confluence and slice2matlab.
12200 Ice programs are reported in:
12203 Ice_GLACIER2ROUTER_EXECUTABLE - path to glacier2router executable
12205 Ice_ICEBOX_EXECUTABLE - path to icebox executable
12206 Ice_ICEBOXXX11_EXECUTABLE - path to icebox++11 executable
12207 Ice_ICEBOXADMIN_EXECUTABLE - path to iceboxadmin executable
12208 Ice_ICEBOXD_EXECUTABLE - path to iceboxd executable
12209 Ice_ICEBOXNET_EXECUTABLE - path to iceboxnet executable
12210 Ice_ICEBRIDGE_EXECUTABLE - path to icebridge executable
12211 Ice_ICEGRIDADMIN_EXECUTABLE - path to icegridadmin executable
12212 Ice_ICEGRIDDB_EXECUTABLE - path to icegriddb executable
12213 Ice_ICEGRIDNODE_EXECUTABLE - path to icegridnode executable
12214 Ice_ICEGRIDNODED_EXECUTABLE - path to icegridnoded executable
12215 Ice_ICEGRIDREGISTRY_EXECUTABLE - path to icegridregistry executable
12216 Ice_ICEGRIDREGISTRYD_EXECUTABLE - path to icegridregistryd executable
12217 Ice_ICEPATCH2CALC_EXECUTABLE - path to icepatch2calc executable
12218 Ice_ICEPATCH2CLIENT_EXECUTABLE - path to icepatch2client executable
12219 Ice_ICEPATCH2SERVER_EXECUTABLE - path to icepatch2server executable
12220 Ice_ICESERVICEINSTALL_EXECUTABLE - path to iceserviceinstall executable
12221 Ice_ICESTORMADMIN_EXECUTABLE - path to icestormadmin executable
12222 Ice_ICESTORMDB_EXECUTABLE - path to icestormdb executable
12223 Ice_ICESTORMMIGRATE_EXECUTABLE - path to icestormmigrate executable
12224 Ice db programs (Windows only; standard system versions on all other
12226 platforms) are reported in:
12227 Ice_DB_ARCHIVE_EXECUTABLE - path to db_archive executable
12229 Ice_DB_CHECKPOINT_EXECUTABLE - path to db_checkpoint executable
12230 Ice_DB_DEADLOCK_EXECUTABLE - path to db_deadlock executable
12231 Ice_DB_DUMP_EXECUTABLE - path to db_dump executable
12232 Ice_DB_HOTBACKUP_EXECUTABLE - path to db_hotbackup executable
12233 Ice_DB_LOAD_EXECUTABLE - path to db_load executable
12234 Ice_DB_LOG_VERIFY_EXECUTABLE - path to db_log_verify executable
12235 Ice_DB_PRINTLOG_EXECUTABLE - path to db_printlog executable
12236 Ice_DB_RECOVER_EXECUTABLE - path to db_recover executable
12237 Ice_DB_STAT_EXECUTABLE - path to db_stat executable
12238 Ice_DB_TUNER_EXECUTABLE - path to db_tuner executable
12239 Ice_DB_UPGRADE_EXECUTABLE - path to db_upgrade executable
12240 Ice_DB_VERIFY_EXECUTABLE - path to db_verify executable
12241 Ice_DUMPDB_EXECUTABLE - path to dumpdb executable
12242 Ice_TRANSFORMDB_EXECUTABLE - path to transformdb executable
12243 Ice component libraries are reported in:
12245 Ice_<C>_FOUND - ON if component was found
12247 Ice_<C>_LIBRARIES - libraries for component
12248 Note that <C> is the uppercased name of the component.
12250 This module reads hints about search results from:
12252 Ice_HOME - the root of the Ice installation
12254 The environment variable ICE_HOME may also be used; the Ice_HOME vari‐
12256 able takes precedence.
12257 NOTE:
12259 On Windows, Ice 3.7.0 and later provide libraries via the NuGet
12260 package manager. Appropriate NuGet packages will be searched for
12261 using CMAKE_PREFIX_PATH, or alternatively Ice_HOME may be set to the
12262 location of a specific NuGet package to restrict the search.
12263 The following cache variables may also be set:
12265 Ice_<P>_EXECUTABLE - the path to executable <P>
12267 Ice_INCLUDE_DIR - the directory containing the Ice headers
12268 Ice_SLICE_DIR - the directory containing the Ice slice interface
12269 definitions
12270 Ice_<C>_LIBRARY - the library for component <C>
12271 NOTE:
12273 In most cases none of the above variables will require setting, un‐
12274 less multiple Ice versions are available and a specific version is
12275 required. On Windows, the most recent version of Ice will be found
12276 through the registry. On Unix, the programs, headers and libraries
12277 will usually be in standard locations, but Ice_SLICE_DIRS might not
12278 be automatically detected (commonly known locations are searched).
12279 All the other variables are defaulted using Ice_HOME, if set. It's
12280 possible to set Ice_HOME and selectively specify alternative loca‐
12281 tions for the other components; this might be required for e.g.
12282 newer versions of Visual Studio if the heuristics are not sufficient
12283 to identify the correct programs and libraries for the specific Vis‐
12284 ual Studio version.
12285 Other variables one may set to control this module are:
12287 Ice_DEBUG - Set to ON to enable debug output from FindIce.
12289 FindIconv
12291 New in version 3.11.
12292 This module finds the iconv() POSIX.1 functions on the system. These
12295 functions might be provided in the regular C library or externally in
12296 the form of an additional library.
12297 The following variables are provided to indicate iconv support:
12299 Iconv_FOUND
12301 Variable indicating if the iconv support was found.
12302 Iconv_INCLUDE_DIRS
12304 The directories containing the iconv headers.
12305 Iconv_LIBRARIES
12307 The iconv libraries to be linked.
12308 Iconv_VERSION
12310 New in version 3.21.
12311 The version of iconv found (x.y)
12314 Iconv_VERSION_MAJOR
12316 New in version 3.21.
12317 The major version of iconv
12320 Iconv_VERSION_MINOR
12322 New in version 3.21.
12323 The minor version of iconv
12326 Iconv_IS_BUILT_IN
12328 A variable indicating whether iconv support is stemming from the
12329 C library or not. Even if the C library provides iconv(), the
12330 presence of an external libiconv implementation might lead to
12331 this being false.
12332 Additionally, the following IMPORTED target is being provided:
12334 Iconv::Iconv
12336 Imported target for using iconv.
12337 The following cache variables may also be set:
12339 Iconv_INCLUDE_DIR
12341 The directory containing the iconv headers.
12342 Iconv_LIBRARY
12344 The iconv library (if not implicitly given in the C library).
12345 NOTE:
12347 On POSIX platforms, iconv might be part of the C library and the
12348 cache variables Iconv_INCLUDE_DIR and Iconv_LIBRARY might be empty.
12349 NOTE:
12351 Some libiconv implementations don't embed the version number in
12352 their header files. In this case the variables Iconv_VERSION* will
12353 be empty.
12354 FindIcotool
12356 Find icotool
12357 This module looks for icotool. Convert and create Win32 icon and cursor
12359 files. This module defines the following values:
12360 ICOTOOL_EXECUTABLE: the full path to the icotool tool.
12362 ICOTOOL_FOUND: True if icotool has been found.
12363 ICOTOOL_VERSION_STRING: the version of icotool found.
12364 FindICU
12366 New in version 3.7.
12367 Find the International Components for Unicode (ICU) libraries and pro‐
12370 grams.
12371 This module supports multiple components. Components can include any
12373 of: data, i18n, io, le, lx, test, tu and uc.
12374 Note that on Windows data is named dt and i18n is named in; any of the
12376 names may be used, and the appropriate platform-specific library name
12377 will be automatically selected.
12378 New in version 3.11: Added support for static libraries on Windows.
12380 This module reports information about the ICU installation in several
12383 variables. General variables:
12384 ICU_VERSION - ICU release version
12386 ICU_FOUND - true if the main programs and libraries were found
12387 ICU_LIBRARIES - component libraries to be linked
12388 ICU_INCLUDE_DIRS - the directories containing the ICU headers
12389 Imported targets:
12391 ICU::<C>
12393 Where <C> is the name of an ICU component, for example ICU::i18n; <C>
12395 is lower-case.
12396 ICU programs are reported in:
12398 ICU_GENCNVAL_EXECUTABLE - path to gencnval executable
12400 ICU_ICUINFO_EXECUTABLE - path to icuinfo executable
12401 ICU_GENBRK_EXECUTABLE - path to genbrk executable
12402 ICU_ICU-CONFIG_EXECUTABLE - path to icu-config executable
12403 ICU_GENRB_EXECUTABLE - path to genrb executable
12404 ICU_GENDICT_EXECUTABLE - path to gendict executable
12405 ICU_DERB_EXECUTABLE - path to derb executable
12406 ICU_PKGDATA_EXECUTABLE - path to pkgdata executable
12407 ICU_UCONV_EXECUTABLE - path to uconv executable
12408 ICU_GENCFU_EXECUTABLE - path to gencfu executable
12409 ICU_MAKECONV_EXECUTABLE - path to makeconv executable
12410 ICU_GENNORM2_EXECUTABLE - path to gennorm2 executable
12411 ICU_GENCCODE_EXECUTABLE - path to genccode executable
12412 ICU_GENSPREP_EXECUTABLE - path to gensprep executable
12413 ICU_ICUPKG_EXECUTABLE - path to icupkg executable
12414 ICU_GENCMN_EXECUTABLE - path to gencmn executable
12415 ICU component libraries are reported in:
12417 ICU_<C>_FOUND - ON if component was found; ``<C>`` is upper-case.
12419 ICU_<C>_LIBRARIES - libraries for component; ``<C>`` is upper-case.
12420 ICU datafiles are reported in:
12422 ICU_MAKEFILE_INC - Makefile.inc
12424 ICU_PKGDATA_INC - pkgdata.inc
12425 This module reads hints about search results from:
12427 ICU_ROOT - the root of the ICU installation
12429 The environment variable ICU_ROOT may also be used; the ICU_ROOT vari‐
12431 able takes precedence.
12432 The following cache variables may also be set:
12434 ICU_<P>_EXECUTABLE - the path to executable <P>; ``<P>`` is upper-case.
12436 ICU_INCLUDE_DIR - the directory containing the ICU headers
12437 ICU_<C>_LIBRARY - the library for component <C>; ``<C>`` is upper-case.
12438 NOTE:
12440 In most cases none of the above variables will require setting, un‐
12441 less multiple ICU versions are available and a specific version is
12442 required.
12443 Other variables one may set to control this module are:
12445 ICU_DEBUG - Set to ON to enable debug output from FindICU.
12447 FindImageMagick
12449 Find ImageMagick binary suite.
12450 New in version 3.9: Added support for ImageMagick 7.
12452 This module will search for a set of ImageMagick tools specified as
12455 components in the find_package() call. Typical components include, but
12456 are not limited to (future versions of ImageMagick might have addi‐
12457 tional components not listed here):
12458 animate
12460 compare
12461 composite
12462 conjure
12463 convert
12464 display
12465 identify
12466 import
12467 mogrify
12468 montage
12469 stream
12470 If no component is specified in the find_package() call, then it only
12472 searches for the ImageMagick executable directory. This code defines
12473 the following variables:
12474 ImageMagick_FOUND - TRUE if all components are found.
12476 ImageMagick_EXECUTABLE_DIR - Full path to executables directory.
12477 ImageMagick_<component>_FOUND - TRUE if <component> is found.
12478 ImageMagick_<component>_EXECUTABLE - Full path to <component> executable.
12479 ImageMagick_VERSION_STRING - the version of ImageMagick found
12480 (since CMake 2.8.8)
12481 ImageMagick_VERSION_STRING will not work for old versions like 5.2.3.
12483 There are also components for the following ImageMagick APIs:
12485 Magick++
12487 MagickWand
12488 MagickCore
12489 For these components the following variables are set:
12491 ImageMagick_FOUND - TRUE if all components are found.
12493 ImageMagick_INCLUDE_DIRS - Full paths to all include dirs.
12494 ImageMagick_LIBRARIES - Full paths to all libraries.
12495 ImageMagick_<component>_FOUND - TRUE if <component> is found.
12496 ImageMagick_<component>_INCLUDE_DIRS - Full path to <component> include dirs.
12497 ImageMagick_<component>_LIBRARIES - Full path to <component> libraries.
12498 Example Usages:
12500 find_package(ImageMagick)
12502 find_package(ImageMagick COMPONENTS convert)
12503 find_package(ImageMagick COMPONENTS convert mogrify display)
12504 find_package(ImageMagick COMPONENTS Magick++)
12505 find_package(ImageMagick COMPONENTS Magick++ convert)
12506 Note that the standard find_package() features are supported (i.e.,
12508 QUIET, REQUIRED, etc.).
12509 FindIntl
12511 New in version 3.2.
12512 Find the Gettext libintl headers and libraries.
12515 This module reports information about the Gettext libintl installation
12517 in several variables.
12518 Intl_FOUND
12520 True if libintl is found.
12521 Intl_INCLUDE_DIRS
12523 The directory containing the libintl headers.
12524 Intl_LIBRARIES
12526 The intl libraries to be linked.
12527 Intl_VERSION
12529 New in version 3.21.
12530 The version of intl found (x.y.z)
12533 Intl_VERSION_MAJOR
12535 New in version 3.21.
12536 The major version of intl
12539 Intl_VERSION_MINOR
12541 New in version 3.21.
12542 The minor version of intl
12545 Intl_VERSION_PATCH
12547 New in version 3.21.
12548 The patch version of intl
12551 New in version 3.20: This module defines IMPORTED target Intl::Intl.
12553 The following cache variables may also be set:
12556 Intl_INCLUDE_DIR
12558 The directory containing the libintl headers
12559 Intl_LIBRARY
12561 The libintl library (if any)
12562 Intl_IS_BUILT_IN
12564 New in version 3.20.
12565 whether intl is a part of the C library.
12568 NOTE:
12570 On some platforms, such as Linux with GNU libc, the gettext func‐
12571 tions are present in the C standard library and libintl is not re‐
12572 quired. Intl_LIBRARIES will be empty in this case.
12573 NOTE:
12575 Some libintl implementations don't embed the version number in their
12576 header files. In this case the variables Intl_VERSION* will be
12577 empty.
12578 NOTE:
12580 If you wish to use the Gettext tools (msgmerge, msgfmt, etc.), use
12581 FindGettext.
12582 FindITK
12584 This module no longer exists.
12585 This module existed in versions of CMake prior to 3.1, but became only
12587 a thin wrapper around find_package(ITK NO_MODULE) to provide compati‐
12588 bility for projects using long-outdated conventions. Now find_pack‐
12589 age(ITK) will search for ITKConfig.cmake directly.
12590 FindJasper
12592 Find the Jasper JPEG2000 library.
12593 IMPORTED Targets
12595 Jasper::Jasper
12596 The jasper library, if found.
12597 Result Variables
12599 This module defines the following variables:
12600 JASPER_FOUND
12602 system has Jasper
12603 JASPER_INCLUDE_DIRS
12605 New in version 3.22.
12606 the Jasper include directory
12609 JASPER_LIBRARIES
12611 the libraries needed to use Jasper
12612 JASPER_VERSION_STRING
12614 the version of Jasper found
12615 Cache variables
12617 The following cache variables may also be set:
12618 JASPER_INCLUDE_DIR
12620 where to find jasper/jasper.h, etc.
12621 JASPER_LIBRARY_RELEASE
12623 where to find the Jasper library (optimized).
12624 JASPER_LIBARRY_DEBUG
12626 where to find the Jasper library (debug).
12627 FindJava
12629 Find Java
12630 This module finds if Java is installed and determines where the include
12632 files and libraries are. The caller may set variable JAVA_HOME to
12633 specify a Java installation prefix explicitly.
12634 See also the FindJNI module to find Java Native Interface (JNI).
12636 New in version 3.10: Added support for Java 9+ version parsing.
12638 Specify one or more of the following components as you call this find
12641 module. See example below.
12642 Runtime = Java Runtime Environment used to execute Java byte-compiled applications
12644 Development = Development tools (java, javac, javah, jar and javadoc), includes Runtime component
12645 IdlJ = Interface Description Language (IDL) to Java compiler
12646 JarSigner = Signer and verifier tool for Java Archive (JAR) files
12647 This module sets the following result variables:
12649 Java_JAVA_EXECUTABLE = the full path to the Java runtime
12651 Java_JAVAC_EXECUTABLE = the full path to the Java compiler
12652 Java_JAVAH_EXECUTABLE = the full path to the Java header generator
12653 Java_JAVADOC_EXECUTABLE = the full path to the Java documentation generator
12654 Java_IDLJ_EXECUTABLE = the full path to the Java idl compiler
12655 Java_JAR_EXECUTABLE = the full path to the Java archiver
12656 Java_JARSIGNER_EXECUTABLE = the full path to the Java jar signer
12657 Java_VERSION_STRING = Version of java found, eg. 1.6.0_12
12658 Java_VERSION_MAJOR = The major version of the package found.
12659 Java_VERSION_MINOR = The minor version of the package found.
12660 Java_VERSION_PATCH = The patch version of the package found.
12661 Java_VERSION_TWEAK = The tweak version of the package found (after '_')
12662 Java_VERSION = This is set to: $major[.$minor[.$patch[.$tweak]]]
12663 New in version 3.4: Added the Java_IDLJ_EXECUTABLE and Java_JAR‐
12665 SIGNER_EXECUTABLE variables.
12666 The minimum required version of Java can be specified using the
12669 find_package() syntax, e.g.
12670 find_package(Java 1.8)
12672 NOTE: ${Java_VERSION} and ${Java_VERSION_STRING} are not guaranteed to
12674 be identical. For example some java version may return: Java_VER‐
12675 SION_STRING = 1.8.0_17 and Java_VERSION = 1.8.0.17
12676 another example is the Java OEM, with: Java_VERSION_STRING = 1.8.0-oem
12678 and Java_VERSION = 1.8.0
12679 For these components the following variables are set:
12681 Java_FOUND - TRUE if all components are found.
12683 Java_<component>_FOUND - TRUE if <component> is found.
12684 Example Usages:
12686 find_package(Java)
12688 find_package(Java 1.8 REQUIRED)
12689 find_package(Java COMPONENTS Runtime)
12690 find_package(Java COMPONENTS Development)
12691 FindJNI
12693 Find Java Native Interface (JNI) libraries.
12694 JNI enables Java code running in a Java Virtual Machine (JVM) to call
12696 and be called by native applications and libraries written in other
12697 languages such as C, C++.
12698 This module finds if Java is installed and determines where the include
12700 files and libraries are. It also determines what the name of the li‐
12701 brary is. The caller may set variable JAVA_HOME to specify a Java in‐
12702 stallation prefix explicitly.
12703 Result Variables
12705 This module sets the following result variables:
12706 JNI_INCLUDE_DIRS
12708 the include dirs to use
12709 JNI_LIBRARIES
12711 the libraries to use (JAWT and JVM)
12712 JNI_FOUND
12714 TRUE if JNI headers and libraries were found.
12715 Cache Variables
12717 The following cache variables are also available to set or use:
12718 JAVA_AWT_LIBRARY
12720 the path to the Java AWT Native Interface (JAWT) library
12721 JAVA_JVM_LIBRARY
12723 the path to the Java Virtual Machine (JVM) library
12724 JAVA_INCLUDE_PATH
12726 the include path to jni.h
12727 JAVA_INCLUDE_PATH2
12729 the include path to jni_md.h and jniport.h
12730 JAVA_AWT_INCLUDE_PATH
12732 the include path to jawt.h
12733 FindJPEG
12735 Find the Joint Photographic Experts Group (JPEG) library (libjpeg)
12736 Imported targets
12738 New in version 3.12.
12739 This module defines the following IMPORTED targets:
12742 JPEG::JPEG
12744 The JPEG library, if found.
12745 Result variables
12747 This module will set the following variables in your project:
12748 JPEG_FOUND
12750 If false, do not try to use JPEG.
12751 JPEG_INCLUDE_DIRS
12753 where to find jpeglib.h, etc.
12754 JPEG_LIBRARIES
12756 the libraries needed to use JPEG.
12757 JPEG_VERSION
12759 New in version 3.12: the version of the JPEG library found
12760 Cache variables
12763 The following cache variables may also be set:
12764 JPEG_INCLUDE_DIRS
12766 where to find jpeglib.h, etc.
12767 JPEG_LIBRARY_RELEASE
12769 where to find the JPEG library (optimized).
12770 JPEG_LIBRARY_DEBUG
12772 where to find the JPEG library (debug).
12773 New in version 3.12: Debug and Release variand are found separately.
12775 Obsolete variables
12778 JPEG_INCLUDE_DIR
12779 where to find jpeglib.h, etc. (same as JPEG_INCLUDE_DIRS)
12780 JPEG_LIBRARY
12782 where to find the JPEG library.
12783 FindKDE3
12785 Find the KDE3 include and library dirs, KDE preprocessors and define a
12786 some macros
12787 This module defines the following variables:
12789 KDE3_DEFINITIONS
12791 compiler definitions required for compiling KDE software
12792 KDE3_INCLUDE_DIR
12794 the KDE include directory
12795 KDE3_INCLUDE_DIRS
12797 the KDE and the Qt include directory, for use with include_di‐
12798 rectories()
12799 KDE3_LIB_DIR
12801 the directory where the KDE libraries are installed, for use
12802 with link_directories()
12803 QT_AND_KDECORE_LIBS
12805 this contains both the Qt and the kdecore library
12806 KDE3_DCOPIDL_EXECUTABLE
12808 the dcopidl executable
12809 KDE3_DCOPIDL2CPP_EXECUTABLE
12811 the dcopidl2cpp executable
12812 KDE3_KCFGC_EXECUTABLE
12814 the kconfig_compiler executable
12815 KDE3_FOUND
12817 set to TRUE if all of the above has been found
12818 The following user adjustable options are provided:
12820 KDE3_BUILD_TESTS
12822 enable this to build KDE testcases
12823 It also adds the following macros (from KDE3Macros.cmake) SRCS_VAR is
12825 always the variable which contains the list of source files for your
12826 application or library.
12827 KDE3_AUTOMOC(file1 ... fileN)
12829 Call this if you want to have automatic moc file handling.
12831 This means if you include "foo.moc" in the source file foo.cpp
12832 a moc file for the header foo.h will be created automatically.
12833 You can set the property SKIP_AUTOMAKE using set_source_files_properties()
12834 to exclude some files in the list from being processed.
12835 KDE3_ADD_MOC_FILES(SRCS_VAR file1 ... fileN )
12837 If you don't use the KDE3_AUTOMOC() macro, for the files
12839 listed here moc files will be created (named "foo.moc.cpp")
12840 KDE3_ADD_DCOP_SKELS(SRCS_VAR header1.h ... headerN.h )
12842 Use this to generate DCOP skeletions from the listed headers.
12844 KDE3_ADD_DCOP_STUBS(SRCS_VAR header1.h ... headerN.h )
12846 Use this to generate DCOP stubs from the listed headers.
12848 KDE3_ADD_UI_FILES(SRCS_VAR file1.ui ... fileN.ui )
12850 Use this to add the Qt designer ui files to your application/library.
12852 KDE3_ADD_KCFG_FILES(SRCS_VAR file1.kcfgc ... fileN.kcfgc )
12854 Use this to add KDE kconfig compiler files to your application/library.
12856 KDE3_INSTALL_LIBTOOL_FILE(target)
12858 This will create and install a simple libtool file for the given target.
12860 KDE3_ADD_EXECUTABLE(name file1 ... fileN )
12862 Currently identical to add_executable(), may provide some advanced
12864 features in the future.
12865 KDE3_ADD_KPART(name [WITH_PREFIX] file1 ... fileN )
12867 Create a KDE plugin (KPart, kioslave, etc.) from the given source files.
12869 If WITH_PREFIX is given, the resulting plugin will have the prefix "lib",
12870 otherwise it won't.
12871 It creates and installs an appropriate libtool la-file.
12872 KDE3_ADD_KDEINIT_EXECUTABLE(name file1 ... fileN )
12874 Create a KDE application in the form of a module loadable via kdeinit.
12876 A library named kdeinit_<name> will be created and a small executable
12877 which links to it.
12878 The option KDE3_ENABLE_FINAL to enable all-in-one compilation is no
12880 longer supported.
12881 Author: Alexander Neundorf <neundorf@kde.org>
12883 FindKDE4
12885 Find KDE4 and provide all necessary variables and macros to compile
12886 software for it. It looks for KDE 4 in the following directories in
12887 the given order:
12888 CMAKE_INSTALL_PREFIX
12890 KDEDIRS
12891 /opt/kde4
12892 Please look in FindKDE4Internal.cmake and KDE4Macros.cmake for more in‐
12894 formation. They are installed with the KDE 4 libraries in
12895 $KDEDIRS/share/apps/cmake/modules/.
12896 Author: Alexander Neundorf <neundorf@kde.org>
12898 FindLAPACK
12900 Find Linear Algebra PACKage (LAPACK) library
12901 This module finds an installed Fortran library that implements the
12903 LAPACK linear-algebra interface.
12904 At least one of the C, CXX, or Fortran languages must be enabled.
12906 Input Variables
12908 The following variables may be set to influence this module's behavior:
12909 BLA_STATIC
12911 if ON use static linkage
12912 BLA_VENDOR
12914 Set to one of the BLAS/LAPACK Vendors to search for BLAS only
12915 from the specified vendor. If not set, all vendors are consid‐
12916 ered.
12917 BLA_F95
12919 if ON tries to find the BLAS95/LAPACK95 interfaces
12920 BLA_PREFER_PKGCONFIG
12922 New in version 3.20.
12923 if set pkg-config will be used to search for a LAPACK library
12926 first and if one is found that is preferred
12927 BLA_SIZEOF_INTEGER
12929 New in version 3.22.
12930 Specify the BLAS/LAPACK library integer size:
12933 4 Search for a BLAS/LAPACK with 32-bit integer interfaces.
12935 8 Search for a BLAS/LAPACK with 64-bit integer interfaces.
12937 ANY Search for any BLAS/LAPACK. Most likely, a BLAS/LAPACK
12939 with 32-bit integer interfaces will be found.
12940 Imported targets
12942 This module defines the following IMPORTED targets:
12943 LAPACK::LAPACK
12945 New in version 3.18.
12946 The libraries to use for LAPACK, if found.
12949 Result Variables
12951 This module defines the following variables:
12952 LAPACK_FOUND
12954 library implementing the LAPACK interface is found
12955 LAPACK_LINKER_FLAGS
12957 uncached list of required linker flags (excluding -l and -L).
12958 LAPACK_LIBRARIES
12960 uncached list of libraries (using full path name) to link
12961 against to use LAPACK
12962 LAPACK95_LIBRARIES
12964 uncached list of libraries (using full path name) to link
12965 against to use LAPACK95
12966 LAPACK95_FOUND
12968 library implementing the LAPACK95 interface is found
12969 Intel MKL
12971 To use the Intel MKL implementation of LAPACK, a project must enable at
12972 least one of the C or CXX languages. Set BLA_VENDOR to an Intel MKL
12973 variant either on the command-line as -DBLA_VENDOR=Intel10_64lp or in
12974 project code:
12975 set(BLA_VENDOR Intel10_64lp)
12977 find_package(LAPACK)
12978 In order to build a project using Intel MKL, and end user must first
12980 establish an Intel MKL environment. See the FindBLAS module section on
12981 Intel MKL for details.
12982 FindLATEX
12984 Find LaTeX
12985 This module finds an installed LaTeX and determines the location of the
12987 compiler. Additionally the module looks for Latex-related software
12988 like BibTeX.
12989 New in version 3.2: Component processing; support for htlatex, pdftops,
12991 Biber, xindy, XeLaTeX, LuaLaTeX.
12992 This module sets the following result variables:
12995 LATEX_FOUND: whether found Latex and requested components
12997 LATEX_<component>_FOUND: whether found <component>
12998 LATEX_COMPILER: path to the LaTeX compiler
12999 PDFLATEX_COMPILER: path to the PdfLaTeX compiler
13000 XELATEX_COMPILER: path to the XeLaTeX compiler
13001 LUALATEX_COMPILER: path to the LuaLaTeX compiler
13002 BIBTEX_COMPILER: path to the BibTeX compiler
13003 BIBER_COMPILER: path to the Biber compiler
13004 MAKEINDEX_COMPILER: path to the MakeIndex compiler
13005 XINDY_COMPILER: path to the xindy compiler
13006 DVIPS_CONVERTER: path to the DVIPS converter
13007 DVIPDF_CONVERTER: path to the DVIPDF converter
13008 PS2PDF_CONVERTER: path to the PS2PDF converter
13009 PDFTOPS_CONVERTER: path to the pdftops converter
13010 LATEX2HTML_CONVERTER: path to the LaTeX2Html converter
13011 HTLATEX_COMPILER: path to the htlatex compiler
13012 Possible components are:
13014 PDFLATEX
13016 XELATEX
13017 LUALATEX
13018 BIBTEX
13019 BIBER
13020 MAKEINDEX
13021 XINDY
13022 DVIPS
13023 DVIPDF
13024 PS2PDF
13025 PDFTOPS
13026 LATEX2HTML
13027 HTLATEX
13028 Example Usages:
13030 find_package(LATEX)
13032 find_package(LATEX COMPONENTS PDFLATEX)
13033 find_package(LATEX COMPONENTS BIBTEX PS2PDF)
13034 FindLibArchive
13036 Find libarchive library and headers. Libarchive is multi-format ar‐
13037 chive and compression library.
13038 The module defines the following variables:
13040 LibArchive_FOUND - true if libarchive was found
13042 LibArchive_INCLUDE_DIRS - include search path
13043 LibArchive_LIBRARIES - libraries to link
13044 LibArchive_VERSION - libarchive 3-component version number
13045 The module defines the following IMPORTED targets:
13047 LibArchive::LibArchive - target for linking against libarchive
13049 New in version 3.6: Support for new libarchive 3.2 version string for‐
13051 mat.
13052 FindLibinput
13055 New in version 3.14.
13056 Find libinput headers and library.
13059 Imported Targets
13061 Libinput::Libinput
13062 The libinput library, if found.
13063 Result Variables
13065 This will define the following variables in your project:
13066 Libinput_FOUND
13068 true if (the requested version of) libinput is available.
13069 Libinput_VERSION
13071 the version of libinput.
13072 Libinput_LIBRARIES
13074 the libraries to link against to use libinput.
13075 Libinput_INCLUDE_DIRS
13077 where to find the libinput headers.
13078 Libinput_COMPILE_OPTIONS
13080 this should be passed to target_compile_options(), if the target
13081 is not used for linking
13082 FindLibLZMA
13084 Find LZMA compression algorithm headers and library.
13085 Imported Targets
13087 New in version 3.14.
13088 This module defines IMPORTED target LibLZMA::LibLZMA, if liblzma has
13091 been found.
13092 Result variables
13094 This module will set the following variables in your project:
13095 LIBLZMA_FOUND
13097 True if liblzma headers and library were found.
13098 LIBLZMA_INCLUDE_DIRS
13100 Directory where liblzma headers are located.
13101 LIBLZMA_LIBRARIES
13103 Lzma libraries to link against.
13104 LIBLZMA_HAS_AUTO_DECODER
13106 True if lzma_auto_decoder() is found (required).
13107 LIBLZMA_HAS_EASY_ENCODER
13109 True if lzma_easy_encoder() is found (required).
13110 LIBLZMA_HAS_LZMA_PRESET
13112 True if lzma_lzma_preset() is found (required).
13113 LIBLZMA_VERSION_MAJOR
13115 The major version of lzma
13116 LIBLZMA_VERSION_MINOR
13118 The minor version of lzma
13119 LIBLZMA_VERSION_PATCH
13121 The patch version of lzma
13122 LIBLZMA_VERSION_STRING
13124 version number as a string (ex: "5.0.3")
13125 FindLibXml2
13127 Find the XML processing library (libxml2).
13128 IMPORTED Targets
13130 New in version 3.12.
13131 The following IMPORTED targets may be defined:
13134 LibXml2::LibXml2
13136 libxml2 library.
13137 LibXml2::xmllint
13139 New in version 3.17.
13140 xmllint command-line executable.
13143 Result variables
13145 This module will set the following variables in your project:
13146 LibXml2_FOUND
13148 true if libxml2 headers and libraries were found
13149 LIBXML2_INCLUDE_DIR
13151 the directory containing LibXml2 headers
13152 LIBXML2_INCLUDE_DIRS
13154 list of the include directories needed to use LibXml2
13155 LIBXML2_LIBRARIES
13157 LibXml2 libraries to be linked
13158 LIBXML2_DEFINITIONS
13160 the compiler switches required for using LibXml2
13161 LIBXML2_XMLLINT_EXECUTABLE
13163 path to the XML checking tool xmllint coming with LibXml2
13164 LIBXML2_VERSION_STRING
13166 the version of LibXml2 found (since CMake 2.8.8)
13167 Cache variables
13169 The following cache variables may also be set:
13170 LIBXML2_INCLUDE_DIR
13172 the directory containing LibXml2 headers
13173 LIBXML2_LIBRARY
13175 path to the LibXml2 library
13176 FindLibXslt
13178 Find the XSL Transformations, Extensible Stylesheet Language Transfor‐
13179 mations (XSLT) library (LibXslt)
13180 IMPORTED Targets
13182 New in version 3.18.
13183 The following IMPORTED targets may be defined:
13186 LibXslt::LibXslt
13188 If the libxslt library has been found
13189 LibXslt::LibExslt
13191 If the libexslt library has been found
13192 LibXslt::xsltproc
13194 If the xsltproc command-line executable has been found
13195 Result variables
13197 This module will set the following variables in your project:
13198 LIBXSLT_FOUND - system has LibXslt LIBXSLT_INCLUDE_DIR - the LibXslt
13199 include directory LIBXSLT_LIBRARIES - Link these to LibXslt
13200 LIBXSLT_DEFINITIONS - Compiler switches required for using LibXslt
13201 LIBXSLT_VERSION_STRING - version of LibXslt found (since CMake
13202 2.8.8)
13203 Additionally, the following two variables are set (but not required for
13205 using xslt):
13206 LIBXSLT_EXSLT_INCLUDE_DIR
13208 New in version 3.18: The include directory for exslt.
13209 LIBXSLT_EXSLT_LIBRARIES
13212 Link to these if you need to link against the exslt library.
13213 LIBXSLT_XSLTPROC_EXECUTABLE
13215 Contains the full path to the xsltproc executable if found.
13216 FindLTTngUST
13218 New in version 3.6.
13219 Find Linux Trace Toolkit Next Generation (LTTng-UST) library.
13222 Imported target
13224 This module defines the following IMPORTED target:
13225 LTTng::UST
13227 The LTTng-UST library, if found
13228 Result variables
13230 This module sets the following
13231 LTTNGUST_FOUND
13233 TRUE if system has LTTng-UST
13234 LTTNGUST_INCLUDE_DIRS
13236 The LTTng-UST include directories
13237 LTTNGUST_LIBRARIES
13239 The libraries needed to use LTTng-UST
13240 LTTNGUST_VERSION_STRING
13242 The LTTng-UST version
13243 LTTNGUST_HAS_TRACEF
13245 TRUE if the tracef() API is available in the system's LTTng-UST
13246 LTTNGUST_HAS_TRACELOG
13248 TRUE if the tracelog() API is available in the system's LT‐
13249 Tng-UST
13250 FindLua
13252 Locate Lua library.
13253 New in version 3.18: Support for Lua 5.4.
13255 This module defines:
13258 ::
13260 LUA_FOUND - if false, do not try to link to Lua LUA_LI‐
13261 BRARIES - both lua and lualib LUA_INCLUDE_DIR - where to
13262 find lua.h LUA_VERSION_STRING - the version of Lua found LUA_VER‐
13263 SION_MAJOR - the major version of Lua LUA_VERSION_MINOR - the mi‐
13264 nor version of Lua LUA_VERSION_PATCH - the patch version of Lua
13265 Note that the expected include convention is
13267 #include "lua.h"
13269 and not
13271 #include <lua/lua.h>
13273 This is because, the lua location is not standardized and may exist in
13275 locations other than lua/
13276 FindLua50
13278 Locate Lua library. This module defines:
13279 ::
13281 LUA50_FOUND, if false, do not try to link to Lua LUA_LIBRARIES, both
13282 lua and lualib LUA_INCLUDE_DIR, where to find lua.h and lualib.h
13283 (and probably lauxlib.h)
13284 Note that the expected include convention is
13286 #include "lua.h"
13288 and not
13290 #include <lua/lua.h>
13292 This is because, the lua location is not standardized and may exist in
13294 locations other than lua/
13295 FindLua51
13297 Locate Lua library. This module defines:
13298 ::
13300 LUA51_FOUND, if false, do not try to link to Lua LUA_LIBRARIES
13301 LUA_INCLUDE_DIR, where to find lua.h LUA_VERSION_STRING, the version
13302 of Lua found (since CMake 2.8.8)
13303 Note that the expected include convention is
13305 #include "lua.h"
13307 and not
13309 #include <lua/lua.h>
13311 This is because, the lua location is not standardized and may exist in
13313 locations other than lua/
13314 FindMatlab
13316 Finds Matlab or Matlab Compiler Runtime (MCR) and provides Matlab
13317 tools, libraries and compilers to CMake.
13318 This package primary purpose is to find the libraries associated with
13320 Matlab or the MCR in order to be able to build Matlab extensions (mex
13321 files). It can also be used:
13322 • to run specific commands in Matlab in case Matlab is available
13324 • for declaring Matlab unit test
13326 • to retrieve various information from Matlab (mex extensions, versions
13328 and release queries, ...)
13329 New in version 3.12: Added Matlab Compiler Runtime (MCR) support.
13331 The module supports the following components:
13334 • ENG_LIBRARY and MAT_LIBRARY: respectively the ENG and MAT libraries
13336 of Matlab
13337 • MAIN_PROGRAM the Matlab binary program. Note that this component is
13339 not available on the MCR version, and will yield an error if the MCR
13340 is found instead of the regular Matlab installation.
13341 • MEX_COMPILER the MEX compiler.
13343 • MCC_COMPILER the MCC compiler, included with the Matlab Compiler
13345 add-on.
13346 • SIMULINK the Simulink environment.
13348 New in version 3.7: Added the MAT_LIBRARY component.
13350 New in version 3.13: Added the ENGINE_LIBRARY, DATAARRAY_LIBRARY and
13353 MCC_COMPILER components.
13354 Changed in version 3.14: Removed the MX_LIBRARY, ENGINE_LIBRARY and
13357 DATAARRAY_LIBRARY components. These libraries are found uncondition‐
13358 ally.
13359 NOTE:
13362 The version given to the find_package() directive is the Matlab ver‐
13363 sion, which should not be confused with the Matlab release name (eg.
13364 R2014). The matlab_get_version_from_release_name() and
13365 matlab_get_release_name_from_version() provide a mapping between the
13366 release name and the version.
13367 The variable Matlab_ROOT_DIR may be specified in order to give the path
13369 of the desired Matlab version. Otherwise, the behavior is platform spe‐
13370 cific:
13371 • Windows: The installed versions of Matlab/MCR are retrieved from the
13373 Windows registry
13374 • OS X: The installed versions of Matlab/MCR are given by the MATLAB
13376 default installation paths in /Application. If no such application is
13377 found, it falls back to the one that might be accessible from the
13378 PATH.
13379 • Unix: The desired Matlab should be accessible from the PATH. This
13381 does not work for MCR installation and Matlab_ROOT_DIR should be
13382 specified on this platform.
13383 Additional information is provided when MATLAB_FIND_DEBUG is set. When
13385 a Matlab/MCR installation is found automatically and the MATLAB_VERSION
13386 is not given, the version is queried from Matlab directly (on Windows
13387 this may pop up a Matlab window) or from the MCR installation.
13388 The mapping of the release names and the version of Matlab is performed
13390 by defining pairs (name, version). The variable
13391 MATLAB_ADDITIONAL_VERSIONS may be provided before the call to the
13392 find_package() in order to handle additional versions.
13393 A Matlab scripts can be added to the set of tests using the
13395 matlab_add_unit_test(). By default, the Matlab unit test framework will
13396 be used (>= 2013a) to run this script, but regular .m files returning
13397 an exit code can be used as well (0 indicating a success).
13398 Module Input Variables
13400 Users or projects may set the following variables to configure the mod‐
13401 ule behavior:
13402 Matlab_ROOT_DIR
13404 the root of the Matlab installation.
13405 MATLAB_FIND_DEBUG
13407 outputs debug information
13408 MATLAB_ADDITIONAL_VERSIONS
13410 additional versions of Matlab for the automatic retrieval of the
13411 installed versions.
13412 Imported targets
13414 New in version 3.22.
13415 This module defines the following IMPORTED targets:
13418 Matlab::mex
13420 The mex library, always available.
13421 Matlab::mx
13423 The mx library of Matlab (arrays), always available.
13424 Matlab::eng
13426 Matlab engine library. Available only if the ENG_LIBRARY compo‐
13427 nent is requested.
13428 Matlab::mat
13430 Matlab matrix library. Available only if the MAT_LIBRARY compo‐
13431 nent is requested.
13432 Matlab::MatlabEngine
13434 Matlab C++ engine library, always available for R2018a and
13435 newer.
13436 Matlab::MatlabDataArray
13438 Matlab C++ data array library, always available for R2018a and
13439 newer.
13440 Variables defined by the module
13442 Result variables
13443 Matlab_FOUND
13444 TRUE if the Matlab installation is found, FALSE otherwise. All
13445 variable below are defined if Matlab is found.
13446 Matlab_ROOT_DIR
13448 the final root of the Matlab installation determined by the
13449 FindMatlab module.
13450 Matlab_MAIN_PROGRAM
13452 the Matlab binary program. Available only if the component
13453 MAIN_PROGRAM is given in the find_package() directive.
13454 Matlab_INCLUDE_DIRS
13456 the path of the Matlab libraries headers
13457 Matlab_MEX_LIBRARY
13459 library for mex, always available.
13460 Matlab_MX_LIBRARY
13462 mx library of Matlab (arrays), always available.
13463 Matlab_ENG_LIBRARY
13465 Matlab engine library. Available only if the component ENG_LI‐
13466 BRARY is requested.
13467 Matlab_MAT_LIBRARY
13469 Matlab matrix library. Available only if the component MAT_LI‐
13470 BRARY is requested.
13471 Matlab_ENGINE_LIBRARY
13473 New in version 3.13.
13474 Matlab C++ engine library, always available for R2018a and
13477 newer.
13478 Matlab_DATAARRAY_LIBRARY
13480 New in version 3.13.
13481 Matlab C++ data array library, always available for R2018a and
13484 newer.
13485 Matlab_LIBRARIES
13487 the whole set of libraries of Matlab
13488 Matlab_MEX_COMPILER
13490 the mex compiler of Matlab. Currently not used. Available only
13491 if the component MEX_COMPILER is requested.
13492 Matlab_MCC_COMPILER
13494 New in version 3.13.
13495 the mcc compiler of Matlab. Included with the Matlab Compiler
13498 add-on. Available only if the component MCC_COMPILER is re‐
13499 quested.
13500 Cached variables
13502 Matlab_MEX_EXTENSION
13503 the extension of the mex files for the current platform (given
13504 by Matlab).
13505 Matlab_ROOT_DIR
13507 the location of the root of the Matlab installation found. If
13508 this value is changed by the user, the result variables are re‐
13509 computed.
13510 Provided macros
13512 matlab_get_version_from_release_name()
13513 returns the version from the release name
13514 matlab_get_release_name_from_version()
13516 returns the release name from the Matlab version
13517 Provided functions
13519 matlab_add_mex()
13520 adds a target compiling a MEX file.
13521 matlab_add_unit_test()
13523 adds a Matlab unit test file as a test to the project.
13524 matlab_extract_all_installed_versions_from_registry()
13526 parses the registry for all Matlab versions. Available on Win‐
13527 dows only. The part of the registry parsed is dependent on the
13528 host processor
13529 matlab_get_all_valid_matlab_roots_from_registry()
13531 returns all the possible Matlab or MCR paths, according to a
13532 previously given list. Only the existing/accessible paths are
13533 kept. This is mainly useful for the searching all possible Mat‐
13534 lab installation.
13535 matlab_get_mex_suffix()
13537 returns the suffix to be used for the mex files (platform/archi‐
13538 tecture dependent)
13539 matlab_get_version_from_matlab_run()
13541 returns the version of Matlab/MCR, given the full directory of
13542 the Matlab/MCR installation path.
13543 Known issues
13545 Symbol clash in a MEX target
13546 By default, every symbols inside a MEX file defined with the
13547 command matlab_add_mex() have hidden visibility, except for the
13548 entry point. This is the default behavior of the MEX compiler,
13549 which lowers the risk of symbol collision between the libraries
13550 shipped with Matlab, and the libraries to which the MEX file is
13551 linking to. This is also the default on Windows platforms.
13552 However, this is not sufficient in certain case, where for in‐
13554 stance your MEX file is linking against libraries that are al‐
13555 ready loaded by Matlab, even if those libraries have different
13556 SONAMES. A possible solution is to hide the symbols of the li‐
13557 braries to which the MEX target is linking to. This can be
13558 achieved in GNU GCC compilers with the linker option -Wl,--ex‐
13559 clude-libs,ALL.
13560 Tests using GPU resources
13562 in case your MEX file is using the GPU and in order to be able
13563 to run unit tests on this MEX file, the GPU resources should be
13564 properly released by Matlab. A possible solution is to make Mat‐
13565 lab aware of the use of the GPU resources in the session, which
13566 can be performed by a command such as D = gpuDevice() at the be‐
13567 ginning of the test script (or via a fixture).
13568 Reference
13570 Matlab_ROOT_DIR
13571 The root folder of the Matlab installation. If set before the
13572 call to find_package(), the module will look for the components
13573 in that path. If not set, then an automatic search of Matlab
13574 will be performed. If set, it should point to a valid version of
13575 Matlab.
13576 MATLAB_FIND_DEBUG
13578 If set, the lookup of Matlab and the intermediate configuration
13579 steps are outputted to the console.
13580 MATLAB_ADDITIONAL_VERSIONS
13582 If set, specifies additional versions of Matlab that may be
13583 looked for. The variable should be a list of strings, organized
13584 by pairs of release name and versions, such as follows:
13585 set(MATLAB_ADDITIONAL_VERSIONS
13587 "release_name1=corresponding_version1"
13588 "release_name2=corresponding_version2"
13589 ...
13590 )
13591 Example:
13593 set(MATLAB_ADDITIONAL_VERSIONS
13595 "R2013b=8.2"
13596 "R2013a=8.1"
13597 "R2012b=8.0")
13598 The order of entries in this list matters when several versions
13600 of Matlab are installed. The priority is set according to the
13601 ordering in this list.
13602 matlab_get_version_from_release_name
13604 Returns the version of Matlab (17.58) from a release name
13605 (R2017k)
13606 matlab_get_release_name_from_version
13608 Returns the release name (R2017k) from the version of Matlab
13609 (17.58)
13610 matlab_extract_all_installed_versions_from_registry
13612 This function parses the registry and founds the Matlab versions
13613 that are installed. The found versions are returned in mat‐
13614 lab_versions. Set win64 to TRUE if the 64 bit version of Matlab
13615 should be looked for The returned list contains all versions un‐
13616 der HKLM\\SOFTWARE\\Mathworks\\MATLAB and HKLM\\SOFTWARE\\Math‐
13617 works\\MATLAB Runtime or an empty list in case an error occurred
13618 (or nothing found).
13619 NOTE:
13621 Only the versions are provided. No check is made over the ex‐
13622 istence of the installation referenced in the registry,
13623 matlab_get_all_valid_matlab_roots_from_registry
13625 Populates the Matlab root with valid versions of Matlab or Mat‐
13626 lab Runtime (MCR). The returned matlab_roots is organized in
13627 triplets (type,version_number,matlab_root_path), where type in‐
13628 dicates either MATLAB or MCR.
13629 matlab_get_all_valid_matlab_roots_from_registry(
13631 matlab_versions
13632 matlab_roots)
13633 matlab_versions
13635 the versions of each of the Matlab or MCR installations
13636 matlab_roots
13638 the location of each of the Matlab or MCR installations
13639 matlab_get_mex_suffix
13641 Returns the extension of the mex files (the suffixes). This
13642 function should not be called before the appropriate Matlab root
13643 has been found.
13644 matlab_get_mex_suffix(
13646 matlab_root
13647 mex_suffix)
13648 matlab_root
13650 the root of the Matlab/MCR installation
13651 mex_suffix
13653 the variable name in which the suffix will be returned.
13654 matlab_get_version_from_matlab_run
13656 This function runs Matlab program specified on arguments and ex‐
13657 tracts its version. If the path provided for the Matlab instal‐
13658 lation points to an MCR installation, the version is extracted
13659 from the installed files.
13660 matlab_get_version_from_matlab_run(
13662 matlab_binary_path
13663 matlab_list_versions)
13664 matlab_binary_path
13666 the location of the matlab binary executable
13667 matlab_list_versions
13669 the version extracted from Matlab
13670 matlab_add_unit_test
13672 Adds a Matlab unit test to the test set of cmake/ctest. This
13673 command requires the component MAIN_PROGRAM and hence is not
13674 available for an MCR installation.
13675 The unit test uses the Matlab unittest framework (default,
13677 available starting Matlab 2013b+) except if the option
13678 NO_UNITTEST_FRAMEWORK is given.
13679 The function expects one Matlab test script file to be given.
13681 In the case NO_UNITTEST_FRAMEWORK is given, the unittest script
13682 file should contain the script to be run, plus an exit command
13683 with the exit value. This exit value will be passed to the ctest
13684 framework (0 success, non 0 failure). Additional arguments ac‐
13685 cepted by add_test() can be passed through TEST_ARGS (eg. CON‐
13686 FIGURATION <config> ...).
13687 matlab_add_unit_test(
13689 NAME <name>
13690 UNITTEST_FILE matlab_file_containing_unittest.m
13691 [CUSTOM_TEST_COMMAND matlab_command_to_run_as_test]
13692 [UNITTEST_PRECOMMAND matlab_command_to_run]
13693 [TIMEOUT timeout]
13694 [ADDITIONAL_PATH path1 [path2 ...]]
13695 [MATLAB_ADDITIONAL_STARTUP_OPTIONS option1 [option2 ...]]
13696 [TEST_ARGS arg1 [arg2 ...]]
13697 [NO_UNITTEST_FRAMEWORK]
13698 )
13699 The function arguments are:
13701 NAME name of the unittest in ctest.
13703 UNITTEST_FILE
13705 the matlab unittest file. Its path will be automatically
13706 added to the Matlab path.
13707 CUSTOM_TEST_COMMAND
13709 Matlab script command to run as the test. If this is not
13710 set, then the following is run: runtests('mat‐
13711 lab_file_name'), exit(max([ans(1,:).Failed])) where mat‐
13712 lab_file_name is the UNITTEST_FILE without the extension.
13713 UNITTEST_PRECOMMAND
13715 Matlab script command to be ran before the file contain‐
13716 ing the test (eg. GPU device initialization based on
13717 CMake variables).
13718 TIMEOUT
13720 the test timeout in seconds. Defaults to 180 seconds as
13721 the Matlab unit test may hang.
13722 ADDITIONAL_PATH
13724 a list of paths to add to the Matlab path prior to run‐
13725 ning the unit test.
13726 MATLAB_ADDITIONAL_STARTUP_OPTIONS
13728 a list of additional option in order to run Matlab from
13729 the command line. -nosplash -nodesktop -nodisplay are
13730 always added.
13731 TEST_ARGS
13733 Additional options provided to the add_test command.
13734 These options are added to the default options (eg. "CON‐
13735 FIGURATIONS Release")
13736 NO_UNITTEST_FRAMEWORK
13738 when set, indicates that the test should not use the
13739 unittest framework of Matlab (available for versions >=
13740 R2013a).
13741 WORKING_DIRECTORY
13743 This will be the working directory for the test. If spec‐
13744 ified it will also be the output directory used for the
13745 log file of the test run. If not specified the temporary
13746 directory ${CMAKE_BINARY_DIR}/Matlab will be used as the
13747 working directory and the log location.
13748 matlab_add_mex
13750 Adds a Matlab MEX target. This commands compiles the given
13751 sources with the current tool-chain in order to produce a MEX
13752 file. The final name of the produced output may be specified, as
13753 well as additional link libraries, and a documentation entry for
13754 the MEX file. Remaining arguments of the call are passed to the
13755 add_library() or add_executable() command.
13756 matlab_add_mex(
13758 NAME <name>
13759 [EXECUTABLE | MODULE | SHARED]
13760 SRC src1 [src2 ...]
13761 [OUTPUT_NAME output_name]
13762 [DOCUMENTATION file.txt]
13763 [LINK_TO target1 target2 ...]
13764 [R2017b | R2018a]
13765 [EXCLUDE_FROM_ALL]
13766 [...]
13767 )
13768 NAME name of the target.
13770 SRC list of source files.
13772 LINK_TO
13774 a list of additional link dependencies. The target links
13775 to libmex and libmx by default.
13776 OUTPUT_NAME
13778 if given, overrides the default name. The default name is
13779 the name of the target without any prefix and with Mat‐
13780 lab_MEX_EXTENSION suffix.
13781 DOCUMENTATION
13783 if given, the file file.txt will be considered as being
13784 the documentation file for the MEX file. This file is
13785 copied into the same folder without any processing, with
13786 the same name as the final mex file, and with extension
13787 .m. In that case, typing help <name> in Matlab prints the
13788 documentation contained in this file.
13789 R2017b or R2018a
13791 New in version 3.14.
13792 May be given to specify the version of the C API to use:
13795 R2017b specifies the traditional (separate complex) C
13796 API, and corresponds to the -R2017b flag for the mex com‐
13797 mand. R2018a specifies the new interleaved complex C API,
13798 and corresponds to the -R2018a flag for the mex command.
13799 Ignored if MATLAB version prior to R2018a. Defaults to
13800 R2017b.
13801 MODULE or SHARED
13803 New in version 3.7.
13804 May be given to specify the type of library to be cre‐
13807 ated.
13808 EXECUTABLE
13810 New in version 3.7.
13811 May be given to create an executable instead of a li‐
13814 brary. If no type is given explicitly, the type is
13815 SHARED.
13816 EXCLUDE_FROM_ALL
13818 This option has the same meaning as for EXCLUDE_FROM_ALL
13819 and is forwarded to add_library() or add_executable()
13820 commands.
13821 The documentation file is not processed and should be in the
13823 following format:
13824 % This is the documentation
13826 function ret = mex_target_output_name(input1)
13827 FindMFC
13829 Find Microsoft Foundation Class Library (MFC) on Windows
13830 Find the native MFC - i.e. decide if an application can link to the
13832 MFC libraries.
13833 MFC_FOUND - Was MFC support found
13835 You don't need to include anything or link anything to use it.
13837 FindMotif
13839 Try to find Motif (or lesstif)
13840 Once done this will define:
13842 MOTIF_FOUND - system has MOTIF
13844 MOTIF_INCLUDE_DIR - include paths to use Motif
13845 MOTIF_LIBRARIES - Link these to use Motif
13846 FindMPEG
13848 Find the native MPEG includes and library
13849 This module defines
13851 MPEG_INCLUDE_DIR, where to find MPEG.h, etc.
13853 MPEG_LIBRARIES, the libraries required to use MPEG.
13854 MPEG_FOUND, If false, do not try to use MPEG.
13855 also defined, but not for general use are
13857 MPEG_mpeg2_LIBRARY, where to find the MPEG library.
13859 MPEG_vo_LIBRARY, where to find the vo library.
13860 FindMPEG2
13862 Find the native MPEG2 includes and library
13863 This module defines
13865 MPEG2_INCLUDE_DIR, path to mpeg2dec/mpeg2.h, etc.
13867 MPEG2_LIBRARIES, the libraries required to use MPEG2.
13868 MPEG2_FOUND, If false, do not try to use MPEG2.
13869 also defined, but not for general use are
13871 MPEG2_mpeg2_LIBRARY, where to find the MPEG2 library.
13873 MPEG2_vo_LIBRARY, where to find the vo library.
13874 FindMPI
13876 Find a Message Passing Interface (MPI) implementation.
13877 The Message Passing Interface (MPI) is a library used to write
13879 high-performance distributed-memory parallel applications, and is typi‐
13880 cally deployed on a cluster. MPI is a standard interface (defined by
13881 the MPI forum) for which many implementations are available.
13882 New in version 3.10: Major overhaul of the module: many new variables,
13884 per-language components, support for a wider variety of runtimes.
13885 Variables for using MPI
13888 The module exposes the components C, CXX, MPICXX and Fortran. Each of
13889 these controls the various MPI languages to search for. The difference
13890 between CXX and MPICXX is that CXX refers to the MPI C API being usable
13891 from C++, whereas MPICXX refers to the MPI-2 C++ API that was removed
13892 again in MPI-3.
13893 Depending on the enabled components the following variables will be
13895 set:
13896 MPI_FOUND
13898 Variable indicating that MPI settings for all requested lan‐
13899 guages have been found. If no components are specified, this is
13900 true if MPI settings for all enabled languages were detected.
13901 Note that the MPICXX component does not affect this variable.
13902 MPI_VERSION
13904 Minimal version of MPI detected among the requested languages,
13905 or all enabled languages if no components were specified.
13906 This module will set the following variables per language in your
13908 project, where <lang> is one of C, CXX, or Fortran:
13909 MPI_<lang>_FOUND
13911 Variable indicating the MPI settings for <lang> were found and
13912 that simple MPI test programs compile with the provided set‐
13913 tings.
13914 MPI_<lang>_COMPILER
13916 MPI compiler for <lang> if such a program exists.
13917 MPI_<lang>_COMPILE_OPTIONS
13919 Compilation options for MPI programs in <lang>, given as a
13920 ;-list.
13921 MPI_<lang>_COMPILE_DEFINITIONS
13923 Compilation definitions for MPI programs in <lang>, given as a
13924 ;-list.
13925 MPI_<lang>_INCLUDE_DIRS
13927 Include path(s) for MPI header.
13928 MPI_<lang>_LINK_FLAGS
13930 Linker flags for MPI programs.
13931 MPI_<lang>_LIBRARIES
13933 All libraries to link MPI programs against.
13934 New in version 3.9: Additionally, the following IMPORTED targets are
13936 defined:
13937 MPI::MPI_<lang>
13940 Target for using MPI from <lang>.
13941 The following variables indicating which bindings are present will be
13943 defined:
13944 MPI_MPICXX_FOUND
13946 Variable indicating whether the MPI-2 C++ bindings are present
13947 (introduced in MPI-2, removed with MPI-3).
13948 MPI_Fortran_HAVE_F77_HEADER
13950 True if the Fortran 77 header mpif.h is available.
13951 MPI_Fortran_HAVE_F90_MODULE
13953 True if the Fortran 90 module mpi can be used for accessing MPI
13954 (MPI-2 and higher only).
13955 MPI_Fortran_HAVE_F08_MODULE
13957 True if the Fortran 2008 mpi_f08 is available to MPI programs
13958 (MPI-3 and higher only).
13959 If possible, the MPI version will be determined by this module. The fa‐
13961 cilities to detect the MPI version were introduced with MPI-1.2, and
13962 therefore cannot be found for older MPI versions.
13963 MPI_<lang>_VERSION_MAJOR
13965 Major version of MPI implemented for <lang> by the MPI distribu‐
13966 tion.
13967 MPI_<lang>_VERSION_MINOR
13969 Minor version of MPI implemented for <lang> by the MPI distribu‐
13970 tion.
13971 MPI_<lang>_VERSION
13973 MPI version implemented for <lang> by the MPI distribution.
13974 Note that there's no variable for the C bindings being accessible
13976 through mpi.h, since the MPI standards always have required this bind‐
13977 ing to work in both C and C++ code.
13978 For running MPI programs, the module sets the following variables
13980 MPIEXEC_EXECUTABLE
13982 Executable for running MPI programs, if such exists.
13983 MPIEXEC_NUMPROC_FLAG
13985 Flag to pass to mpiexec before giving it the number of proces‐
13986 sors to run on.
13987 MPIEXEC_MAX_NUMPROCS
13989 Number of MPI processors to utilize. Defaults to the number of
13990 processors detected on the host system.
13991 MPIEXEC_PREFLAGS
13993 Flags to pass to mpiexec directly before the executable to run.
13994 MPIEXEC_POSTFLAGS
13996 Flags to pass to mpiexec after other flags.
13997 Variables for locating MPI
13999 This module performs a four step search for an MPI implementation:
14000 1. Search for MPIEXEC_EXECUTABLE and, if found, use its base directory.
14002 2. Check if the compiler has MPI support built-in. This is the case if
14004 the user passed a compiler wrapper as CMAKE_<LANG>_COMPILER or if
14005 they use Cray system compiler wrappers.
14006 3. Attempt to find an MPI compiler wrapper and determine the compiler
14008 information from it.
14009 4. Try to find an MPI implementation that does not ship such a wrapper
14011 by guessing settings. Currently, only Microsoft MPI and MPICH2 on
14012 Windows are supported.
14013 For controlling the MPIEXEC_EXECUTABLE step, the following variables
14015 may be set:
14016 MPIEXEC_EXECUTABLE
14018 Manually specify the location of mpiexec.
14019 MPI_HOME
14021 Specify the base directory of the MPI installation.
14022 ENV{MPI_HOME}
14024 Environment variable to specify the base directory of the MPI
14025 installation.
14026 ENV{I_MPI_ROOT}
14028 Environment variable to specify the base directory of the MPI
14029 installation.
14030 For controlling the compiler wrapper step, the following variables may
14032 be set:
14033 MPI_<lang>_COMPILER
14035 Search for the specified compiler wrapper and use it.
14036 MPI_<lang>_COMPILER_FLAGS
14038 Flags to pass to the MPI compiler wrapper during interrogation.
14039 Some compiler wrappers support linking debug or tracing li‐
14040 braries if a specific flag is passed and this variable may be
14041 used to obtain them.
14042 MPI_COMPILER_FLAGS
14044 Used to initialize MPI_<lang>_COMPILER_FLAGS if no language spe‐
14045 cific flag has been given. Empty by default.
14046 MPI_EXECUTABLE_SUFFIX
14048 A suffix which is appended to all names that are being looked
14049 for. For instance you may set this to .mpich or .openmpi to pre‐
14050 fer the one or the other on Debian and its derivatives.
14051 In order to control the guessing step, the following variable may be
14053 set:
14054 MPI_GUESS_LIBRARY_NAME
14056 Valid values are MSMPI and MPICH2. If set, only the given li‐
14057 brary will be searched for. By default, MSMPI will be preferred
14058 over MPICH2 if both are available. This also sets MPI_SKIP_COM‐
14059 PILER_WRAPPER to true, which may be overridden.
14060 Each of the search steps may be skipped with the following control
14062 variables:
14063 MPI_ASSUME_NO_BUILTIN_MPI
14065 If true, the module assumes that the compiler itself does not
14066 provide an MPI implementation and skips to step 2.
14067 MPI_SKIP_COMPILER_WRAPPER
14069 If true, no compiler wrapper will be searched for.
14070 MPI_SKIP_GUESSING
14072 If true, the guessing step will be skipped.
14073 Additionally, the following control variable is available to change
14075 search behavior:
14076 MPI_CXX_SKIP_MPICXX
14078 Add some definitions that will disable the MPI-2 C++ bindings.
14079 Currently supported are MPICH, Open MPI, Platform MPI and deriv‐
14080 atives thereof, for example MVAPICH or Intel MPI.
14081 If the find procedure fails for a variable MPI_<lang>_WORKS, then the
14083 settings detected by or passed to the module did not work and even a
14084 simple MPI test program failed to compile.
14085 If all of these parameters were not sufficient to find the right MPI
14087 implementation, a user may disable the entire autodetection process by
14088 specifying both a list of libraries in MPI_<lang>_LIBRARIES and a list
14089 of include directories in MPI_<lang>_ADDITIONAL_INCLUDE_DIRS. Any
14090 other variable may be set in addition to these two. The module will
14091 then validate the MPI settings and store the settings in the cache.
14092 Cache variables for MPI
14094 The variable MPI_<lang>_INCLUDE_DIRS will be assembled from the follow‐
14095 ing variables. For C and CXX:
14096 MPI_<lang>_HEADER_DIR
14098 Location of the mpi.h header on disk.
14099 For Fortran:
14101 MPI_Fortran_F77_HEADER_DIR
14103 Location of the Fortran 77 header mpif.h, if it exists.
14104 MPI_Fortran_MODULE_DIR
14106 Location of the mpi or mpi_f08 modules, if available.
14107 For all languages the following variables are additionally considered:
14109 MPI_<lang>_ADDITIONAL_INCLUDE_DIRS
14111 A ;-list of paths needed in addition to the normal include di‐
14112 rectories.
14113 MPI_<include_name>_INCLUDE_DIR
14115 Path variables for include folders referred to by <in‐
14116 clude_name>.
14117 MPI_<lang>_ADDITIONAL_INCLUDE_VARS
14119 A ;-list of <include_name> that will be added to the include lo‐
14120 cations of <lang>.
14121 The variable MPI_<lang>_LIBRARIES will be assembled from the following
14123 variables:
14124 MPI_<lib_name>_LIBRARY
14126 The location of a library called <lib_name> for use with MPI.
14127 MPI_<lang>_LIB_NAMES
14129 A ;-list of <lib_name> that will be added to the include loca‐
14130 tions of <lang>.
14131 Usage of mpiexec
14133 When using MPIEXEC_EXECUTABLE to execute MPI applications, you should
14134 typically use all of the MPIEXEC_EXECUTABLE flags as follows:
14135 ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS}
14137 ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS
14138 where EXECUTABLE is the MPI program, and ARGS are the arguments to pass
14140 to the MPI program.
14141 Advanced variables for using MPI
14143 The module can perform some advanced feature detections upon explicit
14144 request.
14145 Important notice: The following checks cannot be performed without exe‐
14147 cuting an MPI test program. Consider the special considerations for
14148 the behavior of try_run() during cross compilation. Moreover, running
14149 an MPI program can cause additional issues, like a firewall notifica‐
14150 tion on some systems. You should only enable these detections if you
14151 absolutely need the information.
14152 If the following variables are set to true, the respective search will
14154 be performed:
14155 MPI_DETERMINE_Fortran_CAPABILITIES
14157 Determine for all available Fortran bindings what the values of
14158 MPI_SUBARRAYS_SUPPORTED and MPI_ASYNC_PROTECTS_NONBLOCKING are
14159 and make their values available as MPI_Fortran_<binding>_SUBAR‐
14160 RAYS and MPI_Fortran_<binding>_ASYNCPROT, where <binding> is one
14161 of F77_HEADER, F90_MODULE and F08_MODULE.
14162 MPI_DETERMINE_LIBRARY_VERSION
14164 For each language, find the output of MPI_Get_library_version
14165 and make it available as MPI_<lang>_LIBRARY_VERSION_STRING.
14166 This information is usually tied to the runtime component of an
14167 MPI implementation and might differ depending on <lang>. Note
14168 that the return value is entirely implementation defined. This
14169 information might be used to identify the MPI vendor and for ex‐
14170 ample pick the correct one of multiple third party binaries that
14171 matches the MPI vendor.
14172 Backward Compatibility
14174 Deprecated since version 3.10.
14175 For backward compatibility with older versions of FindMPI, these vari‐
14178 ables are set:
14179 MPI_COMPILER MPI_LIBRARY MPI_EXTRA_LIBRARY
14181 MPI_COMPILE_FLAGS MPI_INCLUDE_PATH MPI_LINK_FLAGS
14182 MPI_LIBRARIES
14183 In new projects, please use the MPI_<lang>_XXX equivalents. Addition‐
14185 ally, the following variables are deprecated:
14186 MPI_<lang>_COMPILE_FLAGS
14188 Use MPI_<lang>_COMPILE_OPTIONS and MPI_<lang>_COMPILE_DEFINI‐
14189 TIONS instead.
14190 MPI_<lang>_INCLUDE_PATH
14192 For consumption use MPI_<lang>_INCLUDE_DIRS and for specifying
14193 folders use MPI_<lang>_ADDITIONAL_INCLUDE_DIRS instead.
14194 MPIEXEC
14196 Use MPIEXEC_EXECUTABLE instead.
14197 FindMsys
14199 New in version 3.21.
14200 Find MSYS, a POSIX-compatible environment that runs natively on Micro‐
14203 soft Windows
14204 FindODBC
14206 New in version 3.12.
14207 Find an Open Database Connectivity (ODBC) include directory and li‐
14210 brary.
14211 On Windows, when building with Visual Studio, this module assumes the
14213 ODBC library is provided by the available Windows SDK.
14214 On Unix, this module allows to search for ODBC library provided by
14216 unixODBC or iODBC implementations of ODBC API. This module reads hint
14217 about location of the config program:
14218 ODBC_CONFIG
14220 Location of odbc_config or iodbc-config program
14221 Otherwise, this module tries to find the config program, first from
14223 unixODBC, then from iODBC. If no config program found, this module
14224 searches for ODBC header and library in list of known locations.
14225 Imported targets
14227 This module defines the following IMPORTED targets:
14228 ODBC::ODBC
14230 Imported target for using the ODBC library, if found.
14231 Result variables
14233 ODBC_FOUND
14234 Set to true if ODBC library found, otherwise false or undefined.
14235 ODBC_INCLUDE_DIRS
14237 Paths to include directories listed in one variable for use by
14238 ODBC client. May be empty on Windows, where the include direc‐
14239 tory corresponding to the expected Windows SDK is already avail‐
14240 able in the compilation environment.
14241 ODBC_LIBRARIES
14243 Paths to libraries to linked against to use ODBC. May just a
14244 library name on Windows, where the library directory correspond‐
14245 ing to the expected Windows SDK is already available in the com‐
14246 pilation environment.
14247 ODBC_CONFIG
14249 Path to unixODBC or iODBC config program, if found or specified.
14250 Cache variables
14252 For users who wish to edit and control the module behavior, this module
14253 reads hints about search locations from the following variables:
14254 ODBC_INCLUDE_DIR
14256 Path to ODBC include directory with sql.h header.
14257 ODBC_LIBRARY
14259 Path to ODBC library to be linked.
14260 These variables should not be used directly by project code.
14262 Limitations
14264 On Windows, this module does not search for iODBC. On Unix, there is
14265 no way to prefer unixODBC over iODBC, or vice versa, other than provid‐
14266 ing the config program location using the ODBC_CONFIG. This module
14267 does not allow to search for a specific ODBC driver.
14268 FindOpenACC
14270 New in version 3.10.
14271 Detect OpenACC support by the compiler.
14274 This module can be used to detect OpenACC support in a compiler. If
14276 the compiler supports OpenACC, the flags required to compile with Ope‐
14277 nACC support are returned in variables for the different languages.
14278 Currently, only NVHPC, PGI, GNU and Cray compilers are supported.
14279 Imported Targets
14281 New in version 3.16.
14282 The module provides IMPORTED targets:
14285 OpenACC::OpenACC_<lang>
14287 Target for using OpenACC from <lang>.
14288 Variables
14290 This module will set the following variables per language in your
14291 project, where <lang> is one of C, CXX, or Fortran:
14292 OpenACC_<lang>_FOUND
14294 Variable indicating if OpenACC support for <lang> was detected.
14295 OpenACC_<lang>_FLAGS
14297 OpenACC compiler flags for <lang>, separated by spaces.
14298 OpenACC_<lang>_OPTIONS
14300 New in version 3.16.
14301 OpenACC compiler flags for <lang>, as a list. Suitable for usage
14304 with target_compile_options or target_link_options.
14305 The module will also try to provide the OpenACC version variables:
14307 OpenACC_<lang>_SPEC_DATE
14309 Date of the OpenACC specification implemented by the <lang> com‐
14310 piler.
14311 OpenACC_<lang>_VERSION_MAJOR
14313 Major version of OpenACC implemented by the <lang> compiler.
14314 OpenACC_<lang>_VERSION_MINOR
14316 Minor version of OpenACC implemented by the <lang> compiler.
14317 OpenACC_<lang>_VERSION
14319 OpenACC version implemented by the <lang> compiler.
14320 The specification date is formatted as given in the OpenACC standard:
14322 yyyymm where yyyy and mm represents the year and month of the OpenACC
14323 specification implemented by the <lang> compiler.
14324 Input Variables
14326 OpenACC_ACCEL_TARGET=<target> If set, will the correct target accelera‐
14327 tor flag set to the <target> will be returned with Ope‐
14328 nACC_<lang>_FLAGS.
14329 FindOpenAL
14331 Finds Open Audio Library (OpenAL).
14332 Projects using this module should use #include "al.h" to include the
14334 OpenAL header file, not #include <AL/al.h>. The reason for this is
14335 that the latter is not entirely portable. Windows/Creative Labs does
14336 not by default put their headers in AL/ and macOS uses the convention
14337 <OpenAL/al.h>.
14338 Hints
14340 Environment variable $OPENALDIR can be used to set the prefix of OpenAL
14341 installation to be found.
14342 By default on macOS, system framework is search first. In other words,
14344 OpenAL is searched in the following order:
14345 1. System framework: /System/Library/Frameworks, whose priority can be
14347 changed via setting the CMAKE_FIND_FRAMEWORK variable.
14348 2. Environment variable $OPENALDIR.
14350 3. System paths.
14352 4. User-compiled framework: ~/Library/Frameworks.
14354 5. Manually compiled framework: /Library/Frameworks.
14356 6. Add-on package: /opt.
14358 Result Variables
14360 This module defines the following variables:
14361 OPENAL_FOUND
14363 If false, do not try to link to OpenAL
14364 OPENAL_INCLUDE_DIR
14366 OpenAL include directory
14367 OPENAL_LIBRARY
14369 Path to the OpenAL library
14370 OPENAL_VERSION_STRING
14372 Human-readable string containing the version of OpenAL
14373 FindOpenCL
14375 New in version 3.1.
14376 Finds Open Computing Language (OpenCL)
14379 New in version 3.10: Detection of OpenCL 2.1 and 2.2.
14381 IMPORTED Targets
14384 New in version 3.7.
14385 This module defines IMPORTED target OpenCL::OpenCL, if OpenCL has been
14388 found.
14389 Result Variables
14391 This module defines the following variables:
14392 OpenCL_FOUND - True if OpenCL was found
14394 OpenCL_INCLUDE_DIRS - include directories for OpenCL
14395 OpenCL_LIBRARIES - link against this library to use OpenCL
14396 OpenCL_VERSION_STRING - Highest supported OpenCL version (eg. 1.2)
14397 OpenCL_VERSION_MAJOR - The major version of the OpenCL implementation
14398 OpenCL_VERSION_MINOR - The minor version of the OpenCL implementation
14399 The module will also define two cache variables:
14401 OpenCL_INCLUDE_DIR - the OpenCL include directory
14403 OpenCL_LIBRARY - the path to the OpenCL library
14404 FindOpenGL
14406 FindModule for OpenGL and OpenGL Utility Library (GLU).
14407 Changed in version 3.2: X11 is no longer added as a dependency on
14409 Unix/Linux systems.
14410 New in version 3.10: GLVND support on Linux. See the Linux-specific
14413 section below.
14414 Optional COMPONENTS
14417 New in version 3.10.
14418 This module respects several optional COMPONENTS: EGL, GLX, and OpenGL.
14421 There are corresponding import targets for each of these flags.
14422 IMPORTED Targets
14424 New in version 3.8.
14425 This module defines the IMPORTED targets:
14428 OpenGL::GL
14430 Defined to the platform-specific OpenGL libraries if the system
14431 has OpenGL.
14432 OpenGL::GLU
14434 Defined if the system has OpenGL Utility Library (GLU).
14435 New in version 3.10: Additionally, the following GLVND-specific library
14437 targets are defined:
14438 OpenGL::OpenGL
14441 Defined to libOpenGL if the system is GLVND-based.
14442 OpenGL::GLX
14444 Defined if the system has OpenGL Extension to the X Window Sys‐
14445 tem (GLX).
14446 OpenGL::EGL
14448 Defined if the system has EGL.
14449 Result Variables
14451 This module sets the following variables:
14452 OPENGL_FOUND
14454 True, if the system has OpenGL and all components are found.
14455 OPENGL_XMESA_FOUND
14457 True, if the system has XMESA.
14458 OPENGL_GLU_FOUND
14460 True, if the system has GLU.
14461 OpenGL_OpenGL_FOUND
14463 True, if the system has an OpenGL library.
14464 OpenGL_GLX_FOUND
14466 True, if the system has GLX.
14467 OpenGL_EGL_FOUND
14469 True, if the system has EGL.
14470 OPENGL_INCLUDE_DIR
14472 Path to the OpenGL include directory.
14473 OPENGL_EGL_INCLUDE_DIRS
14475 Path to the EGL include directory.
14476 OPENGL_LIBRARIES
14478 Paths to the OpenGL library, windowing system libraries, and GLU
14479 libraries. On Linux, this assumes GLX and is never correct for
14480 EGL-based targets. Clients are encouraged to use the OpenGL::*
14481 import targets instead.
14482 New in version 3.10: Variables for GLVND-specific libraries OpenGL, EGL
14484 and GLX.
14485 Cache variables
14488 The following cache variables may also be set:
14489 OPENGL_egl_LIBRARY
14491 Path to the EGL library.
14492 OPENGL_glu_LIBRARY
14494 Path to the GLU library.
14495 OPENGL_glx_LIBRARY
14497 Path to the GLVND 'GLX' library.
14498 OPENGL_opengl_LIBRARY
14500 Path to the GLVND 'OpenGL' library
14501 OPENGL_gl_LIBRARY
14503 Path to the OpenGL library. New code should prefer the
14504 OpenGL::* import targets.
14505 New in version 3.10: Variables for GLVND-specific libraries OpenGL, EGL
14507 and GLX.
14508 Linux-specific
14511 Some Linux systems utilize GLVND as a new ABI for OpenGL. GLVND sepa‐
14512 rates context libraries from OpenGL itself; OpenGL lives in "li‐
14513 bOpenGL", and contexts are defined in "libGLX" or "libEGL". GLVND is
14514 currently the only way to get OpenGL 3+ functionality via EGL in a man‐
14515 ner portable across vendors. Projects may use GLVND explicitly with
14516 target OpenGL::OpenGL and either OpenGL::GLX or OpenGL::EGL.
14517 Projects may use the OpenGL::GL target (or OPENGL_LIBRARIES variable)
14519 to use legacy GL interfaces. These will use the legacy GL library lo‐
14520 cated by OPENGL_gl_LIBRARY, if available. If OPENGL_gl_LIBRARY is
14521 empty or not found and GLVND is available, the OpenGL::GL target will
14522 use GLVND OpenGL::OpenGL and OpenGL::GLX (and the OPENGL_LIBRARIES
14523 variable will use the corresponding libraries). Thus, for
14524 non-EGL-based Linux targets, the OpenGL::GL target is most portable.
14525 A OpenGL_GL_PREFERENCE variable may be set to specify the preferred way
14527 to provide legacy GL interfaces in case multiple choices are available.
14528 The value may be one of:
14529 GLVND If the GLVND OpenGL and GLX libraries are available, prefer
14531 them. This forces OPENGL_gl_LIBRARY to be empty.
14532 Changed in version 3.11: This is the default, unless policy
14534 CMP0072 is set to OLD and no components are requeted (since com‐
14535 ponents correspond to GLVND libraries).
14536 LEGACY Prefer to use the legacy libGL library, if available.
14539 For EGL targets the client must rely on GLVND support on the user's
14541 system. Linking should use the OpenGL::OpenGL OpenGL::EGL targets.
14542 Using GLES* libraries is theoretically possible in place of
14543 OpenGL::OpenGL, but this module does not currently support that; con‐
14544 tributions welcome.
14545 OPENGL_egl_LIBRARY and OPENGL_EGL_INCLUDE_DIRS are defined in the case
14547 of GLVND. For non-GLVND Linux and other systems these are left unde‐
14548 fined.
14549 macOS-Specific
14551 On OSX FindOpenGL defaults to using the framework version of OpenGL.
14552 People will have to change the cache values of OPENGL_glu_LIBRARY and
14553 OPENGL_gl_LIBRARY to use OpenGL with X11 on OSX.
14554 FindOpenMP
14556 Finds Open Multi-Processing (OpenMP) support.
14557 This module can be used to detect OpenMP support in a compiler. If the
14559 compiler supports OpenMP, the flags required to compile with OpenMP
14560 support are returned in variables for the different languages. The
14561 variables may be empty if the compiler does not need a special flag to
14562 support OpenMP.
14563 New in version 3.5: Clang support.
14565 Variables
14568 New in version 3.10: The module exposes the components C, CXX, and For‐
14569 tran. Each of these controls the various languages to search OpenMP
14570 support for.
14571 Depending on the enabled components the following variables will be
14574 set:
14575 OpenMP_FOUND
14577 Variable indicating that OpenMP flags for all requested lan‐
14578 guages have been found. If no components are specified, this is
14579 true if OpenMP settings for all enabled languages were detected.
14580 OpenMP_VERSION
14582 Minimal version of the OpenMP standard detected among the re‐
14583 quested languages, or all enabled languages if no components
14584 were specified.
14585 This module will set the following variables per language in your
14587 project, where <lang> is one of C, CXX, or Fortran:
14588 OpenMP_<lang>_FOUND
14590 Variable indicating if OpenMP support for <lang> was detected.
14591 OpenMP_<lang>_FLAGS
14593 OpenMP compiler flags for <lang>, separated by spaces.
14594 OpenMP_<lang>_INCLUDE_DIRS
14596 Directories that must be added to the header search path for
14597 <lang> when using OpenMP.
14598 For linking with OpenMP code written in <lang>, the following variables
14600 are provided:
14601 OpenMP_<lang>_LIB_NAMES
14603 ;-list of libraries for OpenMP programs for <lang>.
14604 OpenMP_<libname>_LIBRARY
14606 Location of the individual libraries needed for OpenMP support
14607 in <lang>.
14608 OpenMP_<lang>_LIBRARIES
14610 A list of libraries needed to link with OpenMP code written in
14611 <lang>.
14612 Additionally, the module provides IMPORTED targets:
14614 OpenMP::OpenMP_<lang>
14616 Target for using OpenMP from <lang>.
14617 Specifically for Fortran, the module sets the following variables:
14619 OpenMP_Fortran_HAVE_OMPLIB_HEADER
14621 Boolean indicating if OpenMP is accessible through omp_lib.h.
14622 OpenMP_Fortran_HAVE_OMPLIB_MODULE
14624 Boolean indicating if OpenMP is accessible through the omp_lib
14625 Fortran module.
14626 The module will also try to provide the OpenMP version variables:
14628 OpenMP_<lang>_SPEC_DATE
14630 New in version 3.7.
14631 Date of the OpenMP specification implemented by the <lang> com‐
14634 piler.
14635 OpenMP_<lang>_VERSION_MAJOR
14637 Major version of OpenMP implemented by the <lang> compiler.
14638 OpenMP_<lang>_VERSION_MINOR
14640 Minor version of OpenMP implemented by the <lang> compiler.
14641 OpenMP_<lang>_VERSION
14643 OpenMP version implemented by the <lang> compiler.
14644 The specification date is formatted as given in the OpenMP standard:
14646 yyyymm where yyyy and mm represents the year and month of the OpenMP
14647 specification implemented by the <lang> compiler.
14648 For some compilers, it may be necessary to add a header search path to
14650 find the relevant OpenMP headers. This location may be language-spe‐
14651 cific. Where this is needed, the module may attempt to find the loca‐
14652 tion, but it can be provided directly by setting the OpenMP_<lang>_IN‐
14653 CLUDE_DIR cache variable. Note that this variable is an _input_ con‐
14654 trol to the module. Project code should use the OpenMP_<lang>_IN‐
14655 CLUDE_DIRS _output_ variable if it needs to know what include directo‐
14656 ries are needed.
14657 FindOpenSceneGraph
14659 Find OpenSceneGraph (3D graphics application programming interface)
14660 This module searches for the OpenSceneGraph core "osg" library as well
14662 as FindOpenThreads, and whatever additional COMPONENTS (nodekits) that
14663 you specify.
14664 See http://www.openscenegraph.org
14666 NOTE: To use this module effectively you must either require CMake >=
14668 2.6.3 with cmake_minimum_required(VERSION 2.6.3) or download and place
14669 FindOpenThreads, Findosg functions, Findosg and Find<etc>.cmake files
14670 into your CMAKE_MODULE_PATH.
14671 ----
14674 This module accepts the following variables (note mixed case)
14678 OpenSceneGraph_DEBUG - Enable debugging output
14680 OpenSceneGraph_MARK_AS_ADVANCED - Mark cache variables as advanced
14682 automatically
14683 The following environment variables are also respected for finding the
14685 OSG and it's various components. CMAKE_PREFIX_PATH can also be used
14686 for this (see find_library() CMake documentation).
14687 <MODULE>_DIR
14689 (where MODULE is of the form "OSGVOLUME" and there is a Findos‐
14690 gVolume.cmake` file)
14691 OSG_DIR
14693 OSGDIR
14695 OSG_ROOT
14697 [CMake 2.8.10]: The CMake variable OSG_DIR can now be used as well to
14699 influence detection, instead of needing to specify an environment vari‐
14700 able.
14701 This module defines the following output variables:
14703 OPENSCENEGRAPH_FOUND - Was the OSG and all of the specified components found?
14705 OPENSCENEGRAPH_VERSION - The version of the OSG which was found
14707 OPENSCENEGRAPH_INCLUDE_DIRS - Where to find the headers
14709 OPENSCENEGRAPH_LIBRARIES - The OSG libraries
14711 ================================== Example Usage:
14713 find_package(OpenSceneGraph 2.0.0 REQUIRED osgDB osgUtil)
14715 # libOpenThreads & libosg automatically searched
14716 include_directories(${OPENSCENEGRAPH_INCLUDE_DIRS})
14717 add_executable(foo foo.cc)
14719 target_link_libraries(foo ${OPENSCENEGRAPH_LIBRARIES})
14720 FindOpenSSL
14722 Find the OpenSSL encryption library.
14723 This module finds an installed OpenSSL library and determines its ver‐
14725 sion.
14726 New in version 3.19: When a version is requested, it can be specified
14728 as a simple value or as a range. For a detailed description of version
14729 range usage and capabilities, refer to the find_package() command.
14730 New in version 3.18: Support for OpenSSL 3.0.
14733 Optional COMPONENTS
14736 New in version 3.12.
14737 This module supports two optional COMPONENTS: Crypto and SSL. Both
14740 components have associated imported targets, as described below.
14741 Imported Targets
14743 New in version 3.4.
14744 This module defines the following IMPORTED targets:
14747 OpenSSL::SSL
14749 The OpenSSL ssl library, if found.
14750 OpenSSL::Crypto
14752 The OpenSSL crypto library, if found.
14753 OpenSSL::applink
14755 New in version 3.18.
14756 The OpenSSL applink components that might be need to be compiled
14759 into projects under MSVC. This target is available only if found
14760 OpenSSL version is not less than 0.9.8. By linking this target
14761 the above OpenSSL targets can be linked even if the project has
14762 different MSVC runtime configurations with the above OpenSSL
14763 targets. This target has no effect on platforms other than MSVC.
14764 NOTE: Due to how INTERFACE_SOURCES are consumed by the consuming tar‐
14766 get, unless you certainly know what you are doing, it is always pre‐
14767 ferred to link OpenSSL::applink target as PRIVATE and to make sure that
14768 this target is linked at most once for the whole dependency graph of
14769 any library or executable:
14770 target_link_libraries(myTarget PRIVATE OpenSSL::applink)
14772 Otherwise you would probably encounter unexpected random problems when
14774 building and linking, as both the ISO C and the ISO C++ standard claims
14775 almost nothing about what a link process should be.
14776 Result Variables
14778 This module will set the following variables in your project:
14779 OPENSSL_FOUND
14781 System has the OpenSSL library. If no components are requested
14782 it only requires the crypto library.
14783 OPENSSL_INCLUDE_DIR
14785 The OpenSSL include directory.
14786 OPENSSL_CRYPTO_LIBRARY
14788 The OpenSSL crypto library.
14789 OPENSSL_CRYPTO_LIBRARIES
14791 The OpenSSL crypto library and its dependencies.
14792 OPENSSL_SSL_LIBRARY
14794 The OpenSSL SSL library.
14795 OPENSSL_SSL_LIBRARIES
14797 The OpenSSL SSL library and its dependencies.
14798 OPENSSL_LIBRARIES
14800 All OpenSSL libraries and their dependencies.
14801 OPENSSL_VERSION
14803 This is set to $major.$minor.$revision$patch (e.g. 0.9.8s).
14804 OPENSSL_APPLINK_SOURCE
14806 The sources in the target OpenSSL::applink that is mentioned
14807 above. This variable shall always be undefined if found openssl
14808 version is less than 0.9.8 or if platform is not MSVC.
14809 Hints
14811 Set OPENSSL_ROOT_DIR to the root directory of an OpenSSL installation.
14812 New in version 3.4: Set OPENSSL_USE_STATIC_LIBS to TRUE to look for
14814 static libraries.
14815 New in version 3.5: Set OPENSSL_MSVC_STATIC_RT set TRUE to choose the
14818 MT version of the lib.
14819 FindOpenThreads
14822 OpenThreads is a C++ based threading library. Its largest userbase
14823 seems to OpenSceneGraph so you might notice I accept OSGDIR as an envi‐
14824 ronment path. I consider this part of the Findosg* suite used to find
14825 OpenSceneGraph components. Each component is separate and you must opt
14826 in to each module.
14827 Locate OpenThreads This module defines OPENTHREADS_LIBRARY
14829 OPENTHREADS_FOUND, if false, do not try to link to OpenThreads
14830 OPENTHREADS_INCLUDE_DIR, where to find the headers
14831 $OPENTHREADS_DIR is an environment variable that would correspond to
14833 the ./configure --prefix=$OPENTHREADS_DIR used in building osg.
14834 [CMake 2.8.10]: The CMake variables OPENTHREADS_DIR or OSG_DIR can now
14836 be used as well to influence detection, instead of needing to specify
14837 an environment variable.
14838 Created by Eric Wing.
14840 Findosg
14842 NOTE: It is highly recommended that you use the new FindOpenScene‐
14843 Graph.cmake introduced in CMake 2.6.3 and not use this Find module di‐
14844 rectly.
14845 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14847 nents. Each component is separate and you must opt in to each module.
14848 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14849 as these modules won't do it for you. This is to allow you control
14850 over your own system piece by piece in case you need to opt out of cer‐
14851 tain components or change the Find behavior for a particular module
14852 (perhaps because the default FindOpenGL.cmake module doesn't work with
14853 your system as an example). If you want to use a more convenient mod‐
14854 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14855 of the Findosg*.cmake modules.
14856 Locate osg This module defines
14858 OSG_FOUND - Was the Osg found? OSG_INCLUDE_DIR - Where to find the
14860 headers OSG_LIBRARIES - The libraries to link against for the OSG (use
14861 this)
14862 OSG_LIBRARY - The OSG library OSG_LIBRARY_DEBUG - The OSG debug library
14864 $OSGDIR is an environment variable that would correspond to the ./con‐
14866 figure --prefix=$OSGDIR used in building osg.
14867 Created by Eric Wing.
14869 Findosg_functions
14871 This CMake file contains two macros to assist with searching for OSG
14872 libraries and nodekits. Please see FindOpenSceneGraph.cmake for full
14873 documentation.
14874 FindosgAnimation
14876 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14877 nents. Each component is separate and you must opt in to each module.
14878 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14879 as these modules won't do it for you. This is to allow you control
14880 over your own system piece by piece in case you need to opt out of cer‐
14881 tain components or change the Find behavior for a particular module
14882 (perhaps because the default FindOpenGL.cmake module doesn't work with
14883 your system as an example). If you want to use a more convenient mod‐
14884 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14885 of the Findosg*.cmake modules.
14886 Locate osgAnimation This module defines
14888 OSGANIMATION_FOUND - Was osgAnimation found? OSGANIMATION_INCLUDE_DIR -
14890 Where to find the headers OSGANIMATION_LIBRARIES - The libraries to
14891 link against for the OSG (use this)
14892 OSGANIMATION_LIBRARY - The OSG library OSGANIMATION_LIBRARY_DEBUG - The
14894 OSG debug library
14895 $OSGDIR is an environment variable that would correspond to the ./con‐
14897 figure --prefix=$OSGDIR used in building osg.
14898 Created by Eric Wing.
14900 FindosgDB
14902 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14903 nents. Each component is separate and you must opt in to each module.
14904 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14905 as these modules won't do it for you. This is to allow you control
14906 over your own system piece by piece in case you need to opt out of cer‐
14907 tain components or change the Find behavior for a particular module
14908 (perhaps because the default FindOpenGL module doesn't work with your
14909 system as an example). If you want to use a more convenient module
14910 that includes everything, use the FindOpenSceneGraph instead of the
14911 Findosg*.cmake modules.
14912 Locate osgDB This module defines:
14914 OSGDB_FOUND
14916 Was osgDB found?
14917 OSGDB_INCLUDE_DIR
14919 Where to find the headers
14920 OSGDB_LIBRARIES
14922 The libraries to link against for the osgDB
14923 OSGDB_LIBRARY
14925 The osgDB library
14926 OSGDB_LIBRARY_DEBUG
14928 The osgDB debug library
14929 $OSGDIR is an environment variable that would correspond to:
14931 ./configure --prefix=$OSGDIR used in building osg.
14933 FindosgFX
14935 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14936 nents. Each component is separate and you must opt in to each module.
14937 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14938 as these modules won't do it for you. This is to allow you control
14939 over your own system piece by piece in case you need to opt out of cer‐
14940 tain components or change the Find behavior for a particular module
14941 (perhaps because the default FindOpenGL.cmake module doesn't work with
14942 your system as an example). If you want to use a more convenient mod‐
14943 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14944 of the Findosg*.cmake modules.
14945 Locate osgFX This module defines
14947 OSGFX_FOUND - Was osgFX found? OSGFX_INCLUDE_DIR - Where to find the
14949 headers OSGFX_LIBRARIES - The libraries to link against for the osgFX
14950 (use this)
14951 OSGFX_LIBRARY - The osgFX library OSGFX_LIBRARY_DEBUG - The osgFX debug
14953 library
14954 $OSGDIR is an environment variable that would correspond to the ./con‐
14956 figure --prefix=$OSGDIR used in building osg.
14957 Created by Eric Wing.
14959 FindosgGA
14961 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14962 nents. Each component is separate and you must opt in to each module.
14963 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14964 as these modules won't do it for you. This is to allow you control
14965 over your own system piece by piece in case you need to opt out of cer‐
14966 tain components or change the Find behavior for a particular module
14967 (perhaps because the default FindOpenGL.cmake module doesn't work with
14968 your system as an example). If you want to use a more convenient mod‐
14969 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14970 of the Findosg*.cmake modules.
14971 Locate osgGA This module defines
14973 OSGGA_FOUND - Was osgGA found? OSGGA_INCLUDE_DIR - Where to find the
14975 headers OSGGA_LIBRARIES - The libraries to link against for the osgGA
14976 (use this)
14977 OSGGA_LIBRARY - The osgGA library OSGGA_LIBRARY_DEBUG - The osgGA debug
14979 library
14980 $OSGDIR is an environment variable that would correspond to the ./con‐
14982 figure --prefix=$OSGDIR used in building osg.
14983 Created by Eric Wing.
14985 FindosgIntrospection
14987 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14988 nents. Each component is separate and you must opt in to each module.
14989 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14990 as these modules won't do it for you. This is to allow you control
14991 over your own system piece by piece in case you need to opt out of cer‐
14992 tain components or change the Find behavior for a particular module
14993 (perhaps because the default FindOpenGL.cmake module doesn't work with
14994 your system as an example). If you want to use a more convenient mod‐
14995 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14996 of the Findosg*.cmake modules.
14997 Locate osgINTROSPECTION This module defines
14999 OSGINTROSPECTION_FOUND - Was osgIntrospection found? OSGINTROSPEC‐
15001 TION_INCLUDE_DIR - Where to find the headers OSGINTROSPECTION_LIBRARIES
15002 - The libraries to link for osgIntrospection (use this)
15003 OSGINTROSPECTION_LIBRARY - The osgIntrospection library OSGINTROSPEC‐
15005 TION_LIBRARY_DEBUG - The osgIntrospection debug library
15006 $OSGDIR is an environment variable that would correspond to the ./con‐
15008 figure --prefix=$OSGDIR used in building osg.
15009 Created by Eric Wing.
15011 FindosgManipulator
15013 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15014 nents. Each component is separate and you must opt in to each module.
15015 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15016 as these modules won't do it for you. This is to allow you control
15017 over your own system piece by piece in case you need to opt out of cer‐
15018 tain components or change the Find behavior for a particular module
15019 (perhaps because the default FindOpenGL.cmake module doesn't work with
15020 your system as an example). If you want to use a more convenient mod‐
15021 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15022 of the Findosg*.cmake modules.
15023 Locate osgManipulator This module defines
15025 OSGMANIPULATOR_FOUND - Was osgManipulator found? OSGMANIPULATOR_IN‐
15027 CLUDE_DIR - Where to find the headers OSGMANIPULATOR_LIBRARIES - The
15028 libraries to link for osgManipulator (use this)
15029 OSGMANIPULATOR_LIBRARY - The osgManipulator library OSGMANIPULATOR_LI‐
15031 BRARY_DEBUG - The osgManipulator debug library
15032 $OSGDIR is an environment variable that would correspond to the ./con‐
15034 figure --prefix=$OSGDIR used in building osg.
15035 Created by Eric Wing.
15037 FindosgParticle
15039 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15040 nents. Each component is separate and you must opt in to each module.
15041 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15042 as these modules won't do it for you. This is to allow you control
15043 over your own system piece by piece in case you need to opt out of cer‐
15044 tain components or change the Find behavior for a particular module
15045 (perhaps because the default FindOpenGL.cmake module doesn't work with
15046 your system as an example). If you want to use a more convenient mod‐
15047 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15048 of the Findosg*.cmake modules.
15049 Locate osgParticle This module defines
15051 OSGPARTICLE_FOUND - Was osgParticle found? OSGPARTICLE_INCLUDE_DIR -
15053 Where to find the headers OSGPARTICLE_LIBRARIES - The libraries to link
15054 for osgParticle (use this)
15055 OSGPARTICLE_LIBRARY - The osgParticle library OSGPARTICLE_LIBRARY_DEBUG
15057 - The osgParticle debug library
15058 $OSGDIR is an environment variable that would correspond to the ./con‐
15060 figure --prefix=$OSGDIR used in building osg.
15061 Created by Eric Wing.
15063 FindosgPresentation
15065 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15066 nents. Each component is separate and you must opt in to each module.
15067 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15068 as these modules won't do it for you. This is to allow you control
15069 over your own system piece by piece in case you need to opt out of cer‐
15070 tain components or change the Find behavior for a particular module
15071 (perhaps because the default FindOpenGL.cmake module doesn't work with
15072 your system as an example). If you want to use a more convenient mod‐
15073 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15074 of the Findosg*.cmake modules.
15075 Locate osgPresentation This module defines
15077 OSGPRESENTATION_FOUND - Was osgPresentation found? OSGPRESENTATION_IN‐
15079 CLUDE_DIR - Where to find the headers OSGPRESENTATION_LIBRARIES - The
15080 libraries to link for osgPresentation (use this)
15081 OSGPRESENTATION_LIBRARY - The osgPresentation library OSGPRESENTA‐
15083 TION_LIBRARY_DEBUG - The osgPresentation debug library
15084 $OSGDIR is an environment variable that would correspond to the ./con‐
15086 figure --prefix=$OSGDIR used in building osg.
15087 Created by Eric Wing. Modified to work with osgPresentation by Robert
15089 Osfield, January 2012.
15090 FindosgProducer
15092 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15093 nents. Each component is separate and you must opt in to each module.
15094 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15095 as these modules won't do it for you. This is to allow you control
15096 over your own system piece by piece in case you need to opt out of cer‐
15097 tain components or change the Find behavior for a particular module
15098 (perhaps because the default FindOpenGL.cmake module doesn't work with
15099 your system as an example). If you want to use a more convenient mod‐
15100 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15101 of the Findosg*.cmake modules.
15102 Locate osgProducer This module defines
15104 OSGPRODUCER_FOUND - Was osgProducer found? OSGPRODUCER_INCLUDE_DIR -
15106 Where to find the headers OSGPRODUCER_LIBRARIES - The libraries to link
15107 for osgProducer (use this)
15108 OSGPRODUCER_LIBRARY - The osgProducer library OSGPRODUCER_LIBRARY_DEBUG
15110 - The osgProducer debug library
15111 $OSGDIR is an environment variable that would correspond to the ./con‐
15113 figure --prefix=$OSGDIR used in building osg.
15114 Created by Eric Wing.
15116 FindosgQt
15118 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15119 nents. Each component is separate and you must opt in to each module.
15120 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15121 as these modules won't do it for you. This is to allow you control
15122 over your own system piece by piece in case you need to opt out of cer‐
15123 tain components or change the Find behavior for a particular module
15124 (perhaps because the default FindOpenGL.cmake module doesn't work with
15125 your system as an example). If you want to use a more convenient mod‐
15126 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15127 of the Findosg*.cmake modules.
15128 Locate osgQt This module defines
15130 OSGQT_FOUND - Was osgQt found? OSGQT_INCLUDE_DIR - Where to find the
15132 headers OSGQT_LIBRARIES - The libraries to link for osgQt (use this)
15133 OSGQT_LIBRARY - The osgQt library OSGQT_LIBRARY_DEBUG - The osgQt debug
15135 library
15136 $OSGDIR is an environment variable that would correspond to the ./con‐
15138 figure --prefix=$OSGDIR used in building osg.
15139 Created by Eric Wing. Modified to work with osgQt by Robert Osfield,
15141 January 2012.
15142 FindosgShadow
15144 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15145 nents. Each component is separate and you must opt in to each module.
15146 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15147 as these modules won't do it for you. This is to allow you control
15148 over your own system piece by piece in case you need to opt out of cer‐
15149 tain components or change the Find behavior for a particular module
15150 (perhaps because the default FindOpenGL.cmake module doesn't work with
15151 your system as an example). If you want to use a more convenient mod‐
15152 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15153 of the Findosg*.cmake modules.
15154 Locate osgShadow This module defines
15156 OSGSHADOW_FOUND - Was osgShadow found? OSGSHADOW_INCLUDE_DIR - Where to
15158 find the headers OSGSHADOW_LIBRARIES - The libraries to link for os‐
15159 gShadow (use this)
15160 OSGSHADOW_LIBRARY - The osgShadow library OSGSHADOW_LIBRARY_DEBUG - The
15162 osgShadow debug library
15163 $OSGDIR is an environment variable that would correspond to the ./con‐
15165 figure --prefix=$OSGDIR used in building osg.
15166 Created by Eric Wing.
15168 FindosgSim
15170 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15171 nents. Each component is separate and you must opt in to each module.
15172 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15173 as these modules won't do it for you. This is to allow you control
15174 over your own system piece by piece in case you need to opt out of cer‐
15175 tain components or change the Find behavior for a particular module
15176 (perhaps because the default FindOpenGL.cmake module doesn't work with
15177 your system as an example). If you want to use a more convenient mod‐
15178 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15179 of the Findosg*.cmake modules.
15180 Locate osgSim This module defines
15182 OSGSIM_FOUND - Was osgSim found? OSGSIM_INCLUDE_DIR - Where to find the
15184 headers OSGSIM_LIBRARIES - The libraries to link for osgSim (use this)
15185 OSGSIM_LIBRARY - The osgSim library OSGSIM_LIBRARY_DEBUG - The osgSim
15187 debug library
15188 $OSGDIR is an environment variable that would correspond to the ./con‐
15190 figure --prefix=$OSGDIR used in building osg.
15191 Created by Eric Wing.
15193 FindosgTerrain
15195 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15196 nents. Each component is separate and you must opt in to each module.
15197 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15198 as these modules won't do it for you. This is to allow you control
15199 over your own system piece by piece in case you need to opt out of cer‐
15200 tain components or change the Find behavior for a particular module
15201 (perhaps because the default FindOpenGL.cmake module doesn't work with
15202 your system as an example). If you want to use a more convenient mod‐
15203 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15204 of the Findosg*.cmake modules.
15205 Locate osgTerrain This module defines
15207 OSGTERRAIN_FOUND - Was osgTerrain found? OSGTERRAIN_INCLUDE_DIR - Where
15209 to find the headers OSGTERRAIN_LIBRARIES - The libraries to link for
15210 osgTerrain (use this)
15211 OSGTERRAIN_LIBRARY - The osgTerrain library OSGTERRAIN_LIBRARY_DEBUG -
15213 The osgTerrain debug library
15214 $OSGDIR is an environment variable that would correspond to the ./con‐
15216 figure --prefix=$OSGDIR used in building osg.
15217 Created by Eric Wing.
15219 FindosgText
15221 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15222 nents. Each component is separate and you must opt in to each module.
15223 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15224 as these modules won't do it for you. This is to allow you control
15225 over your own system piece by piece in case you need to opt out of cer‐
15226 tain components or change the Find behavior for a particular module
15227 (perhaps because the default FindOpenGL.cmake module doesn't work with
15228 your system as an example). If you want to use a more convenient mod‐
15229 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15230 of the Findosg*.cmake modules.
15231 Locate osgText This module defines
15233 OSGTEXT_FOUND - Was osgText found? OSGTEXT_INCLUDE_DIR - Where to find
15235 the headers OSGTEXT_LIBRARIES - The libraries to link for osgText (use
15236 this)
15237 OSGTEXT_LIBRARY - The osgText library OSGTEXT_LIBRARY_DEBUG - The osg‐
15239 Text debug library
15240 $OSGDIR is an environment variable that would correspond to the ./con‐
15242 figure --prefix=$OSGDIR used in building osg.
15243 Created by Eric Wing.
15245 FindosgUtil
15247 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15248 nents. Each component is separate and you must opt in to each module.
15249 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15250 as these modules won't do it for you. This is to allow you control
15251 over your own system piece by piece in case you need to opt out of cer‐
15252 tain components or change the Find behavior for a particular module
15253 (perhaps because the default FindOpenGL.cmake module doesn't work with
15254 your system as an example). If you want to use a more convenient mod‐
15255 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15256 of the Findosg*.cmake modules.
15257 Locate osgUtil This module defines
15259 OSGUTIL_FOUND - Was osgUtil found? OSGUTIL_INCLUDE_DIR - Where to find
15261 the headers OSGUTIL_LIBRARIES - The libraries to link for osgUtil (use
15262 this)
15263 OSGUTIL_LIBRARY - The osgUtil library OSGUTIL_LIBRARY_DEBUG - The
15265 osgUtil debug library
15266 $OSGDIR is an environment variable that would correspond to the ./con‐
15268 figure --prefix=$OSGDIR used in building osg.
15269 Created by Eric Wing.
15271 FindosgViewer
15273 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15274 nents. Each component is separate and you must opt in to each module.
15275 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15276 as these modules won't do it for you. This is to allow you control
15277 over your own system piece by piece in case you need to opt out of cer‐
15278 tain components or change the Find behavior for a particular module
15279 (perhaps because the default FindOpenGL.cmake module doesn't work with
15280 your system as an example). If you want to use a more convenient mod‐
15281 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15282 of the Findosg*.cmake modules.
15283 Locate osgViewer This module defines
15285 OSGVIEWER_FOUND - Was osgViewer found? OSGVIEWER_INCLUDE_DIR - Where to
15287 find the headers OSGVIEWER_LIBRARIES - The libraries to link for os‐
15288 gViewer (use this)
15289 OSGVIEWER_LIBRARY - The osgViewer library OSGVIEWER_LIBRARY_DEBUG - The
15291 osgViewer debug library
15292 $OSGDIR is an environment variable that would correspond to the ./con‐
15294 figure --prefix=$OSGDIR used in building osg.
15295 Created by Eric Wing.
15297 FindosgVolume
15299 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15300 nents. Each component is separate and you must opt in to each module.
15301 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15302 as these modules won't do it for you. This is to allow you control
15303 over your own system piece by piece in case you need to opt out of cer‐
15304 tain components or change the Find behavior for a particular module
15305 (perhaps because the default FindOpenGL.cmake module doesn't work with
15306 your system as an example). If you want to use a more convenient mod‐
15307 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15308 of the Findosg*.cmake modules.
15309 Locate osgVolume This module defines
15311 OSGVOLUME_FOUND - Was osgVolume found? OSGVOLUME_INCLUDE_DIR - Where to
15313 find the headers OSGVOLUME_LIBRARIES - The libraries to link for os‐
15314 gVolume (use this)
15315 OSGVOLUME_LIBRARY - The osgVolume library OSGVOLUME_LIBRARY_DEBUG - The
15317 osgVolume debug library
15318 $OSGDIR is an environment variable that would correspond to the ./con‐
15320 figure --prefix=$OSGDIR used in building osg.
15321 Created by Eric Wing.
15323 FindosgWidget
15325 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15326 nents. Each component is separate and you must opt in to each module.
15327 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15328 as these modules won't do it for you. This is to allow you control
15329 over your own system piece by piece in case you need to opt out of cer‐
15330 tain components or change the Find behavior for a particular module
15331 (perhaps because the default FindOpenGL.cmake module doesn't work with
15332 your system as an example). If you want to use a more convenient mod‐
15333 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15334 of the Findosg*.cmake modules.
15335 Locate osgWidget This module defines
15337 OSGWIDGET_FOUND - Was osgWidget found? OSGWIDGET_INCLUDE_DIR - Where to
15339 find the headers OSGWIDGET_LIBRARIES - The libraries to link for osg‐
15340 Widget (use this)
15341 OSGWIDGET_LIBRARY - The osgWidget library OSGWIDGET_LIBRARY_DEBUG - The
15343 osgWidget debug library
15344 $OSGDIR is an environment variable that would correspond to the ./con‐
15346 figure --prefix=$OSGDIR used in building osg.
15347 FindosgWidget.cmake tweaked from Findosg* suite as created by Eric
15349 Wing.
15350 FindPatch
15352 New in version 3.10.
15353 The module defines the following variables:
15356 Patch_EXECUTABLE
15358 Path to patch command-line executable.
15359 Patch_FOUND
15361 True if the patch command-line executable was found.
15362 The following IMPORTED targets are also defined:
15364 Patch::patch
15366 The command-line executable.
15367 Example usage:
15369 find_package(Patch)
15371 if(Patch_FOUND)
15372 message("Patch found: ${Patch_EXECUTABLE}")
15373 endif()
15374 FindPerl
15376 Find perl
15377 this module looks for Perl
15379 PERL_EXECUTABLE - the full path to perl
15381 PERL_FOUND - If false, don't attempt to use perl.
15382 PERL_VERSION_STRING - version of perl found (since CMake 2.8.8)
15383 FindPerlLibs
15385 Find Perl libraries
15386 This module finds if PERL is installed and determines where the include
15388 files and libraries are. It also determines what the name of the li‐
15389 brary is. This code sets the following variables:
15390 PERLLIBS_FOUND = True if perl.h & libperl were found
15392 PERL_INCLUDE_PATH = path to where perl.h is found
15393 PERL_LIBRARY = path to libperl
15394 PERL_EXECUTABLE = full path to the perl binary
15395 The minimum required version of Perl can be specified using the stan‐
15397 dard syntax, e.g. find_package(PerlLibs 6.0)
15398 The following variables are also available if needed
15400 (introduced after CMake 2.6.4)
15401 PERL_SITESEARCH = path to the sitesearch install dir (-V:installsitesearch)
15403 PERL_SITEARCH = path to the sitelib install directory (-V:installsitearch)
15404 PERL_SITELIB = path to the sitelib install directory (-V:installsitelib)
15405 PERL_VENDORARCH = path to the vendor arch install directory (-V:installvendorarch)
15406 PERL_VENDORLIB = path to the vendor lib install directory (-V:installvendorlib)
15407 PERL_ARCHLIB = path to the core arch lib install directory (-V:archlib)
15408 PERL_PRIVLIB = path to the core priv lib install directory (-V:privlib)
15409 PERL_UPDATE_ARCHLIB = path to the update arch lib install directory (-V:installarchlib)
15410 PERL_UPDATE_PRIVLIB = path to the update priv lib install directory (-V:installprivlib)
15411 PERL_EXTRA_C_FLAGS = Compilation flags used to build perl
15412 FindPHP4
15414 Find PHP4
15415 This module finds if PHP4 is installed and determines where the include
15417 files and libraries are. It also determines what the name of the li‐
15418 brary is. This code sets the following variables:
15419 PHP4_INCLUDE_PATH = path to where php.h can be found
15421 PHP4_EXECUTABLE = full path to the php4 binary
15422 FindPhysFS
15424 Locate PhysFS library This module defines PHYSFS_LIBRARY, the name of
15425 the library to link against PHYSFS_FOUND, if false, do not try to link
15426 to PHYSFS PHYSFS_INCLUDE_DIR, where to find physfs.h
15427 $PHYSFSDIR is an environment variable that would correspond to the
15429 ./configure --prefix=$PHYSFSDIR used in building PHYSFS.
15430 Created by Eric Wing.
15432 FindPike
15434 Find Pike
15435 This module finds if PIKE is installed and determines where the include
15437 files and libraries are. It also determines what the name of the li‐
15438 brary is. This code sets the following variables:
15439 PIKE_INCLUDE_PATH = path to where program.h is found
15441 PIKE_EXECUTABLE = full path to the pike binary
15442 FindPkgConfig
15444 A pkg-config module for CMake.
15445 Finds the pkg-config executable and adds the pkg_get_variable(),
15447 pkg_check_modules() and pkg_search_module() commands. The following
15448 variables will also be set:
15449 PKG_CONFIG_FOUND
15451 True if a pkg-config executable was found.
15452 PKG_CONFIG_VERSION_STRING
15454 New in version 2.8.8.
15455 The version of pkg-config that was found.
15458 PKG_CONFIG_EXECUTABLE
15460 The pathname of the pkg-config program.
15461 PKG_CONFIG_ARGN
15463 New in version 3.22.
15464 A list of arguments to pass to pkg-config.
15467 Both PKG_CONFIG_EXECUTABLE and PKG_CONFIG_ARGN are initialized by the
15469 module, but may be overridden by the user. See Variables Affecting Be‐
15470 havior for how these variables are initialized.
15471 pkg_check_modules
15473 Checks for all the given modules, setting a variety of result
15474 variables in the calling scope.
15475 pkg_check_modules(<prefix>
15477 [REQUIRED] [QUIET]
15478 [NO_CMAKE_PATH]
15479 [NO_CMAKE_ENVIRONMENT_PATH]
15480 [IMPORTED_TARGET [GLOBAL]]
15481 <moduleSpec> [<moduleSpec>...])
15482 When the REQUIRED argument is given, the command will fail with
15484 an error if module(s) could not be found.
15485 When the QUIET argument is given, no status messages will be
15487 printed.
15488 New in version 3.1: The CMAKE_PREFIX_PATH, CMAKE_FRAMEWORK_PATH,
15490 and CMAKE_APPBUNDLE_PATH cache and environment variables will be
15491 added to the pkg-config search path. The NO_CMAKE_PATH and
15492 NO_CMAKE_ENVIRONMENT_PATH arguments disable this behavior for
15493 the cache variables and environment variables respectively. The
15494 PKG_CONFIG_USE_CMAKE_PREFIX_PATH variable set to FALSE disables
15495 this behavior globally.
15496 New in version 3.6: The IMPORTED_TARGET argument will create an
15499 imported target named PkgConfig::<prefix> that can be passed di‐
15500 rectly as an argument to target_link_libraries().
15501 New in version 3.13: The GLOBAL argument will make the imported
15504 target available in global scope.
15505 New in version 3.15: Non-library linker options reported by
15508 pkg-config are stored in the INTERFACE_LINK_OPTIONS target prop‐
15509 erty.
15510 Changed in version 3.18: Include directories specified with
15513 -isystem are stored in the INTERFACE_INCLUDE_DIRECTORIES target
15514 property. Previous versions of CMake left them in the INTER‐
15515 FACE_COMPILE_OPTIONS property.
15516 Each <moduleSpec> can be either a bare module name or it can be
15519 a module name with a version constraint (operators =, <, >, <=
15520 and >= are supported). The following are examples for a module
15521 named foo with various constraints:
15522 • foo matches any version.
15524 • foo<2 only matches versions before 2.
15526 • foo>=3.1 matches any version from 3.1 or later.
15528 • foo=1.2.3 requires that foo must be exactly version 1.2.3.
15530 The following variables may be set upon return. Two sets of
15532 values exist: One for the common case (<XXX> = <prefix>) and an‐
15533 other for the information pkg-config provides when called with
15534 the --static option (<XXX> = <prefix>_STATIC).
15535 <XXX>_FOUND
15537 set to 1 if module(s) exist
15538 <XXX>_LIBRARIES
15540 only the libraries (without the '-l')
15541 <XXX>_LINK_LIBRARIES
15543 the libraries and their absolute paths
15544 <XXX>_LIBRARY_DIRS
15546 the paths of the libraries (without the '-L')
15547 <XXX>_LDFLAGS
15549 all required linker flags
15550 <XXX>_LDFLAGS_OTHER
15552 all other linker flags
15553 <XXX>_INCLUDE_DIRS
15555 the '-I' preprocessor flags (without the '-I')
15556 <XXX>_CFLAGS
15558 all required cflags
15559 <XXX>_CFLAGS_OTHER
15561 the other compiler flags
15562 All but <XXX>_FOUND may be a ;-list if the associated variable
15564 returned from pkg-config has multiple values.
15565 Changed in version 3.18: Include directories specified with
15567 -isystem are stored in the <XXX>_INCLUDE_DIRS variable. Previ‐
15568 ous versions of CMake left them in <XXX>_CFLAGS_OTHER.
15569 There are some special variables whose prefix depends on the
15572 number of <moduleSpec> given. When there is only one <module‐
15573 Spec>, <YYY> will simply be <prefix>, but if two or more <mod‐
15574 uleSpec> items are given, <YYY> will be <prefix>_<moduleName>.
15575 <YYY>_VERSION
15577 version of the module
15578 <YYY>_PREFIX
15580 prefix directory of the module
15581 <YYY>_INCLUDEDIR
15583 include directory of the module
15584 <YYY>_LIBDIR
15586 lib directory of the module
15587 Changed in version 3.8: For any given <prefix>, pkg_check_mod‐
15589 ules() can be called multiple times with different parameters.
15590 Previous versions of CMake cached and returned the first suc‐
15591 cessful result.
15592 Changed in version 3.16: If a full path to the found library
15595 can't be determined, but it's still visible to the linker, pass
15596 it through as -l<name>. Previous versions of CMake failed in
15597 this case.
15598 Examples:
15601 pkg_check_modules (GLIB2 glib-2.0)
15603 Looks for any version of glib2. If found, the output variable
15605 GLIB2_VERSION will hold the actual version found.
15606 pkg_check_modules (GLIB2 glib-2.0>=2.10)
15608 Looks for at least version 2.10 of glib2. If found, the output
15610 variable GLIB2_VERSION will hold the actual version found.
15611 pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0)
15613 Looks for both glib2-2.0 (at least version 2.10) and any version
15615 of gtk2+-2.0. Only if both are found will FOO be considered
15616 found. The FOO_glib-2.0_VERSION and FOO_gtk+-2.0_VERSION vari‐
15617 ables will be set to their respective found module versions.
15618 pkg_check_modules (XRENDER REQUIRED xrender)
15620 Requires any version of xrender. Example output variables set
15622 by a successful call:
15623 XRENDER_LIBRARIES=Xrender;X11
15625 XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp
15626 pkg_search_module
15628 The behavior of this command is the same as pkg_check_modules(),
15629 except that rather than checking for all the specified modules,
15630 it searches for just the first successful match.
15631 pkg_search_module(<prefix>
15633 [REQUIRED] [QUIET]
15634 [NO_CMAKE_PATH]
15635 [NO_CMAKE_ENVIRONMENT_PATH]
15636 [IMPORTED_TARGET [GLOBAL]]
15637 <moduleSpec> [<moduleSpec>...])
15638 New in version 3.16: If a module is found, the <prefix>_MOD‐
15640 ULE_NAME variable will contain the name of the matching module.
15641 This variable can be used if you need to run pkg_get_variable().
15642 Example:
15645 pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2)
15647 pkg_get_variable
15649 New in version 3.4.
15650 Retrieves the value of a pkg-config variable varName and stores
15653 it in the result variable resultVar in the calling scope.
15654 pkg_get_variable(<resultVar> <moduleName> <varName>)
15656 If pkg-config returns multiple values for the specified vari‐
15658 able, resultVar will contain a ;-list.
15659 For example:
15661 pkg_get_variable(GI_GIRDIR gobject-introspection-1.0 girdir)
15663 Variables Affecting Behavior
15665 PKG_CONFIG_EXECUTABLE
15666 This cache variable can be set to the path of the pkg-config ex‐
15667 ecutable. find_program() is called internally by the module
15668 with this variable.
15669 New in version 3.1: The PKG_CONFIG environment variable can be
15671 used as a hint if PKG_CONFIG_EXECUTABLE has not yet been set.
15672 Changed in version 3.22: If the PKG_CONFIG environment variable
15675 is set, only the first argument is taken from it when using it
15676 as a hint.
15677 PKG_CONFIG_ARGN
15680 New in version 3.22.
15681 This cache variable can be set to a list of arguments to addi‐
15684 tionally pass to pkg-config if needed. If not provided, it will
15685 be initialized from the PKG_CONFIG environment variable, if set.
15686 The first argument in that environment variable is assumed to be
15687 the pkg-config program, while all remaining arguments after that
15688 are used to initialize PKG_CONFIG_ARGN. If no such environment
15689 variable is defined, PKG_CONFIG_ARGN is initialized to an empty
15690 string. The module does not update the variable once it has been
15691 set in the cache.
15692 PKG_CONFIG_USE_CMAKE_PREFIX_PATH
15694 New in version 3.1.
15695 Specifies whether pkg_check_modules() and pkg_search_module()
15698 should add the paths in the CMAKE_PREFIX_PATH, CMAKE_FRAME‐
15699 WORK_PATH and CMAKE_APPBUNDLE_PATH cache and environment vari‐
15700 ables to the pkg-config search path.
15701 If this variable is not set, this behavior is enabled by default
15703 if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later, disabled oth‐
15704 erwise.
15705 FindPNG
15707 Find libpng, the official reference library for the PNG image format.
15708 Imported targets
15710 New in version 3.5.
15711 This module defines the following IMPORTED target:
15714 PNG::PNG
15716 The libpng library, if found.
15717 Result variables
15719 This module will set the following variables in your project:
15720 PNG_INCLUDE_DIRS
15722 where to find png.h, etc.
15723 PNG_LIBRARIES
15725 the libraries to link against to use PNG.
15726 PNG_DEFINITIONS
15728 You should add_definitions(${PNG_DEFINITIONS}) before compiling
15729 code that includes png library files.
15730 PNG_FOUND
15732 If false, do not try to use PNG.
15733 PNG_VERSION_STRING
15735 the version of the PNG library found (since CMake 2.8.8)
15736 Obsolete variables
15738 The following variables may also be set, for backwards compatibility:
15739 PNG_LIBRARY
15741 where to find the PNG library.
15742 PNG_INCLUDE_DIR
15744 where to find the PNG headers (same as PNG_INCLUDE_DIRS)
15745 Since PNG depends on the ZLib compression library, none of the above
15747 will be defined unless ZLib can be found.
15748 FindPostgreSQL
15750 Find the PostgreSQL installation.
15751 IMPORTED Targets
15753 New in version 3.14.
15754 This module defines IMPORTED target PostgreSQL::PostgreSQL if Post‐
15757 greSQL has been found.
15758 Result Variables
15760 This module will set the following variables in your project:
15761 PostgreSQL_FOUND
15763 True if PostgreSQL is found.
15764 PostgreSQL_LIBRARIES
15766 the PostgreSQL libraries needed for linking
15767 PostgreSQL_INCLUDE_DIRS
15769 the directories of the PostgreSQL headers
15770 PostgreSQL_LIBRARY_DIRS
15772 the link directories for PostgreSQL libraries
15773 PostgreSQL_VERSION_STRING
15775 the version of PostgreSQL found
15776 PostgreSQL_TYPE_INCLUDE_DIR
15778 the directories of the PostgreSQL server headers
15779 Components
15781 This module contains additional Server component, that forcibly checks
15782 for the presence of server headers. Note that PostgreSQL_TYPE_IN‐
15783 CLUDE_DIR is set regardless of the presence of the Server component in
15784 find_package call.
15785 FindProducer
15787 Though Producer isn't directly part of OpenSceneGraph, its primary user
15788 is OSG so I consider this part of the Findosg* suite used to find Open‐
15789 SceneGraph components. You'll notice that I accept OSGDIR as an envi‐
15790 ronment path.
15791 Each component is separate and you must opt in to each module. You
15793 must also opt into OpenGL (and OpenThreads?) as these modules won't do
15794 it for you. This is to allow you control over your own system piece by
15795 piece in case you need to opt out of certain components or change the
15796 Find behavior for a particular module (perhaps because the default
15797 FindOpenGL.cmake module doesn't work with your system as an example).
15798 If you want to use a more convenient module that includes everything,
15799 use the FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules.
15800 Locate Producer This module defines PRODUCER_LIBRARY PRODUCER_FOUND, if
15802 false, do not try to link to Producer PRODUCER_INCLUDE_DIR, where to
15803 find the headers
15804 $PRODUCER_DIR is an environment variable that would correspond to the
15806 ./configure --prefix=$PRODUCER_DIR used in building osg.
15807 Created by Eric Wing.
15809 FindProtobuf
15811 Locate and configure the Google Protocol Buffers library.
15812 New in version 3.6: Support for find_package() version checks.
15814 Changed in version 3.6: All input and output variables use the Proto‐
15817 buf_ prefix. Variables with PROTOBUF_ prefix are still supported for
15818 compatibility.
15819 The following variables can be set and are optional:
15822 Protobuf_SRC_ROOT_FOLDER
15824 When compiling with MSVC, if this cache variable is set the pro‐
15825 tobuf-default VS project build locations (vsprojects/Debug and
15826 vsprojects/Release or vsprojects/x64/Debug and vspro‐
15827 jects/x64/Release) will be searched for libraries and binaries.
15828 Protobuf_IMPORT_DIRS
15830 List of additional directories to be searched for imported
15831 .proto files.
15832 Protobuf_DEBUG
15834 New in version 3.6.
15835 Show debug messages.
15838 Protobuf_USE_STATIC_LIBS
15840 New in version 3.9.
15841 Set to ON to force the use of the static libraries. Default is
15844 OFF.
15845 Defines the following variables:
15847 Protobuf_FOUND
15849 Found the Google Protocol Buffers library (libprotobuf & header
15850 files)
15851 Protobuf_VERSION
15853 New in version 3.6.
15854 Version of package found.
15857 Protobuf_INCLUDE_DIRS
15859 Include directories for Google Protocol Buffers
15860 Protobuf_LIBRARIES
15862 The protobuf libraries
15863 Protobuf_PROTOC_LIBRARIES
15865 The protoc libraries
15866 Protobuf_LITE_LIBRARIES
15868 The protobuf-lite libraries
15869 New in version 3.9: The following IMPORTED targets are also defined:
15871 protobuf::libprotobuf
15874 The protobuf library.
15875 protobuf::libprotobuf-lite
15877 The protobuf lite library.
15878 protobuf::libprotoc
15880 The protoc library.
15881 protobuf::protoc
15883 New in version 3.10: The protoc compiler.
15884 The following cache variables are also available to set or use:
15887 Protobuf_LIBRARY
15889 The protobuf library
15890 Protobuf_PROTOC_LIBRARY
15892 The protoc library
15893 Protobuf_INCLUDE_DIR
15895 The include directory for protocol buffers
15896 Protobuf_PROTOC_EXECUTABLE
15898 The protoc compiler
15899 Protobuf_LIBRARY_DEBUG
15901 The protobuf library (debug)
15902 Protobuf_PROTOC_LIBRARY_DEBUG
15904 The protoc library (debug)
15905 Protobuf_LITE_LIBRARY
15907 The protobuf lite library
15908 Protobuf_LITE_LIBRARY_DEBUG
15910 The protobuf lite library (debug)
15911 Example:
15913 find_package(Protobuf REQUIRED)
15915 include_directories(${Protobuf_INCLUDE_DIRS})
15916 include_directories(${CMAKE_CURRENT_BINARY_DIR})
15917 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS foo.proto)
15918 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS EXPORT_MACRO DLL_EXPORT foo.proto)
15919 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS DESCRIPTORS PROTO_DESCS foo.proto)
15920 protobuf_generate_python(PROTO_PY foo.proto)
15921 add_executable(bar bar.cc ${PROTO_SRCS} ${PROTO_HDRS})
15922 target_link_libraries(bar ${Protobuf_LIBRARIES})
15923 NOTE:
15925 The protobuf_generate_cpp and protobuf_generate_python functions and
15926 add_executable() or add_library() calls only work properly within
15927 the same directory.
15928 protobuf_generate_cpp
15930 Add custom commands to process .proto files to C++:
15931 protobuf_generate_cpp (<SRCS> <HDRS>
15933 [DESCRIPTORS <DESC>] [EXPORT_MACRO <MACRO>] [<ARGN>...])
15934 SRCS Variable to define with autogenerated source files
15936 HDRS Variable to define with autogenerated header files
15938 DESCRIPTORS
15940 New in version 3.10: Variable to define with autogener‐
15941 ated descriptor files, if requested.
15942 EXPORT_MACRO
15945 is a macro which should expand to __declspec(dllexport)
15946 or __declspec(dllimport) depending on what is being com‐
15947 piled.
15948 ARGN .proto files
15950 protobuf_generate_python
15952 New in version 3.4.
15953 Add custom commands to process .proto files to Python:
15956 protobuf_generate_python (<PY> [<ARGN>...])
15958 PY Variable to define with autogenerated Python files
15960 ARGN .proto files
15962 FindPython
15964 New in version 3.12.
15965 Find Python interpreter, compiler and development environment (include
15968 directories and libraries).
15969 New in version 3.19: When a version is requested, it can be specified
15971 as a simple value or as a range. For a detailed description of version
15972 range usage and capabilities, refer to the find_package() command.
15973 The following components are supported:
15976 • Interpreter: search for Python interpreter.
15978 • Compiler: search for Python compiler. Only offered by IronPython.
15980 • Development: search for development artifacts (include directories
15982 and libraries).
15983 New in version 3.18: This component includes two sub-components which
15985 can be specified independently:
15986 • Development.Module: search for artifacts for Python module develop‐
15988 ments.
15989 • Development.Embed: search for artifacts for Python embedding devel‐
15991 opments.
15992 • NumPy: search for NumPy include directories.
15995 New in version 3.14: Added the NumPy component.
15997 If no COMPONENTS are specified, Interpreter is assumed.
16000 If component Development is specified, it implies sub-components Devel‐
16002 opment.Module and Development.Embed.
16003 To ensure consistent versions between components Interpreter, Compiler,
16005 Development (or one of its sub-components) and NumPy, specify all com‐
16006 ponents at the same time:
16007 find_package (Python COMPONENTS Interpreter Development)
16009 This module looks preferably for version 3 of Python. If not found,
16011 version 2 is searched. To manage concurrent versions 3 and 2 of
16012 Python, use FindPython3 and FindPython2 modules rather than this one.
16013 NOTE:
16015 If components Interpreter and Development (or one of its sub-compo‐
16016 nents) are both specified, this module search only for interpreter
16017 with same platform architecture as the one defined by CMake configu‐
16018 ration. This constraint does not apply if only Interpreter component
16019 is specified.
16020 Imported Targets
16022 This module defines the following Imported Targets:
16023 Changed in version 3.14: Imported Targets are only created when
16025 CMAKE_ROLE is PROJECT.
16026 Python::Interpreter
16029 Python interpreter. Target defined if component Interpreter is
16030 found.
16031 Python::Compiler
16033 Python compiler. Target defined if component Compiler is found.
16034 Python::Module
16036 New in version 3.15.
16037 Python library for Python module. Target defined if component
16040 Development.Module is found.
16041 Python::Python
16043 Python library for Python embedding. Target defined if component
16044 Development.Embed is found.
16045 Python::NumPy
16047 New in version 3.14.
16048 NumPy Python library. Target defined if component NumPy is
16051 found.
16052 Result Variables
16054 This module will set the following variables in your project (see Stan‐
16055 dard Variable Names):
16056 Python_FOUND
16058 System has the Python requested components.
16059 Python_Interpreter_FOUND
16061 System has the Python interpreter.
16062 Python_EXECUTABLE
16064 Path to the Python interpreter.
16065 Python_INTERPRETER_ID
16067 A short string unique to the interpreter. Possible values in‐
16069 clude:
16070 • Python
16072 • ActivePython
16074 • Anaconda
16076 • Canopy
16078 • IronPython
16080 • PyPy
16082 Python_STDLIB
16084 Standard platform independent installation directory.
16085 Information returned by distutils.syscon‐
16087 fig.get_python_lib(plat_specific=False,standard_lib=True) or
16088 else sysconfig.get_path('stdlib').
16089 Python_STDARCH
16091 Standard platform dependent installation directory.
16092 Information returned by distutils.syscon‐
16094 fig.get_python_lib(plat_specific=True,standard_lib=True) or else
16095 sysconfig.get_path('platstdlib').
16096 Python_SITELIB
16098 Third-party platform independent installation directory.
16099 Information returned by distutils.syscon‐
16101 fig.get_python_lib(plat_specific=False,standard_lib=False) or
16102 else sysconfig.get_path('purelib').
16103 Python_SITEARCH
16105 Third-party platform dependent installation directory.
16106 Information returned by distutils.syscon‐
16108 fig.get_python_lib(plat_specific=True,standard_lib=False) or
16109 else sysconfig.get_path('platlib').
16110 Python_SOABI
16112 New in version 3.17.
16113 Extension suffix for modules.
16116 Information returned by distutils.sysconfig.get_con‐
16118 fig_var('SOABI') or computed from distutils.sysconfig.get_con‐
16119 fig_var('EXT_SUFFIX') or python-config --extension-suffix. If
16120 package distutils.sysconfig is not available, sysconfig.get_con‐
16121 fig_var('SOABI') or sysconfig.get_config_var('EXT_SUFFIX') are
16122 used.
16123 Python_Compiler_FOUND
16125 System has the Python compiler.
16126 Python_COMPILER
16128 Path to the Python compiler. Only offered by IronPython.
16129 Python_COMPILER_ID
16131 A short string unique to the compiler. Possible values include:
16133 • IronPython
16135 Python_DOTNET_LAUNCHER
16137 New in version 3.18.
16138 The .Net interpreter. Only used by IronPython implementation.
16141 Python_Development_FOUND
16143 System has the Python development artifacts.
16144 Python_Development.Module_FOUND
16146 New in version 3.18.
16147 System has the Python development artifacts for Python module.
16150 Python_Development.Embed_FOUND
16152 New in version 3.18.
16153 System has the Python development artifacts for Python embed‐
16156 ding.
16157 Python_INCLUDE_DIRS
16159 The Python include directories.
16160 Python_LINK_OPTIONS
16162 New in version 3.19.
16163 The Python link options. Some configurations require specific
16166 link options for a correct build and execution.
16167 Python_LIBRARIES
16169 The Python libraries.
16170 Python_LIBRARY_DIRS
16172 The Python library directories.
16173 Python_RUNTIME_LIBRARY_DIRS
16175 The Python runtime library directories.
16176 Python_VERSION
16178 Python version.
16179 Python_VERSION_MAJOR
16181 Python major version.
16182 Python_VERSION_MINOR
16184 Python minor version.
16185 Python_VERSION_PATCH
16187 Python patch version.
16188 Python_PyPy_VERSION
16190 New in version 3.18.
16191 Python PyPy version.
16194 Python_NumPy_FOUND
16196 New in version 3.14.
16197 System has the NumPy.
16200 Python_NumPy_INCLUDE_DIRS
16202 New in version 3.14.
16203 The NumPy include directories.
16206 Python_NumPy_VERSION
16208 New in version 3.14.
16209 The NumPy version.
16212 Hints
16214 Python_ROOT_DIR
16215 Define the root directory of a Python installation.
16216 Python_USE_STATIC_LIBS
16218 • If not defined, search for shared libraries and static li‐
16220 braries in that order.
16221 • If set to TRUE, search only for static libraries.
16223 • If set to FALSE, search only for shared libraries.
16225 Python_FIND_ABI
16227 New in version 3.16.
16228 This variable defines which ABIs, as defined in PEP 3149, should
16231 be searched.
16232 NOTE:
16234 This hint will be honored only when searched for Python ver‐
16235 sion 3.
16236 NOTE:
16238 If Python_FIND_ABI is not defined, any ABI will be searched.
16239 The Python_FIND_ABI variable is a 3-tuple specifying, in that
16241 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
16242 element can be set to one of the following:
16243 • ON: Corresponding flag is selected.
16245 • OFF: Corresponding flag is not selected.
16247 • ANY: The two possibilities (ON and OFF) will be searched.
16249 From this 3-tuple, various ABIs will be searched starting from
16251 the most specialized to the most general. Moreover, debug ver‐
16252 sions will be searched after non-debug ones.
16253 For example, if we have:
16255 set (Python_FIND_ABI "ON" "ANY" "ANY")
16257 The following flags combinations will be appended, in that or‐
16259 der, to the artifact names: dmu, dm, du, and d.
16260 And to search any possible ABIs:
16262 set (Python_FIND_ABI "ANY" "ANY" "ANY")
16264 The following combinations, in that order, will be used: mu, m,
16266 u, <empty>, dmu, dm, du and d.
16267 NOTE:
16269 This hint is useful only on POSIX systems. So, on Windows
16270 systems, when Python_FIND_ABI is defined, Python distribu‐
16271 tions from python.org will be found only if value for each
16272 flag is OFF or ANY.
16273 Python_FIND_STRATEGY
16275 New in version 3.15.
16276 This variable defines how lookup will be done. The
16279 Python_FIND_STRATEGY variable can be set to one of the follow‐
16280 ing:
16281 • VERSION: Try to find the most recent version in all specified
16283 locations. This is the default if policy CMP0094 is undefined
16284 or set to OLD.
16285 • LOCATION: Stops lookup as soon as a version satisfying version
16287 constraints is founded. This is the default if policy CMP0094
16288 is set to NEW.
16289 Python_FIND_REGISTRY
16291 New in version 3.13.
16292 On Windows the Python_FIND_REGISTRY variable determine the order
16295 of preference between registry and environment variables. the
16296 Python_FIND_REGISTRY variable can be set to one of the follow‐
16297 ing:
16298 • FIRST: Try to use registry before environment variables. This
16300 is the default.
16301 • LAST: Try to use registry after environment variables.
16303 • NEVER: Never try to use registry.
16305 Python_FIND_FRAMEWORK
16307 New in version 3.15.
16308 On macOS the Python_FIND_FRAMEWORK variable determine the order
16311 of preference between Apple-style and unix-style package compo‐
16312 nents. This variable can take same values as CMAKE_FIND_FRAME‐
16313 WORK variable.
16314 NOTE:
16316 Value ONLY is not supported so FIRST will be used instead.
16317 If Python_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
16319 variable will be used, if any.
16320 Python_FIND_VIRTUALENV
16322 New in version 3.15.
16323 This variable defines the handling of virtual environments man‐
16326 aged by virtualenv or conda. It is meaningful only when a vir‐
16327 tual environment is active (i.e. the activate script has been
16328 evaluated). In this case, it takes precedence over
16329 Python_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
16330 Python_FIND_VIRTUALENV variable can be set to one of the follow‐
16331 ing:
16332 • FIRST: The virtual environment is used before any other stan‐
16334 dard paths to look-up for the interpreter. This is the de‐
16335 fault.
16336 • ONLY: Only the virtual environment is used to look-up for the
16338 interpreter.
16339 • STANDARD: The virtual environment is not used to look-up for
16341 the interpreter but environment variable PATH is always con‐
16342 sidered. In this case, variable Python_FIND_REGISTRY (Win‐
16343 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
16344 LAST or NEVER to select preferably the interpreter from the
16345 virtual environment.
16346 New in version 3.17: Added support for conda environments.
16348 NOTE:
16351 If the component Development is requested, it is strongly
16352 recommended to also include the component Interpreter to get
16353 expected result.
16354 Python_FIND_IMPLEMENTATIONS
16356 New in version 3.18.
16357 This variable defines, in an ordered list, the different imple‐
16360 mentations which will be searched. The Python_FIND_IMPLEMENTA‐
16361 TIONS variable can hold the following values:
16362 • CPython: this is the standard implementation. Various prod‐
16364 ucts, like Anaconda or ActivePython, rely on this implementa‐
16365 tion.
16366 • IronPython: This implementation use the CSharp language for
16368 .NET Framework on top of the Dynamic Language Runtime (DLR).
16369 See IronPython.
16370 • PyPy: This implementation use RPython language and RPython
16372 translation toolchain to produce the python interpreter. See
16373 PyPy.
16374 The default value is:
16376 • Windows platform: CPython, IronPython
16378 • Other platforms: CPython
16380 NOTE:
16382 This hint has the lowest priority of all hints, so even if,
16383 for example, you specify IronPython first and CPython in sec‐
16384 ond, a python product based on CPython can be selected be‐
16385 cause, for example with Python_FIND_STRATEGY=LOCATION, each
16386 location will be search first for IronPython and second for
16387 CPython.
16388 NOTE:
16390 When IronPython is specified, on platforms other than Win‐
16391 dows, the .Net interpreter (i.e. mono command) is expected to
16392 be available through the PATH variable.
16393 Python_FIND_UNVERSIONED_NAMES
16395 New in version 3.20.
16396 This variable defines how the generic names will be searched.
16399 Currently, it only applies to the generic names of the inter‐
16400 preter, namely, python3 or python2 and python. The
16401 Python_FIND_UNVERSIONED_NAMES variable can be set to one of the
16402 following values:
16403 • FIRST: The generic names are searched before the more special‐
16405 ized ones (such as python2.5 for example).
16406 • LAST: The generic names are searched after the more special‐
16408 ized ones. This is the default.
16409 • NEVER: The generic name are not searched at all.
16411 Artifacts Specification
16413 New in version 3.16.
16414 To solve special cases, it is possible to specify directly the arti‐
16417 facts by setting the following variables:
16418 Python_EXECUTABLE
16420 The path to the interpreter.
16421 Python_COMPILER
16423 The path to the compiler.
16424 Python_DOTNET_LAUNCHER
16426 New in version 3.18.
16427 The .Net interpreter. Only used by IronPython implementation.
16430 Python_LIBRARY
16432 The path to the library. It will be used to compute the vari‐
16433 ables Python_LIBRARIES, Python_LIBRARY_DIRS and Python_RUN‐
16434 TIME_LIBRARY_DIRS.
16435 Python_INCLUDE_DIR
16437 The path to the directory of the Python headers. It will be used
16438 to compute the variable Python_INCLUDE_DIRS.
16439 Python_NumPy_INCLUDE_DIR
16441 The path to the directory of the NumPy headers. It will be used
16442 to compute the variable Python_NumPy_INCLUDE_DIRS.
16443 NOTE:
16445 All paths must be absolute. Any artifact specified with a relative
16446 path will be ignored.
16447 NOTE:
16449 When an artifact is specified, all HINTS will be ignored and no
16450 search will be performed for this artifact.
16451 If more than one artifact is specified, it is the user's responsi‐
16453 bility to ensure the consistency of the various artifacts.
16454 By default, this module supports multiple calls in different directo‐
16456 ries of a project with different version/component requirements while
16457 providing correct and consistent results for each call. To support this
16458 behavior, CMake cache is not used in the traditional way which can be
16459 problematic for interactive specification. So, to enable also interac‐
16460 tive specification, module behavior can be controlled with the follow‐
16461 ing variable:
16462 Python_ARTIFACTS_INTERACTIVE
16464 New in version 3.18.
16465 Selects the behavior of the module. This is a boolean variable:
16468 • If set to TRUE: Create CMake cache entries for the above arti‐
16470 fact specification variables so that users can edit them in‐
16471 teractively. This disables support for multiple version/com‐
16472 ponent requirements.
16473 • If set to FALSE or undefined: Enable multiple version/compo‐
16475 nent requirements.
16476 Commands
16478 This module defines the command Python_add_library (when CMAKE_ROLE is
16479 PROJECT), which has the same semantics as add_library() and adds a de‐
16480 pendency to target Python::Python or, when library type is MODULE, to
16481 target Python::Module and takes care of Python module naming rules:
16482 Python_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
16484 <source1> [<source2> ...])
16485 If the library type is not specified, MODULE is assumed.
16487 New in version 3.17: For MODULE library type, if option WITH_SOABI is
16489 specified, the module suffix will include the Python_SOABI value, if
16490 any.
16491 FindPython2
16494 New in version 3.12.
16495 Find Python 2 interpreter, compiler and development environment (in‐
16498 clude directories and libraries).
16499 New in version 3.19: When a version is requested, it can be specified
16501 as a simple value or as a range. For a detailed description of version
16502 range usage and capabilities, refer to the find_package() command.
16503 The following components are supported:
16506 • Interpreter: search for Python 2 interpreter
16508 • Compiler: search for Python 2 compiler. Only offered by IronPython.
16510 • Development: search for development artifacts (include directories
16512 and libraries).
16513 New in version 3.18: This component includes two sub-components which
16515 can be specified independently:
16516 • Development.Module: search for artifacts for Python 2 module devel‐
16518 opments.
16519 • Development.Embed: search for artifacts for Python 2 embedding de‐
16521 velopments.
16522 • NumPy: search for NumPy include directories.
16525 New in version 3.14: Added the NumPy component.
16527 If no COMPONENTS are specified, Interpreter is assumed.
16530 If component Development is specified, it implies sub-components Devel‐
16532 opment.Module and Development.Embed.
16533 To ensure consistent versions between components Interpreter, Compiler,
16535 Development (or one of its sub-components) and NumPy, specify all com‐
16536 ponents at the same time:
16537 find_package (Python2 COMPONENTS Interpreter Development)
16539 This module looks only for version 2 of Python. This module can be used
16541 concurrently with FindPython3 module to use both Python versions.
16542 The FindPython module can be used if Python version does not matter for
16544 you.
16545 NOTE:
16547 If components Interpreter and Development (or one of its sub-compo‐
16548 nents) are both specified, this module search only for interpreter
16549 with same platform architecture as the one defined by CMake configu‐
16550 ration. This constraint does not apply if only Interpreter component
16551 is specified.
16552 Imported Targets
16554 This module defines the following Imported Targets:
16555 Changed in version 3.14: Imported Targets are only created when
16557 CMAKE_ROLE is PROJECT.
16558 Python2::Interpreter
16561 Python 2 interpreter. Target defined if component Interpreter is
16562 found.
16563 Python2::Compiler
16565 Python 2 compiler. Target defined if component Compiler is
16566 found.
16567 Python2::Module
16569 New in version 3.15.
16570 Python 2 library for Python module. Target defined if component
16573 Development.Module is found.
16574 Python2::Python
16576 Python 2 library for Python embedding. Target defined if compo‐
16577 nent Development.Embed is found.
16578 Python2::NumPy
16580 New in version 3.14.
16581 NumPy library for Python 2. Target defined if component NumPy is
16584 found.
16585 Result Variables
16587 This module will set the following variables in your project (see Stan‐
16588 dard Variable Names):
16589 Python2_FOUND
16591 System has the Python 2 requested components.
16592 Python2_Interpreter_FOUND
16594 System has the Python 2 interpreter.
16595 Python2_EXECUTABLE
16597 Path to the Python 2 interpreter.
16598 Python2_INTERPRETER_ID
16600 A short string unique to the interpreter. Possible values in‐
16602 clude:
16603 • Python
16605 • ActivePython
16607 • Anaconda
16609 • Canopy
16611 • IronPython
16613 • PyPy
16615 Python2_STDLIB
16617 Standard platform independent installation directory.
16618 Information returned by distutils.syscon‐
16620 fig.get_python_lib(plat_specific=False,standard_lib=True) or
16621 else sysconfig.get_path('stdlib').
16622 Python2_STDARCH
16624 Standard platform dependent installation directory.
16625 Information returned by distutils.syscon‐
16627 fig.get_python_lib(plat_specific=True,standard_lib=True) or else
16628 sysconfig.get_path('platstdlib').
16629 Python2_SITELIB
16631 Third-party platform independent installation directory.
16632 Information returned by distutils.syscon‐
16634 fig.get_python_lib(plat_specific=False,standard_lib=False) or
16635 else sysconfig.get_path('purelib').
16636 Python2_SITEARCH
16638 Third-party platform dependent installation directory.
16639 Information returned by distutils.syscon‐
16641 fig.get_python_lib(plat_specific=True,standard_lib=False) or
16642 else sysconfig.get_path('platlib').
16643 Python2_Compiler_FOUND
16645 System has the Python 2 compiler.
16646 Python2_COMPILER
16648 Path to the Python 2 compiler. Only offered by IronPython.
16649 Python2_COMPILER_ID
16651 A short string unique to the compiler. Possible values include:
16653 • IronPython
16655 Python2_DOTNET_LAUNCHER
16657 New in version 3.18.
16658 The .Net interpreter. Only used by IronPython implementation.
16661 Python2_Development_FOUND
16663 System has the Python 2 development artifacts.
16664 Python2_Development.Module_FOUND
16666 New in version 3.18.
16667 System has the Python 2 development artifacts for Python module.
16670 Python2_Development.Embed_FOUND
16672 New in version 3.18.
16673 System has the Python 2 development artifacts for Python embed‐
16676 ding.
16677 Python2_INCLUDE_DIRS
16679 The Python 2 include directories.
16680 Python2_LINK_OPTIONS
16682 New in version 3.19.
16683 The Python 2 link options. Some configurations require specific
16686 link options for a correct build and execution.
16687 Python2_LIBRARIES
16689 The Python 2 libraries.
16690 Python2_LIBRARY_DIRS
16692 The Python 2 library directories.
16693 Python2_RUNTIME_LIBRARY_DIRS
16695 The Python 2 runtime library directories.
16696 Python2_VERSION
16698 Python 2 version.
16699 Python2_VERSION_MAJOR
16701 Python 2 major version.
16702 Python2_VERSION_MINOR
16704 Python 2 minor version.
16705 Python2_VERSION_PATCH
16707 Python 2 patch version.
16708 Python2_PyPy_VERSION
16710 New in version 3.18.
16711 Python 2 PyPy version.
16714 Python2_NumPy_FOUND
16716 New in version 3.14.
16717 System has the NumPy.
16720 Python2_NumPy_INCLUDE_DIRS
16722 New in version 3.14.
16723 The NumPy include directories.
16726 Python2_NumPy_VERSION
16728 New in version 3.14.
16729 The NumPy version.
16732 Hints
16734 Python2_ROOT_DIR
16735 Define the root directory of a Python 2 installation.
16736 Python2_USE_STATIC_LIBS
16738 • If not defined, search for shared libraries and static li‐
16740 braries in that order.
16741 • If set to TRUE, search only for static libraries.
16743 • If set to FALSE, search only for shared libraries.
16745 Python2_FIND_STRATEGY
16747 New in version 3.15.
16748 This variable defines how lookup will be done. The
16751 Python2_FIND_STRATEGY variable can be set to one of the follow‐
16752 ing:
16753 • VERSION: Try to find the most recent version in all specified
16755 locations. This is the default if policy CMP0094 is undefined
16756 or set to OLD.
16757 • LOCATION: Stops lookup as soon as a version satisfying version
16759 constraints is founded. This is the default if policy CMP0094
16760 is set to NEW.
16761 Python2_FIND_REGISTRY
16763 New in version 3.13.
16764 On Windows the Python2_FIND_REGISTRY variable determine the or‐
16767 der of preference between registry and environment variables.
16768 the Python2_FIND_REGISTRY variable can be set to one of the fol‐
16769 lowing:
16770 • FIRST: Try to use registry before environment variables. This
16772 is the default.
16773 • LAST: Try to use registry after environment variables.
16775 • NEVER: Never try to use registry.
16777 Python2_FIND_FRAMEWORK
16779 New in version 3.15.
16780 On macOS the Python2_FIND_FRAMEWORK variable determine the order
16783 of preference between Apple-style and unix-style package compo‐
16784 nents. This variable can take same values as CMAKE_FIND_FRAME‐
16785 WORK variable.
16786 NOTE:
16788 Value ONLY is not supported so FIRST will be used instead.
16789 If Python2_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
16791 variable will be used, if any.
16792 Python2_FIND_VIRTUALENV
16794 New in version 3.15.
16795 This variable defines the handling of virtual environments man‐
16798 aged by virtualenv or conda. It is meaningful only when a vir‐
16799 tual environment is active (i.e. the activate script has been
16800 evaluated). In this case, it takes precedence over
16801 Python2_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
16802 Python2_FIND_VIRTUALENV variable can be set to one of the fol‐
16803 lowing:
16804 • FIRST: The virtual environment is used before any other stan‐
16806 dard paths to look-up for the interpreter. This is the de‐
16807 fault.
16808 • ONLY: Only the virtual environment is used to look-up for the
16810 interpreter.
16811 • STANDARD: The virtual environment is not used to look-up for
16813 the interpreter but environment variable PATH is always con‐
16814 sidered. In this case, variable Python2_FIND_REGISTRY (Win‐
16815 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
16816 LAST or NEVER to select preferably the interpreter from the
16817 virtual environment.
16818 New in version 3.17: Added support for conda environments.
16820 NOTE:
16823 If the component Development is requested, it is strongly
16824 recommended to also include the component Interpreter to get
16825 expected result.
16826 Python2_FIND_IMPLEMENTATIONS
16828 New in version 3.18.
16829 This variable defines, in an ordered list, the different imple‐
16832 mentations which will be searched. The Python2_FIND_IMPLEMENTA‐
16833 TIONS variable can hold the following values:
16834 • CPython: this is the standard implementation. Various prod‐
16836 ucts, like Anaconda or ActivePython, rely on this implementa‐
16837 tion.
16838 • IronPython: This implementation use the CSharp language for
16840 .NET Framework on top of the Dynamic Language Runtime (DLR).
16841 See IronPython.
16842 • PyPy: This implementation use RPython language and RPython
16844 translation toolchain to produce the python interpreter. See
16845 PyPy.
16846 The default value is:
16848 • Windows platform: CPython, IronPython
16850 • Other platforms: CPython
16852 NOTE:
16854 This hint has the lowest priority of all hints, so even if,
16855 for example, you specify IronPython first and CPython in sec‐
16856 ond, a python product based on CPython can be selected be‐
16857 cause, for example with Python2_FIND_STRATEGY=LOCATION, each
16858 location will be search first for IronPython and second for
16859 CPython.
16860 NOTE:
16862 When IronPython is specified, on platforms other than Win‐
16863 dows, the .Net interpreter (i.e. mono command) is expected to
16864 be available through the PATH variable.
16865 Python2_FIND_UNVERSIONED_NAMES
16867 New in version 3.20.
16868 This variable defines how the generic names will be searched.
16871 Currently, it only applies to the generic names of the inter‐
16872 preter, namely, python2 and python. The Python2_FIND_UNVER‐
16873 SIONED_NAMES variable can be set to one of the following values:
16874 • FIRST: The generic names are searched before the more special‐
16876 ized ones (such as python2.5 for example).
16877 • LAST: The generic names are searched after the more special‐
16879 ized ones. This is the default.
16880 • NEVER: The generic name are not searched at all.
16882 Artifacts Specification
16884 New in version 3.16.
16885 To solve special cases, it is possible to specify directly the arti‐
16888 facts by setting the following variables:
16889 Python2_EXECUTABLE
16891 The path to the interpreter.
16892 Python2_COMPILER
16894 The path to the compiler.
16895 Python2_DOTNET_LAUNCHER
16897 New in version 3.18.
16898 The .Net interpreter. Only used by IronPython implementation.
16901 Python2_LIBRARY
16903 The path to the library. It will be used to compute the vari‐
16904 ables Python2_LIBRARIES, Python2_LIBRARY_DIRS and Python2_RUN‐
16905 TIME_LIBRARY_DIRS.
16906 Python2_INCLUDE_DIR
16908 The path to the directory of the Python headers. It will be used
16909 to compute the variable Python2_INCLUDE_DIRS.
16910 Python2_NumPy_INCLUDE_DIR
16912 The path to the directory of the NumPy headers. It will be used
16913 to compute the variable Python2_NumPy_INCLUDE_DIRS.
16914 NOTE:
16916 All paths must be absolute. Any artifact specified with a relative
16917 path will be ignored.
16918 NOTE:
16920 When an artifact is specified, all HINTS will be ignored and no
16921 search will be performed for this artifact.
16922 If more than one artifact is specified, it is the user's responsi‐
16924 bility to ensure the consistency of the various artifacts.
16925 By default, this module supports multiple calls in different directo‐
16927 ries of a project with different version/component requirements while
16928 providing correct and consistent results for each call. To support this
16929 behavior, CMake cache is not used in the traditional way which can be
16930 problematic for interactive specification. So, to enable also interac‐
16931 tive specification, module behavior can be controlled with the follow‐
16932 ing variable:
16933 Python2_ARTIFACTS_INTERACTIVE
16935 New in version 3.18.
16936 Selects the behavior of the module. This is a boolean variable:
16939 • If set to TRUE: Create CMake cache entries for the above arti‐
16941 fact specification variables so that users can edit them in‐
16942 teractively. This disables support for multiple version/com‐
16943 ponent requirements.
16944 • If set to FALSE or undefined: Enable multiple version/compo‐
16946 nent requirements.
16947 Commands
16949 This module defines the command Python2_add_library (when CMAKE_ROLE is
16950 PROJECT), which has the same semantics as add_library() and adds a de‐
16951 pendency to target Python2::Python or, when library type is MODULE, to
16952 target Python2::Module and takes care of Python module naming rules:
16953 Python2_add_library (<name> [STATIC | SHARED | MODULE]
16955 <source1> [<source2> ...])
16956 If library type is not specified, MODULE is assumed.
16958 FindPython3
16960 New in version 3.12.
16961 Find Python 3 interpreter, compiler and development environment (in‐
16964 clude directories and libraries).
16965 New in version 3.19: When a version is requested, it can be specified
16967 as a simple value or as a range. For a detailed description of version
16968 range usage and capabilities, refer to the find_package() command.
16969 The following components are supported:
16972 • Interpreter: search for Python 3 interpreter
16974 • Compiler: search for Python 3 compiler. Only offered by IronPython.
16976 • Development: search for development artifacts (include directories
16978 and libraries).
16979 New in version 3.18: This component includes two sub-components which
16981 can be specified independently:
16982 • Development.Module: search for artifacts for Python 3 module devel‐
16984 opments.
16985 • Development.Embed: search for artifacts for Python 3 embedding de‐
16987 velopments.
16988 • NumPy: search for NumPy include directories.
16991 New in version 3.14: Added the NumPy component.
16993 If no COMPONENTS are specified, Interpreter is assumed.
16996 If component Development is specified, it implies sub-components Devel‐
16998 opment.Module and Development.Embed.
16999 To ensure consistent versions between components Interpreter, Compiler,
17001 Development (or one of its sub-components) and NumPy, specify all com‐
17002 ponents at the same time:
17003 find_package (Python3 COMPONENTS Interpreter Development)
17005 This module looks only for version 3 of Python. This module can be used
17007 concurrently with FindPython2 module to use both Python versions.
17008 The FindPython module can be used if Python version does not matter for
17010 you.
17011 NOTE:
17013 If components Interpreter and Development (or one of its sub-compo‐
17014 nents) are both specified, this module search only for interpreter
17015 with same platform architecture as the one defined by CMake configu‐
17016 ration. This constraint does not apply if only Interpreter component
17017 is specified.
17018 Imported Targets
17020 This module defines the following Imported Targets:
17021 Changed in version 3.14: Imported Targets are only created when
17023 CMAKE_ROLE is PROJECT.
17024 Python3::Interpreter
17027 Python 3 interpreter. Target defined if component Interpreter is
17028 found.
17029 Python3::Compiler
17031 Python 3 compiler. Target defined if component Compiler is
17032 found.
17033 Python3::Module
17035 New in version 3.15.
17036 Python 3 library for Python module. Target defined if component
17039 Development.Module is found.
17040 Python3::Python
17042 Python 3 library for Python embedding. Target defined if compo‐
17043 nent Development.Embed is found.
17044 Python3::NumPy
17046 New in version 3.14.
17047 NumPy library for Python 3. Target defined if component NumPy is
17050 found.
17051 Result Variables
17053 This module will set the following variables in your project (see Stan‐
17054 dard Variable Names):
17055 Python3_FOUND
17057 System has the Python 3 requested components.
17058 Python3_Interpreter_FOUND
17060 System has the Python 3 interpreter.
17061 Python3_EXECUTABLE
17063 Path to the Python 3 interpreter.
17064 Python3_INTERPRETER_ID
17066 A short string unique to the interpreter. Possible values in‐
17068 clude:
17069 • Python
17071 • ActivePython
17073 • Anaconda
17075 • Canopy
17077 • IronPython
17079 • PyPy
17081 Python3_STDLIB
17083 Standard platform independent installation directory.
17084 Information returned by distutils.syscon‐
17086 fig.get_python_lib(plat_specific=False,standard_lib=True) or
17087 else sysconfig.get_path('stdlib').
17088 Python3_STDARCH
17090 Standard platform dependent installation directory.
17091 Information returned by distutils.syscon‐
17093 fig.get_python_lib(plat_specific=True,standard_lib=True) or else
17094 sysconfig.get_path('platstdlib').
17095 Python3_SITELIB
17097 Third-party platform independent installation directory.
17098 Information returned by distutils.syscon‐
17100 fig.get_python_lib(plat_specific=False,standard_lib=False) or
17101 else sysconfig.get_path('purelib').
17102 Python3_SITEARCH
17104 Third-party platform dependent installation directory.
17105 Information returned by distutils.syscon‐
17107 fig.get_python_lib(plat_specific=True,standard_lib=False) or
17108 else sysconfig.get_path('platlib').
17109 Python3_SOABI
17111 New in version 3.17.
17112 Extension suffix for modules.
17115 Information returned by distutils.sysconfig.get_con‐
17117 fig_var('SOABI') or computed from distutils.sysconfig.get_con‐
17118 fig_var('EXT_SUFFIX') or python3-config --extension-suffix. If
17119 package distutils.sysconfig is not available, sysconfig.get_con‐
17120 fig_var('SOABI') or sysconfig.get_config_var('EXT_SUFFIX') are
17121 used.
17122 Python3_Compiler_FOUND
17124 System has the Python 3 compiler.
17125 Python3_COMPILER
17127 Path to the Python 3 compiler. Only offered by IronPython.
17128 Python3_COMPILER_ID
17130 A short string unique to the compiler. Possible values include:
17132 • IronPython
17134 Python3_DOTNET_LAUNCHER
17136 New in version 3.18.
17137 The .Net interpreter. Only used by IronPython implementation.
17140 Python3_Development_FOUND
17142 System has the Python 3 development artifacts.
17143 Python3_Development.Module_FOUND
17145 New in version 3.18.
17146 System has the Python 3 development artifacts for Python module.
17149 Python3_Development.Embed_FOUND
17151 New in version 3.18.
17152 System has the Python 3 development artifacts for Python embed‐
17155 ding.
17156 Python3_INCLUDE_DIRS
17158 The Python 3 include directories.
17159 Python3_LINK_OPTIONS
17161 New in version 3.19.
17162 The Python 3 link options. Some configurations require specific
17165 link options for a correct build and execution.
17166 Python3_LIBRARIES
17168 The Python 3 libraries.
17169 Python3_LIBRARY_DIRS
17171 The Python 3 library directories.
17172 Python3_RUNTIME_LIBRARY_DIRS
17174 The Python 3 runtime library directories.
17175 Python3_VERSION
17177 Python 3 version.
17178 Python3_VERSION_MAJOR
17180 Python 3 major version.
17181 Python3_VERSION_MINOR
17183 Python 3 minor version.
17184 Python3_VERSION_PATCH
17186 Python 3 patch version.
17187 Python3_PyPy_VERSION
17189 New in version 3.18.
17190 Python 3 PyPy version.
17193 Python3_NumPy_FOUND
17195 New in version 3.14.
17196 System has the NumPy.
17199 Python3_NumPy_INCLUDE_DIRS
17201 New in version 3.14.
17202 The NumPy include directories.
17205 Python3_NumPy_VERSION
17207 New in version 3.14.
17208 The NumPy version.
17211 Hints
17213 Python3_ROOT_DIR
17214 Define the root directory of a Python 3 installation.
17215 Python3_USE_STATIC_LIBS
17217 • If not defined, search for shared libraries and static li‐
17219 braries in that order.
17220 • If set to TRUE, search only for static libraries.
17222 • If set to FALSE, search only for shared libraries.
17224 Python3_FIND_ABI
17226 New in version 3.16.
17227 This variable defines which ABIs, as defined in PEP 3149, should
17230 be searched.
17231 NOTE:
17233 If Python3_FIND_ABI is not defined, any ABI will be searched.
17234 The Python3_FIND_ABI variable is a 3-tuple specifying, in that
17236 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
17237 element can be set to one of the following:
17238 • ON: Corresponding flag is selected.
17240 • OFF: Corresponding flag is not selected.
17242 • ANY: The two possibilities (ON and OFF) will be searched.
17244 From this 3-tuple, various ABIs will be searched starting from
17246 the most specialized to the most general. Moreover, debug ver‐
17247 sions will be searched after non-debug ones.
17248 For example, if we have:
17250 set (Python3_FIND_ABI "ON" "ANY" "ANY")
17252 The following flags combinations will be appended, in that or‐
17254 der, to the artifact names: dmu, dm, du, and d.
17255 And to search any possible ABIs:
17257 set (Python3_FIND_ABI "ANY" "ANY" "ANY")
17259 The following combinations, in that order, will be used: mu, m,
17261 u, <empty>, dmu, dm, du and d.
17262 NOTE:
17264 This hint is useful only on POSIX systems. So, on Windows
17265 systems, when Python3_FIND_ABI is defined, Python distribu‐
17266 tions from python.org will be found only if value for each
17267 flag is OFF or ANY.
17268 Python3_FIND_STRATEGY
17270 New in version 3.15.
17271 This variable defines how lookup will be done. The
17274 Python3_FIND_STRATEGY variable can be set to one of the follow‐
17275 ing:
17276 • VERSION: Try to find the most recent version in all specified
17278 locations. This is the default if policy CMP0094 is undefined
17279 or set to OLD.
17280 • LOCATION: Stops lookup as soon as a version satisfying version
17282 constraints is founded. This is the default if policy CMP0094
17283 is set to NEW.
17284 Python3_FIND_REGISTRY
17286 New in version 3.13.
17287 On Windows the Python3_FIND_REGISTRY variable determine the or‐
17290 der of preference between registry and environment variables.
17291 The Python3_FIND_REGISTRY variable can be set to one of the fol‐
17292 lowing:
17293 • FIRST: Try to use registry before environment variables. This
17295 is the default.
17296 • LAST: Try to use registry after environment variables.
17298 • NEVER: Never try to use registry.
17300 Python3_FIND_FRAMEWORK
17302 New in version 3.15.
17303 On macOS the Python3_FIND_FRAMEWORK variable determine the order
17306 of preference between Apple-style and unix-style package compo‐
17307 nents. This variable can take same values as CMAKE_FIND_FRAME‐
17308 WORK variable.
17309 NOTE:
17311 Value ONLY is not supported so FIRST will be used instead.
17312 If Python3_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
17314 variable will be used, if any.
17315 Python3_FIND_VIRTUALENV
17317 New in version 3.15.
17318 This variable defines the handling of virtual environments man‐
17321 aged by virtualenv or conda. It is meaningful only when a vir‐
17322 tual environment is active (i.e. the activate script has been
17323 evaluated). In this case, it takes precedence over
17324 Python3_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
17325 Python3_FIND_VIRTUALENV variable can be set to one of the fol‐
17326 lowing:
17327 • FIRST: The virtual environment is used before any other stan‐
17329 dard paths to look-up for the interpreter. This is the de‐
17330 fault.
17331 • ONLY: Only the virtual environment is used to look-up for the
17333 interpreter.
17334 • STANDARD: The virtual environment is not used to look-up for
17336 the interpreter but environment variable PATH is always con‐
17337 sidered. In this case, variable Python3_FIND_REGISTRY (Win‐
17338 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
17339 LAST or NEVER to select preferably the interpreter from the
17340 virtual environment.
17341 New in version 3.17: Added support for conda environments.
17343 NOTE:
17346 If the component Development is requested, it is strongly
17347 recommended to also include the component Interpreter to get
17348 expected result.
17349 Python3_FIND_IMPLEMENTATIONS
17351 New in version 3.18.
17352 This variable defines, in an ordered list, the different imple‐
17355 mentations which will be searched. The Python3_FIND_IMPLEMENTA‐
17356 TIONS variable can hold the following values:
17357 • CPython: this is the standard implementation. Various prod‐
17359 ucts, like Anaconda or ActivePython, rely on this implementa‐
17360 tion.
17361 • IronPython: This implementation use the CSharp language for
17363 .NET Framework on top of the Dynamic Language Runtime (DLR).
17364 See IronPython.
17365 • PyPy: This implementation use RPython language and RPython
17367 translation toolchain to produce the python interpreter. See
17368 PyPy.
17369 The default value is:
17371 • Windows platform: CPython, IronPython
17373 • Other platforms: CPython
17375 NOTE:
17377 This hint has the lowest priority of all hints, so even if,
17378 for example, you specify IronPython first and CPython in sec‐
17379 ond, a python product based on CPython can be selected be‐
17380 cause, for example with Python3_FIND_STRATEGY=LOCATION, each
17381 location will be search first for IronPython and second for
17382 CPython.
17383 NOTE:
17385 When IronPython is specified, on platforms other than Win‐
17386 dows, the .Net interpreter (i.e. mono command) is expected to
17387 be available through the PATH variable.
17388 Python3_FIND_UNVERSIONED_NAMES
17390 New in version 3.20.
17391 This variable defines how the generic names will be searched.
17394 Currently, it only applies to the generic names of the inter‐
17395 preter, namely, python3 and python. The Python3_FIND_UNVER‐
17396 SIONED_NAMES variable can be set to one of the following values:
17397 • FIRST: The generic names are searched before the more special‐
17399 ized ones (such as python3.5 for example).
17400 • LAST: The generic names are searched after the more special‐
17402 ized ones. This is the default.
17403 • NEVER: The generic name are not searched at all.
17405 Artifacts Specification
17407 New in version 3.16.
17408 To solve special cases, it is possible to specify directly the arti‐
17411 facts by setting the following variables:
17412 Python3_EXECUTABLE
17414 The path to the interpreter.
17415 Python3_COMPILER
17417 The path to the compiler.
17418 Python3_DOTNET_LAUNCHER
17420 New in version 3.18.
17421 The .Net interpreter. Only used by IronPython implementation.
17424 Python3_LIBRARY
17426 The path to the library. It will be used to compute the vari‐
17427 ables Python3_LIBRARIES, Python3_LIBRARY_DIRS and Python3_RUN‐
17428 TIME_LIBRARY_DIRS.
17429 Python3_INCLUDE_DIR
17431 The path to the directory of the Python headers. It will be used
17432 to compute the variable Python3_INCLUDE_DIRS.
17433 Python3_NumPy_INCLUDE_DIR
17435 The path to the directory of the NumPy headers. It will be used
17436 to compute the variable Python3_NumPy_INCLUDE_DIRS.
17437 NOTE:
17439 All paths must be absolute. Any artifact specified with a relative
17440 path will be ignored.
17441 NOTE:
17443 When an artifact is specified, all HINTS will be ignored and no
17444 search will be performed for this artifact.
17445 If more than one artifact is specified, it is the user's responsi‐
17447 bility to ensure the consistency of the various artifacts.
17448 By default, this module supports multiple calls in different directo‐
17450 ries of a project with different version/component requirements while
17451 providing correct and consistent results for each call. To support this
17452 behavior, CMake cache is not used in the traditional way which can be
17453 problematic for interactive specification. So, to enable also interac‐
17454 tive specification, module behavior can be controlled with the follow‐
17455 ing variable:
17456 Python3_ARTIFACTS_INTERACTIVE
17458 New in version 3.18.
17459 Selects the behavior of the module. This is a boolean variable:
17462 • If set to TRUE: Create CMake cache entries for the above arti‐
17464 fact specification variables so that users can edit them in‐
17465 teractively. This disables support for multiple version/com‐
17466 ponent requirements.
17467 • If set to FALSE or undefined: Enable multiple version/compo‐
17469 nent requirements.
17470 Commands
17472 This module defines the command Python3_add_library (when CMAKE_ROLE is
17473 PROJECT), which has the same semantics as add_library() and adds a de‐
17474 pendency to target Python3::Python or, when library type is MODULE, to
17475 target Python3::Module and takes care of Python module naming rules:
17476 Python3_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
17478 <source1> [<source2> ...])
17479 If the library type is not specified, MODULE is assumed.
17481 New in version 3.17: For MODULE library type, if option WITH_SOABI is
17483 specified, the module suffix will include the Python3_SOABI value, if
17484 any.
17485 FindQt3
17488 Locate Qt include paths and libraries
17489 This module defines:
17491 QT_INCLUDE_DIR - where to find qt.h, etc.
17493 QT_LIBRARIES - the libraries to link against to use Qt.
17494 QT_DEFINITIONS - definitions to use when
17495 compiling code that uses Qt.
17496 QT_FOUND - If false, don't try to use Qt.
17497 QT_VERSION_STRING - the version of Qt found
17498 If you need the multithreaded version of Qt, set QT_MT_REQUIRED to TRUE
17500 Also defined, but not for general use are:
17502 QT_MOC_EXECUTABLE, where to find the moc tool.
17504 QT_UIC_EXECUTABLE, where to find the uic tool.
17505 QT_QT_LIBRARY, where to find the Qt library.
17506 QT_QTMAIN_LIBRARY, where to find the qtmain
17507 library. This is only required by Qt3 on Windows.
17508 FindQt4
17510 Finding and Using Qt4
17511 This module can be used to find Qt4. The most important issue is that
17512 the Qt4 qmake is available via the system path. This qmake is then
17513 used to detect basically everything else. This module defines a number
17514 of IMPORTED targets, macros and variables.
17515 Typical usage could be something like:
17517 set(CMAKE_AUTOMOC ON)
17519 set(CMAKE_INCLUDE_CURRENT_DIR ON)
17520 find_package(Qt4 4.4.3 REQUIRED QtGui QtXml)
17521 add_executable(myexe main.cpp)
17522 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
17523 NOTE:
17525 When using IMPORTED targets, the qtmain.lib static library is auto‐
17526 matically linked on Windows for WIN32 executables. To disable that
17527 globally, set the QT4_NO_LINK_QTMAIN variable before finding Qt4. To
17528 disable that for a particular executable, set the QT4_NO_LINK_QTMAIN
17529 target property to TRUE on the executable.
17530 Qt Build Tools
17532 Qt relies on some bundled tools for code generation, such as moc for
17533 meta-object code generation,``uic`` for widget layout and population,
17534 and rcc for virtual filesystem content generation. These tools may be
17535 automatically invoked by cmake(1) if the appropriate conditions are
17536 met. See cmake-qt(7) for more.
17537 Qt Macros
17539 In some cases it can be necessary or useful to invoke the Qt build
17540 tools in a more-manual way. Several macros are available to add targets
17541 for such uses.
17542 macro QT4_WRAP_CPP(outfiles inputfile ... [TARGET tgt] OPTIONS ...)
17544 create moc code from a list of files containing Qt class with
17545 the Q_OBJECT declaration. Per-directory preprocessor definitions
17546 are also added. If the <tgt> is specified, the
17547 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
17548 the <tgt> are passed to moc. Options may be given to moc, such as
17549 those found when executing "moc -help".
17550 macro QT4_WRAP_UI(outfiles inputfile ... OPTIONS ...)
17552 create code from a list of Qt designer ui files.
17553 Options may be given to uic, such as those found
17554 when executing "uic -help"
17555 macro QT4_ADD_RESOURCES(outfiles inputfile ... OPTIONS ...)
17557 create code from a list of Qt resource files.
17558 Options may be given to rcc, such as those found
17559 when executing "rcc -help"
17560 macro QT4_GENERATE_MOC(inputfile outputfile [TARGET tgt])
17562 creates a rule to run moc on infile and create outfile.
17563 Use this if for some reason QT4_WRAP_CPP() isn't appropriate, e.g.
17564 because you need a custom filename for the moc file or something
17565 similar. If the <tgt> is specified, the
17566 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
17567 the <tgt> are passed to moc.
17568 macro QT4_ADD_DBUS_INTERFACE(outfiles interface basename)
17570 Create the interface header and implementation files with the
17571 given basename from the given interface xml file and add it to
17572 the list of sources.
17573 You can pass additional parameters to the qdbusxml2cpp call by setting
17575 properties on the input file:
17576 INCLUDE the given file will be included in the generate interface header
17578 CLASSNAME the generated class is named accordingly
17580 NO_NAMESPACE the generated class is not wrapped in a namespace
17582 macro QT4_ADD_DBUS_INTERFACES(outfiles inputfile ... )
17584 Create the interface header and implementation files
17585 for all listed interface xml files.
17586 The basename will be automatically determined from the name
17587 of the xml file.
17588 The source file properties described for
17590 QT4_ADD_DBUS_INTERFACE also apply here.
17591 macro QT4_ADD_DBUS_ADAPTOR(outfiles xmlfile parentheader parentclassname
17593 [basename] [classname])
17594 create a dbus adaptor (header and implementation file) from the xml file
17595 describing the interface, and add it to the list of sources. The adaptor
17596 forwards the calls to a parent class, defined in parentheader and named
17597 parentclassname. The name of the generated files will be
17598 <basename>adaptor.{cpp,h} where basename defaults to the basename of the
17599 xml file.
17600 If <classname> is provided, then it will be used as the classname of the
17601 adaptor itself.
17602 macro QT4_GENERATE_DBUS_INTERFACE( header [interfacename] OPTIONS ...)
17604 generate the xml interface file from the given header.
17605 If the optional argument interfacename is omitted, the name of the
17606 interface file is constructed from the basename of the header with
17607 the suffix .xml appended.
17608 Options may be given to qdbuscpp2xml, such as those found when
17609 executing "qdbuscpp2xml --help"
17610 macro QT4_CREATE_TRANSLATION( qm_files directories ... sources ...
17612 ts_files ... OPTIONS ...)
17613 out: qm_files
17614 in: directories sources ts_files
17615 options: flags to pass to lupdate, such as -extensions to specify
17616 extensions for a directory scan.
17617 generates commands to create .ts (via lupdate) and .qm
17618 (via lrelease) - files from directories and/or sources. The ts files are
17619 created and/or updated in the source tree (unless given with full paths).
17620 The qm files are generated in the build tree.
17621 Updating the translations can be done by adding the qm_files
17622 to the source list of your library/executable, so they are
17623 always updated, or by adding a custom target to control when
17624 they get updated/generated.
17625 macro QT4_ADD_TRANSLATION( qm_files ts_files ... )
17627 out: qm_files
17628 in: ts_files
17629 generates commands to create .qm from .ts - files. The generated
17630 filenames can be found in qm_files. The ts_files
17631 must exist and are not updated in any way.
17632 macro QT4_AUTOMOC(sourcefile1 sourcefile2 ... [TARGET tgt])
17634 The qt4_automoc macro is obsolete. Use the CMAKE_AUTOMOC feature instead.
17635 This macro is still experimental.
17636 It can be used to have moc automatically handled.
17637 So if you have the files foo.h and foo.cpp, and in foo.h a
17638 a class uses the Q_OBJECT macro, moc has to run on it. If you don't
17639 want to use QT4_WRAP_CPP() (which is reliable and mature), you can insert
17640 #include "foo.moc"
17641 in foo.cpp and then give foo.cpp as argument to QT4_AUTOMOC(). This will
17642 scan all listed files at cmake-time for such included moc files and if it
17643 finds them cause a rule to be generated to run moc at build time on the
17644 accompanying header file foo.h.
17645 If a source file has the SKIP_AUTOMOC property set it will be ignored by
17646 this macro.
17647 If the <tgt> is specified, the INTERFACE_INCLUDE_DIRECTORIES and
17648 INTERFACE_COMPILE_DEFINITIONS from the <tgt> are passed to moc.
17649 function QT4_USE_MODULES( target [link_type] modules...)
17651 This function is obsolete. Use target_link_libraries with IMPORTED targets
17652 instead.
17653 Make <target> use the <modules> from Qt. Using a Qt module means
17654 to link to the library, add the relevant include directories for the
17655 module, and add the relevant compiler defines for using the module.
17656 Modules are roughly equivalent to components of Qt4, so usage would be
17657 something like:
17658 qt4_use_modules(myexe Core Gui Declarative)
17659 to use QtCore, QtGui and QtDeclarative. The optional <link_type> argument
17660 can be specified as either LINK_PUBLIC or LINK_PRIVATE to specify the
17661 same argument to the target_link_libraries call.
17662 IMPORTED Targets
17664 A particular Qt library may be used by using the corresponding IMPORTED
17665 target with the target_link_libraries() command:
17666 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
17668 Using a target in this way causes :cmake(1)` to use the appropriate in‐
17670 clude directories and compile definitions for the target when compiling
17671 myexe.
17672 Targets are aware of their dependencies, so for example it is not nec‐
17674 essary to list Qt4::QtCore if another Qt library is listed, and it is
17675 not necessary to list Qt4::QtGui if Qt4::QtDeclarative is listed. Tar‐
17676 gets may be tested for existence in the usual way with the if(TARGET)
17677 command.
17678 The Qt toolkit may contain both debug and release libraries. cmake(1)
17680 will choose the appropriate version based on the build configuration.
17681 Qt4::QtCore
17683 The QtCore target
17684 Qt4::QtGui
17686 The QtGui target
17687 Qt4::Qt3Support
17689 The Qt3Support target
17690 Qt4::QtAssistant
17692 The QtAssistant target
17693 Qt4::QtAssistantClient
17695 The QtAssistantClient target
17696 Qt4::QAxContainer
17698 The QAxContainer target (Windows only)
17699 Qt4::QAxServer
17701 The QAxServer target (Windows only)
17702 Qt4::QtDBus
17704 The QtDBus target
17705 Qt4::QtDeclarative
17707 The QtDeclarative target
17708 Qt4::QtDesigner
17710 The QtDesigner target
17711 Qt4::QtDesignerComponents
17713 The QtDesignerComponents target
17714 Qt4::QtHelp
17716 The QtHelp target
17717 Qt4::QtMotif
17719 The QtMotif target
17720 Qt4::QtMultimedia
17722 The QtMultimedia target
17723 Qt4::QtNetwork
17725 The QtNetwork target
17726 Qt4::QtNsPLugin
17728 The QtNsPLugin target
17729 Qt4::QtOpenGL
17731 The QtOpenGL target
17732 Qt4::QtScript
17734 The QtScript target
17735 Qt4::QtScriptTools
17737 The QtScriptTools target
17738 Qt4::QtSql
17740 The QtSql target
17741 Qt4::QtSvg
17743 The QtSvg target
17744 Qt4::QtTest
17746 The QtTest target
17747 Qt4::QtUiTools
17749 The QtUiTools target
17750 Qt4::QtWebKit
17752 The QtWebKit target
17753 Qt4::QtXml
17755 The QtXml target
17756 Qt4::QtXmlPatterns
17758 The QtXmlPatterns target
17759 Qt4::phonon
17761 The phonon target
17762 Result Variables
17764 Below is a detailed list of variables that FindQt4.cmake sets.
17765 Qt4_FOUND
17767 If false, don't try to use Qt 4.
17768 QT_FOUND
17770 If false, don't try to use Qt. This variable is for compatibil‐
17771 ity only.
17772 QT4_FOUND
17774 If false, don't try to use Qt 4. This variable is for compati‐
17775 bility only.
17776 QT_VERSION_MAJOR
17778 The major version of Qt found.
17779 QT_VERSION_MINOR
17781 The minor version of Qt found.
17782 QT_VERSION_PATCH
17784 The patch version of Qt found.
17785 FindQuickTime
17787 Locate QuickTime This module defines QUICKTIME_LIBRARY QUICKTIME_FOUND,
17788 if false, do not try to link to gdal QUICKTIME_INCLUDE_DIR, where to
17789 find the headers
17790 $QUICKTIME_DIR is an environment variable that would correspond to the
17792 ./configure --prefix=$QUICKTIME_DIR
17793 Created by Eric Wing.
17795 FindRTI
17797 Try to find M&S HLA RTI libraries
17798 This module finds if any HLA RTI is installed and locates the standard
17800 RTI include files and libraries.
17801 RTI is a simulation infrastructure standardized by IEEE and SISO. It
17803 has a well defined C++ API that assures that simulation applications
17804 are independent on a particular RTI implementation.
17805 http://en.wikipedia.org/wiki/Run-Time_Infrastructure_(simulation)
17807 This code sets the following variables:
17809 RTI_INCLUDE_DIR = the directory where RTI includes file are found
17811 RTI_LIBRARIES = The libraries to link against to use RTI
17812 RTI_DEFINITIONS = -DRTI_USES_STD_FSTREAM
17813 RTI_FOUND = Set to FALSE if any HLA RTI was not found
17814 Report problems to <certi-devel@nongnu.org>
17816 FindRuby
17818 Find Ruby
17819 This module finds if Ruby is installed and determines where the include
17821 files and libraries are. Ruby 1.8 through 2.7 are supported.
17822 The minimum required version of Ruby can be specified using the stan‐
17824 dard syntax, e.g.
17825 find_package(Ruby 2.5.1 EXACT REQUIRED)
17827 # OR
17828 find_package(Ruby 2.4)
17829 It also determines what the name of the library is.
17831 Virtual environments such as RVM are handled as well, by passing the
17833 argument Ruby_FIND_VIRTUALENV
17834 Result Variables
17836 This module will set the following variables in your project:
17837 Ruby_FOUND
17839 set to true if ruby was found successfully
17840 Ruby_EXECUTABLE
17842 full path to the ruby binary
17843 Ruby_INCLUDE_DIRS
17845 include dirs to be used when using the ruby library
17846 Ruby_LIBRARIES
17848 New in version 3.18: libraries needed to use ruby from C.
17849 Ruby_VERSION
17852 the version of ruby which was found, e.g. "1.8.7"
17853 Ruby_VERSION_MAJOR
17855 Ruby major version.
17856 Ruby_VERSION_MINOR
17858 Ruby minor version.
17859 Ruby_VERSION_PATCH
17861 Ruby patch version.
17862 Changed in version 3.18: Previous versions of CMake used the RUBY_ pre‐
17864 fix for all variables. The following variables are provided for com‐
17865 patibility reasons, don't use them in new code:
17866 RUBY_EXECUTABLE
17869 same as Ruby_EXECUTABLE.
17870 RUBY_INCLUDE_DIRS
17872 same as Ruby_INCLUDE_DIRS.
17873 RUBY_INCLUDE_PATH
17875 same as Ruby_INCLUDE_DIRS.
17876 RUBY_LIBRARY
17878 same as Ruby_LIBRARY.
17879 RUBY_VERSION
17881 same as Ruby_VERSION.
17882 RUBY_FOUND
17884 same as Ruby_FOUND.
17885 Hints
17887 New in version 3.18.
17888 Ruby_ROOT_DIR
17891 Define the root directory of a Ruby installation.
17892 Ruby_FIND_VIRTUALENV
17894 This variable defines the handling of virtual environments man‐
17895 aged by rvm. It is meaningful only when a virtual environment is
17896 active (i.e. the rvm script has been evaluated or at least the
17897 MY_RUBY_HOME environment variable is set). The Ruby_FIND_VIR‐
17898 TUALENV variable can be set to empty or one of the following:
17899 • FIRST: The virtual environment is used before any other stan‐
17901 dard paths to look-up for the interpreter. This is the de‐
17902 fault.
17903 • ONLY: Only the virtual environment is used to look-up for the
17905 interpreter.
17906 • STANDARD: The virtual environment is not used to look-up for
17908 the interpreter (assuming it isn't still in the PATH...)
17909 FindSDL
17911 Locate the SDL library
17912 Imported targets
17914 New in version 3.19.
17915 This module defines the following IMPORTED target:
17918 SDL::SDL
17920 The SDL library, if found
17921 Result variables
17923 This module will set the following variables in your project:
17924 SDL_INCLUDE_DIRS
17926 where to find SDL.h
17927 SDL_LIBRARIES
17929 the name of the library to link against
17930 SDL_FOUND
17932 if false, do not try to link to SDL
17933 SDL_VERSION
17935 the human-readable string containing the version of SDL if found
17936 SDL_VERSION_MAJOR
17938 SDL major version
17939 SDL_VERSION_MINOR
17941 SDL minor version
17942 SDL_VERSION_PATCH
17944 SDL patch version
17945 New in version 3.19: Added the SDL_INCLUDE_DIRS, SDL_LIBRARIES and
17947 SDL_VERSION[_<PART>] variables.
17948 Cache variables
17951 These variables may optionally be set to help this module find the cor‐
17952 rect files:
17953 SDL_INCLUDE_DIR
17955 where to find SDL.h
17956 SDL_LIBRARY
17958 the name of the library to link against
17959 Variables for locating SDL
17961 This module responds to the flag:
17962 SDL_BUILDING_LIBRARY
17964 If this is defined, then no SDL_main will be linked in because
17965 only applications need main(). Otherwise, it is assumed you are
17966 building an application and this module will attempt to locate
17967 and set the proper link flags as part of the returned SDL_LI‐
17968 BRARY variable.
17969 Obsolete variables
17971 Deprecated since version 3.19.
17972 These variables are obsolete and provided for backwards compatibility:
17975 SDL_VERSION_STRING
17977 the human-readable string containing the version of SDL if
17978 found. Identical to SDL_VERSION
17979 Don't forget to include SDLmain.h and SDLmain.m your project for the OS
17981 X framework based version. (Other versions link to -lSDLmain which
17982 this module will try to find on your behalf.) Also for OS X, this mod‐
17983 ule will automatically add the -framework Cocoa on your behalf.
17984 Additional Note: If you see an empty SDL_LIBRARY_TEMP in your configu‐
17986 ration and no SDL_LIBRARY, it means CMake did not find your SDL library
17987 (SDL.dll, libsdl.so, SDL.framework, etc). Set SDL_LIBRARY_TEMP to
17988 point to your SDL library, and configure again. Similarly, if you see
17989 an empty SDLMAIN_LIBRARY, you should set this value as appropriate.
17990 These values are used to generate the final SDL_LIBRARY variable, but
17991 when these values are unset, SDL_LIBRARY does not get created.
17992 $SDLDIR is an environment variable that would correspond to the ./con‐
17994 figure --prefix=$SDLDIR used in building SDL. l.e.galup 9-20-02
17995 On OSX, this will prefer the Framework version (if found) over others.
17997 People will have to manually change the cache values of SDL_LIBRARY to
17998 override this selection or set the CMake environment CMAKE_INCLUDE_PATH
17999 to modify the search paths.
18000 Note that the header path has changed from SDL/SDL.h to just SDL.h This
18002 needed to change because "proper" SDL convention is #include "SDL.h",
18003 not <SDL/SDL.h>. This is done for portability reasons because not all
18004 systems place things in SDL/ (see FreeBSD).
18005 FindSDL_image
18007 Locate SDL_image library
18008 This module defines:
18010 SDL_IMAGE_LIBRARIES, the name of the library to link against
18012 SDL_IMAGE_INCLUDE_DIRS, where to find the headers
18013 SDL_IMAGE_FOUND, if false, do not try to link against
18014 SDL_IMAGE_VERSION_STRING - human-readable string containing the
18015 version of SDL_image
18016 For backward compatibility the following variables are also set:
18018 SDLIMAGE_LIBRARY (same value as SDL_IMAGE_LIBRARIES)
18020 SDLIMAGE_INCLUDE_DIR (same value as SDL_IMAGE_INCLUDE_DIRS)
18021 SDLIMAGE_FOUND (same value as SDL_IMAGE_FOUND)
18022 $SDLDIR is an environment variable that would correspond to the ./con‐
18024 figure --prefix=$SDLDIR used in building SDL.
18025 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
18027 but with modifications to recognize OS X frameworks and additional Unix
18028 paths (FreeBSD, etc).
18029 FindSDL_mixer
18031 Locate SDL_mixer library
18032 This module defines:
18034 SDL_MIXER_LIBRARIES, the name of the library to link against
18036 SDL_MIXER_INCLUDE_DIRS, where to find the headers
18037 SDL_MIXER_FOUND, if false, do not try to link against
18038 SDL_MIXER_VERSION_STRING - human-readable string containing the
18039 version of SDL_mixer
18040 For backward compatibility the following variables are also set:
18042 SDLMIXER_LIBRARY (same value as SDL_MIXER_LIBRARIES)
18044 SDLMIXER_INCLUDE_DIR (same value as SDL_MIXER_INCLUDE_DIRS)
18045 SDLMIXER_FOUND (same value as SDL_MIXER_FOUND)
18046 $SDLDIR is an environment variable that would correspond to the ./con‐
18048 figure --prefix=$SDLDIR used in building SDL.
18049 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
18051 but with modifications to recognize OS X frameworks and additional Unix
18052 paths (FreeBSD, etc).
18053 FindSDL_net
18055 Locate SDL_net library
18056 This module defines:
18058 SDL_NET_LIBRARIES, the name of the library to link against
18060 SDL_NET_INCLUDE_DIRS, where to find the headers
18061 SDL_NET_FOUND, if false, do not try to link against
18062 SDL_NET_VERSION_STRING - human-readable string containing the version of SDL_net
18063 For backward compatibility the following variables are also set:
18065 SDLNET_LIBRARY (same value as SDL_NET_LIBRARIES)
18067 SDLNET_INCLUDE_DIR (same value as SDL_NET_INCLUDE_DIRS)
18068 SDLNET_FOUND (same value as SDL_NET_FOUND)
18069 $SDLDIR is an environment variable that would correspond to the ./con‐
18071 figure --prefix=$SDLDIR used in building SDL.
18072 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
18074 but with modifications to recognize OS X frameworks and additional Unix
18075 paths (FreeBSD, etc).
18076 FindSDL_sound
18078 Locates the SDL_sound library
18079 This module depends on SDL being found and must be called AFTER Find‐
18081 SDL.cmake is called.
18082 This module defines
18084 SDL_SOUND_INCLUDE_DIR, where to find SDL_sound.h
18086 SDL_SOUND_FOUND, if false, do not try to link to SDL_sound
18087 SDL_SOUND_LIBRARIES, this contains the list of libraries that you need
18088 to link against.
18089 SDL_SOUND_EXTRAS, this is an optional variable for you to add your own
18090 flags to SDL_SOUND_LIBRARIES. This is prepended to SDL_SOUND_LIBRARIES.
18091 This is available mostly for cases this module failed to anticipate for
18092 and you must add additional flags. This is marked as ADVANCED.
18093 SDL_SOUND_VERSION_STRING, human-readable string containing the
18094 version of SDL_sound
18095 This module also defines (but you shouldn't need to use directly)
18097 SDL_SOUND_LIBRARY, the name of just the SDL_sound library you would link
18099 against. Use SDL_SOUND_LIBRARIES for you link instructions and not this one.
18100 And might define the following as needed
18102 MIKMOD_LIBRARY
18104 MODPLUG_LIBRARY
18105 OGG_LIBRARY
18106 VORBIS_LIBRARY
18107 SMPEG_LIBRARY
18108 FLAC_LIBRARY
18109 SPEEX_LIBRARY
18110 Typically, you should not use these variables directly, and you should
18112 use SDL_SOUND_LIBRARIES which contains SDL_SOUND_LIBRARY and the other
18113 audio libraries (if needed) to successfully compile on your system.
18114 Created by Eric Wing. This module is a bit more complicated than the
18116 other FindSDL* family modules. The reason is that SDL_sound can be
18117 compiled in a large variety of different ways which are independent of
18118 platform. SDL_sound may dynamically link against other 3rd party li‐
18119 braries to get additional codec support, such as Ogg Vorbis, SMPEG,
18120 ModPlug, MikMod, FLAC, Speex, and potentially others. Under some cir‐
18121 cumstances which I don't fully understand, there seems to be a require‐
18122 ment that dependent libraries of libraries you use must also be explic‐
18123 itly linked against in order to successfully compile. SDL_sound does
18124 not currently have any system in place to know how it was compiled. So
18125 this CMake module does the hard work in trying to discover which 3rd
18126 party libraries are required for building (if any). This module uses a
18127 brute force approach to create a test program that uses SDL_sound, and
18128 then tries to build it. If the build fails, it parses the error output
18129 for known symbol names to figure out which libraries are needed.
18130 Responds to the $SDLDIR and $SDLSOUNDDIR environmental variable that
18132 would correspond to the ./configure --prefix=$SDLDIR used in building
18133 SDL.
18134 On OSX, this will prefer the Framework version (if found) over others.
18136 People will have to manually change the cache values of SDL_LIBRARY to
18137 override this selectionor set the CMake environment CMAKE_INCLUDE_PATH
18138 to modify the search paths.
18139 FindSDL_ttf
18141 Locate SDL_ttf library
18142 This module defines:
18144 SDL_TTF_LIBRARIES, the name of the library to link against
18146 SDL_TTF_INCLUDE_DIRS, where to find the headers
18147 SDL_TTF_FOUND, if false, do not try to link against
18148 SDL_TTF_VERSION_STRING - human-readable string containing the version of SDL_ttf
18149 For backward compatibility the following variables are also set:
18151 SDLTTF_LIBRARY (same value as SDL_TTF_LIBRARIES)
18153 SDLTTF_INCLUDE_DIR (same value as SDL_TTF_INCLUDE_DIRS)
18154 SDLTTF_FOUND (same value as SDL_TTF_FOUND)
18155 $SDLDIR is an environment variable that would correspond to the ./con‐
18157 figure --prefix=$SDLDIR used in building SDL.
18158 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
18160 but with modifications to recognize OS X frameworks and additional Unix
18161 paths (FreeBSD, etc).
18162 FindSelfPackers
18164 Find upx
18165 This module looks for some executable packers (i.e. software that com‐
18167 press executables or shared libs into on-the-fly self-extracting exe‐
18168 cutables or shared libs. Examples:
18169 UPX: http://wildsau.idv.uni-linz.ac.at/mfx/upx.html
18171 FindSquish
18173 -- Typical Use
18174 This module can be used to find Squish.
18176 SQUISH_FOUND If false, don't try to use Squish
18178 SQUISH_VERSION The full version of Squish found
18179 SQUISH_VERSION_MAJOR The major version of Squish found
18180 SQUISH_VERSION_MINOR The minor version of Squish found
18181 SQUISH_VERSION_PATCH The patch version of Squish found
18182 SQUISH_INSTALL_DIR The Squish installation directory
18184 (containing bin, lib, etc)
18185 SQUISH_SERVER_EXECUTABLE The squishserver executable
18186 SQUISH_CLIENT_EXECUTABLE The squishrunner executable
18187 SQUISH_INSTALL_DIR_FOUND Was the install directory found?
18189 SQUISH_SERVER_EXECUTABLE_FOUND Was the server executable found?
18190 SQUISH_CLIENT_EXECUTABLE_FOUND Was the client executable found?
18191 It provides the function squish_add_test() for adding a squish test to
18193 cmake using Squish >= 4.x:
18194 squish_add_test(cmakeTestName
18196 AUT targetName SUITE suiteName TEST squishTestName
18197 [SETTINGSGROUP group] [PRE_COMMAND command] [POST_COMMAND command] )
18198 Changed in version 3.18: In previous CMake versions, this function was
18200 named squish_v4_add_test.
18201 The arguments have the following meaning:
18204 cmakeTestName
18206 this will be used as the first argument for add_test()
18207 AUT targetName
18209 the name of the cmake target which will be used as AUT, i.e. the
18210 executable which will be tested.
18211 SUITE suiteName
18213 this is either the full path to the squish suite, or just the
18214 last directory of the suite, i.e. the suite name. In this case
18215 the CMakeLists.txt which calls squish_add_test() must be located
18216 in the parent directory of the suite directory.
18217 TEST squishTestName
18219 the name of the squish test, i.e. the name of the subdirectory
18220 of the test inside the suite directory.
18221 SETTINGSGROUP group
18223 deprecated, this argument will be ignored.
18224 PRE_COMMAND command
18226 if specified, the given command will be executed before starting
18227 the squish test.
18228 POST_COMMAND command
18230 same as PRE_COMMAND, but after the squish test has been exe‐
18231 cuted.
18232 enable_testing()
18234 find_package(Squish 6.5)
18235 if (SQUISH_FOUND)
18236 squish_add_test(myTestName
18237 AUT myApp
18238 SUITE ${CMAKE_SOURCE_DIR}/tests/mySuite
18239 TEST someSquishTest
18240 )
18241 endif ()
18242 For users of Squish version 3.x the macro squish_v3_add_test() is pro‐
18244 vided:
18245 squish_v3_add_test(testName applicationUnderTest testCase envVars testWrapper)
18247 Use this macro to add a test using Squish 3.x.
18248 enable_testing()
18250 find_package(Squish 3.0)
18251 if (SQUISH_FOUND)
18252 squish_v3_add_test(myTestName myApplication testCase envVars testWrapper)
18253 endif ()
18254 FindSQLite3
18256 New in version 3.14.
18257 Find the SQLite libraries, v3
18260 IMPORTED targets
18262 This module defines the following IMPORTED target:
18263 SQLite::SQLite3
18265 Result variables
18267 This module will set the following variables if found:
18268 SQLite3_INCLUDE_DIRS
18270 where to find sqlite3.h, etc.
18271 SQLite3_LIBRARIES
18273 the libraries to link against to use SQLite3.
18274 SQLite3_VERSION
18276 version of the SQLite3 library found
18277 SQLite3_FOUND
18279 TRUE if found
18280 FindSubversion
18282 Extract information from a subversion working copy
18283 The module defines the following variables:
18285 Subversion_SVN_EXECUTABLE - path to svn command line client
18287 Subversion_VERSION_SVN - version of svn command line client
18288 Subversion_FOUND - true if the command line client was found
18289 SUBVERSION_FOUND - same as Subversion_FOUND, set for compatibility reasons
18290 The minimum required version of Subversion can be specified using the
18292 standard syntax, e.g. find_package(Subversion 1.4).
18293 If the command line client executable is found two macros are defined:
18295 Subversion_WC_INFO(<dir> <var-prefix> [IGNORE_SVN_FAILURE])
18297 Subversion_WC_LOG(<dir> <var-prefix>)
18298 Subversion_WC_INFO extracts information of a subversion working copy at
18300 a given location. This macro defines the following variables if run‐
18301 ning Subversion's info command on <dir> succeeds; otherwise a SEND_ER‐
18302 ROR message is generated.
18303 New in version 3.13: The error can be ignored by providing the IG‐
18305 NORE_SVN_FAILURE option, which causes these variables to remain unde‐
18306 fined.
18307 <var-prefix>_WC_URL - url of the repository (at <dir>)
18310 <var-prefix>_WC_ROOT - root url of the repository
18311 <var-prefix>_WC_REVISION - current revision
18312 <var-prefix>_WC_LAST_CHANGED_AUTHOR - author of last commit
18313 <var-prefix>_WC_LAST_CHANGED_DATE - date of last commit
18314 <var-prefix>_WC_LAST_CHANGED_REV - revision of last commit
18315 <var-prefix>_WC_INFO - output of command `svn info <dir>'
18316 Subversion_WC_LOG retrieves the log message of the base revision of a
18318 subversion working copy at a given location. This macro defines the
18319 variable:
18320 <var-prefix>_LAST_CHANGED_LOG - last log of base revision
18322 Example usage:
18324 find_package(Subversion)
18326 if(SUBVERSION_FOUND)
18327 Subversion_WC_INFO(${PROJECT_SOURCE_DIR} Project)
18328 message("Current revision is ${Project_WC_REVISION}")
18329 Subversion_WC_LOG(${PROJECT_SOURCE_DIR} Project)
18330 message("Last changed log is ${Project_LAST_CHANGED_LOG}")
18331 endif()
18332 FindSWIG
18334 Find the Simplified Wrapper and Interface Generator (SWIG) executable.
18335 This module finds an installed SWIG and determines its version.
18337 New in version 3.18: If a COMPONENTS or OPTIONAL_COMPONENTS argument is
18339 given to the find_package() command, it will also determine supported
18340 target languages.
18341 New in version 3.19: When a version is requested, it can be specified
18344 as a simple value or as a range. For a detailed description of version
18345 range usage and capabilities, refer to the find_package() command.
18346 The module defines the following variables:
18349 SWIG_FOUND
18351 Whether SWIG and any required components were found on the sys‐
18352 tem.
18353 SWIG_EXECUTABLE
18355 Path to the SWIG executable.
18356 SWIG_DIR
18358 Path to the installed SWIG Lib directory (result of swig
18359 -swiglib).
18360 SWIG_VERSION
18362 SWIG executable version (result of swig -version).
18363 SWIG_<lang>_FOUND
18365 If COMPONENTS or OPTIONAL_COMPONENTS are requested, each avail‐
18366 able target language <lang> (lowercase) will be set to TRUE.
18367 Any COMPONENTS given to find_package should be the names of supported
18369 target languages as provided to the LANGUAGE argument of swig_add_li‐
18370 brary, such as python or perl5. Language names must be lowercase.
18371 All information is collected from the SWIG_EXECUTABLE, so the version
18373 to be found can be changed from the command line by means of setting
18374 SWIG_EXECUTABLE.
18375 Example usage requiring SWIG 4.0 or higher and Python language support,
18377 with optional Fortran support:
18378 find_package(SWIG 4.0 COMPONENTS python OPTIONAL_COMPONENTS fortran)
18380 if(SWIG_FOUND)
18381 message("SWIG found: ${SWIG_EXECUTABLE}")
18382 if(NOT SWIG_fortran_FOUND)
18383 message(WARNING "SWIG Fortran bindings cannot be generated")
18384 endif()
18385 endif()
18386 FindTCL
18388 TK_INTERNAL_PATH was removed.
18389 This module finds if Tcl is installed and determines where the include
18391 files and libraries are. It also determines what the name of the li‐
18392 brary is. This code sets the following variables:
18393 TCL_FOUND = Tcl was found
18395 TK_FOUND = Tk was found
18396 TCLTK_FOUND = Tcl and Tk were found
18397 TCL_LIBRARY = path to Tcl library (tcl tcl80)
18398 TCL_INCLUDE_PATH = path to where tcl.h can be found
18399 TCL_TCLSH = path to tclsh binary (tcl tcl80)
18400 TK_LIBRARY = path to Tk library (tk tk80 etc)
18401 TK_INCLUDE_PATH = path to where tk.h can be found
18402 TK_WISH = full path to the wish executable
18403 In an effort to remove some clutter and clear up some issues for people
18405 who are not necessarily Tcl/Tk gurus/developers, some variables were
18406 moved or removed. Changes compared to CMake 2.4 are:
18407 => they were only useful for people writing Tcl/Tk extensions.
18409 => these libs are not packaged by default with Tcl/Tk distributions.
18410 Even when Tcl/Tk is built from source, several flavors of debug libs
18411 are created and there is no real reason to pick a single one
18412 specifically (say, amongst tcl84g, tcl84gs, or tcl84sgx).
18413 Let's leave that choice to the user by allowing him to assign
18414 TCL_LIBRARY to any Tcl library, debug or not.
18415 => this ended up being only a Win32 variable, and there is a lot of
18416 confusion regarding the location of this file in an installed Tcl/Tk
18417 tree anyway (see 8.5 for example). If you need the internal path at
18418 this point it is safer you ask directly where the *source* tree is
18419 and dig from there.
18420 FindTclsh
18422 Find tclsh
18423 This module finds if TCL is installed and determines where the include
18425 files and libraries are. It also determines what the name of the li‐
18426 brary is. This code sets the following variables:
18427 TCLSH_FOUND = TRUE if tclsh has been found
18429 TCL_TCLSH = the path to the tclsh executable
18430 FindTclStub
18432 TCL_STUB_LIBRARY_DEBUG and TK_STUB_LIBRARY_DEBUG were removed.
18433 This module finds Tcl stub libraries. It first finds Tcl include files
18435 and libraries by calling FindTCL.cmake. How to Use the Tcl Stubs Li‐
18436 brary:
18437 http://tcl.activestate.com/doc/howto/stubs.html
18439 Using Stub Libraries:
18441 http://safari.oreilly.com/0130385603/ch48lev1sec3
18443 This code sets the following variables:
18445 TCL_STUB_LIBRARY = path to Tcl stub library
18447 TK_STUB_LIBRARY = path to Tk stub library
18448 TTK_STUB_LIBRARY = path to ttk stub library
18449 In an effort to remove some clutter and clear up some issues for people
18451 who are not necessarily Tcl/Tk gurus/developers, some variables were
18452 moved or removed. Changes compared to CMake 2.4 are:
18453 => these libs are not packaged by default with Tcl/Tk distributions.
18455 Even when Tcl/Tk is built from source, several flavors of debug libs
18456 are created and there is no real reason to pick a single one
18457 specifically (say, amongst tclstub84g, tclstub84gs, or tclstub84sgx).
18458 Let's leave that choice to the user by allowing him to assign
18459 TCL_STUB_LIBRARY to any Tcl library, debug or not.
18460 FindThreads
18462 This module determines the thread library of the system.
18463 Imported Targets
18465 New in version 3.1.
18466 This module defines the following IMPORTED target:
18469 Threads::Threads
18471 The thread library, if found.
18472 Result Variables
18474 The following variables are set:
18475 Threads_FOUND
18477 If a supported thread library was found.
18478 CMAKE_THREAD_LIBS_INIT
18480 The thread library to use. This may be empty if the thread func‐
18481 tions are provided by the system libraries and no special flags
18482 are needed to use them.
18483 CMAKE_USE_WIN32_THREADS_INIT
18485 If the found thread library is the win32 one.
18486 CMAKE_USE_PTHREADS_INIT
18488 If the found thread library is pthread compatible.
18489 CMAKE_HP_PTHREADS_INIT
18491 If the found thread library is the HP thread library.
18492 Variables Affecting Behavior
18494 THREADS_PREFER_PTHREAD_FLAG
18495 New in version 3.1.
18496 If the use of the -pthread compiler and linker flag is preferred
18499 then the caller can set this variable to TRUE. The compiler flag
18500 can only be used with the imported target. Use of both the im‐
18501 ported target as well as this switch is highly recommended for
18502 new code.
18503 This variable has no effect if the system libraries provide the
18505 thread functions, i.e. when CMAKE_THREAD_LIBS_INIT will be
18506 empty.
18507 FindTIFF
18509 Find the TIFF library (libtiff, https://libtiff.gitlab.io/libtiff/).
18510 Optional COMPONENTS
18512 This module supports the optional component CXX, for use with the COM‐
18513 PONENTS argument of the find_package() command. This component has an
18514 associated imported target, as described below.
18515 Imported targets
18517 New in version 3.5.
18518 This module defines the following IMPORTED targets:
18521 TIFF::TIFF
18523 The TIFF library, if found.
18524 TIFF::CXX
18526 New in version 3.19.
18527 The C++ wrapper libtiffxx, if requested by the COMPONENTS CXX
18530 option, if the compiler is not MSVC (which includes the C++
18531 wrapper in libtiff), and if found.
18532 Result variables
18534 This module will set the following variables in your project:
18535 TIFF_FOUND
18537 true if the TIFF headers and libraries were found
18538 TIFF_INCLUDE_DIR
18540 the directory containing the TIFF headers
18541 TIFF_INCLUDE_DIRS
18543 the directory containing the TIFF headers
18544 TIFF_LIBRARIES
18546 TIFF libraries to be linked
18547 Cache variables
18549 The following cache variables may also be set:
18550 TIFF_INCLUDE_DIR
18552 the directory containing the TIFF headers
18553 TIFF_LIBRARY_RELEASE
18555 the path to the TIFF library for release configurations
18556 TIFF_LIBRARY_DEBUG
18558 the path to the TIFF library for debug configurations
18559 TIFFXX_LIBRARY_RELEASE
18561 the path to the TIFFXX library for release configurations
18562 TIFFXX_LIBRARY_DEBUG
18564 the path to the TIFFXX library for debug configurations
18565 New in version 3.4: Debug and Release variants are found separately.
18567 FindUnixCommands
18570 Find Unix commands, including the ones from Cygwin
18571 This module looks for the Unix commands bash, cp, gzip, mv, rm, and tar
18573 and stores the result in the variables BASH, CP, GZIP, MV, RM, and TAR.
18574 FindVTK
18576 This module no longer exists.
18577 This module existed in versions of CMake prior to 3.1, but became only
18579 a thin wrapper around find_package(VTK NO_MODULE) to provide compati‐
18580 bility for projects using long-outdated conventions. Now find_pack‐
18581 age(VTK) will search for VTKConfig.cmake directly.
18582 FindVulkan
18584 New in version 3.7.
18585 Find Vulkan, which is a low-overhead, cross-platform 3D graphics and
18588 computing API.
18589 IMPORTED Targets
18591 This module defines IMPORTED targets if Vulkan has been found:
18592 Vulkan::Vulkan
18594 The main Vulkan library.
18595 Vulkan::glslc
18597 New in version 3.19.
18598 The GLSLC SPIR-V compiler, if it has been found.
18601 Vulkan::Headers
18603 New in version 3.21.
18604 Provides just Vulkan headers include paths, if found. No li‐
18607 brary is included in this target. This can be useful for appli‐
18608 cations that load Vulkan library dynamically.
18609 Vulkan::glslangValidator
18611 New in version 3.21.
18612 The glslangValidator tool, if found. It is used to compile GLSL
18615 and HLSL shaders into SPIR-V.
18616 Result Variables
18618 This module defines the following variables:
18619 Vulkan_FOUND - "True" if Vulkan was found
18621 Vulkan_INCLUDE_DIRS - include directories for Vulkan
18622 Vulkan_LIBRARIES - link against this library to use Vulkan
18623 The module will also define three cache variables:
18625 Vulkan_INCLUDE_DIR - the Vulkan include directory
18627 Vulkan_LIBRARY - the path to the Vulkan library
18628 Vulkan_GLSLC_EXECUTABLE - the path to the GLSL SPIR-V compiler
18629 Vulkan_GLSLANG_VALIDATOR_EXECUTABLE - the path to the glslangValidator tool
18630 Hints
18632 New in version 3.18.
18633 The VULKAN_SDK environment variable optionally specifies the location
18636 of the Vulkan SDK root directory for the given architecture. It is typ‐
18637 ically set by sourcing the toplevel setup-env.sh script of the Vulkan
18638 SDK directory into the shell environment.
18639 FindWget
18641 Find wget
18642 This module looks for wget. This module defines the following values:
18644 WGET_EXECUTABLE: the full path to the wget tool.
18646 WGET_FOUND: True if wget has been found.
18647 FindWish
18649 Find wish installation
18650 This module finds if TCL is installed and determines where the include
18652 files and libraries are. It also determines what the name of the li‐
18653 brary is. This code sets the following variables:
18654 TK_WISH = the path to the wish executable
18656 if UNIX is defined, then it will look for the cygwin version first
18658 FindwxWidgets
18660 Find a wxWidgets (a.k.a., wxWindows) installation.
18661 This module finds if wxWidgets is installed and selects a default con‐
18663 figuration to use. wxWidgets is a modular library. To specify the
18664 modules that you will use, you need to name them as components to the
18665 package:
18666 find_package(wxWidgets COMPONENTS core base ... OPTIONAL_COMPONENTS net
18668 ...)
18669 New in version 3.4: Support for find_package() version argument; web‐
18671 view component.
18672 New in version 3.14: OPTIONAL_COMPONENTS support.
18675 There are two search branches: a windows style and a unix style. For
18678 windows, the following variables are searched for and set to defaults
18679 in case of multiple choices. Change them if the defaults are not de‐
18680 sired (i.e., these are the only variables you should change to select a
18681 configuration):
18682 wxWidgets_ROOT_DIR - Base wxWidgets directory
18684 (e.g., C:/wxWidgets-2.6.3).
18685 wxWidgets_LIB_DIR - Path to wxWidgets libraries
18686 (e.g., C:/wxWidgets-2.6.3/lib/vc_lib).
18687 wxWidgets_CONFIGURATION - Configuration to use
18688 (e.g., msw, mswd, mswu, mswunivud, etc.)
18689 wxWidgets_EXCLUDE_COMMON_LIBRARIES
18690 - Set to TRUE to exclude linking of
18691 commonly required libs (e.g., png tiff
18692 jpeg zlib regex expat).
18693 For unix style it uses the wx-config utility. You can select between
18695 debug/release, unicode/ansi, universal/non-universal, and static/shared
18696 in the QtDialog or ccmake interfaces by turning ON/OFF the following
18697 variables:
18698 wxWidgets_USE_DEBUG
18700 wxWidgets_USE_UNICODE
18701 wxWidgets_USE_UNIVERSAL
18702 wxWidgets_USE_STATIC
18703 There is also a wxWidgets_CONFIG_OPTIONS variable for all other options
18705 that need to be passed to the wx-config utility. For example, to use
18706 the base toolkit found in the /usr/local path, set the variable (before
18707 calling the FIND_PACKAGE command) as such:
18708 set(wxWidgets_CONFIG_OPTIONS --toolkit=base --prefix=/usr)
18710 The following are set after the configuration is done for both windows
18712 and unix style:
18713 wxWidgets_FOUND - Set to TRUE if wxWidgets was found.
18715 wxWidgets_INCLUDE_DIRS - Include directories for WIN32
18716 i.e., where to find "wx/wx.h" and
18717 "wx/setup.h"; possibly empty for unices.
18718 wxWidgets_LIBRARIES - Path to the wxWidgets libraries.
18719 wxWidgets_LIBRARY_DIRS - compile time link dirs, useful for
18720 rpath on UNIX. Typically an empty string
18721 in WIN32 environment.
18722 wxWidgets_DEFINITIONS - Contains defines required to compile/link
18723 against WX, e.g. WXUSINGDLL
18724 wxWidgets_DEFINITIONS_DEBUG- Contains defines required to compile/link
18725 against WX debug builds, e.g. __WXDEBUG__
18726 wxWidgets_CXX_FLAGS - Include dirs and compiler flags for
18727 unices, empty on WIN32. Essentially
18728 "`wx-config --cxxflags`".
18729 wxWidgets_USE_FILE - Convenience include file.
18730 New in version 3.11: The following environment variables can be used as
18732 hints: WX_CONFIG, WXRC_CMD.
18733 Sample usage:
18736 # Note that for MinGW users the order of libs is important!
18738 find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net)
18739 if(wxWidgets_FOUND)
18740 include(${wxWidgets_USE_FILE})
18741 # and for each of your dependent executable/library targets:
18742 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
18743 endif()
18744 If wxWidgets is required (i.e., not an optional part):
18746 find_package(wxWidgets REQUIRED gl core base OPTIONAL_COMPONENTS net)
18748 include(${wxWidgets_USE_FILE})
18749 # and for each of your dependent executable/library targets:
18750 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
18751 FindX11
18753 Find X11 installation
18754 Try to find X11 on UNIX systems. The following values are defined
18756 X11_FOUND - True if X11 is available
18758 X11_INCLUDE_DIR - include directories to use X11
18759 X11_LIBRARIES - link against these to use X11
18760 and also the following more fine grained variables and targets:
18762 New in version 3.14: Imported targets.
18764 X11_ICE_INCLUDE_PATH, X11_ICE_LIB, X11_ICE_FOUND, X11::ICE
18767 X11_SM_INCLUDE_PATH, X11_SM_LIB, X11_SM_FOUND, X11::SM
18768 X11_X11_INCLUDE_PATH, X11_X11_LIB, X11::X11
18769 X11_Xaccessrules_INCLUDE_PATH,
18770 X11_Xaccessstr_INCLUDE_PATH, X11_Xaccess_FOUND
18771 X11_Xau_INCLUDE_PATH, X11_Xau_LIB, X11_Xau_FOUND, X11::Xau
18772 X11_xcb_INCLUDE_PATH, X11_xcb_LIB, X11_xcb_FOUND, X11::xcb
18773 X11_X11_xcb_INCLUDE_PATH, X11_X11_xcb_LIB, X11_X11_xcb_FOUND, X11::X11_xcb
18774 X11_xcb_icccm_INCLUDE_PATH, X11_xcb_icccm_LIB, X11_xcb_icccm_FOUND, X11::xcb_icccm
18775 X11_xcb_util_INCLUDE_PATH, X11_xcb_util_LIB, X11_xcb_util_FOUND, X11::xcb_util
18776 X11_xcb_xfixes_INCLUDE_PATH, X11_xcb_xfixes_LIB, X11_xcb_xfixes_FOUND, X11::xcb_xfixes
18777 X11_xcb_xkb_INCLUDE_PATH, X11_xcb_xkb_LIB, X11_xcb_xkb_FOUND, X11::xcb_xkb
18778 X11_Xcomposite_INCLUDE_PATH, X11_Xcomposite_LIB, X11_Xcomposite_FOUND, X11::Xcomposite
18779 X11_Xcursor_INCLUDE_PATH, X11_Xcursor_LIB, X11_Xcursor_FOUND, X11::Xcursor
18780 X11_Xdamage_INCLUDE_PATH, X11_Xdamage_LIB, X11_Xdamage_FOUND, X11::Xdamage
18781 X11_Xdmcp_INCLUDE_PATH, X11_Xdmcp_LIB, X11_Xdmcp_FOUND, X11::Xdmcp
18782 X11_Xext_INCLUDE_PATH, X11_Xext_LIB, X11_Xext_FOUND, X11::Xext
18783 X11_Xxf86misc_INCLUDE_PATH, X11_Xxf86misc_LIB, X11_Xxf86misc_FOUND, X11::Xxf86misc
18784 X11_Xxf86vm_INCLUDE_PATH, X11_Xxf86vm_LIB X11_Xxf86vm_FOUND, X11::Xxf86vm
18785 X11_Xfixes_INCLUDE_PATH, X11_Xfixes_LIB, X11_Xfixes_FOUND, X11::Xfixes
18786 X11_Xft_INCLUDE_PATH, X11_Xft_LIB, X11_Xft_FOUND, X11::Xft
18787 X11_Xi_INCLUDE_PATH, X11_Xi_LIB, X11_Xi_FOUND, X11::Xi
18788 X11_Xinerama_INCLUDE_PATH, X11_Xinerama_LIB, X11_Xinerama_FOUND, X11::Xinerama
18789 X11_Xkb_INCLUDE_PATH,
18790 X11_Xkblib_INCLUDE_PATH, X11_Xkb_FOUND, X11::Xkb
18791 X11_xkbcommon_INCLUDE_PATH, X11_xkbcommon_LIB, X11_xkbcommon_FOUND, X11::xkbcommon
18792 X11_xkbcommon_X11_INCLUDE_PATH,X11_xkbcommon_X11_LIB,X11_xkbcommon_X11_FOUND,X11::xkbcommon_X11
18793 X11_xkbfile_INCLUDE_PATH, X11_xkbfile_LIB, X11_xkbfile_FOUND, X11::xkbfile
18794 X11_Xmu_INCLUDE_PATH, X11_Xmu_LIB, X11_Xmu_FOUND, X11::Xmu
18795 X11_Xpm_INCLUDE_PATH, X11_Xpm_LIB, X11_Xpm_FOUND, X11::Xpm
18796 X11_Xtst_INCLUDE_PATH, X11_Xtst_LIB, X11_Xtst_FOUND, X11::Xtst
18797 X11_Xrandr_INCLUDE_PATH, X11_Xrandr_LIB, X11_Xrandr_FOUND, X11::Xrandr
18798 X11_Xrender_INCLUDE_PATH, X11_Xrender_LIB, X11_Xrender_FOUND, X11::Xrender
18799 X11_XRes_INCLUDE_PATH, X11_XRes_LIB, X11_XRes_FOUND, X11::XRes
18800 X11_Xss_INCLUDE_PATH, X11_Xss_LIB, X11_Xss_FOUND, X11::Xss
18801 X11_Xt_INCLUDE_PATH, X11_Xt_LIB, X11_Xt_FOUND, X11::Xt
18802 X11_Xutil_INCLUDE_PATH, X11_Xutil_FOUND, X11::Xutil
18803 X11_Xv_INCLUDE_PATH, X11_Xv_LIB, X11_Xv_FOUND, X11::Xv
18804 X11_dpms_INCLUDE_PATH, (in X11_Xext_LIB), X11_dpms_FOUND
18805 X11_XShm_INCLUDE_PATH, (in X11_Xext_LIB), X11_XShm_FOUND
18806 X11_Xshape_INCLUDE_PATH, (in X11_Xext_LIB), X11_Xshape_FOUND
18807 X11_XSync_INCLUDE_PATH, (in X11_Xext_LIB), X11_XSync_FOUND
18808 X11_Xaw_INCLUDE_PATH, X11_Xaw_LIB X11_Xaw_FOUND X11::Xaw
18809 New in version 3.14: Renamed Xxf86misc, X11_Xxf86misc, X11_Xxf86vm,
18811 X11_xkbfile, X11_Xtst, and X11_Xss libraries to match their file names.
18812 Deprecated the X11_Xinput library. Old names are still available for
18813 compatibility.
18814 New in version 3.14: Added the X11_Xext_INCLUDE_PATH variable.
18817 New in version 3.18: Added the xcb, X11-xcb, xcb-icccm, xcb-xkb, xkb‐
18820 common, and xkbcommon-X11 libraries.
18821 New in version 3.19: Added the Xaw, xcb_util, and xcb_xfixes libraries.
18824 FindXalanC
18827 New in version 3.5.
18828 Find the Apache Xalan-C++ XSL transform processor headers and li‐
18831 braries.
18832 Imported targets
18834 This module defines the following IMPORTED targets:
18835 XalanC::XalanC
18837 The Xalan-C++ xalan-c library, if found.
18838 Result variables
18840 This module will set the following variables in your project:
18841 XalanC_FOUND
18843 true if the Xalan headers and libraries were found
18844 XalanC_VERSION
18846 Xalan release version
18847 XalanC_INCLUDE_DIRS
18849 the directory containing the Xalan headers; note XercesC_IN‐
18850 CLUDE_DIRS is also required
18851 XalanC_LIBRARIES
18853 Xalan libraries to be linked; note XercesC_LIBRARIES is also re‐
18854 quired
18855 Cache variables
18857 The following cache variables may also be set:
18858 XalanC_INCLUDE_DIR
18860 the directory containing the Xalan headers
18861 XalanC_LIBRARY
18863 the Xalan library
18864 FindXCTest
18866 New in version 3.3.
18867 Functions to help creating and executing XCTest bundles.
18870 An XCTest bundle is a CFBundle with a special product-type and bundle
18872 extension. The Mac Developer Library provides more information in the
18873 Testing with Xcode document.
18874 Module Functions
18876 xctest_add_bundle
18877 The xctest_add_bundle function creates a XCTest bundle named
18878 <target> which will test the target <testee>. Supported target
18879 types for testee are Frameworks and App Bundles:
18880 xctest_add_bundle(
18882 <target> # Name of the XCTest bundle
18883 <testee> # Target name of the testee
18884 )
18885 xctest_add_test
18887 The xctest_add_test function adds an XCTest bundle to the
18888 project to be run by ctest(1). The test will be named <name> and
18889 tests <bundle>:
18890 xctest_add_test(
18892 <name> # Test name
18893 <bundle> # Target name of XCTest bundle
18894 )
18895 Module Variables
18897 The following variables are set by including this module:
18898 XCTest_FOUND
18900 True if the XCTest Framework and executable were found.
18901 XCTest_EXECUTABLE
18903 The path to the xctest command line tool used to execute XCTest
18904 bundles.
18905 XCTest_INCLUDE_DIRS
18907 The directory containing the XCTest Framework headers.
18908 XCTest_LIBRARIES
18910 The location of the XCTest Framework.
18911 FindXercesC
18913 New in version 3.1.
18914 Find the Apache Xerces-C++ validating XML parser headers and libraries.
18917 Imported targets
18919 New in version 3.5.
18920 This module defines the following IMPORTED targets:
18923 XercesC::XercesC
18925 The Xerces-C++ xerces-c library, if found.
18926 Result variables
18928 This module will set the following variables in your project:
18929 XercesC_FOUND
18931 true if the Xerces headers and libraries were found
18932 XercesC_VERSION
18934 Xerces release version
18935 XercesC_INCLUDE_DIRS
18937 the directory containing the Xerces headers
18938 XercesC_LIBRARIES
18940 Xerces libraries to be linked
18941 Cache variables
18943 The following cache variables may also be set:
18944 XercesC_INCLUDE_DIR
18946 the directory containing the Xerces headers
18947 XercesC_LIBRARY
18949 the Xerces library
18950 New in version 3.4: Debug and Release variants are found separately.
18952 FindXMLRPC
18955 Find xmlrpc
18956 Find the native XMLRPC headers and libraries.
18958 XMLRPC_INCLUDE_DIRS - where to find xmlrpc.h, etc.
18960 XMLRPC_LIBRARIES - List of libraries when using xmlrpc.
18961 XMLRPC_FOUND - True if xmlrpc found.
18962 XMLRPC modules may be specified as components for this find module.
18964 Modules may be listed by running "xmlrpc-c-config". Modules include:
18965 c++ C++ wrapper code
18967 libwww-client libwww-based client
18968 cgi-server CGI-based server
18969 abyss-server ABYSS-based server
18970 Typical usage:
18972 find_package(XMLRPC REQUIRED libwww-client)
18974 FindZLIB
18976 Find the native ZLIB includes and library.
18977 IMPORTED Targets
18979 New in version 3.1.
18980 This module defines IMPORTED target ZLIB::ZLIB, if ZLIB has been found.
18983 Result Variables
18985 This module defines the following variables:
18986 ZLIB_INCLUDE_DIRS - where to find zlib.h, etc.
18988 ZLIB_LIBRARIES - List of libraries when using zlib.
18989 ZLIB_FOUND - True if zlib found.
18990 ZLIB_VERSION_STRING - The version of zlib found (x.y.z)
18992 ZLIB_VERSION_MAJOR - The major version of zlib
18993 ZLIB_VERSION_MINOR - The minor version of zlib
18994 ZLIB_VERSION_PATCH - The patch version of zlib
18995 ZLIB_VERSION_TWEAK - The tweak version of zlib
18996 New in version 3.4: Debug and Release variants are found separately.
18998 Backward Compatibility
19001 The following variable are provided for backward compatibility
19002 ZLIB_MAJOR_VERSION - The major version of zlib
19004 ZLIB_MINOR_VERSION - The minor version of zlib
19005 ZLIB_PATCH_VERSION - The patch version of zlib
19006 Hints
19008 A user may set ZLIB_ROOT to a zlib installation root to tell this mod‐
19009 ule where to look.
19010
19012 Deprecated Utility Modules
19013 AddFileDependencies
19014 Deprecated since version 3.20.
19015 Add dependencies to a source file.
19018 add_file_dependencies(<source> <files>...)
19020 Adds the given <files> to the dependencies of file <source>.
19022 Do not use this command in new code. It is just a wrapper around:
19024 set_property(SOURCE <source> APPEND PROPERTY OBJECT_DEPENDS <files>...)
19026 Instead use the set_property() command to append to the OBJECT_DEPENDS
19028 source file property directly.
19029 CMakeDetermineVSServicePack
19031 Deprecated since version 3.0: Do not use.
19032 The functionality of this module has been superseded by the
19035 CMAKE_<LANG>_COMPILER_VERSION variable that contains the compiler ver‐
19036 sion number.
19037 Determine the Visual Studio service pack of the 'cl' in use.
19039 Usage:
19041 if(MSVC)
19043 include(CMakeDetermineVSServicePack)
19044 DetermineVSServicePack( my_service_pack )
19045 if( my_service_pack )
19046 message(STATUS "Detected: ${my_service_pack}")
19047 endif()
19048 endif()
19049 Function DetermineVSServicePack sets the given variable to one of the
19051 following values or an empty string if unknown:
19052 vc80, vc80sp1
19054 vc90, vc90sp1
19055 vc100, vc100sp1
19056 vc110, vc110sp1, vc110sp2, vc110sp3, vc110sp4
19057 CMakeExpandImportedTargets
19059 Deprecated since version 3.4: Do not use.
19060 This module was once needed to expand imported targets to the underly‐
19063 ing libraries they reference on disk for use with the try_compile() and
19064 try_run() commands. These commands now support imported libraries in
19065 their LINK_LIBRARIES options (since CMake 2.8.11 for try_compile() and
19066 since CMake 3.2 for try_run()).
19067 This module does not support the policy CMP0022 NEW behavior or use of
19069 the INTERFACE_LINK_LIBRARIES property because generator expressions
19070 cannot be evaluated during configuration.
19071 CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
19073 [CONFIGURATION <config>])
19074 CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces
19076 all imported targets contained in this list with their actual file
19077 paths of the referenced libraries on disk, including the libraries from
19078 their link interfaces. If a CONFIGURATION is given, it uses the re‐
19079 spective configuration of the imported targets if it exists. If no
19080 CONFIGURATION is given, it uses the first configuration from
19081 ${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}.
19082 cmake_expand_imported_targets(expandedLibs
19084 LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
19085 CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
19086 CMakeForceCompiler
19088 Deprecated since version 3.6: Do not use.
19089 The macros provided by this module were once intended for use by
19092 cross-compiling toolchain files when CMake was not able to automati‐
19093 cally detect the compiler identification. Since the introduction of
19094 this module, CMake's compiler identification capabilities have improved
19095 and can now be taught to recognize any compiler. Furthermore, the
19096 suite of information CMake detects from a compiler is now too extensive
19097 to be provided by toolchain files using these macros.
19098 One common use case for this module was to skip CMake's checks for a
19100 working compiler when using a cross-compiler that cannot link binaries
19101 without special flags or custom linker scripts. This case is now sup‐
19102 ported by setting the CMAKE_TRY_COMPILE_TARGET_TYPE variable in the
19103 toolchain file instead.
19104 ----
19107 Macro CMAKE_FORCE_C_COMPILER has the following signature:
19111 CMAKE_FORCE_C_COMPILER(<compiler> <compiler-id>)
19113 It sets CMAKE_C_COMPILER to the given compiler and the cmake internal
19115 variable CMAKE_C_COMPILER_ID to the given compiler-id. It also by‐
19116 passes the check for working compiler and basic compiler information
19117 tests.
19118 Macro CMAKE_FORCE_CXX_COMPILER has the following signature:
19120 CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler-id>)
19122 It sets CMAKE_CXX_COMPILER to the given compiler and the cmake internal
19124 variable CMAKE_CXX_COMPILER_ID to the given compiler-id. It also by‐
19125 passes the check for working compiler and basic compiler information
19126 tests.
19127 Macro CMAKE_FORCE_Fortran_COMPILER has the following signature:
19129 CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler-id>)
19131 It sets CMAKE_Fortran_COMPILER to the given compiler and the cmake in‐
19133 ternal variable CMAKE_Fortran_COMPILER_ID to the given compiler-id. It
19134 also bypasses the check for working compiler and basic compiler infor‐
19135 mation tests.
19136 So a simple toolchain file could look like this:
19138 include (CMakeForceCompiler)
19140 set(CMAKE_SYSTEM_NAME Generic)
19141 CMAKE_FORCE_C_COMPILER (chc12 MetrowerksHicross)
19142 CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross)
19143 CMakeParseArguments
19145 This module once implemented the cmake_parse_arguments() command that
19146 is now implemented natively by CMake. It is now an empty placeholder
19147 for compatibility with projects that include it to get the command from
19148 CMake 3.4 and lower.
19149 Documentation
19151 Deprecated since version 3.18: This module does nothing, unless policy
19152 CMP0106 is set to OLD.
19153 This module provides support for the VTK documentation framework. It
19156 relies on several tools (Doxygen, Perl, etc).
19157 MacroAddFileDependencies
19159 Deprecated since version 3.14.
19160 MACRO_ADD_FILE_DEPENDENCIES(<source> <files>...)
19163 Do not use this command in new code. It is just a wrapper around:
19165 set_property(SOURCE <source> APPEND PROPERTY OBJECT_DEPENDS <files>...)
19167 Instead use the set_property() command to append to the OBJECT_DEPENDS
19169 source file property directly.
19170 TestCXXAcceptsFlag
19172 Deprecated since version 3.0: See CheckCXXCompilerFlag.
19173 Check if the CXX compiler accepts a flag.
19176 CHECK_CXX_ACCEPTS_FLAG(<flags> <variable>)
19178 <flags>
19180 the flags to try
19181 <variable>
19183 variable to store the result
19184 UseJavaClassFilelist
19186 Changed in version 3.20: This module was previously documented by mis‐
19187 take and was never meant for direct inclusion by project code. See the
19188 UseJava module.
19189 UseJavaSymlinks
19192 Changed in version 3.20: This module was previously documented by mis‐
19193 take and was never meant for direct inclusion by project code. See the
19194 UseJava module.
19195 UsePkgConfig
19198 Obsolete pkg-config module for CMake, use FindPkgConfig instead.
19199 This module defines the following macro:
19201 PKGCONFIG(package includedir libdir linkflags cflags)
19203 Calling PKGCONFIG will fill the desired information into the 4 given
19205 arguments, e.g. PKGCONFIG(libart-2.0 LIBART_INCLUDE_DIR
19206 LIBART_LINK_DIR LIBART_LINK_FLAGS LIBART_CFLAGS) if pkg-config was NOT
19207 found or the specified software package doesn't exist, the variable
19208 will be empty when the function returns, otherwise they will contain
19209 the respective information
19210 Use_wxWindows
19212 Deprecated since version 2.8.10: Use find_package(wxWidgets) and in‐
19213 clude(${wxWidgets_USE_FILE}) instead.
19214 This convenience include finds if wxWindows is installed and set the
19217 appropriate libs, incdirs, flags etc. author Jan Woetzel <jw -at-
19218 mip.informatik.uni-kiel.de> (07/2003)
19219 USAGE:
19221 just include Use_wxWindows.cmake
19223 in your projects CMakeLists.txt
19224 include( ${CMAKE_MODULE_PATH}/Use_wxWindows.cmake)
19226 if you are sure you need GL then
19228 set(WXWINDOWS_USE_GL 1)
19230 *before* you include this file.
19232 WriteBasicConfigVersionFile
19234 Deprecated since version 3.0: Use the identical command write_ba‐
19235 sic_package_version_file() from module CMakePackageConfigHelpers.
19236 WRITE_BASIC_CONFIG_VERSION_FILE( filename
19239 [VERSION major.minor.patch]
19240 COMPATIBILITY (AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion)
19241 [ARCH_INDEPENDENT]
19242 )
19243 WriteCompilerDetectionHeader
19245 Deprecated since version 3.20: This module is available only if policy
19246 CMP0120 is not set to NEW. Do not use it in new code.
19247 New in version 3.1.
19250 This module provides the function write_compiler_detection_header().
19253 This function can be used to generate a file suitable for preprocessor
19255 inclusion which contains macros to be used in source code:
19256 write_compiler_detection_header(
19258 FILE <file>
19259 PREFIX <prefix>
19260 [OUTPUT_FILES_VAR <output_files_var> OUTPUT_DIR <output_dir>]
19261 COMPILERS <compiler> [...]
19262 FEATURES <feature> [...]
19263 [BARE_FEATURES <feature> [...]]
19264 [VERSION <version>]
19265 [PROLOG <prolog>]
19266 [EPILOG <epilog>]
19267 [ALLOW_UNKNOWN_COMPILERS]
19268 [ALLOW_UNKNOWN_COMPILER_VERSIONS]
19269 )
19270 This generates the file <file> with macros which all have the prefix
19272 <prefix>.
19273 By default, all content is written directly to the <file>. The OUT‐
19275 PUT_FILES_VAR may be specified to cause the compiler-specific content
19276 to be written to separate files. The separate files are then available
19277 in the <output_files_var> and may be consumed by the caller for instal‐
19278 lation for example. The OUTPUT_DIR specifies a relative path from the
19279 main <file> to the compiler-specific files. For example:
19280 write_compiler_detection_header(
19282 FILE climbingstats_compiler_detection.h
19283 PREFIX ClimbingStats
19284 OUTPUT_FILES_VAR support_files
19285 OUTPUT_DIR compilers
19286 COMPILERS GNU Clang MSVC Intel
19287 FEATURES cxx_variadic_templates
19288 )
19289 install(FILES
19290 ${CMAKE_CURRENT_BINARY_DIR}/climbingstats_compiler_detection.h
19291 DESTINATION include
19292 )
19293 install(FILES
19294 ${support_files}
19295 DESTINATION include/compilers
19296 )
19297 VERSION may be used to specify the API version to be generated. Future
19299 versions of CMake may introduce alternative APIs. A given API is se‐
19300 lected by any <version> value greater than or equal to the version of
19301 CMake that introduced the given API and less than the version of CMake
19302 that introduced its succeeding API. The value of the CMAKE_MINIMUM_RE‐
19303 QUIRED_VERSION variable is used if no explicit version is specified.
19304 (As of CMake version 3.22.0 there is only one API version.)
19305 PROLOG may be specified as text content to write at the start of the
19307 header. EPILOG may be specified as text content to write at the end of
19308 the header
19309 At least one <compiler> and one <feature> must be listed. Compilers
19311 which are known to CMake, but not specified are detected and a pre‐
19312 processor #error is generated for them. A preprocessor macro matching
19313 <PREFIX>_COMPILER_IS_<compiler> is generated for each compiler known to
19314 CMake to contain the value 0 or 1.
19315 Possible compiler identifiers are documented with the CMAKE_<LANG>_COM‐
19317 PILER_ID variable. Available features in this version of CMake are
19318 listed in the CMAKE_C_KNOWN_FEATURES and CMAKE_CXX_KNOWN_FEATURES
19319 global properties. See the cmake-compile-features(7) manual for infor‐
19320 mation on compile features.
19321 New in version 3.2: Added MSVC and AppleClang compiler support.
19323 New in version 3.6: Added Intel compiler support.
19326 Changed in version 3.8: The {c,cxx}_std_* meta-features are ignored if
19329 requested.
19330 New in version 3.8: ALLOW_UNKNOWN_COMPILERS and ALLOW_UNKNOWN_COM‐
19333 PILER_VERSIONS cause the module to generate conditions that treat un‐
19334 known compilers as simply lacking all features. Without these options
19335 the default behavior is to generate a #error for unknown compilers and
19336 versions.
19337 New in version 3.12: BARE_FEATURES will define the compatibility macros
19340 with the name used in newer versions of the language standard, so the
19341 code can use the new feature name unconditionally.
19342 Feature Test Macros
19345 For each compiler, a preprocessor macro is generated matching <PRE‐
19346 FIX>_COMPILER_IS_<compiler> which has the content either 0 or 1, de‐
19347 pending on the compiler in use. Preprocessor macros for compiler ver‐
19348 sion components are generated matching <PREFIX>_COMPILER_VERSION_MAJOR
19349 <PREFIX>_COMPILER_VERSION_MINOR and <PREFIX>_COMPILER_VERSION_PATCH
19350 containing decimal values for the corresponding compiler version compo‐
19351 nents, if defined.
19352 A preprocessor test is generated based on the compiler version denoting
19354 whether each feature is enabled. A preprocessor macro matching <PRE‐
19355 FIX>_COMPILER_<FEATURE>, where <FEATURE> is the upper-case <feature>
19356 name, is generated to contain the value 0 or 1 depending on whether the
19357 compiler in use supports the feature:
19358 write_compiler_detection_header(
19360 FILE climbingstats_compiler_detection.h
19361 PREFIX ClimbingStats
19362 COMPILERS GNU Clang AppleClang MSVC Intel
19363 FEATURES cxx_variadic_templates
19364 )
19365 #if ClimbingStats_COMPILER_CXX_VARIADIC_TEMPLATES
19367 template<typename... T>
19368 void someInterface(T t...) { /* ... */ }
19369 #else
19370 // Compatibility versions
19371 template<typename T1>
19372 void someInterface(T1 t1) { /* ... */ }
19373 template<typename T1, typename T2>
19374 void someInterface(T1 t1, T2 t2) { /* ... */ }
19375 template<typename T1, typename T2, typename T3>
19376 void someInterface(T1 t1, T2 t2, T3 t3) { /* ... */ }
19377 #endif
19378 Symbol Macros
19380 Some additional symbol-defines are created for particular features for
19381 use as symbols which may be conditionally defined empty:
19382 class MyClass ClimbingStats_FINAL
19384 {
19385 ClimbingStats_CONSTEXPR int someInterface() { return 42; }
19386 };
19387 The ClimbingStats_FINAL macro will expand to final if the compiler (and
19389 its flags) support the cxx_final feature, and the ClimbingStats_CONST‐
19390 EXPR macro will expand to constexpr if cxx_constexpr is supported.
19391 If BARE_FEATURES cxx_final was given as argument the final keyword will
19393 be defined for old compilers, too.
19394 The following features generate corresponding symbol defines and if
19396 they are available as BARE_FEATURES:
19397 ┌──────────────────┬────────────────────┬─────────────┬──────┐
19400 │Feature │ Define │ Symbol │ bare │
19401 ├──────────────────┼────────────────────┼─────────────┼──────┤
19402 │c_restrict │ <PREFIX>_RE‐ │ restrict │ yes │
19403 │ │ STRICT │ │ │
19404 ├──────────────────┼────────────────────┼─────────────┼──────┤
19405 │cxx_constexpr │ <PREFIX>_CONST‐ │ constexpr │ yes │
19406 │ │ EXPR │ │ │
19407 ├──────────────────┼────────────────────┼─────────────┼──────┤
19408 │cxx_deleted_func‐ │ <PRE‐ │ = delete │ │
19409 │tions │ FIX>_DELETED_FUNC‐ │ │ │
19410 │ │ TION │ │ │
19411 ├──────────────────┼────────────────────┼─────────────┼──────┤
19412 │cxx_extern_tem‐ │ <PREFIX>_EX‐ │ extern │ │
19413 │plates │ TERN_TEMPLATE │ │ │
19414 ├──────────────────┼────────────────────┼─────────────┼──────┤
19415 │cxx_final │ <PREFIX>_FINAL │ final │ yes │
19416 ├──────────────────┼────────────────────┼─────────────┼──────┤
19417 │cxx_noexcept │ <PREFIX>_NOEXCEPT │ noexcept │ yes │
19418 ├──────────────────┼────────────────────┼─────────────┼──────┤
19419 │cxx_noexcept │ <PREFIX>_NOEX‐ │ noexcept(X) │ │
19420 │ │ CEPT_EXPR(X) │ │ │
19421 ├──────────────────┼────────────────────┼─────────────┼──────┤
19422 │cxx_override │ <PREFIX>_OVERRIDE │ override │ yes │
19423 └──────────────────┴────────────────────┴─────────────┴──────┘
19424 Compatibility Implementation Macros
19426 Some features are suitable for wrapping in a macro with a backward com‐
19427 patibility implementation if the compiler does not support the feature.
19428 When the cxx_static_assert feature is not provided by the compiler, a
19430 compatibility implementation is available via the <PREFIX>_STATIC_AS‐
19431 SERT(COND) and <PREFIX>_STATIC_ASSERT_MSG(COND, MSG) function-like
19432 macros. The macros expand to static_assert where that compiler feature
19433 is available, and to a compatibility implementation otherwise. In the
19434 first form, the condition is stringified in the message field of
19435 static_assert. In the second form, the message MSG is passed to the
19436 message field of static_assert, or ignored if using the backward com‐
19437 patibility implementation.
19438 The cxx_attribute_deprecated feature provides a macro definition <PRE‐
19440 FIX>_DEPRECATED, which expands to either the standard [[deprecated]]
19441 attribute or a compiler-specific decorator such as __attri‐
19442 bute__((__deprecated__)) used by GNU compilers.
19443 The cxx_alignas feature provides a macro definition <PREFIX>_ALIGNAS
19445 which expands to either the standard alignas decorator or a com‐
19446 piler-specific decorator such as __attribute__ ((__aligned__)) used by
19447 GNU compilers.
19448 The cxx_alignof feature provides a macro definition <PREFIX>_ALIGNOF
19450 which expands to either the standard alignof decorator or a com‐
19451 piler-specific decorator such as __alignof__ used by GNU compilers.
19452 ┌─────────────────┬──────────────────┬────────────────┬──────┐
19454 │Feature │ Define │ Symbol │ bare │
19455 ├─────────────────┼──────────────────┼────────────────┼──────┤
19456 │cxx_alignas │ <PREFIX>_ALIGNAS │ alignas │ │
19457 ├─────────────────┼──────────────────┼────────────────┼──────┤
19458 │cxx_alignof │ <PREFIX>_ALIGNOF │ alignof │ │
19459 ├─────────────────┼──────────────────┼────────────────┼──────┤
19460 │cxx_nullptr │ <PREFIX>_NULLPTR │ nullptr │ yes │
19461 ├─────────────────┼──────────────────┼────────────────┼──────┤
19462 │cxx_static_as‐ │ <PRE‐ │ static_assert │ │
19463 │sert │ FIX>_STATIC_AS‐ │ │ │
19464 │ │ SERT │ │ │
19465 ├─────────────────┼──────────────────┼────────────────┼──────┤
19466 │cxx_static_as‐ │ <PRE‐ │ static_assert │ │
19467 │sert │ FIX>_STATIC_AS‐ │ │ │
19468 │ │ SERT_MSG │ │ │
19469 ├─────────────────┼──────────────────┼────────────────┼──────┤
19470 │cxx_attri‐ │ <PREFIX>_DEPRE‐ │ [[deprecated]] │ │
19471 │bute_deprecated │ CATED │ │ │
19472 ├─────────────────┼──────────────────┼────────────────┼──────┤
19473 │cxx_attri‐ │ <PREFIX>_DEPRE‐ │ [[deprecated]] │ │
19474 │bute_deprecated │ CATED_MSG │ │ │
19475 ├─────────────────┼──────────────────┼────────────────┼──────┤
19476 │cxx_thread_local │ <PRE‐ │ thread_local │ │
19477 │ │ FIX>_THREAD_LO‐ │ │ │
19478 │ │ CAL │ │ │
19479 └─────────────────┴──────────────────┴────────────────┴──────┘
19480 A use-case which arises with such deprecation macros is the deprecation
19482 of an entire library. In that case, all public API in the library may
19483 be decorated with the <PREFIX>_DEPRECATED macro. This results in very
19484 noisy build output when building the library itself, so the macro may
19485 be may be defined to empty in that case when building the deprecated
19486 library:
19487 add_library(compat_support ${srcs})
19489 target_compile_definitions(compat_support
19490 PRIVATE
19491 CompatSupport_DEPRECATED=
19492 )
19493 Example Usage
19495 NOTE:
19496 This section was migrated from the cmake-compile-features(7) manual
19497 since it relies on the WriteCompilerDetectionHeader module which is
19498 removed by policy CMP0120.
19499 Compile features may be preferred if available, without creating a hard
19501 requirement. For example, a library may provide alternative implemen‐
19502 tations depending on whether the cxx_variadic_templates feature is
19503 available:
19504 #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES
19506 template<int I, int... Is>
19507 struct Interface;
19508 template<int I>
19510 struct Interface<I>
19511 {
19512 static int accumulate()
19513 {
19514 return I;
19515 }
19516 };
19517 template<int I, int... Is>
19519 struct Interface
19520 {
19521 static int accumulate()
19522 {
19523 return I + Interface<Is...>::accumulate();
19524 }
19525 };
19526 #else
19527 template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
19528 struct Interface
19529 {
19530 static int accumulate() { return I1 + I2 + I3 + I4; }
19531 };
19532 #endif
19533 Such an interface depends on using the correct preprocessor defines for
19535 the compiler features. CMake can generate a header file containing
19536 such defines using the WriteCompilerDetectionHeader module. The module
19537 contains the write_compiler_detection_header function which accepts pa‐
19538 rameters to control the content of the generated header file:
19539 write_compiler_detection_header(
19541 FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
19542 PREFIX Foo
19543 COMPILERS GNU
19544 FEATURES
19545 cxx_variadic_templates
19546 )
19547 Such a header file may be used internally in the source code of a
19549 project, and it may be installed and used in the interface of library
19550 code.
19551 For each feature listed in FEATURES, a preprocessor definition is cre‐
19553 ated in the header file, and defined to either 1 or 0.
19554 Additionally, some features call for additional defines, such as the
19556 cxx_final and cxx_override features. Rather than being used in #ifdef
19557 code, the final keyword is abstracted by a symbol which is defined to
19558 either final, a compiler-specific equivalent, or to empty. That way,
19559 C++ code can be written to unconditionally use the symbol, and compiler
19560 support determines what it is expanded to:
19561 struct Interface {
19563 virtual void Execute() = 0;
19564 };
19565 struct Concrete Foo_FINAL {
19567 void Execute() Foo_OVERRIDE;
19568 };
19569 In this case, Foo_FINAL will expand to final if the compiler supports
19571 the keyword, or to empty otherwise.
19572 In this use-case, the project code may wish to enable a particular lan‐
19574 guage standard if available from the compiler. The CXX_STANDARD target
19575 property may be set to the desired language standard for a particular
19576 target, and the CMAKE_CXX_STANDARD variable may be set to influence all
19577 following targets:
19578 write_compiler_detection_header(
19580 FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
19581 PREFIX Foo
19582 COMPILERS GNU
19583 FEATURES
19584 cxx_final cxx_override
19585 )
19586 # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
19588 # which will expand to 'final' if the compiler supports the requested
19589 # CXX_STANDARD.
19590 add_library(foo foo.cpp)
19591 set_property(TARGET foo PROPERTY CXX_STANDARD 11)
19592 # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
19594 # which will expand to 'final' if the compiler supports the feature,
19595 # even though CXX_STANDARD is not set explicitly. The requirement of
19596 # cxx_constexpr causes CMake to set CXX_STANDARD internally, which
19597 # affects the compile flags.
19598 add_library(foo_impl foo_impl.cpp)
19599 target_compile_features(foo_impl PRIVATE cxx_constexpr)
19600 The write_compiler_detection_header function also creates compatibility
19602 code for other features which have standard equivalents. For example,
19603 the cxx_static_assert feature is emulated with a template and ab‐
19604 stracted via the <PREFIX>_STATIC_ASSERT and <PREFIX>_STATIC_ASSERT_MSG
19605 function-macros.
19606 Deprecated Find Modules
19608 FindCUDA
19609 WARNING:
19610 Deprecated since version 3.10.
19611 It is no longer necessary to use this module or call find_package(CUDA)
19613 for compiling CUDA code. Instead, list CUDA among the languages named
19614 in the top-level call to the project() command, or call the enable_lan‐
19615 guage() command with CUDA. Then one can add CUDA (.cu) sources di‐
19616 rectly to targets similar to other languages.
19617 New in version 3.17: To find and use the CUDA toolkit libraries manu‐
19619 ally, use the FindCUDAToolkit module instead. It works regardless of
19620 the CUDA language being enabled.
19621 Documentation of Deprecated Usage
19624 Tools for building CUDA C files: libraries and build dependencies.
19625 This script locates the NVIDIA CUDA C tools. It should work on Linux,
19627 Windows, and macOS and should be reasonably up to date with CUDA C re‐
19628 leases.
19629 New in version 3.19: QNX support.
19631 This script makes use of the standard find_package() arguments of <VER‐
19634 SION>, REQUIRED and QUIET. CUDA_FOUND will report if an acceptable
19635 version of CUDA was found.
19636 The script will prompt the user to specify CUDA_TOOLKIT_ROOT_DIR if the
19638 prefix cannot be determined by the location of nvcc in the system path
19639 and REQUIRED is specified to find_package(). To use a different in‐
19640 stalled version of the toolkit set the environment variable
19641 CUDA_BIN_PATH before running cmake (e.g. CUDA_BIN_PATH=/usr/lo‐
19642 cal/cuda1.0 instead of the default /usr/local/cuda) or set CUDA_TOOL‐
19643 KIT_ROOT_DIR after configuring. If you change the value of CUDA_TOOL‐
19644 KIT_ROOT_DIR, various components that depend on the path will be relo‐
19645 cated.
19646 It might be necessary to set CUDA_TOOLKIT_ROOT_DIR manually on certain
19648 platforms, or to use a CUDA runtime not installed in the default loca‐
19649 tion. In newer versions of the toolkit the CUDA library is included
19650 with the graphics driver -- be sure that the driver version matches
19651 what is needed by the CUDA runtime version.
19652 Input Variables
19654 The following variables affect the behavior of the macros in the script
19655 (in alphabetical order). Note that any of these flags can be changed
19656 multiple times in the same directory before calling cuda_add_exe‐
19657 cutable(), cuda_add_library(), cuda_compile(), cuda_compile_ptx(),
19658 cuda_compile_fatbin(), cuda_compile_cubin() or cuda_wrap_srcs():
19659 CUDA_64_BIT_DEVICE_CODE (Default: host bit size)
19661 Set to ON to compile for 64 bit device code, OFF for 32 bit de‐
19662 vice code. Note that making this different from the host code
19663 when generating object or C files from CUDA code just won't
19664 work, because size_t gets defined by nvcc in the generated
19665 source. If you compile to PTX and then load the file yourself,
19666 you can mix bit sizes between device and host.
19667 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE (Default: ON)
19669 Set to ON if you want the custom build rule to be attached to
19670 the source file in Visual Studio. Turn OFF if you add the same
19671 cuda file to multiple targets.
19672 This allows the user to build the target from the CUDA file;
19674 however, bad things can happen if the CUDA source file is added
19675 to multiple targets. When performing parallel builds it is pos‐
19676 sible for the custom build command to be run more than once and
19677 in parallel causing cryptic build errors. VS runs the rules for
19678 every source file in the target, and a source can have only one
19679 rule no matter how many projects it is added to. When the rule
19680 is run from multiple targets race conditions can occur on the
19681 generated file. Eventually everything will get built, but if
19682 the user is unaware of this behavior, there may be confusion.
19683 It would be nice if this script could detect the reuse of source
19684 files across multiple targets and turn the option off for the
19685 user, but no good solution could be found.
19686 CUDA_BUILD_CUBIN (Default: OFF)
19688 Set to ON to enable and extra compilation pass with the -cubin
19689 option in Device mode. The output is parsed and register, shared
19690 memory usage is printed during build.
19691 CUDA_BUILD_EMULATION (Default: OFF for device mode)
19693 Set to ON for Emulation mode. -D_DEVICEEMU is defined for CUDA C
19694 files when CUDA_BUILD_EMULATION is TRUE.
19695 CUDA_LINK_LIBRARIES_KEYWORD (Default: "")
19697 New in version 3.9.
19698 The <PRIVATE|PUBLIC|INTERFACE> keyword to use for internal tar‐
19701 get_link_libraries() calls. The default is to use no keyword
19702 which uses the old "plain" form of target_link_libraries(). Note
19703 that is matters because whatever is used inside the FindCUDA
19704 module must also be used outside - the two forms of tar‐
19705 get_link_libraries() cannot be mixed.
19706 CUDA_GENERATED_OUTPUT_DIR (Default: CMAKE_CURRENT_BINARY_DIR)
19708 Set to the path you wish to have the generated files placed. If
19709 it is blank output files will be placed in CMAKE_CURRENT_BI‐
19710 NARY_DIR. Intermediate files will always be placed in
19711 CMAKE_CURRENT_BINARY_DIR/CMakeFiles.
19712 CUDA_HOST_COMPILATION_CPP (Default: ON)
19714 Set to OFF for C compilation of host code.
19715 CUDA_HOST_COMPILER (Default: CMAKE_C_COMPILER)
19717 Set the host compiler to be used by nvcc. Ignored if -ccbin or
19718 --compiler-bindir is already present in the CUDA_NVCC_FLAGS or
19719 CUDA_NVCC_FLAGS_<CONFIG> variables. For Visual Studio targets,
19720 the host compiler is constructed with one or more visual studio
19721 macros such as $(VCInstallDir), that expands out to the path
19722 when the command is run from within VS.
19723 New in version 3.13: If the CUDAHOSTCXX environment variable is
19725 set it will be used as the default.
19726 CUDA_NVCC_FLAGS, CUDA_NVCC_FLAGS_<CONFIG>
19729 Additional NVCC command line arguments. NOTE: multiple argu‐
19730 ments must be semi-colon delimited (e.g. --compiler-op‐
19731 tions;-Wall)
19732 New in version 3.6: Contents of these variables may use genera‐
19734 tor expressions.
19735 CUDA_PROPAGATE_HOST_FLAGS (Default: ON)
19738 Set to ON to propagate CMAKE_{C,CXX}_FLAGS and their configura‐
19739 tion dependent counterparts (e.g. CMAKE_C_FLAGS_DEBUG) automati‐
19740 cally to the host compiler through nvcc's -Xcompiler flag. This
19741 helps make the generated host code match the rest of the system
19742 better. Sometimes certain flags give nvcc problems, and this
19743 will help you turn the flag propagation off. This does not af‐
19744 fect the flags supplied directly to nvcc via CUDA_NVCC_FLAGS or
19745 through the OPTION flags specified through cuda_add_library(),
19746 cuda_add_executable(), or cuda_wrap_srcs(). Flags used for
19747 shared library compilation are not affected by this flag.
19748 CUDA_SEPARABLE_COMPILATION (Default: OFF)
19750 If set this will enable separable compilation for all CUDA run‐
19751 time object files. If used outside of cuda_add_executable() and
19752 cuda_add_library() (e.g. calling cuda_wrap_srcs() directly),
19753 cuda_compute_separable_compilation_object_file_name() and
19754 cuda_link_separable_compilation_objects() should be called.
19755 CUDA_SOURCE_PROPERTY_FORMAT
19757 New in version 3.3.
19758 If this source file property is set, it can override the format
19761 specified to cuda_wrap_srcs() (OBJ, PTX, CUBIN, or FATBIN). If
19762 an input source file is not a .cu file, setting this file will
19763 cause it to be treated as a .cu file. See documentation for
19764 set_source_files_properties on how to set this property.
19765 CUDA_USE_STATIC_CUDA_RUNTIME (Default: ON)
19767 New in version 3.3.
19768 When enabled the static version of the CUDA runtime library will
19771 be used in CUDA_LIBRARIES. If the version of CUDA configured
19772 doesn't support this option, then it will be silently disabled.
19773 CUDA_VERBOSE_BUILD (Default: OFF)
19775 Set to ON to see all the commands used when building the CUDA
19776 file. When using a Makefile generator the value defaults to
19777 VERBOSE (run make VERBOSE=1 to see output), although setting
19778 CUDA_VERBOSE_BUILD to ON will always print the output.
19779 Commands
19781 The script creates the following functions and macros (in alphabetical
19782 order):
19783 cuda_add_cufft_to_target(<cuda_target>)
19785 Adds the cufft library to the target (can be any target). Handles
19787 whether you are in emulation mode or not.
19788 cuda_add_cublas_to_target(<cuda_target>)
19790 Adds the cublas library to the target (can be any target). Handles
19792 whether you are in emulation mode or not.
19793 cuda_add_executable(<cuda_target> <file>...
19795 [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [OPTIONS ...])
19796 Creates an executable <cuda_target> which is made up of the files spec‐
19798 ified. All of the non CUDA C files are compiled using the standard
19799 build rules specified by CMake and the CUDA files are compiled to ob‐
19800 ject files using nvcc and the host compiler. In addition CUDA_IN‐
19801 CLUDE_DIRS is added automatically to include_directories(). Some stan‐
19802 dard CMake target calls can be used on the target after calling this
19803 macro (e.g. set_target_properties() and target_link_libraries()), but
19804 setting properties that adjust compilation flags will not affect code
19805 compiled by nvcc. Such flags should be modified before calling
19806 cuda_add_executable(), cuda_add_library() or cuda_wrap_srcs().
19807 cuda_add_library(<cuda_target> <file>...
19809 [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [OPTIONS ...])
19810 Same as cuda_add_executable() except that a library is created.
19812 cuda_build_clean_target()
19814 Creates a convenience target that deletes all the dependency files gen‐
19816 erated. You should make clean after running this target to ensure the
19817 dependency files get regenerated.
19818 cuda_compile(<generated_files> <file>... [STATIC | SHARED | MODULE]
19820 [OPTIONS ...])
19821 Returns a list of generated files from the input source files to be
19823 used with add_library() or add_executable().
19824 cuda_compile_ptx(<generated_files> <file>... [OPTIONS ...])
19826 Returns a list of PTX files generated from the input source files.
19828 cuda_compile_fatbin(<generated_files> <file>... [OPTIONS ...])
19830 New in version 3.1.
19832 Returns a list of FATBIN files generated from the input source files.
19835 cuda_compile_cubin(<generated_files> <file>... [OPTIONS ...])
19837 New in version 3.1.
19839 Returns a list of CUBIN files generated from the input source files.
19842 cuda_compute_separable_compilation_object_file_name(<output_file_var>
19844 <cuda_target>
19845 <object_files>)
19846 Compute the name of the intermediate link file used for separable com‐
19848 pilation. This file name is typically passed into CUDA_LINK_SEPARA‐
19849 BLE_COMPILATION_OBJECTS. output_file_var is produced based on
19850 cuda_target the list of objects files that need separable compilation
19851 as specified by <object_files>. If the <object_files> list is empty,
19852 then <output_file_var> will be empty. This function is called automat‐
19853 ically for cuda_add_library() and cuda_add_executable(). Note that
19854 this is a function and not a macro.
19855 cuda_include_directories(path0 path1 ...)
19857 Sets the directories that should be passed to nvcc (e.g. nvcc -Ipath0
19859 -Ipath1 ...). These paths usually contain other .cu files.
19860 cuda_link_separable_compilation_objects(<output_file_var> <cuda_target>
19862 <nvcc_flags> <object_files>)
19863 Generates the link object required by separable compilation from the
19865 given object files. This is called automatically for cuda_add_exe‐
19866 cutable() and cuda_add_library(), but can be called manually when using
19867 cuda_wrap_srcs() directly. When called from cuda_add_library() or
19868 cuda_add_executable() the <nvcc_flags> passed in are the same as the
19869 flags passed in via the OPTIONS argument. The only nvcc flag added au‐
19870 tomatically is the bitness flag as specified by CUDA_64_BIT_DE‐
19871 VICE_CODE. Note that this is a function instead of a macro.
19872 cuda_select_nvcc_arch_flags(<out_variable> [<target_CUDA_architecture> ...])
19874 Selects GPU arch flags for nvcc based on target_CUDA_architecture.
19876 Values for target_CUDA_architecture:
19878 • Auto: detects local machine GPU compute arch at runtime.
19880 • Common and All: cover common and entire subsets of architectures.
19882 • <name>: one of Fermi, Kepler, Maxwell, Kepler+Tegra, Kepler+Tesla,
19884 Maxwell+Tegra, Pascal.
19885 • <ver>, <ver>(<ver>), <ver>+PTX, where <ver> is one of 2.0, 2.1, 3.0,
19887 3.2, 3.5, 3.7, 5.0, 5.2, 5.3, 6.0, 6.2.
19888 Returns list of flags to be added to CUDA_NVCC_FLAGS in <out_variable>.
19890 Additionally, sets <out_variable>_readable to the resulting numeric
19891 list.
19892 Example:
19894 cuda_select_nvcc_arch_flags(ARCH_FLAGS 3.0 3.5+PTX 5.2(5.0) Maxwell)
19896 list(APPEND CUDA_NVCC_FLAGS ${ARCH_FLAGS})
19897 More info on CUDA architectures: https://en.wikipedia.org/wiki/CUDA.
19899 Note that this is a function instead of a macro.
19900 cuda_wrap_srcs(<cuda_target> <format> <generated_files> <file>...
19902 [STATIC | SHARED | MODULE] [OPTIONS ...])
19903 This is where all the magic happens. cuda_add_executable(),
19905 cuda_add_library(), cuda_compile(), and cuda_compile_ptx() all call
19906 this function under the hood.
19907 Given the list of files <file>... this macro generates custom commands
19909 that generate either PTX or linkable objects (use PTX or OBJ for the
19910 <format> argument to switch). Files that don't end with .cu or have
19911 the HEADER_FILE_ONLY property are ignored.
19912 The arguments passed in after OPTIONS are extra command line options to
19914 give to nvcc. You can also specify per configuration options by speci‐
19915 fying the name of the configuration followed by the options. General
19916 options must precede configuration specific options. Not all configu‐
19917 rations need to be specified, only the ones provided will be used. For
19918 example:
19919 cuda_add_executable(...
19921 OPTIONS -DFLAG=2 "-DFLAG_OTHER=space in flag"
19922 DEBUG -g
19923 RELEASE --use_fast_math
19924 RELWITHDEBINFO --use_fast_math;-g
19925 MINSIZEREL --use_fast_math)
19926 For certain configurations (namely VS generating object files with
19928 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE set to ON), no generated file
19929 will be produced for the given cuda file. This is because when you add
19930 the cuda file to Visual Studio it knows that this file produces an ob‐
19931 ject file and will link in the resulting object file automatically.
19932 This script will also generate a separate cmake script that is used at
19934 build time to invoke nvcc. This is for several reasons:
19935 • nvcc can return negative numbers as return values which confuses Vis‐
19937 ual Studio into thinking that the command succeeded. The script now
19938 checks the error codes and produces errors when there was a problem.
19939 • nvcc has been known to not delete incomplete results when it encoun‐
19941 ters problems. This confuses build systems into thinking the target
19942 was generated when in fact an unusable file exists. The script now
19943 deletes the output files if there was an error.
19944 • By putting all the options that affect the build into a file and then
19946 make the build rule dependent on the file, the output files will be
19947 regenerated when the options change.
19948 This script also looks at optional arguments STATIC, SHARED, or MODULE
19950 to determine when to target the object compilation for a shared li‐
19951 brary. BUILD_SHARED_LIBS is ignored in cuda_wrap_srcs(), but it is re‐
19952 spected in cuda_add_library(). On some systems special flags are added
19953 for building objects intended for shared libraries. A preprocessor
19954 macro, <target_name>_EXPORTS is defined when a shared library compila‐
19955 tion is detected.
19956 Flags passed into add_definitions with -D or /D are passed along to
19958 nvcc.
19959 Result Variables
19961 The script defines the following variables:
19962 CUDA_VERSION_MAJOR
19964 The major version of cuda as reported by nvcc.
19965 CUDA_VERSION_MINOR
19967 The minor version.
19968 CUDA_VERSION, CUDA_VERSION_STRING
19970 Full version in the X.Y format.
19971 CUDA_HAS_FP16
19973 New in version 3.6: Whether a short float (float16, fp16) is
19974 supported.
19975 CUDA_TOOLKIT_ROOT_DIR
19978 Path to the CUDA Toolkit (defined if not set).
19979 CUDA_SDK_ROOT_DIR
19981 Path to the CUDA SDK. Use this to find files in the SDK. This
19982 script will not directly support finding specific libraries or
19983 headers, as that isn't supported by NVIDIA. If you want to
19984 change libraries when the path changes see the FindCUDA.cmake
19985 script for an example of how to clear these variables. There
19986 are also examples of how to use the CUDA_SDK_ROOT_DIR to locate
19987 headers or libraries, if you so choose (at your own risk).
19988 CUDA_INCLUDE_DIRS
19990 Include directory for cuda headers. Added automatically for
19991 cuda_add_executable() and cuda_add_library().
19992 CUDA_LIBRARIES
19994 Cuda RT library.
19995 CUDA_CUFFT_LIBRARIES
19997 Device or emulation library for the Cuda FFT implementation (al‐
19998 ternative to cuda_add_cufft_to_target() macro)
19999 CUDA_CUBLAS_LIBRARIES
20001 Device or emulation library for the Cuda BLAS implementation
20002 (alternative to cuda_add_cublas_to_target() macro).
20003 CUDA_cudart_static_LIBRARY
20005 Statically linkable cuda runtime library. Only available for
20006 CUDA version 5.5+.
20007 CUDA_cudadevrt_LIBRARY
20009 New in version 3.7: Device runtime library. Required for sepa‐
20010 rable compilation.
20011 CUDA_cupti_LIBRARY
20014 CUDA Profiling Tools Interface library. Only available for CUDA
20015 version 4.0+.
20016 CUDA_curand_LIBRARY
20018 CUDA Random Number Generation library. Only available for CUDA
20019 version 3.2+.
20020 CUDA_cusolver_LIBRARY
20022 New in version 3.2: CUDA Direct Solver library. Only available
20023 for CUDA version 7.0+.
20024 CUDA_cusparse_LIBRARY
20027 CUDA Sparse Matrix library. Only available for CUDA version
20028 3.2+.
20029 CUDA_npp_LIBRARY
20031 NVIDIA Performance Primitives lib. Only available for CUDA ver‐
20032 sion 4.0+.
20033 CUDA_nppc_LIBRARY
20035 NVIDIA Performance Primitives lib (core). Only available for
20036 CUDA version 5.5+.
20037 CUDA_nppi_LIBRARY
20039 NVIDIA Performance Primitives lib (image processing). Only
20040 available for CUDA version 5.5 - 8.0.
20041 CUDA_nppial_LIBRARY
20043 NVIDIA Performance Primitives lib (image processing). Only
20044 available for CUDA version 9.0.
20045 CUDA_nppicc_LIBRARY
20047 NVIDIA Performance Primitives lib (image processing). Only
20048 available for CUDA version 9.0.
20049 CUDA_nppicom_LIBRARY
20051 NVIDIA Performance Primitives lib (image processing). Only
20052 available for CUDA version 9.0 - 10.2. Replaced by nvjpeg.
20053 CUDA_nppidei_LIBRARY
20055 NVIDIA Performance Primitives lib (image processing). Only
20056 available for CUDA version 9.0.
20057 CUDA_nppif_LIBRARY
20059 NVIDIA Performance Primitives lib (image processing). Only
20060 available for CUDA version 9.0.
20061 CUDA_nppig_LIBRARY
20063 NVIDIA Performance Primitives lib (image processing). Only
20064 available for CUDA version 9.0.
20065 CUDA_nppim_LIBRARY
20067 NVIDIA Performance Primitives lib (image processing). Only
20068 available for CUDA version 9.0.
20069 CUDA_nppist_LIBRARY
20071 NVIDIA Performance Primitives lib (image processing). Only
20072 available for CUDA version 9.0.
20073 CUDA_nppisu_LIBRARY
20075 NVIDIA Performance Primitives lib (image processing). Only
20076 available for CUDA version 9.0.
20077 CUDA_nppitc_LIBRARY
20079 NVIDIA Performance Primitives lib (image processing). Only
20080 available for CUDA version 9.0.
20081 CUDA_npps_LIBRARY
20083 NVIDIA Performance Primitives lib (signal processing). Only
20084 available for CUDA version 5.5+.
20085 CUDA_nvcuvenc_LIBRARY
20087 CUDA Video Encoder library. Only available for CUDA version
20088 3.2+. Windows only.
20089 CUDA_nvcuvid_LIBRARY
20091 CUDA Video Decoder library. Only available for CUDA version
20092 3.2+. Windows only.
20093 CUDA_nvToolsExt_LIBRARY
20095 New in version 3.16: NVIDA CUDA Tools Extension library. Avail‐
20096 able for CUDA version 5+.
20097 CUDA_OpenCL_LIBRARY
20100 New in version 3.16: NVIDA CUDA OpenCL library. Available for
20101 CUDA version 5+.
20102 FindPythonInterp
20105 Deprecated since version 3.12: Use FindPython3, FindPython2 or Find‐
20106 Python instead.
20107 Find python interpreter
20110 This module finds if Python interpreter is installed and determines
20112 where the executables are. This code sets the following variables:
20113 PYTHONINTERP_FOUND - Was the Python executable found
20115 PYTHON_EXECUTABLE - path to the Python interpreter
20116 PYTHON_VERSION_STRING - Python version found e.g. 2.5.2
20118 PYTHON_VERSION_MAJOR - Python major version found e.g. 2
20119 PYTHON_VERSION_MINOR - Python minor version found e.g. 5
20120 PYTHON_VERSION_PATCH - Python patch version found e.g. 2
20121 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
20123 of version numbers that should be taken into account when searching for
20124 Python. You need to set this variable before calling find_pack‐
20125 age(PythonInterp).
20126 If calling both find_package(PythonInterp) and find_package(Python‐
20128 Libs), call find_package(PythonInterp) first to get the currently ac‐
20129 tive Python version by default with a consistent version of PYTHON_LI‐
20130 BRARIES.
20131 NOTE:
20133 A call to find_package(PythonInterp ${V}) for python version V may
20134 find a python executable with no version suffix. In this case no
20135 attempt is made to avoid python executables from other versions.
20136 Use FindPython3, FindPython2 or FindPython instead.
20137 FindPythonLibs
20139 Deprecated since version 3.12: Use FindPython3, FindPython2 or Find‐
20140 Python instead.
20141 Find python libraries
20144 This module finds if Python is installed and determines where the in‐
20146 clude files and libraries are. It also determines what the name of the
20147 library is. This code sets the following variables:
20148 PYTHONLIBS_FOUND - have the Python libs been found
20150 PYTHON_LIBRARIES - path to the python library
20151 PYTHON_INCLUDE_PATH - path to where Python.h is found (deprecated)
20152 PYTHON_INCLUDE_DIRS - path to where Python.h is found
20153 PYTHON_DEBUG_LIBRARIES - path to the debug library (deprecated)
20154 PYTHONLIBS_VERSION_STRING - version of the Python libs found (since CMake 2.8.8)
20155 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
20157 of version numbers that should be taken into account when searching for
20158 Python. You need to set this variable before calling find_pack‐
20159 age(PythonLibs).
20160 If you'd like to specify the installation of Python to use, you should
20162 modify the following cache variables:
20163 PYTHON_LIBRARY - path to the python library
20165 PYTHON_INCLUDE_DIR - path to where Python.h is found
20166 If calling both find_package(PythonInterp) and find_package(Python‐
20168 Libs), call find_package(PythonInterp) first to get the currently ac‐
20169 tive Python version by default with a consistent version of PYTHON_LI‐
20170 BRARIES.
20171 FindQt
20173 Deprecated since version 3.14: This module is available only if policy
20174 CMP0084 is not set to NEW.
20175 Searches for all installed versions of Qt3 or Qt4.
20178 This module cannot handle Qt5 or any later versions. For those, see
20180 cmake-qt(7).
20181 This module should only be used if your project can work with multiple
20183 versions of Qt. If not, you should just directly use FindQt4 or
20184 FindQt3. If multiple versions of Qt are found on the machine, then The
20185 user must set the option DESIRED_QT_VERSION to the version they want to
20186 use. If only one version of qt is found on the machine, then the DE‐
20187 SIRED_QT_VERSION is set to that version and the matching FindQt3 or
20188 FindQt4 module is included. Once the user sets DESIRED_QT_VERSION,
20189 then the FindQt3 or FindQt4 module is included.
20190 QT_REQUIRED if this is set to TRUE then if CMake can
20192 not find Qt4 or Qt3 an error is raised
20193 and a message is sent to the user.
20194 DESIRED_QT_VERSION OPTION is created
20196 QT4_INSTALLED is set to TRUE if qt4 is found.
20197 QT3_INSTALLED is set to TRUE if qt3 is found.
20198 FindwxWindows
20200 Deprecated since version 3.0: Replaced by FindwxWidgets.
20201 Find wxWindows (wxWidgets) installation
20204 This module finds if wxWindows/wxWidgets is installed and determines
20206 where the include files and libraries are. It also determines what the
20207 name of the library is. This code sets the following variables:
20208 WXWINDOWS_FOUND = system has WxWindows
20210 WXWINDOWS_LIBRARIES = path to the wxWindows libraries
20211 on Unix/Linux with additional
20212 linker flags from
20213 "wx-config --libs"
20214 CMAKE_WXWINDOWS_CXX_FLAGS = Compiler flags for wxWindows,
20215 essentially "`wx-config --cxxflags`"
20216 on Linux
20217 WXWINDOWS_INCLUDE_DIR = where to find "wx/wx.h" and "wx/setup.h"
20218 WXWINDOWS_LINK_DIRECTORIES = link directories, useful for rpath on
20219 Unix
20220 WXWINDOWS_DEFINITIONS = extra defines
20221 OPTIONS If you need OpenGL support please
20223 set(WXWINDOWS_USE_GL 1)
20225 in your CMakeLists.txt before you include this file.
20227 HAVE_ISYSTEM - true required to replace -I by -isystem on g++
20229 For convenience include Use_wxWindows.cmake in your project's CMake‐
20231 Lists.txt using include(${CMAKE_CURRENT_LIST_DIR}/Use_wxWindows.cmake).
20232 USAGE
20234 set(WXWINDOWS_USE_GL 1)
20236 find_package(wxWindows)
20237 NOTES wxWidgets 2.6.x is supported for monolithic builds e.g. compiled
20239 in wx/build/msw dir as:
20240 nmake -f makefile.vc BUILD=debug SHARED=0 USE_OPENGL=1 MONOLITHIC=1
20242 DEPRECATED
20244 CMAKE_WX_CAN_COMPILE
20246 WXWINDOWS_LIBRARY
20247 CMAKE_WX_CXX_FLAGS
20248 WXWINDOWS_INCLUDE_PATH
20249 AUTHOR Jan Woetzel <http://www.mip.informatik.uni-kiel.de/~jw>
20251 (07/2003-01/2006)
20252 Legacy CPack Modules
20254 These modules used to be mistakenly exposed to the user, and have been
20255 moved out of user visibility. They are for CPack internal use, and
20256 should never be used directly.
20257 CPackArchive
20259 New in version 3.9.
20260 The documentation for the CPack Archive generator has moved here: CPack
20263 Archive Generator
20264 CPackBundle
20266 The documentation for the CPack Bundle generator has moved here: CPack
20267 Bundle Generator
20268 CPackCygwin
20270 The documentation for the CPack Cygwin generator has moved here: CPack
20271 Cygwin Generator
20272 CPackDeb
20274 The documentation for the CPack DEB generator has moved here: CPack DEB
20275 Generator
20276 CPackDMG
20278 The documentation for the CPack DragNDrop generator has moved here:
20279 CPack DragNDrop Generator
20280 CPackFreeBSD
20282 New in version 3.10.
20283 The documentation for the CPack FreeBSD generator has moved here: CPack
20286 FreeBSD Generator
20287 CPackNSIS
20289 The documentation for the CPack NSIS generator has moved here: CPack
20290 NSIS Generator
20291 CPackNuGet
20293 New in version 3.12.
20294 The documentation for the CPack NuGet generator has moved here: CPack
20297 NuGet Generator
20298 CPackPackageMaker
20300 The documentation for the CPack PackageMaker generator has moved here:
20301 CPack PackageMaker Generator
20302 CPackProductBuild
20304 New in version 3.7.
20305 The documentation for the CPack productbuild generator has moved here:
20308 CPack productbuild Generator
20309 CPackRPM
20311 The documentation for the CPack RPM generator has moved here: CPack RPM
20312 Generator
20313 CPackWIX
20315 The documentation for the CPack WIX generator has moved here: CPack WIX
20316 Generator
20317
20319 2000-2021 Kitware, Inc. and Contributors
203203.22.0 Dec 02, 2021 CMAKE-MODULES(7)