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
293 CheckCSourceCompiles module. See documentation of that module for a
294 listing of variables 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
321 CheckSourceCompiles module. See documentation of that module for a
322 listing 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
372 INCLUDE_DIRECTORIES 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
384 Imported 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
449 Imported 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
479 CheckCXXSourceCompiles module. See documentation of that module for a
480 listing of 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
530 INCLUDE_DIRECTORIES 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
542 Imported 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
608 Imported 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
706 CheckFortranSourceCompiles module. See documentation of that module
707 for a 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
778 check_fortran_source_runs() command to actually run the compiled
779 code.
780 The result will be stored in the internal cache variable <re‐
782 sultVar>, with a boolean true value for success and boolean
783 false for failure.
784 If FAIL_REGEX is provided, then failure is determined by check‐
786 ing if anything in the output matches any of the specified regu‐
787 lar expressions.
788 By default, the test source file will be given a .F file exten‐
790 sion. The SRC_EXT option can be used to override this with .<ex‐
791 tension> instead-- .F90 is a typical choice.
792 The underlying check is performed by the try_compile() command.
794 The compile and link commands can be influenced by setting any
795 of the following variables prior to calling check_for‐
796 tran_source_compiles():
797 CMAKE_REQUIRED_FLAGS
799 Additional flags to pass to the compiler. Note that the
800 contents of CMAKE_Fortran_FLAGS and its associated con‐
801 figuration-specific variable are automatically added to
802 the compiler command before the contents of CMAKE_RE‐
803 QUIRED_FLAGS.
804 CMAKE_REQUIRED_DEFINITIONS
806 A ;-list of compiler definitions of the form -DFOO or
807 -DFOO=bar. A definition for the name specified by <re‐
808 sultVar> will also be added automatically.
809 CMAKE_REQUIRED_INCLUDES
811 A ;-list of header search paths to pass to the compiler.
812 These will be the only header search paths used by
813 try_compile(), i.e. the contents of the
814 INCLUDE_DIRECTORIES directory property will be ignored.
815 CMAKE_REQUIRED_LINK_OPTIONS
817 New in version 3.14.
818 A ;-list of options to add to the link command (see
821 try_compile() for further details).
822 CMAKE_REQUIRED_LIBRARIES
824 A ;-list of libraries to add to the link command. These
825 can be the name of system libraries or they can be
826 Imported Targets (see try_compile() for further details).
827 CMAKE_REQUIRED_QUIET
829 If this variable evaluates to a boolean true value, all
830 status messages associated with the check will be sup‐
831 pressed.
832 The check is only performed once, with the result cached in the
834 variable named by <resultVar>. Every subsequent CMake run will
835 re-use this cached value rather than performing the check again,
836 even if the <code> changes. In order to force the check to be
837 re-evaluated, the variable named by <resultVar> must be manually
838 removed from the cache.
839 CheckFortranSourceRuns
841 New in version 3.14.
842 Check if given Fortran source compiles and links into an executable and
845 can subsequently be run.
846 check_fortran_source_runs
848 check_fortran_source_runs(<code> <resultVar>
850 [SRC_EXT <extension>])
851 Check that the source supplied in <code> can be compiled as a
853 Fortran source file, linked as an executable and then run. The
854 <code> must be a Fortran program containing at least an end
855 statement--for example:
856 check_fortran_source_runs("real :: x[*]; call co_sum(x); end" F2018coarrayOK)
858 This command can help avoid costly build processes when a com‐
860 piler lacks support for a necessary feature, or a particular
861 vendor library is not compatible with the Fortran compiler ver‐
862 sion being used. Some of these failures only occur at runtime
863 instead of linktime, and a trivial runtime example can catch the
864 issue before the main build process.
865 If the <code> could be built and run successfully, the internal
867 cache variable specified by <resultVar> will be set to 1, other‐
868 wise it will be set to an value that evaluates to boolean false
869 (e.g. an empty string or an error message).
870 By default, the test source file will be given a .F90 file ex‐
872 tension. The SRC_EXT option can be used to override this with
873 .<extension> instead.
874 The underlying check is performed by the try_run() command. The
876 compile and link commands can be influenced by setting any of
877 the following variables prior to calling check_for‐
878 tran_source_runs():
879 CMAKE_REQUIRED_FLAGS
881 Additional flags to pass to the compiler. Note that the
882 contents of CMAKE_Fortran_FLAGS and its associated con‐
883 figuration-specific variable are automatically added to
884 the compiler command before the contents of CMAKE_RE‐
885 QUIRED_FLAGS.
886 CMAKE_REQUIRED_DEFINITIONS
888 A ;-list of compiler definitions of the form -DFOO or
889 -DFOO=bar. A definition for the name specified by <re‐
890 sultVar> will also be added automatically.
891 CMAKE_REQUIRED_INCLUDES
893 A ;-list of header search paths to pass to the compiler.
894 These will be the only header search paths used by
895 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
896 directory property will be ignored.
897 CMAKE_REQUIRED_LINK_OPTIONS
899 A ;-list of options to add to the link command (see
900 try_run() for further details).
901 CMAKE_REQUIRED_LIBRARIES
903 A ;-list of libraries to add to the link command. These
904 can be the name of system libraries or they can be
905 Imported Targets (see try_run() for further details).
906 CMAKE_REQUIRED_QUIET
908 If this variable evaluates to a boolean true value, all
909 status messages associated with the check will be sup‐
910 pressed.
911 The check is only performed once, with the result cached in the
913 variable named by <resultVar>. Every subsequent CMake run will
914 re-use this cached value rather than performing the check again,
915 even if the <code> changes. In order to force the check to be
916 re-evaluated, the variable named by <resultVar> must be manually
917 removed from the cache.
918 CheckFunctionExists
920 Check if a C function can be linked
921 check_function_exists
923 check_function_exists(<function> <variable>)
925 Checks that the <function> is provided by libraries on the sys‐
927 tem and store the result in a <variable>, which will be created
928 as an internal cache variable.
929 The following variables may be set before calling this macro to modify
931 the way the check is run:
932 CMAKE_REQUIRED_FLAGS
934 string of compile command line flags.
935 CMAKE_REQUIRED_DEFINITIONS
937 a ;-list of macros to define (-DFOO=bar).
938 CMAKE_REQUIRED_INCLUDES
940 a ;-list of header search paths to pass to the compiler.
941 CMAKE_REQUIRED_LINK_OPTIONS
943 New in version 3.14: a ;-list of options to add to the link com‐
944 mand.
945 CMAKE_REQUIRED_LIBRARIES
948 a ;-list of libraries to add to the link command. See policy
949 CMP0075.
950 CMAKE_REQUIRED_QUIET
952 New in version 3.1: execute quietly without messages.
953 NOTE:
956 Prefer using CheckSymbolExists instead of this module, for the fol‐
957 lowing reasons:
958 • check_function_exists() can't detect functions that are inlined in
960 headers or specified as a macro.
961 • check_function_exists() can't detect anything in the 32-bit ver‐
963 sions of the Win32 API, because of a mismatch in calling conven‐
964 tions.
965 • check_function_exists() only verifies linking, it does not verify
967 that the function is declared in system headers.
968 CheckIncludeFileCXX
970 Provides a macro to check if a header file can be included in CXX.
971 CHECK_INCLUDE_FILE_CXX
973 CHECK_INCLUDE_FILE_CXX(<include> <variable> [<flags>])
975 Check if the given <include> file may be included in a CXX
977 source file and store the result in an internal cache entry
978 named <variable>. The optional third argument may be used to
979 add compilation flags to the check (or use CMAKE_REQUIRED_FLAGS
980 below).
981 The following variables may be set before calling this macro to modify
983 the way the check is run:
984 CMAKE_REQUIRED_FLAGS
986 string of compile command line flags.
987 CMAKE_REQUIRED_DEFINITIONS
989 a ;-list of macros to define (-DFOO=bar).
990 CMAKE_REQUIRED_INCLUDES
992 a ;-list of header search paths to pass to the compiler.
993 CMAKE_REQUIRED_LINK_OPTIONS
995 New in version 3.14: a ;-list of options to add to the link com‐
996 mand.
997 CMAKE_REQUIRED_LIBRARIES
1000 a ;-list of libraries to add to the link command. See policy
1001 CMP0075.
1002 CMAKE_REQUIRED_QUIET
1004 New in version 3.1: execute quietly without messages.
1005 See modules CheckIncludeFile and CheckIncludeFiles to check for one or
1008 more C headers.
1009 CheckIncludeFile
1011 Provides a macro to check if a header file can be included in C.
1012 CHECK_INCLUDE_FILE
1014 CHECK_INCLUDE_FILE(<include> <variable> [<flags>])
1016 Check if the given <include> file may be included in a C source
1018 file and store the result in an internal cache entry named
1019 <variable>. The optional third argument may be used to add com‐
1020 pilation flags to the check (or use CMAKE_REQUIRED_FLAGS below).
1021 The following variables may be set before calling this macro to modify
1023 the way the check is run:
1024 CMAKE_REQUIRED_FLAGS
1026 string of compile command line flags.
1027 CMAKE_REQUIRED_DEFINITIONS
1029 a ;-list of macros to define (-DFOO=bar).
1030 CMAKE_REQUIRED_INCLUDES
1032 a ;-list of header search paths to pass to the compiler.
1033 CMAKE_REQUIRED_LINK_OPTIONS
1035 New in version 3.14: a ;-list of options to add to the link com‐
1036 mand.
1037 CMAKE_REQUIRED_LIBRARIES
1040 a ;-list of libraries to add to the link command. See policy
1041 CMP0075.
1042 CMAKE_REQUIRED_QUIET
1044 New in version 3.1: execute quietly without messages.
1045 See the CheckIncludeFiles module to check for multiple headers at once.
1048 See the CheckIncludeFileCXX module to check for headers using the CXX
1049 language.
1050 CheckIncludeFiles
1052 Provides a macro to check if a list of one or more header files can be
1053 included together.
1054 CHECK_INCLUDE_FILES
1056 CHECK_INCLUDE_FILES("<includes>" <variable> [LANGUAGE <language>])
1058 Check if the given <includes> list may be included together in a
1060 source file and store the result in an internal cache entry
1061 named <variable>. Specify the <includes> argument as a ;-list
1062 of header file names.
1063 If LANGUAGE is set, the specified compiler will be used to per‐
1065 form the check. Acceptable values are C and CXX. If not set, the
1066 C compiler will be used if enabled. If the C compiler is not en‐
1067 abled, the C++ compiler will be used if enabled.
1068 The following variables may be set before calling this macro to modify
1070 the way the check is run:
1071 CMAKE_REQUIRED_FLAGS
1073 string of compile command line flags.
1074 CMAKE_REQUIRED_DEFINITIONS
1076 a ;-list of macros to define (-DFOO=bar).
1077 CMAKE_REQUIRED_INCLUDES
1079 a ;-list of header search paths to pass to the compiler.
1080 CMAKE_REQUIRED_LINK_OPTIONS
1082 New in version 3.14: a ;-list of options to add to the link com‐
1083 mand.
1084 CMAKE_REQUIRED_LIBRARIES
1087 a ;-list of libraries to add to the link command. See policy
1088 CMP0075.
1089 CMAKE_REQUIRED_QUIET
1091 New in version 3.1: execute quietly without messages.
1092 See modules CheckIncludeFile and CheckIncludeFileCXX to check for a
1095 single header file in C or CXX languages.
1096 CheckIPOSupported
1098 New in version 3.9.
1099 Check whether the compiler supports an interprocedural optimization
1102 (IPO/LTO). Use this before enabling the INTERPROCEDURAL_OPTIMIZATION
1103 target property.
1104 check_ipo_supported
1106 check_ipo_supported([RESULT <result>] [OUTPUT <output>]
1108 [LANGUAGES <lang>...])
1109 Options are:
1111 RESULT <result>
1113 Set <result> variable to YES if IPO is supported by the
1114 compiler and NO otherwise. If this option is not given
1115 then the command will issue a fatal error if IPO is not
1116 supported.
1117 OUTPUT <output>
1119 Set <output> variable with details about any error.
1120 LANGUAGES <lang>...
1122 Specify languages whose compilers to check. Languages C,
1123 CXX, and Fortran are supported.
1124 It makes no sense to use this module when CMP0069 is set to OLD so mod‐
1126 ule will return error in this case. See policy CMP0069 for details.
1127 New in version 3.13: Add support for Visual Studio generators.
1129 New in version 3.24: The check uses the caller's CMAKE_<LANG>_FLAGS and
1132 CMAKE_<LANG>_FLAGS_<CONFIG> values. See policy CMP0138.
1133 Examples
1136 check_ipo_supported() # fatal error if IPO is not supported
1137 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
1138 # Optional IPO. Do not use IPO if it's not supported by compiler.
1140 check_ipo_supported(RESULT result OUTPUT output)
1141 if(result)
1142 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
1143 else()
1144 message(WARNING "IPO is not supported: ${output}")
1145 endif()
1146 CheckLanguage
1148 Check if a language can be enabled
1149 Usage:
1151 check_language(<lang>)
1153 where <lang> is a language that may be passed to enable_language() such
1155 as Fortran. If CMAKE_<LANG>_COMPILER is already defined the check does
1156 nothing. Otherwise it tries enabling the language in a test project.
1157 The result is cached in CMAKE_<LANG>_COMPILER as the compiler that was
1158 found, or NOTFOUND if the language cannot be enabled. For CUDA which
1159 can have an explicit host compiler, the cache CMAKE_CUDA_HOST_COMPILER
1160 variable will be set if it was required for compilation (and cleared if
1161 it was not).
1162 Example:
1164 check_language(Fortran)
1166 if(CMAKE_Fortran_COMPILER)
1167 enable_language(Fortran)
1168 else()
1169 message(STATUS "No Fortran support")
1170 endif()
1171 CheckLibraryExists
1173 Check if the function exists.
1174 CHECK_LIBRARY_EXISTS
1176 CHECK_LIBRARY_EXISTS(LIBRARY FUNCTION LOCATION VARIABLE)
1178 LIBRARY - the name of the library you are looking for
1180 FUNCTION - the name of the function
1181 LOCATION - location where the library should be found
1182 VARIABLE - variable to store the result
1183 Will be created as an internal cache variable.
1184 The following variables may be set before calling this macro to modify
1186 the way the check is run:
1187 CMAKE_REQUIRED_FLAGS
1189 string of compile command line flags.
1190 CMAKE_REQUIRED_DEFINITIONS
1192 list of macros to define (-DFOO=bar).
1193 CMAKE_REQUIRED_LINK_OPTIONS
1195 New in version 3.14: list of options to pass to link command.
1196 CMAKE_REQUIRED_LIBRARIES
1199 list of libraries to link.
1200 CMAKE_REQUIRED_QUIET
1202 New in version 3.1: execute quietly without messages.
1203 CheckLinkerFlag
1206 New in version 3.18.
1207 Check whether the compiler supports a given link flag.
1210 check_linker_flag
1212 check_linker_flag(<lang> <flag> <var>)
1214 Check that the link <flag> is accepted by the <lang> compiler without a
1216 diagnostic. Stores the result in an internal cache entry named <var>.
1217 This command temporarily sets the CMAKE_REQUIRED_LINK_OPTIONS variable
1219 and calls the check_source_compiles() command from the
1220 CheckSourceCompiles module. See that module's documentation for a
1221 listing of variables that can otherwise modify the build.
1222 The underlying implementation relies on the LINK_OPTIONS property to
1224 check the specified flag. The LINKER: prefix, as described in the
1225 target_link_options() command, can be used as well.
1226 A positive result from this check indicates only that the compiler did
1228 not issue a diagnostic message when given the link flag. Whether the
1229 flag has any effect or even a specific one is beyond the scope of this
1230 module.
1231 NOTE:
1233 Since the try_compile() command forwards flags from variables like
1234 CMAKE_<LANG>_FLAGS, unknown flags in such variables may cause a
1235 false negative for this check.
1236 CheckOBJCCompilerFlag
1238 New in version 3.16.
1239 Check whether the Objective-C compiler supports a given flag.
1242 check_objc_compiler_flag
1244 check_objc_compiler_flag(<flag> <var>)
1246 Check that the <flag> is accepted by the compiler without a di‐
1248 agnostic. Stores the result in an internal cache entry named
1249 <var>.
1250 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
1252 and calls the check_objc_source_compiles macro from the
1253 CheckOBJCSourceCompiles module. See documentation of that module for a
1254 listing of variables that can otherwise modify the build.
1255 A positive result from this check indicates only that the compiler did
1257 not issue a diagnostic message when given the flag. Whether the flag
1258 has any effect or even a specific one is beyond the scope of this mod‐
1259 ule.
1260 NOTE:
1262 Since the try_compile() command forwards flags from variables like
1263 CMAKE_OBJC_FLAGS, unknown flags in such variables may cause a false
1264 negative for this check.
1265 CheckOBJCSourceCompiles
1267 New in version 3.16.
1268 Check if given Objective-C source compiles and links into an exe‐
1271 cutable.
1272 check_objc_source_compiles
1274 check_objc_source_compiles(<code> <resultVar>
1276 [FAIL_REGEX <regex1> [<regex2>...]])
1277 Check that the source supplied in <code> can be compiled as a
1279 Objectie-C source file and linked as an executable (so it must
1280 contain at least a main() function). The result will be stored
1281 in the internal cache variable specified by <resultVar>, with a
1282 boolean true value for success and boolean false for failure. If
1283 FAIL_REGEX is provided, then failure is determined by checking
1284 if anything in the output matches any of the specified regular
1285 expressions.
1286 The underlying check is performed by the try_compile() command.
1288 The compile and link commands can be influenced by setting any
1289 of the following variables prior to calling
1290 check_objc_source_compiles():
1291 CMAKE_REQUIRED_FLAGS
1293 Additional flags to pass to the compiler. Note that the
1294 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1295 ration-specific variable are automatically added to the
1296 compiler command before the contents of CMAKE_RE‐
1297 QUIRED_FLAGS.
1298 CMAKE_REQUIRED_DEFINITIONS
1300 A ;-list of compiler definitions of the form -DFOO or
1301 -DFOO=bar. A definition for the name specified by <re‐
1302 sultVar> will also be added automatically.
1303 CMAKE_REQUIRED_INCLUDES
1305 A ;-list of header search paths to pass to the compiler.
1306 These will be the only header search paths used by
1307 try_compile(), i.e. the contents of the
1308 INCLUDE_DIRECTORIES directory property will be ignored.
1309 CMAKE_REQUIRED_LINK_OPTIONS
1311 A ;-list of options to add to the link command (see
1312 try_compile() for further details).
1313 CMAKE_REQUIRED_LIBRARIES
1315 A ;-list of libraries to add to the link command. These
1316 can be the name of system libraries or they can be
1317 Imported Targets (see try_compile() for further details).
1318 CMAKE_REQUIRED_QUIET
1320 If this variable evaluates to a boolean true value, all
1321 status messages associated with the check will be sup‐
1322 pressed.
1323 The check is only performed once, with the result cached in the
1325 variable named by <resultVar>. Every subsequent CMake run will
1326 re-use this cached value rather than performing the check again,
1327 even if the <code> changes. In order to force the check to be
1328 re-evaluated, the variable named by <resultVar> must be manually
1329 removed from the cache.
1330 CheckOBJCSourceRuns
1332 New in version 3.16.
1333 Check if given Objective-C source compiles and links into an executable
1336 and can subsequently be run.
1337 check_objc_source_runs
1339 check_objc_source_runs(<code> <resultVar>)
1341 Check that the source supplied in <code> can be compiled as a
1343 Objective-C source file, linked as an executable and then run.
1344 The <code> must contain at least a main() function. If the
1345 <code> could be built and run successfully, the internal cache
1346 variable specified by <resultVar> will be set to 1, otherwise it
1347 will be set to an value that evaluates to boolean false (e.g. an
1348 empty string or an error message).
1349 The underlying check is performed by the try_run() command. The
1351 compile and link commands can be influenced by setting any of
1352 the following variables prior to calling
1353 check_objc_source_runs():
1354 CMAKE_REQUIRED_FLAGS
1356 Additional flags to pass to the compiler. Note that the
1357 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1358 ration-specific variable are automatically added to the
1359 compiler command before the contents of CMAKE_RE‐
1360 QUIRED_FLAGS.
1361 CMAKE_REQUIRED_DEFINITIONS
1363 A ;-list of compiler definitions of the form -DFOO or
1364 -DFOO=bar. A definition for the name specified by <re‐
1365 sultVar> will also be added automatically.
1366 CMAKE_REQUIRED_INCLUDES
1368 A ;-list of header search paths to pass to the compiler.
1369 These will be the only header search paths used by
1370 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1371 directory property will be ignored.
1372 CMAKE_REQUIRED_LINK_OPTIONS
1374 A ;-list of options to add to the link command (see
1375 try_run() for further details).
1376 CMAKE_REQUIRED_LIBRARIES
1378 A ;-list of libraries to add to the link command. These
1379 can be the name of system libraries or they can be
1380 Imported Targets (see try_run() for further details).
1381 CMAKE_REQUIRED_QUIET
1383 If this variable evaluates to a boolean true value, all
1384 status messages associated with the check will be sup‐
1385 pressed.
1386 The check is only performed once, with the result cached in the
1388 variable named by <resultVar>. Every subsequent CMake run will
1389 re-use this cached value rather than performing the check again,
1390 even if the <code> changes. In order to force the check to be
1391 re-evaluated, the variable named by <resultVar> must be manually
1392 removed from the cache.
1393 CheckOBJCXXCompilerFlag
1395 New in version 3.16.
1396 Check whether the Objective-C++ compiler supports a given flag.
1399 check_objcxx_compiler_flag
1401 check_objcxx_compiler_flag(<flag> <var>)
1403 Check that the <flag> is accepted by the compiler without a di‐
1405 agnostic. Stores the result in an internal cache entry named
1406 <var>.
1407 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
1409 and calls the check_objcxx_source_compiles macro from the
1410 CheckOBJCXXSourceCompiles module. See documentation of that module for
1411 a listing of variables that can otherwise modify the build.
1412 A positive result from this check indicates only that the compiler did
1414 not issue a diagnostic message when given the flag. Whether the flag
1415 has any effect or even a specific one is beyond the scope of this mod‐
1416 ule.
1417 NOTE:
1419 Since the try_compile() command forwards flags from variables like
1420 CMAKE_OBJCXX_FLAGS, unknown flags in such variables may cause a
1421 false negative for this check.
1422 CheckOBJCXXSourceCompiles
1424 New in version 3.16.
1425 Check if given Objective-C++ source compiles and links into an exe‐
1428 cutable.
1429 check_objcxx_source_compiles
1431 check_objcxx_source_compiles(<code> <resultVar>
1433 [FAIL_REGEX <regex1> [<regex2>...]])
1434 Check that the source supplied in <code> can be compiled as a
1436 Objective-C++ source file and linked as an executable (so it
1437 must contain at least a main() function). The result will be
1438 stored in the internal cache variable specified by <resultVar>,
1439 with a boolean true value for success and boolean false for
1440 failure. If FAIL_REGEX is provided, then failure is determined
1441 by checking if anything in the output matches any of the speci‐
1442 fied regular expressions.
1443 The underlying check is performed by the try_compile() command.
1445 The compile and link commands can be influenced by setting any
1446 of the following variables prior to calling check_ob‐
1447 jcxx_source_compiles():
1448 CMAKE_REQUIRED_FLAGS
1450 Additional flags to pass to the compiler. Note that the
1451 contents of CMAKE_OBJCXX_FLAGS and its associated config‐
1452 uration-specific variable are automatically added to the
1453 compiler command before the contents of CMAKE_RE‐
1454 QUIRED_FLAGS.
1455 CMAKE_REQUIRED_DEFINITIONS
1457 A ;-list of compiler definitions of the form -DFOO or
1458 -DFOO=bar. A definition for the name specified by <re‐
1459 sultVar> will also be added automatically.
1460 CMAKE_REQUIRED_INCLUDES
1462 A ;-list of header search paths to pass to the compiler.
1463 These will be the only header search paths used by
1464 try_compile(), i.e. the contents of the
1465 INCLUDE_DIRECTORIES directory property will be ignored.
1466 CMAKE_REQUIRED_LINK_OPTIONS
1468 A ;-list of options to add to the link command (see
1469 try_compile() for further details).
1470 CMAKE_REQUIRED_LIBRARIES
1472 A ;-list of libraries to add to the link command. These
1473 can be the name of system libraries or they can be
1474 Imported Targets (see try_compile() for further details).
1475 CMAKE_REQUIRED_QUIET
1477 If this variable evaluates to a boolean true value, all
1478 status messages associated with the check will be sup‐
1479 pressed.
1480 The check is only performed once, with the result cached in the
1482 variable named by <resultVar>. Every subsequent CMake run will
1483 re-use this cached value rather than performing the check again,
1484 even if the <code> changes. In order to force the check to be
1485 re-evaluated, the variable named by <resultVar> must be manually
1486 removed from the cache.
1487 CheckOBJCXXSourceRuns
1489 New in version 3.16.
1490 Check if given Objective-C++ source compiles and links into an exe‐
1493 cutable and can subsequently be run.
1494 check_objcxx_source_runs
1496 check_objcxx_source_runs(<code> <resultVar>)
1498 Check that the source supplied in <code> can be compiled as a
1500 Objective-C++ source file, linked as an executable and then run.
1501 The <code> must contain at least a main() function. If the
1502 <code> could be built and run successfully, the internal cache
1503 variable specified by <resultVar> will be set to 1, otherwise it
1504 will be set to an value that evaluates to boolean false (e.g. an
1505 empty string or an error message).
1506 The underlying check is performed by the try_run() command. The
1508 compile and link commands can be influenced by setting any of
1509 the following variables prior to calling check_ob‐
1510 jcxx_source_runs():
1511 CMAKE_REQUIRED_FLAGS
1513 Additional flags to pass to the compiler. Note that the
1514 contents of CMAKE_OBJCXX_FLAGS and its associated config‐
1515 uration-specific variable are automatically added to the
1516 compiler command before the contents of CMAKE_RE‐
1517 QUIRED_FLAGS.
1518 CMAKE_REQUIRED_DEFINITIONS
1520 A ;-list of compiler definitions of the form -DFOO or
1521 -DFOO=bar. A definition for the name specified by <re‐
1522 sultVar> will also be added automatically.
1523 CMAKE_REQUIRED_INCLUDES
1525 A ;-list of header search paths to pass to the compiler.
1526 These will be the only header search paths used by
1527 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1528 directory property will be ignored.
1529 CMAKE_REQUIRED_LINK_OPTIONS
1531 A ;-list of options to add to the link command (see
1532 try_run() for further details).
1533 CMAKE_REQUIRED_LIBRARIES
1535 A ;-list of libraries to add to the link command. These
1536 can be the name of system libraries or they can be
1537 Imported Targets (see try_run() for further details).
1538 CMAKE_REQUIRED_QUIET
1540 If this variable evaluates to a boolean true value, all
1541 status messages associated with the check will be sup‐
1542 pressed.
1543 The check is only performed once, with the result cached in the
1545 variable named by <resultVar>. Every subsequent CMake run will
1546 re-use this cached value rather than performing the check again,
1547 even if the <code> changes. In order to force the check to be
1548 re-evaluated, the variable named by <resultVar> must be manually
1549 removed from the cache.
1550 CheckPIESupported
1552 New in version 3.14.
1553 Check whether the linker supports Position Independent Code (PIE) or No
1556 Position Independent Code (NO_PIE) for executables. Use this to ensure
1557 that the POSITION_INDEPENDENT_CODE target property for executables will
1558 be honored at link time.
1559 check_pie_supported
1561 check_pie_supported([OUTPUT_VARIABLE <output>]
1563 [LANGUAGES <lang>...])
1564 Options are:
1566 OUTPUT_VARIABLE <output>
1568 Set <output> variable with details about any error. If
1569 the check is bypassed because it uses cached results from
1570 a previous call, the output will be empty even if errors
1571 were present in the previous call.
1572 LANGUAGES <lang>...
1574 Check the linkers used for each of the specified lan‐
1575 guages. If this option is not provided, the command
1576 checks all enabled languages.
1577 C, CXX, Fortran are supported.
1579 New in version 3.23: OBJC, OBJCXX, CUDA, and HIP are sup‐
1581 ported.
1582 It makes no sense to use this module when CMP0083 is set to OLD, so the
1585 command will return an error in this case. See policy CMP0083 for de‐
1586 tails.
1587 Variables
1589 For each language checked, two boolean cache variables are defined.
1590 CMAKE_<lang>_LINK_PIE_SUPPORTED
1592 Set to true if PIE is supported by the linker and false oth‐
1593 erwise.
1594 CMAKE_<lang>_LINK_NO_PIE_SUPPORTED
1596 Set to true if NO_PIE is supported by the linker and false
1597 otherwise.
1598 Examples
1600 check_pie_supported()
1601 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1602 # Retrieve any error message.
1604 check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C)
1605 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1606 if(NOT CMAKE_C_LINK_PIE_SUPPORTED)
1607 message(WARNING "PIE is not supported at link time: ${output}.\n"
1608 "PIE link options will not be passed to linker.")
1609 endif()
1610 CheckPrototypeDefinition
1612 Check if the prototype we expect is correct.
1613 check_prototype_definition
1615 check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER VARIABLE)
1617 FUNCTION - The name of the function (used to check if prototype exists)
1619 PROTOTYPE- The prototype to check.
1620 RETURN - The return value of the function.
1621 HEADER - The header files required.
1622 VARIABLE - The variable to store the result.
1623 Will be created as an internal cache variable.
1624 Example:
1626 check_prototype_definition(getpwent_r
1628 "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)"
1629 "NULL"
1630 "unistd.h;pwd.h"
1631 SOLARIS_GETPWENT_R)
1632 The following variables may be set before calling this function to mod‐
1634 ify the way the check is run:
1635 CMAKE_REQUIRED_FLAGS
1637 string of compile command line flags.
1638 CMAKE_REQUIRED_DEFINITIONS
1640 list of macros to define (-DFOO=bar).
1641 CMAKE_REQUIRED_INCLUDES
1643 list of include directories.
1644 CMAKE_REQUIRED_LINK_OPTIONS
1646 New in version 3.14: list of options to pass to link command.
1647 CMAKE_REQUIRED_LIBRARIES
1650 list of libraries to link.
1651 CMAKE_REQUIRED_QUIET
1653 New in version 3.1: execute quietly without messages.
1654 CheckSourceCompiles
1657 New in version 3.19.
1658 Check if given source compiles and links into an executable.
1661 check_source_compiles
1663 check_source_compiles(<lang> <code> <resultVar>
1665 [FAIL_REGEX <regex1> [<regex2>...]]
1666 [SRC_EXT <extension>])
1667 Check that the source supplied in <code> can be compiled as a
1669 source file for the requested language and linked as an exe‐
1670 cutable (so it must contain at least a main() function). The re‐
1671 sult will be stored in the internal cache variable specified by
1672 <resultVar>, with a boolean true value for success and boolean
1673 false for failure. If FAIL_REGEX is provided, then failure is
1674 determined by checking if anything in the output matches any of
1675 the specified regular expressions.
1676 By default, the test source file will be given a file extension
1678 that matches the requested language. The SRC_EXT option can be
1679 used to override this with .<extension> instead.
1680 The underlying check is performed by the try_compile() command.
1682 The compile and link commands can be influenced by setting any
1683 of the following variables prior to calling check_source_com‐
1684 piles():
1685 CMAKE_REQUIRED_FLAGS
1687 Additional flags to pass to the compiler. Note that the
1688 contents of CMAKE_<LANG>_FLAGS and its associated config‐
1689 uration-specific variable are automatically added to the
1690 compiler command before the contents of CMAKE_RE‐
1691 QUIRED_FLAGS.
1692 CMAKE_REQUIRED_DEFINITIONS
1694 A ;-list of compiler definitions of the form -DFOO or
1695 -DFOO=bar. A definition for the name specified by <re‐
1696 sultVar> will also be added automatically.
1697 CMAKE_REQUIRED_INCLUDES
1699 A ;-list of header search paths to pass to the compiler.
1700 These will be the only header search paths used by
1701 try_compile(), i.e. the contents of the
1702 INCLUDE_DIRECTORIES directory property will be ignored.
1703 CMAKE_REQUIRED_LINK_OPTIONS
1705 A ;-list of options to add to the link command (see
1706 try_compile() for further details).
1707 CMAKE_REQUIRED_LIBRARIES
1709 A ;-list of libraries to add to the link command. These
1710 can be the name of system libraries or they can be
1711 Imported Targets (see try_compile() for further details).
1712 CMAKE_REQUIRED_QUIET
1714 If this variable evaluates to a boolean true value, all
1715 status messages associated with the check will be sup‐
1716 pressed.
1717 The check is only performed once, with the result cached in the
1719 variable named by <resultVar>. Every subsequent CMake run will
1720 re-use this cached value rather than performing the check again,
1721 even if the <code> changes. In order to force the check to be
1722 re-evaluated, the variable named by <resultVar> must be manually
1723 removed from the cache.
1724 CheckSourceRuns
1726 New in version 3.19.
1727 Check if given source compiles and links into an executable and can
1730 subsequently be run.
1731 check_source_runs
1733 check_source_runs(<lang> <code> <resultVar>
1735 [SRC_EXT <extension>])
1736 Check that the source supplied in <code> can be compiled as a
1738 source file for the requested language, linked as an executable
1739 and then run. The <code> must contain at least a main() func‐
1740 tion. If the <code> could be built and run successfully, the in‐
1741 ternal cache variable specified by <resultVar> will be set to 1,
1742 otherwise it will be set to an value that evaluates to boolean
1743 false (e.g. an empty string or an error message).
1744 By default, the test source file will be given a file extension
1746 that matches the requested language. The SRC_EXT option can be
1747 used to override this with .<extension> instead.
1748 The underlying check is performed by the try_run() command. The
1750 compile and link commands can be influenced by setting any of
1751 the following variables prior to calling
1752 check_objc_source_runs():
1753 CMAKE_REQUIRED_FLAGS
1755 Additional flags to pass to the compiler. Note that the
1756 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1757 ration-specific variable are automatically added to the
1758 compiler command before the contents of CMAKE_RE‐
1759 QUIRED_FLAGS.
1760 CMAKE_REQUIRED_DEFINITIONS
1762 A ;-list of compiler definitions of the form -DFOO or
1763 -DFOO=bar. A definition for the name specified by <re‐
1764 sultVar> will also be added automatically.
1765 CMAKE_REQUIRED_INCLUDES
1767 A ;-list of header search paths to pass to the compiler.
1768 These will be the only header search paths used by
1769 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1770 directory property will be ignored.
1771 CMAKE_REQUIRED_LINK_OPTIONS
1773 A ;-list of options to add to the link command (see
1774 try_run() for further details).
1775 CMAKE_REQUIRED_LIBRARIES
1777 A ;-list of libraries to add to the link command. These
1778 can be the name of system libraries or they can be
1779 Imported Targets (see try_run() for further details).
1780 CMAKE_REQUIRED_QUIET
1782 If this variable evaluates to a boolean true value, all
1783 status messages associated with the check will be sup‐
1784 pressed.
1785 The check is only performed once, with the result cached in the
1787 variable named by <resultVar>. Every subsequent CMake run will
1788 re-use this cached value rather than performing the check again,
1789 even if the <code> changes. In order to force the check to be
1790 re-evaluated, the variable named by <resultVar> must be manually
1791 removed from the cache.
1792 CheckStructHasMember
1794 Check if the given struct or class has the specified member variable
1795 CHECK_STRUCT_HAS_MEMBER
1797 CHECK_STRUCT_HAS_MEMBER(<struct> <member> <header> <variable>
1799 [LANGUAGE <language>])
1800 <struct> - the name of the struct or class you are interested in
1802 <member> - the member which existence you want to check
1803 <header> - the header(s) where the prototype should be declared
1804 <variable> - variable to store the result
1805 <language> - the compiler to use (C or CXX)
1806 The following variables may be set before calling this macro to modify
1808 the way the check is run:
1809 CMAKE_REQUIRED_FLAGS
1811 string of compile command line flags.
1812 CMAKE_REQUIRED_DEFINITIONS
1814 list of macros to define (-DFOO=bar).
1815 CMAKE_REQUIRED_INCLUDES
1817 list of include directories.
1818 CMAKE_REQUIRED_LINK_OPTIONS
1820 New in version 3.14: list of options to pass to link command.
1821 CMAKE_REQUIRED_LIBRARIES
1824 list of libraries to link.
1825 CMAKE_REQUIRED_QUIET
1827 New in version 3.1: execute quietly without messages.
1828 Example:
1831 CHECK_STRUCT_HAS_MEMBER("struct timeval" tv_sec sys/select.h
1833 HAVE_TIMEVAL_TV_SEC LANGUAGE C)
1834 CheckSymbolExists
1836 Provides a macro to check if a symbol exists as a function, variable,
1837 or macro in C.
1838 check_symbol_exists
1840 check_symbol_exists(<symbol> <files> <variable>)
1842 Check that the <symbol> is available after including given
1844 header <files> and store the result in a <variable>. Specify
1845 the list of files in one argument as a semicolon-separated list.
1846 <variable> will be created as an internal cache variable.
1847 If the header files define the symbol as a macro it is considered
1849 available and assumed to work. If the header files declare the symbol
1850 as a function or variable then the symbol must also be available for
1851 linking (so intrinsics may not be detected). If the symbol is a type,
1852 enum value, or intrinsic it will not be recognized (consider using
1853 CheckTypeSize or CheckSourceCompiles). If the check needs to be done
1854 in C++, consider using CheckCXXSymbolExists instead.
1855 The following variables may be set before calling this macro to modify
1857 the way the check is run:
1858 CMAKE_REQUIRED_FLAGS
1860 string of compile command line flags.
1861 CMAKE_REQUIRED_DEFINITIONS
1863 a ;-list of macros to define (-DFOO=bar).
1864 CMAKE_REQUIRED_INCLUDES
1866 a ;-list of header search paths to pass to the compiler.
1867 CMAKE_REQUIRED_LINK_OPTIONS
1869 New in version 3.14: a ;-list of options to add to the link com‐
1870 mand.
1871 CMAKE_REQUIRED_LIBRARIES
1874 a ;-list of libraries to add to the link command. See policy
1875 CMP0075.
1876 CMAKE_REQUIRED_QUIET
1878 New in version 3.1: execute quietly without messages.
1879 For example:
1882 include(CheckSymbolExists)
1884 # Check for macro SEEK_SET
1886 check_symbol_exists(SEEK_SET "stdio.h" HAVE_SEEK_SET)
1887 # Check for function fopen
1888 check_symbol_exists(fopen "stdio.h" HAVE_FOPEN)
1889 CheckTypeSize
1891 Check sizeof a type
1892 check_type_size
1894 check_type_size(<type> <variable> [BUILTIN_TYPES_ONLY]
1896 [LANGUAGE <language>])
1897 Check if the type exists and determine its size. Results are
1899 reported in the following variables:
1900 HAVE_<variable>
1902 Holds a true or false value indicating whether the type
1903 exists.
1904 <variable>
1906 Holds one of the following values:
1907 <size> Type has non-zero size <size>.
1909 0 Type has architecture-dependent size. This may
1911 occur when CMAKE_OSX_ARCHITECTURES has multiple
1912 architectures. In this case <variable>_CODE con‐
1913 tains C preprocessor tests mapping from each ar‐
1914 chitecture macro to the corresponding type size.
1915 The list of architecture macros is stored in
1916 <variable>_KEYS, and the value for each key is
1917 stored in <variable>-<key>.
1918 "" (empty string)
1920 Type does not exist.
1921 <variable>_CODE
1923 Holds C preprocessor code to define the macro <variable>
1924 to the size of the type, or to leave the macro undefined
1925 if the type does not exist.
1926 The options are:
1928 BUILTIN_TYPES_ONLY
1930 Support only compiler-builtin types. If not given, the macro
1931 checks for headers <sys/types.h>, <stdint.h>, and <stddef.h>,
1932 and saves results in HAVE_SYS_TYPES_H, HAVE_STDINT_H, and
1933 HAVE_STDDEF_H. The type size check automatically includes
1934 the available headers, thus supporting checks of types de‐
1935 fined in the headers.
1936 LANGUAGE <language>
1938 Use the <language> compiler to perform the check. Ac‐
1939 ceptable values are C and CXX.
1940 Despite the name of the macro you may use it to check the size of more
1942 complex expressions, too. To check e.g. for the size of a struct mem‐
1943 ber you can do something like this:
1944 check_type_size("((struct something*)0)->member" SIZEOF_MEMBER)
1946 The following variables may be set before calling this macro to modify
1948 the way the check is run:
1949 CMAKE_REQUIRED_FLAGS
1951 string of compile command line flags.
1952 CMAKE_REQUIRED_DEFINITIONS
1954 list of macros to define (-DFOO=bar).
1955 CMAKE_REQUIRED_INCLUDES
1957 list of include directories.
1958 CMAKE_REQUIRED_LINK_OPTIONS
1960 New in version 3.14: list of options to pass to link command.
1961 CMAKE_REQUIRED_LIBRARIES
1964 list of libraries to link.
1965 CMAKE_REQUIRED_QUIET
1967 New in version 3.1: execute quietly without messages.
1968 CMAKE_EXTRA_INCLUDE_FILES
1971 list of extra headers to include.
1972 CheckVariableExists
1974 Check if the variable exists.
1975 CHECK_VARIABLE_EXISTS
1977 CHECK_VARIABLE_EXISTS(VAR VARIABLE)
1979 VAR - the name of the variable
1981 VARIABLE - variable to store the result
1982 Will be created as an internal cache variable.
1983 This macro is only for C variables.
1985 The following variables may be set before calling this macro to modify
1987 the way the check is run:
1988 CMAKE_REQUIRED_FLAGS
1990 string of compile command line flags.
1991 CMAKE_REQUIRED_DEFINITIONS
1993 list of macros to define (-DFOO=bar).
1994 CMAKE_REQUIRED_LINK_OPTIONS
1996 New in version 3.14: list of options to pass to link command.
1997 CMAKE_REQUIRED_LIBRARIES
2000 list of libraries to link.
2001 CMAKE_REQUIRED_QUIET
2003 New in version 3.1: execute quietly without messages.
2004 CMakeAddFortranSubdirectory
2007 Add a fortran-only subdirectory, find a fortran compiler, and build.
2008 The cmake_add_fortran_subdirectory function adds a subdirectory to a
2010 project that contains a fortran-only subproject. The module will check
2011 the current compiler and see if it can support fortran. If no fortran
2012 compiler is found and the compiler is MSVC, then this module will find
2013 the MinGW gfortran. It will then use an external project to build with
2014 the MinGW tools. It will also create imported targets for the li‐
2015 braries created. This will only work if the fortran code is built into
2016 a dll, so BUILD_SHARED_LIBS is turned on in the project. In addition
2017 the CMAKE_GNUtoMS option is set to on, so that Microsoft .lib files are
2018 created. Usage is as follows:
2019 cmake_add_fortran_subdirectory(
2021 <subdir> # name of subdirectory
2022 PROJECT <project_name> # project name in subdir top CMakeLists.txt
2023 ARCHIVE_DIR <dir> # dir where project places .lib files
2024 RUNTIME_DIR <dir> # dir where project places .dll files
2025 LIBRARIES <lib>... # names of library targets to import
2026 LINK_LIBRARIES # link interface libraries for LIBRARIES
2027 [LINK_LIBS <lib> <dep>...]...
2028 CMAKE_COMMAND_LINE ... # extra command line flags to pass to cmake
2029 NO_EXTERNAL_INSTALL # skip installation of external project
2030 )
2031 Relative paths in ARCHIVE_DIR and RUNTIME_DIR are interpreted with re‐
2033 spect to the build directory corresponding to the source directory in
2034 which the function is invoked.
2035 Limitations:
2037 NO_EXTERNAL_INSTALL is required for forward compatibility with a future
2039 version that supports installation of the external project binaries
2040 during make install.
2041 CMakeBackwardCompatibilityCXX
2043 define a bunch of backwards compatibility variables
2044 CMAKE_ANSI_CXXFLAGS - flag for ansi c++
2046 CMAKE_HAS_ANSI_STRING_STREAM - has <strstream>
2047 include(TestForANSIStreamHeaders)
2048 include(CheckIncludeFileCXX)
2049 include(TestForSTDNamespace)
2050 include(TestForANSIForScope)
2051 CMakeDependentOption
2053 Macro to provide an option dependent on other options.
2054 This macro presents an option to the user only if a set of other condi‐
2056 tions are true.
2057 cmake_dependent_option
2059 cmake_dependent_option(<option> "<help_text>" <value> <depends> <force>)
2061 Makes <option> available to the user if the semicolon-separated
2063 list of conditions in <depends> are all true. Otherwise, a lo‐
2064 cal variable named <option> is set to <force>.
2065 When <option> is available, the given <help_text> and initial
2067 <value> are used. Otherwise, any value set by the user is pre‐
2068 served for when <depends> is satisfied in the future.
2069 Note that the <option> variable only has a value which satisfies
2071 the <depends> condition within the scope of the caller because
2072 it is a local variable.
2073 Example invocation:
2075 cmake_dependent_option(USE_FOO "Use Foo" ON "USE_BAR;NOT USE_ZOT" OFF)
2077 If USE_BAR is true and USE_ZOT is false, this provides an option called
2079 USE_FOO that defaults to ON. Otherwise, it sets USE_FOO to OFF and
2080 hides the option from the user. If the status of USE_BAR or USE_ZOT
2081 ever changes, any value for the USE_FOO option is saved so that when
2082 the option is re-enabled it retains its old value.
2083 New in version 3.22: Full Condition Syntax is now supported. See pol‐
2085 icy CMP0127.
2086 CMakeFindDependencyMacro
2089 find_dependency
2090 The find_dependency() macro wraps a find_package() call for a
2091 package dependency:
2092 find_dependency(<dep> [...])
2094 It is designed to be used in a Package Configuration File
2096 (<PackageName>Config.cmake). find_dependency forwards the cor‐
2097 rect parameters for QUIET and REQUIRED which were passed to the
2098 original find_package() call. Any additional arguments speci‐
2099 fied are forwarded to find_package().
2100 If the dependency could not be found it sets an informative di‐
2102 agnostic message and calls return() to end processing of the
2103 calling package configuration file and return to the
2104 find_package() command that loaded it.
2105 NOTE:
2107 The call to return() makes this macro unsuitable to call from
2108 Find Modules.
2109 CMakeFindFrameworks
2111 helper module to find OSX frameworks
2112 This module reads hints about search locations from variables:
2114 CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS - Extra directories
2116 CMakeFindPackageMode
2118 This file is executed by cmake when invoked with --find-package. It
2119 expects that the following variables are set using -D:
2120 NAME name of the package
2122 COMPILER_ID
2124 the CMake compiler ID for which the result is, i.e. GNU/In‐
2125 tel/Clang/MSVC, etc.
2126 LANGUAGE
2128 language for which the result will be used, i.e. C/CXX/For‐
2129 tran/ASM
2130 MODE
2132 EXIST only check for existence of the given package
2134 COMPILE
2136 print the flags needed for compiling an object file which
2137 uses the given package
2138 LINK print the flags needed for linking when using the given
2140 package
2141 QUIET if TRUE, don't print anything
2143 CMakeGraphVizOptions
2145 The builtin Graphviz support of CMake.
2146 Generating Graphviz files
2148 CMake can generate Graphviz files showing the dependencies between the
2149 targets in a project, as well as external libraries which are linked
2150 against.
2151 When running CMake with the --graphviz=foo.dot option, it produces:
2153 • a foo.dot file, showing all dependencies in the project
2155 • a foo.dot.<target> file for each target, showing on which other tar‐
2157 gets it depends
2158 • a foo.dot.<target>.dependers file for each target, showing which
2160 other targets depend on it
2161 Those .dot files can be converted to images using the dot command from
2163 the Graphviz package:
2164 dot -Tpng -o foo.png foo.dot
2166 New in version 3.10: The different dependency types PUBLIC, INTERFACE
2168 and PRIVATE are represented as solid, dashed and dotted edges.
2169 Variables specific to the Graphviz support
2172 The resulting graphs can be huge. The look and content of the gener‐
2173 ated graphs can be controlled using the file CMakeGraphVizOp‐
2174 tions.cmake. This file is first searched in CMAKE_BINARY_DIR, and then
2175 in CMAKE_SOURCE_DIR. If found, the variables set in it are used to ad‐
2176 just options for the generated Graphviz files.
2177 GRAPHVIZ_GRAPH_NAME
2179 The graph name.
2180 • Mandatory: NO
2182 • Default: value of CMAKE_PROJECT_NAME
2184 GRAPHVIZ_GRAPH_HEADER
2186 The header written at the top of the Graphviz files.
2187 • Mandatory: NO
2189 • Default: "node [ fontsize = "12" ];"
2191 GRAPHVIZ_NODE_PREFIX
2193 The prefix for each node in the Graphviz files.
2194 • Mandatory: NO
2196 • Default: "node"
2198 GRAPHVIZ_EXECUTABLES
2200 Set to FALSE to exclude executables from the generated graphs.
2201 • Mandatory: NO
2203 • Default: TRUE
2205 GRAPHVIZ_STATIC_LIBS
2207 Set to FALSE to exclude static libraries from the generated
2208 graphs.
2209 • Mandatory: NO
2211 • Default: TRUE
2213 GRAPHVIZ_SHARED_LIBS
2215 Set to FALSE to exclude shared libraries from the generated
2216 graphs.
2217 • Mandatory: NO
2219 • Default: TRUE
2221 GRAPHVIZ_MODULE_LIBS
2223 Set to FALSE to exclude module libraries from the generated
2224 graphs.
2225 • Mandatory: NO
2227 • Default: TRUE
2229 GRAPHVIZ_INTERFACE_LIBS
2231 Set to FALSE to exclude interface libraries from the generated
2232 graphs.
2233 • Mandatory: NO
2235 • Default: TRUE
2237 GRAPHVIZ_OBJECT_LIBS
2239 Set to FALSE to exclude object libraries from the generated
2240 graphs.
2241 • Mandatory: NO
2243 • Default: TRUE
2245 GRAPHVIZ_UNKNOWN_LIBS
2247 Set to FALSE to exclude unknown libraries from the generated
2248 graphs.
2249 • Mandatory: NO
2251 • Default: TRUE
2253 GRAPHVIZ_EXTERNAL_LIBS
2255 Set to FALSE to exclude external libraries from the generated
2256 graphs.
2257 • Mandatory: NO
2259 • Default: TRUE
2261 GRAPHVIZ_CUSTOM_TARGETS
2263 Set to TRUE to include custom targets in the generated graphs.
2264 • Mandatory: NO
2266 • Default: FALSE
2268 GRAPHVIZ_IGNORE_TARGETS
2270 A list of regular expressions for names of targets to exclude
2271 from the generated graphs.
2272 • Mandatory: NO
2274 • Default: empty
2276 GRAPHVIZ_GENERATE_PER_TARGET
2278 Set to FALSE to not generate per-target graphs foo.dot.<target>.
2279 • Mandatory: NO
2281 • Default: TRUE
2283 GRAPHVIZ_GENERATE_DEPENDERS
2285 Set to FALSE to not generate depender graphs foo.dot.<tar‐
2286 get>.dependers.
2287 • Mandatory: NO
2289 • Default: TRUE
2291 CMakePackageConfigHelpers
2293 Helpers functions for creating config files that can be included by
2294 other projects to find and use a package.
2295 Adds the configure_package_config_file() and
2297 write_basic_package_version_file() commands.
2298 Generating a Package Configuration File
2300 configure_package_config_file
2301 Create a config file for a project:
2302 configure_package_config_file(<input> <output>
2304 INSTALL_DESTINATION <path>
2305 [PATH_VARS <var1> <var2> ... <varN>]
2306 [NO_SET_AND_CHECK_MACRO]
2307 [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
2308 [INSTALL_PREFIX <path>]
2309 )
2310 configure_package_config_file() should be used instead of the plain
2312 configure_file() command when creating the <PackageName>Config.cmake or
2313 <PackageName>-config.cmake file for installing a project or library.
2314 It helps making the resulting package relocatable by avoiding hardcoded
2315 paths in the installed Config.cmake file.
2316 In a FooConfig.cmake file there may be code like this to make the in‐
2318 stall destinations know to the using project:
2319 set(FOO_INCLUDE_DIR "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
2321 set(FOO_DATA_DIR "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
2322 set(FOO_ICONS_DIR "@CMAKE_INSTALL_PREFIX@/share/icons" )
2323 #...logic to determine installedPrefix from the own location...
2324 set(FOO_CONFIG_DIR "${installedPrefix}/@CONFIG_INSTALL_DIR@" )
2325 All 4 options shown above are not sufficient, since the first 3 hard‐
2327 code the absolute directory locations, and the 4th case works only if
2328 the logic to determine the installedPrefix is correct, and if CON‐
2329 FIG_INSTALL_DIR contains a relative path, which in general cannot be
2330 guaranteed. This has the effect that the resulting FooConfig.cmake
2331 file would work poorly under Windows and OSX, where users are used to
2332 choose the install location of a binary package at install time, inde‐
2333 pendent from how CMAKE_INSTALL_PREFIX was set at build/cmake time.
2334 Using configure_package_config_file helps. If used correctly, it makes
2336 the resulting FooConfig.cmake file relocatable. Usage:
2337 1. write a FooConfig.cmake.in file as you are used to
2339 2. insert a line containing only the string @PACKAGE_INIT@
2341 3. instead of set(FOO_DIR "@SOME_INSTALL_DIR@"), use set(FOO_DIR
2343 "@PACKAGE_SOME_INSTALL_DIR@") (this must be after the @PACKAGE_INIT@
2344 line)
2345 4. instead of using the normal configure_file(), use configure_pack‐
2347 age_config_file()
2348 The <input> and <output> arguments are the input and output file, the
2350 same way as in configure_file().
2351 The <path> given to INSTALL_DESTINATION must be the destination where
2353 the FooConfig.cmake file will be installed to. This path can either be
2354 absolute, or relative to the INSTALL_PREFIX path.
2355 The variables <var1> to <varN> given as PATH_VARS are the variables
2357 which contain install destinations. For each of them the macro will
2358 create a helper variable PACKAGE_<var...>. These helper variables must
2359 be used in the FooConfig.cmake.in file for setting the installed loca‐
2360 tion. They are calculated by configure_package_config_file so that
2361 they are always relative to the installed location of the package.
2362 This works both for relative and also for absolute locations. For ab‐
2363 solute locations it works only if the absolute location is a subdirec‐
2364 tory of INSTALL_PREFIX.
2365 New in version 3.1: If the INSTALL_PREFIX argument is passed, this is
2367 used as base path to calculate all the relative paths. The <path> ar‐
2368 gument must be an absolute path. If this argument is not passed, the
2369 CMAKE_INSTALL_PREFIX variable will be used instead. The default value
2370 is good when generating a FooConfig.cmake file to use your package from
2371 the install tree. When generating a FooConfig.cmake file to use your
2372 package from the build tree this option should be used.
2373 By default configure_package_config_file also generates two helper
2376 macros, set_and_check() and check_required_components() into the
2377 FooConfig.cmake file.
2378 set_and_check() should be used instead of the normal set() command for
2380 setting directories and file locations. Additionally to setting the
2381 variable it also checks that the referenced file or directory actually
2382 exists and fails with a FATAL_ERROR otherwise. This makes sure that
2383 the created FooConfig.cmake file does not contain wrong references.
2384 When using the NO_SET_AND_CHECK_MACRO, this macro is not generated into
2385 the FooConfig.cmake file.
2386 check_required_components(<PackageName>) should be called at the end of
2388 the FooConfig.cmake file. This macro checks whether all requested,
2389 non-optional components have been found, and if this is not the case,
2390 sets the Foo_FOUND variable to FALSE, so that the package is considered
2391 to be not found. It does that by testing the Foo_<Component>_FOUND
2392 variables for all requested required components. This macro should be
2393 called even if the package doesn't provide any components to make sure
2394 users are not specifying components erroneously. When using the
2395 NO_CHECK_REQUIRED_COMPONENTS_MACRO option, this macro is not generated
2396 into the FooConfig.cmake file.
2397 For an example see below the documentation for
2399 write_basic_package_version_file().
2400 Generating a Package Version File
2402 write_basic_package_version_file
2403 Create a version file for a project:
2404 write_basic_package_version_file(<filename>
2406 [VERSION <major.minor.patch>]
2407 COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion>
2408 [ARCH_INDEPENDENT] )
2409 Writes a file for use as <PackageName>ConfigVersion.cmake file to
2411 <filename>. See the documentation of find_package() for details on
2412 this.
2413 <filename> is the output filename, it should be in the build tree.
2415 <major.minor.patch> is the version number of the project to be in‐
2416 stalled.
2417 If no VERSION is given, the PROJECT_VERSION variable is used. If this
2419 hasn't been set, it errors out.
2420 The COMPATIBILITY mode AnyNewerVersion means that the installed package
2422 version will be considered compatible if it is newer or exactly the
2423 same as the requested version. This mode should be used for packages
2424 which are fully backward compatible, also across major versions. If
2425 SameMajorVersion is used instead, then the behavior differs from
2426 AnyNewerVersion in that the major version number must be the same as
2427 requested, e.g. version 2.0 will not be considered compatible if 1.0
2428 is requested. This mode should be used for packages which guarantee
2429 backward compatibility within the same major version. If SameMinorVer‐
2430 sion is used, the behavior is the same as SameMajorVersion, but both
2431 major and minor version must be the same as requested, e.g version 0.2
2432 will not be compatible if 0.1 is requested. If ExactVersion is used,
2433 then the package is only considered compatible if the requested version
2434 matches exactly its own version number (not considering the tweak ver‐
2435 sion). For example, version 1.2.3 of a package is only considered com‐
2436 patible to requested version 1.2.3. This mode is for packages without
2437 compatibility guarantees. If your project has more elaborated version
2438 matching rules, you will need to write your own custom ConfigVer‐
2439 sion.cmake file instead of using this macro.
2440 New in version 3.11: The SameMinorVersion compatibility mode.
2442 New in version 3.14: If ARCH_INDEPENDENT is given, the installed pack‐
2445 age version will be considered compatible even if it was built for a
2446 different architecture than the requested architecture. Otherwise, an
2447 architecture check will be performed, and the package will be consid‐
2448 ered compatible only if the architecture matches exactly. For example,
2449 if the package is built for a 32-bit architecture, the package is only
2450 considered compatible if it is used on a 32-bit architecture, unless
2451 ARCH_INDEPENDENT is given, in which case the package is considered com‐
2452 patible on any architecture.
2453 NOTE:
2456 ARCH_INDEPENDENT is intended for header-only libraries or similar
2457 packages with no binaries.
2458 New in version 3.19: The version file generated by AnyNewerVersion,
2460 SameMajorVersion and SameMinorVersion arguments of COMPATIBILITY handle
2461 the version range if any is specified (see find_package() command for
2462 the details). ExactVersion mode is incompatible with version ranges
2463 and will display an author warning if one is specified.
2464 Internally, this macro executes configure_file() to create the result‐
2467 ing version file. Depending on the COMPATIBILITY, the corresponding
2468 BasicConfigVersion-<COMPATIBILITY>.cmake.in file is used. Please note
2469 that these files are internal to CMake and you should not call
2470 configure_file() on them yourself, but they can be used as starting
2471 point to create more sophisticted custom ConfigVersion.cmake files.
2472 Example Generating Package Files
2474 Example using both configure_package_config_file() and write_ba‐
2475 sic_package_version_file():
2476 CMakeLists.txt:
2478 set(INCLUDE_INSTALL_DIR include/ ... CACHE )
2480 set(LIB_INSTALL_DIR lib/ ... CACHE )
2481 set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
2482 #...
2483 include(CMakePackageConfigHelpers)
2484 configure_package_config_file(FooConfig.cmake.in
2485 ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2486 INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
2487 PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
2488 write_basic_package_version_file(
2489 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2490 VERSION 1.2.3
2491 COMPATIBILITY SameMajorVersion )
2492 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2493 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2494 DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )
2495 FooConfig.cmake.in:
2497 set(FOO_VERSION x.y.z)
2499 ...
2500 @PACKAGE_INIT@
2501 ...
2502 set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
2503 set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")
2504 check_required_components(Foo)
2506 CMakePrintHelpers
2508 Convenience functions for printing properties and variables, useful
2509 e.g. for debugging.
2510 cmake_print_properties(<TARGETS [<target1> ...] |
2512 SOURCES [<source1> ...] |
2513 DIRECTORIES [<dir1> ...] |
2514 TESTS [<test1> ...] |
2515 CACHE_ENTRIES [<entry1> ...] >
2516 PROPERTIES [<prop1> ...] )
2517 This function prints the values of the properties of the given targets,
2519 source files, directories, tests or cache entries. Exactly one of the
2520 scope keywords must be used. The scope keyword and its arguments must
2521 come before the PROPERTIES keyword, in the arguments list.
2522 Example:
2524 cmake_print_properties(TARGETS foo bar PROPERTIES
2526 LOCATION INTERFACE_INCLUDE_DIRECTORIES)
2527 This will print the LOCATION and INTERFACE_INCLUDE_DIRECTORIES proper‐
2529 ties for both targets foo and bar.
2530 cmake_print_variables(var1 var2 .. varN)
2532 This function will print the name of each variable followed by its
2534 value. Example:
2535 cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION DOES_NOT_EXIST)
2537 Gives:
2539 -- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; DOES_NOT_EXIST=""
2541 CMakePrintSystemInformation
2543 Print system information.
2544 This module serves diagnostic purposes. Just include it in a project to
2546 see various internal CMake variables.
2547 CMakePushCheckState
2549 This module defines three macros: CMAKE_PUSH_CHECK_STATE()
2550 CMAKE_POP_CHECK_STATE() and CMAKE_RESET_CHECK_STATE() These macros can
2551 be used to save, restore and reset (i.e., clear contents) the state of
2552 the variables CMAKE_REQUIRED_FLAGS, CMAKE_REQUIRED_DEFINITIONS,
2553 CMAKE_REQUIRED_LINK_OPTIONS, CMAKE_REQUIRED_LIBRARIES, CMAKE_RE‐
2554 QUIRED_INCLUDES and CMAKE_EXTRA_INCLUDE_FILES used by the various
2555 Check-files coming with CMake, like e.g. check_function_exists() etc.
2556 The variable contents are pushed on a stack, pushing multiple times is
2557 supported. This is useful e.g. when executing such tests in a
2558 Find-module, where they have to be set, but after the Find-module has
2559 been executed they should have the same value as they had before.
2560 CMAKE_PUSH_CHECK_STATE() macro receives optional argument RESET.
2562 Whether it's specified, CMAKE_PUSH_CHECK_STATE() will set all CMAKE_RE‐
2563 QUIRED_* variables to empty values, same as CMAKE_RESET_CHECK_STATE()
2564 call will do.
2565 Usage:
2567 cmake_push_check_state(RESET)
2569 set(CMAKE_REQUIRED_DEFINITIONS -DSOME_MORE_DEF)
2570 check_function_exists(...)
2571 cmake_reset_check_state()
2572 set(CMAKE_REQUIRED_DEFINITIONS -DANOTHER_DEF)
2573 check_function_exists(...)
2574 cmake_pop_check_state()
2575 CMakeVerifyManifest
2577 CMakeVerifyManifest.cmake
2578 This script is used to verify that embedded manifests and side by side
2580 manifests for a project match. To run this script, cd to a directory
2581 and run the script with cmake -P. On the command line you can pass in
2582 versions that are OK even if not found in the .manifest files. For ex‐
2583 ample, cmake -Dallow_versions=8.0.50608.0 -PCmakeVerifyManifest.cmake
2584 could be used to allow an embedded manifest of 8.0.50608.0 to be used
2585 in a project even if that version was not found in the .manifest file.
2586 CPack
2588 Configure generators for binary installers and source packages.
2589 Introduction
2591 The CPack module generates the configuration files CPackConfig.cmake
2592 and CPackSourceConfig.cmake. They are intended for use in a subsequent
2593 run of the cpack program where they steer the generation of installers
2594 or/and source packages.
2595 Depending on the CMake generator, the CPack module may also add two new
2597 build targets, package and package_source. See the packaging targets
2598 section below for details.
2599 The generated binary installers will contain all files that have been
2601 installed via CMake's install() command (and the deprecated commands
2602 install_files(), install_programs(), and install_targets()). Note that
2603 the DESTINATION option of the install() command must be a relative
2604 path; otherwise installed files are ignored by CPack.
2605 Certain kinds of binary installers can be configured such that users
2607 can select individual application components to install. See the
2608 CPackComponent module for further details.
2609 Source packages (configured through CPackSourceConfig.cmake and gener‐
2611 ated by the CPack Archive Generator) will contain all source files in
2612 the project directory except those specified in
2613 CPACK_SOURCE_IGNORE_FILES.
2614 CPack Generators
2616 The CPACK_GENERATOR variable has different meanings in different con‐
2617 texts. In a CMakeLists.txt file, CPACK_GENERATOR is a list of genera‐
2618 tors: and when cpack is run with no other arguments, it will iterate
2619 over that list and produce one package for each generator. In a
2620 CPACK_PROJECT_CONFIG_FILE, CPACK_GENERATOR is a string naming a single
2621 generator. If you need per-cpack-generator logic to control other
2622 cpack settings, then you need a CPACK_PROJECT_CONFIG_FILE. If set, the
2623 CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator
2624 basis. It only need contain overrides.
2625 Here's how it works:
2627 • cpack runs
2629 • it includes CPackConfig.cmake
2631 • it iterates over the generators given by the -G command line option,
2633 or if no such option was specified, over the list of generators given
2634 by the CPACK_GENERATOR variable set in the CPackConfig.cmake input
2635 file.
2636 • foreach generator, it then
2638 • sets CPACK_GENERATOR to the one currently being iterated
2640 • includes the CPACK_PROJECT_CONFIG_FILE
2642 • produces the package for that generator
2644 This is the key: For each generator listed in CPACK_GENERATOR in CPack‐
2646 Config.cmake, cpack will reset CPACK_GENERATOR internally to the one
2647 currently being used and then include the CPACK_PROJECT_CONFIG_FILE.
2648 For a list of available generators, see cpack-generators(7).
2650 Targets package and package_source
2652 If CMake is run with the Makefile, Ninja, or Xcode generator, then in‐
2653 clude(CPack) generates a target package. This makes it possible to
2654 build a binary installer from CMake, Make, or Ninja: Instead of cpack,
2655 one may call cmake --build . --target package or make package or ninja
2656 package. The VS generator creates an uppercase target PACKAGE.
2657 If CMake is run with the Makefile or Ninja generator, then in‐
2659 clude(CPack) also generates a target package_source. To build a source
2660 package, instead of cpack -G TGZ --config CPackSourceConfig.cmake one
2661 may call cmake --build . --target package_source, make package_source,
2662 or ninja package_source.
2663 Variables common to all CPack Generators
2665 Before including this CPack module in your CMakeLists.txt file, there
2666 are a variety of variables that can be set to customize the resulting
2667 installers. The most commonly-used variables are:
2668 CPACK_PACKAGE_NAME
2670 The name of the package (or application). If not specified, it
2671 defaults to the project name.
2672 CPACK_PACKAGE_VENDOR
2674 The name of the package vendor. (e.g., "Kitware"). The default
2675 is "Humanity".
2676 CPACK_PACKAGE_DIRECTORY
2678 The directory in which CPack is doing its packaging. If it is
2679 not set then this will default (internally) to the build dir.
2680 This variable may be defined in a CPack config file or from the
2681 cpack command line option -B. If set, the command line option
2682 overrides the value found in the config file.
2683 CPACK_PACKAGE_VERSION_MAJOR
2685 Package major version. This variable will always be set, but
2686 its default value depends on whether or not version details were
2687 given to the project() command in the top level CMakeLists.txt
2688 file. If version details were given, the default value will be
2689 CMAKE_PROJECT_VERSION_MAJOR. If no version details were given,
2690 a default version of 0.1.1 will be assumed, leading to
2691 CPACK_PACKAGE_VERSION_MAJOR having a default value of 0.
2692 CPACK_PACKAGE_VERSION_MINOR
2694 Package minor version. The default value is determined based on
2695 whether or not version details were given to the project() com‐
2696 mand in the top level CMakeLists.txt file. If version details
2697 were given, the default value will be
2698 CMAKE_PROJECT_VERSION_MINOR, but if no minor version component
2699 was specified then CPACK_PACKAGE_VERSION_MINOR will be left un‐
2700 set. If no project version was given at all, a default version
2701 of 0.1.1 will be assumed, leading to CPACK_PACKAGE_VERSION_MINOR
2702 having a default value of 1.
2703 CPACK_PACKAGE_VERSION_PATCH
2705 Package patch version. The default value is determined based on
2706 whether or not version details were given to the project() com‐
2707 mand in the top level CMakeLists.txt file. If version details
2708 were given, the default value will be
2709 CMAKE_PROJECT_VERSION_PATCH, but if no patch version component
2710 was specified then CPACK_PACKAGE_VERSION_PATCH will be left un‐
2711 set. If no project version was given at all, a default version
2712 of 0.1.1 will be assumed, leading to CPACK_PACKAGE_VERSION_PATCH
2713 having a default value of 1.
2714 CPACK_PACKAGE_DESCRIPTION
2716 A description of the project, used in places such as the intro‐
2717 duction screen of CPack-generated Windows installers. If not
2718 set, the value of this variable is populated from the file named
2719 by CPACK_PACKAGE_DESCRIPTION_FILE.
2720 CPACK_PACKAGE_DESCRIPTION_FILE
2722 A text file used to describe the project when
2723 CPACK_PACKAGE_DESCRIPTION is not explicitly set. The default
2724 value for CPACK_PACKAGE_DESCRIPTION_FILE points to a built-in
2725 template file Templates/CPack.GenericDescription.txt.
2726 CPACK_PACKAGE_DESCRIPTION_SUMMARY
2728 Short description of the project (only a few words). If the
2729 CMAKE_PROJECT_DESCRIPTION variable is set, it is used as the de‐
2730 fault value, otherwise the default will be a string generated by
2731 CMake based on CMAKE_PROJECT_NAME.
2732 CPACK_PACKAGE_HOMEPAGE_URL
2734 Project homepage URL. The default value is taken from the
2735 CMAKE_PROJECT_HOMEPAGE_URL variable, which is set by the top
2736 level project() command, or else the default will be empty if no
2737 URL was provided to project().
2738 CPACK_PACKAGE_FILE_NAME
2740 The name of the package file to generate, not including the ex‐
2741 tension. For example, cmake-2.6.1-Linux-i686. The default
2742 value is:
2743 ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}
2745 CPACK_PACKAGE_INSTALL_DIRECTORY
2747 Installation directory on the target system. This may be used by
2748 some CPack generators like NSIS to create an installation direc‐
2749 tory e.g., "CMake 2.5" below the installation prefix. All in‐
2750 stalled elements will be put inside this directory.
2751 CPACK_PACKAGE_ICON
2753 A branding image that will be displayed inside the installer
2754 (used by GUI installers).
2755 CPACK_PACKAGE_CHECKSUM
2757 New in version 3.7.
2758 An algorithm that will be used to generate an additional file
2761 with the checksum of the package. The output file name will be:
2762 ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}
2764 Supported algorithms are those listed by the string(<HASH>) com‐
2766 mand.
2767 CPACK_PROJECT_CONFIG_FILE
2769 CPack-time project CPack configuration file. This file is in‐
2770 cluded at cpack time, once per generator after CPack has set
2771 CPACK_GENERATOR to the actual generator being used. It allows
2772 per-generator setting of CPACK_* variables at cpack time.
2773 CPACK_RESOURCE_FILE_LICENSE
2775 License to be embedded in the installer. It will typically be
2776 displayed to the user by the produced installer (often with an
2777 explicit "Accept" button, for graphical installers) prior to in‐
2778 stallation. This license file is NOT added to the installed
2779 files but is used by some CPack generators like NSIS. If you
2780 want to use UTF-8 characters, the file needs to be encoded in
2781 UTF-8 BOM. If you want to install a license file (may be the
2782 same as this one) along with your project, you must add an ap‐
2783 propriate CMake install() command in your CMakeLists.txt.
2784 CPACK_RESOURCE_FILE_README
2786 ReadMe file to be embedded in the installer. It typically de‐
2787 scribes in some detail the purpose of the project during the in‐
2788 stallation. Not all CPack generators use this file.
2789 CPACK_RESOURCE_FILE_WELCOME
2791 Welcome file to be embedded in the installer. It welcomes users
2792 to this installer. Typically used in the graphical installers
2793 on Windows and Mac OS X.
2794 CPACK_MONOLITHIC_INSTALL
2796 Disables the component-based installation mechanism. When set,
2797 the component specification is ignored and all installed items
2798 are put in a single "MONOLITHIC" package. Some CPack generators
2799 do monolithic packaging by default and may be asked to do compo‐
2800 nent packaging by setting CPACK_<GENNAME>_COMPONENT_INSTALL to
2801 TRUE.
2802 CPACK_GENERATOR
2804 List of CPack generators to use. If not specified, CPack will
2805 create a set of options following the naming pattern
2806 CPACK_BINARY_<GENNAME> (e.g. CPACK_BINARY_NSIS) allowing the
2807 user to enable/disable individual generators. If the -G option
2808 is given on the cpack command line, it will override this vari‐
2809 able and any CPACK_BINARY_<GENNAME> options.
2810 CPACK_OUTPUT_CONFIG_FILE
2812 The name of the CPack binary configuration file. This file is
2813 the CPack configuration generated by the CPack module for binary
2814 installers. Defaults to CPackConfig.cmake.
2815 CPACK_PACKAGE_EXECUTABLES
2817 Lists each of the executables and associated text label to be
2818 used to create Start Menu shortcuts. For example, setting this
2819 to the list ccmake;CMake will create a shortcut named "CMake"
2820 that will execute the installed executable ccmake. Not all
2821 CPack generators use it (at least NSIS, and WIX do).
2822 CPACK_STRIP_FILES
2824 List of files to be stripped. Starting with CMake 2.6.0,
2825 CPACK_STRIP_FILES will be a boolean variable which enables
2826 stripping of all files (a list of files evaluates to TRUE in
2827 CMake, so this change is compatible).
2828 CPACK_VERBATIM_VARIABLES
2830 New in version 3.4.
2831 If set to TRUE, values of variables prefixed with CPACK_ will be
2834 escaped before being written to the configuration files, so that
2835 the cpack program receives them exactly as they were specified.
2836 If not, characters like quotes and backslashes can cause parsing
2837 errors or alter the value received by the cpack program. De‐
2838 faults to FALSE for backwards compatibility.
2839 CPACK_THREADS
2841 New in version 3.20.
2842 Number of threads to use when performing parallelized opera‐
2845 tions, such as compressing the installer package.
2846 Some compression methods used by CPack generators such as Debian
2848 or Archive may take advantage of multiple CPU cores to speed up
2849 compression. CPACK_THREADS can be set to specify how many
2850 threads will be used for compression.
2851 A positive integer can be used to specify an exact desired
2853 thread count.
2854 When given a negative integer CPack will use the absolute value
2856 as the upper limit but may choose a lower value based on the
2857 available hardware concurrency.
2858 Given 0 CPack will try to use all available CPU cores.
2860 By default CPACK_THREADS is set to 1.
2862 The following compression methods may take advantage of multiple
2864 cores:
2865 xz Supported if CMake is built with a liblzma that supports
2867 parallel compression.
2868 New in version 3.21: Official CMake binaries available on
2870 cmake.org now ship with a liblzma that supports parallel
2871 compression. Older versions did not.
2872 zstd New in version 3.24.
2875 Supported if CMake is built with libarchive 3.6 or
2878 higher. Official CMake binaries available on cmake.org
2879 support it.
2880 Other compression methods ignore this value and use only one
2882 thread.
2883 Variables for Source Package Generators
2885 The following CPack variables are specific to source packages, and will
2886 not affect binary packages:
2887 CPACK_SOURCE_PACKAGE_FILE_NAME
2889 The name of the source package. For example cmake-2.6.1.
2890 CPACK_SOURCE_STRIP_FILES
2892 List of files in the source tree that will be stripped. Start‐
2893 ing with CMake 2.6.0, CPACK_SOURCE_STRIP_FILES will be a boolean
2894 variable which enables stripping of all files (a list of files
2895 evaluates to TRUE in CMake, so this change is compatible).
2896 CPACK_SOURCE_GENERATOR
2898 List of generators used for the source packages. As with
2899 CPACK_GENERATOR, if this is not specified then CPack will create
2900 a set of options (e.g. CPACK_SOURCE_ZIP) allowing users to se‐
2901 lect which packages will be generated.
2902 CPACK_SOURCE_OUTPUT_CONFIG_FILE
2904 The name of the CPack source configuration file. This file is
2905 the CPack configuration generated by the CPack module for source
2906 installers. Defaults to CPackSourceConfig.cmake.
2907 CPACK_SOURCE_IGNORE_FILES
2909 Pattern of files in the source tree that won't be packaged when
2910 building a source package. This is a list of regular expression
2911 patterns (that must be properly escaped), e.g.,
2912 /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
2913 Variables for Advanced Use
2915 The following variables are for advanced uses of CPack:
2916 CPACK_CMAKE_GENERATOR
2918 What CMake generator should be used if the project is a CMake
2919 project. Defaults to the value of CMAKE_GENERATOR. Few users
2920 will want to change this setting.
2921 CPACK_INSTALL_CMAKE_PROJECTS
2923 List of four values that specify what project to install. The
2924 four values are: Build directory, Project Name, Project Compo‐
2925 nent, Directory. If omitted, CPack will build an installer that
2926 installs everything.
2927 CPACK_SYSTEM_NAME
2929 System name, defaults to the value of CMAKE_SYSTEM_NAME, except
2930 on Windows where it will be win32 or win64.
2931 CPACK_PACKAGE_VERSION
2933 Package full version, used internally. By default, this is
2934 built from CPACK_PACKAGE_VERSION_MAJOR,
2935 CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH.
2936 CPACK_TOPLEVEL_TAG
2938 Directory for the installed files.
2939 CPACK_INSTALL_COMMANDS
2941 Extra commands to install components. The environment variable
2942 CMAKE_INSTALL_PREFIX is set to the temporary install directory
2943 during execution.
2944 CPACK_INSTALL_SCRIPTS
2946 New in version 3.16.
2947 Extra CMake scripts executed by CPack during its local staging
2950 installation. They are executed before installing the files to
2951 be packaged. The scripts are not called by a standalone install
2952 (e.g.: make install). For every script, the following variables
2953 will be set: CMAKE_CURRENT_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR
2954 and CMAKE_INSTALL_PREFIX (which is set to the staging install
2955 directory). The singular form CMAKE_INSTALL_SCRIPT is supported
2956 as an alternative variable for historical reasons, but its value
2957 is ignored if CMAKE_INSTALL_SCRIPTS is set and a warning will be
2958 issued.
2959 See also CPACK_PRE_BUILD_SCRIPTS and CPACK_POST_BUILD_SCRIPTS
2961 which can be used to specify scripts to be executed later in the
2962 packaging process.
2963 CPACK_PRE_BUILD_SCRIPTS
2965 New in version 3.19.
2966 List of CMake scripts to execute after CPack has installed the
2969 files to be packaged into a staging directory and before produc‐
2970 ing the package(s) from those files. See also
2971 CPACK_INSTALL_SCRIPTS and CPACK_POST_BUILD_SCRIPTS.
2972 CPACK_POST_BUILD_SCRIPTS
2974 New in version 3.19.
2975 List of CMake scripts to execute after CPack has produced the
2978 resultant packages and before copying them back to the build di‐
2979 rectory. See also CPACK_INSTALL_SCRIPTS,
2980 CPACK_PRE_BUILD_SCRIPTS and CPACK_PACKAGE_FILES.
2981 CPACK_PACKAGE_FILES
2983 New in version 3.19.
2984 List of package files created in the staging directory, with
2987 each file provided as a full absolute path. This variable is
2988 populated by CPack just before invoking the post-build scripts
2989 listed in CPACK_POST_BUILD_SCRIPTS. It is the preferred way for
2990 the post-build scripts to know the set of package files to oper‐
2991 ate on. Projects should not try to set this variable them‐
2992 selves.
2993 CPACK_INSTALLED_DIRECTORIES
2995 Extra directories to install.
2996 CPACK_PACKAGE_INSTALL_REGISTRY_KEY
2998 Registry key used when installing this project. This is only
2999 used by installers for Windows. The default value is based on
3000 the installation directory.
3001 CPACK_CREATE_DESKTOP_LINKS
3003 List of desktop links to create. Each desktop link requires a
3004 corresponding start menu shortcut as created by
3005 CPACK_PACKAGE_EXECUTABLES.
3006 CPACK_BINARY_<GENNAME>
3008 CPack generated options for binary generators. The CPack.cmake
3009 module generates (when CPACK_GENERATOR is not set) a set of
3010 CMake options (see CMake option() command) which may then be
3011 used to select the CPack generator(s) to be used when building
3012 the package target or when running cpack without the -G option.
3013 CPACK_READELF_EXECUTABLE
3015 New in version 3.25.
3016 Specify the readelf executable path used by CPack. The default
3019 value will be CMAKE_READELF when set. Otherwise, the default
3020 value will be empty and CPack will use find_program() to deter‐
3021 mine the readelf path when needed.
3022 CPACK_OBJCOPY_EXECUTABLE
3024 New in version 3.25.
3025 Specify the objcopy executable path used by CPack. The default
3028 value will be CMAKE_OBJCOPY when set. Otherwise, the default
3029 value will be empty and CPack will use find_program() to deter‐
3030 mine the objcopy path when needed.
3031 CPACK_OBJDUMP_EXECUTABLE
3033 New in version 3.25.
3034 Specify the objdump executable path used by CPack. The default
3037 value will be CMAKE_OBJDUMP when set. Otherwise, the default
3038 value will be empty and CPack will use find_program() to deter‐
3039 mine the objdump path when needed.
3040 CPackComponent
3042 Configure components for binary installers and source packages.
3043 Introduction
3045 This module is automatically included by CPack.
3046 Certain binary installers (especially the graphical installers) gener‐
3048 ated by CPack allow users to select individual application components
3049 to install. This module allows developers to configure the packaging
3050 of such components.
3051 Contents is assigned to components by the COMPONENT argument of CMake's
3053 install() command. Components can be annotated with user-friendly
3054 names and descriptions, inter-component dependencies, etc., and grouped
3055 in various ways to customize the resulting installer, using the com‐
3056 mands described below.
3057 To specify different groupings for different CPack generators use a
3059 CPACK_PROJECT_CONFIG_FILE.
3060 Variables
3062 The following variables influence the component-specific packaging:
3063 CPACK_COMPONENTS_ALL
3065 The list of component to install.
3066 The default value of this variable is computed by CPack and con‐
3068 tains all components defined by the project. The user may set
3069 it to only include the specified components.
3070 Instead of specifying all the desired components, it is possible
3072 to obtain a list of all defined components and then remove the
3073 unwanted ones from the list. The get_cmake_property() command
3074 can be used to obtain the COMPONENTS property, then the
3075 list(REMOVE_ITEM) command can be used to remove the unwanted
3076 ones. For example, to use all defined components except foo and
3077 bar:
3078 get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS)
3080 list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar")
3081 CPACK_<GENNAME>_COMPONENT_INSTALL
3083 Enable/Disable component install for CPack generator <GENNAME>.
3084 Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc...) has
3086 a legacy default behavior. e.g. RPM builds monolithic whereas
3087 NSIS builds component. One can change the default behavior by
3088 setting this variable to 0/1 or OFF/ON.
3089 CPACK_COMPONENTS_GROUPING
3091 Specify how components are grouped for multi-package compo‐
3092 nent-aware CPack generators.
3093 Some generators like RPM or ARCHIVE (TGZ, ZIP, ...) may generate
3095 several packages files when there are components, depending on
3096 the value of this variable:
3097 • ONE_PER_GROUP (default): create one package per component
3099 group
3100 • IGNORE : create one package per component (ignore the groups)
3102 • ALL_COMPONENTS_IN_ONE : create a single package with all re‐
3104 quested components
3105 CPACK_COMPONENT_<compName>_DISPLAY_NAME
3107 The name to be displayed for a component.
3108 CPACK_COMPONENT_<compName>_DESCRIPTION
3110 The description of a component.
3111 CPACK_COMPONENT_<compName>_GROUP
3113 The group of a component.
3114 CPACK_COMPONENT_<compName>_DEPENDS
3116 The dependencies (list of components) on which this component
3117 depends.
3118 CPACK_COMPONENT_<compName>_HIDDEN
3120 True if this component is hidden from the user.
3121 CPACK_COMPONENT_<compName>_REQUIRED
3123 True if this component is required.
3124 CPACK_COMPONENT_<compName>_DISABLED
3126 True if this component is not selected to be installed by de‐
3127 fault.
3128 Commands
3130 Add component
3131 cpack_add_component
3132 Describe an installation component.
3134 cpack_add_component(compname
3136 [DISPLAY_NAME name]
3137 [DESCRIPTION description]
3138 [HIDDEN | REQUIRED | DISABLED ]
3139 [GROUP group]
3140 [DEPENDS comp1 comp2 ... ]
3141 [INSTALL_TYPES type1 type2 ... ]
3142 [DOWNLOADED]
3143 [ARCHIVE_FILE filename]
3144 [PLIST filename])
3145 compname is the name of an installation component, as defined by the
3147 COMPONENT argument of one or more CMake install() commands. With the
3148 cpack_add_component command one can set a name, a description, and
3149 other attributes of an installation component. One can also assign a
3150 component to a component group.
3151 DISPLAY_NAME is the displayed name of the component, used in graphical
3153 installers to display the component name. This value can be any
3154 string.
3155 DESCRIPTION is an extended description of the component, used in graph‐
3157 ical installers to give the user additional information about the com‐
3158 ponent. Descriptions can span multiple lines using \n as the line sep‐
3159 arator. Typically, these descriptions should be no more than a few
3160 lines long.
3161 HIDDEN indicates that this component will be hidden in the graphical
3163 installer, so that the user cannot directly change whether it is in‐
3164 stalled or not.
3165 REQUIRED indicates that this component is required, and therefore will
3167 always be installed. It will be visible in the graphical installer,
3168 but it cannot be unselected. (Typically, required components are shown
3169 greyed out).
3170 DISABLED indicates that this component should be disabled (unselected)
3172 by default. The user is free to select this component for installa‐
3173 tion, unless it is also HIDDEN.
3174 DEPENDS lists the components on which this component depends. If this
3176 component is selected, then each of the components listed must also be
3177 selected. The dependency information is encoded within the installer
3178 itself, so that users cannot install inconsistent sets of components.
3179 GROUP names the component group of which this component is a part. If
3181 not provided, the component will be a standalone component, not part of
3182 any component group. Component groups are described with the
3183 cpack_add_component_group command, detailed below.
3184 INSTALL_TYPES lists the installation types of which this component is a
3186 part. When one of these installations types is selected, this compo‐
3187 nent will automatically be selected. Installation types are described
3188 with the cpack_add_install_type command, detailed below.
3189 DOWNLOADED indicates that this component should be downloaded
3191 on-the-fly by the installer, rather than packaged in with the installer
3192 itself. For more information, see the cpack_configure_downloads com‐
3193 mand.
3194 ARCHIVE_FILE provides a name for the archive file created by CPack to
3196 be used for downloaded components. If not supplied, CPack will create
3197 a file with some name based on CPACK_PACKAGE_FILE_NAME and the name of
3198 the component. See cpack_configure_downloads for more information.
3199 PLIST gives a filename that is passed to pkgbuild with the --compo‐
3201 nent-plist argument when using the productbuild generator.
3202 Add component group
3204 cpack_add_component_group
3205 Describes a group of related CPack installation components.
3207 cpack_add_component_group(groupname
3209 [DISPLAY_NAME name]
3210 [DESCRIPTION description]
3211 [PARENT_GROUP parent]
3212 [EXPANDED]
3213 [BOLD_TITLE])
3214 The cpack_add_component_group describes a group of installation compo‐
3216 nents, which will be placed together within the listing of options.
3217 Typically, component groups allow the user to select/deselect all of
3218 the components within a single group via a single group-level option.
3219 Use component groups to reduce the complexity of installers with many
3220 options. groupname is an arbitrary name used to identify the group in
3221 the GROUP argument of the cpack_add_component command, which is used to
3222 place a component in a group. The name of the group must not conflict
3223 with the name of any component.
3224 DISPLAY_NAME is the displayed name of the component group, used in
3226 graphical installers to display the component group name. This value
3227 can be any string.
3228 DESCRIPTION is an extended description of the component group, used in
3230 graphical installers to give the user additional information about the
3231 components within that group. Descriptions can span multiple lines us‐
3232 ing \n as the line separator. Typically, these descriptions should be
3233 no more than a few lines long.
3234 PARENT_GROUP, if supplied, names the parent group of this group. Par‐
3236 ent groups are used to establish a hierarchy of groups, providing an
3237 arbitrary hierarchy of groups.
3238 EXPANDED indicates that, by default, the group should show up as "ex‐
3240 panded", so that the user immediately sees all of the components within
3241 the group. Otherwise, the group will initially show up as a single en‐
3242 try.
3243 BOLD_TITLE indicates that the group title should appear in bold, to
3245 call the user's attention to the group.
3246 Add installation type
3248 cpack_add_install_type
3249 Add a new installation type containing a set of predefined component
3251 selections to the graphical installer.
3252 cpack_add_install_type(typename
3254 [DISPLAY_NAME name])
3255 The cpack_add_install_type command identifies a set of preselected com‐
3257 ponents that represents a common use case for an application. For ex‐
3258 ample, a "Developer" install type might include an application along
3259 with its header and library files, while an "End user" install type
3260 might just include the application's executable. Each component iden‐
3261 tifies itself with one or more install types via the INSTALL_TYPES ar‐
3262 gument to cpack_add_component.
3263 DISPLAY_NAME is the displayed name of the install type, which will typ‐
3265 ically show up in a drop-down box within a graphical installer. This
3266 value can be any string.
3267 Configure downloads
3269 cpack_configure_downloads
3270 Configure CPack to download selected components on-the-fly as part of
3272 the installation process.
3273 cpack_configure_downloads(site
3275 [UPLOAD_DIRECTORY dirname]
3276 [ALL]
3277 [ADD_REMOVE|NO_ADD_REMOVE])
3278 The cpack_configure_downloads command configures installation-time
3280 downloads of selected components. For each downloadable component,
3281 CPack will create an archive containing the contents of that component,
3282 which should be uploaded to the given site. When the user selects that
3283 component for installation, the installer will download and extract the
3284 component in place. This feature is useful for creating small install‐
3285 ers that only download the requested components, saving bandwidth. Ad‐
3286 ditionally, the installers are small enough that they will be installed
3287 as part of the normal installation process, and the "Change" button in
3288 Windows Add/Remove Programs control panel will allow one to add or re‐
3289 move parts of the application after the original installation. On Win‐
3290 dows, the downloaded-components functionality requires the ZipDLL
3291 plug-in for NSIS, available at:
3292 http://nsis.sourceforge.net/ZipDLL_plug-in
3294 On macOS, installers that download components on-the-fly can only be
3296 built and installed on system using macOS 10.5 or later.
3297 The site argument is a URL where the archives for downloadable compo‐
3299 nents will reside, e.g., https://cmake.org/files/v3.25/ All of the ar‐
3300 chives produced by CPack should be uploaded to that location.
3301 UPLOAD_DIRECTORY is the local directory where CPack will create the
3303 various archives for each of the components. The contents of this di‐
3304 rectory should be uploaded to a location accessible by the URL given in
3305 the site argument. If omitted, CPack will use the directory CPackU‐
3306 ploads inside the CMake binary directory to store the generated ar‐
3307 chives.
3308 The ALL flag indicates that all components be downloaded. Otherwise,
3310 only those components explicitly marked as DOWNLOADED or that have a
3311 specified ARCHIVE_FILE will be downloaded. Additionally, the ALL op‐
3312 tion implies ADD_REMOVE (unless NO_ADD_REMOVE is specified).
3313 ADD_REMOVE indicates that CPack should install a copy of the installer
3315 that can be called from Windows' Add/Remove Programs dialog (via the
3316 "Modify" button) to change the set of installed components. NO_ADD_RE‐
3317 MOVE turns off this behavior. This option is ignored on Mac OS X.
3318 CPackIFW
3320 New in version 3.1.
3321 This module looks for the location of the command-line utilities sup‐
3324 plied with the Qt Installer Framework (QtIFW).
3325 The module also defines several commands to control the behavior of the
3327 CPack IFW Generator.
3328 Commands
3330 The module defines the following commands:
3331 cpack_ifw_configure_component
3333 Sets the arguments specific to the CPack IFW generator.
3334 cpack_ifw_configure_component(<compname> [COMMON] [ESSENTIAL] [VIRTUAL]
3336 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
3337 [NAME <name>]
3338 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
3339 [DESCRIPTION <description>] # Note: Internationalization supported
3340 [UPDATE_TEXT <update_text>]
3341 [VERSION <version>]
3342 [RELEASE_DATE <release_date>]
3343 [SCRIPT <script>]
3344 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
3345 [DEPENDS|DEPENDENCIES <com_id> ...]
3346 [AUTO_DEPEND_ON <comp_id> ...]
3347 [LICENSES <display_name> <file_path> ...]
3348 [DEFAULT <value>]
3349 [USER_INTERFACES <file_path> <file_path> ...]
3350 [TRANSLATIONS <file_path> <file_path> ...]
3351 [REPLACES <comp_id> ...]
3352 [CHECKABLE <value>])
3353 This command should be called after cpack_add_component() com‐
3355 mand.
3356 COMMON if set, then the component will be packaged and installed
3358 as part of a group to which it belongs.
3359 ESSENTIAL
3361 New in version 3.6.
3362 if set, then the package manager stays disabled until
3365 that component is updated.
3366 VIRTUAL
3368 New in version 3.8.
3369 if set, then the component will be hidden from the in‐
3372 staller. It is a equivalent of the HIDDEN option from
3373 the cpack_add_component() command.
3374 FORCED_INSTALLATION
3376 New in version 3.8.
3377 if set, then the component must always be installed. It
3380 is a equivalent of the REQUIRED option from the
3381 cpack_add_component() command.
3382 REQUIRES_ADMIN_RIGHTS
3384 New in version 3.8.
3385 set it if the component needs to be installed with ele‐
3388 vated permissions.
3389 NAME is used to create domain-like identification for this
3391 component. By default used origin component name.
3392 DISPLAY_NAME
3394 New in version 3.8.
3395 set to rewrite original name configured by
3398 cpack_add_component() command.
3399 DESCRIPTION
3401 New in version 3.8.
3402 set to rewrite original description configured by
3405 cpack_add_component() command.
3406 UPDATE_TEXT
3408 New in version 3.8.
3409 will be added to the component description if this is an
3412 update to the component.
3413 VERSION
3415 is version of component. By default used
3416 CPACK_PACKAGE_VERSION.
3417 RELEASE_DATE
3419 New in version 3.8.
3420 keep empty to auto generate.
3423 SCRIPT is a relative or absolute path to operations script for
3425 this component.
3426 SORTING_PRIORITY
3428 New in version 3.8.
3429 is priority of the component in the tree.
3432 PRIORITY
3434 Deprecated since version 3.8: Old name for SORTING_PRIOR‐
3435 ITY.
3436 DEPENDS, DEPENDENCIES
3439 New in version 3.8.
3440 list of dependency component or component group identi‐
3443 fiers in QtIFW style.
3444 New in version 3.21.
3446 Component or group names listed as dependencies may con‐
3449 tain hyphens. This requires QtIFW 3.1 or later.
3450 AUTO_DEPEND_ON
3452 New in version 3.8.
3453 list of identifiers of component or component group in
3456 QtIFW style that this component has an automatic depen‐
3457 dency on.
3458 LICENSES
3460 pair of <display_name> and <file_path> of license text
3461 for this component. You can specify more then one li‐
3462 cense.
3463 DEFAULT
3465 New in version 3.8.
3466 Possible values are: TRUE, FALSE, and SCRIPT. Set to
3469 FALSE to disable the component in the installer or to
3470 SCRIPT to resolved during runtime (don't forget add the
3471 file of the script as a value of the SCRIPT option).
3472 USER_INTERFACES
3474 New in version 3.7.
3475 is a list of <file_path> ('.ui' files) representing pages
3478 to load.
3479 TRANSLATIONS
3481 New in version 3.8.
3482 is a list of <file_path> ('.qm' files) representing
3485 translations to load.
3486 REPLACES
3488 New in version 3.10.
3489 list of identifiers of component or component group to
3492 replace.
3493 CHECKABLE
3495 New in version 3.10.
3496 Possible values are: TRUE, FALSE. Set to FALSE if you
3499 want to hide the checkbox for an item. This is useful
3500 when only a few subcomponents should be selected instead
3501 of all.
3502 cpack_ifw_configure_component_group
3504 Sets the arguments specific to the CPack IFW generator.
3505 cpack_ifw_configure_component_group(<groupname> [VIRTUAL]
3507 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
3508 [NAME <name>]
3509 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
3510 [DESCRIPTION <description>] # Note: Internationalization supported
3511 [UPDATE_TEXT <update_text>]
3512 [VERSION <version>]
3513 [RELEASE_DATE <release_date>]
3514 [SCRIPT <script>]
3515 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
3516 [DEPENDS|DEPENDENCIES <com_id> ...]
3517 [AUTO_DEPEND_ON <comp_id> ...]
3518 [LICENSES <display_name> <file_path> ...]
3519 [DEFAULT <value>]
3520 [USER_INTERFACES <file_path> <file_path> ...]
3521 [TRANSLATIONS <file_path> <file_path> ...]
3522 [REPLACES <comp_id> ...]
3523 [CHECKABLE <value>])
3524 This command should be called after cpack_add_component_group()
3526 command.
3527 VIRTUAL
3529 New in version 3.8.
3530 if set, then the group will be hidden from the installer.
3533 Note that setting this on a root component does not work.
3534 FORCED_INSTALLATION
3536 New in version 3.8.
3537 if set, then the group must always be installed.
3540 REQUIRES_ADMIN_RIGHTS
3542 New in version 3.8.
3543 set it if the component group needs to be installed with
3546 elevated permissions.
3547 NAME is used to create domain-like identification for this
3549 component group. By default used origin component group
3550 name.
3551 DISPLAY_NAME
3553 New in version 3.8.
3554 set to rewrite original name configured by
3557 cpack_add_component_group() command.
3558 DESCRIPTION
3560 New in version 3.8.
3561 set to rewrite original description configured by
3564 cpack_add_component_group() command.
3565 UPDATE_TEXT
3567 New in version 3.8.
3568 will be added to the component group description if this
3571 is an update to the component group.
3572 VERSION
3574 is version of component group. By default used
3575 CPACK_PACKAGE_VERSION.
3576 RELEASE_DATE
3578 New in version 3.8.
3579 keep empty to auto generate.
3582 SCRIPT is a relative or absolute path to operations script for
3584 this component group.
3585 SORTING_PRIORITY
3587 is priority of the component group in the tree.
3588 PRIORITY
3590 Deprecated since version 3.8: Old name for SORTING_PRIOR‐
3591 ITY.
3592 DEPENDS, DEPENDENCIES
3595 New in version 3.8.
3596 list of dependency component or component group identi‐
3599 fiers in QtIFW style.
3600 New in version 3.21.
3602 Component or group names listed as dependencies may con‐
3605 tain hyphens. This requires QtIFW 3.1 or later.
3606 AUTO_DEPEND_ON
3608 New in version 3.8.
3609 list of identifiers of component or component group in
3612 QtIFW style that this component group has an automatic
3613 dependency on.
3614 LICENSES
3616 pair of <display_name> and <file_path> of license text
3617 for this component group. You can specify more then one
3618 license.
3619 DEFAULT
3621 New in version 3.8.
3622 Possible values are: TRUE, FALSE, and SCRIPT. Set to
3625 TRUE to preselect the group in the installer (this takes
3626 effect only on groups that have no visible child compo‐
3627 nents) or to SCRIPT to resolved during runtime (don't
3628 forget add the file of the script as a value of the
3629 SCRIPT option).
3630 USER_INTERFACES
3632 New in version 3.7.
3633 is a list of <file_path> ('.ui' files) representing pages
3636 to load.
3637 TRANSLATIONS
3639 New in version 3.8.
3640 is a list of <file_path> ('.qm' files) representing
3643 translations to load.
3644 REPLACES
3646 New in version 3.10.
3647 list of identifiers of component or component group to
3650 replace.
3651 CHECKABLE
3653 New in version 3.10.
3654 Possible values are: TRUE, FALSE. Set to FALSE if you
3657 want to hide the checkbox for an item. This is useful
3658 when only a few subcomponents should be selected instead
3659 of all.
3660 cpack_ifw_add_repository
3662 Add QtIFW specific remote repository to binary installer.
3663 cpack_ifw_add_repository(<reponame> [DISABLED]
3665 URL <url>
3666 [USERNAME <username>]
3667 [PASSWORD <password>]
3668 [DISPLAY_NAME <display_name>])
3669 This command will also add the <reponame> repository to a vari‐
3671 able CPACK_IFW_REPOSITORIES_ALL.
3672 DISABLED
3674 if set, then the repository will be disabled by default.
3675 URL is points to a list of available components.
3677 USERNAME
3679 is used as user on a protected repository.
3680 PASSWORD
3682 is password to use on a protected repository.
3683 DISPLAY_NAME
3685 is string to display instead of the URL.
3686 cpack_ifw_update_repository
3688 New in version 3.6.
3689 Update QtIFW specific repository from remote repository.
3692 cpack_ifw_update_repository(<reponame>
3694 [[ADD|REMOVE] URL <url>]|
3695 [REPLACE OLD_URL <old_url> NEW_URL <new_url>]]
3696 [USERNAME <username>]
3697 [PASSWORD <password>]
3698 [DISPLAY_NAME <display_name>])
3699 This command will also add the <reponame> repository to a vari‐
3701 able CPACK_IFW_REPOSITORIES_ALL.
3702 URL is points to a list of available components.
3704 OLD_URL
3706 is points to a list that will replaced.
3707 NEW_URL
3709 is points to a list that will replace to.
3710 USERNAME
3712 is used as user on a protected repository.
3713 PASSWORD
3715 is password to use on a protected repository.
3716 DISPLAY_NAME
3718 is string to display instead of the URL.
3719 cpack_ifw_add_package_resources
3721 New in version 3.7.
3722 Add additional resources in the installer binary.
3725 cpack_ifw_add_package_resources(<file_path> <file_path> ...)
3727 This command will also add the specified files to a variable
3729 CPACK_IFW_PACKAGE_RESOURCES.
3730 CPackIFWConfigureFile
3732 New in version 3.8.
3733 The module defines configure_file() similar command to configure file
3736 templates prepared in QtIFW/SDK/Creator style.
3737 Commands
3739 The module defines the following commands:
3740 cpack_ifw_configure_file
3742 Copy a file to another location and modify its contents.
3743 cpack_ifw_configure_file(<input> <output>)
3745 Copies an <input> file to an <output> file and substitutes vari‐
3747 able values referenced as %{VAR} or %VAR% in the input file con‐
3748 tent. Each variable reference will be replaced with the current
3749 value of the variable, or the empty string if the variable is
3750 not defined.
3751 CSharpUtilities
3753 New in version 3.8.
3754 Functions to make configuration of CSharp/.NET targets easier.
3757 A collection of CMake utility functions useful for dealing with CSharp
3759 targets for Visual Studio generators from version 2010 and later.
3760 The following functions are provided by this module:
3762 Main functions
3764 • csharp_set_windows_forms_properties()
3766 • csharp_set_designer_cs_properties()
3768 • csharp_set_xaml_cs_properties()
3770 Helper functions
3772 • csharp_get_filename_keys()
3774 • csharp_get_filename_key_base()
3776 • csharp_get_dependentupon_name()
3778 Main functions provided by the module
3780 csharp_set_windows_forms_properties
3781 Sets source file properties for use of Windows Forms. Use this,
3782 if your CSharp target uses Windows Forms:
3783 csharp_set_windows_forms_properties([<file1> [<file2> [...]]])
3785 <fileN>
3787 List of all source files which are relevant for setting
3788 the VS_CSHARP_<tagname> properties (including .cs, .resx
3789 and .Designer.cs extensions).
3790 In the list of all given files for all files ending with .De‐
3792 signer.cs and .resx is searched. For every designer or resource
3793 file a file with the same base name but only .cs as extension is
3794 searched. If this is found, the VS_CSHARP_<tagname> properties
3795 are set as follows:
3796 for the .cs file:
3798 • VS_CSHARP_SubType "Form"
3800 for the .Designer.cs file (if it exists):
3802 • VS_CSHARP_DependentUpon <cs-filename>
3804 • VS_CSHARP_DesignTime "" (delete tag if previously de‐
3806 fined)
3807 • VS_CSHARP_AutoGen ""(delete tag if previously defined)
3809 for the .resx file (if it exists):
3811 • VS_RESOURCE_GENERATOR "" (delete tag if previously de‐
3813 fined)
3814 • VS_CSHARP_DependentUpon <cs-filename>
3816 • VS_CSHARP_SubType "Designer"
3818 csharp_set_designer_cs_properties
3820 Sets source file properties of .Designer.cs files depending on
3821 sibling filenames. Use this, if your CSharp target does not use
3822 Windows Forms (for Windows Forms use
3823 csharp_set_designer_cs_properties() instead):
3824 csharp_set_designer_cs_properties([<file1> [<file2> [...]]])
3826 <fileN>
3828 List of all source files which are relevant for setting
3829 the VS_CSHARP_<tagname> properties (including .cs, .resx,
3830 .settings and .Designer.cs extensions).
3831 In the list of all given files for all files ending with .De‐
3833 signer.cs is searched. For every designer file all files with
3834 the same base name but different extensions are searched. If a
3835 match is found, the source file properties of the designer file
3836 are set depending on the extension of the matched file:
3837 if match is .resx file:
3839 • VS_CSHARP_AutoGen "True"
3841 • VS_CSHARP_DesignTime "True"
3843 • VS_CSHARP_DependentUpon <resx-filename>
3845 if match is .cs file:
3847 • VS_CSHARP_DependentUpon <cs-filename>
3849 if match is .settings file:
3851 • VS_CSHARP_AutoGen "True"
3853 • VS_CSHARP_DesignTimeSharedInput "True"
3855 • VS_CSHARP_DependentUpon <settings-filename>
3857 NOTE:
3859 Because the source file properties of the .Designer.cs file are set
3860 according to the found matches and every match sets the
3861 VS_CSHARP_DependentUpon property, there should only be one match for
3862 each Designer.cs file.
3863 csharp_set_xaml_cs_properties
3865 Sets source file properties for use of Windows Presentation
3866 Foundation (WPF) and XAML. Use this, if your CSharp target uses
3867 WPF/XAML:
3868 csharp_set_xaml_cs_properties([<file1> [<file2> [...]]])
3870 <fileN>
3872 List of all source files which are relevant for setting
3873 the VS_CSHARP_<tagname> properties (including .cs, .xaml,
3874 and .xaml.cs extensions).
3875 In the list of all given files for all files ending with
3877 .xaml.cs is searched. For every xaml-cs file, a file with the
3878 same base name but extension .xaml is searched. If a match is
3879 found, the source file properties of the .xaml.cs file are set:
3880 • VS_CSHARP_DependentUpon <xaml-filename>
3882 Helper functions which are used by the above ones
3884 csharp_get_filename_keys
3885 Helper function which computes a list of key values to identify
3886 source files independently of relative/absolute paths given in
3887 cmake and eliminates case sensitivity:
3888 csharp_get_filename_keys(OUT [<file1> [<file2> [...]]])
3890 OUT Name of the variable in which the list of keys is stored
3892 <fileN>
3894 filename(s) as given to to CSharp target using
3895 add_library() or add_executable()
3896 In some way the function applies a canonicalization to the
3898 source names. This is necessary to find file matches if the
3899 files have been added to the target with different directory
3900 prefixes:
3901 add_library(lib
3903 myfile.cs
3904 ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs)
3905 set_source_files_properties(myfile.Designer.cs PROPERTIES
3907 VS_CSHARP_DependentUpon myfile.cs)
3908 # this will fail, because in cmake
3910 # - ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs
3911 # - myfile.Designer.cs
3912 # are not the same source file. The source file property is not set.
3913 csharp_get_filename_key_base
3915 Returns the full filepath and name without extension of a key.
3916 KEY is expected to be a key from csharp_get_filename_keys. In
3917 BASE the value of KEY without the file extension is returned:
3918 csharp_get_filename_key_base(BASE KEY)
3920 BASE Name of the variable with the computed "base" of KEY.
3922 KEY The key of which the base will be computed. Expected to
3924 be a upper case full filename.
3925 csharp_get_dependentupon_name
3927 Computes a string which can be used as value for the source file
3928 property VS_CSHARP_<tagname> with target being DependentUpon:
3929 csharp_get_dependentupon_name(NAME FILE)
3931 NAME Name of the variable with the result value
3933 FILE Filename to convert to <DependentUpon> value
3935 Actually this is only the filename without any path given at the
3937 moment.
3938 CTest
3940 Configure a project for testing with CTest/CDash
3941 Include this module in the top CMakeLists.txt file of a project to en‐
3943 able testing with CTest and dashboard submissions to CDash:
3944 project(MyProject)
3946 ...
3947 include(CTest)
3948 The module automatically creates a BUILD_TESTING option that selects
3950 whether to enable testing support (ON by default). After including the
3951 module, use code like:
3952 if(BUILD_TESTING)
3954 # ... CMake code to create tests ...
3955 endif()
3956 to creating tests when testing is enabled.
3958 To enable submissions to a CDash server, create a CTestConfig.cmake
3960 file at the top of the project with content such as:
3961 set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
3963 set(CTEST_SUBMIT_URL "http://my.cdash.org/submit.php?project=MyProject")
3964 (the CDash server can provide the file to a project administrator who
3966 configures MyProject). Settings in the config file are shared by both
3967 this CTest module and the ctest(1) command-line Dashboard Client mode
3968 (ctest -S).
3969 While building a project for submission to CDash, CTest scans the build
3971 output for errors and warnings and reports them with surrounding con‐
3972 text from the build log. This generic approach works for all build
3973 tools, but does not give details about the command invocation that pro‐
3974 duced a given problem. One may get more detailed reports by setting
3975 the CTEST_USE_LAUNCHERS variable:
3976 set(CTEST_USE_LAUNCHERS 1)
3978 in the CTestConfig.cmake file.
3980 CTestCoverageCollectGCOV
3982 New in version 3.2.
3983 This module provides the ctest_coverage_collect_gcov function.
3986 This function runs gcov on all .gcda files found in the binary tree and
3988 packages the resulting .gcov files into a tar file. This tarball also
3989 contains the following:
3990 • data.json defines the source and build directories for use by CDash.
3992 • Labels.json indicates any LABELS that have been set on the source
3994 files.
3995 • The uncovered directory holds any uncovered files found by
3997 CTEST_EXTRA_COVERAGE_GLOB.
3998 After generating this tar file, it can be sent to CDash for display
4000 with the ctest_submit(CDASH_UPLOAD) command.
4001 ctest_coverage_collect_gcov
4003 ctest_coverage_collect_gcov(TARBALL <tarfile>
4005 [SOURCE <source_dir>][BUILD <build_dir>]
4006 [GCOV_COMMAND <gcov_command>]
4007 [GCOV_OPTIONS <options>...]
4008 )
4009 Run gcov and package a tar file for CDash. The options are:
4011 TARBALL <tarfile>
4013 Specify the location of the .tar file to be created for
4014 later upload to CDash. Relative paths will be inter‐
4015 preted with respect to the top-level build directory.
4016 TARBALL_COMPRESSION <option>
4018 New in version 3.18.
4019 Specify a compression algorithm for the TARBALL data
4022 file. Using this option reduces the size of the data
4023 file before it is submitted to CDash. <option> must be
4024 one of GZIP, BZIP2, XZ, ZSTD, FROM_EXT, or an expression
4025 that CMake evaluates as FALSE. The default value is
4026 BZIP2.
4027 If FROM_EXT is specified, the resulting file will be com‐
4029 pressed based on the file extension of the <tarfile>
4030 (i.e. .tar.gz will use GZIP compression). File extensions
4031 that will produce compressed output include .tar.gz,
4032 .tgz, .tar.bzip2, .tbz, .tar.xz, and .txz.
4033 SOURCE <source_dir>
4035 Specify the top-level source directory for the build.
4036 Default is the value of CTEST_SOURCE_DIRECTORY.
4037 BUILD <build_dir>
4039 Specify the top-level build directory for the build. De‐
4040 fault is the value of CTEST_BINARY_DIRECTORY.
4041 GCOV_COMMAND <gcov_command>
4043 Specify the full path to the gcov command on the machine.
4044 Default is the value of CTEST_COVERAGE_COMMAND.
4045 GCOV_OPTIONS <options>...
4047 Specify options to be passed to gcov. The gcov command
4048 is run as gcov <options>... -o <gcov-dir> <file>.gcda.
4049 If not specified, the default option is just -b -x.
4050 GLOB New in version 3.6.
4052 Recursively search for .gcda files in build_dir rather
4055 than determining search locations by reading TargetDirec‐
4056 tories.txt.
4057 DELETE New in version 3.6.
4059 Delete coverage files after they've been packaged into
4062 the .tar.
4063 QUIET Suppress non-error messages that otherwise would have
4065 been printed out by this function.
4066 New in version 3.3: Added support for the
4068 CTEST_CUSTOM_COVERAGE_EXCLUDE variable.
4069 CTestScriptMode
4072 This file is read by ctest in script mode (-S)
4073 CTestUseLaunchers
4075 Set the RULE_LAUNCH_* global properties when CTEST_USE_LAUNCHERS is on.
4076 CTestUseLaunchers is automatically included when you include(CTest).
4078 However, it is split out into its own module file so projects can use
4079 the CTEST_USE_LAUNCHERS functionality independently.
4080 To use launchers, set CTEST_USE_LAUNCHERS to ON in a ctest -S dashboard
4082 script, and then also set it in the cache of the configured project.
4083 Both cmake and ctest need to know the value of it for the launchers to
4084 work properly. CMake needs to know in order to generate proper build
4085 rules, and ctest, in order to produce the proper error and warning
4086 analysis.
4087 For convenience, you may set the ENV variable CTEST_USE_LAUNCHERS_DE‐
4089 FAULT in your ctest -S script, too. Then, as long as your CMakeLists
4090 uses include(CTest) or include(CTestUseLaunchers), it will use the
4091 value of the ENV variable to initialize a CTEST_USE_LAUNCHERS cache
4092 variable. This cache variable initialization only occurs if
4093 CTEST_USE_LAUNCHERS is not already defined.
4094 New in version 3.8: If CTEST_USE_LAUNCHERS is on in a ctest -S script
4096 the ctest_configure command will add -DCTEST_USE_LAUNCHERS:BOOL=TRUE to
4097 the cmake command used to configure the project.
4098 Dart
4101 Configure a project for testing with CTest or old Dart Tcl Client
4102 This file is the backwards-compatibility version of the CTest module.
4104 It supports using the old Dart 1 Tcl client for driving dashboard sub‐
4105 missions as well as testing with CTest. This module should be included
4106 in the CMakeLists.txt file at the top of a project. Typical usage:
4107 include(Dart)
4109 if(BUILD_TESTING)
4110 # ... testing related CMake code ...
4111 endif()
4112 The BUILD_TESTING option is created by the Dart module to determine
4114 whether testing support should be enabled. The default is ON.
4115 DeployQt4
4117 Functions to help assemble a standalone Qt4 executable.
4118 A collection of CMake utility functions useful for deploying Qt4 exe‐
4120 cutables.
4121 The following functions are provided by this module:
4123 write_qt4_conf
4125 resolve_qt4_paths
4126 fixup_qt4_executable
4127 install_qt4_plugin_path
4128 install_qt4_plugin
4129 install_qt4_executable
4130 Requires CMake 2.6 or greater because it uses function and PAR‐
4132 ENT_SCOPE. Also depends on BundleUtilities.cmake.
4133 write_qt4_conf(<qt_conf_dir> <qt_conf_contents>)
4135 Writes a qt.conf file with the <qt_conf_contents> into <qt_conf_dir>.
4137 resolve_qt4_paths(<paths_var> [<executable_path>])
4139 Loop through <paths_var> list and if any don't exist resolve them rela‐
4141 tive to the <executable_path> (if supplied) or the CMAKE_INSTALL_PRE‐
4142 FIX.
4143 fixup_qt4_executable(<executable>
4145 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>])
4146 Copies Qt plugins, writes a Qt configuration file (if needed) and fixes
4148 up a Qt4 executable using BundleUtilities so it is standalone and can
4149 be drag-and-drop copied to another machine as long as all of the system
4150 libraries are compatible.
4151 <executable> should point to the executable to be fixed-up.
4153 <qtplugins> should contain a list of the names or paths of any Qt plug‐
4155 ins to be installed.
4156 <libs> will be passed to BundleUtilities and should be a list of any
4158 already installed plugins, libraries or executables to also be
4159 fixed-up.
4160 <dirs> will be passed to BundleUtilities and should contain and direc‐
4162 tories to be searched to find library dependencies.
4163 <plugins_dir> allows an custom plugins directory to be used.
4165 <request_qt_conf> will force a qt.conf file to be written even if not
4167 needed.
4168 install_qt4_plugin_path(plugin executable copy installed_plugin_path_var
4170 <plugins_dir> <component> <configurations>)
4171 Install (or copy) a resolved <plugin> to the default plugins directory
4173 (or <plugins_dir>) relative to <executable> and store the result in
4174 <installed_plugin_path_var>.
4175 If <copy> is set to TRUE then the plugins will be copied rather than
4177 installed. This is to allow this module to be used at CMake time
4178 rather than install time.
4179 If <component> is set then anything installed will use this COMPONENT.
4181 install_qt4_plugin(plugin executable copy installed_plugin_path_var
4183 <plugins_dir> <component>)
4184 Install (or copy) an unresolved <plugin> to the default plugins direc‐
4186 tory (or <plugins_dir>) relative to <executable> and store the result
4187 in <installed_plugin_path_var>. See documentation of IN‐
4188 STALL_QT4_PLUGIN_PATH.
4189 install_qt4_executable(<executable>
4191 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>])
4192 Installs Qt plugins, writes a Qt configuration file (if needed) and
4194 fixes up a Qt4 executable using BundleUtilities so it is standalone and
4195 can be drag-and-drop copied to another machine as long as all of the
4196 system libraries are compatible. The executable will be fixed-up at
4197 install time. <component> is the COMPONENT used for bundle fixup and
4198 plugin installation. See documentation of FIXUP_QT4_BUNDLE.
4199 ExternalData
4201 Manage data files stored outside source tree
4202 Introduction
4204 Use this module to unambiguously reference data files stored outside
4205 the source tree and fetch them at build time from arbitrary local and
4206 remote content-addressed locations. Functions provided by this module
4207 recognize arguments with the syntax DATA{<name>} as references to ex‐
4208 ternal data, replace them with full paths to local copies of those
4209 data, and create build rules to fetch and update the local copies.
4210 For example:
4212 include(ExternalData)
4214 set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
4215 "file:////host/share/%(algo)/%(hash)"
4216 "http://data.org/%(algo)/%(hash)")
4217 ExternalData_Add_Test(MyData
4218 NAME MyTest
4219 COMMAND MyExe DATA{MyInput.png}
4220 )
4221 ExternalData_Add_Target(MyData)
4222 When test MyTest runs the DATA{MyInput.png} argument will be replaced
4224 by the full path to a real instance of the data file MyInput.png on
4225 disk. If the source tree contains a content link such as MyIn‐
4226 put.png.md5 then the MyData target creates a real MyInput.png in the
4227 build tree.
4228 Module Functions
4230 ExternalData_Expand_Arguments
4231 The ExternalData_Expand_Arguments function evaluates DATA{} ref‐
4232 erences in its arguments and constructs a new list of arguments:
4233 ExternalData_Expand_Arguments(
4235 <target> # Name of data management target
4236 <outVar> # Output variable
4237 [args...] # Input arguments, DATA{} allowed
4238 )
4239 It replaces each DATA{} reference in an argument with the full
4241 path of a real data file on disk that will exist after the <tar‐
4242 get> builds.
4243 ExternalData_Add_Test
4245 The ExternalData_Add_Test function wraps around the CMake
4246 add_test() command but supports DATA{} references in its argu‐
4247 ments:
4248 ExternalData_Add_Test(
4250 <target> # Name of data management target
4251 ... # Arguments of add_test(), DATA{} allowed
4252 )
4253 It passes its arguments through ExternalData_Expand_Arguments
4255 and then invokes the add_test() command using the results.
4256 ExternalData_Add_Target
4258 The ExternalData_Add_Target function creates a custom target to
4259 manage local instances of data files stored externally:
4260 ExternalData_Add_Target(
4262 <target> # Name of data management target
4263 [SHOW_PROGRESS <ON|OFF>] # Show progress during the download
4264 )
4265 It creates custom commands in the target as necessary to make
4267 data files available for each DATA{} reference previously evalu‐
4268 ated by other functions provided by this module. Data files may
4269 be fetched from one of the URL templates specified in the Exter‐
4270 nalData_URL_TEMPLATES variable, or may be found locally in one
4271 of the paths specified in the ExternalData_OBJECT_STORES vari‐
4272 able.
4273 New in version 3.20: The SHOW_PROGRESS argument may be passed to
4275 suppress progress information during the download of objects. If
4276 not provided, it defaults to OFF for Ninja and Ninja Multi-Con‐
4277 fig generators and ON otherwise.
4278 Typically only one target is needed to manage all external data
4281 within a project. Call this function once at the end of config‐
4282 uration after all data references have been processed.
4283 Module Variables
4285 The following variables configure behavior. They should be set before
4286 calling any of the functions provided by this module.
4287 ExternalData_BINARY_ROOT
4289 The ExternalData_BINARY_ROOT variable may be set to the direc‐
4290 tory to hold the real data files named by expanded DATA{} refer‐
4291 ences. The default is CMAKE_BINARY_DIR. The directory layout
4292 will mirror that of content links under External‐
4293 Data_SOURCE_ROOT.
4294 ExternalData_CUSTOM_SCRIPT_<key>
4296 New in version 3.2.
4297 Specify a full path to a .cmake custom fetch script identified
4300 by <key> in entries of the ExternalData_URL_TEMPLATES list. See
4301 Custom Fetch Scripts.
4302 ExternalData_LINK_CONTENT
4304 The ExternalData_LINK_CONTENT variable may be set to the name of
4305 a supported hash algorithm to enable automatic conversion of
4306 real data files referenced by the DATA{} syntax into content
4307 links. For each such <file> a content link named <file><ext> is
4308 created. The original file is renamed to the form .External‐
4309 Data_<algo>_<hash> to stage it for future transmission to one of
4310 the locations in the list of URL templates (by means outside the
4311 scope of this module). The data fetch rule created for the con‐
4312 tent link will use the staged object if it cannot be found using
4313 any URL template.
4314 ExternalData_NO_SYMLINKS
4316 New in version 3.3.
4317 The real data files named by expanded DATA{} references may be
4320 made available under ExternalData_BINARY_ROOT using symbolic
4321 links on some platforms. The ExternalData_NO_SYMLINKS variable
4322 may be set to disable use of symbolic links and enable use of
4323 copies instead.
4324 ExternalData_OBJECT_STORES
4326 The ExternalData_OBJECT_STORES variable may be set to a list of
4327 local directories that store objects using the layout
4328 <dir>/%(algo)/%(hash). These directories will be searched first
4329 for a needed object. If the object is not available in any
4330 store then it will be fetched remotely using the URL templates
4331 and added to the first local store listed. If no stores are
4332 specified the default is a location inside the build tree.
4333 ExternalData_SERIES_PARSE
4335 ExternalData_SERIES_PARSE_PREFIX
4337 ExternalData_SERIES_PARSE_NUMBER
4339 ExternalData_SERIES_PARSE_SUFFIX
4341 ExternalData_SERIES_MATCH
4343 See Referencing File Series.
4344 ExternalData_SOURCE_ROOT
4346 The ExternalData_SOURCE_ROOT variable may be set to the highest
4347 source directory containing any path named by a DATA{} refer‐
4348 ence. The default is CMAKE_SOURCE_DIR. External‐
4349 Data_SOURCE_ROOT and CMAKE_SOURCE_DIR must refer to directories
4350 within a single source distribution (e.g. they come together in
4351 one tarball).
4352 ExternalData_TIMEOUT_ABSOLUTE
4354 The ExternalData_TIMEOUT_ABSOLUTE variable sets the download ab‐
4355 solute timeout, in seconds, with a default of 300 seconds. Set
4356 to 0 to disable enforcement.
4357 ExternalData_TIMEOUT_INACTIVITY
4359 The ExternalData_TIMEOUT_INACTIVITY variable sets the download
4360 inactivity timeout, in seconds, with a default of 60 seconds.
4361 Set to 0 to disable enforcement.
4362 ExternalData_URL_ALGO_<algo>_<key>
4364 New in version 3.3.
4365 Specify a custom URL component to be substituted for URL tem‐
4368 plate placeholders of the form %(algo:<key>), where <key> is a
4369 valid C identifier, when fetching an object referenced via hash
4370 algorithm <algo>. If not defined, the default URL component is
4371 just <algo> for any <key>.
4372 ExternalData_URL_TEMPLATES
4374 The ExternalData_URL_TEMPLATES may be set to provide a list of
4375 URL templates using the placeholders %(algo) and %(hash) in each
4376 template. Data fetch rules try each URL template in order by
4377 substituting the hash algorithm name for %(algo) and the hash
4378 value for %(hash). Alternatively one may use %(algo:<key>) with
4379 ExternalData_URL_ALGO_<algo>_<key> variables to gain more flexi‐
4380 bility in remote URLs.
4381 Referencing Files
4383 Referencing Single Files
4384 The DATA{} syntax is literal and the <name> is a full or relative path
4385 within the source tree. The source tree must contain either a real
4386 data file at <name> or a "content link" at <name><ext> containing a
4387 hash of the real file using a hash algorithm corresponding to <ext>.
4388 For example, the argument DATA{img.png} may be satisfied by either a
4389 real img.png file in the current source directory or a img.png.md5 file
4390 containing its MD5 sum.
4391 New in version 3.8: Multiple content links of the same name with dif‐
4393 ferent hash algorithms are supported (e.g. img.png.sha256 and
4394 img.png.sha1) so long as they all correspond to the same real file.
4395 This allows objects to be fetched from sources indexed by different
4396 hash algorithms.
4397 Referencing File Series
4400 The DATA{} syntax can be told to fetch a file series using the form
4401 DATA{<name>,:}, where the : is literal. If the source tree contains a
4402 group of files or content links named like a series then a reference to
4403 one member adds rules to fetch all of them. Although all members of a
4404 series are fetched, only the file originally named by the DATA{} argu‐
4405 ment is substituted for it. The default configuration recognizes file
4406 series names ending with #.ext, _#.ext, .#.ext, or -#.ext where # is a
4407 sequence of decimal digits and .ext is any single extension. Configure
4408 it with a regex that parses <number> and <suffix> parts from the end of
4409 <name>:
4410 ExternalData_SERIES_PARSE = regex of the form (<number>)(<suffix>)$
4412 For more complicated cases set:
4414 ExternalData_SERIES_PARSE = regex with at least two () groups
4416 ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
4417 ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
4418 ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number
4419 Configure series number matching with a regex that matches the <number>
4421 part of series members named <prefix><number><suffix>:
4422 ExternalData_SERIES_MATCH = regex matching <number> in all series members
4424 Note that the <suffix> of a series does not include a hash-algorithm
4426 extension.
4427 Referencing Associated Files
4429 The DATA{} syntax can alternatively match files associated with the
4430 named file and contained in the same directory. Associated files may
4431 be specified by options using the syntax
4432 DATA{<name>,<opt1>,<opt2>,...}. Each option may specify one file by
4433 name or specify a regular expression to match file names using the syn‐
4434 tax REGEX:<regex>. For example, the arguments:
4435 DATA{MyData/MyInput.mhd,MyInput.img} # File pair
4437 DATA{MyData/MyFrames00.png,REGEX:MyFrames[0-9]+\\.png} # Series
4438 will pass MyInput.mha and MyFrames00.png on the command line but ensure
4440 that the associated files are present next to them.
4441 Referencing Directories
4443 The DATA{} syntax may reference a directory using a trailing slash and
4444 a list of associated files. The form DATA{<name>/,<opt1>,<opt2>,...}
4445 adds rules to fetch any files in the directory that match one of the
4446 associated file options. For example, the argument DATA{My‐
4447 DataDir/,REGEX:.*} will pass the full path to a MyDataDir directory on
4448 the command line and ensure that the directory contains files corre‐
4449 sponding to every file or content link in the MyDataDir source direc‐
4450 tory.
4451 New in version 3.3: In order to match associated files in subdirecto‐
4453 ries, specify a RECURSE: option, e.g. DATA{MyDataDir/,RE‐
4454 CURSE:,REGEX:.*}.
4455 Hash Algorithms
4458 The following hash algorithms are supported:
4459 %(algo) <ext> Description
4461 ------- ----- -----------
4462 MD5 .md5 Message-Digest Algorithm 5, RFC 1321
4463 SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174
4464 SHA224 .sha224 US Secure Hash Algorithms, RFC 4634
4465 SHA256 .sha256 US Secure Hash Algorithms, RFC 4634
4466 SHA384 .sha384 US Secure Hash Algorithms, RFC 4634
4467 SHA512 .sha512 US Secure Hash Algorithms, RFC 4634
4468 SHA3_224 .sha3-224 Keccak SHA-3
4469 SHA3_256 .sha3-256 Keccak SHA-3
4470 SHA3_384 .sha3-384 Keccak SHA-3
4471 SHA3_512 .sha3-512 Keccak SHA-3
4472 New in version 3.8: Added the SHA3_* hash algorithms.
4474 Note that the hashes are used only for unique data identification and
4477 download verification.
4478 Custom Fetch Scripts
4480 New in version 3.2.
4481 When a data file must be fetched from one of the URL templates speci‐
4484 fied in the ExternalData_URL_TEMPLATES variable, it is normally down‐
4485 loaded using the file(DOWNLOAD) command. One may specify usage of a
4486 custom fetch script by using a URL template of the form ExternalData‐
4487 CustomScript://<key>/<loc>. The <key> must be a C identifier, and the
4488 <loc> must contain the %(algo) and %(hash) placeholders. A variable
4489 corresponding to the key, ExternalData_CUSTOM_SCRIPT_<key>, must be set
4490 to the full path to a .cmake script file. The script will be included
4491 to perform the actual fetch, and provided with the following variables:
4492 ExternalData_CUSTOM_LOCATION
4494 When a custom fetch script is loaded, this variable is set to
4495 the location part of the URL, which will contain the substituted
4496 hash algorithm name and content hash value.
4497 ExternalData_CUSTOM_FILE
4499 When a custom fetch script is loaded, this variable is set to
4500 the full path to a file in which the script must store the
4501 fetched content. The name of the file is unspecified and should
4502 not be interpreted in any way.
4503 The custom fetch script is expected to store fetched content in the
4505 file or set a variable:
4506 ExternalData_CUSTOM_ERROR
4508 When a custom fetch script fails to fetch the requested content,
4509 it must set this variable to a short one-line message describing
4510 the reason for failure.
4511 ExternalProject
4513 Commands
4514 External Project Definition
4515 ExternalProject_Add
4516 The ExternalProject_Add() function creates a custom target to
4517 drive download, update/patch, configure, build, install and test
4518 steps of an external project:
4519 ExternalProject_Add(<name> [<option>...])
4521 The individual steps within the process can be driven indepen‐
4523 dently if required (e.g. for CDash submission) and extra custom
4524 steps can be defined, along with the ability to control the step
4525 dependencies. The directory structure used for the management of
4526 the external project can also be customized. The function sup‐
4527 ports a large number of options which can be used to tailor the
4528 external project behavior.
4529 Directory Options:
4531 Most of the time, the default directory layout is suffi‐
4532 cient. It is largely an implementation detail that the
4533 main project usually doesn't need to change. In some cir‐
4534 cumstances, however, control over the directory layout
4535 can be useful or necessary. The directory options are po‐
4536 tentially more useful from the point of view that the
4537 main build can use the ExternalProject_Get_Property()
4538 command to retrieve their values, thereby allowing the
4539 main project to refer to build artifacts of the external
4540 project.
4541 PREFIX <dir>
4543 Root directory for the external project. Unless
4544 otherwise noted below, all other directories asso‐
4545 ciated with the external project will be created
4546 under here.
4547 TMP_DIR <dir>
4549 Directory in which to store temporary files.
4550 STAMP_DIR <dir>
4552 Directory in which to store the timestamps of each
4553 step. Log files from individual steps are also
4554 created in here unless overridden by LOG_DIR (see
4555 Logging Options below).
4556 LOG_DIR <dir>
4558 New in version 3.14.
4559 Directory in which to store the logs of each step.
4562 DOWNLOAD_DIR <dir>
4564 Directory in which to store downloaded files be‐
4565 fore unpacking them. This directory is only used
4566 by the URL download method, all other download
4567 methods use SOURCE_DIR directly instead.
4568 SOURCE_DIR <dir>
4570 Source directory into which downloaded contents
4571 will be unpacked, or for non-URL download methods,
4572 the directory in which the repository should be
4573 checked out, cloned, etc. If no download method is
4574 specified, this must point to an existing direc‐
4575 tory where the external project has already been
4576 unpacked or cloned/checked out.
4577 NOTE:
4579 If a download method is specified, any existing
4580 contents of the source directory may be
4581 deleted. Only the URL download method checks
4582 whether this directory is either missing or
4583 empty before initiating the download, stopping
4584 with an error if it is not empty. All other
4585 download methods silently discard any previous
4586 contents of the source directory.
4587 BINARY_DIR <dir>
4589 Specify the build directory location. This option
4590 is ignored if BUILD_IN_SOURCE is enabled.
4591 INSTALL_DIR <dir>
4593 Installation prefix to be placed in the <IN‐
4594 STALL_DIR> placeholder. This does not actually
4595 configure the external project to install to the
4596 given prefix. That must be done by passing appro‐
4597 priate arguments to the external project configu‐
4598 ration step, e.g. using <INSTALL_DIR>.
4599 If any of the above ..._DIR options are not specified,
4601 their defaults are computed as follows. If the PREFIX op‐
4602 tion is given or the EP_PREFIX directory property is set,
4603 then an external project is built and installed under the
4604 specified prefix:
4605 TMP_DIR = <prefix>/tmp
4607 STAMP_DIR = <prefix>/src/<name>-stamp
4608 DOWNLOAD_DIR = <prefix>/src
4609 SOURCE_DIR = <prefix>/src/<name>
4610 BINARY_DIR = <prefix>/src/<name>-build
4611 INSTALL_DIR = <prefix>
4612 LOG_DIR = <STAMP_DIR>
4613 Otherwise, if the EP_BASE directory property is set then
4615 components of an external project are stored under the
4616 specified base:
4617 TMP_DIR = <base>/tmp/<name>
4619 STAMP_DIR = <base>/Stamp/<name>
4620 DOWNLOAD_DIR = <base>/Download/<name>
4621 SOURCE_DIR = <base>/Source/<name>
4622 BINARY_DIR = <base>/Build/<name>
4623 INSTALL_DIR = <base>/Install/<name>
4624 LOG_DIR = <STAMP_DIR>
4625 If no PREFIX, EP_PREFIX, or EP_BASE is specified, then
4627 the default is to set PREFIX to <name>-prefix. Relative
4628 paths are interpreted with respect to
4629 CMAKE_CURRENT_BINARY_DIR at the point where ExternalPro‐
4630 ject_Add() is called.
4631 Download Step Options:
4633 A download method can be omitted if the SOURCE_DIR option
4634 is used to point to an existing non-empty directory. Oth‐
4635 erwise, one of the download methods below must be speci‐
4636 fied (multiple download methods should not be given) or a
4637 custom DOWNLOAD_COMMAND provided.
4638 DOWNLOAD_COMMAND <cmd>...
4640 Overrides the command used for the download step
4641 (generator expressions are supported). If this op‐
4642 tion is specified, all other download options will
4643 be ignored. Providing an empty string for <cmd>
4644 effectively disables the download step.
4645 URL Download
4647 URL <url1> [<url2>...]
4649 List of paths and/or URL(s) of the external
4650 project's source. When more than one URL is
4651 given, they are tried in turn until one
4652 succeeds. A URL may be an ordinary path in
4653 the local file system (in which case it
4654 must be the only URL provided) or any down‐
4655 loadable URL supported by the
4656 file(DOWNLOAD) command. A local filesystem
4657 path may refer to either an existing direc‐
4658 tory or to an archive file, whereas a URL
4659 is expected to point to a file which can be
4660 treated as an archive. When an archive is
4661 used, it will be unpacked automatically un‐
4662 less the DOWNLOAD_NO_EXTRACT option is set
4663 to prevent it. The archive type is deter‐
4664 mined by inspecting the actual content
4665 rather than using logic based on the file
4666 extension.
4667 Changed in version 3.7: Multiple URLs are
4669 allowed.
4670 URL_HASH <algo>=<hashValue>
4673 Hash of the archive file to be downloaded.
4674 The argument should be of the form
4675 <algo>=<hashValue> where algo can be any of
4676 the hashing algorithms supported by the
4677 file() command. Specifying this option is
4678 strongly recommended for URL downloads, as
4679 it ensures the integrity of the downloaded
4680 content. It is also used as a check for a
4681 previously downloaded file, allowing con‐
4682 nection to the remote location to be
4683 avoided altogether if the local directory
4684 already has a file from an earlier download
4685 that matches the specified hash.
4686 URL_MD5 <md5>
4688 Equivalent to URL_HASH MD5=<md5>.
4689 DOWNLOAD_NAME <fname>
4691 File name to use for the downloaded file.
4692 If not given, the end of the URL is used to
4693 determine the file name. This option is
4694 rarely needed, the default name is gener‐
4695 ally suitable and is not normally used out‐
4696 side of code internal to the ExternalPro‐
4697 ject module.
4698 DOWNLOAD_EXTRACT_TIMESTAMP <bool>
4700 New in version 3.24.
4701 When specified with a true value, the time‐
4704 stamps of the extracted files will match
4705 those in the archive. When false, the time‐
4706 stamps of the extracted files will reflect
4707 the time at which the extraction was per‐
4708 formed. If the download URL changes, time‐
4709 stamps based off those in the archive can
4710 result in dependent targets not being re‐
4711 built when they potentially should have
4712 been. Therefore, unless the file timestamps
4713 are significant to the project in some way,
4714 use a false value for this option. If DOWN‐
4715 LOAD_EXTRACT_TIMESTAMP is not given, the
4716 default is false. See policy CMP0135.
4717 DOWNLOAD_NO_EXTRACT <bool>
4719 New in version 3.6.
4720 Allows the extraction part of the download
4723 step to be disabled by passing a boolean
4724 true value for this option. If this option
4725 is not given, the downloaded contents will
4726 be unpacked automatically if required. If
4727 extraction has been disabled, the full path
4728 to the downloaded file is available as
4729 <DOWNLOADED_FILE> in subsequent steps or as
4730 the property DOWNLOADED_FILE with the
4731 ExternalProject_Get_Property() command.
4732 DOWNLOAD_NO_PROGRESS <bool>
4734 Can be used to disable logging the download
4735 progress. If this option is not given,
4736 download progress messages will be logged.
4737 TIMEOUT <seconds>
4739 Maximum time allowed for file download op‐
4740 erations.
4741 INACTIVITY_TIMEOUT <seconds>
4743 New in version 3.19.
4744 Terminate the operation after a period of
4747 inactivity.
4748 HTTP_USERNAME <username>
4750 New in version 3.7.
4751 Username for the download operation if au‐
4754 thentication is required.
4755 HTTP_PASSWORD <password>
4757 New in version 3.7.
4758 Password for the download operation if au‐
4761 thentication is required.
4762 HTTP_HEADER <header1> [<header2>...]
4764 New in version 3.7.
4765 Provides an arbitrary list of HTTP headers
4768 for the download operation. This can be
4769 useful for accessing content in systems
4770 like AWS, etc.
4771 TLS_VERIFY <bool>
4773 Specifies whether certificate verification
4774 should be performed for https URLs. If this
4775 option is not provided, the default behav‐
4776 ior is determined by the CMAKE_TLS_VERIFY
4777 variable (see file(DOWNLOAD)). If that is
4778 also not set, certificate verification will
4779 not be performed. In situations where
4780 URL_HASH cannot be provided, this option
4781 can be an alternative verification measure.
4782 Changed in version 3.6: This option also
4784 applies to git clone invocations.
4785 TLS_CAINFO <file>
4788 Specify a custom certificate authority file
4789 to use if TLS_VERIFY is enabled. If this
4790 option is not specified, the value of the
4791 CMAKE_TLS_CAINFO variable will be used in‐
4792 stead (see file(DOWNLOAD))
4793 NETRC <level>
4795 New in version 3.11.
4796 Specify whether the .netrc file is to be
4799 used for operation. If this option is not
4800 specified, the value of the CMAKE_NETRC
4801 variable will be used instead (see
4802 file(DOWNLOAD)). Valid levels are:
4803 IGNORED
4805 The .netrc file is ignored. This is
4806 the default.
4807 OPTIONAL
4809 The .netrc file is optional, and in‐
4810 formation in the URL is preferred.
4811 The file will be scanned to find
4812 which ever information is not speci‐
4813 fied in the URL.
4814 REQUIRED
4816 The .netrc file is required, and in‐
4817 formation in the URL is ignored.
4818 NETRC_FILE <file>
4820 New in version 3.11.
4821 Specify an alternative .netrc file to the
4824 one in your home directory if the NETRC
4825 level is OPTIONAL or REQUIRED. If this op‐
4826 tion is not specified, the value of the
4827 CMAKE_NETRC_FILE variable will be used in‐
4828 stead (see file(DOWNLOAD))
4829 New in version 3.1: Added support for tbz2,
4831 .tar.xz, .txz, and .7z extensions.
4832 Git NOTE: A git version of 1.6.5 or later is required
4835 if this download method is used.
4836 GIT_REPOSITORY <url>
4838 URL of the git repository. Any URL under‐
4839 stood by the git command may be used.
4840 GIT_TAG <tag>
4842 Git branch name, tag or commit hash. Note
4843 that branch names and tags should generally
4844 be specified as remote names (i.e. ori‐
4845 gin/myBranch rather than simply myBranch).
4846 This ensures that if the remote end has its
4847 tag moved or branch rebased or history
4848 rewritten, the local clone will still be
4849 updated correctly. In general, however,
4850 specifying a commit hash should be pre‐
4851 ferred for a number of reasons:
4852 • If the local clone already has the commit
4854 corresponding to the hash, no git fetch
4855 needs to be performed to check for
4856 changes each time CMake is re-run. This
4857 can result in a significant speed up if
4858 many external projects are being used.
4859 • Using a specific git hash ensures that
4861 the main project's own history is fully
4862 traceable to a specific point in the ex‐
4863 ternal project's evolution. If a branch
4864 or tag name is used instead, then check‐
4865 ing out a specific commit of the main
4866 project doesn't necessarily pin the whole
4867 build to a specific point in the life of
4868 the external project. The lack of such
4869 deterministic behavior makes the main
4870 project lose traceability and repeatabil‐
4871 ity.
4872 If GIT_SHALLOW is enabled then GIT_TAG
4874 works only with branch names and tags. A
4875 commit hash is not allowed.
4876 Note that if not provided, GIT_TAG defaults
4878 to master, not the default Git branch name.
4879 GIT_REMOTE_NAME <name>
4881 The optional name of the remote. If this
4882 option is not specified, it defaults to
4883 origin.
4884 GIT_SUBMODULES <module>...
4886 Specific git submodules that should also be
4887 updated. If this option is not provided,
4888 all git submodules will be updated.
4889 Changed in version 3.16: When CMP0097 is
4891 set to NEW, if this value is set to an
4892 empty string then no submodules are ini‐
4893 tialized or updated.
4894 GIT_SUBMODULES_RECURSE <bool>
4897 New in version 3.17.
4898 Specify whether git submodules (if any)
4901 should update recursively by passing the
4902 --recursive flag to git submodule update.
4903 If not specified, the default is on.
4904 GIT_SHALLOW <bool>
4906 New in version 3.6.
4907 When this option is enabled, the git clone
4910 operation will be given the --depth 1 op‐
4911 tion. This performs a shallow clone, which
4912 avoids downloading the whole history and
4913 instead retrieves just the commit denoted
4914 by the GIT_TAG option.
4915 GIT_PROGRESS <bool>
4917 New in version 3.8.
4918 When enabled, this option instructs the git
4921 clone operation to report its progress by
4922 passing it the --progress option. Without
4923 this option, the clone step for large
4924 projects may appear to make the build
4925 stall, since nothing will be logged until
4926 the clone operation finishes. While this
4927 option can be used to provide progress to
4928 prevent the appearance of the build having
4929 stalled, it may also make the build overly
4930 noisy if lots of external projects are
4931 used.
4932 GIT_CONFIG <option1> [<option2>...]
4934 New in version 3.8.
4935 Specify a list of config options to pass to
4938 git clone. Each option listed will be
4939 transformed into its own --config <option>
4940 on the git clone command line, with each
4941 option required to be in the form
4942 key=value.
4943 GIT_REMOTE_UPDATE_STRATEGY <strategy>
4945 New in version 3.18.
4946 When GIT_TAG refers to a remote branch,
4949 this option can be used to specify how the
4950 update step behaves. The <strategy> must
4951 be one of the following:
4952 CHECKOUT
4954 Ignore the local branch and always
4955 checkout the branch specified by
4956 GIT_TAG.
4957 REBASE Try to rebase the current branch to
4959 the one specified by GIT_TAG. If
4960 there are local uncommitted changes,
4961 they will be stashed first and
4962 popped again after rebasing. If re‐
4963 basing or popping stashed changes
4964 fail, abort the rebase and halt with
4965 an error. When GIT_REMOTE_UP‐
4966 DATE_STRATEGY is not present, this
4967 is the default strategy unless the
4968 default has been overridden with
4969 CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY
4970 (see below). Note that if the
4971 branch specified in GIT_TAG is dif‐
4972 ferent to the upstream branch cur‐
4973 rently being tracked, it is not safe
4974 to perform a rebase. In that situa‐
4975 tion, REBASE will silently be
4976 treated as CHECKOUT instead.
4977 REBASE_CHECKOUT
4979 Same as REBASE except if the rebase
4980 fails, an annotated tag will be cre‐
4981 ated at the original HEAD position
4982 from before the rebase and then
4983 checkout GIT_TAG just like the
4984 CHECKOUT strategy. The message
4985 stored on the annotated tag will
4986 give information about what was at‐
4987 tempted and the tag name will in‐
4988 clude a timestamp so that each
4989 failed run will add a new tag. This
4990 strategy ensures no changes will be
4991 lost, but updates should always suc‐
4992 ceed if GIT_TAG refers to a valid
4993 ref unless there are uncommitted
4994 changes that cannot be popped suc‐
4995 cessfully.
4996 The variable CMAKE_EP_GIT_REMOTE_UP‐
4998 DATE_STRATEGY can be set to override the
4999 default strategy. This variable should not
5000 be set by a project, it is intended for the
5001 user to set. It is primarily intended for
5002 use in continuous integration scripts to
5003 ensure that when history is rewritten on a
5004 remote branch, the build doesn't end up
5005 with unintended changes or failed builds
5006 resulting from conflicts during rebase op‐
5007 erations.
5008 Subversion
5010 SVN_REPOSITORY <url>
5012 URL of the Subversion repository.
5013 SVN_REVISION -r<rev>
5015 Revision to checkout from the Subversion
5016 repository.
5017 SVN_USERNAME <username>
5019 Username for the Subversion checkout and
5020 update.
5021 SVN_PASSWORD <password>
5023 Password for the Subversion checkout and
5024 update.
5025 SVN_TRUST_CERT <bool>
5027 Specifies whether to trust the Subversion
5028 server site certificate. If enabled, the
5029 --trust-server-cert option is passed to the
5030 svn checkout and update commands.
5031 Mercurial
5033 HG_REPOSITORY <url>
5035 URL of the mercurial repository.
5036 HG_TAG <tag>
5038 Mercurial branch name, tag or commit id.
5039 CVS
5041 CVS_REPOSITORY <cvsroot>
5043 CVSROOT of the CVS repository.
5044 CVS_MODULE <mod>
5046 Module to checkout from the CVS repository.
5047 CVS_TAG <tag>
5049 Tag to checkout from the CVS repository.
5050 Update Step Options:
5052 Whenever CMake is re-run, by default the external
5053 project's sources will be updated if the download method
5054 supports updates (e.g. a git repository would be checked
5055 if the GIT_TAG does not refer to a specific commit).
5056 UPDATE_COMMAND <cmd>...
5058 Overrides the download method's update step with a
5059 custom command. The command may use generator ex‐
5060 pressions.
5061 UPDATE_DISCONNECTED <bool>
5063 New in version 3.2.
5064 When enabled, this option causes the update step
5067 to be skipped. It does not, however, prevent the
5068 download step. The update step can still be added
5069 as a step target (see
5070 ExternalProject_Add_StepTargets()) and called man‐
5071 ually. This is useful if you want to allow devel‐
5072 opers to build the project when disconnected from
5073 the network (the network may still be needed for
5074 the download step though).
5075 When this option is present, it is generally ad‐
5077 visable to make the value a cache variable under
5078 the developer's control rather than hard-coding
5079 it. If this option is not present, the default
5080 value is taken from the EP_UPDATE_DISCONNECTED di‐
5081 rectory property. If that is also not defined, up‐
5082 dates are performed as normal. The EP_UPDATE_DIS‐
5083 CONNECTED directory property is intended as a con‐
5084 venience for controlling the UPDATE_DISCONNECTED
5085 behavior for an entire section of a project's di‐
5086 rectory hierarchy and may be a more convenient
5087 method of giving developers control over whether
5088 or not to perform updates (assuming the project
5089 also provides a cache variable or some other con‐
5090 venient method for setting the directory prop‐
5091 erty).
5092 This may cause a step target to be created auto‐
5094 matically for the download step. See policy
5095 CMP0114.
5096 Patch Step Options:
5098 PATCH_COMMAND <cmd>...
5100 Specifies a custom command to patch the sources
5101 after an update. By default, no patch command is
5102 defined. Note that it can be quite difficult to
5103 define an appropriate patch command that performs
5104 robustly, especially for download methods such as
5105 git where changing the GIT_TAG will not discard
5106 changes from a previous patch, but the patch com‐
5107 mand will be called again after updating to the
5108 new tag.
5109 Configure Step Options:
5111 The configure step is run after the download and update
5112 steps. By default, the external project is assumed to be
5113 a CMake project, but this can be overridden if required.
5114 CONFIGURE_COMMAND <cmd>...
5116 The default configure command runs CMake with a
5117 few options based on the main project. The op‐
5118 tions added are typically only those needed to use
5119 the same generator as the main project, but the
5120 CMAKE_GENERATOR option can be given to override
5121 this. The project is responsible for adding any
5122 toolchain details, flags or other settings it
5123 wants to re-use from the main project or otherwise
5124 specify (see CMAKE_ARGS, CMAKE_CACHE_ARGS and
5125 CMAKE_CACHE_DEFAULT_ARGS below).
5126 For non-CMake external projects, the CONFIG‐
5128 URE_COMMAND option must be used to override the
5129 default configure command (generator expressions
5130 are supported). For projects that require no con‐
5131 figure step, specify this option with an empty
5132 string as the command to execute.
5133 CMAKE_COMMAND /.../cmake
5135 Specify an alternative cmake executable for the
5136 configure step (use an absolute path). This is
5137 generally not recommended, since it is usually de‐
5138 sirable to use the same CMake version throughout
5139 the whole build. This option is ignored if a cus‐
5140 tom configure command has been specified with CON‐
5141 FIGURE_COMMAND.
5142 CMAKE_GENERATOR <gen>
5144 Override the CMake generator used for the config‐
5145 ure step. Without this option, the same generator
5146 as the main build will be used. This option is ig‐
5147 nored if a custom configure command has been spec‐
5148 ified with the CONFIGURE_COMMAND option.
5149 CMAKE_GENERATOR_PLATFORM <platform>
5151 New in version 3.1.
5152 Pass a generator-specific platform name to the
5155 CMake command (see CMAKE_GENERATOR_PLATFORM). It
5156 is an error to provide this option without the
5157 CMAKE_GENERATOR option.
5158 CMAKE_GENERATOR_TOOLSET <toolset>
5160 Pass a generator-specific toolset name to the
5161 CMake command (see CMAKE_GENERATOR_TOOLSET). It is
5162 an error to provide this option without the
5163 CMAKE_GENERATOR option.
5164 CMAKE_GENERATOR_INSTANCE <instance>
5166 New in version 3.11.
5167 Pass a generator-specific instance selection to
5170 the CMake command (see CMAKE_GENERATOR_INSTANCE).
5171 It is an error to provide this option without the
5172 CMAKE_GENERATOR option.
5173 CMAKE_ARGS <arg>...
5175 The specified arguments are passed to the cmake
5176 command line. They can be any argument the cmake
5177 command understands, not just cache values defined
5178 by -D... arguments (see also CMake Options).
5179 New in version 3.3: Arguments may use generator
5181 expressions.
5182 CMAKE_CACHE_ARGS <arg>...
5185 This is an alternate way of specifying cache vari‐
5186 ables where command line length issues may become
5187 a problem. The arguments are expected to be in the
5188 form -Dvar:STRING=value, which are then trans‐
5189 formed into CMake set() commands with the FORCE
5190 option used. These set() commands are written to a
5191 pre-load script which is then applied using the
5192 cmake -C command line option.
5193 New in version 3.3: Arguments may use generator
5195 expressions.
5196 CMAKE_CACHE_DEFAULT_ARGS <arg>...
5199 New in version 3.2.
5200 This is the same as the CMAKE_CACHE_ARGS option
5203 except the set() commands do not include the FORCE
5204 keyword. This means the values act as initial de‐
5205 faults only and will not override any variables
5206 already set from a previous run. Use this option
5207 with care, as it can lead to different behavior
5208 depending on whether the build starts from a fresh
5209 build directory or re-uses previous build con‐
5210 tents.
5211 New in version 3.15: If the CMake generator is the
5213 Green Hills MULTI and not overridden, the original
5214 project's settings for the GHS toolset and target
5215 system customization cache variables are propa‐
5216 gated into the external project.
5217 SOURCE_SUBDIR <dir>
5220 New in version 3.7.
5221 When no CONFIGURE_COMMAND option is specified, the
5224 configure step assumes the external project has a
5225 CMakeLists.txt file at the top of its source tree
5226 (i.e. in SOURCE_DIR). The SOURCE_SUBDIR option can
5227 be used to point to an alternative directory
5228 within the source tree to use as the top of the
5229 CMake source tree instead. This must be a relative
5230 path and it will be interpreted as being relative
5231 to SOURCE_DIR.
5232 New in version 3.14: When BUILD_IN_SOURCE option
5234 is enabled, the BUILD_COMMAND is used to point to
5235 an alternative directory within the source tree.
5236 CONFIGURE_HANDLED_BY_BUILD <bool>
5239 New in version 3.20.
5240 Enabling this option relaxes the dependencies of
5243 the configure step on other external projects to
5244 order-only. This means the configure step will be
5245 executed after its external project dependencies
5246 are built but it will not be marked dirty when one
5247 of its external project dependencies is rebuilt.
5248 This option can be enabled when the build step is
5249 smart enough to figure out if the configure step
5250 needs to be rerun. CMake and Meson are examples of
5251 build systems whose build step is smart enough to
5252 know if the configure step needs to be rerun.
5253 Build Step Options:
5255 If the configure step assumed the external project uses
5256 CMake as its build system, the build step will also. Oth‐
5257 erwise, the build step will assume a Makefile-based build
5258 and simply run make with no arguments as the default
5259 build step. This can be overridden with custom build com‐
5260 mands if required.
5261 If both the main project and the external project use
5263 make as their build tool, the build step of the external
5264 project is invoked as a recursive make using $(MAKE).
5265 This will communicate some build tool settings from the
5266 main project to the external project. If either the main
5267 project or external project is not using make, no build
5268 tool settings will be passed to the external project
5269 other than those established by the configure step (i.e.
5270 running ninja -v in the main project will not pass -v to
5271 the external project's build step, even if it also uses
5272 ninja as its build tool).
5273 BUILD_COMMAND <cmd>...
5275 Overrides the default build command (generator ex‐
5276 pressions are supported). If this option is not
5277 given, the default build command will be chosen to
5278 integrate with the main build in the most appro‐
5279 priate way (e.g. using recursive make for Makefile
5280 generators or cmake --build if the project uses a
5281 CMake build). This option can be specified with an
5282 empty string as the command to make the build step
5283 do nothing.
5284 BUILD_IN_SOURCE <bool>
5286 When this option is enabled, the build will be
5287 done directly within the external project's source
5288 tree. This should generally be avoided, the use of
5289 a separate build directory is usually preferred,
5290 but it can be useful when the external project as‐
5291 sumes an in-source build. The BINARY_DIR option
5292 should not be specified if building in-source.
5293 BUILD_ALWAYS <bool>
5295 Enabling this option forces the build step to al‐
5296 ways be run. This can be the easiest way to ro‐
5297 bustly ensure that the external project's own
5298 build dependencies are evaluated rather than rely‐
5299 ing on the default success timestamp-based method.
5300 This option is not normally needed unless develop‐
5301 ers are expected to modify something the external
5302 project's build depends on in a way that is not
5303 detectable via the step target dependencies (e.g.
5304 SOURCE_DIR is used without a download method and
5305 developers might modify the sources in
5306 SOURCE_DIR).
5307 BUILD_BYPRODUCTS <file>...
5309 New in version 3.2.
5310 Specifies files that will be generated by the
5313 build command but which might or might not have
5314 their modification time updated by subsequent
5315 builds. These ultimately get passed through as
5316 BYPRODUCTS to the build step's own underlying call
5317 to add_custom_command().
5318 Install Step Options:
5320 If the configure step assumed the external project uses
5321 CMake as its build system, the install step will also.
5322 Otherwise, the install step will assume a Makefile-based
5323 build and simply run make install as the default build
5324 step. This can be overridden with custom install commands
5325 if required.
5326 INSTALL_COMMAND <cmd>...
5328 The external project's own install step is invoked
5329 as part of the main project's build. It is done
5330 after the external project's build step and may be
5331 before or after the external project's test step
5332 (see the TEST_BEFORE_INSTALL option below). The
5333 external project's install rules are not part of
5334 the main project's install rules, so if anything
5335 from the external project should be installed as
5336 part of the main build, these need to be specified
5337 in the main build as additional install() com‐
5338 mands. The default install step builds the install
5339 target of the external project, but this can be
5340 overridden with a custom command using this option
5341 (generator expressions are supported). Passing an
5342 empty string as the <cmd> makes the install step
5343 do nothing.
5344 NOTE:
5346 If the CMAKE_INSTALL_MODE environment variable is set
5347 when the main project is built, it will only have an
5348 effect if the following conditions are met:
5349 • The main project's configure step assumed the exter‐
5351 nal project uses CMake as its build system.
5352 • The external project's install command actually
5354 runs. Note that due to the way ExternalProject may
5355 use timestamps internally, if nothing the install
5356 step depends on needs to be re-executed, the install
5357 command might also not need to run.
5358 Note also that ExternalProject does not check whether
5360 the CMAKE_INSTALL_MODE environment variable changes
5361 from one run to another.
5362 Test Step Options:
5364 The test step is only defined if at least one of the fol‐
5365 lowing TEST_... options are provided.
5366 TEST_COMMAND <cmd>...
5368 Overrides the default test command (generator ex‐
5369 pressions are supported). If this option is not
5370 given, the default behavior of the test step is to
5371 build the external project's own test target. This
5372 option can be specified with <cmd> as an empty
5373 string, which allows the test step to still be de‐
5374 fined, but it will do nothing. Do not specify any
5375 of the other TEST_... options if providing an
5376 empty string as the test command, but prefer to
5377 omit all TEST_... options altogether if the test
5378 step target is not needed.
5379 TEST_BEFORE_INSTALL <bool>
5381 When this option is enabled, the test step will be
5382 executed before the install step. The default be‐
5383 havior is for the test step to run after the in‐
5384 stall step.
5385 TEST_AFTER_INSTALL <bool>
5387 This option is mainly useful as a way to indicate
5388 that the test step is desired but all default be‐
5389 havior is sufficient. Specifying this option with
5390 a boolean true value ensures the test step is de‐
5391 fined and that it comes after the install step. If
5392 both TEST_BEFORE_INSTALL and TEST_AFTER_INSTALL
5393 are enabled, the latter is silently ignored.
5394 TEST_EXCLUDE_FROM_MAIN <bool>
5396 New in version 3.2.
5397 If enabled, the main build's default ALL target
5400 will not depend on the test step. This can be a
5401 useful way of ensuring the test step is defined
5402 but only gets invoked when manually requested.
5403 This may cause a step target to be created auto‐
5404 matically for either the install or build step.
5405 See policy CMP0114.
5406 Output Logging Options:
5408 Each of the following LOG_... options can be used to wrap
5409 the relevant step in a script to capture its output to
5410 files. The log files will be created in LOG_DIR if sup‐
5411 plied or otherwise the STAMP_DIR directory with step-spe‐
5412 cific file names.
5413 LOG_DOWNLOAD <bool>
5415 When enabled, the output of the download step is
5416 logged to files.
5417 LOG_UPDATE <bool>
5419 When enabled, the output of the update step is
5420 logged to files.
5421 LOG_PATCH <bool>
5423 New in version 3.14.
5424 When enabled, the output of the patch step is
5427 logged to files.
5428 LOG_CONFIGURE <bool>
5430 When enabled, the output of the configure step is
5431 logged to files.
5432 LOG_BUILD <bool>
5434 When enabled, the output of the build step is
5435 logged to files.
5436 LOG_INSTALL <bool>
5438 When enabled, the output of the install step is
5439 logged to files.
5440 LOG_TEST <bool>
5442 When enabled, the output of the test step is
5443 logged to files.
5444 LOG_MERGED_STDOUTERR <bool>
5446 New in version 3.14.
5447 When enabled, stdout and stderr will be merged for
5450 any step whose output is being logged to files.
5451 LOG_OUTPUT_ON_FAILURE <bool>
5453 New in version 3.14.
5454 This option only has an effect if at least one of
5457 the other LOG_<step> options is enabled. If an
5458 error occurs for a step which has logging to file
5459 enabled, that step's output will be printed to the
5460 console if LOG_OUTPUT_ON_FAILURE is set to true.
5461 For cases where a large amount of output is
5462 recorded, just the end of that output may be
5463 printed to the console.
5464 Terminal Access Options:
5466 New in version 3.4.
5467 Steps can be given direct access to the terminal in some
5470 cases. Giving a step access to the terminal may allow it
5471 to receive terminal input if required, such as for au‐
5472 thentication details not provided by other options. With
5473 the Ninja generator, these options place the steps in the
5474 console job pool. Each step can be given access to the
5475 terminal individually via the following options:
5476 USES_TERMINAL_DOWNLOAD <bool>
5478 Give the download step access to the terminal.
5479 USES_TERMINAL_UPDATE <bool>
5481 Give the update step access to the terminal.
5482 USES_TERMINAL_PATCH <bool>
5484 New in version 3.23.
5485 Give the patch step access to the terminal.
5488 USES_TERMINAL_CONFIGURE <bool>
5490 Give the configure step access to the terminal.
5491 USES_TERMINAL_BUILD <bool>
5493 Give the build step access to the terminal.
5494 USES_TERMINAL_INSTALL <bool>
5496 Give the install step access to the terminal.
5497 USES_TERMINAL_TEST <bool>
5499 Give the test step access to the terminal.
5500 Target Options:
5502 DEPENDS <targets>...
5504 Specify other targets on which the external
5505 project depends. The other targets will be brought
5506 up to date before any of the external project's
5507 steps are executed. Because the external project
5508 uses additional custom targets internally for each
5509 step, the DEPENDS option is the most convenient
5510 way to ensure all of those steps depend on the
5511 other targets. Simply doing
5512 add_dependencies(<name> <targets>) will not make
5513 any of the steps dependent on <targets>.
5514 EXCLUDE_FROM_ALL <bool>
5516 When enabled, this option excludes the external
5517 project from the default ALL target of the main
5518 build.
5519 STEP_TARGETS <step-target>...
5521 Generate custom targets for the specified steps.
5522 This is required if the steps need to be triggered
5523 manually or if they need to be used as dependen‐
5524 cies of other targets. If this option is not spec‐
5525 ified, the default value is taken from the
5526 EP_STEP_TARGETS directory property. See
5527 ExternalProject_Add_StepTargets() below for fur‐
5528 ther discussion of the effects of this option.
5529 INDEPENDENT_STEP_TARGETS <step-target>...
5531 Deprecated since version 3.19: This is allowed
5532 only if policy CMP0114 is not set to NEW.
5533 Generates custom targets for the specified steps
5536 and prevent these targets from having the usual
5537 dependencies applied to them. If this option is
5538 not specified, the default value is taken from the
5539 EP_INDEPENDENT_STEP_TARGETS directory property.
5540 This option is mostly useful for allowing individ‐
5541 ual steps to be driven independently, such as for
5542 a CDash setup where each step should be initiated
5543 and reported individually rather than as one whole
5544 build. See ExternalProject_Add_StepTargets() below
5545 for further discussion of the effects of this op‐
5546 tion.
5547 Miscellaneous Options:
5549 LIST_SEPARATOR <sep>
5551 For any of the various ..._COMMAND options, and
5552 CMAKE_ARGS, replace ; with <sep> in the specified
5553 command lines. This can be useful where list
5554 variables may be given in commands where they
5555 should end up as space-separated arguments (<sep>
5556 would be a single space character string in this
5557 case).
5558 COMMAND <cmd>...
5560 Any of the other ..._COMMAND options can have ad‐
5561 ditional commands appended to them by following
5562 them with as many COMMAND ... options as needed (‐
5563 generator expressions are supported). For example:
5564 ExternalProject_Add(example
5566 ... # Download options, etc.
5567 BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
5568 COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
5569 COMMAND ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
5570 )
5571 It should also be noted that each build step is created via a
5573 call to ExternalProject_Add_Step(). See that command's documen‐
5574 tation for the automatic substitutions that are supported for
5575 some options.
5576 Obtaining Project Properties
5578 ExternalProject_Get_Property
5579 The ExternalProject_Get_Property() function retrieves external
5580 project target properties:
5581 ExternalProject_Get_Property(<name> <prop1> [<prop2>...])
5583 The function stores property values in variables of the same
5585 name. Property names correspond to the keyword argument names of
5586 ExternalProject_Add(). For example, the source directory might
5587 be retrieved like so:
5588 ExternalProject_Get_property(myExtProj SOURCE_DIR)
5590 message("Source dir of myExtProj = ${SOURCE_DIR}")
5591 Explicit Step Management
5593 The ExternalProject_Add() function on its own is often sufficient for
5594 incorporating an external project into the main build. Certain scenar‐
5595 ios require additional work to implement desired behavior, such as
5596 adding in a custom step or making steps available as manually trigger‐
5597 able targets. The ExternalProject_Add_Step(), ExternalProject_Add_Step‐
5598 Targets() and ExternalProject_Add_StepDependencies functions provide
5599 the lower level control needed to implement such step-level capabili‐
5600 ties.
5601 ExternalProject_Add_Step
5603 The ExternalProject_Add_Step() function specifies an additional
5604 custom step for an external project defined by an earlier call
5605 to ExternalProject_Add():
5606 ExternalProject_Add_Step(<name> <step> [<option>...])
5608 <name> is the same as the name passed to the original call to
5610 ExternalProject_Add(). The specified <step> must not be one of
5611 the pre-defined steps (mkdir, download, update, patch, config‐
5612 ure, build, install or test). The supported options are:
5613 COMMAND <cmd>...
5615 The command line to be executed by this custom step (‐
5616 generator expressions are supported). This option can be
5617 repeated multiple times to specify multiple commands to
5618 be executed in order.
5619 COMMENT "<text>..."
5621 Text to be printed when the custom step executes.
5622 DEPENDEES <step>...
5624 Other steps (custom or pre-defined) on which this step
5625 depends.
5626 DEPENDERS <step>...
5628 Other steps (custom or pre-defined) that depend on this
5629 new custom step.
5630 DEPENDS <file>...
5632 Files on which this custom step depends.
5633 INDEPENDENT <bool>
5635 New in version 3.19.
5636 Specifies whether this step is independent of the exter‐
5639 nal dependencies specified by the ExternalProject_Add()'s
5640 DEPENDS option. The default is FALSE. Steps marked as
5641 independent may depend only on other steps marked inde‐
5642 pendent. See policy CMP0114.
5643 Note that this use of the term "independent" refers only
5645 to independence from external targets specified by the
5646 DEPENDS option and is orthogonal to a step's dependencies
5647 on other steps.
5648 If a step target is created for an independent step by
5650 the ExternalProject_Add() STEP_TARGETS option or by the
5651 ExternalProject_Add_StepTargets() function, it will not
5652 depend on the external targets, but may depend on targets
5653 for other steps.
5654 BYPRODUCTS <file>...
5656 New in version 3.2.
5657 Files that will be generated by this custom step but
5660 which might or might not have their modification time up‐
5661 dated by subsequent builds. This list of files will ulti‐
5662 mately be passed through as the BYPRODUCTS option to the
5663 add_custom_command() used to implement the custom step
5664 internally.
5665 ALWAYS <bool>
5667 When enabled, this option specifies that the custom step
5668 should always be run (i.e. that it is always considered
5669 out of date).
5670 EXCLUDE_FROM_MAIN <bool>
5672 When enabled, this option specifies that the external
5673 project's main target does not depend on the custom step.
5674 This may cause step targets to be created automatically
5675 for the steps on which this step depends. See policy
5676 CMP0114.
5677 WORKING_DIRECTORY <dir>
5679 Specifies the working directory to set before running the
5680 custom step's command. If this option is not specified,
5681 the directory will be the value of the
5682 CMAKE_CURRENT_BINARY_DIR at the point where ExternalPro‐
5683 ject_Add_Step() was called.
5684 LOG <bool>
5686 If set, this causes the output from the custom step to be
5687 captured to files in the external project's LOG_DIR if
5688 supplied or STAMP_DIR.
5689 USES_TERMINAL <bool>
5691 If enabled, this gives the custom step direct access to
5692 the terminal if possible.
5693 The command line, comment, working directory and byproducts of
5695 every standard and custom step are processed to replace the to‐
5696 kens <SOURCE_DIR>, <SOURCE_SUBDIR>, <BINARY_DIR>, <INSTALL_DIR>
5697 <TMP_DIR>, <DOWNLOAD_DIR> and <DOWNLOADED_FILE> with their cor‐
5698 responding property values defined in the original call to
5699 ExternalProject_Add().
5700 New in version 3.3: Token replacement is extended to byproducts.
5702 New in version 3.11: The <DOWNLOAD_DIR> substitution token.
5705 ExternalProject_Add_StepTargets
5708 The ExternalProject_Add_StepTargets() function generates targets
5709 for the steps listed. The name of each created target will be of
5710 the form <name>-<step>:
5711 ExternalProject_Add_StepTargets(<name> <step1> [<step2>...])
5713 Creating a target for a step allows it to be used as a depen‐
5715 dency of another target or to be triggered manually. Having tar‐
5716 gets for specific steps also allows them to be driven indepen‐
5717 dently of each other by specifying targets on build command
5718 lines. For example, you may be submitting to a sub-project based
5719 dashboard where you want to drive the configure portion of the
5720 build, then submit to the dashboard, followed by the build por‐
5721 tion, followed by tests. If you invoke a custom target that de‐
5722 pends on a step halfway through the step dependency chain, then
5723 all the previous steps will also run to ensure everything is up
5724 to date.
5725 Internally, ExternalProject_Add() calls
5727 ExternalProject_Add_Step() to create each step. If any STEP_TAR‐
5728 GETS were specified, then ExternalProject_Add_StepTargets() will
5729 also be called after ExternalProject_Add_Step(). Even if a step
5730 is not mentioned in the STEP_TARGETS option, ExternalPro‐
5731 ject_Add_StepTargets() can still be called later to manually de‐
5732 fine a target for the step.
5733 The STEP_TARGETS option for ExternalProject_Add() is generally
5735 the easiest way to ensure targets are created for specific steps
5736 of interest. For custom steps, ExternalProject_Add_StepTar‐
5737 gets() must be called explicitly if a target should also be cre‐
5738 ated for that custom step. An alternative to these two options
5739 is to populate the EP_STEP_TARGETS directory property. It acts
5740 as a default for the step target options and can save having to
5741 repeatedly specify the same set of step targets when multiple
5742 external projects are being defined.
5743 New in version 3.19: If CMP0114 is set to NEW, step targets are
5745 fully responsible for holding the custom commands implementing
5746 their steps. The primary target created by ExternalProject_Add
5747 depends on the step targets, and the step targets depend on each
5748 other. The target-level dependencies match the file-level de‐
5749 pendencies used by the custom commands for each step. The tar‐
5750 gets for steps created with ExternalProject_Add_Step()'s INDE‐
5751 PENDENT option do not depend on the external targets specified
5752 by ExternalProject_Add()'s DEPENDS option. The predefined steps
5753 mkdir, download, update, and patch are independent.
5754 If CMP0114 is not NEW, the following deprecated behavior is
5757 available:
5758 • A deprecated NO_DEPENDS option may be specified immediately
5760 after the <name> and before the first step. If the NO_DEPENDS
5761 option is specified, the step target will not depend on the
5762 dependencies of the external project (i.e. on any dependencies
5763 of the <name> custom target created by ExternalProject_Add()).
5764 This is usually safe for the download, update and patch steps,
5765 since they do not typically require that the dependencies are
5766 updated and built. Using NO_DEPENDS for any of the other
5767 pre-defined steps, however, may break parallel builds. Only
5768 use NO_DEPENDS where it is certain that the named steps gen‐
5769 uinely do not have dependencies. For custom steps, consider
5770 whether or not the custom commands require the dependencies to
5771 be configured, built and installed.
5772 • The INDEPENDENT_STEP_TARGETS option for ExternalProject_Add(),
5774 or the EP_INDEPENDENT_STEP_TARGETS directory property, tells
5775 the function to call ExternalProject_Add_StepTargets() inter‐
5776 nally using the NO_DEPENDS option for the specified steps.
5777 ExternalProject_Add_StepDependencies
5779 New in version 3.2.
5780 The ExternalProject_Add_StepDependencies() function can be used
5783 to add dependencies to a step. The dependencies added must be
5784 targets CMake already knows about (these can be ordinary exe‐
5785 cutable or library targets, custom targets or even step targets
5786 of another external project):
5787 ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])
5789 This function takes care to set both target and file level de‐
5791 pendencies and will ensure that parallel builds will not break.
5792 It should be used instead of add_dependencies() whenever adding
5793 a dependency for some of the step targets generated by the Ex‐
5794 ternalProject module.
5795 Examples
5797 The following example shows how to download and build a hypothetical
5798 project called FooBar from github:
5799 include(ExternalProject)
5801 ExternalProject_Add(foobar
5802 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
5803 GIT_TAG origin/release/1.2.3
5804 )
5805 For the sake of the example, also define a second hypothetical external
5807 project called SecretSauce, which is downloaded from a web server. Two
5808 URLs are given to take advantage of a faster internal network if avail‐
5809 able, with a fallback to a slower external server. The project is a
5810 typical Makefile project with no configure step, so some of the default
5811 commands are overridden. The build is only required to build the sauce
5812 target:
5813 find_program(MAKE_EXE NAMES gmake nmake make)
5815 ExternalProject_Add(secretsauce
5816 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
5817 https://www.somecompany.com/downloads/sauce-2.7.zip
5818 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
5819 CONFIGURE_COMMAND ""
5820 BUILD_COMMAND ${MAKE_EXE} sauce
5821 )
5822 Suppose the build step of secretsauce requires that foobar must already
5824 be built. This could be enforced like so:
5825 ExternalProject_Add_StepDependencies(secretsauce build foobar)
5827 Another alternative would be to create a custom target for foobar's
5829 build step and make secretsauce depend on that rather than the whole
5830 foobar project. This would mean foobar only needs to be built, it
5831 doesn't need to run its install or test steps before secretsauce can be
5832 built. The dependency can also be defined along with the secretsauce
5833 project:
5834 ExternalProject_Add_StepTargets(foobar build)
5836 ExternalProject_Add(secretsauce
5837 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
5838 https://www.somecompany.com/downloads/sauce-2.7.zip
5839 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
5840 CONFIGURE_COMMAND ""
5841 BUILD_COMMAND ${MAKE_EXE} sauce
5842 DEPENDS foobar-build
5843 )
5844 Instead of calling ExternalProject_Add_StepTargets(), the target could
5846 be defined along with the foobar project itself:
5847 ExternalProject_Add(foobar
5849 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
5850 GIT_TAG origin/release/1.2.3
5851 STEP_TARGETS build
5852 )
5853 If many external projects should have the same set of step targets,
5855 setting a directory property may be more convenient. The build step
5856 target could be created automatically by setting the EP_STEP_TARGETS
5857 directory property before creating the external projects with
5858 ExternalProject_Add():
5859 set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)
5861 Lastly, suppose that secretsauce provides a script called makedoc which
5863 can be used to generate its own documentation. Further suppose that the
5864 script expects the output directory to be provided as the only parame‐
5865 ter and that it should be run from the secretsauce source directory. A
5866 custom step and a custom target to trigger the script can be defined
5867 like so:
5868 ExternalProject_Add_Step(secretsauce docs
5870 COMMAND <SOURCE_DIR>/makedoc <BINARY_DIR>
5871 WORKING_DIRECTORY <SOURCE_DIR>
5872 COMMENT "Building secretsauce docs"
5873 ALWAYS TRUE
5874 EXCLUDE_FROM_MAIN TRUE
5875 )
5876 ExternalProject_Add_StepTargets(secretsauce docs)
5877 The custom step could then be triggered from the main build like so:
5879 cmake --build . --target secretsauce-docs
5881 FeatureSummary
5883 Functions for generating a summary of enabled/disabled features.
5884 These functions can be used to generate a summary of enabled and dis‐
5886 abled packages and/or feature for a build tree such as:
5887 -- The following OPTIONAL packages have been found:
5889 LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
5890 * Enables HTML-import in MyWordProcessor
5891 * Enables odt-export in MyWordProcessor
5892 PNG, A PNG image library., <http://www.libpng.org/pub/png/>
5893 * Enables saving screenshots
5894 -- The following OPTIONAL packages have not been found:
5895 Lua51, The Lua scripting language., <http://www.lua.org>
5896 * Enables macros in MyWordProcessor
5897 Foo, Foo provides cool stuff.
5898 Global Properties
5900 FeatureSummary_PKG_TYPES
5901 The global property FeatureSummary_PKG_TYPES defines the type of pack‐
5903 ages used by FeatureSummary.
5904 The order in this list is important, the first package type in the list
5906 is the least important, the last is the most important. the of a pack‐
5907 age can only be changed to higher types.
5908 The default package types are , RUNTIME, OPTIONAL, RECOMMENDED and RE‐
5910 QUIRED, and their importance is RUNTIME < OPTIONAL < RECOMMENDED < RE‐
5911 QUIRED.
5912 FeatureSummary_REQUIRED_PKG_TYPES
5914 The global property FeatureSummary_REQUIRED_PKG_TYPES defines which
5916 package types are required.
5917 If one or more package in this categories has not been found, CMake
5919 will abort when calling feature_summary() with the 'FATAL_ON_MISS‐
5920 ING_REQUIRED_PACKAGES' option enabled.
5921 The default value for this global property is REQUIRED.
5923 FeatureSummary_DEFAULT_PKG_TYPE
5925 The global property FeatureSummary_DEFAULT_PKG_TYPE defines which pack‐
5927 age type is the default one. When calling feature_summary(), if the
5928 user did not set the package type explicitly, the package will be as‐
5929 signed to this category.
5930 This value must be one of the types defined in the
5932 FeatureSummary_PKG_TYPES global property unless the package type is set
5933 for all the packages.
5934 The default value for this global property is OPTIONAL.
5936 FeatureSummary_<TYPE>_DESCRIPTION
5938 New in version 3.9.
5940 The global property FeatureSummary_<TYPE>_DESCRIPTION can be defined
5943 for each type to replace the type name with the specified string when‐
5944 ever the package type is used in an output string.
5945 If not set, the string "<TYPE> packages" is used.
5947 Functions
5949 feature_summary
5950 feature_summary( [FILENAME <file>]
5952 [APPEND]
5953 [VAR <variable_name>]
5954 [INCLUDE_QUIET_PACKAGES]
5955 [FATAL_ON_MISSING_REQUIRED_PACKAGES]
5956 [DESCRIPTION "<description>" | DEFAULT_DESCRIPTION]
5957 [QUIET_ON_EMPTY]
5958 WHAT (ALL
5959 | PACKAGES_FOUND | PACKAGES_NOT_FOUND
5960 | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
5961 | ENABLED_FEATURES | DISABLED_FEATURES)
5962 )
5963 The feature_summary() macro can be used to print information
5965 about enabled or disabled packages or features of a project. By
5966 default, only the names of the features/packages will be printed
5967 and their required version when one was specified. Use
5968 set_package_properties() to add more useful information, like
5969 e.g. a download URL for the respective package or their purpose
5970 in the project.
5971 The WHAT option is the only mandatory option. Here you specify
5973 what information will be printed:
5974 ALL print everything
5976 ENABLED_FEATURES
5978 the list of all features which are enabled
5979 DISABLED_FEATURES
5981 the list of all features which are disabled
5982 PACKAGES_FOUND
5984 the list of all packages which have been found
5985 PACKAGES_NOT_FOUND
5987 the list of all packages which have not been found
5988 For each package type <TYPE> defined by the
5990 FeatureSummary_PKG_TYPES global property, the following informa‐
5991 tion can also be used:
5992 <TYPE>_PACKAGES_FOUND
5994 only those packages which have been found which have the
5995 type <TYPE>
5996 <TYPE>_PACKAGES_NOT_FOUND
5998 only those packages which have not been found which have
5999 the type <TYPE>
6000 Changed in version 3.1: With the exception of the ALL value,
6002 these values can be combined in order to customize the output.
6003 For example:
6004 feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
6006 If a FILENAME is given, the information is printed into this
6009 file. If APPEND is used, it is appended to this file, otherwise
6010 the file is overwritten if it already existed. If the VAR op‐
6011 tion is used, the information is "printed" into the specified
6012 variable. If FILENAME is not used, the information is printed
6013 to the terminal. Using the DESCRIPTION option a description or
6014 headline can be set which will be printed above the actual con‐
6015 tent. If only one type of package was requested, no title is
6016 printed, unless it is explicitly set using either DESCRIPTION to
6017 use a custom string, or DEFAULT_DESCRIPTION to use a default ti‐
6018 tle for the requested type. If INCLUDE_QUIET_PACKAGES is given,
6019 packages which have been searched with find_package(... QUIET)
6020 will also be listed. By default they are skipped. If FA‐
6021 TAL_ON_MISSING_REQUIRED_PACKAGES is given, CMake will abort if a
6022 package which is marked as one of the package types listed in
6023 the FeatureSummary_REQUIRED_PKG_TYPES global property has not
6024 been found. The default value for the
6025 FeatureSummary_REQUIRED_PKG_TYPES global property is REQUIRED.
6026 New in version 3.9: The DEFAULT_DESCRIPTION option.
6028 The FeatureSummary_DEFAULT_PKG_TYPE global property can be modi‐
6031 fied to change the default package type assigned when not ex‐
6032 plicitly assigned by the user.
6033 New in version 3.8: If the QUIET_ON_EMPTY option is used, if
6035 only one type of package was requested, and no packages belong‐
6036 ing to that category were found, then no output (including the
6037 DESCRIPTION) is printed or added to the VAR variable.
6038 Example 1, append everything to a file:
6041 include(FeatureSummary)
6043 feature_summary(WHAT ALL
6044 FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
6045 Example 2, print the enabled features into the variable enabled‐
6047 FeaturesText, including QUIET packages:
6048 include(FeatureSummary)
6050 feature_summary(WHAT ENABLED_FEATURES
6051 INCLUDE_QUIET_PACKAGES
6052 DESCRIPTION "Enabled Features:"
6053 VAR enabledFeaturesText)
6054 message(STATUS "${enabledFeaturesText}")
6055 Example 3, change default package types and print only the cate‐
6057 gories that are not empty:
6058 include(FeatureSummary)
6060 set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
6061 find_package(FOO)
6062 set_package_properties(FOO PROPERTIES TYPE BUILD)
6063 feature_summary(WHAT BUILD_PACKAGES_FOUND
6064 Description "Build tools found:"
6065 QUIET_ON_EMPTY)
6066 feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
6067 Description "Build tools not found:"
6068 QUIET_ON_EMPTY)
6069 set_package_properties
6071 set_package_properties(<name> PROPERTIES
6073 [ URL <url> ]
6074 [ DESCRIPTION <description> ]
6075 [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
6076 [ PURPOSE <purpose> ]
6077 )
6078 Use this macro to set up information about the named package,
6080 which can then be displayed via FEATURE_SUMMARY(). This can be
6081 done either directly in the Find-module or in the project which
6082 uses the module after the find_package() call. The features for
6083 which information can be set are added automatically by the
6084 find_package() command.
6085 URL <url>
6087 This should be the homepage of the package, or something
6088 similar. Ideally this is set already directly in the
6089 Find-module.
6090 DESCRIPTION <description>
6092 A short description what that package is, at most one
6093 sentence. Ideally this is set already directly in the
6094 Find-module.
6095 TYPE <type>
6097 What type of dependency has the using project on that
6098 package. Default is OPTIONAL. In this case it is a
6099 package which can be used by the project when available
6100 at buildtime, but it also work without. RECOMMENDED is
6101 similar to OPTIONAL, i.e. the project will build if the
6102 package is not present, but the functionality of the re‐
6103 sulting binaries will be severely limited. If a REQUIRED
6104 package is not available at buildtime, the project may
6105 not even build. This can be combined with the FA‐
6106 TAL_ON_MISSING_REQUIRED_PACKAGES argument for fea‐
6107 ture_summary(). Last, a RUNTIME package is a package
6108 which is actually not used at all during the build, but
6109 which is required for actually running the resulting bi‐
6110 naries. So if such a package is missing, the project can
6111 still be built, but it may not work later on. If
6112 set_package_properties() is called multiple times for the
6113 same package with different TYPEs, the TYPE is only
6114 changed to higher TYPEs (RUNTIME < OPTIONAL < RECOMMENDED
6115 < REQUIRED), lower TYPEs are ignored. The TYPE property
6116 is project-specific, so it cannot be set by the Find-mod‐
6117 ule, but must be set in the project. Type accepted can
6118 be changed by setting the FeatureSummary_PKG_TYPES global
6119 property.
6120 PURPOSE <purpose>
6122 This describes which features this package enables in the
6123 project, i.e. it tells the user what functionality he
6124 gets in the resulting binaries. If set_package_proper‐
6125 ties() is called multiple times for a package, all PUR‐
6126 POSE properties are appended to a list of purposes of the
6127 package in the project. As the TYPE property, also the
6128 PURPOSE property is project-specific, so it cannot be set
6129 by the Find-module, but must be set in the project.
6130 Example for setting the info for a package:
6132 find_package(LibXml2)
6134 set_package_properties(LibXml2 PROPERTIES
6135 DESCRIPTION "A XML processing library."
6136 URL "http://xmlsoft.org/")
6137 # or
6138 set_package_properties(LibXml2 PROPERTIES
6139 TYPE RECOMMENDED
6140 PURPOSE "Enables HTML-import in MyWordProcessor")
6141 # or
6142 set_package_properties(LibXml2 PROPERTIES
6143 TYPE OPTIONAL
6144 PURPOSE "Enables odt-export in MyWordProcessor")
6145 find_package(DBUS)
6147 set_package_properties(DBUS PROPERTIES
6148 TYPE RUNTIME
6149 PURPOSE "Necessary to disable the screensaver during a presentation")
6150 add_feature_info
6152 add_feature_info(<name> <enabled> <description>)
6154 Use this macro to add information about a feature with the given
6156 <name>. <enabled> contains whether this feature is enabled or
6157 not. It can be a variable or a list of conditions. <descrip‐
6158 tion> is a text describing the feature. The information can be
6159 displayed using feature_summary() for ENABLED_FEATURES and DIS‐
6160 ABLED_FEATURES respectively.
6161 Changed in version 3.8: <enabled> can be a list of conditions.
6163 Example for setting the info for a feature:
6166 option(WITH_FOO "Help for foo" ON)
6168 add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
6169 Legacy Macros
6171 The following macros are provided for compatibility with previous CMake
6172 versions:
6173 set_package_info
6175 set_package_info(<name> <description> [ <url> [<purpose>] ])
6177 Use this macro to set up information about the named package,
6179 which can then be displayed via feature_summary(). This can be
6180 done either directly in the Find-module or in the project which
6181 uses the module after the find_package() call. The features for
6182 which information can be set are added automatically by the
6183 find_package() command.
6184 set_feature_info
6186 set_feature_info(<name> <description> [<url>])
6188 Does the same as:
6190 set_package_info(<name> <description> <url>)
6192 print_enabled_features
6194 print_enabled_features()
6196 Does the same as
6198 feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
6200 print_disabled_features
6202 print_disabled_features()
6204 Does the same as
6206 feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
6208 FetchContent
6210 New in version 3.11.
6211 NOTE:
6214 The Using Dependencies Guide provides a high-level introduction to
6215 this general topic. It provides a broader overview of where the
6216 FetchContent module fits into the bigger picture, including its re‐
6217 lationship to the find_package() command. The guide is recommended
6218 pre-reading before moving on to the details below.
6219 Overview
6221 This module enables populating content at configure time via any method
6222 supported by the ExternalProject module. Whereas ExternalProject_Add()
6223 downloads at build time, the FetchContent module makes content avail‐
6224 able immediately, allowing the configure step to use the content in
6225 commands like add_subdirectory(), include() or file() operations.
6226 Content population details should be defined separately from the com‐
6228 mand that performs the actual population. This separation ensures that
6229 all the dependency details are defined before anything might try to use
6230 them to populate content. This is particularly important in more com‐
6231 plex project hierarchies where dependencies may be shared between mul‐
6232 tiple projects.
6233 The following shows a typical example of declaring content details for
6235 some dependencies and then ensuring they are populated with a separate
6236 call:
6237 FetchContent_Declare(
6239 googletest
6240 GIT_REPOSITORY https://github.com/google/googletest.git
6241 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
6242 )
6243 FetchContent_Declare(
6244 myCompanyIcons
6245 URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
6246 URL_HASH MD5=5588a7b18261c20068beabfb4f530b87
6247 )
6248 FetchContent_MakeAvailable(googletest myCompanyIcons)
6250 The FetchContent_MakeAvailable() command ensures the named dependencies
6252 have been populated, either by an earlier call or by populating them
6253 itself. When performing the population, it will also add them to the
6254 main build, if possible, so that the main build can use the populated
6255 projects' targets, etc. See the command's documentation for how these
6256 steps are performed.
6257 When using a hierarchical project arrangement, projects at higher lev‐
6259 els in the hierarchy are able to override the declared details of con‐
6260 tent specified anywhere lower in the project hierarchy. The first de‐
6261 tails to be declared for a given dependency take precedence, regardless
6262 of where in the project hierarchy that occurs. Similarly, the first
6263 call that tries to populate a dependency "wins", with subsequent popu‐
6264 lations reusing the result of the first instead of repeating the popu‐
6265 lation again. See the Examples which demonstrate this scenario.
6266 In some cases, the main project may need to have more precise control
6268 over the population, or it may be required to explicitly define the
6269 population steps in a way that cannot be captured by the declared de‐
6270 tails alone. For such situations, the lower level
6271 FetchContent_GetProperties() and FetchContent_Populate() commands can
6272 be used. These lack the richer features provided by
6273 FetchContent_MakeAvailable() though, so their direct use should be con‐
6274 sidered a last resort. The typical pattern of such custom steps looks
6275 like this:
6276 # NOTE: Where possible, prefer to use FetchContent_MakeAvailable()
6278 # instead of custom logic like this
6279 # Check if population has already been performed
6281 FetchContent_GetProperties(depname)
6282 if(NOT depname_POPULATED)
6283 # Fetch the content using previously declared details
6284 FetchContent_Populate(depname)
6285 # Set custom variables, policies, etc.
6287 # ...
6288 # Bring the populated content into the build
6290 add_subdirectory(${depname_SOURCE_DIR} ${depname_BINARY_DIR})
6291 endif()
6292 The FetchContent module also supports defining and populating content
6294 in a single call, with no check for whether the content has been popu‐
6295 lated elsewhere already. This should not be done in projects, but may
6296 be appropriate for populating content in CMake's script mode. See
6297 FetchContent_Populate() for details.
6298 Commands
6300 FetchContent_Declare
6301 FetchContent_Declare(
6303 <name>
6304 <contentOptions>...
6305 [SYSTEM]
6306 [OVERRIDE_FIND_PACKAGE |
6307 FIND_PACKAGE_ARGS args...]
6308 )
6309 The FetchContent_Declare() function records the options that de‐
6311 scribe how to populate the specified content. If such details
6312 have already been recorded earlier in this project (regardless
6313 of where in the project hierarchy), this and all later calls for
6314 the same content <name> are ignored. This "first to record,
6315 wins" approach is what allows hierarchical projects to have par‐
6316 ent projects override content details of child projects.
6317 The content <name> can be any string without spaces, but good
6319 practice would be to use only letters, numbers and underscores.
6320 The name will be treated case-insensitively and it should be ob‐
6321 vious for the content it represents, often being the name of the
6322 child project or the value given to its top level project() com‐
6323 mand (if it is a CMake project). For well-known public
6324 projects, the name should generally be the official name of the
6325 project. Choosing an unusual name makes it unlikely that other
6326 projects needing that same content will use the same name, lead‐
6327 ing to the content being populated multiple times.
6328 The <contentOptions> can be any of the download, update or patch
6330 options that the ExternalProject_Add() command understands. The
6331 configure, build, install and test steps are explicitly disabled
6332 and therefore options related to them will be ignored. The
6333 SOURCE_SUBDIR option is an exception, see
6334 FetchContent_MakeAvailable() for details on how that affects be‐
6335 havior.
6336 In most cases, <contentOptions> will just be a couple of options
6338 defining the download method and method-specific details like a
6339 commit tag or archive hash. For example:
6340 FetchContent_Declare(
6342 googletest
6343 GIT_REPOSITORY https://github.com/google/googletest.git
6344 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
6345 )
6346 FetchContent_Declare(
6348 myCompanyIcons
6349 URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
6350 URL_HASH MD5=5588a7b18261c20068beabfb4f530b87
6351 )
6352 FetchContent_Declare(
6354 myCompanyCertificates
6355 SVN_REPOSITORY svn+ssh://svn.mycompany.com/srv/svn/trunk/certs
6356 SVN_REVISION -r12345
6357 )
6358 Where contents are being fetched from a remote location and you
6360 do not control that server, it is advisable to use a hash for
6361 GIT_TAG rather than a branch or tag name. A commit hash is more
6362 secure and helps to confirm that the downloaded contents are
6363 what you expected.
6364 Changed in version 3.14: Commands for the download, update or
6366 patch steps can access the terminal. This may be needed for
6367 things like password prompts or real-time display of command
6368 progress.
6369 New in version 3.22: The CMAKE_TLS_VERIFY, CMAKE_TLS_CAINFO,
6372 CMAKE_NETRC and CMAKE_NETRC_FILE variables now provide the de‐
6373 faults for their corresponding content options, just like they
6374 do for ExternalProject_Add(). Previously, these variables were
6375 ignored by the FetchContent module.
6376 New in version 3.24:
6379 FIND_PACKAGE_ARGS
6381 This option is for scenarios where the
6382 FetchContent_MakeAvailable() command may first try a call
6383 to find_package() to satisfy the dependency for <name>.
6384 By default, such a call would be simply find_pack‐
6385 age(<name>), but FIND_PACKAGE_ARGS can be used to provide
6386 additional arguments to be appended after the <name>.
6387 FIND_PACKAGE_ARGS can also be given with nothing after
6388 it, which indicates that find_package() can still be
6389 called if FETCHCONTENT_TRY_FIND_PACKAGE_MODE is set to
6390 OPT_IN or is not set.
6391 Everything after the FIND_PACKAGE_ARGS keyword is ap‐
6393 pended to the find_package() call, so all other <con‐
6394 tentOptions> must come before the FIND_PACKAGE_ARGS key‐
6395 word. If the CMAKE_FIND_PACKAGE_TARGETS_GLOBAL variable
6396 is set to true at the time FetchContent_Declare() is
6397 called, a GLOBAL keyword will be appended to the
6398 find_package() arguments if it was not already specified.
6399 It will also be appended if FIND_PACKAGE_ARGS was not
6400 given, but FETCHCONTENT_TRY_FIND_PACKAGE_MODE was set to
6401 ALWAYS.
6402 OVERRIDE_FIND_PACKAGE cannot be used when FIND_PACK‐
6404 AGE_ARGS is given.
6405 Dependency Providers discusses another way that
6407 FetchContent_MakeAvailable() calls can be redirected.
6408 FIND_PACKAGE_ARGS is intended for project control,
6409 whereas dependency providers allow users to override
6410 project behavior.
6411 OVERRIDE_FIND_PACKAGE
6413 When a FetchContent_Declare(<name> ...) call includes
6414 this option, subsequent calls to find_package(<name> ...)
6415 will ensure that FetchContent_MakeAvailable(<name>) has
6416 been called, then use the config package files in the
6417 CMAKE_FIND_PACKAGE_REDIRECTS_DIR directory (which are
6418 usually created by FetchContent_MakeAvailable()). This
6419 effectively makes FetchContent_MakeAvailable() override
6420 find_package() for the named dependency, allowing the
6421 former to satisfy the package requirements of the latter.
6422 FIND_PACKAGE_ARGS cannot be used when OVERRIDE_FIND_PACK‐
6423 AGE is given.
6424 If a dependency provider has been set and the project
6426 calls find_package() for the <name> dependency, OVER‐
6427 RIDE_FIND_PACKAGE will not prevent the provider from see‐
6428 ing that call. Dependency providers always have the op‐
6429 portunity to intercept any direct call to find_package(),
6430 except if that call contains the BYPASS_PROVIDER option.
6431 New in version 3.25:
6434 SYSTEM If the SYSTEM argument is provided, the SYSTEM directory
6436 property of a subdirectory added by
6437 FetchContent_MakeAvailable() will be set to true. This
6438 will affect non-imported targets created as part of that
6439 command. See the SYSTEM target property documentation
6440 for a more detailed discussion of the effects.
6441 FetchContent_MakeAvailable
6444 New in version 3.14.
6445 FetchContent_MakeAvailable(<name1> [<name2>...])
6448 This command ensures that each of the named dependencies are
6450 made available to the project by the time it returns. There
6451 must have been a call to FetchContent_Declare() for each depen‐
6452 dency, and the first such call will control how that dependency
6453 will be made available, as described below.
6454 If <lowercaseName>_SOURCE_DIR is not set:
6456 • New in version 3.24: If a dependency provider is set, call the
6458 provider's command with FETCHCONTENT_MAKEAVAILABLE_SERIAL as
6459 the first argument, followed by the arguments of the first
6460 call to FetchContent_Declare() for <name>. If SOURCE_DIR or
6461 BINARY_DIR were not part of the original declared arguments,
6462 they will be added with their default values. If
6463 FETCHCONTENT_TRY_FIND_PACKAGE_MODE was set to NEVER when the
6464 details were declared, any FIND_PACKAGE_ARGS will be omitted.
6465 The OVERRIDE_FIND_PACKAGE keyword is also always omitted. If
6466 the provider fulfilled the request, FetchContent_MakeAvail‐
6467 able() will consider that dependency handled, skip the remain‐
6468 ing steps below and move on to the next dependency in the
6469 list.
6470 • New in version 3.24: If permitted, find_package(<name>
6473 [<args>...]) will be called, where <args>... may be provided
6474 by the FIND_PACKAGE_ARGS option in FetchContent_Declare().
6475 The value of the FETCHCONTENT_TRY_FIND_PACKAGE_MODE variable
6476 at the time FetchContent_Declare() was called determines
6477 whether FetchContent_MakeAvailable() can call find_package().
6478 If the CMAKE_FIND_PACKAGE_TARGETS_GLOBAL variable is set to
6479 true when FetchContent_MakeAvailable() is called, it still af‐
6480 fects any imported targets created when that in turn calls
6481 find_package(), even if that variable was false when the cor‐
6482 responding details were declared.
6483 If the dependency was not satisfied by a provider or a
6486 find_package() call, FetchContent_MakeAvailable() then uses the
6487 following logic to make the dependency available:
6488 • If the dependency has already been populated earlier in this
6490 run, set the <lowercaseName>_POPULATED, <lowercase‐
6491 Name>_SOURCE_DIR and <lowercaseName>_BINARY_DIR variables in
6492 the same way as a call to FetchContent_GetProperties(), then
6493 skip the remaining steps below and move on to the next depen‐
6494 dency in the list.
6495 • Call FetchContent_Populate() to populate the dependency using
6497 the details recorded by an earlier call to
6498 FetchContent_Declare(). Halt with a fatal error if no such
6499 details have been recorded.
6500 FETCHCONTENT_SOURCE_DIR_<uppercaseName> can be used to over‐
6501 ride the declared details and use content provided at the
6502 specified location instead.
6503 • New in version 3.24: Ensure the
6505 CMAKE_FIND_PACKAGE_REDIRECTS_DIR directory contains a <lower‐
6506 caseName>-config.cmake and a <lowercaseName>-config-ver‐
6507 sion.cmake file (or equivalently <name>Config.cmake and
6508 <name>ConfigVersion.cmake). The directory that the
6509 CMAKE_FIND_PACKAGE_REDIRECTS_DIR variable points to is cleared
6510 at the start of every CMake run. If no config file exists
6511 when FetchContent_Populate() returns, a minimal one will be
6512 written which includes any <lowercaseName>-extra.cmake or
6513 <name>Extra.cmake file with the OPTIONAL flag (so the files
6514 can be missing and won't generate a warning). Similarly, if
6515 no config version file exists, a very simple one will be writ‐
6516 ten which sets PACKAGE_VERSION_COMPATIBLE and PACKAGE_VER‐
6517 SION_EXACT to true. This ensures all future calls to
6518 find_package() for the dependency will use the redirected con‐
6519 fig file, regardless of any version requirements. CMake can‐
6520 not automatically determine an arbitrary dependency's version,
6521 so it cannot set PACKAGE_VERSION. When a dependency is pulled
6522 in via add_subdirectory() in the next step, it may choose to
6523 overwrite the generated config version file in
6524 CMAKE_FIND_PACKAGE_REDIRECTS_DIR with one that also sets PACK‐
6525 AGE_VERSION. The dependency may also write a <lowercase‐
6526 Name>-extra.cmake or <name>Extra.cmake file to perform custom
6527 processing or define any variables that their normal (in‐
6528 stalled) package config file would otherwise usually define
6529 (many projects don't do any custom processing or set any vari‐
6530 ables and therefore have no need to do this). If required,
6531 the main project can write these files instead if the depen‐
6532 dency project doesn't do so. This allows the main project to
6533 add missing details from older dependencies that haven't or
6534 can't be updated to support this functionality. See
6535 Integrating With find_package() for examples.
6536 • If the top directory of the populated content contains a
6539 CMakeLists.txt file, call add_subdirectory() to add it to the
6540 main build. It is not an error for there to be no CMake‐
6541 Lists.txt file, which allows the command to be used for depen‐
6542 dencies that make downloaded content available at a known lo‐
6543 cation, but which do not need or support being added directly
6544 to the build.
6545 New in version 3.18: The SOURCE_SUBDIR option can be given in
6547 the declared details to look somewhere below the top directory
6548 instead (i.e. the same way that SOURCE_SUBDIR is used by the
6549 ExternalProject_Add() command). The path provided with
6550 SOURCE_SUBDIR must be relative and will be treated as relative
6551 to the top directory. It can also point to a directory that
6552 does not contain a CMakeLists.txt file or even to a directory
6553 that doesn't exist. This can be used to avoid adding a
6554 project that contains a CMakeLists.txt file in its top direc‐
6555 tory.
6556 New in version 3.25: If the SYSTEM keyword was included in the
6559 call to FetchContent_Declare(), the SYSTEM keyword will be
6560 added to the add_subdirectory() command as well.
6561 Projects should aim to declare the details of all dependencies
6564 they might use before they call FetchContent_MakeAvailable() for
6565 any of them. This ensures that if any of the dependencies are
6566 also sub-dependencies of one or more of the others, the main
6567 project still controls the details that will be used (because it
6568 will declare them first before the dependencies get a chance
6569 to). In the following code samples, assume that the uses_other
6570 dependency also uses FetchContent to add the other dependency
6571 internally:
6572 # WRONG: Should declare all details first
6574 FetchContent_Declare(uses_other ...)
6575 FetchContent_MakeAvailable(uses_other)
6576 FetchContent_Declare(other ...) # Will be ignored, uses_other beat us to it
6578 FetchContent_MakeAvailable(other) # Would use details declared by uses_other
6579 # CORRECT: All details declared first, so they will take priority
6581 FetchContent_Declare(uses_other ...)
6582 FetchContent_Declare(other ...)
6583 FetchContent_MakeAvailable(uses_other other)
6584 Note that CMAKE_VERIFY_INTERFACE_HEADER_SETS is explicitly set
6586 to false upon entry to FetchContent_MakeAvailable(), and is re‐
6587 stored to its original value before the command returns. Devel‐
6588 opers typically only want to verify header sets from the main
6589 project, not those from any dependencies. This local manipula‐
6590 tion of the CMAKE_VERIFY_INTERFACE_HEADER_SETS variable provides
6591 that intuitive behavior. You can use variables like
6592 CMAKE_PROJECT_INCLUDE or CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE to
6593 turn verification back on for all or some dependencies. You can
6594 also set the VERIFY_INTERFACE_HEADER_SETS property of individual
6595 targets.
6596 FetchContent_Populate
6598 NOTE:
6599 Where possible, prefer to use FetchContent_MakeAvailable()
6600 instead of implementing population manually with this com‐
6601 mand.
6602 FetchContent_Populate(<name>)
6604 In most cases, the only argument given to FetchContent_Popu‐
6606 late() is the <name>. When used this way, the command assumes
6607 the content details have been recorded by an earlier call to
6608 FetchContent_Declare(). The details are stored in a global
6609 property, so they are unaffected by things like variable or di‐
6610 rectory scope. Therefore, it doesn't matter where in the
6611 project the details were previously declared, as long as they
6612 have been declared before the call to FetchContent_Populate().
6613 Those saved details are then used to construct a call to
6614 ExternalProject_Add() in a private sub-build to perform the con‐
6615 tent population immediately. The implementation of ExternalPro‐
6616 ject_Add() ensures that if the content has already been popu‐
6617 lated in a previous CMake run, that content will be reused
6618 rather than repopulating them again. For the common case where
6619 population involves downloading content, the cost of the down‐
6620 load is only paid once.
6621 An internal global property records when a particular content
6623 population request has been processed. If FetchContent_Popu‐
6624 late() is called more than once for the same content name within
6625 a configure run, the second call will halt with an error.
6626 Projects can and should check whether content population has al‐
6627 ready been processed with the FetchContent_GetProperties() com‐
6628 mand before calling FetchContent_Populate().
6629 FetchContent_Populate() will set three variables in the scope of
6631 the caller:
6632 <lowercaseName>_POPULATED
6634 This will always be set to TRUE by the call.
6635 <lowercaseName>_SOURCE_DIR
6637 The location where the populated content can be found
6638 upon return.
6639 <lowercaseName>_BINARY_DIR
6641 A directory intended for use as a corresponding build di‐
6642 rectory.
6643 The main use case for the <lowercaseName>_SOURCE_DIR and <lower‐
6645 caseName>_BINARY_DIR variables is to call add_subdirectory() im‐
6646 mediately after population:
6647 FetchContent_Populate(FooBar)
6649 add_subdirectory(${foobar_SOURCE_DIR} ${foobar_BINARY_DIR})
6650 The values of the three variables can also be retrieved from
6652 anywhere in the project hierarchy using the
6653 FetchContent_GetProperties() command.
6654 The FetchContent_Populate() command also supports a syntax al‐
6656 lowing the content details to be specified directly rather than
6657 using any saved details. This is more low-level and use of this
6658 form is generally to be avoided in favor of using saved content
6659 details as outlined above. Nevertheless, in certain situations
6660 it can be useful to invoke the content population as an isolated
6661 operation (typically as part of implementing some other higher
6662 level feature or when using CMake in script mode):
6663 FetchContent_Populate(
6665 <name>
6666 [QUIET]
6667 [SUBBUILD_DIR <subBuildDir>]
6668 [SOURCE_DIR <srcDir>]
6669 [BINARY_DIR <binDir>]
6670 ...
6671 )
6672 This form has a number of key differences to that where only
6674 <name> is provided:
6675 • All required population details are assumed to have been pro‐
6677 vided directly in the call to FetchContent_Populate(). Any
6678 saved details for <name> are ignored.
6679 • No check is made for whether content for <name> has already
6681 been populated.
6682 • No global property is set to record that the population has
6684 occurred.
6685 • No global properties record the source or binary directories
6687 used for the populated content.
6688 • The FETCHCONTENT_FULLY_DISCONNECTED and FETCHCONTENT_UP‐
6690 DATES_DISCONNECTED cache variables are ignored.
6691 The <lowercaseName>_SOURCE_DIR and <lowercaseName>_BINARY_DIR
6693 variables are still returned to the caller, but since these lo‐
6694 cations are not stored as global properties when this form is
6695 used, they are only available to the calling scope and below
6696 rather than the entire project hierarchy. No <lowercase‐
6697 Name>_POPULATED variable is set in the caller's scope with this
6698 form.
6699 The supported options for FetchContent_Populate() are the same
6701 as those for FetchContent_Declare(). Those few options shown
6702 just above are either specific to FetchContent_Populate() or
6703 their behavior is slightly modified from how
6704 ExternalProject_Add() treats them:
6705 QUIET The QUIET option can be given to hide the output associ‐
6707 ated with populating the specified content. If the popu‐
6708 lation fails, the output will be shown regardless of
6709 whether this option was given or not so that the cause of
6710 the failure can be diagnosed. The global FETCHCON‐
6711 TENT_QUIET cache variable has no effect on FetchCon‐
6712 tent_Populate() calls where the content details are pro‐
6713 vided directly.
6714 SUBBUILD_DIR
6716 The SUBBUILD_DIR argument can be provided to change the
6717 location of the sub-build created to perform the popula‐
6718 tion. The default value is ${CMAKE_CURRENT_BI‐
6719 NARY_DIR}/<lowercaseName>-subbuild and it would be un‐
6720 usual to need to override this default. If a relative
6721 path is specified, it will be interpreted as relative to
6722 CMAKE_CURRENT_BINARY_DIR. This option should not be con‐
6723 fused with the SOURCE_SUBDIR option which only affects
6724 the FetchContent_MakeAvailable() command.
6725 SOURCE_DIR, BINARY_DIR
6727 The SOURCE_DIR and BINARY_DIR arguments are supported by
6728 ExternalProject_Add(), but different default values are
6729 used by FetchContent_Populate(). SOURCE_DIR defaults to
6730 ${CMAKE_CURRENT_BINARY_DIR}/<lowercaseName>-src and BI‐
6731 NARY_DIR defaults to ${CMAKE_CURRENT_BINARY_DIR}/<lower‐
6732 caseName>-build. If a relative path is specified, it
6733 will be interpreted as relative to
6734 CMAKE_CURRENT_BINARY_DIR.
6735 In addition to the above explicit options, any other unrecog‐
6737 nized options are passed through unmodified to
6738 ExternalProject_Add() to perform the download, patch and update
6739 steps. The following options are explicitly prohibited (they
6740 are disabled by the FetchContent_Populate() command):
6741 • CONFIGURE_COMMAND
6743 • BUILD_COMMAND
6745 • INSTALL_COMMAND
6747 • TEST_COMMAND
6749 If using FetchContent_Populate() within CMake's script mode, be
6751 aware that the implementation sets up a sub-build which there‐
6752 fore requires a CMake generator and build tool to be available.
6753 If these cannot be found by default, then the CMAKE_GENERATOR
6754 and/or CMAKE_MAKE_PROGRAM variables will need to be set appro‐
6755 priately on the command line invoking the script.
6756 New in version 3.18: Added support for the DOWNLOAD_NO_EXTRACT
6758 option.
6759 FetchContent_GetProperties
6762 When using saved content details, a call to
6763 FetchContent_MakeAvailable() or FetchContent_Populate() records
6764 information in global properties which can be queried at any
6765 time. This information may include the source and binary direc‐
6766 tories associated with the content and also whether or not the
6767 content population has been processed during the current config‐
6768 ure run.
6769 FetchContent_GetProperties(
6771 <name>
6772 [SOURCE_DIR <srcDirVar>]
6773 [BINARY_DIR <binDirVar>]
6774 [POPULATED <doneVar>]
6775 )
6776 The SOURCE_DIR, BINARY_DIR and POPULATED options can be used to
6778 specify which properties should be retrieved. Each option ac‐
6779 cepts a value which is the name of the variable in which to
6780 store that property. Most of the time though, only <name> is
6781 given, in which case the call will then set the same variables
6782 as a call to FetchContent_MakeAvailable(name) or
6783 FetchContent_Populate(name). Note that the SOURCE_DIR and BI‐
6784 NARY_DIR values can be empty if the call is fulfilled by a
6785 dependency provider.
6786 This command is rarely needed when using
6788 FetchContent_MakeAvailable(). It is more commonly used as part
6789 of implementing the following pattern with
6790 FetchContent_Populate(), which ensures that the relevant vari‐
6791 ables will always be defined regardless of whether or not the
6792 population has been performed elsewhere in the project already:
6793 # Check if population has already been performed
6795 FetchContent_GetProperties(depname)
6796 if(NOT depname_POPULATED)
6797 # Fetch the content using previously declared details
6798 FetchContent_Populate(depname)
6799 # Set custom variables, policies, etc.
6801 # ...
6802 # Bring the populated content into the build
6804 add_subdirectory(${depname_SOURCE_DIR} ${depname_BINARY_DIR})
6805 endif()
6806 FetchContent_SetPopulated
6808 New in version 3.24.
6809 NOTE:
6812 This command should only be called by dependency providers.
6813 Calling it in any other context is unsupported and future
6814 CMake versions may halt with a fatal error in such cases.
6815 FetchContent_SetPopulated(
6817 <name>
6818 [SOURCE_DIR <srcDir>]
6819 [BINARY_DIR <binDir>]
6820 )
6821 If a provider command fulfills a FETCHCONTENT_MAKEAVAILABLE_SE‐
6823 RIAL request, it must call this function before returning. The
6824 SOURCE_DIR and BINARY_DIR arguments can be used to specify the
6825 values that FetchContent_GetProperties() should return for its
6826 corresponding arguments. Only provide SOURCE_DIR and BINARY_DIR
6827 if they have the same meaning as if they had been populated by
6828 the built-in FetchContent_MakeAvailable() implementation.
6829 Variables
6831 A number of cache variables can influence the behavior where details
6832 from a FetchContent_Declare() call are used to populate content.
6833 NOTE:
6835 All of these variables are intended for the developer to customize
6836 behavior. They should not normally be set by the project.
6837 FETCHCONTENT_BASE_DIR
6839 In most cases, the saved details do not specify any options re‐
6840 lating to the directories to use for the internal sub-build, fi‐
6841 nal source and build areas. It is generally best to leave these
6842 decisions up to the FetchContent module to handle on the
6843 project's behalf. The FETCHCONTENT_BASE_DIR cache variable con‐
6844 trols the point under which all content population directories
6845 are collected, but in most cases, developers would not need to
6846 change this. The default location is ${CMAKE_BINARY_DIR}/_deps,
6847 but if developers change this value, they should aim to keep the
6848 path short and just below the top level of the build tree to
6849 avoid running into path length problems on Windows.
6850 FETCHCONTENT_QUIET
6852 The logging output during population can be quite verbose, mak‐
6853 ing the configure stage quite noisy. This cache option (ON by
6854 default) hides all population output unless an error is encoun‐
6855 tered. If experiencing problems with hung downloads, temporar‐
6856 ily switching this option off may help diagnose which content
6857 population is causing the issue.
6858 FETCHCONTENT_FULLY_DISCONNECTED
6860 When this option is enabled, no attempt is made to download or
6861 update any content. It is assumed that all content has already
6862 been populated in a previous run or the source directories have
6863 been pointed at existing contents the developer has provided
6864 manually (using options described further below). When the de‐
6865 veloper knows that no changes have been made to any content de‐
6866 tails, turning this option ON can significantly speed up the
6867 configure stage. It is OFF by default.
6868 FETCHCONTENT_UPDATES_DISCONNECTED
6870 This is a less severe download/update control compared to
6871 FETCHCONTENT_FULLY_DISCONNECTED. Instead of bypassing all down‐
6872 load and update logic, FETCHCONTENT_UPDATES_DISCONNECTED only
6873 disables the update stage. Therefore, if content has not been
6874 downloaded previously, it will still be downloaded when this op‐
6875 tion is enabled. This can speed up the configure stage, but not
6876 as much as FETCHCONTENT_FULLY_DISCONNECTED. It is OFF by de‐
6877 fault.
6878 FETCHCONTENT_TRY_FIND_PACKAGE_MODE
6880 New in version 3.24.
6881 This variable modifies the details that FetchContent_Declare()
6884 records for a given dependency. While it ultimately controls
6885 the behavior of FetchContent_MakeAvailable(), it is the vari‐
6886 able's value when FetchContent_Declare() is called that gets
6887 used. It makes no difference what the variable is set to when
6888 FetchContent_MakeAvailable() is called. Since the variable
6889 should only be set by the user and not by projects directly, it
6890 will typically have the same value throughout anyway, so this
6891 distinction is not usually noticeable.
6892 FETCHCONTENT_TRY_FIND_PACKAGE_MODE ultimately controls whether
6894 FetchContent_MakeAvailable() is allowed to call find_package()
6895 to satisfy a dependency. The variable can be set to one of the
6896 following values:
6897 OPT_IN FetchContent_MakeAvailable() will only call
6899 find_package() if the FetchContent_Declare() call in‐
6900 cluded a FIND_PACKAGE_ARGS keyword. This is also the de‐
6901 fault behavior if FETCHCONTENT_TRY_FIND_PACKAGE_MODE is
6902 not set.
6903 ALWAYS find_package() can be called by
6905 FetchContent_MakeAvailable() regardless of whether the
6906 FetchContent_Declare() call included a FIND_PACKAGE_ARGS
6907 keyword or not. If no FIND_PACKAGE_ARGS keyword was
6908 given, the behavior will be as though FIND_PACKAGE_ARGS
6909 had been provided, with no additional arguments after it.
6910 NEVER FetchContent_MakeAvailable() will not call
6912 find_package(). Any FIND_PACKAGE_ARGS given to the
6913 FetchContent_Declare() call will be ignored.
6914 As a special case, if the
6916 FETCHCONTENT_SOURCE_DIR_<uppercaseName> variable has a non-empty
6917 value for a dependency, it is assumed that the user is overrid‐
6918 ing all other methods of making that dependency available.
6919 FETCHCONTENT_TRY_FIND_PACKAGE_MODE will have no effect on that
6920 dependency and FetchContent_MakeAvailable() will not try to call
6921 find_package() for it.
6922 In addition to the above, the following variables are also defined for
6924 each content name:
6925 FETCHCONTENT_SOURCE_DIR_<uppercaseName>
6927 If this is set, no download or update steps are performed for
6928 the specified content and the <lowercaseName>_SOURCE_DIR vari‐
6929 able returned to the caller is pointed at this location. This
6930 gives developers a way to have a separate checkout of the con‐
6931 tent that they can modify freely without interference from the
6932 build. The build simply uses that existing source, but it still
6933 defines <lowercaseName>_BINARY_DIR to point inside its own build
6934 area. Developers are strongly encouraged to use this mechanism
6935 rather than editing the sources populated in the default loca‐
6936 tion, as changes to sources in the default location can be lost
6937 when content population details are changed by the project.
6938 FETCHCONTENT_UPDATES_DISCONNECTED_<uppercaseName>
6940 This is the per-content equivalent of
6941 FETCHCONTENT_UPDATES_DISCONNECTED. If the global option or this
6942 option is ON, then updates will be disabled for the named con‐
6943 tent. Disabling updates for individual content can be useful
6944 for content whose details rarely change, while still leaving
6945 other frequently changing content with updates enabled.
6946 Examples
6948 Typical Case
6949 This first fairly straightforward example ensures that some popular
6950 testing frameworks are available to the main build:
6951 include(FetchContent)
6953 FetchContent_Declare(
6954 googletest
6955 GIT_REPOSITORY https://github.com/google/googletest.git
6956 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
6957 )
6958 FetchContent_Declare(
6959 Catch2
6960 GIT_REPOSITORY https://github.com/catchorg/Catch2.git
6961 GIT_TAG de6fe184a9ac1a06895cdd1c9b437f0a0bdf14ad # v2.13.4
6962 )
6963 # After the following call, the CMake targets defined by googletest and
6965 # Catch2 will be available to the rest of the build
6966 FetchContent_MakeAvailable(googletest Catch2)
6967 Integrating With find_package()
6969 For the previous example, if the user wanted to try to find googletest
6970 and Catch2 via find_package() first before trying to download and build
6971 them from source, they could set the FETCHCONTENT_TRY_FIND_PACKAGE_MODE
6972 variable to ALWAYS. This would also affect any other calls to
6973 FetchContent_Declare() throughout the project, which might not be ac‐
6974 ceptable. The behavior can be enabled for just these two dependencies
6975 instead by adding FIND_PACKAGE_ARGS to the declared details and leaving
6976 FETCHCONTENT_TRY_FIND_PACKAGE_MODE unset, or set to OPT_IN:
6977 include(FetchContent)
6979 FetchContent_Declare(
6980 googletest
6981 GIT_REPOSITORY https://github.com/google/googletest.git
6982 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
6983 FIND_PACKAGE_ARGS NAMES GTest
6984 )
6985 FetchContent_Declare(
6986 Catch2
6987 GIT_REPOSITORY https://github.com/catchorg/Catch2.git
6988 GIT_TAG de6fe184a9ac1a06895cdd1c9b437f0a0bdf14ad # v2.13.4
6989 FIND_PACKAGE_ARGS
6990 )
6991 # This will try calling find_package() first for both dependencies
6993 FetchContent_MakeAvailable(googletest Catch2)
6994 For Catch2, no additional arguments to find_package() are needed, so no
6996 additional arguments are provided after the FIND_PACKAGE_ARGS keyword.
6997 For googletest, its package is more commonly called GTest, so arguments
6998 are added to support it being found by that name.
6999 If the user wanted to disable FetchContent_MakeAvailable() from calling
7001 find_package() for any dependency, even if it provided FIND_PACK‐
7002 AGE_ARGS in its declared details, they could set
7003 FETCHCONTENT_TRY_FIND_PACKAGE_MODE to NEVER.
7004 If the project wanted to indicate that these two dependencies should be
7006 downloaded and built from source and that find_package() calls should
7007 be redirected to use the built dependencies, the OVERRIDE_FIND_PACKAGE
7008 option should be used when declaring the content details:
7009 include(FetchContent)
7011 FetchContent_Declare(
7012 googletest
7013 GIT_REPOSITORY https://github.com/google/googletest.git
7014 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
7015 OVERRIDE_FIND_PACKAGE
7016 )
7017 FetchContent_Declare(
7018 Catch2
7019 GIT_REPOSITORY https://github.com/catchorg/Catch2.git
7020 GIT_TAG de6fe184a9ac1a06895cdd1c9b437f0a0bdf14ad # v2.13.4
7021 OVERRIDE_FIND_PACKAGE
7022 )
7023 # The following will automatically forward through to FetchContent_MakeAvailable()
7025 find_package(googletest)
7026 find_package(Catch2)
7027 CMake provides a FindGTest module which defines some variables that
7029 older projects may use instead of linking to the imported targets. To
7030 support those cases, we can provide an extra file. In keeping with the
7031 "first to define, wins" philosophy of FetchContent, we only write out
7032 that file if something else hasn't already done so.
7033 FetchContent_MakeAvailable(googletest)
7035 if(NOT EXISTS ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/googletest-extra.cmake AND
7037 NOT EXISTS ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/googletestExtra.cmake)
7038 file(WRITE ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/googletest-extra.cmake
7039 [=[
7040 if("${GTEST_LIBRARIES}" STREQUAL "" AND TARGET GTest::gtest)
7041 set(GTEST_LIBRARIES GTest::gtest)
7042 endif()
7043 if("${GTEST_MAIN_LIBRARIES}" STREQUAL "" AND TARGET GTest::gtest_main)
7044 set(GTEST_MAIN_LIBRARIES GTest::gtest_main)
7045 endif()
7046 if("${GTEST_BOTH_LIBRARIES}" STREQUAL "")
7047 set(GTEST_BOTH_LIBRARIES ${GTEST_LIBRARIES} ${GTEST_MAIN_LIBRARIES})
7048 endif()
7049 ]=])
7050 endif()
7051 Projects will also likely be using find_package(GTest) rather than
7053 find_package(googletest), but it is possible to make use of the
7054 CMAKE_FIND_PACKAGE_REDIRECTS_DIR area to pull in the latter as a depen‐
7055 dency of the former. This is likely to be sufficient to satisfy a typ‐
7056 ical find_package(GTest) call.
7057 FetchContent_MakeAvailable(googletest)
7059 if(NOT EXISTS ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/gtest-config.cmake AND
7061 NOT EXISTS ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/GTestConfig.cmake)
7062 file(WRITE ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/gtest-config.cmake
7063 [=[
7064 include(CMakeFindDependencyMacro)
7065 find_dependency(googletest)
7066 ]=])
7067 endif()
7068 if(NOT EXISTS ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/gtest-config-version.cmake AND
7070 NOT EXISTS ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/GTestConfigVersion.cmake)
7071 file(WRITE ${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/gtest-config-version.cmake
7072 [=[
7073 include(${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/googletest-config-version.cmake OPTIONAL)
7074 if(NOT PACKAGE_VERSION_COMPATIBLE)
7075 include(${CMAKE_FIND_PACKAGE_REDIRECTS_DIR}/googletestConfigVersion.cmake OPTIONAL)
7076 endif()
7077 ]=])
7078 endif()
7079 Overriding Where To Find CMakeLists.txt
7081 If the sub-project's CMakeLists.txt file is not at the top level of its
7082 source tree, the SOURCE_SUBDIR option can be used to tell FetchContent
7083 where to find it. The following example shows how to use that option,
7084 and it also sets a variable which is meaningful to the subproject be‐
7085 fore pulling it into the main build (set as an INTERNAL cache variable
7086 to avoid problems with policy CMP0077):
7087 include(FetchContent)
7089 FetchContent_Declare(
7090 protobuf
7091 GIT_REPOSITORY https://github.com/protocolbuffers/protobuf.git
7092 GIT_TAG ae50d9b9902526efd6c7a1907d09739f959c6297 # v3.15.0
7093 SOURCE_SUBDIR cmake
7094 )
7095 set(protobuf_BUILD_TESTS OFF CACHE INTERNAL "")
7096 FetchContent_MakeAvailable(protobuf)
7097 Complex Dependency Hierarchies
7099 In more complex project hierarchies, the dependency relationships can
7100 be more complicated. Consider a hierarchy where projA is the top level
7101 project and it depends directly on projects projB and projC. Both
7102 projB and projC can be built standalone and they also both depend on
7103 another project projD. projB additionally depends on projE. This ex‐
7104 ample assumes that all five projects are available on a company git
7105 server. The CMakeLists.txt of each project might have sections like
7106 the following:
7107 projA:
7109 include(FetchContent)
7111 FetchContent_Declare(
7112 projB
7113 GIT_REPOSITORY git@mycompany.com:git/projB.git
7114 GIT_TAG 4a89dc7e24ff212a7b5167bef7ab079d
7115 )
7116 FetchContent_Declare(
7117 projC
7118 GIT_REPOSITORY git@mycompany.com:git/projC.git
7119 GIT_TAG 4ad4016bd1d8d5412d135cf8ceea1bb9
7120 )
7121 FetchContent_Declare(
7122 projD
7123 GIT_REPOSITORY git@mycompany.com:git/projD.git
7124 GIT_TAG origin/integrationBranch
7125 )
7126 FetchContent_Declare(
7127 projE
7128 GIT_REPOSITORY git@mycompany.com:git/projE.git
7129 GIT_TAG v2.3-rc1
7130 )
7131 # Order is important, see notes in the discussion further below
7133 FetchContent_MakeAvailable(projD projB projC)
7134 projB:
7136 include(FetchContent)
7138 FetchContent_Declare(
7139 projD
7140 GIT_REPOSITORY git@mycompany.com:git/projD.git
7141 GIT_TAG 20b415f9034bbd2a2e8216e9a5c9e632
7142 )
7143 FetchContent_Declare(
7144 projE
7145 GIT_REPOSITORY git@mycompany.com:git/projE.git
7146 GIT_TAG 68e20f674a48be38d60e129f600faf7d
7147 )
7148 FetchContent_MakeAvailable(projD projE)
7150 projC:
7152 include(FetchContent)
7154 FetchContent_Declare(
7155 projD
7156 GIT_REPOSITORY git@mycompany.com:git/projD.git
7157 GIT_TAG 7d9a17ad2c962aa13e2fbb8043fb6b8a
7158 )
7159 # This particular version of projD requires workarounds
7161 FetchContent_GetProperties(projD)
7162 if(NOT projd_POPULATED)
7163 FetchContent_Populate(projD)
7164 # Copy an additional/replacement file into the populated source
7166 file(COPY someFile.c DESTINATION ${projd_SOURCE_DIR}/src)
7167 add_subdirectory(${projd_SOURCE_DIR} ${projd_BINARY_DIR})
7169 endif()
7170 A few key points should be noted in the above:
7172 • projB and projC define different content details for projD, but projA
7174 also defines a set of content details for projD. Because projA will
7175 define them first, the details from projB and projC will not be used.
7176 The override details defined by projA are not required to match ei‐
7177 ther of those from projB or projC, but it is up to the higher level
7178 project to ensure that the details it does define still make sense
7179 for the child projects.
7180 • In the projA call to FetchContent_MakeAvailable(), projD is listed
7182 ahead of projB and projC to ensure that projA is in control of how
7183 projD is populated.
7184 • While projA defines content details for projE, it does not need to
7186 explicitly call FetchContent_MakeAvailable(projE) or FetchCon‐
7187 tent_Populate(projD) itself. Instead, it leaves that to the child
7188 projB. For higher level projects, it is often enough to just define
7189 the override content details and leave the actual population to the
7190 child projects. This saves repeating the same thing at each level of
7191 the project hierarchy unnecessarily.
7192 Populating Content Without Adding It To The Build
7194 Projects don't always need to add the populated content to the build.
7195 Sometimes the project just wants to make the downloaded content avail‐
7196 able at a predictable location. The next example ensures that a set of
7197 standard company toolchain files (and potentially even the toolchain
7198 binaries themselves) is available early enough to be used for that same
7199 build.
7200 cmake_minimum_required(VERSION 3.14)
7202 include(FetchContent)
7204 FetchContent_Declare(
7205 mycom_toolchains
7206 URL https://intranet.mycompany.com//toolchains_1.3.2.tar.gz
7207 )
7208 FetchContent_MakeAvailable(mycom_toolchains)
7209 project(CrossCompileExample)
7211 The project could be configured to use one of the downloaded toolchains
7213 like so:
7214 cmake -DCMAKE_TOOLCHAIN_FILE=_deps/mycom_toolchains-src/toolchain_arm.cmake /path/to/src
7216 When CMake processes the CMakeLists.txt file, it will download and un‐
7218 pack the tarball into _deps/mycompany_toolchains-src relative to the
7219 build directory. The CMAKE_TOOLCHAIN_FILE variable is not used until
7220 the project() command is reached, at which point CMake looks for the
7221 named toolchain file relative to the build directory. Because the tar‐
7222 ball has already been downloaded and unpacked by then, the toolchain
7223 file will be in place, even the very first time that cmake is run in
7224 the build directory.
7225 Populating Content In CMake Script Mode
7227 This last example demonstrates how one might download and unpack a
7228 firmware tarball using CMake's script mode. The call to
7229 FetchContent_Populate() specifies all the content details and the un‐
7230 packed firmware will be placed in a firmware directory below the cur‐
7231 rent working directory.
7232 getFirmware.cmake:
7234 # NOTE: Intended to be run in script mode with cmake -P
7236 include(FetchContent)
7237 FetchContent_Populate(
7238 firmware
7239 URL https://mycompany.com/assets/firmware-1.23-arm.tar.gz
7240 URL_HASH MD5=68247684da89b608d466253762b0ff11
7241 SOURCE_DIR firmware
7242 )
7243 FindPackageHandleStandardArgs
7245 This module provides functions intended to be used in Find Modules im‐
7246 plementing find_package(<PackageName>) calls.
7247 find_package_handle_standard_args
7249 This command handles the REQUIRED, QUIET and version-related ar‐
7250 guments of find_package(). It also sets the <PackageName>_FOUND
7251 variable. The package is considered found if all variables
7252 listed contain valid results, e.g. valid filepaths.
7253 There are two signatures:
7255 find_package_handle_standard_args(<PackageName>
7257 (DEFAULT_MSG|<custom-failure-message>)
7258 <required-var>...
7259 )
7260 find_package_handle_standard_args(<PackageName>
7262 [FOUND_VAR <result-var>]
7263 [REQUIRED_VARS <required-var>...]
7264 [VERSION_VAR <version-var>]
7265 [HANDLE_VERSION_RANGE]
7266 [HANDLE_COMPONENTS]
7267 [CONFIG_MODE]
7268 [NAME_MISMATCHED]
7269 [REASON_FAILURE_MESSAGE <reason-failure-message>]
7270 [FAIL_MESSAGE <custom-failure-message>]
7271 )
7272 The <PackageName>_FOUND variable will be set to TRUE if all the
7274 variables <required-var>... are valid and any optional con‐
7275 straints are satisfied, and FALSE otherwise. A success or fail‐
7276 ure message may be displayed based on the results and on whether
7277 the REQUIRED and/or QUIET option was given to the find_package()
7278 call.
7279 The options are:
7281 (DEFAULT_MSG|<custom-failure-message>)
7283 In the simple signature this specifies the failure mes‐
7284 sage. Use DEFAULT_MSG to ask for a default message to be
7285 computed (recommended). Not valid in the full signature.
7286 FOUND_VAR <result-var>
7288 Deprecated since version 3.3.
7289 Specifies either <PackageName>_FOUND or <PACKAGE‐
7292 NAME>_FOUND as the result variable. This exists only for
7293 compatibility with older versions of CMake and is now ig‐
7294 nored. Result variables of both names are always set for
7295 compatibility.
7296 REQUIRED_VARS <required-var>...
7298 Specify the variables which are required for this pack‐
7299 age. These may be named in the generated failure message
7300 asking the user to set the missing variable values.
7301 Therefore these should typically be cache entries such as
7302 FOO_LIBRARY and not output variables like FOO_LIBRARIES.
7303 Changed in version 3.18: If HANDLE_COMPONENTS is speci‐
7305 fied, this option can be omitted.
7306 VERSION_VAR <version-var>
7309 Specify the name of a variable that holds the version of
7310 the package that has been found. This version will be
7311 checked against the (potentially) specified required ver‐
7312 sion given to the find_package() call, including its EX‐
7313 ACT option. The default messages include information
7314 about the required version and the version which has been
7315 actually found, both if the version is ok or not.
7316 HANDLE_VERSION_RANGE
7318 New in version 3.19.
7319 Enable handling of a version range, if one is specified.
7322 Without this option, a developer warning will be dis‐
7323 played if a version range is specified.
7324 HANDLE_COMPONENTS
7326 Enable handling of package components. In this case, the
7327 command will report which components have been found and
7328 which are missing, and the <PackageName>_FOUND variable
7329 will be set to FALSE if any of the required components
7330 (i.e. not the ones listed after the OPTIONAL_COMPONENTS
7331 option of find_package()) are missing.
7332 CONFIG_MODE
7334 Specify that the calling find module is a wrapper around
7335 a call to find_package(<PackageName> NO_MODULE). This
7336 implies a VERSION_VAR value of <PackageName>_VERSION.
7337 The command will automatically check whether the package
7338 configuration file was found.
7339 REASON_FAILURE_MESSAGE <reason-failure-message>
7341 New in version 3.16.
7342 Specify a custom message of the reason for the failure
7345 which will be appended to the default generated message.
7346 FAIL_MESSAGE <custom-failure-message>
7348 Specify a custom failure message instead of using the de‐
7349 fault generated message. Not recommended.
7350 NAME_MISMATCHED
7352 New in version 3.17.
7353 Indicate that the <PackageName> does not match
7356 ${CMAKE_FIND_PACKAGE_NAME}. This is usually a mistake and
7357 raises a warning, but it may be intentional for usage of
7358 the command for components of a larger package.
7359 Example for the simple signature:
7361 find_package_handle_standard_args(LibXml2 DEFAULT_MSG
7363 LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
7364 The LibXml2 package is considered to be found if both LIBXML2_LIBRARY
7366 and LIBXML2_INCLUDE_DIR are valid. Then also LibXml2_FOUND is set to
7367 TRUE. If it is not found and REQUIRED was used, it fails with a
7368 message(FATAL_ERROR), independent whether QUIET was used or not. If it
7369 is found, success will be reported, including the content of the first
7370 <required-var>. On repeated CMake runs, the same message will not be
7371 printed again.
7372 NOTE:
7374 If <PackageName> does not match CMAKE_FIND_PACKAGE_NAME for the
7375 calling module, a warning that there is a mismatch is given. The
7376 FPHSA_NAME_MISMATCHED variable may be set to bypass the warning if
7377 using the old signature and the NAME_MISMATCHED argument using the
7378 new signature. To avoid forcing the caller to require newer versions
7379 of CMake for usage, the variable's value will be used if defined
7380 when the NAME_MISMATCHED argument is not passed for the new signa‐
7381 ture (but using both is an error)..
7382 Example for the full signature:
7384 find_package_handle_standard_args(LibArchive
7386 REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
7387 VERSION_VAR LibArchive_VERSION)
7388 In this case, the LibArchive package is considered to be found if both
7390 LibArchive_LIBRARY and LibArchive_INCLUDE_DIR are valid. Also the ver‐
7391 sion of LibArchive will be checked by using the version contained in
7392 LibArchive_VERSION. Since no FAIL_MESSAGE is given, the default mes‐
7393 sages will be printed.
7394 Another example for the full signature:
7396 find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
7398 find_package_handle_standard_args(Automoc4 CONFIG_MODE)
7399 In this case, a FindAutmoc4.cmake module wraps a call to find_pack‐
7401 age(Automoc4 NO_MODULE) and adds an additional search directory for au‐
7402 tomoc4. Then the call to find_package_handle_standard_args produces a
7403 proper success/failure message.
7404 find_package_check_version
7406 New in version 3.19.
7407 Helper function which can be used to check if a <version> is
7410 valid against version-related arguments of find_package().
7411 find_package_check_version(<version> <result-var>
7413 [HANDLE_VERSION_RANGE]
7414 [RESULT_MESSAGE_VARIABLE <message-var>]
7415 )
7416 The <result-var> will hold a boolean value giving the result of
7418 the check.
7419 The options are:
7421 HANDLE_VERSION_RANGE
7423 Enable handling of a version range, if one is specified.
7424 Without this option, a developer warning will be dis‐
7425 played if a version range is specified.
7426 RESULT_MESSAGE_VARIABLE <message-var>
7428 Specify a variable to get back a message describing the
7429 result of the check.
7430 Example for the usage:
7432 find_package_check_version(1.2.3 result HANDLE_VERSION_RANGE
7434 RESULT_MESSAGE_VARIABLE reason)
7435 if (result)
7436 message (STATUS "${reason}")
7437 else()
7438 message (FATAL_ERROR "${reason}")
7439 endif()
7440 FindPackageMessage
7442 find_package_message(<name> "message for user" "find result details")
7443 This function is intended to be used in FindXXX.cmake modules files.
7445 It will print a message once for each unique find result. This is use‐
7446 ful for telling the user where a package was found. The first argument
7447 specifies the name (XXX) of the package. The second argument specifies
7448 the message to display. The third argument lists details about the
7449 find result so that if they change the message will be displayed again.
7450 The macro also obeys the QUIET argument to the find_package command.
7451 Example:
7453 if(X11_FOUND)
7455 find_package_message(X11 "Found X11: ${X11_X11_LIB}"
7456 "[${X11_X11_LIB}][${X11_INCLUDE_DIR}]")
7457 else()
7458 ...
7459 endif()
7460 FortranCInterface
7462 Fortran/C Interface Detection
7463 This module automatically detects the API by which C and Fortran lan‐
7465 guages interact.
7466 Module Variables
7468 Variables that indicate if the mangling is found:
7469 FortranCInterface_GLOBAL_FOUND
7471 Global subroutines and functions.
7472 FortranCInterface_MODULE_FOUND
7474 Module subroutines and functions (declared by "MODULE PROCE‐
7475 DURE").
7476 This module also provides the following variables to specify the de‐
7478 tected mangling, though a typical use case does not need to reference
7479 them and can use the Module Functions below.
7480 FortranCInterface_GLOBAL_PREFIX
7482 Prefix for a global symbol without an underscore.
7483 FortranCInterface_GLOBAL_SUFFIX
7485 Suffix for a global symbol without an underscore.
7486 FortranCInterface_GLOBAL_CASE
7488 The case for a global symbol without an underscore, either UPPER
7489 or LOWER.
7490 FortranCInterface_GLOBAL__PREFIX
7492 Prefix for a global symbol with an underscore.
7493 FortranCInterface_GLOBAL__SUFFIX
7495 Suffix for a global symbol with an underscore.
7496 FortranCInterface_GLOBAL__CASE
7498 The case for a global symbol with an underscore, either UPPER or
7499 LOWER.
7500 FortranCInterface_MODULE_PREFIX
7502 Prefix for a module symbol without an underscore.
7503 FortranCInterface_MODULE_MIDDLE
7505 Middle of a module symbol without an underscore that appears be‐
7506 tween the name of the module and the name of the symbol.
7507 FortranCInterface_MODULE_SUFFIX
7509 Suffix for a module symbol without an underscore.
7510 FortranCInterface_MODULE_CASE
7512 The case for a module symbol without an underscore, either UPPER
7513 or LOWER.
7514 FortranCInterface_MODULE__PREFIX
7516 Prefix for a module symbol with an underscore.
7517 FortranCInterface_MODULE__MIDDLE
7519 Middle of a module symbol with an underscore that appears be‐
7520 tween the name of the module and the name of the symbol.
7521 FortranCInterface_MODULE__SUFFIX
7523 Suffix for a module symbol with an underscore.
7524 FortranCInterface_MODULE__CASE
7526 The case for a module symbol with an underscore, either UPPER or
7527 LOWER.
7528 Module Functions
7530 FortranCInterface_HEADER
7531 The FortranCInterface_HEADER function is provided to generate a
7532 C header file containing macros to mangle symbol names:
7533 FortranCInterface_HEADER(<file>
7535 [MACRO_NAMESPACE <macro-ns>]
7536 [SYMBOL_NAMESPACE <ns>]
7537 [SYMBOLS [<module>:]<function> ...])
7538 It generates in <file> definitions of the following macros:
7540 #define FortranCInterface_GLOBAL (name,NAME) ...
7542 #define FortranCInterface_GLOBAL_(name,NAME) ...
7543 #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
7544 #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
7545 These macros mangle four categories of Fortran symbols, respec‐
7547 tively:
7548 • Global symbols without '_': call mysub()
7550 • Global symbols with '_' : call my_sub()
7552 • Module symbols without '_': use mymod; call mysub()
7554 • Module symbols with '_' : use mymod; call my_sub()
7556 If mangling for a category is not known, its macro is left unde‐
7558 fined. All macros require raw names in both lower case and up‐
7559 per case.
7560 The options are:
7562 MACRO_NAMESPACE
7564 Replace the default FortranCInterface_ prefix with a
7565 given namespace <macro-ns>.
7566 SYMBOLS
7568 List symbols to mangle automatically with C preprocessor
7569 definitions:
7570 <function> ==> #define <ns><function> ...
7572 <module>:<function> ==> #define <ns><module>_<function> ...
7573 If the mangling for some symbol is not known then no pre‐
7575 processor definition is created, and a warning is dis‐
7576 played.
7577 SYMBOL_NAMESPACE
7579 Prefix all preprocessor definitions generated by the SYM‐
7580 BOLS option with a given namespace <ns>.
7581 FortranCInterface_VERIFY
7583 The FortranCInterface_VERIFY function is provided to verify that
7584 the Fortran and C/C++ compilers work together:
7585 FortranCInterface_VERIFY([CXX] [QUIET])
7587 It tests whether a simple test executable using Fortran and C
7589 (and C++ when the CXX option is given) compiles and links suc‐
7590 cessfully. The result is stored in the cache entry FortranCIn‐
7591 terface_VERIFIED_C (or FortranCInterface_VERIFIED_CXX if CXX is
7592 given) as a boolean. If the check fails and QUIET is not given
7593 the function terminates with a fatal error message describing
7594 the problem. The purpose of this check is to stop a build early
7595 for incompatible compiler combinations. The test is built in
7596 the Release configuration.
7597 Example Usage
7599 include(FortranCInterface)
7600 FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
7601 This creates a "FC.h" header that defines mangling macros FC_GLOBAL(),
7603 FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
7604 include(FortranCInterface)
7606 FortranCInterface_HEADER(FCMangle.h
7607 MACRO_NAMESPACE "FC_"
7608 SYMBOL_NAMESPACE "FC_"
7609 SYMBOLS mysub mymod:my_sub)
7610 This creates a "FCMangle.h" header that defines the same FC_*() man‐
7612 gling macros as the previous example plus preprocessor symbols FC_mysub
7613 and FC_mymod_my_sub.
7614 Additional Manglings
7616 FortranCInterface is aware of possible GLOBAL and MODULE manglings for
7617 many Fortran compilers, but it also provides an interface to specify
7618 new possible manglings. Set the variables:
7619 FortranCInterface_GLOBAL_SYMBOLS
7621 FortranCInterface_MODULE_SYMBOLS
7622 before including FortranCInterface to specify manglings of the symbols
7624 MySub, My_Sub, MyModule:MySub, and My_Module:My_Sub. For example, the
7625 code:
7626 set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
7628 # ^^^^^ ^^^^^^ ^^^^^
7629 set(FortranCInterface_MODULE_SYMBOLS
7630 __mymodule_MOD_mysub __my_module_MOD_my_sub)
7631 # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^
7632 include(FortranCInterface)
7633 tells FortranCInterface to try given GLOBAL and MODULE manglings. (The
7635 carets point at raw symbol names for clarity in this example but are
7636 not needed.)
7637 GenerateExportHeader
7639 Function for generation of export macros for libraries
7640 This module provides the function GENERATE_EXPORT_HEADER().
7642 New in version 3.12: Added support for C projects. Previous versions
7644 supported C++ project only.
7645 The GENERATE_EXPORT_HEADER function can be used to generate a file
7648 suitable for preprocessor inclusion which contains EXPORT macros to be
7649 used in library classes:
7650 GENERATE_EXPORT_HEADER( LIBRARY_TARGET
7652 [BASE_NAME <base_name>]
7653 [EXPORT_MACRO_NAME <export_macro_name>]
7654 [EXPORT_FILE_NAME <export_file_name>]
7655 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
7656 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
7657 [INCLUDE_GUARD_NAME <include_guard_name>]
7658 [STATIC_DEFINE <static_define>]
7659 [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
7660 [DEFINE_NO_DEPRECATED]
7661 [PREFIX_NAME <prefix_name>]
7662 [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
7663 )
7664 The target properties CXX_VISIBILITY_PRESET and
7666 VISIBILITY_INLINES_HIDDEN can be used to add the appropriate compile
7667 flags for targets. See the documentation of those target properties,
7668 and the convenience variables CMAKE_CXX_VISIBILITY_PRESET and
7669 CMAKE_VISIBILITY_INLINES_HIDDEN.
7670 By default GENERATE_EXPORT_HEADER() generates macro names in a file
7672 name determined by the name of the library. This means that in the
7673 simplest case, users of GenerateExportHeader will be equivalent to:
7674 set(CMAKE_CXX_VISIBILITY_PRESET hidden)
7676 set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
7677 add_library(somelib someclass.cpp)
7678 generate_export_header(somelib)
7679 install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR})
7680 install(FILES
7681 someclass.h
7682 ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${INCLUDE_INSTALL_DIR}
7683 )
7684 And in the ABI header files:
7686 #include "somelib_export.h"
7688 class SOMELIB_EXPORT SomeClass {
7689 ...
7690 };
7691 The CMake fragment will generate a file in the ${CMAKE_CURRENT_BI‐
7693 NARY_DIR} called somelib_export.h containing the macros SOMELIB_EXPORT,
7694 SOMELIB_NO_EXPORT, SOMELIB_DEPRECATED, SOMELIB_DEPRECATED_EXPORT and
7695 SOMELIB_DEPRECATED_NO_EXPORT. They will be followed by content taken
7696 from the variable specified by the CUSTOM_CONTENT_FROM_VARIABLE option,
7697 if any. The resulting file should be installed with other headers in
7698 the library.
7699 The BASE_NAME argument can be used to override the file name and the
7701 names used for the macros:
7702 add_library(somelib someclass.cpp)
7704 generate_export_header(somelib
7705 BASE_NAME other_name
7706 )
7707 Generates a file called other_name_export.h containing the macros
7709 OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT and OTHER_NAME_DEPRECATED etc.
7710 The BASE_NAME may be overridden by specifying other options in the
7712 function. For example:
7713 add_library(somelib someclass.cpp)
7715 generate_export_header(somelib
7716 EXPORT_MACRO_NAME OTHER_NAME_EXPORT
7717 )
7718 creates the macro OTHER_NAME_EXPORT instead of SOMELIB_EXPORT, but
7720 other macros and the generated file name is as default:
7721 add_library(somelib someclass.cpp)
7723 generate_export_header(somelib
7724 DEPRECATED_MACRO_NAME KDE_DEPRECATED
7725 )
7726 creates the macro KDE_DEPRECATED instead of SOMELIB_DEPRECATED.
7728 If LIBRARY_TARGET is a static library, macros are defined without val‐
7730 ues.
7731 If the same sources are used to create both a shared and a static li‐
7733 brary, the uppercased symbol ${BASE_NAME}_STATIC_DEFINE should be used
7734 when building the static library:
7735 add_library(shared_variant SHARED ${lib_SRCS})
7737 add_library(static_variant ${lib_SRCS})
7738 generate_export_header(shared_variant BASE_NAME libshared_and_static)
7739 set_target_properties(static_variant PROPERTIES
7740 COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)
7741 This will cause the export macros to expand to nothing when building
7743 the static library.
7744 If DEFINE_NO_DEPRECATED is specified, then a macro ${BASE_NAME}_NO_DEP‐
7746 RECATED will be defined This macro can be used to remove deprecated
7747 code from preprocessor output:
7748 option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
7750 if (EXCLUDE_DEPRECATED)
7751 set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED)
7752 endif()
7753 generate_export_header(somelib ${NO_BUILD_DEPRECATED})
7754 And then in somelib:
7756 class SOMELIB_EXPORT SomeClass
7758 {
7759 public:
7760 #ifndef SOMELIB_NO_DEPRECATED
7761 SOMELIB_DEPRECATED void oldMethod();
7762 #endif
7763 };
7764 #ifndef SOMELIB_NO_DEPRECATED
7766 void SomeClass::oldMethod() { }
7767 #endif
7768 If PREFIX_NAME is specified, the argument will be used as a prefix to
7770 all generated macros.
7771 For example:
7773 generate_export_header(somelib PREFIX_NAME VTK_)
7775 Generates the macros VTK_SOMELIB_EXPORT etc.
7777 New in version 3.1: Library target can be an OBJECT library.
7779 New in version 3.7: Added the CUSTOM_CONTENT_FROM_VARIABLE option.
7782 New in version 3.11: Added the INCLUDE_GUARD_NAME option.
7785 ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
7788 Deprecated since version 3.0: Set the target properties
7790 CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HIDDEN instead.
7791 The ADD_COMPILER_EXPORT_FLAGS function adds -fvisibility=hidden to
7794 CMAKE_CXX_FLAGS if supported, and is a no-op on Windows which does not
7795 need extra compiler flags for exporting support. You may optionally
7796 pass a single argument to ADD_COMPILER_EXPORT_FLAGS that will be popu‐
7797 lated with the CXX_FLAGS required to enable visibility support for the
7798 compiler/architecture in use.
7799 GetPrerequisites
7801 Deprecated since version 3.16: Use file(GET_RUNTIME_DEPENDENCIES) in‐
7802 stead.
7803 Functions to analyze and list executable file prerequisites.
7806 This module provides functions to list the .dll, .dylib or .so files
7808 that an executable or shared library file depends on. (Its prerequi‐
7809 sites.)
7810 It uses various tools to obtain the list of required shared library
7812 files:
7813 dumpbin (Windows)
7815 objdump (MinGW on Windows)
7816 ldd (Linux/Unix)
7817 otool (Mac OSX)
7818 Changed in version 3.16: The tool specified by CMAKE_OBJDUMP will be
7820 used, if set.
7821 The following functions are provided by this module:
7824 get_prerequisites
7826 list_prerequisites
7827 list_prerequisites_by_glob
7828 gp_append_unique
7829 is_file_executable
7830 gp_item_default_embedded_path
7831 (projects can override with gp_item_default_embedded_path_override)
7832 gp_resolve_item
7833 (projects can override with gp_resolve_item_override)
7834 gp_resolved_file_type
7835 (projects can override with gp_resolved_file_type_override)
7836 gp_file_type
7837 GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse>
7839 <exepath> <dirs> [<rpaths>])
7840 Get the list of shared library files required by <target>. The list in
7842 the variable named <prerequisites_var> should be empty on first entry
7843 to this function. On exit, <prerequisites_var> will contain the list
7844 of required shared library files.
7845 <target> is the full path to an executable file. <prerequisites_var>
7847 is the name of a CMake variable to contain the results. <exclude_sys‐
7848 tem> must be 0 or 1 indicating whether to include or exclude "system"
7849 prerequisites. If <recurse> is set to 1 all prerequisites will be
7850 found recursively, if set to 0 only direct prerequisites are listed.
7851 <exepath> is the path to the top level executable used for @exe‐
7852 cutable_path replacement on the Mac. <dirs> is a list of paths where
7853 libraries might be found: these paths are searched first when a target
7854 without any path info is given. Then standard system locations are
7855 also searched: PATH, Framework locations, /usr/lib...
7856 New in version 3.14: The variable GET_PREREQUISITES_VERBOSE can be set
7858 to true to enable verbose output.
7859 LIST_PREREQUISITES(<target> [<recurse> [<exclude_system> [<verbose>]]])
7862 Print a message listing the prerequisites of <target>.
7864 <target> is the name of a shared library or executable target or the
7866 full path to a shared library or executable file. If <recurse> is set
7867 to 1 all prerequisites will be found recursively, if set to 0 only di‐
7868 rect prerequisites are listed. <exclude_system> must be 0 or 1 indi‐
7869 cating whether to include or exclude "system" prerequisites. With
7870 <verbose> set to 0 only the full path names of the prerequisites are
7871 printed, set to 1 extra information will be displayed.
7872 LIST_PREREQUISITES_BY_GLOB(<glob_arg> <glob_exp>)
7874 Print the prerequisites of shared library and executable files matching
7876 a globbing pattern. <glob_arg> is GLOB or GLOB_RECURSE and <glob_exp>
7877 is a globbing expression used with "file(GLOB" or "file(GLOB_RECURSE"
7878 to retrieve a list of matching files. If a matching file is exe‐
7879 cutable, its prerequisites are listed.
7880 Any additional (optional) arguments provided are passed along as the
7882 optional arguments to the list_prerequisites calls.
7883 GP_APPEND_UNIQUE(<list_var> <value>)
7885 Append <value> to the list variable <list_var> only if the value is not
7887 already in the list.
7888 IS_FILE_EXECUTABLE(<file> <result_var>)
7890 Return 1 in <result_var> if <file> is a binary executable, 0 otherwise.
7892 GP_ITEM_DEFAULT_EMBEDDED_PATH(<item> <default_embedded_path_var>)
7894 Return the path that others should refer to the item by when the item
7896 is embedded inside a bundle.
7897 Override on a per-project basis by providing a project-specific
7899 gp_item_default_embedded_path_override function.
7900 GP_RESOLVE_ITEM(<context> <item> <exepath> <dirs> <resolved_item_var>
7902 [<rpaths>])
7903 Resolve an item into an existing full path file.
7905 Override on a per-project basis by providing a project-specific gp_re‐
7907 solve_item_override function.
7908 GP_RESOLVED_FILE_TYPE(<original_file> <file> <exepath> <dirs> <type_var>
7910 [<rpaths>])
7911 Return the type of <file> with respect to <original_file>. String de‐
7913 scribing type of prerequisite is returned in variable named <type_var>.
7914 Use <exepath> and <dirs> if necessary to resolve non-absolute <file>
7916 values -- but only for non-embedded items.
7917 Possible types are:
7919 system
7921 local
7922 embedded
7923 other
7924 Override on a per-project basis by providing a project-specific gp_re‐
7926 solved_file_type_override function.
7927 GP_FILE_TYPE(<original_file> <file> <type_var>)
7929 Return the type of <file> with respect to <original_file>. String de‐
7931 scribing type of prerequisite is returned in variable named <type_var>.
7932 Possible types are:
7934 system
7936 local
7937 embedded
7938 other
7939 GNUInstallDirs
7941 Define GNU standard installation directories
7942 Provides install directory variables as defined by the GNU Coding Stan‐
7944 dards.
7945 Result Variables
7947 Inclusion of this module defines the following variables:
7948 CMAKE_INSTALL_<dir>
7950 Destination for files of a given type. This value may be passed to
7951 the DESTINATION options of install() commands for the corresponding
7952 file type. It should typically be a path relative to the installa‐
7953 tion prefix so that it can be converted to an absolute path in a re‐
7954 locatable way (see CMAKE_INSTALL_FULL_<dir>). However, an absolute
7955 path is also allowed.
7956 CMAKE_INSTALL_FULL_<dir>
7958 The absolute path generated from the corresponding CMAKE_IN‐
7959 STALL_<dir> value. If the value is not already an absolute path, an
7960 absolute path is constructed typically by prepending the value of
7961 the CMAKE_INSTALL_PREFIX variable. However, there are some special
7962 cases as documented below.
7963 where <dir> is one of:
7965 BINDIR user executables (bin)
7967 SBINDIR
7969 system admin executables (sbin)
7970 LIBEXECDIR
7972 program executables (libexec)
7973 SYSCONFDIR
7975 read-only single-machine data (etc)
7976 SHAREDSTATEDIR
7978 modifiable architecture-independent data (com)
7979 LOCALSTATEDIR
7981 modifiable single-machine data (var)
7982 RUNSTATEDIR
7984 New in version 3.9: run-time variable data (LOCALSTATEDIR/run)
7985 LIBDIR object code libraries (lib or lib64)
7988 On Debian, this may be lib/<multiarch-tuple> when
7990 CMAKE_INSTALL_PREFIX is /usr.
7991 INCLUDEDIR
7993 C header files (include)
7994 OLDINCLUDEDIR
7996 C header files for non-gcc (/usr/include)
7997 DATAROOTDIR
7999 read-only architecture-independent data root (share)
8000 DATADIR
8002 read-only architecture-independent data (DATAROOTDIR)
8003 INFODIR
8005 info documentation (DATAROOTDIR/info)
8006 LOCALEDIR
8008 locale-dependent data (DATAROOTDIR/locale)
8009 MANDIR man documentation (DATAROOTDIR/man)
8011 DOCDIR documentation root (DATAROOTDIR/doc/PROJECT_NAME)
8013 If the includer does not define a value the above-shown default will be
8015 used and the value will appear in the cache for editing by the user.
8016 Special Cases
8018 New in version 3.4.
8019 The following values of CMAKE_INSTALL_PREFIX are special:
8022 /
8024 For <dir> other than the SYSCONFDIR, LOCALSTATEDIR and RUNSTATEDIR,
8025 the value of CMAKE_INSTALL_<dir> is prefixed with usr/ if it is not
8026 user-specified as an absolute path. For example, the INCLUDEDIR
8027 value include becomes usr/include. This is required by the GNU Cod‐
8028 ing Standards, which state:
8029 When building the complete GNU system, the prefix will be empty
8030 and /usr will be a symbolic link to /.
8031 /usr
8033 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
8034 CMAKE_INSTALL_FULL_<dir> is computed by prepending just / to the
8035 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
8036 lute path. For example, the SYSCONFDIR value etc becomes /etc.
8037 This is required by the GNU Coding Standards.
8038 /opt/...
8040 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
8041 CMAKE_INSTALL_FULL_<dir> is computed by appending the prefix to the
8042 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
8043 lute path. For example, the SYSCONFDIR value etc becomes
8044 /etc/opt/.... This is defined by the Filesystem Hierarchy Standard.
8045 This behavior does not apply to paths under /opt/homebrew/....
8047 Macros
8049 GNUInstallDirs_get_absolute_install_dir
8050 GNUInstallDirs_get_absolute_install_dir(absvar var dirname)
8052 New in version 3.7.
8054 Set the given variable absvar to the absolute path contained
8057 within the variable var. This is to allow the computation of an
8058 absolute path, accounting for all the special cases documented
8059 above. While this macro is used to compute the various
8060 CMAKE_INSTALL_FULL_<dir> variables, it is exposed publicly to
8061 allow users who create additional path variables to also compute
8062 absolute paths where necessary, using the same logic. dirname
8063 is the directory name to get, e.g. BINDIR.
8064 Changed in version 3.20: Added the <dirname> parameter. Previ‐
8066 ous versions of CMake passed this value through the variable
8067 ${dir}.
8068 GoogleTest
8071 New in version 3.9.
8072 This module defines functions to help use the Google Test infrastruc‐
8075 ture. Two mechanisms for adding tests are provided. gtest_add_tests()
8076 has been around for some time, originally via find_package(GTest).
8077 gtest_discover_tests() was introduced in CMake 3.10.
8078 The (older) gtest_add_tests() scans source files to identify tests.
8080 This is usually effective, with some caveats, including in cross-com‐
8081 piling environments, and makes setting additional properties on tests
8082 more convenient. However, its handling of parameterized tests is less
8083 comprehensive, and it requires re-running CMake to detect changes to
8084 the list of tests.
8085 The (newer) gtest_discover_tests() discovers tests by asking the com‐
8087 piled test executable to enumerate its tests. This is more robust and
8088 provides better handling of parameterized tests, and does not require
8089 CMake to be re-run when tests change. However, it may not work in a
8090 cross-compiling environment, and setting test properties is less conve‐
8091 nient.
8092 More details can be found in the documentation of the respective func‐
8094 tions.
8095 Both commands are intended to replace use of add_test() to register
8097 tests, and will create a separate CTest test for each Google Test test
8098 case. Note that this is in some cases less efficient, as common set-up
8099 and tear-down logic cannot be shared by multiple test cases executing
8100 in the same instance. However, it provides more fine-grained pass/fail
8101 information to CTest, which is usually considered as more beneficial.
8102 By default, the CTest test name is the same as the Google Test name
8103 (i.e. suite.testcase); see also TEST_PREFIX and TEST_SUFFIX.
8104 gtest_add_tests
8106 Automatically add tests with CTest by scanning source code for
8107 Google Test macros:
8108 gtest_add_tests(TARGET target
8110 [SOURCES src1...]
8111 [EXTRA_ARGS arg1...]
8112 [WORKING_DIRECTORY dir]
8113 [TEST_PREFIX prefix]
8114 [TEST_SUFFIX suffix]
8115 [SKIP_DEPENDENCY]
8116 [TEST_LIST outVar]
8117 )
8118 gtest_add_tests attempts to identify tests by scanning source
8120 files. Although this is generally effective, it uses only a ba‐
8121 sic regular expression match, which can be defeated by atypical
8122 test declarations, and is unable to fully "split" parameterized
8123 tests. Additionally, it requires that CMake be re-run to dis‐
8124 cover any newly added, removed or renamed tests (by default,
8125 this means that CMake is re-run when any test source file is
8126 changed, but see SKIP_DEPENDENCY). However, it has the advan‐
8127 tage of declaring tests at CMake time, which somewhat simplifies
8128 setting additional properties on tests, and always works in a
8129 cross-compiling environment.
8130 The options are:
8132 TARGET target
8134 Specifies the Google Test executable, which must be a
8135 known CMake executable target. CMake will substitute the
8136 location of the built executable when running the test.
8137 SOURCES src1...
8139 When provided, only the listed files will be scanned for
8140 test cases. If this option is not given, the SOURCES
8141 property of the specified target will be used to obtain
8142 the list of sources.
8143 EXTRA_ARGS arg1...
8145 Any extra arguments to pass on the command line to each
8146 test case.
8147 WORKING_DIRECTORY dir
8149 Specifies the directory in which to run the discovered
8150 test cases. If this option is not provided, the current
8151 binary directory is used.
8152 TEST_PREFIX prefix
8154 Specifies a prefix to be prepended to the name of each
8155 discovered test case. This can be useful when the same
8156 source files are being used in multiple calls to
8157 gtest_add_test() but with different EXTRA_ARGS.
8158 TEST_SUFFIX suffix
8160 Similar to TEST_PREFIX except the suffix is appended to
8161 the name of every discovered test case. Both TEST_PREFIX
8162 and TEST_SUFFIX may be specified.
8163 SKIP_DEPENDENCY
8165 Normally, the function creates a dependency which will
8166 cause CMake to be re-run if any of the sources being
8167 scanned are changed. This is to ensure that the list of
8168 discovered tests is updated. If this behavior is not de‐
8169 sired (as may be the case while actually writing the test
8170 cases), this option can be used to prevent the dependency
8171 from being added.
8172 TEST_LIST outVar
8174 The variable named by outVar will be populated in the
8175 calling scope with the list of discovered test cases.
8176 This allows the caller to do things like manipulate test
8177 properties of the discovered tests.
8178 Usage example:
8180 include(GoogleTest)
8182 add_executable(FooTest FooUnitTest.cxx)
8183 gtest_add_tests(TARGET FooTest
8184 TEST_SUFFIX .noArgs
8185 TEST_LIST noArgsTests
8186 )
8187 gtest_add_tests(TARGET FooTest
8188 EXTRA_ARGS --someArg someValue
8189 TEST_SUFFIX .withArgs
8190 TEST_LIST withArgsTests
8191 )
8192 set_tests_properties(${noArgsTests} PROPERTIES TIMEOUT 10)
8193 set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20)
8194 For backward compatibility, the following form is also sup‐
8196 ported:
8197 gtest_add_tests(exe args files...)
8199 exe The path to the test executable or the name of a CMake
8201 target.
8202 args A ;-list of extra arguments to be passed to executable.
8204 The entire list must be passed as a single argument. En‐
8205 close it in quotes, or pass "" for no arguments.
8206 files...
8208 A list of source files to search for tests and test fix‐
8209 tures. Alternatively, use AUTO to specify that exe is
8210 the name of a CMake executable target whose sources
8211 should be scanned.
8212 include(GoogleTest)
8214 set(FooTestArgs --foo 1 --bar 2)
8215 add_executable(FooTest FooUnitTest.cxx)
8216 gtest_add_tests(FooTest "${FooTestArgs}" AUTO)
8217 gtest_discover_tests
8219 Automatically add tests with CTest by querying the compiled test
8220 executable for available tests:
8221 gtest_discover_tests(target
8223 [EXTRA_ARGS arg1...]
8224 [WORKING_DIRECTORY dir]
8225 [TEST_PREFIX prefix]
8226 [TEST_SUFFIX suffix]
8227 [TEST_FILTER expr]
8228 [NO_PRETTY_TYPES] [NO_PRETTY_VALUES]
8229 [PROPERTIES name1 value1...]
8230 [TEST_LIST var]
8231 [DISCOVERY_TIMEOUT seconds]
8232 [XML_OUTPUT_DIR dir]
8233 [DISCOVERY_MODE <POST_BUILD|PRE_TEST>]
8234 )
8235 New in version 3.10.
8237 gtest_discover_tests() sets up a post-build command on the test
8240 executable that generates the list of tests by parsing the out‐
8241 put from running the test with the --gtest_list_tests argument.
8242 Compared to the source parsing approach of gtest_add_tests(),
8243 this ensures that the full list of tests, including instantia‐
8244 tions of parameterized tests, is obtained. Since test discovery
8245 occurs at build time, it is not necessary to re-run CMake when
8246 the list of tests changes. However, it requires that
8247 CROSSCOMPILING_EMULATOR is properly set in order to function in
8248 a cross-compiling environment.
8249 Additionally, setting properties on tests is somewhat less con‐
8251 venient, since the tests are not available at CMake time. Addi‐
8252 tional test properties may be assigned to the set of tests as a
8253 whole using the PROPERTIES option. If more fine-grained test
8254 control is needed, custom content may be provided through an ex‐
8255 ternal CTest script using the TEST_INCLUDE_FILES directory prop‐
8256 erty. The set of discovered tests is made accessible to such a
8257 script via the <target>_TESTS variable.
8258 The options are:
8260 target Specifies the Google Test executable, which must be a
8262 known CMake executable target. CMake will substitute the
8263 location of the built executable when running the test.
8264 EXTRA_ARGS arg1...
8266 Any extra arguments to pass on the command line to each
8267 test case.
8268 WORKING_DIRECTORY dir
8270 Specifies the directory in which to run the discovered
8271 test cases. If this option is not provided, the current
8272 binary directory is used.
8273 TEST_PREFIX prefix
8275 Specifies a prefix to be prepended to the name of each
8276 discovered test case. This can be useful when the same
8277 test executable is being used in multiple calls to
8278 gtest_discover_tests() but with different EXTRA_ARGS.
8279 TEST_SUFFIX suffix
8281 Similar to TEST_PREFIX except the suffix is appended to
8282 the name of every discovered test case. Both TEST_PREFIX
8283 and TEST_SUFFIX may be specified.
8284 TEST_FILTER expr
8286 New in version 3.22.
8287 Filter expression to pass as a --gtest_filter argument
8290 during test discovery. Note that the expression is a
8291 wildcard-based format that matches against the original
8292 test names as used by gtest. For type or value-parame‐
8293 terized tests, these names may be different to the poten‐
8294 tially pretty-printed test names that ctest uses.
8295 NO_PRETTY_TYPES
8297 By default, the type index of type-parameterized tests is
8298 replaced by the actual type name in the CTest test name.
8299 If this behavior is undesirable (e.g. because the type
8300 names are unwieldy), this option will suppress this be‐
8301 havior.
8302 NO_PRETTY_VALUES
8304 By default, the value index of value-parameterized tests
8305 is replaced by the actual value in the CTest test name.
8306 If this behavior is undesirable (e.g. because the value
8307 strings are unwieldy), this option will suppress this be‐
8308 havior.
8309 PROPERTIES name1 value1...
8311 Specifies additional properties to be set on all tests
8312 discovered by this invocation of gtest_discover_tests().
8313 TEST_LIST var
8315 Make the list of tests available in the variable var,
8316 rather than the default <target>_TESTS. This can be use‐
8317 ful when the same test executable is being used in multi‐
8318 ple calls to gtest_discover_tests(). Note that this
8319 variable is only available in CTest.
8320 DISCOVERY_TIMEOUT num
8322 New in version 3.10.3.
8323 Specifies how long (in seconds) CMake will wait for the
8326 test to enumerate available tests. If the test takes
8327 longer than this, discovery (and your build) will fail.
8328 Most test executables will enumerate their tests very
8329 quickly, but under some exceptional circumstances, a test
8330 may require a longer timeout. The default is 5. See
8331 also the TIMEOUT option of execute_process().
8332 NOTE:
8334 In CMake versions 3.10.1 and 3.10.2, this option was
8335 called TIMEOUT. This clashed with the TIMEOUT test
8336 property, which is one of the common properties that
8337 would be set with the PROPERTIES keyword, usually
8338 leading to legal but unintended behavior. The keyword
8339 was changed to DISCOVERY_TIMEOUT in CMake 3.10.3 to
8340 address this problem. The ambiguous behavior of the
8341 TIMEOUT keyword in 3.10.1 and 3.10.2 has not been pre‐
8342 served.
8343 XML_OUTPUT_DIR dir
8345 New in version 3.18.
8346 If specified, the parameter is passed along with
8349 --gtest_output=xml: to test executable. The actual file
8350 name is the same as the test target, including prefix and
8351 suffix. This should be used instead of EXTRA_ARGS
8352 --gtest_output=xml to avoid race conditions writing the
8353 XML result output when using parallel test execution.
8354 DISCOVERY_MODE
8356 New in version 3.18.
8357 Provides greater control over when gtest_discover_tests()
8360 performs test discovery. By default, POST_BUILD sets up a
8361 post-build command to perform test discovery at build
8362 time. In certain scenarios, like cross-compiling, this
8363 POST_BUILD behavior is not desirable. By contrast,
8364 PRE_TEST delays test discovery until just prior to test
8365 execution. This way test discovery occurs in the target
8366 environment where the test has a better chance at finding
8367 appropriate runtime dependencies.
8368 DISCOVERY_MODE defaults to the value of the
8370 CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE variable if it
8371 is not passed when calling gtest_discover_tests(). This
8372 provides a mechanism for globally selecting a preferred
8373 test discovery behavior without having to modify each
8374 call site.
8375 InstallRequiredSystemLibraries
8377 Include this module to search for compiler-provided system runtime li‐
8378 braries and add install rules for them. Some optional variables may be
8379 set prior to including the module to adjust behavior:
8380 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS
8382 Specify additional runtime libraries that may not be detected.
8383 After inclusion any detected libraries will be appended to this.
8384 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP
8386 Set to TRUE to skip calling the install(PROGRAMS) command to al‐
8387 low the includer to specify its own install rule, using the
8388 value of CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS to get the list of
8389 libraries.
8390 CMAKE_INSTALL_DEBUG_LIBRARIES
8392 Set to TRUE to install the debug runtime libraries when avail‐
8393 able with MSVC tools.
8394 CMAKE_INSTALL_DEBUG_LIBRARIES_ONLY
8396 Set to TRUE to install only the debug runtime libraries with
8397 MSVC tools even if the release runtime libraries are also avail‐
8398 able.
8399 CMAKE_INSTALL_UCRT_LIBRARIES
8401 New in version 3.6.
8402 Set to TRUE to install the Windows Universal CRT libraries for
8405 app-local deployment (e.g. to Windows XP). This is meaningful
8406 only with MSVC from Visual Studio 2015 or higher.
8407 New in version 3.9: One may set a CMAKE_WINDOWS_KITS_10_DIR en‐
8409 vironment variable to an absolute path to tell CMake to look for
8410 Windows 10 SDKs in a custom location. The specified directory
8411 is expected to contain Redist/ucrt/DLLs/* directories.
8412 CMAKE_INSTALL_MFC_LIBRARIES
8415 Set to TRUE to install the MSVC MFC runtime libraries.
8416 CMAKE_INSTALL_OPENMP_LIBRARIES
8418 Set to TRUE to install the MSVC OpenMP runtime libraries
8419 CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION
8421 Specify the install(PROGRAMS) command DESTINATION option. If
8422 not specified, the default is bin on Windows and lib elsewhere.
8423 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_NO_WARNINGS
8425 Set to TRUE to disable warnings about required library files
8426 that do not exist. (For example, Visual Studio Express editions
8427 may not provide the redistributable files.)
8428 CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT
8430 New in version 3.3.
8431 Specify the install(PROGRAMS) command COMPONENT option. If not
8434 specified, no such option will be used.
8435 New in version 3.10: Support for installing Intel compiler runtimes.
8437 ProcessorCount
8440 ProcessorCount(var)
8441 Determine the number of processors/cores and save value in ${var}
8443 Sets the variable named ${var} to the number of physical cores avail‐
8445 able on the machine if the information can be determined. Otherwise it
8446 is set to 0. Currently this functionality is implemented for AIX, cyg‐
8447 win, FreeBSD, HPUX, Linux, macOS, QNX, Sun and Windows.
8448 Changed in version 3.15: On Linux, returns the container CPU count in‐
8450 stead of the host CPU count.
8451 This function is guaranteed to return a positive integer (>=1) if it
8454 succeeds. It returns 0 if there's a problem determining the processor
8455 count.
8456 Example use, in a ctest -S dashboard script:
8458 include(ProcessorCount)
8460 ProcessorCount(N)
8461 if(NOT N EQUAL 0)
8462 set(CTEST_BUILD_FLAGS -j${N})
8463 set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N})
8464 endif()
8465 This function is intended to offer an approximation of the value of the
8467 number of compute cores available on the current machine, such that you
8468 may use that value for parallel building and parallel testing. It is
8469 meant to help utilize as much of the machine as seems reasonable. Of
8470 course, knowledge of what else might be running on the machine simulta‐
8471 neously should be used when deciding whether to request a machine's
8472 full capacity all for yourself.
8473 SelectLibraryConfigurations
8475 select_library_configurations(basename)
8476 This macro takes a library base name as an argument, and will choose
8478 good values for the variables
8479 basename_LIBRARY
8481 basename_LIBRARIES
8482 basename_LIBRARY_DEBUG
8483 basename_LIBRARY_RELEASE
8484 depending on what has been found and set.
8486 If only basename_LIBRARY_RELEASE is defined, basename_LIBRARY will be
8488 set to the release value, and basename_LIBRARY_DEBUG will be set to
8489 basename_LIBRARY_DEBUG-NOTFOUND. If only basename_LIBRARY_DEBUG is de‐
8490 fined, then basename_LIBRARY will take the debug value, and base‐
8491 name_LIBRARY_RELEASE will be set to basename_LIBRARY_RELEASE-NOTFOUND.
8492 If the generator supports configuration types, then basename_LIBRARY
8494 and basename_LIBRARIES will be set with debug and optimized flags spec‐
8495 ifying the library to be used for the given configuration. If no build
8496 type has been set or the generator in use does not support configura‐
8497 tion types, then basename_LIBRARY and basename_LIBRARIES will take only
8498 the release value, or the debug value if the release one is not set.
8499 SquishTestScript
8501 This script launches a GUI test using Squish. You should not call the
8502 script directly; instead, you should access it via the SQUISH_ADD_TEST
8503 macro that is defined in FindSquish.cmake.
8504 This script starts the Squish server, launches the test on the client,
8506 and finally stops the squish server. If any of these steps fail (in‐
8507 cluding if the tests do not pass) then a fatal error is raised.
8508 TestBigEndian
8510 Deprecated since version 3.20: Supserseded by the
8511 CMAKE_<LANG>_BYTE_ORDER variable.
8512 Check if the target architecture is big endian or little endian.
8515 test_big_endian
8517 test_big_endian(<var>)
8519 Stores in variable <var> either 1 or 0 indicating whether the
8521 target architecture is big or little endian.
8522 TestForANSIForScope
8524 Check for ANSI for scope support
8525 Check if the compiler restricts the scope of variables declared in a
8527 for-init-statement to the loop body.
8528 CMAKE_NO_ANSI_FOR_SCOPE - holds result
8530 TestForANSIStreamHeaders
8532 Test for compiler support of ANSI stream headers iostream, etc.
8533 check if the compiler supports the standard ANSI iostream header (with‐
8535 out the .h)
8536 CMAKE_NO_ANSI_STREAM_HEADERS - defined by the results
8538 TestForSSTREAM
8540 Test for compiler support of ANSI sstream header
8541 check if the compiler supports the standard ANSI sstream header
8543 CMAKE_NO_ANSI_STRING_STREAM - defined by the results
8545 TestForSTDNamespace
8547 Test for std:: namespace support
8548 check if the compiler supports std:: on stl classes
8550 CMAKE_NO_STD_NAMESPACE - defined by the results
8552 UseEcos
8554 This module defines variables and macros required to build eCos appli‐
8555 cation.
8556 This file contains the following macros: ECOS_ADD_INCLUDE_DIRECTORIES()
8558 - add the eCos include dirs ECOS_ADD_EXECUTABLE(name source1 ...
8559 sourceN ) - create an eCos executable ECOS_ADJUST_DIRECTORY(VAR source1
8560 ... sourceN ) - adjusts the path of the source files and puts the re‐
8561 sult into VAR
8562 Macros for selecting the toolchain: ECOS_USE_ARM_ELF_TOOLS() - enable
8564 the ARM ELF toolchain for the directory where it is called
8565 ECOS_USE_I386_ELF_TOOLS() - enable the i386 ELF toolchain for the di‐
8566 rectory where it is called ECOS_USE_PPC_EABI_TOOLS() - enable the Pow‐
8567 erPC toolchain for the directory where it is called
8568 It contains the following variables: ECOS_DEFINITIONS ECOSCONFIG_EXE‐
8570 CUTABLE ECOS_CONFIG_FILE - defaults to ecos.ecc, if your eCos configu‐
8571 ration file has a different name, adjust this variable for internal use
8572 only:
8573 ECOS_ADD_TARGET_LIB
8575 UseJava
8577 This file provides support for Java. It is assumed that FindJava has
8578 already been loaded. See FindJava for information on how to load Java
8579 into your CMake project.
8580 Synopsis
8582 Creating and Installing JARS
8583 add_jar (<target_name> [SOURCES] <source1> [<source2>...] ...)
8584 install_jar (<target_name> DESTINATION <destination> [COMPONENT <component>])
8585 install_jni_symlink (<target_name> DESTINATION <destination> [COMPONENT <component>])
8586 Header Generation
8588 create_javah ((TARGET <target> | GENERATED_FILES <VAR>) CLASSES <class>... ...)
8589 Exporting JAR Targets
8591 install_jar_exports (TARGETS <jars>... FILE <filename> DESTINATION <destination> ...)
8592 export_jars (TARGETS <jars>... [NAMESPACE <namespace>] FILE <filename>)
8593 Finding JARs
8595 find_jar (<VAR> NAMES <name1> [<name2>...] [PATHS <path1> [<path2>... ENV <var>]] ...)
8596 Creating Java Documentation
8598 create_javadoc (<VAR> (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...]) ...)
8599 Creating And Installing JARs
8601 add_jar
8602 Creates a jar file containing java objects and, optionally, re‐
8603 sources:
8604 add_jar(<target_name>
8606 [SOURCES] <source1> [<source2>...] [<resource1>...]
8607 [RESOURCES NAMESPACE <ns1> <resource1>... [NAMESPACE <nsX> <resourceX>...]... ]
8608 [INCLUDE_JARS <jar1> [<jar2>...]]
8609 [ENTRY_POINT <entry>]
8610 [VERSION <version>]
8611 [MANIFEST <manifest>]
8612 [OUTPUT_NAME <name>]
8613 [OUTPUT_DIR <dir>]
8614 [GENERATE_NATIVE_HEADERS <target>
8615 [DESTINATION (<dir>|INSTALL <dir> [BUILD <dir>])]]
8616 )
8617 This command creates a <target_name>.jar. It compiles the given
8619 <source> files and adds the given <resource> files to the jar
8620 file. Source files can be java files or listing files (prefixed
8621 by @). If only resource files are given then just a jar file is
8622 created.
8623 SOURCES
8625 Compiles the specified source files and adds the result
8626 in the jar file.
8627 New in version 3.4: Support for response files, prefixed
8629 by @.
8630 RESOURCES
8633 New in version 3.21.
8634 Adds the named <resource> files to the jar by stripping
8637 the source file path and placing the file beneath <ns>
8638 within the jar.
8639 For example:
8641 RESOURCES NAMESPACE "/com/my/namespace" "a/path/to/resource.txt"
8643 results in a resource accessible via /com/my/name‐
8645 space/resource.txt within the jar.
8646 Resources may be added without adjusting the namespace by
8648 adding them to the list of SOURCES (original behavior),
8649 in this case, resource paths must be relative to
8650 CMAKE_CURRENT_SOURCE_DIR. Adding resources without using
8651 the RESOURCES parameter in out of source builds will al‐
8652 most certainly result in confusion.
8653 NOTE:
8655 Adding resources via the SOURCES parameter relies upon
8656 a hard-coded list of file extensions which are tested
8657 to determine whether they compile (e.g. File.java).
8658 SOURCES files which match the extensions are compiled.
8659 Files which do not match are treated as resources. To
8660 include uncompiled resources matching those file ex‐
8661 tensions use the RESOURCES parameter.
8662 INCLUDE_JARS
8664 The list of jars are added to the classpath when compil‐
8665 ing the java sources and also to the dependencies of the
8666 target. INCLUDE_JARS also accepts other target names cre‐
8667 ated by add_jar(). For backwards compatibility, jar files
8668 listed as sources are ignored (as they have been since
8669 the first version of this module).
8670 ENTRY_POINT
8672 Defines an entry point in the jar file.
8673 VERSION
8675 Adds a version to the target output name.
8676 The following example will create a jar file with the
8678 name shibboleet-1.2.0.jar and will create a symlink shib‐
8679 boleet.jar pointing to the jar with the version informa‐
8680 tion.
8681 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
8683 MANIFEST
8685 Defines a custom manifest for the jar.
8686 OUTPUT_NAME
8688 Specify a different output name for the target.
8689 OUTPUT_DIR
8691 Sets the directory where the jar file will be generated.
8692 If not specified, CMAKE_CURRENT_BINARY_DIR is used as the
8693 output directory.
8694 GENERATE_NATIVE_HEADERS
8696 New in version 3.11.
8697 Generates native header files for methods declared as na‐
8700 tive. These files provide the connective glue that allow
8701 your Java and C code to interact. An INTERFACE target
8702 will be created for an easy usage of generated files.
8703 Sub-option DESTINATION can be used to specify the output
8704 directory for generated header files.
8705 This option requires, at least, version 1.8 of the JDK.
8707 For an optimum usage of this option, it is recommended to
8709 include module JNI before any call to add_jar(). The pro‐
8710 duced target for native headers can then be used to com‐
8711 pile C/C++ sources with the target_link_libraries() com‐
8712 mand.
8713 find_package(JNI)
8715 add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native)
8716 add_library(bar bar.cpp)
8717 target_link_libraries(bar PRIVATE foo-native)
8718 New in version 3.20: DESTINATION sub-option now supports
8720 the possibility to specify different output directories
8721 for BUILD and INSTALL steps. If BUILD directory is not
8722 specified, a default directory will be used.
8723 To export the interface target generated by GENERATE_NA‐
8725 TIVE_HEADERS option, sub-option INSTALL of DESTINATION is
8726 required:
8727 add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native
8729 DESTINATION INSTALL include)
8730 install(TARGETS foo-native EXPORT native)
8731 install(DIRECTORY "$<TARGET_PROPERTY:foo-native,NATIVE_HEADERS_DIRECTORY>/"
8732 DESTINATION include)
8733 install(EXPORT native DESTINATION /to/export NAMESPACE foo)
8734 Some variables can be set to customize the behavior of add_jar()
8737 as well as the java compiler:
8738 CMAKE_JAVA_COMPILE_FLAGS
8740 Specify additional flags to java compiler.
8741 CMAKE_JAVA_INCLUDE_PATH
8743 Specify additional paths to the class path.
8744 CMAKE_JNI_TARGET
8746 If the target is a JNI library, sets this boolean vari‐
8747 able to TRUE to enable creation of a JNI symbolic link
8748 (see also install_jni_symlink()).
8749 CMAKE_JAR_CLASSES_PREFIX
8751 If multiple jars should be produced from the same java
8752 source filetree, to prevent the accumulation of duplicate
8753 class files in subsequent jars, set/reset
8754 CMAKE_JAR_CLASSES_PREFIX prior to calling the add_jar():
8755 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
8757 add_jar(foo foo.java)
8758 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
8760 add_jar(bar bar.java)
8761 The add_jar() function sets the following target properties on
8763 <target_name>:
8764 INSTALL_FILES
8766 The files which should be installed. This is used by
8767 install_jar().
8768 JNI_SYMLINK
8770 The JNI symlink which should be installed. This is used
8771 by install_jni_symlink().
8772 JAR_FILE
8774 The location of the jar file so that you can include it.
8775 CLASSDIR
8777 The directory where the class files can be found. For
8778 example to use them with javah.
8779 NATIVE_HEADERS_DIRECTORY
8781 New in version 3.20.
8782 The directory where native headers are generated. Defined
8785 when option GENERATE_NATIVE_HEADERS is specified.
8786 install_jar
8788 This command installs the jar file to the given destination:
8789 install_jar(<target_name> <destination>)
8791 install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>])
8792 This command installs the <target_name> file to the given <des‐
8794 tination>. It should be called in the same scope as add_jar()
8795 or it will fail.
8796 New in version 3.4: The second signature with DESTINATION and
8798 COMPONENT options.
8799 DESTINATION
8802 Specify the directory on disk to which a file will be in‐
8803 stalled.
8804 COMPONENT
8806 Specify an installation component name with which the in‐
8807 stall rule is associated, such as "runtime" or "develop‐
8808 ment".
8809 The install_jar() command sets the following target properties
8811 on <target_name>:
8812 INSTALL_DESTINATION
8814 Holds the <destination> as described above, and is used
8815 by install_jar_exports().
8816 install_jni_symlink
8818 Installs JNI symlinks for target generated by add_jar():
8819 install_jni_symlink(<target_name> <destination>)
8821 install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>])
8822 This command installs the <target_name> JNI symlinks to the
8824 given <destination>. It should be called in the same scope as
8825 add_jar() or it will fail.
8826 New in version 3.4: The second signature with DESTINATION and
8828 COMPONENT options.
8829 DESTINATION
8832 Specify the directory on disk to which a file will be in‐
8833 stalled.
8834 COMPONENT
8836 Specify an installation component name with which the in‐
8837 stall rule is associated, such as "runtime" or "develop‐
8838 ment".
8839 Utilize the following commands to create a JNI symbolic link:
8841 set(CMAKE_JNI_TARGET TRUE)
8843 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
8844 install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
8845 install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})
8846 Header Generation
8848 create_javah
8849 New in version 3.4.
8850 Generates C header files for java classes:
8853 create_javah(TARGET <target> | GENERATED_FILES <VAR>
8855 CLASSES <class>...
8856 [CLASSPATH <classpath>...]
8857 [DEPENDS <depend>...]
8858 [OUTPUT_NAME <path>|OUTPUT_DIR <path>]
8859 )
8860 Deprecated since version 3.11: This command will no longer be
8862 supported starting with version 10 of the JDK due to the
8863 suppression of javah tool. The add_jar(GENERATE_NATIVE_HEADERS)
8864 command should be used instead.
8865 Create C header files from java classes. These files provide the
8868 connective glue that allow your Java and C code to interact.
8869 There are two main signatures for create_javah(). The first
8871 signature returns generated files through variable specified by
8872 the GENERATED_FILES option. For example:
8873 create_javah(GENERATED_FILES files_headers
8875 CLASSES org.cmake.HelloWorld
8876 CLASSPATH hello.jar
8877 )
8878 The second signature for create_javah() creates a target which
8880 encapsulates header files generation. E.g.
8881 create_javah(TARGET target_headers
8883 CLASSES org.cmake.HelloWorld
8884 CLASSPATH hello.jar
8885 )
8886 Both signatures share same options.
8888 CLASSES
8890 Specifies Java classes used to generate headers.
8891 CLASSPATH
8893 Specifies various paths to look up classes. Here .class
8894 files, jar files or targets created by command add_jar
8895 can be used.
8896 DEPENDS
8898 Targets on which the javah target depends.
8899 OUTPUT_NAME
8901 Concatenates the resulting header files for all the
8902 classes listed by option CLASSES into <path>. Same be‐
8903 havior as option -o of javah tool.
8904 OUTPUT_DIR
8906 Sets the directory where the header files will be gener‐
8907 ated. Same behavior as option -d of javah tool. If not
8908 specified, CMAKE_CURRENT_BINARY_DIR is used as the output
8909 directory.
8910 Exporting JAR Targets
8912 install_jar_exports
8913 New in version 3.7.
8914 Installs a target export file:
8917 install_jar_exports(TARGETS <jars>...
8919 [NAMESPACE <namespace>]
8920 FILE <filename>
8921 DESTINATION <destination> [COMPONENT <component>])
8922 This command installs a target export file <filename> for the
8924 named jar targets to the given <destination> directory. Its
8925 function is similar to that of install(EXPORT).
8926 TARGETS
8928 List of targets created by add_jar() command.
8929 NAMESPACE
8931 New in version 3.9.
8932 The <namespace> value will be prepend to the target names
8935 as they are written to the import file.
8936 FILE Specify name of the export file.
8938 DESTINATION
8940 Specify the directory on disk to which a file will be in‐
8941 stalled.
8942 COMPONENT
8944 Specify an installation component name with which the in‐
8945 stall rule is associated, such as "runtime" or "develop‐
8946 ment".
8947 export_jars
8949 New in version 3.7.
8950 Writes a target export file:
8953 export_jars(TARGETS <jars>...
8955 [NAMESPACE <namespace>]
8956 FILE <filename>)
8957 This command writes a target export file <filename> for the
8959 named <jars> targets. Its function is similar to that of
8960 export().
8961 TARGETS
8963 List of targets created by add_jar() command.
8964 NAMESPACE
8966 New in version 3.9.
8967 The <namespace> value will be prepend to the target names
8970 as they are written to the import file.
8971 FILE Specify name of the export file.
8973 Finding JARs
8975 find_jar
8976 Finds the specified jar file:
8977 find_jar(<VAR>
8979 <name> | NAMES <name1> [<name2>...]
8980 [PATHS <path1> [<path2>... ENV <var>]]
8981 [VERSIONS <version1> [<version2>]]
8982 [DOC "cache documentation string"]
8983 )
8984 This command is used to find a full path to the named jar. A
8986 cache entry named by <VAR> is created to store the result of
8987 this command. If the full path to a jar is found the result is
8988 stored in the variable and the search will not repeated unless
8989 the variable is cleared. If nothing is found, the result will
8990 be <VAR>-NOTFOUND, and the search will be attempted again next
8991 time find_jar() is invoked with the same variable.
8992 NAMES Specify one or more possible names for the jar file.
8994 PATHS Specify directories to search in addition to the default
8996 locations. The ENV var sub-option reads paths from a
8997 system environment variable.
8998 VERSIONS
9000 Specify jar versions.
9001 DOC Specify the documentation string for the <VAR> cache en‐
9003 try.
9004 Creating Java Documentation
9006 create_javadoc
9007 Creates java documentation based on files and packages:
9008 create_javadoc(<VAR>
9010 (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...])
9011 [SOURCEPATH <sourcepath>]
9012 [CLASSPATH <classpath>]
9013 [INSTALLPATH <install path>]
9014 [DOCTITLE <the documentation title>]
9015 [WINDOWTITLE <the title of the document>]
9016 [AUTHOR (TRUE|FALSE)]
9017 [USE (TRUE|FALSE)]
9018 [VERSION (TRUE|FALSE)]
9019 )
9020 The create_javadoc() command can be used to create java documen‐
9022 tation. There are two main signatures for create_javadoc().
9023 The first signature works with package names on a path with
9025 source files:
9026 create_javadoc(my_example_doc
9028 PACKAGES com.example.foo com.example.bar
9029 SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
9030 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
9031 WINDOWTITLE "My example"
9032 DOCTITLE "<h1>My example</h1>"
9033 AUTHOR TRUE
9034 USE TRUE
9035 VERSION TRUE
9036 )
9037 The second signature for create_javadoc() works on a given list
9039 of files:
9040 create_javadoc(my_example_doc
9042 FILES java/A.java java/B.java
9043 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
9044 WINDOWTITLE "My example"
9045 DOCTITLE "<h1>My example</h1>"
9046 AUTHOR TRUE
9047 USE TRUE
9048 VERSION TRUE
9049 )
9050 Both signatures share most of the options. For more details
9052 please read the javadoc manpage.
9053 PACKAGES
9055 Specify java packages.
9056 FILES Specify java source files. If relative paths are speci‐
9058 fied, they are relative to CMAKE_CURRENT_SOURCE_DIR.
9059 SOURCEPATH
9061 Specify the directory where to look for packages. By de‐
9062 fault, CMAKE_CURRENT_SOURCE_DIR directory is used.
9063 CLASSPATH
9065 Specify where to find user class files. Same behavior as
9066 option -classpath of javadoc tool.
9067 INSTALLPATH
9069 Specify where to install the java documentation. If you
9070 specified, the documentation will be installed to
9071 ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>.
9072 DOCTITLE
9074 Specify the title to place near the top of the overview
9075 summary file. Same behavior as option -doctitle of
9076 javadoc tool.
9077 WINDOWTITLE
9079 Specify the title to be placed in the HTML <title> tag.
9080 Same behavior as option -windowtitle of javadoc tool.
9081 AUTHOR When value TRUE is specified, includes the @author text
9083 in the generated docs. Same behavior as option -author
9084 of javadoc tool.
9085 USE When value TRUE is specified, creates class and package
9087 usage pages. Includes one Use page for each documented
9088 class and package. Same behavior as option -use of
9089 javadoc tool.
9090 VERSION
9092 When value TRUE is specified, includes the version text
9093 in the generated docs. Same behavior as option -version
9094 of javadoc tool.
9095 UseSWIG
9097 This file provides support for SWIG. It is assumed that FindSWIG module
9098 has already been loaded.
9099 Defines the following command for use with SWIG:
9101 swig_add_library
9103 New in version 3.8.
9104 Define swig module with given name and specified language:
9107 swig_add_library(<name>
9109 [TYPE <SHARED|MODULE|STATIC|USE_BUILD_SHARED_LIBS>]
9110 LANGUAGE <language>
9111 [NO_PROXY]
9112 [OUTPUT_DIR <directory>]
9113 [OUTFILE_DIR <directory>]
9114 SOURCES <file>...
9115 )
9116 Targets created with the swig_add_library command have the same
9118 capabilities as targets created with the add_library() command,
9119 so those targets can be used with any command expecting a target
9120 (e.g. target_link_libraries()).
9121 Changed in version 3.13: This command creates a target with the
9123 specified <name> when policy CMP0078 is set to NEW. Otherwise,
9124 the legacy behavior will choose a different target name and
9125 store it in the SWIG_MODULE_<name>_REAL_NAME variable.
9126 Changed in version 3.15: Alternate library name (set with the
9129 OUTPUT_NAME property, for example) will be passed on to Python
9130 and CSharp wrapper libraries.
9131 Changed in version 3.21: Generated library use standard naming
9134 conventions for CSharp language when policy CMP0122 is set to
9135 NEW. Otherwise, the legacy behavior is applied.
9136 NOTE:
9139 For multi-config generators, this module does not support
9140 configuration-specific files generated by SWIG. All build
9141 configurations must result in the same generated source file.
9142 NOTE:
9144 For Makefile Generators, if, for some sources, the
9145 USE_SWIG_DEPENDENCIES property is FALSE, swig_add_library
9146 does not track file dependencies, so depending on the
9147 <name>_swig_compilation custom target is required for targets
9148 which require the swig-generated files to exist. Other gener‐
9149 ators may depend on the source files that would be generated
9150 by SWIG.
9151 TYPE SHARED, MODULE and STATIC have the same semantic as for
9153 the add_library() command. If USE_BUILD_SHARED_LIBS is
9154 specified, the library type will be STATIC or SHARED
9155 based on whether the current value of the
9156 BUILD_SHARED_LIBS variable is ON. If no type is speci‐
9157 fied, MODULE will be used.
9158 LANGUAGE
9160 Specify the target language.
9161 New in version 3.1: Go and Lua language support.
9163 New in version 3.2: R language support.
9166 New in version 3.18: Fortran language support.
9169 NO_PROXY
9172 New in version 3.12.
9173 Prevent the generation of the wrapper layer (swig -no‐
9176 proxy option).
9177 OUTPUT_DIR
9179 New in version 3.12.
9180 Specify where to write the language specific files (swig
9183 -outdir option). If not given, the CMAKE_SWIG_OUTDIR
9184 variable will be used. If neither is specified, the de‐
9185 fault depends on the value of the UseSWIG_MODULE_VERSION
9186 variable as follows:
9187 • If UseSWIG_MODULE_VERSION is 1 or is undefined, output
9189 is written to the CMAKE_CURRENT_BINARY_DIR directory.
9190 • If UseSWIG_MODULE_VERSION is 2, a dedicated directory
9192 will be used. The path of this directory can be re‐
9193 trieved from the SWIG_SUPPORT_FILES_DIRECTORY target
9194 property.
9195 OUTFILE_DIR
9197 New in version 3.12.
9198 Specify an output directory name where the generated
9201 source file will be placed (swig -o option). If not spec‐
9202 ified, the SWIG_OUTFILE_DIR variable will be used. If
9203 neither is specified, OUTPUT_DIR or CMAKE_SWIG_OUTDIR is
9204 used instead.
9205 SOURCES
9207 List of sources for the library. Files with extension .i
9208 will be identified as sources for the SWIG tool. Other
9209 files will be handled in the standard way.
9210 New in version 3.14: This behavior can be overridden by
9212 specifying the variable SWIG_SOURCE_FILE_EXTENSIONS.
9213 NOTE:
9216 If UseSWIG_MODULE_VERSION is set to 2, it is strongly recom‐
9217 mended to use a dedicated directory unique to the target when
9218 either the OUTPUT_DIR option or the CMAKE_SWIG_OUTDIR vari‐
9219 able are specified. The output directory contents are erased
9220 as part of the target build, so to prevent interference be‐
9221 tween targets or losing other important files, each target
9222 should have its own dedicated output directory.
9223 swig_link_libraries
9225 Link libraries to swig module:
9226 swig_link_libraries(<name> <item>...)
9228 This command has same capabilities as target_link_libraries()
9230 command.
9231 NOTE:
9233 If variable UseSWIG_TARGET_NAME_PREFERENCE is set to STAN‐
9234 DARD, this command is deprecated and target_link_libraries()
9235 command must be used instead.
9236 Source file properties on module files must be set before the invoca‐
9238 tion of the swig_add_library command to specify special behavior of
9239 SWIG and ensure generated files will receive the required settings.
9240 CPLUSPLUS
9242 Call SWIG in c++ mode. For example:
9243 set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON)
9245 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
9246 SWIG_FLAGS
9248 Deprecated since version 3.12: Replaced with the fine-grained
9249 properties that follow.
9250 Pass custom flags to the SWIG executable.
9253 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS
9255 New in version 3.12.
9256 Add custom flags to SWIG compiler and have same semantic as
9259 properties INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and
9260 COMPILE_OPTIONS.
9261 USE_TARGET_INCLUDE_DIRECTORIES
9263 New in version 3.13.
9264 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
9267 will be forwarded to SWIG compiler. If set to FALSE target
9268 property INCLUDE_DIRECTORIES will be ignored. If not set, target
9269 property SWIG_USE_TARGET_INCLUDE_DIRECTORIES will be considered.
9270 GENERATED_INCLUDE_DIRECTORIES, GENERATED_COMPILE_DEFINITIONS and GENER‐
9272 ATED_COMPILE_OPTIONS
9273 New in version 3.12.
9274 Add custom flags to the C/C++ generated source. They will fill,
9277 respectively, properties INCLUDE_DIRECTORIES,
9278 COMPILE_DEFINITIONS and COMPILE_OPTIONS of generated C/C++ file.
9279 DEPENDS
9281 New in version 3.12.
9282 Specify additional dependencies to the source file.
9285 USE_SWIG_DEPENDENCIES
9287 New in version 3.20.
9288 If set to TRUE, implicit dependencies are generated by the swig
9291 tool itself. This property is only meaningful for Makefile,
9292 Ninja, Xcode, and Visual Studio (Visual Studio 11 2012 and
9293 above) generators. Default value is FALSE.
9294 New in version 3.21: Added the support of Xcode generator.
9296 New in version 3.22: Added the support of Visual Studio Genera‐
9299 tors.
9300 SWIG_MODULE_NAME
9303 Specify the actual import name of the module in the target lan‐
9304 guage. This is required if it cannot be scanned automatically
9305 from source or different from the module file basename. For ex‐
9306 ample:
9307 set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)
9309 Changed in version 3.14: If policy CMP0086 is set to NEW, -mod‐
9311 ule <module_name> is passed to SWIG compiler.
9312 OUTPUT_DIR
9315 New in version 3.19.
9316 Specify where to write the language specific files (swig -outdir
9319 option) for the considered source file. If not specified, the
9320 other ways to define the output directory applies (see OUT‐
9321 PUT_DIR option of swig_add_library() command).
9322 OUTFILE_DIR
9324 New in version 3.19.
9325 Specify an output directory where the generated source file will
9328 be placed (swig -o option) for the considered source file. If
9329 not specified, OUTPUT_DIR source property will be used. If nei‐
9330 ther are specified, the other ways to define output file direc‐
9331 tory applies (see OUTFILE_DIR option of swig_add_library() com‐
9332 mand).
9333 Target library properties can be set to apply same configuration to all
9335 SWIG input files.
9336 SWIG_INCLUDE_DIRECTORIES, SWIG_COMPILE_DEFINITIONS and SWIG_COMPILE_OP‐
9338 TIONS
9339 New in version 3.12.
9340 These properties will be applied to all SWIG input files and
9343 have same semantic as target properties INCLUDE_DIRECTORIES,
9344 COMPILE_DEFINITIONS and COMPILE_OPTIONS.
9345 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
9347 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
9348 set_property(TARGET mymod PROPERTY SWIG_COMPILE_DEFINITIONS MY_DEF1 MY_DEF2)
9349 set_property(TARGET mymod PROPERTY SWIG_COMPILE_OPTIONS -bla -blb)
9350 SWIG_USE_TARGET_INCLUDE_DIRECTORIES
9352 New in version 3.13.
9353 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
9356 will be forwarded to SWIG compiler. If set to FALSE or not de‐
9357 fined, target property INCLUDE_DIRECTORIES will be ignored. This
9358 behavior can be overridden by specifying source property
9359 USE_TARGET_INCLUDE_DIRECTORIES.
9360 SWIG_GENERATED_INCLUDE_DIRECTORIES, SWIG_GENERATED_COMPILE_DEFINITIONS
9362 and SWIG_GENERATED_COMPILE_OPTIONS
9363 New in version 3.12.
9364 These properties will populate, respectively, properties
9367 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_FLAGS of
9368 all generated C/C++ files.
9369 SWIG_DEPENDS
9371 New in version 3.12.
9372 Add dependencies to all SWIG input files.
9375 The following target properties are output properties and can be used
9377 to get information about support files generated by SWIG interface com‐
9378 pilation.
9379 SWIG_SUPPORT_FILES
9381 New in version 3.12.
9382 This output property list of wrapper files generated during SWIG
9385 compilation.
9386 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
9388 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
9389 get_property(support_files TARGET mymod PROPERTY SWIG_SUPPORT_FILES)
9390 NOTE:
9392 Only most principal support files are listed. In case some
9393 advanced features of SWIG are used (for example %template),
9394 associated support files may not be listed. Prefer to use the
9395 SWIG_SUPPORT_FILES_DIRECTORY property to handle support
9396 files.
9397 SWIG_SUPPORT_FILES_DIRECTORY
9399 New in version 3.12.
9400 This output property specifies the directory where support files
9403 will be generated.
9404 NOTE:
9406 When source property OUTPUT_DIR is defined, multiple directo‐
9407 ries can be specified as part of SWIG_SUPPORT_FILES_DIREC‐
9408 TORY.
9409 Some variables can be set to customize the behavior of swig_add_library
9411 as well as SWIG:
9412 UseSWIG_MODULE_VERSION
9414 New in version 3.12.
9415 Specify different behaviors for UseSWIG module.
9418 • Set to 1 or undefined: Legacy behavior is applied.
9420 • Set to 2: A new strategy is applied regarding support files:
9422 the output directory of support files is erased before SWIG
9423 interface compilation.
9424 CMAKE_SWIG_FLAGS
9426 Add flags to all swig calls.
9427 CMAKE_SWIG_OUTDIR
9429 Specify where to write the language specific files (swig -outdir
9430 option).
9431 SWIG_OUTFILE_DIR
9433 New in version 3.8.
9434 Specify an output directory name where the generated source file
9437 will be placed. If not specified, CMAKE_SWIG_OUTDIR is used.
9438 SWIG_MODULE_<name>_EXTRA_DEPS
9440 Specify extra dependencies for the generated module for <name>.
9441 SWIG_SOURCE_FILE_EXTENSIONS
9443 New in version 3.14.
9444 Specify a list of source file extensions to override the default
9447 behavior of considering only .i files as sources for the SWIG
9448 tool. For example:
9449 set(SWIG_SOURCE_FILE_EXTENSIONS ".i" ".swg")
9451 SWIG_USE_SWIG_DEPENDENCIES
9453 New in version 3.20.
9454 If set to TRUE, implicit dependencies are generated by the swig
9457 tool itself. This variable is only meaningful for Makefile,
9458 Ninja, Xcode, and Visual Studio (Visual Studio 11 2012 and
9459 above) generators. Default value is FALSE.
9460 Source file property USE_SWIG_DEPENDENCIES, if not defined, will
9462 be initialized with the value of this variable.
9463 New in version 3.21: Added the support of Xcode generator.
9465 New in version 3.22: Added the support of Visual Studio Genera‐
9468 tors.
9469 UsewxWidgets
9472 Convenience include for using wxWidgets library.
9473 Determines if wxWidgets was FOUND and sets the appropriate libs, in‐
9475 cdirs, flags, etc. INCLUDE_DIRECTORIES and LINK_DIRECTORIES are
9476 called.
9477 USAGE
9479 # Note that for MinGW users the order of libs is important!
9481 find_package(wxWidgets REQUIRED net gl core base)
9482 include(${wxWidgets_USE_FILE})
9483 # and for each of your dependent executable/library targets:
9484 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
9485 DEPRECATED
9487 LINK_LIBRARIES is not called in favor of adding dependencies per target.
9489 AUTHOR
9491 Jan Woetzel <jw -at- mip.informatik.uni-kiel.de>
9493
9495 These modules search for third-party software. They are normally
9496 called through the find_package() command.
9497 FindALSA
9499 Find Advanced Linux Sound Architecture (ALSA)
9500 Find the alsa libraries (asound)
9502 IMPORTED Targets
9504 New in version 3.12.
9505 This module defines IMPORTED target ALSA::ALSA, if ALSA has been found.
9508 Result Variables
9510 This module defines the following variables:
9511 ALSA_FOUND
9513 True if ALSA_INCLUDE_DIR & ALSA_LIBRARY are found
9514 ALSA_LIBRARIES
9516 List of libraries when using ALSA.
9517 ALSA_INCLUDE_DIRS
9519 Where to find the ALSA headers.
9520 Cache variables
9522 The following cache variables may also be set:
9523 ALSA_INCLUDE_DIR
9525 the ALSA include directory
9526 ALSA_LIBRARY
9528 the absolute path of the asound library
9529 FindArmadillo
9531 Find the Armadillo C++ library. Armadillo is a library for linear al‐
9532 gebra & scientific computing.
9533 New in version 3.18: Support for linking wrapped libraries directly
9535 (ARMA_DONT_USE_WRAPPER).
9536 Using Armadillo:
9539 find_package(Armadillo REQUIRED)
9541 include_directories(${ARMADILLO_INCLUDE_DIRS})
9542 add_executable(foo foo.cc)
9543 target_link_libraries(foo ${ARMADILLO_LIBRARIES})
9544 This module sets the following variables:
9546 ARMADILLO_FOUND - set to true if the library is found
9548 ARMADILLO_INCLUDE_DIRS - list of required include directories
9549 ARMADILLO_LIBRARIES - list of libraries to be linked
9550 ARMADILLO_VERSION_MAJOR - major version number
9551 ARMADILLO_VERSION_MINOR - minor version number
9552 ARMADILLO_VERSION_PATCH - patch version number
9553 ARMADILLO_VERSION_STRING - version number as a string (ex: "1.0.4")
9554 ARMADILLO_VERSION_NAME - name of the version (ex: "Antipodean Antileech")
9555 FindASPELL
9557 Try to find ASPELL
9558 Once done this will define
9560 ASPELL_FOUND - system has ASPELL
9562 ASPELL_EXECUTABLE - the ASPELL executable
9563 ASPELL_INCLUDE_DIR - the ASPELL include directory
9564 ASPELL_LIBRARIES - The libraries needed to use ASPELL
9565 ASPELL_DEFINITIONS - Compiler switches required for using ASPELL
9566 FindAVIFile
9568 Locate AVIFILE library and include paths
9569 AVIFILE (https://avifile.sourceforge.net/) is a set of libraries for
9571 i386 machines to use various AVI codecs. Support is limited beyond
9572 Linux. Windows provides native AVI support, and so doesn't need this
9573 library. This module defines
9574 AVIFILE_INCLUDE_DIR, where to find avifile.h , etc.
9576 AVIFILE_LIBRARIES, the libraries to link against
9577 AVIFILE_DEFINITIONS, definitions to use when compiling
9578 AVIFILE_FOUND, If false, don't try to use AVIFILE
9579 FindBacktrace
9581 Find provider for backtrace(3).
9582 Checks if OS supports backtrace(3) via either libc or custom library.
9584 This module defines the following variables:
9585 Backtrace_HEADER
9587 The header file needed for backtrace(3). Cached. Could be
9588 forcibly set by user.
9589 Backtrace_INCLUDE_DIRS
9591 The include directories needed to use backtrace(3) header.
9592 Backtrace_LIBRARIES
9594 The libraries (linker flags) needed to use backtrace(3), if any.
9595 Backtrace_FOUND
9597 Is set if and only if backtrace(3) support detected.
9598 The following cache variables are also available to set or use:
9600 Backtrace_LIBRARY
9602 The external library providing backtrace, if any.
9603 Backtrace_INCLUDE_DIR
9605 The directory holding the backtrace(3) header.
9606 Typical usage is to generate of header file using configure_file() with
9608 the contents like the following:
9609 #cmakedefine01 Backtrace_FOUND
9611 #if Backtrace_FOUND
9612 # include <${Backtrace_HEADER}>
9613 #endif
9614 And then reference that generated header file in actual source.
9616 FindBISON
9618 Find bison executable and provide a macro to generate custom build
9619 rules.
9620 The module defines the following variables:
9622 BISON_EXECUTABLE
9624 path to the bison program
9625 BISON_VERSION
9627 version of bison
9628 BISON_FOUND
9630 "True" if the program was found
9631 The minimum required version of bison can be specified using the stan‐
9633 dard CMake syntax, e.g. find_package(BISON 2.1.3).
9634 If bison is found, the module defines the macro:
9636 BISON_TARGET(<Name> <YaccInput> <CodeOutput>
9638 [COMPILE_FLAGS <flags>]
9639 [DEFINES_FILE <file>]
9640 [VERBOSE [<file>]]
9641 [REPORT_FILE <file>]
9642 )
9643 which will create a custom rule to generate a parser. <YaccInput> is
9645 the path to a yacc file. <CodeOutput> is the name of the source file
9646 generated by bison. A header file is also be generated, and contains
9647 the token list.
9648 Changed in version 3.14: When CMP0088 is set to NEW, bison runs in the
9650 CMAKE_CURRENT_BINARY_DIR directory.
9651 The options are:
9654 COMPILE_FLAGS <flags>
9656 Specify flags to be added to the bison command line.
9657 DEFINES_FILE <file>
9659 New in version 3.4.
9660 Specify a non-default header <file> to be generated by bison.
9663 VERBOSE [<file>]
9665 Tell bison to write a report file of the grammar and parser.
9666 Deprecated since version 3.7: If <file> is given, it specifies
9668 path the report file is copied to. [<file>] is left for back‐
9669 ward compatibility of this module. Use VERBOSE REPORT_FILE
9670 <file>.
9671 REPORT_FILE <file>
9674 New in version 3.7.
9675 Specify a non-default report <file>, if generated.
9678 The macro defines the following variables:
9680 BISON_<Name>_DEFINED
9682 True is the macro ran successfully
9683 BISON_<Name>_INPUT
9685 The input source file, an alias for <YaccInput>
9686 BISON_<Name>_OUTPUT_SOURCE
9688 The source file generated by bison
9689 BISON_<Name>_OUTPUT_HEADER
9691 The header file generated by bison
9692 BISON_<Name>_OUTPUTS
9694 All files generated by bison including the source, the header
9695 and the report
9696 BISON_<Name>_COMPILE_FLAGS
9698 Options used in the bison command line
9699 Example usage:
9701 find_package(BISON)
9703 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp
9704 DEFINES_FILE ${CMAKE_CURRENT_BINARY_DIR}/parser.h)
9705 add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
9706 FindBLAS
9708 Find Basic Linear Algebra Subprograms (BLAS) library
9709 This module finds an installed Fortran library that implements the BLAS
9711 linear-algebra interface.
9712 At least one of the C, CXX, or Fortran languages must be enabled.
9714 Input Variables
9716 The following variables may be set to influence this module's behavior:
9717 BLA_STATIC
9719 if ON use static linkage
9720 BLA_VENDOR
9722 Set to one of the BLAS/LAPACK Vendors to search for BLAS only
9723 from the specified vendor. If not set, all vendors are consid‐
9724 ered.
9725 BLA_F95
9727 if ON tries to find the BLAS95 interfaces
9728 BLA_PREFER_PKGCONFIG
9730 New in version 3.11.
9731 if set pkg-config will be used to search for a BLAS library
9734 first and if one is found that is preferred
9735 BLA_PKGCONFIG_BLAS
9737 New in version 3.25.
9738 If set, the pkg-config method will look for this module name in‐
9741 stead of just blas.
9742 BLA_SIZEOF_INTEGER
9744 New in version 3.22.
9745 Specify the BLAS/LAPACK library integer size:
9748 4 Search for a BLAS/LAPACK with 32-bit integer interfaces.
9750 8 Search for a BLAS/LAPACK with 64-bit integer interfaces.
9752 ANY Search for any BLAS/LAPACK. Most likely, a BLAS/LAPACK
9754 with 32-bit integer interfaces will be found.
9755 Imported targets
9757 This module defines the following IMPORTED targets:
9758 BLAS::BLAS
9760 New in version 3.18.
9761 The libraries to use for BLAS, if found.
9764 Result Variables
9766 This module defines the following variables:
9767 BLAS_FOUND
9769 library implementing the BLAS interface is found
9770 BLAS_LINKER_FLAGS
9772 uncached list of required linker flags (excluding -l and -L).
9773 BLAS_LIBRARIES
9775 uncached list of libraries (using full path name) to link
9776 against to use BLAS (may be empty if compiler implicitly links
9777 BLAS)
9778 BLAS95_LIBRARIES
9780 uncached list of libraries (using full path name) to link
9781 against to use BLAS95 interface
9782 BLAS95_FOUND
9784 library implementing the BLAS95 interface is found
9785 BLAS/LAPACK Vendors
9787 Generic
9788 Generic reference implementation
9789 ACML, ACML_MP, ACML_GPU
9791 AMD Core Math Library
9792 Apple, NAS
9794 Apple BLAS (Accelerate), and Apple NAS (vecLib)
9795 Arm, Arm_mp, Arm_ilp64, Arm_ilp64_mp
9797 New in version 3.18.
9798 Arm Performance Libraries
9801 ATLAS Automatically Tuned Linear Algebra Software
9803 CXML, DXML
9805 Compaq/Digital Extended Math Library
9806 EML, EML_mt
9808 New in version 3.20.
9809 Elbrus Math Library
9812 FLAME New in version 3.11.
9814 BLIS Framework
9817 FlexiBLAS
9819 New in version 3.19.
9820 Fujitsu_SSL2, Fujitsu_SSL2BLAMP, Fujitsu_SSL2SVE, Fujitsu_SSL2BLAMPSVE
9823 New in version 3.20.
9824 Fujitsu SSL2 serial and parallel blas/lapack with SVE instruc‐
9827 tions
9828 Goto GotoBLAS
9830 IBMESSL, IBMESSL_SMP
9832 IBM Engineering and Scientific Subroutine Library
9833 Intel Intel MKL 32 bit and 64 bit obsolete versions
9835 Intel10_32
9837 Intel MKL v10 32 bit, threaded code
9838 Intel10_64lp
9840 Intel MKL v10+ 64 bit, threaded code, lp64 model
9841 Intel10_64lp_seq
9843 Intel MKL v10+ 64 bit, sequential code, lp64 model
9844 Intel10_64ilp
9846 New in version 3.13.
9847 Intel MKL v10+ 64 bit, threaded code, ilp64 model
9850 Intel10_64ilp_seq
9852 New in version 3.13.
9853 Intel MKL v10+ 64 bit, sequential code, ilp64 model
9856 Intel10_64_dyn
9858 New in version 3.17.
9859 Intel MKL v10+ 64 bit, single dynamic library
9862 NVHPC New in version 3.21.
9864 NVIDIA HPC SDK
9867 OpenBLAS
9869 New in version 3.6.
9870 PhiPACK
9873 Portable High Performance ANSI C (PHiPAC)
9874 SCSL, SCSL_mp
9876 Scientific Computing Software Library
9877 SGIMATH
9879 SGI Scientific Mathematical Library
9880 SunPerf
9882 Sun Performance Library
9883 Intel MKL
9885 To use the Intel MKL implementation of BLAS, a project must enable at
9886 least one of the C or CXX languages. Set BLA_VENDOR to an Intel MKL
9887 variant either on the command-line as -DBLA_VENDOR=Intel10_64lp or in
9888 project code:
9889 set(BLA_VENDOR Intel10_64lp)
9891 find_package(BLAS)
9892 In order to build a project using Intel MKL, and end user must first
9894 establish an Intel MKL environment:
9895 Intel oneAPI
9897 Source the full Intel environment script:
9898 . /opt/intel/oneapi/setvars.sh
9900 Or, source the MKL component environment script:
9902 . /opt/intel/oneapi/mkl/latest/env/vars.sh
9904 Intel Classic
9906 Source the full Intel environment script:
9907 . /opt/intel/bin/compilervars.sh intel64
9909 Or, source the MKL component environment script:
9911 . /opt/intel/mkl/bin/mklvars.sh intel64
9913 The above environment scripts set the MKLROOT environment variable to
9915 the top of the MKL installation. They also add the location of the
9916 runtime libraries to the dynamic library loader environment variable
9917 for your platform (e.g. LD_LIBRARY_PATH). This is necessary for pro‐
9918 grams linked against MKL to run.
9919 NOTE:
9921 As of Intel oneAPI 2021.2, loading only the MKL component does not
9922 make all of its dependencies available. In particular, the iomp5
9923 library must be available separately, or provided by also loading
9924 the compiler component environment:
9925 . /opt/intel/oneapi/compiler/latest/env/vars.sh
9927 FindBoost
9929 Find Boost include dirs and libraries
9930 Use this module by invoking find_package() with the form:
9932 find_package(Boost
9934 [version] [EXACT] # Minimum or EXACT version e.g. 1.67.0
9935 [REQUIRED] # Fail with error if Boost is not found
9936 [COMPONENTS <libs>...] # Boost libraries by their canonical name
9937 # e.g. "date_time" for "libboost_date_time"
9938 [OPTIONAL_COMPONENTS <libs>...]
9939 # Optional Boost libraries by their canonical name)
9940 ) # e.g. "date_time" for "libboost_date_time"
9941 This module finds headers and requested component libraries OR a CMake
9943 package configuration file provided by a "Boost CMake" build. For the
9944 latter case skip to the Boost CMake section below.
9945 New in version 3.7: bzip2 and zlib components (Windows only).
9947 New in version 3.11: The OPTIONAL_COMPONENTS option.
9950 New in version 3.13: stacktrace_* components.
9953 New in version 3.19: bzip2 and zlib components on all platforms.
9956 Result Variables
9959 This module defines the following variables:
9960 Boost_FOUND
9962 True if headers and requested libraries were found.
9963 Boost_INCLUDE_DIRS
9965 Boost include directories.
9966 Boost_LIBRARY_DIRS
9968 Link directories for Boost libraries.
9969 Boost_LIBRARIES
9971 Boost component libraries to be linked.
9972 Boost_<COMPONENT>_FOUND
9974 True if component <COMPONENT> was found (<COMPONENT> name is up‐
9975 per-case).
9976 Boost_<COMPONENT>_LIBRARY
9978 Libraries to link for component <COMPONENT> (may include
9979 target_link_libraries() debug/optimized keywords).
9980 Boost_VERSION_MACRO
9982 BOOST_VERSION value from boost/version.hpp.
9983 Boost_VERSION_STRING
9985 Boost version number in X.Y.Z format.
9986 Boost_VERSION
9988 Boost version number in X.Y.Z format (same as Boost_VER‐
9989 SION_STRING).
9990 Changed in version 3.15: In previous CMake versions, this vari‐
9992 able used the raw version string from the Boost header (same as
9993 Boost_VERSION_MACRO). See policy CMP0093.
9994 Boost_LIB_VERSION
9997 Version string appended to library filenames.
9998 Boost_VERSION_MAJOR, Boost_MAJOR_VERSION
10000 Boost major version number (X in X.Y.Z).
10001 Boost_VERSION_MINOR, Boost_MINOR_VERSION
10003 Boost minor version number (Y in X.Y.Z).
10004 Boost_VERSION_PATCH, Boost_SUBMINOR_VERSION
10006 Boost subminor version number (Z in X.Y.Z).
10007 Boost_VERSION_COUNT
10009 Amount of version components (3).
10010 Boost_LIB_DIAGNOSTIC_DEFINITIONS (Windows-specific)
10012 Pass to add_definitions() to have diagnostic information about
10013 Boost's automatic linking displayed during compilation
10014 New in version 3.15: The Boost_VERSION_<PART> variables.
10016 Cache variables
10019 Search results are saved persistently in CMake cache entries:
10020 Boost_INCLUDE_DIR
10022 Directory containing Boost headers.
10023 Boost_LIBRARY_DIR_RELEASE
10025 Directory containing release Boost libraries.
10026 Boost_LIBRARY_DIR_DEBUG
10028 Directory containing debug Boost libraries.
10029 Boost_<COMPONENT>_LIBRARY_DEBUG
10031 Component <COMPONENT> library debug variant.
10032 Boost_<COMPONENT>_LIBRARY_RELEASE
10034 Component <COMPONENT> library release variant.
10035 New in version 3.3: Per-configuration variables Boost_LIBRARY_DIR_RE‐
10037 LEASE and Boost_LIBRARY_DIR_DEBUG.
10038 Hints
10041 This module reads hints about search locations from variables:
10042 BOOST_ROOT, BOOSTROOT
10044 Preferred installation prefix.
10045 BOOST_INCLUDEDIR
10047 Preferred include directory e.g. <prefix>/include.
10048 BOOST_LIBRARYDIR
10050 Preferred library directory e.g. <prefix>/lib.
10051 Boost_NO_SYSTEM_PATHS
10053 Set to ON to disable searching in locations not specified by
10054 these hint variables. Default is OFF.
10055 Boost_ADDITIONAL_VERSIONS
10057 List of Boost versions not known to this module. (Boost install
10058 locations may contain the version).
10059 Users may set these hints or results as CACHE entries. Projects should
10061 not read these entries directly but instead use the above result vari‐
10062 ables. Note that some hint names start in upper-case BOOST. One may
10063 specify these as environment variables if they are not specified as
10064 CMake variables or cache entries.
10065 This module first searches for the Boost header files using the above
10067 hint variables (excluding BOOST_LIBRARYDIR) and saves the result in
10068 Boost_INCLUDE_DIR. Then it searches for requested component libraries
10069 using the above hints (excluding BOOST_INCLUDEDIR and Boost_ADDI‐
10070 TIONAL_VERSIONS), "lib" directories near Boost_INCLUDE_DIR, and the li‐
10071 brary name configuration settings below. It saves the library directo‐
10072 ries in Boost_LIBRARY_DIR_DEBUG and Boost_LIBRARY_DIR_RELEASE and indi‐
10073 vidual library locations in Boost_<COMPONENT>_LIBRARY_DEBUG and
10074 Boost_<COMPONENT>_LIBRARY_RELEASE. When one changes settings used by
10075 previous searches in the same build tree (excluding environment vari‐
10076 ables) this module discards previous search results affected by the
10077 changes and searches again.
10078 Imported Targets
10080 New in version 3.5.
10081 This module defines the following IMPORTED targets:
10084 Boost::boost
10086 Target for header-only dependencies. (Boost include directory).
10087 Boost::headers
10089 New in version 3.15: Alias for Boost::boost.
10090 Boost::<component>
10093 Target for specific component dependency (shared or static li‐
10094 brary); <component> name is lower-case.
10095 Boost::diagnostic_definitions
10097 Interface target to enable diagnostic information about Boost's
10098 automatic linking during compilation (adds -DBOOST_LIB_DIAGNOS‐
10099 TIC).
10100 Boost::disable_autolinking
10102 Interface target to disable automatic linking with MSVC (adds
10103 -DBOOST_ALL_NO_LIB).
10104 Boost::dynamic_linking
10106 Interface target to enable dynamic linking with MSVC (adds
10107 -DBOOST_ALL_DYN_LINK).
10108 Implicit dependencies such as Boost::filesystem requiring Boost::system
10110 will be automatically detected and satisfied, even if system is not
10111 specified when using find_package() and if Boost::system is not added
10112 to target_link_libraries(). If using Boost::thread, then
10113 Threads::Threads will also be added automatically.
10114 It is important to note that the imported targets behave differently
10116 than variables created by this module: multiple calls to
10117 find_package(Boost) in the same directory or sub-directories with dif‐
10118 ferent options (e.g. static or shared) will not override the values of
10119 the targets created by the first call.
10120 Other Variables
10122 Boost libraries come in many variants encoded in their file name.
10123 Users or projects may tell this module which variant to find by setting
10124 variables:
10125 Boost_USE_DEBUG_LIBS
10127 New in version 3.10.
10128 Set to ON or OFF to specify whether to search and use the debug
10131 libraries. Default is ON.
10132 Boost_USE_RELEASE_LIBS
10134 New in version 3.10.
10135 Set to ON or OFF to specify whether to search and use the re‐
10138 lease libraries. Default is ON.
10139 Boost_USE_MULTITHREADED
10141 Set to OFF to use the non-multithreaded libraries ("mt" tag).
10142 Default is ON.
10143 Boost_USE_STATIC_LIBS
10145 Set to ON to force the use of the static libraries. Default is
10146 OFF.
10147 Boost_USE_STATIC_RUNTIME
10149 Set to ON or OFF to specify whether to use libraries linked
10150 statically to the C++ runtime ("s" tag). Default is platform
10151 dependent.
10152 Boost_USE_DEBUG_RUNTIME
10154 Set to ON or OFF to specify whether to use libraries linked to
10155 the MS debug C++ runtime ("g" tag). Default is ON.
10156 Boost_USE_DEBUG_PYTHON
10158 Set to ON to use libraries compiled with a debug Python build
10159 ("y" tag). Default is OFF.
10160 Boost_USE_STLPORT
10162 Set to ON to use libraries compiled with STLPort ("p" tag). De‐
10163 fault is OFF.
10164 Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
10166 Set to ON to use libraries compiled with STLPort deprecated "na‐
10167 tive iostreams" ("n" tag). Default is OFF.
10168 Boost_COMPILER
10170 Set to the compiler-specific library suffix (e.g. -gcc43). De‐
10171 fault is auto-computed for the C++ compiler in use.
10172 Changed in version 3.9: A list may be used if multiple compati‐
10174 ble suffixes should be tested for, in decreasing order of pref‐
10175 erence.
10176 Boost_LIB_PREFIX
10179 New in version 3.18.
10180 Set to the platform-specific library name prefix (e.g. lib) used
10183 by Boost static libs. This is needed only on platforms where
10184 CMake does not know the prefix by default.
10185 Boost_ARCHITECTURE
10187 New in version 3.13.
10188 Set to the architecture-specific library suffix (e.g. -x64).
10191 Default is auto-computed for the C++ compiler in use.
10192 Boost_THREADAPI
10194 Suffix for thread component library name, such as pthread or
10195 win32. Names with and without this suffix will both be tried.
10196 Boost_NAMESPACE
10198 Alternate namespace used to build boost with e.g. if set to my‐
10199 boost, will search for myboost_thread instead of boost_thread.
10200 Other variables one may set to control this module are:
10202 Boost_DEBUG
10204 Set to ON to enable debug output from FindBoost. Please enable
10205 this before filing any bug report.
10206 Boost_REALPATH
10208 Set to ON to resolve symlinks for discovered libraries to assist
10209 with packaging. For example, the "system" component library may
10210 be resolved to /usr/lib/libboost_system.so.1.67.0 instead of
10211 /usr/lib/libboost_system.so. This does not affect linking and
10212 should not be enabled unless the user needs this information.
10213 Boost_LIBRARY_DIR
10215 Default value for Boost_LIBRARY_DIR_RELEASE and Boost_LI‐
10216 BRARY_DIR_DEBUG.
10217 Boost_NO_WARN_NEW_VERSIONS
10219 New in version 3.20.
10220 Set to ON to suppress the warning about unknown dependencies for
10223 new Boost versions.
10224 On Visual Studio and Borland compilers Boost headers request automatic
10226 linking to corresponding libraries. This requires matching libraries
10227 to be linked explicitly or available in the link library search path.
10228 In this case setting Boost_USE_STATIC_LIBS to OFF may not achieve dy‐
10229 namic linking. Boost automatic linking typically requests static li‐
10230 braries with a few exceptions (such as Boost.Python). Use:
10231 add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})
10233 to ask Boost to report information about automatic linking requests.
10235 Examples
10237 Find Boost headers only:
10238 find_package(Boost 1.36.0)
10240 if(Boost_FOUND)
10241 include_directories(${Boost_INCLUDE_DIRS})
10242 add_executable(foo foo.cc)
10243 endif()
10244 Find Boost libraries and use imported targets:
10246 find_package(Boost 1.56 REQUIRED COMPONENTS
10248 date_time filesystem iostreams)
10249 add_executable(foo foo.cc)
10250 target_link_libraries(foo Boost::date_time Boost::filesystem
10251 Boost::iostreams)
10252 Find Boost Python 3.6 libraries and use imported targets:
10254 find_package(Boost 1.67 REQUIRED COMPONENTS
10256 python36 numpy36)
10257 add_executable(foo foo.cc)
10258 target_link_libraries(foo Boost::python36 Boost::numpy36)
10259 Find Boost headers and some static (release only) libraries:
10261 set(Boost_USE_STATIC_LIBS ON) # only find static libs
10263 set(Boost_USE_DEBUG_LIBS OFF) # ignore debug libs and
10264 set(Boost_USE_RELEASE_LIBS ON) # only find release libs
10265 set(Boost_USE_MULTITHREADED ON)
10266 set(Boost_USE_STATIC_RUNTIME OFF)
10267 find_package(Boost 1.66.0 COMPONENTS date_time filesystem system ...)
10268 if(Boost_FOUND)
10269 include_directories(${Boost_INCLUDE_DIRS})
10270 add_executable(foo foo.cc)
10271 target_link_libraries(foo ${Boost_LIBRARIES})
10272 endif()
10273 Boost CMake
10275 If Boost was built using the boost-cmake project or from Boost 1.70.0
10276 on it provides a package configuration file for use with find_package's
10277 config mode. This module looks for the package configuration file
10278 called BoostConfig.cmake or boost-config.cmake and stores the result in
10279 CACHE entry Boost_DIR. If found, the package configuration file is
10280 loaded and this module returns with no further action. See documenta‐
10281 tion of the Boost CMake package configuration for details on what it
10282 provides.
10283 Set Boost_NO_BOOST_CMAKE to ON, to disable the search for boost-cmake.
10285 FindBullet
10287 Try to find the Bullet physics engine
10288 This module defines the following variables
10290 BULLET_FOUND - Was bullet found
10292 BULLET_INCLUDE_DIRS - the Bullet include directories
10293 BULLET_LIBRARIES - Link to this, by default it includes
10294 all bullet components (Dynamics,
10295 Collision, LinearMath, & SoftBody)
10296 This module accepts the following variables
10298 BULLET_ROOT - Can be set to bullet install path or Windows build path
10300 FindBZip2
10302 Try to find BZip2
10303 IMPORTED Targets
10305 New in version 3.12.
10306 This module defines IMPORTED target BZip2::BZip2, if BZip2 has been
10309 found.
10310 Result Variables
10312 This module defines the following variables:
10313 BZIP2_FOUND
10315 system has BZip2
10316 BZIP2_INCLUDE_DIRS
10318 New in version 3.12: the BZip2 include directories
10319 BZIP2_LIBRARIES
10322 Link these to use BZip2
10323 BZIP2_NEED_PREFIX
10325 this is set if the functions are prefixed with BZ2_
10326 BZIP2_VERSION_STRING
10328 the version of BZip2 found
10329 Cache variables
10331 The following cache variables may also be set:
10332 BZIP2_INCLUDE_DIR
10334 the BZip2 include directory
10335 FindCABLE
10337 Find CABLE
10338 This module finds if CABLE is installed and determines where the in‐
10340 clude files and libraries are. This code sets the following variables:
10341 CABLE the path to the cable executable
10343 CABLE_TCL_LIBRARY the path to the Tcl wrapper library
10344 CABLE_INCLUDE_DIR the path to the include directory
10345 To build Tcl wrappers, you should add shared library and link it to
10347 ${CABLE_TCL_LIBRARY}. You should also add ${CABLE_INCLUDE_DIR} as an
10348 include directory.
10349 FindCoin3D
10351 Find Coin3D (Open Inventor)
10352 Coin3D is an implementation of the Open Inventor API. It provides data
10354 structures and algorithms for 3D visualization.
10355 This module defines the following variables
10357 COIN3D_FOUND - system has Coin3D - Open Inventor
10359 COIN3D_INCLUDE_DIRS - where the Inventor include directory can be found
10360 COIN3D_LIBRARIES - Link to this to use Coin3D
10361 FindCUDAToolkit
10363 New in version 3.17.
10364 This script locates the NVIDIA CUDA toolkit and the associated li‐
10367 braries, but does not require the CUDA language be enabled for a given
10368 project. This module does not search for the NVIDIA CUDA Samples.
10369 New in version 3.19: QNX support.
10371 Search Behavior
10374 The CUDA Toolkit search behavior uses the following order:
10375 1. If the CUDA language has been enabled we will use the directory con‐
10377 taining the compiler as the first search location for nvcc.
10378 2. If the CUDAToolkit_ROOT cmake configuration variable (e.g., -DCUDA‐
10380 Toolkit_ROOT=/some/path) or environment variable is defined, it will
10381 be searched. If both an environment variable and a configuration
10382 variable are specified, the configuration variable takes precedence.
10383 The directory specified here must be such that the executable nvcc
10385 or the appropriate version.txt file can be found underneath the
10386 specified directory.
10387 3. If the CUDA_PATH environment variable is defined, it will be
10389 searched for nvcc.
10390 4. The user's path is searched for nvcc using find_program(). If this
10392 is found, no subsequent search attempts are performed. Users are
10393 responsible for ensuring that the first nvcc to show up in the path
10394 is the desired path in the event that multiple CUDA Toolkits are in‐
10395 stalled.
10396 5. On Unix systems, if the symbolic link /usr/local/cuda exists, this
10398 is used. No subsequent search attempts are performed. No default
10399 symbolic link location exists for the Windows platform.
10400 6. The platform specific default install locations are searched. If
10402 exactly one candidate is found, this is used. The default CUDA
10403 Toolkit install locations searched are:
10404 ┌───────────┬────────────────────────────┐
10406 │Platform │ Search Pattern │
10407 ├───────────┼────────────────────────────┤
10408 │macOS │ /Developer/NVIDIA/CUDA-X.Y │
10409 ├───────────┼────────────────────────────┤
10410 │Other Unix │ /usr/local/cuda-X.Y │
10411 └───────────┴────────────────────────────┘
10412 │Windows │ C:\Program Files\NVIDIA │
10416 │ │ GPU Computing Tool‐ │
10417 │ │ kit\CUDA\vX.Y │
10418 └───────────┴────────────────────────────┘
10419 Where X.Y would be a specific version of the CUDA Toolkit, such as
10421 /usr/local/cuda-9.0 or C:\Program Files\NVIDIA GPU Computing Tool‐
10422 kit\CUDA\v9.0
10423 NOTE:
10425 When multiple CUDA Toolkits are installed in the default location
10426 of a system (e.g., both /usr/local/cuda-9.0 and /usr/lo‐
10427 cal/cuda-10.0 exist but the /usr/local/cuda symbolic link does
10428 not exist), this package is marked as not found.
10429 There are too many factors involved in making an automatic deci‐
10431 sion in the presence of multiple CUDA Toolkits being installed.
10432 In this situation, users are encouraged to either (1) set CUDA‐
10433 Toolkit_ROOT [22mor (2) ensure that the correct nvcc executable shows
10434 up in $PATH for find_program() to find.
10435 Arguments
10437 [<version>]
10438 The [<version>] argument requests a version with which the pack‐
10439 age found should be compatible. See find_package version format
10440 for more details.
10441 Options
10443 REQUIRED
10444 If specified, configuration will error if a suitable CUDA Tool‐
10445 kit is not found.
10446 QUIET If specified, the search for a suitable CUDA Toolkit will not
10448 produce any messages.
10449 EXACT If specified, the CUDA Toolkit is considered found only if the
10451 exact VERSION specified is recovered.
10452 Imported targets
10454 An imported target named CUDA::toolkit is provided.
10455 This module defines IMPORTED targets for each of the following li‐
10457 braries that are part of the CUDAToolkit:
10458 • CUDA Runtime Library
10460 • CUDA Driver Library
10462 • cuBLAS
10464 • cuFile
10466 • cuFFT
10468 • cuRAND
10470 • cuSOLVER
10472 • cuSPARSE
10474 • cuPTI
10476 • NPP
10478 • nvBLAS
10480 • nvGRAPH
10482 • nvJPEG
10484 • nvidia-ML
10486 • nvPTX Compiler
10488 • nvRTC
10490 • nvToolsExt
10492 • nvtx3
10494 • OpenCL
10496 • cuLIBOS
10498 CUDA Runtime Library
10500 The CUDA Runtime library (cudart) are what most applications will typi‐
10501 cally need to link against to make any calls such as cudaMalloc, and
10502 cudaFree.
10503 Targets Created:
10505 • CUDA::cudart
10507 • CUDA::cudart_static
10509 CUDA Driver Library
10511 The CUDA Driver library (cuda) are used by applications that use calls
10512 such as cuMemAlloc, and cuMemFree.
10513 Targets Created:
10515 • CUDA::cuda_driver
10517 cuBLAS
10519 The cuBLAS library.
10520 Targets Created:
10522 • CUDA::cublas
10524 • CUDA::cublas_static
10526 • CUDA::cublasLt starting in CUDA 10.1
10528 • CUDA::cublasLt_static starting in CUDA 10.1
10530 cuFile
10532 New in version 3.25.
10533 The NVIDIA GPUDirect Storage cuFile library.
10536 Targets Created:
10538 • CUDA::cuFile starting in CUDA 11.4
10540 • CUDA::cuFile_static starting in CUDA 11.4
10542 • CUDA::cuFile_rdma starting in CUDA 11.4
10544 • CUDA::cuFile_rdma_static starting in CUDA 11.4
10546 cuFFT
10548 The cuFFT library.
10549 Targets Created:
10551 • CUDA::cufft
10553 • CUDA::cufftw
10555 • CUDA::cufft_static
10557 • CUDA::cufft_static_nocallback starting in CUDA 9.2, requires CMake
10559 3.23+
10560 • CUDA::cufftw_static
10562 cuRAND
10564 The cuRAND library.
10565 Targets Created:
10567 • CUDA::curand
10569 • CUDA::curand_static
10571 cuSOLVER
10573 The cuSOLVER library.
10574 Targets Created:
10576 • CUDA::cusolver
10578 • CUDA::cusolver_static
10580 cuSPARSE
10582 The cuSPARSE library.
10583 Targets Created:
10585 • CUDA::cusparse
10587 • CUDA::cusparse_static
10589 cupti
10591 The NVIDIA CUDA Profiling Tools Interface.
10592 Targets Created:
10594 • CUDA::cupti
10596 • CUDA::cupti_static
10598 NPP
10600 The NPP libraries.
10601 Targets Created:
10603 • nppc:
10605 • CUDA::nppc
10607 • CUDA::nppc_static
10609 • nppial: Arithmetic and logical operation functions in nppi_arith‐
10611 metic_and_logical_operations.h
10612 • CUDA::nppial
10614 • CUDA::nppial_static
10616 • nppicc: Color conversion and sampling functions in nppi_color_conver‐
10618 sion.h
10619 • CUDA::nppicc
10621 • CUDA::nppicc_static
10623 • nppicom: JPEG compression and decompression functions in nppi_com‐
10625 pression_functions.h Removed starting in CUDA 11.0, use nvJPEG in‐
10626 stead.
10627 • CUDA::nppicom
10629 • CUDA::nppicom_static
10631 • nppidei: Data exchange and initialization functions in nppi_data_ex‐
10633 change_and_initialization.h
10634 • CUDA::nppidei
10636 • CUDA::nppidei_static
10638 • nppif: Filtering and computer vision functions in nppi_filter_func‐
10640 tions.h
10641 • CUDA::nppif
10643 • CUDA::nppif_static
10645 • nppig: Geometry transformation functions found in nppi_geome‐
10647 try_transforms.h
10648 • CUDA::nppig
10650 • CUDA::nppig_static
10652 • nppim: Morphological operation functions found in nppi_morphologi‐
10654 cal_operations.h
10655 • CUDA::nppim
10657 • CUDA::nppim_static
10659 • nppist: Statistics and linear transform in nppi_statistics_func‐
10661 tions.h and nppi_linear_transforms.h
10662 • CUDA::nppist
10664 • CUDA::nppist_static
10666 • nppisu: Memory support functions in nppi_support_functions.h
10668 • CUDA::nppisu
10670 • CUDA::nppisu_static
10672 • nppitc: Threshold and compare operation functions in nppi_thresh‐
10674 old_and_compare_operations.h
10675 • CUDA::nppitc
10677 • CUDA::nppitc_static
10679 • npps:
10681 • CUDA::npps
10683 • CUDA::npps_static
10685 nvBLAS
10687 The nvBLAS libraries. This is a shared library only.
10688 Targets Created:
10690 • CUDA::nvblas
10692 nvGRAPH
10694 The nvGRAPH library. Removed starting in CUDA 11.0
10695 Targets Created:
10697 • CUDA::nvgraph
10699 • CUDA::nvgraph_static
10701 nvJPEG
10703 The nvJPEG library. Introduced in CUDA 10.
10704 Targets Created:
10706 • CUDA::nvjpeg
10708 • CUDA::nvjpeg_static
10710 nvPTX Compiler
10712 New in version 3.25.
10713 The nvPTX (PTX Compilation) library. The PTX Compiler APIs are a set
10716 of APIs which can be used to compile a PTX program into GPU assembly
10717 code. Introduced in CUDA 11.1 This is a static library only.
10718 Targets Created:
10720 • CUDA::nvptxcompiler_static starting in CUDA 11.1
10722 nvRTC
10724 The nvRTC (Runtime Compilation) library. This is a shared library
10725 only.
10726 Targets Created:
10728 • CUDA::nvrtc
10730 nvidia-ML
10732 The NVIDIA Management Library. This is a shared library only.
10733 Targets Created:
10735 • CUDA::nvml
10737 nvToolsExt
10739 Deprecated since version 3.25: With CUDA 10.0+, use nvtx3.
10740 The NVIDIA Tools Extension. This is a shared library only.
10743 Targets Created:
10745 • CUDA::nvToolsExt
10747 nvtx3
10749 New in version 3.25.
10750 The header-only NVIDIA Tools Extension Library. Introduced in CUDA
10753 10.0.
10754 Targets created:
10756 • CUDA::nvtx3
10758 OpenCL
10760 The NVIDIA OpenCL Library. This is a shared library only.
10761 Targets Created:
10763 • CUDA::OpenCL
10765 cuLIBOS
10767 The cuLIBOS library is a backend thread abstraction layer library which
10768 is static only. The CUDA::cublas_static, CUDA::cusparse_static,
10769 CUDA::cufft_static, CUDA::curand_static, and (when implemented) NPP li‐
10770 braries all automatically have this dependency linked.
10771 Target Created:
10773 • CUDA::culibos
10775 Note: direct usage of this target by consumers should not be necessary.
10777 Result variables
10779 CUDAToolkit_FOUND
10780 A boolean specifying whether or not the CUDA Toolkit was found.
10781 CUDAToolkit_VERSION
10783 The exact version of the CUDA Toolkit found (as reported by nvcc
10784 --version or version.txt).
10785 CUDAToolkit_VERSION_MAJOR
10787 The major version of the CUDA Toolkit.
10788 CUDAToolkit_VERSION_MINOR
10790 The minor version of the CUDA Toolkit.
10791 CUDAToolkit_VERSION_PATCH
10793 The patch version of the CUDA Toolkit.
10794 CUDAToolkit_BIN_DIR
10796 The path to the CUDA Toolkit library directory that contains the
10797 CUDA executable nvcc.
10798 CUDAToolkit_INCLUDE_DIRS
10800 The path to the CUDA Toolkit include folder containing the
10801 header files required to compile a project linking against CUDA.
10802 CUDAToolkit_LIBRARY_DIR
10804 The path to the CUDA Toolkit library directory that contains the
10805 CUDA Runtime library cudart.
10806 CUDAToolkit_LIBRARY_ROOT
10808 New in version 3.18.
10809 The path to the CUDA Toolkit directory containing the nvvm di‐
10812 rectory and version.txt.
10813 CUDAToolkit_TARGET_DIR
10815 The path to the CUDA Toolkit directory including the target ar‐
10816 chitecture when cross-compiling. When not cross-compiling this
10817 will be equivalent to the parent directory of CUDA‐
10818 Toolkit_BIN_DIR.
10819 CUDAToolkit_NVCC_EXECUTABLE
10821 The path to the NVIDIA CUDA compiler nvcc. Note that this path
10822 may not be the same as CMAKE_CUDA_COMPILER. nvcc must be found
10823 to determine the CUDA Toolkit version as well as determining
10824 other features of the Toolkit. This variable is set for the
10825 convenience of modules that depend on this one.
10826 FindCups
10828 Find the Common UNIX Printing System (CUPS).
10829 Set CUPS_REQUIRE_IPP_DELETE_ATTRIBUTE to TRUE if you need a version
10831 which features this function (i.e. at least 1.1.19)
10832 Imported targets
10834 New in version 3.15.
10835 This module defines IMPORTED target Cups::Cups, if Cups has been found.
10838 Result variables
10840 This module will set the following variables in your project:
10841 CUPS_FOUND
10843 true if CUPS headers and libraries were found
10844 CUPS_INCLUDE_DIRS
10846 the directory containing the Cups headers
10847 CUPS_LIBRARIES
10849 the libraries to link against to use CUPS.
10850 CUPS_VERSION_STRING
10852 the version of CUPS found (since CMake 2.8.8)
10853 Cache variables
10855 The following cache variables may also be set:
10856 CUPS_INCLUDE_DIR
10858 the directory containing the Cups headers
10859 FindCURL
10861 Find the native CURL headers and libraries.
10862 New in version 3.14: This module accept optional COMPONENTS to check
10864 supported features and protocols:
10865 PROTOCOLS: ICT FILE FTP FTPS GOPHER HTTP HTTPS IMAP IMAPS LDAP LDAPS POP3
10868 POP3S RTMP RTSP SCP SFTP SMB SMBS SMTP SMTPS TELNET TFTP
10869 FEATURES: SSL IPv6 UnixSockets libz AsynchDNS IDN GSS-API PSL SPNEGO
10870 Kerberos NTLM NTLM_WB TLS-SRP HTTP2 HTTPS-proxy
10871 IMPORTED Targets
10873 New in version 3.12.
10874 This module defines IMPORTED target CURL::libcurl, if curl has been
10877 found.
10878 Result Variables
10880 This module defines the following variables:
10881 CURL_FOUND
10883 "True" if curl found.
10884 CURL_INCLUDE_DIRS
10886 where to find curl/curl.h, etc.
10887 CURL_LIBRARIES
10889 List of libraries when using curl.
10890 CURL_VERSION_STRING
10892 The version of curl found.
10893 New in version 3.13: Debug and Release variants are found separately.
10895 CURL CMake
10898 New in version 3.17.
10899 If CURL was built using the CMake buildsystem then it provides its own
10902 CURLConfig.cmake file for use with the find_package() command's config
10903 mode. This module looks for this file and, if found, returns its re‐
10904 sults with no further action.
10905 Set CURL_NO_CURL_CMAKE to ON to disable this search.
10907 FindCurses
10909 Find the curses or ncurses include file and library.
10910 Result Variables
10912 This module defines the following variables:
10913 CURSES_FOUND
10915 True if Curses is found.
10916 CURSES_INCLUDE_DIRS
10918 The include directories needed to use Curses.
10919 CURSES_LIBRARIES
10921 The libraries needed to use Curses.
10922 CURSES_CFLAGS
10924 New in version 3.16.
10925 Parameters which ought be given to C/C++ compilers when using
10928 Curses.
10929 CURSES_HAVE_CURSES_H
10931 True if curses.h is available.
10932 CURSES_HAVE_NCURSES_H
10934 True if ncurses.h is available.
10935 CURSES_HAVE_NCURSES_NCURSES_H
10937 True if ncurses/ncurses.h is available.
10938 CURSES_HAVE_NCURSES_CURSES_H
10940 True if ncurses/curses.h is available.
10941 Set CURSES_NEED_NCURSES to TRUE before the find_package(Curses) call if
10943 NCurses functionality is required.
10944 New in version 3.10: Set CURSES_NEED_WIDE to TRUE before the find_pack‐
10946 age(Curses) call if unicode functionality is required.
10947 Backward Compatibility
10950 The following variable are provided for backward compatibility:
10951 CURSES_INCLUDE_DIR
10953 Path to Curses include. Use CURSES_INCLUDE_DIRS instead.
10954 CURSES_LIBRARY
10956 Path to Curses library. Use CURSES_LIBRARIES instead.
10957 FindCVS
10959 Find the Concurrent Versions System (CVS).
10960 The module defines the following variables:
10962 CVS_EXECUTABLE - path to cvs command line client
10964 CVS_FOUND - true if the command line client was found
10965 Example usage:
10967 find_package(CVS)
10969 if(CVS_FOUND)
10970 message("CVS found: ${CVS_EXECUTABLE}")
10971 endif()
10972 FindCxxTest
10974 Find CxxTest unit testing framework.
10975 Find the CxxTest suite and declare a helper macro for creating unit
10977 tests and integrating them with CTest. For more details on CxxTest see
10978 https://cxxtest.com
10979 INPUT Variables
10981 CXXTEST_USE_PYTHON [deprecated since 1.3]
10983 Only used in the case both Python & Perl
10984 are detected on the system to control
10985 which CxxTest code generator is used.
10986 Valid only for CxxTest version 3.
10987 NOTE: In older versions of this Find Module,
10989 this variable controlled if the Python test
10990 generator was used instead of the Perl one,
10991 regardless of which scripting language the
10992 user had installed.
10993 CXXTEST_TESTGEN_ARGS (since CMake 2.8.3)
10995 Specify a list of options to pass to the CxxTest code
10996 generator. If not defined, --error-printer is
10997 passed.
10998 OUTPUT Variables
11000 CXXTEST_FOUND
11002 True if the CxxTest framework was found
11003 CXXTEST_INCLUDE_DIRS
11004 Where to find the CxxTest include directory
11005 CXXTEST_PERL_TESTGEN_EXECUTABLE
11006 The perl-based test generator
11007 CXXTEST_PYTHON_TESTGEN_EXECUTABLE
11008 The python-based test generator
11009 CXXTEST_TESTGEN_EXECUTABLE (since CMake 2.8.3)
11010 The test generator that is actually used (chosen using user preferences
11011 and interpreters found in the system)
11012 CXXTEST_TESTGEN_INTERPRETER (since CMake 2.8.3)
11013 The full path to the Perl or Python executable on the system, on
11014 platforms where the script cannot be executed using its shebang line.
11015 MACROS for optional use by CMake users:
11017 CXXTEST_ADD_TEST(<test_name> <gen_source_file> <input_files_to_testgen...>)
11019 Creates a CxxTest runner and adds it to the CTest testing suite
11020 Parameters:
11021 test_name The name of the test
11022 gen_source_file The generated source filename to be
11023 generated by CxxTest
11024 input_files_to_testgen The list of header files containing the
11025 CxxTest::TestSuite's to be included in
11026 this runner
11027 #==============
11029 Example Usage:
11030 find_package(CxxTest)
11032 if(CXXTEST_FOUND)
11033 include_directories(${CXXTEST_INCLUDE_DIR})
11034 enable_testing()
11035 CXXTEST_ADD_TEST(unittest_foo foo_test.cc
11037 ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h)
11038 target_link_libraries(unittest_foo foo) # as needed
11039 endif()
11040 This will (if CxxTest is found):
11042 1. Invoke the testgen executable to autogenerate foo_test.cc in the
11043 binary tree from "foo_test.h" in the current source directory.
11044 2. Create an executable and test called unittest_foo.
11045 #=============
11047 Example foo_test.h:
11048 #include <cxxtest/TestSuite.h>
11050 class MyTestSuite : public CxxTest::TestSuite
11052 {
11053 public:
11054 void testAddition( void )
11055 {
11056 TS_ASSERT( 1 + 1 > 1 );
11057 TS_ASSERT_EQUALS( 1 + 1, 2 );
11058 }
11059 };
11060 FindCygwin
11062 Find Cygwin, a POSIX-compatible environment that runs natively on Mi‐
11063 crosoft Windows
11064 FindDart
11066 Find DART
11067 This module looks for the dart testing software and sets DART_ROOT to
11069 point to where it found it.
11070 FindDCMTK
11072 Find DICOM ToolKit (DCMTK) libraries and applications
11073 The module defines the following variables:
11075 DCMTK_INCLUDE_DIRS - Directories to include to use DCMTK
11077 DCMTK_LIBRARIES - Files to link against to use DCMTK
11078 DCMTK_FOUND - If false, don't try to use DCMTK
11079 DCMTK_DIR - (optional) Source directory for DCMTK
11080 Compatibility
11082 This module is able to find a version of DCMTK that does or does not
11083 export a DCMTKConfig.cmake file. It applies a two step process:
11084 • Step 1: Attempt to find DCMTK version providing a DCMTKConfig.cmake
11086 file.
11087 • Step 2: If step 1 failed, rely on FindDCMTK.cmake to set DCMTK_*
11089 variables details below.
11090 Recent DCMTK provides a DCMTKConfig.cmake package configuration file.
11092 To exclusively use the package configuration file (recommended when
11093 possible), pass the NO_MODULE option to find_package(). For example,
11094 find_package(DCMTK NO_MODULE). This requires official DCMTK snapshot
11095 3.6.1_20140617 or newer.
11096 Until all clients update to the more recent DCMTK, build systems will
11098 need to support different versions of DCMTK.
11099 On any given system, the following combinations of DCMTK versions could
11101 be considered:
11102 ┌───────┬─────────────────┬─────────────────┬─────────────┐
11104 │ │ SYSTEM DCMTK │ LOCAL DCMTK │ Supported ? │
11105 ├───────┼─────────────────┼─────────────────┼─────────────┤
11106 │Case A │ NA │ [ ] DCMTKConfig │ YES │
11107 ├───────┼─────────────────┼─────────────────┼─────────────┤
11108 │Case B │ NA │ [X] DCMTKConfig │ YES │
11109 ├───────┼─────────────────┼─────────────────┼─────────────┤
11110 │Case C │ [ ] DCMTKConfig │ NA │ YES │
11111 ├───────┼─────────────────┼─────────────────┼─────────────┤
11112 │Case D │ [X] DCMTKConfig │ NA │ YES │
11113 ├───────┼─────────────────┼─────────────────┼─────────────┤
11114 │Case E │ [ ] DCMTKConfig │ [ ] DCMTKConfig │ YES (*) │
11115 ├───────┼─────────────────┼─────────────────┼─────────────┤
11116 │Case F │ [X] DCMTKConfig │ [ ] DCMTKConfig │ NO │
11117 ├───────┼─────────────────┼─────────────────┼─────────────┤
11118 │Case G │ [ ] DCMTKConfig │ [X] DCMTKConfig │ YES │
11119 ├───────┼─────────────────┼─────────────────┼─────────────┤
11120 │Case H │ [X] DCMTKConfig │ [X] DCMTKConfig │ YES │
11121 └───────┴─────────────────┴─────────────────┴─────────────┘
11122 (*) See Troubleshooting section.
11123 Legend:
11125 NA ...............: Means that no System or Local DCMTK is available
11126 [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export
11128 a DCMTKConfig.cmake file.
11129 [X] DCMTKConfig ..: Means that the version of DCMTK exports a DCMTK‐
11131 Config.cmake file.
11132 Troubleshooting
11134 What to do if my project finds a different version of DCMTK?
11135 Remove DCMTK entry from the CMake cache per find_package() documenta‐
11137 tion.
11138 FindDevIL
11140 This module locates the developer's image library.
11141 https://openil.sourceforge.net/
11142 IMPORTED Targets
11144 New in version 3.21.
11145 This module defines the IMPORTED targets:
11148 DevIL::IL
11150 Defined if the system has DevIL.
11151 DevIL::ILU
11153 Defined if the system has DevIL Utilities.
11154 DevIL::ILUT
11156 Defined if the system has DevIL Utility Toolkit.
11157 Result Variables
11159 This module sets:
11160 IL_LIBRARIES
11162 The name of the IL library. These include the full path to the
11163 core DevIL library. This one has to be linked into the applica‐
11164 tion.
11165 ILU_LIBRARIES
11167 The name of the ILU library. Again, the full path. This library
11168 is for filters and effects, not actual loading. It doesn't have
11169 to be linked if the functionality it provides is not used.
11170 ILUT_LIBRARIES
11172 The name of the ILUT library. Full path. This part of the li‐
11173 brary interfaces with OpenGL. It is not strictly needed in ap‐
11174 plications.
11175 IL_INCLUDE_DIR
11177 where to find the il.h, ilu.h and ilut.h files.
11178 DevIL_FOUND
11180 This is set to TRUE if all the above variables were set. This
11181 will be set to false if ILU or ILUT are not found, even if they
11182 are not needed. In most systems, if one library is found all the
11183 others are as well. That's the way the DevIL developers release
11184 it.
11185 DevIL_ILUT_FOUND
11187 New in version 3.21.
11188 This is set to TRUE if the ILUT library is found.
11191 FindDoxygen
11193 Doxygen is a documentation generation tool (see
11194 https://www.doxygen.nl). This module looks for Doxygen and some op‐
11195 tional tools it supports:
11196 dot Graphviz dot utility used to render various graphs.
11198 mscgen Message Chart Generator utility used by Doxygen's \msc and \msc‐
11200 file commands.
11201 dia Dia the diagram editor used by Doxygen's \diafile command.
11203 New in version 3.9: These tools are available as components in the
11205 find_package() command. For example:
11206 # Require dot, treat the other components as optional
11209 find_package(Doxygen
11210 REQUIRED dot
11211 OPTIONAL_COMPONENTS mscgen dia)
11212 The following variables are defined by this module:
11214 DOXYGEN_FOUND
11216 True if the doxygen executable was found.
11217 DOXYGEN_VERSION
11219 The version reported by doxygen --version.
11220 New in version 3.9: The module defines IMPORTED targets for Doxygen and
11222 each component found. These can be used as part of custom commands,
11223 etc. and should be preferred over old-style (and now deprecated) vari‐
11224 ables like DOXYGEN_EXECUTABLE. The following import targets are defined
11225 if their corresponding executable could be found (the component import
11226 targets will only be defined if that component was requested):
11227 Doxygen::doxygen
11230 Doxygen::dot
11231 Doxygen::mscgen
11232 Doxygen::dia
11233 Functions
11235 doxygen_add_docs
11236 New in version 3.9.
11237 This function is intended as a convenience for adding a target
11240 for generating documentation with Doxygen. It aims to provide
11241 sensible defaults so that projects can generally just provide
11242 the input files and directories and that will be sufficient to
11243 give sensible results. The function supports the ability to cus‐
11244 tomize the Doxygen configuration used to build the documenta‐
11245 tion.
11246 doxygen_add_docs(targetName
11248 [filesOrDirs...]
11249 [ALL]
11250 [USE_STAMP_FILE]
11251 [WORKING_DIRECTORY dir]
11252 [COMMENT comment])
11253 The function constructs a Doxyfile and defines a custom target
11255 that runs Doxygen on that generated file. The listed files and
11256 directories are used as the INPUT of the generated Doxyfile and
11257 they can contain wildcards. Any files that are listed explic‐
11258 itly will also be added as SOURCES of the custom target so they
11259 will show up in an IDE project's source list.
11260 So that relative input paths work as expected, by default the
11262 working directory of the Doxygen command will be the current
11263 source directory (i.e. CMAKE_CURRENT_SOURCE_DIR). This can be
11264 overridden with the WORKING_DIRECTORY option to change the di‐
11265 rectory used as the relative base point. Note also that Doxy‐
11266 gen's default behavior is to strip the working directory from
11267 relative paths in the generated documentation (see the
11268 STRIP_FROM_PATH Doxygen config option for details).
11269 If provided, the optional comment will be passed as the COMMENT
11271 for the add_custom_target() command used to create the custom
11272 target internally.
11273 New in version 3.12: If ALL is set, the target will be added to
11275 the default build target.
11276 New in version 3.16: If USE_STAMP_FILE is set, the custom com‐
11279 mand defined by this function will create a stamp file with the
11280 name <targetName>.stamp in the current binary directory whenever
11281 doxygen is re-run. With this option present, all items in
11282 <filesOrDirs> must be files (i.e. no directories, symlinks or
11283 wildcards) and each of the files must exist at the time doxy‐
11284 gen_add_docs() is called. An error will be raised if any of the
11285 items listed is missing or is not a file when USE_STAMP_FILE is
11286 given. A dependency will be created on each of the files so
11287 that doxygen will only be re-run if one of the files is updated.
11288 Without the USE_STAMP_FILE option, doxygen will always be re-run
11289 if the <targetName> target is built regardless of whether any‐
11290 thing listed in <filesOrDirs> has changed.
11291 The contents of the generated Doxyfile can be customized by set‐
11294 ting CMake variables before calling doxygen_add_docs(). Any
11295 variable with a name of the form DOXYGEN_<tag> will have its
11296 value substituted for the corresponding <tag> configuration op‐
11297 tion in the Doxyfile. See the Doxygen documentation for the full
11298 list of supported configuration options.
11299 Some of Doxygen's defaults are overridden to provide more appro‐
11301 priate behavior for a CMake project. Each of the following will
11302 be explicitly set unless the variable already has a value before
11303 doxygen_add_docs() is called (with some exceptions noted):
11304 DOXYGEN_HAVE_DOT
11306 Set to YES if the dot component was requested and it was
11307 found, NO otherwise. Any existing value of DOXY‐
11308 GEN_HAVE_DOT is ignored.
11309 DOXYGEN_DOT_MULTI_TARGETS
11311 Set to YES by this module (note that this requires a dot
11312 version newer than 1.8.10). This option is only meaning‐
11313 ful if DOXYGEN_HAVE_DOT is also set to YES.
11314 DOXYGEN_GENERATE_LATEX
11316 Set to NO by this module.
11317 DOXYGEN_WARN_FORMAT
11319 For Visual Studio based generators, this is set to the
11320 form recognized by the Visual Studio IDE: $file($line) :
11321 $text. For all other generators, Doxygen's default value
11322 is not overridden.
11323 DOXYGEN_PROJECT_NAME
11325 Populated with the name of the current project (i.e.
11326 PROJECT_NAME).
11327 DOXYGEN_PROJECT_NUMBER
11329 Populated with the version of the current project (i.e.
11330 PROJECT_VERSION).
11331 DOXYGEN_PROJECT_BRIEF
11333 Populated with the description of the current project
11334 (i.e. PROJECT_DESCRIPTION).
11335 DOXYGEN_INPUT
11337 Projects should not set this variable. It will be popu‐
11338 lated with the set of files and directories passed to
11339 doxygen_add_docs(), thereby providing consistent behavior
11340 with the other built-in commands like add_executable(),
11341 add_library() and add_custom_target(). If a variable
11342 named DOXYGEN_INPUT is set by the project, it will be ig‐
11343 nored and a warning will be issued.
11344 DOXYGEN_RECURSIVE
11346 Set to YES by this module.
11347 DOXYGEN_EXCLUDE_PATTERNS
11349 If the set of inputs includes directories, this variable
11350 will specify patterns used to exclude files from them.
11351 The following patterns are added by doxygen_add_docs() to
11352 ensure CMake-specific files and directories are not in‐
11353 cluded in the input. If the project sets DOXYGEN_EX‐
11354 CLUDE_PATTERNS, those contents are merged with these ad‐
11355 ditional patterns rather than replacing them:
11356 */.git/*
11358 */.svn/*
11359 */.hg/*
11360 */CMakeFiles/*
11361 */_CPack_Packages/*
11362 DartConfiguration.tcl
11363 CMakeLists.txt
11364 CMakeCache.txt
11365 DOXYGEN_OUTPUT_DIRECTORY
11367 Set to CMAKE_CURRENT_BINARY_DIR by this module. Note that
11368 if the project provides its own value for this and it is
11369 a relative path, it will be converted to an absolute path
11370 relative to the current binary directory. This is neces‐
11371 sary because doxygen will normally be run from a direc‐
11372 tory within the source tree so that relative source paths
11373 work as expected. If this directory does not exist, it
11374 will be recursively created prior to executing the doxy‐
11375 gen commands.
11376 To change any of these defaults or override any other Doxygen config
11378 option, set relevant variables before calling doxygen_add_docs(). For
11379 example:
11380 set(DOXYGEN_GENERATE_HTML NO)
11382 set(DOXYGEN_GENERATE_MAN YES)
11383 doxygen_add_docs(
11385 doxygen
11386 ${PROJECT_SOURCE_DIR}
11387 COMMENT "Generate man pages"
11388 )
11389 A number of Doxygen config options accept lists of values, but Doxygen
11391 requires them to be separated by whitespace. CMake variables hold lists
11392 as a string with items separated by semi-colons, so a conversion needs
11393 to be performed. The doxygen_add_docs() command specifically checks the
11394 following Doxygen config options and will convert their associated
11395 CMake variable's contents into the required form if set. CMake vari‐
11396 ables are named DOXYGEN_<name> for the Doxygen settings specified here.
11397 ABBREVIATE_BRIEF
11399 ALIASES
11400 CITE_BIB_FILES
11401 DIAFILE_DIRS
11402 DOTFILE_DIRS
11403 DOT_FONTPATH
11404 ENABLED_SECTIONS
11405 EXAMPLE_PATH
11406 EXAMPLE_PATTERNS
11407 EXCLUDE
11408 EXCLUDE_PATTERNS
11409 EXCLUDE_SYMBOLS
11410 EXPAND_AS_DEFINED
11411 EXTENSION_MAPPING
11412 EXTRA_PACKAGES
11413 EXTRA_SEARCH_MAPPINGS
11414 FILE_PATTERNS
11415 FILTER_PATTERNS
11416 FILTER_SOURCE_PATTERNS
11417 HTML_EXTRA_FILES
11418 HTML_EXTRA_STYLESHEET
11419 IGNORE_PREFIX
11420 IMAGE_PATH
11421 INCLUDE_FILE_PATTERNS
11422 INCLUDE_PATH
11423 INPUT
11424 LATEX_EXTRA_FILES
11425 LATEX_EXTRA_STYLESHEET
11426 MATHJAX_EXTENSIONS
11427 MSCFILE_DIRS
11428 PLANTUML_INCLUDE_PATH
11429 PREDEFINED
11430 QHP_CUST_FILTER_ATTRS
11431 QHP_SECT_FILTER_ATTRS
11432 STRIP_FROM_INC_PATH
11433 STRIP_FROM_PATH
11434 TAGFILES
11435 TCL_SUBST
11436 The following single value Doxygen options will be quoted automatically
11438 if they contain at least one space:
11439 CHM_FILE
11441 DIA_PATH
11442 DOCBOOK_OUTPUT
11443 DOCSET_FEEDNAME
11444 DOCSET_PUBLISHER_NAME
11445 DOT_FONTNAME
11446 DOT_PATH
11447 EXTERNAL_SEARCH_ID
11448 FILE_VERSION_FILTER
11449 GENERATE_TAGFILE
11450 HHC_LOCATION
11451 HTML_FOOTER
11452 HTML_HEADER
11453 HTML_OUTPUT
11454 HTML_STYLESHEET
11455 INPUT_FILTER
11456 LATEX_FOOTER
11457 LATEX_HEADER
11458 LATEX_OUTPUT
11459 LAYOUT_FILE
11460 MAN_OUTPUT
11461 MAN_SUBDIR
11462 MATHJAX_CODEFILE
11463 MSCGEN_PATH
11464 OUTPUT_DIRECTORY
11465 PERL_PATH
11466 PLANTUML_JAR_PATH
11467 PROJECT_BRIEF
11468 PROJECT_LOGO
11469 PROJECT_NAME
11470 QCH_FILE
11471 QHG_LOCATION
11472 QHP_CUST_FILTER_NAME
11473 QHP_VIRTUAL_FOLDER
11474 RTF_EXTENSIONS_FILE
11475 RTF_OUTPUT
11476 RTF_STYLESHEET_FILE
11477 SEARCHDATA_FILE
11478 USE_MDFILE_AS_MAINPAGE
11479 WARN_FORMAT
11480 WARN_LOGFILE
11481 XML_OUTPUT
11482 New in version 3.11: There are situations where it may be undesirable
11484 for a particular config option to be automatically quoted by doxy‐
11485 gen_add_docs(), such as ALIASES which may need to include its own em‐
11486 bedded quoting. The DOXYGEN_VERBATIM_VARS variable can be used to
11487 specify a list of Doxygen variables (including the leading DOXYGEN_
11488 prefix) which should not be quoted. The project is then responsible
11489 for ensuring that those variables' values make sense when placed di‐
11490 rectly in the Doxygen input file. In the case of list variables, list
11491 items are still separated by spaces, it is only the automatic quoting
11492 that is skipped. For example, the following allows doxygen_add_docs()
11493 to apply quoting to DOXYGEN_PROJECT_BRIEF, but not each item in the
11494 DOXYGEN_ALIASES list (bracket syntax can also be used to make working
11495 with embedded quotes easier):
11496 set(DOXYGEN_PROJECT_BRIEF "String with spaces")
11499 set(DOXYGEN_ALIASES
11500 [[somealias="@some_command param"]]
11501 "anotherAlias=@foobar"
11502 )
11503 set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)
11504 The resultant Doxyfile will contain the following lines:
11506 PROJECT_BRIEF = "String with spaces"
11508 ALIASES = somealias="@some_command param" anotherAlias=@foobar
11509 Deprecated Result Variables
11511 Deprecated since version 3.9.
11512 For compatibility with previous versions of CMake, the following vari‐
11515 ables are also defined but they are deprecated and should no longer be
11516 used:
11517 DOXYGEN_EXECUTABLE
11519 The path to the doxygen command. If projects need to refer to
11520 the doxygen executable directly, they should use the Doxy‐
11521 gen::doxygen import target instead.
11522 DOXYGEN_DOT_FOUND
11524 True if the dot executable was found.
11525 DOXYGEN_DOT_EXECUTABLE
11527 The path to the dot command. If projects need to refer to the
11528 dot executable directly, they should use the Doxygen::dot import
11529 target instead.
11530 DOXYGEN_DOT_PATH
11532 The path to the directory containing the dot executable as re‐
11533 ported in DOXYGEN_DOT_EXECUTABLE. The path may have forward
11534 slashes even on Windows and is not suitable for direct substitu‐
11535 tion into a Doxyfile.in template. If you need this value, get
11536 the IMPORTED_LOCATION property of the Doxygen::dot target and
11537 use get_filename_component() to extract the directory part of
11538 that path. You may also want to consider using
11539 file(TO_NATIVE_PATH) to prepare the path for a Doxygen configu‐
11540 ration file.
11541 Deprecated Hint Variables
11543 Deprecated since version 3.9.
11544 DOXYGEN_SKIP_DOT
11547 This variable has no effect for the component form of find_pack‐
11548 age. In backward compatibility mode (i.e. without components
11549 list) it prevents the finder module from searching for
11550 Graphviz's dot utility.
11551 FindEnvModules
11553 New in version 3.15.
11554 Locate an environment module implementation and make commands available
11557 to CMake scripts to use them. This is compatible with both Lua-based
11558 Lmod and TCL-based EnvironmentModules.
11559 This module is intended for the use case of setting up the compiler and
11561 library environment within a CTest Script (ctest -S). It can also be
11562 used in a CMake Script (cmake -P).
11563 NOTE:
11565 The loaded environment will not survive past the end of the calling
11566 process. Do not use this module in project code (CMakeLists.txt
11567 files) to load a compiler environment; it will not be available dur‐
11568 ing the build. Instead load the environment manually before running
11569 CMake or using the generated build system.
11570 Example Usage
11572 set(CTEST_BUILD_NAME "CrayLinux-CrayPE-Cray-dynamic")
11573 set(CTEST_BUILD_CONFIGURATION Release)
11574 set(CTEST_BUILD_FLAGS "-k -j8")
11575 set(CTEST_CMAKE_GENERATOR "Unix Makefiles")
11576 ...
11578 find_package(EnvModules REQUIRED)
11580 env_module(purge)
11582 env_module(load modules)
11583 env_module(load craype)
11584 env_module(load PrgEnv-cray)
11585 env_module(load craype-knl)
11586 env_module(load cray-mpich)
11587 env_module(load cray-libsci)
11588 set(ENV{CRAYPE_LINK_TYPE} dynamic)
11590 ...
11592 Result Variables
11594 This module will set the following variables in your project:
11595 EnvModules_FOUND
11597 True if a compatible environment modules framework was found.
11598 Cache Variables
11600 The following cache variable will be set:
11601 EnvModules_COMMAND
11603 The low level module command to use. Currently supported imple‐
11604 mentations are the Lua based Lmod and TCL based EnvironmentMod‐
11605 ules.
11606 Environment Variables
11608 ENV{MODULESHOME}
11609 Usually set by the module environment implementation, used as a
11610 hint to locate the module command to execute.
11611 Provided Functions
11613 This defines the following CMake functions for interacting with envi‐
11614 ronment modules:
11615 env_module
11617 Execute an aribitrary module command:
11618 env_module(cmd arg1 ... argN)
11620 env_module(
11621 COMMAND cmd arg1 ... argN
11622 [OUTPUT_VARIABLE <out-var>]
11623 [RESULT_VARIABLE <ret-var>]
11624 )
11625 The options are:
11627 cmd arg1 ... argN
11629 The module sub-command and arguments to execute as if
11630 they were passed directly to the module command in your
11631 shell environment.
11632 OUTPUT_VARIABLE <out-var>
11634 The standard output from executing the module command.
11635 RESULT_VARIABLE <ret-var>
11637 The return code from executing the module command.
11638 env_module_swap
11640 Swap one module for another:
11641 env_module_swap(out_mod in_mod
11643 [OUTPUT_VARIABLE <out-var>]
11644 [RESULT_VARIABLE <ret-var>]
11645 )
11646 This is functionally equivalent to the module swap out_mod
11648 in_mod shell command. The options are:
11649 OUTPUT_VARIABLE <out-var>
11651 The standard output from executing the module command.
11652 RESULT_VARIABLE <ret-var>
11654 The return code from executing the module command.
11655 env_module_list
11657 Retrieve the list of currently loaded modules:
11658 env_module_list(<out-var>)
11660 This is functionally equivalent to the module list shell com‐
11662 mand. The result is stored in <out-var> as a properly formatted
11663 CMake semicolon-separated list variable.
11664 env_module_avail
11666 Retrieve the list of available modules:
11667 env_module_avail([<mod-prefix>] <out-var>)
11669 This is functionally equivalent to the module avail <mod-prefix>
11671 shell command. The result is stored in <out-var> as a properly
11672 formatted CMake semicolon-separated list variable.
11673 FindEXPAT
11675 Find the native Expat headers and library. Expat is a stream-oriented
11676 XML parser library written in C.
11677 Imported Targets
11679 New in version 3.10.
11680 This module defines the following IMPORTED targets:
11683 EXPAT::EXPAT
11685 The Expat expat library, if found.
11686 Result Variables
11688 This module will set the following variables in your project:
11689 EXPAT_INCLUDE_DIRS
11691 where to find expat.h, etc.
11692 EXPAT_LIBRARIES
11694 the libraries to link against to use Expat.
11695 EXPAT_FOUND
11697 true if the Expat headers and libraries were found.
11698 FindFLEX
11700 Find Fast Lexical Analyzer (Flex) executable and provides a macro to
11701 generate custom build rules
11702 The module defines the following variables:
11704 FLEX_FOUND - True is flex executable is found
11706 FLEX_EXECUTABLE - the path to the flex executable
11707 FLEX_VERSION - the version of flex
11708 FLEX_LIBRARIES - The flex libraries
11709 FLEX_INCLUDE_DIRS - The path to the flex headers
11710 The minimum required version of flex can be specified using the stan‐
11712 dard syntax, e.g. find_package(FLEX 2.5.13)
11713 If flex is found on the system, the module provides the macro:
11715 FLEX_TARGET(Name FlexInput FlexOutput
11717 [COMPILE_FLAGS <string>]
11718 [DEFINES_FILE <string>]
11719 )
11720 which creates a custom command to generate the FlexOutput file from the
11722 FlexInput file. Name is an alias used to get details of this custom
11723 command. If COMPILE_FLAGS option is specified, the next parameter is
11724 added to the flex command line.
11725 New in version 3.5: If flex is configured to output a header file, the
11727 DEFINES_FILE option may be used to specify its name.
11728 Changed in version 3.17: When CMP0098 is set to NEW, flex runs in the
11731 CMAKE_CURRENT_BINARY_DIR directory.
11732 The macro defines the following variables:
11735 FLEX_${Name}_DEFINED - true is the macro ran successfully
11737 FLEX_${Name}_OUTPUTS - the source file generated by the custom rule, an
11738 alias for FlexOutput
11739 FLEX_${Name}_INPUT - the flex source file, an alias for ${FlexInput}
11740 FLEX_${Name}_OUTPUT_HEADER - the header flex output, if any.
11741 Flex scanners often use tokens defined by Bison: the code generated by
11743 Flex depends of the header generated by Bison. This module also de‐
11744 fines a macro:
11745 ADD_FLEX_BISON_DEPENDENCY(FlexTarget BisonTarget)
11747 which adds the required dependency between a scanner and a parser where
11749 FlexTarget and BisonTarget are the first parameters of respectively
11750 FLEX_TARGET and BISON_TARGET macros.
11751 ====================================================================
11753 Example:
11754 find_package(BISON)
11756 find_package(FLEX)
11757 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
11759 FLEX_TARGET(MyScanner lexer.l ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp)
11760 ADD_FLEX_BISON_DEPENDENCY(MyScanner MyParser)
11761 include_directories(${CMAKE_CURRENT_BINARY_DIR})
11763 add_executable(Foo
11764 Foo.cc
11765 ${BISON_MyParser_OUTPUTS}
11766 ${FLEX_MyScanner_OUTPUTS}
11767 )
11768 target_link_libraries(Foo ${FLEX_LIBRARIES})
11769 ====================================================================
11770 FindFLTK
11772 Find the Fast Light Toolkit (FLTK) library
11773 Input Variables
11775 By default this module will search for all of the FLTK components and
11776 add them to the FLTK_LIBRARIES variable. You can limit the components
11777 which get placed in FLTK_LIBRARIES by defining one or more of the fol‐
11778 lowing three options:
11779 FLTK_SKIP_OPENGL
11781 Set to true to disable searching for the FLTK GL library
11782 FLTK_SKIP_FORMS
11784 Set to true to disable searching for the FLTK Forms library
11785 FLTK_SKIP_IMAGES
11787 Set to true to disable searching for the FLTK Images library
11788 FLTK is composed also by a binary tool. You can set the following op‐
11790 tion:
11791 FLTK_SKIP_FLUID
11793 Set to true to not look for the FLUID binary
11794 Result Variables
11796 The following variables will be defined:
11797 FLTK_FOUND
11799 True if all components not skipped were found
11800 FLTK_INCLUDE_DIR
11802 Path to the include directory for FLTK header files
11803 FLTK_LIBRARIES
11805 List of the FLTK libraries found
11806 FLTK_FLUID_EXECUTABLE
11808 Path to the FLUID binary tool
11809 FLTK_WRAP_UI
11811 True if FLUID is found, used to enable the FLTK_WRAP_UI command
11812 Cache Variables
11814 The following cache variables are also available to set or use:
11815 FLTK_BASE_LIBRARY_RELEASE
11817 The FLTK base library (optimized)
11818 FLTK_BASE_LIBRARY_DEBUG
11820 The FLTK base library (debug)
11821 FLTK_GL_LIBRARY_RELEASE
11823 The FLTK GL library (optimized)
11824 FLTK_GL_LIBRARY_DEBUG
11826 The FLTK GL library (debug)
11827 FLTK_FORMS_LIBRARY_RELEASE
11829 The FLTK Forms library (optimized)
11830 FLTK_FORMS_LIBRARY_DEBUG
11832 The FLTK Forms library (debug)
11833 FLTK_IMAGES_LIBRARY_RELEASE
11835 The FLTK Images protobuf library (optimized)
11836 FLTK_IMAGES_LIBRARY_DEBUG
11838 The FLTK Images library (debug)
11839 New in version 3.11: Debug and Release variants are found separately
11841 and use per-configuration variables.
11842 FindFLTK2
11845 Find the native FLTK 2.0 includes and library
11846 The following settings are defined
11848 FLTK2_FLUID_EXECUTABLE, where to find the Fluid tool
11850 FLTK2_WRAP_UI, This enables the FLTK2_WRAP_UI command
11851 FLTK2_INCLUDE_DIR, where to find include files
11852 FLTK2_LIBRARIES, list of fltk2 libraries
11853 FLTK2_FOUND, Don't use FLTK2 if false.
11854 The following settings should not be used in general.
11856 FLTK2_BASE_LIBRARY = the full path to fltk2.lib
11858 FLTK2_GL_LIBRARY = the full path to fltk2_gl.lib
11859 FLTK2_IMAGES_LIBRARY = the full path to fltk2_images.lib
11860 FindFontconfig
11862 New in version 3.14.
11863 Find Fontconfig headers and library.
11866 Imported Targets
11868 Fontconfig::Fontconfig
11869 The Fontconfig library, if found.
11870 Result Variables
11872 This will define the following variables in your project:
11873 Fontconfig_FOUND
11875 true if (the requested version of) Fontconfig is available.
11876 Fontconfig_VERSION
11878 the version of Fontconfig.
11879 Fontconfig_LIBRARIES
11881 the libraries to link against to use Fontconfig.
11882 Fontconfig_INCLUDE_DIRS
11884 where to find the Fontconfig headers.
11885 Fontconfig_COMPILE_OPTIONS
11887 this should be passed to target_compile_options(), if the target
11888 is not used for linking
11889 FindFreetype
11891 Find the FreeType font renderer includes and library.
11892 Imported Targets
11894 New in version 3.10.
11895 This module defines the following IMPORTED target:
11898 Freetype::Freetype
11900 The Freetype freetype library, if found
11901 Result Variables
11903 This module will set the following variables in your project:
11904 FREETYPE_FOUND
11906 true if the Freetype headers and libraries were found
11907 FREETYPE_INCLUDE_DIRS
11909 directories containing the Freetype headers. This is the con‐
11910 catenation of the variables:
11911 FREETYPE_INCLUDE_DIR_ft2build
11913 directory holding the main Freetype API configuration
11914 header
11915 FREETYPE_INCLUDE_DIR_freetype2
11917 directory holding Freetype public headers
11918 FREETYPE_LIBRARIES
11920 the library to link against
11921 FREETYPE_VERSION_STRING
11923 the version of freetype found
11924 New in version 3.7: Debug and Release variants are found separately.
11926 Hints
11929 The user may set the environment variable FREETYPE_DIR to the root di‐
11930 rectory of a Freetype installation.
11931 FindGCCXML
11933 Find the GCC-XML front-end executable.
11934 This module will define the following variables:
11936 GCCXML - the GCC-XML front-end executable.
11938 FindGDAL
11940 Find Geospatial Data Abstraction Library (GDAL).
11941 IMPORTED Targets
11943 New in version 3.14.
11944 This module defines IMPORTED target GDAL::GDAL if GDAL has been found.
11947 Result Variables
11949 This module will set the following variables in your project:
11950 GDAL_FOUND
11952 True if GDAL is found.
11953 GDAL_INCLUDE_DIRS
11955 Include directories for GDAL headers.
11956 GDAL_LIBRARIES
11958 Libraries to link to GDAL.
11959 GDAL_VERSION
11961 New in version 3.14: The version of GDAL found.
11962 Cache variables
11965 The following cache variables may also be set:
11966 GDAL_LIBRARY
11968 The libgdal library file.
11969 GDAL_INCLUDE_DIR
11971 The directory containing gdal.h.
11972 Hints
11974 Set GDAL_DIR or GDAL_ROOT in the environment to specify the GDAL in‐
11975 stallation prefix.
11976 The following variables may be set to modify the search strategy:
11978 FindGDAL_SKIP_GDAL_CONFIG
11980 If set, gdal-config will not be used. This can be useful if
11981 there are GDAL libraries built with autotools (which provide the
11982 tool) and CMake (which do not) in the same environment.
11983 GDAL_ADDITIONAL_LIBRARY_VERSIONS
11985 Extra versions of library names to search for.
11986 FindGettext
11988 Find GNU gettext tools
11989 This module looks for the GNU gettext tools. This module defines the
11991 following values:
11992 GETTEXT_MSGMERGE_EXECUTABLE: the full path to the msgmerge tool.
11994 GETTEXT_MSGFMT_EXECUTABLE: the full path to the msgfmt tool.
11995 GETTEXT_FOUND: True if gettext has been found.
11996 GETTEXT_VERSION_STRING: the version of gettext found (since CMake 2.8.8)
11997 Additionally it provides the following macros:
11999 GETTEXT_CREATE_TRANSLATIONS ( outputFile [ALL] file1 ... fileN )
12001 This will create a target "translations" which will convert the
12003 given input po files into the binary output mo file. If the
12004 ALL option is used, the translations will also be created when
12005 building the default target.
12006 GETTEXT_PROCESS_POT_FILE( <potfile> [ALL] [INSTALL_DESTINATION <dest‐
12008 dir>] LANGUAGES <lang1> <lang2> ... )
12009 Process the given pot file to mo files.
12011 If INSTALL_DESTINATION is given then automatically install rules will
12012 be created, the language subdirectory will be taken into account
12013 (by default use share/locale/).
12014 If ALL is specified, the pot file is processed when building the all target.
12015 It creates a custom target "potfile".
12016 GETTEXT_PROCESS_PO_FILES( <lang> [ALL] [INSTALL_DESTINATION <dir>]
12018 PO_FILES <po1> <po2> ... )
12019 Process the given po files to mo files for the given language.
12021 If INSTALL_DESTINATION is given then automatically install rules will
12022 be created, the language subdirectory will be taken into account
12023 (by default use share/locale/).
12024 If ALL is specified, the po files are processed when building the all target.
12025 It creates a custom target "pofiles".
12026 New in version 3.2: If you wish to use the Gettext library (libintl),
12028 use FindIntl.
12029 FindGIF
12032 This finds the Graphics Interchange Format (GIF) library (giflib)
12033 Imported targets
12035 This module defines the following IMPORTED target:
12036 GIF::GIF
12038 The giflib library, if found.
12039 Result variables
12041 This module will set the following variables in your project:
12042 GIF_FOUND
12044 If false, do not try to use GIF.
12045 GIF_INCLUDE_DIRS
12047 where to find gif_lib.h, etc.
12048 GIF_LIBRARIES
12050 the libraries needed to use GIF.
12051 GIF_VERSION
12053 3, 4 or a full version string (eg 5.1.4) for versions >= 4.1.6.
12054 Cache variables
12056 The following cache variables may also be set:
12057 GIF_INCLUDE_DIR
12059 where to find the GIF headers.
12060 GIF_LIBRARY
12062 where to find the GIF library.
12063 Hints
12065 GIF_DIR is an environment variable that would correspond to the ./con‐
12066 figure --prefix=$GIF_DIR.
12067 FindGit
12069 The module defines the following variables:
12070 GIT_EXECUTABLE
12072 Path to Git command-line client.
12073 Git_FOUND, GIT_FOUND
12075 True if the Git command-line client was found.
12076 GIT_VERSION_STRING
12078 The version of Git found.
12079 New in version 3.14: The module defines the following IMPORTED targets
12081 (when CMAKE_ROLE is PROJECT):
12082 Git::Git
12085 Executable of the Git command-line client.
12086 Example usage:
12088 find_package(Git)
12090 if(Git_FOUND)
12091 message("Git found: ${GIT_EXECUTABLE}")
12092 endif()
12093 FindGLEW
12095 Find the OpenGL Extension Wrangler Library (GLEW)
12096 Input Variables
12098 The following variables may be set to influence this module's behavior:
12099 GLEW_USE_STATIC_LIBS
12101 to find and create IMPORTED target for static linkage.
12102 GLEW_VERBOSE
12104 to output a detailed log of this module.
12105 Imported Targets
12107 New in version 3.1.
12108 This module defines the following Imported Targets:
12111 GLEW::glew
12113 The GLEW shared library.
12114 GLEW::glew_s
12116 The GLEW static library, if GLEW_USE_STATIC_LIBS is set to TRUE.
12117 GLEW::GLEW
12119 Duplicates either GLEW::glew or GLEW::glew_s based on availabil‐
12120 ity.
12121 Result Variables
12123 This module defines the following variables:
12124 GLEW_INCLUDE_DIRS
12126 include directories for GLEW
12127 GLEW_LIBRARIES
12129 libraries to link against GLEW
12130 GLEW_SHARED_LIBRARIES
12132 libraries to link against shared GLEW
12133 GLEW_STATIC_LIBRARIES
12135 libraries to link against static GLEW
12136 GLEW_FOUND
12138 true if GLEW has been found and can be used
12139 GLEW_VERSION
12141 GLEW version
12142 GLEW_VERSION_MAJOR
12144 GLEW major version
12145 GLEW_VERSION_MINOR
12147 GLEW minor version
12148 GLEW_VERSION_MICRO
12150 GLEW micro version
12151 New in version 3.7: Debug and Release variants are found separately.
12153 FindGLUT
12156 Find OpenGL Utility Toolkit (GLUT) library and include files.
12157 IMPORTED Targets
12159 New in version 3.1.
12160 This module defines the IMPORTED targets:
12163 GLUT::GLUT
12165 Defined if the system has GLUT.
12166 Result Variables
12168 This module defines the following variables:
12169 GLUT_FOUND
12171 True if glut was found.
12172 GLUT_INCLUDE_DIRS
12174 New in version 3.23.
12175 Where to find GL/glut.h, etc.
12178 GLUT_LIBRARIES
12180 List of libraries for using glut.
12181 Cache Variables
12183 This module may set the following variables depending on platform.
12184 These variables may optionally be set to help this module find the cor‐
12185 rect files, but clients should not use these as results:
12186 GLUT_INCLUDE_DIR
12188 The full path to the directory containing GL/glut.h, not includ‐
12189 ing GL/.
12190 GLUT_glut_LIBRARY
12192 The full path to the glut library.
12193 GLUT_Xmu_LIBRARY
12195 The full path to the Xmu library.
12196 GLUT_Xi_LIBRARY
12198 The full path to the Xi Library.
12199 Obsolete Variables
12201 The following variables may also be provided, for backwards compatibil‐
12202 ity:
12203 GLUT_INCLUDE_DIR
12205 This is one of above Cache Variables, but prior to CMake 3.23
12206 was also a result variable. Prefer to use GLUT_INCLUDE_DIRS in‐
12207 stead in CMake 3.23 and above.
12208 FindGnuplot
12210 this module looks for gnuplot
12211 Once done this will define
12213 GNUPLOT_FOUND - system has Gnuplot
12215 GNUPLOT_EXECUTABLE - the Gnuplot executable
12216 GNUPLOT_VERSION_STRING - the version of Gnuplot found (since CMake 2.8.8)
12217 GNUPLOT_VERSION_STRING will not work for old versions like 3.7.1.
12219 FindGnuTLS
12221 Find the GNU Transport Layer Security library (gnutls)
12222 IMPORTED Targets
12224 New in version 3.16.
12225 This module defines IMPORTED target GnuTLS::GnuTLS, if gnutls has been
12228 found.
12229 Result Variables
12231 GNUTLS_FOUND
12232 System has gnutls
12233 GNUTLS_INCLUDE_DIR
12235 The gnutls include directory
12236 GNUTLS_LIBRARIES
12238 The libraries needed to use gnutls
12239 GNUTLS_DEFINITIONS
12241 Compiler switches required for using gnutls
12242 GNUTLS_VERSION
12244 version of gnutls.
12245 FindGSL
12247 New in version 3.2.
12248 Find the native GNU Scientific Library (GSL) includes and libraries.
12251 The GNU Scientific Library (GSL) is a numerical library for C and C++
12253 programmers. It is free software under the GNU General Public License.
12254 Imported Targets
12256 If GSL is found, this module defines the following IMPORTED targets:
12257 GSL::gsl - The main GSL library.
12259 GSL::gslcblas - The CBLAS support library used by GSL.
12260 Result Variables
12262 This module will set the following variables in your project:
12263 GSL_FOUND - True if GSL found on the local system
12265 GSL_INCLUDE_DIRS - Location of GSL header files.
12266 GSL_LIBRARIES - The GSL libraries.
12267 GSL_VERSION - The version of the discovered GSL install.
12268 Hints
12270 Set GSL_ROOT_DIR to a directory that contains a GSL installation.
12271 This script expects to find libraries at $GSL_ROOT_DIR/lib and the GSL
12273 headers at $GSL_ROOT_DIR/include/gsl. The library directory may op‐
12274 tionally provide Release and Debug folders. If available, the libraries
12275 named gsld, gslblasd or cblasd are recognized as debug libraries. For
12276 Unix-like systems, this script will use $GSL_ROOT_DIR/bin/gsl-config
12277 (if found) to aid in the discovery of GSL.
12278 Cache Variables
12280 This module may set the following variables depending on platform and
12281 type of GSL installation discovered. These variables may optionally be
12282 set to help this module find the correct files:
12283 GSL_CBLAS_LIBRARY - Location of the GSL CBLAS library.
12285 GSL_CBLAS_LIBRARY_DEBUG - Location of the debug GSL CBLAS library (if any).
12286 GSL_CONFIG_EXECUTABLE - Location of the ``gsl-config`` script (if any).
12287 GSL_LIBRARY - Location of the GSL library.
12288 GSL_LIBRARY_DEBUG - Location of the debug GSL library (if any).
12289 FindGTest
12291 Locate the Google C++ Testing Framework.
12292 New in version 3.20: Upstream GTestConfig.cmake is used if possible.
12294 Imported targets
12297 New in version 3.20: This module defines the following IMPORTED tar‐
12298 gets:
12299 GTest::gtest
12302 The Google Test gtest library, if found; adds Thread::Thread au‐
12303 tomatically
12304 GTest::gtest_main
12306 The Google Test gtest_main library, if found
12307 New in version 3.23.
12309 GTest::gmock
12312 The Google Mock gmock library, if found; adds Thread::Thread au‐
12313 tomatically
12314 GTest::gmock_main
12316 The Google Mock gmock_main library, if found
12317 Deprecated since version 3.20: For backwards compatibility, this module
12319 defines additionally the following deprecated IMPORTED targets (avail‐
12320 able since 3.5):
12321 GTest::GTest
12324 The Google Test gtest library, if found; adds Thread::Thread au‐
12325 tomatically
12326 GTest::Main
12328 The Google Test gtest_main library, if found
12329 Result variables
12331 This module will set the following variables in your project:
12332 GTest_FOUND
12334 Found the Google Testing framework
12335 GTEST_INCLUDE_DIRS
12337 the directory containing the Google Test headers
12338 The library variables below are set as normal variables. These contain
12340 debug/optimized keywords when a debugging library is found.
12341 GTEST_LIBRARIES
12343 The Google Test gtest library; note it also requires linking
12344 with an appropriate thread library
12345 GTEST_MAIN_LIBRARIES
12347 The Google Test gtest_main library
12348 GTEST_BOTH_LIBRARIES
12350 Both gtest and gtest_main
12351 Cache variables
12353 The following cache variables may also be set:
12354 GTEST_ROOT
12356 The root directory of the Google Test installation (may also be
12357 set as an environment variable)
12358 GTEST_MSVC_SEARCH
12360 If compiling with MSVC, this variable can be set to MT or MD
12361 (the default) to enable searching a GTest build tree
12362 Example usage
12364 enable_testing()
12365 find_package(GTest REQUIRED)
12366 add_executable(foo foo.cc)
12368 target_link_libraries(foo GTest::gtest GTest::gtest_main)
12369 add_test(AllTestsInFoo foo)
12371 Deeper integration with CTest
12373 See GoogleTest for information on the gtest_add_tests() and
12374 gtest_discover_tests() commands.
12375 Changed in version 3.9: Previous CMake versions defined
12377 gtest_add_tests() macro in this module.
12378 FindGTK
12381 Find GTK, glib and GTKGLArea
12382 GTK_INCLUDE_DIR - Directories to include to use GTK
12384 GTK_LIBRARIES - Files to link against to use GTK
12385 GTK_FOUND - GTK was found
12386 GTK_GL_FOUND - GTK's GL features were found
12387 FindGTK2
12389 Find the GTK2 widget libraries and several of its other optional compo‐
12390 nents like gtkmm, glade, and glademm.
12391 Specify one or more of the following components as you call this find
12393 module. See example below.
12394 • gtk
12396 • gtkmm
12398 • glade
12400 • glademm
12402 Imported Targets
12404 This module defines the following IMPORTED targets (subject to compo‐
12405 nent selection):
12406 GTK2::atk, GTK2::atkmm, GTK2::cairo, GTK2::cairomm, GTK2::gdk_pixbuf,
12408 GTK2::gdk, GTK2::gdkmm, GTK2::gio, GTK2::giomm, GTK2::glade,
12409 GTK2::glademm, GTK2::glib, GTK2::glibmm, GTK2::gmodule, GTK2::gobject,
12410 GTK2::gthread, GTK2::gtk, GTK2::gtkmm, GTK2::harfbuzz, GTK2::pango,
12411 GTK2::pangocairo, GTK2::pangoft2, GTK2::pangomm, GTK2::pangoxft,
12412 GTK2::sigc.
12413 New in version 3.16.7: Added the GTK2::harfbuzz target.
12415 Result Variables
12418 The following variables will be defined for your use
12419 GTK2_FOUND
12421 Were all of your specified components found?
12422 GTK2_INCLUDE_DIRS
12424 All include directories
12425 GTK2_LIBRARIES
12427 All libraries
12428 GTK2_TARGETS
12430 New in version 3.5: All imported targets
12431 GTK2_DEFINITIONS
12434 Additional compiler flags
12435 GTK2_VERSION
12437 The version of GTK2 found (x.y.z)
12438 GTK2_MAJOR_VERSION
12440 The major version of GTK2
12441 GTK2_MINOR_VERSION
12443 The minor version of GTK2
12444 GTK2_PATCH_VERSION
12446 The patch version of GTK2
12447 New in version 3.5: When GTK2_USE_IMPORTED_TARGETS is set to TRUE,
12449 GTK2_LIBRARIES will list imported targets instead of library paths.
12450 Input Variables
12453 Optional variables you can define prior to calling this module:
12454 GTK2_DEBUG
12456 Enables verbose debugging of the module
12457 GTK2_ADDITIONAL_SUFFIXES
12459 Allows defining additional directories to search for include
12460 files
12461 Example Usage
12463 Call find_package() once. Here are some examples to pick from:
12464 Require GTK 2.6 or later:
12466 find_package(GTK2 2.6 REQUIRED gtk)
12468 Require GTK 2.10 or later and Glade:
12470 find_package(GTK2 2.10 REQUIRED gtk glade)
12472 Search for GTK/GTKMM 2.8 or later:
12474 find_package(GTK2 2.8 COMPONENTS gtk gtkmm)
12476 Use the results:
12478 if(GTK2_FOUND)
12480 include_directories(${GTK2_INCLUDE_DIRS})
12481 add_executable(mygui mygui.cc)
12482 target_link_libraries(mygui ${GTK2_LIBRARIES})
12483 endif()
12484 FindHDF5
12486 Find Hierarchical Data Format (HDF5), a library for reading and writing
12487 self describing array data.
12488 This module invokes the HDF5 wrapper compiler that should be installed
12490 alongside HDF5. Depending upon the HDF5 Configuration, the wrapper
12491 compiler is called either h5cc or h5pcc. If this succeeds, the module
12492 will then call the compiler with the show argument to see what flags
12493 are used when compiling an HDF5 client application.
12494 The module will optionally accept the COMPONENTS argument. If no COM‐
12496 PONENTS are specified, then the find module will default to finding
12497 only the HDF5 C library. If one or more COMPONENTS are specified, the
12498 module will attempt to find the language bindings for the specified
12499 components. The valid components are C, CXX, Fortran, HL. HL refers
12500 to the "high-level" HDF5 functions for C and Fortran. If the COMPO‐
12501 NENTS argument is not given, the module will attempt to find only the C
12502 bindings. For example, to use Fortran HDF5 and HDF5-HL functions, do:
12503 find_package(HDF5 COMPONENTS Fortran HL).
12504 This module will read the variable HDF5_USE_STATIC_LIBRARIES to deter‐
12506 mine whether or not to prefer a static link to a dynamic link for HDF5
12507 and all of it's dependencies. To use this feature, make sure that the
12508 HDF5_USE_STATIC_LIBRARIES variable is set before the call to find_pack‐
12509 age.
12510 New in version 3.10: Support for HDF5_USE_STATIC_LIBRARIES on Windows.
12512 Both the serial and parallel HDF5 wrappers are considered and the first
12515 directory to contain either one will be used. In the event that both
12516 appear in the same directory the serial version is preferentially se‐
12517 lected. This behavior can be reversed by setting the variable HDF5_PRE‐
12518 FER_PARALLEL to TRUE.
12519 In addition to finding the includes and libraries required to compile
12521 an HDF5 client application, this module also makes an effort to find
12522 tools that come with the HDF5 distribution that may be useful for re‐
12523 gression testing.
12524 Result Variables
12526 This module will set the following variables in your project:
12527 HDF5_FOUND
12529 HDF5 was found on the system
12530 HDF5_VERSION
12532 New in version 3.3: HDF5 library version
12533 HDF5_INCLUDE_DIRS
12536 Location of the HDF5 header files
12537 HDF5_DEFINITIONS
12539 Required compiler definitions for HDF5
12540 HDF5_LIBRARIES
12542 Required libraries for all requested bindings
12543 HDF5_HL_LIBRARIES
12545 Required libraries for the HDF5 high level API for all bindings,
12546 if the HL component is enabled
12547 Available components are: C CXX Fortran and HL. For each enabled lan‐
12549 guage binding, a corresponding HDF5_${LANG}_LIBRARIES variable, and po‐
12550 tentially HDF5_${LANG}_DEFINITIONS, will be defined. If the HL compo‐
12551 nent is enabled, then an HDF5_${LANG}_HL_LIBRARIES will also be de‐
12552 fined. With all components enabled, the following variables will be
12553 defined:
12554 HDF5_C_DEFINITIONS
12556 Required compiler definitions for HDF5 C bindings
12557 HDF5_CXX_DEFINITIONS
12559 Required compiler definitions for HDF5 C++ bindings
12560 HDF5_Fortran_DEFINITIONS
12562 Required compiler definitions for HDF5 Fortran bindings
12563 HDF5_C_INCLUDE_DIRS
12565 Required include directories for HDF5 C bindings
12566 HDF5_CXX_INCLUDE_DIRS
12568 Required include directories for HDF5 C++ bindings
12569 HDF5_Fortran_INCLUDE_DIRS
12571 Required include directories for HDF5 Fortran bindings
12572 HDF5_C_LIBRARIES
12574 Required libraries for the HDF5 C bindings
12575 HDF5_CXX_LIBRARIES
12577 Required libraries for the HDF5 C++ bindings
12578 HDF5_Fortran_LIBRARIES
12580 Required libraries for the HDF5 Fortran bindings
12581 HDF5_C_HL_LIBRARIES
12583 Required libraries for the high level C bindings
12584 HDF5_CXX_HL_LIBRARIES
12586 Required libraries for the high level C++ bindings
12587 HDF5_Fortran_HL_LIBRARIES
12589 Required libraries for the high level Fortran bindings.
12590 HDF5_IS_PARALLEL
12592 HDF5 library has parallel IO support
12593 HDF5_C_COMPILER_EXECUTABLE
12595 path to the HDF5 C wrapper compiler
12596 HDF5_CXX_COMPILER_EXECUTABLE
12598 path to the HDF5 C++ wrapper compiler
12599 HDF5_Fortran_COMPILER_EXECUTABLE
12601 path to the HDF5 Fortran wrapper compiler
12602 HDF5_C_COMPILER_EXECUTABLE_NO_INTERROGATE
12604 path to the primary C compiler which is also the HDF5 wrapper
12605 HDF5_CXX_COMPILER_EXECUTABLE_NO_INTERROGATE
12607 path to the primary C++ compiler which is also the HDF5 wrapper
12608 HDF5_Fortran_COMPILER_EXECUTABLE_NO_INTERROGATE
12610 path to the primary Fortran compiler which is also the HDF5
12611 wrapper
12612 HDF5_DIFF_EXECUTABLE
12614 path to the HDF5 dataset comparison tool
12615 With all components enabled, the following targets will be defined:
12617 HDF5::HDF5
12619 All detected HDF5_LIBRARIES.
12620 hdf5::hdf5
12622 C library.
12623 hdf5::hdf5_cpp
12625 C++ library.
12626 hdf5::hdf5_fortran
12628 Fortran library.
12629 hdf5::hdf5_hl
12631 High-level C library.
12632 hdf5::hdf5_hl_cpp
12634 High-level C++ library.
12635 hdf5::hdf5_hl_fortran
12637 High-level Fortran library.
12638 hdf5::h5diff
12640 h5diff executable.
12641 Hints
12643 The following variables can be set to guide the search for HDF5 li‐
12644 braries and includes:
12645 HDF5_PREFER_PARALLEL
12647 New in version 3.4.
12648 set true to prefer parallel HDF5 (by default, serial is pre‐
12651 ferred)
12652 HDF5_FIND_DEBUG
12654 New in version 3.9.
12655 Set true to get extra debugging output.
12658 HDF5_NO_FIND_PACKAGE_CONFIG_FILE
12660 New in version 3.8.
12661 Set true to skip trying to find hdf5-config.cmake.
12664 FindHg
12666 Extract information from a mercurial working copy.
12667 The module defines the following variables:
12669 HG_EXECUTABLE - path to mercurial command line client (hg)
12671 HG_FOUND - true if the command line client was found
12672 HG_VERSION_STRING - the version of mercurial found
12673 New in version 3.1: If the command line client executable is found the
12675 following macro is defined:
12676 HG_WC_INFO(<dir> <var-prefix>)
12679 Hg_WC_INFO extracts information of a mercurial working copy at a given
12681 location. This macro defines the following variables:
12682 <var-prefix>_WC_CHANGESET - current changeset
12684 <var-prefix>_WC_REVISION - current revision
12685 Example usage:
12687 find_package(Hg)
12689 if(HG_FOUND)
12690 message("hg found: ${HG_EXECUTABLE}")
12691 HG_WC_INFO(${PROJECT_SOURCE_DIR} Project)
12692 message("Current revision is ${Project_WC_REVISION}")
12693 message("Current changeset is ${Project_WC_CHANGESET}")
12694 endif()
12695 FindHSPELL
12697 Try to find Hebrew spell-checker (Hspell) and morphology engine.
12698 Once done this will define
12700 HSPELL_FOUND - system has Hspell
12702 HSPELL_INCLUDE_DIR - the Hspell include directory
12703 HSPELL_LIBRARIES - The libraries needed to use Hspell
12704 HSPELL_DEFINITIONS - Compiler switches required for using Hspell
12705 HSPELL_VERSION_STRING - The version of Hspell found (x.y)
12707 HSPELL_MAJOR_VERSION - the major version of Hspell
12708 HSPELL_MINOR_VERSION - The minor version of Hspell
12709 FindHTMLHelp
12711 This module looks for Microsoft HTML Help Compiler
12712 It defines:
12714 HTML_HELP_COMPILER : full path to the Compiler (hhc.exe)
12716 HTML_HELP_INCLUDE_PATH : include path to the API (htmlhelp.h)
12717 HTML_HELP_LIBRARY : full path to the library (htmlhelp.lib)
12718 FindIce
12720 New in version 3.1.
12721 Find the ZeroC Internet Communication Engine (ICE) programs, libraries
12724 and datafiles.
12725 This module supports multiple components. Components can include any
12727 of: Freeze, Glacier2, Ice, IceBox, IceDB, IceDiscovery, IceGrid, IceLo‐
12728 catorDiscovery, IcePatch, IceSSL, IceStorm, IceUtil, IceXML, or Slice.
12729 Ice 3.7 and later also include C++11-specific components: Glacier2++11,
12731 Ice++11, IceBox++11, IceDiscovery++11 IceGrid, IceLocatorDiscovery++11,
12732 IceSSL++11, IceStorm++11
12733 Note that the set of supported components is Ice version-specific.
12735 New in version 3.4: Imported targets for components and most EXECUTABLE
12737 variables.
12738 New in version 3.7: Debug and Release variants are found separately.
12741 New in version 3.10: Ice 3.7 support, including new components, pro‐
12744 grams and the Nuget package.
12745 This module reports information about the Ice installation in several
12748 variables. General variables:
12749 Ice_VERSION - Ice release version
12751 Ice_FOUND - true if the main programs and libraries were found
12752 Ice_LIBRARIES - component libraries to be linked
12753 Ice_INCLUDE_DIRS - the directories containing the Ice headers
12754 Ice_SLICE_DIRS - the directories containing the Ice slice interface
12755 definitions
12756 Imported targets:
12758 Ice::<C>
12760 Where <C> is the name of an Ice component, for example Ice::Glacier2 or
12762 Ice++11.
12763 Ice slice programs are reported in:
12765 Ice_SLICE2CONFLUENCE_EXECUTABLE - path to slice2confluence executable
12767 Ice_SLICE2CPP_EXECUTABLE - path to slice2cpp executable
12768 Ice_SLICE2CS_EXECUTABLE - path to slice2cs executable
12769 Ice_SLICE2FREEZEJ_EXECUTABLE - path to slice2freezej executable
12770 Ice_SLICE2FREEZE_EXECUTABLE - path to slice2freeze executable
12771 Ice_SLICE2HTML_EXECUTABLE - path to slice2html executable
12772 Ice_SLICE2JAVA_EXECUTABLE - path to slice2java executable
12773 Ice_SLICE2JS_EXECUTABLE - path to slice2js executable
12774 Ice_SLICE2MATLAB_EXECUTABLE - path to slice2matlab executable
12775 Ice_SLICE2OBJC_EXECUTABLE - path to slice2objc executable
12776 Ice_SLICE2PHP_EXECUTABLE - path to slice2php executable
12777 Ice_SLICE2PY_EXECUTABLE - path to slice2py executable
12778 Ice_SLICE2RB_EXECUTABLE - path to slice2rb executable
12779 New in version 3.14: Variables for slice2confluence and slice2matlab.
12781 Ice programs are reported in:
12784 Ice_GLACIER2ROUTER_EXECUTABLE - path to glacier2router executable
12786 Ice_ICEBOX_EXECUTABLE - path to icebox executable
12787 Ice_ICEBOXXX11_EXECUTABLE - path to icebox++11 executable
12788 Ice_ICEBOXADMIN_EXECUTABLE - path to iceboxadmin executable
12789 Ice_ICEBOXD_EXECUTABLE - path to iceboxd executable
12790 Ice_ICEBOXNET_EXECUTABLE - path to iceboxnet executable
12791 Ice_ICEBRIDGE_EXECUTABLE - path to icebridge executable
12792 Ice_ICEGRIDADMIN_EXECUTABLE - path to icegridadmin executable
12793 Ice_ICEGRIDDB_EXECUTABLE - path to icegriddb executable
12794 Ice_ICEGRIDNODE_EXECUTABLE - path to icegridnode executable
12795 Ice_ICEGRIDNODED_EXECUTABLE - path to icegridnoded executable
12796 Ice_ICEGRIDREGISTRY_EXECUTABLE - path to icegridregistry executable
12797 Ice_ICEGRIDREGISTRYD_EXECUTABLE - path to icegridregistryd executable
12798 Ice_ICEPATCH2CALC_EXECUTABLE - path to icepatch2calc executable
12799 Ice_ICEPATCH2CLIENT_EXECUTABLE - path to icepatch2client executable
12800 Ice_ICEPATCH2SERVER_EXECUTABLE - path to icepatch2server executable
12801 Ice_ICESERVICEINSTALL_EXECUTABLE - path to iceserviceinstall executable
12802 Ice_ICESTORMADMIN_EXECUTABLE - path to icestormadmin executable
12803 Ice_ICESTORMDB_EXECUTABLE - path to icestormdb executable
12804 Ice_ICESTORMMIGRATE_EXECUTABLE - path to icestormmigrate executable
12805 Ice db programs (Windows only; standard system versions on all other
12807 platforms) are reported in:
12808 Ice_DB_ARCHIVE_EXECUTABLE - path to db_archive executable
12810 Ice_DB_CHECKPOINT_EXECUTABLE - path to db_checkpoint executable
12811 Ice_DB_DEADLOCK_EXECUTABLE - path to db_deadlock executable
12812 Ice_DB_DUMP_EXECUTABLE - path to db_dump executable
12813 Ice_DB_HOTBACKUP_EXECUTABLE - path to db_hotbackup executable
12814 Ice_DB_LOAD_EXECUTABLE - path to db_load executable
12815 Ice_DB_LOG_VERIFY_EXECUTABLE - path to db_log_verify executable
12816 Ice_DB_PRINTLOG_EXECUTABLE - path to db_printlog executable
12817 Ice_DB_RECOVER_EXECUTABLE - path to db_recover executable
12818 Ice_DB_STAT_EXECUTABLE - path to db_stat executable
12819 Ice_DB_TUNER_EXECUTABLE - path to db_tuner executable
12820 Ice_DB_UPGRADE_EXECUTABLE - path to db_upgrade executable
12821 Ice_DB_VERIFY_EXECUTABLE - path to db_verify executable
12822 Ice_DUMPDB_EXECUTABLE - path to dumpdb executable
12823 Ice_TRANSFORMDB_EXECUTABLE - path to transformdb executable
12824 Ice component libraries are reported in:
12826 Ice_<C>_FOUND - ON if component was found
12828 Ice_<C>_LIBRARIES - libraries for component
12829 Note that <C> is the uppercased name of the component.
12831 This module reads hints about search results from:
12833 Ice_HOME - the root of the Ice installation
12835 The environment variable ICE_HOME may also be used; the Ice_HOME vari‐
12837 able takes precedence.
12838 NOTE:
12840 On Windows, Ice 3.7.0 and later provide libraries via the NuGet
12841 package manager. Appropriate NuGet packages will be searched for
12842 using CMAKE_PREFIX_PATH, or alternatively Ice_HOME may be set to the
12843 location of a specific NuGet package to restrict the search.
12844 The following cache variables may also be set:
12846 Ice_<P>_EXECUTABLE - the path to executable <P>
12848 Ice_INCLUDE_DIR - the directory containing the Ice headers
12849 Ice_SLICE_DIR - the directory containing the Ice slice interface
12850 definitions
12851 Ice_<C>_LIBRARY - the library for component <C>
12852 NOTE:
12854 In most cases none of the above variables will require setting, un‐
12855 less multiple Ice versions are available and a specific version is
12856 required. On Windows, the most recent version of Ice will be found
12857 through the registry. On Unix, the programs, headers and libraries
12858 will usually be in standard locations, but Ice_SLICE_DIRS might not
12859 be automatically detected (commonly known locations are searched).
12860 All the other variables are defaulted using Ice_HOME, if set. It's
12861 possible to set Ice_HOME and selectively specify alternative loca‐
12862 tions for the other components; this might be required for e.g.
12863 newer versions of Visual Studio if the heuristics are not sufficient
12864 to identify the correct programs and libraries for the specific Vis‐
12865 ual Studio version.
12866 Other variables one may set to control this module are:
12868 Ice_DEBUG - Set to ON to enable debug output from FindIce.
12870 FindIconv
12872 New in version 3.11.
12873 This module finds the iconv() POSIX.1 functions on the system. These
12876 functions might be provided in the regular C library or externally in
12877 the form of an additional library.
12878 The following variables are provided to indicate iconv support:
12880 Iconv_FOUND
12882 Variable indicating if the iconv support was found.
12883 Iconv_INCLUDE_DIRS
12885 The directories containing the iconv headers.
12886 Iconv_LIBRARIES
12888 The iconv libraries to be linked.
12889 Iconv_VERSION
12891 New in version 3.21.
12892 The version of iconv found (x.y)
12895 Iconv_VERSION_MAJOR
12897 New in version 3.21.
12898 The major version of iconv
12901 Iconv_VERSION_MINOR
12903 New in version 3.21.
12904 The minor version of iconv
12907 Iconv_IS_BUILT_IN
12909 A variable indicating whether iconv support is stemming from the
12910 C library or not. Even if the C library provides iconv(), the
12911 presence of an external libiconv implementation might lead to
12912 this being false.
12913 Additionally, the following IMPORTED target is being provided:
12915 Iconv::Iconv
12917 Imported target for using iconv.
12918 The following cache variables may also be set:
12920 Iconv_INCLUDE_DIR
12922 The directory containing the iconv headers.
12923 Iconv_LIBRARY
12925 The iconv library (if not implicitly given in the C library).
12926 NOTE:
12928 On POSIX platforms, iconv might be part of the C library and the
12929 cache variables Iconv_INCLUDE_DIR and Iconv_LIBRARY might be empty.
12930 NOTE:
12932 Some libiconv implementations don't embed the version number in
12933 their header files. In this case the variables Iconv_VERSION* will
12934 be empty.
12935 FindIcotool
12937 Find icotool
12938 This module looks for icotool. Convert and create Win32 icon and cursor
12940 files. This module defines the following values:
12941 ICOTOOL_EXECUTABLE: the full path to the icotool tool.
12943 ICOTOOL_FOUND: True if icotool has been found.
12944 ICOTOOL_VERSION_STRING: the version of icotool found.
12945 FindICU
12947 New in version 3.7.
12948 Find the International Components for Unicode (ICU) libraries and pro‐
12951 grams.
12952 This module supports multiple components. Components can include any
12954 of: data, i18n, io, le, lx, test, tu and uc.
12955 Note that on Windows data is named dt and i18n is named in; any of the
12957 names may be used, and the appropriate platform-specific library name
12958 will be automatically selected.
12959 New in version 3.11: Added support for static libraries on Windows.
12961 This module reports information about the ICU installation in several
12964 variables. General variables:
12965 ICU_VERSION - ICU release version
12967 ICU_FOUND - true if the main programs and libraries were found
12968 ICU_LIBRARIES - component libraries to be linked
12969 ICU_INCLUDE_DIRS - the directories containing the ICU headers
12970 Imported targets:
12972 ICU::<C>
12974 Where <C> is the name of an ICU component, for example ICU::i18n; <C>
12976 is lower-case.
12977 ICU programs are reported in:
12979 ICU_GENCNVAL_EXECUTABLE - path to gencnval executable
12981 ICU_ICUINFO_EXECUTABLE - path to icuinfo executable
12982 ICU_GENBRK_EXECUTABLE - path to genbrk executable
12983 ICU_ICU-CONFIG_EXECUTABLE - path to icu-config executable
12984 ICU_GENRB_EXECUTABLE - path to genrb executable
12985 ICU_GENDICT_EXECUTABLE - path to gendict executable
12986 ICU_DERB_EXECUTABLE - path to derb executable
12987 ICU_PKGDATA_EXECUTABLE - path to pkgdata executable
12988 ICU_UCONV_EXECUTABLE - path to uconv executable
12989 ICU_GENCFU_EXECUTABLE - path to gencfu executable
12990 ICU_MAKECONV_EXECUTABLE - path to makeconv executable
12991 ICU_GENNORM2_EXECUTABLE - path to gennorm2 executable
12992 ICU_GENCCODE_EXECUTABLE - path to genccode executable
12993 ICU_GENSPREP_EXECUTABLE - path to gensprep executable
12994 ICU_ICUPKG_EXECUTABLE - path to icupkg executable
12995 ICU_GENCMN_EXECUTABLE - path to gencmn executable
12996 ICU component libraries are reported in:
12998 ICU_<C>_FOUND - ON if component was found; ``<C>`` is upper-case.
13000 ICU_<C>_LIBRARIES - libraries for component; ``<C>`` is upper-case.
13001 ICU datafiles are reported in:
13003 ICU_MAKEFILE_INC - Makefile.inc
13005 ICU_PKGDATA_INC - pkgdata.inc
13006 This module reads hints about search results from:
13008 ICU_ROOT - the root of the ICU installation
13010 The environment variable ICU_ROOT may also be used; the ICU_ROOT vari‐
13012 able takes precedence.
13013 The following cache variables may also be set:
13015 ICU_<P>_EXECUTABLE - the path to executable <P>; ``<P>`` is upper-case.
13017 ICU_INCLUDE_DIR - the directory containing the ICU headers
13018 ICU_<C>_LIBRARY - the library for component <C>; ``<C>`` is upper-case.
13019 NOTE:
13021 In most cases none of the above variables will require setting, un‐
13022 less multiple ICU versions are available and a specific version is
13023 required.
13024 Other variables one may set to control this module are:
13026 ICU_DEBUG - Set to ON to enable debug output from FindICU.
13028 FindImageMagick
13030 Find ImageMagick binary suite.
13031 New in version 3.9: Added support for ImageMagick 7.
13033 This module will search for a set of ImageMagick tools specified as
13036 components in the find_package() call. Typical components include, but
13037 are not limited to (future versions of ImageMagick might have addi‐
13038 tional components not listed here):
13039 animate
13041 compare
13042 composite
13043 conjure
13044 convert
13045 display
13046 identify
13047 import
13048 mogrify
13049 montage
13050 stream
13051 If no component is specified in the find_package() call, then it only
13053 searches for the ImageMagick executable directory. This code defines
13054 the following variables:
13055 ImageMagick_FOUND - TRUE if all components are found.
13057 ImageMagick_EXECUTABLE_DIR - Full path to executables directory.
13058 ImageMagick_<component>_FOUND - TRUE if <component> is found.
13059 ImageMagick_<component>_EXECUTABLE - Full path to <component> executable.
13060 ImageMagick_VERSION_STRING - the version of ImageMagick found
13061 (since CMake 2.8.8)
13062 ImageMagick_VERSION_STRING will not work for old versions like 5.2.3.
13064 There are also components for the following ImageMagick APIs:
13066 Magick++
13068 MagickWand
13069 MagickCore
13070 For these components the following variables are set:
13072 ImageMagick_FOUND - TRUE if all components are found.
13074 ImageMagick_INCLUDE_DIRS - Full paths to all include dirs.
13075 ImageMagick_LIBRARIES - Full paths to all libraries.
13076 ImageMagick_<component>_FOUND - TRUE if <component> is found.
13077 ImageMagick_<component>_INCLUDE_DIRS - Full path to <component> include dirs.
13078 ImageMagick_<component>_LIBRARIES - Full path to <component> libraries.
13079 Example Usages:
13081 find_package(ImageMagick)
13083 find_package(ImageMagick COMPONENTS convert)
13084 find_package(ImageMagick COMPONENTS convert mogrify display)
13085 find_package(ImageMagick COMPONENTS Magick++)
13086 find_package(ImageMagick COMPONENTS Magick++ convert)
13087 Note that the standard find_package() features are supported (i.e.,
13089 QUIET, REQUIRED, etc.).
13090 FindIntl
13092 New in version 3.2.
13093 Find the Gettext libintl headers and libraries.
13096 This module reports information about the Gettext libintl installation
13098 in several variables.
13099 Intl_FOUND
13101 True if libintl is found.
13102 Intl_INCLUDE_DIRS
13104 The directory containing the libintl headers.
13105 Intl_LIBRARIES
13107 The intl libraries to be linked.
13108 Intl_VERSION
13110 New in version 3.21.
13111 The version of intl found (x.y.z)
13114 Intl_VERSION_MAJOR
13116 New in version 3.21.
13117 The major version of intl
13120 Intl_VERSION_MINOR
13122 New in version 3.21.
13123 The minor version of intl
13126 Intl_VERSION_PATCH
13128 New in version 3.21.
13129 The patch version of intl
13132 New in version 3.20: This module defines IMPORTED target Intl::Intl.
13134 The following cache variables may also be set:
13137 Intl_INCLUDE_DIR
13139 The directory containing the libintl headers
13140 Intl_LIBRARY
13142 The libintl library (if any)
13143 Intl_IS_BUILT_IN
13145 New in version 3.20.
13146 whether intl is a part of the C library.
13149 NOTE:
13151 On some platforms, such as Linux with GNU libc, the gettext func‐
13152 tions are present in the C standard library and libintl is not re‐
13153 quired. Intl_LIBRARIES will be empty in this case.
13154 NOTE:
13156 Some libintl implementations don't embed the version number in their
13157 header files. In this case the variables Intl_VERSION* will be
13158 empty.
13159 NOTE:
13161 If you wish to use the Gettext tools (msgmerge, msgfmt, etc.), use
13162 FindGettext.
13163 FindITK
13165 This module no longer exists.
13166 This module existed in versions of CMake prior to 3.1, but became only
13168 a thin wrapper around find_package(ITK NO_MODULE) to provide compati‐
13169 bility for projects using long-outdated conventions. Now find_pack‐
13170 age(ITK) will search for ITKConfig.cmake directly.
13171 FindJasper
13173 Find the Jasper JPEG2000 library.
13174 IMPORTED Targets
13176 Jasper::Jasper
13177 The jasper library, if found.
13178 Result Variables
13180 This module defines the following variables:
13181 JASPER_FOUND
13183 system has Jasper
13184 JASPER_INCLUDE_DIRS
13186 New in version 3.22.
13187 the Jasper include directory
13190 JASPER_LIBRARIES
13192 the libraries needed to use Jasper
13193 JASPER_VERSION_STRING
13195 the version of Jasper found
13196 Cache variables
13198 The following cache variables may also be set:
13199 JASPER_INCLUDE_DIR
13201 where to find jasper/jasper.h, etc.
13202 JASPER_LIBRARY_RELEASE
13204 where to find the Jasper library (optimized).
13205 JASPER_LIBARRY_DEBUG
13207 where to find the Jasper library (debug).
13208 FindJava
13210 Find Java
13211 This module finds if Java is installed and determines where the include
13213 files and libraries are. The caller may set variable JAVA_HOME to
13214 specify a Java installation prefix explicitly.
13215 See also the FindJNI module to find Java Native Interface (JNI).
13217 New in version 3.10: Added support for Java 9+ version parsing.
13219 Specify one or more of the following components as you call this find
13222 module. See example below.
13223 Runtime = Java Runtime Environment used to execute Java byte-compiled applications
13225 Development = Development tools (java, javac, javah, jar and javadoc), includes Runtime component
13226 IdlJ = Interface Description Language (IDL) to Java compiler
13227 JarSigner = Signer and verifier tool for Java Archive (JAR) files
13228 This module sets the following result variables:
13230 Java_JAVA_EXECUTABLE = the full path to the Java runtime
13232 Java_JAVAC_EXECUTABLE = the full path to the Java compiler
13233 Java_JAVAH_EXECUTABLE = the full path to the Java header generator
13234 Java_JAVADOC_EXECUTABLE = the full path to the Java documentation generator
13235 Java_IDLJ_EXECUTABLE = the full path to the Java idl compiler
13236 Java_JAR_EXECUTABLE = the full path to the Java archiver
13237 Java_JARSIGNER_EXECUTABLE = the full path to the Java jar signer
13238 Java_VERSION_STRING = Version of java found, eg. 1.6.0_12
13239 Java_VERSION_MAJOR = The major version of the package found.
13240 Java_VERSION_MINOR = The minor version of the package found.
13241 Java_VERSION_PATCH = The patch version of the package found.
13242 Java_VERSION_TWEAK = The tweak version of the package found (after '_')
13243 Java_VERSION = This is set to: $major[.$minor[.$patch[.$tweak]]]
13244 New in version 3.4: Added the Java_IDLJ_EXECUTABLE and Java_JAR‐
13246 SIGNER_EXECUTABLE variables.
13247 The minimum required version of Java can be specified using the
13250 find_package() syntax, e.g.
13251 find_package(Java 1.8)
13253 NOTE: ${Java_VERSION} and ${Java_VERSION_STRING} are not guaranteed to
13255 be identical. For example some java version may return: Java_VER‐
13256 SION_STRING = 1.8.0_17 and Java_VERSION = 1.8.0.17
13257 another example is the Java OEM, with: Java_VERSION_STRING = 1.8.0-oem
13259 and Java_VERSION = 1.8.0
13260 For these components the following variables are set:
13262 Java_FOUND - TRUE if all components are found.
13264 Java_<component>_FOUND - TRUE if <component> is found.
13265 Example Usages:
13267 find_package(Java)
13269 find_package(Java 1.8 REQUIRED)
13270 find_package(Java COMPONENTS Runtime)
13271 find_package(Java COMPONENTS Development)
13272 FindJNI
13274 Find Java Native Interface (JNI) headers and libraries.
13275 JNI enables Java code running in a Java Virtual Machine (JVM) or Dalvik
13277 Virtual Machine (DVM) on Android to call and be called by native appli‐
13278 cations and libraries written in other languages such as C and C++.
13279 This module finds if Java is installed and determines where the include
13281 files and libraries are. It also determines what the name of the li‐
13282 brary is. The caller may set variable JAVA_HOME to specify a Java in‐
13283 stallation prefix explicitly.
13284 New in version 3.24: Added imported targets, components AWT, JVM, and
13286 Android NDK support. If no components are specified, the module de‐
13287 faults to an empty components list while targeting Android, and all
13288 available components otherwise.
13289 When using Android NDK, the corresponding package version is reported
13291 and a specific release can be requested. At Android API level 31 and
13292 above, the additional NativeHelper component can be requested. Native‐
13293 Helper is also exposed as an implicit dependency of the JVM component
13294 (only if this does not cause a conflict) which provides a uniform ac‐
13295 cess to JVM functions.
13296 Imported Targets
13299 New in version 3.24.
13300 JNI::JNI
13303 Main JNI target, defined only if jni.h was found.
13304 JNI::AWT
13306 Java AWT Native Interface (JAWT) library, defined only if compo‐
13307 nent AWT was found.
13308 JNI::JVM
13310 Java Virtual Machine (JVM) library, defined only if component
13311 JVM was found.
13312 JNI::NativeHelper
13314 When targeting Android API level 31 and above, the import target
13315 will provide access to libnativehelper.so that exposes JVM func‐
13316 tions such as JNI_CreateJavaVM.
13317 Result Variables
13319 This module sets the following result variables:
13320 JNI_INCLUDE_DIRS
13322 The include directories to use.
13323 JNI_LIBRARIES
13325 The libraries to use (JAWT and JVM).
13326 JNI_FOUND
13328 TRUE if JNI headers and libraries were found.
13329 JNI_<component>_FOUND
13331 New in version 3.24.
13332 TRUE if <component> was found.
13335 JNI_VERSION
13337 Full Android NDK package version (including suffixes such as
13338 -beta3 and -rc1) or undefined otherwise.
13339 JNI_VERSION_MAJOR
13341 New in version 3.24.
13342 Android NDK major version or undefined otherwise.
13345 JNI_VERSION_MINOR
13347 New in version 3.24.
13348 Android NDK minor version or undefined otherwise.
13351 JNI_VERSION_PATCH
13353 New in version 3.24.
13354 Android NDK patch version or undefined otherwise.
13357 Cache Variables
13359 The following cache variables are also available to set or use:
13360 JAVA_AWT_LIBRARY
13362 The path to the Java AWT Native Interface (JAWT) library.
13363 JAVA_JVM_LIBRARY
13365 The path to the Java Virtual Machine (JVM) library.
13366 JAVA_INCLUDE_PATH
13368 The include path to jni.h.
13369 JAVA_INCLUDE_PATH2
13371 The include path to machine-dependant headers jni_md.h and jni‐
13372 port.h. The variable is defined only if jni.h depends on one of
13373 these headers. In contrast, Android NDK jni.h can be typically
13374 used standalone.
13375 JAVA_AWT_INCLUDE_PATH
13377 The include path to jawt.h.
13378 FindJPEG
13380 Find the Joint Photographic Experts Group (JPEG) library (libjpeg)
13381 Imported targets
13383 New in version 3.12.
13384 This module defines the following IMPORTED targets:
13387 JPEG::JPEG
13389 The JPEG library, if found.
13390 Result variables
13392 This module will set the following variables in your project:
13393 JPEG_FOUND
13395 If false, do not try to use JPEG.
13396 JPEG_INCLUDE_DIRS
13398 where to find jpeglib.h, etc.
13399 JPEG_LIBRARIES
13401 the libraries needed to use JPEG.
13402 JPEG_VERSION
13404 New in version 3.12: the version of the JPEG library found
13405 Cache variables
13408 The following cache variables may also be set:
13409 JPEG_INCLUDE_DIRS
13411 where to find jpeglib.h, etc.
13412 JPEG_LIBRARY_RELEASE
13414 where to find the JPEG library (optimized).
13415 JPEG_LIBRARY_DEBUG
13417 where to find the JPEG library (debug).
13418 New in version 3.12: Debug and Release variand are found separately.
13420 Obsolete variables
13423 JPEG_INCLUDE_DIR
13424 where to find jpeglib.h, etc. (same as JPEG_INCLUDE_DIRS)
13425 JPEG_LIBRARY
13427 where to find the JPEG library.
13428 FindKDE3
13430 Find the KDE3 include and library dirs, KDE preprocessors and define a
13431 some macros
13432 This module defines the following variables:
13434 KDE3_DEFINITIONS
13436 compiler definitions required for compiling KDE software
13437 KDE3_INCLUDE_DIR
13439 the KDE include directory
13440 KDE3_INCLUDE_DIRS
13442 the KDE and the Qt include directory, for use with include_di‐
13443 rectories()
13444 KDE3_LIB_DIR
13446 the directory where the KDE libraries are installed, for use
13447 with link_directories()
13448 QT_AND_KDECORE_LIBS
13450 this contains both the Qt and the kdecore library
13451 KDE3_DCOPIDL_EXECUTABLE
13453 the dcopidl executable
13454 KDE3_DCOPIDL2CPP_EXECUTABLE
13456 the dcopidl2cpp executable
13457 KDE3_KCFGC_EXECUTABLE
13459 the kconfig_compiler executable
13460 KDE3_FOUND
13462 set to TRUE if all of the above has been found
13463 The following user adjustable options are provided:
13465 KDE3_BUILD_TESTS
13467 enable this to build KDE testcases
13468 It also adds the following macros (from KDE3Macros.cmake) SRCS_VAR is
13470 always the variable which contains the list of source files for your
13471 application or library.
13472 KDE3_AUTOMOC(file1 ... fileN)
13474 Call this if you want to have automatic moc file handling.
13476 This means if you include "foo.moc" in the source file foo.cpp
13477 a moc file for the header foo.h will be created automatically.
13478 You can set the property SKIP_AUTOMAKE using set_source_files_properties()
13479 to exclude some files in the list from being processed.
13480 KDE3_ADD_MOC_FILES(SRCS_VAR file1 ... fileN )
13482 If you don't use the KDE3_AUTOMOC() macro, for the files
13484 listed here moc files will be created (named "foo.moc.cpp")
13485 KDE3_ADD_DCOP_SKELS(SRCS_VAR header1.h ... headerN.h )
13487 Use this to generate DCOP skeletions from the listed headers.
13489 KDE3_ADD_DCOP_STUBS(SRCS_VAR header1.h ... headerN.h )
13491 Use this to generate DCOP stubs from the listed headers.
13493 KDE3_ADD_UI_FILES(SRCS_VAR file1.ui ... fileN.ui )
13495 Use this to add the Qt designer ui files to your application/library.
13497 KDE3_ADD_KCFG_FILES(SRCS_VAR file1.kcfgc ... fileN.kcfgc )
13499 Use this to add KDE kconfig compiler files to your application/library.
13501 KDE3_INSTALL_LIBTOOL_FILE(target)
13503 This will create and install a simple libtool file for the given target.
13505 KDE3_ADD_EXECUTABLE(name file1 ... fileN )
13507 Currently identical to add_executable(), may provide some advanced
13509 features in the future.
13510 KDE3_ADD_KPART(name [WITH_PREFIX] file1 ... fileN )
13512 Create a KDE plugin (KPart, kioslave, etc.) from the given source files.
13514 If WITH_PREFIX is given, the resulting plugin will have the prefix "lib",
13515 otherwise it won't.
13516 It creates and installs an appropriate libtool la-file.
13517 KDE3_ADD_KDEINIT_EXECUTABLE(name file1 ... fileN )
13519 Create a KDE application in the form of a module loadable via kdeinit.
13521 A library named kdeinit_<name> will be created and a small executable
13522 which links to it.
13523 The option KDE3_ENABLE_FINAL to enable all-in-one compilation is no
13525 longer supported.
13526 Author: Alexander Neundorf <neundorf@kde.org>
13528 FindKDE4
13530 Find KDE4 and provide all necessary variables and macros to compile
13531 software for it. It looks for KDE 4 in the following directories in
13532 the given order:
13533 CMAKE_INSTALL_PREFIX
13535 KDEDIRS
13536 /opt/kde4
13537 Please look in FindKDE4Internal.cmake and KDE4Macros.cmake for more in‐
13539 formation. They are installed with the KDE 4 libraries in
13540 $KDEDIRS/share/apps/cmake/modules/.
13541 Author: Alexander Neundorf <neundorf@kde.org>
13543 FindLAPACK
13545 Find Linear Algebra PACKage (LAPACK) library
13546 This module finds an installed Fortran library that implements the
13548 LAPACK linear-algebra interface.
13549 At least one of the C, CXX, or Fortran languages must be enabled.
13551 Input Variables
13553 The following variables may be set to influence this module's behavior:
13554 BLA_STATIC
13556 if ON use static linkage
13557 BLA_VENDOR
13559 Set to one of the BLAS/LAPACK Vendors to search for BLAS only
13560 from the specified vendor. If not set, all vendors are consid‐
13561 ered.
13562 BLA_F95
13564 if ON tries to find the BLAS95/LAPACK95 interfaces
13565 BLA_PREFER_PKGCONFIG
13567 New in version 3.20.
13568 if set pkg-config will be used to search for a LAPACK library
13571 first and if one is found that is preferred
13572 BLA_PKGCONFIG_LAPACK
13574 New in version 3.25.
13575 If set, the pkg-config method will look for this module name in‐
13578 stead of just lapack.
13579 BLA_SIZEOF_INTEGER
13581 New in version 3.22.
13582 Specify the BLAS/LAPACK library integer size:
13585 4 Search for a BLAS/LAPACK with 32-bit integer interfaces.
13587 8 Search for a BLAS/LAPACK with 64-bit integer interfaces.
13589 ANY Search for any BLAS/LAPACK. Most likely, a BLAS/LAPACK
13591 with 32-bit integer interfaces will be found.
13592 Imported targets
13594 This module defines the following IMPORTED targets:
13595 LAPACK::LAPACK
13597 New in version 3.18.
13598 The libraries to use for LAPACK, if found.
13601 Result Variables
13603 This module defines the following variables:
13604 LAPACK_FOUND
13606 library implementing the LAPACK interface is found
13607 LAPACK_LINKER_FLAGS
13609 uncached list of required linker flags (excluding -l and -L).
13610 LAPACK_LIBRARIES
13612 uncached list of libraries (using full path name) to link
13613 against to use LAPACK
13614 LAPACK95_LIBRARIES
13616 uncached list of libraries (using full path name) to link
13617 against to use LAPACK95
13618 LAPACK95_FOUND
13620 library implementing the LAPACK95 interface is found
13621 Intel MKL
13623 To use the Intel MKL implementation of LAPACK, a project must enable at
13624 least one of the C or CXX languages. Set BLA_VENDOR to an Intel MKL
13625 variant either on the command-line as -DBLA_VENDOR=Intel10_64lp or in
13626 project code:
13627 set(BLA_VENDOR Intel10_64lp)
13629 find_package(LAPACK)
13630 In order to build a project using Intel MKL, and end user must first
13632 establish an Intel MKL environment. See the FindBLAS module section on
13633 Intel MKL for details.
13634 FindLATEX
13636 Find LaTeX
13637 This module finds an installed LaTeX and determines the location of the
13639 compiler. Additionally the module looks for Latex-related software
13640 like BibTeX.
13641 New in version 3.2: Component processing; support for htlatex, pdftops,
13643 Biber, xindy, XeLaTeX, LuaLaTeX.
13644 This module sets the following result variables:
13647 LATEX_FOUND: whether found Latex and requested components
13649 LATEX_<component>_FOUND: whether found <component>
13650 LATEX_COMPILER: path to the LaTeX compiler
13651 PDFLATEX_COMPILER: path to the PdfLaTeX compiler
13652 XELATEX_COMPILER: path to the XeLaTeX compiler
13653 LUALATEX_COMPILER: path to the LuaLaTeX compiler
13654 BIBTEX_COMPILER: path to the BibTeX compiler
13655 BIBER_COMPILER: path to the Biber compiler
13656 MAKEINDEX_COMPILER: path to the MakeIndex compiler
13657 XINDY_COMPILER: path to the xindy compiler
13658 DVIPS_CONVERTER: path to the DVIPS converter
13659 DVIPDF_CONVERTER: path to the DVIPDF converter
13660 PS2PDF_CONVERTER: path to the PS2PDF converter
13661 PDFTOPS_CONVERTER: path to the pdftops converter
13662 LATEX2HTML_CONVERTER: path to the LaTeX2Html converter
13663 HTLATEX_COMPILER: path to the htlatex compiler
13664 Possible components are:
13666 PDFLATEX
13668 XELATEX
13669 LUALATEX
13670 BIBTEX
13671 BIBER
13672 MAKEINDEX
13673 XINDY
13674 DVIPS
13675 DVIPDF
13676 PS2PDF
13677 PDFTOPS
13678 LATEX2HTML
13679 HTLATEX
13680 Example Usages:
13682 find_package(LATEX)
13684 find_package(LATEX COMPONENTS PDFLATEX)
13685 find_package(LATEX COMPONENTS BIBTEX PS2PDF)
13686 FindLibArchive
13688 Find libarchive library and headers. Libarchive is multi-format ar‐
13689 chive and compression library.
13690 The module defines the following variables:
13692 LibArchive_FOUND - true if libarchive was found
13694 LibArchive_INCLUDE_DIRS - include search path
13695 LibArchive_LIBRARIES - libraries to link
13696 LibArchive_VERSION - libarchive 3-component version number
13697 The module defines the following IMPORTED targets:
13699 LibArchive::LibArchive - target for linking against libarchive
13701 New in version 3.6: Support for new libarchive 3.2 version string for‐
13703 mat.
13704 New in version 3.17: Provides an imported target.
13707 FindLibinput
13710 New in version 3.14.
13711 Find libinput headers and library.
13714 Imported Targets
13716 Libinput::Libinput
13717 The libinput library, if found.
13718 Result Variables
13720 This will define the following variables in your project:
13721 Libinput_FOUND
13723 true if (the requested version of) libinput is available.
13724 Libinput_VERSION
13726 the version of libinput.
13727 Libinput_LIBRARIES
13729 the libraries to link against to use libinput.
13730 Libinput_INCLUDE_DIRS
13732 where to find the libinput headers.
13733 Libinput_COMPILE_OPTIONS
13735 this should be passed to target_compile_options(), if the target
13736 is not used for linking
13737 FindLibLZMA
13739 Find LZMA compression algorithm headers and library.
13740 Imported Targets
13742 New in version 3.14.
13743 This module defines IMPORTED target LibLZMA::LibLZMA, if liblzma has
13746 been found.
13747 Result variables
13749 This module will set the following variables in your project:
13750 LIBLZMA_FOUND
13752 True if liblzma headers and library were found.
13753 LIBLZMA_INCLUDE_DIRS
13755 Directory where liblzma headers are located.
13756 LIBLZMA_LIBRARIES
13758 Lzma libraries to link against.
13759 LIBLZMA_HAS_AUTO_DECODER
13761 True if lzma_auto_decoder() is found (required).
13762 LIBLZMA_HAS_EASY_ENCODER
13764 True if lzma_easy_encoder() is found (required).
13765 LIBLZMA_HAS_LZMA_PRESET
13767 True if lzma_lzma_preset() is found (required).
13768 LIBLZMA_VERSION_MAJOR
13770 The major version of lzma
13771 LIBLZMA_VERSION_MINOR
13773 The minor version of lzma
13774 LIBLZMA_VERSION_PATCH
13776 The patch version of lzma
13777 LIBLZMA_VERSION_STRING
13779 version number as a string (ex: "5.0.3")
13780 FindLibXml2
13782 Find the XML processing library (libxml2).
13783 IMPORTED Targets
13785 New in version 3.12.
13786 The following IMPORTED targets may be defined:
13789 LibXml2::LibXml2
13791 libxml2 library.
13792 LibXml2::xmllint
13794 New in version 3.17.
13795 xmllint command-line executable.
13798 Result variables
13800 This module will set the following variables in your project:
13801 LibXml2_FOUND
13803 true if libxml2 headers and libraries were found
13804 LIBXML2_INCLUDE_DIR
13806 the directory containing LibXml2 headers
13807 LIBXML2_INCLUDE_DIRS
13809 list of the include directories needed to use LibXml2
13810 LIBXML2_LIBRARIES
13812 LibXml2 libraries to be linked
13813 LIBXML2_DEFINITIONS
13815 the compiler switches required for using LibXml2
13816 LIBXML2_XMLLINT_EXECUTABLE
13818 path to the XML checking tool xmllint coming with LibXml2
13819 LIBXML2_VERSION_STRING
13821 the version of LibXml2 found (since CMake 2.8.8)
13822 Cache variables
13824 The following cache variables may also be set:
13825 LIBXML2_INCLUDE_DIR
13827 the directory containing LibXml2 headers
13828 LIBXML2_LIBRARY
13830 path to the LibXml2 library
13831 FindLibXslt
13833 Find the XSL Transformations, Extensible Stylesheet Language Transfor‐
13834 mations (XSLT) library (LibXslt)
13835 IMPORTED Targets
13837 New in version 3.18.
13838 The following IMPORTED targets may be defined:
13841 LibXslt::LibXslt
13843 If the libxslt library has been found
13844 LibXslt::LibExslt
13846 If the libexslt library has been found
13847 LibXslt::xsltproc
13849 If the xsltproc command-line executable has been found
13850 Result variables
13852 This module will set the following variables in your project:
13853 LIBXSLT_FOUND - system has LibXslt LIBXSLT_INCLUDE_DIR - the LibXslt
13854 include directory LIBXSLT_LIBRARIES - Link these to LibXslt
13855 LIBXSLT_DEFINITIONS - Compiler switches required for using LibXslt
13856 LIBXSLT_VERSION_STRING - version of LibXslt found (since CMake
13857 2.8.8)
13858 Additionally, the following two variables are set (but not required for
13860 using xslt):
13861 LIBXSLT_EXSLT_INCLUDE_DIR
13863 New in version 3.18: The include directory for exslt.
13864 LIBXSLT_EXSLT_LIBRARIES
13867 Link to these if you need to link against the exslt library.
13868 LIBXSLT_XSLTPROC_EXECUTABLE
13870 Contains the full path to the xsltproc executable if found.
13871 FindLTTngUST
13873 New in version 3.6.
13874 Find Linux Trace Toolkit Next Generation (LTTng-UST) library.
13877 Imported target
13879 This module defines the following IMPORTED target:
13880 LTTng::UST
13882 The LTTng-UST library, if found
13883 Result variables
13885 This module sets the following
13886 LTTNGUST_FOUND
13888 TRUE if system has LTTng-UST
13889 LTTNGUST_INCLUDE_DIRS
13891 The LTTng-UST include directories
13892 LTTNGUST_LIBRARIES
13894 The libraries needed to use LTTng-UST
13895 LTTNGUST_VERSION_STRING
13897 The LTTng-UST version
13898 LTTNGUST_HAS_TRACEF
13900 TRUE if the tracef() API is available in the system's LTTng-UST
13901 LTTNGUST_HAS_TRACELOG
13903 TRUE if the tracelog() API is available in the system's LT‐
13904 Tng-UST
13905 FindLua
13907 Locate Lua library.
13908 New in version 3.18: Support for Lua 5.4.
13910 This module defines:
13913 LUA_FOUND
13915 if false, do not try to link to Lua
13916 LUA_LIBRARIES
13918 both lua and lualib
13919 LUA_INCLUDE_DIR
13921 where to find lua.h
13922 LUA_VERSION_STRING
13924 the version of Lua found
13925 LUA_VERSION_MAJOR
13927 the major version of Lua
13928 LUA_VERSION_MINOR
13930 the minor version of Lua
13931 LUA_VERSION_PATCH
13933 the patch version of Lua
13934 Note that the expected include convention is
13936 #include "lua.h"
13938 and not
13940 #include <lua/lua.h>
13942 This is because, the lua location is not standardized and may exist in
13944 locations other than lua/
13945 FindLua50
13947 Locate Lua library. This module defines:
13948 ::
13950 LUA50_FOUND, if false, do not try to link to Lua LUA_LIBRARIES, both
13951 lua and lualib LUA_INCLUDE_DIR, where to find lua.h and lualib.h
13952 (and probably lauxlib.h)
13953 Note that the expected include convention is
13955 #include "lua.h"
13957 and not
13959 #include <lua/lua.h>
13961 This is because, the lua location is not standardized and may exist in
13963 locations other than lua/
13964 FindLua51
13966 Locate Lua library. This module defines:
13967 ::
13969 LUA51_FOUND, if false, do not try to link to Lua LUA_LIBRARIES
13970 LUA_INCLUDE_DIR, where to find lua.h LUA_VERSION_STRING, the version
13971 of Lua found (since CMake 2.8.8)
13972 Note that the expected include convention is
13974 #include "lua.h"
13976 and not
13978 #include <lua/lua.h>
13980 This is because, the lua location is not standardized and may exist in
13982 locations other than lua/
13983 FindMatlab
13985 Finds Matlab or Matlab Compiler Runtime (MCR) and provides Matlab
13986 tools, libraries and compilers to CMake.
13987 This package primary purpose is to find the libraries associated with
13989 Matlab or the MCR in order to be able to build Matlab extensions (mex
13990 files). It can also be used:
13991 • to run specific commands in Matlab in case Matlab is available
13993 • for declaring Matlab unit test
13995 • to retrieve various information from Matlab (mex extensions, versions
13997 and release queries, ...)
13998 New in version 3.12: Added Matlab Compiler Runtime (MCR) support.
14000 The module supports the following components:
14003 • ENG_LIBRARY and MAT_LIBRARY: respectively the ENG and MAT libraries
14005 of Matlab
14006 • MAIN_PROGRAM the Matlab binary program. Note that this component is
14008 not available on the MCR version, and will yield an error if the MCR
14009 is found instead of the regular Matlab installation.
14010 • MEX_COMPILER the MEX compiler.
14012 • MCC_COMPILER the MCC compiler, included with the Matlab Compiler
14014 add-on.
14015 • SIMULINK the Simulink environment.
14017 New in version 3.7: Added the MAT_LIBRARY component.
14019 New in version 3.13: Added the ENGINE_LIBRARY, DATAARRAY_LIBRARY and
14022 MCC_COMPILER components.
14023 Changed in version 3.14: Removed the MX_LIBRARY, ENGINE_LIBRARY and
14026 DATAARRAY_LIBRARY components. These libraries are found uncondition‐
14027 ally.
14028 NOTE:
14031 The version given to the find_package() directive is the Matlab ver‐
14032 sion, which should not be confused with the Matlab release name (eg.
14033 R2014). The matlab_get_version_from_release_name() and
14034 matlab_get_release_name_from_version() provide a mapping between the
14035 release name and the version.
14036 The variable Matlab_ROOT_DIR may be specified in order to give the path
14038 of the desired Matlab version. Otherwise, the behavior is platform spe‐
14039 cific:
14040 • Windows: The installed versions of Matlab/MCR are retrieved from the
14042 Windows registry
14043 • OS X: The installed versions of Matlab/MCR are given by the MATLAB
14045 default installation paths in /Application. If no such application is
14046 found, it falls back to the one that might be accessible from the
14047 PATH.
14048 • Unix: The desired Matlab should be accessible from the PATH. This
14050 does not work for MCR installation and Matlab_ROOT_DIR should be
14051 specified on this platform.
14052 Additional information is provided when MATLAB_FIND_DEBUG is set. When
14054 a Matlab/MCR installation is found automatically and the MATLAB_VERSION
14055 is not given, the version is queried from Matlab directly (on Windows
14056 this may pop up a Matlab window) or from the MCR installation.
14057 The mapping of the release names and the version of Matlab is performed
14059 by defining pairs (name, version). The variable
14060 MATLAB_ADDITIONAL_VERSIONS may be provided before the call to the
14061 find_package() in order to handle additional versions.
14062 A Matlab scripts can be added to the set of tests using the
14064 matlab_add_unit_test(). By default, the Matlab unit test framework will
14065 be used (>= 2013a) to run this script, but regular .m files returning
14066 an exit code can be used as well (0 indicating a success).
14067 Module Input Variables
14069 Users or projects may set the following variables to configure the mod‐
14070 ule behavior:
14071 Matlab_ROOT
14073 New in version 3.25.
14074 Default value for Matlab_ROOT_DIR, the root of the Matlab in‐
14077 stallation.
14078 Matlab_ROOT_DIR
14080 The root of the Matlab installation.
14081 MATLAB_FIND_DEBUG
14083 outputs debug information
14084 MATLAB_ADDITIONAL_VERSIONS
14086 additional versions of Matlab for the automatic retrieval of the
14087 installed versions.
14088 Imported targets
14090 New in version 3.22.
14091 This module defines the following IMPORTED targets:
14094 Matlab::mex
14096 The mex library, always available.
14097 Matlab::mx
14099 The mx library of Matlab (arrays), always available.
14100 Matlab::eng
14102 Matlab engine library. Available only if the ENG_LIBRARY compo‐
14103 nent is requested.
14104 Matlab::mat
14106 Matlab matrix library. Available only if the MAT_LIBRARY compo‐
14107 nent is requested.
14108 Matlab::MatlabEngine
14110 Matlab C++ engine library, always available for R2018a and
14111 newer.
14112 Matlab::MatlabDataArray
14114 Matlab C++ data array library, always available for R2018a and
14115 newer.
14116 Variables defined by the module
14118 Result variables
14119 Matlab_FOUND
14120 TRUE if the Matlab installation is found, FALSE otherwise. All
14121 variable below are defined if Matlab is found.
14122 Matlab_ROOT_DIR
14124 the final root of the Matlab installation determined by the
14125 FindMatlab module.
14126 Matlab_MAIN_PROGRAM
14128 the Matlab binary program. Available only if the component
14129 MAIN_PROGRAM is given in the find_package() directive.
14130 Matlab_INCLUDE_DIRS
14132 the path of the Matlab libraries headers
14133 Matlab_MEX_LIBRARY
14135 library for mex, always available.
14136 Matlab_MX_LIBRARY
14138 mx library of Matlab (arrays), always available.
14139 Matlab_ENG_LIBRARY
14141 Matlab engine library. Available only if the component ENG_LI‐
14142 BRARY is requested.
14143 Matlab_MAT_LIBRARY
14145 Matlab matrix library. Available only if the component MAT_LI‐
14146 BRARY is requested.
14147 Matlab_ENGINE_LIBRARY
14149 New in version 3.13.
14150 Matlab C++ engine library, always available for R2018a and
14153 newer.
14154 Matlab_DATAARRAY_LIBRARY
14156 New in version 3.13.
14157 Matlab C++ data array library, always available for R2018a and
14160 newer.
14161 Matlab_LIBRARIES
14163 the whole set of libraries of Matlab
14164 Matlab_MEX_COMPILER
14166 the mex compiler of Matlab. Currently not used. Available only
14167 if the component MEX_COMPILER is requested.
14168 Matlab_MCC_COMPILER
14170 New in version 3.13.
14171 the mcc compiler of Matlab. Included with the Matlab Compiler
14174 add-on. Available only if the component MCC_COMPILER is re‐
14175 quested.
14176 Cached variables
14178 Matlab_MEX_EXTENSION
14179 the extension of the mex files for the current platform (given
14180 by Matlab).
14181 Matlab_ROOT_DIR
14183 the location of the root of the Matlab installation found. If
14184 this value is changed by the user, the result variables are re‐
14185 computed.
14186 Provided macros
14188 matlab_get_version_from_release_name()
14189 returns the version from the release name
14190 matlab_get_release_name_from_version()
14192 returns the release name from the Matlab version
14193 Provided functions
14195 matlab_add_mex()
14196 adds a target compiling a MEX file.
14197 matlab_add_unit_test()
14199 adds a Matlab unit test file as a test to the project.
14200 matlab_extract_all_installed_versions_from_registry()
14202 parses the registry for all Matlab versions. Available on Win‐
14203 dows only. The part of the registry parsed is dependent on the
14204 host processor
14205 matlab_get_all_valid_matlab_roots_from_registry()
14207 returns all the possible Matlab or MCR paths, according to a
14208 previously given list. Only the existing/accessible paths are
14209 kept. This is mainly useful for the searching all possible Mat‐
14210 lab installation.
14211 matlab_get_mex_suffix()
14213 returns the suffix to be used for the mex files (platform/archi‐
14214 tecture dependent)
14215 matlab_get_version_from_matlab_run()
14217 returns the version of Matlab/MCR, given the full directory of
14218 the Matlab/MCR installation path.
14219 Known issues
14221 Symbol clash in a MEX target
14222 By default, every symbols inside a MEX file defined with the
14223 command matlab_add_mex() have hidden visibility, except for the
14224 entry point. This is the default behavior of the MEX compiler,
14225 which lowers the risk of symbol collision between the libraries
14226 shipped with Matlab, and the libraries to which the MEX file is
14227 linking to. This is also the default on Windows platforms.
14228 However, this is not sufficient in certain case, where for in‐
14230 stance your MEX file is linking against libraries that are al‐
14231 ready loaded by Matlab, even if those libraries have different
14232 SONAMES. A possible solution is to hide the symbols of the li‐
14233 braries to which the MEX target is linking to. This can be
14234 achieved in GNU GCC compilers with the linker option -Wl,--ex‐
14235 clude-libs,ALL.
14236 Tests using GPU resources
14238 in case your MEX file is using the GPU and in order to be able
14239 to run unit tests on this MEX file, the GPU resources should be
14240 properly released by Matlab. A possible solution is to make Mat‐
14241 lab aware of the use of the GPU resources in the session, which
14242 can be performed by a command such as D = gpuDevice() at the be‐
14243 ginning of the test script (or via a fixture).
14244 Reference
14246 Matlab_ROOT_DIR
14247 The root folder of the Matlab installation. If set before the
14248 call to find_package(), the module will look for the components
14249 in that path. If not set, then an automatic search of Matlab
14250 will be performed. If set, it should point to a valid version of
14251 Matlab.
14252 MATLAB_FIND_DEBUG
14254 If set, the lookup of Matlab and the intermediate configuration
14255 steps are outputted to the console.
14256 MATLAB_ADDITIONAL_VERSIONS
14258 If set, specifies additional versions of Matlab that may be
14259 looked for. The variable should be a list of strings, organized
14260 by pairs of release name and versions, such as follows:
14261 set(MATLAB_ADDITIONAL_VERSIONS
14263 "release_name1=corresponding_version1"
14264 "release_name2=corresponding_version2"
14265 ...
14266 )
14267 Example:
14269 set(MATLAB_ADDITIONAL_VERSIONS
14271 "R2013b=8.2"
14272 "R2013a=8.1"
14273 "R2012b=8.0")
14274 The order of entries in this list matters when several versions
14276 of Matlab are installed. The priority is set according to the
14277 ordering in this list.
14278 matlab_get_version_from_release_name
14280 Returns the version of Matlab (17.58) from a release name
14281 (R2017k)
14282 matlab_get_release_name_from_version
14284 Returns the release name (R2017k) from the version of Matlab
14285 (17.58)
14286 matlab_extract_all_installed_versions_from_registry
14288 This function parses the registry and founds the Matlab versions
14289 that are installed. The found versions are returned in mat‐
14290 lab_versions. Set win64 to TRUE if the 64 bit version of Matlab
14291 should be looked for The returned list contains all versions un‐
14292 der HKLM\\SOFTWARE\\Mathworks\\MATLAB and HKLM\\SOFTWARE\\Math‐
14293 works\\MATLAB Runtime or an empty list in case an error occurred
14294 (or nothing found).
14295 NOTE:
14297 Only the versions are provided. No check is made over the ex‐
14298 istence of the installation referenced in the registry,
14299 matlab_get_all_valid_matlab_roots_from_registry
14301 Populates the Matlab root with valid versions of Matlab or Mat‐
14302 lab Runtime (MCR). The returned matlab_roots is organized in
14303 triplets (type,version_number,matlab_root_path), where type in‐
14304 dicates either MATLAB or MCR.
14305 matlab_get_all_valid_matlab_roots_from_registry(
14307 matlab_versions
14308 matlab_roots)
14309 matlab_versions
14311 the versions of each of the Matlab or MCR installations
14312 matlab_roots
14314 the location of each of the Matlab or MCR installations
14315 matlab_get_mex_suffix
14317 Returns the extension of the mex files (the suffixes). This
14318 function should not be called before the appropriate Matlab root
14319 has been found.
14320 matlab_get_mex_suffix(
14322 matlab_root
14323 mex_suffix)
14324 matlab_root
14326 the root of the Matlab/MCR installation
14327 mex_suffix
14329 the variable name in which the suffix will be returned.
14330 matlab_get_version_from_matlab_run
14332 This function runs Matlab program specified on arguments and ex‐
14333 tracts its version. If the path provided for the Matlab instal‐
14334 lation points to an MCR installation, the version is extracted
14335 from the installed files.
14336 matlab_get_version_from_matlab_run(
14338 matlab_binary_path
14339 matlab_list_versions)
14340 matlab_binary_path
14342 the location of the matlab binary executable
14343 matlab_list_versions
14345 the version extracted from Matlab
14346 matlab_add_unit_test
14348 Adds a Matlab unit test to the test set of cmake/ctest. This
14349 command requires the component MAIN_PROGRAM and hence is not
14350 available for an MCR installation.
14351 The unit test uses the Matlab unittest framework (default,
14353 available starting Matlab 2013b+) except if the option
14354 NO_UNITTEST_FRAMEWORK is given.
14355 The function expects one Matlab test script file to be given.
14357 In the case NO_UNITTEST_FRAMEWORK is given, the unittest script
14358 file should contain the script to be run, plus an exit command
14359 with the exit value. This exit value will be passed to the ctest
14360 framework (0 success, non 0 failure). Additional arguments ac‐
14361 cepted by add_test() can be passed through TEST_ARGS (eg. CON‐
14362 FIGURATION <config> ...).
14363 matlab_add_unit_test(
14365 NAME <name>
14366 UNITTEST_FILE matlab_file_containing_unittest.m
14367 [CUSTOM_TEST_COMMAND matlab_command_to_run_as_test]
14368 [UNITTEST_PRECOMMAND matlab_command_to_run]
14369 [TIMEOUT timeout]
14370 [ADDITIONAL_PATH path1 [path2 ...]]
14371 [MATLAB_ADDITIONAL_STARTUP_OPTIONS option1 [option2 ...]]
14372 [TEST_ARGS arg1 [arg2 ...]]
14373 [NO_UNITTEST_FRAMEWORK]
14374 )
14375 The function arguments are:
14377 NAME name of the unittest in ctest.
14379 UNITTEST_FILE
14381 the matlab unittest file. Its path will be automatically
14382 added to the Matlab path.
14383 CUSTOM_TEST_COMMAND
14385 Matlab script command to run as the test. If this is not
14386 set, then the following is run: runtests('mat‐
14387 lab_file_name'), exit(max([ans(1,:).Failed])) where mat‐
14388 lab_file_name is the UNITTEST_FILE without the extension.
14389 UNITTEST_PRECOMMAND
14391 Matlab script command to be ran before the file contain‐
14392 ing the test (eg. GPU device initialization based on
14393 CMake variables).
14394 TIMEOUT
14396 the test timeout in seconds. Defaults to 180 seconds as
14397 the Matlab unit test may hang.
14398 ADDITIONAL_PATH
14400 a list of paths to add to the Matlab path prior to run‐
14401 ning the unit test.
14402 MATLAB_ADDITIONAL_STARTUP_OPTIONS
14404 a list of additional option in order to run Matlab from
14405 the command line. -nosplash -nodesktop -nodisplay are
14406 always added.
14407 TEST_ARGS
14409 Additional options provided to the add_test command.
14410 These options are added to the default options (eg. "CON‐
14411 FIGURATIONS Release")
14412 NO_UNITTEST_FRAMEWORK
14414 when set, indicates that the test should not use the
14415 unittest framework of Matlab (available for versions >=
14416 R2013a).
14417 WORKING_DIRECTORY
14419 This will be the working directory for the test. If spec‐
14420 ified it will also be the output directory used for the
14421 log file of the test run. If not specified the temporary
14422 directory ${CMAKE_BINARY_DIR}/Matlab will be used as the
14423 working directory and the log location.
14424 matlab_add_mex
14426 Adds a Matlab MEX target. This commands compiles the given
14427 sources with the current tool-chain in order to produce a MEX
14428 file. The final name of the produced output may be specified, as
14429 well as additional link libraries, and a documentation entry for
14430 the MEX file. Remaining arguments of the call are passed to the
14431 add_library() or add_executable() command.
14432 matlab_add_mex(
14434 NAME <name>
14435 [EXECUTABLE | MODULE | SHARED]
14436 SRC src1 [src2 ...]
14437 [OUTPUT_NAME output_name]
14438 [DOCUMENTATION file.txt]
14439 [LINK_TO target1 target2 ...]
14440 [R2017b | R2018a]
14441 [EXCLUDE_FROM_ALL]
14442 [NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES]
14443 [...]
14444 )
14445 NAME name of the target.
14447 SRC list of source files.
14449 LINK_TO
14451 a list of additional link dependencies. The target links
14452 to libmex and libmx by default, unless the NO_IM‐
14453 PLICIT_LINK_TO_MATLAB_LIBRARIES option is passed.
14454 OUTPUT_NAME
14456 if given, overrides the default name. The default name is
14457 the name of the target without any prefix and with Mat‐
14458 lab_MEX_EXTENSION suffix.
14459 DOCUMENTATION
14461 if given, the file file.txt will be considered as being
14462 the documentation file for the MEX file. This file is
14463 copied into the same folder without any processing, with
14464 the same name as the final mex file, and with extension
14465 .m. In that case, typing help <name> in Matlab prints the
14466 documentation contained in this file.
14467 R2017b or R2018a
14469 New in version 3.14.
14470 May be given to specify the version of the C API to use:
14473 R2017b specifies the traditional (separate complex) C
14474 API, and corresponds to the -R2017b flag for the mex com‐
14475 mand. R2018a specifies the new interleaved complex C API,
14476 and corresponds to the -R2018a flag for the mex command.
14477 Ignored if MATLAB version prior to R2018a. Defaults to
14478 R2017b.
14479 MODULE or SHARED
14481 New in version 3.7.
14482 May be given to specify the type of library to be cre‐
14485 ated.
14486 EXECUTABLE
14488 New in version 3.7.
14489 May be given to create an executable instead of a li‐
14492 brary. If no type is given explicitly, the type is
14493 SHARED.
14494 EXCLUDE_FROM_ALL
14496 This option has the same meaning as for EXCLUDE_FROM_ALL
14497 and is forwarded to add_library() or add_executable()
14498 commands.
14499 NO_IMPLICIT_LINK_TO_MATLAB_LIBRARIES
14501 New in version 3.24.
14502 This option permits to disable the automatic linking of
14505 MATLAB libraries, so that only the libraries that are ac‐
14506 tually required can be linked via the LINK_TO option.
14507 The documentation file is not processed and should be in the
14509 following format:
14510 % This is the documentation
14512 function ret = mex_target_output_name(input1)
14513 FindMFC
14515 Find Microsoft Foundation Class Library (MFC) on Windows
14516 Find the native MFC - i.e. decide if an application can link to the
14518 MFC libraries.
14519 MFC_FOUND - Was MFC support found
14521 You don't need to include anything or link anything to use it.
14523 FindMotif
14525 Try to find Motif (or lesstif)
14526 Once done this will define:
14528 MOTIF_FOUND - system has MOTIF
14530 MOTIF_INCLUDE_DIR - include paths to use Motif
14531 MOTIF_LIBRARIES - Link these to use Motif
14532 FindMPEG
14534 Find the native MPEG includes and library
14535 This module defines
14537 MPEG_INCLUDE_DIR, where to find MPEG.h, etc.
14539 MPEG_LIBRARIES, the libraries required to use MPEG.
14540 MPEG_FOUND, If false, do not try to use MPEG.
14541 also defined, but not for general use are
14543 MPEG_mpeg2_LIBRARY, where to find the MPEG library.
14545 MPEG_vo_LIBRARY, where to find the vo library.
14546 FindMPEG2
14548 Find the native MPEG2 includes and library
14549 This module defines
14551 MPEG2_INCLUDE_DIR, path to mpeg2dec/mpeg2.h, etc.
14553 MPEG2_LIBRARIES, the libraries required to use MPEG2.
14554 MPEG2_FOUND, If false, do not try to use MPEG2.
14555 also defined, but not for general use are
14557 MPEG2_mpeg2_LIBRARY, where to find the MPEG2 library.
14559 MPEG2_vo_LIBRARY, where to find the vo library.
14560 FindMPI
14562 Find a Message Passing Interface (MPI) implementation.
14563 The Message Passing Interface (MPI) is a library used to write
14565 high-performance distributed-memory parallel applications, and is typi‐
14566 cally deployed on a cluster. MPI is a standard interface (defined by
14567 the MPI forum) for which many implementations are available.
14568 New in version 3.10: Major overhaul of the module: many new variables,
14570 per-language components, support for a wider variety of runtimes.
14571 Variables for using MPI
14574 The module exposes the components C, CXX, MPICXX and Fortran. Each of
14575 these controls the various MPI languages to search for. The difference
14576 between CXX and MPICXX is that CXX refers to the MPI C API being usable
14577 from C++, whereas MPICXX refers to the MPI-2 C++ API that was removed
14578 again in MPI-3.
14579 Depending on the enabled components the following variables will be
14581 set:
14582 MPI_FOUND
14584 Variable indicating that MPI settings for all requested lan‐
14585 guages have been found. If no components are specified, this is
14586 true if MPI settings for all enabled languages were detected.
14587 Note that the MPICXX component does not affect this variable.
14588 MPI_VERSION
14590 Minimal version of MPI detected among the requested languages,
14591 or all enabled languages if no components were specified.
14592 This module will set the following variables per language in your
14594 project, where <lang> is one of C, CXX, or Fortran:
14595 MPI_<lang>_FOUND
14597 Variable indicating the MPI settings for <lang> were found and
14598 that simple MPI test programs compile with the provided set‐
14599 tings.
14600 MPI_<lang>_COMPILER
14602 MPI compiler for <lang> if such a program exists.
14603 MPI_<lang>_COMPILE_OPTIONS
14605 Compilation options for MPI programs in <lang>, given as a
14606 ;-list.
14607 MPI_<lang>_COMPILE_DEFINITIONS
14609 Compilation definitions for MPI programs in <lang>, given as a
14610 ;-list.
14611 MPI_<lang>_INCLUDE_DIRS
14613 Include path(s) for MPI header.
14614 MPI_<lang>_LINK_FLAGS
14616 Linker flags for MPI programs.
14617 MPI_<lang>_LIBRARIES
14619 All libraries to link MPI programs against.
14620 New in version 3.9: Additionally, the following IMPORTED targets are
14622 defined:
14623 MPI::MPI_<lang>
14626 Target for using MPI from <lang>.
14627 The following variables indicating which bindings are present will be
14629 defined:
14630 MPI_MPICXX_FOUND
14632 Variable indicating whether the MPI-2 C++ bindings are present
14633 (introduced in MPI-2, removed with MPI-3).
14634 MPI_Fortran_HAVE_F77_HEADER
14636 True if the Fortran 77 header mpif.h is available.
14637 MPI_Fortran_HAVE_F90_MODULE
14639 True if the Fortran 90 module mpi can be used for accessing MPI
14640 (MPI-2 and higher only).
14641 MPI_Fortran_HAVE_F08_MODULE
14643 True if the Fortran 2008 mpi_f08 is available to MPI programs
14644 (MPI-3 and higher only).
14645 If possible, the MPI version will be determined by this module. The fa‐
14647 cilities to detect the MPI version were introduced with MPI-1.2, and
14648 therefore cannot be found for older MPI versions.
14649 MPI_<lang>_VERSION_MAJOR
14651 Major version of MPI implemented for <lang> by the MPI distribu‐
14652 tion.
14653 MPI_<lang>_VERSION_MINOR
14655 Minor version of MPI implemented for <lang> by the MPI distribu‐
14656 tion.
14657 MPI_<lang>_VERSION
14659 MPI version implemented for <lang> by the MPI distribution.
14660 Note that there's no variable for the C bindings being accessible
14662 through mpi.h, since the MPI standards always have required this bind‐
14663 ing to work in both C and C++ code.
14664 For running MPI programs, the module sets the following variables
14666 MPIEXEC_EXECUTABLE
14668 Executable for running MPI programs, if such exists.
14669 MPIEXEC_NUMPROC_FLAG
14671 Flag to pass to mpiexec before giving it the number of proces‐
14672 sors to run on.
14673 MPIEXEC_MAX_NUMPROCS
14675 Number of MPI processors to utilize. Defaults to the number of
14676 processors detected on the host system.
14677 MPIEXEC_PREFLAGS
14679 Flags to pass to mpiexec directly before the executable to run.
14680 MPIEXEC_POSTFLAGS
14682 Flags to pass to mpiexec after other flags.
14683 Variables for locating MPI
14685 This module performs a four step search for an MPI implementation:
14686 1. Search for MPIEXEC_EXECUTABLE and, if found, use its base directory.
14688 2. Check if the compiler has MPI support built-in. This is the case if
14690 the user passed a compiler wrapper as CMAKE_<LANG>_COMPILER or if
14691 they use Cray system compiler wrappers.
14692 3. Attempt to find an MPI compiler wrapper and determine the compiler
14694 information from it.
14695 4. Try to find an MPI implementation that does not ship such a wrapper
14697 by guessing settings. Currently, only Microsoft MPI and MPICH2 on
14698 Windows are supported.
14699 For controlling the MPIEXEC_EXECUTABLE step, the following variables
14701 may be set:
14702 MPIEXEC_EXECUTABLE
14704 Manually specify the location of mpiexec.
14705 MPI_HOME
14707 Specify the base directory of the MPI installation.
14708 ENV{MPI_HOME}
14710 Environment variable to specify the base directory of the MPI
14711 installation.
14712 ENV{I_MPI_ROOT}
14714 Environment variable to specify the base directory of the MPI
14715 installation.
14716 For controlling the compiler wrapper step, the following variables may
14718 be set:
14719 MPI_<lang>_COMPILER
14721 Search for the specified compiler wrapper and use it.
14722 MPI_<lang>_COMPILER_FLAGS
14724 Flags to pass to the MPI compiler wrapper during interrogation.
14725 Some compiler wrappers support linking debug or tracing li‐
14726 braries if a specific flag is passed and this variable may be
14727 used to obtain them.
14728 MPI_COMPILER_FLAGS
14730 Used to initialize MPI_<lang>_COMPILER_FLAGS if no language spe‐
14731 cific flag has been given. Empty by default.
14732 MPI_EXECUTABLE_SUFFIX
14734 A suffix which is appended to all names that are being looked
14735 for. For instance you may set this to .mpich or .openmpi to pre‐
14736 fer the one or the other on Debian and its derivatives.
14737 In order to control the guessing step, the following variable may be
14739 set:
14740 MPI_GUESS_LIBRARY_NAME
14742 Valid values are MSMPI and MPICH2. If set, only the given li‐
14743 brary will be searched for. By default, MSMPI will be preferred
14744 over MPICH2 if both are available. This also sets MPI_SKIP_COM‐
14745 PILER_WRAPPER to true, which may be overridden.
14746 Each of the search steps may be skipped with the following control
14748 variables:
14749 MPI_ASSUME_NO_BUILTIN_MPI
14751 If true, the module assumes that the compiler itself does not
14752 provide an MPI implementation and skips to step 2.
14753 MPI_SKIP_COMPILER_WRAPPER
14755 If true, no compiler wrapper will be searched for.
14756 MPI_SKIP_GUESSING
14758 If true, the guessing step will be skipped.
14759 Additionally, the following control variable is available to change
14761 search behavior:
14762 MPI_CXX_SKIP_MPICXX
14764 Add some definitions that will disable the MPI-2 C++ bindings.
14765 Currently supported are MPICH, Open MPI, Platform MPI and deriv‐
14766 atives thereof, for example MVAPICH or Intel MPI.
14767 If the find procedure fails for a variable MPI_<lang>_WORKS, then the
14769 settings detected by or passed to the module did not work and even a
14770 simple MPI test program failed to compile.
14771 If all of these parameters were not sufficient to find the right MPI
14773 implementation, a user may disable the entire autodetection process by
14774 specifying both a list of libraries in MPI_<lang>_LIBRARIES and a list
14775 of include directories in MPI_<lang>_ADDITIONAL_INCLUDE_DIRS. Any
14776 other variable may be set in addition to these two. The module will
14777 then validate the MPI settings and store the settings in the cache.
14778 Cache variables for MPI
14780 The variable MPI_<lang>_INCLUDE_DIRS will be assembled from the follow‐
14781 ing variables. For C and CXX:
14782 MPI_<lang>_HEADER_DIR
14784 Location of the mpi.h header on disk.
14785 For Fortran:
14787 MPI_Fortran_F77_HEADER_DIR
14789 Location of the Fortran 77 header mpif.h, if it exists.
14790 MPI_Fortran_MODULE_DIR
14792 Location of the mpi or mpi_f08 modules, if available.
14793 For all languages the following variables are additionally considered:
14795 MPI_<lang>_ADDITIONAL_INCLUDE_DIRS
14797 A ;-list of paths needed in addition to the normal include di‐
14798 rectories.
14799 MPI_<include_name>_INCLUDE_DIR
14801 Path variables for include folders referred to by <in‐
14802 clude_name>.
14803 MPI_<lang>_ADDITIONAL_INCLUDE_VARS
14805 A ;-list of <include_name> that will be added to the include lo‐
14806 cations of <lang>.
14807 The variable MPI_<lang>_LIBRARIES will be assembled from the following
14809 variables:
14810 MPI_<lib_name>_LIBRARY
14812 The location of a library called <lib_name> for use with MPI.
14813 MPI_<lang>_LIB_NAMES
14815 A ;-list of <lib_name> that will be added to the include loca‐
14816 tions of <lang>.
14817 Usage of mpiexec
14819 When using MPIEXEC_EXECUTABLE to execute MPI applications, you should
14820 typically use all of the MPIEXEC_EXECUTABLE flags as follows:
14821 ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS}
14823 ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS
14824 where EXECUTABLE is the MPI program, and ARGS are the arguments to pass
14826 to the MPI program.
14827 Advanced variables for using MPI
14829 The module can perform some advanced feature detections upon explicit
14830 request.
14831 Important notice: The following checks cannot be performed without exe‐
14833 cuting an MPI test program. Consider the special considerations for
14834 the behavior of try_run() during cross compilation. Moreover, running
14835 an MPI program can cause additional issues, like a firewall notifica‐
14836 tion on some systems. You should only enable these detections if you
14837 absolutely need the information.
14838 If the following variables are set to true, the respective search will
14840 be performed:
14841 MPI_DETERMINE_Fortran_CAPABILITIES
14843 Determine for all available Fortran bindings what the values of
14844 MPI_SUBARRAYS_SUPPORTED and MPI_ASYNC_PROTECTS_NONBLOCKING are
14845 and make their values available as MPI_Fortran_<binding>_SUBAR‐
14846 RAYS and MPI_Fortran_<binding>_ASYNCPROT, where <binding> is one
14847 of F77_HEADER, F90_MODULE and F08_MODULE.
14848 MPI_DETERMINE_LIBRARY_VERSION
14850 For each language, find the output of MPI_Get_library_version
14851 and make it available as MPI_<lang>_LIBRARY_VERSION_STRING.
14852 This information is usually tied to the runtime component of an
14853 MPI implementation and might differ depending on <lang>. Note
14854 that the return value is entirely implementation defined. This
14855 information might be used to identify the MPI vendor and for ex‐
14856 ample pick the correct one of multiple third party binaries that
14857 matches the MPI vendor.
14858 Backward Compatibility
14860 Deprecated since version 3.10.
14861 For backward compatibility with older versions of FindMPI, these vari‐
14864 ables are set:
14865 MPI_COMPILER MPI_LIBRARY MPI_EXTRA_LIBRARY
14867 MPI_COMPILE_FLAGS MPI_INCLUDE_PATH MPI_LINK_FLAGS
14868 MPI_LIBRARIES
14869 In new projects, please use the MPI_<lang>_XXX equivalents. Addition‐
14871 ally, the following variables are deprecated:
14872 MPI_<lang>_COMPILE_FLAGS
14874 Use MPI_<lang>_COMPILE_OPTIONS and MPI_<lang>_COMPILE_DEFINI‐
14875 TIONS instead.
14876 MPI_<lang>_INCLUDE_PATH
14878 For consumption use MPI_<lang>_INCLUDE_DIRS and for specifying
14879 folders use MPI_<lang>_ADDITIONAL_INCLUDE_DIRS instead.
14880 MPIEXEC
14882 Use MPIEXEC_EXECUTABLE instead.
14883 FindMsys
14885 New in version 3.21.
14886 Find MSYS, a POSIX-compatible environment that runs natively on Micro‐
14889 soft Windows
14890 FindODBC
14892 New in version 3.12.
14893 Find an Open Database Connectivity (ODBC) include directory and li‐
14896 brary.
14897 On Windows, when building with Visual Studio, this module assumes the
14899 ODBC library is provided by the available Windows SDK.
14900 On Unix, this module allows to search for ODBC library provided by
14902 unixODBC or iODBC implementations of ODBC API. This module reads hint
14903 about location of the config program:
14904 ODBC_CONFIG
14906 Location of odbc_config or iodbc-config program
14907 Otherwise, this module tries to find the config program, first from
14909 unixODBC, then from iODBC. If no config program found, this module
14910 searches for ODBC header and library in list of known locations.
14911 Imported targets
14913 This module defines the following IMPORTED targets:
14914 ODBC::ODBC
14916 Imported target for using the ODBC library, if found.
14917 Result variables
14919 ODBC_FOUND
14920 Set to true if ODBC library found, otherwise false or undefined.
14921 ODBC_INCLUDE_DIRS
14923 Paths to include directories listed in one variable for use by
14924 ODBC client. May be empty on Windows, where the include direc‐
14925 tory corresponding to the expected Windows SDK is already avail‐
14926 able in the compilation environment.
14927 ODBC_LIBRARIES
14929 Paths to libraries to linked against to use ODBC. May just a
14930 library name on Windows, where the library directory correspond‐
14931 ing to the expected Windows SDK is already available in the com‐
14932 pilation environment.
14933 ODBC_CONFIG
14935 Path to unixODBC or iODBC config program, if found or specified.
14936 Cache variables
14938 For users who wish to edit and control the module behavior, this module
14939 reads hints about search locations from the following variables:
14940 ODBC_INCLUDE_DIR
14942 Path to ODBC include directory with sql.h header.
14943 ODBC_LIBRARY
14945 Path to ODBC library to be linked.
14946 These variables should not be used directly by project code.
14948 Limitations
14950 On Windows, this module does not search for iODBC. On Unix, there is
14951 no way to prefer unixODBC over iODBC, or vice versa, other than provid‐
14952 ing the config program location using the ODBC_CONFIG. This module
14953 does not allow to search for a specific ODBC driver.
14954 FindOpenACC
14956 New in version 3.10.
14957 Detect OpenACC support by the compiler.
14960 This module can be used to detect OpenACC support in a compiler. If
14962 the compiler supports OpenACC, the flags required to compile with Ope‐
14963 nACC support are returned in variables for the different languages.
14964 Currently, only NVHPC, PGI, GNU and Cray compilers are supported.
14965 Imported Targets
14967 New in version 3.16.
14968 The module provides IMPORTED targets:
14971 OpenACC::OpenACC_<lang>
14973 Target for using OpenACC from <lang>.
14974 Variables
14976 The module defines the following variables:
14977 OpenACC_FOUND
14979 New in version 3.25.
14980 Variable indicating that OpenACC flags for at least one lan‐
14983 guages have been found.
14984 This module will set the following variables per language in your
14986 project, where <lang> is one of C, CXX, or Fortran:
14987 OpenACC_<lang>_FOUND
14989 Variable indicating if OpenACC support for <lang> was detected.
14990 OpenACC_<lang>_FLAGS
14992 OpenACC compiler flags for <lang>, separated by spaces.
14993 OpenACC_<lang>_OPTIONS
14995 New in version 3.16.
14996 OpenACC compiler flags for <lang>, as a list. Suitable for usage
14999 with target_compile_options or target_link_options.
15000 The module will also try to provide the OpenACC version variables:
15002 OpenACC_<lang>_SPEC_DATE
15004 Date of the OpenACC specification implemented by the <lang> com‐
15005 piler.
15006 OpenACC_<lang>_VERSION_MAJOR
15008 Major version of OpenACC implemented by the <lang> compiler.
15009 OpenACC_<lang>_VERSION_MINOR
15011 Minor version of OpenACC implemented by the <lang> compiler.
15012 OpenACC_<lang>_VERSION
15014 OpenACC version implemented by the <lang> compiler.
15015 The specification date is formatted as given in the OpenACC standard:
15017 yyyymm where yyyy and mm represents the year and month of the OpenACC
15018 specification implemented by the <lang> compiler.
15019 Input Variables
15021 OpenACC_ACCEL_TARGET=<target> If set, will the correct target accelera‐
15022 tor flag set to the <target> will be returned with Ope‐
15023 nACC_<lang>_FLAGS.
15024 FindOpenAL
15026 Finds Open Audio Library (OpenAL).
15027 Projects using this module should use #include "al.h" to include the
15029 OpenAL header file, not #include <AL/al.h>. The reason for this is
15030 that the latter is not entirely portable. Windows/Creative Labs does
15031 not by default put their headers in AL/ and macOS uses the convention
15032 <OpenAL/al.h>.
15033 Hints
15035 Environment variable $OPENALDIR can be used to set the prefix of OpenAL
15036 installation to be found.
15037 By default on macOS, system framework is search first. In other words,
15039 OpenAL is searched in the following order:
15040 1. System framework: /System/Library/Frameworks, whose priority can be
15042 changed via setting the CMAKE_FIND_FRAMEWORK variable.
15043 2. Environment variable $OPENALDIR.
15045 3. System paths.
15047 4. User-compiled framework: ~/Library/Frameworks.
15049 5. Manually compiled framework: /Library/Frameworks.
15051 6. Add-on package: /opt.
15053 IMPORTED Targets
15055 New in version 3.25.
15056 This module defines the IMPORTED target:
15059 OpenAL::OpenAL
15061 The OpenAL library, if found.
15062 Result Variables
15064 This module defines the following variables:
15065 OPENAL_FOUND
15067 If false, do not try to link to OpenAL
15068 OPENAL_INCLUDE_DIR
15070 OpenAL include directory
15071 OPENAL_LIBRARY
15073 Path to the OpenAL library
15074 OPENAL_VERSION_STRING
15076 Human-readable string containing the version of OpenAL
15077 FindOpenCL
15079 New in version 3.1.
15080 Finds Open Computing Language (OpenCL)
15083 New in version 3.10: Detection of OpenCL 2.1 and 2.2.
15085 IMPORTED Targets
15088 New in version 3.7.
15089 This module defines IMPORTED target OpenCL::OpenCL, if OpenCL has been
15092 found.
15093 Result Variables
15095 This module defines the following variables:
15096 OpenCL_FOUND - True if OpenCL was found
15098 OpenCL_INCLUDE_DIRS - include directories for OpenCL
15099 OpenCL_LIBRARIES - link against this library to use OpenCL
15100 OpenCL_VERSION_STRING - Highest supported OpenCL version (eg. 1.2)
15101 OpenCL_VERSION_MAJOR - The major version of the OpenCL implementation
15102 OpenCL_VERSION_MINOR - The minor version of the OpenCL implementation
15103 The module will also define two cache variables:
15105 OpenCL_INCLUDE_DIR - the OpenCL include directory
15107 OpenCL_LIBRARY - the path to the OpenCL library
15108 FindOpenGL
15110 FindModule for OpenGL and OpenGL Utility Library (GLU).
15111 Changed in version 3.2: X11 is no longer added as a dependency on
15113 Unix/Linux systems.
15114 New in version 3.10: GLVND support on Linux. See the Linux-specific
15117 section below.
15118 Optional COMPONENTS
15121 New in version 3.10.
15122 This module respects several optional COMPONENTS: EGL, GLX, and OpenGL.
15125 There are corresponding import targets for each of these flags.
15126 IMPORTED Targets
15128 New in version 3.8.
15129 This module defines the IMPORTED targets:
15132 OpenGL::GL
15134 Defined to the platform-specific OpenGL libraries if the system
15135 has OpenGL.
15136 OpenGL::GLU
15138 Defined if the system has OpenGL Utility Library (GLU).
15139 New in version 3.10: Additionally, the following GLVND-specific library
15141 targets are defined:
15142 OpenGL::OpenGL
15145 Defined to libOpenGL if the system is GLVND-based.
15146 OpenGL::GLX
15148 Defined if the system has OpenGL Extension to the X Window Sys‐
15149 tem (GLX).
15150 OpenGL::EGL
15152 Defined if the system has EGL.
15153 Result Variables
15155 This module sets the following variables:
15156 OPENGL_FOUND
15158 True, if the system has OpenGL and all components are found.
15159 OPENGL_XMESA_FOUND
15161 True, if the system has XMESA.
15162 OPENGL_GLU_FOUND
15164 True, if the system has GLU.
15165 OpenGL_OpenGL_FOUND
15167 True, if the system has an OpenGL library.
15168 OpenGL_GLX_FOUND
15170 True, if the system has GLX.
15171 OpenGL_EGL_FOUND
15173 True, if the system has EGL.
15174 OPENGL_INCLUDE_DIR
15176 Path to the OpenGL include directory.
15177 OPENGL_EGL_INCLUDE_DIRS
15179 Path to the EGL include directory.
15180 OPENGL_LIBRARIES
15182 Paths to the OpenGL library, windowing system libraries, and GLU
15183 libraries. On Linux, this assumes GLX and is never correct for
15184 EGL-based targets. Clients are encouraged to use the OpenGL::*
15185 import targets instead.
15186 New in version 3.10: Variables for GLVND-specific libraries OpenGL, EGL
15188 and GLX.
15189 Cache variables
15192 The following cache variables may also be set:
15193 OPENGL_egl_LIBRARY
15195 Path to the EGL library.
15196 OPENGL_glu_LIBRARY
15198 Path to the GLU library.
15199 OPENGL_glx_LIBRARY
15201 Path to the GLVND 'GLX' library.
15202 OPENGL_opengl_LIBRARY
15204 Path to the GLVND 'OpenGL' library
15205 OPENGL_gl_LIBRARY
15207 Path to the OpenGL library. New code should prefer the
15208 OpenGL::* import targets.
15209 New in version 3.10: Variables for GLVND-specific libraries OpenGL, EGL
15211 and GLX.
15212 Linux-specific
15215 Some Linux systems utilize GLVND as a new ABI for OpenGL. GLVND sepa‐
15216 rates context libraries from OpenGL itself; OpenGL lives in "li‐
15217 bOpenGL", and contexts are defined in "libGLX" or "libEGL". GLVND is
15218 currently the only way to get OpenGL 3+ functionality via EGL in a man‐
15219 ner portable across vendors. Projects may use GLVND explicitly with
15220 target OpenGL::OpenGL and either OpenGL::GLX or OpenGL::EGL.
15221 Projects may use the OpenGL::GL target (or OPENGL_LIBRARIES variable)
15223 to use legacy GL interfaces. These will use the legacy GL library lo‐
15224 cated by OPENGL_gl_LIBRARY, if available. If OPENGL_gl_LIBRARY is
15225 empty or not found and GLVND is available, the OpenGL::GL target will
15226 use GLVND OpenGL::OpenGL and OpenGL::GLX (and the OPENGL_LIBRARIES
15227 variable will use the corresponding libraries). Thus, for
15228 non-EGL-based Linux targets, the OpenGL::GL target is most portable.
15229 A OpenGL_GL_PREFERENCE variable may be set to specify the preferred way
15231 to provide legacy GL interfaces in case multiple choices are available.
15232 The value may be one of:
15233 GLVND If the GLVND OpenGL and GLX libraries are available, prefer
15235 them. This forces OPENGL_gl_LIBRARY to be empty.
15236 Changed in version 3.11: This is the default, unless policy
15238 CMP0072 is set to OLD and no components are requeted (since com‐
15239 ponents correspond to GLVND libraries).
15240 LEGACY Prefer to use the legacy libGL library, if available.
15243 For EGL targets the client must rely on GLVND support on the user's
15245 system. Linking should use the OpenGL::OpenGL OpenGL::EGL targets.
15246 Using GLES* libraries is theoretically possible in place of
15247 OpenGL::OpenGL, but this module does not currently support that; con‐
15248 tributions welcome.
15249 OPENGL_egl_LIBRARY and OPENGL_EGL_INCLUDE_DIRS are defined in the case
15251 of GLVND. For non-GLVND Linux and other systems these are left unde‐
15252 fined.
15253 macOS-Specific
15255 On OSX FindOpenGL defaults to using the framework version of OpenGL.
15256 People will have to change the cache values of OPENGL_glu_LIBRARY and
15257 OPENGL_gl_LIBRARY to use OpenGL with X11 on OSX.
15258 FindOpenMP
15260 Finds Open Multi-Processing (OpenMP) support.
15261 This module can be used to detect OpenMP support in a compiler. If the
15263 compiler supports OpenMP, the flags required to compile with OpenMP
15264 support are returned in variables for the different languages. The
15265 variables may be empty if the compiler does not need a special flag to
15266 support OpenMP.
15267 New in version 3.5: Clang support.
15269 Variables
15272 New in version 3.10: The module exposes the components C, CXX, and For‐
15273 tran. Each of these controls the various languages to search OpenMP
15274 support for.
15275 Depending on the enabled components the following variables will be
15278 set:
15279 OpenMP_FOUND
15281 Variable indicating that OpenMP flags for all requested lan‐
15282 guages have been found. If no components are specified, this is
15283 true if OpenMP settings for all enabled languages were detected.
15284 OpenMP_VERSION
15286 Minimal version of the OpenMP standard detected among the re‐
15287 quested languages, or all enabled languages if no components
15288 were specified.
15289 This module will set the following variables per language in your
15291 project, where <lang> is one of C, CXX, or Fortran:
15292 OpenMP_<lang>_FOUND
15294 Variable indicating if OpenMP support for <lang> was detected.
15295 OpenMP_<lang>_FLAGS
15297 OpenMP compiler flags for <lang>, separated by spaces.
15298 OpenMP_<lang>_INCLUDE_DIRS
15300 Directories that must be added to the header search path for
15301 <lang> when using OpenMP.
15302 For linking with OpenMP code written in <lang>, the following variables
15304 are provided:
15305 OpenMP_<lang>_LIB_NAMES
15307 ;-list of libraries for OpenMP programs for <lang>.
15308 OpenMP_<libname>_LIBRARY
15310 Location of the individual libraries needed for OpenMP support
15311 in <lang>.
15312 OpenMP_<lang>_LIBRARIES
15314 A list of libraries needed to link with OpenMP code written in
15315 <lang>.
15316 Additionally, the module provides IMPORTED targets:
15318 OpenMP::OpenMP_<lang>
15320 Target for using OpenMP from <lang>.
15321 Specifically for Fortran, the module sets the following variables:
15323 OpenMP_Fortran_HAVE_OMPLIB_HEADER
15325 Boolean indicating if OpenMP is accessible through omp_lib.h.
15326 OpenMP_Fortran_HAVE_OMPLIB_MODULE
15328 Boolean indicating if OpenMP is accessible through the omp_lib
15329 Fortran module.
15330 The module will also try to provide the OpenMP version variables:
15332 OpenMP_<lang>_SPEC_DATE
15334 New in version 3.7.
15335 Date of the OpenMP specification implemented by the <lang> com‐
15338 piler.
15339 OpenMP_<lang>_VERSION_MAJOR
15341 Major version of OpenMP implemented by the <lang> compiler.
15342 OpenMP_<lang>_VERSION_MINOR
15344 Minor version of OpenMP implemented by the <lang> compiler.
15345 OpenMP_<lang>_VERSION
15347 OpenMP version implemented by the <lang> compiler.
15348 The specification date is formatted as given in the OpenMP standard:
15350 yyyymm where yyyy and mm represents the year and month of the OpenMP
15351 specification implemented by the <lang> compiler.
15352 For some compilers, it may be necessary to add a header search path to
15354 find the relevant OpenMP headers. This location may be language-spe‐
15355 cific. Where this is needed, the module may attempt to find the loca‐
15356 tion, but it can be provided directly by setting the OpenMP_<lang>_IN‐
15357 CLUDE_DIR cache variable. Note that this variable is an _input_ con‐
15358 trol to the module. Project code should use the OpenMP_<lang>_IN‐
15359 CLUDE_DIRS _output_ variable if it needs to know what include directo‐
15360 ries are needed.
15361 FindOpenSceneGraph
15363 Find OpenSceneGraph (3D graphics application programming interface)
15364 This module searches for the OpenSceneGraph core "osg" library as well
15366 as FindOpenThreads, and whatever additional COMPONENTS (nodekits) that
15367 you specify.
15368 See http://www.openscenegraph.org
15370 NOTE: To use this module effectively you must either require CMake >=
15372 2.6.3 with cmake_minimum_required(VERSION 2.6.3) or download and place
15373 FindOpenThreads, Findosg functions, Findosg and Find<etc>.cmake files
15374 into your CMAKE_MODULE_PATH.
15375 ----
15378 This module accepts the following variables (note mixed case)
15382 OpenSceneGraph_DEBUG - Enable debugging output
15384 OpenSceneGraph_MARK_AS_ADVANCED - Mark cache variables as advanced
15386 automatically
15387 The following environment variables are also respected for finding the
15389 OSG and it's various components. CMAKE_PREFIX_PATH can also be used
15390 for this (see find_library() CMake documentation).
15391 <MODULE>_DIR
15393 (where MODULE is of the form "OSGVOLUME" and there is a
15394 FindosgVolume.cmake` file)
15395 OSG_DIR
15397 OSGDIR
15399 OSG_ROOT
15401 [CMake 2.8.10]: The CMake variable OSG_DIR can now be used as well to
15403 influence detection, instead of needing to specify an environment vari‐
15404 able.
15405 This module defines the following output variables:
15407 OPENSCENEGRAPH_FOUND - Was the OSG and all of the specified components found?
15409 OPENSCENEGRAPH_VERSION - The version of the OSG which was found
15411 OPENSCENEGRAPH_INCLUDE_DIRS - Where to find the headers
15413 OPENSCENEGRAPH_LIBRARIES - The OSG libraries
15415 ================================== Example Usage:
15417 find_package(OpenSceneGraph 2.0.0 REQUIRED osgDB osgUtil)
15419 # libOpenThreads & libosg automatically searched
15420 include_directories(${OPENSCENEGRAPH_INCLUDE_DIRS})
15421 add_executable(foo foo.cc)
15423 target_link_libraries(foo ${OPENSCENEGRAPH_LIBRARIES})
15424 FindOpenSP
15426 New in version 3.25.
15427 Try to find the OpenSP library.
15430 Result Variables
15432 This will define the following variables:
15433 OpenSP_FOUND
15435 True if (the requested version of) OpenSP is available
15436 OpenSP_VERSION
15438 The version of OpenSP
15439 OpenSP_VERSION_MAJOR
15441 The major version of OpenSP
15442 OpenSP_VERSION_MINOR
15444 The minor version of OpenSP
15445 OpenSP_VERSION_PATCH
15447 The patch version of OpenSP
15448 OpenSP_INCLUDE_DIRS
15450 The include dirs of OpenSP with its headers
15451 OpenSP_LIBRARIES
15453 The OpenSP library for use with target_link_libraries(). This
15454 can be passed to target_link_libraries() instead of the IMPORTED
15455 OpenSP::OpenSP target
15456 OpenSP_MULTI_BYTE
15458 True if SP_MULTI_BYTE was found to be defined in OpenSP's con‐
15459 fig.h header file, which indicates that the OpenSP library was
15460 compiled with support for multi-byte characters. The consuming
15461 target needs to define the SP_MULTI_BYTE to match this value in
15462 order to avoid issues with character decoding.
15463 IMPORTED Targets
15465 This module defines the IMPORTED target OpenSP::OpenSP, if OpenSP has
15466 been found.
15467 Cache variables
15469 The following cache variables may also be set:
15470 OpenSP_INCLUDE_DIR
15472 the OpenSP include directory
15473 OpenSP_LIBRARY
15475 the absolute path of the osp library
15476 FindOpenSSL
15478 Find the OpenSSL encryption library.
15479 This module finds an installed OpenSSL library and determines its ver‐
15481 sion.
15482 New in version 3.19: When a version is requested, it can be specified
15484 as a simple value or as a range. For a detailed description of version
15485 range usage and capabilities, refer to the find_package() command.
15486 New in version 3.18: Support for OpenSSL 3.0.
15489 Optional COMPONENTS
15492 New in version 3.12.
15493 This module supports two optional COMPONENTS: Crypto and SSL. Both
15496 components have associated imported targets, as described below.
15497 Imported Targets
15499 New in version 3.4.
15500 This module defines the following IMPORTED targets:
15503 OpenSSL::SSL
15505 The OpenSSL ssl library, if found.
15506 OpenSSL::Crypto
15508 The OpenSSL crypto library, if found.
15509 OpenSSL::applink
15511 New in version 3.18.
15512 The OpenSSL applink components that might be need to be compiled
15515 into projects under MSVC. This target is available only if found
15516 OpenSSL version is not less than 0.9.8. By linking this target
15517 the above OpenSSL targets can be linked even if the project has
15518 different MSVC runtime configurations with the above OpenSSL
15519 targets. This target has no effect on platforms other than MSVC.
15520 NOTE: Due to how INTERFACE_SOURCES are consumed by the consuming tar‐
15522 get, unless you certainly know what you are doing, it is always pre‐
15523 ferred to link OpenSSL::applink target as PRIVATE and to make sure that
15524 this target is linked at most once for the whole dependency graph of
15525 any library or executable:
15526 target_link_libraries(myTarget PRIVATE OpenSSL::applink)
15528 Otherwise you would probably encounter unexpected random problems when
15530 building and linking, as both the ISO C and the ISO C++ standard claims
15531 almost nothing about what a link process should be.
15532 Result Variables
15534 This module will set the following variables in your project:
15535 OPENSSL_FOUND
15537 System has the OpenSSL library. If no components are requested
15538 it only requires the crypto library.
15539 OPENSSL_INCLUDE_DIR
15541 The OpenSSL include directory.
15542 OPENSSL_CRYPTO_LIBRARY
15544 The OpenSSL crypto library.
15545 OPENSSL_CRYPTO_LIBRARIES
15547 The OpenSSL crypto library and its dependencies.
15548 OPENSSL_SSL_LIBRARY
15550 The OpenSSL SSL library.
15551 OPENSSL_SSL_LIBRARIES
15553 The OpenSSL SSL library and its dependencies.
15554 OPENSSL_LIBRARIES
15556 All OpenSSL libraries and their dependencies.
15557 OPENSSL_VERSION
15559 This is set to $major.$minor.$revision$patch (e.g. 0.9.8s).
15560 OPENSSL_APPLINK_SOURCE
15562 The sources in the target OpenSSL::applink that is mentioned
15563 above. This variable shall always be undefined if found openssl
15564 version is less than 0.9.8 or if platform is not MSVC.
15565 Hints
15567 The following variables may be set to control search behavior:
15568 OPENSSL_ROOT_DIR
15570 Set to the root directory of an OpenSSL installation.
15571 OPENSSL_USE_STATIC_LIBS
15573 New in version 3.4.
15574 Set to TRUE to look for static libraries.
15577 OPENSSL_MSVC_STATIC_RT
15579 New in version 3.5.
15580 Set to TRUE to choose the MT version of the lib.
15583 ENV{PKG_CONFIG_PATH}
15585 On UNIX-like systems, pkg-config is used to locate the system
15586 OpenSSL. Set the PKG_CONFIG_PATH environment varialbe to look
15587 in alternate locations. Useful on multi-lib systems.
15588 FindOpenThreads
15590 OpenThreads is a C++ based threading library. Its largest userbase
15591 seems to OpenSceneGraph so you might notice I accept OSGDIR as an envi‐
15592 ronment path. I consider this part of the Findosg* suite used to find
15593 OpenSceneGraph components. Each component is separate and you must opt
15594 in to each module.
15595 Locate OpenThreads This module defines OPENTHREADS_LIBRARY
15597 OPENTHREADS_FOUND, if false, do not try to link to OpenThreads
15598 OPENTHREADS_INCLUDE_DIR, where to find the headers
15599 $OPENTHREADS_DIR is an environment variable that would correspond to
15601 the ./configure --prefix=$OPENTHREADS_DIR used in building osg.
15602 [CMake 2.8.10]: The CMake variables OPENTHREADS_DIR or OSG_DIR can now
15604 be used as well to influence detection, instead of needing to specify
15605 an environment variable.
15606 Created by Eric Wing.
15608 Findosg
15610 NOTE: It is highly recommended that you use the new FindOpenScene‐
15611 Graph.cmake introduced in CMake 2.6.3 and not use this Find module di‐
15612 rectly.
15613 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15615 nents. Each component is separate and you must opt in to each module.
15616 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15617 as these modules won't do it for you. This is to allow you control
15618 over your own system piece by piece in case you need to opt out of cer‐
15619 tain components or change the Find behavior for a particular module
15620 (perhaps because the default FindOpenGL.cmake module doesn't work with
15621 your system as an example). If you want to use a more convenient mod‐
15622 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15623 of the Findosg*.cmake modules.
15624 Locate osg This module defines
15626 OSG_FOUND - Was the Osg found? OSG_INCLUDE_DIR - Where to find the
15628 headers OSG_LIBRARIES - The libraries to link against for the OSG (use
15629 this)
15630 OSG_LIBRARY - The OSG library OSG_LIBRARY_DEBUG - The OSG debug library
15632 $OSGDIR is an environment variable that would correspond to the ./con‐
15634 figure --prefix=$OSGDIR used in building osg.
15635 Created by Eric Wing.
15637 Findosg_functions
15639 This CMake file contains two macros to assist with searching for OSG
15640 libraries and nodekits. Please see FindOpenSceneGraph.cmake for full
15641 documentation.
15642 FindosgAnimation
15644 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15645 nents. Each component is separate and you must opt in to each module.
15646 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15647 as these modules won't do it for you. This is to allow you control
15648 over your own system piece by piece in case you need to opt out of cer‐
15649 tain components or change the Find behavior for a particular module
15650 (perhaps because the default FindOpenGL.cmake module doesn't work with
15651 your system as an example). If you want to use a more convenient mod‐
15652 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15653 of the Findosg*.cmake modules.
15654 Locate osgAnimation This module defines
15656 OSGANIMATION_FOUND - Was osgAnimation found? OSGANIMATION_INCLUDE_DIR -
15658 Where to find the headers OSGANIMATION_LIBRARIES - The libraries to
15659 link against for the OSG (use this)
15660 OSGANIMATION_LIBRARY - The OSG library OSGANIMATION_LIBRARY_DEBUG - The
15662 OSG debug library
15663 $OSGDIR is an environment variable that would correspond to the ./con‐
15665 figure --prefix=$OSGDIR used in building osg.
15666 Created by Eric Wing.
15668 FindosgDB
15670 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15671 nents. Each component is separate and you must opt in to each module.
15672 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15673 as these modules won't do it for you. This is to allow you control
15674 over your own system piece by piece in case you need to opt out of cer‐
15675 tain components or change the Find behavior for a particular module
15676 (perhaps because the default FindOpenGL module doesn't work with your
15677 system as an example). If you want to use a more convenient module
15678 that includes everything, use the FindOpenSceneGraph instead of the
15679 Findosg*.cmake modules.
15680 Locate osgDB This module defines:
15682 OSGDB_FOUND
15684 Was osgDB found?
15685 OSGDB_INCLUDE_DIR
15687 Where to find the headers
15688 OSGDB_LIBRARIES
15690 The libraries to link against for the osgDB
15691 OSGDB_LIBRARY
15693 The osgDB library
15694 OSGDB_LIBRARY_DEBUG
15696 The osgDB debug library
15697 $OSGDIR is an environment variable that would correspond to:
15699 ./configure --prefix=$OSGDIR used in building osg.
15701 FindosgFX
15703 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15704 nents. Each component is separate and you must opt in to each module.
15705 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15706 as these modules won't do it for you. This is to allow you control
15707 over your own system piece by piece in case you need to opt out of cer‐
15708 tain components or change the Find behavior for a particular module
15709 (perhaps because the default FindOpenGL.cmake module doesn't work with
15710 your system as an example). If you want to use a more convenient mod‐
15711 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15712 of the Findosg*.cmake modules.
15713 Locate osgFX This module defines
15715 OSGFX_FOUND - Was osgFX found? OSGFX_INCLUDE_DIR - Where to find the
15717 headers OSGFX_LIBRARIES - The libraries to link against for the osgFX
15718 (use this)
15719 OSGFX_LIBRARY - The osgFX library OSGFX_LIBRARY_DEBUG - The osgFX debug
15721 library
15722 $OSGDIR is an environment variable that would correspond to the ./con‐
15724 figure --prefix=$OSGDIR used in building osg.
15725 Created by Eric Wing.
15727 FindosgGA
15729 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15730 nents. Each component is separate and you must opt in to each module.
15731 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15732 as these modules won't do it for you. This is to allow you control
15733 over your own system piece by piece in case you need to opt out of cer‐
15734 tain components or change the Find behavior for a particular module
15735 (perhaps because the default FindOpenGL.cmake module doesn't work with
15736 your system as an example). If you want to use a more convenient mod‐
15737 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15738 of the Findosg*.cmake modules.
15739 Locate osgGA This module defines
15741 OSGGA_FOUND - Was osgGA found? OSGGA_INCLUDE_DIR - Where to find the
15743 headers OSGGA_LIBRARIES - The libraries to link against for the osgGA
15744 (use this)
15745 OSGGA_LIBRARY - The osgGA library OSGGA_LIBRARY_DEBUG - The osgGA debug
15747 library
15748 $OSGDIR is an environment variable that would correspond to the ./con‐
15750 figure --prefix=$OSGDIR used in building osg.
15751 Created by Eric Wing.
15753 FindosgIntrospection
15755 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15756 nents. Each component is separate and you must opt in to each module.
15757 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15758 as these modules won't do it for you. This is to allow you control
15759 over your own system piece by piece in case you need to opt out of cer‐
15760 tain components or change the Find behavior for a particular module
15761 (perhaps because the default FindOpenGL.cmake module doesn't work with
15762 your system as an example). If you want to use a more convenient mod‐
15763 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15764 of the Findosg*.cmake modules.
15765 Locate osgINTROSPECTION This module defines
15767 OSGINTROSPECTION_FOUND - Was osgIntrospection found? OSGINTROSPEC‐
15769 TION_INCLUDE_DIR - Where to find the headers OSGINTROSPECTION_LIBRARIES
15770 - The libraries to link for osgIntrospection (use this)
15771 OSGINTROSPECTION_LIBRARY - The osgIntrospection library OSGINTROSPEC‐
15773 TION_LIBRARY_DEBUG - The osgIntrospection debug library
15774 $OSGDIR is an environment variable that would correspond to the ./con‐
15776 figure --prefix=$OSGDIR used in building osg.
15777 Created by Eric Wing.
15779 FindosgManipulator
15781 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15782 nents. Each component is separate and you must opt in to each module.
15783 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15784 as these modules won't do it for you. This is to allow you control
15785 over your own system piece by piece in case you need to opt out of cer‐
15786 tain components or change the Find behavior for a particular module
15787 (perhaps because the default FindOpenGL.cmake module doesn't work with
15788 your system as an example). If you want to use a more convenient mod‐
15789 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15790 of the Findosg*.cmake modules.
15791 Locate osgManipulator This module defines
15793 OSGMANIPULATOR_FOUND - Was osgManipulator found? OSGMANIPULATOR_IN‐
15795 CLUDE_DIR - Where to find the headers OSGMANIPULATOR_LIBRARIES - The
15796 libraries to link for osgManipulator (use this)
15797 OSGMANIPULATOR_LIBRARY - The osgManipulator library OSGMANIPULATOR_LI‐
15799 BRARY_DEBUG - The osgManipulator debug library
15800 $OSGDIR is an environment variable that would correspond to the ./con‐
15802 figure --prefix=$OSGDIR used in building osg.
15803 Created by Eric Wing.
15805 FindosgParticle
15807 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15808 nents. Each component is separate and you must opt in to each module.
15809 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15810 as these modules won't do it for you. This is to allow you control
15811 over your own system piece by piece in case you need to opt out of cer‐
15812 tain components or change the Find behavior for a particular module
15813 (perhaps because the default FindOpenGL.cmake module doesn't work with
15814 your system as an example). If you want to use a more convenient mod‐
15815 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15816 of the Findosg*.cmake modules.
15817 Locate osgParticle This module defines
15819 OSGPARTICLE_FOUND - Was osgParticle found? OSGPARTICLE_INCLUDE_DIR -
15821 Where to find the headers OSGPARTICLE_LIBRARIES - The libraries to link
15822 for osgParticle (use this)
15823 OSGPARTICLE_LIBRARY - The osgParticle library OSGPARTICLE_LIBRARY_DEBUG
15825 - The osgParticle debug library
15826 $OSGDIR is an environment variable that would correspond to the ./con‐
15828 figure --prefix=$OSGDIR used in building osg.
15829 Created by Eric Wing.
15831 FindosgPresentation
15833 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15834 nents. Each component is separate and you must opt in to each module.
15835 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15836 as these modules won't do it for you. This is to allow you control
15837 over your own system piece by piece in case you need to opt out of cer‐
15838 tain components or change the Find behavior for a particular module
15839 (perhaps because the default FindOpenGL.cmake module doesn't work with
15840 your system as an example). If you want to use a more convenient mod‐
15841 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15842 of the Findosg*.cmake modules.
15843 Locate osgPresentation This module defines
15845 OSGPRESENTATION_FOUND - Was osgPresentation found? OSGPRESENTATION_IN‐
15847 CLUDE_DIR - Where to find the headers OSGPRESENTATION_LIBRARIES - The
15848 libraries to link for osgPresentation (use this)
15849 OSGPRESENTATION_LIBRARY - The osgPresentation library OSGPRESENTA‐
15851 TION_LIBRARY_DEBUG - The osgPresentation debug library
15852 $OSGDIR is an environment variable that would correspond to the ./con‐
15854 figure --prefix=$OSGDIR used in building osg.
15855 Created by Eric Wing. Modified to work with osgPresentation by Robert
15857 Osfield, January 2012.
15858 FindosgProducer
15860 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15861 nents. Each component is separate and you must opt in to each module.
15862 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15863 as these modules won't do it for you. This is to allow you control
15864 over your own system piece by piece in case you need to opt out of cer‐
15865 tain components or change the Find behavior for a particular module
15866 (perhaps because the default FindOpenGL.cmake module doesn't work with
15867 your system as an example). If you want to use a more convenient mod‐
15868 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15869 of the Findosg*.cmake modules.
15870 Locate osgProducer This module defines
15872 OSGPRODUCER_FOUND - Was osgProducer found? OSGPRODUCER_INCLUDE_DIR -
15874 Where to find the headers OSGPRODUCER_LIBRARIES - The libraries to link
15875 for osgProducer (use this)
15876 OSGPRODUCER_LIBRARY - The osgProducer library OSGPRODUCER_LIBRARY_DEBUG
15878 - The osgProducer debug library
15879 $OSGDIR is an environment variable that would correspond to the ./con‐
15881 figure --prefix=$OSGDIR used in building osg.
15882 Created by Eric Wing.
15884 FindosgQt
15886 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15887 nents. Each component is separate and you must opt in to each module.
15888 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15889 as these modules won't do it for you. This is to allow you control
15890 over your own system piece by piece in case you need to opt out of cer‐
15891 tain components or change the Find behavior for a particular module
15892 (perhaps because the default FindOpenGL.cmake module doesn't work with
15893 your system as an example). If you want to use a more convenient mod‐
15894 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15895 of the Findosg*.cmake modules.
15896 Locate osgQt This module defines
15898 OSGQT_FOUND - Was osgQt found? OSGQT_INCLUDE_DIR - Where to find the
15900 headers OSGQT_LIBRARIES - The libraries to link for osgQt (use this)
15901 OSGQT_LIBRARY - The osgQt library OSGQT_LIBRARY_DEBUG - The osgQt debug
15903 library
15904 $OSGDIR is an environment variable that would correspond to the ./con‐
15906 figure --prefix=$OSGDIR used in building osg.
15907 Created by Eric Wing. Modified to work with osgQt by Robert Osfield,
15909 January 2012.
15910 FindosgShadow
15912 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15913 nents. Each component is separate and you must opt in to each module.
15914 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15915 as these modules won't do it for you. This is to allow you control
15916 over your own system piece by piece in case you need to opt out of cer‐
15917 tain components or change the Find behavior for a particular module
15918 (perhaps because the default FindOpenGL.cmake module doesn't work with
15919 your system as an example). If you want to use a more convenient mod‐
15920 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15921 of the Findosg*.cmake modules.
15922 Locate osgShadow This module defines
15924 OSGSHADOW_FOUND - Was osgShadow found? OSGSHADOW_INCLUDE_DIR - Where to
15926 find the headers OSGSHADOW_LIBRARIES - The libraries to link for os‐
15927 gShadow (use this)
15928 OSGSHADOW_LIBRARY - The osgShadow library OSGSHADOW_LIBRARY_DEBUG - The
15930 osgShadow debug library
15931 $OSGDIR is an environment variable that would correspond to the ./con‐
15933 figure --prefix=$OSGDIR used in building osg.
15934 Created by Eric Wing.
15936 FindosgSim
15938 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15939 nents. Each component is separate and you must opt in to each module.
15940 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15941 as these modules won't do it for you. This is to allow you control
15942 over your own system piece by piece in case you need to opt out of cer‐
15943 tain components or change the Find behavior for a particular module
15944 (perhaps because the default FindOpenGL.cmake module doesn't work with
15945 your system as an example). If you want to use a more convenient mod‐
15946 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15947 of the Findosg*.cmake modules.
15948 Locate osgSim This module defines
15950 OSGSIM_FOUND - Was osgSim found? OSGSIM_INCLUDE_DIR - Where to find the
15952 headers OSGSIM_LIBRARIES - The libraries to link for osgSim (use this)
15953 OSGSIM_LIBRARY - The osgSim library OSGSIM_LIBRARY_DEBUG - The osgSim
15955 debug library
15956 $OSGDIR is an environment variable that would correspond to the ./con‐
15958 figure --prefix=$OSGDIR used in building osg.
15959 Created by Eric Wing.
15961 FindosgTerrain
15963 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15964 nents. Each component is separate and you must opt in to each module.
15965 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15966 as these modules won't do it for you. This is to allow you control
15967 over your own system piece by piece in case you need to opt out of cer‐
15968 tain components or change the Find behavior for a particular module
15969 (perhaps because the default FindOpenGL.cmake module doesn't work with
15970 your system as an example). If you want to use a more convenient mod‐
15971 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15972 of the Findosg*.cmake modules.
15973 Locate osgTerrain This module defines
15975 OSGTERRAIN_FOUND - Was osgTerrain found? OSGTERRAIN_INCLUDE_DIR - Where
15977 to find the headers OSGTERRAIN_LIBRARIES - The libraries to link for
15978 osgTerrain (use this)
15979 OSGTERRAIN_LIBRARY - The osgTerrain library OSGTERRAIN_LIBRARY_DEBUG -
15981 The osgTerrain debug library
15982 $OSGDIR is an environment variable that would correspond to the ./con‐
15984 figure --prefix=$OSGDIR used in building osg.
15985 Created by Eric Wing.
15987 FindosgText
15989 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15990 nents. Each component is separate and you must opt in to each module.
15991 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15992 as these modules won't do it for you. This is to allow you control
15993 over your own system piece by piece in case you need to opt out of cer‐
15994 tain components or change the Find behavior for a particular module
15995 (perhaps because the default FindOpenGL.cmake module doesn't work with
15996 your system as an example). If you want to use a more convenient mod‐
15997 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15998 of the Findosg*.cmake modules.
15999 Locate osgText This module defines
16001 OSGTEXT_FOUND - Was osgText found? OSGTEXT_INCLUDE_DIR - Where to find
16003 the headers OSGTEXT_LIBRARIES - The libraries to link for osgText (use
16004 this)
16005 OSGTEXT_LIBRARY - The osgText library OSGTEXT_LIBRARY_DEBUG - The osg‐
16007 Text debug library
16008 $OSGDIR is an environment variable that would correspond to the ./con‐
16010 figure --prefix=$OSGDIR used in building osg.
16011 Created by Eric Wing.
16013 FindosgUtil
16015 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16016 nents. Each component is separate and you must opt in to each module.
16017 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16018 as these modules won't do it for you. This is to allow you control
16019 over your own system piece by piece in case you need to opt out of cer‐
16020 tain components or change the Find behavior for a particular module
16021 (perhaps because the default FindOpenGL.cmake module doesn't work with
16022 your system as an example). If you want to use a more convenient mod‐
16023 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16024 of the Findosg*.cmake modules.
16025 Locate osgUtil This module defines
16027 OSGUTIL_FOUND - Was osgUtil found? OSGUTIL_INCLUDE_DIR - Where to find
16029 the headers OSGUTIL_LIBRARIES - The libraries to link for osgUtil (use
16030 this)
16031 OSGUTIL_LIBRARY - The osgUtil library OSGUTIL_LIBRARY_DEBUG - The
16033 osgUtil debug library
16034 $OSGDIR is an environment variable that would correspond to the ./con‐
16036 figure --prefix=$OSGDIR used in building osg.
16037 Created by Eric Wing.
16039 FindosgViewer
16041 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16042 nents. Each component is separate and you must opt in to each module.
16043 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16044 as these modules won't do it for you. This is to allow you control
16045 over your own system piece by piece in case you need to opt out of cer‐
16046 tain components or change the Find behavior for a particular module
16047 (perhaps because the default FindOpenGL.cmake module doesn't work with
16048 your system as an example). If you want to use a more convenient mod‐
16049 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16050 of the Findosg*.cmake modules.
16051 Locate osgViewer This module defines
16053 OSGVIEWER_FOUND - Was osgViewer found? OSGVIEWER_INCLUDE_DIR - Where to
16055 find the headers OSGVIEWER_LIBRARIES - The libraries to link for os‐
16056 gViewer (use this)
16057 OSGVIEWER_LIBRARY - The osgViewer library OSGVIEWER_LIBRARY_DEBUG - The
16059 osgViewer debug library
16060 $OSGDIR is an environment variable that would correspond to the ./con‐
16062 figure --prefix=$OSGDIR used in building osg.
16063 Created by Eric Wing.
16065 FindosgVolume
16067 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16068 nents. Each component is separate and you must opt in to each module.
16069 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16070 as these modules won't do it for you. This is to allow you control
16071 over your own system piece by piece in case you need to opt out of cer‐
16072 tain components or change the Find behavior for a particular module
16073 (perhaps because the default FindOpenGL.cmake module doesn't work with
16074 your system as an example). If you want to use a more convenient mod‐
16075 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16076 of the Findosg*.cmake modules.
16077 Locate osgVolume This module defines
16079 OSGVOLUME_FOUND - Was osgVolume found? OSGVOLUME_INCLUDE_DIR - Where to
16081 find the headers OSGVOLUME_LIBRARIES - The libraries to link for os‐
16082 gVolume (use this)
16083 OSGVOLUME_LIBRARY - The osgVolume library OSGVOLUME_LIBRARY_DEBUG - The
16085 osgVolume debug library
16086 $OSGDIR is an environment variable that would correspond to the ./con‐
16088 figure --prefix=$OSGDIR used in building osg.
16089 Created by Eric Wing.
16091 FindosgWidget
16093 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
16094 nents. Each component is separate and you must opt in to each module.
16095 You must also opt into OpenGL and OpenThreads (and Producer if needed)
16096 as these modules won't do it for you. This is to allow you control
16097 over your own system piece by piece in case you need to opt out of cer‐
16098 tain components or change the Find behavior for a particular module
16099 (perhaps because the default FindOpenGL.cmake module doesn't work with
16100 your system as an example). If you want to use a more convenient mod‐
16101 ule that includes everything, use the FindOpenSceneGraph.cmake instead
16102 of the Findosg*.cmake modules.
16103 Locate osgWidget This module defines
16105 OSGWIDGET_FOUND - Was osgWidget found? OSGWIDGET_INCLUDE_DIR - Where to
16107 find the headers OSGWIDGET_LIBRARIES - The libraries to link for osg‐
16108 Widget (use this)
16109 OSGWIDGET_LIBRARY - The osgWidget library OSGWIDGET_LIBRARY_DEBUG - The
16111 osgWidget debug library
16112 $OSGDIR is an environment variable that would correspond to the ./con‐
16114 figure --prefix=$OSGDIR used in building osg.
16115 FindosgWidget.cmake tweaked from Findosg* suite as created by Eric
16117 Wing.
16118 FindPatch
16120 New in version 3.10.
16121 The module defines the following variables:
16124 Patch_EXECUTABLE
16126 Path to patch command-line executable.
16127 Patch_FOUND
16129 True if the patch command-line executable was found.
16130 The following IMPORTED targets are also defined:
16132 Patch::patch
16134 The command-line executable.
16135 Example usage:
16137 find_package(Patch)
16139 if(Patch_FOUND)
16140 message("Patch found: ${Patch_EXECUTABLE}")
16141 endif()
16142 FindPerl
16144 Find perl
16145 this module looks for Perl
16147 PERL_EXECUTABLE - the full path to perl
16149 PERL_FOUND - If false, don't attempt to use perl.
16150 PERL_VERSION_STRING - version of perl found (since CMake 2.8.8)
16151 FindPerlLibs
16153 Find Perl libraries
16154 This module finds if PERL is installed and determines where the include
16156 files and libraries are. It also determines what the name of the li‐
16157 brary is. This code sets the following variables:
16158 PERLLIBS_FOUND = True if perl.h & libperl were found
16160 PERL_INCLUDE_PATH = path to where perl.h is found
16161 PERL_LIBRARY = path to libperl
16162 PERL_EXECUTABLE = full path to the perl binary
16163 The minimum required version of Perl can be specified using the stan‐
16165 dard syntax, e.g. find_package(PerlLibs 6.0)
16166 The following variables are also available if needed
16168 (introduced after CMake 2.6.4)
16169 PERL_SITESEARCH = path to the sitesearch install dir (-V:installsitesearch)
16171 PERL_SITEARCH = path to the sitelib install directory (-V:installsitearch)
16172 PERL_SITELIB = path to the sitelib install directory (-V:installsitelib)
16173 PERL_VENDORARCH = path to the vendor arch install directory (-V:installvendorarch)
16174 PERL_VENDORLIB = path to the vendor lib install directory (-V:installvendorlib)
16175 PERL_ARCHLIB = path to the core arch lib install directory (-V:archlib)
16176 PERL_PRIVLIB = path to the core priv lib install directory (-V:privlib)
16177 PERL_UPDATE_ARCHLIB = path to the update arch lib install directory (-V:installarchlib)
16178 PERL_UPDATE_PRIVLIB = path to the update priv lib install directory (-V:installprivlib)
16179 PERL_EXTRA_C_FLAGS = Compilation flags used to build perl
16180 FindPHP4
16182 Find PHP4
16183 This module finds if PHP4 is installed and determines where the include
16185 files and libraries are. It also determines what the name of the li‐
16186 brary is. This code sets the following variables:
16187 PHP4_INCLUDE_PATH = path to where php.h can be found
16189 PHP4_EXECUTABLE = full path to the php4 binary
16190 FindPhysFS
16192 Locate PhysFS library This module defines PHYSFS_LIBRARY, the name of
16193 the library to link against PHYSFS_FOUND, if false, do not try to link
16194 to PHYSFS PHYSFS_INCLUDE_DIR, where to find physfs.h
16195 $PHYSFSDIR is an environment variable that would correspond to the
16197 ./configure --prefix=$PHYSFSDIR used in building PHYSFS.
16198 Created by Eric Wing.
16200 FindPike
16202 Find Pike
16203 This module finds if PIKE is installed and determines where the include
16205 files and libraries are. It also determines what the name of the li‐
16206 brary is. This code sets the following variables:
16207 PIKE_INCLUDE_PATH = path to where program.h is found
16209 PIKE_EXECUTABLE = full path to the pike binary
16210 FindPkgConfig
16212 A pkg-config module for CMake.
16213 Finds the pkg-config executable and adds the pkg_get_variable(),
16215 pkg_check_modules() and pkg_search_module() commands. The following
16216 variables will also be set:
16217 PKG_CONFIG_FOUND
16219 True if a pkg-config executable was found.
16220 PKG_CONFIG_VERSION_STRING
16222 New in version 2.8.8.
16223 The version of pkg-config that was found.
16226 PKG_CONFIG_EXECUTABLE
16228 The pathname of the pkg-config program.
16229 PKG_CONFIG_ARGN
16231 New in version 3.22.
16232 A list of arguments to pass to pkg-config.
16235 Both PKG_CONFIG_EXECUTABLE and PKG_CONFIG_ARGN are initialized by the
16237 module, but may be overridden by the user. See Variables Affecting Be‐
16238 havior for how these variables are initialized.
16239 pkg_check_modules
16241 Checks for all the given modules, setting a variety of result
16242 variables in the calling scope.
16243 pkg_check_modules(<prefix>
16245 [REQUIRED] [QUIET]
16246 [NO_CMAKE_PATH]
16247 [NO_CMAKE_ENVIRONMENT_PATH]
16248 [IMPORTED_TARGET [GLOBAL]]
16249 <moduleSpec> [<moduleSpec>...])
16250 When the REQUIRED argument is given, the command will fail with
16252 an error if module(s) could not be found.
16253 When the QUIET argument is given, no status messages will be
16255 printed.
16256 New in version 3.1: The CMAKE_PREFIX_PATH, CMAKE_FRAMEWORK_PATH,
16258 and CMAKE_APPBUNDLE_PATH cache and environment variables will be
16259 added to the pkg-config search path. The NO_CMAKE_PATH and
16260 NO_CMAKE_ENVIRONMENT_PATH arguments disable this behavior for
16261 the cache variables and environment variables respectively. The
16262 PKG_CONFIG_USE_CMAKE_PREFIX_PATH variable set to FALSE disables
16263 this behavior globally.
16264 New in version 3.6: The IMPORTED_TARGET argument will create an
16267 imported target named PkgConfig::<prefix> that can be passed di‐
16268 rectly as an argument to target_link_libraries().
16269 New in version 3.13: The GLOBAL argument will make the imported
16272 target available in global scope.
16273 New in version 3.15: Non-library linker options reported by
16276 pkg-config are stored in the INTERFACE_LINK_OPTIONS target prop‐
16277 erty.
16278 Changed in version 3.18: Include directories specified with
16281 -isystem are stored in the INTERFACE_INCLUDE_DIRECTORIES target
16282 property. Previous versions of CMake left them in the
16283 INTERFACE_COMPILE_OPTIONS property.
16284 Each <moduleSpec> can be either a bare module name or it can be
16287 a module name with a version constraint (operators =, <, >, <=
16288 and >= are supported). The following are examples for a module
16289 named foo with various constraints:
16290 • foo matches any version.
16292 • foo<2 only matches versions before 2.
16294 • foo>=3.1 matches any version from 3.1 or later.
16296 • foo=1.2.3 requires that foo must be exactly version 1.2.3.
16298 The following variables may be set upon return. Two sets of
16300 values exist: One for the common case (<XXX> = <prefix>) and an‐
16301 other for the information pkg-config provides when called with
16302 the --static option (<XXX> = <prefix>_STATIC).
16303 <XXX>_FOUND
16305 set to 1 if module(s) exist
16306 <XXX>_LIBRARIES
16308 only the libraries (without the '-l')
16309 <XXX>_LINK_LIBRARIES
16311 the libraries and their absolute paths
16312 <XXX>_LIBRARY_DIRS
16314 the paths of the libraries (without the '-L')
16315 <XXX>_LDFLAGS
16317 all required linker flags
16318 <XXX>_LDFLAGS_OTHER
16320 all other linker flags
16321 <XXX>_INCLUDE_DIRS
16323 the '-I' preprocessor flags (without the '-I')
16324 <XXX>_CFLAGS
16326 all required cflags
16327 <XXX>_CFLAGS_OTHER
16329 the other compiler flags
16330 All but <XXX>_FOUND may be a ;-list if the associated variable
16332 returned from pkg-config has multiple values.
16333 Changed in version 3.18: Include directories specified with
16335 -isystem are stored in the <XXX>_INCLUDE_DIRS variable. Previ‐
16336 ous versions of CMake left them in <XXX>_CFLAGS_OTHER.
16337 There are some special variables whose prefix depends on the
16340 number of <moduleSpec> given. When there is only one <module‐
16341 Spec>, <YYY> will simply be <prefix>, but if two or more <mod‐
16342 uleSpec> items are given, <YYY> will be <prefix>_<moduleName>.
16343 <YYY>_VERSION
16345 version of the module
16346 <YYY>_PREFIX
16348 prefix directory of the module
16349 <YYY>_INCLUDEDIR
16351 include directory of the module
16352 <YYY>_LIBDIR
16354 lib directory of the module
16355 Changed in version 3.8: For any given <prefix>, pkg_check_mod‐
16357 ules() can be called multiple times with different parameters.
16358 Previous versions of CMake cached and returned the first suc‐
16359 cessful result.
16360 Changed in version 3.16: If a full path to the found library
16363 can't be determined, but it's still visible to the linker, pass
16364 it through as -l<name>. Previous versions of CMake failed in
16365 this case.
16366 Examples:
16369 pkg_check_modules (GLIB2 glib-2.0)
16371 Looks for any version of glib2. If found, the output variable
16373 GLIB2_VERSION will hold the actual version found.
16374 pkg_check_modules (GLIB2 glib-2.0>=2.10)
16376 Looks for at least version 2.10 of glib2. If found, the output
16378 variable GLIB2_VERSION will hold the actual version found.
16379 pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0)
16381 Looks for both glib2-2.0 (at least version 2.10) and any version
16383 of gtk2+-2.0. Only if both are found will FOO be considered
16384 found. The FOO_glib-2.0_VERSION and FOO_gtk+-2.0_VERSION vari‐
16385 ables will be set to their respective found module versions.
16386 pkg_check_modules (XRENDER REQUIRED xrender)
16388 Requires any version of xrender. Example output variables set
16390 by a successful call:
16391 XRENDER_LIBRARIES=Xrender;X11
16393 XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp
16394 pkg_search_module
16396 The behavior of this command is the same as pkg_check_modules(),
16397 except that rather than checking for all the specified modules,
16398 it searches for just the first successful match.
16399 pkg_search_module(<prefix>
16401 [REQUIRED] [QUIET]
16402 [NO_CMAKE_PATH]
16403 [NO_CMAKE_ENVIRONMENT_PATH]
16404 [IMPORTED_TARGET [GLOBAL]]
16405 <moduleSpec> [<moduleSpec>...])
16406 New in version 3.16: If a module is found, the <prefix>_MOD‐
16408 ULE_NAME variable will contain the name of the matching module.
16409 This variable can be used if you need to run pkg_get_variable().
16410 Example:
16413 pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2)
16415 pkg_get_variable
16417 New in version 3.4.
16418 Retrieves the value of a pkg-config variable varName and stores
16421 it in the result variable resultVar in the calling scope.
16422 pkg_get_variable(<resultVar> <moduleName> <varName>)
16424 If pkg-config returns multiple values for the specified vari‐
16426 able, resultVar will contain a ;-list.
16427 For example:
16429 pkg_get_variable(GI_GIRDIR gobject-introspection-1.0 girdir)
16431 Variables Affecting Behavior
16433 PKG_CONFIG_EXECUTABLE
16434 This cache variable can be set to the path of the pkg-config ex‐
16435 ecutable. find_program() is called internally by the module
16436 with this variable.
16437 New in version 3.1: The PKG_CONFIG environment variable can be
16439 used as a hint if PKG_CONFIG_EXECUTABLE has not yet been set.
16440 Changed in version 3.22: If the PKG_CONFIG environment variable
16443 is set, only the first argument is taken from it when using it
16444 as a hint.
16445 PKG_CONFIG_ARGN
16448 New in version 3.22.
16449 This cache variable can be set to a list of arguments to addi‐
16452 tionally pass to pkg-config if needed. If not provided, it will
16453 be initialized from the PKG_CONFIG environment variable, if set.
16454 The first argument in that environment variable is assumed to be
16455 the pkg-config program, while all remaining arguments after that
16456 are used to initialize PKG_CONFIG_ARGN. If no such environment
16457 variable is defined, PKG_CONFIG_ARGN is initialized to an empty
16458 string. The module does not update the variable once it has been
16459 set in the cache.
16460 PKG_CONFIG_USE_CMAKE_PREFIX_PATH
16462 New in version 3.1.
16463 Specifies whether pkg_check_modules() and pkg_search_module()
16466 should add the paths in the CMAKE_PREFIX_PATH,
16467 CMAKE_FRAMEWORK_PATH and CMAKE_APPBUNDLE_PATH cache and environ‐
16468 ment variables to the pkg-config search path.
16469 If this variable is not set, this behavior is enabled by default
16471 if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later, disabled oth‐
16472 erwise.
16473 FindPNG
16475 Find libpng, the official reference library for the PNG image format.
16476 Imported targets
16478 New in version 3.5.
16479 This module defines the following IMPORTED target:
16482 PNG::PNG
16484 The libpng library, if found.
16485 Result variables
16487 This module will set the following variables in your project:
16488 PNG_INCLUDE_DIRS
16490 where to find png.h, etc.
16491 PNG_LIBRARIES
16493 the libraries to link against to use PNG.
16494 PNG_DEFINITIONS
16496 You should add_definitions(${PNG_DEFINITIONS}) before compiling
16497 code that includes png library files.
16498 PNG_FOUND
16500 If false, do not try to use PNG.
16501 PNG_VERSION_STRING
16503 the version of the PNG library found (since CMake 2.8.8)
16504 Obsolete variables
16506 The following variables may also be set, for backwards compatibility:
16507 PNG_LIBRARY
16509 where to find the PNG library.
16510 PNG_INCLUDE_DIR
16512 where to find the PNG headers (same as PNG_INCLUDE_DIRS)
16513 Since PNG depends on the ZLib compression library, none of the above
16515 will be defined unless ZLib can be found.
16516 FindPostgreSQL
16518 Find the PostgreSQL installation.
16519 IMPORTED Targets
16521 New in version 3.14.
16522 This module defines IMPORTED target PostgreSQL::PostgreSQL if Post‐
16525 greSQL has been found.
16526 Result Variables
16528 This module will set the following variables in your project:
16529 PostgreSQL_FOUND
16531 True if PostgreSQL is found.
16532 PostgreSQL_LIBRARIES
16534 the PostgreSQL libraries needed for linking
16535 PostgreSQL_INCLUDE_DIRS
16537 the directories of the PostgreSQL headers
16538 PostgreSQL_LIBRARY_DIRS
16540 the link directories for PostgreSQL libraries
16541 PostgreSQL_VERSION_STRING
16543 the version of PostgreSQL found
16544 PostgreSQL_TYPE_INCLUDE_DIR
16546 the directories of the PostgreSQL server headers
16547 Components
16549 This module contains additional Server component, that forcibly checks
16550 for the presence of server headers. Note that PostgreSQL_TYPE_IN‐
16551 CLUDE_DIR is set regardless of the presence of the Server component in
16552 find_package call.
16553 FindProducer
16555 Though Producer isn't directly part of OpenSceneGraph, its primary user
16556 is OSG so I consider this part of the Findosg* suite used to find Open‐
16557 SceneGraph components. You'll notice that I accept OSGDIR as an envi‐
16558 ronment path.
16559 Each component is separate and you must opt in to each module. You
16561 must also opt into OpenGL (and OpenThreads?) as these modules won't do
16562 it for you. This is to allow you control over your own system piece by
16563 piece in case you need to opt out of certain components or change the
16564 Find behavior for a particular module (perhaps because the default
16565 FindOpenGL.cmake module doesn't work with your system as an example).
16566 If you want to use a more convenient module that includes everything,
16567 use the FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules.
16568 Locate Producer This module defines PRODUCER_LIBRARY PRODUCER_FOUND, if
16570 false, do not try to link to Producer PRODUCER_INCLUDE_DIR, where to
16571 find the headers
16572 $PRODUCER_DIR is an environment variable that would correspond to the
16574 ./configure --prefix=$PRODUCER_DIR used in building osg.
16575 Created by Eric Wing.
16577 FindProtobuf
16579 Locate and configure the Google Protocol Buffers library.
16580 New in version 3.6: Support for find_package() version checks.
16582 Changed in version 3.6: All input and output variables use the Proto‐
16585 buf_ prefix. Variables with PROTOBUF_ prefix are still supported for
16586 compatibility.
16587 The following variables can be set and are optional:
16590 Protobuf_SRC_ROOT_FOLDER
16592 When compiling with MSVC, if this cache variable is set the pro‐
16593 tobuf-default VS project build locations (vsprojects/Debug and
16594 vsprojects/Release or vsprojects/x64/Debug and vspro‐
16595 jects/x64/Release) will be searched for libraries and binaries.
16596 Protobuf_IMPORT_DIRS
16598 List of additional directories to be searched for imported
16599 .proto files.
16600 Protobuf_DEBUG
16602 New in version 3.6.
16603 Show debug messages.
16606 Protobuf_USE_STATIC_LIBS
16608 New in version 3.9.
16609 Set to ON to force the use of the static libraries. Default is
16612 OFF.
16613 Defines the following variables:
16615 Protobuf_FOUND
16617 Found the Google Protocol Buffers library (libprotobuf & header
16618 files)
16619 Protobuf_VERSION
16621 New in version 3.6.
16622 Version of package found.
16625 Protobuf_INCLUDE_DIRS
16627 Include directories for Google Protocol Buffers
16628 Protobuf_LIBRARIES
16630 The protobuf libraries
16631 Protobuf_PROTOC_LIBRARIES
16633 The protoc libraries
16634 Protobuf_LITE_LIBRARIES
16636 The protobuf-lite libraries
16637 New in version 3.9: The following IMPORTED targets are also defined:
16639 protobuf::libprotobuf
16642 The protobuf library.
16643 protobuf::libprotobuf-lite
16645 The protobuf lite library.
16646 protobuf::libprotoc
16648 The protoc library.
16649 protobuf::protoc
16651 New in version 3.10: The protoc compiler.
16652 The following cache variables are also available to set or use:
16655 Protobuf_LIBRARY
16657 The protobuf library
16658 Protobuf_PROTOC_LIBRARY
16660 The protoc library
16661 Protobuf_INCLUDE_DIR
16663 The include directory for protocol buffers
16664 Protobuf_PROTOC_EXECUTABLE
16666 The protoc compiler
16667 Protobuf_LIBRARY_DEBUG
16669 The protobuf library (debug)
16670 Protobuf_PROTOC_LIBRARY_DEBUG
16672 The protoc library (debug)
16673 Protobuf_LITE_LIBRARY
16675 The protobuf lite library
16676 Protobuf_LITE_LIBRARY_DEBUG
16678 The protobuf lite library (debug)
16679 Example:
16681 find_package(Protobuf REQUIRED)
16683 include_directories(${Protobuf_INCLUDE_DIRS})
16684 include_directories(${CMAKE_CURRENT_BINARY_DIR})
16685 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS foo.proto)
16686 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS EXPORT_MACRO DLL_EXPORT foo.proto)
16687 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS DESCRIPTORS PROTO_DESCS foo.proto)
16688 protobuf_generate_python(PROTO_PY foo.proto)
16689 add_executable(bar bar.cc ${PROTO_SRCS} ${PROTO_HDRS})
16690 target_link_libraries(bar ${Protobuf_LIBRARIES})
16691 NOTE:
16693 The protobuf_generate_cpp and protobuf_generate_python functions and
16694 add_executable() or add_library() calls only work properly within
16695 the same directory.
16696 protobuf_generate_cpp
16698 Add custom commands to process .proto files to C++:
16699 protobuf_generate_cpp (<SRCS> <HDRS>
16701 [DESCRIPTORS <DESC>] [EXPORT_MACRO <MACRO>] [<ARGN>...])
16702 SRCS Variable to define with autogenerated source files
16704 HDRS Variable to define with autogenerated header files
16706 DESCRIPTORS
16708 New in version 3.10: Variable to define with autogener‐
16709 ated descriptor files, if requested.
16710 EXPORT_MACRO
16713 is a macro which should expand to __declspec(dllexport)
16714 or __declspec(dllimport) depending on what is being com‐
16715 piled.
16716 ARGN .proto files
16718 protobuf_generate_python
16720 New in version 3.4.
16721 Add custom commands to process .proto files to Python:
16724 protobuf_generate_python (<PY> [<ARGN>...])
16726 PY Variable to define with autogenerated Python files
16728 ARGN .proto files
16730 FindPython
16732 New in version 3.12.
16733 Find Python interpreter, compiler and development environment (include
16736 directories and libraries).
16737 New in version 3.19: When a version is requested, it can be specified
16739 as a simple value or as a range. For a detailed description of version
16740 range usage and capabilities, refer to the find_package() command.
16741 The following components are supported:
16744 • Interpreter: search for Python interpreter.
16746 • Compiler: search for Python compiler. Only offered by IronPython.
16748 • Development: search for development artifacts (include directories
16750 and libraries).
16751 New in version 3.18: This component includes two sub-components which
16753 can be specified independently:
16754 • Development.Module: search for artifacts for Python module develop‐
16756 ments.
16757 • Development.Embed: search for artifacts for Python embedding devel‐
16759 opments.
16760 • NumPy: search for NumPy include directories.
16763 New in version 3.14: Added the NumPy component.
16765 If no COMPONENTS are specified, Interpreter is assumed.
16768 If component Development is specified, it implies sub-components Devel‐
16770 opment.Module and Development.Embed.
16771 To ensure consistent versions between components Interpreter, Compiler,
16773 Development (or one of its sub-components) and NumPy, specify all com‐
16774 ponents at the same time:
16775 find_package (Python COMPONENTS Interpreter Development)
16777 This module looks preferably for version 3 of Python. If not found,
16779 version 2 is searched. To manage concurrent versions 3 and 2 of
16780 Python, use FindPython3 and FindPython2 modules rather than this one.
16781 NOTE:
16783 If components Interpreter and Development (or one of its sub-compo‐
16784 nents) are both specified, this module search only for interpreter
16785 with same platform architecture as the one defined by CMake configu‐
16786 ration. This constraint does not apply if only Interpreter component
16787 is specified.
16788 Imported Targets
16790 This module defines the following Imported Targets:
16791 Changed in version 3.14: Imported Targets are only created when
16793 CMAKE_ROLE is PROJECT.
16794 Python::Interpreter
16797 Python interpreter. Target defined if component Interpreter is
16798 found.
16799 Python::Compiler
16801 Python compiler. Target defined if component Compiler is found.
16802 Python::Module
16804 New in version 3.15.
16805 Python library for Python module. Target defined if component
16808 Development.Module is found.
16809 Python::Python
16811 Python library for Python embedding. Target defined if component
16812 Development.Embed is found.
16813 Python::NumPy
16815 New in version 3.14.
16816 NumPy Python library. Target defined if component NumPy is
16819 found.
16820 Result Variables
16822 This module will set the following variables in your project (see
16823 Standard Variable Names):
16824 Python_FOUND
16826 System has the Python requested components.
16827 Python_Interpreter_FOUND
16829 System has the Python interpreter.
16830 Python_EXECUTABLE
16832 Path to the Python interpreter.
16833 Python_INTERPRETER_ID
16835 A short string unique to the interpreter. Possible values in‐
16837 clude:
16838 • Python
16840 • ActivePython
16842 • Anaconda
16844 • Canopy
16846 • IronPython
16848 • PyPy
16850 Python_STDLIB
16852 Standard platform independent installation directory.
16853 Information returned by distutils.syscon‐
16855 fig.get_python_lib(plat_specific=False,standard_lib=True) or
16856 else sysconfig.get_path('stdlib').
16857 Python_STDARCH
16859 Standard platform dependent installation directory.
16860 Information returned by distutils.syscon‐
16862 fig.get_python_lib(plat_specific=True,standard_lib=True) or else
16863 sysconfig.get_path('platstdlib').
16864 Python_SITELIB
16866 Third-party platform independent installation directory.
16867 Information returned by distutils.syscon‐
16869 fig.get_python_lib(plat_specific=False,standard_lib=False) or
16870 else sysconfig.get_path('purelib').
16871 Python_SITEARCH
16873 Third-party platform dependent installation directory.
16874 Information returned by distutils.syscon‐
16876 fig.get_python_lib(plat_specific=True,standard_lib=False) or
16877 else sysconfig.get_path('platlib').
16878 Python_SOABI
16880 New in version 3.17.
16881 Extension suffix for modules.
16884 Information returned by distutils.sysconfig.get_con‐
16886 fig_var('SOABI') or computed from distutils.sysconfig.get_con‐
16887 fig_var('EXT_SUFFIX') or python-config --extension-suffix. If
16888 package distutils.sysconfig is not available, sysconfig.get_con‐
16889 fig_var('SOABI') or sysconfig.get_config_var('EXT_SUFFIX') are
16890 used.
16891 Python_Compiler_FOUND
16893 System has the Python compiler.
16894 Python_COMPILER
16896 Path to the Python compiler. Only offered by IronPython.
16897 Python_COMPILER_ID
16899 A short string unique to the compiler. Possible values include:
16901 • IronPython
16903 Python_DOTNET_LAUNCHER
16905 New in version 3.18.
16906 The .Net interpreter. Only used by IronPython implementation.
16909 Python_Development_FOUND
16911 System has the Python development artifacts.
16912 Python_Development.Module_FOUND
16914 New in version 3.18.
16915 System has the Python development artifacts for Python module.
16918 Python_Development.Embed_FOUND
16920 New in version 3.18.
16921 System has the Python development artifacts for Python embed‐
16924 ding.
16925 Python_INCLUDE_DIRS
16927 The Python include directories.
16928 Python_LINK_OPTIONS
16930 New in version 3.19.
16931 The Python link options. Some configurations require specific
16934 link options for a correct build and execution.
16935 Python_LIBRARIES
16937 The Python libraries.
16938 Python_LIBRARY_DIRS
16940 The Python library directories.
16941 Python_RUNTIME_LIBRARY_DIRS
16943 The Python runtime library directories.
16944 Python_VERSION
16946 Python version.
16947 Python_VERSION_MAJOR
16949 Python major version.
16950 Python_VERSION_MINOR
16952 Python minor version.
16953 Python_VERSION_PATCH
16955 Python patch version.
16956 Python_PyPy_VERSION
16958 New in version 3.18.
16959 Python PyPy version.
16962 Python_NumPy_FOUND
16964 New in version 3.14.
16965 System has the NumPy.
16968 Python_NumPy_INCLUDE_DIRS
16970 New in version 3.14.
16971 The NumPy include directories.
16974 Python_NumPy_VERSION
16976 New in version 3.14.
16977 The NumPy version.
16980 Hints
16982 Python_ROOT_DIR
16983 Define the root directory of a Python installation.
16984 Python_USE_STATIC_LIBS
16986 • If not defined, search for shared libraries and static li‐
16988 braries in that order.
16989 • If set to TRUE, search only for static libraries.
16991 • If set to FALSE, search only for shared libraries.
16993 NOTE:
16995 This hint will be ignored on Windows because static libraries
16996 are not available on this platform.
16997 Python_FIND_ABI
16999 New in version 3.16.
17000 This variable defines which ABIs, as defined in PEP 3149, should
17003 be searched.
17004 NOTE:
17006 This hint will be honored only when searched for Python ver‐
17007 sion 3.
17008 NOTE:
17010 If Python_FIND_ABI is not defined, any ABI will be searched.
17011 The Python_FIND_ABI variable is a 3-tuple specifying, in that
17013 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
17014 element can be set to one of the following:
17015 • ON: Corresponding flag is selected.
17017 • OFF: Corresponding flag is not selected.
17019 • ANY: The two possibilities (ON and OFF) will be searched.
17021 From this 3-tuple, various ABIs will be searched starting from
17023 the most specialized to the most general. Moreover, debug ver‐
17024 sions will be searched after non-debug ones.
17025 For example, if we have:
17027 set (Python_FIND_ABI "ON" "ANY" "ANY")
17029 The following flags combinations will be appended, in that or‐
17031 der, to the artifact names: dmu, dm, du, and d.
17032 And to search any possible ABIs:
17034 set (Python_FIND_ABI "ANY" "ANY" "ANY")
17036 The following combinations, in that order, will be used: mu, m,
17038 u, <empty>, dmu, dm, du and d.
17039 NOTE:
17041 This hint is useful only on POSIX systems. So, on Windows
17042 systems, when Python_FIND_ABI is defined, Python distribu‐
17043 tions from python.org will be found only if value for each
17044 flag is OFF or ANY.
17045 Python_FIND_STRATEGY
17047 New in version 3.15.
17048 This variable defines how lookup will be done. The
17051 Python_FIND_STRATEGY variable can be set to one of the follow‐
17052 ing:
17053 • VERSION: Try to find the most recent version in all specified
17055 locations. This is the default if policy CMP0094 is undefined
17056 or set to OLD.
17057 • LOCATION: Stops lookup as soon as a version satisfying version
17059 constraints is founded. This is the default if policy CMP0094
17060 is set to NEW.
17061 Python_FIND_REGISTRY
17063 New in version 3.13.
17064 On Windows the Python_FIND_REGISTRY variable determine the order
17067 of preference between registry and environment variables. the
17068 Python_FIND_REGISTRY variable can be set to one of the follow‐
17069 ing:
17070 • FIRST: Try to use registry before environment variables. This
17072 is the default.
17073 • LAST: Try to use registry after environment variables.
17075 • NEVER: Never try to use registry.
17077 Python_FIND_FRAMEWORK
17079 New in version 3.15.
17080 On macOS the Python_FIND_FRAMEWORK variable determine the order
17083 of preference between Apple-style and unix-style package compo‐
17084 nents. This variable can take same values as
17085 CMAKE_FIND_FRAMEWORK variable.
17086 NOTE:
17088 Value ONLY is not supported so FIRST will be used instead.
17089 If Python_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
17091 variable will be used, if any.
17092 Python_FIND_VIRTUALENV
17094 New in version 3.15.
17095 This variable defines the handling of virtual environments man‐
17098 aged by virtualenv or conda. It is meaningful only when a vir‐
17099 tual environment is active (i.e. the activate script has been
17100 evaluated). In this case, it takes precedence over
17101 Python_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
17102 Python_FIND_VIRTUALENV variable can be set to one of the follow‐
17103 ing:
17104 • FIRST: The virtual environment is used before any other stan‐
17106 dard paths to look-up for the interpreter. This is the de‐
17107 fault.
17108 • ONLY: Only the virtual environment is used to look-up for the
17110 interpreter.
17111 • STANDARD: The virtual environment is not used to look-up for
17113 the interpreter but environment variable PATH is always con‐
17114 sidered. In this case, variable Python_FIND_REGISTRY (Win‐
17115 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
17116 LAST or NEVER to select preferably the interpreter from the
17117 virtual environment.
17118 New in version 3.17: Added support for conda environments.
17120 NOTE:
17123 If the component Development is requested, it is strongly
17124 recommended to also include the component Interpreter to get
17125 expected result.
17126 Python_FIND_IMPLEMENTATIONS
17128 New in version 3.18.
17129 This variable defines, in an ordered list, the different imple‐
17132 mentations which will be searched. The Python_FIND_IMPLEMENTA‐
17133 TIONS variable can hold the following values:
17134 • CPython: this is the standard implementation. Various prod‐
17136 ucts, like Anaconda or ActivePython, rely on this implementa‐
17137 tion.
17138 • IronPython: This implementation use the CSharp language for
17140 .NET Framework on top of the Dynamic Language Runtime (DLR).
17141 See IronPython.
17142 • PyPy: This implementation use RPython language and RPython
17144 translation toolchain to produce the python interpreter. See
17145 PyPy.
17146 The default value is:
17148 • Windows platform: CPython, IronPython
17150 • Other platforms: CPython
17152 NOTE:
17154 This hint has the lowest priority of all hints, so even if,
17155 for example, you specify IronPython first and CPython in sec‐
17156 ond, a python product based on CPython can be selected be‐
17157 cause, for example with Python_FIND_STRATEGY=LOCATION, each
17158 location will be search first for IronPython and second for
17159 CPython.
17160 NOTE:
17162 When IronPython is specified, on platforms other than Win‐
17163 dows, the .Net interpreter (i.e. mono command) is expected to
17164 be available through the PATH variable.
17165 Python_FIND_UNVERSIONED_NAMES
17167 New in version 3.20.
17168 This variable defines how the generic names will be searched.
17171 Currently, it only applies to the generic names of the inter‐
17172 preter, namely, python3 or python2 and python. The
17173 Python_FIND_UNVERSIONED_NAMES variable can be set to one of the
17174 following values:
17175 • FIRST: The generic names are searched before the more special‐
17177 ized ones (such as python2.5 for example).
17178 • LAST: The generic names are searched after the more special‐
17180 ized ones. This is the default.
17181 • NEVER: The generic name are not searched at all.
17183 Artifacts Specification
17185 New in version 3.16.
17186 To solve special cases, it is possible to specify directly the arti‐
17189 facts by setting the following variables:
17190 Python_EXECUTABLE
17192 The path to the interpreter.
17193 Python_COMPILER
17195 The path to the compiler.
17196 Python_DOTNET_LAUNCHER
17198 New in version 3.18.
17199 The .Net interpreter. Only used by IronPython implementation.
17202 Python_LIBRARY
17204 The path to the library. It will be used to compute the vari‐
17205 ables Python_LIBRARIES, Python_LIBRARY_DIRS and Python_RUN‐
17206 TIME_LIBRARY_DIRS.
17207 Python_INCLUDE_DIR
17209 The path to the directory of the Python headers. It will be used
17210 to compute the variable Python_INCLUDE_DIRS.
17211 Python_NumPy_INCLUDE_DIR
17213 The path to the directory of the NumPy headers. It will be used
17214 to compute the variable Python_NumPy_INCLUDE_DIRS.
17215 NOTE:
17217 All paths must be absolute. Any artifact specified with a relative
17218 path will be ignored.
17219 NOTE:
17221 When an artifact is specified, all HINTS will be ignored and no
17222 search will be performed for this artifact.
17223 If more than one artifact is specified, it is the user's responsi‐
17225 bility to ensure the consistency of the various artifacts.
17226 By default, this module supports multiple calls in different directo‐
17228 ries of a project with different version/component requirements while
17229 providing correct and consistent results for each call. To support this
17230 behavior, CMake cache is not used in the traditional way which can be
17231 problematic for interactive specification. So, to enable also interac‐
17232 tive specification, module behavior can be controlled with the follow‐
17233 ing variable:
17234 Python_ARTIFACTS_INTERACTIVE
17236 New in version 3.18.
17237 Selects the behavior of the module. This is a boolean variable:
17240 • If set to TRUE: Create CMake cache entries for the above arti‐
17242 fact specification variables so that users can edit them in‐
17243 teractively. This disables support for multiple version/com‐
17244 ponent requirements.
17245 • If set to FALSE or undefined: Enable multiple version/compo‐
17247 nent requirements.
17248 Commands
17250 This module defines the command Python_add_library (when CMAKE_ROLE is
17251 PROJECT), which has the same semantics as add_library() and adds a de‐
17252 pendency to target Python::Python or, when library type is MODULE, to
17253 target Python::Module and takes care of Python module naming rules:
17254 Python_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
17256 <source1> [<source2> ...])
17257 If the library type is not specified, MODULE is assumed.
17259 New in version 3.17: For MODULE library type, if option WITH_SOABI is
17261 specified, the module suffix will include the Python_SOABI value, if
17262 any.
17263 FindPython2
17266 New in version 3.12.
17267 Find Python 2 interpreter, compiler and development environment (in‐
17270 clude directories and libraries).
17271 New in version 3.19: When a version is requested, it can be specified
17273 as a simple value or as a range. For a detailed description of version
17274 range usage and capabilities, refer to the find_package() command.
17275 The following components are supported:
17278 • Interpreter: search for Python 2 interpreter
17280 • Compiler: search for Python 2 compiler. Only offered by IronPython.
17282 • Development: search for development artifacts (include directories
17284 and libraries).
17285 New in version 3.18: This component includes two sub-components which
17287 can be specified independently:
17288 • Development.Module: search for artifacts for Python 2 module devel‐
17290 opments.
17291 • Development.Embed: search for artifacts for Python 2 embedding de‐
17293 velopments.
17294 • NumPy: search for NumPy include directories.
17297 New in version 3.14: Added the NumPy component.
17299 If no COMPONENTS are specified, Interpreter is assumed.
17302 If component Development is specified, it implies sub-components Devel‐
17304 opment.Module and Development.Embed.
17305 To ensure consistent versions between components Interpreter, Compiler,
17307 Development (or one of its sub-components) and NumPy, specify all com‐
17308 ponents at the same time:
17309 find_package (Python2 COMPONENTS Interpreter Development)
17311 This module looks only for version 2 of Python. This module can be used
17313 concurrently with FindPython3 module to use both Python versions.
17314 The FindPython module can be used if Python version does not matter for
17316 you.
17317 NOTE:
17319 If components Interpreter and Development (or one of its sub-compo‐
17320 nents) are both specified, this module search only for interpreter
17321 with same platform architecture as the one defined by CMake configu‐
17322 ration. This constraint does not apply if only Interpreter component
17323 is specified.
17324 Imported Targets
17326 This module defines the following Imported Targets:
17327 Changed in version 3.14: Imported Targets are only created when
17329 CMAKE_ROLE is PROJECT.
17330 Python2::Interpreter
17333 Python 2 interpreter. Target defined if component Interpreter is
17334 found.
17335 Python2::Compiler
17337 Python 2 compiler. Target defined if component Compiler is
17338 found.
17339 Python2::Module
17341 New in version 3.15.
17342 Python 2 library for Python module. Target defined if component
17345 Development.Module is found.
17346 Python2::Python
17348 Python 2 library for Python embedding. Target defined if compo‐
17349 nent Development.Embed is found.
17350 Python2::NumPy
17352 New in version 3.14.
17353 NumPy library for Python 2. Target defined if component NumPy is
17356 found.
17357 Result Variables
17359 This module will set the following variables in your project (see
17360 Standard Variable Names):
17361 Python2_FOUND
17363 System has the Python 2 requested components.
17364 Python2_Interpreter_FOUND
17366 System has the Python 2 interpreter.
17367 Python2_EXECUTABLE
17369 Path to the Python 2 interpreter.
17370 Python2_INTERPRETER_ID
17372 A short string unique to the interpreter. Possible values in‐
17374 clude:
17375 • Python
17377 • ActivePython
17379 • Anaconda
17381 • Canopy
17383 • IronPython
17385 • PyPy
17387 Python2_STDLIB
17389 Standard platform independent installation directory.
17390 Information returned by distutils.syscon‐
17392 fig.get_python_lib(plat_specific=False,standard_lib=True) or
17393 else sysconfig.get_path('stdlib').
17394 Python2_STDARCH
17396 Standard platform dependent installation directory.
17397 Information returned by distutils.syscon‐
17399 fig.get_python_lib(plat_specific=True,standard_lib=True) or else
17400 sysconfig.get_path('platstdlib').
17401 Python2_SITELIB
17403 Third-party platform independent installation directory.
17404 Information returned by distutils.syscon‐
17406 fig.get_python_lib(plat_specific=False,standard_lib=False) or
17407 else sysconfig.get_path('purelib').
17408 Python2_SITEARCH
17410 Third-party platform dependent installation directory.
17411 Information returned by distutils.syscon‐
17413 fig.get_python_lib(plat_specific=True,standard_lib=False) or
17414 else sysconfig.get_path('platlib').
17415 Python2_Compiler_FOUND
17417 System has the Python 2 compiler.
17418 Python2_COMPILER
17420 Path to the Python 2 compiler. Only offered by IronPython.
17421 Python2_COMPILER_ID
17423 A short string unique to the compiler. Possible values include:
17425 • IronPython
17427 Python2_DOTNET_LAUNCHER
17429 New in version 3.18.
17430 The .Net interpreter. Only used by IronPython implementation.
17433 Python2_Development_FOUND
17435 System has the Python 2 development artifacts.
17436 Python2_Development.Module_FOUND
17438 New in version 3.18.
17439 System has the Python 2 development artifacts for Python module.
17442 Python2_Development.Embed_FOUND
17444 New in version 3.18.
17445 System has the Python 2 development artifacts for Python embed‐
17448 ding.
17449 Python2_INCLUDE_DIRS
17451 The Python 2 include directories.
17452 Python2_LINK_OPTIONS
17454 New in version 3.19.
17455 The Python 2 link options. Some configurations require specific
17458 link options for a correct build and execution.
17459 Python2_LIBRARIES
17461 The Python 2 libraries.
17462 Python2_LIBRARY_DIRS
17464 The Python 2 library directories.
17465 Python2_RUNTIME_LIBRARY_DIRS
17467 The Python 2 runtime library directories.
17468 Python2_VERSION
17470 Python 2 version.
17471 Python2_VERSION_MAJOR
17473 Python 2 major version.
17474 Python2_VERSION_MINOR
17476 Python 2 minor version.
17477 Python2_VERSION_PATCH
17479 Python 2 patch version.
17480 Python2_PyPy_VERSION
17482 New in version 3.18.
17483 Python 2 PyPy version.
17486 Python2_NumPy_FOUND
17488 New in version 3.14.
17489 System has the NumPy.
17492 Python2_NumPy_INCLUDE_DIRS
17494 New in version 3.14.
17495 The NumPy include directories.
17498 Python2_NumPy_VERSION
17500 New in version 3.14.
17501 The NumPy version.
17504 Hints
17506 Python2_ROOT_DIR
17507 Define the root directory of a Python 2 installation.
17508 Python2_USE_STATIC_LIBS
17510 • If not defined, search for shared libraries and static li‐
17512 braries in that order.
17513 • If set to TRUE, search only for static libraries.
17515 • If set to FALSE, search only for shared libraries.
17517 NOTE:
17519 This hint will be ignored on Windows because static libraries
17520 are not available on this platform.
17521 Python2_FIND_STRATEGY
17523 New in version 3.15.
17524 This variable defines how lookup will be done. The
17527 Python2_FIND_STRATEGY variable can be set to one of the follow‐
17528 ing:
17529 • VERSION: Try to find the most recent version in all specified
17531 locations. This is the default if policy CMP0094 is undefined
17532 or set to OLD.
17533 • LOCATION: Stops lookup as soon as a version satisfying version
17535 constraints is founded. This is the default if policy CMP0094
17536 is set to NEW.
17537 Python2_FIND_REGISTRY
17539 New in version 3.13.
17540 On Windows the Python2_FIND_REGISTRY variable determine the or‐
17543 der of preference between registry and environment variables.
17544 the Python2_FIND_REGISTRY variable can be set to one of the fol‐
17545 lowing:
17546 • FIRST: Try to use registry before environment variables. This
17548 is the default.
17549 • LAST: Try to use registry after environment variables.
17551 • NEVER: Never try to use registry.
17553 Python2_FIND_FRAMEWORK
17555 New in version 3.15.
17556 On macOS the Python2_FIND_FRAMEWORK variable determine the order
17559 of preference between Apple-style and unix-style package compo‐
17560 nents. This variable can take same values as
17561 CMAKE_FIND_FRAMEWORK variable.
17562 NOTE:
17564 Value ONLY is not supported so FIRST will be used instead.
17565 If Python2_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
17567 variable will be used, if any.
17568 Python2_FIND_VIRTUALENV
17570 New in version 3.15.
17571 This variable defines the handling of virtual environments man‐
17574 aged by virtualenv or conda. It is meaningful only when a vir‐
17575 tual environment is active (i.e. the activate script has been
17576 evaluated). In this case, it takes precedence over
17577 Python2_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
17578 Python2_FIND_VIRTUALENV variable can be set to one of the fol‐
17579 lowing:
17580 • FIRST: The virtual environment is used before any other stan‐
17582 dard paths to look-up for the interpreter. This is the de‐
17583 fault.
17584 • ONLY: Only the virtual environment is used to look-up for the
17586 interpreter.
17587 • STANDARD: The virtual environment is not used to look-up for
17589 the interpreter but environment variable PATH is always con‐
17590 sidered. In this case, variable Python2_FIND_REGISTRY (Win‐
17591 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
17592 LAST or NEVER to select preferably the interpreter from the
17593 virtual environment.
17594 New in version 3.17: Added support for conda environments.
17596 NOTE:
17599 If the component Development is requested, it is strongly
17600 recommended to also include the component Interpreter to get
17601 expected result.
17602 Python2_FIND_IMPLEMENTATIONS
17604 New in version 3.18.
17605 This variable defines, in an ordered list, the different imple‐
17608 mentations which will be searched. The Python2_FIND_IMPLEMENTA‐
17609 TIONS variable can hold the following values:
17610 • CPython: this is the standard implementation. Various prod‐
17612 ucts, like Anaconda or ActivePython, rely on this implementa‐
17613 tion.
17614 • IronPython: This implementation use the CSharp language for
17616 .NET Framework on top of the Dynamic Language Runtime (DLR).
17617 See IronPython.
17618 • PyPy: This implementation use RPython language and RPython
17620 translation toolchain to produce the python interpreter. See
17621 PyPy.
17622 The default value is:
17624 • Windows platform: CPython, IronPython
17626 • Other platforms: CPython
17628 NOTE:
17630 This hint has the lowest priority of all hints, so even if,
17631 for example, you specify IronPython first and CPython in sec‐
17632 ond, a python product based on CPython can be selected be‐
17633 cause, for example with Python2_FIND_STRATEGY=LOCATION, each
17634 location will be search first for IronPython and second for
17635 CPython.
17636 NOTE:
17638 When IronPython is specified, on platforms other than Win‐
17639 dows, the .Net interpreter (i.e. mono command) is expected to
17640 be available through the PATH variable.
17641 Python2_FIND_UNVERSIONED_NAMES
17643 New in version 3.20.
17644 This variable defines how the generic names will be searched.
17647 Currently, it only applies to the generic names of the inter‐
17648 preter, namely, python2 and python. The Python2_FIND_UNVER‐
17649 SIONED_NAMES variable can be set to one of the following values:
17650 • FIRST: The generic names are searched before the more special‐
17652 ized ones (such as python2.5 for example).
17653 • LAST: The generic names are searched after the more special‐
17655 ized ones. This is the default.
17656 • NEVER: The generic name are not searched at all.
17658 Artifacts Specification
17660 New in version 3.16.
17661 To solve special cases, it is possible to specify directly the arti‐
17664 facts by setting the following variables:
17665 Python2_EXECUTABLE
17667 The path to the interpreter.
17668 Python2_COMPILER
17670 The path to the compiler.
17671 Python2_DOTNET_LAUNCHER
17673 New in version 3.18.
17674 The .Net interpreter. Only used by IronPython implementation.
17677 Python2_LIBRARY
17679 The path to the library. It will be used to compute the vari‐
17680 ables Python2_LIBRARIES, Python2_LIBRARY_DIRS and Python2_RUN‐
17681 TIME_LIBRARY_DIRS.
17682 Python2_INCLUDE_DIR
17684 The path to the directory of the Python headers. It will be used
17685 to compute the variable Python2_INCLUDE_DIRS.
17686 Python2_NumPy_INCLUDE_DIR
17688 The path to the directory of the NumPy headers. It will be used
17689 to compute the variable Python2_NumPy_INCLUDE_DIRS.
17690 NOTE:
17692 All paths must be absolute. Any artifact specified with a relative
17693 path will be ignored.
17694 NOTE:
17696 When an artifact is specified, all HINTS will be ignored and no
17697 search will be performed for this artifact.
17698 If more than one artifact is specified, it is the user's responsi‐
17700 bility to ensure the consistency of the various artifacts.
17701 By default, this module supports multiple calls in different directo‐
17703 ries of a project with different version/component requirements while
17704 providing correct and consistent results for each call. To support this
17705 behavior, CMake cache is not used in the traditional way which can be
17706 problematic for interactive specification. So, to enable also interac‐
17707 tive specification, module behavior can be controlled with the follow‐
17708 ing variable:
17709 Python2_ARTIFACTS_INTERACTIVE
17711 New in version 3.18.
17712 Selects the behavior of the module. This is a boolean variable:
17715 • If set to TRUE: Create CMake cache entries for the above arti‐
17717 fact specification variables so that users can edit them in‐
17718 teractively. This disables support for multiple version/com‐
17719 ponent requirements.
17720 • If set to FALSE or undefined: Enable multiple version/compo‐
17722 nent requirements.
17723 Commands
17725 This module defines the command Python2_add_library (when CMAKE_ROLE is
17726 PROJECT), which has the same semantics as add_library() and adds a de‐
17727 pendency to target Python2::Python or, when library type is MODULE, to
17728 target Python2::Module and takes care of Python module naming rules:
17729 Python2_add_library (<name> [STATIC | SHARED | MODULE]
17731 <source1> [<source2> ...])
17732 If library type is not specified, MODULE is assumed.
17734 FindPython3
17736 New in version 3.12.
17737 Find Python 3 interpreter, compiler and development environment (in‐
17740 clude directories and libraries).
17741 New in version 3.19: When a version is requested, it can be specified
17743 as a simple value or as a range. For a detailed description of version
17744 range usage and capabilities, refer to the find_package() command.
17745 The following components are supported:
17748 • Interpreter: search for Python 3 interpreter
17750 • Compiler: search for Python 3 compiler. Only offered by IronPython.
17752 • Development: search for development artifacts (include directories
17754 and libraries).
17755 New in version 3.18: This component includes two sub-components which
17757 can be specified independently:
17758 • Development.Module: search for artifacts for Python 3 module devel‐
17760 opments.
17761 • Development.Embed: search for artifacts for Python 3 embedding de‐
17763 velopments.
17764 • NumPy: search for NumPy include directories.
17767 New in version 3.14: Added the NumPy component.
17769 If no COMPONENTS are specified, Interpreter is assumed.
17772 If component Development is specified, it implies sub-components Devel‐
17774 opment.Module and Development.Embed.
17775 To ensure consistent versions between components Interpreter, Compiler,
17777 Development (or one of its sub-components) and NumPy, specify all com‐
17778 ponents at the same time:
17779 find_package (Python3 COMPONENTS Interpreter Development)
17781 This module looks only for version 3 of Python. This module can be used
17783 concurrently with FindPython2 module to use both Python versions.
17784 The FindPython module can be used if Python version does not matter for
17786 you.
17787 NOTE:
17789 If components Interpreter and Development (or one of its sub-compo‐
17790 nents) are both specified, this module search only for interpreter
17791 with same platform architecture as the one defined by CMake configu‐
17792 ration. This constraint does not apply if only Interpreter component
17793 is specified.
17794 Imported Targets
17796 This module defines the following Imported Targets:
17797 Changed in version 3.14: Imported Targets are only created when
17799 CMAKE_ROLE is PROJECT.
17800 Python3::Interpreter
17803 Python 3 interpreter. Target defined if component Interpreter is
17804 found.
17805 Python3::Compiler
17807 Python 3 compiler. Target defined if component Compiler is
17808 found.
17809 Python3::Module
17811 New in version 3.15.
17812 Python 3 library for Python module. Target defined if component
17815 Development.Module is found.
17816 Python3::Python
17818 Python 3 library for Python embedding. Target defined if compo‐
17819 nent Development.Embed is found.
17820 Python3::NumPy
17822 New in version 3.14.
17823 NumPy library for Python 3. Target defined if component NumPy is
17826 found.
17827 Result Variables
17829 This module will set the following variables in your project (see
17830 Standard Variable Names):
17831 Python3_FOUND
17833 System has the Python 3 requested components.
17834 Python3_Interpreter_FOUND
17836 System has the Python 3 interpreter.
17837 Python3_EXECUTABLE
17839 Path to the Python 3 interpreter.
17840 Python3_INTERPRETER_ID
17842 A short string unique to the interpreter. Possible values in‐
17844 clude:
17845 • Python
17847 • ActivePython
17849 • Anaconda
17851 • Canopy
17853 • IronPython
17855 • PyPy
17857 Python3_STDLIB
17859 Standard platform independent installation directory.
17860 Information returned by distutils.syscon‐
17862 fig.get_python_lib(plat_specific=False,standard_lib=True) or
17863 else sysconfig.get_path('stdlib').
17864 Python3_STDARCH
17866 Standard platform dependent installation directory.
17867 Information returned by distutils.syscon‐
17869 fig.get_python_lib(plat_specific=True,standard_lib=True) or else
17870 sysconfig.get_path('platstdlib').
17871 Python3_SITELIB
17873 Third-party platform independent installation directory.
17874 Information returned by distutils.syscon‐
17876 fig.get_python_lib(plat_specific=False,standard_lib=False) or
17877 else sysconfig.get_path('purelib').
17878 Python3_SITEARCH
17880 Third-party platform dependent installation directory.
17881 Information returned by distutils.syscon‐
17883 fig.get_python_lib(plat_specific=True,standard_lib=False) or
17884 else sysconfig.get_path('platlib').
17885 Python3_SOABI
17887 New in version 3.17.
17888 Extension suffix for modules.
17891 Information returned by distutils.sysconfig.get_con‐
17893 fig_var('SOABI') or computed from distutils.sysconfig.get_con‐
17894 fig_var('EXT_SUFFIX') or python3-config --extension-suffix. If
17895 package distutils.sysconfig is not available, sysconfig.get_con‐
17896 fig_var('SOABI') or sysconfig.get_config_var('EXT_SUFFIX') are
17897 used.
17898 Python3_Compiler_FOUND
17900 System has the Python 3 compiler.
17901 Python3_COMPILER
17903 Path to the Python 3 compiler. Only offered by IronPython.
17904 Python3_COMPILER_ID
17906 A short string unique to the compiler. Possible values include:
17908 • IronPython
17910 Python3_DOTNET_LAUNCHER
17912 New in version 3.18.
17913 The .Net interpreter. Only used by IronPython implementation.
17916 Python3_Development_FOUND
17918 System has the Python 3 development artifacts.
17919 Python3_Development.Module_FOUND
17921 New in version 3.18.
17922 System has the Python 3 development artifacts for Python module.
17925 Python3_Development.Embed_FOUND
17927 New in version 3.18.
17928 System has the Python 3 development artifacts for Python embed‐
17931 ding.
17932 Python3_INCLUDE_DIRS
17934 The Python 3 include directories.
17935 Python3_LINK_OPTIONS
17937 New in version 3.19.
17938 The Python 3 link options. Some configurations require specific
17941 link options for a correct build and execution.
17942 Python3_LIBRARIES
17944 The Python 3 libraries.
17945 Python3_LIBRARY_DIRS
17947 The Python 3 library directories.
17948 Python3_RUNTIME_LIBRARY_DIRS
17950 The Python 3 runtime library directories.
17951 Python3_VERSION
17953 Python 3 version.
17954 Python3_VERSION_MAJOR
17956 Python 3 major version.
17957 Python3_VERSION_MINOR
17959 Python 3 minor version.
17960 Python3_VERSION_PATCH
17962 Python 3 patch version.
17963 Python3_PyPy_VERSION
17965 New in version 3.18.
17966 Python 3 PyPy version.
17969 Python3_NumPy_FOUND
17971 New in version 3.14.
17972 System has the NumPy.
17975 Python3_NumPy_INCLUDE_DIRS
17977 New in version 3.14.
17978 The NumPy include directories.
17981 Python3_NumPy_VERSION
17983 New in version 3.14.
17984 The NumPy version.
17987 Hints
17989 Python3_ROOT_DIR
17990 Define the root directory of a Python 3 installation.
17991 Python3_USE_STATIC_LIBS
17993 • If not defined, search for shared libraries and static li‐
17995 braries in that order.
17996 • If set to TRUE, search only for static libraries.
17998 • If set to FALSE, search only for shared libraries.
18000 NOTE:
18002 This hint will be ignored on Windows because static libraries
18003 are not available on this platform.
18004 Python3_FIND_ABI
18006 New in version 3.16.
18007 This variable defines which ABIs, as defined in PEP 3149, should
18010 be searched.
18011 NOTE:
18013 If Python3_FIND_ABI is not defined, any ABI will be searched.
18014 The Python3_FIND_ABI variable is a 3-tuple specifying, in that
18016 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
18017 element can be set to one of the following:
18018 • ON: Corresponding flag is selected.
18020 • OFF: Corresponding flag is not selected.
18022 • ANY: The two possibilities (ON and OFF) will be searched.
18024 From this 3-tuple, various ABIs will be searched starting from
18026 the most specialized to the most general. Moreover, debug ver‐
18027 sions will be searched after non-debug ones.
18028 For example, if we have:
18030 set (Python3_FIND_ABI "ON" "ANY" "ANY")
18032 The following flags combinations will be appended, in that or‐
18034 der, to the artifact names: dmu, dm, du, and d.
18035 And to search any possible ABIs:
18037 set (Python3_FIND_ABI "ANY" "ANY" "ANY")
18039 The following combinations, in that order, will be used: mu, m,
18041 u, <empty>, dmu, dm, du and d.
18042 NOTE:
18044 This hint is useful only on POSIX systems. So, on Windows
18045 systems, when Python3_FIND_ABI is defined, Python distribu‐
18046 tions from python.org will be found only if value for each
18047 flag is OFF or ANY.
18048 Python3_FIND_STRATEGY
18050 New in version 3.15.
18051 This variable defines how lookup will be done. The
18054 Python3_FIND_STRATEGY variable can be set to one of the follow‐
18055 ing:
18056 • VERSION: Try to find the most recent version in all specified
18058 locations. This is the default if policy CMP0094 is undefined
18059 or set to OLD.
18060 • LOCATION: Stops lookup as soon as a version satisfying version
18062 constraints is founded. This is the default if policy CMP0094
18063 is set to NEW.
18064 Python3_FIND_REGISTRY
18066 New in version 3.13.
18067 On Windows the Python3_FIND_REGISTRY variable determine the or‐
18070 der of preference between registry and environment variables.
18071 The Python3_FIND_REGISTRY variable can be set to one of the fol‐
18072 lowing:
18073 • FIRST: Try to use registry before environment variables. This
18075 is the default.
18076 • LAST: Try to use registry after environment variables.
18078 • NEVER: Never try to use registry.
18080 Python3_FIND_FRAMEWORK
18082 New in version 3.15.
18083 On macOS the Python3_FIND_FRAMEWORK variable determine the order
18086 of preference between Apple-style and unix-style package compo‐
18087 nents. This variable can take same values as
18088 CMAKE_FIND_FRAMEWORK variable.
18089 NOTE:
18091 Value ONLY is not supported so FIRST will be used instead.
18092 If Python3_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
18094 variable will be used, if any.
18095 Python3_FIND_VIRTUALENV
18097 New in version 3.15.
18098 This variable defines the handling of virtual environments man‐
18101 aged by virtualenv or conda. It is meaningful only when a vir‐
18102 tual environment is active (i.e. the activate script has been
18103 evaluated). In this case, it takes precedence over
18104 Python3_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
18105 Python3_FIND_VIRTUALENV variable can be set to one of the fol‐
18106 lowing:
18107 • FIRST: The virtual environment is used before any other stan‐
18109 dard paths to look-up for the interpreter. This is the de‐
18110 fault.
18111 • ONLY: Only the virtual environment is used to look-up for the
18113 interpreter.
18114 • STANDARD: The virtual environment is not used to look-up for
18116 the interpreter but environment variable PATH is always con‐
18117 sidered. In this case, variable Python3_FIND_REGISTRY (Win‐
18118 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
18119 LAST or NEVER to select preferably the interpreter from the
18120 virtual environment.
18121 New in version 3.17: Added support for conda environments.
18123 NOTE:
18126 If the component Development is requested, it is strongly
18127 recommended to also include the component Interpreter to get
18128 expected result.
18129 Python3_FIND_IMPLEMENTATIONS
18131 New in version 3.18.
18132 This variable defines, in an ordered list, the different imple‐
18135 mentations which will be searched. The Python3_FIND_IMPLEMENTA‐
18136 TIONS variable can hold the following values:
18137 • CPython: this is the standard implementation. Various prod‐
18139 ucts, like Anaconda or ActivePython, rely on this implementa‐
18140 tion.
18141 • IronPython: This implementation use the CSharp language for
18143 .NET Framework on top of the Dynamic Language Runtime (DLR).
18144 See IronPython.
18145 • PyPy: This implementation use RPython language and RPython
18147 translation toolchain to produce the python interpreter. See
18148 PyPy.
18149 The default value is:
18151 • Windows platform: CPython, IronPython
18153 • Other platforms: CPython
18155 NOTE:
18157 This hint has the lowest priority of all hints, so even if,
18158 for example, you specify IronPython first and CPython in sec‐
18159 ond, a python product based on CPython can be selected be‐
18160 cause, for example with Python3_FIND_STRATEGY=LOCATION, each
18161 location will be search first for IronPython and second for
18162 CPython.
18163 NOTE:
18165 When IronPython is specified, on platforms other than Win‐
18166 dows, the .Net interpreter (i.e. mono command) is expected to
18167 be available through the PATH variable.
18168 Python3_FIND_UNVERSIONED_NAMES
18170 New in version 3.20.
18171 This variable defines how the generic names will be searched.
18174 Currently, it only applies to the generic names of the inter‐
18175 preter, namely, python3 and python. The Python3_FIND_UNVER‐
18176 SIONED_NAMES variable can be set to one of the following values:
18177 • FIRST: The generic names are searched before the more special‐
18179 ized ones (such as python3.5 for example).
18180 • LAST: The generic names are searched after the more special‐
18182 ized ones. This is the default.
18183 • NEVER: The generic name are not searched at all.
18185 Artifacts Specification
18187 New in version 3.16.
18188 To solve special cases, it is possible to specify directly the arti‐
18191 facts by setting the following variables:
18192 Python3_EXECUTABLE
18194 The path to the interpreter.
18195 Python3_COMPILER
18197 The path to the compiler.
18198 Python3_DOTNET_LAUNCHER
18200 New in version 3.18.
18201 The .Net interpreter. Only used by IronPython implementation.
18204 Python3_LIBRARY
18206 The path to the library. It will be used to compute the vari‐
18207 ables Python3_LIBRARIES, Python3_LIBRARY_DIRS and Python3_RUN‐
18208 TIME_LIBRARY_DIRS.
18209 Python3_INCLUDE_DIR
18211 The path to the directory of the Python headers. It will be used
18212 to compute the variable Python3_INCLUDE_DIRS.
18213 Python3_NumPy_INCLUDE_DIR
18215 The path to the directory of the NumPy headers. It will be used
18216 to compute the variable Python3_NumPy_INCLUDE_DIRS.
18217 NOTE:
18219 All paths must be absolute. Any artifact specified with a relative
18220 path will be ignored.
18221 NOTE:
18223 When an artifact is specified, all HINTS will be ignored and no
18224 search will be performed for this artifact.
18225 If more than one artifact is specified, it is the user's responsi‐
18227 bility to ensure the consistency of the various artifacts.
18228 By default, this module supports multiple calls in different directo‐
18230 ries of a project with different version/component requirements while
18231 providing correct and consistent results for each call. To support this
18232 behavior, CMake cache is not used in the traditional way which can be
18233 problematic for interactive specification. So, to enable also interac‐
18234 tive specification, module behavior can be controlled with the follow‐
18235 ing variable:
18236 Python3_ARTIFACTS_INTERACTIVE
18238 New in version 3.18.
18239 Selects the behavior of the module. This is a boolean variable:
18242 • If set to TRUE: Create CMake cache entries for the above arti‐
18244 fact specification variables so that users can edit them in‐
18245 teractively. This disables support for multiple version/com‐
18246 ponent requirements.
18247 • If set to FALSE or undefined: Enable multiple version/compo‐
18249 nent requirements.
18250 Commands
18252 This module defines the command Python3_add_library (when CMAKE_ROLE is
18253 PROJECT), which has the same semantics as add_library() and adds a de‐
18254 pendency to target Python3::Python or, when library type is MODULE, to
18255 target Python3::Module and takes care of Python module naming rules:
18256 Python3_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
18258 <source1> [<source2> ...])
18259 If the library type is not specified, MODULE is assumed.
18261 New in version 3.17: For MODULE library type, if option WITH_SOABI is
18263 specified, the module suffix will include the Python3_SOABI value, if
18264 any.
18265 FindQt3
18268 Locate Qt include paths and libraries
18269 This module defines:
18271 QT_INCLUDE_DIR - where to find qt.h, etc.
18273 QT_LIBRARIES - the libraries to link against to use Qt.
18274 QT_DEFINITIONS - definitions to use when
18275 compiling code that uses Qt.
18276 QT_FOUND - If false, don't try to use Qt.
18277 QT_VERSION_STRING - the version of Qt found
18278 If you need the multithreaded version of Qt, set QT_MT_REQUIRED to TRUE
18280 Also defined, but not for general use are:
18282 QT_MOC_EXECUTABLE, where to find the moc tool.
18284 QT_UIC_EXECUTABLE, where to find the uic tool.
18285 QT_QT_LIBRARY, where to find the Qt library.
18286 QT_QTMAIN_LIBRARY, where to find the qtmain
18287 library. This is only required by Qt3 on Windows.
18288 FindQt4
18290 Finding and Using Qt4
18291 This module can be used to find Qt4. The most important issue is that
18292 the Qt4 qmake is available via the system path. This qmake is then
18293 used to detect basically everything else. This module defines a number
18294 of IMPORTED targets, macros and variables.
18295 Typical usage could be something like:
18297 set(CMAKE_AUTOMOC ON)
18299 set(CMAKE_INCLUDE_CURRENT_DIR ON)
18300 find_package(Qt4 4.4.3 REQUIRED QtGui QtXml)
18301 add_executable(myexe main.cpp)
18302 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
18303 NOTE:
18305 When using IMPORTED targets, the qtmain.lib static library is auto‐
18306 matically linked on Windows for WIN32 executables. To disable that
18307 globally, set the QT4_NO_LINK_QTMAIN variable before finding Qt4. To
18308 disable that for a particular executable, set the QT4_NO_LINK_QTMAIN
18309 target property to TRUE on the executable.
18310 Qt Build Tools
18312 Qt relies on some bundled tools for code generation, such as moc for
18313 meta-object code generation,``uic`` for widget layout and population,
18314 and rcc for virtual filesystem content generation. These tools may be
18315 automatically invoked by cmake(1) if the appropriate conditions are
18316 met. See cmake-qt(7) for more.
18317 Qt Macros
18319 In some cases it can be necessary or useful to invoke the Qt build
18320 tools in a more-manual way. Several macros are available to add targets
18321 for such uses.
18322 macro QT4_WRAP_CPP(outfiles inputfile ... [TARGET tgt] OPTIONS ...)
18324 create moc code from a list of files containing Qt class with
18325 the Q_OBJECT declaration. Per-directory preprocessor definitions
18326 are also added. If the <tgt> is specified, the
18327 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
18328 the <tgt> are passed to moc. Options may be given to moc, such as
18329 those found when executing "moc -help".
18330 macro QT4_WRAP_UI(outfiles inputfile ... OPTIONS ...)
18332 create code from a list of Qt designer ui files.
18333 Options may be given to uic, such as those found
18334 when executing "uic -help"
18335 macro QT4_ADD_RESOURCES(outfiles inputfile ... OPTIONS ...)
18337 create code from a list of Qt resource files.
18338 Options may be given to rcc, such as those found
18339 when executing "rcc -help"
18340 macro QT4_GENERATE_MOC(inputfile outputfile [TARGET tgt])
18342 creates a rule to run moc on infile and create outfile.
18343 Use this if for some reason QT4_WRAP_CPP() isn't appropriate, e.g.
18344 because you need a custom filename for the moc file or something
18345 similar. If the <tgt> is specified, the
18346 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
18347 the <tgt> are passed to moc.
18348 macro QT4_ADD_DBUS_INTERFACE(outfiles interface basename)
18350 Create the interface header and implementation files with the
18351 given basename from the given interface xml file and add it to
18352 the list of sources.
18353 You can pass additional parameters to the qdbusxml2cpp call by setting
18355 properties on the input file:
18356 INCLUDE the given file will be included in the generate interface header
18358 CLASSNAME the generated class is named accordingly
18360 NO_NAMESPACE the generated class is not wrapped in a namespace
18362 macro QT4_ADD_DBUS_INTERFACES(outfiles inputfile ... )
18364 Create the interface header and implementation files
18365 for all listed interface xml files.
18366 The basename will be automatically determined from the name
18367 of the xml file.
18368 The source file properties described for
18370 QT4_ADD_DBUS_INTERFACE also apply here.
18371 macro QT4_ADD_DBUS_ADAPTOR(outfiles xmlfile parentheader parentclassname
18373 [basename] [classname])
18374 create a dbus adaptor (header and implementation file) from the xml file
18375 describing the interface, and add it to the list of sources. The adaptor
18376 forwards the calls to a parent class, defined in parentheader and named
18377 parentclassname. The name of the generated files will be
18378 <basename>adaptor.{cpp,h} where basename defaults to the basename of the
18379 xml file.
18380 If <classname> is provided, then it will be used as the classname of the
18381 adaptor itself.
18382 macro QT4_GENERATE_DBUS_INTERFACE( header [interfacename] OPTIONS ...)
18384 generate the xml interface file from the given header.
18385 If the optional argument interfacename is omitted, the name of the
18386 interface file is constructed from the basename of the header with
18387 the suffix .xml appended.
18388 Options may be given to qdbuscpp2xml, such as those found when
18389 executing "qdbuscpp2xml --help"
18390 macro QT4_CREATE_TRANSLATION( qm_files directories ... sources ...
18392 ts_files ... OPTIONS ...)
18393 out: qm_files
18394 in: directories sources ts_files
18395 options: flags to pass to lupdate, such as -extensions to specify
18396 extensions for a directory scan.
18397 generates commands to create .ts (via lupdate) and .qm
18398 (via lrelease) - files from directories and/or sources. The ts files are
18399 created and/or updated in the source tree (unless given with full paths).
18400 The qm files are generated in the build tree.
18401 Updating the translations can be done by adding the qm_files
18402 to the source list of your library/executable, so they are
18403 always updated, or by adding a custom target to control when
18404 they get updated/generated.
18405 macro QT4_ADD_TRANSLATION( qm_files ts_files ... )
18407 out: qm_files
18408 in: ts_files
18409 generates commands to create .qm from .ts - files. The generated
18410 filenames can be found in qm_files. The ts_files
18411 must exist and are not updated in any way.
18412 macro QT4_AUTOMOC(sourcefile1 sourcefile2 ... [TARGET tgt])
18414 The qt4_automoc macro is obsolete. Use the CMAKE_AUTOMOC feature instead.
18415 This macro is still experimental.
18416 It can be used to have moc automatically handled.
18417 So if you have the files foo.h and foo.cpp, and in foo.h a
18418 a class uses the Q_OBJECT macro, moc has to run on it. If you don't
18419 want to use QT4_WRAP_CPP() (which is reliable and mature), you can insert
18420 #include "foo.moc"
18421 in foo.cpp and then give foo.cpp as argument to QT4_AUTOMOC(). This will
18422 scan all listed files at cmake-time for such included moc files and if it
18423 finds them cause a rule to be generated to run moc at build time on the
18424 accompanying header file foo.h.
18425 If a source file has the SKIP_AUTOMOC property set it will be ignored by
18426 this macro.
18427 If the <tgt> is specified, the INTERFACE_INCLUDE_DIRECTORIES and
18428 INTERFACE_COMPILE_DEFINITIONS from the <tgt> are passed to moc.
18429 function QT4_USE_MODULES( target [link_type] modules...)
18431 This function is obsolete. Use target_link_libraries with IMPORTED targets
18432 instead.
18433 Make <target> use the <modules> from Qt. Using a Qt module means
18434 to link to the library, add the relevant include directories for the
18435 module, and add the relevant compiler defines for using the module.
18436 Modules are roughly equivalent to components of Qt4, so usage would be
18437 something like:
18438 qt4_use_modules(myexe Core Gui Declarative)
18439 to use QtCore, QtGui and QtDeclarative. The optional <link_type> argument
18440 can be specified as either LINK_PUBLIC or LINK_PRIVATE to specify the
18441 same argument to the target_link_libraries call.
18442 IMPORTED Targets
18444 A particular Qt library may be used by using the corresponding IMPORTED
18445 target with the target_link_libraries() command:
18446 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
18448 Using a target in this way causes :cmake(1)` to use the appropriate in‐
18450 clude directories and compile definitions for the target when compiling
18451 myexe.
18452 Targets are aware of their dependencies, so for example it is not nec‐
18454 essary to list Qt4::QtCore if another Qt library is listed, and it is
18455 not necessary to list Qt4::QtGui if Qt4::QtDeclarative is listed. Tar‐
18456 gets may be tested for existence in the usual way with the if(TARGET)
18457 command.
18458 The Qt toolkit may contain both debug and release libraries. cmake(1)
18460 will choose the appropriate version based on the build configuration.
18461 Qt4::QtCore
18463 The QtCore target
18464 Qt4::QtGui
18466 The QtGui target
18467 Qt4::Qt3Support
18469 The Qt3Support target
18470 Qt4::QtAssistant
18472 The QtAssistant target
18473 Qt4::QtAssistantClient
18475 The QtAssistantClient target
18476 Qt4::QAxContainer
18478 The QAxContainer target (Windows only)
18479 Qt4::QAxServer
18481 The QAxServer target (Windows only)
18482 Qt4::QtDBus
18484 The QtDBus target
18485 Qt4::QtDeclarative
18487 The QtDeclarative target
18488 Qt4::QtDesigner
18490 The QtDesigner target
18491 Qt4::QtDesignerComponents
18493 The QtDesignerComponents target
18494 Qt4::QtHelp
18496 The QtHelp target
18497 Qt4::QtMotif
18499 The QtMotif target
18500 Qt4::QtMultimedia
18502 The QtMultimedia target
18503 Qt4::QtNetwork
18505 The QtNetwork target
18506 Qt4::QtNsPLugin
18508 The QtNsPLugin target
18509 Qt4::QtOpenGL
18511 The QtOpenGL target
18512 Qt4::QtScript
18514 The QtScript target
18515 Qt4::QtScriptTools
18517 The QtScriptTools target
18518 Qt4::QtSql
18520 The QtSql target
18521 Qt4::QtSvg
18523 The QtSvg target
18524 Qt4::QtTest
18526 The QtTest target
18527 Qt4::QtUiTools
18529 The QtUiTools target
18530 Qt4::QtWebKit
18532 The QtWebKit target
18533 Qt4::QtXml
18535 The QtXml target
18536 Qt4::QtXmlPatterns
18538 The QtXmlPatterns target
18539 Qt4::phonon
18541 The phonon target
18542 Result Variables
18544 Below is a detailed list of variables that FindQt4.cmake sets.
18545 Qt4_FOUND
18547 If false, don't try to use Qt 4.
18548 QT_FOUND
18550 If false, don't try to use Qt. This variable is for compatibil‐
18551 ity only.
18552 QT4_FOUND
18554 If false, don't try to use Qt 4. This variable is for compati‐
18555 bility only.
18556 QT_VERSION_MAJOR
18558 The major version of Qt found.
18559 QT_VERSION_MINOR
18561 The minor version of Qt found.
18562 QT_VERSION_PATCH
18564 The patch version of Qt found.
18565 FindQuickTime
18567 Locate QuickTime This module defines QUICKTIME_LIBRARY QUICKTIME_FOUND,
18568 if false, do not try to link to gdal QUICKTIME_INCLUDE_DIR, where to
18569 find the headers
18570 $QUICKTIME_DIR is an environment variable that would correspond to the
18572 ./configure --prefix=$QUICKTIME_DIR
18573 Created by Eric Wing.
18575 FindRTI
18577 Try to find M&S HLA RTI libraries
18578 This module finds if any HLA RTI is installed and locates the standard
18580 RTI include files and libraries.
18581 RTI is a simulation infrastructure standardized by IEEE and SISO. It
18583 has a well defined C++ API that assures that simulation applications
18584 are independent on a particular RTI implementation.
18585 http://en.wikipedia.org/wiki/Run-Time_Infrastructure_(simulation)
18587 This code sets the following variables:
18589 RTI_INCLUDE_DIR = the directory where RTI includes file are found
18591 RTI_LIBRARIES = The libraries to link against to use RTI
18592 RTI_DEFINITIONS = -DRTI_USES_STD_FSTREAM
18593 RTI_FOUND = Set to FALSE if any HLA RTI was not found
18594 Report problems to <certi-devel@nongnu.org>
18596 FindRuby
18598 Find Ruby
18599 This module finds if Ruby is installed and determines where the include
18601 files and libraries are. Ruby 1.8 through 3.1 are supported.
18602 The minimum required version of Ruby can be specified using the stan‐
18604 dard syntax, e.g.
18605 find_package(Ruby 2.5.1 EXACT REQUIRED)
18607 # OR
18608 find_package(Ruby 2.4)
18609 It also determines what the name of the library is.
18611 Virtual environments such as RVM are handled as well, by passing the
18613 argument Ruby_FIND_VIRTUALENV
18614 Result Variables
18616 This module will set the following variables in your project:
18617 Ruby_FOUND
18619 set to true if ruby was found successfully
18620 Ruby_EXECUTABLE
18622 full path to the ruby binary
18623 Ruby_INCLUDE_DIRS
18625 include dirs to be used when using the ruby library
18626 Ruby_LIBRARIES
18628 New in version 3.18: libraries needed to use ruby from C.
18629 Ruby_VERSION
18632 the version of ruby which was found, e.g. "1.8.7"
18633 Ruby_VERSION_MAJOR
18635 Ruby major version.
18636 Ruby_VERSION_MINOR
18638 Ruby minor version.
18639 Ruby_VERSION_PATCH
18641 Ruby patch version.
18642 Changed in version 3.18: Previous versions of CMake used the RUBY_ pre‐
18644 fix for all variables. The following variables are provided for com‐
18645 patibility reasons, don't use them in new code:
18646 RUBY_EXECUTABLE
18649 same as Ruby_EXECUTABLE.
18650 RUBY_INCLUDE_DIRS
18652 same as Ruby_INCLUDE_DIRS.
18653 RUBY_INCLUDE_PATH
18655 same as Ruby_INCLUDE_DIRS.
18656 RUBY_LIBRARY
18658 same as Ruby_LIBRARY.
18659 RUBY_VERSION
18661 same as Ruby_VERSION.
18662 RUBY_FOUND
18664 same as Ruby_FOUND.
18665 Hints
18667 New in version 3.18.
18668 Ruby_FIND_VIRTUALENV
18671 This variable defines the handling of virtual environments man‐
18672 aged by rvm. It is meaningful only when a virtual environment is
18673 active (i.e. the rvm script has been evaluated or at least the
18674 MY_RUBY_HOME environment variable is set). The Ruby_FIND_VIR‐
18675 TUALENV variable can be set to empty or one of the following:
18676 • FIRST: The virtual environment is used before any other stan‐
18678 dard paths to look-up for the interpreter. This is the de‐
18679 fault.
18680 • ONLY: Only the virtual environment is used to look-up for the
18682 interpreter.
18683 • STANDARD: The virtual environment is not used to look-up for
18685 the interpreter (assuming it isn't still in the PATH...)
18686 FindSDL
18688 Locate the SDL library
18689 Imported targets
18691 New in version 3.19.
18692 This module defines the following IMPORTED target:
18695 SDL::SDL
18697 The SDL library, if found
18698 Result variables
18700 This module will set the following variables in your project:
18701 SDL_INCLUDE_DIRS
18703 where to find SDL.h
18704 SDL_LIBRARIES
18706 the name of the library to link against
18707 SDL_FOUND
18709 if false, do not try to link to SDL
18710 SDL_VERSION
18712 the human-readable string containing the version of SDL if found
18713 SDL_VERSION_MAJOR
18715 SDL major version
18716 SDL_VERSION_MINOR
18718 SDL minor version
18719 SDL_VERSION_PATCH
18721 SDL patch version
18722 New in version 3.19: Added the SDL_INCLUDE_DIRS, SDL_LIBRARIES and
18724 SDL_VERSION[_<PART>] variables.
18725 Cache variables
18728 These variables may optionally be set to help this module find the cor‐
18729 rect files:
18730 SDL_INCLUDE_DIR
18732 where to find SDL.h
18733 SDL_LIBRARY
18735 the name of the library to link against
18736 Variables for locating SDL
18738 This module responds to the flag:
18739 SDL_BUILDING_LIBRARY
18741 If this is defined, then no SDL_main will be linked in because
18742 only applications need main(). Otherwise, it is assumed you are
18743 building an application and this module will attempt to locate
18744 and set the proper link flags as part of the returned SDL_LI‐
18745 BRARY variable.
18746 Obsolete variables
18748 Deprecated since version 3.19.
18749 These variables are obsolete and provided for backwards compatibility:
18752 SDL_VERSION_STRING
18754 the human-readable string containing the version of SDL if
18755 found. Identical to SDL_VERSION
18756 Don't forget to include SDLmain.h and SDLmain.m your project for the OS
18758 X framework based version. (Other versions link to -lSDLmain which
18759 this module will try to find on your behalf.) Also for OS X, this mod‐
18760 ule will automatically add the -framework Cocoa on your behalf.
18761 Additional Note: If you see an empty SDL_LIBRARY_TEMP in your configu‐
18763 ration and no SDL_LIBRARY, it means CMake did not find your SDL library
18764 (SDL.dll, libsdl.so, SDL.framework, etc). Set SDL_LIBRARY_TEMP to
18765 point to your SDL library, and configure again. Similarly, if you see
18766 an empty SDLMAIN_LIBRARY, you should set this value as appropriate.
18767 These values are used to generate the final SDL_LIBRARY variable, but
18768 when these values are unset, SDL_LIBRARY does not get created.
18769 $SDLDIR is an environment variable that would correspond to the ./con‐
18771 figure --prefix=$SDLDIR used in building SDL. l.e.galup 9-20-02
18772 On OSX, this will prefer the Framework version (if found) over others.
18774 People will have to manually change the cache values of SDL_LIBRARY to
18775 override this selection or set the CMake environment CMAKE_INCLUDE_PATH
18776 to modify the search paths.
18777 Note that the header path has changed from SDL/SDL.h to just SDL.h This
18779 needed to change because "proper" SDL convention is #include "SDL.h",
18780 not <SDL/SDL.h>. This is done for portability reasons because not all
18781 systems place things in SDL/ (see FreeBSD).
18782 FindSDL_image
18784 Locate SDL_image library
18785 This module defines:
18787 SDL_IMAGE_LIBRARIES, the name of the library to link against
18789 SDL_IMAGE_INCLUDE_DIRS, where to find the headers
18790 SDL_IMAGE_FOUND, if false, do not try to link against
18791 SDL_IMAGE_VERSION_STRING - human-readable string containing the
18792 version of SDL_image
18793 For backward compatibility the following variables are also set:
18795 SDLIMAGE_LIBRARY (same value as SDL_IMAGE_LIBRARIES)
18797 SDLIMAGE_INCLUDE_DIR (same value as SDL_IMAGE_INCLUDE_DIRS)
18798 SDLIMAGE_FOUND (same value as SDL_IMAGE_FOUND)
18799 $SDLDIR is an environment variable that would correspond to the ./con‐
18801 figure --prefix=$SDLDIR used in building SDL.
18802 FindSDL_gfx
18804 New in version 3.25.
18805 Locate SDL_gfx library
18808 This module defines:
18810 SDL::SDL_gfx, the name of the target to use with target_*() commands
18812 SDL_GFX_LIBRARIES, the name of the library to link against
18813 SDL_GFX_INCLUDE_DIRS, where to find the headers
18814 SDL_GFX_FOUND, if false, do not try to link against
18815 SDL_GFX_VERSION_STRING - human-readable string containing the
18816 version of SDL_gfx
18817 $SDLDIR is an environment variable that would correspond to the ./con‐
18819 figure --prefix=$SDLDIR used in building SDL.
18820 FindSDL_mixer
18822 Locate SDL_mixer library
18823 This module defines:
18825 SDL_MIXER_LIBRARIES, the name of the library to link against
18827 SDL_MIXER_INCLUDE_DIRS, where to find the headers
18828 SDL_MIXER_FOUND, if false, do not try to link against
18829 SDL_MIXER_VERSION_STRING - human-readable string containing the
18830 version of SDL_mixer
18831 For backward compatibility the following variables are also set:
18833 SDLMIXER_LIBRARY (same value as SDL_MIXER_LIBRARIES)
18835 SDLMIXER_INCLUDE_DIR (same value as SDL_MIXER_INCLUDE_DIRS)
18836 SDLMIXER_FOUND (same value as SDL_MIXER_FOUND)
18837 $SDLDIR is an environment variable that would correspond to the ./con‐
18839 figure --prefix=$SDLDIR used in building SDL.
18840 FindSDL_net
18842 Locate SDL_net library
18843 This module defines:
18845 SDL_NET_LIBRARIES, the name of the library to link against
18847 SDL_NET_INCLUDE_DIRS, where to find the headers
18848 SDL_NET_FOUND, if false, do not try to link against
18849 SDL_NET_VERSION_STRING - human-readable string containing the version of SDL_net
18850 For backward compatibility the following variables are also set:
18852 SDLNET_LIBRARY (same value as SDL_NET_LIBRARIES)
18854 SDLNET_INCLUDE_DIR (same value as SDL_NET_INCLUDE_DIRS)
18855 SDLNET_FOUND (same value as SDL_NET_FOUND)
18856 $SDLDIR is an environment variable that would correspond to the ./con‐
18858 figure --prefix=$SDLDIR used in building SDL.
18859 FindSDL_sound
18861 Locates the SDL_sound library
18862 This module depends on SDL being found and must be called AFTER Find‐
18864 SDL.cmake is called.
18865 This module defines
18867 SDL_SOUND_INCLUDE_DIR, where to find SDL_sound.h
18869 SDL_SOUND_FOUND, if false, do not try to link to SDL_sound
18870 SDL_SOUND_LIBRARIES, this contains the list of libraries that you need
18871 to link against.
18872 SDL_SOUND_EXTRAS, this is an optional variable for you to add your own
18873 flags to SDL_SOUND_LIBRARIES. This is prepended to SDL_SOUND_LIBRARIES.
18874 This is available mostly for cases this module failed to anticipate for
18875 and you must add additional flags. This is marked as ADVANCED.
18876 SDL_SOUND_VERSION_STRING, human-readable string containing the
18877 version of SDL_sound
18878 This module also defines (but you shouldn't need to use directly)
18880 SDL_SOUND_LIBRARY, the name of just the SDL_sound library you would link
18882 against. Use SDL_SOUND_LIBRARIES for you link instructions and not this one.
18883 And might define the following as needed
18885 MIKMOD_LIBRARY
18887 MODPLUG_LIBRARY
18888 OGG_LIBRARY
18889 VORBIS_LIBRARY
18890 SMPEG_LIBRARY
18891 FLAC_LIBRARY
18892 SPEEX_LIBRARY
18893 Typically, you should not use these variables directly, and you should
18895 use SDL_SOUND_LIBRARIES which contains SDL_SOUND_LIBRARY and the other
18896 audio libraries (if needed) to successfully compile on your system.
18897 Responds to the $SDLDIR and $SDLSOUNDDIR environmental variable that
18899 would correspond to the ./configure --prefix=$SDLDIR used in building
18900 SDL.
18901 On OSX, this will prefer the Framework version (if found) over others.
18903 People will have to manually change the cache values of SDL_LIBRARY to
18904 override this selectionor set the CMake environment CMAKE_INCLUDE_PATH
18905 to modify the search paths.
18906 FindSDL_ttf
18908 Locate SDL_ttf library
18909 This module defines:
18911 SDL_TTF_LIBRARIES, the name of the library to link against
18913 SDL_TTF_INCLUDE_DIRS, where to find the headers
18914 SDL_TTF_FOUND, if false, do not try to link against
18915 SDL_TTF_VERSION_STRING - human-readable string containing the version of SDL_ttf
18916 For backward compatibility the following variables are also set:
18918 SDLTTF_LIBRARY (same value as SDL_TTF_LIBRARIES)
18920 SDLTTF_INCLUDE_DIR (same value as SDL_TTF_INCLUDE_DIRS)
18921 SDLTTF_FOUND (same value as SDL_TTF_FOUND)
18922 $SDLDIR is an environment variable that would correspond to the ./con‐
18924 figure --prefix=$SDLDIR used in building SDL.
18925 FindSelfPackers
18927 Find upx
18928 This module looks for some executable packers (i.e. software that com‐
18930 press executables or shared libs into on-the-fly self-extracting exe‐
18931 cutables or shared libs. Examples:
18932 UPX: http://wildsau.idv.uni-linz.ac.at/mfx/upx.html
18934 FindSquish
18936 -- Typical Use
18937 This module can be used to find Squish.
18939 SQUISH_FOUND If false, don't try to use Squish
18941 SQUISH_VERSION The full version of Squish found
18942 SQUISH_VERSION_MAJOR The major version of Squish found
18943 SQUISH_VERSION_MINOR The minor version of Squish found
18944 SQUISH_VERSION_PATCH The patch version of Squish found
18945 SQUISH_INSTALL_DIR The Squish installation directory
18947 (containing bin, lib, etc)
18948 SQUISH_SERVER_EXECUTABLE The squishserver executable
18949 SQUISH_CLIENT_EXECUTABLE The squishrunner executable
18950 SQUISH_INSTALL_DIR_FOUND Was the install directory found?
18952 SQUISH_SERVER_EXECUTABLE_FOUND Was the server executable found?
18953 SQUISH_CLIENT_EXECUTABLE_FOUND Was the client executable found?
18954 It provides the function squish_add_test() for adding a squish test to
18956 cmake using Squish >= 4.x:
18957 squish_add_test(cmakeTestName
18959 AUT targetName SUITE suiteName TEST squishTestName
18960 [SETTINGSGROUP group] [PRE_COMMAND command] [POST_COMMAND command] )
18961 Changed in version 3.18: In previous CMake versions, this function was
18963 named squish_v4_add_test.
18964 The arguments have the following meaning:
18967 cmakeTestName
18969 this will be used as the first argument for add_test()
18970 AUT targetName
18972 the name of the cmake target which will be used as AUT, i.e. the
18973 executable which will be tested.
18974 SUITE suiteName
18976 this is either the full path to the squish suite, or just the
18977 last directory of the suite, i.e. the suite name. In this case
18978 the CMakeLists.txt which calls squish_add_test() must be located
18979 in the parent directory of the suite directory.
18980 TEST squishTestName
18982 the name of the squish test, i.e. the name of the subdirectory
18983 of the test inside the suite directory.
18984 SETTINGSGROUP group
18986 deprecated, this argument will be ignored.
18987 PRE_COMMAND command
18989 if specified, the given command will be executed before starting
18990 the squish test.
18991 POST_COMMAND command
18993 same as PRE_COMMAND, but after the squish test has been exe‐
18994 cuted.
18995 enable_testing()
18997 find_package(Squish 6.5)
18998 if (SQUISH_FOUND)
18999 squish_add_test(myTestName
19000 AUT myApp
19001 SUITE ${CMAKE_SOURCE_DIR}/tests/mySuite
19002 TEST someSquishTest
19003 )
19004 endif ()
19005 For users of Squish version 3.x the macro squish_v3_add_test() is pro‐
19007 vided:
19008 squish_v3_add_test(testName applicationUnderTest testCase envVars testWrapper)
19010 Use this macro to add a test using Squish 3.x.
19011 enable_testing()
19013 find_package(Squish 3.0)
19014 if (SQUISH_FOUND)
19015 squish_v3_add_test(myTestName myApplication testCase envVars testWrapper)
19016 endif ()
19017 FindSQLite3
19019 New in version 3.14.
19020 Find the SQLite libraries, v3
19023 IMPORTED targets
19025 This module defines the following IMPORTED target:
19026 SQLite::SQLite3
19028 Result variables
19030 This module will set the following variables if found:
19031 SQLite3_INCLUDE_DIRS
19033 where to find sqlite3.h, etc.
19034 SQLite3_LIBRARIES
19036 the libraries to link against to use SQLite3.
19037 SQLite3_VERSION
19039 version of the SQLite3 library found
19040 SQLite3_FOUND
19042 TRUE if found
19043 FindSubversion
19045 Extract information from a subversion working copy
19046 The module defines the following variables:
19048 Subversion_SVN_EXECUTABLE - path to svn command line client
19050 Subversion_VERSION_SVN - version of svn command line client
19051 Subversion_FOUND - true if the command line client was found
19052 SUBVERSION_FOUND - same as Subversion_FOUND, set for compatibility reasons
19053 The minimum required version of Subversion can be specified using the
19055 standard syntax, e.g. find_package(Subversion 1.4).
19056 If the command line client executable is found two macros are defined:
19058 Subversion_WC_INFO(<dir> <var-prefix> [IGNORE_SVN_FAILURE])
19060 Subversion_WC_LOG(<dir> <var-prefix>)
19061 Subversion_WC_INFO extracts information of a subversion working copy at
19063 a given location. This macro defines the following variables if run‐
19064 ning Subversion's info command on <dir> succeeds; otherwise a SEND_ER‐
19065 ROR message is generated.
19066 New in version 3.13: The error can be ignored by providing the IG‐
19068 NORE_SVN_FAILURE option, which causes these variables to remain unde‐
19069 fined.
19070 <var-prefix>_WC_URL - url of the repository (at <dir>)
19073 <var-prefix>_WC_ROOT - root url of the repository
19074 <var-prefix>_WC_REVISION - current revision
19075 <var-prefix>_WC_LAST_CHANGED_AUTHOR - author of last commit
19076 <var-prefix>_WC_LAST_CHANGED_DATE - date of last commit
19077 <var-prefix>_WC_LAST_CHANGED_REV - revision of last commit
19078 <var-prefix>_WC_INFO - output of command `svn info <dir>'
19079 Subversion_WC_LOG retrieves the log message of the base revision of a
19081 subversion working copy at a given location. This macro defines the
19082 variable:
19083 <var-prefix>_LAST_CHANGED_LOG - last log of base revision
19085 Example usage:
19087 find_package(Subversion)
19089 if(SUBVERSION_FOUND)
19090 Subversion_WC_INFO(${PROJECT_SOURCE_DIR} Project)
19091 message("Current revision is ${Project_WC_REVISION}")
19092 Subversion_WC_LOG(${PROJECT_SOURCE_DIR} Project)
19093 message("Last changed log is ${Project_LAST_CHANGED_LOG}")
19094 endif()
19095 FindSWIG
19097 Find the Simplified Wrapper and Interface Generator (SWIG) executable.
19098 This module finds an installed SWIG and determines its version.
19100 New in version 3.18: If a COMPONENTS or OPTIONAL_COMPONENTS argument is
19102 given to the find_package() command, it will also determine supported
19103 target languages.
19104 New in version 3.19: When a version is requested, it can be specified
19107 as a simple value or as a range. For a detailed description of version
19108 range usage and capabilities, refer to the find_package() command.
19109 The module defines the following variables:
19112 SWIG_FOUND
19114 Whether SWIG and any required components were found on the sys‐
19115 tem.
19116 SWIG_EXECUTABLE
19118 Path to the SWIG executable.
19119 SWIG_DIR
19121 Path to the installed SWIG Lib directory (result of swig
19122 -swiglib).
19123 SWIG_VERSION
19125 SWIG executable version (result of swig -version).
19126 SWIG_<lang>_FOUND
19128 If COMPONENTS or OPTIONAL_COMPONENTS are requested, each avail‐
19129 able target language <lang> (lowercase) will be set to TRUE.
19130 Any COMPONENTS given to find_package should be the names of supported
19132 target languages as provided to the LANGUAGE argument of swig_add_li‐
19133 brary, such as python or perl5. Language names must be lowercase.
19134 All information is collected from the SWIG_EXECUTABLE, so the version
19136 to be found can be changed from the command line by means of setting
19137 SWIG_EXECUTABLE.
19138 Example usage requiring SWIG 4.0 or higher and Python language support,
19140 with optional Fortran support:
19141 find_package(SWIG 4.0 COMPONENTS python OPTIONAL_COMPONENTS fortran)
19143 if(SWIG_FOUND)
19144 message("SWIG found: ${SWIG_EXECUTABLE}")
19145 if(NOT SWIG_fortran_FOUND)
19146 message(WARNING "SWIG Fortran bindings cannot be generated")
19147 endif()
19148 endif()
19149 FindTCL
19151 TK_INTERNAL_PATH was removed.
19152 This module finds if Tcl is installed and determines where the include
19154 files and libraries are. It also determines what the name of the li‐
19155 brary is. This code sets the following variables:
19156 TCL_FOUND = Tcl was found
19158 TK_FOUND = Tk was found
19159 TCLTK_FOUND = Tcl and Tk were found
19160 TCL_LIBRARY = path to Tcl library (tcl tcl80)
19161 TCL_INCLUDE_PATH = path to where tcl.h can be found
19162 TCL_TCLSH = path to tclsh binary (tcl tcl80)
19163 TK_LIBRARY = path to Tk library (tk tk80 etc)
19164 TK_INCLUDE_PATH = path to where tk.h can be found
19165 TK_WISH = full path to the wish executable
19166 In an effort to remove some clutter and clear up some issues for people
19168 who are not necessarily Tcl/Tk gurus/developers, some variables were
19169 moved or removed. Changes compared to CMake 2.4 are:
19170 => they were only useful for people writing Tcl/Tk extensions.
19172 => these libs are not packaged by default with Tcl/Tk distributions.
19173 Even when Tcl/Tk is built from source, several flavors of debug libs
19174 are created and there is no real reason to pick a single one
19175 specifically (say, amongst tcl84g, tcl84gs, or tcl84sgx).
19176 Let's leave that choice to the user by allowing him to assign
19177 TCL_LIBRARY to any Tcl library, debug or not.
19178 => this ended up being only a Win32 variable, and there is a lot of
19179 confusion regarding the location of this file in an installed Tcl/Tk
19180 tree anyway (see 8.5 for example). If you need the internal path at
19181 this point it is safer you ask directly where the *source* tree is
19182 and dig from there.
19183 FindTclsh
19185 Find tclsh
19186 This module finds if TCL is installed and determines where the include
19188 files and libraries are. It also determines what the name of the li‐
19189 brary is. This code sets the following variables:
19190 TCLSH_FOUND = TRUE if tclsh has been found
19192 TCL_TCLSH = the path to the tclsh executable
19193 FindTclStub
19195 TCL_STUB_LIBRARY_DEBUG and TK_STUB_LIBRARY_DEBUG were removed.
19196 This module finds Tcl stub libraries. It first finds Tcl include files
19198 and libraries by calling FindTCL.cmake. How to Use the Tcl Stubs Li‐
19199 brary:
19200 http://tcl.activestate.com/doc/howto/stubs.html
19202 Using Stub Libraries:
19204 http://safari.oreilly.com/0130385603/ch48lev1sec3
19206 This code sets the following variables:
19208 TCL_STUB_LIBRARY = path to Tcl stub library
19210 TK_STUB_LIBRARY = path to Tk stub library
19211 TTK_STUB_LIBRARY = path to ttk stub library
19212 In an effort to remove some clutter and clear up some issues for people
19214 who are not necessarily Tcl/Tk gurus/developers, some variables were
19215 moved or removed. Changes compared to CMake 2.4 are:
19216 => these libs are not packaged by default with Tcl/Tk distributions.
19218 Even when Tcl/Tk is built from source, several flavors of debug libs
19219 are created and there is no real reason to pick a single one
19220 specifically (say, amongst tclstub84g, tclstub84gs, or tclstub84sgx).
19221 Let's leave that choice to the user by allowing him to assign
19222 TCL_STUB_LIBRARY to any Tcl library, debug or not.
19223 FindThreads
19225 This module determines the thread library of the system.
19226 Imported Targets
19228 New in version 3.1.
19229 This module defines the following IMPORTED target:
19232 Threads::Threads
19234 The thread library, if found.
19235 Result Variables
19237 The following variables are set:
19238 Threads_FOUND
19240 If a supported thread library was found.
19241 CMAKE_THREAD_LIBS_INIT
19243 The thread library to use. This may be empty if the thread func‐
19244 tions are provided by the system libraries and no special flags
19245 are needed to use them.
19246 CMAKE_USE_WIN32_THREADS_INIT
19248 If the found thread library is the win32 one.
19249 CMAKE_USE_PTHREADS_INIT
19251 If the found thread library is pthread compatible.
19252 CMAKE_HP_PTHREADS_INIT
19254 If the found thread library is the HP thread library.
19255 Variables Affecting Behavior
19257 THREADS_PREFER_PTHREAD_FLAG
19258 New in version 3.1.
19259 If the use of the -pthread compiler and linker flag is preferred
19262 then the caller can set this variable to TRUE. The compiler flag
19263 can only be used with the imported target. Use of both the im‐
19264 ported target as well as this switch is highly recommended for
19265 new code.
19266 This variable has no effect if the system libraries provide the
19268 thread functions, i.e. when CMAKE_THREAD_LIBS_INIT will be
19269 empty.
19270 FindTIFF
19272 Find the TIFF library (libtiff, https://libtiff.gitlab.io/libtiff/).
19273 Optional COMPONENTS
19275 This module supports the optional component CXX, for use with the COM‐
19276 PONENTS argument of the find_package() command. This component has an
19277 associated imported target, as described below.
19278 Imported targets
19280 New in version 3.5.
19281 This module defines the following IMPORTED targets:
19284 TIFF::TIFF
19286 The TIFF library, if found.
19287 TIFF::CXX
19289 New in version 3.19.
19290 The C++ wrapper libtiffxx, if requested by the COMPONENTS CXX
19293 option, if the compiler is not MSVC (which includes the C++
19294 wrapper in libtiff), and if found.
19295 Result variables
19297 This module will set the following variables in your project:
19298 TIFF_FOUND
19300 true if the TIFF headers and libraries were found
19301 TIFF_INCLUDE_DIR
19303 the directory containing the TIFF headers
19304 TIFF_INCLUDE_DIRS
19306 the directory containing the TIFF headers
19307 TIFF_LIBRARIES
19309 TIFF libraries to be linked
19310 Cache variables
19312 The following cache variables may also be set:
19313 TIFF_INCLUDE_DIR
19315 the directory containing the TIFF headers
19316 TIFF_LIBRARY_RELEASE
19318 the path to the TIFF library for release configurations
19319 TIFF_LIBRARY_DEBUG
19321 the path to the TIFF library for debug configurations
19322 TIFFXX_LIBRARY_RELEASE
19324 the path to the TIFFXX library for release configurations
19325 TIFFXX_LIBRARY_DEBUG
19327 the path to the TIFFXX library for debug configurations
19328 New in version 3.4: Debug and Release variants are found separately.
19330 FindUnixCommands
19333 Find Unix commands, including the ones from Cygwin
19334 This module looks for the Unix commands bash, cp, gzip, mv, rm, and tar
19336 and stores the result in the variables BASH, CP, GZIP, MV, RM, and TAR.
19337 FindVTK
19339 This module no longer exists.
19340 This module existed in versions of CMake prior to 3.1, but became only
19342 a thin wrapper around find_package(VTK NO_MODULE) to provide compati‐
19343 bility for projects using long-outdated conventions. Now find_pack‐
19344 age(VTK) will search for VTKConfig.cmake directly.
19345 FindVulkan
19347 New in version 3.7.
19348 Find Vulkan, which is a low-overhead, cross-platform 3D graphics and
19351 computing API.
19352 Optional COMPONENTS
19354 New in version 3.24.
19355 This module respects several optional COMPONENTS. There are corre‐
19358 sponding imported targets for each of these.
19359 glslc The SPIR-V compiler.
19361 glslangValidator
19363 The glslangValidator tool.
19364 glslang
19366 The SPIR-V generator library.
19367 shaderc_combined
19369 The static library for Vulkan shader compilation.
19370 SPIRV-Tools
19372 Tools to process SPIR-V modules.
19373 MoltenVK
19375 On macOS, an additional component MoltenVK is available.
19376 dxc New in version 3.25.
19378 The DirectX Shader Compiler.
19381 The glslc and glslangValidator components are provided even if not ex‐
19383 plicitly requested (for backward compatibility).
19384 IMPORTED Targets
19386 This module defines IMPORTED targets if Vulkan has been found:
19387 Vulkan::Vulkan
19389 The main Vulkan library.
19390 Vulkan::glslc
19392 New in version 3.19.
19393 The GLSLC SPIR-V compiler, if it has been found.
19396 Vulkan::Headers
19398 New in version 3.21.
19399 Provides just Vulkan headers include paths, if found. No li‐
19402 brary is included in this target. This can be useful for appli‐
19403 cations that load Vulkan library dynamically.
19404 Vulkan::glslangValidator
19406 New in version 3.21.
19407 The glslangValidator tool, if found. It is used to compile GLSL
19410 and HLSL shaders into SPIR-V.
19411 Vulkan::glslang
19413 New in version 3.24.
19414 Defined if SDK has the Khronos-reference front-end shader parser
19417 and SPIR-V generator library (glslang).
19418 Vulkan::shaderc_combined
19420 New in version 3.24.
19421 Defined if SDK has the Google static library for Vulkan shader
19424 compilation (shaderc_combined).
19425 Vulkan::SPIRV-Tools
19427 New in version 3.24.
19428 Defined if SDK has the Khronos library to process SPIR-V modules
19431 (SPIRV-Tools).
19432 Vulkan::MoltenVK
19434 New in version 3.24.
19435 Defined if SDK has the Khronos library which implement a subset
19438 of Vulkan API over Apple Metal graphics framework. (MoltenVK).
19439 Vulkan::volk
19441 New in version 3.25.
19442 Defined if SDK has the Vulkan meta-loader (volk).
19445 Vulkan::dxc_lib
19447 New in version 3.25.
19448 Defined if SDK has the DirectX shader compiler library.
19451 Vulkan::dxc_exe
19453 New in version 3.25.
19454 Defined if SDK has the DirectX shader compiler CLI tool.
19457 Result Variables
19459 This module defines the following variables:
19460 Vulkan_FOUND
19462 set to true if Vulkan was found
19463 Vulkan_INCLUDE_DIRS
19465 include directories for Vulkan
19466 Vulkan_LIBRARIES
19468 link against this library to use Vulkan
19469 Vulkan_VERSION
19471 New in version 3.23.
19472 value from vulkan/vulkan_core.h
19475 Vulkan_glslc_FOUND
19477 New in version 3.24.
19478 True, if the SDK has the glslc executable.
19481 Vulkan_glslangValidator_FOUND
19483 New in version 3.24.
19484 True, if the SDK has the glslangValidator executable.
19487 Vulkan_glslang_FOUND
19489 New in version 3.24.
19490 True, if the SDK has the glslang library.
19493 Vulkan_shaderc_combined_FOUND
19495 New in version 3.24.
19496 True, if the SDK has the shaderc_combined library.
19499 Vulkan_SPIRV-Tools_FOUND
19501 New in version 3.24.
19502 True, if the SDK has the SPIRV-Tools library.
19505 Vulkan_MoltenVK_FOUND
19507 New in version 3.24.
19508 True, if the SDK has the MoltenVK library.
19511 Vulkan_volk_FOUND
19513 New in version 3.25.
19514 True, if the SDK has the volk library.
19517 Vulkan_dxc_lib_FOUND
19519 New in version 3.25.
19520 True, if the SDK has the DirectX shader compiler library.
19523 Vulkan_dxc_exe_FOUND
19525 New in version 3.25.
19526 True, if the SDK has the DirectX shader compiler CLI tool.
19529 The module will also defines these cache variables:
19531 Vulkan_INCLUDE_DIR
19533 the Vulkan include directory
19534 Vulkan_LIBRARY
19536 the path to the Vulkan library
19537 Vulkan_GLSLC_EXECUTABLE
19539 the path to the GLSL SPIR-V compiler
19540 Vulkan_GLSLANG_VALIDATOR_EXECUTABLE
19542 the path to the glslangValidator tool
19543 Vulkan_glslang_LIBRARY
19545 New in version 3.24.
19546 Path to the glslang library.
19549 Vulkan_shaderc_combined_LIBRARY
19551 New in version 3.24.
19552 Path to the shaderc_combined library.
19555 Vulkan_SPIRV-Tools_LIBRARY
19557 New in version 3.24.
19558 Path to the SPIRV-Tools library.
19561 Vulkan_MoltenVK_LIBRARY
19563 New in version 3.24.
19564 Path to the MoltenVK library.
19567 Vulkan_volk_LIBRARY
19569 New in version 3.25.
19570 Path to the volk library.
19573 Vulkan_dxc_LIBRARY
19575 New in version 3.25.
19576 Path to the DirectX shader compiler library.
19579 Vulkan_dxc_EXECUTABLE
19581 New in version 3.25.
19582 Path to the DirectX shader compiler CLI tool.
19585 Hints
19587 New in version 3.18.
19588 The VULKAN_SDK environment variable optionally specifies the location
19591 of the Vulkan SDK root directory for the given architecture. It is typ‐
19592 ically set by sourcing the toplevel setup-env.sh script of the Vulkan
19593 SDK directory into the shell environment.
19594 FindWget
19596 Find wget
19597 This module looks for wget. This module defines the following values:
19599 WGET_EXECUTABLE: the full path to the wget tool.
19601 WGET_FOUND: True if wget has been found.
19602 FindWish
19604 Find wish installation
19605 This module finds if TCL is installed and determines where the include
19607 files and libraries are. It also determines what the name of the li‐
19608 brary is. This code sets the following variables:
19609 TK_WISH = the path to the wish executable
19611 if UNIX is defined, then it will look for the cygwin version first
19613 FindwxWidgets
19615 Find a wxWidgets (a.k.a., wxWindows) installation.
19616 This module finds if wxWidgets is installed and selects a default con‐
19618 figuration to use. wxWidgets is a modular library. To specify the
19619 modules that you will use, you need to name them as components to the
19620 package:
19621 find_package(wxWidgets COMPONENTS core base ... OPTIONAL_COMPONENTS net
19623 ...)
19624 New in version 3.4: Support for find_package() version argument; web‐
19626 view component.
19627 New in version 3.14: OPTIONAL_COMPONENTS support.
19630 There are two search branches: a windows style and a unix style. For
19633 windows, the following variables are searched for and set to defaults
19634 in case of multiple choices. Change them if the defaults are not de‐
19635 sired (i.e., these are the only variables you should change to select a
19636 configuration):
19637 wxWidgets_ROOT_DIR - Base wxWidgets directory
19639 (e.g., C:/wxWidgets-3.2.0).
19640 wxWidgets_LIB_DIR - Path to wxWidgets libraries
19641 (e.g., C:/wxWidgets-3.2.0/lib/vc_x64_lib).
19642 wxWidgets_CONFIGURATION - Configuration to use
19643 (e.g., msw, mswd, mswu, mswunivud, etc.)
19644 wxWidgets_EXCLUDE_COMMON_LIBRARIES
19645 - Set to TRUE to exclude linking of
19646 commonly required libs (e.g., png tiff
19647 jpeg zlib regex expat).
19648 For unix style it uses the wx-config utility. You can select between
19650 debug/release, unicode/ansi, universal/non-universal, and static/shared
19651 in the QtDialog or ccmake interfaces by turning ON/OFF the following
19652 variables:
19653 wxWidgets_USE_DEBUG
19655 wxWidgets_USE_UNICODE
19656 wxWidgets_USE_UNIVERSAL
19657 wxWidgets_USE_STATIC
19658 There is also a wxWidgets_CONFIG_OPTIONS variable for all other options
19660 that need to be passed to the wx-config utility. For example, to use
19661 the base toolkit found in the /usr/local path, set the variable (before
19662 calling the FIND_PACKAGE command) as such:
19663 set(wxWidgets_CONFIG_OPTIONS --toolkit=base --prefix=/usr)
19665 The following are set after the configuration is done for both windows
19667 and unix style:
19668 wxWidgets_FOUND - Set to TRUE if wxWidgets was found.
19670 wxWidgets_INCLUDE_DIRS - Include directories for WIN32
19671 i.e., where to find "wx/wx.h" and
19672 "wx/setup.h"; possibly empty for unices.
19673 wxWidgets_LIBRARIES - Path to the wxWidgets libraries.
19674 wxWidgets_LIBRARY_DIRS - compile time link dirs, useful for
19675 rpath on UNIX. Typically an empty string
19676 in WIN32 environment.
19677 wxWidgets_DEFINITIONS - Contains defines required to compile/link
19678 against WX, e.g. WXUSINGDLL
19679 wxWidgets_DEFINITIONS_DEBUG- Contains defines required to compile/link
19680 against WX debug builds, e.g. __WXDEBUG__
19681 wxWidgets_CXX_FLAGS - Include dirs and compiler flags for
19682 unices, empty on WIN32. Essentially
19683 "`wx-config --cxxflags`".
19684 wxWidgets_USE_FILE - Convenience include file.
19685 New in version 3.11: The following environment variables can be used as
19687 hints: WX_CONFIG, WXRC_CMD.
19688 Sample usage:
19691 # Note that for MinGW users the order of libs is important!
19693 find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net)
19694 if(wxWidgets_FOUND)
19695 include(${wxWidgets_USE_FILE})
19696 # and for each of your dependent executable/library targets:
19697 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
19698 endif()
19699 If wxWidgets is required (i.e., not an optional part):
19701 find_package(wxWidgets REQUIRED gl core base OPTIONAL_COMPONENTS net)
19703 include(${wxWidgets_USE_FILE})
19704 # and for each of your dependent executable/library targets:
19705 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
19706 FindX11
19708 Find X11 installation
19709 Try to find X11 on UNIX systems. The following values are defined
19711 X11_FOUND - True if X11 is available
19713 X11_INCLUDE_DIR - include directories to use X11
19714 X11_LIBRARIES - link against these to use X11
19715 and also the following more fine grained variables and targets:
19717 New in version 3.14: Imported targets.
19719 X11_ICE_INCLUDE_PATH, X11_ICE_LIB, X11_ICE_FOUND, X11::ICE
19722 X11_SM_INCLUDE_PATH, X11_SM_LIB, X11_SM_FOUND, X11::SM
19723 X11_X11_INCLUDE_PATH, X11_X11_LIB, X11::X11
19724 X11_Xaccessrules_INCLUDE_PATH,
19725 X11_Xaccessstr_INCLUDE_PATH, X11_Xaccess_FOUND
19726 X11_Xau_INCLUDE_PATH, X11_Xau_LIB, X11_Xau_FOUND, X11::Xau
19727 X11_xcb_INCLUDE_PATH, X11_xcb_LIB, X11_xcb_FOUND, X11::xcb
19728 X11_X11_xcb_INCLUDE_PATH, X11_X11_xcb_LIB, X11_X11_xcb_FOUND, X11::X11_xcb
19729 X11_xcb_icccm_INCLUDE_PATH, X11_xcb_icccm_LIB, X11_xcb_icccm_FOUND, X11::xcb_icccm
19730 X11_xcb_randr_INCLUDE_PATH, X11_xcb_randr_LIB, X11_xcb_randr_FOUND, X11::xcb_randr
19731 X11_xcb_util_INCLUDE_PATH, X11_xcb_util_LIB, X11_xcb_util_FOUND, X11::xcb_util
19732 X11_xcb_xfixes_INCLUDE_PATH, X11_xcb_xfixes_LIB, X11_xcb_xfixes_FOUND, X11::xcb_xfixes
19733 X11_xcb_xtest_INCLUDE_PATH, X11_xcb_xtest_LIB, X11_xcb_xtest_FOUND, X11::xcb_xtest
19734 X11_xcb_keysyms_INCLUDE_PATH, X11_xcb_keysyms_LIB,X11_xcb_keysyms_FOUND,X11::xcb_keysyms
19735 X11_xcb_xkb_INCLUDE_PATH, X11_xcb_xkb_LIB, X11_xcb_xkb_FOUND, X11::xcb_xkb
19736 X11_Xcomposite_INCLUDE_PATH, X11_Xcomposite_LIB, X11_Xcomposite_FOUND, X11::Xcomposite
19737 X11_Xcursor_INCLUDE_PATH, X11_Xcursor_LIB, X11_Xcursor_FOUND, X11::Xcursor
19738 X11_Xdamage_INCLUDE_PATH, X11_Xdamage_LIB, X11_Xdamage_FOUND, X11::Xdamage
19739 X11_Xdmcp_INCLUDE_PATH, X11_Xdmcp_LIB, X11_Xdmcp_FOUND, X11::Xdmcp
19740 X11_Xext_INCLUDE_PATH, X11_Xext_LIB, X11_Xext_FOUND, X11::Xext
19741 X11_Xxf86misc_INCLUDE_PATH, X11_Xxf86misc_LIB, X11_Xxf86misc_FOUND, X11::Xxf86misc
19742 X11_Xxf86vm_INCLUDE_PATH, X11_Xxf86vm_LIB X11_Xxf86vm_FOUND, X11::Xxf86vm
19743 X11_Xfixes_INCLUDE_PATH, X11_Xfixes_LIB, X11_Xfixes_FOUND, X11::Xfixes
19744 X11_Xft_INCLUDE_PATH, X11_Xft_LIB, X11_Xft_FOUND, X11::Xft
19745 X11_Xi_INCLUDE_PATH, X11_Xi_LIB, X11_Xi_FOUND, X11::Xi
19746 X11_Xinerama_INCLUDE_PATH, X11_Xinerama_LIB, X11_Xinerama_FOUND, X11::Xinerama
19747 X11_Xkb_INCLUDE_PATH,
19748 X11_Xkblib_INCLUDE_PATH, X11_Xkb_FOUND, X11::Xkb
19749 X11_xkbcommon_INCLUDE_PATH, X11_xkbcommon_LIB, X11_xkbcommon_FOUND, X11::xkbcommon
19750 X11_xkbcommon_X11_INCLUDE_PATH,X11_xkbcommon_X11_LIB,X11_xkbcommon_X11_FOUND,X11::xkbcommon_X11
19751 X11_xkbfile_INCLUDE_PATH, X11_xkbfile_LIB, X11_xkbfile_FOUND, X11::xkbfile
19752 X11_Xmu_INCLUDE_PATH, X11_Xmu_LIB, X11_Xmu_FOUND, X11::Xmu
19753 X11_Xpm_INCLUDE_PATH, X11_Xpm_LIB, X11_Xpm_FOUND, X11::Xpm
19754 X11_Xtst_INCLUDE_PATH, X11_Xtst_LIB, X11_Xtst_FOUND, X11::Xtst
19755 X11_Xrandr_INCLUDE_PATH, X11_Xrandr_LIB, X11_Xrandr_FOUND, X11::Xrandr
19756 X11_Xrender_INCLUDE_PATH, X11_Xrender_LIB, X11_Xrender_FOUND, X11::Xrender
19757 X11_XRes_INCLUDE_PATH, X11_XRes_LIB, X11_XRes_FOUND, X11::XRes
19758 X11_Xss_INCLUDE_PATH, X11_Xss_LIB, X11_Xss_FOUND, X11::Xss
19759 X11_Xt_INCLUDE_PATH, X11_Xt_LIB, X11_Xt_FOUND, X11::Xt
19760 X11_Xutil_INCLUDE_PATH, X11_Xutil_FOUND, X11::Xutil
19761 X11_Xv_INCLUDE_PATH, X11_Xv_LIB, X11_Xv_FOUND, X11::Xv
19762 X11_dpms_INCLUDE_PATH, (in X11_Xext_LIB), X11_dpms_FOUND
19763 X11_XShm_INCLUDE_PATH, (in X11_Xext_LIB), X11_XShm_FOUND
19764 X11_Xshape_INCLUDE_PATH, (in X11_Xext_LIB), X11_Xshape_FOUND
19765 X11_XSync_INCLUDE_PATH, (in X11_Xext_LIB), X11_XSync_FOUND
19766 X11_Xaw_INCLUDE_PATH, X11_Xaw_LIB X11_Xaw_FOUND X11::Xaw
19767 New in version 3.14: Renamed Xxf86misc, X11_Xxf86misc, X11_Xxf86vm,
19769 X11_xkbfile, X11_Xtst, and X11_Xss libraries to match their file names.
19770 Deprecated the X11_Xinput library. Old names are still available for
19771 compatibility.
19772 New in version 3.14: Added the X11_Xext_INCLUDE_PATH variable.
19775 New in version 3.18: Added the xcb, X11-xcb, xcb-icccm, xcb-xkb, xkb‐
19778 common, and xkbcommon-X11 libraries.
19779 New in version 3.19: Added the Xaw, xcb_util, and xcb_xfixes libraries.
19782 New in version 3.24: Added the xcb_randr, xcb_xtext, and xcb_keysyms
19785 libraries.
19786 FindXalanC
19789 New in version 3.5.
19790 Find the Apache Xalan-C++ XSL transform processor headers and li‐
19793 braries.
19794 Imported targets
19796 This module defines the following IMPORTED targets:
19797 XalanC::XalanC
19799 The Xalan-C++ xalan-c library, if found.
19800 Result variables
19802 This module will set the following variables in your project:
19803 XalanC_FOUND
19805 true if the Xalan headers and libraries were found
19806 XalanC_VERSION
19808 Xalan release version
19809 XalanC_INCLUDE_DIRS
19811 the directory containing the Xalan headers; note XercesC_IN‐
19812 CLUDE_DIRS is also required
19813 XalanC_LIBRARIES
19815 Xalan libraries to be linked; note XercesC_LIBRARIES is also re‐
19816 quired
19817 Cache variables
19819 The following cache variables may also be set:
19820 XalanC_INCLUDE_DIR
19822 the directory containing the Xalan headers
19823 XalanC_LIBRARY
19825 the Xalan library
19826 FindXCTest
19828 New in version 3.3.
19829 Functions to help creating and executing XCTest bundles.
19832 An XCTest bundle is a CFBundle with a special product-type and bundle
19834 extension. The Mac Developer Library provides more information in the
19835 Testing with Xcode document.
19836 Module Functions
19838 xctest_add_bundle
19839 The xctest_add_bundle function creates a XCTest bundle named
19840 <target> which will test the target <testee>. Supported target
19841 types for testee are Frameworks and App Bundles:
19842 xctest_add_bundle(
19844 <target> # Name of the XCTest bundle
19845 <testee> # Target name of the testee
19846 )
19847 xctest_add_test
19849 The xctest_add_test function adds an XCTest bundle to the
19850 project to be run by ctest(1). The test will be named <name> and
19851 tests <bundle>:
19852 xctest_add_test(
19854 <name> # Test name
19855 <bundle> # Target name of XCTest bundle
19856 )
19857 Module Variables
19859 The following variables are set by including this module:
19860 XCTest_FOUND
19862 True if the XCTest Framework and executable were found.
19863 XCTest_EXECUTABLE
19865 The path to the xctest command line tool used to execute XCTest
19866 bundles.
19867 XCTest_INCLUDE_DIRS
19869 The directory containing the XCTest Framework headers.
19870 XCTest_LIBRARIES
19872 The location of the XCTest Framework.
19873 FindXercesC
19875 New in version 3.1.
19876 Find the Apache Xerces-C++ validating XML parser headers and libraries.
19879 Imported targets
19881 New in version 3.5.
19882 This module defines the following IMPORTED targets:
19885 XercesC::XercesC
19887 The Xerces-C++ xerces-c library, if found.
19888 Result variables
19890 This module will set the following variables in your project:
19891 XercesC_FOUND
19893 true if the Xerces headers and libraries were found
19894 XercesC_VERSION
19896 Xerces release version
19897 XercesC_INCLUDE_DIRS
19899 the directory containing the Xerces headers
19900 XercesC_LIBRARIES
19902 Xerces libraries to be linked
19903 Cache variables
19905 The following cache variables may also be set:
19906 XercesC_INCLUDE_DIR
19908 the directory containing the Xerces headers
19909 XercesC_LIBRARY
19911 the Xerces library
19912 New in version 3.4: Debug and Release variants are found separately.
19914 FindXMLRPC
19917 Find xmlrpc
19918 Find the native XMLRPC headers and libraries.
19920 XMLRPC_INCLUDE_DIRS - where to find xmlrpc.h, etc.
19922 XMLRPC_LIBRARIES - List of libraries when using xmlrpc.
19923 XMLRPC_FOUND - True if xmlrpc found.
19924 XMLRPC modules may be specified as components for this find module.
19926 Modules may be listed by running "xmlrpc-c-config". Modules include:
19927 c++ C++ wrapper code
19929 libwww-client libwww-based client
19930 cgi-server CGI-based server
19931 abyss-server ABYSS-based server
19932 Typical usage:
19934 find_package(XMLRPC REQUIRED libwww-client)
19936 FindZLIB
19938 Find the native ZLIB includes and library.
19939 IMPORTED Targets
19941 New in version 3.1.
19942 This module defines IMPORTED target ZLIB::ZLIB, if ZLIB has been found.
19945 Result Variables
19947 This module defines the following variables:
19948 ZLIB_INCLUDE_DIRS - where to find zlib.h, etc.
19950 ZLIB_LIBRARIES - List of libraries when using zlib.
19951 ZLIB_FOUND - True if zlib found.
19952 ZLIB_VERSION_STRING - The version of zlib found (x.y.z)
19954 ZLIB_VERSION_MAJOR - The major version of zlib
19955 ZLIB_VERSION_MINOR - The minor version of zlib
19956 ZLIB_VERSION_PATCH - The patch version of zlib
19957 ZLIB_VERSION_TWEAK - The tweak version of zlib
19958 New in version 3.4: Debug and Release variants are found separately.
19960 Backward Compatibility
19963 The following variable are provided for backward compatibility
19964 ZLIB_MAJOR_VERSION - The major version of zlib
19966 ZLIB_MINOR_VERSION - The minor version of zlib
19967 ZLIB_PATCH_VERSION - The patch version of zlib
19968 Hints
19970 A user may set ZLIB_ROOT to a zlib installation root to tell this mod‐
19971 ule where to look.
19972 New in version 3.24: Set ZLIB_USE_STATIC_LIBS to ON to look for static
19974 libraries. Default is OFF.
19975
19978 Deprecated Utility Modules
19979 AddFileDependencies
19980 Deprecated since version 3.20.
19981 Add dependencies to a source file.
19984 add_file_dependencies(<source> <files>...)
19986 Adds the given <files> to the dependencies of file <source>.
19988 Do not use this command in new code. It is just a wrapper around:
19990 set_property(SOURCE <source> APPEND PROPERTY OBJECT_DEPENDS <files>...)
19992 Instead use the set_property() command to append to the OBJECT_DEPENDS
19994 source file property directly.
19995 CMakeDetermineVSServicePack
19997 Deprecated since version 3.0: Do not use.
19998 The functionality of this module has been superseded by the
20001 CMAKE_<LANG>_COMPILER_VERSION variable that contains the compiler ver‐
20002 sion number.
20003 Determine the Visual Studio service pack of the 'cl' in use.
20005 Usage:
20007 if(MSVC)
20009 include(CMakeDetermineVSServicePack)
20010 DetermineVSServicePack( my_service_pack )
20011 if( my_service_pack )
20012 message(STATUS "Detected: ${my_service_pack}")
20013 endif()
20014 endif()
20015 Function DetermineVSServicePack sets the given variable to one of the
20017 following values or an empty string if unknown:
20018 vc80, vc80sp1
20020 vc90, vc90sp1
20021 vc100, vc100sp1
20022 vc110, vc110sp1, vc110sp2, vc110sp3, vc110sp4
20023 CMakeExpandImportedTargets
20025 Deprecated since version 3.4: Do not use.
20026 This module was once needed to expand imported targets to the underly‐
20029 ing libraries they reference on disk for use with the try_compile() and
20030 try_run() commands. These commands now support imported libraries in
20031 their LINK_LIBRARIES options (since CMake 2.8.11 for try_compile() and
20032 since CMake 3.2 for try_run()).
20033 This module does not support the policy CMP0022 NEW behavior or use of
20035 the INTERFACE_LINK_LIBRARIES property because generator expressions
20036 cannot be evaluated during configuration.
20037 CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
20039 [CONFIGURATION <config>])
20040 CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces
20042 all imported targets contained in this list with their actual file
20043 paths of the referenced libraries on disk, including the libraries from
20044 their link interfaces. If a CONFIGURATION is given, it uses the re‐
20045 spective configuration of the imported targets if it exists. If no
20046 CONFIGURATION is given, it uses the first configuration from
20047 ${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}.
20048 cmake_expand_imported_targets(expandedLibs
20050 LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
20051 CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
20052 CMakeForceCompiler
20054 Deprecated since version 3.6: Do not use.
20055 The macros provided by this module were once intended for use by
20058 cross-compiling toolchain files when CMake was not able to automati‐
20059 cally detect the compiler identification. Since the introduction of
20060 this module, CMake's compiler identification capabilities have improved
20061 and can now be taught to recognize any compiler. Furthermore, the
20062 suite of information CMake detects from a compiler is now too extensive
20063 to be provided by toolchain files using these macros.
20064 One common use case for this module was to skip CMake's checks for a
20066 working compiler when using a cross-compiler that cannot link binaries
20067 without special flags or custom linker scripts. This case is now sup‐
20068 ported by setting the CMAKE_TRY_COMPILE_TARGET_TYPE variable in the
20069 toolchain file instead.
20070 ----
20073 Macro CMAKE_FORCE_C_COMPILER has the following signature:
20077 CMAKE_FORCE_C_COMPILER(<compiler> <compiler-id>)
20079 It sets CMAKE_C_COMPILER to the given compiler and the cmake internal
20081 variable CMAKE_C_COMPILER_ID to the given compiler-id. It also by‐
20082 passes the check for working compiler and basic compiler information
20083 tests.
20084 Macro CMAKE_FORCE_CXX_COMPILER has the following signature:
20086 CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler-id>)
20088 It sets CMAKE_CXX_COMPILER to the given compiler and the cmake internal
20090 variable CMAKE_CXX_COMPILER_ID to the given compiler-id. It also by‐
20091 passes the check for working compiler and basic compiler information
20092 tests.
20093 Macro CMAKE_FORCE_Fortran_COMPILER has the following signature:
20095 CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler-id>)
20097 It sets CMAKE_Fortran_COMPILER to the given compiler and the cmake in‐
20099 ternal variable CMAKE_Fortran_COMPILER_ID to the given compiler-id. It
20100 also bypasses the check for working compiler and basic compiler infor‐
20101 mation tests.
20102 So a simple toolchain file could look like this:
20104 include (CMakeForceCompiler)
20106 set(CMAKE_SYSTEM_NAME Generic)
20107 CMAKE_FORCE_C_COMPILER (chc12 MetrowerksHicross)
20108 CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross)
20109 CMakeParseArguments
20111 This module once implemented the cmake_parse_arguments() command that
20112 is now implemented natively by CMake. It is now an empty placeholder
20113 for compatibility with projects that include it to get the command from
20114 CMake 3.4 and lower.
20115 Documentation
20117 Deprecated since version 3.18: This module does nothing, unless policy
20118 CMP0106 is set to OLD.
20119 This module provides support for the VTK documentation framework. It
20122 relies on several tools (Doxygen, Perl, etc).
20123 MacroAddFileDependencies
20125 Deprecated since version 3.14.
20126 MACRO_ADD_FILE_DEPENDENCIES(<source> <files>...)
20129 Do not use this command in new code. It is just a wrapper around:
20131 set_property(SOURCE <source> APPEND PROPERTY OBJECT_DEPENDS <files>...)
20133 Instead use the set_property() command to append to the OBJECT_DEPENDS
20135 source file property directly.
20136 TestCXXAcceptsFlag
20138 Deprecated since version 3.0: See CheckCXXCompilerFlag.
20139 Check if the CXX compiler accepts a flag.
20142 CHECK_CXX_ACCEPTS_FLAG(<flags> <variable>)
20144 <flags>
20146 the flags to try
20147 <variable>
20149 variable to store the result
20150 UseJavaClassFilelist
20152 Changed in version 3.20: This module was previously documented by mis‐
20153 take and was never meant for direct inclusion by project code. See the
20154 UseJava module.
20155 UseJavaSymlinks
20158 Changed in version 3.20: This module was previously documented by mis‐
20159 take and was never meant for direct inclusion by project code. See the
20160 UseJava module.
20161 UsePkgConfig
20164 Obsolete pkg-config module for CMake, use FindPkgConfig instead.
20165 This module defines the following macro:
20167 PKGCONFIG(package includedir libdir linkflags cflags)
20169 Calling PKGCONFIG will fill the desired information into the 4 given
20171 arguments, e.g. PKGCONFIG(libart-2.0 LIBART_INCLUDE_DIR
20172 LIBART_LINK_DIR LIBART_LINK_FLAGS LIBART_CFLAGS) if pkg-config was NOT
20173 found or the specified software package doesn't exist, the variable
20174 will be empty when the function returns, otherwise they will contain
20175 the respective information
20176 Use_wxWindows
20178 Deprecated since version 2.8.10: Use find_package(wxWidgets) and in‐
20179 clude(${wxWidgets_USE_FILE}) instead.
20180 This convenience include finds if wxWindows is installed and set the
20183 appropriate libs, incdirs, flags etc. author Jan Woetzel <jw -at-
20184 mip.informatik.uni-kiel.de> (07/2003)
20185 USAGE:
20187 just include Use_wxWindows.cmake
20189 in your projects CMakeLists.txt
20190 include( ${CMAKE_MODULE_PATH}/Use_wxWindows.cmake)
20192 if you are sure you need GL then
20194 set(WXWINDOWS_USE_GL 1)
20196 *before* you include this file.
20198 WriteBasicConfigVersionFile
20200 Deprecated since version 3.0: Use the identical command
20201 write_basic_package_version_file() from module
20202 CMakePackageConfigHelpers.
20203 WRITE_BASIC_CONFIG_VERSION_FILE( filename
20206 [VERSION major.minor.patch]
20207 COMPATIBILITY (AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion)
20208 [ARCH_INDEPENDENT]
20209 )
20210 WriteCompilerDetectionHeader
20212 Deprecated since version 3.20: This module is available only if policy
20213 CMP0120 is not set to NEW. Do not use it in new code.
20214 New in version 3.1.
20217 This module provides the function write_compiler_detection_header().
20220 This function can be used to generate a file suitable for preprocessor
20222 inclusion which contains macros to be used in source code:
20223 write_compiler_detection_header(
20225 FILE <file>
20226 PREFIX <prefix>
20227 [OUTPUT_FILES_VAR <output_files_var> OUTPUT_DIR <output_dir>]
20228 COMPILERS <compiler> [...]
20229 FEATURES <feature> [...]
20230 [BARE_FEATURES <feature> [...]]
20231 [VERSION <version>]
20232 [PROLOG <prolog>]
20233 [EPILOG <epilog>]
20234 [ALLOW_UNKNOWN_COMPILERS]
20235 [ALLOW_UNKNOWN_COMPILER_VERSIONS]
20236 )
20237 This generates the file <file> with macros which all have the prefix
20239 <prefix>.
20240 By default, all content is written directly to the <file>. The OUT‐
20242 PUT_FILES_VAR may be specified to cause the compiler-specific content
20243 to be written to separate files. The separate files are then available
20244 in the <output_files_var> and may be consumed by the caller for instal‐
20245 lation for example. The OUTPUT_DIR specifies a relative path from the
20246 main <file> to the compiler-specific files. For example:
20247 write_compiler_detection_header(
20249 FILE climbingstats_compiler_detection.h
20250 PREFIX ClimbingStats
20251 OUTPUT_FILES_VAR support_files
20252 OUTPUT_DIR compilers
20253 COMPILERS GNU Clang MSVC Intel
20254 FEATURES cxx_variadic_templates
20255 )
20256 install(FILES
20257 ${CMAKE_CURRENT_BINARY_DIR}/climbingstats_compiler_detection.h
20258 DESTINATION include
20259 )
20260 install(FILES
20261 ${support_files}
20262 DESTINATION include/compilers
20263 )
20264 VERSION may be used to specify the API version to be generated. Future
20266 versions of CMake may introduce alternative APIs. A given API is se‐
20267 lected by any <version> value greater than or equal to the version of
20268 CMake that introduced the given API and less than the version of CMake
20269 that introduced its succeeding API. The value of the
20270 CMAKE_MINIMUM_REQUIRED_VERSION variable is used if no explicit version
20271 is specified. (As of CMake version 3.25.2 there is only one API ver‐
20272 sion.)
20273 PROLOG may be specified as text content to write at the start of the
20275 header. EPILOG may be specified as text content to write at the end of
20276 the header
20277 At least one <compiler> and one <feature> must be listed. Compilers
20279 which are known to CMake, but not specified are detected and a pre‐
20280 processor #error is generated for them. A preprocessor macro matching
20281 <PREFIX>_COMPILER_IS_<compiler> is generated for each compiler known to
20282 CMake to contain the value 0 or 1.
20283 Possible compiler identifiers are documented with the
20285 CMAKE_<LANG>_COMPILER_ID variable. Available features in this version
20286 of CMake are listed in the CMAKE_C_KNOWN_FEATURES and
20287 CMAKE_CXX_KNOWN_FEATURES global properties. See the
20288 cmake-compile-features(7) manual for information on compile features.
20289 New in version 3.2: Added MSVC and AppleClang compiler support.
20291 New in version 3.6: Added Intel compiler support.
20294 Changed in version 3.8: The {c,cxx}_std_* meta-features are ignored if
20297 requested.
20298 New in version 3.8: ALLOW_UNKNOWN_COMPILERS and ALLOW_UNKNOWN_COM‐
20301 PILER_VERSIONS cause the module to generate conditions that treat un‐
20302 known compilers as simply lacking all features. Without these options
20303 the default behavior is to generate a #error for unknown compilers and
20304 versions.
20305 New in version 3.12: BARE_FEATURES will define the compatibility macros
20308 with the name used in newer versions of the language standard, so the
20309 code can use the new feature name unconditionally.
20310 Feature Test Macros
20313 For each compiler, a preprocessor macro is generated matching <PRE‐
20314 FIX>_COMPILER_IS_<compiler> which has the content either 0 or 1, de‐
20315 pending on the compiler in use. Preprocessor macros for compiler ver‐
20316 sion components are generated matching <PREFIX>_COMPILER_VERSION_MAJOR
20317 <PREFIX>_COMPILER_VERSION_MINOR and <PREFIX>_COMPILER_VERSION_PATCH
20318 containing decimal values for the corresponding compiler version compo‐
20319 nents, if defined.
20320 A preprocessor test is generated based on the compiler version denoting
20322 whether each feature is enabled. A preprocessor macro matching <PRE‐
20323 FIX>_COMPILER_<FEATURE>, where <FEATURE> is the upper-case <feature>
20324 name, is generated to contain the value 0 or 1 depending on whether the
20325 compiler in use supports the feature:
20326 write_compiler_detection_header(
20328 FILE climbingstats_compiler_detection.h
20329 PREFIX ClimbingStats
20330 COMPILERS GNU Clang AppleClang MSVC Intel
20331 FEATURES cxx_variadic_templates
20332 )
20333 #if ClimbingStats_COMPILER_CXX_VARIADIC_TEMPLATES
20335 template<typename... T>
20336 void someInterface(T t...) { /* ... */ }
20337 #else
20338 // Compatibility versions
20339 template<typename T1>
20340 void someInterface(T1 t1) { /* ... */ }
20341 template<typename T1, typename T2>
20342 void someInterface(T1 t1, T2 t2) { /* ... */ }
20343 template<typename T1, typename T2, typename T3>
20344 void someInterface(T1 t1, T2 t2, T3 t3) { /* ... */ }
20345 #endif
20346 Symbol Macros
20348 Some additional symbol-defines are created for particular features for
20349 use as symbols which may be conditionally defined empty:
20350 class MyClass ClimbingStats_FINAL
20352 {
20353 ClimbingStats_CONSTEXPR int someInterface() { return 42; }
20354 };
20355 The ClimbingStats_FINAL macro will expand to final if the compiler (and
20357 its flags) support the cxx_final feature, and the ClimbingStats_CONST‐
20358 EXPR macro will expand to constexpr if cxx_constexpr is supported.
20359 If BARE_FEATURES cxx_final was given as argument the final keyword will
20361 be defined for old compilers, too.
20362 The following features generate corresponding symbol defines and if
20364 they are available as BARE_FEATURES:
20365 ┌──────────────────┬────────────────────┬─────────────┬──────┐
20367 │Feature │ Define │ Symbol │ bare │
20368 ├──────────────────┼────────────────────┼─────────────┼──────┤
20369 │c_restrict │ <PREFIX>_RE‐ │ restrict │ yes │
20370 │ │ STRICT │ │ │
20371 └──────────────────┴────────────────────┴─────────────┴──────┘
20372 │cxx_constexpr │ <PREFIX>_CONST‐ │ constexpr │ yes │
20376 │ │ EXPR │ │ │
20377 ├──────────────────┼────────────────────┼─────────────┼──────┤
20378 │cxx_deleted_func‐ │ <PRE‐ │ = delete │ │
20379 │tions │ FIX>_DELETED_FUNC‐ │ │ │
20380 │ │ TION │ │ │
20381 ├──────────────────┼────────────────────┼─────────────┼──────┤
20382 │cxx_extern_tem‐ │ <PREFIX>_EX‐ │ extern │ │
20383 │plates │ TERN_TEMPLATE │ │ │
20384 ├──────────────────┼────────────────────┼─────────────┼──────┤
20385 │cxx_final │ <PREFIX>_FINAL │ final │ yes │
20386 ├──────────────────┼────────────────────┼─────────────┼──────┤
20387 │cxx_noexcept │ <PREFIX>_NOEXCEPT │ noexcept │ yes │
20388 ├──────────────────┼────────────────────┼─────────────┼──────┤
20389 │cxx_noexcept │ <PREFIX>_NOEX‐ │ noexcept(X) │ │
20390 │ │ CEPT_EXPR(X) │ │ │
20391 ├──────────────────┼────────────────────┼─────────────┼──────┤
20392 │cxx_override │ <PREFIX>_OVERRIDE │ override │ yes │
20393 └──────────────────┴────────────────────┴─────────────┴──────┘
20394 Compatibility Implementation Macros
20396 Some features are suitable for wrapping in a macro with a backward com‐
20397 patibility implementation if the compiler does not support the feature.
20398 When the cxx_static_assert feature is not provided by the compiler, a
20400 compatibility implementation is available via the <PREFIX>_STATIC_AS‐
20401 SERT(COND) and <PREFIX>_STATIC_ASSERT_MSG(COND, MSG) function-like
20402 macros. The macros expand to static_assert where that compiler feature
20403 is available, and to a compatibility implementation otherwise. In the
20404 first form, the condition is stringified in the message field of
20405 static_assert. In the second form, the message MSG is passed to the
20406 message field of static_assert, or ignored if using the backward com‐
20407 patibility implementation.
20408 The cxx_attribute_deprecated feature provides a macro definition <PRE‐
20410 FIX>_DEPRECATED, which expands to either the standard [[deprecated]]
20411 attribute or a compiler-specific decorator such as __attri‐
20412 bute__((__deprecated__)) used by GNU compilers.
20413 The cxx_alignas feature provides a macro definition <PREFIX>_ALIGNAS
20415 which expands to either the standard alignas decorator or a com‐
20416 piler-specific decorator such as __attribute__ ((__aligned__)) used by
20417 GNU compilers.
20418 The cxx_alignof feature provides a macro definition <PREFIX>_ALIGNOF
20420 which expands to either the standard alignof decorator or a com‐
20421 piler-specific decorator such as __alignof__ used by GNU compilers.
20422 ┌─────────────────┬──────────────────┬────────────────┬──────┐
20424 │Feature │ Define │ Symbol │ bare │
20425 ├─────────────────┼──────────────────┼────────────────┼──────┤
20426 │cxx_alignas │ <PREFIX>_ALIGNAS │ alignas │ │
20427 ├─────────────────┼──────────────────┼────────────────┼──────┤
20428 │cxx_alignof │ <PREFIX>_ALIGNOF │ alignof │ │
20429 ├─────────────────┼──────────────────┼────────────────┼──────┤
20430 │cxx_nullptr │ <PREFIX>_NULLPTR │ nullptr │ yes │
20431 ├─────────────────┼──────────────────┼────────────────┼──────┤
20432 │cxx_static_as‐ │ <PRE‐ │ static_assert │ │
20433 │sert │ FIX>_STATIC_AS‐ │ │ │
20434 │ │ SERT │ │ │
20435 ├─────────────────┼──────────────────┼────────────────┼──────┤
20436 │cxx_static_as‐ │ <PRE‐ │ static_assert │ │
20437 │sert │ FIX>_STATIC_AS‐ │ │ │
20438 │ │ SERT_MSG │ │ │
20439 ├─────────────────┼──────────────────┼────────────────┼──────┤
20440 │cxx_attri‐ │ <PREFIX>_DEPRE‐ │ [[deprecated]] │ │
20441 │bute_deprecated │ CATED │ │ │
20442 ├─────────────────┼──────────────────┼────────────────┼──────┤
20443 │cxx_attri‐ │ <PREFIX>_DEPRE‐ │ [[deprecated]] │ │
20444 │bute_deprecated │ CATED_MSG │ │ │
20445 ├─────────────────┼──────────────────┼────────────────┼──────┤
20446 │cxx_thread_local │ <PRE‐ │ thread_local │ │
20447 │ │ FIX>_THREAD_LO‐ │ │ │
20448 │ │ CAL │ │ │
20449 └─────────────────┴──────────────────┴────────────────┴──────┘
20450 A use-case which arises with such deprecation macros is the deprecation
20452 of an entire library. In that case, all public API in the library may
20453 be decorated with the <PREFIX>_DEPRECATED macro. This results in very
20454 noisy build output when building the library itself, so the macro may
20455 be may be defined to empty in that case when building the deprecated
20456 library:
20457 add_library(compat_support ${srcs})
20459 target_compile_definitions(compat_support
20460 PRIVATE
20461 CompatSupport_DEPRECATED=
20462 )
20463 Example Usage
20465 NOTE:
20466 This section was migrated from the cmake-compile-features(7) manual
20467 since it relies on the WriteCompilerDetectionHeader module which is
20468 removed by policy CMP0120.
20469 Compile features may be preferred if available, without creating a hard
20471 requirement. For example, a library may provide alternative implemen‐
20472 tations depending on whether the cxx_variadic_templates feature is
20473 available:
20474 #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES
20476 template<int I, int... Is>
20477 struct Interface;
20478 template<int I>
20480 struct Interface<I>
20481 {
20482 static int accumulate()
20483 {
20484 return I;
20485 }
20486 };
20487 template<int I, int... Is>
20489 struct Interface
20490 {
20491 static int accumulate()
20492 {
20493 return I + Interface<Is...>::accumulate();
20494 }
20495 };
20496 #else
20497 template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
20498 struct Interface
20499 {
20500 static int accumulate() { return I1 + I2 + I3 + I4; }
20501 };
20502 #endif
20503 Such an interface depends on using the correct preprocessor defines for
20505 the compiler features. CMake can generate a header file containing
20506 such defines using the WriteCompilerDetectionHeader module. The module
20507 contains the write_compiler_detection_header function which accepts pa‐
20508 rameters to control the content of the generated header file:
20509 write_compiler_detection_header(
20511 FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
20512 PREFIX Foo
20513 COMPILERS GNU
20514 FEATURES
20515 cxx_variadic_templates
20516 )
20517 Such a header file may be used internally in the source code of a
20519 project, and it may be installed and used in the interface of library
20520 code.
20521 For each feature listed in FEATURES, a preprocessor definition is cre‐
20523 ated in the header file, and defined to either 1 or 0.
20524 Additionally, some features call for additional defines, such as the
20526 cxx_final and cxx_override features. Rather than being used in #ifdef
20527 code, the final keyword is abstracted by a symbol which is defined to
20528 either final, a compiler-specific equivalent, or to empty. That way,
20529 C++ code can be written to unconditionally use the symbol, and compiler
20530 support determines what it is expanded to:
20531 struct Interface {
20533 virtual void Execute() = 0;
20534 };
20535 struct Concrete Foo_FINAL {
20537 void Execute() Foo_OVERRIDE;
20538 };
20539 In this case, Foo_FINAL will expand to final if the compiler supports
20541 the keyword, or to empty otherwise.
20542 In this use-case, the project code may wish to enable a particular lan‐
20544 guage standard if available from the compiler. The CXX_STANDARD target
20545 property may be set to the desired language standard for a particular
20546 target, and the CMAKE_CXX_STANDARD variable may be set to influence all
20547 following targets:
20548 write_compiler_detection_header(
20550 FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
20551 PREFIX Foo
20552 COMPILERS GNU
20553 FEATURES
20554 cxx_final cxx_override
20555 )
20556 # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
20558 # which will expand to 'final' if the compiler supports the requested
20559 # CXX_STANDARD.
20560 add_library(foo foo.cpp)
20561 set_property(TARGET foo PROPERTY CXX_STANDARD 11)
20562 # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
20564 # which will expand to 'final' if the compiler supports the feature,
20565 # even though CXX_STANDARD is not set explicitly. The requirement of
20566 # cxx_constexpr causes CMake to set CXX_STANDARD internally, which
20567 # affects the compile flags.
20568 add_library(foo_impl foo_impl.cpp)
20569 target_compile_features(foo_impl PRIVATE cxx_constexpr)
20570 The write_compiler_detection_header function also creates compatibility
20572 code for other features which have standard equivalents. For example,
20573 the cxx_static_assert feature is emulated with a template and ab‐
20574 stracted via the <PREFIX>_STATIC_ASSERT and <PREFIX>_STATIC_ASSERT_MSG
20575 function-macros.
20576 Deprecated Find Modules
20578 FindCUDA
20579 WARNING:
20580 Deprecated since version 3.10.
20581 It is no longer necessary to use this module or call find_package(CUDA)
20583 for compiling CUDA code. Instead, list CUDA among the languages named
20584 in the top-level call to the project() command, or call the
20585 enable_language() command with CUDA. Then one can add CUDA (.cu)
20586 sources directly to targets similar to other languages.
20587 New in version 3.17: To find and use the CUDA toolkit libraries manu‐
20589 ally, use the FindCUDAToolkit module instead. It works regardless of
20590 the CUDA language being enabled.
20591 Documentation of Deprecated Usage
20594 Tools for building CUDA C files: libraries and build dependencies.
20595 This script locates the NVIDIA CUDA C tools. It should work on Linux,
20597 Windows, and macOS and should be reasonably up to date with CUDA C re‐
20598 leases.
20599 New in version 3.19: QNX support.
20601 This script makes use of the standard find_package() arguments of <VER‐
20604 SION>, REQUIRED and QUIET. CUDA_FOUND will report if an acceptable
20605 version of CUDA was found.
20606 The script will prompt the user to specify CUDA_TOOLKIT_ROOT_DIR if the
20608 prefix cannot be determined by the location of nvcc in the system path
20609 and REQUIRED is specified to find_package(). To use a different in‐
20610 stalled version of the toolkit set the environment variable
20611 CUDA_BIN_PATH before running cmake (e.g. CUDA_BIN_PATH=/usr/lo‐
20612 cal/cuda1.0 instead of the default /usr/local/cuda) or set CUDA_TOOL‐
20613 KIT_ROOT_DIR after configuring. If you change the value of CUDA_TOOL‐
20614 KIT_ROOT_DIR, various components that depend on the path will be relo‐
20615 cated.
20616 It might be necessary to set CUDA_TOOLKIT_ROOT_DIR manually on certain
20618 platforms, or to use a CUDA runtime not installed in the default loca‐
20619 tion. In newer versions of the toolkit the CUDA library is included
20620 with the graphics driver -- be sure that the driver version matches
20621 what is needed by the CUDA runtime version.
20622 Input Variables
20624 The following variables affect the behavior of the macros in the script
20625 (in alphabetical order). Note that any of these flags can be changed
20626 multiple times in the same directory before calling cuda_add_exe‐
20627 cutable(), cuda_add_library(), cuda_compile(), cuda_compile_ptx(),
20628 cuda_compile_fatbin(), cuda_compile_cubin() or cuda_wrap_srcs():
20629 CUDA_64_BIT_DEVICE_CODE (Default: host bit size)
20631 Set to ON to compile for 64 bit device code, OFF for 32 bit de‐
20632 vice code. Note that making this different from the host code
20633 when generating object or C files from CUDA code just won't
20634 work, because size_t gets defined by nvcc in the generated
20635 source. If you compile to PTX and then load the file yourself,
20636 you can mix bit sizes between device and host.
20637 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE (Default: ON)
20639 Set to ON if you want the custom build rule to be attached to
20640 the source file in Visual Studio. Turn OFF if you add the same
20641 cuda file to multiple targets.
20642 This allows the user to build the target from the CUDA file;
20644 however, bad things can happen if the CUDA source file is added
20645 to multiple targets. When performing parallel builds it is pos‐
20646 sible for the custom build command to be run more than once and
20647 in parallel causing cryptic build errors. VS runs the rules for
20648 every source file in the target, and a source can have only one
20649 rule no matter how many projects it is added to. When the rule
20650 is run from multiple targets race conditions can occur on the
20651 generated file. Eventually everything will get built, but if
20652 the user is unaware of this behavior, there may be confusion.
20653 It would be nice if this script could detect the reuse of source
20654 files across multiple targets and turn the option off for the
20655 user, but no good solution could be found.
20656 CUDA_BUILD_CUBIN (Default: OFF)
20658 Set to ON to enable and extra compilation pass with the -cubin
20659 option in Device mode. The output is parsed and register, shared
20660 memory usage is printed during build.
20661 CUDA_BUILD_EMULATION (Default: OFF for device mode)
20663 Set to ON for Emulation mode. -D_DEVICEEMU is defined for CUDA C
20664 files when CUDA_BUILD_EMULATION is TRUE.
20665 CUDA_LINK_LIBRARIES_KEYWORD (Default: "")
20667 New in version 3.9.
20668 The <PRIVATE|PUBLIC|INTERFACE> keyword to use for internal
20671 target_link_libraries() calls. The default is to use no keyword
20672 which uses the old "plain" form of target_link_libraries(). Note
20673 that is matters because whatever is used inside the FindCUDA
20674 module must also be used outside - the two forms of
20675 target_link_libraries() cannot be mixed.
20676 CUDA_GENERATED_OUTPUT_DIR (Default: CMAKE_CURRENT_BINARY_DIR)
20678 Set to the path you wish to have the generated files placed. If
20679 it is blank output files will be placed in
20680 CMAKE_CURRENT_BINARY_DIR. Intermediate files will always be
20681 placed in CMAKE_CURRENT_BINARY_DIR/CMakeFiles.
20682 CUDA_HOST_COMPILATION_CPP (Default: ON)
20684 Set to OFF for C compilation of host code.
20685 CUDA_HOST_COMPILER (Default: CMAKE_C_COMPILER)
20687 Set the host compiler to be used by nvcc. Ignored if -ccbin or
20688 --compiler-bindir is already present in the CUDA_NVCC_FLAGS or
20689 CUDA_NVCC_FLAGS_<CONFIG> variables. For Visual Studio targets,
20690 the host compiler is constructed with one or more visual studio
20691 macros such as $(VCInstallDir), that expands out to the path
20692 when the command is run from within VS.
20693 New in version 3.13: If the CUDAHOSTCXX environment variable is
20695 set it will be used as the default.
20696 CUDA_NVCC_FLAGS, CUDA_NVCC_FLAGS_<CONFIG>
20699 Additional NVCC command line arguments. NOTE: multiple argu‐
20700 ments must be semi-colon delimited (e.g. --compiler-op‐
20701 tions;-Wall)
20702 New in version 3.6: Contents of these variables may use
20704 generator expressions.
20705 CUDA_PROPAGATE_HOST_FLAGS (Default: ON)
20708 Set to ON to propagate CMAKE_{C,CXX}_FLAGS and their configura‐
20709 tion dependent counterparts (e.g. CMAKE_C_FLAGS_DEBUG) automati‐
20710 cally to the host compiler through nvcc's -Xcompiler flag. This
20711 helps make the generated host code match the rest of the system
20712 better. Sometimes certain flags give nvcc problems, and this
20713 will help you turn the flag propagation off. This does not af‐
20714 fect the flags supplied directly to nvcc via CUDA_NVCC_FLAGS or
20715 through the OPTION flags specified through cuda_add_library(),
20716 cuda_add_executable(), or cuda_wrap_srcs(). Flags used for
20717 shared library compilation are not affected by this flag.
20718 CUDA_SEPARABLE_COMPILATION (Default: OFF)
20720 If set this will enable separable compilation for all CUDA run‐
20721 time object files. If used outside of cuda_add_executable() and
20722 cuda_add_library() (e.g. calling cuda_wrap_srcs() directly),
20723 cuda_compute_separable_compilation_object_file_name() and
20724 cuda_link_separable_compilation_objects() should be called.
20725 CUDA_SOURCE_PROPERTY_FORMAT
20727 New in version 3.3.
20728 If this source file property is set, it can override the format
20731 specified to cuda_wrap_srcs() (OBJ, PTX, CUBIN, or FATBIN). If
20732 an input source file is not a .cu file, setting this file will
20733 cause it to be treated as a .cu file. See documentation for
20734 set_source_files_properties on how to set this property.
20735 CUDA_USE_STATIC_CUDA_RUNTIME (Default: ON)
20737 New in version 3.3.
20738 When enabled the static version of the CUDA runtime library will
20741 be used in CUDA_LIBRARIES. If the version of CUDA configured
20742 doesn't support this option, then it will be silently disabled.
20743 CUDA_VERBOSE_BUILD (Default: OFF)
20745 Set to ON to see all the commands used when building the CUDA
20746 file. When using a Makefile generator the value defaults to
20747 VERBOSE (run make VERBOSE=1 to see output), although setting
20748 CUDA_VERBOSE_BUILD to ON will always print the output.
20749 Commands
20751 The script creates the following functions and macros (in alphabetical
20752 order):
20753 cuda_add_cufft_to_target(<cuda_target>)
20755 Adds the cufft library to the target (can be any target). Handles
20757 whether you are in emulation mode or not.
20758 cuda_add_cublas_to_target(<cuda_target>)
20760 Adds the cublas library to the target (can be any target). Handles
20762 whether you are in emulation mode or not.
20763 cuda_add_executable(<cuda_target> <file>...
20765 [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [OPTIONS ...])
20766 Creates an executable <cuda_target> which is made up of the files spec‐
20768 ified. All of the non CUDA C files are compiled using the standard
20769 build rules specified by CMake and the CUDA files are compiled to ob‐
20770 ject files using nvcc and the host compiler. In addition CUDA_IN‐
20771 CLUDE_DIRS is added automatically to include_directories(). Some stan‐
20772 dard CMake target calls can be used on the target after calling this
20773 macro (e.g. set_target_properties() and target_link_libraries()), but
20774 setting properties that adjust compilation flags will not affect code
20775 compiled by nvcc. Such flags should be modified before calling
20776 cuda_add_executable(), cuda_add_library() or cuda_wrap_srcs().
20777 cuda_add_library(<cuda_target> <file>...
20779 [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [OPTIONS ...])
20780 Same as cuda_add_executable() except that a library is created.
20782 cuda_build_clean_target()
20784 Creates a convenience target that deletes all the dependency files gen‐
20786 erated. You should make clean after running this target to ensure the
20787 dependency files get regenerated.
20788 cuda_compile(<generated_files> <file>... [STATIC | SHARED | MODULE]
20790 [OPTIONS ...])
20791 Returns a list of generated files from the input source files to be
20793 used with add_library() or add_executable().
20794 cuda_compile_ptx(<generated_files> <file>... [OPTIONS ...])
20796 Returns a list of PTX files generated from the input source files.
20798 cuda_compile_fatbin(<generated_files> <file>... [OPTIONS ...])
20800 New in version 3.1.
20802 Returns a list of FATBIN files generated from the input source files.
20805 cuda_compile_cubin(<generated_files> <file>... [OPTIONS ...])
20807 New in version 3.1.
20809 Returns a list of CUBIN files generated from the input source files.
20812 cuda_compute_separable_compilation_object_file_name(<output_file_var>
20814 <cuda_target>
20815 <object_files>)
20816 Compute the name of the intermediate link file used for separable com‐
20818 pilation. This file name is typically passed into CUDA_LINK_SEPARA‐
20819 BLE_COMPILATION_OBJECTS. output_file_var is produced based on
20820 cuda_target the list of objects files that need separable compilation
20821 as specified by <object_files>. If the <object_files> list is empty,
20822 then <output_file_var> will be empty. This function is called automat‐
20823 ically for cuda_add_library() and cuda_add_executable(). Note that
20824 this is a function and not a macro.
20825 cuda_include_directories(path0 path1 ...)
20827 Sets the directories that should be passed to nvcc (e.g. nvcc -Ipath0
20829 -Ipath1 ...). These paths usually contain other .cu files.
20830 cuda_link_separable_compilation_objects(<output_file_var> <cuda_target>
20832 <nvcc_flags> <object_files>)
20833 Generates the link object required by separable compilation from the
20835 given object files. This is called automatically for cuda_add_exe‐
20836 cutable() and cuda_add_library(), but can be called manually when using
20837 cuda_wrap_srcs() directly. When called from cuda_add_library() or
20838 cuda_add_executable() the <nvcc_flags> passed in are the same as the
20839 flags passed in via the OPTIONS argument. The only nvcc flag added au‐
20840 tomatically is the bitness flag as specified by CUDA_64_BIT_DE‐
20841 VICE_CODE. Note that this is a function instead of a macro.
20842 cuda_select_nvcc_arch_flags(<out_variable> [<target_CUDA_architecture> ...])
20844 Selects GPU arch flags for nvcc based on target_CUDA_architecture.
20846 Values for target_CUDA_architecture:
20848 • Auto: detects local machine GPU compute arch at runtime.
20850 • Common and All: cover common and entire subsets of architectures.
20852 • <name>: one of Fermi, Kepler, Maxwell, Kepler+Tegra, Kepler+Tesla,
20854 Maxwell+Tegra, Pascal.
20855 • <ver>, <ver>(<ver>), <ver>+PTX, where <ver> is one of 2.0, 2.1, 3.0,
20857 3.2, 3.5, 3.7, 5.0, 5.2, 5.3, 6.0, 6.2.
20858 Returns list of flags to be added to CUDA_NVCC_FLAGS in <out_variable>.
20860 Additionally, sets <out_variable>_readable to the resulting numeric
20861 list.
20862 Example:
20864 cuda_select_nvcc_arch_flags(ARCH_FLAGS 3.0 3.5+PTX 5.2(5.0) Maxwell)
20866 list(APPEND CUDA_NVCC_FLAGS ${ARCH_FLAGS})
20867 More info on CUDA architectures: https://en.wikipedia.org/wiki/CUDA.
20869 Note that this is a function instead of a macro.
20870 cuda_wrap_srcs(<cuda_target> <format> <generated_files> <file>...
20872 [STATIC | SHARED | MODULE] [OPTIONS ...])
20873 This is where all the magic happens. cuda_add_executable(),
20875 cuda_add_library(), cuda_compile(), and cuda_compile_ptx() all call
20876 this function under the hood.
20877 Given the list of files <file>... this macro generates custom commands
20879 that generate either PTX or linkable objects (use PTX or OBJ for the
20880 <format> argument to switch). Files that don't end with .cu or have
20881 the HEADER_FILE_ONLY property are ignored.
20882 The arguments passed in after OPTIONS are extra command line options to
20884 give to nvcc. You can also specify per configuration options by speci‐
20885 fying the name of the configuration followed by the options. General
20886 options must precede configuration specific options. Not all configu‐
20887 rations need to be specified, only the ones provided will be used. For
20888 example:
20889 cuda_add_executable(...
20891 OPTIONS -DFLAG=2 "-DFLAG_OTHER=space in flag"
20892 DEBUG -g
20893 RELEASE --use_fast_math
20894 RELWITHDEBINFO --use_fast_math;-g
20895 MINSIZEREL --use_fast_math)
20896 For certain configurations (namely VS generating object files with
20898 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE set to ON), no generated file
20899 will be produced for the given cuda file. This is because when you add
20900 the cuda file to Visual Studio it knows that this file produces an ob‐
20901 ject file and will link in the resulting object file automatically.
20902 This script will also generate a separate cmake script that is used at
20904 build time to invoke nvcc. This is for several reasons:
20905 • nvcc can return negative numbers as return values which confuses Vis‐
20907 ual Studio into thinking that the command succeeded. The script now
20908 checks the error codes and produces errors when there was a problem.
20909 • nvcc has been known to not delete incomplete results when it encoun‐
20911 ters problems. This confuses build systems into thinking the target
20912 was generated when in fact an unusable file exists. The script now
20913 deletes the output files if there was an error.
20914 • By putting all the options that affect the build into a file and then
20916 make the build rule dependent on the file, the output files will be
20917 regenerated when the options change.
20918 This script also looks at optional arguments STATIC, SHARED, or MODULE
20920 to determine when to target the object compilation for a shared li‐
20921 brary. BUILD_SHARED_LIBS is ignored in cuda_wrap_srcs(), but it is re‐
20922 spected in cuda_add_library(). On some systems special flags are added
20923 for building objects intended for shared libraries. A preprocessor
20924 macro, <target_name>_EXPORTS is defined when a shared library compila‐
20925 tion is detected.
20926 Flags passed into add_definitions with -D or /D are passed along to
20928 nvcc.
20929 Result Variables
20931 The script defines the following variables:
20932 CUDA_VERSION_MAJOR
20934 The major version of cuda as reported by nvcc.
20935 CUDA_VERSION_MINOR
20937 The minor version.
20938 CUDA_VERSION, CUDA_VERSION_STRING
20940 Full version in the X.Y format.
20941 CUDA_HAS_FP16
20943 New in version 3.6: Whether a short float (float16, fp16) is
20944 supported.
20945 CUDA_TOOLKIT_ROOT_DIR
20948 Path to the CUDA Toolkit (defined if not set).
20949 CUDA_SDK_ROOT_DIR
20951 Path to the CUDA SDK. Use this to find files in the SDK. This
20952 script will not directly support finding specific libraries or
20953 headers, as that isn't supported by NVIDIA. If you want to
20954 change libraries when the path changes see the FindCUDA.cmake
20955 script for an example of how to clear these variables. There
20956 are also examples of how to use the CUDA_SDK_ROOT_DIR to locate
20957 headers or libraries, if you so choose (at your own risk).
20958 CUDA_INCLUDE_DIRS
20960 Include directory for cuda headers. Added automatically for
20961 cuda_add_executable() and cuda_add_library().
20962 CUDA_LIBRARIES
20964 Cuda RT library.
20965 CUDA_CUFFT_LIBRARIES
20967 Device or emulation library for the Cuda FFT implementation (al‐
20968 ternative to cuda_add_cufft_to_target() macro)
20969 CUDA_CUBLAS_LIBRARIES
20971 Device or emulation library for the Cuda BLAS implementation
20972 (alternative to cuda_add_cublas_to_target() macro).
20973 CUDA_cudart_static_LIBRARY
20975 Statically linkable cuda runtime library. Only available for
20976 CUDA version 5.5+.
20977 CUDA_cudadevrt_LIBRARY
20979 New in version 3.7: Device runtime library. Required for sepa‐
20980 rable compilation.
20981 CUDA_cupti_LIBRARY
20984 CUDA Profiling Tools Interface library. Only available for CUDA
20985 version 4.0+.
20986 CUDA_curand_LIBRARY
20988 CUDA Random Number Generation library. Only available for CUDA
20989 version 3.2+.
20990 CUDA_cusolver_LIBRARY
20992 New in version 3.2: CUDA Direct Solver library. Only available
20993 for CUDA version 7.0+.
20994 CUDA_cusparse_LIBRARY
20997 CUDA Sparse Matrix library. Only available for CUDA version
20998 3.2+.
20999 CUDA_npp_LIBRARY
21001 NVIDIA Performance Primitives lib. Only available for CUDA ver‐
21002 sion 4.0+.
21003 CUDA_nppc_LIBRARY
21005 NVIDIA Performance Primitives lib (core). Only available for
21006 CUDA version 5.5+.
21007 CUDA_nppi_LIBRARY
21009 NVIDIA Performance Primitives lib (image processing). Only
21010 available for CUDA version 5.5 - 8.0.
21011 CUDA_nppial_LIBRARY
21013 NVIDIA Performance Primitives lib (image processing). Only
21014 available for CUDA version 9.0.
21015 CUDA_nppicc_LIBRARY
21017 NVIDIA Performance Primitives lib (image processing). Only
21018 available for CUDA version 9.0.
21019 CUDA_nppicom_LIBRARY
21021 NVIDIA Performance Primitives lib (image processing). Only
21022 available for CUDA version 9.0 - 10.2. Replaced by nvjpeg.
21023 CUDA_nppidei_LIBRARY
21025 NVIDIA Performance Primitives lib (image processing). Only
21026 available for CUDA version 9.0.
21027 CUDA_nppif_LIBRARY
21029 NVIDIA Performance Primitives lib (image processing). Only
21030 available for CUDA version 9.0.
21031 CUDA_nppig_LIBRARY
21033 NVIDIA Performance Primitives lib (image processing). Only
21034 available for CUDA version 9.0.
21035 CUDA_nppim_LIBRARY
21037 NVIDIA Performance Primitives lib (image processing). Only
21038 available for CUDA version 9.0.
21039 CUDA_nppist_LIBRARY
21041 NVIDIA Performance Primitives lib (image processing). Only
21042 available for CUDA version 9.0.
21043 CUDA_nppisu_LIBRARY
21045 NVIDIA Performance Primitives lib (image processing). Only
21046 available for CUDA version 9.0.
21047 CUDA_nppitc_LIBRARY
21049 NVIDIA Performance Primitives lib (image processing). Only
21050 available for CUDA version 9.0.
21051 CUDA_npps_LIBRARY
21053 NVIDIA Performance Primitives lib (signal processing). Only
21054 available for CUDA version 5.5+.
21055 CUDA_nvcuvenc_LIBRARY
21057 CUDA Video Encoder library. Only available for CUDA version
21058 3.2+. Windows only.
21059 CUDA_nvcuvid_LIBRARY
21061 CUDA Video Decoder library. Only available for CUDA version
21062 3.2+. Windows only.
21063 CUDA_nvToolsExt_LIBRARY
21065 New in version 3.16: NVIDA CUDA Tools Extension library. Avail‐
21066 able for CUDA version 5+.
21067 CUDA_OpenCL_LIBRARY
21070 New in version 3.16: NVIDA CUDA OpenCL library. Available for
21071 CUDA version 5+.
21072 FindPythonInterp
21075 Deprecated since version 3.12: Use FindPython3, FindPython2 or
21076 FindPython instead.
21077 Find python interpreter
21080 This module finds if Python interpreter is installed and determines
21082 where the executables are. This code sets the following variables:
21083 PYTHONINTERP_FOUND - Was the Python executable found
21085 PYTHON_EXECUTABLE - path to the Python interpreter
21086 PYTHON_VERSION_STRING - Python version found e.g. 2.5.2
21088 PYTHON_VERSION_MAJOR - Python major version found e.g. 2
21089 PYTHON_VERSION_MINOR - Python minor version found e.g. 5
21090 PYTHON_VERSION_PATCH - Python patch version found e.g. 2
21091 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
21093 of version numbers that should be taken into account when searching for
21094 Python. You need to set this variable before calling find_pack‐
21095 age(PythonInterp).
21096 If calling both find_package(PythonInterp) and find_package(Python‐
21098 Libs), call find_package(PythonInterp) first to get the currently ac‐
21099 tive Python version by default with a consistent version of PYTHON_LI‐
21100 BRARIES.
21101 NOTE:
21103 A call to find_package(PythonInterp ${V}) for python version V may
21104 find a python executable with no version suffix. In this case no
21105 attempt is made to avoid python executables from other versions.
21106 Use FindPython3, FindPython2 or FindPython instead.
21107 FindPythonLibs
21109 Deprecated since version 3.12: Use FindPython3, FindPython2 or
21110 FindPython instead.
21111 Find python libraries
21114 This module finds if Python is installed and determines where the in‐
21116 clude files and libraries are. It also determines what the name of the
21117 library is. This code sets the following variables:
21118 PYTHONLIBS_FOUND - have the Python libs been found
21120 PYTHON_LIBRARIES - path to the python library
21121 PYTHON_INCLUDE_PATH - path to where Python.h is found (deprecated)
21122 PYTHON_INCLUDE_DIRS - path to where Python.h is found
21123 PYTHON_DEBUG_LIBRARIES - path to the debug library (deprecated)
21124 PYTHONLIBS_VERSION_STRING - version of the Python libs found (since CMake 2.8.8)
21125 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
21127 of version numbers that should be taken into account when searching for
21128 Python. You need to set this variable before calling find_pack‐
21129 age(PythonLibs).
21130 If you'd like to specify the installation of Python to use, you should
21132 modify the following cache variables:
21133 PYTHON_LIBRARY - path to the python library
21135 PYTHON_INCLUDE_DIR - path to where Python.h is found
21136 If calling both find_package(PythonInterp) and find_package(Python‐
21138 Libs), call find_package(PythonInterp) first to get the currently ac‐
21139 tive Python version by default with a consistent version of PYTHON_LI‐
21140 BRARIES.
21141 FindQt
21143 Deprecated since version 3.14: This module is available only if policy
21144 CMP0084 is not set to NEW.
21145 Searches for all installed versions of Qt3 or Qt4.
21148 This module cannot handle Qt5 or any later versions. For those, see
21150 cmake-qt(7).
21151 This module should only be used if your project can work with multiple
21153 versions of Qt. If not, you should just directly use FindQt4 or
21154 FindQt3. If multiple versions of Qt are found on the machine, then The
21155 user must set the option DESIRED_QT_VERSION to the version they want to
21156 use. If only one version of qt is found on the machine, then the DE‐
21157 SIRED_QT_VERSION is set to that version and the matching FindQt3 or
21158 FindQt4 module is included. Once the user sets DESIRED_QT_VERSION,
21159 then the FindQt3 or FindQt4 module is included.
21160 QT_REQUIRED if this is set to TRUE then if CMake can
21162 not find Qt4 or Qt3 an error is raised
21163 and a message is sent to the user.
21164 DESIRED_QT_VERSION OPTION is created
21166 QT4_INSTALLED is set to TRUE if qt4 is found.
21167 QT3_INSTALLED is set to TRUE if qt3 is found.
21168 FindwxWindows
21170 Deprecated since version 3.0: Replaced by FindwxWidgets.
21171 Find wxWindows (wxWidgets) installation
21174 This module finds if wxWindows/wxWidgets is installed and determines
21176 where the include files and libraries are. It also determines what the
21177 name of the library is. This code sets the following variables:
21178 WXWINDOWS_FOUND = system has WxWindows
21180 WXWINDOWS_LIBRARIES = path to the wxWindows libraries
21181 on Unix/Linux with additional
21182 linker flags from
21183 "wx-config --libs"
21184 CMAKE_WXWINDOWS_CXX_FLAGS = Compiler flags for wxWindows,
21185 essentially "`wx-config --cxxflags`"
21186 on Linux
21187 WXWINDOWS_INCLUDE_DIR = where to find "wx/wx.h" and "wx/setup.h"
21188 WXWINDOWS_LINK_DIRECTORIES = link directories, useful for rpath on
21189 Unix
21190 WXWINDOWS_DEFINITIONS = extra defines
21191 OPTIONS If you need OpenGL support please
21193 set(WXWINDOWS_USE_GL 1)
21195 in your CMakeLists.txt before you include this file.
21197 HAVE_ISYSTEM - true required to replace -I by -isystem on g++
21199 For convenience include Use_wxWindows.cmake in your project's CMake‐
21201 Lists.txt using include(${CMAKE_CURRENT_LIST_DIR}/Use_wxWindows.cmake).
21202 USAGE
21204 set(WXWINDOWS_USE_GL 1)
21206 find_package(wxWindows)
21207 NOTES wxWidgets 2.6.x is supported for monolithic builds e.g. compiled
21209 in wx/build/msw dir as:
21210 nmake -f makefile.vc BUILD=debug SHARED=0 USE_OPENGL=1 MONOLITHIC=1
21212 DEPRECATED
21214 CMAKE_WX_CAN_COMPILE
21216 WXWINDOWS_LIBRARY
21217 CMAKE_WX_CXX_FLAGS
21218 WXWINDOWS_INCLUDE_PATH
21219 AUTHOR Jan Woetzel (07/2003-01/2006)
21221 Legacy CPack Modules
21223 These modules used to be mistakenly exposed to the user, and have been
21224 moved out of user visibility. They are for CPack internal use, and
21225 should never be used directly.
21226 CPackArchive
21228 New in version 3.9.
21229 The documentation for the CPack Archive generator has moved here: CPack
21232 Archive Generator
21233 CPackBundle
21235 The documentation for the CPack Bundle generator has moved here: CPack
21236 Bundle Generator
21237 CPackCygwin
21239 The documentation for the CPack Cygwin generator has moved here: CPack
21240 Cygwin Generator
21241 CPackDeb
21243 The documentation for the CPack DEB generator has moved here: CPack DEB
21244 Generator
21245 CPackDMG
21247 The documentation for the CPack DragNDrop generator has moved here:
21248 CPack DragNDrop Generator
21249 CPackFreeBSD
21251 New in version 3.10.
21252 The documentation for the CPack FreeBSD generator has moved here: CPack
21255 FreeBSD Generator
21256 CPackNSIS
21258 The documentation for the CPack NSIS generator has moved here: CPack
21259 NSIS Generator
21260 CPackNuGet
21262 New in version 3.12.
21263 The documentation for the CPack NuGet generator has moved here: CPack
21266 NuGet Generator
21267 CPackProductBuild
21269 New in version 3.7.
21270 The documentation for the CPack productbuild generator has moved here:
21273 CPack productbuild Generator
21274 CPackRPM
21276 The documentation for the CPack RPM generator has moved here: CPack RPM
21277 Generator
21278 CPackWIX
21280 The documentation for the CPack WIX generator has moved here: CPack WIX
21281 Generator
21282
21284 2000-2023 Kitware, Inc. and Contributors
212853.25.2 Jan 19, 2023 CMAKE-MODULES(7)