1CMAKE-MODULES(7) CMake CMAKE-MODULES(7)
2
6 cmake-modules - CMake Modules Reference
7 The modules listed here are part of the CMake distribution. Projects
9 may provide further modules; their location(s) can be specified in the
10 CMAKE_MODULE_PATH variable.
11
13 These modules are loaded using the include() command.
14 AndroidTestUtilities
16 New in version 3.7.
17 Create a test that automatically loads specified data onto an Android
20 device.
21 Introduction
23 Use this module to push data needed for testing an Android device be‐
24 havior onto a connected Android device. The module will accept files
25 and libraries as well as separate destinations for each. It will create
26 a test that loads the files into a device object store and link to them
27 from the specified destination. The files are only uploaded if they are
28 not already in the object store.
29 For example:
31 include(AndroidTestUtilities)
33 android_add_test_data(
34 example_setup_test
35 FILES <files>...
36 LIBS <libs>...
37 DEVICE_TEST_DIR "/data/local/tests/example"
38 DEVICE_OBJECT_STORE "/sdcard/.ExternalData/SHA"
39 )
40 At build time a test named "example_setup_test" will be created. Run
42 this test on the command line with ctest(1) to load the data onto the
43 Android device.
44 Module Functions
46 android_add_test_data
47 android_add_test_data(<test-name>
49 [FILES <files>...] [FILES_DEST <device-dir>]
50 [LIBS <libs>...] [LIBS_DEST <device-dir>]
51 [DEVICE_OBJECT_STORE <device-dir>]
52 [DEVICE_TEST_DIR <device-dir>]
53 [NO_LINK_REGEX <strings>...]
54 )
55 The android_add_test_data function is used to copy files and li‐
57 braries needed to run project-specific tests. On the host oper‐
58 ating system, this is done at build time. For on-device testing,
59 the files are loaded onto the device by the manufactured test at
60 run time.
61 This function accepts the following named parameters:
63 FILES <files>...
65 zero or more files needed for testing
66 LIBS <libs>...
68 zero or more libraries needed for testing
69 FILES_DEST <device-dir>
71 absolute path where the data files are expected to be
72 LIBS_DEST <device-dir>
74 absolute path where the libraries are expected to be
75 DEVICE_OBJECT_STORE <device-dir>
77 absolute path to the location where the data is stored
78 on-device
79 DEVICE_TEST_DIR <device-dir>
81 absolute path to the root directory of the on-device test
82 location
83 NO_LINK_REGEX <strings>...
85 list of regex strings matching the names of files that
86 should be copied from the object store to the testing di‐
87 rectory
88 BundleUtilities
90 Functions to help assemble a standalone bundle application.
91 A collection of CMake utility functions useful for dealing with .app
93 bundles on the Mac and bundle-like directories on any OS.
94 The following functions are provided by this module:
96 fixup_bundle
98 copy_and_fixup_bundle
99 verify_app
100 get_bundle_main_executable
101 get_dotapp_dir
102 get_bundle_and_executable
103 get_bundle_all_executables
104 get_item_key
105 get_item_rpaths
106 clear_bundle_keys
107 set_bundle_key_values
108 get_bundle_keys
109 copy_resolved_item_into_bundle
110 copy_resolved_framework_into_bundle
111 fixup_bundle_item
112 verify_bundle_prerequisites
113 verify_bundle_symlinks
114 Requires CMake 2.6 or greater because it uses function, break and PAR‐
116 ENT_SCOPE. Also depends on GetPrerequisites.cmake.
117 DO NOT USE THESE FUNCTIONS AT CONFIGURE TIME (from CMakeLists.txt)!
119 Instead, invoke them from an install(CODE) or install(SCRIPT) rule.
120 fixup_bundle(<app> <libs> <dirs>)
122 Fix up <app> bundle in-place and make it standalone, such that it can
124 be drag-n-drop copied to another machine and run on that machine as
125 long as all of the system libraries are compatible.
126 If you pass plugins to fixup_bundle as the libs parameter, you should
128 install them or copy them into the bundle before calling fixup_bundle.
129 The <libs> parameter is a list of libraries that must be fixed up, but
130 that cannot be determined by otool output analysis (i.e. plugins).
131 Gather all the keys for all the executables and libraries in a bundle,
133 and then, for each key, copy each prerequisite into the bundle. Then
134 fix each one up according to its own list of prerequisites.
135 Then clear all the keys and call verify_app on the final bundle to en‐
137 sure that it is truly standalone.
138 New in version 3.6: As an optional parameter (IGNORE_ITEM) a list of
140 file names can be passed, which are then ignored (e.g. IGNORE_ITEM
141 "vcredist_x86.exe;vcredist_x64.exe").
142 copy_and_fixup_bundle(<src> <dst> <libs> <dirs>)
145 Makes a copy of the bundle <src> at location <dst> and then fixes up
147 the new copied bundle in-place at <dst>.
148 verify_app(<app>)
150 Verifies that an application <app> appears valid based on running
152 analysis tools on it. Calls message(FATAL_ERROR) if the application is
153 not verified.
154 New in version 3.6: As an optional parameter (IGNORE_ITEM) a list of
156 file names can be passed, which are then ignored (e.g. IGNORE_ITEM
157 "vcredist_x86.exe;vcredist_x64.exe")
158 get_bundle_main_executable(<bundle> <result_var>)
161 The result will be the full path name of the bundle's main executable
163 file or an error: prefixed string if it could not be determined.
164 get_dotapp_dir(<exe> <dotapp_dir_var>)
166 Returns the nearest parent dir whose name ends with .app given the full
168 path to an executable. If there is no such parent dir, then simply re‐
169 turn the dir containing the executable.
170 The returned directory may or may not exist.
172 get_bundle_and_executable(<app> <bundle_var> <executable_var> <valid_var>)
174 Takes either a .app directory name or the name of an executable nested
176 inside a .app directory and returns the path to the .app directory in
177 <bundle_var> and the path to its main executable in <executable_var>.
178 get_bundle_all_executables(<bundle> <exes_var>)
180 Scans <bundle> bundle recursively for all <exes_var> executable files
182 and accumulates them into a variable.
183 get_item_key(<item> <key_var>)
185 Given <item> file name, generate <key_var> key that should be unique
187 considering the set of libraries that need copying or fixing up to make
188 a bundle standalone. This is essentially the file name including ex‐
189 tension with . replaced by _
190 This key is used as a prefix for CMake variables so that we can asso‐
192 ciate a set of variables with a given item based on its key.
193 clear_bundle_keys(<keys_var>)
195 Loop over the <keys_var> list of keys, clearing all the variables asso‐
197 ciated with each key. After the loop, clear the list of keys itself.
198 Caller of get_bundle_keys should call clear_bundle_keys when done with
200 list of keys.
201 set_bundle_key_values(<keys_var> <context> <item> <exepath> <dirs>
203 <copyflag> [<rpaths>])
204 Add <keys_var> key to the list (if necessary) for the given item. If
206 added, also set all the variables associated with that key.
207 get_bundle_keys(<app> <libs> <dirs> <keys_var>)
209 Loop over all the executable and library files within <app> bundle (and
211 given as extra <libs>) and accumulate a list of keys representing them.
212 Set values associated with each key such that we can loop over all of
213 them and copy prerequisite libs into the bundle and then do appropriate
214 install_name_tool fixups.
215 New in version 3.6: As an optional parameter (IGNORE_ITEM) a list of
217 file names can be passed, which are then ignored (e.g. IGNORE_ITEM
218 "vcredist_x86.exe;vcredist_x64.exe")
219 copy_resolved_item_into_bundle(<resolved_item> <resolved_embedded_item>)
222 Copy a resolved item into the bundle if necessary. Copy is not neces‐
224 sary, if the <resolved_item> is "the same as" the <resolved_embed‐
225 ded_item>.
226 copy_resolved_framework_into_bundle(<resolved_item> <resolved_embedded_item>)
228 Copy a resolved framework into the bundle if necessary. Copy is not
230 necessary, if the <resolved_item> is "the same as" the <resolved_embed‐
231 ded_item>.
232 By default, BU_COPY_FULL_FRAMEWORK_CONTENTS is not set. If you want
234 full frameworks embedded in your bundles, set BU_COPY_FULL_FRAME‐
235 WORK_CONTENTS to ON before calling fixup_bundle. By default, COPY_RE‐
236 SOLVED_FRAMEWORK_INTO_BUNDLE copies the framework dylib itself plus the
237 framework Resources directory.
238 fixup_bundle_item(<resolved_embedded_item> <exepath> <dirs>)
240 Get the direct/non-system prerequisites of the <resolved_embed‐
242 ded_item>. For each prerequisite, change the way it is referenced to
243 the value of the _EMBEDDED_ITEM keyed variable for that prerequisite.
244 (Most likely changing to an @executable_path style reference.)
245 This function requires that the <resolved_embedded_item> be inside the
247 bundle already. In other words, if you pass plugins to fixup_bundle as
248 the libs parameter, you should install them or copy them into the bun‐
249 dle before calling fixup_bundle. The libs parameter is a list of li‐
250 braries that must be fixed up, but that cannot be determined by otool
251 output analysis. (i.e., plugins)
252 Also, change the id of the item being fixed up to its own _EMBED‐
254 DED_ITEM value.
255 Accumulate changes in a local variable and make one call to in‐
257 stall_name_tool at the end of the function with all the changes at
258 once.
259 If the BU_CHMOD_BUNDLE_ITEMS variable is set then bundle items will be
261 marked writable before install_name_tool tries to change them.
262 verify_bundle_prerequisites(<bundle> <result_var> <info_var>)
264 Verifies that the sum of all prerequisites of all files inside the bun‐
266 dle are contained within the bundle or are system libraries, presumed
267 to exist everywhere.
268 New in version 3.6: As an optional parameter (IGNORE_ITEM) a list of
270 file names can be passed, which are then ignored (e.g. IGNORE_ITEM
271 "vcredist_x86.exe;vcredist_x64.exe")
272 verify_bundle_symlinks(<bundle> <result_var> <info_var>)
275 Verifies that any symlinks found in the <bundle> bundle point to other
277 files that are already also in the bundle... Anything that points to
278 an external file causes this function to fail the verification.
279 CheckCCompilerFlag
281 Check whether the C compiler supports a given flag.
282 check_c_compiler_flag
284 check_c_compiler_flag(<flag> <var>)
286 Check that the <flag> is accepted by the compiler without a di‐
288 agnostic. Stores the result in an internal cache entry named
289 <var>.
290 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
292 and calls the check_c_source_compiles macro from the CheckCSourceCom‐
293 piles module. See documentation of that module for a listing of vari‐
294 ables that can otherwise modify the build.
295 A positive result from this check indicates only that the compiler did
297 not issue a diagnostic message when given the flag. Whether the flag
298 has any effect or even a specific one is beyond the scope of this mod‐
299 ule.
300 NOTE:
302 Since the try_compile() command forwards flags from variables like
303 CMAKE_C_FLAGS, unknown flags in such variables may cause a false
304 negative for this check.
305 CheckCompilerFlag
307 New in version 3.19.
308 Check whether the compiler supports a given flag.
311 check_compiler_flag
313 check_compiler_flag(<lang> <flag> <var>)
315 Check that the <flag> is accepted by the compiler without a diagnostic.
317 Stores the result in an internal cache entry named <var>.
318 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
320 and calls the check_source_compiles(<LANG>) function from the Check‐
321 SourceCompiles module. See documentation of that module for a listing
322 of variables that can otherwise modify the build.
323 A positive result from this check indicates only that the compiler did
325 not issue a diagnostic message when given the flag. Whether the flag
326 has any effect or even a specific one is beyond the scope of this mod‐
327 ule.
328 NOTE:
330 Since the try_compile() command forwards flags from variables like
331 CMAKE_<LANG>_FLAGS, unknown flags in such variables may cause a
332 false negative for this check.
333 CheckCSourceCompiles
335 Check if given C source compiles and links into an executable.
336 check_c_source_compiles
338 check_c_source_compiles(<code> <resultVar>
340 [FAIL_REGEX <regex1> [<regex2>...]])
341 Check that the source supplied in <code> can be compiled as a C
343 source file and linked as an executable (so it must contain at
344 least a main() function). The result will be stored in the in‐
345 ternal cache variable specified by <resultVar>, with a boolean
346 true value for success and boolean false for failure. If
347 FAIL_REGEX is provided, then failure is determined by checking
348 if anything in the output matches any of the specified regular
349 expressions.
350 The underlying check is performed by the try_compile() command.
352 The compile and link commands can be influenced by setting any
353 of the following variables prior to calling check_c_source_com‐
354 piles():
355 CMAKE_REQUIRED_FLAGS
357 Additional flags to pass to the compiler. Note that the
358 contents of CMAKE_C_FLAGS and its associated configura‐
359 tion-specific variable are automatically added to the
360 compiler command before the contents of CMAKE_RE‐
361 QUIRED_FLAGS.
362 CMAKE_REQUIRED_DEFINITIONS
364 A ;-list of compiler definitions of the form -DFOO or
365 -DFOO=bar. A definition for the name specified by <re‐
366 sultVar> will also be added automatically.
367 CMAKE_REQUIRED_INCLUDES
369 A ;-list of header search paths to pass to the compiler.
370 These will be the only header search paths used by
371 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
372 RIES directory property will be ignored.
373 CMAKE_REQUIRED_LINK_OPTIONS
375 New in version 3.14.
376 A ;-list of options to add to the link command (see
379 try_compile() for further details).
380 CMAKE_REQUIRED_LIBRARIES
382 A ;-list of libraries to add to the link command. These
383 can be the name of system libraries or they can be Im‐
384 ported Targets (see try_compile() for further details).
385 CMAKE_REQUIRED_QUIET
387 New in version 3.1.
388 If this variable evaluates to a boolean true value, all
391 status messages associated with the check will be sup‐
392 pressed.
393 The check is only performed once, with the result cached in the
395 variable named by <resultVar>. Every subsequent CMake run will
396 re-use this cached value rather than performing the check again,
397 even if the <code> changes. In order to force the check to be
398 re-evaluated, the variable named by <resultVar> must be manually
399 removed from the cache.
400 CheckCSourceRuns
402 Check if given C source compiles and links into an executable and can
403 subsequently be run.
404 check_c_source_runs
406 check_c_source_runs(<code> <resultVar>)
408 Check that the source supplied in <code> can be compiled as a C
410 source file, linked as an executable and then run. The <code>
411 must contain at least a main() function. If the <code> could be
412 built and run successfully, the internal cache variable speci‐
413 fied by <resultVar> will be set to 1, otherwise it will be set
414 to an value that evaluates to boolean false (e.g. an empty
415 string or an error message).
416 The underlying check is performed by the try_run() command. The
418 compile and link commands can be influenced by setting any of
419 the following variables prior to calling check_c_source_runs():
420 CMAKE_REQUIRED_FLAGS
422 Additional flags to pass to the compiler. Note that the
423 contents of CMAKE_C_FLAGS and its associated configura‐
424 tion-specific variable are automatically added to the
425 compiler command before the contents of CMAKE_RE‐
426 QUIRED_FLAGS.
427 CMAKE_REQUIRED_DEFINITIONS
429 A ;-list of compiler definitions of the form -DFOO or
430 -DFOO=bar. A definition for the name specified by <re‐
431 sultVar> will also be added automatically.
432 CMAKE_REQUIRED_INCLUDES
434 A ;-list of header search paths to pass to the compiler.
435 These will be the only header search paths used by
436 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
437 directory property will be ignored.
438 CMAKE_REQUIRED_LINK_OPTIONS
440 New in version 3.14.
441 A ;-list of options to add to the link command (see
444 try_run() for further details).
445 CMAKE_REQUIRED_LIBRARIES
447 A ;-list of libraries to add to the link command. These
448 can be the name of system libraries or they can be Im‐
449 ported Targets (see try_run() for further details).
450 CMAKE_REQUIRED_QUIET
452 New in version 3.1.
453 If this variable evaluates to a boolean true value, all
456 status messages associated with the check will be sup‐
457 pressed.
458 The check is only performed once, with the result cached in the
460 variable named by <resultVar>. Every subsequent CMake run will
461 re-use this cached value rather than performing the check again,
462 even if the <code> changes. In order to force the check to be
463 re-evaluated, the variable named by <resultVar> must be manually
464 removed from the cache.
465 CheckCXXCompilerFlag
467 Check whether the CXX compiler supports a given flag.
468 check_cxx_compiler_flag
470 check_cxx_compiler_flag(<flag> <var>)
472 Check that the <flag> is accepted by the compiler without a di‐
474 agnostic. Stores the result in an internal cache entry named
475 <var>.
476 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
478 and calls the check_cxx_source_compiles macro from the CheckCXXSource‐
479 Compiles module. See documentation of that module for a listing of
480 variables that can otherwise modify the build.
481 A positive result from this check indicates only that the compiler did
483 not issue a diagnostic message when given the flag. Whether the flag
484 has any effect or even a specific one is beyond the scope of this mod‐
485 ule.
486 NOTE:
488 Since the try_compile() command forwards flags from variables like
489 CMAKE_CXX_FLAGS, unknown flags in such variables may cause a false
490 negative for this check.
491 CheckCXXSourceCompiles
493 Check if given C++ source compiles and links into an executable.
494 check_cxx_source_compiles
496 check_cxx_source_compiles(<code> <resultVar>
498 [FAIL_REGEX <regex1> [<regex2>...]])
499 Check that the source supplied in <code> can be compiled as a
501 C++ source file and linked as an executable (so it must contain
502 at least a main() function). The result will be stored in the
503 internal cache variable specified by <resultVar>, with a boolean
504 true value for success and boolean false for failure. If
505 FAIL_REGEX is provided, then failure is determined by checking
506 if anything in the output matches any of the specified regular
507 expressions.
508 The underlying check is performed by the try_compile() command.
510 The compile and link commands can be influenced by setting any
511 of the following variables prior to calling
512 check_cxx_source_compiles():
513 CMAKE_REQUIRED_FLAGS
515 Additional flags to pass to the compiler. Note that the
516 contents of CMAKE_CXX_FLAGS and its associated configura‐
517 tion-specific variable are automatically added to the
518 compiler command before the contents of CMAKE_RE‐
519 QUIRED_FLAGS.
520 CMAKE_REQUIRED_DEFINITIONS
522 A ;-list of compiler definitions of the form -DFOO or
523 -DFOO=bar. A definition for the name specified by <re‐
524 sultVar> will also be added automatically.
525 CMAKE_REQUIRED_INCLUDES
527 A ;-list of header search paths to pass to the compiler.
528 These will be the only header search paths used by
529 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
530 RIES directory property will be ignored.
531 CMAKE_REQUIRED_LINK_OPTIONS
533 New in version 3.14.
534 A ;-list of options to add to the link command (see
537 try_compile() for further details).
538 CMAKE_REQUIRED_LIBRARIES
540 A ;-list of libraries to add to the link command. These
541 can be the name of system libraries or they can be Im‐
542 ported Targets (see try_compile() for further details).
543 CMAKE_REQUIRED_QUIET
545 New in version 3.1.
546 If this variable evaluates to a boolean true value, all
549 status messages associated with the check will be sup‐
550 pressed.
551 The check is only performed once, with the result cached in the
553 variable named by <resultVar>. Every subsequent CMake run will
554 re-use this cached value rather than performing the check again,
555 even if the <code> changes. In order to force the check to be
556 re-evaluated, the variable named by <resultVar> must be manually
557 removed from the cache.
558 CheckCXXSourceRuns
560 Check if given C++ source compiles and links into an executable and can
561 subsequently be run.
562 check_cxx_source_runs
564 check_cxx_source_runs(<code> <resultVar>)
566 Check that the source supplied in <code> can be compiled as a
568 C++ source file, linked as an executable and then run. The
569 <code> must contain at least a main() function. If the <code>
570 could be built and run successfully, the internal cache variable
571 specified by <resultVar> will be set to 1, otherwise it will be
572 set to an value that evaluates to boolean false (e.g. an empty
573 string or an error message).
574 The underlying check is performed by the try_run() command. The
576 compile and link commands can be influenced by setting any of
577 the following variables prior to calling
578 check_cxx_source_runs():
579 CMAKE_REQUIRED_FLAGS
581 Additional flags to pass to the compiler. Note that the
582 contents of CMAKE_CXX_FLAGS and its associated configura‐
583 tion-specific variable are automatically added to the
584 compiler command before the contents of CMAKE_RE‐
585 QUIRED_FLAGS.
586 CMAKE_REQUIRED_DEFINITIONS
588 A ;-list of compiler definitions of the form -DFOO or
589 -DFOO=bar. A definition for the name specified by <re‐
590 sultVar> will also be added automatically.
591 CMAKE_REQUIRED_INCLUDES
593 A ;-list of header search paths to pass to the compiler.
594 These will be the only header search paths used by
595 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
596 directory property will be ignored.
597 CMAKE_REQUIRED_LINK_OPTIONS
599 New in version 3.14.
600 A ;-list of options to add to the link command (see
603 try_run() for further details).
604 CMAKE_REQUIRED_LIBRARIES
606 A ;-list of libraries to add to the link command. These
607 can be the name of system libraries or they can be Im‐
608 ported Targets (see try_run() for further details).
609 CMAKE_REQUIRED_QUIET
611 New in version 3.1.
612 If this variable evaluates to a boolean true value, all
615 status messages associated with the check will be sup‐
616 pressed.
617 The check is only performed once, with the result cached in the
619 variable named by <resultVar>. Every subsequent CMake run will
620 re-use this cached value rather than performing the check again,
621 even if the <code> changes. In order to force the check to be
622 re-evaluated, the variable named by <resultVar> must be manually
623 removed from the cache.
624 CheckCXXSymbolExists
626 Check if a symbol exists as a function, variable, or macro in C++.
627 check_cxx_symbol_exists
629 check_cxx_symbol_exists(<symbol> <files> <variable>)
631 Check that the <symbol> is available after including given
633 header <files> and store the result in a <variable>. Specify
634 the list of files in one argument as a semicolon-separated list.
635 check_cxx_symbol_exists() can be used to check for symbols as
636 seen by the C++ compiler, as opposed to check_symbol_exists(),
637 which always uses the C compiler.
638 If the header files define the symbol as a macro it is consid‐
640 ered available and assumed to work. If the header files declare
641 the symbol as a function or variable then the symbol must also
642 be available for linking. If the symbol is a type, enum value,
643 or C++ template it will not be recognized: consider using the
644 CheckTypeSize or CheckSourceCompiles module instead.
645 NOTE:
647 This command is unreliable when <symbol> is (potentially) an over‐
648 loaded function. Since there is no reliable way to predict whether a
649 given function in the system environment may be defined as an over‐
650 loaded function or may be an overloaded function on other systems or
651 will become so in the future, it is generally advised to use the
652 CheckCXXSourceCompiles module for checking any function symbol (un‐
653 less somehow you surely know the checked function is not overloaded
654 on other systems or will not be so in the future).
655 The following variables may be set before calling this macro to modify
657 the way the check is run:
658 CMAKE_REQUIRED_FLAGS
660 string of compile command line flags.
661 CMAKE_REQUIRED_DEFINITIONS
663 a ;-list of macros to define (-DFOO=bar).
664 CMAKE_REQUIRED_INCLUDES
666 a ;-list of header search paths to pass to the compiler.
667 CMAKE_REQUIRED_LINK_OPTIONS
669 New in version 3.14: a ;-list of options to add to the link com‐
670 mand.
671 CMAKE_REQUIRED_LIBRARIES
674 a ;-list of libraries to add to the link command. See policy
675 CMP0075.
676 CMAKE_REQUIRED_QUIET
678 New in version 3.1: execute quietly without messages.
679 For example:
682 include(CheckCXXSymbolExists)
684 # Check for macro SEEK_SET
686 check_cxx_symbol_exists(SEEK_SET "cstdio" HAVE_SEEK_SET)
687 # Check for function std::fopen
688 check_cxx_symbol_exists(std::fopen "cstdio" HAVE_STD_FOPEN)
689 CheckFortranCompilerFlag
691 New in version 3.3.
692 Check whether the Fortran compiler supports a given flag.
695 check_fortran_compiler_flag
697 check_fortran_compiler_flag(<flag> <var>)
699 Check that the <flag> is accepted by the compiler without a di‐
701 agnostic. Stores the result in an internal cache entry named
702 <var>.
703 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
705 and calls the check_fortran_source_compiles macro from the CheckFor‐
706 tranSourceCompiles module. See documentation of that module for a
707 listing of variables that can otherwise modify the build.
708 A positive result from this check indicates only that the compiler did
710 not issue a diagnostic message when given the flag. Whether the flag
711 has any effect or even a specific one is beyond the scope of this mod‐
712 ule.
713 NOTE:
715 Since the try_compile() command forwards flags from variables like
716 CMAKE_Fortran_FLAGS, unknown flags in such variables may cause a
717 false negative for this check.
718 CheckFortranFunctionExists
720 Check if a Fortran function exists.
721 CHECK_FORTRAN_FUNCTION_EXISTS
723 CHECK_FORTRAN_FUNCTION_EXISTS(<function> <result>)
725 where
727 <function>
729 the name of the Fortran function
730 <result>
732 variable to store the result; will be created as an in‐
733 ternal cache variable.
734 NOTE:
736 This command does not detect functions in Fortran modules. In gen‐
737 eral it is recommended to use CheckSourceCompiles instead to deter‐
738 mine if a Fortran function or subroutine is available.
739 The following variables may be set before calling this macro to modify
741 the way the check is run:
742 CMAKE_REQUIRED_LINK_OPTIONS
744 New in version 3.14: A ;-list of options to add to the link com‐
745 mand (see try_compile() for further details).
746 CMAKE_REQUIRED_LIBRARIES
749 A ;-list of libraries to add to the link command. These can be
750 the name of system libraries or they can be Imported Targets
751 (see try_compile() for further details).
752 CheckFortranSourceCompiles
754 New in version 3.1.
755 Check if given Fortran source compiles and links into an executable.
758 check_fortran_source_compiles
760 check_fortran_source_compiles(<code> <resultVar>
762 [FAIL_REGEX <regex>...]
763 [SRC_EXT <extension>]
764 )
765 Checks that the source supplied in <code> can be compiled as a
767 Fortran source file and linked as an executable. The <code> must
768 be a Fortran program containing at least an end statement--for
769 example:
770 check_fortran_source_compiles("character :: b; error stop b; end" F2018ESTOPOK SRC_EXT F90)
772 This command can help avoid costly build processes when a com‐
774 piler lacks support for a necessary feature, or a particular
775 vendor library is not compatible with the Fortran compiler ver‐
776 sion being used. This generate-time check may advise the user of
777 such before the main build process. See also the check_for‐
778 tran_source_runs() command to actually run the compiled code.
779 The result will be stored in the internal cache variable <re‐
781 sultVar>, with a boolean true value for success and boolean
782 false for failure.
783 If FAIL_REGEX is provided, then failure is determined by check‐
785 ing if anything in the output matches any of the specified regu‐
786 lar expressions.
787 By default, the test source file will be given a .F file exten‐
789 sion. The SRC_EXT option can be used to override this with .<ex‐
790 tension> instead-- .F90 is a typical choice.
791 The underlying check is performed by the try_compile() command.
793 The compile and link commands can be influenced by setting any
794 of the following variables prior to calling check_for‐
795 tran_source_compiles():
796 CMAKE_REQUIRED_FLAGS
798 Additional flags to pass to the compiler. Note that the
799 contents of CMAKE_Fortran_FLAGS and its associated con‐
800 figuration-specific variable are automatically added to
801 the compiler command before the contents of CMAKE_RE‐
802 QUIRED_FLAGS.
803 CMAKE_REQUIRED_DEFINITIONS
805 A ;-list of compiler definitions of the form -DFOO or
806 -DFOO=bar. A definition for the name specified by <re‐
807 sultVar> will also be added automatically.
808 CMAKE_REQUIRED_INCLUDES
810 A ;-list of header search paths to pass to the compiler.
811 These will be the only header search paths used by
812 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
813 RIES directory property will be ignored.
814 CMAKE_REQUIRED_LINK_OPTIONS
816 New in version 3.14.
817 A ;-list of options to add to the link command (see
820 try_compile() for further details).
821 CMAKE_REQUIRED_LIBRARIES
823 A ;-list of libraries to add to the link command. These
824 can be the name of system libraries or they can be Im‐
825 ported Targets (see try_compile() for further details).
826 CMAKE_REQUIRED_QUIET
828 If this variable evaluates to a boolean true value, all
829 status messages associated with the check will be sup‐
830 pressed.
831 The check is only performed once, with the result cached in the
833 variable named by <resultVar>. Every subsequent CMake run will
834 re-use this cached value rather than performing the check again,
835 even if the <code> changes. In order to force the check to be
836 re-evaluated, the variable named by <resultVar> must be manually
837 removed from the cache.
838 CheckFortranSourceRuns
840 New in version 3.14.
841 Check if given Fortran source compiles and links into an executable and
844 can subsequently be run.
845 check_fortran_source_runs
847 check_fortran_source_runs(<code> <resultVar>
849 [SRC_EXT <extension>])
850 Check that the source supplied in <code> can be compiled as a
852 Fortran source file, linked as an executable and then run. The
853 <code> must be a Fortran program containing at least an end
854 statement--for example:
855 check_fortran_source_runs("real :: x[*]; call co_sum(x); end" F2018coarrayOK)
857 This command can help avoid costly build processes when a com‐
859 piler lacks support for a necessary feature, or a particular
860 vendor library is not compatible with the Fortran compiler ver‐
861 sion being used. Some of these failures only occur at runtime
862 instead of linktime, and a trivial runtime example can catch the
863 issue before the main build process.
864 If the <code> could be built and run successfully, the internal
866 cache variable specified by <resultVar> will be set to 1, other‐
867 wise it will be set to an value that evaluates to boolean false
868 (e.g. an empty string or an error message).
869 By default, the test source file will be given a .F90 file ex‐
871 tension. The SRC_EXT option can be used to override this with
872 .<extension> instead.
873 The underlying check is performed by the try_run() command. The
875 compile and link commands can be influenced by setting any of
876 the following variables prior to calling check_for‐
877 tran_source_runs():
878 CMAKE_REQUIRED_FLAGS
880 Additional flags to pass to the compiler. Note that the
881 contents of CMAKE_Fortran_FLAGS and its associated con‐
882 figuration-specific variable are automatically added to
883 the compiler command before the contents of CMAKE_RE‐
884 QUIRED_FLAGS.
885 CMAKE_REQUIRED_DEFINITIONS
887 A ;-list of compiler definitions of the form -DFOO or
888 -DFOO=bar. A definition for the name specified by <re‐
889 sultVar> will also be added automatically.
890 CMAKE_REQUIRED_INCLUDES
892 A ;-list of header search paths to pass to the compiler.
893 These will be the only header search paths used by
894 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
895 directory property will be ignored.
896 CMAKE_REQUIRED_LINK_OPTIONS
898 A ;-list of options to add to the link command (see
899 try_run() for further details).
900 CMAKE_REQUIRED_LIBRARIES
902 A ;-list of libraries to add to the link command. These
903 can be the name of system libraries or they can be Im‐
904 ported Targets (see try_run() for further details).
905 CMAKE_REQUIRED_QUIET
907 If this variable evaluates to a boolean true value, all
908 status messages associated with the check will be sup‐
909 pressed.
910 The check is only performed once, with the result cached in the
912 variable named by <resultVar>. Every subsequent CMake run will
913 re-use this cached value rather than performing the check again,
914 even if the <code> changes. In order to force the check to be
915 re-evaluated, the variable named by <resultVar> must be manually
916 removed from the cache.
917 CheckFunctionExists
919 Check if a C function can be linked
920 check_function_exists
922 check_function_exists(<function> <variable>)
924 Checks that the <function> is provided by libraries on the sys‐
926 tem and store the result in a <variable>, which will be created
927 as an internal cache variable.
928 The following variables may be set before calling this macro to modify
930 the way the check is run:
931 CMAKE_REQUIRED_FLAGS
933 string of compile command line flags.
934 CMAKE_REQUIRED_DEFINITIONS
936 a ;-list of macros to define (-DFOO=bar).
937 CMAKE_REQUIRED_INCLUDES
939 a ;-list of header search paths to pass to the compiler.
940 CMAKE_REQUIRED_LINK_OPTIONS
942 New in version 3.14: a ;-list of options to add to the link com‐
943 mand.
944 CMAKE_REQUIRED_LIBRARIES
947 a ;-list of libraries to add to the link command. See policy
948 CMP0075.
949 CMAKE_REQUIRED_QUIET
951 New in version 3.1: execute quietly without messages.
952 NOTE:
955 Prefer using CheckSymbolExists instead of this module, for the fol‐
956 lowing reasons:
957 • check_function_exists() can't detect functions that are inlined in
959 headers or specified as a macro.
960 • check_function_exists() can't detect anything in the 32-bit ver‐
962 sions of the Win32 API, because of a mismatch in calling conven‐
963 tions.
964 • check_function_exists() only verifies linking, it does not verify
966 that the function is declared in system headers.
967 CheckIncludeFileCXX
969 Provides a macro to check if a header file can be included in CXX.
970 CHECK_INCLUDE_FILE_CXX
972 CHECK_INCLUDE_FILE_CXX(<include> <variable> [<flags>])
974 Check if the given <include> file may be included in a CXX
976 source file and store the result in an internal cache entry
977 named <variable>. The optional third argument may be used to
978 add compilation flags to the check (or use CMAKE_REQUIRED_FLAGS
979 below).
980 The following variables may be set before calling this macro to modify
982 the way the check is run:
983 CMAKE_REQUIRED_FLAGS
985 string of compile command line flags.
986 CMAKE_REQUIRED_DEFINITIONS
988 a ;-list of macros to define (-DFOO=bar).
989 CMAKE_REQUIRED_INCLUDES
991 a ;-list of header search paths to pass to the compiler.
992 CMAKE_REQUIRED_LINK_OPTIONS
994 New in version 3.14: a ;-list of options to add to the link com‐
995 mand.
996 CMAKE_REQUIRED_LIBRARIES
999 a ;-list of libraries to add to the link command. See policy
1000 CMP0075.
1001 CMAKE_REQUIRED_QUIET
1003 New in version 3.1: execute quietly without messages.
1004 See modules CheckIncludeFile and CheckIncludeFiles to check for one or
1007 more C headers.
1008 CheckIncludeFile
1010 Provides a macro to check if a header file can be included in C.
1011 CHECK_INCLUDE_FILE
1013 CHECK_INCLUDE_FILE(<include> <variable> [<flags>])
1015 Check if the given <include> file may be included in a C source
1017 file and store the result in an internal cache entry named
1018 <variable>. The optional third argument may be used to add com‐
1019 pilation flags to the check (or use CMAKE_REQUIRED_FLAGS below).
1020 The following variables may be set before calling this macro to modify
1022 the way the check is run:
1023 CMAKE_REQUIRED_FLAGS
1025 string of compile command line flags.
1026 CMAKE_REQUIRED_DEFINITIONS
1028 a ;-list of macros to define (-DFOO=bar).
1029 CMAKE_REQUIRED_INCLUDES
1031 a ;-list of header search paths to pass to the compiler.
1032 CMAKE_REQUIRED_LINK_OPTIONS
1034 New in version 3.14: a ;-list of options to add to the link com‐
1035 mand.
1036 CMAKE_REQUIRED_LIBRARIES
1039 a ;-list of libraries to add to the link command. See policy
1040 CMP0075.
1041 CMAKE_REQUIRED_QUIET
1043 New in version 3.1: execute quietly without messages.
1044 See the CheckIncludeFiles module to check for multiple headers at once.
1047 See the CheckIncludeFileCXX module to check for headers using the CXX
1048 language.
1049 CheckIncludeFiles
1051 Provides a macro to check if a list of one or more header files can be
1052 included together.
1053 CHECK_INCLUDE_FILES
1055 CHECK_INCLUDE_FILES("<includes>" <variable> [LANGUAGE <language>])
1057 Check if the given <includes> list may be included together in a
1059 source file and store the result in an internal cache entry
1060 named <variable>. Specify the <includes> argument as a ;-list
1061 of header file names.
1062 If LANGUAGE is set, the specified compiler will be used to per‐
1064 form the check. Acceptable values are C and CXX. If not set, the
1065 C compiler will be used if enabled. If the C compiler is not en‐
1066 abled, the C++ compiler will be used if enabled.
1067 The following variables may be set before calling this macro to modify
1069 the way the check is run:
1070 CMAKE_REQUIRED_FLAGS
1072 string of compile command line flags.
1073 CMAKE_REQUIRED_DEFINITIONS
1075 a ;-list of macros to define (-DFOO=bar).
1076 CMAKE_REQUIRED_INCLUDES
1078 a ;-list of header search paths to pass to the compiler.
1079 CMAKE_REQUIRED_LINK_OPTIONS
1081 New in version 3.14: a ;-list of options to add to the link com‐
1082 mand.
1083 CMAKE_REQUIRED_LIBRARIES
1086 a ;-list of libraries to add to the link command. See policy
1087 CMP0075.
1088 CMAKE_REQUIRED_QUIET
1090 New in version 3.1: execute quietly without messages.
1091 See modules CheckIncludeFile and CheckIncludeFileCXX to check for a
1094 single header file in C or CXX languages.
1095 CheckIPOSupported
1097 New in version 3.9.
1098 Check whether the compiler supports an interprocedural optimization
1101 (IPO/LTO). Use this before enabling the INTERPROCEDURAL_OPTIMIZATION
1102 target property.
1103 check_ipo_supported
1105 check_ipo_supported([RESULT <result>] [OUTPUT <output>]
1107 [LANGUAGES <lang>...])
1108 Options are:
1110 RESULT <result>
1112 Set <result> variable to YES if IPO is supported by the
1113 compiler and NO otherwise. If this option is not given
1114 then the command will issue a fatal error if IPO is not
1115 supported.
1116 OUTPUT <output>
1118 Set <output> variable with details about any error.
1119 LANGUAGES <lang>...
1121 Specify languages whose compilers to check. Languages C,
1122 CXX, and Fortran are supported.
1123 It makes no sense to use this module when CMP0069 is set to OLD so mod‐
1125 ule will return error in this case. See policy CMP0069 for details.
1126 New in version 3.13: Add support for Visual Studio generators.
1128 Examples
1131 check_ipo_supported() # fatal error if IPO is not supported
1132 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
1133 # Optional IPO. Do not use IPO if it's not supported by compiler.
1135 check_ipo_supported(RESULT result OUTPUT output)
1136 if(result)
1137 set_property(TARGET foo PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
1138 else()
1139 message(WARNING "IPO is not supported: ${output}")
1140 endif()
1141 CheckLanguage
1143 Check if a language can be enabled
1144 Usage:
1146 check_language(<lang>)
1148 where <lang> is a language that may be passed to enable_language() such
1150 as Fortran. If CMAKE_<LANG>_COMPILER is already defined the check does
1151 nothing. Otherwise it tries enabling the language in a test project.
1152 The result is cached in CMAKE_<LANG>_COMPILER as the compiler that was
1153 found, or NOTFOUND if the language cannot be enabled. For CUDA which
1154 can have an explicit host compiler, the cache CMAKE_CUDA_HOST_COMPILER
1155 variable will be set if it was required for compilation (and cleared if
1156 it was not).
1157 Example:
1159 check_language(Fortran)
1161 if(CMAKE_Fortran_COMPILER)
1162 enable_language(Fortran)
1163 else()
1164 message(STATUS "No Fortran support")
1165 endif()
1166 CheckLibraryExists
1168 Check if the function exists.
1169 CHECK_LIBRARY_EXISTS
1171 CHECK_LIBRARY_EXISTS(LIBRARY FUNCTION LOCATION VARIABLE)
1173 LIBRARY - the name of the library you are looking for
1175 FUNCTION - the name of the function
1176 LOCATION - location where the library should be found
1177 VARIABLE - variable to store the result
1178 Will be created as an internal cache variable.
1179 The following variables may be set before calling this macro to modify
1181 the way the check is run:
1182 CMAKE_REQUIRED_FLAGS
1184 string of compile command line flags.
1185 CMAKE_REQUIRED_DEFINITIONS
1187 list of macros to define (-DFOO=bar).
1188 CMAKE_REQUIRED_LINK_OPTIONS
1190 New in version 3.14: list of options to pass to link command.
1191 CMAKE_REQUIRED_LIBRARIES
1194 list of libraries to link.
1195 CMAKE_REQUIRED_QUIET
1197 New in version 3.1: execute quietly without messages.
1198 CheckLinkerFlag
1201 New in version 3.18.
1202 Check whether the compiler supports a given link flag.
1205 check_linker_flag
1207 check_linker_flag(<lang> <flag> <var>)
1209 Check that the link <flag> is accepted by the <lang> compiler without a
1211 diagnostic. Stores the result in an internal cache entry named <var>.
1212 This command temporarily sets the CMAKE_REQUIRED_LINK_OPTIONS variable
1214 and calls the check_source_compiles() command from the CheckSourceCom‐
1215 piles module. See that module's documentation for a listing of vari‐
1216 ables that can otherwise modify the build.
1217 The underlying implementation relies on the LINK_OPTIONS property to
1219 check the specified flag. The LINKER: prefix, as described in the tar‐
1220 get_link_options() command, can be used as well.
1221 A positive result from this check indicates only that the compiler did
1223 not issue a diagnostic message when given the link flag. Whether the
1224 flag has any effect or even a specific one is beyond the scope of this
1225 module.
1226 NOTE:
1228 Since the try_compile() command forwards flags from variables like
1229 CMAKE_<LANG>_FLAGS, unknown flags in such variables may cause a
1230 false negative for this check.
1231 CheckOBJCCompilerFlag
1233 New in version 3.16.
1234 Check whether the Objective-C compiler supports a given flag.
1237 check_objc_compiler_flag
1239 check_objc_compiler_flag(<flag> <var>)
1241 Check that the <flag> is accepted by the compiler without a di‐
1243 agnostic. Stores the result in an internal cache entry named
1244 <var>.
1245 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
1247 and calls the check_objc_source_compiles macro from the CheckOBJC‐
1248 SourceCompiles module. See documentation of that module for a listing
1249 of variables that can otherwise modify the build.
1250 A positive result from this check indicates only that the compiler did
1252 not issue a diagnostic message when given the flag. Whether the flag
1253 has any effect or even a specific one is beyond the scope of this mod‐
1254 ule.
1255 NOTE:
1257 Since the try_compile() command forwards flags from variables like
1258 CMAKE_OBJC_FLAGS, unknown flags in such variables may cause a false
1259 negative for this check.
1260 CheckOBJCSourceCompiles
1262 New in version 3.16.
1263 Check if given Objective-C source compiles and links into an exe‐
1266 cutable.
1267 check_objc_source_compiles
1269 check_objc_source_compiles(<code> <resultVar>
1271 [FAIL_REGEX <regex1> [<regex2>...]])
1272 Check that the source supplied in <code> can be compiled as a
1274 Objectie-C source file and linked as an executable (so it must
1275 contain at least a main() function). The result will be stored
1276 in the internal cache variable specified by <resultVar>, with a
1277 boolean true value for success and boolean false for failure. If
1278 FAIL_REGEX is provided, then failure is determined by checking
1279 if anything in the output matches any of the specified regular
1280 expressions.
1281 The underlying check is performed by the try_compile() command.
1283 The compile and link commands can be influenced by setting any
1284 of the following variables prior to calling
1285 check_objc_source_compiles():
1286 CMAKE_REQUIRED_FLAGS
1288 Additional flags to pass to the compiler. Note that the
1289 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1290 ration-specific variable are automatically added to the
1291 compiler command before the contents of CMAKE_RE‐
1292 QUIRED_FLAGS.
1293 CMAKE_REQUIRED_DEFINITIONS
1295 A ;-list of compiler definitions of the form -DFOO or
1296 -DFOO=bar. A definition for the name specified by <re‐
1297 sultVar> will also be added automatically.
1298 CMAKE_REQUIRED_INCLUDES
1300 A ;-list of header search paths to pass to the compiler.
1301 These will be the only header search paths used by
1302 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1303 RIES directory property will be ignored.
1304 CMAKE_REQUIRED_LINK_OPTIONS
1306 A ;-list of options to add to the link command (see
1307 try_compile() for further details).
1308 CMAKE_REQUIRED_LIBRARIES
1310 A ;-list of libraries to add to the link command. These
1311 can be the name of system libraries or they can be Im‐
1312 ported Targets (see try_compile() for further details).
1313 CMAKE_REQUIRED_QUIET
1315 If this variable evaluates to a boolean true value, all
1316 status messages associated with the check will be sup‐
1317 pressed.
1318 The check is only performed once, with the result cached in the
1320 variable named by <resultVar>. Every subsequent CMake run will
1321 re-use this cached value rather than performing the check again,
1322 even if the <code> changes. In order to force the check to be
1323 re-evaluated, the variable named by <resultVar> must be manually
1324 removed from the cache.
1325 CheckOBJCSourceRuns
1327 New in version 3.16.
1328 Check if given Objective-C source compiles and links into an executable
1331 and can subsequently be run.
1332 check_objc_source_runs
1334 check_objc_source_runs(<code> <resultVar>)
1336 Check that the source supplied in <code> can be compiled as a
1338 Objective-C source file, linked as an executable and then run.
1339 The <code> must contain at least a main() function. If the
1340 <code> could be built and run successfully, the internal cache
1341 variable specified by <resultVar> will be set to 1, otherwise it
1342 will be set to an value that evaluates to boolean false (e.g. an
1343 empty string or an error message).
1344 The underlying check is performed by the try_run() command. The
1346 compile and link commands can be influenced by setting any of
1347 the following variables prior to calling
1348 check_objc_source_runs():
1349 CMAKE_REQUIRED_FLAGS
1351 Additional flags to pass to the compiler. Note that the
1352 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1353 ration-specific variable are automatically added to the
1354 compiler command before the contents of CMAKE_RE‐
1355 QUIRED_FLAGS.
1356 CMAKE_REQUIRED_DEFINITIONS
1358 A ;-list of compiler definitions of the form -DFOO or
1359 -DFOO=bar. A definition for the name specified by <re‐
1360 sultVar> will also be added automatically.
1361 CMAKE_REQUIRED_INCLUDES
1363 A ;-list of header search paths to pass to the compiler.
1364 These will be the only header search paths used by
1365 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1366 directory property will be ignored.
1367 CMAKE_REQUIRED_LINK_OPTIONS
1369 A ;-list of options to add to the link command (see
1370 try_run() for further details).
1371 CMAKE_REQUIRED_LIBRARIES
1373 A ;-list of libraries to add to the link command. These
1374 can be the name of system libraries or they can be Im‐
1375 ported Targets (see try_run() for further details).
1376 CMAKE_REQUIRED_QUIET
1378 If this variable evaluates to a boolean true value, all
1379 status messages associated with the check will be sup‐
1380 pressed.
1381 The check is only performed once, with the result cached in the
1383 variable named by <resultVar>. Every subsequent CMake run will
1384 re-use this cached value rather than performing the check again,
1385 even if the <code> changes. In order to force the check to be
1386 re-evaluated, the variable named by <resultVar> must be manually
1387 removed from the cache.
1388 CheckOBJCXXCompilerFlag
1390 New in version 3.16.
1391 Check whether the Objective-C++ compiler supports a given flag.
1394 check_objcxx_compiler_flag
1396 check_objcxx_compiler_flag(<flag> <var>)
1398 Check that the <flag> is accepted by the compiler without a di‐
1400 agnostic. Stores the result in an internal cache entry named
1401 <var>.
1402 This command temporarily sets the CMAKE_REQUIRED_DEFINITIONS variable
1404 and calls the check_objcxx_source_compiles macro from the CheckOB‐
1405 JCXXSourceCompiles module. See documentation of that module for a
1406 listing of variables that can otherwise modify the build.
1407 A positive result from this check indicates only that the compiler did
1409 not issue a diagnostic message when given the flag. Whether the flag
1410 has any effect or even a specific one is beyond the scope of this mod‐
1411 ule.
1412 NOTE:
1414 Since the try_compile() command forwards flags from variables like
1415 CMAKE_OBJCXX_FLAGS, unknown flags in such variables may cause a
1416 false negative for this check.
1417 CheckOBJCXXSourceCompiles
1419 New in version 3.16.
1420 Check if given Objective-C++ source compiles and links into an exe‐
1423 cutable.
1424 check_objcxx_source_compiles
1426 check_objcxx_source_compiles(<code> <resultVar>
1428 [FAIL_REGEX <regex1> [<regex2>...]])
1429 Check that the source supplied in <code> can be compiled as a
1431 Objective-C++ source file and linked as an executable (so it
1432 must contain at least a main() function). The result will be
1433 stored in the internal cache variable specified by <resultVar>,
1434 with a boolean true value for success and boolean false for
1435 failure. If FAIL_REGEX is provided, then failure is determined
1436 by checking if anything in the output matches any of the speci‐
1437 fied regular expressions.
1438 The underlying check is performed by the try_compile() command.
1440 The compile and link commands can be influenced by setting any
1441 of the following variables prior to calling check_ob‐
1442 jcxx_source_compiles():
1443 CMAKE_REQUIRED_FLAGS
1445 Additional flags to pass to the compiler. Note that the
1446 contents of CMAKE_OBJCXX_FLAGS and its associated config‐
1447 uration-specific variable are automatically added to the
1448 compiler command before the contents of CMAKE_RE‐
1449 QUIRED_FLAGS.
1450 CMAKE_REQUIRED_DEFINITIONS
1452 A ;-list of compiler definitions of the form -DFOO or
1453 -DFOO=bar. A definition for the name specified by <re‐
1454 sultVar> will also be added automatically.
1455 CMAKE_REQUIRED_INCLUDES
1457 A ;-list of header search paths to pass to the compiler.
1458 These will be the only header search paths used by
1459 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1460 RIES directory property will be ignored.
1461 CMAKE_REQUIRED_LINK_OPTIONS
1463 A ;-list of options to add to the link command (see
1464 try_compile() for further details).
1465 CMAKE_REQUIRED_LIBRARIES
1467 A ;-list of libraries to add to the link command. These
1468 can be the name of system libraries or they can be Im‐
1469 ported Targets (see try_compile() for further details).
1470 CMAKE_REQUIRED_QUIET
1472 If this variable evaluates to a boolean true value, all
1473 status messages associated with the check will be sup‐
1474 pressed.
1475 The check is only performed once, with the result cached in the
1477 variable named by <resultVar>. Every subsequent CMake run will
1478 re-use this cached value rather than performing the check again,
1479 even if the <code> changes. In order to force the check to be
1480 re-evaluated, the variable named by <resultVar> must be manually
1481 removed from the cache.
1482 CheckOBJCXXSourceRuns
1484 New in version 3.16.
1485 Check if given Objective-C++ source compiles and links into an exe‐
1488 cutable and can subsequently be run.
1489 check_objcxx_source_runs
1491 check_objcxx_source_runs(<code> <resultVar>)
1493 Check that the source supplied in <code> can be compiled as a
1495 Objective-C++ source file, linked as an executable and then run.
1496 The <code> must contain at least a main() function. If the
1497 <code> could be built and run successfully, the internal cache
1498 variable specified by <resultVar> will be set to 1, otherwise it
1499 will be set to an value that evaluates to boolean false (e.g. an
1500 empty string or an error message).
1501 The underlying check is performed by the try_run() command. The
1503 compile and link commands can be influenced by setting any of
1504 the following variables prior to calling check_ob‐
1505 jcxx_source_runs():
1506 CMAKE_REQUIRED_FLAGS
1508 Additional flags to pass to the compiler. Note that the
1509 contents of CMAKE_OBJCXX_FLAGS and its associated config‐
1510 uration-specific variable are automatically added to the
1511 compiler command before the contents of CMAKE_RE‐
1512 QUIRED_FLAGS.
1513 CMAKE_REQUIRED_DEFINITIONS
1515 A ;-list of compiler definitions of the form -DFOO or
1516 -DFOO=bar. A definition for the name specified by <re‐
1517 sultVar> will also be added automatically.
1518 CMAKE_REQUIRED_INCLUDES
1520 A ;-list of header search paths to pass to the compiler.
1521 These will be the only header search paths used by
1522 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1523 directory property will be ignored.
1524 CMAKE_REQUIRED_LINK_OPTIONS
1526 A ;-list of options to add to the link command (see
1527 try_run() for further details).
1528 CMAKE_REQUIRED_LIBRARIES
1530 A ;-list of libraries to add to the link command. These
1531 can be the name of system libraries or they can be Im‐
1532 ported Targets (see try_run() for further details).
1533 CMAKE_REQUIRED_QUIET
1535 If this variable evaluates to a boolean true value, all
1536 status messages associated with the check will be sup‐
1537 pressed.
1538 The check is only performed once, with the result cached in the
1540 variable named by <resultVar>. Every subsequent CMake run will
1541 re-use this cached value rather than performing the check again,
1542 even if the <code> changes. In order to force the check to be
1543 re-evaluated, the variable named by <resultVar> must be manually
1544 removed from the cache.
1545 CheckPIESupported
1547 New in version 3.14.
1548 Check whether the linker supports Position Independent Code (PIE) or No
1551 Position Independent Code (NO_PIE) for executables. Use this to ensure
1552 that the POSITION_INDEPENDENT_CODE target property for executables will
1553 be honored at link time.
1554 check_pie_supported
1556 check_pie_supported([OUTPUT_VARIABLE <output>]
1558 [LANGUAGES <lang>...])
1559 Options are:
1561 OUTPUT_VARIABLE <output>
1563 Set <output> variable with details about any error.
1564 LANGUAGES <lang>...
1566 Check the linkers used for each of the specified lan‐
1567 guages. Supported languages are C, CXX, and Fortran.
1568 It makes no sense to use this module when CMP0083 is set to OLD, so the
1570 command will return an error in this case. See policy CMP0083 for de‐
1571 tails.
1572 Variables
1574 For each language checked, two boolean cache variables are defined.
1575 CMAKE_<lang>_LINK_PIE_SUPPORTED
1577 Set to YES if PIE is supported by the linker and NO other‐
1578 wise.
1579 CMAKE_<lang>_LINK_NO_PIE_SUPPORTED
1581 Set to YES if NO_PIE is supported by the linker and NO other‐
1582 wise.
1583 Examples
1585 check_pie_supported()
1586 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1587 # Retrieve any error message.
1589 check_pie_supported(OUTPUT_VARIABLE output LANGUAGES C)
1590 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1591 if(NOT CMAKE_C_LINK_PIE_SUPPORTED)
1592 message(WARNING "PIE is not supported at link time: ${output}.\n"
1593 "PIE link options will not be passed to linker.")
1594 endif()
1595 CheckPrototypeDefinition
1597 Check if the prototype we expect is correct.
1598 check_prototype_definition
1600 check_prototype_definition(FUNCTION PROTOTYPE RETURN HEADER VARIABLE)
1602 FUNCTION - The name of the function (used to check if prototype exists)
1604 PROTOTYPE- The prototype to check.
1605 RETURN - The return value of the function.
1606 HEADER - The header files required.
1607 VARIABLE - The variable to store the result.
1608 Will be created as an internal cache variable.
1609 Example:
1611 check_prototype_definition(getpwent_r
1613 "struct passwd *getpwent_r(struct passwd *src, char *buf, int buflen)"
1614 "NULL"
1615 "unistd.h;pwd.h"
1616 SOLARIS_GETPWENT_R)
1617 The following variables may be set before calling this function to mod‐
1619 ify the way the check is run:
1620 CMAKE_REQUIRED_FLAGS
1622 string of compile command line flags.
1623 CMAKE_REQUIRED_DEFINITIONS
1625 list of macros to define (-DFOO=bar).
1626 CMAKE_REQUIRED_INCLUDES
1628 list of include directories.
1629 CMAKE_REQUIRED_LINK_OPTIONS
1631 New in version 3.14: list of options to pass to link command.
1632 CMAKE_REQUIRED_LIBRARIES
1635 list of libraries to link.
1636 CMAKE_REQUIRED_QUIET
1638 New in version 3.1: execute quietly without messages.
1639 CheckSourceCompiles
1642 New in version 3.19.
1643 Check if given source compiles and links into an executable.
1646 check_source_compiles
1648 check_source_compiles(<lang> <code> <resultVar>
1650 [FAIL_REGEX <regex1> [<regex2>...]]
1651 [SRC_EXT <extension>])
1652 Check that the source supplied in <code> can be compiled as a
1654 source file for the requested language and linked as an exe‐
1655 cutable (so it must contain at least a main() function). The re‐
1656 sult will be stored in the internal cache variable specified by
1657 <resultVar>, with a boolean true value for success and boolean
1658 false for failure. If FAIL_REGEX is provided, then failure is
1659 determined by checking if anything in the output matches any of
1660 the specified regular expressions.
1661 By default, the test source file will be given a file extension
1663 that matches the requested language. The SRC_EXT option can be
1664 used to override this with .<extension> instead.
1665 The underlying check is performed by the try_compile() command.
1667 The compile and link commands can be influenced by setting any
1668 of the following variables prior to calling check_source_com‐
1669 piles():
1670 CMAKE_REQUIRED_FLAGS
1672 Additional flags to pass to the compiler. Note that the
1673 contents of CMAKE_<LANG>_FLAGS and its associated config‐
1674 uration-specific variable are automatically added to the
1675 compiler command before the contents of CMAKE_RE‐
1676 QUIRED_FLAGS.
1677 CMAKE_REQUIRED_DEFINITIONS
1679 A ;-list of compiler definitions of the form -DFOO or
1680 -DFOO=bar. A definition for the name specified by <re‐
1681 sultVar> will also be added automatically.
1682 CMAKE_REQUIRED_INCLUDES
1684 A ;-list of header search paths to pass to the compiler.
1685 These will be the only header search paths used by
1686 try_compile(), i.e. the contents of the INCLUDE_DIRECTO‐
1687 RIES directory property will be ignored.
1688 CMAKE_REQUIRED_LINK_OPTIONS
1690 A ;-list of options to add to the link command (see
1691 try_compile() for further details).
1692 CMAKE_REQUIRED_LIBRARIES
1694 A ;-list of libraries to add to the link command. These
1695 can be the name of system libraries or they can be Im‐
1696 ported Targets (see try_compile() for further details).
1697 CMAKE_REQUIRED_QUIET
1699 If this variable evaluates to a boolean true value, all
1700 status messages associated with the check will be sup‐
1701 pressed.
1702 The check is only performed once, with the result cached in the
1704 variable named by <resultVar>. Every subsequent CMake run will
1705 re-use this cached value rather than performing the check again,
1706 even if the <code> changes. In order to force the check to be
1707 re-evaluated, the variable named by <resultVar> must be manually
1708 removed from the cache.
1709 CheckSourceRuns
1711 New in version 3.19.
1712 Check if given source compiles and links into an executable and can
1715 subsequently be run.
1716 check_source_runs
1718 check_source_runs(<lang> <code> <resultVar>
1720 [SRC_EXT <extension>])
1721 Check that the source supplied in <code> can be compiled as a
1723 source file for the requested language, linked as an executable
1724 and then run. The <code> must contain at least a main() func‐
1725 tion. If the <code> could be built and run successfully, the in‐
1726 ternal cache variable specified by <resultVar> will be set to 1,
1727 otherwise it will be set to an value that evaluates to boolean
1728 false (e.g. an empty string or an error message).
1729 By default, the test source file will be given a file extension
1731 that matches the requested language. The SRC_EXT option can be
1732 used to override this with .<extension> instead.
1733 The underlying check is performed by the try_run() command. The
1735 compile and link commands can be influenced by setting any of
1736 the following variables prior to calling
1737 check_objc_source_runs():
1738 CMAKE_REQUIRED_FLAGS
1740 Additional flags to pass to the compiler. Note that the
1741 contents of CMAKE_OBJC_FLAGS and its associated configu‐
1742 ration-specific variable are automatically added to the
1743 compiler command before the contents of CMAKE_RE‐
1744 QUIRED_FLAGS.
1745 CMAKE_REQUIRED_DEFINITIONS
1747 A ;-list of compiler definitions of the form -DFOO or
1748 -DFOO=bar. A definition for the name specified by <re‐
1749 sultVar> will also be added automatically.
1750 CMAKE_REQUIRED_INCLUDES
1752 A ;-list of header search paths to pass to the compiler.
1753 These will be the only header search paths used by
1754 try_run(), i.e. the contents of the INCLUDE_DIRECTORIES
1755 directory property will be ignored.
1756 CMAKE_REQUIRED_LINK_OPTIONS
1758 A ;-list of options to add to the link command (see
1759 try_run() for further details).
1760 CMAKE_REQUIRED_LIBRARIES
1762 A ;-list of libraries to add to the link command. These
1763 can be the name of system libraries or they can be Im‐
1764 ported Targets (see try_run() for further details).
1765 CMAKE_REQUIRED_QUIET
1767 If this variable evaluates to a boolean true value, all
1768 status messages associated with the check will be sup‐
1769 pressed.
1770 The check is only performed once, with the result cached in the
1772 variable named by <resultVar>. Every subsequent CMake run will
1773 re-use this cached value rather than performing the check again,
1774 even if the <code> changes. In order to force the check to be
1775 re-evaluated, the variable named by <resultVar> must be manually
1776 removed from the cache.
1777 CheckStructHasMember
1779 Check if the given struct or class has the specified member variable
1780 CHECK_STRUCT_HAS_MEMBER
1782 CHECK_STRUCT_HAS_MEMBER(<struct> <member> <header> <variable>
1784 [LANGUAGE <language>])
1785 <struct> - the name of the struct or class you are interested in
1787 <member> - the member which existence you want to check
1788 <header> - the header(s) where the prototype should be declared
1789 <variable> - variable to store the result
1790 <language> - the compiler to use (C or CXX)
1791 The following variables may be set before calling this macro to modify
1793 the way the check is run:
1794 CMAKE_REQUIRED_FLAGS
1796 string of compile command line flags.
1797 CMAKE_REQUIRED_DEFINITIONS
1799 list of macros to define (-DFOO=bar).
1800 CMAKE_REQUIRED_INCLUDES
1802 list of include directories.
1803 CMAKE_REQUIRED_LINK_OPTIONS
1805 New in version 3.14: list of options to pass to link command.
1806 CMAKE_REQUIRED_LIBRARIES
1809 list of libraries to link.
1810 CMAKE_REQUIRED_QUIET
1812 New in version 3.1: execute quietly without messages.
1813 Example:
1816 CHECK_STRUCT_HAS_MEMBER("struct timeval" tv_sec sys/select.h
1818 HAVE_TIMEVAL_TV_SEC LANGUAGE C)
1819 CheckSymbolExists
1821 Provides a macro to check if a symbol exists as a function, variable,
1822 or macro in C.
1823 check_symbol_exists
1825 check_symbol_exists(<symbol> <files> <variable>)
1827 Check that the <symbol> is available after including given
1829 header <files> and store the result in a <variable>. Specify
1830 the list of files in one argument as a semicolon-separated list.
1831 <variable> will be created as an internal cache variable.
1832 If the header files define the symbol as a macro it is considered
1834 available and assumed to work. If the header files declare the symbol
1835 as a function or variable then the symbol must also be available for
1836 linking (so intrinsics may not be detected). If the symbol is a type,
1837 enum value, or intrinsic it will not be recognized (consider using
1838 CheckTypeSize or CheckSourceCompiles). If the check needs to be done
1839 in C++, consider using CheckCXXSymbolExists instead.
1840 The following variables may be set before calling this macro to modify
1842 the way the check is run:
1843 CMAKE_REQUIRED_FLAGS
1845 string of compile command line flags.
1846 CMAKE_REQUIRED_DEFINITIONS
1848 a ;-list of macros to define (-DFOO=bar).
1849 CMAKE_REQUIRED_INCLUDES
1851 a ;-list of header search paths to pass to the compiler.
1852 CMAKE_REQUIRED_LINK_OPTIONS
1854 New in version 3.14: a ;-list of options to add to the link com‐
1855 mand.
1856 CMAKE_REQUIRED_LIBRARIES
1859 a ;-list of libraries to add to the link command. See policy
1860 CMP0075.
1861 CMAKE_REQUIRED_QUIET
1863 New in version 3.1: execute quietly without messages.
1864 For example:
1867 include(CheckSymbolExists)
1869 # Check for macro SEEK_SET
1871 check_symbol_exists(SEEK_SET "stdio.h" HAVE_SEEK_SET)
1872 # Check for function fopen
1873 check_symbol_exists(fopen "stdio.h" HAVE_FOPEN)
1874 CheckTypeSize
1876 Check sizeof a type
1877 CHECK_TYPE_SIZE
1879 CHECK_TYPE_SIZE(TYPE VARIABLE [BUILTIN_TYPES_ONLY]
1881 [LANGUAGE <language>])
1882 Check if the type exists and determine its size. On return,
1884 HAVE_${VARIABLE} holds the existence of the type, and ${VARI‐
1885 ABLE} holds one of the following:
1886 <size> = type has non-zero size <size>
1888 "0" = type has arch-dependent size (see below)
1889 "" = type does not exist
1890 Both HAVE_${VARIABLE} and ${VARIABLE} will be created as inter‐
1892 nal cache variables.
1893 Furthermore, the variable ${VARIABLE}_CODE holds C preprocessor
1895 code to define the macro ${VARIABLE} to the size of the type, or
1896 leave the macro undefined if the type does not exist.
1897 The variable ${VARIABLE} may be 0 when CMAKE_OSX_ARCHITECTURES
1899 has multiple architectures for building OS X universal binaries.
1900 This indicates that the type size varies across architectures.
1901 In this case ${VARIABLE}_CODE contains C preprocessor tests map‐
1902 ping from each architecture macro to the corresponding type
1903 size. The list of architecture macros is stored in ${VARI‐
1904 ABLE}_KEYS, and the value for each key is stored in ${VARI‐
1905 ABLE}-${KEY}.
1906 If the BUILTIN_TYPES_ONLY option is not given, the macro checks
1908 for headers <sys/types.h>, <stdint.h>, and <stddef.h>, and saves
1909 results in HAVE_SYS_TYPES_H, HAVE_STDINT_H, and HAVE_STDDEF_H.
1910 The type size check automatically includes the available head‐
1911 ers, thus supporting checks of types defined in the headers.
1912 If LANGUAGE is set, the specified compiler will be used to per‐
1914 form the check. Acceptable values are C and CXX.
1915 Despite the name of the macro you may use it to check the size of more
1917 complex expressions, too. To check e.g. for the size of a struct mem‐
1918 ber you can do something like this:
1919 check_type_size("((struct something*)0)->member" SIZEOF_MEMBER)
1921 The following variables may be set before calling this macro to modify
1923 the way the check is run:
1924 CMAKE_REQUIRED_FLAGS
1926 string of compile command line flags.
1927 CMAKE_REQUIRED_DEFINITIONS
1929 list of macros to define (-DFOO=bar).
1930 CMAKE_REQUIRED_INCLUDES
1932 list of include directories.
1933 CMAKE_REQUIRED_LINK_OPTIONS
1935 New in version 3.14: list of options to pass to link command.
1936 CMAKE_REQUIRED_LIBRARIES
1939 list of libraries to link.
1940 CMAKE_REQUIRED_QUIET
1942 New in version 3.1: execute quietly without messages.
1943 CMAKE_EXTRA_INCLUDE_FILES
1946 list of extra headers to include.
1947 CheckVariableExists
1949 Check if the variable exists.
1950 CHECK_VARIABLE_EXISTS
1952 CHECK_VARIABLE_EXISTS(VAR VARIABLE)
1954 VAR - the name of the variable
1956 VARIABLE - variable to store the result
1957 Will be created as an internal cache variable.
1958 This macro is only for C variables.
1960 The following variables may be set before calling this macro to modify
1962 the way the check is run:
1963 CMAKE_REQUIRED_FLAGS
1965 string of compile command line flags.
1966 CMAKE_REQUIRED_DEFINITIONS
1968 list of macros to define (-DFOO=bar).
1969 CMAKE_REQUIRED_LINK_OPTIONS
1971 New in version 3.14: list of options to pass to link command.
1972 CMAKE_REQUIRED_LIBRARIES
1975 list of libraries to link.
1976 CMAKE_REQUIRED_QUIET
1978 New in version 3.1: execute quietly without messages.
1979 CMakeAddFortranSubdirectory
1982 Add a fortran-only subdirectory, find a fortran compiler, and build.
1983 The cmake_add_fortran_subdirectory function adds a subdirectory to a
1985 project that contains a fortran-only subproject. The module will check
1986 the current compiler and see if it can support fortran. If no fortran
1987 compiler is found and the compiler is MSVC, then this module will find
1988 the MinGW gfortran. It will then use an external project to build with
1989 the MinGW tools. It will also create imported targets for the li‐
1990 braries created. This will only work if the fortran code is built into
1991 a dll, so BUILD_SHARED_LIBS is turned on in the project. In addition
1992 the CMAKE_GNUtoMS option is set to on, so that Microsoft .lib files are
1993 created. Usage is as follows:
1994 cmake_add_fortran_subdirectory(
1996 <subdir> # name of subdirectory
1997 PROJECT <project_name> # project name in subdir top CMakeLists.txt
1998 ARCHIVE_DIR <dir> # dir where project places .lib files
1999 RUNTIME_DIR <dir> # dir where project places .dll files
2000 LIBRARIES <lib>... # names of library targets to import
2001 LINK_LIBRARIES # link interface libraries for LIBRARIES
2002 [LINK_LIBS <lib> <dep>...]...
2003 CMAKE_COMMAND_LINE ... # extra command line flags to pass to cmake
2004 NO_EXTERNAL_INSTALL # skip installation of external project
2005 )
2006 Relative paths in ARCHIVE_DIR and RUNTIME_DIR are interpreted with re‐
2008 spect to the build directory corresponding to the source directory in
2009 which the function is invoked.
2010 Limitations:
2012 NO_EXTERNAL_INSTALL is required for forward compatibility with a future
2014 version that supports installation of the external project binaries
2015 during make install.
2016 CMakeBackwardCompatibilityCXX
2018 define a bunch of backwards compatibility variables
2019 CMAKE_ANSI_CXXFLAGS - flag for ansi c++
2021 CMAKE_HAS_ANSI_STRING_STREAM - has <strstream>
2022 include(TestForANSIStreamHeaders)
2023 include(CheckIncludeFileCXX)
2024 include(TestForSTDNamespace)
2025 include(TestForANSIForScope)
2026 CMakeDependentOption
2028 Macro to provide an option dependent on other options.
2029 This macro presents an option to the user only if a set of other condi‐
2031 tions are true.
2032 cmake_dependent_option
2034 cmake_dependent_option(<option> "<help_text>" <value> <depends> <force>)
2036 Makes <option> available to the user if <depends> is true. When
2038 <option> is available, the given <help_text> and initial <value>
2039 are used. If the <depends> condition is not true, <option> will
2040 not be presented and will always have the value given by
2041 <force>. Any value set by the user is preserved for when the op‐
2042 tion is presented again. In case <depends> is a semicolon-sepa‐
2043 rated list, all elements must be true in order to initialize
2044 <option> with <value>.
2045 Example invocation:
2047 cmake_dependent_option(USE_FOO "Use Foo" ON "USE_BAR;NOT USE_ZOT" OFF)
2049 If USE_BAR is true and USE_ZOT is false, this provides an option called
2051 USE_FOO that defaults to ON. Otherwise, it sets USE_FOO to OFF and
2052 hides the option from the user. If the status of USE_BAR or USE_ZOT
2053 ever changes, any value for the USE_FOO option is saved so that when
2054 the option is re-enabled it retains its old value.
2055 New in version 3.22: Full Condition Syntax is now supported. See pol‐
2057 icy CMP0127.
2058 CMakeFindDependencyMacro
2061 find_dependency
2062 The find_dependency() macro wraps a find_package() call for a
2063 package dependency:
2064 find_dependency(<dep> [...])
2066 It is designed to be used in a Package Configuration File
2068 (<PackageName>Config.cmake). find_dependency forwards the cor‐
2069 rect parameters for QUIET and REQUIRED which were passed to the
2070 original find_package() call. Any additional arguments speci‐
2071 fied are forwarded to find_package().
2072 If the dependency could not be found it sets an informative di‐
2074 agnostic message and calls return() to end processing of the
2075 calling package configuration file and return to the find_pack‐
2076 age() command that loaded it.
2077 NOTE:
2079 The call to return() makes this macro unsuitable to call from
2080 Find Modules.
2081 CMakeFindFrameworks
2083 helper module to find OSX frameworks
2084 This module reads hints about search locations from variables:
2086 CMAKE_FIND_FRAMEWORK_EXTRA_LOCATIONS - Extra directories
2088 CMakeFindPackageMode
2090 This file is executed by cmake when invoked with --find-package. It
2091 expects that the following variables are set using -D:
2092 NAME name of the package
2094 COMPILER_ID
2096 the CMake compiler ID for which the result is, i.e. GNU/In‐
2097 tel/Clang/MSVC, etc.
2098 LANGUAGE
2100 language for which the result will be used, i.e. C/CXX/For‐
2101 tran/ASM
2102 MODE
2104 EXIST only check for existence of the given package
2106 COMPILE
2108 print the flags needed for compiling an object file which
2109 uses the given package
2110 LINK print the flags needed for linking when using the given
2112 package
2113 QUIET if TRUE, don't print anything
2115 CMakeGraphVizOptions
2117 The builtin Graphviz support of CMake.
2118 Generating Graphviz files
2120 CMake can generate Graphviz files showing the dependencies between the
2121 targets in a project, as well as external libraries which are linked
2122 against.
2123 When running CMake with the --graphviz=foo.dot option, it produces:
2125 • a foo.dot file, showing all dependencies in the project
2127 • a foo.dot.<target> file for each target, showing on which other tar‐
2129 gets it depends
2130 • a foo.dot.<target>.dependers file for each target, showing which
2132 other targets depend on it
2133 Those .dot files can be converted to images using the dot command from
2135 the Graphviz package:
2136 dot -Tpng -o foo.png foo.dot
2138 New in version 3.10: The different dependency types PUBLIC, INTERFACE
2140 and PRIVATE are represented as solid, dashed and dotted edges.
2141 Variables specific to the Graphviz support
2144 The resulting graphs can be huge. The look and content of the gener‐
2145 ated graphs can be controlled using the file CMakeGraphVizOp‐
2146 tions.cmake. This file is first searched in CMAKE_BINARY_DIR, and then
2147 in CMAKE_SOURCE_DIR. If found, the variables set in it are used to ad‐
2148 just options for the generated Graphviz files.
2149 GRAPHVIZ_GRAPH_NAME
2151 The graph name.
2152 • Mandatory: NO
2154 • Default: value of CMAKE_PROJECT_NAME
2156 GRAPHVIZ_GRAPH_HEADER
2158 The header written at the top of the Graphviz files.
2159 • Mandatory: NO
2161 • Default: "node [ fontsize = "12" ];"
2163 GRAPHVIZ_NODE_PREFIX
2165 The prefix for each node in the Graphviz files.
2166 • Mandatory: NO
2168 • Default: "node"
2170 GRAPHVIZ_EXECUTABLES
2172 Set to FALSE to exclude executables from the generated graphs.
2173 • Mandatory: NO
2175 • Default: TRUE
2177 GRAPHVIZ_STATIC_LIBS
2179 Set to FALSE to exclude static libraries from the generated
2180 graphs.
2181 • Mandatory: NO
2183 • Default: TRUE
2185 GRAPHVIZ_SHARED_LIBS
2187 Set to FALSE to exclude shared libraries from the generated
2188 graphs.
2189 • Mandatory: NO
2191 • Default: TRUE
2193 GRAPHVIZ_MODULE_LIBS
2195 Set to FALSE to exclude module libraries from the generated
2196 graphs.
2197 • Mandatory: NO
2199 • Default: TRUE
2201 GRAPHVIZ_INTERFACE_LIBS
2203 Set to FALSE to exclude interface libraries from the generated
2204 graphs.
2205 • Mandatory: NO
2207 • Default: TRUE
2209 GRAPHVIZ_OBJECT_LIBS
2211 Set to FALSE to exclude object libraries from the generated
2212 graphs.
2213 • Mandatory: NO
2215 • Default: TRUE
2217 GRAPHVIZ_UNKNOWN_LIBS
2219 Set to FALSE to exclude unknown libraries from the generated
2220 graphs.
2221 • Mandatory: NO
2223 • Default: TRUE
2225 GRAPHVIZ_EXTERNAL_LIBS
2227 Set to FALSE to exclude external libraries from the generated
2228 graphs.
2229 • Mandatory: NO
2231 • Default: TRUE
2233 GRAPHVIZ_CUSTOM_TARGETS
2235 Set to TRUE to include custom targets in the generated graphs.
2236 • Mandatory: NO
2238 • Default: FALSE
2240 GRAPHVIZ_IGNORE_TARGETS
2242 A list of regular expressions for names of targets to exclude
2243 from the generated graphs.
2244 • Mandatory: NO
2246 • Default: empty
2248 GRAPHVIZ_GENERATE_PER_TARGET
2250 Set to FALSE to not generate per-target graphs foo.dot.<target>.
2251 • Mandatory: NO
2253 • Default: TRUE
2255 GRAPHVIZ_GENERATE_DEPENDERS
2257 Set to FALSE to not generate depender graphs foo.dot.<tar‐
2258 get>.dependers.
2259 • Mandatory: NO
2261 • Default: TRUE
2263 CMakePackageConfigHelpers
2265 Helpers functions for creating config files that can be included by
2266 other projects to find and use a package.
2267 Adds the configure_package_config_file() and
2269 write_basic_package_version_file() commands.
2270 Generating a Package Configuration File
2272 configure_package_config_file
2273 Create a config file for a project:
2274 configure_package_config_file(<input> <output>
2276 INSTALL_DESTINATION <path>
2277 [PATH_VARS <var1> <var2> ... <varN>]
2278 [NO_SET_AND_CHECK_MACRO]
2279 [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
2280 [INSTALL_PREFIX <path>]
2281 )
2282 configure_package_config_file() should be used instead of the plain
2284 configure_file() command when creating the <PackageName>Config.cmake or
2285 <PackageName>-config.cmake file for installing a project or library.
2286 It helps making the resulting package relocatable by avoiding hardcoded
2287 paths in the installed Config.cmake file.
2288 In a FooConfig.cmake file there may be code like this to make the in‐
2290 stall destinations know to the using project:
2291 set(FOO_INCLUDE_DIR "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
2293 set(FOO_DATA_DIR "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
2294 set(FOO_ICONS_DIR "@CMAKE_INSTALL_PREFIX@/share/icons" )
2295 #...logic to determine installedPrefix from the own location...
2296 set(FOO_CONFIG_DIR "${installedPrefix}/@CONFIG_INSTALL_DIR@" )
2297 All 4 options shown above are not sufficient, since the first 3 hard‐
2299 code the absolute directory locations, and the 4th case works only if
2300 the logic to determine the installedPrefix is correct, and if CON‐
2301 FIG_INSTALL_DIR contains a relative path, which in general cannot be
2302 guaranteed. This has the effect that the resulting FooConfig.cmake
2303 file would work poorly under Windows and OSX, where users are used to
2304 choose the install location of a binary package at install time, inde‐
2305 pendent from how CMAKE_INSTALL_PREFIX was set at build/cmake time.
2306 Using configure_package_config_file helps. If used correctly, it makes
2308 the resulting FooConfig.cmake file relocatable. Usage:
2309 1. write a FooConfig.cmake.in file as you are used to
2311 2. insert a line containing only the string @PACKAGE_INIT@
2313 3. instead of set(FOO_DIR "@SOME_INSTALL_DIR@"), use set(FOO_DIR
2315 "@PACKAGE_SOME_INSTALL_DIR@") (this must be after the @PACKAGE_INIT@
2316 line)
2317 4. instead of using the normal configure_file(), use configure_pack‐
2319 age_config_file()
2320 The <input> and <output> arguments are the input and output file, the
2322 same way as in configure_file().
2323 The <path> given to INSTALL_DESTINATION must be the destination where
2325 the FooConfig.cmake file will be installed to. This path can either be
2326 absolute, or relative to the INSTALL_PREFIX path.
2327 The variables <var1> to <varN> given as PATH_VARS are the variables
2329 which contain install destinations. For each of them the macro will
2330 create a helper variable PACKAGE_<var...>. These helper variables must
2331 be used in the FooConfig.cmake.in file for setting the installed loca‐
2332 tion. They are calculated by configure_package_config_file so that
2333 they are always relative to the installed location of the package.
2334 This works both for relative and also for absolute locations. For ab‐
2335 solute locations it works only if the absolute location is a subdirec‐
2336 tory of INSTALL_PREFIX.
2337 New in version 3.1: If the INSTALL_PREFIX argument is passed, this is
2339 used as base path to calculate all the relative paths. The <path> ar‐
2340 gument must be an absolute path. If this argument is not passed, the
2341 CMAKE_INSTALL_PREFIX variable will be used instead. The default value
2342 is good when generating a FooConfig.cmake file to use your package from
2343 the install tree. When generating a FooConfig.cmake file to use your
2344 package from the build tree this option should be used.
2345 By default configure_package_config_file also generates two helper
2348 macros, set_and_check() and check_required_components() into the
2349 FooConfig.cmake file.
2350 set_and_check() should be used instead of the normal set() command for
2352 setting directories and file locations. Additionally to setting the
2353 variable it also checks that the referenced file or directory actually
2354 exists and fails with a FATAL_ERROR otherwise. This makes sure that
2355 the created FooConfig.cmake file does not contain wrong references.
2356 When using the NO_SET_AND_CHECK_MACRO, this macro is not generated into
2357 the FooConfig.cmake file.
2358 check_required_components(<PackageName>) should be called at the end of
2360 the FooConfig.cmake file. This macro checks whether all requested,
2361 non-optional components have been found, and if this is not the case,
2362 sets the Foo_FOUND variable to FALSE, so that the package is considered
2363 to be not found. It does that by testing the Foo_<Component>_FOUND
2364 variables for all requested required components. This macro should be
2365 called even if the package doesn't provide any components to make sure
2366 users are not specifying components erroneously. When using the
2367 NO_CHECK_REQUIRED_COMPONENTS_MACRO option, this macro is not generated
2368 into the FooConfig.cmake file.
2369 For an example see below the documentation for
2371 write_basic_package_version_file().
2372 Generating a Package Version File
2374 write_basic_package_version_file
2375 Create a version file for a project:
2376 write_basic_package_version_file(<filename>
2378 [VERSION <major.minor.patch>]
2379 COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion>
2380 [ARCH_INDEPENDENT] )
2381 Writes a file for use as <PackageName>ConfigVersion.cmake file to
2383 <filename>. See the documentation of find_package() for details on
2384 this.
2385 <filename> is the output filename, it should be in the build tree.
2387 <major.minor.patch> is the version number of the project to be in‐
2388 stalled.
2389 If no VERSION is given, the PROJECT_VERSION variable is used. If this
2391 hasn't been set, it errors out.
2392 The COMPATIBILITY mode AnyNewerVersion means that the installed package
2394 version will be considered compatible if it is newer or exactly the
2395 same as the requested version. This mode should be used for packages
2396 which are fully backward compatible, also across major versions. If
2397 SameMajorVersion is used instead, then the behavior differs from
2398 AnyNewerVersion in that the major version number must be the same as
2399 requested, e.g. version 2.0 will not be considered compatible if 1.0
2400 is requested. This mode should be used for packages which guarantee
2401 backward compatibility within the same major version. If SameMinorVer‐
2402 sion is used, the behavior is the same as SameMajorVersion, but both
2403 major and minor version must be the same as requested, e.g version 0.2
2404 will not be compatible if 0.1 is requested. If ExactVersion is used,
2405 then the package is only considered compatible if the requested version
2406 matches exactly its own version number (not considering the tweak ver‐
2407 sion). For example, version 1.2.3 of a package is only considered com‐
2408 patible to requested version 1.2.3. This mode is for packages without
2409 compatibility guarantees. If your project has more elaborated version
2410 matching rules, you will need to write your own custom ConfigVer‐
2411 sion.cmake file instead of using this macro.
2412 New in version 3.11: The SameMinorVersion compatibility mode.
2414 New in version 3.14: If ARCH_INDEPENDENT is given, the installed pack‐
2417 age version will be considered compatible even if it was built for a
2418 different architecture than the requested architecture. Otherwise, an
2419 architecture check will be performed, and the package will be consid‐
2420 ered compatible only if the architecture matches exactly. For example,
2421 if the package is built for a 32-bit architecture, the package is only
2422 considered compatible if it is used on a 32-bit architecture, unless
2423 ARCH_INDEPENDENT is given, in which case the package is considered com‐
2424 patible on any architecture.
2425 NOTE:
2428 ARCH_INDEPENDENT is intended for header-only libraries or similar
2429 packages with no binaries.
2430 New in version 3.19: COMPATIBILITY_MODE AnyNewerVersion, SameMajorVer‐
2432 sion and SameMinorVersion handle the version range if any is specified
2433 (see find_package() command for the details). ExactVersion mode is in‐
2434 compatible with version ranges and will display an author warning if
2435 one is specified.
2436 Internally, this macro executes configure_file() to create the result‐
2439 ing version file. Depending on the COMPATIBILITY, the corresponding
2440 BasicConfigVersion-<COMPATIBILITY>.cmake.in file is used. Please note
2441 that these files are internal to CMake and you should not call config‐
2442 ure_file() on them yourself, but they can be used as starting point to
2443 create more sophisticted custom ConfigVersion.cmake files.
2444 Example Generating Package Files
2446 Example using both configure_package_config_file() and write_ba‐
2447 sic_package_version_file():
2448 CMakeLists.txt:
2450 set(INCLUDE_INSTALL_DIR include/ ... CACHE )
2452 set(LIB_INSTALL_DIR lib/ ... CACHE )
2453 set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
2454 #...
2455 include(CMakePackageConfigHelpers)
2456 configure_package_config_file(FooConfig.cmake.in
2457 ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2458 INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
2459 PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
2460 write_basic_package_version_file(
2461 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2462 VERSION 1.2.3
2463 COMPATIBILITY SameMajorVersion )
2464 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
2465 ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
2466 DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake )
2467 FooConfig.cmake.in:
2469 set(FOO_VERSION x.y.z)
2471 ...
2472 @PACKAGE_INIT@
2473 ...
2474 set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
2475 set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")
2476 check_required_components(Foo)
2478 CMakePrintHelpers
2480 Convenience functions for printing properties and variables, useful
2481 e.g. for debugging.
2482 cmake_print_properties([TARGETS target1 .. targetN]
2484 [SOURCES source1 .. sourceN]
2485 [DIRECTORIES dir1 .. dirN]
2486 [TESTS test1 .. testN]
2487 [CACHE_ENTRIES entry1 .. entryN]
2488 PROPERTIES prop1 .. propN )
2489 This function prints the values of the properties of the given targets,
2491 source files, directories, tests or cache entries. Exactly one of the
2492 scope keywords must be used. Example:
2493 cmake_print_properties(TARGETS foo bar PROPERTIES
2495 LOCATION INTERFACE_INCLUDE_DIRECTORIES)
2496 This will print the LOCATION and INTERFACE_INCLUDE_DIRECTORIES proper‐
2498 ties for both targets foo and bar.
2499 cmake_print_variables(var1 var2 .. varN)
2501 This function will print the name of each variable followed by its
2503 value. Example:
2504 cmake_print_variables(CMAKE_C_COMPILER CMAKE_MAJOR_VERSION DOES_NOT_EXIST)
2506 Gives:
2508 -- CMAKE_C_COMPILER="/usr/bin/gcc" ; CMAKE_MAJOR_VERSION="2" ; DOES_NOT_EXIST=""
2510 CMakePrintSystemInformation
2512 Print system information.
2513 This module serves diagnostic purposes. Just include it in a project to
2515 see various internal CMake variables.
2516 CMakePushCheckState
2518 This module defines three macros: CMAKE_PUSH_CHECK_STATE()
2519 CMAKE_POP_CHECK_STATE() and CMAKE_RESET_CHECK_STATE() These macros can
2520 be used to save, restore and reset (i.e., clear contents) the state of
2521 the variables CMAKE_REQUIRED_FLAGS, CMAKE_REQUIRED_DEFINITIONS,
2522 CMAKE_REQUIRED_LINK_OPTIONS, CMAKE_REQUIRED_LIBRARIES, CMAKE_RE‐
2523 QUIRED_INCLUDES and CMAKE_EXTRA_INCLUDE_FILES used by the various
2524 Check-files coming with CMake, like e.g. check_function_exists() etc.
2525 The variable contents are pushed on a stack, pushing multiple times is
2526 supported. This is useful e.g. when executing such tests in a
2527 Find-module, where they have to be set, but after the Find-module has
2528 been executed they should have the same value as they had before.
2529 CMAKE_PUSH_CHECK_STATE() macro receives optional argument RESET.
2531 Whether it's specified, CMAKE_PUSH_CHECK_STATE() will set all CMAKE_RE‐
2532 QUIRED_* variables to empty values, same as CMAKE_RESET_CHECK_STATE()
2533 call will do.
2534 Usage:
2536 cmake_push_check_state(RESET)
2538 set(CMAKE_REQUIRED_DEFINITIONS -DSOME_MORE_DEF)
2539 check_function_exists(...)
2540 cmake_reset_check_state()
2541 set(CMAKE_REQUIRED_DEFINITIONS -DANOTHER_DEF)
2542 check_function_exists(...)
2543 cmake_pop_check_state()
2544 CMakeVerifyManifest
2546 CMakeVerifyManifest.cmake
2547 This script is used to verify that embedded manifests and side by side
2549 manifests for a project match. To run this script, cd to a directory
2550 and run the script with cmake -P. On the command line you can pass in
2551 versions that are OK even if not found in the .manifest files. For ex‐
2552 ample, cmake -Dallow_versions=8.0.50608.0 -PCmakeVerifyManifest.cmake
2553 could be used to allow an embedded manifest of 8.0.50608.0 to be used
2554 in a project even if that version was not found in the .manifest file.
2555 CPack
2557 Configure generators for binary installers and source packages.
2558 Introduction
2560 The CPack module generates the configuration files CPackConfig.cmake
2561 and CPackSourceConfig.cmake. They are intended for use in a subsequent
2562 run of the cpack program where they steer the generation of installers
2563 or/and source packages.
2564 Depending on the CMake generator, the CPack module may also add two new
2566 build targets, package and package_source. See the packaging targets
2567 section below for details.
2568 The generated binary installers will contain all files that have been
2570 installed via CMake's install() command (and the deprecated commands
2571 install_files(), install_programs(), and install_targets()). Note that
2572 the DESTINATION option of the install() command must be a relative
2573 path; otherwise installed files are ignored by CPack.
2574 Certain kinds of binary installers can be configured such that users
2576 can select individual application components to install. See the
2577 CPackComponent module for further details.
2578 Source packages (configured through CPackSourceConfig.cmake and gener‐
2580 ated by the CPack Archive Generator) will contain all source files in
2581 the project directory except those specified in
2582 CPACK_SOURCE_IGNORE_FILES.
2583 CPack Generators
2585 The CPACK_GENERATOR variable has different meanings in different con‐
2586 texts. In a CMakeLists.txt file, CPACK_GENERATOR is a list of genera‐
2587 tors: and when cpack is run with no other arguments, it will iterate
2588 over that list and produce one package for each generator. In a
2589 CPACK_PROJECT_CONFIG_FILE, CPACK_GENERATOR is a string naming a single
2590 generator. If you need per-cpack-generator logic to control other
2591 cpack settings, then you need a CPACK_PROJECT_CONFIG_FILE. If set, the
2592 CPACK_PROJECT_CONFIG_FILE is included automatically on a per-generator
2593 basis. It only need contain overrides.
2594 Here's how it works:
2596 • cpack runs
2598 • it includes CPackConfig.cmake
2600 • it iterates over the generators given by the -G command line option,
2602 or if no such option was specified, over the list of generators given
2603 by the CPACK_GENERATOR variable set in the CPackConfig.cmake input
2604 file.
2605 • foreach generator, it then
2607 • sets CPACK_GENERATOR to the one currently being iterated
2609 • includes the CPACK_PROJECT_CONFIG_FILE
2611 • produces the package for that generator
2613 This is the key: For each generator listed in CPACK_GENERATOR in CPack‐
2615 Config.cmake, cpack will reset CPACK_GENERATOR internally to the one
2616 currently being used and then include the CPACK_PROJECT_CONFIG_FILE.
2617 For a list of available generators, see cpack-generators(7).
2619 Targets package and package_source
2621 If CMake is run with the Makefile, Ninja, or Xcode generator, then in‐
2622 clude(CPack) generates a target package. This makes it possible to
2623 build a binary installer from CMake, Make, or Ninja: Instead of cpack,
2624 one may call cmake --build . --target package or make package or ninja
2625 package. The VS generator creates an uppercase target PACKAGE.
2626 If CMake is run with the Makefile or Ninja generator, then in‐
2628 clude(CPack) also generates a target package_source. To build a source
2629 package, instead of cpack -G TGZ --config CPackSourceConfig.cmake one
2630 may call cmake --build . --target package_source, make package_source,
2631 or ninja package_source.
2632 Variables common to all CPack Generators
2634 Before including this CPack module in your CMakeLists.txt file, there
2635 are a variety of variables that can be set to customize the resulting
2636 installers. The most commonly-used variables are:
2637 CPACK_PACKAGE_NAME
2639 The name of the package (or application). If not specified, it
2640 defaults to the project name.
2641 CPACK_PACKAGE_VENDOR
2643 The name of the package vendor. (e.g., "Kitware"). The default
2644 is "Humanity".
2645 CPACK_PACKAGE_DIRECTORY
2647 The directory in which CPack is doing its packaging. If it is
2648 not set then this will default (internally) to the build dir.
2649 This variable may be defined in a CPack config file or from the
2650 cpack command line option -B. If set, the command line option
2651 overrides the value found in the config file.
2652 CPACK_PACKAGE_VERSION_MAJOR
2654 Package major version. This variable will always be set, but
2655 its default value depends on whether or not version details were
2656 given to the project() command in the top level CMakeLists.txt
2657 file. If version details were given, the default value will be
2658 CMAKE_PROJECT_VERSION_MAJOR. If no version details were given,
2659 a default version of 0.1.1 will be assumed, leading to
2660 CPACK_PACKAGE_VERSION_MAJOR having a default value of 0.
2661 CPACK_PACKAGE_VERSION_MINOR
2663 Package minor version. The default value is determined based on
2664 whether or not version details were given to the project() com‐
2665 mand in the top level CMakeLists.txt file. If version details
2666 were given, the default value will be CMAKE_PROJECT_VERSION_MI‐
2667 NOR, but if no minor version component was specified then
2668 CPACK_PACKAGE_VERSION_MINOR will be left unset. If no project
2669 version was given at all, a default version of 0.1.1 will be as‐
2670 sumed, leading to CPACK_PACKAGE_VERSION_MINOR having a default
2671 value of 1.
2672 CPACK_PACKAGE_VERSION_PATCH
2674 Package patch version. The default value is determined based on
2675 whether or not version details were given to the project() com‐
2676 mand in the top level CMakeLists.txt file. If version details
2677 were given, the default value will be CMAKE_PROJECT_VER‐
2678 SION_PATCH, but if no patch version component was specified then
2679 CPACK_PACKAGE_VERSION_PATCH will be left unset. If no project
2680 version was given at all, a default version of 0.1.1 will be as‐
2681 sumed, leading to CPACK_PACKAGE_VERSION_PATCH having a default
2682 value of 1.
2683 CPACK_PACKAGE_DESCRIPTION
2685 A description of the project, used in places such as the intro‐
2686 duction screen of CPack-generated Windows installers. If not
2687 set, the value of this variable is populated from the file named
2688 by CPACK_PACKAGE_DESCRIPTION_FILE.
2689 CPACK_PACKAGE_DESCRIPTION_FILE
2691 A text file used to describe the project when
2692 CPACK_PACKAGE_DESCRIPTION is not explicitly set. The default
2693 value for CPACK_PACKAGE_DESCRIPTION_FILE points to a built-in
2694 template file Templates/CPack.GenericDescription.txt.
2695 CPACK_PACKAGE_DESCRIPTION_SUMMARY
2697 Short description of the project (only a few words). If the
2698 CMAKE_PROJECT_DESCRIPTION variable is set, it is used as the de‐
2699 fault value, otherwise the default will be a string generated by
2700 CMake based on CMAKE_PROJECT_NAME.
2701 CPACK_PACKAGE_HOMEPAGE_URL
2703 Project homepage URL. The default value is taken from the
2704 CMAKE_PROJECT_HOMEPAGE_URL variable, which is set by the top
2705 level project() command, or else the default will be empty if no
2706 URL was provided to project().
2707 CPACK_PACKAGE_FILE_NAME
2709 The name of the package file to generate, not including the ex‐
2710 tension. For example, cmake-2.6.1-Linux-i686. The default
2711 value is:
2712 ${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}
2714 CPACK_PACKAGE_INSTALL_DIRECTORY
2716 Installation directory on the target system. This may be used by
2717 some CPack generators like NSIS to create an installation direc‐
2718 tory e.g., "CMake 2.5" below the installation prefix. All in‐
2719 stalled elements will be put inside this directory.
2720 CPACK_PACKAGE_ICON
2722 A branding image that will be displayed inside the installer
2723 (used by GUI installers).
2724 CPACK_PACKAGE_CHECKSUM
2726 New in version 3.7.
2727 An algorithm that will be used to generate an additional file
2730 with the checksum of the package. The output file name will be:
2731 ${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}
2733 Supported algorithms are those listed by the string(<HASH>) com‐
2735 mand.
2736 CPACK_PROJECT_CONFIG_FILE
2738 CPack-time project CPack configuration file. This file is in‐
2739 cluded at cpack time, once per generator after CPack has set
2740 CPACK_GENERATOR to the actual generator being used. It allows
2741 per-generator setting of CPACK_* variables at cpack time.
2742 CPACK_RESOURCE_FILE_LICENSE
2744 License to be embedded in the installer. It will typically be
2745 displayed to the user by the produced installer (often with an
2746 explicit "Accept" button, for graphical installers) prior to in‐
2747 stallation. This license file is NOT added to the installed
2748 files but is used by some CPack generators like NSIS. If you
2749 want to install a license file (may be the same as this one)
2750 along with your project, you must add an appropriate CMake in‐
2751 stall() command in your CMakeLists.txt.
2752 CPACK_RESOURCE_FILE_README
2754 ReadMe file to be embedded in the installer. It typically de‐
2755 scribes in some detail the purpose of the project during the in‐
2756 stallation. Not all CPack generators use this file.
2757 CPACK_RESOURCE_FILE_WELCOME
2759 Welcome file to be embedded in the installer. It welcomes users
2760 to this installer. Typically used in the graphical installers
2761 on Windows and Mac OS X.
2762 CPACK_MONOLITHIC_INSTALL
2764 Disables the component-based installation mechanism. When set,
2765 the component specification is ignored and all installed items
2766 are put in a single "MONOLITHIC" package. Some CPack generators
2767 do monolithic packaging by default and may be asked to do compo‐
2768 nent packaging by setting CPACK_<GENNAME>_COMPONENT_INSTALL to
2769 TRUE.
2770 CPACK_GENERATOR
2772 List of CPack generators to use. If not specified, CPack will
2773 create a set of options following the naming pattern
2774 CPACK_BINARY_<GENNAME> (e.g. CPACK_BINARY_NSIS) allowing the
2775 user to enable/disable individual generators. If the -G option
2776 is given on the cpack command line, it will override this vari‐
2777 able and any CPACK_BINARY_<GENNAME> options.
2778 CPACK_OUTPUT_CONFIG_FILE
2780 The name of the CPack binary configuration file. This file is
2781 the CPack configuration generated by the CPack module for binary
2782 installers. Defaults to CPackConfig.cmake.
2783 CPACK_PACKAGE_EXECUTABLES
2785 Lists each of the executables and associated text label to be
2786 used to create Start Menu shortcuts. For example, setting this
2787 to the list ccmake;CMake will create a shortcut named "CMake"
2788 that will execute the installed executable ccmake. Not all
2789 CPack generators use it (at least NSIS, WIX and OSXX11 do).
2790 CPACK_STRIP_FILES
2792 List of files to be stripped. Starting with CMake 2.6.0,
2793 CPACK_STRIP_FILES will be a boolean variable which enables
2794 stripping of all files (a list of files evaluates to TRUE in
2795 CMake, so this change is compatible).
2796 CPACK_VERBATIM_VARIABLES
2798 New in version 3.4.
2799 If set to TRUE, values of variables prefixed with CPACK_ will be
2802 escaped before being written to the configuration files, so that
2803 the cpack program receives them exactly as they were specified.
2804 If not, characters like quotes and backslashes can cause parsing
2805 errors or alter the value received by the cpack program. De‐
2806 faults to FALSE for backwards compatibility.
2807 CPACK_THREADS
2809 New in version 3.20.
2810 Number of threads to use when performing parallelized opera‐
2813 tions, such as compressing the installer package.
2814 Some compression methods used by CPack generators such as Debian
2816 or Archive may take advantage of multiple CPU cores to speed up
2817 compression. CPACK_THREADS can be set to specify how many
2818 threads will be used for compression.
2819 A positive integer can be used to specify an exact desired
2821 thread count.
2822 When given a negative integer CPack will use the absolute value
2824 as the upper limit but may choose a lower value based on the
2825 available hardware concurrency.
2826 Given 0 CPack will try to use all available CPU cores.
2828 By default CPACK_THREADS is set to 1.
2830 Currently only xz compression may take advantage of multiple
2832 cores. Other compression methods ignore this value and use only
2833 one thread.
2834 New in version 3.21: Official CMake binaries available on
2836 cmake.org now ship with a liblzma that supports parallel com‐
2837 pression. Older versions did not.
2838 Variables for Source Package Generators
2841 The following CPack variables are specific to source packages, and will
2842 not affect binary packages:
2843 CPACK_SOURCE_PACKAGE_FILE_NAME
2845 The name of the source package. For example cmake-2.6.1.
2846 CPACK_SOURCE_STRIP_FILES
2848 List of files in the source tree that will be stripped. Start‐
2849 ing with CMake 2.6.0, CPACK_SOURCE_STRIP_FILES will be a boolean
2850 variable which enables stripping of all files (a list of files
2851 evaluates to TRUE in CMake, so this change is compatible).
2852 CPACK_SOURCE_GENERATOR
2854 List of generators used for the source packages. As with
2855 CPACK_GENERATOR, if this is not specified then CPack will create
2856 a set of options (e.g. CPACK_SOURCE_ZIP) allowing users to se‐
2857 lect which packages will be generated.
2858 CPACK_SOURCE_OUTPUT_CONFIG_FILE
2860 The name of the CPack source configuration file. This file is
2861 the CPack configuration generated by the CPack module for source
2862 installers. Defaults to CPackSourceConfig.cmake.
2863 CPACK_SOURCE_IGNORE_FILES
2865 Pattern of files in the source tree that won't be packaged when
2866 building a source package. This is a list of regular expression
2867 patterns (that must be properly escaped), e.g.,
2868 /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*
2869 Variables for Advanced Use
2871 The following variables are for advanced uses of CPack:
2872 CPACK_CMAKE_GENERATOR
2874 What CMake generator should be used if the project is a CMake
2875 project. Defaults to the value of CMAKE_GENERATOR. Few users
2876 will want to change this setting.
2877 CPACK_INSTALL_CMAKE_PROJECTS
2879 List of four values that specify what project to install. The
2880 four values are: Build directory, Project Name, Project Compo‐
2881 nent, Directory. If omitted, CPack will build an installer that
2882 installs everything.
2883 CPACK_SYSTEM_NAME
2885 System name, defaults to the value of CMAKE_SYSTEM_NAME, except
2886 on Windows where it will be win32 or win64.
2887 CPACK_PACKAGE_VERSION
2889 Package full version, used internally. By default, this is
2890 built from CPACK_PACKAGE_VERSION_MAJOR,
2891 CPACK_PACKAGE_VERSION_MINOR, and CPACK_PACKAGE_VERSION_PATCH.
2892 CPACK_TOPLEVEL_TAG
2894 Directory for the installed files.
2895 CPACK_INSTALL_COMMANDS
2897 Extra commands to install components. The environment variable
2898 CMAKE_INSTALL_PREFIX is set to the temporary install directory
2899 during execution.
2900 CPACK_INSTALL_SCRIPTS
2902 New in version 3.16.
2903 Extra CMake scripts executed by CPack during its local staging
2906 installation. They are executed before installing the files to
2907 be packaged. The scripts are not called by a standalone install
2908 (e.g.: make install). For every script, the following variables
2909 will be set: CMAKE_CURRENT_SOURCE_DIR, CMAKE_CURRENT_BINARY_DIR
2910 and CMAKE_INSTALL_PREFIX (which is set to the staging install
2911 directory). The singular form CMAKE_INSTALL_SCRIPT is supported
2912 as an alternative variable for historical reasons, but its value
2913 is ignored if CMAKE_INSTALL_SCRIPTS is set and a warning will be
2914 issued.
2915 See also CPACK_PRE_BUILD_SCRIPTS and CPACK_POST_BUILD_SCRIPTS
2917 which can be used to specify scripts to be executed later in the
2918 packaging process.
2919 CPACK_PRE_BUILD_SCRIPTS
2921 New in version 3.19.
2922 List of CMake scripts to execute after CPack has installed the
2925 files to be packaged into a staging directory and before produc‐
2926 ing the package(s) from those files. See also
2927 CPACK_INSTALL_SCRIPTS and CPACK_POST_BUILD_SCRIPTS.
2928 CPACK_POST_BUILD_SCRIPTS
2930 New in version 3.19.
2931 List of CMake scripts to execute after CPack has produced the
2934 resultant packages and before copying them back to the build di‐
2935 rectory. See also CPACK_INSTALL_SCRIPTS,
2936 CPACK_PRE_BUILD_SCRIPTS and CPACK_PACKAGE_FILES.
2937 CPACK_PACKAGE_FILES
2939 New in version 3.19.
2940 List of package files created in the staging directory, with
2943 each file provided as a full absolute path. This variable is
2944 populated by CPack just before invoking the post-build scripts
2945 listed in CPACK_POST_BUILD_SCRIPTS. It is the preferred way for
2946 the post-build scripts to know the set of package files to oper‐
2947 ate on. Projects should not try to set this variable them‐
2948 selves.
2949 CPACK_INSTALLED_DIRECTORIES
2951 Extra directories to install.
2952 CPACK_PACKAGE_INSTALL_REGISTRY_KEY
2954 Registry key used when installing this project. This is only
2955 used by installers for Windows. The default value is based on
2956 the installation directory.
2957 CPACK_CREATE_DESKTOP_LINKS
2959 List of desktop links to create. Each desktop link requires a
2960 corresponding start menu shortcut as created by
2961 CPACK_PACKAGE_EXECUTABLES.
2962 CPACK_BINARY_<GENNAME>
2964 CPack generated options for binary generators. The CPack.cmake
2965 module generates (when CPACK_GENERATOR is not set) a set of
2966 CMake options (see CMake option() command) which may then be
2967 used to select the CPack generator(s) to be used when building
2968 the package target or when running cpack without the -G option.
2969 CPackComponent
2971 Configure components for binary installers and source packages.
2972 Introduction
2974 This module is automatically included by CPack.
2975 Certain binary installers (especially the graphical installers) gener‐
2977 ated by CPack allow users to select individual application components
2978 to install. This module allows developers to configure the packaging
2979 of such components.
2980 Contents is assigned to components by the COMPONENT argument of CMake's
2982 install() command. Components can be annotated with user-friendly
2983 names and descriptions, inter-component dependencies, etc., and grouped
2984 in various ways to customize the resulting installer, using the com‐
2985 mands described below.
2986 To specify different groupings for different CPack generators use a
2988 CPACK_PROJECT_CONFIG_FILE.
2989 Variables
2991 The following variables influence the component-specific packaging:
2992 CPACK_COMPONENTS_ALL
2994 The list of component to install.
2995 The default value of this variable is computed by CPack and con‐
2997 tains all components defined by the project. The user may set
2998 it to only include the specified components.
2999 Instead of specifying all the desired components, it is possible
3001 to obtain a list of all defined components and then remove the
3002 unwanted ones from the list. The get_cmake_property() command
3003 can be used to obtain the COMPONENTS property, then the list(RE‐
3004 MOVE_ITEM) command can be used to remove the unwanted ones. For
3005 example, to use all defined components except foo and bar:
3006 get_cmake_property(CPACK_COMPONENTS_ALL COMPONENTS)
3008 list(REMOVE_ITEM CPACK_COMPONENTS_ALL "foo" "bar")
3009 CPACK_<GENNAME>_COMPONENT_INSTALL
3011 Enable/Disable component install for CPack generator <GENNAME>.
3012 Each CPack Generator (RPM, DEB, ARCHIVE, NSIS, DMG, etc...) has
3014 a legacy default behavior. e.g. RPM builds monolithic whereas
3015 NSIS builds component. One can change the default behavior by
3016 setting this variable to 0/1 or OFF/ON.
3017 CPACK_COMPONENTS_GROUPING
3019 Specify how components are grouped for multi-package compo‐
3020 nent-aware CPack generators.
3021 Some generators like RPM or ARCHIVE (TGZ, ZIP, ...) may generate
3023 several packages files when there are components, depending on
3024 the value of this variable:
3025 • ONE_PER_GROUP (default): create one package per component
3027 group
3028 • IGNORE : create one package per component (ignore the groups)
3030 • ALL_COMPONENTS_IN_ONE : create a single package with all re‐
3032 quested components
3033 CPACK_COMPONENT_<compName>_DISPLAY_NAME
3035 The name to be displayed for a component.
3036 CPACK_COMPONENT_<compName>_DESCRIPTION
3038 The description of a component.
3039 CPACK_COMPONENT_<compName>_GROUP
3041 The group of a component.
3042 CPACK_COMPONENT_<compName>_DEPENDS
3044 The dependencies (list of components) on which this component
3045 depends.
3046 CPACK_COMPONENT_<compName>_HIDDEN
3048 True if this component is hidden from the user.
3049 CPACK_COMPONENT_<compName>_REQUIRED
3051 True if this component is required.
3052 CPACK_COMPONENT_<compName>_DISABLED
3054 True if this component is not selected to be installed by de‐
3055 fault.
3056 Commands
3058 Add component
3059 cpack_add_component
3060 Describe an installation component.
3062 cpack_add_component(compname
3064 [DISPLAY_NAME name]
3065 [DESCRIPTION description]
3066 [HIDDEN | REQUIRED | DISABLED ]
3067 [GROUP group]
3068 [DEPENDS comp1 comp2 ... ]
3069 [INSTALL_TYPES type1 type2 ... ]
3070 [DOWNLOADED]
3071 [ARCHIVE_FILE filename]
3072 [PLIST filename])
3073 compname is the name of an installation component, as defined by the
3075 COMPONENT argument of one or more CMake install() commands. With the
3076 cpack_add_component command one can set a name, a description, and
3077 other attributes of an installation component. One can also assign a
3078 component to a component group.
3079 DISPLAY_NAME is the displayed name of the component, used in graphical
3081 installers to display the component name. This value can be any
3082 string.
3083 DESCRIPTION is an extended description of the component, used in graph‐
3085 ical installers to give the user additional information about the com‐
3086 ponent. Descriptions can span multiple lines using \n as the line sep‐
3087 arator. Typically, these descriptions should be no more than a few
3088 lines long.
3089 HIDDEN indicates that this component will be hidden in the graphical
3091 installer, so that the user cannot directly change whether it is in‐
3092 stalled or not.
3093 REQUIRED indicates that this component is required, and therefore will
3095 always be installed. It will be visible in the graphical installer,
3096 but it cannot be unselected. (Typically, required components are shown
3097 greyed out).
3098 DISABLED indicates that this component should be disabled (unselected)
3100 by default. The user is free to select this component for installa‐
3101 tion, unless it is also HIDDEN.
3102 DEPENDS lists the components on which this component depends. If this
3104 component is selected, then each of the components listed must also be
3105 selected. The dependency information is encoded within the installer
3106 itself, so that users cannot install inconsistent sets of components.
3107 GROUP names the component group of which this component is a part. If
3109 not provided, the component will be a standalone component, not part of
3110 any component group. Component groups are described with the
3111 cpack_add_component_group command, detailed below.
3112 INSTALL_TYPES lists the installation types of which this component is a
3114 part. When one of these installations types is selected, this compo‐
3115 nent will automatically be selected. Installation types are described
3116 with the cpack_add_install_type command, detailed below.
3117 DOWNLOADED indicates that this component should be downloaded
3119 on-the-fly by the installer, rather than packaged in with the installer
3120 itself. For more information, see the cpack_configure_downloads com‐
3121 mand.
3122 ARCHIVE_FILE provides a name for the archive file created by CPack to
3124 be used for downloaded components. If not supplied, CPack will create
3125 a file with some name based on CPACK_PACKAGE_FILE_NAME and the name of
3126 the component. See cpack_configure_downloads for more information.
3127 PLIST gives a filename that is passed to pkgbuild with the --compo‐
3129 nent-plist argument when using the productbuild generator.
3130 Add component group
3132 cpack_add_component_group
3133 Describes a group of related CPack installation components.
3135 cpack_add_component_group(groupname
3137 [DISPLAY_NAME name]
3138 [DESCRIPTION description]
3139 [PARENT_GROUP parent]
3140 [EXPANDED]
3141 [BOLD_TITLE])
3142 The cpack_add_component_group describes a group of installation compo‐
3144 nents, which will be placed together within the listing of options.
3145 Typically, component groups allow the user to select/deselect all of
3146 the components within a single group via a single group-level option.
3147 Use component groups to reduce the complexity of installers with many
3148 options. groupname is an arbitrary name used to identify the group in
3149 the GROUP argument of the cpack_add_component command, which is used to
3150 place a component in a group. The name of the group must not conflict
3151 with the name of any component.
3152 DISPLAY_NAME is the displayed name of the component group, used in
3154 graphical installers to display the component group name. This value
3155 can be any string.
3156 DESCRIPTION is an extended description of the component group, used in
3158 graphical installers to give the user additional information about the
3159 components within that group. Descriptions can span multiple lines us‐
3160 ing \n as the line separator. Typically, these descriptions should be
3161 no more than a few lines long.
3162 PARENT_GROUP, if supplied, names the parent group of this group. Par‐
3164 ent groups are used to establish a hierarchy of groups, providing an
3165 arbitrary hierarchy of groups.
3166 EXPANDED indicates that, by default, the group should show up as "ex‐
3168 panded", so that the user immediately sees all of the components within
3169 the group. Otherwise, the group will initially show up as a single en‐
3170 try.
3171 BOLD_TITLE indicates that the group title should appear in bold, to
3173 call the user's attention to the group.
3174 Add installation type
3176 cpack_add_install_type
3177 Add a new installation type containing a set of predefined component
3179 selections to the graphical installer.
3180 cpack_add_install_type(typename
3182 [DISPLAY_NAME name])
3183 The cpack_add_install_type command identifies a set of preselected com‐
3185 ponents that represents a common use case for an application. For ex‐
3186 ample, a "Developer" install type might include an application along
3187 with its header and library files, while an "End user" install type
3188 might just include the application's executable. Each component iden‐
3189 tifies itself with one or more install types via the INSTALL_TYPES ar‐
3190 gument to cpack_add_component.
3191 DISPLAY_NAME is the displayed name of the install type, which will typ‐
3193 ically show up in a drop-down box within a graphical installer. This
3194 value can be any string.
3195 Configure downloads
3197 cpack_configure_downloads
3198 Configure CPack to download selected components on-the-fly as part of
3200 the installation process.
3201 cpack_configure_downloads(site
3203 [UPLOAD_DIRECTORY dirname]
3204 [ALL]
3205 [ADD_REMOVE|NO_ADD_REMOVE])
3206 The cpack_configure_downloads command configures installation-time
3208 downloads of selected components. For each downloadable component,
3209 CPack will create an archive containing the contents of that component,
3210 which should be uploaded to the given site. When the user selects that
3211 component for installation, the installer will download and extract the
3212 component in place. This feature is useful for creating small install‐
3213 ers that only download the requested components, saving bandwidth. Ad‐
3214 ditionally, the installers are small enough that they will be installed
3215 as part of the normal installation process, and the "Change" button in
3216 Windows Add/Remove Programs control panel will allow one to add or re‐
3217 move parts of the application after the original installation. On Win‐
3218 dows, the downloaded-components functionality requires the ZipDLL
3219 plug-in for NSIS, available at:
3220 http://nsis.sourceforge.net/ZipDLL_plug-in
3222 On macOS, installers that download components on-the-fly can only be
3224 built and installed on system using macOS 10.5 or later.
3225 The site argument is a URL where the archives for downloadable compo‐
3227 nents will reside, e.g., https://cmake.org/files/2.6.1/installer/ All
3228 of the archives produced by CPack should be uploaded to that location.
3229 UPLOAD_DIRECTORY is the local directory where CPack will create the
3231 various archives for each of the components. The contents of this di‐
3232 rectory should be uploaded to a location accessible by the URL given in
3233 the site argument. If omitted, CPack will use the directory CPackU‐
3234 ploads inside the CMake binary directory to store the generated ar‐
3235 chives.
3236 The ALL flag indicates that all components be downloaded. Otherwise,
3238 only those components explicitly marked as DOWNLOADED or that have a
3239 specified ARCHIVE_FILE will be downloaded. Additionally, the ALL op‐
3240 tion implies ADD_REMOVE (unless NO_ADD_REMOVE is specified).
3241 ADD_REMOVE indicates that CPack should install a copy of the installer
3243 that can be called from Windows' Add/Remove Programs dialog (via the
3244 "Modify" button) to change the set of installed components. NO_ADD_RE‐
3245 MOVE turns off this behavior. This option is ignored on Mac OS X.
3246 CPackIFW
3248 New in version 3.1.
3249 This module looks for the location of the command-line utilities sup‐
3252 plied with the Qt Installer Framework (QtIFW).
3253 The module also defines several commands to control the behavior of the
3255 CPack IFW Generator.
3256 Commands
3258 The module defines the following commands:
3259 cpack_ifw_configure_component
3261 Sets the arguments specific to the CPack IFW generator.
3262 cpack_ifw_configure_component(<compname> [COMMON] [ESSENTIAL] [VIRTUAL]
3264 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
3265 [NAME <name>]
3266 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
3267 [DESCRIPTION <description>] # Note: Internationalization supported
3268 [UPDATE_TEXT <update_text>]
3269 [VERSION <version>]
3270 [RELEASE_DATE <release_date>]
3271 [SCRIPT <script>]
3272 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
3273 [DEPENDS|DEPENDENCIES <com_id> ...]
3274 [AUTO_DEPEND_ON <comp_id> ...]
3275 [LICENSES <display_name> <file_path> ...]
3276 [DEFAULT <value>]
3277 [USER_INTERFACES <file_path> <file_path> ...]
3278 [TRANSLATIONS <file_path> <file_path> ...]
3279 [REPLACES <comp_id> ...]
3280 [CHECKABLE <value>])
3281 This command should be called after cpack_add_component() com‐
3283 mand.
3284 COMMON if set, then the component will be packaged and installed
3286 as part of a group to which it belongs.
3287 ESSENTIAL
3289 New in version 3.6.
3290 if set, then the package manager stays disabled until
3293 that component is updated.
3294 VIRTUAL
3296 New in version 3.8.
3297 if set, then the component will be hidden from the in‐
3300 staller. It is a equivalent of the HIDDEN option from
3301 the cpack_add_component() command.
3302 FORCED_INSTALLATION
3304 New in version 3.8.
3305 if set, then the component must always be installed. It
3308 is a equivalent of the REQUIRED option from the
3309 cpack_add_component() command.
3310 REQUIRES_ADMIN_RIGHTS
3312 New in version 3.8.
3313 set it if the component needs to be installed with ele‐
3316 vated permissions.
3317 NAME is used to create domain-like identification for this
3319 component. By default used origin component name.
3320 DISPLAY_NAME
3322 New in version 3.8.
3323 set to rewrite original name configured by cpack_add_com‐
3326 ponent() command.
3327 DESCRIPTION
3329 New in version 3.8.
3330 set to rewrite original description configured by
3333 cpack_add_component() command.
3334 UPDATE_TEXT
3336 New in version 3.8.
3337 will be added to the component description if this is an
3340 update to the component.
3341 VERSION
3343 is version of component. By default used CPACK_PACK‐
3344 AGE_VERSION.
3345 RELEASE_DATE
3347 New in version 3.8.
3348 keep empty to auto generate.
3351 SCRIPT is a relative or absolute path to operations script for
3353 this component.
3354 SORTING_PRIORITY
3356 New in version 3.8.
3357 is priority of the component in the tree.
3360 PRIORITY
3362 Deprecated since version 3.8: Old name for SORTING_PRIOR‐
3363 ITY.
3364 DEPENDS, DEPENDENCIES
3367 New in version 3.8.
3368 list of dependency component or component group identi‐
3371 fiers in QtIFW style.
3372 New in version 3.21.
3374 Component or group names listed as dependencies may con‐
3377 tain hyphens. This requires QtIFW 3.1 or later.
3378 AUTO_DEPEND_ON
3380 New in version 3.8.
3381 list of identifiers of component or component group in
3384 QtIFW style that this component has an automatic depen‐
3385 dency on.
3386 LICENSES
3388 pair of <display_name> and <file_path> of license text
3389 for this component. You can specify more then one li‐
3390 cense.
3391 DEFAULT
3393 New in version 3.8.
3394 Possible values are: TRUE, FALSE, and SCRIPT. Set to
3397 FALSE to disable the component in the installer or to
3398 SCRIPT to resolved during runtime (don't forget add the
3399 file of the script as a value of the SCRIPT option).
3400 USER_INTERFACES
3402 New in version 3.7.
3403 is a list of <file_path> ('.ui' files) representing pages
3406 to load.
3407 TRANSLATIONS
3409 New in version 3.8.
3410 is a list of <file_path> ('.qm' files) representing
3413 translations to load.
3414 REPLACES
3416 New in version 3.10.
3417 list of identifiers of component or component group to
3420 replace.
3421 CHECKABLE
3423 New in version 3.10.
3424 Possible values are: TRUE, FALSE. Set to FALSE if you
3427 want to hide the checkbox for an item. This is useful
3428 when only a few subcomponents should be selected instead
3429 of all.
3430 cpack_ifw_configure_component_group
3432 Sets the arguments specific to the CPack IFW generator.
3433 cpack_ifw_configure_component_group(<groupname> [VIRTUAL]
3435 [FORCED_INSTALLATION] [REQUIRES_ADMIN_RIGHTS]
3436 [NAME <name>]
3437 [DISPLAY_NAME <display_name>] # Note: Internationalization supported
3438 [DESCRIPTION <description>] # Note: Internationalization supported
3439 [UPDATE_TEXT <update_text>]
3440 [VERSION <version>]
3441 [RELEASE_DATE <release_date>]
3442 [SCRIPT <script>]
3443 [PRIORITY|SORTING_PRIORITY <sorting_priority>] # Note: PRIORITY is deprecated
3444 [DEPENDS|DEPENDENCIES <com_id> ...]
3445 [AUTO_DEPEND_ON <comp_id> ...]
3446 [LICENSES <display_name> <file_path> ...]
3447 [DEFAULT <value>]
3448 [USER_INTERFACES <file_path> <file_path> ...]
3449 [TRANSLATIONS <file_path> <file_path> ...]
3450 [REPLACES <comp_id> ...]
3451 [CHECKABLE <value>])
3452 This command should be called after cpack_add_component_group()
3454 command.
3455 VIRTUAL
3457 New in version 3.8.
3458 if set, then the group will be hidden from the installer.
3461 Note that setting this on a root component does not work.
3462 FORCED_INSTALLATION
3464 New in version 3.8.
3465 if set, then the group must always be installed.
3468 REQUIRES_ADMIN_RIGHTS
3470 New in version 3.8.
3471 set it if the component group needs to be installed with
3474 elevated permissions.
3475 NAME is used to create domain-like identification for this
3477 component group. By default used origin component group
3478 name.
3479 DISPLAY_NAME
3481 New in version 3.8.
3482 set to rewrite original name configured by cpack_add_com‐
3485 ponent_group() command.
3486 DESCRIPTION
3488 New in version 3.8.
3489 set to rewrite original description configured by
3492 cpack_add_component_group() command.
3493 UPDATE_TEXT
3495 New in version 3.8.
3496 will be added to the component group description if this
3499 is an update to the component group.
3500 VERSION
3502 is version of component group. By default used
3503 CPACK_PACKAGE_VERSION.
3504 RELEASE_DATE
3506 New in version 3.8.
3507 keep empty to auto generate.
3510 SCRIPT is a relative or absolute path to operations script for
3512 this component group.
3513 SORTING_PRIORITY
3515 is priority of the component group in the tree.
3516 PRIORITY
3518 Deprecated since version 3.8: Old name for SORTING_PRIOR‐
3519 ITY.
3520 DEPENDS, DEPENDENCIES
3523 New in version 3.8.
3524 list of dependency component or component group identi‐
3527 fiers in QtIFW style.
3528 New in version 3.21.
3530 Component or group names listed as dependencies may con‐
3533 tain hyphens. This requires QtIFW 3.1 or later.
3534 AUTO_DEPEND_ON
3536 New in version 3.8.
3537 list of identifiers of component or component group in
3540 QtIFW style that this component group has an automatic
3541 dependency on.
3542 LICENSES
3544 pair of <display_name> and <file_path> of license text
3545 for this component group. You can specify more then one
3546 license.
3547 DEFAULT
3549 New in version 3.8.
3550 Possible values are: TRUE, FALSE, and SCRIPT. Set to
3553 TRUE to preselect the group in the installer (this takes
3554 effect only on groups that have no visible child compo‐
3555 nents) or to SCRIPT to resolved during runtime (don't
3556 forget add the file of the script as a value of the
3557 SCRIPT option).
3558 USER_INTERFACES
3560 New in version 3.7.
3561 is a list of <file_path> ('.ui' files) representing pages
3564 to load.
3565 TRANSLATIONS
3567 New in version 3.8.
3568 is a list of <file_path> ('.qm' files) representing
3571 translations to load.
3572 REPLACES
3574 New in version 3.10.
3575 list of identifiers of component or component group to
3578 replace.
3579 CHECKABLE
3581 New in version 3.10.
3582 Possible values are: TRUE, FALSE. Set to FALSE if you
3585 want to hide the checkbox for an item. This is useful
3586 when only a few subcomponents should be selected instead
3587 of all.
3588 cpack_ifw_add_repository
3590 Add QtIFW specific remote repository to binary installer.
3591 cpack_ifw_add_repository(<reponame> [DISABLED]
3593 URL <url>
3594 [USERNAME <username>]
3595 [PASSWORD <password>]
3596 [DISPLAY_NAME <display_name>])
3597 This command will also add the <reponame> repository to a vari‐
3599 able CPACK_IFW_REPOSITORIES_ALL.
3600 DISABLED
3602 if set, then the repository will be disabled by default.
3603 URL is points to a list of available components.
3605 USERNAME
3607 is used as user on a protected repository.
3608 PASSWORD
3610 is password to use on a protected repository.
3611 DISPLAY_NAME
3613 is string to display instead of the URL.
3614 cpack_ifw_update_repository
3616 New in version 3.6.
3617 Update QtIFW specific repository from remote repository.
3620 cpack_ifw_update_repository(<reponame>
3622 [[ADD|REMOVE] URL <url>]|
3623 [REPLACE OLD_URL <old_url> NEW_URL <new_url>]]
3624 [USERNAME <username>]
3625 [PASSWORD <password>]
3626 [DISPLAY_NAME <display_name>])
3627 This command will also add the <reponame> repository to a vari‐
3629 able CPACK_IFW_REPOSITORIES_ALL.
3630 URL is points to a list of available components.
3632 OLD_URL
3634 is points to a list that will replaced.
3635 NEW_URL
3637 is points to a list that will replace to.
3638 USERNAME
3640 is used as user on a protected repository.
3641 PASSWORD
3643 is password to use on a protected repository.
3644 DISPLAY_NAME
3646 is string to display instead of the URL.
3647 cpack_ifw_add_package_resources
3649 New in version 3.7.
3650 Add additional resources in the installer binary.
3653 cpack_ifw_add_package_resources(<file_path> <file_path> ...)
3655 This command will also add the specified files to a variable
3657 CPACK_IFW_PACKAGE_RESOURCES.
3658 CPackIFWConfigureFile
3660 New in version 3.8.
3661 The module defines configure_file() similar command to configure file
3664 templates prepared in QtIFW/SDK/Creator style.
3665 Commands
3667 The module defines the following commands:
3668 cpack_ifw_configure_file
3670 Copy a file to another location and modify its contents.
3671 cpack_ifw_configure_file(<input> <output>)
3673 Copies an <input> file to an <output> file and substitutes vari‐
3675 able values referenced as %{VAR} or %VAR% in the input file con‐
3676 tent. Each variable reference will be replaced with the current
3677 value of the variable, or the empty string if the variable is
3678 not defined.
3679 CSharpUtilities
3681 New in version 3.8.
3682 Functions to make configuration of CSharp/.NET targets easier.
3685 A collection of CMake utility functions useful for dealing with CSharp
3687 targets for Visual Studio generators from version 2010 and later.
3688 The following functions are provided by this module:
3690 Main functions
3692 • csharp_set_windows_forms_properties()
3694 • csharp_set_designer_cs_properties()
3696 • csharp_set_xaml_cs_properties()
3698 Helper functions
3700 • csharp_get_filename_keys()
3702 • csharp_get_filename_key_base()
3704 • csharp_get_dependentupon_name()
3706 Main functions provided by the module
3708 csharp_set_windows_forms_properties
3709 Sets source file properties for use of Windows Forms. Use this,
3710 if your CSharp target uses Windows Forms:
3711 csharp_set_windows_forms_properties([<file1> [<file2> [...]]])
3713 <fileN>
3715 List of all source files which are relevant for setting
3716 the VS_CSHARP_<tagname> properties (including .cs, .resx
3717 and .Designer.cs extensions).
3718 In the list of all given files for all files ending with .De‐
3720 signer.cs and .resx is searched. For every designer or resource
3721 file a file with the same base name but only .cs as extension is
3722 searched. If this is found, the VS_CSHARP_<tagname> properties
3723 are set as follows:
3724 for the .cs file:
3726 • VS_CSHARP_SubType "Form"
3728 for the .Designer.cs file (if it exists):
3730 • VS_CSHARP_DependentUpon <cs-filename>
3732 • VS_CSHARP_DesignTime "" (delete tag if previously de‐
3734 fined)
3735 • VS_CSHARP_AutoGen ""(delete tag if previously defined)
3737 for the .resx file (if it exists):
3739 • VS_RESOURCE_GENERATOR "" (delete tag if previously de‐
3741 fined)
3742 • VS_CSHARP_DependentUpon <cs-filename>
3744 • VS_CSHARP_SubType "Designer"
3746 csharp_set_designer_cs_properties
3748 Sets source file properties of .Designer.cs files depending on
3749 sibling filenames. Use this, if your CSharp target does not use
3750 Windows Forms (for Windows Forms use
3751 csharp_set_designer_cs_properties() instead):
3752 csharp_set_designer_cs_properties([<file1> [<file2> [...]]])
3754 <fileN>
3756 List of all source files which are relevant for setting
3757 the VS_CSHARP_<tagname> properties (including .cs, .resx,
3758 .settings and .Designer.cs extensions).
3759 In the list of all given files for all files ending with .De‐
3761 signer.cs is searched. For every designer file all files with
3762 the same base name but different extensions are searched. If a
3763 match is found, the source file properties of the designer file
3764 are set depending on the extension of the matched file:
3765 if match is .resx file:
3767 • VS_CSHARP_AutoGen "True"
3769 • VS_CSHARP_DesignTime "True"
3771 • VS_CSHARP_DependentUpon <resx-filename>
3773 if match is .cs file:
3775 • VS_CSHARP_DependentUpon <cs-filename>
3777 if match is .settings file:
3779 • VS_CSHARP_AutoGen "True"
3781 • VS_CSHARP_DesignTimeSharedInput "True"
3783 • VS_CSHARP_DependentUpon <settings-filename>
3785 NOTE:
3787 Because the source file properties of the .Designer.cs file are set
3788 according to the found matches and every match sets the
3789 VS_CSHARP_DependentUpon property, there should only be one match for
3790 each Designer.cs file.
3791 csharp_set_xaml_cs_properties
3793 Sets source file properties for use of Windows Presentation
3794 Foundation (WPF) and XAML. Use this, if your CSharp target uses
3795 WPF/XAML:
3796 csharp_set_xaml_cs_properties([<file1> [<file2> [...]]])
3798 <fileN>
3800 List of all source files which are relevant for setting
3801 the VS_CSHARP_<tagname> properties (including .cs, .xaml,
3802 and .xaml.cs extensions).
3803 In the list of all given files for all files ending with
3805 .xaml.cs is searched. For every xaml-cs file, a file with the
3806 same base name but extension .xaml is searched. If a match is
3807 found, the source file properties of the .xaml.cs file are set:
3808 • VS_CSHARP_DependentUpon <xaml-filename>
3810 Helper functions which are used by the above ones
3812 csharp_get_filename_keys
3813 Helper function which computes a list of key values to identify
3814 source files independently of relative/absolute paths given in
3815 cmake and eliminates case sensitivity:
3816 csharp_get_filename_keys(OUT [<file1> [<file2> [...]]])
3818 OUT Name of the variable in which the list of keys is stored
3820 <fileN>
3822 filename(s) as given to to CSharp target using add_li‐
3823 brary() or add_executable()
3824 In some way the function applies a canonicalization to the
3826 source names. This is necessary to find file matches if the
3827 files have been added to the target with different directory
3828 prefixes:
3829 add_library(lib
3831 myfile.cs
3832 ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs)
3833 set_source_files_properties(myfile.Designer.cs PROPERTIES
3835 VS_CSHARP_DependentUpon myfile.cs)
3836 # this will fail, because in cmake
3838 # - ${CMAKE_CURRENT_SOURCE_DIR}/myfile.Designer.cs
3839 # - myfile.Designer.cs
3840 # are not the same source file. The source file property is not set.
3841 csharp_get_filename_key_base
3843 Returns the full filepath and name without extension of a key.
3844 KEY is expected to be a key from csharp_get_filename_keys. In
3845 BASE the value of KEY without the file extension is returned:
3846 csharp_get_filename_key_base(BASE KEY)
3848 BASE Name of the variable with the computed "base" of KEY.
3850 KEY The key of which the base will be computed. Expected to
3852 be a upper case full filename.
3853 csharp_get_dependentupon_name
3855 Computes a string which can be used as value for the source file
3856 property VS_CSHARP_<tagname> with target being DependentUpon:
3857 csharp_get_dependentupon_name(NAME FILE)
3859 NAME Name of the variable with the result value
3861 FILE Filename to convert to <DependentUpon> value
3863 Actually this is only the filename without any path given at the
3865 moment.
3866 CTest
3868 Configure a project for testing with CTest/CDash
3869 Include this module in the top CMakeLists.txt file of a project to en‐
3871 able testing with CTest and dashboard submissions to CDash:
3872 project(MyProject)
3874 ...
3875 include(CTest)
3876 The module automatically creates a BUILD_TESTING option that selects
3878 whether to enable testing support (ON by default). After including the
3879 module, use code like:
3880 if(BUILD_TESTING)
3882 # ... CMake code to create tests ...
3883 endif()
3884 to creating tests when testing is enabled.
3886 To enable submissions to a CDash server, create a CTestConfig.cmake
3888 file at the top of the project with content such as:
3889 set(CTEST_NIGHTLY_START_TIME "01:00:00 UTC")
3891 set(CTEST_SUBMIT_URL "http://my.cdash.org/submit.php?project=MyProject")
3892 (the CDash server can provide the file to a project administrator who
3894 configures MyProject). Settings in the config file are shared by both
3895 this CTest module and the ctest(1) command-line Dashboard Client mode
3896 (ctest -S).
3897 While building a project for submission to CDash, CTest scans the build
3899 output for errors and warnings and reports them with surrounding con‐
3900 text from the build log. This generic approach works for all build
3901 tools, but does not give details about the command invocation that pro‐
3902 duced a given problem. One may get more detailed reports by setting
3903 the CTEST_USE_LAUNCHERS variable:
3904 set(CTEST_USE_LAUNCHERS 1)
3906 in the CTestConfig.cmake file.
3908 CTestCoverageCollectGCOV
3910 New in version 3.2.
3911 This module provides the ctest_coverage_collect_gcov function.
3914 This function runs gcov on all .gcda files found in the binary tree and
3916 packages the resulting .gcov files into a tar file. This tarball also
3917 contains the following:
3918 • data.json defines the source and build directories for use by CDash.
3920 • Labels.json indicates any LABELS that have been set on the source
3922 files.
3923 • The uncovered directory holds any uncovered files found by CTEST_EX‐
3925 TRA_COVERAGE_GLOB.
3926 After generating this tar file, it can be sent to CDash for display
3928 with the ctest_submit(CDASH_UPLOAD) command.
3929 ctest_coverage_collect_gcov
3931 ctest_coverage_collect_gcov(TARBALL <tarfile>
3933 [SOURCE <source_dir>][BUILD <build_dir>]
3934 [GCOV_COMMAND <gcov_command>]
3935 [GCOV_OPTIONS <options>...]
3936 )
3937 Run gcov and package a tar file for CDash. The options are:
3939 TARBALL <tarfile>
3941 Specify the location of the .tar file to be created for
3942 later upload to CDash. Relative paths will be inter‐
3943 preted with respect to the top-level build directory.
3944 TARBALL_COMPRESSION <option>
3946 New in version 3.18.
3947 Specify a compression algorithm for the TARBALL data
3950 file. Using this option reduces the size of the data
3951 file before it is submitted to CDash. <option> must be
3952 one of GZIP, BZIP2, XZ, ZSTD, FROM_EXT, or an expression
3953 that CMake evaluates as FALSE. The default value is
3954 BZIP2.
3955 If FROM_EXT is specified, the resulting file will be com‐
3957 pressed based on the file extension of the <tarfile>
3958 (i.e. .tar.gz will use GZIP compression). File extensions
3959 that will produce compressed output include .tar.gz,
3960 .tgz, .tar.bzip2, .tbz, .tar.xz, and .txz.
3961 SOURCE <source_dir>
3963 Specify the top-level source directory for the build.
3964 Default is the value of CTEST_SOURCE_DIRECTORY.
3965 BUILD <build_dir>
3967 Specify the top-level build directory for the build. De‐
3968 fault is the value of CTEST_BINARY_DIRECTORY.
3969 GCOV_COMMAND <gcov_command>
3971 Specify the full path to the gcov command on the machine.
3972 Default is the value of CTEST_COVERAGE_COMMAND.
3973 GCOV_OPTIONS <options>...
3975 Specify options to be passed to gcov. The gcov command
3976 is run as gcov <options>... -o <gcov-dir> <file>.gcda.
3977 If not specified, the default option is just -b -x.
3978 GLOB New in version 3.6.
3980 Recursively search for .gcda files in build_dir rather
3983 than determining search locations by reading TargetDirec‐
3984 tories.txt.
3985 DELETE New in version 3.6.
3987 Delete coverage files after they've been packaged into
3990 the .tar.
3991 QUIET Suppress non-error messages that otherwise would have
3993 been printed out by this function.
3994 New in version 3.3: Added support for the CTEST_CUSTOM_COVER‐
3996 AGE_EXCLUDE variable.
3997 CTestScriptMode
4000 This file is read by ctest in script mode (-S)
4001 CTestUseLaunchers
4003 Set the RULE_LAUNCH_* global properties when CTEST_USE_LAUNCHERS is on.
4004 CTestUseLaunchers is automatically included when you include(CTest).
4006 However, it is split out into its own module file so projects can use
4007 the CTEST_USE_LAUNCHERS functionality independently.
4008 To use launchers, set CTEST_USE_LAUNCHERS to ON in a ctest -S dashboard
4010 script, and then also set it in the cache of the configured project.
4011 Both cmake and ctest need to know the value of it for the launchers to
4012 work properly. CMake needs to know in order to generate proper build
4013 rules, and ctest, in order to produce the proper error and warning
4014 analysis.
4015 For convenience, you may set the ENV variable CTEST_USE_LAUNCHERS_DE‐
4017 FAULT in your ctest -S script, too. Then, as long as your CMakeLists
4018 uses include(CTest) or include(CTestUseLaunchers), it will use the
4019 value of the ENV variable to initialize a CTEST_USE_LAUNCHERS cache
4020 variable. This cache variable initialization only occurs if
4021 CTEST_USE_LAUNCHERS is not already defined.
4022 New in version 3.8: If CTEST_USE_LAUNCHERS is on in a ctest -S script
4024 the ctest_configure command will add -DCTEST_USE_LAUNCHERS:BOOL=TRUE to
4025 the cmake command used to configure the project.
4026 Dart
4029 Configure a project for testing with CTest or old Dart Tcl Client
4030 This file is the backwards-compatibility version of the CTest module.
4032 It supports using the old Dart 1 Tcl client for driving dashboard sub‐
4033 missions as well as testing with CTest. This module should be included
4034 in the CMakeLists.txt file at the top of a project. Typical usage:
4035 include(Dart)
4037 if(BUILD_TESTING)
4038 # ... testing related CMake code ...
4039 endif()
4040 The BUILD_TESTING option is created by the Dart module to determine
4042 whether testing support should be enabled. The default is ON.
4043 DeployQt4
4045 Functions to help assemble a standalone Qt4 executable.
4046 A collection of CMake utility functions useful for deploying Qt4 exe‐
4048 cutables.
4049 The following functions are provided by this module:
4051 write_qt4_conf
4053 resolve_qt4_paths
4054 fixup_qt4_executable
4055 install_qt4_plugin_path
4056 install_qt4_plugin
4057 install_qt4_executable
4058 Requires CMake 2.6 or greater because it uses function and PAR‐
4060 ENT_SCOPE. Also depends on BundleUtilities.cmake.
4061 write_qt4_conf(<qt_conf_dir> <qt_conf_contents>)
4063 Writes a qt.conf file with the <qt_conf_contents> into <qt_conf_dir>.
4065 resolve_qt4_paths(<paths_var> [<executable_path>])
4067 Loop through <paths_var> list and if any don't exist resolve them rela‐
4069 tive to the <executable_path> (if supplied) or the CMAKE_INSTALL_PRE‐
4070 FIX.
4071 fixup_qt4_executable(<executable>
4073 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf>])
4074 Copies Qt plugins, writes a Qt configuration file (if needed) and fixes
4076 up a Qt4 executable using BundleUtilities so it is standalone and can
4077 be drag-and-drop copied to another machine as long as all of the system
4078 libraries are compatible.
4079 <executable> should point to the executable to be fixed-up.
4081 <qtplugins> should contain a list of the names or paths of any Qt plug‐
4083 ins to be installed.
4084 <libs> will be passed to BundleUtilities and should be a list of any
4086 already installed plugins, libraries or executables to also be
4087 fixed-up.
4088 <dirs> will be passed to BundleUtilities and should contain and direc‐
4090 tories to be searched to find library dependencies.
4091 <plugins_dir> allows an custom plugins directory to be used.
4093 <request_qt_conf> will force a qt.conf file to be written even if not
4095 needed.
4096 install_qt4_plugin_path(plugin executable copy installed_plugin_path_var
4098 <plugins_dir> <component> <configurations>)
4099 Install (or copy) a resolved <plugin> to the default plugins directory
4101 (or <plugins_dir>) relative to <executable> and store the result in
4102 <installed_plugin_path_var>.
4103 If <copy> is set to TRUE then the plugins will be copied rather than
4105 installed. This is to allow this module to be used at CMake time
4106 rather than install time.
4107 If <component> is set then anything installed will use this COMPONENT.
4109 install_qt4_plugin(plugin executable copy installed_plugin_path_var
4111 <plugins_dir> <component>)
4112 Install (or copy) an unresolved <plugin> to the default plugins direc‐
4114 tory (or <plugins_dir>) relative to <executable> and store the result
4115 in <installed_plugin_path_var>. See documentation of IN‐
4116 STALL_QT4_PLUGIN_PATH.
4117 install_qt4_executable(<executable>
4119 [<qtplugins> <libs> <dirs> <plugins_dir> <request_qt_conf> <component>])
4120 Installs Qt plugins, writes a Qt configuration file (if needed) and
4122 fixes up a Qt4 executable using BundleUtilities so it is standalone and
4123 can be drag-and-drop copied to another machine as long as all of the
4124 system libraries are compatible. The executable will be fixed-up at
4125 install time. <component> is the COMPONENT used for bundle fixup and
4126 plugin installation. See documentation of FIXUP_QT4_BUNDLE.
4127 ExternalData
4129 Manage data files stored outside source tree
4130 Introduction
4132 Use this module to unambiguously reference data files stored outside
4133 the source tree and fetch them at build time from arbitrary local and
4134 remote content-addressed locations. Functions provided by this module
4135 recognize arguments with the syntax DATA{<name>} as references to ex‐
4136 ternal data, replace them with full paths to local copies of those
4137 data, and create build rules to fetch and update the local copies.
4138 For example:
4140 include(ExternalData)
4142 set(ExternalData_URL_TEMPLATES "file:///local/%(algo)/%(hash)"
4143 "file:////host/share/%(algo)/%(hash)"
4144 "http://data.org/%(algo)/%(hash)")
4145 ExternalData_Add_Test(MyData
4146 NAME MyTest
4147 COMMAND MyExe DATA{MyInput.png}
4148 )
4149 ExternalData_Add_Target(MyData)
4150 When test MyTest runs the DATA{MyInput.png} argument will be replaced
4152 by the full path to a real instance of the data file MyInput.png on
4153 disk. If the source tree contains a content link such as MyIn‐
4154 put.png.md5 then the MyData target creates a real MyInput.png in the
4155 build tree.
4156 Module Functions
4158 ExternalData_Expand_Arguments
4159 The ExternalData_Expand_Arguments function evaluates DATA{} ref‐
4160 erences in its arguments and constructs a new list of arguments:
4161 ExternalData_Expand_Arguments(
4163 <target> # Name of data management target
4164 <outVar> # Output variable
4165 [args...] # Input arguments, DATA{} allowed
4166 )
4167 It replaces each DATA{} reference in an argument with the full
4169 path of a real data file on disk that will exist after the <tar‐
4170 get> builds.
4171 ExternalData_Add_Test
4173 The ExternalData_Add_Test function wraps around the CMake
4174 add_test() command but supports DATA{} references in its argu‐
4175 ments:
4176 ExternalData_Add_Test(
4178 <target> # Name of data management target
4179 ... # Arguments of add_test(), DATA{} allowed
4180 )
4181 It passes its arguments through ExternalData_Expand_Arguments
4183 and then invokes the add_test() command using the results.
4184 ExternalData_Add_Target
4186 The ExternalData_Add_Target function creates a custom target to
4187 manage local instances of data files stored externally:
4188 ExternalData_Add_Target(
4190 <target> # Name of data management target
4191 [SHOW_PROGRESS <ON|OFF>] # Show progress during the download
4192 )
4193 It creates custom commands in the target as necessary to make
4195 data files available for each DATA{} reference previously evalu‐
4196 ated by other functions provided by this module. Data files may
4197 be fetched from one of the URL templates specified in the Exter‐
4198 nalData_URL_TEMPLATES variable, or may be found locally in one
4199 of the paths specified in the ExternalData_OBJECT_STORES vari‐
4200 able.
4201 New in version 3.20: The SHOW_PROGRESS argument may be passed to
4203 suppress progress information during the download of objects. If
4204 not provided, it defaults to OFF for Ninja and Ninja Multi-Con‐
4205 fig generators and ON otherwise.
4206 Typically only one target is needed to manage all external data
4209 within a project. Call this function once at the end of config‐
4210 uration after all data references have been processed.
4211 Module Variables
4213 The following variables configure behavior. They should be set before
4214 calling any of the functions provided by this module.
4215 ExternalData_BINARY_ROOT
4217 The ExternalData_BINARY_ROOT variable may be set to the direc‐
4218 tory to hold the real data files named by expanded DATA{} refer‐
4219 ences. The default is CMAKE_BINARY_DIR. The directory layout
4220 will mirror that of content links under External‐
4221 Data_SOURCE_ROOT.
4222 ExternalData_CUSTOM_SCRIPT_<key>
4224 New in version 3.2.
4225 Specify a full path to a .cmake custom fetch script identified
4228 by <key> in entries of the ExternalData_URL_TEMPLATES list. See
4229 Custom Fetch Scripts.
4230 ExternalData_LINK_CONTENT
4232 The ExternalData_LINK_CONTENT variable may be set to the name of
4233 a supported hash algorithm to enable automatic conversion of
4234 real data files referenced by the DATA{} syntax into content
4235 links. For each such <file> a content link named <file><ext> is
4236 created. The original file is renamed to the form .External‐
4237 Data_<algo>_<hash> to stage it for future transmission to one of
4238 the locations in the list of URL templates (by means outside the
4239 scope of this module). The data fetch rule created for the con‐
4240 tent link will use the staged object if it cannot be found using
4241 any URL template.
4242 ExternalData_NO_SYMLINKS
4244 New in version 3.3.
4245 The real data files named by expanded DATA{} references may be
4248 made available under ExternalData_BINARY_ROOT using symbolic
4249 links on some platforms. The ExternalData_NO_SYMLINKS variable
4250 may be set to disable use of symbolic links and enable use of
4251 copies instead.
4252 ExternalData_OBJECT_STORES
4254 The ExternalData_OBJECT_STORES variable may be set to a list of
4255 local directories that store objects using the layout
4256 <dir>/%(algo)/%(hash). These directories will be searched first
4257 for a needed object. If the object is not available in any
4258 store then it will be fetched remotely using the URL templates
4259 and added to the first local store listed. If no stores are
4260 specified the default is a location inside the build tree.
4261 ExternalData_SERIES_PARSE
4263 ExternalData_SERIES_PARSE_PREFIX
4265 ExternalData_SERIES_PARSE_NUMBER
4267 ExternalData_SERIES_PARSE_SUFFIX
4269 ExternalData_SERIES_MATCH
4271 See Referencing File Series.
4272 ExternalData_SOURCE_ROOT
4274 The ExternalData_SOURCE_ROOT variable may be set to the highest
4275 source directory containing any path named by a DATA{} refer‐
4276 ence. The default is CMAKE_SOURCE_DIR. External‐
4277 Data_SOURCE_ROOT and CMAKE_SOURCE_DIR must refer to directories
4278 within a single source distribution (e.g. they come together in
4279 one tarball).
4280 ExternalData_TIMEOUT_ABSOLUTE
4282 The ExternalData_TIMEOUT_ABSOLUTE variable sets the download ab‐
4283 solute timeout, in seconds, with a default of 300 seconds. Set
4284 to 0 to disable enforcement.
4285 ExternalData_TIMEOUT_INACTIVITY
4287 The ExternalData_TIMEOUT_INACTIVITY variable sets the download
4288 inactivity timeout, in seconds, with a default of 60 seconds.
4289 Set to 0 to disable enforcement.
4290 ExternalData_URL_ALGO_<algo>_<key>
4292 New in version 3.3.
4293 Specify a custom URL component to be substituted for URL tem‐
4296 plate placeholders of the form %(algo:<key>), where <key> is a
4297 valid C identifier, when fetching an object referenced via hash
4298 algorithm <algo>. If not defined, the default URL component is
4299 just <algo> for any <key>.
4300 ExternalData_URL_TEMPLATES
4302 The ExternalData_URL_TEMPLATES may be set to provide a list of
4303 URL templates using the placeholders %(algo) and %(hash) in each
4304 template. Data fetch rules try each URL template in order by
4305 substituting the hash algorithm name for %(algo) and the hash
4306 value for %(hash). Alternatively one may use %(algo:<key>) with
4307 ExternalData_URL_ALGO_<algo>_<key> variables to gain more flexi‐
4308 bility in remote URLs.
4309 Referencing Files
4311 Referencing Single Files
4312 The DATA{} syntax is literal and the <name> is a full or relative path
4313 within the source tree. The source tree must contain either a real
4314 data file at <name> or a "content link" at <name><ext> containing a
4315 hash of the real file using a hash algorithm corresponding to <ext>.
4316 For example, the argument DATA{img.png} may be satisfied by either a
4317 real img.png file in the current source directory or a img.png.md5 file
4318 containing its MD5 sum.
4319 New in version 3.8: Multiple content links of the same name with dif‐
4321 ferent hash algorithms are supported (e.g. img.png.sha256 and
4322 img.png.sha1) so long as they all correspond to the same real file.
4323 This allows objects to be fetched from sources indexed by different
4324 hash algorithms.
4325 Referencing File Series
4328 The DATA{} syntax can be told to fetch a file series using the form
4329 DATA{<name>,:}, where the : is literal. If the source tree contains a
4330 group of files or content links named like a series then a reference to
4331 one member adds rules to fetch all of them. Although all members of a
4332 series are fetched, only the file originally named by the DATA{} argu‐
4333 ment is substituted for it. The default configuration recognizes file
4334 series names ending with #.ext, _#.ext, .#.ext, or -#.ext where # is a
4335 sequence of decimal digits and .ext is any single extension. Configure
4336 it with a regex that parses <number> and <suffix> parts from the end of
4337 <name>:
4338 ExternalData_SERIES_PARSE = regex of the form (<number>)(<suffix>)$
4340 For more complicated cases set:
4342 ExternalData_SERIES_PARSE = regex with at least two () groups
4344 ExternalData_SERIES_PARSE_PREFIX = <prefix> regex group number, if any
4345 ExternalData_SERIES_PARSE_NUMBER = <number> regex group number
4346 ExternalData_SERIES_PARSE_SUFFIX = <suffix> regex group number
4347 Configure series number matching with a regex that matches the <number>
4349 part of series members named <prefix><number><suffix>:
4350 ExternalData_SERIES_MATCH = regex matching <number> in all series members
4352 Note that the <suffix> of a series does not include a hash-algorithm
4354 extension.
4355 Referencing Associated Files
4357 The DATA{} syntax can alternatively match files associated with the
4358 named file and contained in the same directory. Associated files may
4359 be specified by options using the syntax
4360 DATA{<name>,<opt1>,<opt2>,...}. Each option may specify one file by
4361 name or specify a regular expression to match file names using the syn‐
4362 tax REGEX:<regex>. For example, the arguments:
4363 DATA{MyData/MyInput.mhd,MyInput.img} # File pair
4365 DATA{MyData/MyFrames00.png,REGEX:MyFrames[0-9]+\\.png} # Series
4366 will pass MyInput.mha and MyFrames00.png on the command line but ensure
4368 that the associated files are present next to them.
4369 Referencing Directories
4371 The DATA{} syntax may reference a directory using a trailing slash and
4372 a list of associated files. The form DATA{<name>/,<opt1>,<opt2>,...}
4373 adds rules to fetch any files in the directory that match one of the
4374 associated file options. For example, the argument DATA{My‐
4375 DataDir/,REGEX:.*} will pass the full path to a MyDataDir directory on
4376 the command line and ensure that the directory contains files corre‐
4377 sponding to every file or content link in the MyDataDir source direc‐
4378 tory.
4379 New in version 3.3: In order to match associated files in subdirecto‐
4381 ries, specify a RECURSE: option, e.g. DATA{MyDataDir/,RE‐
4382 CURSE:,REGEX:.*}.
4383 Hash Algorithms
4386 The following hash algorithms are supported:
4387 %(algo) <ext> Description
4389 ------- ----- -----------
4390 MD5 .md5 Message-Digest Algorithm 5, RFC 1321
4391 SHA1 .sha1 US Secure Hash Algorithm 1, RFC 3174
4392 SHA224 .sha224 US Secure Hash Algorithms, RFC 4634
4393 SHA256 .sha256 US Secure Hash Algorithms, RFC 4634
4394 SHA384 .sha384 US Secure Hash Algorithms, RFC 4634
4395 SHA512 .sha512 US Secure Hash Algorithms, RFC 4634
4396 SHA3_224 .sha3-224 Keccak SHA-3
4397 SHA3_256 .sha3-256 Keccak SHA-3
4398 SHA3_384 .sha3-384 Keccak SHA-3
4399 SHA3_512 .sha3-512 Keccak SHA-3
4400 New in version 3.8: Added the SHA3_* hash algorithms.
4402 Note that the hashes are used only for unique data identification and
4405 download verification.
4406 Custom Fetch Scripts
4408 New in version 3.2.
4409 When a data file must be fetched from one of the URL templates speci‐
4412 fied in the ExternalData_URL_TEMPLATES variable, it is normally down‐
4413 loaded using the file(DOWNLOAD) command. One may specify usage of a
4414 custom fetch script by using a URL template of the form ExternalData‐
4415 CustomScript://<key>/<loc>. The <key> must be a C identifier, and the
4416 <loc> must contain the %(algo) and %(hash) placeholders. A variable
4417 corresponding to the key, ExternalData_CUSTOM_SCRIPT_<key>, must be set
4418 to the full path to a .cmake script file. The script will be included
4419 to perform the actual fetch, and provided with the following variables:
4420 ExternalData_CUSTOM_LOCATION
4422 When a custom fetch script is loaded, this variable is set to
4423 the location part of the URL, which will contain the substituted
4424 hash algorithm name and content hash value.
4425 ExternalData_CUSTOM_FILE
4427 When a custom fetch script is loaded, this variable is set to
4428 the full path to a file in which the script must store the
4429 fetched content. The name of the file is unspecified and should
4430 not be interpreted in any way.
4431 The custom fetch script is expected to store fetched content in the
4433 file or set a variable:
4434 ExternalData_CUSTOM_ERROR
4436 When a custom fetch script fails to fetch the requested content,
4437 it must set this variable to a short one-line message describing
4438 the reason for failure.
4439 ExternalProject
4441 Commands
4442 External Project Definition
4443 ExternalProject_Add
4444 The ExternalProject_Add() function creates a custom target to
4445 drive download, update/patch, configure, build, install and test
4446 steps of an external project:
4447 ExternalProject_Add(<name> [<option>...])
4449 The individual steps within the process can be driven indepen‐
4451 dently if required (e.g. for CDash submission) and extra custom
4452 steps can be defined, along with the ability to control the step
4453 dependencies. The directory structure used for the management of
4454 the external project can also be customized. The function sup‐
4455 ports a large number of options which can be used to tailor the
4456 external project behavior.
4457 Directory Options:
4459 Most of the time, the default directory layout is suffi‐
4460 cient. It is largely an implementation detail that the
4461 main project usually doesn't need to change. In some cir‐
4462 cumstances, however, control over the directory layout
4463 can be useful or necessary. The directory options are po‐
4464 tentially more useful from the point of view that the
4465 main build can use the ExternalProject_Get_Property()
4466 command to retrieve their values, thereby allowing the
4467 main project to refer to build artifacts of the external
4468 project.
4469 PREFIX <dir>
4471 Root directory for the external project. Unless
4472 otherwise noted below, all other directories asso‐
4473 ciated with the external project will be created
4474 under here.
4475 TMP_DIR <dir>
4477 Directory in which to store temporary files.
4478 STAMP_DIR <dir>
4480 Directory in which to store the timestamps of each
4481 step. Log files from individual steps are also
4482 created in here unless overridden by LOG_DIR (see
4483 Logging Options below).
4484 LOG_DIR <dir>
4486 New in version 3.14.
4487 Directory in which to store the logs of each step.
4490 DOWNLOAD_DIR <dir>
4492 Directory in which to store downloaded files be‐
4493 fore unpacking them. This directory is only used
4494 by the URL download method, all other download
4495 methods use SOURCE_DIR directly instead.
4496 SOURCE_DIR <dir>
4498 Source directory into which downloaded contents
4499 will be unpacked, or for non-URL download methods,
4500 the directory in which the repository should be
4501 checked out, cloned, etc. If no download method is
4502 specified, this must point to an existing direc‐
4503 tory where the external project has already been
4504 unpacked or cloned/checked out.
4505 NOTE:
4507 If a download method is specified, any existing
4508 contents of the source directory may be
4509 deleted. Only the URL download method checks
4510 whether this directory is either missing or
4511 empty before initiating the download, stopping
4512 with an error if it is not empty. All other
4513 download methods silently discard any previous
4514 contents of the source directory.
4515 BINARY_DIR <dir>
4517 Specify the build directory location. This option
4518 is ignored if BUILD_IN_SOURCE is enabled.
4519 INSTALL_DIR <dir>
4521 Installation prefix to be placed in the <IN‐
4522 STALL_DIR> placeholder. This does not actually
4523 configure the external project to install to the
4524 given prefix. That must be done by passing appro‐
4525 priate arguments to the external project configu‐
4526 ration step, e.g. using <INSTALL_DIR>.
4527 If any of the above ..._DIR options are not specified,
4529 their defaults are computed as follows. If the PREFIX op‐
4530 tion is given or the EP_PREFIX directory property is set,
4531 then an external project is built and installed under the
4532 specified prefix:
4533 TMP_DIR = <prefix>/tmp
4535 STAMP_DIR = <prefix>/src/<name>-stamp
4536 DOWNLOAD_DIR = <prefix>/src
4537 SOURCE_DIR = <prefix>/src/<name>
4538 BINARY_DIR = <prefix>/src/<name>-build
4539 INSTALL_DIR = <prefix>
4540 LOG_DIR = <STAMP_DIR>
4541 Otherwise, if the EP_BASE directory property is set then
4543 components of an external project are stored under the
4544 specified base:
4545 TMP_DIR = <base>/tmp/<name>
4547 STAMP_DIR = <base>/Stamp/<name>
4548 DOWNLOAD_DIR = <base>/Download/<name>
4549 SOURCE_DIR = <base>/Source/<name>
4550 BINARY_DIR = <base>/Build/<name>
4551 INSTALL_DIR = <base>/Install/<name>
4552 LOG_DIR = <STAMP_DIR>
4553 If no PREFIX, EP_PREFIX, or EP_BASE is specified, then
4555 the default is to set PREFIX to <name>-prefix. Relative
4556 paths are interpreted with respect to CMAKE_CURRENT_BI‐
4557 NARY_DIR at the point where ExternalProject_Add() is
4558 called.
4559 Download Step Options:
4561 A download method can be omitted if the SOURCE_DIR option
4562 is used to point to an existing non-empty directory. Oth‐
4563 erwise, one of the download methods below must be speci‐
4564 fied (multiple download methods should not be given) or a
4565 custom DOWNLOAD_COMMAND provided.
4566 DOWNLOAD_COMMAND <cmd>...
4568 Overrides the command used for the download step
4569 (generator expressions are supported). If this op‐
4570 tion is specified, all other download options will
4571 be ignored. Providing an empty string for <cmd>
4572 effectively disables the download step.
4573 URL Download
4575 URL <url1> [<url2>...]
4577 List of paths and/or URL(s) of the external
4578 project's source. When more than one URL is
4579 given, they are tried in turn until one
4580 succeeds. A URL may be an ordinary path in
4581 the local file system (in which case it
4582 must be the only URL provided) or any down‐
4583 loadable URL supported by the file(DOWN‐
4584 LOAD) command. A local filesystem path may
4585 refer to either an existing directory or to
4586 an archive file, whereas a URL is expected
4587 to point to a file which can be treated as
4588 an archive. When an archive is used, it
4589 will be unpacked automatically unless the
4590 DOWNLOAD_NO_EXTRACT option is set to pre‐
4591 vent it. The archive type is determined by
4592 inspecting the actual content rather than
4593 using logic based on the file extension.
4594 Changed in version 3.7: Multiple URLs are
4596 allowed.
4597 URL_HASH <algo>=<hashValue>
4600 Hash of the archive file to be downloaded.
4601 The argument should be of the form
4602 <algo>=<hashValue> where algo can be any of
4603 the hashing algorithms supported by the
4604 file() command. Specifying this option is
4605 strongly recommended for URL downloads, as
4606 it ensures the integrity of the downloaded
4607 content. It is also used as a check for a
4608 previously downloaded file, allowing con‐
4609 nection to the remote location to be
4610 avoided altogether if the local directory
4611 already has a file from an earlier download
4612 that matches the specified hash.
4613 URL_MD5 <md5>
4615 Equivalent to URL_HASH MD5=<md5>.
4616 DOWNLOAD_NAME <fname>
4618 File name to use for the downloaded file.
4619 If not given, the end of the URL is used to
4620 determine the file name. This option is
4621 rarely needed, the default name is gener‐
4622 ally suitable and is not normally used out‐
4623 side of code internal to the ExternalPro‐
4624 ject module.
4625 DOWNLOAD_NO_EXTRACT <bool>
4627 New in version 3.6.
4628 Allows the extraction part of the download
4631 step to be disabled by passing a boolean
4632 true value for this option. If this option
4633 is not given, the downloaded contents will
4634 be unpacked automatically if required. If
4635 extraction has been disabled, the full path
4636 to the downloaded file is available as
4637 <DOWNLOADED_FILE> in subsequent steps or as
4638 the property DOWNLOADED_FILE with the
4639 ExternalProject_Get_Property() command.
4640 DOWNLOAD_NO_PROGRESS <bool>
4642 Can be used to disable logging the download
4643 progress. If this option is not given,
4644 download progress messages will be logged.
4645 TIMEOUT <seconds>
4647 Maximum time allowed for file download op‐
4648 erations.
4649 INACTIVITY_TIMEOUT <seconds>
4651 New in version 3.19.
4652 Terminate the operation after a period of
4655 inactivity.
4656 HTTP_USERNAME <username>
4658 New in version 3.7.
4659 Username for the download operation if au‐
4662 thentication is required.
4663 HTTP_PASSWORD <password>
4665 New in version 3.7.
4666 Password for the download operation if au‐
4669 thentication is required.
4670 HTTP_HEADER <header1> [<header2>...]
4672 New in version 3.7.
4673 Provides an arbitrary list of HTTP headers
4676 for the download operation. This can be
4677 useful for accessing content in systems
4678 like AWS, etc.
4679 TLS_VERIFY <bool>
4681 Specifies whether certificate verification
4682 should be performed for https URLs. If this
4683 option is not provided, the default behav‐
4684 ior is determined by the CMAKE_TLS_VERIFY
4685 variable (see file(DOWNLOAD)). If that is
4686 also not set, certificate verification will
4687 not be performed. In situations where
4688 URL_HASH cannot be provided, this option
4689 can be an alternative verification measure.
4690 Changed in version 3.6: This option also
4692 applies to git clone invocations.
4693 TLS_CAINFO <file>
4696 Specify a custom certificate authority file
4697 to use if TLS_VERIFY is enabled. If this
4698 option is not specified, the value of the
4699 CMAKE_TLS_CAINFO variable will be used in‐
4700 stead (see file(DOWNLOAD))
4701 NETRC <level>
4703 New in version 3.11.
4704 Specify whether the .netrc file is to be
4707 used for operation. If this option is not
4708 specified, the value of the CMAKE_NETRC
4709 variable will be used instead (see
4710 file(DOWNLOAD)) Valid levels are:
4711 IGNORED
4713 The .netrc file is ignored. This is
4714 the default.
4715 OPTIONAL
4717 The .netrc file is optional, and in‐
4718 formation in the URL is preferred.
4719 The file will be scanned to find
4720 which ever information is not speci‐
4721 fied in the URL.
4722 REQUIRED
4724 The .netrc file is required, and in‐
4725 formation in the URL is ignored.
4726 NETRC_FILE <file>
4728 New in version 3.11.
4729 Specify an alternative .netrc file to the
4732 one in your home directory if the NETRC
4733 level is OPTIONAL or REQUIRED. If this op‐
4734 tion is not specified, the value of the
4735 CMAKE_NETRC_FILE variable will be used in‐
4736 stead (see file(DOWNLOAD))
4737 New in version 3.1: Added support for tbz2,
4739 .tar.xz, .txz, and .7z extensions.
4740 Git NOTE: A git version of 1.6.5 or later is required
4743 if this download method is used.
4744 GIT_REPOSITORY <url>
4746 URL of the git repository. Any URL under‐
4747 stood by the git command may be used.
4748 GIT_TAG <tag>
4750 Git branch name, tag or commit hash. Note
4751 that branch names and tags should generally
4752 be specified as remote names (i.e. ori‐
4753 gin/myBranch rather than simply myBranch).
4754 This ensures that if the remote end has its
4755 tag moved or branch rebased or history
4756 rewritten, the local clone will still be
4757 updated correctly. In general, however,
4758 specifying a commit hash should be pre‐
4759 ferred for a number of reasons:
4760 • If the local clone already has the commit
4762 corresponding to the hash, no git fetch
4763 needs to be performed to check for
4764 changes each time CMake is re-run. This
4765 can result in a significant speed up if
4766 many external projects are being used.
4767 • Using a specific git hash ensures that
4769 the main project's own history is fully
4770 traceable to a specific point in the ex‐
4771 ternal project's evolution. If a branch
4772 or tag name is used instead, then check‐
4773 ing out a specific commit of the main
4774 project doesn't necessarily pin the whole
4775 build to a specific point in the life of
4776 the external project. The lack of such
4777 deterministic behavior makes the main
4778 project lose traceability and repeatabil‐
4779 ity.
4780 If GIT_SHALLOW is enabled then GIT_TAG
4782 works only with branch names and tags. A
4783 commit hash is not allowed.
4784 GIT_REMOTE_NAME <name>
4786 The optional name of the remote. If this
4787 option is not specified, it defaults to
4788 origin.
4789 GIT_SUBMODULES <module>...
4791 Specific git submodules that should also be
4792 updated. If this option is not provided,
4793 all git submodules will be updated.
4794 Changed in version 3.16: When CMP0097 is
4796 set to NEW, if this value is set to an
4797 empty string then no submodules are ini‐
4798 tialized or updated.
4799 GIT_SUBMODULES_RECURSE <bool>
4802 New in version 3.17.
4803 Specify whether git submodules (if any)
4806 should update recursively by passing the
4807 --recursive flag to git submodule update.
4808 If not specified, the default is on.
4809 GIT_SHALLOW <bool>
4811 New in version 3.6.
4812 When this option is enabled, the git clone
4815 operation will be given the --depth 1 op‐
4816 tion. This performs a shallow clone, which
4817 avoids downloading the whole history and
4818 instead retrieves just the commit denoted
4819 by the GIT_TAG option.
4820 GIT_PROGRESS <bool>
4822 New in version 3.8.
4823 When enabled, this option instructs the git
4826 clone operation to report its progress by
4827 passing it the --progress option. Without
4828 this option, the clone step for large
4829 projects may appear to make the build
4830 stall, since nothing will be logged until
4831 the clone operation finishes. While this
4832 option can be used to provide progress to
4833 prevent the appearance of the build having
4834 stalled, it may also make the build overly
4835 noisy if lots of external projects are
4836 used.
4837 GIT_CONFIG <option1> [<option2>...]
4839 New in version 3.8.
4840 Specify a list of config options to pass to
4843 git clone. Each option listed will be
4844 transformed into its own --config <option>
4845 on the git clone command line, with each
4846 option required to be in the form
4847 key=value.
4848 GIT_REMOTE_UPDATE_STRATEGY <strategy>
4850 New in version 3.18.
4851 When GIT_TAG refers to a remote branch,
4854 this option can be used to specify how the
4855 update step behaves. The <strategy> must
4856 be one of the following:
4857 CHECKOUT
4859 Ignore the local branch and always
4860 checkout the branch specified by
4861 GIT_TAG.
4862 REBASE Try to rebase the current branch to
4864 the one specified by GIT_TAG. If
4865 there are local uncommitted changes,
4866 they will be stashed first and
4867 popped again after rebasing. If re‐
4868 basing or popping stashed changes
4869 fail, abort the rebase and halt with
4870 an error. When GIT_REMOTE_UP‐
4871 DATE_STRATEGY is not present, this
4872 is the default strategy unless the
4873 default has been overridden with
4874 CMAKE_EP_GIT_REMOTE_UPDATE_STRATEGY
4875 (see below).
4876 REBASE_CHECKOUT
4878 Same as REBASE except if the rebase
4879 fails, an annotated tag will be cre‐
4880 ated at the original HEAD position
4881 from before the rebase and then
4882 checkout GIT_TAG just like the
4883 CHECKOUT strategy. The message
4884 stored on the annotated tag will
4885 give information about what was at‐
4886 tempted and the tag name will in‐
4887 clude a timestamp so that each
4888 failed run will add a new tag. This
4889 strategy ensures no changes will be
4890 lost, but updates should always suc‐
4891 ceed if GIT_TAG refers to a valid
4892 ref unless there are uncommitted
4893 changes that cannot be popped suc‐
4894 cessfully.
4895 The variable CMAKE_EP_GIT_REMOTE_UP‐
4897 DATE_STRATEGY can be set to override the
4898 default strategy. This variable should not
4899 be set by a project, it is intended for the
4900 user to set. It is primarily intended for
4901 use in continuous integration scripts to
4902 ensure that when history is rewritten on a
4903 remote branch, the build doesn't end up
4904 with unintended changes or failed builds
4905 resulting from conflicts during rebase op‐
4906 erations.
4907 Subversion
4909 SVN_REPOSITORY <url>
4911 URL of the Subversion repository.
4912 SVN_REVISION -r<rev>
4914 Revision to checkout from the Subversion
4915 repository.
4916 SVN_USERNAME <username>
4918 Username for the Subversion checkout and
4919 update.
4920 SVN_PASSWORD <password>
4922 Password for the Subversion checkout and
4923 update.
4924 SVN_TRUST_CERT <bool>
4926 Specifies whether to trust the Subversion
4927 server site certificate. If enabled, the
4928 --trust-server-cert option is passed to the
4929 svn checkout and update commands.
4930 Mercurial
4932 HG_REPOSITORY <url>
4934 URL of the mercurial repository.
4935 HG_TAG <tag>
4937 Mercurial branch name, tag or commit id.
4938 CVS
4940 CVS_REPOSITORY <cvsroot>
4942 CVSROOT of the CVS repository.
4943 CVS_MODULE <mod>
4945 Module to checkout from the CVS repository.
4946 CVS_TAG <tag>
4948 Tag to checkout from the CVS repository.
4949 Update/Patch Step Options:
4951 Whenever CMake is re-run, by default the external
4952 project's sources will be updated if the download method
4953 supports updates (e.g. a git repository would be checked
4954 if the GIT_TAG does not refer to a specific commit).
4955 UPDATE_COMMAND <cmd>...
4957 Overrides the download method's update step with a
4958 custom command. The command may use generator ex‐
4959 pressions.
4960 UPDATE_DISCONNECTED <bool>
4962 New in version 3.2.
4963 When enabled, this option causes the update step
4966 to be skipped. It does not, however, prevent the
4967 download step. The update step can still be added
4968 as a step target (see
4969 ExternalProject_Add_StepTargets()) and called man‐
4970 ually. This is useful if you want to allow devel‐
4971 opers to build the project when disconnected from
4972 the network (the network may still be needed for
4973 the download step though).
4974 When this option is present, it is generally ad‐
4976 visable to make the value a cache variable under
4977 the developer's control rather than hard-coding
4978 it. If this option is not present, the default
4979 value is taken from the EP_UPDATE_DISCONNECTED di‐
4980 rectory property. If that is also not defined, up‐
4981 dates are performed as normal. The EP_UPDATE_DIS‐
4982 CONNECTED directory property is intended as a con‐
4983 venience for controlling the UPDATE_DISCONNECTED
4984 behavior for an entire section of a project's di‐
4985 rectory hierarchy and may be a more convenient
4986 method of giving developers control over whether
4987 or not to perform updates (assuming the project
4988 also provides a cache variable or some other con‐
4989 venient method for setting the directory prop‐
4990 erty).
4991 This may cause a step target to be created auto‐
4993 matically for the download step. See policy
4994 CMP0114.
4995 PATCH_COMMAND <cmd>...
4997 Specifies a custom command to patch the sources
4998 after an update. By default, no patch command is
4999 defined. Note that it can be quite difficult to
5000 define an appropriate patch command that performs
5001 robustly, especially for download methods such as
5002 git where changing the GIT_TAG will not discard
5003 changes from a previous patch, but the patch com‐
5004 mand will be called again after updating to the
5005 new tag.
5006 Configure Step Options:
5008 The configure step is run after the download and update
5009 steps. By default, the external project is assumed to be
5010 a CMake project, but this can be overridden if required.
5011 CONFIGURE_COMMAND <cmd>...
5013 The default configure command runs CMake with a
5014 few options based on the main project. The op‐
5015 tions added are typically only those needed to use
5016 the same generator as the main project, but the
5017 CMAKE_GENERATOR option can be given to override
5018 this. The project is responsible for adding any
5019 toolchain details, flags or other settings it
5020 wants to re-use from the main project or otherwise
5021 specify (see CMAKE_ARGS, CMAKE_CACHE_ARGS and
5022 CMAKE_CACHE_DEFAULT_ARGS below).
5023 For non-CMake external projects, the CONFIG‐
5025 URE_COMMAND option must be used to override the
5026 default configure command (generator expressions
5027 are supported). For projects that require no con‐
5028 figure step, specify this option with an empty
5029 string as the command to execute.
5030 CMAKE_COMMAND /.../cmake
5032 Specify an alternative cmake executable for the
5033 configure step (use an absolute path). This is
5034 generally not recommended, since it is usually de‐
5035 sirable to use the same CMake version throughout
5036 the whole build. This option is ignored if a cus‐
5037 tom configure command has been specified with CON‐
5038 FIGURE_COMMAND.
5039 CMAKE_GENERATOR <gen>
5041 Override the CMake generator used for the config‐
5042 ure step. Without this option, the same generator
5043 as the main build will be used. This option is ig‐
5044 nored if a custom configure command has been spec‐
5045 ified with the CONFIGURE_COMMAND option.
5046 CMAKE_GENERATOR_PLATFORM <platform>
5048 New in version 3.1.
5049 Pass a generator-specific platform name to the
5052 CMake command (see CMAKE_GENERATOR_PLATFORM). It
5053 is an error to provide this option without the
5054 CMAKE_GENERATOR option.
5055 CMAKE_GENERATOR_TOOLSET <toolset>
5057 Pass a generator-specific toolset name to the
5058 CMake command (see CMAKE_GENERATOR_TOOLSET). It is
5059 an error to provide this option without the
5060 CMAKE_GENERATOR option.
5061 CMAKE_GENERATOR_INSTANCE <instance>
5063 New in version 3.11.
5064 Pass a generator-specific instance selection to
5067 the CMake command (see CMAKE_GENERATOR_INSTANCE).
5068 It is an error to provide this option without the
5069 CMAKE_GENERATOR option.
5070 CMAKE_ARGS <arg>...
5072 The specified arguments are passed to the cmake
5073 command line. They can be any argument the cmake
5074 command understands, not just cache values defined
5075 by -D... arguments (see also CMake Options).
5076 New in version 3.3: Arguments may use generator
5078 expressions.
5079 CMAKE_CACHE_ARGS <arg>...
5082 This is an alternate way of specifying cache vari‐
5083 ables where command line length issues may become
5084 a problem. The arguments are expected to be in the
5085 form -Dvar:STRING=value, which are then trans‐
5086 formed into CMake set() commands with the FORCE
5087 option used. These set() commands are written to a
5088 pre-load script which is then applied using the
5089 cmake -C command line option.
5090 New in version 3.3: Arguments may use generator
5092 expressions.
5093 CMAKE_CACHE_DEFAULT_ARGS <arg>...
5096 New in version 3.2.
5097 This is the same as the CMAKE_CACHE_ARGS option
5100 except the set() commands do not include the FORCE
5101 keyword. This means the values act as initial de‐
5102 faults only and will not override any variables
5103 already set from a previous run. Use this option
5104 with care, as it can lead to different behavior
5105 depending on whether the build starts from a fresh
5106 build directory or re-uses previous build con‐
5107 tents.
5108 New in version 3.15: If the CMake generator is the
5110 Green Hills MULTI and not overridden then the
5111 original project's settings for the GHS toolset
5112 and target system customization cache variables
5113 are propagated into the external project.
5114 SOURCE_SUBDIR <dir>
5117 New in version 3.7.
5118 When no CONFIGURE_COMMAND option is specified, the
5121 configure step assumes the external project has a
5122 CMakeLists.txt file at the top of its source tree
5123 (i.e. in SOURCE_DIR). The SOURCE_SUBDIR option can
5124 be used to point to an alternative directory
5125 within the source tree to use as the top of the
5126 CMake source tree instead. This must be a relative
5127 path and it will be interpreted as being relative
5128 to SOURCE_DIR.
5129 New in version 3.14: When BUILD_IN_SOURCE option
5131 is enabled, the BUILD_COMMAND is used to point to
5132 an alternative directory within the source tree.
5133 CONFIGURE_HANDLED_BY_BUILD <bool>
5136 New in version 3.20.
5137 Enabling this option relaxes the dependencies of
5140 the configure step on other external projects to
5141 order-only. This means the configure step will be
5142 executed after its external project dependencies
5143 are built but it will not be marked dirty when one
5144 of its external project dependencies is rebuilt.
5145 This option can be enabled when the build step is
5146 smart enough to figure out if the configure step
5147 needs to be rerun. CMake and Meson are examples of
5148 build systems whose build step is smart enough to
5149 know if the configure step needs to be rerun.
5150 Build Step Options:
5152 If the configure step assumed the external project uses
5153 CMake as its build system, the build step will also. Oth‐
5154 erwise, the build step will assume a Makefile-based build
5155 and simply run make with no arguments as the default
5156 build step. This can be overridden with custom build com‐
5157 mands if required.
5158 If both the main project and the external project use
5160 make as their build tool, the build step of the external
5161 project is invoked as a recursive make using $(MAKE).
5162 This will communicate some build tool settings from the
5163 main project to the external project. If either the main
5164 project or external project is not using make, no build
5165 tool settings will be passed to the external project
5166 other than those established by the configure step (i.e.
5167 running ninja -v in the main project will not pass -v to
5168 the external project's build step, even if it also uses
5169 ninja as its build tool).
5170 BUILD_COMMAND <cmd>...
5172 Overrides the default build command (generator ex‐
5173 pressions are supported). If this option is not
5174 given, the default build command will be chosen to
5175 integrate with the main build in the most appro‐
5176 priate way (e.g. using recursive make for Makefile
5177 generators or cmake --build if the project uses a
5178 CMake build). This option can be specified with an
5179 empty string as the command to make the build step
5180 do nothing.
5181 BUILD_IN_SOURCE <bool>
5183 When this option is enabled, the build will be
5184 done directly within the external project's source
5185 tree. This should generally be avoided, the use of
5186 a separate build directory is usually preferred,
5187 but it can be useful when the external project as‐
5188 sumes an in-source build. The BINARY_DIR option
5189 should not be specified if building in-source.
5190 BUILD_ALWAYS <bool>
5192 Enabling this option forces the build step to al‐
5193 ways be run. This can be the easiest way to ro‐
5194 bustly ensure that the external project's own
5195 build dependencies are evaluated rather than rely‐
5196 ing on the default success timestamp-based method.
5197 This option is not normally needed unless develop‐
5198 ers are expected to modify something the external
5199 project's build depends on in a way that is not
5200 detectable via the step target dependencies (e.g.
5201 SOURCE_DIR is used without a download method and
5202 developers might modify the sources in
5203 SOURCE_DIR).
5204 BUILD_BYPRODUCTS <file>...
5206 New in version 3.2.
5207 Specifies files that will be generated by the
5210 build command but which might or might not have
5211 their modification time updated by subsequent
5212 builds. These ultimately get passed through as
5213 BYPRODUCTS to the build step's own underlying call
5214 to add_custom_command().
5215 Install Step Options:
5217 If the configure step assumed the external project uses
5218 CMake as its build system, the install step will also.
5219 Otherwise, the install step will assume a Makefile-based
5220 build and simply run make install as the default build
5221 step. This can be overridden with custom install commands
5222 if required.
5223 INSTALL_COMMAND <cmd>...
5225 The external project's own install step is invoked
5226 as part of the main project's build. It is done
5227 after the external project's build step and may be
5228 before or after the external project's test step
5229 (see the TEST_BEFORE_INSTALL option below). The
5230 external project's install rules are not part of
5231 the main project's install rules, so if anything
5232 from the external project should be installed as
5233 part of the main build, these need to be specified
5234 in the main build as additional install() com‐
5235 mands. The default install step builds the install
5236 target of the external project, but this can be
5237 overridden with a custom command using this option
5238 (generator expressions are supported). Passing an
5239 empty string as the <cmd> makes the install step
5240 do nothing.
5241 NOTE:
5243 If the CMAKE_INSTALL_MODE environment variable is set
5244 when the main project is built, it will only have an
5245 effect if the following conditions are met:
5246 • The main project's configure step assumed the exter‐
5248 nal project uses CMake as its build system.
5249 • The external project's install command actually
5251 runs. Note that due to the way ExternalProject may
5252 use timestamps internally, if nothing the install
5253 step depends on needs to be re-executed, the install
5254 command might also not need to run.
5255 Note also that ExternalProject does not check whether
5257 the CMAKE_INSTALL_MODE environment variable changes
5258 from one run to another.
5259 Test Step Options:
5261 The test step is only defined if at least one of the fol‐
5262 lowing TEST_... options are provided.
5263 TEST_COMMAND <cmd>...
5265 Overrides the default test command (generator ex‐
5266 pressions are supported). If this option is not
5267 given, the default behavior of the test step is to
5268 build the external project's own test target. This
5269 option can be specified with <cmd> as an empty
5270 string, which allows the test step to still be de‐
5271 fined, but it will do nothing. Do not specify any
5272 of the other TEST_... options if providing an
5273 empty string as the test command, but prefer to
5274 omit all TEST_... options altogether if the test
5275 step target is not needed.
5276 TEST_BEFORE_INSTALL <bool>
5278 When this option is enabled, the test step will be
5279 executed before the install step. The default be‐
5280 havior is for the test step to run after the in‐
5281 stall step.
5282 TEST_AFTER_INSTALL <bool>
5284 This option is mainly useful as a way to indicate
5285 that the test step is desired but all default be‐
5286 havior is sufficient. Specifying this option with
5287 a boolean true value ensures the test step is de‐
5288 fined and that it comes after the install step. If
5289 both TEST_BEFORE_INSTALL and TEST_AFTER_INSTALL
5290 are enabled, the latter is silently ignored.
5291 TEST_EXCLUDE_FROM_MAIN <bool>
5293 New in version 3.2.
5294 If enabled, the main build's default ALL target
5297 will not depend on the test step. This can be a
5298 useful way of ensuring the test step is defined
5299 but only gets invoked when manually requested.
5300 This may cause a step target to be created auto‐
5301 matically for either the install or build step.
5302 See policy CMP0114.
5303 Output Logging Options:
5305 Each of the following LOG_... options can be used to wrap
5306 the relevant step in a script to capture its output to
5307 files. The log files will be created in LOG_DIR if sup‐
5308 plied or otherwise the STAMP_DIR directory with step-spe‐
5309 cific file names.
5310 LOG_DOWNLOAD <bool>
5312 When enabled, the output of the download step is
5313 logged to files.
5314 LOG_UPDATE <bool>
5316 When enabled, the output of the update step is
5317 logged to files.
5318 LOG_PATCH <bool>
5320 New in version 3.14.
5321 When enabled, the output of the patch step is
5324 logged to files.
5325 LOG_CONFIGURE <bool>
5327 When enabled, the output of the configure step is
5328 logged to files.
5329 LOG_BUILD <bool>
5331 When enabled, the output of the build step is
5332 logged to files.
5333 LOG_INSTALL <bool>
5335 When enabled, the output of the install step is
5336 logged to files.
5337 LOG_TEST <bool>
5339 When enabled, the output of the test step is
5340 logged to files.
5341 LOG_MERGED_STDOUTERR <bool>
5343 New in version 3.14.
5344 When enabled, stdout and stderr will be merged for
5347 any step whose output is being logged to files.
5348 LOG_OUTPUT_ON_FAILURE <bool>
5350 New in version 3.14.
5351 This option only has an effect if at least one of
5354 the other LOG_<step> options is enabled. If an
5355 error occurs for a step which has logging to file
5356 enabled, that step's output will be printed to the
5357 console if LOG_OUTPUT_ON_FAILURE is set to true.
5358 For cases where a large amount of output is
5359 recorded, just the end of that output may be
5360 printed to the console.
5361 Terminal Access Options:
5363 New in version 3.4.
5364 Steps can be given direct access to the terminal in some
5367 cases. Giving a step access to the terminal may allow it
5368 to receive terminal input if required, such as for au‐
5369 thentication details not provided by other options. With
5370 the Ninja generator, these options place the steps in the
5371 console job pool. Each step can be given access to the
5372 terminal individually via the following options:
5373 USES_TERMINAL_DOWNLOAD <bool>
5375 Give the download step access to the terminal.
5376 USES_TERMINAL_UPDATE <bool>
5378 Give the update step access to the terminal.
5379 USES_TERMINAL_CONFIGURE <bool>
5381 Give the configure step access to the terminal.
5382 USES_TERMINAL_BUILD <bool>
5384 Give the build step access to the terminal.
5385 USES_TERMINAL_INSTALL <bool>
5387 Give the install step access to the terminal.
5388 USES_TERMINAL_TEST <bool>
5390 Give the test step access to the terminal.
5391 Target Options:
5393 DEPENDS <targets>...
5395 Specify other targets on which the external
5396 project depends. The other targets will be brought
5397 up to date before any of the external project's
5398 steps are executed. Because the external project
5399 uses additional custom targets internally for each
5400 step, the DEPENDS option is the most convenient
5401 way to ensure all of those steps depend on the
5402 other targets. Simply doing add_dependen‐
5403 cies(<name> <targets>) will not make any of the
5404 steps dependent on <targets>.
5405 EXCLUDE_FROM_ALL <bool>
5407 When enabled, this option excludes the external
5408 project from the default ALL target of the main
5409 build.
5410 STEP_TARGETS <step-target>...
5412 Generate custom targets for the specified steps.
5413 This is required if the steps need to be triggered
5414 manually or if they need to be used as dependen‐
5415 cies of other targets. If this option is not spec‐
5416 ified, the default value is taken from the
5417 EP_STEP_TARGETS directory property. See
5418 ExternalProject_Add_StepTargets() below for fur‐
5419 ther discussion of the effects of this option.
5420 INDEPENDENT_STEP_TARGETS <step-target>...
5422 Deprecated since version 3.19: This is allowed
5423 only if policy CMP0114 is not set to NEW.
5424 Generates custom targets for the specified steps
5427 and prevent these targets from having the usual
5428 dependencies applied to them. If this option is
5429 not specified, the default value is taken from the
5430 EP_INDEPENDENT_STEP_TARGETS directory property.
5431 This option is mostly useful for allowing individ‐
5432 ual steps to be driven independently, such as for
5433 a CDash setup where each step should be initiated
5434 and reported individually rather than as one whole
5435 build. See ExternalProject_Add_StepTargets() below
5436 for further discussion of the effects of this op‐
5437 tion.
5438 Miscellaneous Options:
5440 LIST_SEPARATOR <sep>
5442 For any of the various ..._COMMAND options, re‐
5443 place ; with <sep> in the specified command lines.
5444 This can be useful where list variables may be
5445 given in commands where they should end up as
5446 space-separated arguments (<sep> would be a single
5447 space character string in this case).
5448 COMMAND <cmd>...
5450 Any of the other ..._COMMAND options can have ad‐
5451 ditional commands appended to them by following
5452 them with as many COMMAND ... options as needed
5453 (generator expressions are supported). For exam‐
5454 ple:
5455 ExternalProject_Add(example
5457 ... # Download options, etc.
5458 BUILD_COMMAND ${CMAKE_COMMAND} -E echo "Starting $<CONFIG> build"
5459 COMMAND ${CMAKE_COMMAND} --build <BINARY_DIR> --config $<CONFIG>
5460 COMMAND ${CMAKE_COMMAND} -E echo "$<CONFIG> build complete"
5461 )
5462 It should also be noted that each build step is created via a
5464 call to ExternalProject_Add_Step(). See that command's documen‐
5465 tation for the automatic substitutions that are supported for
5466 some options.
5467 Obtaining Project Properties
5469 ExternalProject_Get_Property
5470 The ExternalProject_Get_Property() function retrieves external
5471 project target properties:
5472 ExternalProject_Get_Property(<name> <prop1> [<prop2>...])
5474 The function stores property values in variables of the same
5476 name. Property names correspond to the keyword argument names of
5477 ExternalProject_Add(). For example, the source directory might
5478 be retrieved like so:
5479 ExternalProject_Get_property(myExtProj SOURCE_DIR)
5481 message("Source dir of myExtProj = ${SOURCE_DIR}")
5482 Explicit Step Management
5484 The ExternalProject_Add() function on its own is often sufficient for
5485 incorporating an external project into the main build. Certain scenar‐
5486 ios require additional work to implement desired behavior, such as
5487 adding in a custom step or making steps available as manually trigger‐
5488 able targets. The ExternalProject_Add_Step(), ExternalProject_Add_Step‐
5489 Targets() and ExternalProject_Add_StepDependencies functions provide
5490 the lower level control needed to implement such step-level capabili‐
5491 ties.
5492 ExternalProject_Add_Step
5494 The ExternalProject_Add_Step() function specifies an additional
5495 custom step for an external project defined by an earlier call
5496 to ExternalProject_Add():
5497 ExternalProject_Add_Step(<name> <step> [<option>...])
5499 <name> is the same as the name passed to the original call to
5501 ExternalProject_Add(). The specified <step> must not be one of
5502 the pre-defined steps (mkdir, download, update, patch, config‐
5503 ure, build, install or test). The supported options are:
5504 COMMAND <cmd>...
5506 The command line to be executed by this custom step (gen‐
5507 erator expressions are supported). This option can be re‐
5508 peated multiple times to specify multiple commands to be
5509 executed in order.
5510 COMMENT <text>...
5512 Text to be printed when the custom step executes.
5513 DEPENDEES <step>...
5515 Other steps (custom or pre-defined) on which this step
5516 depends.
5517 DEPENDERS <step>...
5519 Other steps (custom or pre-defined) that depend on this
5520 new custom step.
5521 DEPENDS <file>...
5523 Files on which this custom step depends.
5524 INDEPENDENT <bool>
5526 New in version 3.19.
5527 Specifies whether this step is independent of the exter‐
5530 nal dependencies specified by the ExternalProject_Add()'s
5531 DEPENDS option. The default is FALSE. Steps marked as
5532 independent may depend only on other steps marked inde‐
5533 pendent. See policy CMP0114.
5534 Note that this use of the term "independent" refers only
5536 to independence from external targets specified by the
5537 DEPENDS option and is orthogonal to a step's dependencies
5538 on other steps.
5539 If a step target is created for an independent step by
5541 the ExternalProject_Add() STEP_TARGETS option or by the
5542 ExternalProject_Add_StepTargets() function, it will not
5543 depend on the external targets, but may depend on targets
5544 for other steps.
5545 BYPRODUCTS <file>...
5547 New in version 3.2.
5548 Files that will be generated by this custom step but
5551 which might or might not have their modification time up‐
5552 dated by subsequent builds. This list of files will ulti‐
5553 mately be passed through as the BYPRODUCTS option to the
5554 add_custom_command() used to implement the custom step
5555 internally.
5556 ALWAYS <bool>
5558 When enabled, this option specifies that the custom step
5559 should always be run (i.e. that it is always considered
5560 out of date).
5561 EXCLUDE_FROM_MAIN <bool>
5563 When enabled, this option specifies that the external
5564 project's main target does not depend on the custom step.
5565 This may cause step targets to be created automatically
5566 for the steps on which this step depends. See policy
5567 CMP0114.
5568 WORKING_DIRECTORY <dir>
5570 Specifies the working directory to set before running the
5571 custom step's command. If this option is not specified,
5572 the directory will be the value of the CMAKE_CURRENT_BI‐
5573 NARY_DIR at the point where ExternalProject_Add_Step()
5574 was called.
5575 LOG <bool>
5577 If set, this causes the output from the custom step to be
5578 captured to files in the external project's LOG_DIR if
5579 supplied or STAMP_DIR.
5580 USES_TERMINAL <bool>
5582 If enabled, this gives the custom step direct access to
5583 the terminal if possible.
5584 The command line, comment, working directory and byproducts of
5586 every standard and custom step are processed to replace the to‐
5587 kens <SOURCE_DIR>, <SOURCE_SUBDIR>, <BINARY_DIR>, <INSTALL_DIR>
5588 <TMP_DIR>, <DOWNLOAD_DIR> and <DOWNLOADED_FILE> with their cor‐
5589 responding property values defined in the original call to
5590 ExternalProject_Add().
5591 New in version 3.3: Token replacement is extended to byproducts.
5593 New in version 3.11: The <DOWNLOAD_DIR> substitution token.
5596 ExternalProject_Add_StepTargets
5599 The ExternalProject_Add_StepTargets() function generates targets
5600 for the steps listed. The name of each created target will be of
5601 the form <name>-<step>:
5602 ExternalProject_Add_StepTargets(<name> <step1> [<step2>...])
5604 Creating a target for a step allows it to be used as a depen‐
5606 dency of another target or to be triggered manually. Having tar‐
5607 gets for specific steps also allows them to be driven indepen‐
5608 dently of each other by specifying targets on build command
5609 lines. For example, you may be submitting to a sub-project based
5610 dashboard where you want to drive the configure portion of the
5611 build, then submit to the dashboard, followed by the build por‐
5612 tion, followed by tests. If you invoke a custom target that de‐
5613 pends on a step halfway through the step dependency chain, then
5614 all the previous steps will also run to ensure everything is up
5615 to date.
5616 Internally, ExternalProject_Add() calls
5618 ExternalProject_Add_Step() to create each step. If any STEP_TAR‐
5619 GETS were specified, then ExternalProject_Add_StepTargets() will
5620 also be called after ExternalProject_Add_Step(). Even if a step
5621 is not mentioned in the STEP_TARGETS option, ExternalPro‐
5622 ject_Add_StepTargets() can still be called later to manually de‐
5623 fine a target for the step.
5624 The STEP_TARGETS option for ExternalProject_Add() is generally
5626 the easiest way to ensure targets are created for specific steps
5627 of interest. For custom steps, ExternalProject_Add_StepTar‐
5628 gets() must be called explicitly if a target should also be cre‐
5629 ated for that custom step. An alternative to these two options
5630 is to populate the EP_STEP_TARGETS directory property. It acts
5631 as a default for the step target options and can save having to
5632 repeatedly specify the same set of step targets when multiple
5633 external projects are being defined.
5634 New in version 3.19: If CMP0114 is set to NEW, step targets are
5636 fully responsible for holding the custom commands implementing
5637 their steps. The primary target created by ExternalProject_Add
5638 depends on the step targets, and the step targets depend on each
5639 other. The target-level dependencies match the file-level de‐
5640 pendencies used by the custom commands for each step. The tar‐
5641 gets for steps created with ExternalProject_Add_Step()'s INDE‐
5642 PENDENT option do not depend on the external targets specified
5643 by ExternalProject_Add()'s DEPENDS option. The predefined steps
5644 mkdir, download, update, and patch are independent.
5645 If CMP0114 is not NEW, the following deprecated behavior is
5648 available:
5649 • A deprecated NO_DEPENDS option may be specified immediately
5651 after the <name> and before the first step. If the NO_DEPENDS
5652 option is specified, the step target will not depend on the
5653 dependencies of the external project (i.e. on any dependencies
5654 of the <name> custom target created by ExternalProject_Add()).
5655 This is usually safe for the download, update and patch steps,
5656 since they do not typically require that the dependencies are
5657 updated and built. Using NO_DEPENDS for any of the other
5658 pre-defined steps, however, may break parallel builds. Only
5659 use NO_DEPENDS where it is certain that the named steps gen‐
5660 uinely do not have dependencies. For custom steps, consider
5661 whether or not the custom commands require the dependencies to
5662 be configured, built and installed.
5663 • The INDEPENDENT_STEP_TARGETS option for ExternalProject_Add(),
5665 or the EP_INDEPENDENT_STEP_TARGETS directory property, tells
5666 the function to call ExternalProject_Add_StepTargets() inter‐
5667 nally using the NO_DEPENDS option for the specified steps.
5668 ExternalProject_Add_StepDependencies
5670 New in version 3.2.
5671 The ExternalProject_Add_StepDependencies() function can be used
5674 to add dependencies to a step. The dependencies added must be
5675 targets CMake already knows about (these can be ordinary exe‐
5676 cutable or library targets, custom targets or even step targets
5677 of another external project):
5678 ExternalProject_Add_StepDependencies(<name> <step> <target1> [<target2>...])
5680 This function takes care to set both target and file level de‐
5682 pendencies and will ensure that parallel builds will not break.
5683 It should be used instead of add_dependencies() whenever adding
5684 a dependency for some of the step targets generated by the Ex‐
5685 ternalProject module.
5686 Examples
5688 The following example shows how to download and build a hypothetical
5689 project called FooBar from github:
5690 include(ExternalProject)
5692 ExternalProject_Add(foobar
5693 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
5694 GIT_TAG origin/release/1.2.3
5695 )
5696 For the sake of the example, also define a second hypothetical external
5698 project called SecretSauce, which is downloaded from a web server. Two
5699 URLs are given to take advantage of a faster internal network if avail‐
5700 able, with a fallback to a slower external server. The project is a
5701 typical Makefile project with no configure step, so some of the default
5702 commands are overridden. The build is only required to build the sauce
5703 target:
5704 find_program(MAKE_EXE NAMES gmake nmake make)
5706 ExternalProject_Add(secretsauce
5707 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
5708 https://www.somecompany.com/downloads/sauce-2.7.zip
5709 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
5710 CONFIGURE_COMMAND ""
5711 BUILD_COMMAND ${MAKE_EXE} sauce
5712 )
5713 Suppose the build step of secretsauce requires that foobar must already
5715 be built. This could be enforced like so:
5716 ExternalProject_Add_StepDependencies(secretsauce build foobar)
5718 Another alternative would be to create a custom target for foobar's
5720 build step and make secretsauce depend on that rather than the whole
5721 foobar project. This would mean foobar only needs to be built, it
5722 doesn't need to run its install or test steps before secretsauce can be
5723 built. The dependency can also be defined along with the secretsauce
5724 project:
5725 ExternalProject_Add_StepTargets(foobar build)
5727 ExternalProject_Add(secretsauce
5728 URL http://intranet.somecompany.com/artifacts/sauce-2.7.tgz
5729 https://www.somecompany.com/downloads/sauce-2.7.zip
5730 URL_HASH MD5=d41d8cd98f00b204e9800998ecf8427e
5731 CONFIGURE_COMMAND ""
5732 BUILD_COMMAND ${MAKE_EXE} sauce
5733 DEPENDS foobar-build
5734 )
5735 Instead of calling ExternalProject_Add_StepTargets(), the target could
5737 be defined along with the foobar project itself:
5738 ExternalProject_Add(foobar
5740 GIT_REPOSITORY git@github.com:FooCo/FooBar.git
5741 GIT_TAG origin/release/1.2.3
5742 STEP_TARGETS build
5743 )
5744 If many external projects should have the same set of step targets,
5746 setting a directory property may be more convenient. The build step
5747 target could be created automatically by setting the EP_STEP_TARGETS
5748 directory property before creating the external projects with
5749 ExternalProject_Add():
5750 set_property(DIRECTORY PROPERTY EP_STEP_TARGETS build)
5752 Lastly, suppose that secretsauce provides a script called makedoc which
5754 can be used to generate its own documentation. Further suppose that the
5755 script expects the output directory to be provided as the only parame‐
5756 ter and that it should be run from the secretsauce source directory. A
5757 custom step and a custom target to trigger the script can be defined
5758 like so:
5759 ExternalProject_Add_Step(secretsauce docs
5761 COMMAND <SOURCE_DIR>/makedoc <BINARY_DIR>
5762 WORKING_DIRECTORY <SOURCE_DIR>
5763 COMMENT "Building secretsauce docs"
5764 ALWAYS TRUE
5765 EXCLUDE_FROM_MAIN TRUE
5766 )
5767 ExternalProject_Add_StepTargets(secretsauce docs)
5768 The custom step could then be triggered from the main build like so:
5770 cmake --build . --target secretsauce-docs
5772 FeatureSummary
5774 Functions for generating a summary of enabled/disabled features.
5775 These functions can be used to generate a summary of enabled and dis‐
5777 abled packages and/or feature for a build tree such as:
5778 -- The following OPTIONAL packages have been found:
5780 LibXml2 (required version >= 2.4), XML processing lib, <http://xmlsoft.org>
5781 * Enables HTML-import in MyWordProcessor
5782 * Enables odt-export in MyWordProcessor
5783 PNG, A PNG image library., <http://www.libpng.org/pub/png/>
5784 * Enables saving screenshots
5785 -- The following OPTIONAL packages have not been found:
5786 Lua51, The Lua scripting language., <http://www.lua.org>
5787 * Enables macros in MyWordProcessor
5788 Foo, Foo provides cool stuff.
5789 Global Properties
5791 FeatureSummary_PKG_TYPES
5792 The global property FeatureSummary_PKG_TYPES defines the type of pack‐
5794 ages used by FeatureSummary.
5795 The order in this list is important, the first package type in the list
5797 is the least important, the last is the most important. the of a pack‐
5798 age can only be changed to higher types.
5799 The default package types are , RUNTIME, OPTIONAL, RECOMMENDED and RE‐
5801 QUIRED, and their importance is RUNTIME < OPTIONAL < RECOMMENDED < RE‐
5802 QUIRED.
5803 FeatureSummary_REQUIRED_PKG_TYPES
5805 The global property FeatureSummary_REQUIRED_PKG_TYPES defines which
5807 package types are required.
5808 If one or more package in this categories has not been found, CMake
5810 will abort when calling feature_summary() with the 'FATAL_ON_MISS‐
5811 ING_REQUIRED_PACKAGES' option enabled.
5812 The default value for this global property is REQUIRED.
5814 FeatureSummary_DEFAULT_PKG_TYPE
5816 The global property FeatureSummary_DEFAULT_PKG_TYPE defines which pack‐
5818 age type is the default one. When calling feature_summary(), if the
5819 user did not set the package type explicitly, the package will be as‐
5820 signed to this category.
5821 This value must be one of the types defined in the
5823 FeatureSummary_PKG_TYPES global property unless the package type is set
5824 for all the packages.
5825 The default value for this global property is OPTIONAL.
5827 FeatureSummary_<TYPE>_DESCRIPTION
5829 New in version 3.9.
5831 The global property FeatureSummary_<TYPE>_DESCRIPTION can be defined
5834 for each type to replace the type name with the specified string when‐
5835 ever the package type is used in an output string.
5836 If not set, the string "<TYPE> packages" is used.
5838 Functions
5840 feature_summary
5841 feature_summary( [FILENAME <file>]
5843 [APPEND]
5844 [VAR <variable_name>]
5845 [INCLUDE_QUIET_PACKAGES]
5846 [FATAL_ON_MISSING_REQUIRED_PACKAGES]
5847 [DESCRIPTION "<description>" | DEFAULT_DESCRIPTION]
5848 [QUIET_ON_EMPTY]
5849 WHAT (ALL
5850 | PACKAGES_FOUND | PACKAGES_NOT_FOUND
5851 | <TYPE>_PACKAGES_FOUND | <TYPE>_PACKAGES_NOT_FOUND
5852 | ENABLED_FEATURES | DISABLED_FEATURES)
5853 )
5854 The feature_summary() macro can be used to print information
5856 about enabled or disabled packages or features of a project. By
5857 default, only the names of the features/packages will be printed
5858 and their required version when one was specified. Use
5859 set_package_properties() to add more useful information, like
5860 e.g. a download URL for the respective package or their purpose
5861 in the project.
5862 The WHAT option is the only mandatory option. Here you specify
5864 what information will be printed:
5865 ALL print everything
5867 ENABLED_FEATURES
5869 the list of all features which are enabled
5870 DISABLED_FEATURES
5872 the list of all features which are disabled
5873 PACKAGES_FOUND
5875 the list of all packages which have been found
5876 PACKAGES_NOT_FOUND
5878 the list of all packages which have not been found
5879 For each package type <TYPE> defined by the
5881 FeatureSummary_PKG_TYPES global property, the following informa‐
5882 tion can also be used:
5883 <TYPE>_PACKAGES_FOUND
5885 only those packages which have been found which have the
5886 type <TYPE>
5887 <TYPE>_PACKAGES_NOT_FOUND
5889 only those packages which have not been found which have
5890 the type <TYPE>
5891 Changed in version 3.1: With the exception of the ALL value,
5893 these values can be combined in order to customize the output.
5894 For example:
5895 feature_summary(WHAT ENABLED_FEATURES DISABLED_FEATURES)
5897 If a FILENAME is given, the information is printed into this
5900 file. If APPEND is used, it is appended to this file, otherwise
5901 the file is overwritten if it already existed. If the VAR op‐
5902 tion is used, the information is "printed" into the specified
5903 variable. If FILENAME is not used, the information is printed
5904 to the terminal. Using the DESCRIPTION option a description or
5905 headline can be set which will be printed above the actual con‐
5906 tent. If only one type of package was requested, no title is
5907 printed, unless it is explicitly set using either DESCRIPTION to
5908 use a custom string, or DEFAULT_DESCRIPTION to use a default ti‐
5909 tle for the requested type. If INCLUDE_QUIET_PACKAGES is given,
5910 packages which have been searched with find_package(... QUIET)
5911 will also be listed. By default they are skipped. If FA‐
5912 TAL_ON_MISSING_REQUIRED_PACKAGES is given, CMake will abort if a
5913 package which is marked as one of the package types listed in
5914 the FeatureSummary_REQUIRED_PKG_TYPES global property has not
5915 been found. The default value for the
5916 FeatureSummary_REQUIRED_PKG_TYPES global property is REQUIRED.
5917 New in version 3.9: The DEFAULT_DESCRIPTION option.
5919 The FeatureSummary_DEFAULT_PKG_TYPE global property can be modi‐
5922 fied to change the default package type assigned when not ex‐
5923 plicitly assigned by the user.
5924 New in version 3.8: If the QUIET_ON_EMPTY option is used, if
5926 only one type of package was requested, and no packages belong‐
5927 ing to that category were found, then no output (including the
5928 DESCRIPTION) is printed or added to the VAR variable.
5929 Example 1, append everything to a file:
5932 include(FeatureSummary)
5934 feature_summary(WHAT ALL
5935 FILENAME ${CMAKE_BINARY_DIR}/all.log APPEND)
5936 Example 2, print the enabled features into the variable enabled‐
5938 FeaturesText, including QUIET packages:
5939 include(FeatureSummary)
5941 feature_summary(WHAT ENABLED_FEATURES
5942 INCLUDE_QUIET_PACKAGES
5943 DESCRIPTION "Enabled Features:"
5944 VAR enabledFeaturesText)
5945 message(STATUS "${enabledFeaturesText}")
5946 Example 3, change default package types and print only the cate‐
5948 gories that are not empty:
5949 include(FeatureSummary)
5951 set_property(GLOBAL APPEND PROPERTY FeatureSummary_PKG_TYPES BUILD)
5952 find_package(FOO)
5953 set_package_properties(FOO PROPERTIES TYPE BUILD)
5954 feature_summary(WHAT BUILD_PACKAGES_FOUND
5955 Description "Build tools found:"
5956 QUIET_ON_EMPTY)
5957 feature_summary(WHAT BUILD_PACKAGES_NOT_FOUND
5958 Description "Build tools not found:"
5959 QUIET_ON_EMPTY)
5960 set_package_properties
5962 set_package_properties(<name> PROPERTIES
5964 [ URL <url> ]
5965 [ DESCRIPTION <description> ]
5966 [ TYPE (RUNTIME|OPTIONAL|RECOMMENDED|REQUIRED) ]
5967 [ PURPOSE <purpose> ]
5968 )
5969 Use this macro to set up information about the named package,
5971 which can then be displayed via FEATURE_SUMMARY(). This can be
5972 done either directly in the Find-module or in the project which
5973 uses the module after the find_package() call. The features for
5974 which information can be set are added automatically by the
5975 find_package() command.
5976 URL <url>
5978 This should be the homepage of the package, or something
5979 similar. Ideally this is set already directly in the
5980 Find-module.
5981 DESCRIPTION <description>
5983 A short description what that package is, at most one
5984 sentence. Ideally this is set already directly in the
5985 Find-module.
5986 TYPE <type>
5988 What type of dependency has the using project on that
5989 package. Default is OPTIONAL. In this case it is a
5990 package which can be used by the project when available
5991 at buildtime, but it also work without. RECOMMENDED is
5992 similar to OPTIONAL, i.e. the project will build if the
5993 package is not present, but the functionality of the re‐
5994 sulting binaries will be severely limited. If a REQUIRED
5995 package is not available at buildtime, the project may
5996 not even build. This can be combined with the FA‐
5997 TAL_ON_MISSING_REQUIRED_PACKAGES argument for fea‐
5998 ture_summary(). Last, a RUNTIME package is a package
5999 which is actually not used at all during the build, but
6000 which is required for actually running the resulting bi‐
6001 naries. So if such a package is missing, the project can
6002 still be built, but it may not work later on. If
6003 set_package_properties() is called multiple times for the
6004 same package with different TYPEs, the TYPE is only
6005 changed to higher TYPEs (RUNTIME < OPTIONAL < RECOMMENDED
6006 < REQUIRED), lower TYPEs are ignored. The TYPE property
6007 is project-specific, so it cannot be set by the Find-mod‐
6008 ule, but must be set in the project. Type accepted can
6009 be changed by setting the FeatureSummary_PKG_TYPES global
6010 property.
6011 PURPOSE <purpose>
6013 This describes which features this package enables in the
6014 project, i.e. it tells the user what functionality he
6015 gets in the resulting binaries. If set_package_proper‐
6016 ties() is called multiple times for a package, all PUR‐
6017 POSE properties are appended to a list of purposes of the
6018 package in the project. As the TYPE property, also the
6019 PURPOSE property is project-specific, so it cannot be set
6020 by the Find-module, but must be set in the project.
6021 Example for setting the info for a package:
6023 find_package(LibXml2)
6025 set_package_properties(LibXml2 PROPERTIES
6026 DESCRIPTION "A XML processing library."
6027 URL "http://xmlsoft.org/")
6028 # or
6029 set_package_properties(LibXml2 PROPERTIES
6030 TYPE RECOMMENDED
6031 PURPOSE "Enables HTML-import in MyWordProcessor")
6032 # or
6033 set_package_properties(LibXml2 PROPERTIES
6034 TYPE OPTIONAL
6035 PURPOSE "Enables odt-export in MyWordProcessor")
6036 find_package(DBUS)
6038 set_package_properties(DBUS PROPERTIES
6039 TYPE RUNTIME
6040 PURPOSE "Necessary to disable the screensaver during a presentation")
6041 add_feature_info
6043 add_feature_info(<name> <enabled> <description>)
6045 Use this macro to add information about a feature with the given
6047 <name>. <enabled> contains whether this feature is enabled or
6048 not. It can be a variable or a list of conditions. <descrip‐
6049 tion> is a text describing the feature. The information can be
6050 displayed using feature_summary() for ENABLED_FEATURES and DIS‐
6051 ABLED_FEATURES respectively.
6052 Changed in version 3.8: <enabled> can be a list of conditions.
6054 Example for setting the info for a feature:
6057 option(WITH_FOO "Help for foo" ON)
6059 add_feature_info(Foo WITH_FOO "The Foo feature provides very cool stuff.")
6060 Legacy Macros
6062 The following macros are provided for compatibility with previous CMake
6063 versions:
6064 set_package_info
6066 set_package_info(<name> <description> [ <url> [<purpose>] ])
6068 Use this macro to set up information about the named package,
6070 which can then be displayed via feature_summary(). This can be
6071 done either directly in the Find-module or in the project which
6072 uses the module after the find_package() call. The features for
6073 which information can be set are added automatically by the
6074 find_package() command.
6075 set_feature_info
6077 set_feature_info(<name> <description> [<url>])
6079 Does the same as:
6081 set_package_info(<name> <description> <url>)
6083 print_enabled_features
6085 print_enabled_features()
6087 Does the same as
6089 feature_summary(WHAT ENABLED_FEATURES DESCRIPTION "Enabled features:")
6091 print_disabled_features
6093 print_disabled_features()
6095 Does the same as
6097 feature_summary(WHAT DISABLED_FEATURES DESCRIPTION "Disabled features:")
6099 FetchContent
6101 New in version 3.11.
6102 Overview
6105 This module enables populating content at configure time via any method
6106 supported by the ExternalProject module. Whereas ExternalProject_Add()
6107 downloads at build time, the FetchContent module makes content avail‐
6108 able immediately, allowing the configure step to use the content in
6109 commands like add_subdirectory(), include() or file() operations.
6110 Content population details should be defined separately from the com‐
6112 mand that performs the actual population. This separation ensures that
6113 all the dependency details are defined before anything might try to use
6114 them to populate content. This is particularly important in more com‐
6115 plex project hierarchies where dependencies may be shared between mul‐
6116 tiple projects.
6117 The following shows a typical example of declaring content details for
6119 some dependencies and then ensuring they are populated with a separate
6120 call:
6121 FetchContent_Declare(
6123 googletest
6124 GIT_REPOSITORY https://github.com/google/googletest.git
6125 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
6126 )
6127 FetchContent_Declare(
6128 myCompanyIcons
6129 URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
6130 URL_HASH MD5=5588a7b18261c20068beabfb4f530b87
6131 )
6132 FetchContent_MakeAvailable(googletest secret_sauce)
6134 The FetchContent_MakeAvailable() command ensures the named dependencies
6136 have been populated, either by an earlier call or by populating them
6137 itself. When performing the population, it will also add them to the
6138 main build, if possible, so that the main build can use the populated
6139 projects' targets, etc. See the command's documentation for how these
6140 steps are performed.
6141 When using a hierarchical project arrangement, projects at higher lev‐
6143 els in the hierarchy are able to override the declared details of con‐
6144 tent specified anywhere lower in the project hierarchy. The first de‐
6145 tails to be declared for a given dependency take precedence, regardless
6146 of where in the project hierarchy that occurs. Similarly, the first
6147 call that tries to populate a dependency "wins", with subsequent popu‐
6148 lations reusing the result of the first instead of repeating the popu‐
6149 lation again. See the Examples which demonstrate this scenario.
6150 In some cases, the main project may need to have more precise control
6152 over the population, or it may be required to explicitly define the
6153 population steps in a way that cannot be captured by the declared de‐
6154 tails alone. For such situations, the lower level
6155 FetchContent_GetProperties() and FetchContent_Populate() commands can
6156 be used. These lack the richer features provided by
6157 FetchContent_MakeAvailable() though, so their direct use should be con‐
6158 sidered a last resort. The typical pattern of such custom steps looks
6159 like this:
6160 # NOTE: Where possible, prefer to use FetchContent_MakeAvailable()
6162 # instead of custom logic like this
6163 # Check if population has already been performed
6165 FetchContent_GetProperties(depname)
6166 if(NOT depname_POPULATED)
6167 # Fetch the content using previously declared details
6168 FetchContent_Populate(depname)
6169 # Set custom variables, policies, etc.
6171 # ...
6172 # Bring the populated content into the build
6174 add_subdirectory(${depname_SOURCE_DIR} ${depname_BINARY_DIR})
6175 endif()
6176 The FetchContent module also supports defining and populating content
6178 in a single call, with no check for whether the content has been popu‐
6179 lated elsewhere already. This should not be done in projects, but may
6180 be appropriate for populating content in CMake's script mode. See
6181 FetchContent_Populate() for details.
6182 Commands
6184 FetchContent_Declare
6185 FetchContent_Declare(<name> <contentOptions>...)
6187 The FetchContent_Declare() function records the options that de‐
6189 scribe how to populate the specified content. If such details
6190 have already been recorded earlier in this project (regardless
6191 of where in the project hierarchy), this and all later calls for
6192 the same content <name> are ignored. This "first to record,
6193 wins" approach is what allows hierarchical projects to have par‐
6194 ent projects override content details of child projects.
6195 The content <name> can be any string without spaces, but good
6197 practice would be to use only letters, numbers and underscores.
6198 The name will be treated case-insensitively and it should be ob‐
6199 vious for the content it represents, often being the name of the
6200 child project or the value given to its top level project() com‐
6201 mand (if it is a CMake project). For well-known public
6202 projects, the name should generally be the official name of the
6203 project. Choosing an unusual name makes it unlikely that other
6204 projects needing that same content will use the same name, lead‐
6205 ing to the content being populated multiple times.
6206 The <contentOptions> can be any of the download, update or patch
6208 options that the ExternalProject_Add() command understands. The
6209 configure, build, install and test steps are explicitly disabled
6210 and therefore options related to them will be ignored. The
6211 SOURCE_SUBDIR option is an exception, see
6212 FetchContent_MakeAvailable() for details on how that affects be‐
6213 havior.
6214 In most cases, <contentOptions> will just be a couple of options
6216 defining the download method and method-specific details like a
6217 commit tag or archive hash. For example:
6218 FetchContent_Declare(
6220 googletest
6221 GIT_REPOSITORY https://github.com/google/googletest.git
6222 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
6223 )
6224 FetchContent_Declare(
6226 myCompanyIcons
6227 URL https://intranet.mycompany.com/assets/iconset_1.12.tar.gz
6228 URL_HASH MD5=5588a7b18261c20068beabfb4f530b87
6229 )
6230 FetchContent_Declare(
6232 myCompanyCertificates
6233 SVN_REPOSITORY svn+ssh://svn.mycompany.com/srv/svn/trunk/certs
6234 SVN_REVISION -r12345
6235 )
6236 Where contents are being fetched from a remote location and you
6238 do not control that server, it is advisable to use a hash for
6239 GIT_TAG rather than a branch or tag name. A commit hash is more
6240 secure and helps to confirm that the downloaded contents are
6241 what you expected.
6242 Changed in version 3.14: Commands for the download, update or
6244 patch steps can access the terminal. This may be needed for
6245 things like password prompts or real-time display of command
6246 progress.
6247 New in version 3.22: The CMAKE_TLS_VERIFY, CMAKE_TLS_CAINFO,
6250 CMAKE_NETRC and CMAKE_NETRC_FILE variables now provide the de‐
6251 faults for their corresponding content options, just like they
6252 do for ExternalProject_Add(). Previously, these variables were
6253 ignored by the FetchContent module.
6254 FetchContent_MakeAvailable
6257 New in version 3.14.
6258 FetchContent_MakeAvailable(<name1> [<name2>...])
6261 This command ensures that each of the named dependencies are
6263 populated and potentially added to the build by the time it re‐
6264 turns. It iterates over the list, and for each dependency, the
6265 following logic is applied:
6266 • If the dependency has already been populated earlier in this
6268 run, set the <lowercaseName>_POPULATED, <lowercase‐
6269 Name>_SOURCE_DIR and <lowercaseName>_BINARY_DIR variables in
6270 the same way as a call to FetchContent_GetProperties(), then
6271 skip the remaining steps below and move on to the next depen‐
6272 dency in the list.
6273 • Call FetchContent_Populate() to populate the dependency using
6275 the details recorded by an earlier call to
6276 FetchContent_Declare(). Halt with a fatal error if no such
6277 details have been recorded.
6278 FETCHCONTENT_SOURCE_DIR_<uppercaseName> can be used to over‐
6279 ride the declared details and use content provided at the
6280 specified location instead.
6281 • If the top directory of the populated content contains a
6283 CMakeLists.txt file, call add_subdirectory() to add it to the
6284 main build. It is not an error for there to be no CMake‐
6285 Lists.txt file, which allows the command to be used for depen‐
6286 dencies that make downloaded content available at a known lo‐
6287 cation, but which do not need or support being added directly
6288 to the build.
6289 New in version 3.18: The SOURCE_SUBDIR option can be given in
6291 the declared details to look somewhere below the top directory
6292 instead (i.e. the same way that SOURCE_SUBDIR is used by the
6293 ExternalProject_Add() command). The path provided with
6294 SOURCE_SUBDIR must be relative and will be treated as relative
6295 to the top directory. It can also point to a directory that
6296 does not contain a CMakeLists.txt file or even to a directory
6297 that doesn't exist. This can be used to avoid adding a
6298 project that contains a CMakeLists.txt file in its top direc‐
6299 tory.
6300 Projects should aim to declare the details of all dependencies
6303 they might use before they call FetchContent_MakeAvailable() for
6304 any of them. This ensures that if any of the dependencies are
6305 also sub-dependencies of one or more of the others, the main
6306 project still controls the details that will be used (because it
6307 will declare them first before the dependencies get a chance
6308 to). In the following code samples, assume that the uses_other
6309 dependency also uses FetchContent to add the other dependency
6310 internally:
6311 # WRONG: Should declare all details first
6313 FetchContent_Declare(uses_other ...)
6314 FetchContent_MakeAvailable(uses_other)
6315 FetchContent_Declare(other ...) # Will be ignored, uses_other beat us to it
6317 FetchContent_MakeAvailable(other) # Would use details declared by uses_other
6318 # CORRECT: All details declared first, so they will take priority
6320 FetchContent_Declare(uses_other ...)
6321 FetchContent_Declare(other ...)
6322 FetchContent_MakeAvailable(uses_other other)
6323 FetchContent_Populate
6325 NOTE:
6326 Where possible, prefer to use FetchContent_MakeAvailable()
6327 instead of implementing population manually with this com‐
6328 mand.
6329 FetchContent_Populate(<name>)
6331 In most cases, the only argument given to FetchContent_Popu‐
6333 late() is the <name>. When used this way, the command assumes
6334 the content details have been recorded by an earlier call to
6335 FetchContent_Declare(). The details are stored in a global
6336 property, so they are unaffected by things like variable or di‐
6337 rectory scope. Therefore, it doesn't matter where in the
6338 project the details were previously declared, as long as they
6339 have been declared before the call to FetchContent_Populate().
6340 Those saved details are then used to construct a call to Exter‐
6341 nalProject_Add() in a private sub-build to perform the content
6342 population immediately. The implementation of ExternalPro‐
6343 ject_Add() ensures that if the content has already been popu‐
6344 lated in a previous CMake run, that content will be reused
6345 rather than repopulating them again. For the common case where
6346 population involves downloading content, the cost of the down‐
6347 load is only paid once.
6348 An internal global property records when a particular content
6350 population request has been processed. If FetchContent_Popu‐
6351 late() is called more than once for the same content name within
6352 a configure run, the second call will halt with an error.
6353 Projects can and should check whether content population has al‐
6354 ready been processed with the FetchContent_GetProperties() com‐
6355 mand before calling FetchContent_Populate().
6356 FetchContent_Populate() will set three variables in the scope of
6358 the caller:
6359 <lowercaseName>_POPULATED
6361 This will always be set to TRUE by the call.
6362 <lowercaseName>_SOURCE_DIR
6364 The location where the populated content can be found
6365 upon return.
6366 <lowercaseName>_BINARY_DIR
6368 A directory intended for use as a corresponding build di‐
6369 rectory.
6370 The main use case for the <lowercaseName>_SOURCE_DIR and <lower‐
6372 caseName>_BINARY_DIR variables is to call add_subdirectory() im‐
6373 mediately after population:
6374 FetchContent_Populate(FooBar)
6376 add_subdirectory(${foobar_SOURCE_DIR} ${foobar_BINARY_DIR})
6377 The values of the three variables can also be retrieved from
6379 anywhere in the project hierarchy using the
6380 FetchContent_GetProperties() command.
6381 The FetchContent_Populate() command also supports a syntax al‐
6383 lowing the content details to be specified directly rather than
6384 using any saved details. This is more low-level and use of this
6385 form is generally to be avoided in favor of using saved content
6386 details as outlined above. Nevertheless, in certain situations
6387 it can be useful to invoke the content population as an isolated
6388 operation (typically as part of implementing some other higher
6389 level feature or when using CMake in script mode):
6390 FetchContent_Populate(
6392 <name>
6393 [QUIET]
6394 [SUBBUILD_DIR <subBuildDir>]
6395 [SOURCE_DIR <srcDir>]
6396 [BINARY_DIR <binDir>]
6397 ...
6398 )
6399 This form has a number of key differences to that where only
6401 <name> is provided:
6402 • All required population details are assumed to have been pro‐
6404 vided directly in the call to FetchContent_Populate(). Any
6405 saved details for <name> are ignored.
6406 • No check is made for whether content for <name> has already
6408 been populated.
6409 • No global property is set to record that the population has
6411 occurred.
6412 • No global properties record the source or binary directories
6414 used for the populated content.
6415 • The FETCHCONTENT_FULLY_DISCONNECTED and FETCHCONTENT_UP‐
6417 DATES_DISCONNECTED cache variables are ignored.
6418 The <lowercaseName>_SOURCE_DIR and <lowercaseName>_BINARY_DIR
6420 variables are still returned to the caller, but since these lo‐
6421 cations are not stored as global properties when this form is
6422 used, they are only available to the calling scope and below
6423 rather than the entire project hierarchy. No <lowercase‐
6424 Name>_POPULATED variable is set in the caller's scope with this
6425 form.
6426 The supported options for FetchContent_Populate() are the same
6428 as those for FetchContent_Declare(). Those few options shown
6429 just above are either specific to FetchContent_Populate() or
6430 their behavior is slightly modified from how ExternalPro‐
6431 ject_Add() treats them:
6432 QUIET The QUIET option can be given to hide the output associ‐
6434 ated with populating the specified content. If the popu‐
6435 lation fails, the output will be shown regardless of
6436 whether this option was given or not so that the cause of
6437 the failure can be diagnosed. The global FETCHCON‐
6438 TENT_QUIET cache variable has no effect on FetchCon‐
6439 tent_Populate() calls where the content details are pro‐
6440 vided directly.
6441 SUBBUILD_DIR
6443 The SUBBUILD_DIR argument can be provided to change the
6444 location of the sub-build created to perform the popula‐
6445 tion. The default value is ${CMAKE_CURRENT_BI‐
6446 NARY_DIR}/<lowercaseName>-subbuild and it would be un‐
6447 usual to need to override this default. If a relative
6448 path is specified, it will be interpreted as relative to
6449 CMAKE_CURRENT_BINARY_DIR. This option should not be con‐
6450 fused with the SOURCE_SUBDIR option which only affects
6451 the FetchContent_MakeAvailable() command.
6452 SOURCE_DIR, BINARY_DIR
6454 The SOURCE_DIR and BINARY_DIR arguments are supported by
6455 ExternalProject_Add(), but different default values are
6456 used by FetchContent_Populate(). SOURCE_DIR defaults to
6457 ${CMAKE_CURRENT_BINARY_DIR}/<lowercaseName>-src and BI‐
6458 NARY_DIR defaults to ${CMAKE_CURRENT_BINARY_DIR}/<lower‐
6459 caseName>-build. If a relative path is specified, it
6460 will be interpreted as relative to CMAKE_CURRENT_BI‐
6461 NARY_DIR.
6462 In addition to the above explicit options, any other unrecog‐
6464 nized options are passed through unmodified to ExternalPro‐
6465 ject_Add() to perform the download, patch and update steps. The
6466 following options are explicitly prohibited (they are disabled
6467 by the FetchContent_Populate() command):
6468 • CONFIGURE_COMMAND
6470 • BUILD_COMMAND
6472 • INSTALL_COMMAND
6474 • TEST_COMMAND
6476 If using FetchContent_Populate() within CMake's script mode, be
6478 aware that the implementation sets up a sub-build which there‐
6479 fore requires a CMake generator and build tool to be available.
6480 If these cannot be found by default, then the CMAKE_GENERATOR
6481 and/or CMAKE_MAKE_PROGRAM variables will need to be set appro‐
6482 priately on the command line invoking the script.
6483 New in version 3.18: Added support for the DOWNLOAD_NO_EXTRACT
6485 option.
6486 FetchContent_GetProperties
6489 When using saved content details, a call to
6490 FetchContent_MakeAvailable() or FetchContent_Populate() records
6491 information in global properties which can be queried at any
6492 time. This information includes the source and binary directo‐
6493 ries associated with the content and also whether or not the
6494 content population has been processed during the current config‐
6495 ure run.
6496 FetchContent_GetProperties(
6498 <name>
6499 [SOURCE_DIR <srcDirVar>]
6500 [BINARY_DIR <binDirVar>]
6501 [POPULATED <doneVar>]
6502 )
6503 The SOURCE_DIR, BINARY_DIR and POPULATED options can be used to
6505 specify which properties should be retrieved. Each option ac‐
6506 cepts a value which is the name of the variable in which to
6507 store that property. Most of the time though, only <name> is
6508 given, in which case the call will then set the same variables
6509 as a call to FetchContent_MakeAvailable(name) or
6510 FetchContent_Populate(name).
6511 This command is rarely needed when using
6513 FetchContent_MakeAvailable(). It is more commonly used as part
6514 of implementing the following pattern with
6515 FetchContent_Populate(), which ensures that the relevant vari‐
6516 ables will always be defined regardless of whether or not the
6517 population has been performed elsewhere in the project already:
6518 # Check if population has already been performed
6520 FetchContent_GetProperties(depname)
6521 if(NOT depname_POPULATED)
6522 # Fetch the content using previously declared details
6523 FetchContent_Populate(depname)
6524 # Set custom variables, policies, etc.
6526 # ...
6527 # Bring the populated content into the build
6529 add_subdirectory(${depname_SOURCE_DIR} ${depname_BINARY_DIR})
6530 endif()
6531 Variables
6533 A number of cache variables can influence the behavior where details
6534 from a FetchContent_Declare() call are used to populate content. The
6535 variables are all intended for the developer to customize behavior and
6536 should not normally be set by the project.
6537 FETCHCONTENT_BASE_DIR
6539 In most cases, the saved details do not specify any options re‐
6540 lating to the directories to use for the internal sub-build, fi‐
6541 nal source and build areas. It is generally best to leave these
6542 decisions up to the FetchContent module to handle on the
6543 project's behalf. The FETCHCONTENT_BASE_DIR cache variable con‐
6544 trols the point under which all content population directories
6545 are collected, but in most cases, developers would not need to
6546 change this. The default location is ${CMAKE_BINARY_DIR}/_deps,
6547 but if developers change this value, they should aim to keep the
6548 path short and just below the top level of the build tree to
6549 avoid running into path length problems on Windows.
6550 FETCHCONTENT_QUIET
6552 The logging output during population can be quite verbose, mak‐
6553 ing the configure stage quite noisy. This cache option (ON by
6554 default) hides all population output unless an error is encoun‐
6555 tered. If experiencing problems with hung downloads, temporar‐
6556 ily switching this option off may help diagnose which content
6557 population is causing the issue.
6558 FETCHCONTENT_FULLY_DISCONNECTED
6560 When this option is enabled, no attempt is made to download or
6561 update any content. It is assumed that all content has already
6562 been populated in a previous run or the source directories have
6563 been pointed at existing contents the developer has provided
6564 manually (using options described further below). When the de‐
6565 veloper knows that no changes have been made to any content de‐
6566 tails, turning this option ON can significantly speed up the
6567 configure stage. It is OFF by default.
6568 FETCHCONTENT_UPDATES_DISCONNECTED
6570 This is a less severe download/update control compared to
6571 FETCHCONTENT_FULLY_DISCONNECTED. Instead of bypassing all down‐
6572 load and update logic, FETCHCONTENT_UPDATES_DISCONNECTED only
6573 disables the update stage. Therefore, if content has not been
6574 downloaded previously, it will still be downloaded when this op‐
6575 tion is enabled. This can speed up the configure stage, but not
6576 as much as FETCHCONTENT_FULLY_DISCONNECTED. It is OFF by de‐
6577 fault.
6578 In addition to the above cache variables, the following cache variables
6580 are also defined for each content name:
6581 FETCHCONTENT_SOURCE_DIR_<uppercaseName>
6583 If this is set, no download or update steps are performed for
6584 the specified content and the <lowercaseName>_SOURCE_DIR vari‐
6585 able returned to the caller is pointed at this location. This
6586 gives developers a way to have a separate checkout of the con‐
6587 tent that they can modify freely without interference from the
6588 build. The build simply uses that existing source, but it still
6589 defines <lowercaseName>_BINARY_DIR to point inside its own build
6590 area. Developers are strongly encouraged to use this mechanism
6591 rather than editing the sources populated in the default loca‐
6592 tion, as changes to sources in the default location can be lost
6593 when content population details are changed by the project.
6594 FETCHCONTENT_UPDATES_DISCONNECTED_<uppercaseName>
6596 This is the per-content equivalent of
6597 FETCHCONTENT_UPDATES_DISCONNECTED. If the global option or this
6598 option is ON, then updates will be disabled for the named con‐
6599 tent. Disabling updates for individual content can be useful
6600 for content whose details rarely change, while still leaving
6601 other frequently changing content with updates enabled.
6602 Examples
6604 This first fairly straightforward example ensures that some popular
6605 testing frameworks are available to the main build:
6606 include(FetchContent)
6608 FetchContent_Declare(
6609 googletest
6610 GIT_REPOSITORY https://github.com/google/googletest.git
6611 GIT_TAG 703bd9caab50b139428cea1aaff9974ebee5742e # release-1.10.0
6612 )
6613 FetchContent_Declare(
6614 Catch2
6615 GIT_REPOSITORY https://github.com/catchorg/Catch2.git
6616 GIT_TAG de6fe184a9ac1a06895cdd1c9b437f0a0bdf14ad # v2.13.4
6617 )
6618 # After the following call, the CMake targets defined by googletest and
6620 # Catch2 will be available to the rest of the build
6621 FetchContent_MakeAvailable(googletest Catch2)
6622 If the sub-project's CMakeLists.txt file is not at the top level of its
6624 source tree, the SOURCE_SUBDIR option can be used to tell FetchContent
6625 where to find it. The following example shows how to use that option
6626 and it also sets a variable which is meaningful to the subproject be‐
6627 fore pulling it into the main build:
6628 include(FetchContent)
6630 FetchContent_Declare(
6631 protobuf
6632 GIT_REPOSITORY https://github.com/protocolbuffers/protobuf.git
6633 GIT_TAG ae50d9b9902526efd6c7a1907d09739f959c6297 # v3.15.0
6634 SOURCE_SUBDIR cmake
6635 )
6636 set(protobuf_BUILD_TESTS OFF)
6637 FetchContent_MakeAvailable(protobuf)
6638 In more complex project hierarchies, the dependency relationships can
6640 be more complicated. Consider a hierarchy where projA is the top level
6641 project and it depends directly on projects projB and projC. Both
6642 projB and projC can be built standalone and they also both depend on
6643 another project projD. projB additionally depends on projE. This ex‐
6644 ample assumes that all five projects are available on a company git
6645 server. The CMakeLists.txt of each project might have sections like
6646 the following:
6647 projA:
6649 include(FetchContent)
6651 FetchContent_Declare(
6652 projB
6653 GIT_REPOSITORY git@mycompany.com:git/projB.git
6654 GIT_TAG 4a89dc7e24ff212a7b5167bef7ab079d
6655 )
6656 FetchContent_Declare(
6657 projC
6658 GIT_REPOSITORY git@mycompany.com:git/projC.git
6659 GIT_TAG 4ad4016bd1d8d5412d135cf8ceea1bb9
6660 )
6661 FetchContent_Declare(
6662 projD
6663 GIT_REPOSITORY git@mycompany.com:git/projD.git
6664 GIT_TAG origin/integrationBranch
6665 )
6666 FetchContent_Declare(
6667 projE
6668 GIT_REPOSITORY git@mycompany.com:git/projE.git
6669 GIT_TAG v2.3-rc1
6670 )
6671 # Order is important, see notes in the discussion further below
6673 FetchContent_MakeAvailable(projD projB projC)
6674 projB:
6676 include(FetchContent)
6678 FetchContent_Declare(
6679 projD
6680 GIT_REPOSITORY git@mycompany.com:git/projD.git
6681 GIT_TAG 20b415f9034bbd2a2e8216e9a5c9e632
6682 )
6683 FetchContent_Declare(
6684 projE
6685 GIT_REPOSITORY git@mycompany.com:git/projE.git
6686 GIT_TAG 68e20f674a48be38d60e129f600faf7d
6687 )
6688 FetchContent_MakeAvailable(projD projE)
6690 projC:
6692 include(FetchContent)
6694 FetchContent_Declare(
6695 projD
6696 GIT_REPOSITORY git@mycompany.com:git/projD.git
6697 GIT_TAG 7d9a17ad2c962aa13e2fbb8043fb6b8a
6698 )
6699 # This particular version of projD requires workarounds
6701 FetchContent_GetProperties(projD)
6702 if(NOT projd_POPULATED)
6703 FetchContent_Populate(projD)
6704 # Copy an additional/replacement file into the populated source
6706 file(COPY someFile.c DESTINATION ${projd_SOURCE_DIR}/src)
6707 add_subdirectory(${projd_SOURCE_DIR} ${projd_BINARY_DIR})
6709 endif()
6710 A few key points should be noted in the above:
6712 • projB and projC define different content details for projD, but projA
6714 also defines a set of content details for projD. Because projA will
6715 define them first, the details from projB and projC will not be used.
6716 The override details defined by projA are not required to match ei‐
6717 ther of those from projB or projC, but it is up to the higher level
6718 project to ensure that the details it does define still make sense
6719 for the child projects.
6720 • In the projA call to FetchContent_MakeAvailable(), projD is listed
6722 ahead of projB and projC to ensure that projA is in control of how
6723 projD is populated.
6724 • While projA defines content details for projE, it does not need to
6726 explicitly call FetchContent_MakeAvailable(projE) or FetchCon‐
6727 tent_Populate(projD) itself. Instead, it leaves that to the child
6728 projB. For higher level projects, it is often enough to just define
6729 the override content details and leave the actual population to the
6730 child projects. This saves repeating the same thing at each level of
6731 the project hierarchy unnecessarily.
6732 Projects don't always need to add the populated content to the build.
6734 Sometimes the project just wants to make the downloaded content avail‐
6735 able at a predictable location. The next example ensures that a set of
6736 standard company toolchain files (and potentially even the toolchain
6737 binaries themselves) is available early enough to be used for that same
6738 build.
6739 cmake_minimum_required(VERSION 3.14)
6741 include(FetchContent)
6743 FetchContent_Declare(
6744 mycom_toolchains
6745 URL https://intranet.mycompany.com//toolchains_1.3.2.tar.gz
6746 )
6747 FetchContent_MakeAvailable(mycom_toolchains)
6748 project(CrossCompileExample)
6750 The project could be configured to use one of the downloaded toolchains
6752 like so:
6753 cmake -DCMAKE_TOOLCHAIN_FILE=_deps/mycom_toolchains-src/toolchain_arm.cmake /path/to/src
6755 When CMake processes the CMakeLists.txt file, it will download and un‐
6757 pack the tarball into _deps/mycompany_toolchains-src relative to the
6758 build directory. The CMAKE_TOOLCHAIN_FILE variable is not used until
6759 the project() command is reached, at which point CMake looks for the
6760 named toolchain file relative to the build directory. Because the tar‐
6761 ball has already been downloaded and unpacked by then, the toolchain
6762 file will be in place, even the very first time that cmake is run in
6763 the build directory.
6764 Lastly, the following example demonstrates how one might download and
6766 unpack a firmware tarball using CMake's script mode. The call to
6767 FetchContent_Populate() specifies all the content details and the un‐
6768 packed firmware will be placed in a firmware directory below the cur‐
6769 rent working directory.
6770 getFirmware.cmake:
6772 # NOTE: Intended to be run in script mode with cmake -P
6774 include(FetchContent)
6775 FetchContent_Populate(
6776 firmware
6777 URL https://mycompany.com/assets/firmware-1.23-arm.tar.gz
6778 URL_HASH MD5=68247684da89b608d466253762b0ff11
6779 SOURCE_DIR firmware
6780 )
6781 FindPackageHandleStandardArgs
6783 This module provides functions intended to be used in Find Modules im‐
6784 plementing find_package(<PackageName>) calls.
6785 find_package_handle_standard_args
6787 This command handles the REQUIRED, QUIET and version-related ar‐
6788 guments of find_package(). It also sets the <PackageName>_FOUND
6789 variable. The package is considered found if all variables
6790 listed contain valid results, e.g. valid filepaths.
6791 There are two signatures:
6793 find_package_handle_standard_args(<PackageName>
6795 (DEFAULT_MSG|<custom-failure-message>)
6796 <required-var>...
6797 )
6798 find_package_handle_standard_args(<PackageName>
6800 [FOUND_VAR <result-var>]
6801 [REQUIRED_VARS <required-var>...]
6802 [VERSION_VAR <version-var>]
6803 [HANDLE_VERSION_RANGE]
6804 [HANDLE_COMPONENTS]
6805 [CONFIG_MODE]
6806 [NAME_MISMATCHED]
6807 [REASON_FAILURE_MESSAGE <reason-failure-message>]
6808 [FAIL_MESSAGE <custom-failure-message>]
6809 )
6810 The <PackageName>_FOUND variable will be set to TRUE if all the
6812 variables <required-var>... are valid and any optional con‐
6813 straints are satisfied, and FALSE otherwise. A success or fail‐
6814 ure message may be displayed based on the results and on whether
6815 the REQUIRED and/or QUIET option was given to the find_package()
6816 call.
6817 The options are:
6819 (DEFAULT_MSG|<custom-failure-message>)
6821 In the simple signature this specifies the failure mes‐
6822 sage. Use DEFAULT_MSG to ask for a default message to be
6823 computed (recommended). Not valid in the full signature.
6824 FOUND_VAR <result-var>
6826 Deprecated since version 3.3.
6827 Specifies either <PackageName>_FOUND or <PACKAGE‐
6830 NAME>_FOUND as the result variable. This exists only for
6831 compatibility with older versions of CMake and is now ig‐
6832 nored. Result variables of both names are always set for
6833 compatibility.
6834 REQUIRED_VARS <required-var>...
6836 Specify the variables which are required for this pack‐
6837 age. These may be named in the generated failure message
6838 asking the user to set the missing variable values.
6839 Therefore these should typically be cache entries such as
6840 FOO_LIBRARY and not output variables like FOO_LIBRARIES.
6841 Changed in version 3.18: If HANDLE_COMPONENTS is speci‐
6843 fied, this option can be omitted.
6844 VERSION_VAR <version-var>
6847 Specify the name of a variable that holds the version of
6848 the package that has been found. This version will be
6849 checked against the (potentially) specified required ver‐
6850 sion given to the find_package() call, including its EX‐
6851 ACT option. The default messages include information
6852 about the required version and the version which has been
6853 actually found, both if the version is ok or not.
6854 HANDLE_VERSION_RANGE
6856 New in version 3.19.
6857 Enable handling of a version range, if one is specified.
6860 Without this option, a developer warning will be dis‐
6861 played if a version range is specified.
6862 HANDLE_COMPONENTS
6864 Enable handling of package components. In this case, the
6865 command will report which components have been found and
6866 which are missing, and the <PackageName>_FOUND variable
6867 will be set to FALSE if any of the required components
6868 (i.e. not the ones listed after the OPTIONAL_COMPONENTS
6869 option of find_package()) are missing.
6870 CONFIG_MODE
6872 Specify that the calling find module is a wrapper around
6873 a call to find_package(<PackageName> NO_MODULE). This
6874 implies a VERSION_VAR value of <PackageName>_VERSION.
6875 The command will automatically check whether the package
6876 configuration file was found.
6877 REASON_FAILURE_MESSAGE <reason-failure-message>
6879 New in version 3.16.
6880 Specify a custom message of the reason for the failure
6883 which will be appended to the default generated message.
6884 FAIL_MESSAGE <custom-failure-message>
6886 Specify a custom failure message instead of using the de‐
6887 fault generated message. Not recommended.
6888 NAME_MISMATCHED
6890 New in version 3.17.
6891 Indicate that the <PackageName> does not match
6894 ${CMAKE_FIND_PACKAGE_NAME}. This is usually a mistake and
6895 raises a warning, but it may be intentional for usage of
6896 the command for components of a larger package.
6897 Example for the simple signature:
6899 find_package_handle_standard_args(LibXml2 DEFAULT_MSG
6901 LIBXML2_LIBRARY LIBXML2_INCLUDE_DIR)
6902 The LibXml2 package is considered to be found if both LIBXML2_LIBRARY
6904 and LIBXML2_INCLUDE_DIR are valid. Then also LibXml2_FOUND is set to
6905 TRUE. If it is not found and REQUIRED was used, it fails with a mes‐
6906 sage(FATAL_ERROR), independent whether QUIET was used or not. If it is
6907 found, success will be reported, including the content of the first
6908 <required-var>. On repeated CMake runs, the same message will not be
6909 printed again.
6910 NOTE:
6912 If <PackageName> does not match CMAKE_FIND_PACKAGE_NAME for the
6913 calling module, a warning that there is a mismatch is given. The
6914 FPHSA_NAME_MISMATCHED variable may be set to bypass the warning if
6915 using the old signature and the NAME_MISMATCHED argument using the
6916 new signature. To avoid forcing the caller to require newer versions
6917 of CMake for usage, the variable's value will be used if defined
6918 when the NAME_MISMATCHED argument is not passed for the new signa‐
6919 ture (but using both is an error)..
6920 Example for the full signature:
6922 find_package_handle_standard_args(LibArchive
6924 REQUIRED_VARS LibArchive_LIBRARY LibArchive_INCLUDE_DIR
6925 VERSION_VAR LibArchive_VERSION)
6926 In this case, the LibArchive package is considered to be found if both
6928 LibArchive_LIBRARY and LibArchive_INCLUDE_DIR are valid. Also the ver‐
6929 sion of LibArchive will be checked by using the version contained in
6930 LibArchive_VERSION. Since no FAIL_MESSAGE is given, the default mes‐
6931 sages will be printed.
6932 Another example for the full signature:
6934 find_package(Automoc4 QUIET NO_MODULE HINTS /opt/automoc4)
6936 find_package_handle_standard_args(Automoc4 CONFIG_MODE)
6937 In this case, a FindAutmoc4.cmake module wraps a call to find_pack‐
6939 age(Automoc4 NO_MODULE) and adds an additional search directory for au‐
6940 tomoc4. Then the call to find_package_handle_standard_args produces a
6941 proper success/failure message.
6942 find_package_check_version
6944 New in version 3.19.
6945 Helper function which can be used to check if a <version> is
6948 valid against version-related arguments of find_package().
6949 find_package_check_version(<version> <result-var>
6951 [HANDLE_VERSION_RANGE]
6952 [RESULT_MESSAGE_VARIABLE <message-var>]
6953 )
6954 The <result-var> will hold a boolean value giving the result of
6956 the check.
6957 The options are:
6959 HANDLE_VERSION_RANGE
6961 Enable handling of a version range, if one is specified.
6962 Without this option, a developer warning will be dis‐
6963 played if a version range is specified.
6964 RESULT_MESSAGE_VARIABLE <message-var>
6966 Specify a variable to get back a message describing the
6967 result of the check.
6968 Example for the usage:
6970 find_package_check_version(1.2.3 result HANDLE_VERSION_RANGE
6972 RESULT_MESSAGE_VARIABLE reason)
6973 if (result)
6974 message (STATUS "${reason}")
6975 else()
6976 message (FATAL_ERROR "${reason}")
6977 endif()
6978 FindPackageMessage
6980 find_package_message(<name> "message for user" "find result details")
6981 This function is intended to be used in FindXXX.cmake modules files.
6983 It will print a message once for each unique find result. This is use‐
6984 ful for telling the user where a package was found. The first argument
6985 specifies the name (XXX) of the package. The second argument specifies
6986 the message to display. The third argument lists details about the
6987 find result so that if they change the message will be displayed again.
6988 The macro also obeys the QUIET argument to the find_package command.
6989 Example:
6991 if(X11_FOUND)
6993 find_package_message(X11 "Found X11: ${X11_X11_LIB}"
6994 "[${X11_X11_LIB}][${X11_INCLUDE_DIR}]")
6995 else()
6996 ...
6997 endif()
6998 FortranCInterface
7000 Fortran/C Interface Detection
7001 This module automatically detects the API by which C and Fortran lan‐
7003 guages interact.
7004 Module Variables
7006 Variables that indicate if the mangling is found:
7007 FortranCInterface_GLOBAL_FOUND
7009 Global subroutines and functions.
7010 FortranCInterface_MODULE_FOUND
7012 Module subroutines and functions (declared by "MODULE PROCE‐
7013 DURE").
7014 This module also provides the following variables to specify the de‐
7016 tected mangling, though a typical use case does not need to reference
7017 them and can use the Module Functions below.
7018 FortranCInterface_GLOBAL_PREFIX
7020 Prefix for a global symbol without an underscore.
7021 FortranCInterface_GLOBAL_SUFFIX
7023 Suffix for a global symbol without an underscore.
7024 FortranCInterface_GLOBAL_CASE
7026 The case for a global symbol without an underscore, either UPPER
7027 or LOWER.
7028 FortranCInterface_GLOBAL__PREFIX
7030 Prefix for a global symbol with an underscore.
7031 FortranCInterface_GLOBAL__SUFFIX
7033 Suffix for a global symbol with an underscore.
7034 FortranCInterface_GLOBAL__CASE
7036 The case for a global symbol with an underscore, either UPPER or
7037 LOWER.
7038 FortranCInterface_MODULE_PREFIX
7040 Prefix for a module symbol without an underscore.
7041 FortranCInterface_MODULE_MIDDLE
7043 Middle of a module symbol without an underscore that appears be‐
7044 tween the name of the module and the name of the symbol.
7045 FortranCInterface_MODULE_SUFFIX
7047 Suffix for a module symbol without an underscore.
7048 FortranCInterface_MODULE_CASE
7050 The case for a module symbol without an underscore, either UPPER
7051 or LOWER.
7052 FortranCInterface_MODULE__PREFIX
7054 Prefix for a module symbol with an underscore.
7055 FortranCInterface_MODULE__MIDDLE
7057 Middle of a module symbol with an underscore that appears be‐
7058 tween the name of the module and the name of the symbol.
7059 FortranCInterface_MODULE__SUFFIX
7061 Suffix for a module symbol with an underscore.
7062 FortranCInterface_MODULE__CASE
7064 The case for a module symbol with an underscore, either UPPER or
7065 LOWER.
7066 Module Functions
7068 FortranCInterface_HEADER
7069 The FortranCInterface_HEADER function is provided to generate a
7070 C header file containing macros to mangle symbol names:
7071 FortranCInterface_HEADER(<file>
7073 [MACRO_NAMESPACE <macro-ns>]
7074 [SYMBOL_NAMESPACE <ns>]
7075 [SYMBOLS [<module>:]<function> ...])
7076 It generates in <file> definitions of the following macros:
7078 #define FortranCInterface_GLOBAL (name,NAME) ...
7080 #define FortranCInterface_GLOBAL_(name,NAME) ...
7081 #define FortranCInterface_MODULE (mod,name, MOD,NAME) ...
7082 #define FortranCInterface_MODULE_(mod,name, MOD,NAME) ...
7083 These macros mangle four categories of Fortran symbols, respec‐
7085 tively:
7086 • Global symbols without '_': call mysub()
7088 • Global symbols with '_' : call my_sub()
7090 • Module symbols without '_': use mymod; call mysub()
7092 • Module symbols with '_' : use mymod; call my_sub()
7094 If mangling for a category is not known, its macro is left unde‐
7096 fined. All macros require raw names in both lower case and up‐
7097 per case.
7098 The options are:
7100 MACRO_NAMESPACE
7102 Replace the default FortranCInterface_ prefix with a
7103 given namespace <macro-ns>.
7104 SYMBOLS
7106 List symbols to mangle automatically with C preprocessor
7107 definitions:
7108 <function> ==> #define <ns><function> ...
7110 <module>:<function> ==> #define <ns><module>_<function> ...
7111 If the mangling for some symbol is not known then no pre‐
7113 processor definition is created, and a warning is dis‐
7114 played.
7115 SYMBOL_NAMESPACE
7117 Prefix all preprocessor definitions generated by the SYM‐
7118 BOLS option with a given namespace <ns>.
7119 FortranCInterface_VERIFY
7121 The FortranCInterface_VERIFY function is provided to verify that
7122 the Fortran and C/C++ compilers work together:
7123 FortranCInterface_VERIFY([CXX] [QUIET])
7125 It tests whether a simple test executable using Fortran and C
7127 (and C++ when the CXX option is given) compiles and links suc‐
7128 cessfully. The result is stored in the cache entry FortranCIn‐
7129 terface_VERIFIED_C (or FortranCInterface_VERIFIED_CXX if CXX is
7130 given) as a boolean. If the check fails and QUIET is not given
7131 the function terminates with a fatal error message describing
7132 the problem. The purpose of this check is to stop a build early
7133 for incompatible compiler combinations. The test is built in
7134 the Release configuration.
7135 Example Usage
7137 include(FortranCInterface)
7138 FortranCInterface_HEADER(FC.h MACRO_NAMESPACE "FC_")
7139 This creates a "FC.h" header that defines mangling macros FC_GLOBAL(),
7141 FC_GLOBAL_(), FC_MODULE(), and FC_MODULE_().
7142 include(FortranCInterface)
7144 FortranCInterface_HEADER(FCMangle.h
7145 MACRO_NAMESPACE "FC_"
7146 SYMBOL_NAMESPACE "FC_"
7147 SYMBOLS mysub mymod:my_sub)
7148 This creates a "FCMangle.h" header that defines the same FC_*() man‐
7150 gling macros as the previous example plus preprocessor symbols FC_mysub
7151 and FC_mymod_my_sub.
7152 Additional Manglings
7154 FortranCInterface is aware of possible GLOBAL and MODULE manglings for
7155 many Fortran compilers, but it also provides an interface to specify
7156 new possible manglings. Set the variables:
7157 FortranCInterface_GLOBAL_SYMBOLS
7159 FortranCInterface_MODULE_SYMBOLS
7160 before including FortranCInterface to specify manglings of the symbols
7162 MySub, My_Sub, MyModule:MySub, and My_Module:My_Sub. For example, the
7163 code:
7164 set(FortranCInterface_GLOBAL_SYMBOLS mysub_ my_sub__ MYSUB_)
7166 # ^^^^^ ^^^^^^ ^^^^^
7167 set(FortranCInterface_MODULE_SYMBOLS
7168 __mymodule_MOD_mysub __my_module_MOD_my_sub)
7169 # ^^^^^^^^ ^^^^^ ^^^^^^^^^ ^^^^^^
7170 include(FortranCInterface)
7171 tells FortranCInterface to try given GLOBAL and MODULE manglings. (The
7173 carets point at raw symbol names for clarity in this example but are
7174 not needed.)
7175 GenerateExportHeader
7177 Function for generation of export macros for libraries
7178 This module provides the function GENERATE_EXPORT_HEADER().
7180 New in version 3.12: Added support for C projects. Previous versions
7182 supported C++ project only.
7183 The GENERATE_EXPORT_HEADER function can be used to generate a file
7186 suitable for preprocessor inclusion which contains EXPORT macros to be
7187 used in library classes:
7188 GENERATE_EXPORT_HEADER( LIBRARY_TARGET
7190 [BASE_NAME <base_name>]
7191 [EXPORT_MACRO_NAME <export_macro_name>]
7192 [EXPORT_FILE_NAME <export_file_name>]
7193 [DEPRECATED_MACRO_NAME <deprecated_macro_name>]
7194 [NO_EXPORT_MACRO_NAME <no_export_macro_name>]
7195 [INCLUDE_GUARD_NAME <include_guard_name>]
7196 [STATIC_DEFINE <static_define>]
7197 [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>]
7198 [DEFINE_NO_DEPRECATED]
7199 [PREFIX_NAME <prefix_name>]
7200 [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
7201 )
7202 The target properties CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HID‐
7204 DEN can be used to add the appropriate compile flags for targets. See
7205 the documentation of those target properties, and the convenience vari‐
7206 ables CMAKE_CXX_VISIBILITY_PRESET and CMAKE_VISIBILITY_INLINES_HIDDEN.
7207 By default GENERATE_EXPORT_HEADER() generates macro names in a file
7209 name determined by the name of the library. This means that in the
7210 simplest case, users of GenerateExportHeader will be equivalent to:
7211 set(CMAKE_CXX_VISIBILITY_PRESET hidden)
7213 set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
7214 add_library(somelib someclass.cpp)
7215 generate_export_header(somelib)
7216 install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR})
7217 install(FILES
7218 someclass.h
7219 ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${INCLUDE_INSTALL_DIR}
7220 )
7221 And in the ABI header files:
7223 #include "somelib_export.h"
7225 class SOMELIB_EXPORT SomeClass {
7226 ...
7227 };
7228 The CMake fragment will generate a file in the ${CMAKE_CURRENT_BI‐
7230 NARY_DIR} called somelib_export.h containing the macros SOMELIB_EXPORT,
7231 SOMELIB_NO_EXPORT, SOMELIB_DEPRECATED, SOMELIB_DEPRECATED_EXPORT and
7232 SOMELIB_DEPRECATED_NO_EXPORT. They will be followed by content taken
7233 from the variable specified by the CUSTOM_CONTENT_FROM_VARIABLE option,
7234 if any. The resulting file should be installed with other headers in
7235 the library.
7236 The BASE_NAME argument can be used to override the file name and the
7238 names used for the macros:
7239 add_library(somelib someclass.cpp)
7241 generate_export_header(somelib
7242 BASE_NAME other_name
7243 )
7244 Generates a file called other_name_export.h containing the macros
7246 OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT and OTHER_NAME_DEPRECATED etc.
7247 The BASE_NAME may be overridden by specifying other options in the
7249 function. For example:
7250 add_library(somelib someclass.cpp)
7252 generate_export_header(somelib
7253 EXPORT_MACRO_NAME OTHER_NAME_EXPORT
7254 )
7255 creates the macro OTHER_NAME_EXPORT instead of SOMELIB_EXPORT, but
7257 other macros and the generated file name is as default:
7258 add_library(somelib someclass.cpp)
7260 generate_export_header(somelib
7261 DEPRECATED_MACRO_NAME KDE_DEPRECATED
7262 )
7263 creates the macro KDE_DEPRECATED instead of SOMELIB_DEPRECATED.
7265 If LIBRARY_TARGET is a static library, macros are defined without val‐
7267 ues.
7268 If the same sources are used to create both a shared and a static li‐
7270 brary, the uppercased symbol ${BASE_NAME}_STATIC_DEFINE should be used
7271 when building the static library:
7272 add_library(shared_variant SHARED ${lib_SRCS})
7274 add_library(static_variant ${lib_SRCS})
7275 generate_export_header(shared_variant BASE_NAME libshared_and_static)
7276 set_target_properties(static_variant PROPERTIES
7277 COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)
7278 This will cause the export macros to expand to nothing when building
7280 the static library.
7281 If DEFINE_NO_DEPRECATED is specified, then a macro ${BASE_NAME}_NO_DEP‐
7283 RECATED will be defined This macro can be used to remove deprecated
7284 code from preprocessor output:
7285 option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE)
7287 if (EXCLUDE_DEPRECATED)
7288 set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED)
7289 endif()
7290 generate_export_header(somelib ${NO_BUILD_DEPRECATED})
7291 And then in somelib:
7293 class SOMELIB_EXPORT SomeClass
7295 {
7296 public:
7297 #ifndef SOMELIB_NO_DEPRECATED
7298 SOMELIB_DEPRECATED void oldMethod();
7299 #endif
7300 };
7301 #ifndef SOMELIB_NO_DEPRECATED
7303 void SomeClass::oldMethod() { }
7304 #endif
7305 If PREFIX_NAME is specified, the argument will be used as a prefix to
7307 all generated macros.
7308 For example:
7310 generate_export_header(somelib PREFIX_NAME VTK_)
7312 Generates the macros VTK_SOMELIB_EXPORT etc.
7314 New in version 3.1: Library target can be an OBJECT library.
7316 New in version 3.7: Added the CUSTOM_CONTENT_FROM_VARIABLE option.
7319 New in version 3.11: Added the INCLUDE_GUARD_NAME option.
7322 ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
7325 Deprecated since version 3.0: Set the target properties CXX_VISIBIL‐
7327 ITY_PRESET and VISIBILITY_INLINES_HIDDEN instead.
7328 The ADD_COMPILER_EXPORT_FLAGS function adds -fvisibility=hidden to
7331 CMAKE_CXX_FLAGS if supported, and is a no-op on Windows which does not
7332 need extra compiler flags for exporting support. You may optionally
7333 pass a single argument to ADD_COMPILER_EXPORT_FLAGS that will be popu‐
7334 lated with the CXX_FLAGS required to enable visibility support for the
7335 compiler/architecture in use.
7336 GetPrerequisites
7338 Deprecated since version 3.16: Use file(GET_RUNTIME_DEPENDENCIES) in‐
7339 stead.
7340 Functions to analyze and list executable file prerequisites.
7343 This module provides functions to list the .dll, .dylib or .so files
7345 that an executable or shared library file depends on. (Its prerequi‐
7346 sites.)
7347 It uses various tools to obtain the list of required shared library
7349 files:
7350 dumpbin (Windows)
7352 objdump (MinGW on Windows)
7353 ldd (Linux/Unix)
7354 otool (Mac OSX)
7355 Changed in version 3.16: The tool specified by CMAKE_OBJDUMP will be
7357 used, if set.
7358 The following functions are provided by this module:
7361 get_prerequisites
7363 list_prerequisites
7364 list_prerequisites_by_glob
7365 gp_append_unique
7366 is_file_executable
7367 gp_item_default_embedded_path
7368 (projects can override with gp_item_default_embedded_path_override)
7369 gp_resolve_item
7370 (projects can override with gp_resolve_item_override)
7371 gp_resolved_file_type
7372 (projects can override with gp_resolved_file_type_override)
7373 gp_file_type
7374 GET_PREREQUISITES(<target> <prerequisites_var> <exclude_system> <recurse>
7376 <exepath> <dirs> [<rpaths>])
7377 Get the list of shared library files required by <target>. The list in
7379 the variable named <prerequisites_var> should be empty on first entry
7380 to this function. On exit, <prerequisites_var> will contain the list
7381 of required shared library files.
7382 <target> is the full path to an executable file. <prerequisites_var>
7384 is the name of a CMake variable to contain the results. <exclude_sys‐
7385 tem> must be 0 or 1 indicating whether to include or exclude "system"
7386 prerequisites. If <recurse> is set to 1 all prerequisites will be
7387 found recursively, if set to 0 only direct prerequisites are listed.
7388 <exepath> is the path to the top level executable used for @exe‐
7389 cutable_path replacement on the Mac. <dirs> is a list of paths where
7390 libraries might be found: these paths are searched first when a target
7391 without any path info is given. Then standard system locations are
7392 also searched: PATH, Framework locations, /usr/lib...
7393 New in version 3.14: The variable GET_PREREQUISITES_VERBOSE can be set
7395 to true to enable verbose output.
7396 LIST_PREREQUISITES(<target> [<recurse> [<exclude_system> [<verbose>]]])
7399 Print a message listing the prerequisites of <target>.
7401 <target> is the name of a shared library or executable target or the
7403 full path to a shared library or executable file. If <recurse> is set
7404 to 1 all prerequisites will be found recursively, if set to 0 only di‐
7405 rect prerequisites are listed. <exclude_system> must be 0 or 1 indi‐
7406 cating whether to include or exclude "system" prerequisites. With
7407 <verbose> set to 0 only the full path names of the prerequisites are
7408 printed, set to 1 extra information will be displayed.
7409 LIST_PREREQUISITES_BY_GLOB(<glob_arg> <glob_exp>)
7411 Print the prerequisites of shared library and executable files matching
7413 a globbing pattern. <glob_arg> is GLOB or GLOB_RECURSE and <glob_exp>
7414 is a globbing expression used with "file(GLOB" or "file(GLOB_RECURSE"
7415 to retrieve a list of matching files. If a matching file is exe‐
7416 cutable, its prerequisites are listed.
7417 Any additional (optional) arguments provided are passed along as the
7419 optional arguments to the list_prerequisites calls.
7420 GP_APPEND_UNIQUE(<list_var> <value>)
7422 Append <value> to the list variable <list_var> only if the value is not
7424 already in the list.
7425 IS_FILE_EXECUTABLE(<file> <result_var>)
7427 Return 1 in <result_var> if <file> is a binary executable, 0 otherwise.
7429 GP_ITEM_DEFAULT_EMBEDDED_PATH(<item> <default_embedded_path_var>)
7431 Return the path that others should refer to the item by when the item
7433 is embedded inside a bundle.
7434 Override on a per-project basis by providing a project-specific
7436 gp_item_default_embedded_path_override function.
7437 GP_RESOLVE_ITEM(<context> <item> <exepath> <dirs> <resolved_item_var>
7439 [<rpaths>])
7440 Resolve an item into an existing full path file.
7442 Override on a per-project basis by providing a project-specific gp_re‐
7444 solve_item_override function.
7445 GP_RESOLVED_FILE_TYPE(<original_file> <file> <exepath> <dirs> <type_var>
7447 [<rpaths>])
7448 Return the type of <file> with respect to <original_file>. String de‐
7450 scribing type of prerequisite is returned in variable named <type_var>.
7451 Use <exepath> and <dirs> if necessary to resolve non-absolute <file>
7453 values -- but only for non-embedded items.
7454 Possible types are:
7456 system
7458 local
7459 embedded
7460 other
7461 Override on a per-project basis by providing a project-specific gp_re‐
7463 solved_file_type_override function.
7464 GP_FILE_TYPE(<original_file> <file> <type_var>)
7466 Return the type of <file> with respect to <original_file>. String de‐
7468 scribing type of prerequisite is returned in variable named <type_var>.
7469 Possible types are:
7471 system
7473 local
7474 embedded
7475 other
7476 GNUInstallDirs
7478 Define GNU standard installation directories
7479 Provides install directory variables as defined by the GNU Coding Stan‐
7481 dards.
7482 Result Variables
7484 Inclusion of this module defines the following variables:
7485 CMAKE_INSTALL_<dir>
7487 Destination for files of a given type. This value may be passed to
7488 the DESTINATION options of install() commands for the corresponding
7489 file type. It should typically be a path relative to the installa‐
7490 tion prefix so that it can be converted to an absolute path in a re‐
7491 locatable way (see CMAKE_INSTALL_FULL_<dir>). However, an absolute
7492 path is also allowed.
7493 CMAKE_INSTALL_FULL_<dir>
7495 The absolute path generated from the corresponding CMAKE_IN‐
7496 STALL_<dir> value. If the value is not already an absolute path, an
7497 absolute path is constructed typically by prepending the value of
7498 the CMAKE_INSTALL_PREFIX variable. However, there are some special
7499 cases as documented below.
7500 where <dir> is one of:
7502 BINDIR user executables (bin)
7504 SBINDIR
7506 system admin executables (sbin)
7507 LIBEXECDIR
7509 program executables (libexec)
7510 SYSCONFDIR
7512 read-only single-machine data (etc)
7513 SHAREDSTATEDIR
7515 modifiable architecture-independent data (com)
7516 LOCALSTATEDIR
7518 modifiable single-machine data (var)
7519 RUNSTATEDIR
7521 New in version 3.9: run-time variable data (LOCALSTATEDIR/run)
7522 LIBDIR object code libraries (lib or lib64 or lib/<multiarch-tuple> on
7525 Debian)
7526 INCLUDEDIR
7528 C header files (include)
7529 OLDINCLUDEDIR
7531 C header files for non-gcc (/usr/include)
7532 DATAROOTDIR
7534 read-only architecture-independent data root (share)
7535 DATADIR
7537 read-only architecture-independent data (DATAROOTDIR)
7538 INFODIR
7540 info documentation (DATAROOTDIR/info)
7541 LOCALEDIR
7543 locale-dependent data (DATAROOTDIR/locale)
7544 MANDIR man documentation (DATAROOTDIR/man)
7546 DOCDIR documentation root (DATAROOTDIR/doc/PROJECT_NAME)
7548 If the includer does not define a value the above-shown default will be
7550 used and the value will appear in the cache for editing by the user.
7551 Special Cases
7553 New in version 3.4.
7554 The following values of CMAKE_INSTALL_PREFIX are special:
7557 /
7559 For <dir> other than the SYSCONFDIR, LOCALSTATEDIR and RUNSTATEDIR,
7560 the value of CMAKE_INSTALL_<dir> is prefixed with usr/ if it is not
7561 user-specified as an absolute path. For example, the INCLUDEDIR
7562 value include becomes usr/include. This is required by the GNU Cod‐
7563 ing Standards, which state:
7564 When building the complete GNU system, the prefix will be empty
7565 and /usr will be a symbolic link to /.
7566 /usr
7568 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
7569 CMAKE_INSTALL_FULL_<dir> is computed by prepending just / to the
7570 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
7571 lute path. For example, the SYSCONFDIR value etc becomes /etc.
7572 This is required by the GNU Coding Standards.
7573 /opt/...
7575 For <dir> equal to SYSCONFDIR, LOCALSTATEDIR or RUNSTATEDIR, the
7576 CMAKE_INSTALL_FULL_<dir> is computed by appending the prefix to the
7577 value of CMAKE_INSTALL_<dir> if it is not user-specified as an abso‐
7578 lute path. For example, the SYSCONFDIR value etc becomes
7579 /etc/opt/.... This is defined by the Filesystem Hierarchy Standard.
7580 Macros
7582 GNUInstallDirs_get_absolute_install_dir
7583 GNUInstallDirs_get_absolute_install_dir(absvar var dirname)
7585 New in version 3.7.
7587 Set the given variable absvar to the absolute path contained
7590 within the variable var. This is to allow the computation of an
7591 absolute path, accounting for all the special cases documented
7592 above. While this macro is used to compute the various
7593 CMAKE_INSTALL_FULL_<dir> variables, it is exposed publicly to
7594 allow users who create additional path variables to also compute
7595 absolute paths where necessary, using the same logic. dirname
7596 is the directory name to get, e.g. BINDIR.
7597 Changed in version 3.20: Added the <dirname> parameter. Previ‐
7599 ous versions of CMake passed this value through the variable
7600 ${dir}.
7601 GoogleTest
7604 New in version 3.9.
7605 This module defines functions to help use the Google Test infrastruc‐
7608 ture. Two mechanisms for adding tests are provided. gtest_add_tests()
7609 has been around for some time, originally via find_package(GTest).
7610 gtest_discover_tests() was introduced in CMake 3.10.
7611 The (older) gtest_add_tests() scans source files to identify tests.
7613 This is usually effective, with some caveats, including in cross-com‐
7614 piling environments, and makes setting additional properties on tests
7615 more convenient. However, its handling of parameterized tests is less
7616 comprehensive, and it requires re-running CMake to detect changes to
7617 the list of tests.
7618 The (newer) gtest_discover_tests() discovers tests by asking the com‐
7620 piled test executable to enumerate its tests. This is more robust and
7621 provides better handling of parameterized tests, and does not require
7622 CMake to be re-run when tests change. However, it may not work in a
7623 cross-compiling environment, and setting test properties is less conve‐
7624 nient.
7625 More details can be found in the documentation of the respective func‐
7627 tions.
7628 Both commands are intended to replace use of add_test() to register
7630 tests, and will create a separate CTest test for each Google Test test
7631 case. Note that this is in some cases less efficient, as common set-up
7632 and tear-down logic cannot be shared by multiple test cases executing
7633 in the same instance. However, it provides more fine-grained pass/fail
7634 information to CTest, which is usually considered as more beneficial.
7635 By default, the CTest test name is the same as the Google Test name
7636 (i.e. suite.testcase); see also TEST_PREFIX and TEST_SUFFIX.
7637 gtest_add_tests
7639 Automatically add tests with CTest by scanning source code for
7640 Google Test macros:
7641 gtest_add_tests(TARGET target
7643 [SOURCES src1...]
7644 [EXTRA_ARGS arg1...]
7645 [WORKING_DIRECTORY dir]
7646 [TEST_PREFIX prefix]
7647 [TEST_SUFFIX suffix]
7648 [SKIP_DEPENDENCY]
7649 [TEST_LIST outVar]
7650 )
7651 gtest_add_tests attempts to identify tests by scanning source
7653 files. Although this is generally effective, it uses only a ba‐
7654 sic regular expression match, which can be defeated by atypical
7655 test declarations, and is unable to fully "split" parameterized
7656 tests. Additionally, it requires that CMake be re-run to dis‐
7657 cover any newly added, removed or renamed tests (by default,
7658 this means that CMake is re-run when any test source file is
7659 changed, but see SKIP_DEPENDENCY). However, it has the advan‐
7660 tage of declaring tests at CMake time, which somewhat simplifies
7661 setting additional properties on tests, and always works in a
7662 cross-compiling environment.
7663 The options are:
7665 TARGET target
7667 Specifies the Google Test executable, which must be a
7668 known CMake executable target. CMake will substitute the
7669 location of the built executable when running the test.
7670 SOURCES src1...
7672 When provided, only the listed files will be scanned for
7673 test cases. If this option is not given, the SOURCES
7674 property of the specified target will be used to obtain
7675 the list of sources.
7676 EXTRA_ARGS arg1...
7678 Any extra arguments to pass on the command line to each
7679 test case.
7680 WORKING_DIRECTORY dir
7682 Specifies the directory in which to run the discovered
7683 test cases. If this option is not provided, the current
7684 binary directory is used.
7685 TEST_PREFIX prefix
7687 Specifies a prefix to be prepended to the name of each
7688 discovered test case. This can be useful when the same
7689 source files are being used in multiple calls to
7690 gtest_add_test() but with different EXTRA_ARGS.
7691 TEST_SUFFIX suffix
7693 Similar to TEST_PREFIX except the suffix is appended to
7694 the name of every discovered test case. Both TEST_PREFIX
7695 and TEST_SUFFIX may be specified.
7696 SKIP_DEPENDENCY
7698 Normally, the function creates a dependency which will
7699 cause CMake to be re-run if any of the sources being
7700 scanned are changed. This is to ensure that the list of
7701 discovered tests is updated. If this behavior is not de‐
7702 sired (as may be the case while actually writing the test
7703 cases), this option can be used to prevent the dependency
7704 from being added.
7705 TEST_LIST outVar
7707 The variable named by outVar will be populated in the
7708 calling scope with the list of discovered test cases.
7709 This allows the caller to do things like manipulate test
7710 properties of the discovered tests.
7711 Usage example:
7713 include(GoogleTest)
7715 add_executable(FooTest FooUnitTest.cxx)
7716 gtest_add_tests(TARGET FooTest
7717 TEST_SUFFIX .noArgs
7718 TEST_LIST noArgsTests
7719 )
7720 gtest_add_tests(TARGET FooTest
7721 EXTRA_ARGS --someArg someValue
7722 TEST_SUFFIX .withArgs
7723 TEST_LIST withArgsTests
7724 )
7725 set_tests_properties(${noArgsTests} PROPERTIES TIMEOUT 10)
7726 set_tests_properties(${withArgsTests} PROPERTIES TIMEOUT 20)
7727 For backward compatibility, the following form is also sup‐
7729 ported:
7730 gtest_add_tests(exe args files...)
7732 exe The path to the test executable or the name of a CMake
7734 target.
7735 args A ;-list of extra arguments to be passed to executable.
7737 The entire list must be passed as a single argument. En‐
7738 close it in quotes, or pass "" for no arguments.
7739 files...
7741 A list of source files to search for tests and test fix‐
7742 tures. Alternatively, use AUTO to specify that exe is
7743 the name of a CMake executable target whose sources
7744 should be scanned.
7745 include(GoogleTest)
7747 set(FooTestArgs --foo 1 --bar 2)
7748 add_executable(FooTest FooUnitTest.cxx)
7749 gtest_add_tests(FooTest "${FooTestArgs}" AUTO)
7750 gtest_discover_tests
7752 Automatically add tests with CTest by querying the compiled test
7753 executable for available tests:
7754 gtest_discover_tests(target
7756 [EXTRA_ARGS arg1...]
7757 [WORKING_DIRECTORY dir]
7758 [TEST_PREFIX prefix]
7759 [TEST_SUFFIX suffix]
7760 [TEST_FILTER expr]
7761 [NO_PRETTY_TYPES] [NO_PRETTY_VALUES]
7762 [PROPERTIES name1 value1...]
7763 [TEST_LIST var]
7764 [DISCOVERY_TIMEOUT seconds]
7765 [XML_OUTPUT_DIR dir]
7766 [DISCOVERY_MODE <POST_BUILD|PRE_TEST>]
7767 )
7768 New in version 3.10.
7770 gtest_discover_tests() sets up a post-build command on the test
7773 executable that generates the list of tests by parsing the out‐
7774 put from running the test with the --gtest_list_tests argument.
7775 Compared to the source parsing approach of gtest_add_tests(),
7776 this ensures that the full list of tests, including instantia‐
7777 tions of parameterized tests, is obtained. Since test discovery
7778 occurs at build time, it is not necessary to re-run CMake when
7779 the list of tests changes. However, it requires that CROSSCOM‐
7780 PILING_EMULATOR is properly set in order to function in a
7781 cross-compiling environment.
7782 Additionally, setting properties on tests is somewhat less con‐
7784 venient, since the tests are not available at CMake time. Addi‐
7785 tional test properties may be assigned to the set of tests as a
7786 whole using the PROPERTIES option. If more fine-grained test
7787 control is needed, custom content may be provided through an ex‐
7788 ternal CTest script using the TEST_INCLUDE_FILES directory prop‐
7789 erty. The set of discovered tests is made accessible to such a
7790 script via the <target>_TESTS variable.
7791 The options are:
7793 target Specifies the Google Test executable, which must be a
7795 known CMake executable target. CMake will substitute the
7796 location of the built executable when running the test.
7797 EXTRA_ARGS arg1...
7799 Any extra arguments to pass on the command line to each
7800 test case.
7801 WORKING_DIRECTORY dir
7803 Specifies the directory in which to run the discovered
7804 test cases. If this option is not provided, the current
7805 binary directory is used.
7806 TEST_PREFIX prefix
7808 Specifies a prefix to be prepended to the name of each
7809 discovered test case. This can be useful when the same
7810 test executable is being used in multiple calls to
7811 gtest_discover_tests() but with different EXTRA_ARGS.
7812 TEST_SUFFIX suffix
7814 Similar to TEST_PREFIX except the suffix is appended to
7815 the name of every discovered test case. Both TEST_PREFIX
7816 and TEST_SUFFIX may be specified.
7817 TEST_FILTER expr
7819 New in version 3.22.
7820 Filter expression to pass as a --gtest_filter argument
7823 during test discovery. Note that the expression is a
7824 wildcard-based format that matches against the original
7825 test names as used by gtest. For type or value-parame‐
7826 terized tests, these names may be different to the poten‐
7827 tially pretty-printed test names that ctest uses.
7828 NO_PRETTY_TYPES
7830 By default, the type index of type-parameterized tests is
7831 replaced by the actual type name in the CTest test name.
7832 If this behavior is undesirable (e.g. because the type
7833 names are unwieldy), this option will suppress this be‐
7834 havior.
7835 NO_PRETTY_VALUES
7837 By default, the value index of value-parameterized tests
7838 is replaced by the actual value in the CTest test name.
7839 If this behavior is undesirable (e.g. because the value
7840 strings are unwieldy), this option will suppress this be‐
7841 havior.
7842 PROPERTIES name1 value1...
7844 Specifies additional properties to be set on all tests
7845 discovered by this invocation of gtest_discover_tests().
7846 TEST_LIST var
7848 Make the list of tests available in the variable var,
7849 rather than the default <target>_TESTS. This can be use‐
7850 ful when the same test executable is being used in multi‐
7851 ple calls to gtest_discover_tests(). Note that this
7852 variable is only available in CTest.
7853 DISCOVERY_TIMEOUT num
7855 New in version 3.10.3.
7856 Specifies how long (in seconds) CMake will wait for the
7859 test to enumerate available tests. If the test takes
7860 longer than this, discovery (and your build) will fail.
7861 Most test executables will enumerate their tests very
7862 quickly, but under some exceptional circumstances, a test
7863 may require a longer timeout. The default is 5. See
7864 also the TIMEOUT option of execute_process().
7865 NOTE:
7867 In CMake versions 3.10.1 and 3.10.2, this option was
7868 called TIMEOUT. This clashed with the TIMEOUT test
7869 property, which is one of the common properties that
7870 would be set with the PROPERTIES keyword, usually
7871 leading to legal but unintended behavior. The keyword
7872 was changed to DISCOVERY_TIMEOUT in CMake 3.10.3 to
7873 address this problem. The ambiguous behavior of the
7874 TIMEOUT keyword in 3.10.1 and 3.10.2 has not been pre‐
7875 served.
7876 XML_OUTPUT_DIR dir
7878 New in version 3.18.
7879 If specified, the parameter is passed along with
7882 --gtest_output=xml: to test executable. The actual file
7883 name is the same as the test target, including prefix and
7884 suffix. This should be used instead of EXTRA_ARGS
7885 --gtest_output=xml to avoid race conditions writing the
7886 XML result output when using parallel test execution.
7887 DISCOVERY_MODE
7889 New in version 3.18.
7890 Provides greater control over when gtest_discover_tests()
7893 performs test discovery. By default, POST_BUILD sets up a
7894 post-build command to perform test discovery at build
7895 time. In certain scenarios, like cross-compiling, this
7896 POST_BUILD behavior is not desirable. By contrast,
7897 PRE_TEST delays test discovery until just prior to test
7898 execution. This way test discovery occurs in the target
7899 environment where the test has a better chance at finding
7900 appropriate runtime dependencies.
7901 DISCOVERY_MODE defaults to the value of the
7903 CMAKE_GTEST_DISCOVER_TESTS_DISCOVERY_MODE variable if it
7904 is not passed when calling gtest_discover_tests(). This
7905 provides a mechanism for globally selecting a preferred
7906 test discovery behavior without having to modify each
7907 call site.
7908 InstallRequiredSystemLibraries
7910 Include this module to search for compiler-provided system runtime li‐
7911 braries and add install rules for them. Some optional variables may be
7912 set prior to including the module to adjust behavior:
7913 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS
7915 Specify additional runtime libraries that may not be detected.
7916 After inclusion any detected libraries will be appended to this.
7917 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_SKIP
7919 Set to TRUE to skip calling the install(PROGRAMS) command to al‐
7920 low the includer to specify its own install rule, using the
7921 value of CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS to get the list of
7922 libraries.
7923 CMAKE_INSTALL_DEBUG_LIBRARIES
7925 Set to TRUE to install the debug runtime libraries when avail‐
7926 able with MSVC tools.
7927 CMAKE_INSTALL_DEBUG_LIBRARIES_ONLY
7929 Set to TRUE to install only the debug runtime libraries with
7930 MSVC tools even if the release runtime libraries are also avail‐
7931 able.
7932 CMAKE_INSTALL_UCRT_LIBRARIES
7934 New in version 3.6.
7935 Set to TRUE to install the Windows Universal CRT libraries for
7938 app-local deployment (e.g. to Windows XP). This is meaningful
7939 only with MSVC from Visual Studio 2015 or higher.
7940 New in version 3.9: One may set a CMAKE_WINDOWS_KITS_10_DIR en‐
7942 vironment variable to an absolute path to tell CMake to look for
7943 Windows 10 SDKs in a custom location. The specified directory
7944 is expected to contain Redist/ucrt/DLLs/* directories.
7945 CMAKE_INSTALL_MFC_LIBRARIES
7948 Set to TRUE to install the MSVC MFC runtime libraries.
7949 CMAKE_INSTALL_OPENMP_LIBRARIES
7951 Set to TRUE to install the MSVC OpenMP runtime libraries
7952 CMAKE_INSTALL_SYSTEM_RUNTIME_DESTINATION
7954 Specify the install(PROGRAMS) command DESTINATION option. If
7955 not specified, the default is bin on Windows and lib elsewhere.
7956 CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS_NO_WARNINGS
7958 Set to TRUE to disable warnings about required library files
7959 that do not exist. (For example, Visual Studio Express editions
7960 may not provide the redistributable files.)
7961 CMAKE_INSTALL_SYSTEM_RUNTIME_COMPONENT
7963 New in version 3.3.
7964 Specify the install(PROGRAMS) command COMPONENT option. If not
7967 specified, no such option will be used.
7968 New in version 3.10: Support for installing Intel compiler runtimes.
7970 ProcessorCount
7973 ProcessorCount(var)
7974 Determine the number of processors/cores and save value in ${var}
7976 Sets the variable named ${var} to the number of physical cores avail‐
7978 able on the machine if the information can be determined. Otherwise it
7979 is set to 0. Currently this functionality is implemented for AIX, cyg‐
7980 win, FreeBSD, HPUX, Linux, macOS, QNX, Sun and Windows.
7981 Changed in version 3.15: On Linux, returns the container CPU count in‐
7983 stead of the host CPU count.
7984 This function is guaranteed to return a positive integer (>=1) if it
7987 succeeds. It returns 0 if there's a problem determining the processor
7988 count.
7989 Example use, in a ctest -S dashboard script:
7991 include(ProcessorCount)
7993 ProcessorCount(N)
7994 if(NOT N EQUAL 0)
7995 set(CTEST_BUILD_FLAGS -j${N})
7996 set(ctest_test_args ${ctest_test_args} PARALLEL_LEVEL ${N})
7997 endif()
7998 This function is intended to offer an approximation of the value of the
8000 number of compute cores available on the current machine, such that you
8001 may use that value for parallel building and parallel testing. It is
8002 meant to help utilize as much of the machine as seems reasonable. Of
8003 course, knowledge of what else might be running on the machine simulta‐
8004 neously should be used when deciding whether to request a machine's
8005 full capacity all for yourself.
8006 SelectLibraryConfigurations
8008 select_library_configurations(basename)
8009 This macro takes a library base name as an argument, and will choose
8011 good values for the variables
8012 basename_LIBRARY
8014 basename_LIBRARIES
8015 basename_LIBRARY_DEBUG
8016 basename_LIBRARY_RELEASE
8017 depending on what has been found and set.
8019 If only basename_LIBRARY_RELEASE is defined, basename_LIBRARY will be
8021 set to the release value, and basename_LIBRARY_DEBUG will be set to
8022 basename_LIBRARY_DEBUG-NOTFOUND. If only basename_LIBRARY_DEBUG is de‐
8023 fined, then basename_LIBRARY will take the debug value, and base‐
8024 name_LIBRARY_RELEASE will be set to basename_LIBRARY_RELEASE-NOTFOUND.
8025 If the generator supports configuration types, then basename_LIBRARY
8027 and basename_LIBRARIES will be set with debug and optimized flags spec‐
8028 ifying the library to be used for the given configuration. If no build
8029 type has been set or the generator in use does not support configura‐
8030 tion types, then basename_LIBRARY and basename_LIBRARIES will take only
8031 the release value, or the debug value if the release one is not set.
8032 SquishTestScript
8034 This script launches a GUI test using Squish. You should not call the
8035 script directly; instead, you should access it via the SQUISH_ADD_TEST
8036 macro that is defined in FindSquish.cmake.
8037 This script starts the Squish server, launches the test on the client,
8039 and finally stops the squish server. If any of these steps fail (in‐
8040 cluding if the tests do not pass) then a fatal error is raised.
8041 TestBigEndian
8043 Deprecated since version 3.20: Supserseded by the CMAKE_<LANG>_BYTE_OR‐
8044 DER variable.
8045 Check if the target architecture is big endian or little endian.
8048 test_big_endian
8050 test_big_endian(<var>)
8052 Stores in variable <var> either 1 or 0 indicating whether the
8054 target architecture is big or little endian.
8055 TestForANSIForScope
8057 Check for ANSI for scope support
8058 Check if the compiler restricts the scope of variables declared in a
8060 for-init-statement to the loop body.
8061 CMAKE_NO_ANSI_FOR_SCOPE - holds result
8063 TestForANSIStreamHeaders
8065 Test for compiler support of ANSI stream headers iostream, etc.
8066 check if the compiler supports the standard ANSI iostream header (with‐
8068 out the .h)
8069 CMAKE_NO_ANSI_STREAM_HEADERS - defined by the results
8071 TestForSSTREAM
8073 Test for compiler support of ANSI sstream header
8074 check if the compiler supports the standard ANSI sstream header
8076 CMAKE_NO_ANSI_STRING_STREAM - defined by the results
8078 TestForSTDNamespace
8080 Test for std:: namespace support
8081 check if the compiler supports std:: on stl classes
8083 CMAKE_NO_STD_NAMESPACE - defined by the results
8085 UseEcos
8087 This module defines variables and macros required to build eCos appli‐
8088 cation.
8089 This file contains the following macros: ECOS_ADD_INCLUDE_DIRECTORIES()
8091 - add the eCos include dirs ECOS_ADD_EXECUTABLE(name source1 ...
8092 sourceN ) - create an eCos executable ECOS_ADJUST_DIRECTORY(VAR source1
8093 ... sourceN ) - adjusts the path of the source files and puts the re‐
8094 sult into VAR
8095 Macros for selecting the toolchain: ECOS_USE_ARM_ELF_TOOLS() - enable
8097 the ARM ELF toolchain for the directory where it is called
8098 ECOS_USE_I386_ELF_TOOLS() - enable the i386 ELF toolchain for the di‐
8099 rectory where it is called ECOS_USE_PPC_EABI_TOOLS() - enable the Pow‐
8100 erPC toolchain for the directory where it is called
8101 It contains the following variables: ECOS_DEFINITIONS ECOSCONFIG_EXE‐
8103 CUTABLE ECOS_CONFIG_FILE - defaults to ecos.ecc, if your eCos configu‐
8104 ration file has a different name, adjust this variable for internal use
8105 only:
8106 ECOS_ADD_TARGET_LIB
8108 UseJava
8110 This file provides support for Java. It is assumed that FindJava has
8111 already been loaded. See FindJava for information on how to load Java
8112 into your CMake project.
8113 Synopsis
8115 Creating and Installing JARS
8116 add_jar (<target_name> [SOURCES] <source1> [<source2>...] ...)
8117 install_jar (<target_name> DESTINATION <destination> [COMPONENT <component>])
8118 install_jni_symlink (<target_name> DESTINATION <destination> [COMPONENT <component>])
8119 Header Generation
8121 create_javah ((TARGET <target> | GENERATED_FILES <VAR>) CLASSES <class>... ...)
8122 Exporting JAR Targets
8124 install_jar_exports (TARGETS <jars>... FILE <filename> DESTINATION <destination> ...)
8125 export_jars (TARGETS <jars>... [NAMESPACE <namespace>] FILE <filename>)
8126 Finding JARs
8128 find_jar (<VAR> NAMES <name1> [<name2>...] [PATHS <path1> [<path2>... ENV <var>]] ...)
8129 Creating Java Documentation
8131 create_javadoc (<VAR> (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...]) ...)
8132 Creating And Installing JARs
8134 add_jar
8135 Creates a jar file containing java objects and, optionally, re‐
8136 sources:
8137 add_jar(<target_name>
8139 [SOURCES] <source1> [<source2>...] [<resource1>...]
8140 [RESOURCES NAMESPACE <ns1> <resource1>... [NAMESPACE <nsX> <resourceX>...]... ]
8141 [INCLUDE_JARS <jar1> [<jar2>...]]
8142 [ENTRY_POINT <entry>]
8143 [VERSION <version>]
8144 [MANIFEST <manifest>]
8145 [OUTPUT_NAME <name>]
8146 [OUTPUT_DIR <dir>]
8147 [GENERATE_NATIVE_HEADERS <target>
8148 [DESTINATION (<dir>|INSTALL <dir> [BUILD <dir>])]]
8149 )
8150 This command creates a <target_name>.jar. It compiles the given
8152 <source> files and adds the given <resource> files to the jar
8153 file. Source files can be java files or listing files (prefixed
8154 by @). If only resource files are given then just a jar file is
8155 created.
8156 SOURCES
8158 Compiles the specified source files and adds the result
8159 in the jar file.
8160 New in version 3.4: Support for response files, prefixed
8162 by @.
8163 RESOURCES
8166 New in version 3.21.
8167 Adds the named <resource> files to the jar by stripping
8170 the source file path and placing the file beneath <ns>
8171 within the jar.
8172 For example:
8174 RESOURCES NAMESPACE "/com/my/namespace" "a/path/to/resource.txt"
8176 results in a resource accessible via /com/my/name‐
8178 space/resource.txt within the jar.
8179 Resources may be added without adjusting the namespace by
8181 adding them to the list of SOURCES (original behavior),
8182 in this case, resource paths must be relative to
8183 CMAKE_CURRENT_SOURCE_DIR. Adding resources without using
8184 the RESOURCES parameter in out of source builds will al‐
8185 most certainly result in confusion.
8186 NOTE:
8188 Adding resources via the SOURCES parameter relies upon
8189 a hard-coded list of file extensions which are tested
8190 to determine whether they compile (e.g. File.java).
8191 SOURCES files which match the extensions are compiled.
8192 Files which do not match are treated as resources. To
8193 include uncompiled resources matching those file ex‐
8194 tensions use the RESOURCES parameter.
8195 INCLUDE_JARS
8197 The list of jars are added to the classpath when compil‐
8198 ing the java sources and also to the dependencies of the
8199 target. INCLUDE_JARS also accepts other target names cre‐
8200 ated by add_jar(). For backwards compatibility, jar files
8201 listed as sources are ignored (as they have been since
8202 the first version of this module).
8203 ENTRY_POINT
8205 Defines an entry point in the jar file.
8206 VERSION
8208 Adds a version to the target output name.
8209 The following example will create a jar file with the
8211 name shibboleet-1.2.0.jar and will create a symlink shib‐
8212 boleet.jar pointing to the jar with the version informa‐
8213 tion.
8214 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
8216 MANIFEST
8218 Defines a custom manifest for the jar.
8219 OUTPUT_NAME
8221 Specify a different output name for the target.
8222 OUTPUT_DIR
8224 Sets the directory where the jar file will be generated.
8225 If not specified, CMAKE_CURRENT_BINARY_DIR is used as the
8226 output directory.
8227 GENERATE_NATIVE_HEADERS
8229 New in version 3.11.
8230 Generates native header files for methods declared as na‐
8233 tive. These files provide the connective glue that allow
8234 your Java and C code to interact. An INTERFACE target
8235 will be created for an easy usage of generated files.
8236 Sub-option DESTINATION can be used to specify the output
8237 directory for generated header files.
8238 This option requires, at least, version 1.8 of the JDK.
8240 For an optimum usage of this option, it is recommended to
8242 include module JNI before any call to add_jar(). The pro‐
8243 duced target for native headers can then be used to com‐
8244 pile C/C++ sources with the target_link_libraries() com‐
8245 mand.
8246 find_package(JNI)
8248 add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native)
8249 add_library(bar bar.cpp)
8250 target_link_libraries(bar PRIVATE foo-native)
8251 New in version 3.20: DESTINATION sub-option now supports
8253 the possibility to specify different output directories
8254 for BUILD and INSTALL steps. If BUILD directory is not
8255 specified, a default directory will be used.
8256 To export the interface target generated by GENERATE_NA‐
8258 TIVE_HEADERS option, sub-option INSTALL of DESTINATION is
8259 required:
8260 add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native
8262 DESTINATION INSTALL include)
8263 install(TARGETS foo-native EXPORT native)
8264 install(DIRECTORY "$<TARGET_PROPERTY:foo-native,NATIVE_HEADERS_DIRECTORY>/"
8265 DESTINATION include)
8266 install(EXPORT native DESTINATION /to/export NAMESPACE foo)
8267 Some variables can be set to customize the behavior of add_jar()
8270 as well as the java compiler:
8271 CMAKE_JAVA_COMPILE_FLAGS
8273 Specify additional flags to java compiler.
8274 CMAKE_JAVA_INCLUDE_PATH
8276 Specify additional paths to the class path.
8277 CMAKE_JNI_TARGET
8279 If the target is a JNI library, sets this boolean vari‐
8280 able to TRUE to enable creation of a JNI symbolic link
8281 (see also install_jni_symlink()).
8282 CMAKE_JAR_CLASSES_PREFIX
8284 If multiple jars should be produced from the same java
8285 source filetree, to prevent the accumulation of duplicate
8286 class files in subsequent jars, set/reset
8287 CMAKE_JAR_CLASSES_PREFIX prior to calling the add_jar():
8288 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo)
8290 add_jar(foo foo.java)
8291 set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar)
8293 add_jar(bar bar.java)
8294 The add_jar() function sets the following target properties on
8296 <target_name>:
8297 INSTALL_FILES
8299 The files which should be installed. This is used by
8300 install_jar().
8301 JNI_SYMLINK
8303 The JNI symlink which should be installed. This is used
8304 by install_jni_symlink().
8305 JAR_FILE
8307 The location of the jar file so that you can include it.
8308 CLASSDIR
8310 The directory where the class files can be found. For
8311 example to use them with javah.
8312 NATIVE_HEADERS_DIRECTORY
8314 New in version 3.20.
8315 The directory where native headers are generated. Defined
8318 when option GENERATE_NATIVE_HEADERS is specified.
8319 install_jar
8321 This command installs the jar file to the given destination:
8322 install_jar(<target_name> <destination>)
8324 install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>])
8325 This command installs the <target_name> file to the given <des‐
8327 tination>. It should be called in the same scope as add_jar()
8328 or it will fail.
8329 New in version 3.4: The second signature with DESTINATION and
8331 COMPONENT options.
8332 DESTINATION
8335 Specify the directory on disk to which a file will be in‐
8336 stalled.
8337 COMPONENT
8339 Specify an installation component name with which the in‐
8340 stall rule is associated, such as "runtime" or "develop‐
8341 ment".
8342 The install_jar() command sets the following target properties
8344 on <target_name>:
8345 INSTALL_DESTINATION
8347 Holds the <destination> as described above, and is used
8348 by install_jar_exports().
8349 install_jni_symlink
8351 Installs JNI symlinks for target generated by add_jar():
8352 install_jni_symlink(<target_name> <destination>)
8354 install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>])
8355 This command installs the <target_name> JNI symlinks to the
8357 given <destination>. It should be called in the same scope as
8358 add_jar() or it will fail.
8359 New in version 3.4: The second signature with DESTINATION and
8361 COMPONENT options.
8362 DESTINATION
8365 Specify the directory on disk to which a file will be in‐
8366 stalled.
8367 COMPONENT
8369 Specify an installation component name with which the in‐
8370 stall rule is associated, such as "runtime" or "develop‐
8371 ment".
8372 Utilize the following commands to create a JNI symbolic link:
8374 set(CMAKE_JNI_TARGET TRUE)
8376 add_jar(shibboleet shibbotleet.java VERSION 1.2.0)
8377 install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet)
8378 install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR})
8379 Header Generation
8381 create_javah
8382 New in version 3.4.
8383 Generates C header files for java classes:
8386 create_javah(TARGET <target> | GENERATED_FILES <VAR>
8388 CLASSES <class>...
8389 [CLASSPATH <classpath>...]
8390 [DEPENDS <depend>...]
8391 [OUTPUT_NAME <path>|OUTPUT_DIR <path>]
8392 )
8393 Deprecated since version 3.11: This command will no longer be
8395 supported starting with version 10 of the JDK due to the
8396 suppression of javah tool. The add_jar(GENERATE_NATIVE_HEADERS)
8397 command should be used instead.
8398 Create C header files from java classes. These files provide the
8401 connective glue that allow your Java and C code to interact.
8402 There are two main signatures for create_javah(). The first
8404 signature returns generated files through variable specified by
8405 the GENERATED_FILES option. For example:
8406 create_javah(GENERATED_FILES files_headers
8408 CLASSES org.cmake.HelloWorld
8409 CLASSPATH hello.jar
8410 )
8411 The second signature for create_javah() creates a target which
8413 encapsulates header files generation. E.g.
8414 create_javah(TARGET target_headers
8416 CLASSES org.cmake.HelloWorld
8417 CLASSPATH hello.jar
8418 )
8419 Both signatures share same options.
8421 CLASSES
8423 Specifies Java classes used to generate headers.
8424 CLASSPATH
8426 Specifies various paths to look up classes. Here .class
8427 files, jar files or targets created by command add_jar
8428 can be used.
8429 DEPENDS
8431 Targets on which the javah target depends.
8432 OUTPUT_NAME
8434 Concatenates the resulting header files for all the
8435 classes listed by option CLASSES into <path>. Same be‐
8436 havior as option -o of javah tool.
8437 OUTPUT_DIR
8439 Sets the directory where the header files will be gener‐
8440 ated. Same behavior as option -d of javah tool. If not
8441 specified, CMAKE_CURRENT_BINARY_DIR is used as the output
8442 directory.
8443 Exporting JAR Targets
8445 install_jar_exports
8446 New in version 3.7.
8447 Installs a target export file:
8450 install_jar_exports(TARGETS <jars>...
8452 [NAMESPACE <namespace>]
8453 FILE <filename>
8454 DESTINATION <destination> [COMPONENT <component>])
8455 This command installs a target export file <filename> for the
8457 named jar targets to the given <destination> directory. Its
8458 function is similar to that of install(EXPORT).
8459 TARGETS
8461 List of targets created by add_jar() command.
8462 NAMESPACE
8464 New in version 3.9.
8465 The <namespace> value will be prepend to the target names
8468 as they are written to the import file.
8469 FILE Specify name of the export file.
8471 DESTINATION
8473 Specify the directory on disk to which a file will be in‐
8474 stalled.
8475 COMPONENT
8477 Specify an installation component name with which the in‐
8478 stall rule is associated, such as "runtime" or "develop‐
8479 ment".
8480 export_jars
8482 New in version 3.7.
8483 Writes a target export file:
8486 export_jars(TARGETS <jars>...
8488 [NAMESPACE <namespace>]
8489 FILE <filename>)
8490 This command writes a target export file <filename> for the
8492 named <jars> targets. Its function is similar to that of ex‐
8493 port().
8494 TARGETS
8496 List of targets created by add_jar() command.
8497 NAMESPACE
8499 New in version 3.9.
8500 The <namespace> value will be prepend to the target names
8503 as they are written to the import file.
8504 FILE Specify name of the export file.
8506 Finding JARs
8508 find_jar
8509 Finds the specified jar file:
8510 find_jar(<VAR>
8512 <name> | NAMES <name1> [<name2>...]
8513 [PATHS <path1> [<path2>... ENV <var>]]
8514 [VERSIONS <version1> [<version2>]]
8515 [DOC "cache documentation string"]
8516 )
8517 This command is used to find a full path to the named jar. A
8519 cache entry named by <VAR> is created to store the result of
8520 this command. If the full path to a jar is found the result is
8521 stored in the variable and the search will not repeated unless
8522 the variable is cleared. If nothing is found, the result will
8523 be <VAR>-NOTFOUND, and the search will be attempted again next
8524 time find_jar() is invoked with the same variable.
8525 NAMES Specify one or more possible names for the jar file.
8527 PATHS Specify directories to search in addition to the default
8529 locations. The ENV var sub-option reads paths from a
8530 system environment variable.
8531 VERSIONS
8533 Specify jar versions.
8534 DOC Specify the documentation string for the <VAR> cache en‐
8536 try.
8537 Creating Java Documentation
8539 create_javadoc
8540 Creates java documentation based on files and packages:
8541 create_javadoc(<VAR>
8543 (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...])
8544 [SOURCEPATH <sourcepath>]
8545 [CLASSPATH <classpath>]
8546 [INSTALLPATH <install path>]
8547 [DOCTITLE <the documentation title>]
8548 [WINDOWTITLE <the title of the document>]
8549 [AUTHOR (TRUE|FALSE)]
8550 [USE (TRUE|FALSE)]
8551 [VERSION (TRUE|FALSE)]
8552 )
8553 The create_javadoc() command can be used to create java documen‐
8555 tation. There are two main signatures for create_javadoc().
8556 The first signature works with package names on a path with
8558 source files:
8559 create_javadoc(my_example_doc
8561 PACKAGES com.example.foo com.example.bar
8562 SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}"
8563 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
8564 WINDOWTITLE "My example"
8565 DOCTITLE "<h1>My example</h1>"
8566 AUTHOR TRUE
8567 USE TRUE
8568 VERSION TRUE
8569 )
8570 The second signature for create_javadoc() works on a given list
8572 of files:
8573 create_javadoc(my_example_doc
8575 FILES java/A.java java/B.java
8576 CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH}
8577 WINDOWTITLE "My example"
8578 DOCTITLE "<h1>My example</h1>"
8579 AUTHOR TRUE
8580 USE TRUE
8581 VERSION TRUE
8582 )
8583 Both signatures share most of the options. For more details
8585 please read the javadoc manpage.
8586 PACKAGES
8588 Specify java packages.
8589 FILES Specify java source files. If relative paths are speci‐
8591 fied, they are relative to CMAKE_CURRENT_SOURCE_DIR.
8592 SOURCEPATH
8594 Specify the directory where to look for packages. By de‐
8595 fault, CMAKE_CURRENT_SOURCE_DIR directory is used.
8596 CLASSPATH
8598 Specify where to find user class files. Same behavior as
8599 option -classpath of javadoc tool.
8600 INSTALLPATH
8602 Specify where to install the java documentation. If you
8603 specified, the documentation will be installed to
8604 ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>.
8605 DOCTITLE
8607 Specify the title to place near the top of the overview
8608 summary file. Same behavior as option -doctitle of
8609 javadoc tool.
8610 WINDOWTITLE
8612 Specify the title to be placed in the HTML <title> tag.
8613 Same behavior as option -windowtitle of javadoc tool.
8614 AUTHOR When value TRUE is specified, includes the @author text
8616 in the generated docs. Same behavior as option -author
8617 of javadoc tool.
8618 USE When value TRUE is specified, creates class and package
8620 usage pages. Includes one Use page for each documented
8621 class and package. Same behavior as option -use of
8622 javadoc tool.
8623 VERSION
8625 When value TRUE is specified, includes the version text
8626 in the generated docs. Same behavior as option -version
8627 of javadoc tool.
8628 UseSWIG
8630 This file provides support for SWIG. It is assumed that FindSWIG module
8631 has already been loaded.
8632 Defines the following command for use with SWIG:
8634 swig_add_library
8636 New in version 3.8.
8637 Define swig module with given name and specified language:
8640 swig_add_library(<name>
8642 [TYPE <SHARED|MODULE|STATIC|USE_BUILD_SHARED_LIBS>]
8643 LANGUAGE <language>
8644 [NO_PROXY]
8645 [OUTPUT_DIR <directory>]
8646 [OUTFILE_DIR <directory>]
8647 SOURCES <file>...
8648 )
8649 Targets created with the swig_add_library command have the same
8651 capabilities as targets created with the add_library() command,
8652 so those targets can be used with any command expecting a target
8653 (e.g. target_link_libraries()).
8654 Changed in version 3.13: This command creates a target with the
8656 specified <name> when policy CMP0078 is set to NEW. Otherwise,
8657 the legacy behavior will choose a different target name and
8658 store it in the SWIG_MODULE_<name>_REAL_NAME variable.
8659 Changed in version 3.15: Alternate library name (set with the
8662 OUTPUT_NAME property, for example) will be passed on to Python
8663 and CSharp wrapper libraries.
8664 Changed in version 3.21: Generated library use standard naming
8667 conventions for CSharp language when policy CMP0122 is set to
8668 NEW. Otherwise, the legacy behavior is applied.
8669 NOTE:
8672 For multi-config generators, this module does not support
8673 configuration-specific files generated by SWIG. All build
8674 configurations must result in the same generated source file.
8675 NOTE:
8677 For Makefile Generators, if, for some sources, the
8678 USE_SWIG_DEPENDENCIES property is FALSE, swig_add_library
8679 does not track file dependencies, so depending on the
8680 <name>_swig_compilation custom target is required for targets
8681 which require the swig-generated files to exist. Other gener‐
8682 ators may depend on the source files that would be generated
8683 by SWIG.
8684 TYPE SHARED, MODULE and STATIC have the same semantic as for
8686 the add_library() command. If USE_BUILD_SHARED_LIBS is
8687 specified, the library type will be STATIC or SHARED
8688 based on whether the current value of the
8689 BUILD_SHARED_LIBS variable is ON. If no type is speci‐
8690 fied, MODULE will be used.
8691 LANGUAGE
8693 Specify the target language.
8694 New in version 3.1: Go and Lua language support.
8696 New in version 3.2: R language support.
8699 New in version 3.18: Fortran language support.
8702 NO_PROXY
8705 New in version 3.12.
8706 Prevent the generation of the wrapper layer (swig -no‐
8709 proxy option).
8710 OUTPUT_DIR
8712 New in version 3.12.
8713 Specify where to write the language specific files (swig
8716 -outdir option). If not given, the CMAKE_SWIG_OUTDIR
8717 variable will be used. If neither is specified, the de‐
8718 fault depends on the value of the UseSWIG_MODULE_VERSION
8719 variable as follows:
8720 • If UseSWIG_MODULE_VERSION is 1 or is undefined, output
8722 is written to the CMAKE_CURRENT_BINARY_DIR directory.
8723 • If UseSWIG_MODULE_VERSION is 2, a dedicated directory
8725 will be used. The path of this directory can be re‐
8726 trieved from the SWIG_SUPPORT_FILES_DIRECTORY target
8727 property.
8728 OUTFILE_DIR
8730 New in version 3.12.
8731 Specify an output directory name where the generated
8734 source file will be placed (swig -o option). If not spec‐
8735 ified, the SWIG_OUTFILE_DIR variable will be used. If
8736 neither is specified, OUTPUT_DIR or CMAKE_SWIG_OUTDIR is
8737 used instead.
8738 SOURCES
8740 List of sources for the library. Files with extension .i
8741 will be identified as sources for the SWIG tool. Other
8742 files will be handled in the standard way.
8743 New in version 3.14: This behavior can be overridden by
8745 specifying the variable SWIG_SOURCE_FILE_EXTENSIONS.
8746 NOTE:
8749 If UseSWIG_MODULE_VERSION is set to 2, it is strongly recom‐
8750 mended to use a dedicated directory unique to the target when
8751 either the OUTPUT_DIR option or the CMAKE_SWIG_OUTDIR vari‐
8752 able are specified. The output directory contents are erased
8753 as part of the target build, so to prevent interference be‐
8754 tween targets or losing other important files, each target
8755 should have its own dedicated output directory.
8756 swig_link_libraries
8758 Link libraries to swig module:
8759 swig_link_libraries(<name> <item>...)
8761 This command has same capabilities as target_link_libraries()
8763 command.
8764 NOTE:
8766 If variable UseSWIG_TARGET_NAME_PREFERENCE is set to STAN‐
8767 DARD, this command is deprecated and target_link_libraries()
8768 command must be used instead.
8769 Source file properties on module files must be set before the invoca‐
8771 tion of the swig_add_library command to specify special behavior of
8772 SWIG and ensure generated files will receive the required settings.
8773 CPLUSPLUS
8775 Call SWIG in c++ mode. For example:
8776 set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON)
8778 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
8779 SWIG_FLAGS
8781 Deprecated since version 3.12: Replaced with the fine-grained
8782 properties that follow.
8783 Pass custom flags to the SWIG executable.
8786 INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_OPTIONS
8788 New in version 3.12.
8789 Add custom flags to SWIG compiler and have same semantic as
8792 properties INCLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COM‐
8793 PILE_OPTIONS.
8794 USE_TARGET_INCLUDE_DIRECTORIES
8796 New in version 3.13.
8797 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
8800 will be forwarded to SWIG compiler. If set to FALSE target
8801 property INCLUDE_DIRECTORIES will be ignored. If not set, target
8802 property SWIG_USE_TARGET_INCLUDE_DIRECTORIES will be considered.
8803 GENERATED_INCLUDE_DIRECTORIES, GENERATED_COMPILE_DEFINITIONS and GENER‐
8805 ATED_COMPILE_OPTIONS
8806 New in version 3.12.
8807 Add custom flags to the C/C++ generated source. They will fill,
8810 respectively, properties INCLUDE_DIRECTORIES, COMPILE_DEFINI‐
8811 TIONS and COMPILE_OPTIONS of generated C/C++ file.
8812 DEPENDS
8814 New in version 3.12.
8815 Specify additional dependencies to the source file.
8818 USE_SWIG_DEPENDENCIES
8820 New in version 3.20.
8821 If set to TRUE, implicit dependencies are generated by the swig
8824 tool itself. This property is only meaningful for Makefile,
8825 Ninja, Xcode, and Visual Studio (Visual Studio 11 2012 and
8826 above) generators. Default value is FALSE.
8827 New in version 3.21: Added the support of Xcode generator.
8829 New in version 3.22: Added the support of Visual Studio Genera‐
8832 tors.
8833 SWIG_MODULE_NAME
8836 Specify the actual import name of the module in the target lan‐
8837 guage. This is required if it cannot be scanned automatically
8838 from source or different from the module file basename. For ex‐
8839 ample:
8840 set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname)
8842 Changed in version 3.14: If policy CMP0086 is set to NEW, -mod‐
8844 ule <module_name> is passed to SWIG compiler.
8845 OUTPUT_DIR
8848 New in version 3.19.
8849 Specify where to write the language specific files (swig -outdir
8852 option) for the considered source file. If not specified, the
8853 other ways to define the output directory applies (see OUT‐
8854 PUT_DIR option of swig_add_library() command).
8855 OUTFILE_DIR
8857 New in version 3.19.
8858 Specify an output directory where the generated source file will
8861 be placed (swig -o option) for the considered source file. If
8862 not specified, OUTPUT_DIR source property will be used. If nei‐
8863 ther are specified, the other ways to define output file direc‐
8864 tory applies (see OUTFILE_DIR option of swig_add_library() com‐
8865 mand).
8866 Target library properties can be set to apply same configuration to all
8868 SWIG input files.
8869 SWIG_INCLUDE_DIRECTORIES, SWIG_COMPILE_DEFINITIONS and SWIG_COMPILE_OP‐
8871 TIONS
8872 New in version 3.12.
8873 These properties will be applied to all SWIG input files and
8876 have same semantic as target properties INCLUDE_DIRECTORIES,
8877 COMPILE_DEFINITIONS and COMPILE_OPTIONS.
8878 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
8880 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
8881 set_property(TARGET mymod PROPERTY SWIG_COMPILE_DEFINITIONS MY_DEF1 MY_DEF2)
8882 set_property(TARGET mymod PROPERTY SWIG_COMPILE_OPTIONS -bla -blb)
8883 SWIG_USE_TARGET_INCLUDE_DIRECTORIES
8885 New in version 3.13.
8886 If set to TRUE, contents of target property INCLUDE_DIRECTORIES
8889 will be forwarded to SWIG compiler. If set to FALSE or not de‐
8890 fined, target property INCLUDE_DIRECTORIES will be ignored. This
8891 behavior can be overridden by specifying source property
8892 USE_TARGET_INCLUDE_DIRECTORIES.
8893 SWIG_GENERATED_INCLUDE_DIRECTORIES, SWIG_GENERATED_COMPILE_DEFINITIONS
8895 and SWIG_GENERATED_COMPILE_OPTIONS
8896 New in version 3.12.
8897 These properties will populate, respectively, properties IN‐
8900 CLUDE_DIRECTORIES, COMPILE_DEFINITIONS and COMPILE_FLAGS of all
8901 generated C/C++ files.
8902 SWIG_DEPENDS
8904 New in version 3.12.
8905 Add dependencies to all SWIG input files.
8908 The following target properties are output properties and can be used
8910 to get information about support files generated by SWIG interface com‐
8911 pilation.
8912 SWIG_SUPPORT_FILES
8914 New in version 3.12.
8915 This output property list of wrapper files generated during SWIG
8918 compilation.
8919 set (UseSWIG_TARGET_NAME_PREFERENCE STANDARD)
8921 swig_add_library(mymod LANGUAGE python SOURCES mymod.i)
8922 get_property(support_files TARGET mymod PROPERTY SWIG_SUPPORT_FILES)
8923 NOTE:
8925 Only most principal support files are listed. In case some
8926 advanced features of SWIG are used (for example %template),
8927 associated support files may not be listed. Prefer to use the
8928 SWIG_SUPPORT_FILES_DIRECTORY property to handle support
8929 files.
8930 SWIG_SUPPORT_FILES_DIRECTORY
8932 New in version 3.12.
8933 This output property specifies the directory where support files
8936 will be generated.
8937 NOTE:
8939 When source property OUTPUT_DIR is defined, multiple directo‐
8940 ries can be specified as part of SWIG_SUPPORT_FILES_DIREC‐
8941 TORY.
8942 Some variables can be set to customize the behavior of swig_add_library
8944 as well as SWIG:
8945 UseSWIG_MODULE_VERSION
8947 New in version 3.12.
8948 Specify different behaviors for UseSWIG module.
8951 • Set to 1 or undefined: Legacy behavior is applied.
8953 • Set to 2: A new strategy is applied regarding support files:
8955 the output directory of support files is erased before SWIG
8956 interface compilation.
8957 CMAKE_SWIG_FLAGS
8959 Add flags to all swig calls.
8960 CMAKE_SWIG_OUTDIR
8962 Specify where to write the language specific files (swig -outdir
8963 option).
8964 SWIG_OUTFILE_DIR
8966 New in version 3.8.
8967 Specify an output directory name where the generated source file
8970 will be placed. If not specified, CMAKE_SWIG_OUTDIR is used.
8971 SWIG_MODULE_<name>_EXTRA_DEPS
8973 Specify extra dependencies for the generated module for <name>.
8974 SWIG_SOURCE_FILE_EXTENSIONS
8976 New in version 3.14.
8977 Specify a list of source file extensions to override the default
8980 behavior of considering only .i files as sources for the SWIG
8981 tool. For example:
8982 set(SWIG_SOURCE_FILE_EXTENSIONS ".i" ".swg")
8984 SWIG_USE_SWIG_DEPENDENCIES
8986 New in version 3.20.
8987 If set to TRUE, implicit dependencies are generated by the swig
8990 tool itself. This variable is only meaningful for Makefile,
8991 Ninja, Xcode, and Visual Studio (Visual Studio 11 2012 and
8992 above) generators. Default value is FALSE.
8993 Source file property USE_SWIG_DEPENDENCIES, if not defined, will
8995 be initialized with the value of this variable.
8996 New in version 3.21: Added the support of Xcode generator.
8998 New in version 3.22: Added the support of Visual Studio Genera‐
9001 tors.
9002 UsewxWidgets
9005 Convenience include for using wxWidgets library.
9006 Determines if wxWidgets was FOUND and sets the appropriate libs, in‐
9008 cdirs, flags, etc. INCLUDE_DIRECTORIES and LINK_DIRECTORIES are
9009 called.
9010 USAGE
9012 # Note that for MinGW users the order of libs is important!
9014 find_package(wxWidgets REQUIRED net gl core base)
9015 include(${wxWidgets_USE_FILE})
9016 # and for each of your dependent executable/library targets:
9017 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
9018 DEPRECATED
9020 LINK_LIBRARIES is not called in favor of adding dependencies per target.
9022 AUTHOR
9024 Jan Woetzel <jw -at- mip.informatik.uni-kiel.de>
9026
9028 These modules search for third-party software. They are normally
9029 called through the find_package() command.
9030 FindALSA
9032 Find Advanced Linux Sound Architecture (ALSA)
9033 Find the alsa libraries (asound)
9035 IMPORTED Targets
9037 New in version 3.12.
9038 This module defines IMPORTED target ALSA::ALSA, if ALSA has been found.
9041 Result Variables
9043 This module defines the following variables:
9044 ALSA_FOUND
9046 True if ALSA_INCLUDE_DIR & ALSA_LIBRARY are found
9047 ALSA_LIBRARIES
9049 List of libraries when using ALSA.
9050 ALSA_INCLUDE_DIRS
9052 Where to find the ALSA headers.
9053 Cache variables
9055 The following cache variables may also be set:
9056 ALSA_INCLUDE_DIR
9058 the ALSA include directory
9059 ALSA_LIBRARY
9061 the absolute path of the asound library
9062 FindArmadillo
9064 Find the Armadillo C++ library. Armadillo is a library for linear al‐
9065 gebra & scientific computing.
9066 New in version 3.18: Support for linking wrapped libraries directly
9068 (ARMA_DONT_USE_WRAPPER).
9069 Using Armadillo:
9072 find_package(Armadillo REQUIRED)
9074 include_directories(${ARMADILLO_INCLUDE_DIRS})
9075 add_executable(foo foo.cc)
9076 target_link_libraries(foo ${ARMADILLO_LIBRARIES})
9077 This module sets the following variables:
9079 ARMADILLO_FOUND - set to true if the library is found
9081 ARMADILLO_INCLUDE_DIRS - list of required include directories
9082 ARMADILLO_LIBRARIES - list of libraries to be linked
9083 ARMADILLO_VERSION_MAJOR - major version number
9084 ARMADILLO_VERSION_MINOR - minor version number
9085 ARMADILLO_VERSION_PATCH - patch version number
9086 ARMADILLO_VERSION_STRING - version number as a string (ex: "1.0.4")
9087 ARMADILLO_VERSION_NAME - name of the version (ex: "Antipodean Antileech")
9088 FindASPELL
9090 Try to find ASPELL
9091 Once done this will define
9093 ASPELL_FOUND - system has ASPELL
9095 ASPELL_EXECUTABLE - the ASPELL executable
9096 ASPELL_INCLUDE_DIR - the ASPELL include directory
9097 ASPELL_LIBRARIES - The libraries needed to use ASPELL
9098 ASPELL_DEFINITIONS - Compiler switches required for using ASPELL
9099 FindAVIFile
9101 Locate AVIFILE library and include paths
9102 AVIFILE (http://avifile.sourceforge.net/) is a set of libraries for
9104 i386 machines to use various AVI codecs. Support is limited beyond
9105 Linux. Windows provides native AVI support, and so doesn't need this
9106 library. This module defines
9107 AVIFILE_INCLUDE_DIR, where to find avifile.h , etc.
9109 AVIFILE_LIBRARIES, the libraries to link against
9110 AVIFILE_DEFINITIONS, definitions to use when compiling
9111 AVIFILE_FOUND, If false, don't try to use AVIFILE
9112 FindBacktrace
9114 Find provider for backtrace(3).
9115 Checks if OS supports backtrace(3) via either libc or custom library.
9117 This module defines the following variables:
9118 Backtrace_HEADER
9120 The header file needed for backtrace(3). Cached. Could be
9121 forcibly set by user.
9122 Backtrace_INCLUDE_DIRS
9124 The include directories needed to use backtrace(3) header.
9125 Backtrace_LIBRARIES
9127 The libraries (linker flags) needed to use backtrace(3), if any.
9128 Backtrace_FOUND
9130 Is set if and only if backtrace(3) support detected.
9131 The following cache variables are also available to set or use:
9133 Backtrace_LIBRARY
9135 The external library providing backtrace, if any.
9136 Backtrace_INCLUDE_DIR
9138 The directory holding the backtrace(3) header.
9139 Typical usage is to generate of header file using configure_file() with
9141 the contents like the following:
9142 #cmakedefine01 Backtrace_FOUND
9144 #if Backtrace_FOUND
9145 # include <${Backtrace_HEADER}>
9146 #endif
9147 And then reference that generated header file in actual source.
9149 FindBISON
9151 Find bison executable and provide a macro to generate custom build
9152 rules.
9153 The module defines the following variables:
9155 BISON_EXECUTABLE
9157 path to the bison program
9158 BISON_VERSION
9160 version of bison
9161 BISON_FOUND
9163 "True" if the program was found
9164 The minimum required version of bison can be specified using the stan‐
9166 dard CMake syntax, e.g. find_package(BISON 2.1.3).
9167 If bison is found, the module defines the macro:
9169 BISON_TARGET(<Name> <YaccInput> <CodeOutput>
9171 [COMPILE_FLAGS <flags>]
9172 [DEFINES_FILE <file>]
9173 [VERBOSE [<file>]]
9174 [REPORT_FILE <file>]
9175 )
9176 which will create a custom rule to generate a parser. <YaccInput> is
9178 the path to a yacc file. <CodeOutput> is the name of the source file
9179 generated by bison. A header file is also be generated, and contains
9180 the token list.
9181 Changed in version 3.14: When CMP0088 is set to NEW, bison runs in the
9183 CMAKE_CURRENT_BINARY_DIR directory.
9184 The options are:
9187 COMPILE_FLAGS <flags>
9189 Specify flags to be added to the bison command line.
9190 DEFINES_FILE <file>
9192 New in version 3.4.
9193 Specify a non-default header <file> to be generated by bison.
9196 VERBOSE [<file>]
9198 Tell bison to write a report file of the grammar and parser.
9199 Deprecated since version 3.7: If <file> is given, it specifies
9201 path the report file is copied to. [<file>] is left for back‐
9202 ward compatibility of this module. Use VERBOSE REPORT_FILE
9203 <file>.
9204 REPORT_FILE <file>
9207 New in version 3.7.
9208 Specify a non-default report <file>, if generated.
9211 The macro defines the following variables:
9213 BISON_<Name>_DEFINED
9215 True is the macro ran successfully
9216 BISON_<Name>_INPUT
9218 The input source file, an alias for <YaccInput>
9219 BISON_<Name>_OUTPUT_SOURCE
9221 The source file generated by bison
9222 BISON_<Name>_OUTPUT_HEADER
9224 The header file generated by bison
9225 BISON_<Name>_OUTPUTS
9227 All files generated by bison including the source, the header
9228 and the report
9229 BISON_<Name>_COMPILE_FLAGS
9231 Options used in the bison command line
9232 Example usage:
9234 find_package(BISON)
9236 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp
9237 DEFINES_FILE ${CMAKE_CURRENT_BINARY_DIR}/parser.h)
9238 add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
9239 FindBLAS
9241 Find Basic Linear Algebra Subprograms (BLAS) library
9242 This module finds an installed Fortran library that implements the BLAS
9244 linear-algebra interface.
9245 At least one of the C, CXX, or Fortran languages must be enabled.
9247 Input Variables
9249 The following variables may be set to influence this module's behavior:
9250 BLA_STATIC
9252 if ON use static linkage
9253 BLA_VENDOR
9255 Set to one of the BLAS/LAPACK Vendors to search for BLAS only
9256 from the specified vendor. If not set, all vendors are consid‐
9257 ered.
9258 BLA_F95
9260 if ON tries to find the BLAS95 interfaces
9261 BLA_PREFER_PKGCONFIG
9263 New in version 3.11.
9264 if set pkg-config will be used to search for a BLAS library
9267 first and if one is found that is preferred
9268 BLA_SIZEOF_INTEGER
9270 New in version 3.22.
9271 Specify the BLAS/LAPACK library integer size:
9274 4 Search for a BLAS/LAPACK with 32-bit integer interfaces.
9276 8 Search for a BLAS/LAPACK with 64-bit integer interfaces.
9278 ANY Search for any BLAS/LAPACK. Most likely, a BLAS/LAPACK
9280 with 32-bit integer interfaces will be found.
9281 Imported targets
9283 This module defines the following IMPORTED targets:
9284 BLAS::BLAS
9286 New in version 3.18.
9287 The libraries to use for BLAS, if found.
9290 Result Variables
9292 This module defines the following variables:
9293 BLAS_FOUND
9295 library implementing the BLAS interface is found
9296 BLAS_LINKER_FLAGS
9298 uncached list of required linker flags (excluding -l and -L).
9299 BLAS_LIBRARIES
9301 uncached list of libraries (using full path name) to link
9302 against to use BLAS (may be empty if compiler implicitly links
9303 BLAS)
9304 BLAS95_LIBRARIES
9306 uncached list of libraries (using full path name) to link
9307 against to use BLAS95 interface
9308 BLAS95_FOUND
9310 library implementing the BLAS95 interface is found
9311 BLAS/LAPACK Vendors
9313 Generic
9314 Generic reference implementation
9315 ACML, ACML_MP, ACML_GPU
9317 AMD Core Math Library
9318 Apple, NAS
9320 Apple BLAS (Accelerate), and Apple NAS (vecLib)
9321 Arm, Arm_mp, Arm_ilp64, Arm_ilp64_mp
9323 New in version 3.18.
9324 Arm Performance Libraries
9327 ATLAS Automatically Tuned Linear Algebra Software
9329 CXML, DXML
9331 Compaq/Digital Extended Math Library
9332 EML, EML_mt
9334 New in version 3.20.
9335 Elbrus Math Library
9338 FLAME New in version 3.11.
9340 BLIS Framework
9343 FlexiBLAS
9345 New in version 3.19.
9346 Fujitsu_SSL2, Fujitsu_SSL2BLAMP, Fujitsu_SSL2SVE, Fujitsu_SSL2BLAMPSVE
9349 New in version 3.20.
9350 Fujitsu SSL2 serial and parallel blas/lapack with SVE instruc‐
9353 tions
9354 Goto GotoBLAS
9356 IBMESSL, IBMESSL_SMP
9358 IBM Engineering and Scientific Subroutine Library
9359 Intel Intel MKL 32 bit and 64 bit obsolete versions
9361 Intel10_32
9363 Intel MKL v10 32 bit, threaded code
9364 Intel10_64lp
9366 Intel MKL v10+ 64 bit, threaded code, lp64 model
9367 Intel10_64lp_seq
9369 Intel MKL v10+ 64 bit, sequential code, lp64 model
9370 Intel10_64ilp
9372 New in version 3.13.
9373 Intel MKL v10+ 64 bit, threaded code, ilp64 model
9376 Intel10_64ilp_seq
9378 New in version 3.13.
9379 Intel MKL v10+ 64 bit, sequential code, ilp64 model
9382 Intel10_64_dyn
9384 New in version 3.17.
9385 Intel MKL v10+ 64 bit, single dynamic library
9388 NVHPC New in version 3.21.
9390 NVIDIA HPC SDK
9393 OpenBLAS
9395 New in version 3.6.
9396 PhiPACK
9399 Portable High Performance ANSI C (PHiPAC)
9400 SCSL, SCSL_mp
9402 Scientific Computing Software Library
9403 SGIMATH
9405 SGI Scientific Mathematical Library
9406 SunPerf
9408 Sun Performance Library
9409 Intel MKL
9411 To use the Intel MKL implementation of BLAS, a project must enable at
9412 least one of the C or CXX languages. Set BLA_VENDOR to an Intel MKL
9413 variant either on the command-line as -DBLA_VENDOR=Intel10_64lp or in
9414 project code:
9415 set(BLA_VENDOR Intel10_64lp)
9417 find_package(BLAS)
9418 In order to build a project using Intel MKL, and end user must first
9420 establish an Intel MKL environment:
9421 Intel oneAPI
9423 Source the full Intel environment script:
9424 . /opt/intel/oneapi/setvars.sh
9426 Or, source the MKL component environment script:
9428 . /opt/intel/oneapi/mkl/latest/env/vars.sh
9430 Intel Classic
9432 Source the full Intel environment script:
9433 . /opt/intel/bin/compilervars.sh intel64
9435 Or, source the MKL component environment script:
9437 . /opt/intel/mkl/bin/mklvars.sh intel64
9439 The above environment scripts set the MKLROOT environment variable to
9441 the top of the MKL installation. They also add the location of the
9442 runtime libraries to the dynamic library loader environment variable
9443 for your platform (e.g. LD_LIBRARY_PATH). This is necessary for pro‐
9444 grams linked against MKL to run.
9445 NOTE:
9447 As of Intel oneAPI 2021.2, loading only the MKL component does not
9448 make all of its dependencies available. In particular, the iomp5
9449 library must be available separately, or provided by also loading
9450 the compiler component environment:
9451 . /opt/intel/oneapi/compiler/latest/env/vars.sh
9453 FindBoost
9455 Find Boost include dirs and libraries
9456 Use this module by invoking find_package() with the form:
9458 find_package(Boost
9460 [version] [EXACT] # Minimum or EXACT version e.g. 1.67.0
9461 [REQUIRED] # Fail with error if Boost is not found
9462 [COMPONENTS <libs>...] # Boost libraries by their canonical name
9463 # e.g. "date_time" for "libboost_date_time"
9464 [OPTIONAL_COMPONENTS <libs>...]
9465 # Optional Boost libraries by their canonical name)
9466 ) # e.g. "date_time" for "libboost_date_time"
9467 This module finds headers and requested component libraries OR a CMake
9469 package configuration file provided by a "Boost CMake" build. For the
9470 latter case skip to the Boost CMake section below.
9471 New in version 3.7: bzip2 and zlib components (Windows only).
9473 New in version 3.11: The OPTIONAL_COMPONENTS option.
9476 New in version 3.13: stacktrace_* components.
9479 New in version 3.19: bzip2 and zlib components on all platforms.
9482 Result Variables
9485 This module defines the following variables:
9486 Boost_FOUND
9488 True if headers and requested libraries were found.
9489 Boost_INCLUDE_DIRS
9491 Boost include directories.
9492 Boost_LIBRARY_DIRS
9494 Link directories for Boost libraries.
9495 Boost_LIBRARIES
9497 Boost component libraries to be linked.
9498 Boost_<COMPONENT>_FOUND
9500 True if component <COMPONENT> was found (<COMPONENT> name is up‐
9501 per-case).
9502 Boost_<COMPONENT>_LIBRARY
9504 Libraries to link for component <COMPONENT> (may include tar‐
9505 get_link_libraries() debug/optimized keywords).
9506 Boost_VERSION_MACRO
9508 BOOST_VERSION value from boost/version.hpp.
9509 Boost_VERSION_STRING
9511 Boost version number in X.Y.Z format.
9512 Boost_VERSION
9514 Boost version number in X.Y.Z format (same as Boost_VER‐
9515 SION_STRING).
9516 Changed in version 3.15: In previous CMake versions, this vari‐
9518 able used the raw version string from the Boost header (same as
9519 Boost_VERSION_MACRO). See policy CMP0093.
9520 Boost_LIB_VERSION
9523 Version string appended to library filenames.
9524 Boost_VERSION_MAJOR, Boost_MAJOR_VERSION
9526 Boost major version number (X in X.Y.Z).
9527 Boost_VERSION_MINOR, Boost_MINOR_VERSION
9529 Boost minor version number (Y in X.Y.Z).
9530 Boost_VERSION_PATCH, Boost_SUBMINOR_VERSION
9532 Boost subminor version number (Z in X.Y.Z).
9533 Boost_VERSION_COUNT
9535 Amount of version components (3).
9536 Boost_LIB_DIAGNOSTIC_DEFINITIONS (Windows-specific)
9538 Pass to add_definitions() to have diagnostic information about
9539 Boost's automatic linking displayed during compilation
9540 New in version 3.15: The Boost_VERSION_<PART> variables.
9542 Cache variables
9545 Search results are saved persistently in CMake cache entries:
9546 Boost_INCLUDE_DIR
9548 Directory containing Boost headers.
9549 Boost_LIBRARY_DIR_RELEASE
9551 Directory containing release Boost libraries.
9552 Boost_LIBRARY_DIR_DEBUG
9554 Directory containing debug Boost libraries.
9555 Boost_<COMPONENT>_LIBRARY_DEBUG
9557 Component <COMPONENT> library debug variant.
9558 Boost_<COMPONENT>_LIBRARY_RELEASE
9560 Component <COMPONENT> library release variant.
9561 New in version 3.3: Per-configuration variables Boost_LIBRARY_DIR_RE‐
9563 LEASE and Boost_LIBRARY_DIR_DEBUG.
9564 Hints
9567 This module reads hints about search locations from variables:
9568 BOOST_ROOT, BOOSTROOT
9570 Preferred installation prefix.
9571 BOOST_INCLUDEDIR
9573 Preferred include directory e.g. <prefix>/include.
9574 BOOST_LIBRARYDIR
9576 Preferred library directory e.g. <prefix>/lib.
9577 Boost_NO_SYSTEM_PATHS
9579 Set to ON to disable searching in locations not specified by
9580 these hint variables. Default is OFF.
9581 Boost_ADDITIONAL_VERSIONS
9583 List of Boost versions not known to this module. (Boost install
9584 locations may contain the version).
9585 Users may set these hints or results as CACHE entries. Projects should
9587 not read these entries directly but instead use the above result vari‐
9588 ables. Note that some hint names start in upper-case BOOST. One may
9589 specify these as environment variables if they are not specified as
9590 CMake variables or cache entries.
9591 This module first searches for the Boost header files using the above
9593 hint variables (excluding BOOST_LIBRARYDIR) and saves the result in
9594 Boost_INCLUDE_DIR. Then it searches for requested component libraries
9595 using the above hints (excluding BOOST_INCLUDEDIR and Boost_ADDI‐
9596 TIONAL_VERSIONS), "lib" directories near Boost_INCLUDE_DIR, and the li‐
9597 brary name configuration settings below. It saves the library directo‐
9598 ries in Boost_LIBRARY_DIR_DEBUG and Boost_LIBRARY_DIR_RELEASE and indi‐
9599 vidual library locations in Boost_<COMPONENT>_LIBRARY_DEBUG and
9600 Boost_<COMPONENT>_LIBRARY_RELEASE. When one changes settings used by
9601 previous searches in the same build tree (excluding environment vari‐
9602 ables) this module discards previous search results affected by the
9603 changes and searches again.
9604 Imported Targets
9606 New in version 3.5.
9607 This module defines the following IMPORTED targets:
9610 Boost::boost
9612 Target for header-only dependencies. (Boost include directory).
9613 Boost::headers
9615 New in version 3.15: Alias for Boost::boost.
9616 Boost::<component>
9619 Target for specific component dependency (shared or static li‐
9620 brary); <component> name is lower-case.
9621 Boost::diagnostic_definitions
9623 Interface target to enable diagnostic information about Boost's
9624 automatic linking during compilation (adds -DBOOST_LIB_DIAGNOS‐
9625 TIC).
9626 Boost::disable_autolinking
9628 Interface target to disable automatic linking with MSVC (adds
9629 -DBOOST_ALL_NO_LIB).
9630 Boost::dynamic_linking
9632 Interface target to enable dynamic linking with MSVC (adds
9633 -DBOOST_ALL_DYN_LINK).
9634 Implicit dependencies such as Boost::filesystem requiring Boost::system
9636 will be automatically detected and satisfied, even if system is not
9637 specified when using find_package() and if Boost::system is not added
9638 to target_link_libraries(). If using Boost::thread, then
9639 Threads::Threads will also be added automatically.
9640 It is important to note that the imported targets behave differently
9642 than variables created by this module: multiple calls to find_pack‐
9643 age(Boost) in the same directory or sub-directories with different op‐
9644 tions (e.g. static or shared) will not override the values of the tar‐
9645 gets created by the first call.
9646 Other Variables
9648 Boost libraries come in many variants encoded in their file name.
9649 Users or projects may tell this module which variant to find by setting
9650 variables:
9651 Boost_USE_DEBUG_LIBS
9653 New in version 3.10.
9654 Set to ON or OFF to specify whether to search and use the debug
9657 libraries. Default is ON.
9658 Boost_USE_RELEASE_LIBS
9660 New in version 3.10.
9661 Set to ON or OFF to specify whether to search and use the re‐
9664 lease libraries. Default is ON.
9665 Boost_USE_MULTITHREADED
9667 Set to OFF to use the non-multithreaded libraries ("mt" tag).
9668 Default is ON.
9669 Boost_USE_STATIC_LIBS
9671 Set to ON to force the use of the static libraries. Default is
9672 OFF.
9673 Boost_USE_STATIC_RUNTIME
9675 Set to ON or OFF to specify whether to use libraries linked
9676 statically to the C++ runtime ("s" tag). Default is platform
9677 dependent.
9678 Boost_USE_DEBUG_RUNTIME
9680 Set to ON or OFF to specify whether to use libraries linked to
9681 the MS debug C++ runtime ("g" tag). Default is ON.
9682 Boost_USE_DEBUG_PYTHON
9684 Set to ON to use libraries compiled with a debug Python build
9685 ("y" tag). Default is OFF.
9686 Boost_USE_STLPORT
9688 Set to ON to use libraries compiled with STLPort ("p" tag). De‐
9689 fault is OFF.
9690 Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
9692 Set to ON to use libraries compiled with STLPort deprecated "na‐
9693 tive iostreams" ("n" tag). Default is OFF.
9694 Boost_COMPILER
9696 Set to the compiler-specific library suffix (e.g. -gcc43). De‐
9697 fault is auto-computed for the C++ compiler in use.
9698 Changed in version 3.9: A list may be used if multiple compati‐
9700 ble suffixes should be tested for, in decreasing order of pref‐
9701 erence.
9702 Boost_LIB_PREFIX
9705 New in version 3.18.
9706 Set to the platform-specific library name prefix (e.g. lib) used
9709 by Boost static libs. This is needed only on platforms where
9710 CMake does not know the prefix by default.
9711 Boost_ARCHITECTURE
9713 New in version 3.13.
9714 Set to the architecture-specific library suffix (e.g. -x64).
9717 Default is auto-computed for the C++ compiler in use.
9718 Boost_THREADAPI
9720 Suffix for thread component library name, such as pthread or
9721 win32. Names with and without this suffix will both be tried.
9722 Boost_NAMESPACE
9724 Alternate namespace used to build boost with e.g. if set to my‐
9725 boost, will search for myboost_thread instead of boost_thread.
9726 Other variables one may set to control this module are:
9728 Boost_DEBUG
9730 Set to ON to enable debug output from FindBoost. Please enable
9731 this before filing any bug report.
9732 Boost_REALPATH
9734 Set to ON to resolve symlinks for discovered libraries to assist
9735 with packaging. For example, the "system" component library may
9736 be resolved to /usr/lib/libboost_system.so.1.67.0 instead of
9737 /usr/lib/libboost_system.so. This does not affect linking and
9738 should not be enabled unless the user needs this information.
9739 Boost_LIBRARY_DIR
9741 Default value for Boost_LIBRARY_DIR_RELEASE and Boost_LI‐
9742 BRARY_DIR_DEBUG.
9743 Boost_NO_WARN_NEW_VERSIONS
9745 New in version 3.20.
9746 Set to ON to suppress the warning about unknown dependencies for
9749 new Boost versions.
9750 On Visual Studio and Borland compilers Boost headers request automatic
9752 linking to corresponding libraries. This requires matching libraries
9753 to be linked explicitly or available in the link library search path.
9754 In this case setting Boost_USE_STATIC_LIBS to OFF may not achieve dy‐
9755 namic linking. Boost automatic linking typically requests static li‐
9756 braries with a few exceptions (such as Boost.Python). Use:
9757 add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})
9759 to ask Boost to report information about automatic linking requests.
9761 Examples
9763 Find Boost headers only:
9764 find_package(Boost 1.36.0)
9766 if(Boost_FOUND)
9767 include_directories(${Boost_INCLUDE_DIRS})
9768 add_executable(foo foo.cc)
9769 endif()
9770 Find Boost libraries and use imported targets:
9772 find_package(Boost 1.56 REQUIRED COMPONENTS
9774 date_time filesystem iostreams)
9775 add_executable(foo foo.cc)
9776 target_link_libraries(foo Boost::date_time Boost::filesystem
9777 Boost::iostreams)
9778 Find Boost Python 3.6 libraries and use imported targets:
9780 find_package(Boost 1.67 REQUIRED COMPONENTS
9782 python36 numpy36)
9783 add_executable(foo foo.cc)
9784 target_link_libraries(foo Boost::python36 Boost::numpy36)
9785 Find Boost headers and some static (release only) libraries:
9787 set(Boost_USE_STATIC_LIBS ON) # only find static libs
9789 set(Boost_USE_DEBUG_LIBS OFF) # ignore debug libs and
9790 set(Boost_USE_RELEASE_LIBS ON) # only find release libs
9791 set(Boost_USE_MULTITHREADED ON)
9792 set(Boost_USE_STATIC_RUNTIME OFF)
9793 find_package(Boost 1.66.0 COMPONENTS date_time filesystem system ...)
9794 if(Boost_FOUND)
9795 include_directories(${Boost_INCLUDE_DIRS})
9796 add_executable(foo foo.cc)
9797 target_link_libraries(foo ${Boost_LIBRARIES})
9798 endif()
9799 Boost CMake
9801 If Boost was built using the boost-cmake project or from Boost 1.70.0
9802 on it provides a package configuration file for use with find_package's
9803 config mode. This module looks for the package configuration file
9804 called BoostConfig.cmake or boost-config.cmake and stores the result in
9805 CACHE entry Boost_DIR. If found, the package configuration file is
9806 loaded and this module returns with no further action. See documenta‐
9807 tion of the Boost CMake package configuration for details on what it
9808 provides.
9809 Set Boost_NO_BOOST_CMAKE to ON, to disable the search for boost-cmake.
9811 FindBullet
9813 Try to find the Bullet physics engine
9814 This module defines the following variables
9816 BULLET_FOUND - Was bullet found
9818 BULLET_INCLUDE_DIRS - the Bullet include directories
9819 BULLET_LIBRARIES - Link to this, by default it includes
9820 all bullet components (Dynamics,
9821 Collision, LinearMath, & SoftBody)
9822 This module accepts the following variables
9824 BULLET_ROOT - Can be set to bullet install path or Windows build path
9826 FindBZip2
9828 Try to find BZip2
9829 IMPORTED Targets
9831 New in version 3.12.
9832 This module defines IMPORTED target BZip2::BZip2, if BZip2 has been
9835 found.
9836 Result Variables
9838 This module defines the following variables:
9839 BZIP2_FOUND
9841 system has BZip2
9842 BZIP2_INCLUDE_DIRS
9844 New in version 3.12: the BZip2 include directories
9845 BZIP2_LIBRARIES
9848 Link these to use BZip2
9849 BZIP2_NEED_PREFIX
9851 this is set if the functions are prefixed with BZ2_
9852 BZIP2_VERSION_STRING
9854 the version of BZip2 found
9855 Cache variables
9857 The following cache variables may also be set:
9858 BZIP2_INCLUDE_DIR
9860 the BZip2 include directory
9861 FindCABLE
9863 Find CABLE
9864 This module finds if CABLE is installed and determines where the in‐
9866 clude files and libraries are. This code sets the following variables:
9867 CABLE the path to the cable executable
9869 CABLE_TCL_LIBRARY the path to the Tcl wrapper library
9870 CABLE_INCLUDE_DIR the path to the include directory
9871 To build Tcl wrappers, you should add shared library and link it to
9873 ${CABLE_TCL_LIBRARY}. You should also add ${CABLE_INCLUDE_DIR} as an
9874 include directory.
9875 FindCoin3D
9877 Find Coin3D (Open Inventor)
9878 Coin3D is an implementation of the Open Inventor API. It provides data
9880 structures and algorithms for 3D visualization.
9881 This module defines the following variables
9883 COIN3D_FOUND - system has Coin3D - Open Inventor
9885 COIN3D_INCLUDE_DIRS - where the Inventor include directory can be found
9886 COIN3D_LIBRARIES - Link to this to use Coin3D
9887 FindCUDAToolkit
9889 New in version 3.17.
9890 This script locates the NVIDIA CUDA toolkit and the associated li‐
9893 braries, but does not require the CUDA language be enabled for a given
9894 project. This module does not search for the NVIDIA CUDA Samples.
9895 New in version 3.19: QNX support.
9897 Search Behavior
9900 The CUDA Toolkit search behavior uses the following order:
9901 1. If the CUDA language has been enabled we will use the directory con‐
9903 taining the compiler as the first search location for nvcc.
9904 2. If the CUDAToolkit_ROOT cmake configuration variable (e.g., -DCUDA‐
9906 Toolkit_ROOT=/some/path) or environment variable is defined, it will
9907 be searched. If both an environment variable and a configuration
9908 variable are specified, the configuration variable takes precedence.
9909 The directory specified here must be such that the executable nvcc
9911 or the appropriate version.txt file can be found underneath the
9912 specified directory.
9913 3. If the CUDA_PATH environment variable is defined, it will be
9915 searched for nvcc.
9916 4. The user's path is searched for nvcc using find_program(). If this
9918 is found, no subsequent search attempts are performed. Users are
9919 responsible for ensuring that the first nvcc to show up in the path
9920 is the desired path in the event that multiple CUDA Toolkits are in‐
9921 stalled.
9922 5. On Unix systems, if the symbolic link /usr/local/cuda exists, this
9924 is used. No subsequent search attempts are performed. No default
9925 symbolic link location exists for the Windows platform.
9926 6. The platform specific default install locations are searched. If
9928 exactly one candidate is found, this is used. The default CUDA
9929 Toolkit install locations searched are:
9930 ┌───────────┬────────────────────────────┐
9932 │Platform │ Search Pattern │
9933 ├───────────┼────────────────────────────┤
9934 │macOS │ /Developer/NVIDIA/CUDA-X.Y │
9935 ├───────────┼────────────────────────────┤
9936 │Other Unix │ /usr/local/cuda-X.Y │
9937 ├───────────┼────────────────────────────┤
9938 │Windows │ C:\Program Files\NVIDIA │
9939 │ │ GPU Computing Tool‐ │
9940 │ │ kit\CUDA\vX.Y │
9941 └───────────┴────────────────────────────┘
9942 Where X.Y would be a specific version of the CUDA Toolkit, such as
9944 /usr/local/cuda-9.0 or C:\Program Files\NVIDIA GPU Computing Tool‐
9945 kit\CUDA\v9.0
9946 NOTE:
9948 When multiple CUDA Toolkits are installed in the default location
9949 of a system (e.g., both /usr/local/cuda-9.0 and /usr/lo‐
9950 cal/cuda-10.0 exist but the /usr/local/cuda symbolic link does
9951 not exist), this package is marked as not found.
9952 There are too many factors involved in making an automatic deci‐
9954 sion in the presence of multiple CUDA Toolkits being installed.
9955 In this situation, users are encouraged to either (1) set CUDA‐
9956 Toolkit_ROOT [22mor (2) ensure that the correct nvcc executable shows
9957 up in $PATH for find_program() to find.
9958 Arguments
9960 [<version>]
9961 The [<version>] argument requests a version with which the pack‐
9962 age found should be compatible. See find_package version format
9963 for more details.
9964 Options
9966 REQUIRED
9967 If specified, configuration will error if a suitable CUDA Tool‐
9968 kit is not found.
9969 QUIET If specified, the search for a suitable CUDA Toolkit will not
9971 produce any messages.
9972 EXACT If specified, the CUDA Toolkit is considered found only if the
9974 exact VERSION specified is recovered.
9975 Imported targets
9977 An imported target named CUDA::toolkit is provided.
9978 This module defines IMPORTED targets for each of the following li‐
9980 braries that are part of the CUDAToolkit:
9981 • CUDA Runtime Library
9983 • CUDA Driver Library
9985 • cuBLAS
9987 • cuFFT
9989 • cuRAND
9991 • cuSOLVER
9993 • cuSPARSE
9995 • cuPTI
9997 • NPP
9999 • nvBLAS
10001 • nvGRAPH
10003 • nvJPEG
10005 • nvidia-ML
10007 • nvRTC
10009 • nvToolsExt
10011 • OpenCL
10013 • cuLIBOS
10015 CUDA Runtime Library
10017 The CUDA Runtime library (cudart) are what most applications will typi‐
10018 cally need to link against to make any calls such as cudaMalloc, and
10019 cudaFree.
10020 Targets Created:
10022 • CUDA::cudart
10024 • CUDA::cudart_static
10026 CUDA Driver Library
10028 The CUDA Driver library (cuda) are used by applications that use calls
10029 such as cuMemAlloc, and cuMemFree. This is generally used by advanced
10030 Targets Created:
10032 • CUDA::cuda_driver
10034 • CUDA::cuda_driver
10036 cuBLAS
10038 The cuBLAS library.
10039 Targets Created:
10041 • CUDA::cublas
10043 • CUDA::cublas_static
10045 • CUDA::cublasLt starting in CUDA 10.1
10047 • CUDA::cublasLt_static starting in CUDA 10.1
10049 cuFFT
10051 The cuFFT library.
10052 Targets Created:
10054 • CUDA::cufft
10056 • CUDA::cufftw
10058 • CUDA::cufft_static
10060 • CUDA::cufftw_static
10062 cuRAND
10064 The cuRAND library.
10065 Targets Created:
10067 • CUDA::curand
10069 • CUDA::curand_static
10071 cuSOLVER
10073 The cuSOLVER library.
10074 Targets Created:
10076 • CUDA::cusolver
10078 • CUDA::cusolver_static
10080 cuSPARSE
10082 The cuSPARSE library.
10083 Targets Created:
10085 • CUDA::cusparse
10087 • CUDA::cusparse_static
10089 cupti
10091 The NVIDIA CUDA Profiling Tools Interface.
10092 Targets Created:
10094 • CUDA::cupti
10096 • CUDA::cupti_static
10098 NPP
10100 The NPP libraries.
10101 Targets Created:
10103 • nppc:
10105 • CUDA::nppc
10107 • CUDA::nppc_static
10109 • nppial: Arithmetic and logical operation functions in nppi_arith‐
10111 metic_and_logical_operations.h
10112 • CUDA::nppial
10114 • CUDA::nppial_static
10116 • nppicc: Color conversion and sampling functions in nppi_color_conver‐
10118 sion.h
10119 • CUDA::nppicc
10121 • CUDA::nppicc_static
10123 • nppicom: JPEG compression and decompression functions in nppi_com‐
10125 pression_functions.h Removed starting in CUDA 11.0, use nvJPEG in‐
10126 stead.
10127 • CUDA::nppicom
10129 • CUDA::nppicom_static
10131 • nppidei: Data exchange and initialization functions in nppi_data_ex‐
10133 change_and_initialization.h
10134 • CUDA::nppidei
10136 • CUDA::nppidei_static
10138 • nppif: Filtering and computer vision functions in nppi_filter_func‐
10140 tions.h
10141 • CUDA::nppif
10143 • CUDA::nppif_static
10145 • nppig: Geometry transformation functions found in nppi_geome‐
10147 try_transforms.h
10148 • CUDA::nppig
10150 • CUDA::nppig_static
10152 • nppim: Morphological operation functions found in nppi_morphologi‐
10154 cal_operations.h
10155 • CUDA::nppim
10157 • CUDA::nppim_static
10159 • nppist: Statistics and linear transform in nppi_statistics_func‐
10161 tions.h and nppi_linear_transforms.h
10162 • CUDA::nppist
10164 • CUDA::nppist_static
10166 • nppisu: Memory support functions in nppi_support_functions.h
10168 • CUDA::nppisu
10170 • CUDA::nppisu_static
10172 • nppitc: Threshold and compare operation functions in nppi_thresh‐
10174 old_and_compare_operations.h
10175 • CUDA::nppitc
10177 • CUDA::nppitc_static
10179 • npps:
10181 • CUDA::npps
10183 • CUDA::npps_static
10185 nvBLAS
10187 The nvBLAS libraries. This is a shared library only.
10188 Targets Created:
10190 • CUDA::nvblas
10192 nvGRAPH
10194 The nvGRAPH library. Removed starting in CUDA 11.0
10195 Targets Created:
10197 • CUDA::nvgraph
10199 • CUDA::nvgraph_static
10201 nvJPEG
10203 The nvJPEG library. Introduced in CUDA 10.
10204 Targets Created:
10206 • CUDA::nvjpeg
10208 • CUDA::nvjpeg_static
10210 nvRTC
10212 The nvRTC (Runtime Compilation) library. This is a shared library
10213 only.
10214 Targets Created:
10216 • CUDA::nvrtc
10218 nvidia-ML
10220 The NVIDIA Management Library. This is a shared library only.
10221 Targets Created:
10223 • CUDA::nvml
10225 nvToolsExt
10227 The NVIDIA Tools Extension. This is a shared library only.
10228 Targets Created:
10230 • CUDA::nvToolsExt
10232 OpenCL
10234 The NVIDIA OpenCL Library. This is a shared library only.
10235 Targets Created:
10237 • CUDA::OpenCL
10239 cuLIBOS
10241 The cuLIBOS library is a backend thread abstraction layer library which
10242 is static only. The CUDA::cublas_static, CUDA::cusparse_static,
10243 CUDA::cufft_static, CUDA::curand_static, and (when implemented) NPP li‐
10244 braries all automatically have this dependency linked.
10245 Target Created:
10247 • CUDA::culibos
10249 Note: direct usage of this target by consumers should not be necessary.
10251 Result variables
10253 CUDAToolkit_FOUND
10254 A boolean specifying whether or not the CUDA Toolkit was found.
10255 CUDAToolkit_VERSION
10257 The exact version of the CUDA Toolkit found (as reported by nvcc
10258 --version or version.txt).
10259 CUDAToolkit_VERSION_MAJOR
10261 The major version of the CUDA Toolkit.
10262 CUDAToolkit_VERSION_MINOR
10264 The minor version of the CUDA Toolkit.
10265 CUDAToolkit_VERSION_PATCH
10267 The patch version of the CUDA Toolkit.
10268 CUDAToolkit_BIN_DIR
10270 The path to the CUDA Toolkit library directory that contains the
10271 CUDA executable nvcc.
10272 CUDAToolkit_INCLUDE_DIRS
10274 The path to the CUDA Toolkit include folder containing the
10275 header files required to compile a project linking against CUDA.
10276 CUDAToolkit_LIBRARY_DIR
10278 The path to the CUDA Toolkit library directory that contains the
10279 CUDA Runtime library cudart.
10280 CUDAToolkit_LIBRARY_ROOT
10282 New in version 3.18.
10283 The path to the CUDA Toolkit directory containing the nvvm di‐
10286 rectory and version.txt.
10287 CUDAToolkit_TARGET_DIR
10289 The path to the CUDA Toolkit directory including the target ar‐
10290 chitecture when cross-compiling. When not cross-compiling this
10291 will be equivalent to the parent directory of CUDA‐
10292 Toolkit_BIN_DIR.
10293 CUDAToolkit_NVCC_EXECUTABLE
10295 The path to the NVIDIA CUDA compiler nvcc. Note that this path
10296 may not be the same as CMAKE_CUDA_COMPILER. nvcc must be found
10297 to determine the CUDA Toolkit version as well as determining
10298 other features of the Toolkit. This variable is set for the
10299 convenience of modules that depend on this one.
10300 FindCups
10302 Find the Common UNIX Printing System (CUPS).
10303 Set CUPS_REQUIRE_IPP_DELETE_ATTRIBUTE to TRUE if you need a version
10305 which features this function (i.e. at least 1.1.19)
10306 Imported targets
10308 New in version 3.15.
10309 This module defines IMPORTED target Cups::Cups, if Cups has been found.
10312 Result variables
10314 This module will set the following variables in your project:
10315 CUPS_FOUND
10317 true if CUPS headers and libraries were found
10318 CUPS_INCLUDE_DIRS
10320 the directory containing the Cups headers
10321 CUPS_LIBRARIES
10323 the libraries to link against to use CUPS.
10324 CUPS_VERSION_STRING
10326 the version of CUPS found (since CMake 2.8.8)
10327 Cache variables
10329 The following cache variables may also be set:
10330 CUPS_INCLUDE_DIR
10332 the directory containing the Cups headers
10333 FindCURL
10335 Find the native CURL headers and libraries.
10336 New in version 3.14: This module accept optional COMPONENTS to check
10338 supported features and protocols:
10339 PROTOCOLS: ICT FILE FTP FTPS GOPHER HTTP HTTPS IMAP IMAPS LDAP LDAPS POP3
10342 POP3S RTMP RTSP SCP SFTP SMB SMBS SMTP SMTPS TELNET TFTP
10343 FEATURES: SSL IPv6 UnixSockets libz AsynchDNS IDN GSS-API PSL SPNEGO
10344 Kerberos NTLM NTLM_WB TLS-SRP HTTP2 HTTPS-proxy
10345 IMPORTED Targets
10347 New in version 3.12.
10348 This module defines IMPORTED target CURL::libcurl, if curl has been
10351 found.
10352 Result Variables
10354 This module defines the following variables:
10355 CURL_FOUND
10357 "True" if curl found.
10358 CURL_INCLUDE_DIRS
10360 where to find curl/curl.h, etc.
10361 CURL_LIBRARIES
10363 List of libraries when using curl.
10364 CURL_VERSION_STRING
10366 The version of curl found.
10367 New in version 3.13: Debug and Release variants are found separately.
10369 CURL CMake
10372 New in version 3.17.
10373 If CURL was built using the CMake buildsystem then it provides its own
10376 CURLConfig.cmake file for use with the find_package() command's config
10377 mode. This module looks for this file and, if found, returns its re‐
10378 sults with no further action.
10379 Set CURL_NO_CURL_CMAKE to ON to disable this search.
10381 FindCurses
10383 Find the curses or ncurses include file and library.
10384 Result Variables
10386 This module defines the following variables:
10387 CURSES_FOUND
10389 True if Curses is found.
10390 CURSES_INCLUDE_DIRS
10392 The include directories needed to use Curses.
10393 CURSES_LIBRARIES
10395 The libraries needed to use Curses.
10396 CURSES_CFLAGS
10398 New in version 3.16.
10399 Parameters which ought be given to C/C++ compilers when using
10402 Curses.
10403 CURSES_HAVE_CURSES_H
10405 True if curses.h is available.
10406 CURSES_HAVE_NCURSES_H
10408 True if ncurses.h is available.
10409 CURSES_HAVE_NCURSES_NCURSES_H
10411 True if ncurses/ncurses.h is available.
10412 CURSES_HAVE_NCURSES_CURSES_H
10414 True if ncurses/curses.h is available.
10415 Set CURSES_NEED_NCURSES to TRUE before the find_package(Curses) call if
10417 NCurses functionality is required.
10418 New in version 3.10: Set CURSES_NEED_WIDE to TRUE before the find_pack‐
10420 age(Curses) call if unicode functionality is required.
10421 Backward Compatibility
10424 The following variable are provided for backward compatibility:
10425 CURSES_INCLUDE_DIR
10427 Path to Curses include. Use CURSES_INCLUDE_DIRS instead.
10428 CURSES_LIBRARY
10430 Path to Curses library. Use CURSES_LIBRARIES instead.
10431 FindCVS
10433 Find the Concurrent Versions System (CVS).
10434 The module defines the following variables:
10436 CVS_EXECUTABLE - path to cvs command line client
10438 CVS_FOUND - true if the command line client was found
10439 Example usage:
10441 find_package(CVS)
10443 if(CVS_FOUND)
10444 message("CVS found: ${CVS_EXECUTABLE}")
10445 endif()
10446 FindCxxTest
10448 Find CxxTest unit testing framework.
10449 Find the CxxTest suite and declare a helper macro for creating unit
10451 tests and integrating them with CTest. For more details on CxxTest see
10452 http://cxxtest.tigris.org
10453 INPUT Variables
10455 CXXTEST_USE_PYTHON [deprecated since 1.3]
10457 Only used in the case both Python & Perl
10458 are detected on the system to control
10459 which CxxTest code generator is used.
10460 Valid only for CxxTest version 3.
10461 NOTE: In older versions of this Find Module,
10463 this variable controlled if the Python test
10464 generator was used instead of the Perl one,
10465 regardless of which scripting language the
10466 user had installed.
10467 CXXTEST_TESTGEN_ARGS (since CMake 2.8.3)
10469 Specify a list of options to pass to the CxxTest code
10470 generator. If not defined, --error-printer is
10471 passed.
10472 OUTPUT Variables
10474 CXXTEST_FOUND
10476 True if the CxxTest framework was found
10477 CXXTEST_INCLUDE_DIRS
10478 Where to find the CxxTest include directory
10479 CXXTEST_PERL_TESTGEN_EXECUTABLE
10480 The perl-based test generator
10481 CXXTEST_PYTHON_TESTGEN_EXECUTABLE
10482 The python-based test generator
10483 CXXTEST_TESTGEN_EXECUTABLE (since CMake 2.8.3)
10484 The test generator that is actually used (chosen using user preferences
10485 and interpreters found in the system)
10486 CXXTEST_TESTGEN_INTERPRETER (since CMake 2.8.3)
10487 The full path to the Perl or Python executable on the system, on
10488 platforms where the script cannot be executed using its shebang line.
10489 MACROS for optional use by CMake users:
10491 CXXTEST_ADD_TEST(<test_name> <gen_source_file> <input_files_to_testgen...>)
10493 Creates a CxxTest runner and adds it to the CTest testing suite
10494 Parameters:
10495 test_name The name of the test
10496 gen_source_file The generated source filename to be
10497 generated by CxxTest
10498 input_files_to_testgen The list of header files containing the
10499 CxxTest::TestSuite's to be included in
10500 this runner
10501 #==============
10503 Example Usage:
10504 find_package(CxxTest)
10506 if(CXXTEST_FOUND)
10507 include_directories(${CXXTEST_INCLUDE_DIR})
10508 enable_testing()
10509 CXXTEST_ADD_TEST(unittest_foo foo_test.cc
10511 ${CMAKE_CURRENT_SOURCE_DIR}/foo_test.h)
10512 target_link_libraries(unittest_foo foo) # as needed
10513 endif()
10514 This will (if CxxTest is found):
10516 1. Invoke the testgen executable to autogenerate foo_test.cc in the
10517 binary tree from "foo_test.h" in the current source directory.
10518 2. Create an executable and test called unittest_foo.
10519 #=============
10521 Example foo_test.h:
10522 #include <cxxtest/TestSuite.h>
10524 class MyTestSuite : public CxxTest::TestSuite
10526 {
10527 public:
10528 void testAddition( void )
10529 {
10530 TS_ASSERT( 1 + 1 > 1 );
10531 TS_ASSERT_EQUALS( 1 + 1, 2 );
10532 }
10533 };
10534 FindCygwin
10536 Find Cygwin, a POSIX-compatible environment that runs natively on Mi‐
10537 crosoft Windows
10538 FindDart
10540 Find DART
10541 This module looks for the dart testing software and sets DART_ROOT to
10543 point to where it found it.
10544 FindDCMTK
10546 Find DICOM ToolKit (DCMTK) libraries and applications
10547 The module defines the following variables:
10549 DCMTK_INCLUDE_DIRS - Directories to include to use DCMTK
10551 DCMTK_LIBRARIES - Files to link against to use DCMTK
10552 DCMTK_FOUND - If false, don't try to use DCMTK
10553 DCMTK_DIR - (optional) Source directory for DCMTK
10554 Compatibility
10556 This module is able to find a version of DCMTK that does or does not
10557 export a DCMTKConfig.cmake file. It applies a two step process:
10558 • Step 1: Attempt to find DCMTK version providing a DCMTKConfig.cmake
10560 file.
10561 • Step 2: If step 1 failed, rely on FindDCMTK.cmake to set DCMTK_*
10563 variables details below.
10564 Recent DCMTK provides a DCMTKConfig.cmake package configuration file.
10566 To exclusively use the package configuration file (recommended when
10567 possible), pass the NO_MODULE option to find_package(). For example,
10568 find_package(DCMTK NO_MODULE). This requires official DCMTK snapshot
10569 3.6.1_20140617 or newer.
10570 Until all clients update to the more recent DCMTK, build systems will
10572 need to support different versions of DCMTK.
10573 On any given system, the following combinations of DCMTK versions could
10575 be considered:
10576 ┌───────┬─────────────────┬─────────────────┬─────────────┐
10578 │ │ SYSTEM DCMTK │ LOCAL DCMTK │ Supported ? │
10579 ├───────┼─────────────────┼─────────────────┼─────────────┤
10580 │Case A │ NA │ [ ] DCMTKConfig │ YES │
10581 ├───────┼─────────────────┼─────────────────┼─────────────┤
10582 │Case B │ NA │ [X] DCMTKConfig │ YES │
10583 ├───────┼─────────────────┼─────────────────┼─────────────┤
10584 │Case C │ [ ] DCMTKConfig │ NA │ YES │
10585 ├───────┼─────────────────┼─────────────────┼─────────────┤
10586 │Case D │ [X] DCMTKConfig │ NA │ YES │
10587 ├───────┼─────────────────┼─────────────────┼─────────────┤
10588 │Case E │ [ ] DCMTKConfig │ [ ] DCMTKConfig │ YES (*) │
10589 ├───────┼─────────────────┼─────────────────┼─────────────┤
10590 │Case F │ [X] DCMTKConfig │ [ ] DCMTKConfig │ NO │
10591 ├───────┼─────────────────┼─────────────────┼─────────────┤
10592 │Case G │ [ ] DCMTKConfig │ [X] DCMTKConfig │ YES │
10593 └───────┴─────────────────┴─────────────────┴─────────────┘
10594 │Case H │ [X] DCMTKConfig │ [X] DCMTKConfig │ YES │
10597 └───────┴─────────────────┴─────────────────┴─────────────┘
10598 (*) See Troubleshooting section.
10599 Legend:
10601 NA ...............: Means that no System or Local DCMTK is available
10602 [ ] DCMTKConfig ..: Means that the version of DCMTK does NOT export
10604 a DCMTKConfig.cmake file.
10605 [X] DCMTKConfig ..: Means that the version of DCMTK exports a DCMTK‐
10607 Config.cmake file.
10608 Troubleshooting
10610 What to do if my project finds a different version of DCMTK?
10611 Remove DCMTK entry from the CMake cache per find_package() documenta‐
10613 tion.
10614 FindDevIL
10616 This module locates the developer's image library.
10617 http://openil.sourceforge.net/
10618 IMPORTED Targets
10620 New in version 3.21.
10621 This module defines the IMPORTED targets:
10624 DevIL::IL
10626 Defined if the system has DevIL.
10627 DevIL::ILU
10629 Defined if the system has DevIL Utilities.
10630 DevIL::ILUT
10632 Defined if the system has DevIL Utility Toolkit.
10633 Result Variables
10635 This module sets:
10636 IL_LIBRARIES
10638 The name of the IL library. These include the full path to the
10639 core DevIL library. This one has to be linked into the applica‐
10640 tion.
10641 ILU_LIBRARIES
10643 The name of the ILU library. Again, the full path. This library
10644 is for filters and effects, not actual loading. It doesn't have
10645 to be linked if the functionality it provides is not used.
10646 ILUT_LIBRARIES
10648 The name of the ILUT library. Full path. This part of the li‐
10649 brary interfaces with OpenGL. It is not strictly needed in ap‐
10650 plications.
10651 IL_INCLUDE_DIR
10653 where to find the il.h, ilu.h and ilut.h files.
10654 DevIL_FOUND
10656 This is set to TRUE if all the above variables were set. This
10657 will be set to false if ILU or ILUT are not found, even if they
10658 are not needed. In most systems, if one library is found all the
10659 others are as well. That's the way the DevIL developers release
10660 it.
10661 DevIL_ILUT_FOUND
10663 New in version 3.21.
10664 This is set to TRUE if the ILUT library is found.
10667 FindDoxygen
10669 Doxygen is a documentation generation tool (see
10670 http://www.doxygen.org). This module looks for Doxygen and some op‐
10671 tional tools it supports:
10672 dot Graphviz dot utility used to render various graphs.
10674 mscgen Message Chart Generator utility used by Doxygen's \msc and \msc‐
10676 file commands.
10677 dia Dia the diagram editor used by Doxygen's \diafile command.
10679 New in version 3.9: These tools are available as components in the
10681 find_package() command. For example:
10682 # Require dot, treat the other components as optional
10685 find_package(Doxygen
10686 REQUIRED dot
10687 OPTIONAL_COMPONENTS mscgen dia)
10688 The following variables are defined by this module:
10690 DOXYGEN_FOUND
10692 True if the doxygen executable was found.
10693 DOXYGEN_VERSION
10695 The version reported by doxygen --version.
10696 New in version 3.9: The module defines IMPORTED targets for Doxygen and
10698 each component found. These can be used as part of custom commands,
10699 etc. and should be preferred over old-style (and now deprecated) vari‐
10700 ables like DOXYGEN_EXECUTABLE. The following import targets are defined
10701 if their corresponding executable could be found (the component import
10702 targets will only be defined if that component was requested):
10703 Doxygen::doxygen
10706 Doxygen::dot
10707 Doxygen::mscgen
10708 Doxygen::dia
10709 Functions
10711 doxygen_add_docs
10712 New in version 3.9.
10713 This function is intended as a convenience for adding a target
10716 for generating documentation with Doxygen. It aims to provide
10717 sensible defaults so that projects can generally just provide
10718 the input files and directories and that will be sufficient to
10719 give sensible results. The function supports the ability to cus‐
10720 tomize the Doxygen configuration used to build the documenta‐
10721 tion.
10722 doxygen_add_docs(targetName
10724 [filesOrDirs...]
10725 [ALL]
10726 [USE_STAMP_FILE]
10727 [WORKING_DIRECTORY dir]
10728 [COMMENT comment])
10729 The function constructs a Doxyfile and defines a custom target
10731 that runs Doxygen on that generated file. The listed files and
10732 directories are used as the INPUT of the generated Doxyfile and
10733 they can contain wildcards. Any files that are listed explic‐
10734 itly will also be added as SOURCES of the custom target so they
10735 will show up in an IDE project's source list.
10736 So that relative input paths work as expected, by default the
10738 working directory of the Doxygen command will be the current
10739 source directory (i.e. CMAKE_CURRENT_SOURCE_DIR). This can be
10740 overridden with the WORKING_DIRECTORY option to change the di‐
10741 rectory used as the relative base point. Note also that Doxy‐
10742 gen's default behavior is to strip the working directory from
10743 relative paths in the generated documentation (see the
10744 STRIP_FROM_PATH Doxygen config option for details).
10745 If provided, the optional comment will be passed as the COMMENT
10747 for the add_custom_target() command used to create the custom
10748 target internally.
10749 New in version 3.12: If ALL is set, the target will be added to
10751 the default build target.
10752 New in version 3.16: If USE_STAMP_FILE is set, the custom com‐
10755 mand defined by this function will create a stamp file with the
10756 name <targetName>.stamp in the current binary directory whenever
10757 doxygen is re-run. With this option present, all items in
10758 <filesOrDirs> must be files (i.e. no directories, symlinks or
10759 wildcards) and each of the files must exist at the time doxy‐
10760 gen_add_docs() is called. An error will be raised if any of the
10761 items listed is missing or is not a file when USE_STAMP_FILE is
10762 given. A dependency will be created on each of the files so
10763 that doxygen will only be re-run if one of the files is updated.
10764 Without the USE_STAMP_FILE option, doxygen will always be re-run
10765 if the <targetName> target is built regardless of whether any‐
10766 thing listed in <filesOrDirs> has changed.
10767 The contents of the generated Doxyfile can be customized by set‐
10770 ting CMake variables before calling doxygen_add_docs(). Any
10771 variable with a name of the form DOXYGEN_<tag> will have its
10772 value substituted for the corresponding <tag> configuration op‐
10773 tion in the Doxyfile. See the Doxygen documentation for the full
10774 list of supported configuration options.
10775 Some of Doxygen's defaults are overridden to provide more appro‐
10777 priate behavior for a CMake project. Each of the following will
10778 be explicitly set unless the variable already has a value before
10779 doxygen_add_docs() is called (with some exceptions noted):
10780 DOXYGEN_HAVE_DOT
10782 Set to YES if the dot component was requested and it was
10783 found, NO otherwise. Any existing value of DOXY‐
10784 GEN_HAVE_DOT is ignored.
10785 DOXYGEN_DOT_MULTI_TARGETS
10787 Set to YES by this module (note that this requires a dot
10788 version newer than 1.8.10). This option is only meaning‐
10789 ful if DOXYGEN_HAVE_DOT is also set to YES.
10790 DOXYGEN_GENERATE_LATEX
10792 Set to NO by this module.
10793 DOXYGEN_WARN_FORMAT
10795 For Visual Studio based generators, this is set to the
10796 form recognized by the Visual Studio IDE: $file($line) :
10797 $text. For all other generators, Doxygen's default value
10798 is not overridden.
10799 DOXYGEN_PROJECT_NAME
10801 Populated with the name of the current project (i.e.
10802 PROJECT_NAME).
10803 DOXYGEN_PROJECT_NUMBER
10805 Populated with the version of the current project (i.e.
10806 PROJECT_VERSION).
10807 DOXYGEN_PROJECT_BRIEF
10809 Populated with the description of the current project
10810 (i.e. PROJECT_DESCRIPTION).
10811 DOXYGEN_INPUT
10813 Projects should not set this variable. It will be popu‐
10814 lated with the set of files and directories passed to
10815 doxygen_add_docs(), thereby providing consistent behavior
10816 with the other built-in commands like add_executable(),
10817 add_library() and add_custom_target(). If a variable
10818 named DOXYGEN_INPUT is set by the project, it will be ig‐
10819 nored and a warning will be issued.
10820 DOXYGEN_RECURSIVE
10822 Set to YES by this module.
10823 DOXYGEN_EXCLUDE_PATTERNS
10825 If the set of inputs includes directories, this variable
10826 will specify patterns used to exclude files from them.
10827 The following patterns are added by doxygen_add_docs() to
10828 ensure CMake-specific files and directories are not in‐
10829 cluded in the input. If the project sets DOXYGEN_EX‐
10830 CLUDE_PATTERNS, those contents are merged with these ad‐
10831 ditional patterns rather than replacing them:
10832 */.git/*
10834 */.svn/*
10835 */.hg/*
10836 */CMakeFiles/*
10837 */_CPack_Packages/*
10838 DartConfiguration.tcl
10839 CMakeLists.txt
10840 CMakeCache.txt
10841 DOXYGEN_OUTPUT_DIRECTORY
10843 Set to CMAKE_CURRENT_BINARY_DIR by this module. Note that
10844 if the project provides its own value for this and it is
10845 a relative path, it will be converted to an absolute path
10846 relative to the current binary directory. This is neces‐
10847 sary because doxygen will normally be run from a direc‐
10848 tory within the source tree so that relative source paths
10849 work as expected. If this directory does not exist, it
10850 will be recursively created prior to executing the doxy‐
10851 gen commands.
10852 To change any of these defaults or override any other Doxygen config
10854 option, set relevant variables before calling doxygen_add_docs(). For
10855 example:
10856 set(DOXYGEN_GENERATE_HTML NO)
10858 set(DOXYGEN_GENERATE_MAN YES)
10859 doxygen_add_docs(
10861 doxygen
10862 ${PROJECT_SOURCE_DIR}
10863 COMMENT "Generate man pages"
10864 )
10865 A number of Doxygen config options accept lists of values, but Doxygen
10867 requires them to be separated by whitespace. CMake variables hold lists
10868 as a string with items separated by semi-colons, so a conversion needs
10869 to be performed. The doxygen_add_docs() command specifically checks the
10870 following Doxygen config options and will convert their associated
10871 CMake variable's contents into the required form if set. CMake vari‐
10872 ables are named DOXYGEN_<name> for the Doxygen settings specified here.
10873 ABBREVIATE_BRIEF
10875 ALIASES
10876 CITE_BIB_FILES
10877 DIAFILE_DIRS
10878 DOTFILE_DIRS
10879 DOT_FONTPATH
10880 ENABLED_SECTIONS
10881 EXAMPLE_PATH
10882 EXAMPLE_PATTERNS
10883 EXCLUDE
10884 EXCLUDE_PATTERNS
10885 EXCLUDE_SYMBOLS
10886 EXPAND_AS_DEFINED
10887 EXTENSION_MAPPING
10888 EXTRA_PACKAGES
10889 EXTRA_SEARCH_MAPPINGS
10890 FILE_PATTERNS
10891 FILTER_PATTERNS
10892 FILTER_SOURCE_PATTERNS
10893 HTML_EXTRA_FILES
10894 HTML_EXTRA_STYLESHEET
10895 IGNORE_PREFIX
10896 IMAGE_PATH
10897 INCLUDE_FILE_PATTERNS
10898 INCLUDE_PATH
10899 INPUT
10900 LATEX_EXTRA_FILES
10901 LATEX_EXTRA_STYLESHEET
10902 MATHJAX_EXTENSIONS
10903 MSCFILE_DIRS
10904 PLANTUML_INCLUDE_PATH
10905 PREDEFINED
10906 QHP_CUST_FILTER_ATTRS
10907 QHP_SECT_FILTER_ATTRS
10908 STRIP_FROM_INC_PATH
10909 STRIP_FROM_PATH
10910 TAGFILES
10911 TCL_SUBST
10912 The following single value Doxygen options will be quoted automatically
10914 if they contain at least one space:
10915 CHM_FILE
10917 DIA_PATH
10918 DOCBOOK_OUTPUT
10919 DOCSET_FEEDNAME
10920 DOCSET_PUBLISHER_NAME
10921 DOT_FONTNAME
10922 DOT_PATH
10923 EXTERNAL_SEARCH_ID
10924 FILE_VERSION_FILTER
10925 GENERATE_TAGFILE
10926 HHC_LOCATION
10927 HTML_FOOTER
10928 HTML_HEADER
10929 HTML_OUTPUT
10930 HTML_STYLESHEET
10931 INPUT_FILTER
10932 LATEX_FOOTER
10933 LATEX_HEADER
10934 LATEX_OUTPUT
10935 LAYOUT_FILE
10936 MAN_OUTPUT
10937 MAN_SUBDIR
10938 MATHJAX_CODEFILE
10939 MSCGEN_PATH
10940 OUTPUT_DIRECTORY
10941 PERL_PATH
10942 PLANTUML_JAR_PATH
10943 PROJECT_BRIEF
10944 PROJECT_LOGO
10945 PROJECT_NAME
10946 QCH_FILE
10947 QHG_LOCATION
10948 QHP_CUST_FILTER_NAME
10949 QHP_VIRTUAL_FOLDER
10950 RTF_EXTENSIONS_FILE
10951 RTF_OUTPUT
10952 RTF_STYLESHEET_FILE
10953 SEARCHDATA_FILE
10954 USE_MDFILE_AS_MAINPAGE
10955 WARN_FORMAT
10956 WARN_LOGFILE
10957 XML_OUTPUT
10958 New in version 3.11: There are situations where it may be undesirable
10960 for a particular config option to be automatically quoted by doxy‐
10961 gen_add_docs(), such as ALIASES which may need to include its own em‐
10962 bedded quoting. The DOXYGEN_VERBATIM_VARS variable can be used to
10963 specify a list of Doxygen variables (including the leading DOXYGEN_
10964 prefix) which should not be quoted. The project is then responsible
10965 for ensuring that those variables' values make sense when placed di‐
10966 rectly in the Doxygen input file. In the case of list variables, list
10967 items are still separated by spaces, it is only the automatic quoting
10968 that is skipped. For example, the following allows doxygen_add_docs()
10969 to apply quoting to DOXYGEN_PROJECT_BRIEF, but not each item in the
10970 DOXYGEN_ALIASES list (bracket syntax can also be used to make working
10971 with embedded quotes easier):
10972 set(DOXYGEN_PROJECT_BRIEF "String with spaces")
10975 set(DOXYGEN_ALIASES
10976 [[somealias="@some_command param"]]
10977 "anotherAlias=@foobar"
10978 )
10979 set(DOXYGEN_VERBATIM_VARS DOXYGEN_ALIASES)
10980 The resultant Doxyfile will contain the following lines:
10982 PROJECT_BRIEF = "String with spaces"
10984 ALIASES = somealias="@some_command param" anotherAlias=@foobar
10985 Deprecated Result Variables
10987 Deprecated since version 3.9.
10988 For compatibility with previous versions of CMake, the following vari‐
10991 ables are also defined but they are deprecated and should no longer be
10992 used:
10993 DOXYGEN_EXECUTABLE
10995 The path to the doxygen command. If projects need to refer to
10996 the doxygen executable directly, they should use the Doxy‐
10997 gen::doxygen import target instead.
10998 DOXYGEN_DOT_FOUND
11000 True if the dot executable was found.
11001 DOXYGEN_DOT_EXECUTABLE
11003 The path to the dot command. If projects need to refer to the
11004 dot executable directly, they should use the Doxygen::dot import
11005 target instead.
11006 DOXYGEN_DOT_PATH
11008 The path to the directory containing the dot executable as re‐
11009 ported in DOXYGEN_DOT_EXECUTABLE. The path may have forward
11010 slashes even on Windows and is not suitable for direct substitu‐
11011 tion into a Doxyfile.in template. If you need this value, get
11012 the IMPORTED_LOCATION property of the Doxygen::dot target and
11013 use get_filename_component() to extract the directory part of
11014 that path. You may also want to consider using file(TO_NA‐
11015 TIVE_PATH) to prepare the path for a Doxygen configuration file.
11016 Deprecated Hint Variables
11018 Deprecated since version 3.9.
11019 DOXYGEN_SKIP_DOT
11022 This variable has no effect for the component form of find_pack‐
11023 age. In backward compatibility mode (i.e. without components
11024 list) it prevents the finder module from searching for
11025 Graphviz's dot utility.
11026 FindEnvModules
11028 New in version 3.15.
11029 Locate an environment module implementation and make commands available
11032 to CMake scripts to use them. This is compatible with both Lua-based
11033 Lmod and TCL-based EnvironmentModules.
11034 This module is intended for the use case of setting up the compiler and
11036 library environment within a CTest Script (ctest -S). It can also be
11037 used in a CMake Script (cmake -P).
11038 NOTE:
11040 The loaded environment will not survive past the end of the calling
11041 process. Do not use this module in project code (CMakeLists.txt
11042 files) to load a compiler environment; it will not be available dur‐
11043 ing the build. Instead load the environment manually before running
11044 CMake or using the generated build system.
11045 Example Usage
11047 set(CTEST_BUILD_NAME "CrayLinux-CrayPE-Cray-dynamic")
11048 set(CTEST_BUILD_CONFIGURATION Release)
11049 set(CTEST_BUILD_FLAGS "-k -j8")
11050 set(CTEST_CMAKE_GENERATOR "Unix Makefiles")
11051 ...
11053 find_package(EnvModules REQUIRED)
11055 env_module(purge)
11057 env_module(load modules)
11058 env_module(load craype)
11059 env_module(load PrgEnv-cray)
11060 env_module(load craype-knl)
11061 env_module(load cray-mpich)
11062 env_module(load cray-libsci)
11063 set(ENV{CRAYPE_LINK_TYPE} dynamic)
11065 ...
11067 Result Variables
11069 This module will set the following variables in your project:
11070 EnvModules_FOUND
11072 True if a compatible environment modules framework was found.
11073 Cache Variables
11075 The following cache variable will be set:
11076 EnvModules_COMMAND
11078 The low level module command to use. Currently supported imple‐
11079 mentations are the Lua based Lmod and TCL based EnvironmentMod‐
11080 ules.
11081 Environment Variables
11083 ENV{MODULESHOME}
11084 Usually set by the module environment implementation, used as a
11085 hint to locate the module command to execute.
11086 Provided Functions
11088 This defines the following CMake functions for interacting with envi‐
11089 ronment modules:
11090 env_module
11092 Execute an aribitrary module command:
11093 env_module(cmd arg1 ... argN)
11095 env_module(
11096 COMMAND cmd arg1 ... argN
11097 [OUTPUT_VARIABLE <out-var>]
11098 [RESULT_VARIABLE <ret-var>]
11099 )
11100 The options are:
11102 cmd arg1 ... argN
11104 The module sub-command and arguments to execute as if
11105 they were passed directly to the module command in your
11106 shell environment.
11107 OUTPUT_VARIABLE <out-var>
11109 The standard output from executing the module command.
11110 RESULT_VARIABLE <ret-var>
11112 The return code from executing the module command.
11113 env_module_swap
11115 Swap one module for another:
11116 env_module_swap(out_mod in_mod
11118 [OUTPUT_VARIABLE <out-var>]
11119 [RESULT_VARIABLE <ret-var>]
11120 )
11121 This is functionally equivalent to the module swap out_mod
11123 in_mod shell command. The options are:
11124 OUTPUT_VARIABLE <out-var>
11126 The standard output from executing the module command.
11127 RESULT_VARIABLE <ret-var>
11129 The return code from executing the module command.
11130 env_module_list
11132 Retrieve the list of currently loaded modules:
11133 env_module_list(<out-var>)
11135 This is functionally equivalent to the module list shell com‐
11137 mand. The result is stored in <out-var> as a properly formatted
11138 CMake semicolon-separated list variable.
11139 env_module_avail
11141 Retrieve the list of available modules:
11142 env_module_avail([<mod-prefix>] <out-var>)
11144 This is functionally equivalent to the module avail <mod-prefix>
11146 shell command. The result is stored in <out-var> as a properly
11147 formatted CMake semicolon-separated list variable.
11148 FindEXPAT
11150 Find the native Expat headers and library. Expat is a stream-oriented
11151 XML parser library written in C.
11152 Imported Targets
11154 New in version 3.10.
11155 This module defines the following IMPORTED targets:
11158 EXPAT::EXPAT
11160 The Expat expat library, if found.
11161 Result Variables
11163 This module will set the following variables in your project:
11164 EXPAT_INCLUDE_DIRS
11166 where to find expat.h, etc.
11167 EXPAT_LIBRARIES
11169 the libraries to link against to use Expat.
11170 EXPAT_FOUND
11172 true if the Expat headers and libraries were found.
11173 FindFLEX
11175 Find Fast Lexical Analyzer (Flex) executable and provides a macro to
11176 generate custom build rules
11177 The module defines the following variables:
11179 FLEX_FOUND - True is flex executable is found
11181 FLEX_EXECUTABLE - the path to the flex executable
11182 FLEX_VERSION - the version of flex
11183 FLEX_LIBRARIES - The flex libraries
11184 FLEX_INCLUDE_DIRS - The path to the flex headers
11185 The minimum required version of flex can be specified using the stan‐
11187 dard syntax, e.g. find_package(FLEX 2.5.13)
11188 If flex is found on the system, the module provides the macro:
11190 FLEX_TARGET(Name FlexInput FlexOutput
11192 [COMPILE_FLAGS <string>]
11193 [DEFINES_FILE <string>]
11194 )
11195 which creates a custom command to generate the FlexOutput file from the
11197 FlexInput file. Name is an alias used to get details of this custom
11198 command. If COMPILE_FLAGS option is specified, the next parameter is
11199 added to the flex command line.
11200 New in version 3.5: If flex is configured to output a header file, the
11202 DEFINES_FILE option may be used to specify its name.
11203 Changed in version 3.17: When CMP0098 is set to NEW, flex runs in the
11206 CMAKE_CURRENT_BINARY_DIR directory.
11207 The macro defines the following variables:
11210 FLEX_${Name}_DEFINED - true is the macro ran successfully
11212 FLEX_${Name}_OUTPUTS - the source file generated by the custom rule, an
11213 alias for FlexOutput
11214 FLEX_${Name}_INPUT - the flex source file, an alias for ${FlexInput}
11215 FLEX_${Name}_OUTPUT_HEADER - the header flex output, if any.
11216 Flex scanners often use tokens defined by Bison: the code generated by
11218 Flex depends of the header generated by Bison. This module also de‐
11219 fines a macro:
11220 ADD_FLEX_BISON_DEPENDENCY(FlexTarget BisonTarget)
11222 which adds the required dependency between a scanner and a parser where
11224 FlexTarget and BisonTarget are the first parameters of respectively
11225 FLEX_TARGET and BISON_TARGET macros.
11226 ====================================================================
11228 Example:
11229 find_package(BISON)
11231 find_package(FLEX)
11232 BISON_TARGET(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
11234 FLEX_TARGET(MyScanner lexer.l ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp)
11235 ADD_FLEX_BISON_DEPENDENCY(MyScanner MyParser)
11236 include_directories(${CMAKE_CURRENT_BINARY_DIR})
11238 add_executable(Foo
11239 Foo.cc
11240 ${BISON_MyParser_OUTPUTS}
11241 ${FLEX_MyScanner_OUTPUTS}
11242 )
11243 target_link_libraries(Foo ${FLEX_LIBRARIES})
11244 ====================================================================
11245 FindFLTK
11247 Find the Fast Light Toolkit (FLTK) library
11248 Input Variables
11250 By default this module will search for all of the FLTK components and
11251 add them to the FLTK_LIBRARIES variable. You can limit the components
11252 which get placed in FLTK_LIBRARIES by defining one or more of the fol‐
11253 lowing three options:
11254 FLTK_SKIP_OPENGL
11256 Set to true to disable searching for the FLTK GL library
11257 FLTK_SKIP_FORMS
11259 Set to true to disable searching for the FLTK Forms library
11260 FLTK_SKIP_IMAGES
11262 Set to true to disable searching for the FLTK Images library
11263 FLTK is composed also by a binary tool. You can set the following op‐
11265 tion:
11266 FLTK_SKIP_FLUID
11268 Set to true to not look for the FLUID binary
11269 Result Variables
11271 The following variables will be defined:
11272 FLTK_FOUND
11274 True if all components not skipped were found
11275 FLTK_INCLUDE_DIR
11277 Path to the include directory for FLTK header files
11278 FLTK_LIBRARIES
11280 List of the FLTK libraries found
11281 FLTK_FLUID_EXECUTABLE
11283 Path to the FLUID binary tool
11284 FLTK_WRAP_UI
11286 True if FLUID is found, used to enable the FLTK_WRAP_UI command
11287 Cache Variables
11289 The following cache variables are also available to set or use:
11290 FLTK_BASE_LIBRARY_RELEASE
11292 The FLTK base library (optimized)
11293 FLTK_BASE_LIBRARY_DEBUG
11295 The FLTK base library (debug)
11296 FLTK_GL_LIBRARY_RELEASE
11298 The FLTK GL library (optimized)
11299 FLTK_GL_LIBRARY_DEBUG
11301 The FLTK GL library (debug)
11302 FLTK_FORMS_LIBRARY_RELEASE
11304 The FLTK Forms library (optimized)
11305 FLTK_FORMS_LIBRARY_DEBUG
11307 The FLTK Forms library (debug)
11308 FLTK_IMAGES_LIBRARY_RELEASE
11310 The FLTK Images protobuf library (optimized)
11311 FLTK_IMAGES_LIBRARY_DEBUG
11313 The FLTK Images library (debug)
11314 New in version 3.11: Debug and Release variants are found separately
11316 and use per-configuration variables.
11317 FindFLTK2
11320 Find the native FLTK 2.0 includes and library
11321 The following settings are defined
11323 FLTK2_FLUID_EXECUTABLE, where to find the Fluid tool
11325 FLTK2_WRAP_UI, This enables the FLTK2_WRAP_UI command
11326 FLTK2_INCLUDE_DIR, where to find include files
11327 FLTK2_LIBRARIES, list of fltk2 libraries
11328 FLTK2_FOUND, Don't use FLTK2 if false.
11329 The following settings should not be used in general.
11331 FLTK2_BASE_LIBRARY = the full path to fltk2.lib
11333 FLTK2_GL_LIBRARY = the full path to fltk2_gl.lib
11334 FLTK2_IMAGES_LIBRARY = the full path to fltk2_images.lib
11335 FindFontconfig
11337 New in version 3.14.
11338 Find Fontconfig headers and library.
11341 Imported Targets
11343 Fontconfig::Fontconfig
11344 The Fontconfig library, if found.
11345 Result Variables
11347 This will define the following variables in your project:
11348 Fontconfig_FOUND
11350 true if (the requested version of) Fontconfig is available.
11351 Fontconfig_VERSION
11353 the version of Fontconfig.
11354 Fontconfig_LIBRARIES
11356 the libraries to link against to use Fontconfig.
11357 Fontconfig_INCLUDE_DIRS
11359 where to find the Fontconfig headers.
11360 Fontconfig_COMPILE_OPTIONS
11362 this should be passed to target_compile_options(), if the target
11363 is not used for linking
11364 FindFreetype
11366 Find the FreeType font renderer includes and library.
11367 Imported Targets
11369 New in version 3.10.
11370 This module defines the following IMPORTED target:
11373 Freetype::Freetype
11375 The Freetype freetype library, if found
11376 Result Variables
11378 This module will set the following variables in your project:
11379 FREETYPE_FOUND
11381 true if the Freetype headers and libraries were found
11382 FREETYPE_INCLUDE_DIRS
11384 directories containing the Freetype headers. This is the con‐
11385 catenation of the variables:
11386 FREETYPE_INCLUDE_DIR_ft2build
11388 directory holding the main Freetype API configuration
11389 header
11390 FREETYPE_INCLUDE_DIR_freetype2
11392 directory holding Freetype public headers
11393 FREETYPE_LIBRARIES
11395 the library to link against
11396 FREETYPE_VERSION_STRING
11398 the version of freetype found
11399 New in version 3.7: Debug and Release variants are found separately.
11401 Hints
11404 The user may set the environment variable FREETYPE_DIR to the root di‐
11405 rectory of a Freetype installation.
11406 FindGCCXML
11408 Find the GCC-XML front-end executable.
11409 This module will define the following variables:
11411 GCCXML - the GCC-XML front-end executable.
11413 FindGDAL
11415 Find Geospatial Data Abstraction Library (GDAL).
11416 IMPORTED Targets
11418 New in version 3.14.
11419 This module defines IMPORTED target GDAL::GDAL if GDAL has been found.
11422 Result Variables
11424 This module will set the following variables in your project:
11425 GDAL_FOUND
11427 True if GDAL is found.
11428 GDAL_INCLUDE_DIRS
11430 Include directories for GDAL headers.
11431 GDAL_LIBRARIES
11433 Libraries to link to GDAL.
11434 GDAL_VERSION
11436 New in version 3.14: The version of GDAL found.
11437 Cache variables
11440 The following cache variables may also be set:
11441 GDAL_LIBRARY
11443 The libgdal library file.
11444 GDAL_INCLUDE_DIR
11446 The directory containing gdal.h.
11447 Hints
11449 Set GDAL_DIR or GDAL_ROOT in the environment to specify the GDAL in‐
11450 stallation prefix.
11451 The following variables may be set to modify the search strategy:
11453 FindGDAL_SKIP_GDAL_CONFIG
11455 If set, gdal-config will not be used. This can be useful if
11456 there are GDAL libraries built with autotools (which provide the
11457 tool) and CMake (which do not) in the same environment.
11458 GDAL_ADDITIONAL_LIBRARY_VERSIONS
11460 Extra versions of library names to search for.
11461 FindGettext
11463 Find GNU gettext tools
11464 This module looks for the GNU gettext tools. This module defines the
11466 following values:
11467 GETTEXT_MSGMERGE_EXECUTABLE: the full path to the msgmerge tool.
11469 GETTEXT_MSGFMT_EXECUTABLE: the full path to the msgfmt tool.
11470 GETTEXT_FOUND: True if gettext has been found.
11471 GETTEXT_VERSION_STRING: the version of gettext found (since CMake 2.8.8)
11472 Additionally it provides the following macros:
11474 GETTEXT_CREATE_TRANSLATIONS ( outputFile [ALL] file1 ... fileN )
11476 This will create a target "translations" which will convert the
11478 given input po files into the binary output mo file. If the
11479 ALL option is used, the translations will also be created when
11480 building the default target.
11481 GETTEXT_PROCESS_POT_FILE( <potfile> [ALL] [INSTALL_DESTINATION <dest‐
11483 dir>] LANGUAGES <lang1> <lang2> ... )
11484 Process the given pot file to mo files.
11486 If INSTALL_DESTINATION is given then automatically install rules will
11487 be created, the language subdirectory will be taken into account
11488 (by default use share/locale/).
11489 If ALL is specified, the pot file is processed when building the all target.
11490 It creates a custom target "potfile".
11491 GETTEXT_PROCESS_PO_FILES( <lang> [ALL] [INSTALL_DESTINATION <dir>]
11493 PO_FILES <po1> <po2> ... )
11494 Process the given po files to mo files for the given language.
11496 If INSTALL_DESTINATION is given then automatically install rules will
11497 be created, the language subdirectory will be taken into account
11498 (by default use share/locale/).
11499 If ALL is specified, the po files are processed when building the all target.
11500 It creates a custom target "pofiles".
11501 New in version 3.2: If you wish to use the Gettext library (libintl),
11503 use FindIntl.
11504 FindGIF
11507 This finds the Graphics Interchange Format (GIF) library (giflib)
11508 Imported targets
11510 This module defines the following IMPORTED target:
11511 GIF::GIF
11513 The giflib library, if found.
11514 Result variables
11516 This module will set the following variables in your project:
11517 GIF_FOUND
11519 If false, do not try to use GIF.
11520 GIF_INCLUDE_DIRS
11522 where to find gif_lib.h, etc.
11523 GIF_LIBRARIES
11525 the libraries needed to use GIF.
11526 GIF_VERSION
11528 3, 4 or a full version string (eg 5.1.4) for versions >= 4.1.6.
11529 Cache variables
11531 The following cache variables may also be set:
11532 GIF_INCLUDE_DIR
11534 where to find the GIF headers.
11535 GIF_LIBRARY
11537 where to find the GIF library.
11538 Hints
11540 GIF_DIR is an environment variable that would correspond to the ./con‐
11541 figure --prefix=$GIF_DIR.
11542 FindGit
11544 The module defines the following variables:
11545 GIT_EXECUTABLE
11547 Path to Git command-line client.
11548 Git_FOUND, GIT_FOUND
11550 True if the Git command-line client was found.
11551 GIT_VERSION_STRING
11553 The version of Git found.
11554 New in version 3.14: The module defines the following IMPORTED targets
11556 (when CMAKE_ROLE is PROJECT):
11557 Git::Git
11560 Executable of the Git command-line client.
11561 Example usage:
11563 find_package(Git)
11565 if(Git_FOUND)
11566 message("Git found: ${GIT_EXECUTABLE}")
11567 endif()
11568 FindGLEW
11570 Find the OpenGL Extension Wrangler Library (GLEW)
11571 Input Variables
11573 The following variables may be set to influence this module's behavior:
11574 GLEW_USE_STATIC_LIBS
11576 to find and create IMPORTED target for static linkage.
11577 GLEW_VERBOSE
11579 to output a detailed log of this module.
11580 Imported Targets
11582 New in version 3.1.
11583 This module defines the following Imported Targets:
11586 GLEW::glew
11588 The GLEW shared library.
11589 GLEW::glew_s
11591 The GLEW static library, if GLEW_USE_STATIC_LIBS is set to TRUE.
11592 GLEW::GLEW
11594 Duplicates either GLEW::glew or GLEW::glew_s based on availabil‐
11595 ity.
11596 Result Variables
11598 This module defines the following variables:
11599 GLEW_INCLUDE_DIRS
11601 include directories for GLEW
11602 GLEW_LIBRARIES
11604 libraries to link against GLEW
11605 GLEW_SHARED_LIBRARIES
11607 libraries to link against shared GLEW
11608 GLEW_STATIC_LIBRARIES
11610 libraries to link against static GLEW
11611 GLEW_FOUND
11613 true if GLEW has been found and can be used
11614 GLEW_VERSION
11616 GLEW version
11617 GLEW_VERSION_MAJOR
11619 GLEW major version
11620 GLEW_VERSION_MINOR
11622 GLEW minor version
11623 GLEW_VERSION_MICRO
11625 GLEW micro version
11626 New in version 3.7: Debug and Release variants are found separately.
11628 FindGLUT
11631 Find OpenGL Utility Toolkit (GLUT) library and include files.
11632 IMPORTED Targets
11634 New in version 3.1.
11635 This module defines the IMPORTED targets:
11638 GLUT::GLUT
11640 Defined if the system has GLUT.
11641 Result Variables
11643 This module sets the following variables:
11644 GLUT_INCLUDE_DIR, where to find GL/glut.h, etc.
11646 GLUT_LIBRARIES, the libraries to link against
11647 GLUT_FOUND, If false, do not try to use GLUT.
11648 Also defined, but not for general use are:
11650 GLUT_glut_LIBRARY = the full path to the glut library.
11652 GLUT_Xmu_LIBRARY = the full path to the Xmu library.
11653 GLUT_Xi_LIBRARY = the full path to the Xi Library.
11654 New in version 3.13: Debug and Release variants are found separately.
11656 FindGnuplot
11659 this module looks for gnuplot
11660 Once done this will define
11662 GNUPLOT_FOUND - system has Gnuplot
11664 GNUPLOT_EXECUTABLE - the Gnuplot executable
11665 GNUPLOT_VERSION_STRING - the version of Gnuplot found (since CMake 2.8.8)
11666 GNUPLOT_VERSION_STRING will not work for old versions like 3.7.1.
11668 FindGnuTLS
11670 Find the GNU Transport Layer Security library (gnutls)
11671 IMPORTED Targets
11673 New in version 3.16.
11674 This module defines IMPORTED target GnuTLS::GnuTLS, if gnutls has been
11677 found.
11678 Result Variables
11680 GNUTLS_FOUND
11681 System has gnutls
11682 GNUTLS_INCLUDE_DIR
11684 The gnutls include directory
11685 GNUTLS_LIBRARIES
11687 The libraries needed to use gnutls
11688 GNUTLS_DEFINITIONS
11690 Compiler switches required for using gnutls
11691 GNUTLS_VERSION
11693 version of gnutls.
11694 FindGSL
11696 New in version 3.2.
11697 Find the native GNU Scientific Library (GSL) includes and libraries.
11700 The GNU Scientific Library (GSL) is a numerical library for C and C++
11702 programmers. It is free software under the GNU General Public License.
11703 Imported Targets
11705 If GSL is found, this module defines the following IMPORTED targets:
11706 GSL::gsl - The main GSL library.
11708 GSL::gslcblas - The CBLAS support library used by GSL.
11709 Result Variables
11711 This module will set the following variables in your project:
11712 GSL_FOUND - True if GSL found on the local system
11714 GSL_INCLUDE_DIRS - Location of GSL header files.
11715 GSL_LIBRARIES - The GSL libraries.
11716 GSL_VERSION - The version of the discovered GSL install.
11717 Hints
11719 Set GSL_ROOT_DIR to a directory that contains a GSL installation.
11720 This script expects to find libraries at $GSL_ROOT_DIR/lib and the GSL
11722 headers at $GSL_ROOT_DIR/include/gsl. The library directory may op‐
11723 tionally provide Release and Debug folders. If available, the libraries
11724 named gsld, gslblasd or cblasd are recognized as debug libraries. For
11725 Unix-like systems, this script will use $GSL_ROOT_DIR/bin/gsl-config
11726 (if found) to aid in the discovery of GSL.
11727 Cache Variables
11729 This module may set the following variables depending on platform and
11730 type of GSL installation discovered. These variables may optionally be
11731 set to help this module find the correct files:
11732 GSL_CBLAS_LIBRARY - Location of the GSL CBLAS library.
11734 GSL_CBLAS_LIBRARY_DEBUG - Location of the debug GSL CBLAS library (if any).
11735 GSL_CONFIG_EXECUTABLE - Location of the ``gsl-config`` script (if any).
11736 GSL_LIBRARY - Location of the GSL library.
11737 GSL_LIBRARY_DEBUG - Location of the debug GSL library (if any).
11738 FindGTest
11740 Locate the Google C++ Testing Framework.
11741 New in version 3.20: Upstream GTestConfig.cmake is used if possible.
11743 Imported targets
11746 New in version 3.20: This module defines the following IMPORTED tar‐
11747 gets:
11748 GTest::gtest
11751 The Google Test gtest library, if found; adds Thread::Thread au‐
11752 tomatically
11753 GTest::gtest_main
11755 The Google Test gtest_main library, if found
11756 Deprecated since version 3.20: For backwards compatibility, this module
11758 defines additionally the following deprecated IMPORTED targets (avail‐
11759 able since 3.5):
11760 GTest::GTest
11763 The Google Test gtest library, if found; adds Thread::Thread au‐
11764 tomatically
11765 GTest::Main
11767 The Google Test gtest_main library, if found
11768 Result variables
11770 This module will set the following variables in your project:
11771 GTest_FOUND
11773 Found the Google Testing framework
11774 GTEST_INCLUDE_DIRS
11776 the directory containing the Google Test headers
11777 The library variables below are set as normal variables. These contain
11779 debug/optimized keywords when a debugging library is found.
11780 GTEST_LIBRARIES
11782 The Google Test gtest library; note it also requires linking
11783 with an appropriate thread library
11784 GTEST_MAIN_LIBRARIES
11786 The Google Test gtest_main library
11787 GTEST_BOTH_LIBRARIES
11789 Both gtest and gtest_main
11790 Cache variables
11792 The following cache variables may also be set:
11793 GTEST_ROOT
11795 The root directory of the Google Test installation (may also be
11796 set as an environment variable)
11797 GTEST_MSVC_SEARCH
11799 If compiling with MSVC, this variable can be set to MT or MD
11800 (the default) to enable searching a GTest build tree
11801 Example usage
11803 enable_testing()
11804 find_package(GTest REQUIRED)
11805 add_executable(foo foo.cc)
11807 target_link_libraries(foo GTest::gtest GTest::gtest_main)
11808 add_test(AllTestsInFoo foo)
11810 Deeper integration with CTest
11812 See GoogleTest for information on the gtest_add_tests() and gtest_dis‐
11813 cover_tests() commands.
11814 Changed in version 3.9: Previous CMake versions defined
11816 gtest_add_tests() macro in this module.
11817 FindGTK
11820 Find GTK, glib and GTKGLArea
11821 GTK_INCLUDE_DIR - Directories to include to use GTK
11823 GTK_LIBRARIES - Files to link against to use GTK
11824 GTK_FOUND - GTK was found
11825 GTK_GL_FOUND - GTK's GL features were found
11826 FindGTK2
11828 Find the GTK2 widget libraries and several of its other optional compo‐
11829 nents like gtkmm, glade, and glademm.
11830 Specify one or more of the following components as you call this find
11832 module. See example below.
11833 • gtk
11835 • gtkmm
11837 • glade
11839 • glademm
11841 Imported Targets
11843 This module defines the following IMPORTED targets (subject to compo‐
11844 nent selection):
11845 GTK2::atk, GTK2::atkmm, GTK2::cairo, GTK2::cairomm, GTK2::gdk_pixbuf,
11847 GTK2::gdk, GTK2::gdkmm, GTK2::gio, GTK2::giomm, GTK2::glade,
11848 GTK2::glademm, GTK2::glib, GTK2::glibmm, GTK2::gmodule, GTK2::gobject,
11849 GTK2::gthread, GTK2::gtk, GTK2::gtkmm, GTK2::harfbuzz, GTK2::pango,
11850 GTK2::pangocairo, GTK2::pangoft2, GTK2::pangomm, GTK2::pangoxft,
11851 GTK2::sigc.
11852 New in version 3.16.7: Added the GTK2::harfbuzz target.
11854 Result Variables
11857 The following variables will be defined for your use
11858 GTK2_FOUND
11860 Were all of your specified components found?
11861 GTK2_INCLUDE_DIRS
11863 All include directories
11864 GTK2_LIBRARIES
11866 All libraries
11867 GTK2_TARGETS
11869 New in version 3.5: All imported targets
11870 GTK2_DEFINITIONS
11873 Additional compiler flags
11874 GTK2_VERSION
11876 The version of GTK2 found (x.y.z)
11877 GTK2_MAJOR_VERSION
11879 The major version of GTK2
11880 GTK2_MINOR_VERSION
11882 The minor version of GTK2
11883 GTK2_PATCH_VERSION
11885 The patch version of GTK2
11886 New in version 3.5: When GTK2_USE_IMPORTED_TARGETS is set to TRUE,
11888 GTK2_LIBRARIES will list imported targets instead of library paths.
11889 Input Variables
11892 Optional variables you can define prior to calling this module:
11893 GTK2_DEBUG
11895 Enables verbose debugging of the module
11896 GTK2_ADDITIONAL_SUFFIXES
11898 Allows defining additional directories to search for include
11899 files
11900 Example Usage
11902 Call find_package() once. Here are some examples to pick from:
11903 Require GTK 2.6 or later:
11905 find_package(GTK2 2.6 REQUIRED gtk)
11907 Require GTK 2.10 or later and Glade:
11909 find_package(GTK2 2.10 REQUIRED gtk glade)
11911 Search for GTK/GTKMM 2.8 or later:
11913 find_package(GTK2 2.8 COMPONENTS gtk gtkmm)
11915 Use the results:
11917 if(GTK2_FOUND)
11919 include_directories(${GTK2_INCLUDE_DIRS})
11920 add_executable(mygui mygui.cc)
11921 target_link_libraries(mygui ${GTK2_LIBRARIES})
11922 endif()
11923 FindHDF5
11925 Find Hierarchical Data Format (HDF5), a library for reading and writing
11926 self describing array data.
11927 This module invokes the HDF5 wrapper compiler that should be installed
11929 alongside HDF5. Depending upon the HDF5 Configuration, the wrapper
11930 compiler is called either h5cc or h5pcc. If this succeeds, the module
11931 will then call the compiler with the show argument to see what flags
11932 are used when compiling an HDF5 client application.
11933 The module will optionally accept the COMPONENTS argument. If no COM‐
11935 PONENTS are specified, then the find module will default to finding
11936 only the HDF5 C library. If one or more COMPONENTS are specified, the
11937 module will attempt to find the language bindings for the specified
11938 components. The valid components are C, CXX, Fortran, HL. HL refers
11939 to the "high-level" HDF5 functions for C and Fortran. If the COMPO‐
11940 NENTS argument is not given, the module will attempt to find only the C
11941 bindings. For example, to use Fortran HDF5 and HDF5-HL functions, do:
11942 find_package(HDF5 COMPONENTS Fortran HL).
11943 This module will read the variable HDF5_USE_STATIC_LIBRARIES to deter‐
11945 mine whether or not to prefer a static link to a dynamic link for HDF5
11946 and all of it's dependencies. To use this feature, make sure that the
11947 HDF5_USE_STATIC_LIBRARIES variable is set before the call to find_pack‐
11948 age.
11949 New in version 3.10: Support for HDF5_USE_STATIC_LIBRARIES on Windows.
11951 Both the serial and parallel HDF5 wrappers are considered and the first
11954 directory to contain either one will be used. In the event that both
11955 appear in the same directory the serial version is preferentially se‐
11956 lected. This behavior can be reversed by setting the variable HDF5_PRE‐
11957 FER_PARALLEL to TRUE.
11958 In addition to finding the includes and libraries required to compile
11960 an HDF5 client application, this module also makes an effort to find
11961 tools that come with the HDF5 distribution that may be useful for re‐
11962 gression testing.
11963 Result Variables
11965 This module will set the following variables in your project:
11966 HDF5_FOUND
11968 HDF5 was found on the system
11969 HDF5_VERSION
11971 New in version 3.3: HDF5 library version
11972 HDF5_INCLUDE_DIRS
11975 Location of the HDF5 header files
11976 HDF5_DEFINITIONS
11978 Required compiler definitions for HDF5
11979 HDF5_LIBRARIES
11981 Required libraries for all requested bindings
11982 HDF5_HL_LIBRARIES
11984 Required libraries for the HDF5 high level API for all bindings,
11985 if the HL component is enabled
11986 Available components are: C CXX Fortran and HL. For each enabled lan‐
11988 guage binding, a corresponding HDF5_${LANG}_LIBRARIES variable, and po‐
11989 tentially HDF5_${LANG}_DEFINITIONS, will be defined. If the HL compo‐
11990 nent is enabled, then an HDF5_${LANG}_HL_LIBRARIES will also be de‐
11991 fined. With all components enabled, the following variables will be
11992 defined:
11993 HDF5_C_DEFINITIONS
11995 Required compiler definitions for HDF5 C bindings
11996 HDF5_CXX_DEFINITIONS
11998 Required compiler definitions for HDF5 C++ bindings
11999 HDF5_Fortran_DEFINITIONS
12001 Required compiler definitions for HDF5 Fortran bindings
12002 HDF5_C_INCLUDE_DIRS
12004 Required include directories for HDF5 C bindings
12005 HDF5_CXX_INCLUDE_DIRS
12007 Required include directories for HDF5 C++ bindings
12008 HDF5_Fortran_INCLUDE_DIRS
12010 Required include directories for HDF5 Fortran bindings
12011 HDF5_C_LIBRARIES
12013 Required libraries for the HDF5 C bindings
12014 HDF5_CXX_LIBRARIES
12016 Required libraries for the HDF5 C++ bindings
12017 HDF5_Fortran_LIBRARIES
12019 Required libraries for the HDF5 Fortran bindings
12020 HDF5_C_HL_LIBRARIES
12022 Required libraries for the high level C bindings
12023 HDF5_CXX_HL_LIBRARIES
12025 Required libraries for the high level C++ bindings
12026 HDF5_Fortran_HL_LIBRARIES
12028 Required libraries for the high level Fortran bindings.
12029 HDF5_IS_PARALLEL
12031 HDF5 library has parallel IO support
12032 HDF5_C_COMPILER_EXECUTABLE
12034 path to the HDF5 C wrapper compiler
12035 HDF5_CXX_COMPILER_EXECUTABLE
12037 path to the HDF5 C++ wrapper compiler
12038 HDF5_Fortran_COMPILER_EXECUTABLE
12040 path to the HDF5 Fortran wrapper compiler
12041 HDF5_C_COMPILER_EXECUTABLE_NO_INTERROGATE
12043 path to the primary C compiler which is also the HDF5 wrapper
12044 HDF5_CXX_COMPILER_EXECUTABLE_NO_INTERROGATE
12046 path to the primary C++ compiler which is also the HDF5 wrapper
12047 HDF5_Fortran_COMPILER_EXECUTABLE_NO_INTERROGATE
12049 path to the primary Fortran compiler which is also the HDF5
12050 wrapper
12051 HDF5_DIFF_EXECUTABLE
12053 path to the HDF5 dataset comparison tool
12054 With all components enabled, the following targets will be defined:
12056 HDF5::HDF5
12058 All detected HDF5_LIBRARIES.
12059 hdf5::hdf5
12061 C library.
12062 hdf5::hdf5_cpp
12064 C++ library.
12065 hdf5::hdf5_fortran
12067 Fortran library.
12068 hdf5::hdf5_hl
12070 High-level C library.
12071 hdf5::hdf5_hl_cpp
12073 High-level C++ library.
12074 hdf5::hdf5_hl_fortran
12076 High-level Fortran library.
12077 hdf5::h5diff
12079 h5diff executable.
12080 Hints
12082 The following variables can be set to guide the search for HDF5 li‐
12083 braries and includes:
12084 HDF5_PREFER_PARALLEL
12086 New in version 3.4.
12087 set true to prefer parallel HDF5 (by default, serial is pre‐
12090 ferred)
12091 HDF5_FIND_DEBUG
12093 New in version 3.9.
12094 Set true to get extra debugging output.
12097 HDF5_NO_FIND_PACKAGE_CONFIG_FILE
12099 New in version 3.8.
12100 Set true to skip trying to find hdf5-config.cmake.
12103 FindHg
12105 Extract information from a mercurial working copy.
12106 The module defines the following variables:
12108 HG_EXECUTABLE - path to mercurial command line client (hg)
12110 HG_FOUND - true if the command line client was found
12111 HG_VERSION_STRING - the version of mercurial found
12112 New in version 3.1: If the command line client executable is found the
12114 following macro is defined:
12115 HG_WC_INFO(<dir> <var-prefix>)
12118 Hg_WC_INFO extracts information of a mercurial working copy at a given
12120 location. This macro defines the following variables:
12121 <var-prefix>_WC_CHANGESET - current changeset
12123 <var-prefix>_WC_REVISION - current revision
12124 Example usage:
12126 find_package(Hg)
12128 if(HG_FOUND)
12129 message("hg found: ${HG_EXECUTABLE}")
12130 HG_WC_INFO(${PROJECT_SOURCE_DIR} Project)
12131 message("Current revision is ${Project_WC_REVISION}")
12132 message("Current changeset is ${Project_WC_CHANGESET}")
12133 endif()
12134 FindHSPELL
12136 Try to find Hebrew spell-checker (Hspell) and morphology engine.
12137 Once done this will define
12139 HSPELL_FOUND - system has Hspell
12141 HSPELL_INCLUDE_DIR - the Hspell include directory
12142 HSPELL_LIBRARIES - The libraries needed to use Hspell
12143 HSPELL_DEFINITIONS - Compiler switches required for using Hspell
12144 HSPELL_VERSION_STRING - The version of Hspell found (x.y)
12146 HSPELL_MAJOR_VERSION - the major version of Hspell
12147 HSPELL_MINOR_VERSION - The minor version of Hspell
12148 FindHTMLHelp
12150 This module looks for Microsoft HTML Help Compiler
12151 It defines:
12153 HTML_HELP_COMPILER : full path to the Compiler (hhc.exe)
12155 HTML_HELP_INCLUDE_PATH : include path to the API (htmlhelp.h)
12156 HTML_HELP_LIBRARY : full path to the library (htmlhelp.lib)
12157 FindIce
12159 New in version 3.1.
12160 Find the ZeroC Internet Communication Engine (ICE) programs, libraries
12163 and datafiles.
12164 This module supports multiple components. Components can include any
12166 of: Freeze, Glacier2, Ice, IceBox, IceDB, IceDiscovery, IceGrid, IceLo‐
12167 catorDiscovery, IcePatch, IceSSL, IceStorm, IceUtil, IceXML, or Slice.
12168 Ice 3.7 and later also include C++11-specific components: Glacier2++11,
12170 Ice++11, IceBox++11, IceDiscovery++11 IceGrid, IceLocatorDiscovery++11,
12171 IceSSL++11, IceStorm++11
12172 Note that the set of supported components is Ice version-specific.
12174 New in version 3.4: Imported targets for components and most EXECUTABLE
12176 variables.
12177 New in version 3.7: Debug and Release variants are found separately.
12180 New in version 3.10: Ice 3.7 support, including new components, pro‐
12183 grams and the Nuget package.
12184 This module reports information about the Ice installation in several
12187 variables. General variables:
12188 Ice_VERSION - Ice release version
12190 Ice_FOUND - true if the main programs and libraries were found
12191 Ice_LIBRARIES - component libraries to be linked
12192 Ice_INCLUDE_DIRS - the directories containing the Ice headers
12193 Ice_SLICE_DIRS - the directories containing the Ice slice interface
12194 definitions
12195 Imported targets:
12197 Ice::<C>
12199 Where <C> is the name of an Ice component, for example Ice::Glacier2 or
12201 Ice++11.
12202 Ice slice programs are reported in:
12204 Ice_SLICE2CONFLUENCE_EXECUTABLE - path to slice2confluence executable
12206 Ice_SLICE2CPP_EXECUTABLE - path to slice2cpp executable
12207 Ice_SLICE2CS_EXECUTABLE - path to slice2cs executable
12208 Ice_SLICE2FREEZEJ_EXECUTABLE - path to slice2freezej executable
12209 Ice_SLICE2FREEZE_EXECUTABLE - path to slice2freeze executable
12210 Ice_SLICE2HTML_EXECUTABLE - path to slice2html executable
12211 Ice_SLICE2JAVA_EXECUTABLE - path to slice2java executable
12212 Ice_SLICE2JS_EXECUTABLE - path to slice2js executable
12213 Ice_SLICE2MATLAB_EXECUTABLE - path to slice2matlab executable
12214 Ice_SLICE2OBJC_EXECUTABLE - path to slice2objc executable
12215 Ice_SLICE2PHP_EXECUTABLE - path to slice2php executable
12216 Ice_SLICE2PY_EXECUTABLE - path to slice2py executable
12217 Ice_SLICE2RB_EXECUTABLE - path to slice2rb executable
12218 New in version 3.14: Variables for slice2confluence and slice2matlab.
12220 Ice programs are reported in:
12223 Ice_GLACIER2ROUTER_EXECUTABLE - path to glacier2router executable
12225 Ice_ICEBOX_EXECUTABLE - path to icebox executable
12226 Ice_ICEBOXXX11_EXECUTABLE - path to icebox++11 executable
12227 Ice_ICEBOXADMIN_EXECUTABLE - path to iceboxadmin executable
12228 Ice_ICEBOXD_EXECUTABLE - path to iceboxd executable
12229 Ice_ICEBOXNET_EXECUTABLE - path to iceboxnet executable
12230 Ice_ICEBRIDGE_EXECUTABLE - path to icebridge executable
12231 Ice_ICEGRIDADMIN_EXECUTABLE - path to icegridadmin executable
12232 Ice_ICEGRIDDB_EXECUTABLE - path to icegriddb executable
12233 Ice_ICEGRIDNODE_EXECUTABLE - path to icegridnode executable
12234 Ice_ICEGRIDNODED_EXECUTABLE - path to icegridnoded executable
12235 Ice_ICEGRIDREGISTRY_EXECUTABLE - path to icegridregistry executable
12236 Ice_ICEGRIDREGISTRYD_EXECUTABLE - path to icegridregistryd executable
12237 Ice_ICEPATCH2CALC_EXECUTABLE - path to icepatch2calc executable
12238 Ice_ICEPATCH2CLIENT_EXECUTABLE - path to icepatch2client executable
12239 Ice_ICEPATCH2SERVER_EXECUTABLE - path to icepatch2server executable
12240 Ice_ICESERVICEINSTALL_EXECUTABLE - path to iceserviceinstall executable
12241 Ice_ICESTORMADMIN_EXECUTABLE - path to icestormadmin executable
12242 Ice_ICESTORMDB_EXECUTABLE - path to icestormdb executable
12243 Ice_ICESTORMMIGRATE_EXECUTABLE - path to icestormmigrate executable
12244 Ice db programs (Windows only; standard system versions on all other
12246 platforms) are reported in:
12247 Ice_DB_ARCHIVE_EXECUTABLE - path to db_archive executable
12249 Ice_DB_CHECKPOINT_EXECUTABLE - path to db_checkpoint executable
12250 Ice_DB_DEADLOCK_EXECUTABLE - path to db_deadlock executable
12251 Ice_DB_DUMP_EXECUTABLE - path to db_dump executable
12252 Ice_DB_HOTBACKUP_EXECUTABLE - path to db_hotbackup executable
12253 Ice_DB_LOAD_EXECUTABLE - path to db_load executable
12254 Ice_DB_LOG_VERIFY_EXECUTABLE - path to db_log_verify executable
12255 Ice_DB_PRINTLOG_EXECUTABLE - path to db_printlog executable
12256 Ice_DB_RECOVER_EXECUTABLE - path to db_recover executable
12257 Ice_DB_STAT_EXECUTABLE - path to db_stat executable
12258 Ice_DB_TUNER_EXECUTABLE - path to db_tuner executable
12259 Ice_DB_UPGRADE_EXECUTABLE - path to db_upgrade executable
12260 Ice_DB_VERIFY_EXECUTABLE - path to db_verify executable
12261 Ice_DUMPDB_EXECUTABLE - path to dumpdb executable
12262 Ice_TRANSFORMDB_EXECUTABLE - path to transformdb executable
12263 Ice component libraries are reported in:
12265 Ice_<C>_FOUND - ON if component was found
12267 Ice_<C>_LIBRARIES - libraries for component
12268 Note that <C> is the uppercased name of the component.
12270 This module reads hints about search results from:
12272 Ice_HOME - the root of the Ice installation
12274 The environment variable ICE_HOME may also be used; the Ice_HOME vari‐
12276 able takes precedence.
12277 NOTE:
12279 On Windows, Ice 3.7.0 and later provide libraries via the NuGet
12280 package manager. Appropriate NuGet packages will be searched for
12281 using CMAKE_PREFIX_PATH, or alternatively Ice_HOME may be set to the
12282 location of a specific NuGet package to restrict the search.
12283 The following cache variables may also be set:
12285 Ice_<P>_EXECUTABLE - the path to executable <P>
12287 Ice_INCLUDE_DIR - the directory containing the Ice headers
12288 Ice_SLICE_DIR - the directory containing the Ice slice interface
12289 definitions
12290 Ice_<C>_LIBRARY - the library for component <C>
12291 NOTE:
12293 In most cases none of the above variables will require setting, un‐
12294 less multiple Ice versions are available and a specific version is
12295 required. On Windows, the most recent version of Ice will be found
12296 through the registry. On Unix, the programs, headers and libraries
12297 will usually be in standard locations, but Ice_SLICE_DIRS might not
12298 be automatically detected (commonly known locations are searched).
12299 All the other variables are defaulted using Ice_HOME, if set. It's
12300 possible to set Ice_HOME and selectively specify alternative loca‐
12301 tions for the other components; this might be required for e.g.
12302 newer versions of Visual Studio if the heuristics are not sufficient
12303 to identify the correct programs and libraries for the specific Vis‐
12304 ual Studio version.
12305 Other variables one may set to control this module are:
12307 Ice_DEBUG - Set to ON to enable debug output from FindIce.
12309 FindIconv
12311 New in version 3.11.
12312 This module finds the iconv() POSIX.1 functions on the system. These
12315 functions might be provided in the regular C library or externally in
12316 the form of an additional library.
12317 The following variables are provided to indicate iconv support:
12319 Iconv_FOUND
12321 Variable indicating if the iconv support was found.
12322 Iconv_INCLUDE_DIRS
12324 The directories containing the iconv headers.
12325 Iconv_LIBRARIES
12327 The iconv libraries to be linked.
12328 Iconv_VERSION
12330 New in version 3.21.
12331 The version of iconv found (x.y)
12334 Iconv_VERSION_MAJOR
12336 New in version 3.21.
12337 The major version of iconv
12340 Iconv_VERSION_MINOR
12342 New in version 3.21.
12343 The minor version of iconv
12346 Iconv_IS_BUILT_IN
12348 A variable indicating whether iconv support is stemming from the
12349 C library or not. Even if the C library provides iconv(), the
12350 presence of an external libiconv implementation might lead to
12351 this being false.
12352 Additionally, the following IMPORTED target is being provided:
12354 Iconv::Iconv
12356 Imported target for using iconv.
12357 The following cache variables may also be set:
12359 Iconv_INCLUDE_DIR
12361 The directory containing the iconv headers.
12362 Iconv_LIBRARY
12364 The iconv library (if not implicitly given in the C library).
12365 NOTE:
12367 On POSIX platforms, iconv might be part of the C library and the
12368 cache variables Iconv_INCLUDE_DIR and Iconv_LIBRARY might be empty.
12369 NOTE:
12371 Some libiconv implementations don't embed the version number in
12372 their header files. In this case the variables Iconv_VERSION* will
12373 be empty.
12374 FindIcotool
12376 Find icotool
12377 This module looks for icotool. Convert and create Win32 icon and cursor
12379 files. This module defines the following values:
12380 ICOTOOL_EXECUTABLE: the full path to the icotool tool.
12382 ICOTOOL_FOUND: True if icotool has been found.
12383 ICOTOOL_VERSION_STRING: the version of icotool found.
12384 FindICU
12386 New in version 3.7.
12387 Find the International Components for Unicode (ICU) libraries and pro‐
12390 grams.
12391 This module supports multiple components. Components can include any
12393 of: data, i18n, io, le, lx, test, tu and uc.
12394 Note that on Windows data is named dt and i18n is named in; any of the
12396 names may be used, and the appropriate platform-specific library name
12397 will be automatically selected.
12398 New in version 3.11: Added support for static libraries on Windows.
12400 This module reports information about the ICU installation in several
12403 variables. General variables:
12404 ICU_VERSION - ICU release version
12406 ICU_FOUND - true if the main programs and libraries were found
12407 ICU_LIBRARIES - component libraries to be linked
12408 ICU_INCLUDE_DIRS - the directories containing the ICU headers
12409 Imported targets:
12411 ICU::<C>
12413 Where <C> is the name of an ICU component, for example ICU::i18n; <C>
12415 is lower-case.
12416 ICU programs are reported in:
12418 ICU_GENCNVAL_EXECUTABLE - path to gencnval executable
12420 ICU_ICUINFO_EXECUTABLE - path to icuinfo executable
12421 ICU_GENBRK_EXECUTABLE - path to genbrk executable
12422 ICU_ICU-CONFIG_EXECUTABLE - path to icu-config executable
12423 ICU_GENRB_EXECUTABLE - path to genrb executable
12424 ICU_GENDICT_EXECUTABLE - path to gendict executable
12425 ICU_DERB_EXECUTABLE - path to derb executable
12426 ICU_PKGDATA_EXECUTABLE - path to pkgdata executable
12427 ICU_UCONV_EXECUTABLE - path to uconv executable
12428 ICU_GENCFU_EXECUTABLE - path to gencfu executable
12429 ICU_MAKECONV_EXECUTABLE - path to makeconv executable
12430 ICU_GENNORM2_EXECUTABLE - path to gennorm2 executable
12431 ICU_GENCCODE_EXECUTABLE - path to genccode executable
12432 ICU_GENSPREP_EXECUTABLE - path to gensprep executable
12433 ICU_ICUPKG_EXECUTABLE - path to icupkg executable
12434 ICU_GENCMN_EXECUTABLE - path to gencmn executable
12435 ICU component libraries are reported in:
12437 ICU_<C>_FOUND - ON if component was found; ``<C>`` is upper-case.
12439 ICU_<C>_LIBRARIES - libraries for component; ``<C>`` is upper-case.
12440 ICU datafiles are reported in:
12442 ICU_MAKEFILE_INC - Makefile.inc
12444 ICU_PKGDATA_INC - pkgdata.inc
12445 This module reads hints about search results from:
12447 ICU_ROOT - the root of the ICU installation
12449 The environment variable ICU_ROOT may also be used; the ICU_ROOT vari‐
12451 able takes precedence.
12452 The following cache variables may also be set:
12454 ICU_<P>_EXECUTABLE - the path to executable <P>; ``<P>`` is upper-case.
12456 ICU_INCLUDE_DIR - the directory containing the ICU headers
12457 ICU_<C>_LIBRARY - the library for component <C>; ``<C>`` is upper-case.
12458 NOTE:
12460 In most cases none of the above variables will require setting, un‐
12461 less multiple ICU versions are available and a specific version is
12462 required.
12463 Other variables one may set to control this module are:
12465 ICU_DEBUG - Set to ON to enable debug output from FindICU.
12467 FindImageMagick
12469 Find ImageMagick binary suite.
12470 New in version 3.9: Added support for ImageMagick 7.
12472 This module will search for a set of ImageMagick tools specified as
12475 components in the find_package() call. Typical components include, but
12476 are not limited to (future versions of ImageMagick might have addi‐
12477 tional components not listed here):
12478 animate
12480 compare
12481 composite
12482 conjure
12483 convert
12484 display
12485 identify
12486 import
12487 mogrify
12488 montage
12489 stream
12490 If no component is specified in the find_package() call, then it only
12492 searches for the ImageMagick executable directory. This code defines
12493 the following variables:
12494 ImageMagick_FOUND - TRUE if all components are found.
12496 ImageMagick_EXECUTABLE_DIR - Full path to executables directory.
12497 ImageMagick_<component>_FOUND - TRUE if <component> is found.
12498 ImageMagick_<component>_EXECUTABLE - Full path to <component> executable.
12499 ImageMagick_VERSION_STRING - the version of ImageMagick found
12500 (since CMake 2.8.8)
12501 ImageMagick_VERSION_STRING will not work for old versions like 5.2.3.
12503 There are also components for the following ImageMagick APIs:
12505 Magick++
12507 MagickWand
12508 MagickCore
12509 For these components the following variables are set:
12511 ImageMagick_FOUND - TRUE if all components are found.
12513 ImageMagick_INCLUDE_DIRS - Full paths to all include dirs.
12514 ImageMagick_LIBRARIES - Full paths to all libraries.
12515 ImageMagick_<component>_FOUND - TRUE if <component> is found.
12516 ImageMagick_<component>_INCLUDE_DIRS - Full path to <component> include dirs.
12517 ImageMagick_<component>_LIBRARIES - Full path to <component> libraries.
12518 Example Usages:
12520 find_package(ImageMagick)
12522 find_package(ImageMagick COMPONENTS convert)
12523 find_package(ImageMagick COMPONENTS convert mogrify display)
12524 find_package(ImageMagick COMPONENTS Magick++)
12525 find_package(ImageMagick COMPONENTS Magick++ convert)
12526 Note that the standard find_package() features are supported (i.e.,
12528 QUIET, REQUIRED, etc.).
12529 FindIntl
12531 New in version 3.2.
12532 Find the Gettext libintl headers and libraries.
12535 This module reports information about the Gettext libintl installation
12537 in several variables.
12538 Intl_FOUND
12540 True if libintl is found.
12541 Intl_INCLUDE_DIRS
12543 The directory containing the libintl headers.
12544 Intl_LIBRARIES
12546 The intl libraries to be linked.
12547 Intl_VERSION
12549 New in version 3.21.
12550 The version of intl found (x.y.z)
12553 Intl_VERSION_MAJOR
12555 New in version 3.21.
12556 The major version of intl
12559 Intl_VERSION_MINOR
12561 New in version 3.21.
12562 The minor version of intl
12565 Intl_VERSION_PATCH
12567 New in version 3.21.
12568 The patch version of intl
12571 New in version 3.20: This module defines IMPORTED target Intl::Intl.
12573 The following cache variables may also be set:
12576 Intl_INCLUDE_DIR
12578 The directory containing the libintl headers
12579 Intl_LIBRARY
12581 The libintl library (if any)
12582 Intl_IS_BUILT_IN
12584 New in version 3.20.
12585 whether intl is a part of the C library.
12588 NOTE:
12590 On some platforms, such as Linux with GNU libc, the gettext func‐
12591 tions are present in the C standard library and libintl is not re‐
12592 quired. Intl_LIBRARIES will be empty in this case.
12593 NOTE:
12595 Some libintl implementations don't embed the version number in their
12596 header files. In this case the variables Intl_VERSION* will be
12597 empty.
12598 NOTE:
12600 If you wish to use the Gettext tools (msgmerge, msgfmt, etc.), use
12601 FindGettext.
12602 FindITK
12604 This module no longer exists.
12605 This module existed in versions of CMake prior to 3.1, but became only
12607 a thin wrapper around find_package(ITK NO_MODULE) to provide compati‐
12608 bility for projects using long-outdated conventions. Now find_pack‐
12609 age(ITK) will search for ITKConfig.cmake directly.
12610 FindJasper
12612 Find the Jasper JPEG2000 library.
12613 IMPORTED Targets
12615 Jasper::Jasper
12616 The jasper library, if found.
12617 Result Variables
12619 This module defines the following variables:
12620 JASPER_FOUND
12622 system has Jasper
12623 JASPER_INCLUDE_DIRS
12625 New in version 3.22.
12626 the Jasper include directory
12629 JASPER_LIBRARIES
12631 the libraries needed to use Jasper
12632 JASPER_VERSION_STRING
12634 the version of Jasper found
12635 Cache variables
12637 The following cache variables may also be set:
12638 JASPER_INCLUDE_DIR
12640 where to find jasper/jasper.h, etc.
12641 JASPER_LIBRARY_RELEASE
12643 where to find the Jasper library (optimized).
12644 JASPER_LIBARRY_DEBUG
12646 where to find the Jasper library (debug).
12647 FindJava
12649 Find Java
12650 This module finds if Java is installed and determines where the include
12652 files and libraries are. The caller may set variable JAVA_HOME to
12653 specify a Java installation prefix explicitly.
12654 See also the FindJNI module to find Java Native Interface (JNI).
12656 New in version 3.10: Added support for Java 9+ version parsing.
12658 Specify one or more of the following components as you call this find
12661 module. See example below.
12662 Runtime = Java Runtime Environment used to execute Java byte-compiled applications
12664 Development = Development tools (java, javac, javah, jar and javadoc), includes Runtime component
12665 IdlJ = Interface Description Language (IDL) to Java compiler
12666 JarSigner = Signer and verifier tool for Java Archive (JAR) files
12667 This module sets the following result variables:
12669 Java_JAVA_EXECUTABLE = the full path to the Java runtime
12671 Java_JAVAC_EXECUTABLE = the full path to the Java compiler
12672 Java_JAVAH_EXECUTABLE = the full path to the Java header generator
12673 Java_JAVADOC_EXECUTABLE = the full path to the Java documentation generator
12674 Java_IDLJ_EXECUTABLE = the full path to the Java idl compiler
12675 Java_JAR_EXECUTABLE = the full path to the Java archiver
12676 Java_JARSIGNER_EXECUTABLE = the full path to the Java jar signer
12677 Java_VERSION_STRING = Version of java found, eg. 1.6.0_12
12678 Java_VERSION_MAJOR = The major version of the package found.
12679 Java_VERSION_MINOR = The minor version of the package found.
12680 Java_VERSION_PATCH = The patch version of the package found.
12681 Java_VERSION_TWEAK = The tweak version of the package found (after '_')
12682 Java_VERSION = This is set to: $major[.$minor[.$patch[.$tweak]]]
12683 New in version 3.4: Added the Java_IDLJ_EXECUTABLE and Java_JAR‐
12685 SIGNER_EXECUTABLE variables.
12686 The minimum required version of Java can be specified using the
12689 find_package() syntax, e.g.
12690 find_package(Java 1.8)
12692 NOTE: ${Java_VERSION} and ${Java_VERSION_STRING} are not guaranteed to
12694 be identical. For example some java version may return: Java_VER‐
12695 SION_STRING = 1.8.0_17 and Java_VERSION = 1.8.0.17
12696 another example is the Java OEM, with: Java_VERSION_STRING = 1.8.0-oem
12698 and Java_VERSION = 1.8.0
12699 For these components the following variables are set:
12701 Java_FOUND - TRUE if all components are found.
12703 Java_<component>_FOUND - TRUE if <component> is found.
12704 Example Usages:
12706 find_package(Java)
12708 find_package(Java 1.8 REQUIRED)
12709 find_package(Java COMPONENTS Runtime)
12710 find_package(Java COMPONENTS Development)
12711 FindJNI
12713 Find Java Native Interface (JNI) libraries.
12714 JNI enables Java code running in a Java Virtual Machine (JVM) to call
12716 and be called by native applications and libraries written in other
12717 languages such as C, C++.
12718 This module finds if Java is installed and determines where the include
12720 files and libraries are. It also determines what the name of the li‐
12721 brary is. The caller may set variable JAVA_HOME to specify a Java in‐
12722 stallation prefix explicitly.
12723 Result Variables
12725 This module sets the following result variables:
12726 JNI_INCLUDE_DIRS
12728 the include dirs to use
12729 JNI_LIBRARIES
12731 the libraries to use (JAWT and JVM)
12732 JNI_FOUND
12734 TRUE if JNI headers and libraries were found.
12735 Cache Variables
12737 The following cache variables are also available to set or use:
12738 JAVA_AWT_LIBRARY
12740 the path to the Java AWT Native Interface (JAWT) library
12741 JAVA_JVM_LIBRARY
12743 the path to the Java Virtual Machine (JVM) library
12744 JAVA_INCLUDE_PATH
12746 the include path to jni.h
12747 JAVA_INCLUDE_PATH2
12749 the include path to jni_md.h and jniport.h
12750 JAVA_AWT_INCLUDE_PATH
12752 the include path to jawt.h
12753 FindJPEG
12755 Find the Joint Photographic Experts Group (JPEG) library (libjpeg)
12756 Imported targets
12758 New in version 3.12.
12759 This module defines the following IMPORTED targets:
12762 JPEG::JPEG
12764 The JPEG library, if found.
12765 Result variables
12767 This module will set the following variables in your project:
12768 JPEG_FOUND
12770 If false, do not try to use JPEG.
12771 JPEG_INCLUDE_DIRS
12773 where to find jpeglib.h, etc.
12774 JPEG_LIBRARIES
12776 the libraries needed to use JPEG.
12777 JPEG_VERSION
12779 New in version 3.12: the version of the JPEG library found
12780 Cache variables
12783 The following cache variables may also be set:
12784 JPEG_INCLUDE_DIRS
12786 where to find jpeglib.h, etc.
12787 JPEG_LIBRARY_RELEASE
12789 where to find the JPEG library (optimized).
12790 JPEG_LIBRARY_DEBUG
12792 where to find the JPEG library (debug).
12793 New in version 3.12: Debug and Release variand are found separately.
12795 Obsolete variables
12798 JPEG_INCLUDE_DIR
12799 where to find jpeglib.h, etc. (same as JPEG_INCLUDE_DIRS)
12800 JPEG_LIBRARY
12802 where to find the JPEG library.
12803 FindKDE3
12805 Find the KDE3 include and library dirs, KDE preprocessors and define a
12806 some macros
12807 This module defines the following variables:
12809 KDE3_DEFINITIONS
12811 compiler definitions required for compiling KDE software
12812 KDE3_INCLUDE_DIR
12814 the KDE include directory
12815 KDE3_INCLUDE_DIRS
12817 the KDE and the Qt include directory, for use with include_di‐
12818 rectories()
12819 KDE3_LIB_DIR
12821 the directory where the KDE libraries are installed, for use
12822 with link_directories()
12823 QT_AND_KDECORE_LIBS
12825 this contains both the Qt and the kdecore library
12826 KDE3_DCOPIDL_EXECUTABLE
12828 the dcopidl executable
12829 KDE3_DCOPIDL2CPP_EXECUTABLE
12831 the dcopidl2cpp executable
12832 KDE3_KCFGC_EXECUTABLE
12834 the kconfig_compiler executable
12835 KDE3_FOUND
12837 set to TRUE if all of the above has been found
12838 The following user adjustable options are provided:
12840 KDE3_BUILD_TESTS
12842 enable this to build KDE testcases
12843 It also adds the following macros (from KDE3Macros.cmake) SRCS_VAR is
12845 always the variable which contains the list of source files for your
12846 application or library.
12847 KDE3_AUTOMOC(file1 ... fileN)
12849 Call this if you want to have automatic moc file handling.
12851 This means if you include "foo.moc" in the source file foo.cpp
12852 a moc file for the header foo.h will be created automatically.
12853 You can set the property SKIP_AUTOMAKE using set_source_files_properties()
12854 to exclude some files in the list from being processed.
12855 KDE3_ADD_MOC_FILES(SRCS_VAR file1 ... fileN )
12857 If you don't use the KDE3_AUTOMOC() macro, for the files
12859 listed here moc files will be created (named "foo.moc.cpp")
12860 KDE3_ADD_DCOP_SKELS(SRCS_VAR header1.h ... headerN.h )
12862 Use this to generate DCOP skeletions from the listed headers.
12864 KDE3_ADD_DCOP_STUBS(SRCS_VAR header1.h ... headerN.h )
12866 Use this to generate DCOP stubs from the listed headers.
12868 KDE3_ADD_UI_FILES(SRCS_VAR file1.ui ... fileN.ui )
12870 Use this to add the Qt designer ui files to your application/library.
12872 KDE3_ADD_KCFG_FILES(SRCS_VAR file1.kcfgc ... fileN.kcfgc )
12874 Use this to add KDE kconfig compiler files to your application/library.
12876 KDE3_INSTALL_LIBTOOL_FILE(target)
12878 This will create and install a simple libtool file for the given target.
12880 KDE3_ADD_EXECUTABLE(name file1 ... fileN )
12882 Currently identical to add_executable(), may provide some advanced
12884 features in the future.
12885 KDE3_ADD_KPART(name [WITH_PREFIX] file1 ... fileN )
12887 Create a KDE plugin (KPart, kioslave, etc.) from the given source files.
12889 If WITH_PREFIX is given, the resulting plugin will have the prefix "lib",
12890 otherwise it won't.
12891 It creates and installs an appropriate libtool la-file.
12892 KDE3_ADD_KDEINIT_EXECUTABLE(name file1 ... fileN )
12894 Create a KDE application in the form of a module loadable via kdeinit.
12896 A library named kdeinit_<name> will be created and a small executable
12897 which links to it.
12898 The option KDE3_ENABLE_FINAL to enable all-in-one compilation is no
12900 longer supported.
12901 Author: Alexander Neundorf <neundorf@kde.org>
12903 FindKDE4
12905 Find KDE4 and provide all necessary variables and macros to compile
12906 software for it. It looks for KDE 4 in the following directories in
12907 the given order:
12908 CMAKE_INSTALL_PREFIX
12910 KDEDIRS
12911 /opt/kde4
12912 Please look in FindKDE4Internal.cmake and KDE4Macros.cmake for more in‐
12914 formation. They are installed with the KDE 4 libraries in
12915 $KDEDIRS/share/apps/cmake/modules/.
12916 Author: Alexander Neundorf <neundorf@kde.org>
12918 FindLAPACK
12920 Find Linear Algebra PACKage (LAPACK) library
12921 This module finds an installed Fortran library that implements the
12923 LAPACK linear-algebra interface.
12924 At least one of the C, CXX, or Fortran languages must be enabled.
12926 Input Variables
12928 The following variables may be set to influence this module's behavior:
12929 BLA_STATIC
12931 if ON use static linkage
12932 BLA_VENDOR
12934 Set to one of the BLAS/LAPACK Vendors to search for BLAS only
12935 from the specified vendor. If not set, all vendors are consid‐
12936 ered.
12937 BLA_F95
12939 if ON tries to find the BLAS95/LAPACK95 interfaces
12940 BLA_PREFER_PKGCONFIG
12942 New in version 3.20.
12943 if set pkg-config will be used to search for a LAPACK library
12946 first and if one is found that is preferred
12947 BLA_SIZEOF_INTEGER
12949 New in version 3.22.
12950 Specify the BLAS/LAPACK library integer size:
12953 4 Search for a BLAS/LAPACK with 32-bit integer interfaces.
12955 8 Search for a BLAS/LAPACK with 64-bit integer interfaces.
12957 ANY Search for any BLAS/LAPACK. Most likely, a BLAS/LAPACK
12959 with 32-bit integer interfaces will be found.
12960 Imported targets
12962 This module defines the following IMPORTED targets:
12963 LAPACK::LAPACK
12965 New in version 3.18.
12966 The libraries to use for LAPACK, if found.
12969 Result Variables
12971 This module defines the following variables:
12972 LAPACK_FOUND
12974 library implementing the LAPACK interface is found
12975 LAPACK_LINKER_FLAGS
12977 uncached list of required linker flags (excluding -l and -L).
12978 LAPACK_LIBRARIES
12980 uncached list of libraries (using full path name) to link
12981 against to use LAPACK
12982 LAPACK95_LIBRARIES
12984 uncached list of libraries (using full path name) to link
12985 against to use LAPACK95
12986 LAPACK95_FOUND
12988 library implementing the LAPACK95 interface is found
12989 Intel MKL
12991 To use the Intel MKL implementation of LAPACK, a project must enable at
12992 least one of the C or CXX languages. Set BLA_VENDOR to an Intel MKL
12993 variant either on the command-line as -DBLA_VENDOR=Intel10_64lp or in
12994 project code:
12995 set(BLA_VENDOR Intel10_64lp)
12997 find_package(LAPACK)
12998 In order to build a project using Intel MKL, and end user must first
13000 establish an Intel MKL environment. See the FindBLAS module section on
13001 Intel MKL for details.
13002 FindLATEX
13004 Find LaTeX
13005 This module finds an installed LaTeX and determines the location of the
13007 compiler. Additionally the module looks for Latex-related software
13008 like BibTeX.
13009 New in version 3.2: Component processing; support for htlatex, pdftops,
13011 Biber, xindy, XeLaTeX, LuaLaTeX.
13012 This module sets the following result variables:
13015 LATEX_FOUND: whether found Latex and requested components
13017 LATEX_<component>_FOUND: whether found <component>
13018 LATEX_COMPILER: path to the LaTeX compiler
13019 PDFLATEX_COMPILER: path to the PdfLaTeX compiler
13020 XELATEX_COMPILER: path to the XeLaTeX compiler
13021 LUALATEX_COMPILER: path to the LuaLaTeX compiler
13022 BIBTEX_COMPILER: path to the BibTeX compiler
13023 BIBER_COMPILER: path to the Biber compiler
13024 MAKEINDEX_COMPILER: path to the MakeIndex compiler
13025 XINDY_COMPILER: path to the xindy compiler
13026 DVIPS_CONVERTER: path to the DVIPS converter
13027 DVIPDF_CONVERTER: path to the DVIPDF converter
13028 PS2PDF_CONVERTER: path to the PS2PDF converter
13029 PDFTOPS_CONVERTER: path to the pdftops converter
13030 LATEX2HTML_CONVERTER: path to the LaTeX2Html converter
13031 HTLATEX_COMPILER: path to the htlatex compiler
13032 Possible components are:
13034 PDFLATEX
13036 XELATEX
13037 LUALATEX
13038 BIBTEX
13039 BIBER
13040 MAKEINDEX
13041 XINDY
13042 DVIPS
13043 DVIPDF
13044 PS2PDF
13045 PDFTOPS
13046 LATEX2HTML
13047 HTLATEX
13048 Example Usages:
13050 find_package(LATEX)
13052 find_package(LATEX COMPONENTS PDFLATEX)
13053 find_package(LATEX COMPONENTS BIBTEX PS2PDF)
13054 FindLibArchive
13056 Find libarchive library and headers. Libarchive is multi-format ar‐
13057 chive and compression library.
13058 The module defines the following variables:
13060 LibArchive_FOUND - true if libarchive was found
13062 LibArchive_INCLUDE_DIRS - include search path
13063 LibArchive_LIBRARIES - libraries to link
13064 LibArchive_VERSION - libarchive 3-component version number
13065 The module defines the following IMPORTED targets:
13067 LibArchive::LibArchive - target for linking against libarchive
13069 New in version 3.6: Support for new libarchive 3.2 version string for‐
13071 mat.
13072 FindLibinput
13075 New in version 3.14.
13076 Find libinput headers and library.
13079 Imported Targets
13081 Libinput::Libinput
13082 The libinput library, if found.
13083 Result Variables
13085 This will define the following variables in your project:
13086 Libinput_FOUND
13088 true if (the requested version of) libinput is available.
13089 Libinput_VERSION
13091 the version of libinput.
13092 Libinput_LIBRARIES
13094 the libraries to link against to use libinput.
13095 Libinput_INCLUDE_DIRS
13097 where to find the libinput headers.
13098 Libinput_COMPILE_OPTIONS
13100 this should be passed to target_compile_options(), if the target
13101 is not used for linking
13102 FindLibLZMA
13104 Find LZMA compression algorithm headers and library.
13105 Imported Targets
13107 New in version 3.14.
13108 This module defines IMPORTED target LibLZMA::LibLZMA, if liblzma has
13111 been found.
13112 Result variables
13114 This module will set the following variables in your project:
13115 LIBLZMA_FOUND
13117 True if liblzma headers and library were found.
13118 LIBLZMA_INCLUDE_DIRS
13120 Directory where liblzma headers are located.
13121 LIBLZMA_LIBRARIES
13123 Lzma libraries to link against.
13124 LIBLZMA_HAS_AUTO_DECODER
13126 True if lzma_auto_decoder() is found (required).
13127 LIBLZMA_HAS_EASY_ENCODER
13129 True if lzma_easy_encoder() is found (required).
13130 LIBLZMA_HAS_LZMA_PRESET
13132 True if lzma_lzma_preset() is found (required).
13133 LIBLZMA_VERSION_MAJOR
13135 The major version of lzma
13136 LIBLZMA_VERSION_MINOR
13138 The minor version of lzma
13139 LIBLZMA_VERSION_PATCH
13141 The patch version of lzma
13142 LIBLZMA_VERSION_STRING
13144 version number as a string (ex: "5.0.3")
13145 FindLibXml2
13147 Find the XML processing library (libxml2).
13148 IMPORTED Targets
13150 New in version 3.12.
13151 The following IMPORTED targets may be defined:
13154 LibXml2::LibXml2
13156 libxml2 library.
13157 LibXml2::xmllint
13159 New in version 3.17.
13160 xmllint command-line executable.
13163 Result variables
13165 This module will set the following variables in your project:
13166 LibXml2_FOUND
13168 true if libxml2 headers and libraries were found
13169 LIBXML2_INCLUDE_DIR
13171 the directory containing LibXml2 headers
13172 LIBXML2_INCLUDE_DIRS
13174 list of the include directories needed to use LibXml2
13175 LIBXML2_LIBRARIES
13177 LibXml2 libraries to be linked
13178 LIBXML2_DEFINITIONS
13180 the compiler switches required for using LibXml2
13181 LIBXML2_XMLLINT_EXECUTABLE
13183 path to the XML checking tool xmllint coming with LibXml2
13184 LIBXML2_VERSION_STRING
13186 the version of LibXml2 found (since CMake 2.8.8)
13187 Cache variables
13189 The following cache variables may also be set:
13190 LIBXML2_INCLUDE_DIR
13192 the directory containing LibXml2 headers
13193 LIBXML2_LIBRARY
13195 path to the LibXml2 library
13196 FindLibXslt
13198 Find the XSL Transformations, Extensible Stylesheet Language Transfor‐
13199 mations (XSLT) library (LibXslt)
13200 IMPORTED Targets
13202 New in version 3.18.
13203 The following IMPORTED targets may be defined:
13206 LibXslt::LibXslt
13208 If the libxslt library has been found
13209 LibXslt::LibExslt
13211 If the libexslt library has been found
13212 LibXslt::xsltproc
13214 If the xsltproc command-line executable has been found
13215 Result variables
13217 This module will set the following variables in your project:
13218 LIBXSLT_FOUND - system has LibXslt LIBXSLT_INCLUDE_DIR - the LibXslt
13219 include directory LIBXSLT_LIBRARIES - Link these to LibXslt
13220 LIBXSLT_DEFINITIONS - Compiler switches required for using LibXslt
13221 LIBXSLT_VERSION_STRING - version of LibXslt found (since CMake
13222 2.8.8)
13223 Additionally, the following two variables are set (but not required for
13225 using xslt):
13226 LIBXSLT_EXSLT_INCLUDE_DIR
13228 New in version 3.18: The include directory for exslt.
13229 LIBXSLT_EXSLT_LIBRARIES
13232 Link to these if you need to link against the exslt library.
13233 LIBXSLT_XSLTPROC_EXECUTABLE
13235 Contains the full path to the xsltproc executable if found.
13236 FindLTTngUST
13238 New in version 3.6.
13239 Find Linux Trace Toolkit Next Generation (LTTng-UST) library.
13242 Imported target
13244 This module defines the following IMPORTED target:
13245 LTTng::UST
13247 The LTTng-UST library, if found
13248 Result variables
13250 This module sets the following
13251 LTTNGUST_FOUND
13253 TRUE if system has LTTng-UST
13254 LTTNGUST_INCLUDE_DIRS
13256 The LTTng-UST include directories
13257 LTTNGUST_LIBRARIES
13259 The libraries needed to use LTTng-UST
13260 LTTNGUST_VERSION_STRING
13262 The LTTng-UST version
13263 LTTNGUST_HAS_TRACEF
13265 TRUE if the tracef() API is available in the system's LTTng-UST
13266 LTTNGUST_HAS_TRACELOG
13268 TRUE if the tracelog() API is available in the system's LT‐
13269 Tng-UST
13270 FindLua
13272 Locate Lua library.
13273 New in version 3.18: Support for Lua 5.4.
13275 This module defines:
13278 ::
13280 LUA_FOUND - if false, do not try to link to Lua LUA_LI‐
13281 BRARIES - both lua and lualib LUA_INCLUDE_DIR - where to
13282 find lua.h LUA_VERSION_STRING - the version of Lua found LUA_VER‐
13283 SION_MAJOR - the major version of Lua LUA_VERSION_MINOR - the mi‐
13284 nor version of Lua LUA_VERSION_PATCH - the patch version of Lua
13285 Note that the expected include convention is
13287 #include "lua.h"
13289 and not
13291 #include <lua/lua.h>
13293 This is because, the lua location is not standardized and may exist in
13295 locations other than lua/
13296 FindLua50
13298 Locate Lua library. This module defines:
13299 ::
13301 LUA50_FOUND, if false, do not try to link to Lua LUA_LIBRARIES, both
13302 lua and lualib LUA_INCLUDE_DIR, where to find lua.h and lualib.h
13303 (and probably lauxlib.h)
13304 Note that the expected include convention is
13306 #include "lua.h"
13308 and not
13310 #include <lua/lua.h>
13312 This is because, the lua location is not standardized and may exist in
13314 locations other than lua/
13315 FindLua51
13317 Locate Lua library. This module defines:
13318 ::
13320 LUA51_FOUND, if false, do not try to link to Lua LUA_LIBRARIES
13321 LUA_INCLUDE_DIR, where to find lua.h LUA_VERSION_STRING, the version
13322 of Lua found (since CMake 2.8.8)
13323 Note that the expected include convention is
13325 #include "lua.h"
13327 and not
13329 #include <lua/lua.h>
13331 This is because, the lua location is not standardized and may exist in
13333 locations other than lua/
13334 FindMatlab
13336 Finds Matlab or Matlab Compiler Runtime (MCR) and provides Matlab
13337 tools, libraries and compilers to CMake.
13338 This package primary purpose is to find the libraries associated with
13340 Matlab or the MCR in order to be able to build Matlab extensions (mex
13341 files). It can also be used:
13342 • to run specific commands in Matlab in case Matlab is available
13344 • for declaring Matlab unit test
13346 • to retrieve various information from Matlab (mex extensions, versions
13348 and release queries, ...)
13349 New in version 3.12: Added Matlab Compiler Runtime (MCR) support.
13351 The module supports the following components:
13354 • ENG_LIBRARY and MAT_LIBRARY: respectively the ENG and MAT libraries
13356 of Matlab
13357 • MAIN_PROGRAM the Matlab binary program. Note that this component is
13359 not available on the MCR version, and will yield an error if the MCR
13360 is found instead of the regular Matlab installation.
13361 • MEX_COMPILER the MEX compiler.
13363 • MCC_COMPILER the MCC compiler, included with the Matlab Compiler
13365 add-on.
13366 • SIMULINK the Simulink environment.
13368 New in version 3.7: Added the MAT_LIBRARY component.
13370 New in version 3.13: Added the ENGINE_LIBRARY, DATAARRAY_LIBRARY and
13373 MCC_COMPILER components.
13374 Changed in version 3.14: Removed the MX_LIBRARY, ENGINE_LIBRARY and
13377 DATAARRAY_LIBRARY components. These libraries are found uncondition‐
13378 ally.
13379 NOTE:
13382 The version given to the find_package() directive is the Matlab ver‐
13383 sion, which should not be confused with the Matlab release name (eg.
13384 R2014). The matlab_get_version_from_release_name() and
13385 matlab_get_release_name_from_version() provide a mapping between the
13386 release name and the version.
13387 The variable Matlab_ROOT_DIR may be specified in order to give the path
13389 of the desired Matlab version. Otherwise, the behavior is platform spe‐
13390 cific:
13391 • Windows: The installed versions of Matlab/MCR are retrieved from the
13393 Windows registry
13394 • OS X: The installed versions of Matlab/MCR are given by the MATLAB
13396 default installation paths in /Application. If no such application is
13397 found, it falls back to the one that might be accessible from the
13398 PATH.
13399 • Unix: The desired Matlab should be accessible from the PATH. This
13401 does not work for MCR installation and Matlab_ROOT_DIR should be
13402 specified on this platform.
13403 Additional information is provided when MATLAB_FIND_DEBUG is set. When
13405 a Matlab/MCR installation is found automatically and the MATLAB_VERSION
13406 is not given, the version is queried from Matlab directly (on Windows
13407 this may pop up a Matlab window) or from the MCR installation.
13408 The mapping of the release names and the version of Matlab is performed
13410 by defining pairs (name, version). The variable
13411 MATLAB_ADDITIONAL_VERSIONS may be provided before the call to the
13412 find_package() in order to handle additional versions.
13413 A Matlab scripts can be added to the set of tests using the
13415 matlab_add_unit_test(). By default, the Matlab unit test framework will
13416 be used (>= 2013a) to run this script, but regular .m files returning
13417 an exit code can be used as well (0 indicating a success).
13418 Module Input Variables
13420 Users or projects may set the following variables to configure the mod‐
13421 ule behavior:
13422 Matlab_ROOT_DIR
13424 the root of the Matlab installation.
13425 MATLAB_FIND_DEBUG
13427 outputs debug information
13428 MATLAB_ADDITIONAL_VERSIONS
13430 additional versions of Matlab for the automatic retrieval of the
13431 installed versions.
13432 Imported targets
13434 New in version 3.22.
13435 This module defines the following IMPORTED targets:
13438 Matlab::mex
13440 The mex library, always available.
13441 Matlab::mx
13443 The mx library of Matlab (arrays), always available.
13444 Matlab::eng
13446 Matlab engine library. Available only if the ENG_LIBRARY compo‐
13447 nent is requested.
13448 Matlab::mat
13450 Matlab matrix library. Available only if the MAT_LIBRARY compo‐
13451 nent is requested.
13452 Matlab::MatlabEngine
13454 Matlab C++ engine library, always available for R2018a and
13455 newer.
13456 Matlab::MatlabDataArray
13458 Matlab C++ data array library, always available for R2018a and
13459 newer.
13460 Variables defined by the module
13462 Result variables
13463 Matlab_FOUND
13464 TRUE if the Matlab installation is found, FALSE otherwise. All
13465 variable below are defined if Matlab is found.
13466 Matlab_ROOT_DIR
13468 the final root of the Matlab installation determined by the
13469 FindMatlab module.
13470 Matlab_MAIN_PROGRAM
13472 the Matlab binary program. Available only if the component
13473 MAIN_PROGRAM is given in the find_package() directive.
13474 Matlab_INCLUDE_DIRS
13476 the path of the Matlab libraries headers
13477 Matlab_MEX_LIBRARY
13479 library for mex, always available.
13480 Matlab_MX_LIBRARY
13482 mx library of Matlab (arrays), always available.
13483 Matlab_ENG_LIBRARY
13485 Matlab engine library. Available only if the component ENG_LI‐
13486 BRARY is requested.
13487 Matlab_MAT_LIBRARY
13489 Matlab matrix library. Available only if the component MAT_LI‐
13490 BRARY is requested.
13491 Matlab_ENGINE_LIBRARY
13493 New in version 3.13.
13494 Matlab C++ engine library, always available for R2018a and
13497 newer.
13498 Matlab_DATAARRAY_LIBRARY
13500 New in version 3.13.
13501 Matlab C++ data array library, always available for R2018a and
13504 newer.
13505 Matlab_LIBRARIES
13507 the whole set of libraries of Matlab
13508 Matlab_MEX_COMPILER
13510 the mex compiler of Matlab. Currently not used. Available only
13511 if the component MEX_COMPILER is requested.
13512 Matlab_MCC_COMPILER
13514 New in version 3.13.
13515 the mcc compiler of Matlab. Included with the Matlab Compiler
13518 add-on. Available only if the component MCC_COMPILER is re‐
13519 quested.
13520 Cached variables
13522 Matlab_MEX_EXTENSION
13523 the extension of the mex files for the current platform (given
13524 by Matlab).
13525 Matlab_ROOT_DIR
13527 the location of the root of the Matlab installation found. If
13528 this value is changed by the user, the result variables are re‐
13529 computed.
13530 Provided macros
13532 matlab_get_version_from_release_name()
13533 returns the version from the release name
13534 matlab_get_release_name_from_version()
13536 returns the release name from the Matlab version
13537 Provided functions
13539 matlab_add_mex()
13540 adds a target compiling a MEX file.
13541 matlab_add_unit_test()
13543 adds a Matlab unit test file as a test to the project.
13544 matlab_extract_all_installed_versions_from_registry()
13546 parses the registry for all Matlab versions. Available on Win‐
13547 dows only. The part of the registry parsed is dependent on the
13548 host processor
13549 matlab_get_all_valid_matlab_roots_from_registry()
13551 returns all the possible Matlab or MCR paths, according to a
13552 previously given list. Only the existing/accessible paths are
13553 kept. This is mainly useful for the searching all possible Mat‐
13554 lab installation.
13555 matlab_get_mex_suffix()
13557 returns the suffix to be used for the mex files (platform/archi‐
13558 tecture dependent)
13559 matlab_get_version_from_matlab_run()
13561 returns the version of Matlab/MCR, given the full directory of
13562 the Matlab/MCR installation path.
13563 Known issues
13565 Symbol clash in a MEX target
13566 By default, every symbols inside a MEX file defined with the
13567 command matlab_add_mex() have hidden visibility, except for the
13568 entry point. This is the default behavior of the MEX compiler,
13569 which lowers the risk of symbol collision between the libraries
13570 shipped with Matlab, and the libraries to which the MEX file is
13571 linking to. This is also the default on Windows platforms.
13572 However, this is not sufficient in certain case, where for in‐
13574 stance your MEX file is linking against libraries that are al‐
13575 ready loaded by Matlab, even if those libraries have different
13576 SONAMES. A possible solution is to hide the symbols of the li‐
13577 braries to which the MEX target is linking to. This can be
13578 achieved in GNU GCC compilers with the linker option -Wl,--ex‐
13579 clude-libs,ALL.
13580 Tests using GPU resources
13582 in case your MEX file is using the GPU and in order to be able
13583 to run unit tests on this MEX file, the GPU resources should be
13584 properly released by Matlab. A possible solution is to make Mat‐
13585 lab aware of the use of the GPU resources in the session, which
13586 can be performed by a command such as D = gpuDevice() at the be‐
13587 ginning of the test script (or via a fixture).
13588 Reference
13590 Matlab_ROOT_DIR
13591 The root folder of the Matlab installation. If set before the
13592 call to find_package(), the module will look for the components
13593 in that path. If not set, then an automatic search of Matlab
13594 will be performed. If set, it should point to a valid version of
13595 Matlab.
13596 MATLAB_FIND_DEBUG
13598 If set, the lookup of Matlab and the intermediate configuration
13599 steps are outputted to the console.
13600 MATLAB_ADDITIONAL_VERSIONS
13602 If set, specifies additional versions of Matlab that may be
13603 looked for. The variable should be a list of strings, organized
13604 by pairs of release name and versions, such as follows:
13605 set(MATLAB_ADDITIONAL_VERSIONS
13607 "release_name1=corresponding_version1"
13608 "release_name2=corresponding_version2"
13609 ...
13610 )
13611 Example:
13613 set(MATLAB_ADDITIONAL_VERSIONS
13615 "R2013b=8.2"
13616 "R2013a=8.1"
13617 "R2012b=8.0")
13618 The order of entries in this list matters when several versions
13620 of Matlab are installed. The priority is set according to the
13621 ordering in this list.
13622 matlab_get_version_from_release_name
13624 Returns the version of Matlab (17.58) from a release name
13625 (R2017k)
13626 matlab_get_release_name_from_version
13628 Returns the release name (R2017k) from the version of Matlab
13629 (17.58)
13630 matlab_extract_all_installed_versions_from_registry
13632 This function parses the registry and founds the Matlab versions
13633 that are installed. The found versions are returned in mat‐
13634 lab_versions. Set win64 to TRUE if the 64 bit version of Matlab
13635 should be looked for The returned list contains all versions un‐
13636 der HKLM\\SOFTWARE\\Mathworks\\MATLAB and HKLM\\SOFTWARE\\Math‐
13637 works\\MATLAB Runtime or an empty list in case an error occurred
13638 (or nothing found).
13639 NOTE:
13641 Only the versions are provided. No check is made over the ex‐
13642 istence of the installation referenced in the registry,
13643 matlab_get_all_valid_matlab_roots_from_registry
13645 Populates the Matlab root with valid versions of Matlab or Mat‐
13646 lab Runtime (MCR). The returned matlab_roots is organized in
13647 triplets (type,version_number,matlab_root_path), where type in‐
13648 dicates either MATLAB or MCR.
13649 matlab_get_all_valid_matlab_roots_from_registry(
13651 matlab_versions
13652 matlab_roots)
13653 matlab_versions
13655 the versions of each of the Matlab or MCR installations
13656 matlab_roots
13658 the location of each of the Matlab or MCR installations
13659 matlab_get_mex_suffix
13661 Returns the extension of the mex files (the suffixes). This
13662 function should not be called before the appropriate Matlab root
13663 has been found.
13664 matlab_get_mex_suffix(
13666 matlab_root
13667 mex_suffix)
13668 matlab_root
13670 the root of the Matlab/MCR installation
13671 mex_suffix
13673 the variable name in which the suffix will be returned.
13674 matlab_get_version_from_matlab_run
13676 This function runs Matlab program specified on arguments and ex‐
13677 tracts its version. If the path provided for the Matlab instal‐
13678 lation points to an MCR installation, the version is extracted
13679 from the installed files.
13680 matlab_get_version_from_matlab_run(
13682 matlab_binary_path
13683 matlab_list_versions)
13684 matlab_binary_path
13686 the location of the matlab binary executable
13687 matlab_list_versions
13689 the version extracted from Matlab
13690 matlab_add_unit_test
13692 Adds a Matlab unit test to the test set of cmake/ctest. This
13693 command requires the component MAIN_PROGRAM and hence is not
13694 available for an MCR installation.
13695 The unit test uses the Matlab unittest framework (default,
13697 available starting Matlab 2013b+) except if the option
13698 NO_UNITTEST_FRAMEWORK is given.
13699 The function expects one Matlab test script file to be given.
13701 In the case NO_UNITTEST_FRAMEWORK is given, the unittest script
13702 file should contain the script to be run, plus an exit command
13703 with the exit value. This exit value will be passed to the ctest
13704 framework (0 success, non 0 failure). Additional arguments ac‐
13705 cepted by add_test() can be passed through TEST_ARGS (eg. CON‐
13706 FIGURATION <config> ...).
13707 matlab_add_unit_test(
13709 NAME <name>
13710 UNITTEST_FILE matlab_file_containing_unittest.m
13711 [CUSTOM_TEST_COMMAND matlab_command_to_run_as_test]
13712 [UNITTEST_PRECOMMAND matlab_command_to_run]
13713 [TIMEOUT timeout]
13714 [ADDITIONAL_PATH path1 [path2 ...]]
13715 [MATLAB_ADDITIONAL_STARTUP_OPTIONS option1 [option2 ...]]
13716 [TEST_ARGS arg1 [arg2 ...]]
13717 [NO_UNITTEST_FRAMEWORK]
13718 )
13719 The function arguments are:
13721 NAME name of the unittest in ctest.
13723 UNITTEST_FILE
13725 the matlab unittest file. Its path will be automatically
13726 added to the Matlab path.
13727 CUSTOM_TEST_COMMAND
13729 Matlab script command to run as the test. If this is not
13730 set, then the following is run: runtests('mat‐
13731 lab_file_name'), exit(max([ans(1,:).Failed])) where mat‐
13732 lab_file_name is the UNITTEST_FILE without the extension.
13733 UNITTEST_PRECOMMAND
13735 Matlab script command to be ran before the file contain‐
13736 ing the test (eg. GPU device initialization based on
13737 CMake variables).
13738 TIMEOUT
13740 the test timeout in seconds. Defaults to 180 seconds as
13741 the Matlab unit test may hang.
13742 ADDITIONAL_PATH
13744 a list of paths to add to the Matlab path prior to run‐
13745 ning the unit test.
13746 MATLAB_ADDITIONAL_STARTUP_OPTIONS
13748 a list of additional option in order to run Matlab from
13749 the command line. -nosplash -nodesktop -nodisplay are
13750 always added.
13751 TEST_ARGS
13753 Additional options provided to the add_test command.
13754 These options are added to the default options (eg. "CON‐
13755 FIGURATIONS Release")
13756 NO_UNITTEST_FRAMEWORK
13758 when set, indicates that the test should not use the
13759 unittest framework of Matlab (available for versions >=
13760 R2013a).
13761 WORKING_DIRECTORY
13763 This will be the working directory for the test. If spec‐
13764 ified it will also be the output directory used for the
13765 log file of the test run. If not specified the temporary
13766 directory ${CMAKE_BINARY_DIR}/Matlab will be used as the
13767 working directory and the log location.
13768 matlab_add_mex
13770 Adds a Matlab MEX target. This commands compiles the given
13771 sources with the current tool-chain in order to produce a MEX
13772 file. The final name of the produced output may be specified, as
13773 well as additional link libraries, and a documentation entry for
13774 the MEX file. Remaining arguments of the call are passed to the
13775 add_library() or add_executable() command.
13776 matlab_add_mex(
13778 NAME <name>
13779 [EXECUTABLE | MODULE | SHARED]
13780 SRC src1 [src2 ...]
13781 [OUTPUT_NAME output_name]
13782 [DOCUMENTATION file.txt]
13783 [LINK_TO target1 target2 ...]
13784 [R2017b | R2018a]
13785 [EXCLUDE_FROM_ALL]
13786 [...]
13787 )
13788 NAME name of the target.
13790 SRC list of source files.
13792 LINK_TO
13794 a list of additional link dependencies. The target links
13795 to libmex and libmx by default.
13796 OUTPUT_NAME
13798 if given, overrides the default name. The default name is
13799 the name of the target without any prefix and with Mat‐
13800 lab_MEX_EXTENSION suffix.
13801 DOCUMENTATION
13803 if given, the file file.txt will be considered as being
13804 the documentation file for the MEX file. This file is
13805 copied into the same folder without any processing, with
13806 the same name as the final mex file, and with extension
13807 .m. In that case, typing help <name> in Matlab prints the
13808 documentation contained in this file.
13809 R2017b or R2018a
13811 New in version 3.14.
13812 May be given to specify the version of the C API to use:
13815 R2017b specifies the traditional (separate complex) C
13816 API, and corresponds to the -R2017b flag for the mex com‐
13817 mand. R2018a specifies the new interleaved complex C API,
13818 and corresponds to the -R2018a flag for the mex command.
13819 Ignored if MATLAB version prior to R2018a. Defaults to
13820 R2017b.
13821 MODULE or SHARED
13823 New in version 3.7.
13824 May be given to specify the type of library to be cre‐
13827 ated.
13828 EXECUTABLE
13830 New in version 3.7.
13831 May be given to create an executable instead of a li‐
13834 brary. If no type is given explicitly, the type is
13835 SHARED.
13836 EXCLUDE_FROM_ALL
13838 This option has the same meaning as for EXCLUDE_FROM_ALL
13839 and is forwarded to add_library() or add_executable()
13840 commands.
13841 The documentation file is not processed and should be in the
13843 following format:
13844 % This is the documentation
13846 function ret = mex_target_output_name(input1)
13847 FindMFC
13849 Find Microsoft Foundation Class Library (MFC) on Windows
13850 Find the native MFC - i.e. decide if an application can link to the
13852 MFC libraries.
13853 MFC_FOUND - Was MFC support found
13855 You don't need to include anything or link anything to use it.
13857 FindMotif
13859 Try to find Motif (or lesstif)
13860 Once done this will define:
13862 MOTIF_FOUND - system has MOTIF
13864 MOTIF_INCLUDE_DIR - include paths to use Motif
13865 MOTIF_LIBRARIES - Link these to use Motif
13866 FindMPEG
13868 Find the native MPEG includes and library
13869 This module defines
13871 MPEG_INCLUDE_DIR, where to find MPEG.h, etc.
13873 MPEG_LIBRARIES, the libraries required to use MPEG.
13874 MPEG_FOUND, If false, do not try to use MPEG.
13875 also defined, but not for general use are
13877 MPEG_mpeg2_LIBRARY, where to find the MPEG library.
13879 MPEG_vo_LIBRARY, where to find the vo library.
13880 FindMPEG2
13882 Find the native MPEG2 includes and library
13883 This module defines
13885 MPEG2_INCLUDE_DIR, path to mpeg2dec/mpeg2.h, etc.
13887 MPEG2_LIBRARIES, the libraries required to use MPEG2.
13888 MPEG2_FOUND, If false, do not try to use MPEG2.
13889 also defined, but not for general use are
13891 MPEG2_mpeg2_LIBRARY, where to find the MPEG2 library.
13893 MPEG2_vo_LIBRARY, where to find the vo library.
13894 FindMPI
13896 Find a Message Passing Interface (MPI) implementation.
13897 The Message Passing Interface (MPI) is a library used to write
13899 high-performance distributed-memory parallel applications, and is typi‐
13900 cally deployed on a cluster. MPI is a standard interface (defined by
13901 the MPI forum) for which many implementations are available.
13902 New in version 3.10: Major overhaul of the module: many new variables,
13904 per-language components, support for a wider variety of runtimes.
13905 Variables for using MPI
13908 The module exposes the components C, CXX, MPICXX and Fortran. Each of
13909 these controls the various MPI languages to search for. The difference
13910 between CXX and MPICXX is that CXX refers to the MPI C API being usable
13911 from C++, whereas MPICXX refers to the MPI-2 C++ API that was removed
13912 again in MPI-3.
13913 Depending on the enabled components the following variables will be
13915 set:
13916 MPI_FOUND
13918 Variable indicating that MPI settings for all requested lan‐
13919 guages have been found. If no components are specified, this is
13920 true if MPI settings for all enabled languages were detected.
13921 Note that the MPICXX component does not affect this variable.
13922 MPI_VERSION
13924 Minimal version of MPI detected among the requested languages,
13925 or all enabled languages if no components were specified.
13926 This module will set the following variables per language in your
13928 project, where <lang> is one of C, CXX, or Fortran:
13929 MPI_<lang>_FOUND
13931 Variable indicating the MPI settings for <lang> were found and
13932 that simple MPI test programs compile with the provided set‐
13933 tings.
13934 MPI_<lang>_COMPILER
13936 MPI compiler for <lang> if such a program exists.
13937 MPI_<lang>_COMPILE_OPTIONS
13939 Compilation options for MPI programs in <lang>, given as a
13940 ;-list.
13941 MPI_<lang>_COMPILE_DEFINITIONS
13943 Compilation definitions for MPI programs in <lang>, given as a
13944 ;-list.
13945 MPI_<lang>_INCLUDE_DIRS
13947 Include path(s) for MPI header.
13948 MPI_<lang>_LINK_FLAGS
13950 Linker flags for MPI programs.
13951 MPI_<lang>_LIBRARIES
13953 All libraries to link MPI programs against.
13954 New in version 3.9: Additionally, the following IMPORTED targets are
13956 defined:
13957 MPI::MPI_<lang>
13960 Target for using MPI from <lang>.
13961 The following variables indicating which bindings are present will be
13963 defined:
13964 MPI_MPICXX_FOUND
13966 Variable indicating whether the MPI-2 C++ bindings are present
13967 (introduced in MPI-2, removed with MPI-3).
13968 MPI_Fortran_HAVE_F77_HEADER
13970 True if the Fortran 77 header mpif.h is available.
13971 MPI_Fortran_HAVE_F90_MODULE
13973 True if the Fortran 90 module mpi can be used for accessing MPI
13974 (MPI-2 and higher only).
13975 MPI_Fortran_HAVE_F08_MODULE
13977 True if the Fortran 2008 mpi_f08 is available to MPI programs
13978 (MPI-3 and higher only).
13979 If possible, the MPI version will be determined by this module. The fa‐
13981 cilities to detect the MPI version were introduced with MPI-1.2, and
13982 therefore cannot be found for older MPI versions.
13983 MPI_<lang>_VERSION_MAJOR
13985 Major version of MPI implemented for <lang> by the MPI distribu‐
13986 tion.
13987 MPI_<lang>_VERSION_MINOR
13989 Minor version of MPI implemented for <lang> by the MPI distribu‐
13990 tion.
13991 MPI_<lang>_VERSION
13993 MPI version implemented for <lang> by the MPI distribution.
13994 Note that there's no variable for the C bindings being accessible
13996 through mpi.h, since the MPI standards always have required this bind‐
13997 ing to work in both C and C++ code.
13998 For running MPI programs, the module sets the following variables
14000 MPIEXEC_EXECUTABLE
14002 Executable for running MPI programs, if such exists.
14003 MPIEXEC_NUMPROC_FLAG
14005 Flag to pass to mpiexec before giving it the number of proces‐
14006 sors to run on.
14007 MPIEXEC_MAX_NUMPROCS
14009 Number of MPI processors to utilize. Defaults to the number of
14010 processors detected on the host system.
14011 MPIEXEC_PREFLAGS
14013 Flags to pass to mpiexec directly before the executable to run.
14014 MPIEXEC_POSTFLAGS
14016 Flags to pass to mpiexec after other flags.
14017 Variables for locating MPI
14019 This module performs a four step search for an MPI implementation:
14020 1. Search for MPIEXEC_EXECUTABLE and, if found, use its base directory.
14022 2. Check if the compiler has MPI support built-in. This is the case if
14024 the user passed a compiler wrapper as CMAKE_<LANG>_COMPILER or if
14025 they use Cray system compiler wrappers.
14026 3. Attempt to find an MPI compiler wrapper and determine the compiler
14028 information from it.
14029 4. Try to find an MPI implementation that does not ship such a wrapper
14031 by guessing settings. Currently, only Microsoft MPI and MPICH2 on
14032 Windows are supported.
14033 For controlling the MPIEXEC_EXECUTABLE step, the following variables
14035 may be set:
14036 MPIEXEC_EXECUTABLE
14038 Manually specify the location of mpiexec.
14039 MPI_HOME
14041 Specify the base directory of the MPI installation.
14042 ENV{MPI_HOME}
14044 Environment variable to specify the base directory of the MPI
14045 installation.
14046 ENV{I_MPI_ROOT}
14048 Environment variable to specify the base directory of the MPI
14049 installation.
14050 For controlling the compiler wrapper step, the following variables may
14052 be set:
14053 MPI_<lang>_COMPILER
14055 Search for the specified compiler wrapper and use it.
14056 MPI_<lang>_COMPILER_FLAGS
14058 Flags to pass to the MPI compiler wrapper during interrogation.
14059 Some compiler wrappers support linking debug or tracing li‐
14060 braries if a specific flag is passed and this variable may be
14061 used to obtain them.
14062 MPI_COMPILER_FLAGS
14064 Used to initialize MPI_<lang>_COMPILER_FLAGS if no language spe‐
14065 cific flag has been given. Empty by default.
14066 MPI_EXECUTABLE_SUFFIX
14068 A suffix which is appended to all names that are being looked
14069 for. For instance you may set this to .mpich or .openmpi to pre‐
14070 fer the one or the other on Debian and its derivatives.
14071 In order to control the guessing step, the following variable may be
14073 set:
14074 MPI_GUESS_LIBRARY_NAME
14076 Valid values are MSMPI and MPICH2. If set, only the given li‐
14077 brary will be searched for. By default, MSMPI will be preferred
14078 over MPICH2 if both are available. This also sets MPI_SKIP_COM‐
14079 PILER_WRAPPER to true, which may be overridden.
14080 Each of the search steps may be skipped with the following control
14082 variables:
14083 MPI_ASSUME_NO_BUILTIN_MPI
14085 If true, the module assumes that the compiler itself does not
14086 provide an MPI implementation and skips to step 2.
14087 MPI_SKIP_COMPILER_WRAPPER
14089 If true, no compiler wrapper will be searched for.
14090 MPI_SKIP_GUESSING
14092 If true, the guessing step will be skipped.
14093 Additionally, the following control variable is available to change
14095 search behavior:
14096 MPI_CXX_SKIP_MPICXX
14098 Add some definitions that will disable the MPI-2 C++ bindings.
14099 Currently supported are MPICH, Open MPI, Platform MPI and deriv‐
14100 atives thereof, for example MVAPICH or Intel MPI.
14101 If the find procedure fails for a variable MPI_<lang>_WORKS, then the
14103 settings detected by or passed to the module did not work and even a
14104 simple MPI test program failed to compile.
14105 If all of these parameters were not sufficient to find the right MPI
14107 implementation, a user may disable the entire autodetection process by
14108 specifying both a list of libraries in MPI_<lang>_LIBRARIES and a list
14109 of include directories in MPI_<lang>_ADDITIONAL_INCLUDE_DIRS. Any
14110 other variable may be set in addition to these two. The module will
14111 then validate the MPI settings and store the settings in the cache.
14112 Cache variables for MPI
14114 The variable MPI_<lang>_INCLUDE_DIRS will be assembled from the follow‐
14115 ing variables. For C and CXX:
14116 MPI_<lang>_HEADER_DIR
14118 Location of the mpi.h header on disk.
14119 For Fortran:
14121 MPI_Fortran_F77_HEADER_DIR
14123 Location of the Fortran 77 header mpif.h, if it exists.
14124 MPI_Fortran_MODULE_DIR
14126 Location of the mpi or mpi_f08 modules, if available.
14127 For all languages the following variables are additionally considered:
14129 MPI_<lang>_ADDITIONAL_INCLUDE_DIRS
14131 A ;-list of paths needed in addition to the normal include di‐
14132 rectories.
14133 MPI_<include_name>_INCLUDE_DIR
14135 Path variables for include folders referred to by <in‐
14136 clude_name>.
14137 MPI_<lang>_ADDITIONAL_INCLUDE_VARS
14139 A ;-list of <include_name> that will be added to the include lo‐
14140 cations of <lang>.
14141 The variable MPI_<lang>_LIBRARIES will be assembled from the following
14143 variables:
14144 MPI_<lib_name>_LIBRARY
14146 The location of a library called <lib_name> for use with MPI.
14147 MPI_<lang>_LIB_NAMES
14149 A ;-list of <lib_name> that will be added to the include loca‐
14150 tions of <lang>.
14151 Usage of mpiexec
14153 When using MPIEXEC_EXECUTABLE to execute MPI applications, you should
14154 typically use all of the MPIEXEC_EXECUTABLE flags as follows:
14155 ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} ${MPIEXEC_MAX_NUMPROCS}
14157 ${MPIEXEC_PREFLAGS} EXECUTABLE ${MPIEXEC_POSTFLAGS} ARGS
14158 where EXECUTABLE is the MPI program, and ARGS are the arguments to pass
14160 to the MPI program.
14161 Advanced variables for using MPI
14163 The module can perform some advanced feature detections upon explicit
14164 request.
14165 Important notice: The following checks cannot be performed without exe‐
14167 cuting an MPI test program. Consider the special considerations for
14168 the behavior of try_run() during cross compilation. Moreover, running
14169 an MPI program can cause additional issues, like a firewall notifica‐
14170 tion on some systems. You should only enable these detections if you
14171 absolutely need the information.
14172 If the following variables are set to true, the respective search will
14174 be performed:
14175 MPI_DETERMINE_Fortran_CAPABILITIES
14177 Determine for all available Fortran bindings what the values of
14178 MPI_SUBARRAYS_SUPPORTED and MPI_ASYNC_PROTECTS_NONBLOCKING are
14179 and make their values available as MPI_Fortran_<binding>_SUBAR‐
14180 RAYS and MPI_Fortran_<binding>_ASYNCPROT, where <binding> is one
14181 of F77_HEADER, F90_MODULE and F08_MODULE.
14182 MPI_DETERMINE_LIBRARY_VERSION
14184 For each language, find the output of MPI_Get_library_version
14185 and make it available as MPI_<lang>_LIBRARY_VERSION_STRING.
14186 This information is usually tied to the runtime component of an
14187 MPI implementation and might differ depending on <lang>. Note
14188 that the return value is entirely implementation defined. This
14189 information might be used to identify the MPI vendor and for ex‐
14190 ample pick the correct one of multiple third party binaries that
14191 matches the MPI vendor.
14192 Backward Compatibility
14194 Deprecated since version 3.10.
14195 For backward compatibility with older versions of FindMPI, these vari‐
14198 ables are set:
14199 MPI_COMPILER MPI_LIBRARY MPI_EXTRA_LIBRARY
14201 MPI_COMPILE_FLAGS MPI_INCLUDE_PATH MPI_LINK_FLAGS
14202 MPI_LIBRARIES
14203 In new projects, please use the MPI_<lang>_XXX equivalents. Addition‐
14205 ally, the following variables are deprecated:
14206 MPI_<lang>_COMPILE_FLAGS
14208 Use MPI_<lang>_COMPILE_OPTIONS and MPI_<lang>_COMPILE_DEFINI‐
14209 TIONS instead.
14210 MPI_<lang>_INCLUDE_PATH
14212 For consumption use MPI_<lang>_INCLUDE_DIRS and for specifying
14213 folders use MPI_<lang>_ADDITIONAL_INCLUDE_DIRS instead.
14214 MPIEXEC
14216 Use MPIEXEC_EXECUTABLE instead.
14217 FindMsys
14219 New in version 3.21.
14220 Find MSYS, a POSIX-compatible environment that runs natively on Micro‐
14223 soft Windows
14224 FindODBC
14226 New in version 3.12.
14227 Find an Open Database Connectivity (ODBC) include directory and li‐
14230 brary.
14231 On Windows, when building with Visual Studio, this module assumes the
14233 ODBC library is provided by the available Windows SDK.
14234 On Unix, this module allows to search for ODBC library provided by
14236 unixODBC or iODBC implementations of ODBC API. This module reads hint
14237 about location of the config program:
14238 ODBC_CONFIG
14240 Location of odbc_config or iodbc-config program
14241 Otherwise, this module tries to find the config program, first from
14243 unixODBC, then from iODBC. If no config program found, this module
14244 searches for ODBC header and library in list of known locations.
14245 Imported targets
14247 This module defines the following IMPORTED targets:
14248 ODBC::ODBC
14250 Imported target for using the ODBC library, if found.
14251 Result variables
14253 ODBC_FOUND
14254 Set to true if ODBC library found, otherwise false or undefined.
14255 ODBC_INCLUDE_DIRS
14257 Paths to include directories listed in one variable for use by
14258 ODBC client. May be empty on Windows, where the include direc‐
14259 tory corresponding to the expected Windows SDK is already avail‐
14260 able in the compilation environment.
14261 ODBC_LIBRARIES
14263 Paths to libraries to linked against to use ODBC. May just a
14264 library name on Windows, where the library directory correspond‐
14265 ing to the expected Windows SDK is already available in the com‐
14266 pilation environment.
14267 ODBC_CONFIG
14269 Path to unixODBC or iODBC config program, if found or specified.
14270 Cache variables
14272 For users who wish to edit and control the module behavior, this module
14273 reads hints about search locations from the following variables:
14274 ODBC_INCLUDE_DIR
14276 Path to ODBC include directory with sql.h header.
14277 ODBC_LIBRARY
14279 Path to ODBC library to be linked.
14280 These variables should not be used directly by project code.
14282 Limitations
14284 On Windows, this module does not search for iODBC. On Unix, there is
14285 no way to prefer unixODBC over iODBC, or vice versa, other than provid‐
14286 ing the config program location using the ODBC_CONFIG. This module
14287 does not allow to search for a specific ODBC driver.
14288 FindOpenACC
14290 New in version 3.10.
14291 Detect OpenACC support by the compiler.
14294 This module can be used to detect OpenACC support in a compiler. If
14296 the compiler supports OpenACC, the flags required to compile with Ope‐
14297 nACC support are returned in variables for the different languages.
14298 Currently, only NVHPC, PGI, GNU and Cray compilers are supported.
14299 Imported Targets
14301 New in version 3.16.
14302 The module provides IMPORTED targets:
14305 OpenACC::OpenACC_<lang>
14307 Target for using OpenACC from <lang>.
14308 Variables
14310 This module will set the following variables per language in your
14311 project, where <lang> is one of C, CXX, or Fortran:
14312 OpenACC_<lang>_FOUND
14314 Variable indicating if OpenACC support for <lang> was detected.
14315 OpenACC_<lang>_FLAGS
14317 OpenACC compiler flags for <lang>, separated by spaces.
14318 OpenACC_<lang>_OPTIONS
14320 New in version 3.16.
14321 OpenACC compiler flags for <lang>, as a list. Suitable for usage
14324 with target_compile_options or target_link_options.
14325 The module will also try to provide the OpenACC version variables:
14327 OpenACC_<lang>_SPEC_DATE
14329 Date of the OpenACC specification implemented by the <lang> com‐
14330 piler.
14331 OpenACC_<lang>_VERSION_MAJOR
14333 Major version of OpenACC implemented by the <lang> compiler.
14334 OpenACC_<lang>_VERSION_MINOR
14336 Minor version of OpenACC implemented by the <lang> compiler.
14337 OpenACC_<lang>_VERSION
14339 OpenACC version implemented by the <lang> compiler.
14340 The specification date is formatted as given in the OpenACC standard:
14342 yyyymm where yyyy and mm represents the year and month of the OpenACC
14343 specification implemented by the <lang> compiler.
14344 Input Variables
14346 OpenACC_ACCEL_TARGET=<target> If set, will the correct target accelera‐
14347 tor flag set to the <target> will be returned with Ope‐
14348 nACC_<lang>_FLAGS.
14349 FindOpenAL
14351 Finds Open Audio Library (OpenAL).
14352 Projects using this module should use #include "al.h" to include the
14354 OpenAL header file, not #include <AL/al.h>. The reason for this is
14355 that the latter is not entirely portable. Windows/Creative Labs does
14356 not by default put their headers in AL/ and macOS uses the convention
14357 <OpenAL/al.h>.
14358 Hints
14360 Environment variable $OPENALDIR can be used to set the prefix of OpenAL
14361 installation to be found.
14362 By default on macOS, system framework is search first. In other words,
14364 OpenAL is searched in the following order:
14365 1. System framework: /System/Library/Frameworks, whose priority can be
14367 changed via setting the CMAKE_FIND_FRAMEWORK variable.
14368 2. Environment variable $OPENALDIR.
14370 3. System paths.
14372 4. User-compiled framework: ~/Library/Frameworks.
14374 5. Manually compiled framework: /Library/Frameworks.
14376 6. Add-on package: /opt.
14378 Result Variables
14380 This module defines the following variables:
14381 OPENAL_FOUND
14383 If false, do not try to link to OpenAL
14384 OPENAL_INCLUDE_DIR
14386 OpenAL include directory
14387 OPENAL_LIBRARY
14389 Path to the OpenAL library
14390 OPENAL_VERSION_STRING
14392 Human-readable string containing the version of OpenAL
14393 FindOpenCL
14395 New in version 3.1.
14396 Finds Open Computing Language (OpenCL)
14399 New in version 3.10: Detection of OpenCL 2.1 and 2.2.
14401 IMPORTED Targets
14404 New in version 3.7.
14405 This module defines IMPORTED target OpenCL::OpenCL, if OpenCL has been
14408 found.
14409 Result Variables
14411 This module defines the following variables:
14412 OpenCL_FOUND - True if OpenCL was found
14414 OpenCL_INCLUDE_DIRS - include directories for OpenCL
14415 OpenCL_LIBRARIES - link against this library to use OpenCL
14416 OpenCL_VERSION_STRING - Highest supported OpenCL version (eg. 1.2)
14417 OpenCL_VERSION_MAJOR - The major version of the OpenCL implementation
14418 OpenCL_VERSION_MINOR - The minor version of the OpenCL implementation
14419 The module will also define two cache variables:
14421 OpenCL_INCLUDE_DIR - the OpenCL include directory
14423 OpenCL_LIBRARY - the path to the OpenCL library
14424 FindOpenGL
14426 FindModule for OpenGL and OpenGL Utility Library (GLU).
14427 Changed in version 3.2: X11 is no longer added as a dependency on
14429 Unix/Linux systems.
14430 New in version 3.10: GLVND support on Linux. See the Linux-specific
14433 section below.
14434 Optional COMPONENTS
14437 New in version 3.10.
14438 This module respects several optional COMPONENTS: EGL, GLX, and OpenGL.
14441 There are corresponding import targets for each of these flags.
14442 IMPORTED Targets
14444 New in version 3.8.
14445 This module defines the IMPORTED targets:
14448 OpenGL::GL
14450 Defined to the platform-specific OpenGL libraries if the system
14451 has OpenGL.
14452 OpenGL::GLU
14454 Defined if the system has OpenGL Utility Library (GLU).
14455 New in version 3.10: Additionally, the following GLVND-specific library
14457 targets are defined:
14458 OpenGL::OpenGL
14461 Defined to libOpenGL if the system is GLVND-based.
14462 OpenGL::GLX
14464 Defined if the system has OpenGL Extension to the X Window Sys‐
14465 tem (GLX).
14466 OpenGL::EGL
14468 Defined if the system has EGL.
14469 Result Variables
14471 This module sets the following variables:
14472 OPENGL_FOUND
14474 True, if the system has OpenGL and all components are found.
14475 OPENGL_XMESA_FOUND
14477 True, if the system has XMESA.
14478 OPENGL_GLU_FOUND
14480 True, if the system has GLU.
14481 OpenGL_OpenGL_FOUND
14483 True, if the system has an OpenGL library.
14484 OpenGL_GLX_FOUND
14486 True, if the system has GLX.
14487 OpenGL_EGL_FOUND
14489 True, if the system has EGL.
14490 OPENGL_INCLUDE_DIR
14492 Path to the OpenGL include directory.
14493 OPENGL_EGL_INCLUDE_DIRS
14495 Path to the EGL include directory.
14496 OPENGL_LIBRARIES
14498 Paths to the OpenGL library, windowing system libraries, and GLU
14499 libraries. On Linux, this assumes GLX and is never correct for
14500 EGL-based targets. Clients are encouraged to use the OpenGL::*
14501 import targets instead.
14502 New in version 3.10: Variables for GLVND-specific libraries OpenGL, EGL
14504 and GLX.
14505 Cache variables
14508 The following cache variables may also be set:
14509 OPENGL_egl_LIBRARY
14511 Path to the EGL library.
14512 OPENGL_glu_LIBRARY
14514 Path to the GLU library.
14515 OPENGL_glx_LIBRARY
14517 Path to the GLVND 'GLX' library.
14518 OPENGL_opengl_LIBRARY
14520 Path to the GLVND 'OpenGL' library
14521 OPENGL_gl_LIBRARY
14523 Path to the OpenGL library. New code should prefer the
14524 OpenGL::* import targets.
14525 New in version 3.10: Variables for GLVND-specific libraries OpenGL, EGL
14527 and GLX.
14528 Linux-specific
14531 Some Linux systems utilize GLVND as a new ABI for OpenGL. GLVND sepa‐
14532 rates context libraries from OpenGL itself; OpenGL lives in "li‐
14533 bOpenGL", and contexts are defined in "libGLX" or "libEGL". GLVND is
14534 currently the only way to get OpenGL 3+ functionality via EGL in a man‐
14535 ner portable across vendors. Projects may use GLVND explicitly with
14536 target OpenGL::OpenGL and either OpenGL::GLX or OpenGL::EGL.
14537 Projects may use the OpenGL::GL target (or OPENGL_LIBRARIES variable)
14539 to use legacy GL interfaces. These will use the legacy GL library lo‐
14540 cated by OPENGL_gl_LIBRARY, if available. If OPENGL_gl_LIBRARY is
14541 empty or not found and GLVND is available, the OpenGL::GL target will
14542 use GLVND OpenGL::OpenGL and OpenGL::GLX (and the OPENGL_LIBRARIES
14543 variable will use the corresponding libraries). Thus, for
14544 non-EGL-based Linux targets, the OpenGL::GL target is most portable.
14545 A OpenGL_GL_PREFERENCE variable may be set to specify the preferred way
14547 to provide legacy GL interfaces in case multiple choices are available.
14548 The value may be one of:
14549 GLVND If the GLVND OpenGL and GLX libraries are available, prefer
14551 them. This forces OPENGL_gl_LIBRARY to be empty.
14552 Changed in version 3.11: This is the default, unless policy
14554 CMP0072 is set to OLD and no components are requeted (since com‐
14555 ponents correspond to GLVND libraries).
14556 LEGACY Prefer to use the legacy libGL library, if available.
14559 For EGL targets the client must rely on GLVND support on the user's
14561 system. Linking should use the OpenGL::OpenGL OpenGL::EGL targets.
14562 Using GLES* libraries is theoretically possible in place of
14563 OpenGL::OpenGL, but this module does not currently support that; con‐
14564 tributions welcome.
14565 OPENGL_egl_LIBRARY and OPENGL_EGL_INCLUDE_DIRS are defined in the case
14567 of GLVND. For non-GLVND Linux and other systems these are left unde‐
14568 fined.
14569 macOS-Specific
14571 On OSX FindOpenGL defaults to using the framework version of OpenGL.
14572 People will have to change the cache values of OPENGL_glu_LIBRARY and
14573 OPENGL_gl_LIBRARY to use OpenGL with X11 on OSX.
14574 FindOpenMP
14576 Finds Open Multi-Processing (OpenMP) support.
14577 This module can be used to detect OpenMP support in a compiler. If the
14579 compiler supports OpenMP, the flags required to compile with OpenMP
14580 support are returned in variables for the different languages. The
14581 variables may be empty if the compiler does not need a special flag to
14582 support OpenMP.
14583 New in version 3.5: Clang support.
14585 Variables
14588 New in version 3.10: The module exposes the components C, CXX, and For‐
14589 tran. Each of these controls the various languages to search OpenMP
14590 support for.
14591 Depending on the enabled components the following variables will be
14594 set:
14595 OpenMP_FOUND
14597 Variable indicating that OpenMP flags for all requested lan‐
14598 guages have been found. If no components are specified, this is
14599 true if OpenMP settings for all enabled languages were detected.
14600 OpenMP_VERSION
14602 Minimal version of the OpenMP standard detected among the re‐
14603 quested languages, or all enabled languages if no components
14604 were specified.
14605 This module will set the following variables per language in your
14607 project, where <lang> is one of C, CXX, or Fortran:
14608 OpenMP_<lang>_FOUND
14610 Variable indicating if OpenMP support for <lang> was detected.
14611 OpenMP_<lang>_FLAGS
14613 OpenMP compiler flags for <lang>, separated by spaces.
14614 OpenMP_<lang>_INCLUDE_DIRS
14616 Directories that must be added to the header search path for
14617 <lang> when using OpenMP.
14618 For linking with OpenMP code written in <lang>, the following variables
14620 are provided:
14621 OpenMP_<lang>_LIB_NAMES
14623 ;-list of libraries for OpenMP programs for <lang>.
14624 OpenMP_<libname>_LIBRARY
14626 Location of the individual libraries needed for OpenMP support
14627 in <lang>.
14628 OpenMP_<lang>_LIBRARIES
14630 A list of libraries needed to link with OpenMP code written in
14631 <lang>.
14632 Additionally, the module provides IMPORTED targets:
14634 OpenMP::OpenMP_<lang>
14636 Target for using OpenMP from <lang>.
14637 Specifically for Fortran, the module sets the following variables:
14639 OpenMP_Fortran_HAVE_OMPLIB_HEADER
14641 Boolean indicating if OpenMP is accessible through omp_lib.h.
14642 OpenMP_Fortran_HAVE_OMPLIB_MODULE
14644 Boolean indicating if OpenMP is accessible through the omp_lib
14645 Fortran module.
14646 The module will also try to provide the OpenMP version variables:
14648 OpenMP_<lang>_SPEC_DATE
14650 New in version 3.7.
14651 Date of the OpenMP specification implemented by the <lang> com‐
14654 piler.
14655 OpenMP_<lang>_VERSION_MAJOR
14657 Major version of OpenMP implemented by the <lang> compiler.
14658 OpenMP_<lang>_VERSION_MINOR
14660 Minor version of OpenMP implemented by the <lang> compiler.
14661 OpenMP_<lang>_VERSION
14663 OpenMP version implemented by the <lang> compiler.
14664 The specification date is formatted as given in the OpenMP standard:
14666 yyyymm where yyyy and mm represents the year and month of the OpenMP
14667 specification implemented by the <lang> compiler.
14668 For some compilers, it may be necessary to add a header search path to
14670 find the relevant OpenMP headers. This location may be language-spe‐
14671 cific. Where this is needed, the module may attempt to find the loca‐
14672 tion, but it can be provided directly by setting the OpenMP_<lang>_IN‐
14673 CLUDE_DIR cache variable. Note that this variable is an _input_ con‐
14674 trol to the module. Project code should use the OpenMP_<lang>_IN‐
14675 CLUDE_DIRS _output_ variable if it needs to know what include directo‐
14676 ries are needed.
14677 FindOpenSceneGraph
14679 Find OpenSceneGraph (3D graphics application programming interface)
14680 This module searches for the OpenSceneGraph core "osg" library as well
14682 as FindOpenThreads, and whatever additional COMPONENTS (nodekits) that
14683 you specify.
14684 See http://www.openscenegraph.org
14686 NOTE: To use this module effectively you must either require CMake >=
14688 2.6.3 with cmake_minimum_required(VERSION 2.6.3) or download and place
14689 FindOpenThreads, Findosg functions, Findosg and Find<etc>.cmake files
14690 into your CMAKE_MODULE_PATH.
14691 ----
14694 This module accepts the following variables (note mixed case)
14698 OpenSceneGraph_DEBUG - Enable debugging output
14700 OpenSceneGraph_MARK_AS_ADVANCED - Mark cache variables as advanced
14702 automatically
14703 The following environment variables are also respected for finding the
14705 OSG and it's various components. CMAKE_PREFIX_PATH can also be used
14706 for this (see find_library() CMake documentation).
14707 <MODULE>_DIR
14709 (where MODULE is of the form "OSGVOLUME" and there is a Findos‐
14710 gVolume.cmake` file)
14711 OSG_DIR
14713 OSGDIR
14715 OSG_ROOT
14717 [CMake 2.8.10]: The CMake variable OSG_DIR can now be used as well to
14719 influence detection, instead of needing to specify an environment vari‐
14720 able.
14721 This module defines the following output variables:
14723 OPENSCENEGRAPH_FOUND - Was the OSG and all of the specified components found?
14725 OPENSCENEGRAPH_VERSION - The version of the OSG which was found
14727 OPENSCENEGRAPH_INCLUDE_DIRS - Where to find the headers
14729 OPENSCENEGRAPH_LIBRARIES - The OSG libraries
14731 ================================== Example Usage:
14733 find_package(OpenSceneGraph 2.0.0 REQUIRED osgDB osgUtil)
14735 # libOpenThreads & libosg automatically searched
14736 include_directories(${OPENSCENEGRAPH_INCLUDE_DIRS})
14737 add_executable(foo foo.cc)
14739 target_link_libraries(foo ${OPENSCENEGRAPH_LIBRARIES})
14740 FindOpenSSL
14742 Find the OpenSSL encryption library.
14743 This module finds an installed OpenSSL library and determines its ver‐
14745 sion.
14746 New in version 3.19: When a version is requested, it can be specified
14748 as a simple value or as a range. For a detailed description of version
14749 range usage and capabilities, refer to the find_package() command.
14750 New in version 3.18: Support for OpenSSL 3.0.
14753 Optional COMPONENTS
14756 New in version 3.12.
14757 This module supports two optional COMPONENTS: Crypto and SSL. Both
14760 components have associated imported targets, as described below.
14761 Imported Targets
14763 New in version 3.4.
14764 This module defines the following IMPORTED targets:
14767 OpenSSL::SSL
14769 The OpenSSL ssl library, if found.
14770 OpenSSL::Crypto
14772 The OpenSSL crypto library, if found.
14773 OpenSSL::applink
14775 New in version 3.18.
14776 The OpenSSL applink components that might be need to be compiled
14779 into projects under MSVC. This target is available only if found
14780 OpenSSL version is not less than 0.9.8. By linking this target
14781 the above OpenSSL targets can be linked even if the project has
14782 different MSVC runtime configurations with the above OpenSSL
14783 targets. This target has no effect on platforms other than MSVC.
14784 NOTE: Due to how INTERFACE_SOURCES are consumed by the consuming tar‐
14786 get, unless you certainly know what you are doing, it is always pre‐
14787 ferred to link OpenSSL::applink target as PRIVATE and to make sure that
14788 this target is linked at most once for the whole dependency graph of
14789 any library or executable:
14790 target_link_libraries(myTarget PRIVATE OpenSSL::applink)
14792 Otherwise you would probably encounter unexpected random problems when
14794 building and linking, as both the ISO C and the ISO C++ standard claims
14795 almost nothing about what a link process should be.
14796 Result Variables
14798 This module will set the following variables in your project:
14799 OPENSSL_FOUND
14801 System has the OpenSSL library. If no components are requested
14802 it only requires the crypto library.
14803 OPENSSL_INCLUDE_DIR
14805 The OpenSSL include directory.
14806 OPENSSL_CRYPTO_LIBRARY
14808 The OpenSSL crypto library.
14809 OPENSSL_CRYPTO_LIBRARIES
14811 The OpenSSL crypto library and its dependencies.
14812 OPENSSL_SSL_LIBRARY
14814 The OpenSSL SSL library.
14815 OPENSSL_SSL_LIBRARIES
14817 The OpenSSL SSL library and its dependencies.
14818 OPENSSL_LIBRARIES
14820 All OpenSSL libraries and their dependencies.
14821 OPENSSL_VERSION
14823 This is set to $major.$minor.$revision$patch (e.g. 0.9.8s).
14824 OPENSSL_APPLINK_SOURCE
14826 The sources in the target OpenSSL::applink that is mentioned
14827 above. This variable shall always be undefined if found openssl
14828 version is less than 0.9.8 or if platform is not MSVC.
14829 Hints
14831 Set OPENSSL_ROOT_DIR to the root directory of an OpenSSL installation.
14832 New in version 3.4: Set OPENSSL_USE_STATIC_LIBS to TRUE to look for
14834 static libraries.
14835 New in version 3.5: Set OPENSSL_MSVC_STATIC_RT set TRUE to choose the
14838 MT version of the lib.
14839 FindOpenThreads
14842 OpenThreads is a C++ based threading library. Its largest userbase
14843 seems to OpenSceneGraph so you might notice I accept OSGDIR as an envi‐
14844 ronment path. I consider this part of the Findosg* suite used to find
14845 OpenSceneGraph components. Each component is separate and you must opt
14846 in to each module.
14847 Locate OpenThreads This module defines OPENTHREADS_LIBRARY
14849 OPENTHREADS_FOUND, if false, do not try to link to OpenThreads
14850 OPENTHREADS_INCLUDE_DIR, where to find the headers
14851 $OPENTHREADS_DIR is an environment variable that would correspond to
14853 the ./configure --prefix=$OPENTHREADS_DIR used in building osg.
14854 [CMake 2.8.10]: The CMake variables OPENTHREADS_DIR or OSG_DIR can now
14856 be used as well to influence detection, instead of needing to specify
14857 an environment variable.
14858 Created by Eric Wing.
14860 Findosg
14862 NOTE: It is highly recommended that you use the new FindOpenScene‐
14863 Graph.cmake introduced in CMake 2.6.3 and not use this Find module di‐
14864 rectly.
14865 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14867 nents. Each component is separate and you must opt in to each module.
14868 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14869 as these modules won't do it for you. This is to allow you control
14870 over your own system piece by piece in case you need to opt out of cer‐
14871 tain components or change the Find behavior for a particular module
14872 (perhaps because the default FindOpenGL.cmake module doesn't work with
14873 your system as an example). If you want to use a more convenient mod‐
14874 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14875 of the Findosg*.cmake modules.
14876 Locate osg This module defines
14878 OSG_FOUND - Was the Osg found? OSG_INCLUDE_DIR - Where to find the
14880 headers OSG_LIBRARIES - The libraries to link against for the OSG (use
14881 this)
14882 OSG_LIBRARY - The OSG library OSG_LIBRARY_DEBUG - The OSG debug library
14884 $OSGDIR is an environment variable that would correspond to the ./con‐
14886 figure --prefix=$OSGDIR used in building osg.
14887 Created by Eric Wing.
14889 Findosg_functions
14891 This CMake file contains two macros to assist with searching for OSG
14892 libraries and nodekits. Please see FindOpenSceneGraph.cmake for full
14893 documentation.
14894 FindosgAnimation
14896 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14897 nents. Each component is separate and you must opt in to each module.
14898 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14899 as these modules won't do it for you. This is to allow you control
14900 over your own system piece by piece in case you need to opt out of cer‐
14901 tain components or change the Find behavior for a particular module
14902 (perhaps because the default FindOpenGL.cmake module doesn't work with
14903 your system as an example). If you want to use a more convenient mod‐
14904 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14905 of the Findosg*.cmake modules.
14906 Locate osgAnimation This module defines
14908 OSGANIMATION_FOUND - Was osgAnimation found? OSGANIMATION_INCLUDE_DIR -
14910 Where to find the headers OSGANIMATION_LIBRARIES - The libraries to
14911 link against for the OSG (use this)
14912 OSGANIMATION_LIBRARY - The OSG library OSGANIMATION_LIBRARY_DEBUG - The
14914 OSG debug library
14915 $OSGDIR is an environment variable that would correspond to the ./con‐
14917 figure --prefix=$OSGDIR used in building osg.
14918 Created by Eric Wing.
14920 FindosgDB
14922 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14923 nents. Each component is separate and you must opt in to each module.
14924 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14925 as these modules won't do it for you. This is to allow you control
14926 over your own system piece by piece in case you need to opt out of cer‐
14927 tain components or change the Find behavior for a particular module
14928 (perhaps because the default FindOpenGL module doesn't work with your
14929 system as an example). If you want to use a more convenient module
14930 that includes everything, use the FindOpenSceneGraph instead of the
14931 Findosg*.cmake modules.
14932 Locate osgDB This module defines:
14934 OSGDB_FOUND
14936 Was osgDB found?
14937 OSGDB_INCLUDE_DIR
14939 Where to find the headers
14940 OSGDB_LIBRARIES
14942 The libraries to link against for the osgDB
14943 OSGDB_LIBRARY
14945 The osgDB library
14946 OSGDB_LIBRARY_DEBUG
14948 The osgDB debug library
14949 $OSGDIR is an environment variable that would correspond to:
14951 ./configure --prefix=$OSGDIR used in building osg.
14953 FindosgFX
14955 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14956 nents. Each component is separate and you must opt in to each module.
14957 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14958 as these modules won't do it for you. This is to allow you control
14959 over your own system piece by piece in case you need to opt out of cer‐
14960 tain components or change the Find behavior for a particular module
14961 (perhaps because the default FindOpenGL.cmake module doesn't work with
14962 your system as an example). If you want to use a more convenient mod‐
14963 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14964 of the Findosg*.cmake modules.
14965 Locate osgFX This module defines
14967 OSGFX_FOUND - Was osgFX found? OSGFX_INCLUDE_DIR - Where to find the
14969 headers OSGFX_LIBRARIES - The libraries to link against for the osgFX
14970 (use this)
14971 OSGFX_LIBRARY - The osgFX library OSGFX_LIBRARY_DEBUG - The osgFX debug
14973 library
14974 $OSGDIR is an environment variable that would correspond to the ./con‐
14976 figure --prefix=$OSGDIR used in building osg.
14977 Created by Eric Wing.
14979 FindosgGA
14981 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
14982 nents. Each component is separate and you must opt in to each module.
14983 You must also opt into OpenGL and OpenThreads (and Producer if needed)
14984 as these modules won't do it for you. This is to allow you control
14985 over your own system piece by piece in case you need to opt out of cer‐
14986 tain components or change the Find behavior for a particular module
14987 (perhaps because the default FindOpenGL.cmake module doesn't work with
14988 your system as an example). If you want to use a more convenient mod‐
14989 ule that includes everything, use the FindOpenSceneGraph.cmake instead
14990 of the Findosg*.cmake modules.
14991 Locate osgGA This module defines
14993 OSGGA_FOUND - Was osgGA found? OSGGA_INCLUDE_DIR - Where to find the
14995 headers OSGGA_LIBRARIES - The libraries to link against for the osgGA
14996 (use this)
14997 OSGGA_LIBRARY - The osgGA library OSGGA_LIBRARY_DEBUG - The osgGA debug
14999 library
15000 $OSGDIR is an environment variable that would correspond to the ./con‐
15002 figure --prefix=$OSGDIR used in building osg.
15003 Created by Eric Wing.
15005 FindosgIntrospection
15007 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15008 nents. Each component is separate and you must opt in to each module.
15009 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15010 as these modules won't do it for you. This is to allow you control
15011 over your own system piece by piece in case you need to opt out of cer‐
15012 tain components or change the Find behavior for a particular module
15013 (perhaps because the default FindOpenGL.cmake module doesn't work with
15014 your system as an example). If you want to use a more convenient mod‐
15015 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15016 of the Findosg*.cmake modules.
15017 Locate osgINTROSPECTION This module defines
15019 OSGINTROSPECTION_FOUND - Was osgIntrospection found? OSGINTROSPEC‐
15021 TION_INCLUDE_DIR - Where to find the headers OSGINTROSPECTION_LIBRARIES
15022 - The libraries to link for osgIntrospection (use this)
15023 OSGINTROSPECTION_LIBRARY - The osgIntrospection library OSGINTROSPEC‐
15025 TION_LIBRARY_DEBUG - The osgIntrospection debug library
15026 $OSGDIR is an environment variable that would correspond to the ./con‐
15028 figure --prefix=$OSGDIR used in building osg.
15029 Created by Eric Wing.
15031 FindosgManipulator
15033 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15034 nents. Each component is separate and you must opt in to each module.
15035 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15036 as these modules won't do it for you. This is to allow you control
15037 over your own system piece by piece in case you need to opt out of cer‐
15038 tain components or change the Find behavior for a particular module
15039 (perhaps because the default FindOpenGL.cmake module doesn't work with
15040 your system as an example). If you want to use a more convenient mod‐
15041 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15042 of the Findosg*.cmake modules.
15043 Locate osgManipulator This module defines
15045 OSGMANIPULATOR_FOUND - Was osgManipulator found? OSGMANIPULATOR_IN‐
15047 CLUDE_DIR - Where to find the headers OSGMANIPULATOR_LIBRARIES - The
15048 libraries to link for osgManipulator (use this)
15049 OSGMANIPULATOR_LIBRARY - The osgManipulator library OSGMANIPULATOR_LI‐
15051 BRARY_DEBUG - The osgManipulator debug library
15052 $OSGDIR is an environment variable that would correspond to the ./con‐
15054 figure --prefix=$OSGDIR used in building osg.
15055 Created by Eric Wing.
15057 FindosgParticle
15059 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15060 nents. Each component is separate and you must opt in to each module.
15061 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15062 as these modules won't do it for you. This is to allow you control
15063 over your own system piece by piece in case you need to opt out of cer‐
15064 tain components or change the Find behavior for a particular module
15065 (perhaps because the default FindOpenGL.cmake module doesn't work with
15066 your system as an example). If you want to use a more convenient mod‐
15067 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15068 of the Findosg*.cmake modules.
15069 Locate osgParticle This module defines
15071 OSGPARTICLE_FOUND - Was osgParticle found? OSGPARTICLE_INCLUDE_DIR -
15073 Where to find the headers OSGPARTICLE_LIBRARIES - The libraries to link
15074 for osgParticle (use this)
15075 OSGPARTICLE_LIBRARY - The osgParticle library OSGPARTICLE_LIBRARY_DEBUG
15077 - The osgParticle debug library
15078 $OSGDIR is an environment variable that would correspond to the ./con‐
15080 figure --prefix=$OSGDIR used in building osg.
15081 Created by Eric Wing.
15083 FindosgPresentation
15085 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15086 nents. Each component is separate and you must opt in to each module.
15087 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15088 as these modules won't do it for you. This is to allow you control
15089 over your own system piece by piece in case you need to opt out of cer‐
15090 tain components or change the Find behavior for a particular module
15091 (perhaps because the default FindOpenGL.cmake module doesn't work with
15092 your system as an example). If you want to use a more convenient mod‐
15093 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15094 of the Findosg*.cmake modules.
15095 Locate osgPresentation This module defines
15097 OSGPRESENTATION_FOUND - Was osgPresentation found? OSGPRESENTATION_IN‐
15099 CLUDE_DIR - Where to find the headers OSGPRESENTATION_LIBRARIES - The
15100 libraries to link for osgPresentation (use this)
15101 OSGPRESENTATION_LIBRARY - The osgPresentation library OSGPRESENTA‐
15103 TION_LIBRARY_DEBUG - The osgPresentation debug library
15104 $OSGDIR is an environment variable that would correspond to the ./con‐
15106 figure --prefix=$OSGDIR used in building osg.
15107 Created by Eric Wing. Modified to work with osgPresentation by Robert
15109 Osfield, January 2012.
15110 FindosgProducer
15112 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15113 nents. Each component is separate and you must opt in to each module.
15114 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15115 as these modules won't do it for you. This is to allow you control
15116 over your own system piece by piece in case you need to opt out of cer‐
15117 tain components or change the Find behavior for a particular module
15118 (perhaps because the default FindOpenGL.cmake module doesn't work with
15119 your system as an example). If you want to use a more convenient mod‐
15120 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15121 of the Findosg*.cmake modules.
15122 Locate osgProducer This module defines
15124 OSGPRODUCER_FOUND - Was osgProducer found? OSGPRODUCER_INCLUDE_DIR -
15126 Where to find the headers OSGPRODUCER_LIBRARIES - The libraries to link
15127 for osgProducer (use this)
15128 OSGPRODUCER_LIBRARY - The osgProducer library OSGPRODUCER_LIBRARY_DEBUG
15130 - The osgProducer debug library
15131 $OSGDIR is an environment variable that would correspond to the ./con‐
15133 figure --prefix=$OSGDIR used in building osg.
15134 Created by Eric Wing.
15136 FindosgQt
15138 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15139 nents. Each component is separate and you must opt in to each module.
15140 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15141 as these modules won't do it for you. This is to allow you control
15142 over your own system piece by piece in case you need to opt out of cer‐
15143 tain components or change the Find behavior for a particular module
15144 (perhaps because the default FindOpenGL.cmake module doesn't work with
15145 your system as an example). If you want to use a more convenient mod‐
15146 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15147 of the Findosg*.cmake modules.
15148 Locate osgQt This module defines
15150 OSGQT_FOUND - Was osgQt found? OSGQT_INCLUDE_DIR - Where to find the
15152 headers OSGQT_LIBRARIES - The libraries to link for osgQt (use this)
15153 OSGQT_LIBRARY - The osgQt library OSGQT_LIBRARY_DEBUG - The osgQt debug
15155 library
15156 $OSGDIR is an environment variable that would correspond to the ./con‐
15158 figure --prefix=$OSGDIR used in building osg.
15159 Created by Eric Wing. Modified to work with osgQt by Robert Osfield,
15161 January 2012.
15162 FindosgShadow
15164 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15165 nents. Each component is separate and you must opt in to each module.
15166 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15167 as these modules won't do it for you. This is to allow you control
15168 over your own system piece by piece in case you need to opt out of cer‐
15169 tain components or change the Find behavior for a particular module
15170 (perhaps because the default FindOpenGL.cmake module doesn't work with
15171 your system as an example). If you want to use a more convenient mod‐
15172 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15173 of the Findosg*.cmake modules.
15174 Locate osgShadow This module defines
15176 OSGSHADOW_FOUND - Was osgShadow found? OSGSHADOW_INCLUDE_DIR - Where to
15178 find the headers OSGSHADOW_LIBRARIES - The libraries to link for os‐
15179 gShadow (use this)
15180 OSGSHADOW_LIBRARY - The osgShadow library OSGSHADOW_LIBRARY_DEBUG - The
15182 osgShadow debug library
15183 $OSGDIR is an environment variable that would correspond to the ./con‐
15185 figure --prefix=$OSGDIR used in building osg.
15186 Created by Eric Wing.
15188 FindosgSim
15190 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15191 nents. Each component is separate and you must opt in to each module.
15192 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15193 as these modules won't do it for you. This is to allow you control
15194 over your own system piece by piece in case you need to opt out of cer‐
15195 tain components or change the Find behavior for a particular module
15196 (perhaps because the default FindOpenGL.cmake module doesn't work with
15197 your system as an example). If you want to use a more convenient mod‐
15198 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15199 of the Findosg*.cmake modules.
15200 Locate osgSim This module defines
15202 OSGSIM_FOUND - Was osgSim found? OSGSIM_INCLUDE_DIR - Where to find the
15204 headers OSGSIM_LIBRARIES - The libraries to link for osgSim (use this)
15205 OSGSIM_LIBRARY - The osgSim library OSGSIM_LIBRARY_DEBUG - The osgSim
15207 debug library
15208 $OSGDIR is an environment variable that would correspond to the ./con‐
15210 figure --prefix=$OSGDIR used in building osg.
15211 Created by Eric Wing.
15213 FindosgTerrain
15215 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15216 nents. Each component is separate and you must opt in to each module.
15217 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15218 as these modules won't do it for you. This is to allow you control
15219 over your own system piece by piece in case you need to opt out of cer‐
15220 tain components or change the Find behavior for a particular module
15221 (perhaps because the default FindOpenGL.cmake module doesn't work with
15222 your system as an example). If you want to use a more convenient mod‐
15223 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15224 of the Findosg*.cmake modules.
15225 Locate osgTerrain This module defines
15227 OSGTERRAIN_FOUND - Was osgTerrain found? OSGTERRAIN_INCLUDE_DIR - Where
15229 to find the headers OSGTERRAIN_LIBRARIES - The libraries to link for
15230 osgTerrain (use this)
15231 OSGTERRAIN_LIBRARY - The osgTerrain library OSGTERRAIN_LIBRARY_DEBUG -
15233 The osgTerrain debug library
15234 $OSGDIR is an environment variable that would correspond to the ./con‐
15236 figure --prefix=$OSGDIR used in building osg.
15237 Created by Eric Wing.
15239 FindosgText
15241 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15242 nents. Each component is separate and you must opt in to each module.
15243 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15244 as these modules won't do it for you. This is to allow you control
15245 over your own system piece by piece in case you need to opt out of cer‐
15246 tain components or change the Find behavior for a particular module
15247 (perhaps because the default FindOpenGL.cmake module doesn't work with
15248 your system as an example). If you want to use a more convenient mod‐
15249 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15250 of the Findosg*.cmake modules.
15251 Locate osgText This module defines
15253 OSGTEXT_FOUND - Was osgText found? OSGTEXT_INCLUDE_DIR - Where to find
15255 the headers OSGTEXT_LIBRARIES - The libraries to link for osgText (use
15256 this)
15257 OSGTEXT_LIBRARY - The osgText library OSGTEXT_LIBRARY_DEBUG - The osg‐
15259 Text debug library
15260 $OSGDIR is an environment variable that would correspond to the ./con‐
15262 figure --prefix=$OSGDIR used in building osg.
15263 Created by Eric Wing.
15265 FindosgUtil
15267 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15268 nents. Each component is separate and you must opt in to each module.
15269 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15270 as these modules won't do it for you. This is to allow you control
15271 over your own system piece by piece in case you need to opt out of cer‐
15272 tain components or change the Find behavior for a particular module
15273 (perhaps because the default FindOpenGL.cmake module doesn't work with
15274 your system as an example). If you want to use a more convenient mod‐
15275 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15276 of the Findosg*.cmake modules.
15277 Locate osgUtil This module defines
15279 OSGUTIL_FOUND - Was osgUtil found? OSGUTIL_INCLUDE_DIR - Where to find
15281 the headers OSGUTIL_LIBRARIES - The libraries to link for osgUtil (use
15282 this)
15283 OSGUTIL_LIBRARY - The osgUtil library OSGUTIL_LIBRARY_DEBUG - The
15285 osgUtil debug library
15286 $OSGDIR is an environment variable that would correspond to the ./con‐
15288 figure --prefix=$OSGDIR used in building osg.
15289 Created by Eric Wing.
15291 FindosgViewer
15293 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15294 nents. Each component is separate and you must opt in to each module.
15295 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15296 as these modules won't do it for you. This is to allow you control
15297 over your own system piece by piece in case you need to opt out of cer‐
15298 tain components or change the Find behavior for a particular module
15299 (perhaps because the default FindOpenGL.cmake module doesn't work with
15300 your system as an example). If you want to use a more convenient mod‐
15301 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15302 of the Findosg*.cmake modules.
15303 Locate osgViewer This module defines
15305 OSGVIEWER_FOUND - Was osgViewer found? OSGVIEWER_INCLUDE_DIR - Where to
15307 find the headers OSGVIEWER_LIBRARIES - The libraries to link for os‐
15308 gViewer (use this)
15309 OSGVIEWER_LIBRARY - The osgViewer library OSGVIEWER_LIBRARY_DEBUG - The
15311 osgViewer debug library
15312 $OSGDIR is an environment variable that would correspond to the ./con‐
15314 figure --prefix=$OSGDIR used in building osg.
15315 Created by Eric Wing.
15317 FindosgVolume
15319 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15320 nents. Each component is separate and you must opt in to each module.
15321 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15322 as these modules won't do it for you. This is to allow you control
15323 over your own system piece by piece in case you need to opt out of cer‐
15324 tain components or change the Find behavior for a particular module
15325 (perhaps because the default FindOpenGL.cmake module doesn't work with
15326 your system as an example). If you want to use a more convenient mod‐
15327 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15328 of the Findosg*.cmake modules.
15329 Locate osgVolume This module defines
15331 OSGVOLUME_FOUND - Was osgVolume found? OSGVOLUME_INCLUDE_DIR - Where to
15333 find the headers OSGVOLUME_LIBRARIES - The libraries to link for os‐
15334 gVolume (use this)
15335 OSGVOLUME_LIBRARY - The osgVolume library OSGVOLUME_LIBRARY_DEBUG - The
15337 osgVolume debug library
15338 $OSGDIR is an environment variable that would correspond to the ./con‐
15340 figure --prefix=$OSGDIR used in building osg.
15341 Created by Eric Wing.
15343 FindosgWidget
15345 This is part of the Findosg* suite used to find OpenSceneGraph compo‐
15346 nents. Each component is separate and you must opt in to each module.
15347 You must also opt into OpenGL and OpenThreads (and Producer if needed)
15348 as these modules won't do it for you. This is to allow you control
15349 over your own system piece by piece in case you need to opt out of cer‐
15350 tain components or change the Find behavior for a particular module
15351 (perhaps because the default FindOpenGL.cmake module doesn't work with
15352 your system as an example). If you want to use a more convenient mod‐
15353 ule that includes everything, use the FindOpenSceneGraph.cmake instead
15354 of the Findosg*.cmake modules.
15355 Locate osgWidget This module defines
15357 OSGWIDGET_FOUND - Was osgWidget found? OSGWIDGET_INCLUDE_DIR - Where to
15359 find the headers OSGWIDGET_LIBRARIES - The libraries to link for osg‐
15360 Widget (use this)
15361 OSGWIDGET_LIBRARY - The osgWidget library OSGWIDGET_LIBRARY_DEBUG - The
15363 osgWidget debug library
15364 $OSGDIR is an environment variable that would correspond to the ./con‐
15366 figure --prefix=$OSGDIR used in building osg.
15367 FindosgWidget.cmake tweaked from Findosg* suite as created by Eric
15369 Wing.
15370 FindPatch
15372 New in version 3.10.
15373 The module defines the following variables:
15376 Patch_EXECUTABLE
15378 Path to patch command-line executable.
15379 Patch_FOUND
15381 True if the patch command-line executable was found.
15382 The following IMPORTED targets are also defined:
15384 Patch::patch
15386 The command-line executable.
15387 Example usage:
15389 find_package(Patch)
15391 if(Patch_FOUND)
15392 message("Patch found: ${Patch_EXECUTABLE}")
15393 endif()
15394 FindPerl
15396 Find perl
15397 this module looks for Perl
15399 PERL_EXECUTABLE - the full path to perl
15401 PERL_FOUND - If false, don't attempt to use perl.
15402 PERL_VERSION_STRING - version of perl found (since CMake 2.8.8)
15403 FindPerlLibs
15405 Find Perl libraries
15406 This module finds if PERL is installed and determines where the include
15408 files and libraries are. It also determines what the name of the li‐
15409 brary is. This code sets the following variables:
15410 PERLLIBS_FOUND = True if perl.h & libperl were found
15412 PERL_INCLUDE_PATH = path to where perl.h is found
15413 PERL_LIBRARY = path to libperl
15414 PERL_EXECUTABLE = full path to the perl binary
15415 The minimum required version of Perl can be specified using the stan‐
15417 dard syntax, e.g. find_package(PerlLibs 6.0)
15418 The following variables are also available if needed
15420 (introduced after CMake 2.6.4)
15421 PERL_SITESEARCH = path to the sitesearch install dir (-V:installsitesearch)
15423 PERL_SITEARCH = path to the sitelib install directory (-V:installsitearch)
15424 PERL_SITELIB = path to the sitelib install directory (-V:installsitelib)
15425 PERL_VENDORARCH = path to the vendor arch install directory (-V:installvendorarch)
15426 PERL_VENDORLIB = path to the vendor lib install directory (-V:installvendorlib)
15427 PERL_ARCHLIB = path to the core arch lib install directory (-V:archlib)
15428 PERL_PRIVLIB = path to the core priv lib install directory (-V:privlib)
15429 PERL_UPDATE_ARCHLIB = path to the update arch lib install directory (-V:installarchlib)
15430 PERL_UPDATE_PRIVLIB = path to the update priv lib install directory (-V:installprivlib)
15431 PERL_EXTRA_C_FLAGS = Compilation flags used to build perl
15432 FindPHP4
15434 Find PHP4
15435 This module finds if PHP4 is installed and determines where the include
15437 files and libraries are. It also determines what the name of the li‐
15438 brary is. This code sets the following variables:
15439 PHP4_INCLUDE_PATH = path to where php.h can be found
15441 PHP4_EXECUTABLE = full path to the php4 binary
15442 FindPhysFS
15444 Locate PhysFS library This module defines PHYSFS_LIBRARY, the name of
15445 the library to link against PHYSFS_FOUND, if false, do not try to link
15446 to PHYSFS PHYSFS_INCLUDE_DIR, where to find physfs.h
15447 $PHYSFSDIR is an environment variable that would correspond to the
15449 ./configure --prefix=$PHYSFSDIR used in building PHYSFS.
15450 Created by Eric Wing.
15452 FindPike
15454 Find Pike
15455 This module finds if PIKE is installed and determines where the include
15457 files and libraries are. It also determines what the name of the li‐
15458 brary is. This code sets the following variables:
15459 PIKE_INCLUDE_PATH = path to where program.h is found
15461 PIKE_EXECUTABLE = full path to the pike binary
15462 FindPkgConfig
15464 A pkg-config module for CMake.
15465 Finds the pkg-config executable and adds the pkg_get_variable(),
15467 pkg_check_modules() and pkg_search_module() commands. The following
15468 variables will also be set:
15469 PKG_CONFIG_FOUND
15471 True if a pkg-config executable was found.
15472 PKG_CONFIG_VERSION_STRING
15474 New in version 2.8.8.
15475 The version of pkg-config that was found.
15478 PKG_CONFIG_EXECUTABLE
15480 The pathname of the pkg-config program.
15481 PKG_CONFIG_ARGN
15483 New in version 3.22.
15484 A list of arguments to pass to pkg-config.
15487 Both PKG_CONFIG_EXECUTABLE and PKG_CONFIG_ARGN are initialized by the
15489 module, but may be overridden by the user. See Variables Affecting Be‐
15490 havior for how these variables are initialized.
15491 pkg_check_modules
15493 Checks for all the given modules, setting a variety of result
15494 variables in the calling scope.
15495 pkg_check_modules(<prefix>
15497 [REQUIRED] [QUIET]
15498 [NO_CMAKE_PATH]
15499 [NO_CMAKE_ENVIRONMENT_PATH]
15500 [IMPORTED_TARGET [GLOBAL]]
15501 <moduleSpec> [<moduleSpec>...])
15502 When the REQUIRED argument is given, the command will fail with
15504 an error if module(s) could not be found.
15505 When the QUIET argument is given, no status messages will be
15507 printed.
15508 New in version 3.1: The CMAKE_PREFIX_PATH, CMAKE_FRAMEWORK_PATH,
15510 and CMAKE_APPBUNDLE_PATH cache and environment variables will be
15511 added to the pkg-config search path. The NO_CMAKE_PATH and
15512 NO_CMAKE_ENVIRONMENT_PATH arguments disable this behavior for
15513 the cache variables and environment variables respectively. The
15514 PKG_CONFIG_USE_CMAKE_PREFIX_PATH variable set to FALSE disables
15515 this behavior globally.
15516 New in version 3.6: The IMPORTED_TARGET argument will create an
15519 imported target named PkgConfig::<prefix> that can be passed di‐
15520 rectly as an argument to target_link_libraries().
15521 New in version 3.13: The GLOBAL argument will make the imported
15524 target available in global scope.
15525 New in version 3.15: Non-library linker options reported by
15528 pkg-config are stored in the INTERFACE_LINK_OPTIONS target prop‐
15529 erty.
15530 Changed in version 3.18: Include directories specified with
15533 -isystem are stored in the INTERFACE_INCLUDE_DIRECTORIES target
15534 property. Previous versions of CMake left them in the INTER‐
15535 FACE_COMPILE_OPTIONS property.
15536 Each <moduleSpec> can be either a bare module name or it can be
15539 a module name with a version constraint (operators =, <, >, <=
15540 and >= are supported). The following are examples for a module
15541 named foo with various constraints:
15542 • foo matches any version.
15544 • foo<2 only matches versions before 2.
15546 • foo>=3.1 matches any version from 3.1 or later.
15548 • foo=1.2.3 requires that foo must be exactly version 1.2.3.
15550 The following variables may be set upon return. Two sets of
15552 values exist: One for the common case (<XXX> = <prefix>) and an‐
15553 other for the information pkg-config provides when called with
15554 the --static option (<XXX> = <prefix>_STATIC).
15555 <XXX>_FOUND
15557 set to 1 if module(s) exist
15558 <XXX>_LIBRARIES
15560 only the libraries (without the '-l')
15561 <XXX>_LINK_LIBRARIES
15563 the libraries and their absolute paths
15564 <XXX>_LIBRARY_DIRS
15566 the paths of the libraries (without the '-L')
15567 <XXX>_LDFLAGS
15569 all required linker flags
15570 <XXX>_LDFLAGS_OTHER
15572 all other linker flags
15573 <XXX>_INCLUDE_DIRS
15575 the '-I' preprocessor flags (without the '-I')
15576 <XXX>_CFLAGS
15578 all required cflags
15579 <XXX>_CFLAGS_OTHER
15581 the other compiler flags
15582 All but <XXX>_FOUND may be a ;-list if the associated variable
15584 returned from pkg-config has multiple values.
15585 Changed in version 3.18: Include directories specified with
15587 -isystem are stored in the <XXX>_INCLUDE_DIRS variable. Previ‐
15588 ous versions of CMake left them in <XXX>_CFLAGS_OTHER.
15589 There are some special variables whose prefix depends on the
15592 number of <moduleSpec> given. When there is only one <module‐
15593 Spec>, <YYY> will simply be <prefix>, but if two or more <mod‐
15594 uleSpec> items are given, <YYY> will be <prefix>_<moduleName>.
15595 <YYY>_VERSION
15597 version of the module
15598 <YYY>_PREFIX
15600 prefix directory of the module
15601 <YYY>_INCLUDEDIR
15603 include directory of the module
15604 <YYY>_LIBDIR
15606 lib directory of the module
15607 Changed in version 3.8: For any given <prefix>, pkg_check_mod‐
15609 ules() can be called multiple times with different parameters.
15610 Previous versions of CMake cached and returned the first suc‐
15611 cessful result.
15612 Changed in version 3.16: If a full path to the found library
15615 can't be determined, but it's still visible to the linker, pass
15616 it through as -l<name>. Previous versions of CMake failed in
15617 this case.
15618 Examples:
15621 pkg_check_modules (GLIB2 glib-2.0)
15623 Looks for any version of glib2. If found, the output variable
15625 GLIB2_VERSION will hold the actual version found.
15626 pkg_check_modules (GLIB2 glib-2.0>=2.10)
15628 Looks for at least version 2.10 of glib2. If found, the output
15630 variable GLIB2_VERSION will hold the actual version found.
15631 pkg_check_modules (FOO glib-2.0>=2.10 gtk+-2.0)
15633 Looks for both glib2-2.0 (at least version 2.10) and any version
15635 of gtk2+-2.0. Only if both are found will FOO be considered
15636 found. The FOO_glib-2.0_VERSION and FOO_gtk+-2.0_VERSION vari‐
15637 ables will be set to their respective found module versions.
15638 pkg_check_modules (XRENDER REQUIRED xrender)
15640 Requires any version of xrender. Example output variables set
15642 by a successful call:
15643 XRENDER_LIBRARIES=Xrender;X11
15645 XRENDER_STATIC_LIBRARIES=Xrender;X11;pthread;Xau;Xdmcp
15646 pkg_search_module
15648 The behavior of this command is the same as pkg_check_modules(),
15649 except that rather than checking for all the specified modules,
15650 it searches for just the first successful match.
15651 pkg_search_module(<prefix>
15653 [REQUIRED] [QUIET]
15654 [NO_CMAKE_PATH]
15655 [NO_CMAKE_ENVIRONMENT_PATH]
15656 [IMPORTED_TARGET [GLOBAL]]
15657 <moduleSpec> [<moduleSpec>...])
15658 New in version 3.16: If a module is found, the <prefix>_MOD‐
15660 ULE_NAME variable will contain the name of the matching module.
15661 This variable can be used if you need to run pkg_get_variable().
15662 Example:
15665 pkg_search_module (BAR libxml-2.0 libxml2 libxml>=2)
15667 pkg_get_variable
15669 New in version 3.4.
15670 Retrieves the value of a pkg-config variable varName and stores
15673 it in the result variable resultVar in the calling scope.
15674 pkg_get_variable(<resultVar> <moduleName> <varName>)
15676 If pkg-config returns multiple values for the specified vari‐
15678 able, resultVar will contain a ;-list.
15679 For example:
15681 pkg_get_variable(GI_GIRDIR gobject-introspection-1.0 girdir)
15683 Variables Affecting Behavior
15685 PKG_CONFIG_EXECUTABLE
15686 This cache variable can be set to the path of the pkg-config ex‐
15687 ecutable. find_program() is called internally by the module
15688 with this variable.
15689 New in version 3.1: The PKG_CONFIG environment variable can be
15691 used as a hint if PKG_CONFIG_EXECUTABLE has not yet been set.
15692 Changed in version 3.22: If the PKG_CONFIG environment variable
15695 is set, only the first argument is taken from it when using it
15696 as a hint.
15697 PKG_CONFIG_ARGN
15700 New in version 3.22.
15701 This cache variable can be set to a list of arguments to addi‐
15704 tionally pass to pkg-config if needed. If not provided, it will
15705 be initialized from the PKG_CONFIG environment variable, if set.
15706 The first argument in that environment variable is assumed to be
15707 the pkg-config program, while all remaining arguments after that
15708 are used to initialize PKG_CONFIG_ARGN. If no such environment
15709 variable is defined, PKG_CONFIG_ARGN is initialized to an empty
15710 string. The module does not update the variable once it has been
15711 set in the cache.
15712 PKG_CONFIG_USE_CMAKE_PREFIX_PATH
15714 New in version 3.1.
15715 Specifies whether pkg_check_modules() and pkg_search_module()
15718 should add the paths in the CMAKE_PREFIX_PATH, CMAKE_FRAME‐
15719 WORK_PATH and CMAKE_APPBUNDLE_PATH cache and environment vari‐
15720 ables to the pkg-config search path.
15721 If this variable is not set, this behavior is enabled by default
15723 if CMAKE_MINIMUM_REQUIRED_VERSION is 3.1 or later, disabled oth‐
15724 erwise.
15725 FindPNG
15727 Find libpng, the official reference library for the PNG image format.
15728 Imported targets
15730 New in version 3.5.
15731 This module defines the following IMPORTED target:
15734 PNG::PNG
15736 The libpng library, if found.
15737 Result variables
15739 This module will set the following variables in your project:
15740 PNG_INCLUDE_DIRS
15742 where to find png.h, etc.
15743 PNG_LIBRARIES
15745 the libraries to link against to use PNG.
15746 PNG_DEFINITIONS
15748 You should add_definitions(${PNG_DEFINITIONS}) before compiling
15749 code that includes png library files.
15750 PNG_FOUND
15752 If false, do not try to use PNG.
15753 PNG_VERSION_STRING
15755 the version of the PNG library found (since CMake 2.8.8)
15756 Obsolete variables
15758 The following variables may also be set, for backwards compatibility:
15759 PNG_LIBRARY
15761 where to find the PNG library.
15762 PNG_INCLUDE_DIR
15764 where to find the PNG headers (same as PNG_INCLUDE_DIRS)
15765 Since PNG depends on the ZLib compression library, none of the above
15767 will be defined unless ZLib can be found.
15768 FindPostgreSQL
15770 Find the PostgreSQL installation.
15771 IMPORTED Targets
15773 New in version 3.14.
15774 This module defines IMPORTED target PostgreSQL::PostgreSQL if Post‐
15777 greSQL has been found.
15778 Result Variables
15780 This module will set the following variables in your project:
15781 PostgreSQL_FOUND
15783 True if PostgreSQL is found.
15784 PostgreSQL_LIBRARIES
15786 the PostgreSQL libraries needed for linking
15787 PostgreSQL_INCLUDE_DIRS
15789 the directories of the PostgreSQL headers
15790 PostgreSQL_LIBRARY_DIRS
15792 the link directories for PostgreSQL libraries
15793 PostgreSQL_VERSION_STRING
15795 the version of PostgreSQL found
15796 PostgreSQL_TYPE_INCLUDE_DIR
15798 the directories of the PostgreSQL server headers
15799 Components
15801 This module contains additional Server component, that forcibly checks
15802 for the presence of server headers. Note that PostgreSQL_TYPE_IN‐
15803 CLUDE_DIR is set regardless of the presence of the Server component in
15804 find_package call.
15805 FindProducer
15807 Though Producer isn't directly part of OpenSceneGraph, its primary user
15808 is OSG so I consider this part of the Findosg* suite used to find Open‐
15809 SceneGraph components. You'll notice that I accept OSGDIR as an envi‐
15810 ronment path.
15811 Each component is separate and you must opt in to each module. You
15813 must also opt into OpenGL (and OpenThreads?) as these modules won't do
15814 it for you. This is to allow you control over your own system piece by
15815 piece in case you need to opt out of certain components or change the
15816 Find behavior for a particular module (perhaps because the default
15817 FindOpenGL.cmake module doesn't work with your system as an example).
15818 If you want to use a more convenient module that includes everything,
15819 use the FindOpenSceneGraph.cmake instead of the Findosg*.cmake modules.
15820 Locate Producer This module defines PRODUCER_LIBRARY PRODUCER_FOUND, if
15822 false, do not try to link to Producer PRODUCER_INCLUDE_DIR, where to
15823 find the headers
15824 $PRODUCER_DIR is an environment variable that would correspond to the
15826 ./configure --prefix=$PRODUCER_DIR used in building osg.
15827 Created by Eric Wing.
15829 FindProtobuf
15831 Locate and configure the Google Protocol Buffers library.
15832 New in version 3.6: Support for find_package() version checks.
15834 Changed in version 3.6: All input and output variables use the Proto‐
15837 buf_ prefix. Variables with PROTOBUF_ prefix are still supported for
15838 compatibility.
15839 The following variables can be set and are optional:
15842 Protobuf_SRC_ROOT_FOLDER
15844 When compiling with MSVC, if this cache variable is set the pro‐
15845 tobuf-default VS project build locations (vsprojects/Debug and
15846 vsprojects/Release or vsprojects/x64/Debug and vspro‐
15847 jects/x64/Release) will be searched for libraries and binaries.
15848 Protobuf_IMPORT_DIRS
15850 List of additional directories to be searched for imported
15851 .proto files.
15852 Protobuf_DEBUG
15854 New in version 3.6.
15855 Show debug messages.
15858 Protobuf_USE_STATIC_LIBS
15860 New in version 3.9.
15861 Set to ON to force the use of the static libraries. Default is
15864 OFF.
15865 Defines the following variables:
15867 Protobuf_FOUND
15869 Found the Google Protocol Buffers library (libprotobuf & header
15870 files)
15871 Protobuf_VERSION
15873 New in version 3.6.
15874 Version of package found.
15877 Protobuf_INCLUDE_DIRS
15879 Include directories for Google Protocol Buffers
15880 Protobuf_LIBRARIES
15882 The protobuf libraries
15883 Protobuf_PROTOC_LIBRARIES
15885 The protoc libraries
15886 Protobuf_LITE_LIBRARIES
15888 The protobuf-lite libraries
15889 New in version 3.9: The following IMPORTED targets are also defined:
15891 protobuf::libprotobuf
15894 The protobuf library.
15895 protobuf::libprotobuf-lite
15897 The protobuf lite library.
15898 protobuf::libprotoc
15900 The protoc library.
15901 protobuf::protoc
15903 New in version 3.10: The protoc compiler.
15904 The following cache variables are also available to set or use:
15907 Protobuf_LIBRARY
15909 The protobuf library
15910 Protobuf_PROTOC_LIBRARY
15912 The protoc library
15913 Protobuf_INCLUDE_DIR
15915 The include directory for protocol buffers
15916 Protobuf_PROTOC_EXECUTABLE
15918 The protoc compiler
15919 Protobuf_LIBRARY_DEBUG
15921 The protobuf library (debug)
15922 Protobuf_PROTOC_LIBRARY_DEBUG
15924 The protoc library (debug)
15925 Protobuf_LITE_LIBRARY
15927 The protobuf lite library
15928 Protobuf_LITE_LIBRARY_DEBUG
15930 The protobuf lite library (debug)
15931 Example:
15933 find_package(Protobuf REQUIRED)
15935 include_directories(${Protobuf_INCLUDE_DIRS})
15936 include_directories(${CMAKE_CURRENT_BINARY_DIR})
15937 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS foo.proto)
15938 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS EXPORT_MACRO DLL_EXPORT foo.proto)
15939 protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS DESCRIPTORS PROTO_DESCS foo.proto)
15940 protobuf_generate_python(PROTO_PY foo.proto)
15941 add_executable(bar bar.cc ${PROTO_SRCS} ${PROTO_HDRS})
15942 target_link_libraries(bar ${Protobuf_LIBRARIES})
15943 NOTE:
15945 The protobuf_generate_cpp and protobuf_generate_python functions and
15946 add_executable() or add_library() calls only work properly within
15947 the same directory.
15948 protobuf_generate_cpp
15950 Add custom commands to process .proto files to C++:
15951 protobuf_generate_cpp (<SRCS> <HDRS>
15953 [DESCRIPTORS <DESC>] [EXPORT_MACRO <MACRO>] [<ARGN>...])
15954 SRCS Variable to define with autogenerated source files
15956 HDRS Variable to define with autogenerated header files
15958 DESCRIPTORS
15960 New in version 3.10: Variable to define with autogener‐
15961 ated descriptor files, if requested.
15962 EXPORT_MACRO
15965 is a macro which should expand to __declspec(dllexport)
15966 or __declspec(dllimport) depending on what is being com‐
15967 piled.
15968 ARGN .proto files
15970 protobuf_generate_python
15972 New in version 3.4.
15973 Add custom commands to process .proto files to Python:
15976 protobuf_generate_python (<PY> [<ARGN>...])
15978 PY Variable to define with autogenerated Python files
15980 ARGN .proto files
15982 FindPython
15984 New in version 3.12.
15985 Find Python interpreter, compiler and development environment (include
15988 directories and libraries).
15989 New in version 3.19: When a version is requested, it can be specified
15991 as a simple value or as a range. For a detailed description of version
15992 range usage and capabilities, refer to the find_package() command.
15993 The following components are supported:
15996 • Interpreter: search for Python interpreter.
15998 • Compiler: search for Python compiler. Only offered by IronPython.
16000 • Development: search for development artifacts (include directories
16002 and libraries).
16003 New in version 3.18: This component includes two sub-components which
16005 can be specified independently:
16006 • Development.Module: search for artifacts for Python module develop‐
16008 ments.
16009 • Development.Embed: search for artifacts for Python embedding devel‐
16011 opments.
16012 • NumPy: search for NumPy include directories.
16015 New in version 3.14: Added the NumPy component.
16017 If no COMPONENTS are specified, Interpreter is assumed.
16020 If component Development is specified, it implies sub-components Devel‐
16022 opment.Module and Development.Embed.
16023 To ensure consistent versions between components Interpreter, Compiler,
16025 Development (or one of its sub-components) and NumPy, specify all com‐
16026 ponents at the same time:
16027 find_package (Python COMPONENTS Interpreter Development)
16029 This module looks preferably for version 3 of Python. If not found,
16031 version 2 is searched. To manage concurrent versions 3 and 2 of
16032 Python, use FindPython3 and FindPython2 modules rather than this one.
16033 NOTE:
16035 If components Interpreter and Development (or one of its sub-compo‐
16036 nents) are both specified, this module search only for interpreter
16037 with same platform architecture as the one defined by CMake configu‐
16038 ration. This constraint does not apply if only Interpreter component
16039 is specified.
16040 Imported Targets
16042 This module defines the following Imported Targets:
16043 Changed in version 3.14: Imported Targets are only created when
16045 CMAKE_ROLE is PROJECT.
16046 Python::Interpreter
16049 Python interpreter. Target defined if component Interpreter is
16050 found.
16051 Python::Compiler
16053 Python compiler. Target defined if component Compiler is found.
16054 Python::Module
16056 New in version 3.15.
16057 Python library for Python module. Target defined if component
16060 Development.Module is found.
16061 Python::Python
16063 Python library for Python embedding. Target defined if component
16064 Development.Embed is found.
16065 Python::NumPy
16067 New in version 3.14.
16068 NumPy Python library. Target defined if component NumPy is
16071 found.
16072 Result Variables
16074 This module will set the following variables in your project (see Stan‐
16075 dard Variable Names):
16076 Python_FOUND
16078 System has the Python requested components.
16079 Python_Interpreter_FOUND
16081 System has the Python interpreter.
16082 Python_EXECUTABLE
16084 Path to the Python interpreter.
16085 Python_INTERPRETER_ID
16087 A short string unique to the interpreter. Possible values in‐
16089 clude:
16090 • Python
16092 • ActivePython
16094 • Anaconda
16096 • Canopy
16098 • IronPython
16100 • PyPy
16102 Python_STDLIB
16104 Standard platform independent installation directory.
16105 Information returned by distutils.syscon‐
16107 fig.get_python_lib(plat_specific=False,standard_lib=True) or
16108 else sysconfig.get_path('stdlib').
16109 Python_STDARCH
16111 Standard platform dependent installation directory.
16112 Information returned by distutils.syscon‐
16114 fig.get_python_lib(plat_specific=True,standard_lib=True) or else
16115 sysconfig.get_path('platstdlib').
16116 Python_SITELIB
16118 Third-party platform independent installation directory.
16119 Information returned by distutils.syscon‐
16121 fig.get_python_lib(plat_specific=False,standard_lib=False) or
16122 else sysconfig.get_path('purelib').
16123 Python_SITEARCH
16125 Third-party platform dependent installation directory.
16126 Information returned by distutils.syscon‐
16128 fig.get_python_lib(plat_specific=True,standard_lib=False) or
16129 else sysconfig.get_path('platlib').
16130 Python_SOABI
16132 New in version 3.17.
16133 Extension suffix for modules.
16136 Information returned by distutils.sysconfig.get_con‐
16138 fig_var('SOABI') or computed from distutils.sysconfig.get_con‐
16139 fig_var('EXT_SUFFIX') or python-config --extension-suffix. If
16140 package distutils.sysconfig is not available, sysconfig.get_con‐
16141 fig_var('SOABI') or sysconfig.get_config_var('EXT_SUFFIX') are
16142 used.
16143 Python_Compiler_FOUND
16145 System has the Python compiler.
16146 Python_COMPILER
16148 Path to the Python compiler. Only offered by IronPython.
16149 Python_COMPILER_ID
16151 A short string unique to the compiler. Possible values include:
16153 • IronPython
16155 Python_DOTNET_LAUNCHER
16157 New in version 3.18.
16158 The .Net interpreter. Only used by IronPython implementation.
16161 Python_Development_FOUND
16163 System has the Python development artifacts.
16164 Python_Development.Module_FOUND
16166 New in version 3.18.
16167 System has the Python development artifacts for Python module.
16170 Python_Development.Embed_FOUND
16172 New in version 3.18.
16173 System has the Python development artifacts for Python embed‐
16176 ding.
16177 Python_INCLUDE_DIRS
16179 The Python include directories.
16180 Python_LINK_OPTIONS
16182 New in version 3.19.
16183 The Python link options. Some configurations require specific
16186 link options for a correct build and execution.
16187 Python_LIBRARIES
16189 The Python libraries.
16190 Python_LIBRARY_DIRS
16192 The Python library directories.
16193 Python_RUNTIME_LIBRARY_DIRS
16195 The Python runtime library directories.
16196 Python_VERSION
16198 Python version.
16199 Python_VERSION_MAJOR
16201 Python major version.
16202 Python_VERSION_MINOR
16204 Python minor version.
16205 Python_VERSION_PATCH
16207 Python patch version.
16208 Python_PyPy_VERSION
16210 New in version 3.18.
16211 Python PyPy version.
16214 Python_NumPy_FOUND
16216 New in version 3.14.
16217 System has the NumPy.
16220 Python_NumPy_INCLUDE_DIRS
16222 New in version 3.14.
16223 The NumPy include directories.
16226 Python_NumPy_VERSION
16228 New in version 3.14.
16229 The NumPy version.
16232 Hints
16234 Python_ROOT_DIR
16235 Define the root directory of a Python installation.
16236 Python_USE_STATIC_LIBS
16238 • If not defined, search for shared libraries and static li‐
16240 braries in that order.
16241 • If set to TRUE, search only for static libraries.
16243 • If set to FALSE, search only for shared libraries.
16245 NOTE:
16247 This hint will be ignored on Windows because static libraries
16248 are not available on this platform.
16249 Python_FIND_ABI
16251 New in version 3.16.
16252 This variable defines which ABIs, as defined in PEP 3149, should
16255 be searched.
16256 NOTE:
16258 This hint will be honored only when searched for Python ver‐
16259 sion 3.
16260 NOTE:
16262 If Python_FIND_ABI is not defined, any ABI will be searched.
16263 The Python_FIND_ABI variable is a 3-tuple specifying, in that
16265 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
16266 element can be set to one of the following:
16267 • ON: Corresponding flag is selected.
16269 • OFF: Corresponding flag is not selected.
16271 • ANY: The two possibilities (ON and OFF) will be searched.
16273 From this 3-tuple, various ABIs will be searched starting from
16275 the most specialized to the most general. Moreover, debug ver‐
16276 sions will be searched after non-debug ones.
16277 For example, if we have:
16279 set (Python_FIND_ABI "ON" "ANY" "ANY")
16281 The following flags combinations will be appended, in that or‐
16283 der, to the artifact names: dmu, dm, du, and d.
16284 And to search any possible ABIs:
16286 set (Python_FIND_ABI "ANY" "ANY" "ANY")
16288 The following combinations, in that order, will be used: mu, m,
16290 u, <empty>, dmu, dm, du and d.
16291 NOTE:
16293 This hint is useful only on POSIX systems. So, on Windows
16294 systems, when Python_FIND_ABI is defined, Python distribu‐
16295 tions from python.org will be found only if value for each
16296 flag is OFF or ANY.
16297 Python_FIND_STRATEGY
16299 New in version 3.15.
16300 This variable defines how lookup will be done. The
16303 Python_FIND_STRATEGY variable can be set to one of the follow‐
16304 ing:
16305 • VERSION: Try to find the most recent version in all specified
16307 locations. This is the default if policy CMP0094 is undefined
16308 or set to OLD.
16309 • LOCATION: Stops lookup as soon as a version satisfying version
16311 constraints is founded. This is the default if policy CMP0094
16312 is set to NEW.
16313 Python_FIND_REGISTRY
16315 New in version 3.13.
16316 On Windows the Python_FIND_REGISTRY variable determine the order
16319 of preference between registry and environment variables. the
16320 Python_FIND_REGISTRY variable can be set to one of the follow‐
16321 ing:
16322 • FIRST: Try to use registry before environment variables. This
16324 is the default.
16325 • LAST: Try to use registry after environment variables.
16327 • NEVER: Never try to use registry.
16329 Python_FIND_FRAMEWORK
16331 New in version 3.15.
16332 On macOS the Python_FIND_FRAMEWORK variable determine the order
16335 of preference between Apple-style and unix-style package compo‐
16336 nents. This variable can take same values as CMAKE_FIND_FRAME‐
16337 WORK variable.
16338 NOTE:
16340 Value ONLY is not supported so FIRST will be used instead.
16341 If Python_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
16343 variable will be used, if any.
16344 Python_FIND_VIRTUALENV
16346 New in version 3.15.
16347 This variable defines the handling of virtual environments man‐
16350 aged by virtualenv or conda. It is meaningful only when a vir‐
16351 tual environment is active (i.e. the activate script has been
16352 evaluated). In this case, it takes precedence over
16353 Python_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
16354 Python_FIND_VIRTUALENV variable can be set to one of the follow‐
16355 ing:
16356 • FIRST: The virtual environment is used before any other stan‐
16358 dard paths to look-up for the interpreter. This is the de‐
16359 fault.
16360 • ONLY: Only the virtual environment is used to look-up for the
16362 interpreter.
16363 • STANDARD: The virtual environment is not used to look-up for
16365 the interpreter but environment variable PATH is always con‐
16366 sidered. In this case, variable Python_FIND_REGISTRY (Win‐
16367 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
16368 LAST or NEVER to select preferably the interpreter from the
16369 virtual environment.
16370 New in version 3.17: Added support for conda environments.
16372 NOTE:
16375 If the component Development is requested, it is strongly
16376 recommended to also include the component Interpreter to get
16377 expected result.
16378 Python_FIND_IMPLEMENTATIONS
16380 New in version 3.18.
16381 This variable defines, in an ordered list, the different imple‐
16384 mentations which will be searched. The Python_FIND_IMPLEMENTA‐
16385 TIONS variable can hold the following values:
16386 • CPython: this is the standard implementation. Various prod‐
16388 ucts, like Anaconda or ActivePython, rely on this implementa‐
16389 tion.
16390 • IronPython: This implementation use the CSharp language for
16392 .NET Framework on top of the Dynamic Language Runtime (DLR).
16393 See IronPython.
16394 • PyPy: This implementation use RPython language and RPython
16396 translation toolchain to produce the python interpreter. See
16397 PyPy.
16398 The default value is:
16400 • Windows platform: CPython, IronPython
16402 • Other platforms: CPython
16404 NOTE:
16406 This hint has the lowest priority of all hints, so even if,
16407 for example, you specify IronPython first and CPython in sec‐
16408 ond, a python product based on CPython can be selected be‐
16409 cause, for example with Python_FIND_STRATEGY=LOCATION, each
16410 location will be search first for IronPython and second for
16411 CPython.
16412 NOTE:
16414 When IronPython is specified, on platforms other than Win‐
16415 dows, the .Net interpreter (i.e. mono command) is expected to
16416 be available through the PATH variable.
16417 Python_FIND_UNVERSIONED_NAMES
16419 New in version 3.20.
16420 This variable defines how the generic names will be searched.
16423 Currently, it only applies to the generic names of the inter‐
16424 preter, namely, python3 or python2 and python. The
16425 Python_FIND_UNVERSIONED_NAMES variable can be set to one of the
16426 following values:
16427 • FIRST: The generic names are searched before the more special‐
16429 ized ones (such as python2.5 for example).
16430 • LAST: The generic names are searched after the more special‐
16432 ized ones. This is the default.
16433 • NEVER: The generic name are not searched at all.
16435 Artifacts Specification
16437 New in version 3.16.
16438 To solve special cases, it is possible to specify directly the arti‐
16441 facts by setting the following variables:
16442 Python_EXECUTABLE
16444 The path to the interpreter.
16445 Python_COMPILER
16447 The path to the compiler.
16448 Python_DOTNET_LAUNCHER
16450 New in version 3.18.
16451 The .Net interpreter. Only used by IronPython implementation.
16454 Python_LIBRARY
16456 The path to the library. It will be used to compute the vari‐
16457 ables Python_LIBRARIES, Python_LIBRARY_DIRS and Python_RUN‐
16458 TIME_LIBRARY_DIRS.
16459 Python_INCLUDE_DIR
16461 The path to the directory of the Python headers. It will be used
16462 to compute the variable Python_INCLUDE_DIRS.
16463 Python_NumPy_INCLUDE_DIR
16465 The path to the directory of the NumPy headers. It will be used
16466 to compute the variable Python_NumPy_INCLUDE_DIRS.
16467 NOTE:
16469 All paths must be absolute. Any artifact specified with a relative
16470 path will be ignored.
16471 NOTE:
16473 When an artifact is specified, all HINTS will be ignored and no
16474 search will be performed for this artifact.
16475 If more than one artifact is specified, it is the user's responsi‐
16477 bility to ensure the consistency of the various artifacts.
16478 By default, this module supports multiple calls in different directo‐
16480 ries of a project with different version/component requirements while
16481 providing correct and consistent results for each call. To support this
16482 behavior, CMake cache is not used in the traditional way which can be
16483 problematic for interactive specification. So, to enable also interac‐
16484 tive specification, module behavior can be controlled with the follow‐
16485 ing variable:
16486 Python_ARTIFACTS_INTERACTIVE
16488 New in version 3.18.
16489 Selects the behavior of the module. This is a boolean variable:
16492 • If set to TRUE: Create CMake cache entries for the above arti‐
16494 fact specification variables so that users can edit them in‐
16495 teractively. This disables support for multiple version/com‐
16496 ponent requirements.
16497 • If set to FALSE or undefined: Enable multiple version/compo‐
16499 nent requirements.
16500 Commands
16502 This module defines the command Python_add_library (when CMAKE_ROLE is
16503 PROJECT), which has the same semantics as add_library() and adds a de‐
16504 pendency to target Python::Python or, when library type is MODULE, to
16505 target Python::Module and takes care of Python module naming rules:
16506 Python_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
16508 <source1> [<source2> ...])
16509 If the library type is not specified, MODULE is assumed.
16511 New in version 3.17: For MODULE library type, if option WITH_SOABI is
16513 specified, the module suffix will include the Python_SOABI value, if
16514 any.
16515 FindPython2
16518 New in version 3.12.
16519 Find Python 2 interpreter, compiler and development environment (in‐
16522 clude directories and libraries).
16523 New in version 3.19: When a version is requested, it can be specified
16525 as a simple value or as a range. For a detailed description of version
16526 range usage and capabilities, refer to the find_package() command.
16527 The following components are supported:
16530 • Interpreter: search for Python 2 interpreter
16532 • Compiler: search for Python 2 compiler. Only offered by IronPython.
16534 • Development: search for development artifacts (include directories
16536 and libraries).
16537 New in version 3.18: This component includes two sub-components which
16539 can be specified independently:
16540 • Development.Module: search for artifacts for Python 2 module devel‐
16542 opments.
16543 • Development.Embed: search for artifacts for Python 2 embedding de‐
16545 velopments.
16546 • NumPy: search for NumPy include directories.
16549 New in version 3.14: Added the NumPy component.
16551 If no COMPONENTS are specified, Interpreter is assumed.
16554 If component Development is specified, it implies sub-components Devel‐
16556 opment.Module and Development.Embed.
16557 To ensure consistent versions between components Interpreter, Compiler,
16559 Development (or one of its sub-components) and NumPy, specify all com‐
16560 ponents at the same time:
16561 find_package (Python2 COMPONENTS Interpreter Development)
16563 This module looks only for version 2 of Python. This module can be used
16565 concurrently with FindPython3 module to use both Python versions.
16566 The FindPython module can be used if Python version does not matter for
16568 you.
16569 NOTE:
16571 If components Interpreter and Development (or one of its sub-compo‐
16572 nents) are both specified, this module search only for interpreter
16573 with same platform architecture as the one defined by CMake configu‐
16574 ration. This constraint does not apply if only Interpreter component
16575 is specified.
16576 Imported Targets
16578 This module defines the following Imported Targets:
16579 Changed in version 3.14: Imported Targets are only created when
16581 CMAKE_ROLE is PROJECT.
16582 Python2::Interpreter
16585 Python 2 interpreter. Target defined if component Interpreter is
16586 found.
16587 Python2::Compiler
16589 Python 2 compiler. Target defined if component Compiler is
16590 found.
16591 Python2::Module
16593 New in version 3.15.
16594 Python 2 library for Python module. Target defined if component
16597 Development.Module is found.
16598 Python2::Python
16600 Python 2 library for Python embedding. Target defined if compo‐
16601 nent Development.Embed is found.
16602 Python2::NumPy
16604 New in version 3.14.
16605 NumPy library for Python 2. Target defined if component NumPy is
16608 found.
16609 Result Variables
16611 This module will set the following variables in your project (see Stan‐
16612 dard Variable Names):
16613 Python2_FOUND
16615 System has the Python 2 requested components.
16616 Python2_Interpreter_FOUND
16618 System has the Python 2 interpreter.
16619 Python2_EXECUTABLE
16621 Path to the Python 2 interpreter.
16622 Python2_INTERPRETER_ID
16624 A short string unique to the interpreter. Possible values in‐
16626 clude:
16627 • Python
16629 • ActivePython
16631 • Anaconda
16633 • Canopy
16635 • IronPython
16637 • PyPy
16639 Python2_STDLIB
16641 Standard platform independent installation directory.
16642 Information returned by distutils.syscon‐
16644 fig.get_python_lib(plat_specific=False,standard_lib=True) or
16645 else sysconfig.get_path('stdlib').
16646 Python2_STDARCH
16648 Standard platform dependent installation directory.
16649 Information returned by distutils.syscon‐
16651 fig.get_python_lib(plat_specific=True,standard_lib=True) or else
16652 sysconfig.get_path('platstdlib').
16653 Python2_SITELIB
16655 Third-party platform independent installation directory.
16656 Information returned by distutils.syscon‐
16658 fig.get_python_lib(plat_specific=False,standard_lib=False) or
16659 else sysconfig.get_path('purelib').
16660 Python2_SITEARCH
16662 Third-party platform dependent installation directory.
16663 Information returned by distutils.syscon‐
16665 fig.get_python_lib(plat_specific=True,standard_lib=False) or
16666 else sysconfig.get_path('platlib').
16667 Python2_Compiler_FOUND
16669 System has the Python 2 compiler.
16670 Python2_COMPILER
16672 Path to the Python 2 compiler. Only offered by IronPython.
16673 Python2_COMPILER_ID
16675 A short string unique to the compiler. Possible values include:
16677 • IronPython
16679 Python2_DOTNET_LAUNCHER
16681 New in version 3.18.
16682 The .Net interpreter. Only used by IronPython implementation.
16685 Python2_Development_FOUND
16687 System has the Python 2 development artifacts.
16688 Python2_Development.Module_FOUND
16690 New in version 3.18.
16691 System has the Python 2 development artifacts for Python module.
16694 Python2_Development.Embed_FOUND
16696 New in version 3.18.
16697 System has the Python 2 development artifacts for Python embed‐
16700 ding.
16701 Python2_INCLUDE_DIRS
16703 The Python 2 include directories.
16704 Python2_LINK_OPTIONS
16706 New in version 3.19.
16707 The Python 2 link options. Some configurations require specific
16710 link options for a correct build and execution.
16711 Python2_LIBRARIES
16713 The Python 2 libraries.
16714 Python2_LIBRARY_DIRS
16716 The Python 2 library directories.
16717 Python2_RUNTIME_LIBRARY_DIRS
16719 The Python 2 runtime library directories.
16720 Python2_VERSION
16722 Python 2 version.
16723 Python2_VERSION_MAJOR
16725 Python 2 major version.
16726 Python2_VERSION_MINOR
16728 Python 2 minor version.
16729 Python2_VERSION_PATCH
16731 Python 2 patch version.
16732 Python2_PyPy_VERSION
16734 New in version 3.18.
16735 Python 2 PyPy version.
16738 Python2_NumPy_FOUND
16740 New in version 3.14.
16741 System has the NumPy.
16744 Python2_NumPy_INCLUDE_DIRS
16746 New in version 3.14.
16747 The NumPy include directories.
16750 Python2_NumPy_VERSION
16752 New in version 3.14.
16753 The NumPy version.
16756 Hints
16758 Python2_ROOT_DIR
16759 Define the root directory of a Python 2 installation.
16760 Python2_USE_STATIC_LIBS
16762 • If not defined, search for shared libraries and static li‐
16764 braries in that order.
16765 • If set to TRUE, search only for static libraries.
16767 • If set to FALSE, search only for shared libraries.
16769 NOTE:
16771 This hint will be ignored on Windows because static libraries
16772 are not available on this platform.
16773 Python2_FIND_STRATEGY
16775 New in version 3.15.
16776 This variable defines how lookup will be done. The
16779 Python2_FIND_STRATEGY variable can be set to one of the follow‐
16780 ing:
16781 • VERSION: Try to find the most recent version in all specified
16783 locations. This is the default if policy CMP0094 is undefined
16784 or set to OLD.
16785 • LOCATION: Stops lookup as soon as a version satisfying version
16787 constraints is founded. This is the default if policy CMP0094
16788 is set to NEW.
16789 Python2_FIND_REGISTRY
16791 New in version 3.13.
16792 On Windows the Python2_FIND_REGISTRY variable determine the or‐
16795 der of preference between registry and environment variables.
16796 the Python2_FIND_REGISTRY variable can be set to one of the fol‐
16797 lowing:
16798 • FIRST: Try to use registry before environment variables. This
16800 is the default.
16801 • LAST: Try to use registry after environment variables.
16803 • NEVER: Never try to use registry.
16805 Python2_FIND_FRAMEWORK
16807 New in version 3.15.
16808 On macOS the Python2_FIND_FRAMEWORK variable determine the order
16811 of preference between Apple-style and unix-style package compo‐
16812 nents. This variable can take same values as CMAKE_FIND_FRAME‐
16813 WORK variable.
16814 NOTE:
16816 Value ONLY is not supported so FIRST will be used instead.
16817 If Python2_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
16819 variable will be used, if any.
16820 Python2_FIND_VIRTUALENV
16822 New in version 3.15.
16823 This variable defines the handling of virtual environments man‐
16826 aged by virtualenv or conda. It is meaningful only when a vir‐
16827 tual environment is active (i.e. the activate script has been
16828 evaluated). In this case, it takes precedence over
16829 Python2_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
16830 Python2_FIND_VIRTUALENV variable can be set to one of the fol‐
16831 lowing:
16832 • FIRST: The virtual environment is used before any other stan‐
16834 dard paths to look-up for the interpreter. This is the de‐
16835 fault.
16836 • ONLY: Only the virtual environment is used to look-up for the
16838 interpreter.
16839 • STANDARD: The virtual environment is not used to look-up for
16841 the interpreter but environment variable PATH is always con‐
16842 sidered. In this case, variable Python2_FIND_REGISTRY (Win‐
16843 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
16844 LAST or NEVER to select preferably the interpreter from the
16845 virtual environment.
16846 New in version 3.17: Added support for conda environments.
16848 NOTE:
16851 If the component Development is requested, it is strongly
16852 recommended to also include the component Interpreter to get
16853 expected result.
16854 Python2_FIND_IMPLEMENTATIONS
16856 New in version 3.18.
16857 This variable defines, in an ordered list, the different imple‐
16860 mentations which will be searched. The Python2_FIND_IMPLEMENTA‐
16861 TIONS variable can hold the following values:
16862 • CPython: this is the standard implementation. Various prod‐
16864 ucts, like Anaconda or ActivePython, rely on this implementa‐
16865 tion.
16866 • IronPython: This implementation use the CSharp language for
16868 .NET Framework on top of the Dynamic Language Runtime (DLR).
16869 See IronPython.
16870 • PyPy: This implementation use RPython language and RPython
16872 translation toolchain to produce the python interpreter. See
16873 PyPy.
16874 The default value is:
16876 • Windows platform: CPython, IronPython
16878 • Other platforms: CPython
16880 NOTE:
16882 This hint has the lowest priority of all hints, so even if,
16883 for example, you specify IronPython first and CPython in sec‐
16884 ond, a python product based on CPython can be selected be‐
16885 cause, for example with Python2_FIND_STRATEGY=LOCATION, each
16886 location will be search first for IronPython and second for
16887 CPython.
16888 NOTE:
16890 When IronPython is specified, on platforms other than Win‐
16891 dows, the .Net interpreter (i.e. mono command) is expected to
16892 be available through the PATH variable.
16893 Python2_FIND_UNVERSIONED_NAMES
16895 New in version 3.20.
16896 This variable defines how the generic names will be searched.
16899 Currently, it only applies to the generic names of the inter‐
16900 preter, namely, python2 and python. The Python2_FIND_UNVER‐
16901 SIONED_NAMES variable can be set to one of the following values:
16902 • FIRST: The generic names are searched before the more special‐
16904 ized ones (such as python2.5 for example).
16905 • LAST: The generic names are searched after the more special‐
16907 ized ones. This is the default.
16908 • NEVER: The generic name are not searched at all.
16910 Artifacts Specification
16912 New in version 3.16.
16913 To solve special cases, it is possible to specify directly the arti‐
16916 facts by setting the following variables:
16917 Python2_EXECUTABLE
16919 The path to the interpreter.
16920 Python2_COMPILER
16922 The path to the compiler.
16923 Python2_DOTNET_LAUNCHER
16925 New in version 3.18.
16926 The .Net interpreter. Only used by IronPython implementation.
16929 Python2_LIBRARY
16931 The path to the library. It will be used to compute the vari‐
16932 ables Python2_LIBRARIES, Python2_LIBRARY_DIRS and Python2_RUN‐
16933 TIME_LIBRARY_DIRS.
16934 Python2_INCLUDE_DIR
16936 The path to the directory of the Python headers. It will be used
16937 to compute the variable Python2_INCLUDE_DIRS.
16938 Python2_NumPy_INCLUDE_DIR
16940 The path to the directory of the NumPy headers. It will be used
16941 to compute the variable Python2_NumPy_INCLUDE_DIRS.
16942 NOTE:
16944 All paths must be absolute. Any artifact specified with a relative
16945 path will be ignored.
16946 NOTE:
16948 When an artifact is specified, all HINTS will be ignored and no
16949 search will be performed for this artifact.
16950 If more than one artifact is specified, it is the user's responsi‐
16952 bility to ensure the consistency of the various artifacts.
16953 By default, this module supports multiple calls in different directo‐
16955 ries of a project with different version/component requirements while
16956 providing correct and consistent results for each call. To support this
16957 behavior, CMake cache is not used in the traditional way which can be
16958 problematic for interactive specification. So, to enable also interac‐
16959 tive specification, module behavior can be controlled with the follow‐
16960 ing variable:
16961 Python2_ARTIFACTS_INTERACTIVE
16963 New in version 3.18.
16964 Selects the behavior of the module. This is a boolean variable:
16967 • If set to TRUE: Create CMake cache entries for the above arti‐
16969 fact specification variables so that users can edit them in‐
16970 teractively. This disables support for multiple version/com‐
16971 ponent requirements.
16972 • If set to FALSE or undefined: Enable multiple version/compo‐
16974 nent requirements.
16975 Commands
16977 This module defines the command Python2_add_library (when CMAKE_ROLE is
16978 PROJECT), which has the same semantics as add_library() and adds a de‐
16979 pendency to target Python2::Python or, when library type is MODULE, to
16980 target Python2::Module and takes care of Python module naming rules:
16981 Python2_add_library (<name> [STATIC | SHARED | MODULE]
16983 <source1> [<source2> ...])
16984 If library type is not specified, MODULE is assumed.
16986 FindPython3
16988 New in version 3.12.
16989 Find Python 3 interpreter, compiler and development environment (in‐
16992 clude directories and libraries).
16993 New in version 3.19: When a version is requested, it can be specified
16995 as a simple value or as a range. For a detailed description of version
16996 range usage and capabilities, refer to the find_package() command.
16997 The following components are supported:
17000 • Interpreter: search for Python 3 interpreter
17002 • Compiler: search for Python 3 compiler. Only offered by IronPython.
17004 • Development: search for development artifacts (include directories
17006 and libraries).
17007 New in version 3.18: This component includes two sub-components which
17009 can be specified independently:
17010 • Development.Module: search for artifacts for Python 3 module devel‐
17012 opments.
17013 • Development.Embed: search for artifacts for Python 3 embedding de‐
17015 velopments.
17016 • NumPy: search for NumPy include directories.
17019 New in version 3.14: Added the NumPy component.
17021 If no COMPONENTS are specified, Interpreter is assumed.
17024 If component Development is specified, it implies sub-components Devel‐
17026 opment.Module and Development.Embed.
17027 To ensure consistent versions between components Interpreter, Compiler,
17029 Development (or one of its sub-components) and NumPy, specify all com‐
17030 ponents at the same time:
17031 find_package (Python3 COMPONENTS Interpreter Development)
17033 This module looks only for version 3 of Python. This module can be used
17035 concurrently with FindPython2 module to use both Python versions.
17036 The FindPython module can be used if Python version does not matter for
17038 you.
17039 NOTE:
17041 If components Interpreter and Development (or one of its sub-compo‐
17042 nents) are both specified, this module search only for interpreter
17043 with same platform architecture as the one defined by CMake configu‐
17044 ration. This constraint does not apply if only Interpreter component
17045 is specified.
17046 Imported Targets
17048 This module defines the following Imported Targets:
17049 Changed in version 3.14: Imported Targets are only created when
17051 CMAKE_ROLE is PROJECT.
17052 Python3::Interpreter
17055 Python 3 interpreter. Target defined if component Interpreter is
17056 found.
17057 Python3::Compiler
17059 Python 3 compiler. Target defined if component Compiler is
17060 found.
17061 Python3::Module
17063 New in version 3.15.
17064 Python 3 library for Python module. Target defined if component
17067 Development.Module is found.
17068 Python3::Python
17070 Python 3 library for Python embedding. Target defined if compo‐
17071 nent Development.Embed is found.
17072 Python3::NumPy
17074 New in version 3.14.
17075 NumPy library for Python 3. Target defined if component NumPy is
17078 found.
17079 Result Variables
17081 This module will set the following variables in your project (see Stan‐
17082 dard Variable Names):
17083 Python3_FOUND
17085 System has the Python 3 requested components.
17086 Python3_Interpreter_FOUND
17088 System has the Python 3 interpreter.
17089 Python3_EXECUTABLE
17091 Path to the Python 3 interpreter.
17092 Python3_INTERPRETER_ID
17094 A short string unique to the interpreter. Possible values in‐
17096 clude:
17097 • Python
17099 • ActivePython
17101 • Anaconda
17103 • Canopy
17105 • IronPython
17107 • PyPy
17109 Python3_STDLIB
17111 Standard platform independent installation directory.
17112 Information returned by distutils.syscon‐
17114 fig.get_python_lib(plat_specific=False,standard_lib=True) or
17115 else sysconfig.get_path('stdlib').
17116 Python3_STDARCH
17118 Standard platform dependent installation directory.
17119 Information returned by distutils.syscon‐
17121 fig.get_python_lib(plat_specific=True,standard_lib=True) or else
17122 sysconfig.get_path('platstdlib').
17123 Python3_SITELIB
17125 Third-party platform independent installation directory.
17126 Information returned by distutils.syscon‐
17128 fig.get_python_lib(plat_specific=False,standard_lib=False) or
17129 else sysconfig.get_path('purelib').
17130 Python3_SITEARCH
17132 Third-party platform dependent installation directory.
17133 Information returned by distutils.syscon‐
17135 fig.get_python_lib(plat_specific=True,standard_lib=False) or
17136 else sysconfig.get_path('platlib').
17137 Python3_SOABI
17139 New in version 3.17.
17140 Extension suffix for modules.
17143 Information returned by distutils.sysconfig.get_con‐
17145 fig_var('SOABI') or computed from distutils.sysconfig.get_con‐
17146 fig_var('EXT_SUFFIX') or python3-config --extension-suffix. If
17147 package distutils.sysconfig is not available, sysconfig.get_con‐
17148 fig_var('SOABI') or sysconfig.get_config_var('EXT_SUFFIX') are
17149 used.
17150 Python3_Compiler_FOUND
17152 System has the Python 3 compiler.
17153 Python3_COMPILER
17155 Path to the Python 3 compiler. Only offered by IronPython.
17156 Python3_COMPILER_ID
17158 A short string unique to the compiler. Possible values include:
17160 • IronPython
17162 Python3_DOTNET_LAUNCHER
17164 New in version 3.18.
17165 The .Net interpreter. Only used by IronPython implementation.
17168 Python3_Development_FOUND
17170 System has the Python 3 development artifacts.
17171 Python3_Development.Module_FOUND
17173 New in version 3.18.
17174 System has the Python 3 development artifacts for Python module.
17177 Python3_Development.Embed_FOUND
17179 New in version 3.18.
17180 System has the Python 3 development artifacts for Python embed‐
17183 ding.
17184 Python3_INCLUDE_DIRS
17186 The Python 3 include directories.
17187 Python3_LINK_OPTIONS
17189 New in version 3.19.
17190 The Python 3 link options. Some configurations require specific
17193 link options for a correct build and execution.
17194 Python3_LIBRARIES
17196 The Python 3 libraries.
17197 Python3_LIBRARY_DIRS
17199 The Python 3 library directories.
17200 Python3_RUNTIME_LIBRARY_DIRS
17202 The Python 3 runtime library directories.
17203 Python3_VERSION
17205 Python 3 version.
17206 Python3_VERSION_MAJOR
17208 Python 3 major version.
17209 Python3_VERSION_MINOR
17211 Python 3 minor version.
17212 Python3_VERSION_PATCH
17214 Python 3 patch version.
17215 Python3_PyPy_VERSION
17217 New in version 3.18.
17218 Python 3 PyPy version.
17221 Python3_NumPy_FOUND
17223 New in version 3.14.
17224 System has the NumPy.
17227 Python3_NumPy_INCLUDE_DIRS
17229 New in version 3.14.
17230 The NumPy include directories.
17233 Python3_NumPy_VERSION
17235 New in version 3.14.
17236 The NumPy version.
17239 Hints
17241 Python3_ROOT_DIR
17242 Define the root directory of a Python 3 installation.
17243 Python3_USE_STATIC_LIBS
17245 • If not defined, search for shared libraries and static li‐
17247 braries in that order.
17248 • If set to TRUE, search only for static libraries.
17250 • If set to FALSE, search only for shared libraries.
17252 NOTE:
17254 This hint will be ignored on Windows because static libraries
17255 are not available on this platform.
17256 Python3_FIND_ABI
17258 New in version 3.16.
17259 This variable defines which ABIs, as defined in PEP 3149, should
17262 be searched.
17263 NOTE:
17265 If Python3_FIND_ABI is not defined, any ABI will be searched.
17266 The Python3_FIND_ABI variable is a 3-tuple specifying, in that
17268 order, pydebug (d), pymalloc (m) and unicode (u) flags. Each
17269 element can be set to one of the following:
17270 • ON: Corresponding flag is selected.
17272 • OFF: Corresponding flag is not selected.
17274 • ANY: The two possibilities (ON and OFF) will be searched.
17276 From this 3-tuple, various ABIs will be searched starting from
17278 the most specialized to the most general. Moreover, debug ver‐
17279 sions will be searched after non-debug ones.
17280 For example, if we have:
17282 set (Python3_FIND_ABI "ON" "ANY" "ANY")
17284 The following flags combinations will be appended, in that or‐
17286 der, to the artifact names: dmu, dm, du, and d.
17287 And to search any possible ABIs:
17289 set (Python3_FIND_ABI "ANY" "ANY" "ANY")
17291 The following combinations, in that order, will be used: mu, m,
17293 u, <empty>, dmu, dm, du and d.
17294 NOTE:
17296 This hint is useful only on POSIX systems. So, on Windows
17297 systems, when Python3_FIND_ABI is defined, Python distribu‐
17298 tions from python.org will be found only if value for each
17299 flag is OFF or ANY.
17300 Python3_FIND_STRATEGY
17302 New in version 3.15.
17303 This variable defines how lookup will be done. The
17306 Python3_FIND_STRATEGY variable can be set to one of the follow‐
17307 ing:
17308 • VERSION: Try to find the most recent version in all specified
17310 locations. This is the default if policy CMP0094 is undefined
17311 or set to OLD.
17312 • LOCATION: Stops lookup as soon as a version satisfying version
17314 constraints is founded. This is the default if policy CMP0094
17315 is set to NEW.
17316 Python3_FIND_REGISTRY
17318 New in version 3.13.
17319 On Windows the Python3_FIND_REGISTRY variable determine the or‐
17322 der of preference between registry and environment variables.
17323 The Python3_FIND_REGISTRY variable can be set to one of the fol‐
17324 lowing:
17325 • FIRST: Try to use registry before environment variables. This
17327 is the default.
17328 • LAST: Try to use registry after environment variables.
17330 • NEVER: Never try to use registry.
17332 Python3_FIND_FRAMEWORK
17334 New in version 3.15.
17335 On macOS the Python3_FIND_FRAMEWORK variable determine the order
17338 of preference between Apple-style and unix-style package compo‐
17339 nents. This variable can take same values as CMAKE_FIND_FRAME‐
17340 WORK variable.
17341 NOTE:
17343 Value ONLY is not supported so FIRST will be used instead.
17344 If Python3_FIND_FRAMEWORK is not defined, CMAKE_FIND_FRAMEWORK
17346 variable will be used, if any.
17347 Python3_FIND_VIRTUALENV
17349 New in version 3.15.
17350 This variable defines the handling of virtual environments man‐
17353 aged by virtualenv or conda. It is meaningful only when a vir‐
17354 tual environment is active (i.e. the activate script has been
17355 evaluated). In this case, it takes precedence over
17356 Python3_FIND_REGISTRY and CMAKE_FIND_FRAMEWORK variables. The
17357 Python3_FIND_VIRTUALENV variable can be set to one of the fol‐
17358 lowing:
17359 • FIRST: The virtual environment is used before any other stan‐
17361 dard paths to look-up for the interpreter. This is the de‐
17362 fault.
17363 • ONLY: Only the virtual environment is used to look-up for the
17365 interpreter.
17366 • STANDARD: The virtual environment is not used to look-up for
17368 the interpreter but environment variable PATH is always con‐
17369 sidered. In this case, variable Python3_FIND_REGISTRY (Win‐
17370 dows) or CMAKE_FIND_FRAMEWORK (macOS) can be set with value
17371 LAST or NEVER to select preferably the interpreter from the
17372 virtual environment.
17373 New in version 3.17: Added support for conda environments.
17375 NOTE:
17378 If the component Development is requested, it is strongly
17379 recommended to also include the component Interpreter to get
17380 expected result.
17381 Python3_FIND_IMPLEMENTATIONS
17383 New in version 3.18.
17384 This variable defines, in an ordered list, the different imple‐
17387 mentations which will be searched. The Python3_FIND_IMPLEMENTA‐
17388 TIONS variable can hold the following values:
17389 • CPython: this is the standard implementation. Various prod‐
17391 ucts, like Anaconda or ActivePython, rely on this implementa‐
17392 tion.
17393 • IronPython: This implementation use the CSharp language for
17395 .NET Framework on top of the Dynamic Language Runtime (DLR).
17396 See IronPython.
17397 • PyPy: This implementation use RPython language and RPython
17399 translation toolchain to produce the python interpreter. See
17400 PyPy.
17401 The default value is:
17403 • Windows platform: CPython, IronPython
17405 • Other platforms: CPython
17407 NOTE:
17409 This hint has the lowest priority of all hints, so even if,
17410 for example, you specify IronPython first and CPython in sec‐
17411 ond, a python product based on CPython can be selected be‐
17412 cause, for example with Python3_FIND_STRATEGY=LOCATION, each
17413 location will be search first for IronPython and second for
17414 CPython.
17415 NOTE:
17417 When IronPython is specified, on platforms other than Win‐
17418 dows, the .Net interpreter (i.e. mono command) is expected to
17419 be available through the PATH variable.
17420 Python3_FIND_UNVERSIONED_NAMES
17422 New in version 3.20.
17423 This variable defines how the generic names will be searched.
17426 Currently, it only applies to the generic names of the inter‐
17427 preter, namely, python3 and python. The Python3_FIND_UNVER‐
17428 SIONED_NAMES variable can be set to one of the following values:
17429 • FIRST: The generic names are searched before the more special‐
17431 ized ones (such as python3.5 for example).
17432 • LAST: The generic names are searched after the more special‐
17434 ized ones. This is the default.
17435 • NEVER: The generic name are not searched at all.
17437 Artifacts Specification
17439 New in version 3.16.
17440 To solve special cases, it is possible to specify directly the arti‐
17443 facts by setting the following variables:
17444 Python3_EXECUTABLE
17446 The path to the interpreter.
17447 Python3_COMPILER
17449 The path to the compiler.
17450 Python3_DOTNET_LAUNCHER
17452 New in version 3.18.
17453 The .Net interpreter. Only used by IronPython implementation.
17456 Python3_LIBRARY
17458 The path to the library. It will be used to compute the vari‐
17459 ables Python3_LIBRARIES, Python3_LIBRARY_DIRS and Python3_RUN‐
17460 TIME_LIBRARY_DIRS.
17461 Python3_INCLUDE_DIR
17463 The path to the directory of the Python headers. It will be used
17464 to compute the variable Python3_INCLUDE_DIRS.
17465 Python3_NumPy_INCLUDE_DIR
17467 The path to the directory of the NumPy headers. It will be used
17468 to compute the variable Python3_NumPy_INCLUDE_DIRS.
17469 NOTE:
17471 All paths must be absolute. Any artifact specified with a relative
17472 path will be ignored.
17473 NOTE:
17475 When an artifact is specified, all HINTS will be ignored and no
17476 search will be performed for this artifact.
17477 If more than one artifact is specified, it is the user's responsi‐
17479 bility to ensure the consistency of the various artifacts.
17480 By default, this module supports multiple calls in different directo‐
17482 ries of a project with different version/component requirements while
17483 providing correct and consistent results for each call. To support this
17484 behavior, CMake cache is not used in the traditional way which can be
17485 problematic for interactive specification. So, to enable also interac‐
17486 tive specification, module behavior can be controlled with the follow‐
17487 ing variable:
17488 Python3_ARTIFACTS_INTERACTIVE
17490 New in version 3.18.
17491 Selects the behavior of the module. This is a boolean variable:
17494 • If set to TRUE: Create CMake cache entries for the above arti‐
17496 fact specification variables so that users can edit them in‐
17497 teractively. This disables support for multiple version/com‐
17498 ponent requirements.
17499 • If set to FALSE or undefined: Enable multiple version/compo‐
17501 nent requirements.
17502 Commands
17504 This module defines the command Python3_add_library (when CMAKE_ROLE is
17505 PROJECT), which has the same semantics as add_library() and adds a de‐
17506 pendency to target Python3::Python or, when library type is MODULE, to
17507 target Python3::Module and takes care of Python module naming rules:
17508 Python3_add_library (<name> [STATIC | SHARED | MODULE [WITH_SOABI]]
17510 <source1> [<source2> ...])
17511 If the library type is not specified, MODULE is assumed.
17513 New in version 3.17: For MODULE library type, if option WITH_SOABI is
17515 specified, the module suffix will include the Python3_SOABI value, if
17516 any.
17517 FindQt3
17520 Locate Qt include paths and libraries
17521 This module defines:
17523 QT_INCLUDE_DIR - where to find qt.h, etc.
17525 QT_LIBRARIES - the libraries to link against to use Qt.
17526 QT_DEFINITIONS - definitions to use when
17527 compiling code that uses Qt.
17528 QT_FOUND - If false, don't try to use Qt.
17529 QT_VERSION_STRING - the version of Qt found
17530 If you need the multithreaded version of Qt, set QT_MT_REQUIRED to TRUE
17532 Also defined, but not for general use are:
17534 QT_MOC_EXECUTABLE, where to find the moc tool.
17536 QT_UIC_EXECUTABLE, where to find the uic tool.
17537 QT_QT_LIBRARY, where to find the Qt library.
17538 QT_QTMAIN_LIBRARY, where to find the qtmain
17539 library. This is only required by Qt3 on Windows.
17540 FindQt4
17542 Finding and Using Qt4
17543 This module can be used to find Qt4. The most important issue is that
17544 the Qt4 qmake is available via the system path. This qmake is then
17545 used to detect basically everything else. This module defines a number
17546 of IMPORTED targets, macros and variables.
17547 Typical usage could be something like:
17549 set(CMAKE_AUTOMOC ON)
17551 set(CMAKE_INCLUDE_CURRENT_DIR ON)
17552 find_package(Qt4 4.4.3 REQUIRED QtGui QtXml)
17553 add_executable(myexe main.cpp)
17554 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
17555 NOTE:
17557 When using IMPORTED targets, the qtmain.lib static library is auto‐
17558 matically linked on Windows for WIN32 executables. To disable that
17559 globally, set the QT4_NO_LINK_QTMAIN variable before finding Qt4. To
17560 disable that for a particular executable, set the QT4_NO_LINK_QTMAIN
17561 target property to TRUE on the executable.
17562 Qt Build Tools
17564 Qt relies on some bundled tools for code generation, such as moc for
17565 meta-object code generation,``uic`` for widget layout and population,
17566 and rcc for virtual filesystem content generation. These tools may be
17567 automatically invoked by cmake(1) if the appropriate conditions are
17568 met. See cmake-qt(7) for more.
17569 Qt Macros
17571 In some cases it can be necessary or useful to invoke the Qt build
17572 tools in a more-manual way. Several macros are available to add targets
17573 for such uses.
17574 macro QT4_WRAP_CPP(outfiles inputfile ... [TARGET tgt] OPTIONS ...)
17576 create moc code from a list of files containing Qt class with
17577 the Q_OBJECT declaration. Per-directory preprocessor definitions
17578 are also added. If the <tgt> is specified, the
17579 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
17580 the <tgt> are passed to moc. Options may be given to moc, such as
17581 those found when executing "moc -help".
17582 macro QT4_WRAP_UI(outfiles inputfile ... OPTIONS ...)
17584 create code from a list of Qt designer ui files.
17585 Options may be given to uic, such as those found
17586 when executing "uic -help"
17587 macro QT4_ADD_RESOURCES(outfiles inputfile ... OPTIONS ...)
17589 create code from a list of Qt resource files.
17590 Options may be given to rcc, such as those found
17591 when executing "rcc -help"
17592 macro QT4_GENERATE_MOC(inputfile outputfile [TARGET tgt])
17594 creates a rule to run moc on infile and create outfile.
17595 Use this if for some reason QT4_WRAP_CPP() isn't appropriate, e.g.
17596 because you need a custom filename for the moc file or something
17597 similar. If the <tgt> is specified, the
17598 INTERFACE_INCLUDE_DIRECTORIES and INTERFACE_COMPILE_DEFINITIONS from
17599 the <tgt> are passed to moc.
17600 macro QT4_ADD_DBUS_INTERFACE(outfiles interface basename)
17602 Create the interface header and implementation files with the
17603 given basename from the given interface xml file and add it to
17604 the list of sources.
17605 You can pass additional parameters to the qdbusxml2cpp call by setting
17607 properties on the input file:
17608 INCLUDE the given file will be included in the generate interface header
17610 CLASSNAME the generated class is named accordingly
17612 NO_NAMESPACE the generated class is not wrapped in a namespace
17614 macro QT4_ADD_DBUS_INTERFACES(outfiles inputfile ... )
17616 Create the interface header and implementation files
17617 for all listed interface xml files.
17618 The basename will be automatically determined from the name
17619 of the xml file.
17620 The source file properties described for
17622 QT4_ADD_DBUS_INTERFACE also apply here.
17623 macro QT4_ADD_DBUS_ADAPTOR(outfiles xmlfile parentheader parentclassname
17625 [basename] [classname])
17626 create a dbus adaptor (header and implementation file) from the xml file
17627 describing the interface, and add it to the list of sources. The adaptor
17628 forwards the calls to a parent class, defined in parentheader and named
17629 parentclassname. The name of the generated files will be
17630 <basename>adaptor.{cpp,h} where basename defaults to the basename of the
17631 xml file.
17632 If <classname> is provided, then it will be used as the classname of the
17633 adaptor itself.
17634 macro QT4_GENERATE_DBUS_INTERFACE( header [interfacename] OPTIONS ...)
17636 generate the xml interface file from the given header.
17637 If the optional argument interfacename is omitted, the name of the
17638 interface file is constructed from the basename of the header with
17639 the suffix .xml appended.
17640 Options may be given to qdbuscpp2xml, such as those found when
17641 executing "qdbuscpp2xml --help"
17642 macro QT4_CREATE_TRANSLATION( qm_files directories ... sources ...
17644 ts_files ... OPTIONS ...)
17645 out: qm_files
17646 in: directories sources ts_files
17647 options: flags to pass to lupdate, such as -extensions to specify
17648 extensions for a directory scan.
17649 generates commands to create .ts (via lupdate) and .qm
17650 (via lrelease) - files from directories and/or sources. The ts files are
17651 created and/or updated in the source tree (unless given with full paths).
17652 The qm files are generated in the build tree.
17653 Updating the translations can be done by adding the qm_files
17654 to the source list of your library/executable, so they are
17655 always updated, or by adding a custom target to control when
17656 they get updated/generated.
17657 macro QT4_ADD_TRANSLATION( qm_files ts_files ... )
17659 out: qm_files
17660 in: ts_files
17661 generates commands to create .qm from .ts - files. The generated
17662 filenames can be found in qm_files. The ts_files
17663 must exist and are not updated in any way.
17664 macro QT4_AUTOMOC(sourcefile1 sourcefile2 ... [TARGET tgt])
17666 The qt4_automoc macro is obsolete. Use the CMAKE_AUTOMOC feature instead.
17667 This macro is still experimental.
17668 It can be used to have moc automatically handled.
17669 So if you have the files foo.h and foo.cpp, and in foo.h a
17670 a class uses the Q_OBJECT macro, moc has to run on it. If you don't
17671 want to use QT4_WRAP_CPP() (which is reliable and mature), you can insert
17672 #include "foo.moc"
17673 in foo.cpp and then give foo.cpp as argument to QT4_AUTOMOC(). This will
17674 scan all listed files at cmake-time for such included moc files and if it
17675 finds them cause a rule to be generated to run moc at build time on the
17676 accompanying header file foo.h.
17677 If a source file has the SKIP_AUTOMOC property set it will be ignored by
17678 this macro.
17679 If the <tgt> is specified, the INTERFACE_INCLUDE_DIRECTORIES and
17680 INTERFACE_COMPILE_DEFINITIONS from the <tgt> are passed to moc.
17681 function QT4_USE_MODULES( target [link_type] modules...)
17683 This function is obsolete. Use target_link_libraries with IMPORTED targets
17684 instead.
17685 Make <target> use the <modules> from Qt. Using a Qt module means
17686 to link to the library, add the relevant include directories for the
17687 module, and add the relevant compiler defines for using the module.
17688 Modules are roughly equivalent to components of Qt4, so usage would be
17689 something like:
17690 qt4_use_modules(myexe Core Gui Declarative)
17691 to use QtCore, QtGui and QtDeclarative. The optional <link_type> argument
17692 can be specified as either LINK_PUBLIC or LINK_PRIVATE to specify the
17693 same argument to the target_link_libraries call.
17694 IMPORTED Targets
17696 A particular Qt library may be used by using the corresponding IMPORTED
17697 target with the target_link_libraries() command:
17698 target_link_libraries(myexe Qt4::QtGui Qt4::QtXml)
17700 Using a target in this way causes :cmake(1)` to use the appropriate in‐
17702 clude directories and compile definitions for the target when compiling
17703 myexe.
17704 Targets are aware of their dependencies, so for example it is not nec‐
17706 essary to list Qt4::QtCore if another Qt library is listed, and it is
17707 not necessary to list Qt4::QtGui if Qt4::QtDeclarative is listed. Tar‐
17708 gets may be tested for existence in the usual way with the if(TARGET)
17709 command.
17710 The Qt toolkit may contain both debug and release libraries. cmake(1)
17712 will choose the appropriate version based on the build configuration.
17713 Qt4::QtCore
17715 The QtCore target
17716 Qt4::QtGui
17718 The QtGui target
17719 Qt4::Qt3Support
17721 The Qt3Support target
17722 Qt4::QtAssistant
17724 The QtAssistant target
17725 Qt4::QtAssistantClient
17727 The QtAssistantClient target
17728 Qt4::QAxContainer
17730 The QAxContainer target (Windows only)
17731 Qt4::QAxServer
17733 The QAxServer target (Windows only)
17734 Qt4::QtDBus
17736 The QtDBus target
17737 Qt4::QtDeclarative
17739 The QtDeclarative target
17740 Qt4::QtDesigner
17742 The QtDesigner target
17743 Qt4::QtDesignerComponents
17745 The QtDesignerComponents target
17746 Qt4::QtHelp
17748 The QtHelp target
17749 Qt4::QtMotif
17751 The QtMotif target
17752 Qt4::QtMultimedia
17754 The QtMultimedia target
17755 Qt4::QtNetwork
17757 The QtNetwork target
17758 Qt4::QtNsPLugin
17760 The QtNsPLugin target
17761 Qt4::QtOpenGL
17763 The QtOpenGL target
17764 Qt4::QtScript
17766 The QtScript target
17767 Qt4::QtScriptTools
17769 The QtScriptTools target
17770 Qt4::QtSql
17772 The QtSql target
17773 Qt4::QtSvg
17775 The QtSvg target
17776 Qt4::QtTest
17778 The QtTest target
17779 Qt4::QtUiTools
17781 The QtUiTools target
17782 Qt4::QtWebKit
17784 The QtWebKit target
17785 Qt4::QtXml
17787 The QtXml target
17788 Qt4::QtXmlPatterns
17790 The QtXmlPatterns target
17791 Qt4::phonon
17793 The phonon target
17794 Result Variables
17796 Below is a detailed list of variables that FindQt4.cmake sets.
17797 Qt4_FOUND
17799 If false, don't try to use Qt 4.
17800 QT_FOUND
17802 If false, don't try to use Qt. This variable is for compatibil‐
17803 ity only.
17804 QT4_FOUND
17806 If false, don't try to use Qt 4. This variable is for compati‐
17807 bility only.
17808 QT_VERSION_MAJOR
17810 The major version of Qt found.
17811 QT_VERSION_MINOR
17813 The minor version of Qt found.
17814 QT_VERSION_PATCH
17816 The patch version of Qt found.
17817 FindQuickTime
17819 Locate QuickTime This module defines QUICKTIME_LIBRARY QUICKTIME_FOUND,
17820 if false, do not try to link to gdal QUICKTIME_INCLUDE_DIR, where to
17821 find the headers
17822 $QUICKTIME_DIR is an environment variable that would correspond to the
17824 ./configure --prefix=$QUICKTIME_DIR
17825 Created by Eric Wing.
17827 FindRTI
17829 Try to find M&S HLA RTI libraries
17830 This module finds if any HLA RTI is installed and locates the standard
17832 RTI include files and libraries.
17833 RTI is a simulation infrastructure standardized by IEEE and SISO. It
17835 has a well defined C++ API that assures that simulation applications
17836 are independent on a particular RTI implementation.
17837 http://en.wikipedia.org/wiki/Run-Time_Infrastructure_(simulation)
17839 This code sets the following variables:
17841 RTI_INCLUDE_DIR = the directory where RTI includes file are found
17843 RTI_LIBRARIES = The libraries to link against to use RTI
17844 RTI_DEFINITIONS = -DRTI_USES_STD_FSTREAM
17845 RTI_FOUND = Set to FALSE if any HLA RTI was not found
17846 Report problems to <certi-devel@nongnu.org>
17848 FindRuby
17850 Find Ruby
17851 This module finds if Ruby is installed and determines where the include
17853 files and libraries are. Ruby 1.8 through 2.7 are supported.
17854 The minimum required version of Ruby can be specified using the stan‐
17856 dard syntax, e.g.
17857 find_package(Ruby 2.5.1 EXACT REQUIRED)
17859 # OR
17860 find_package(Ruby 2.4)
17861 It also determines what the name of the library is.
17863 Virtual environments such as RVM are handled as well, by passing the
17865 argument Ruby_FIND_VIRTUALENV
17866 Result Variables
17868 This module will set the following variables in your project:
17869 Ruby_FOUND
17871 set to true if ruby was found successfully
17872 Ruby_EXECUTABLE
17874 full path to the ruby binary
17875 Ruby_INCLUDE_DIRS
17877 include dirs to be used when using the ruby library
17878 Ruby_LIBRARIES
17880 New in version 3.18: libraries needed to use ruby from C.
17881 Ruby_VERSION
17884 the version of ruby which was found, e.g. "1.8.7"
17885 Ruby_VERSION_MAJOR
17887 Ruby major version.
17888 Ruby_VERSION_MINOR
17890 Ruby minor version.
17891 Ruby_VERSION_PATCH
17893 Ruby patch version.
17894 Changed in version 3.18: Previous versions of CMake used the RUBY_ pre‐
17896 fix for all variables. The following variables are provided for com‐
17897 patibility reasons, don't use them in new code:
17898 RUBY_EXECUTABLE
17901 same as Ruby_EXECUTABLE.
17902 RUBY_INCLUDE_DIRS
17904 same as Ruby_INCLUDE_DIRS.
17905 RUBY_INCLUDE_PATH
17907 same as Ruby_INCLUDE_DIRS.
17908 RUBY_LIBRARY
17910 same as Ruby_LIBRARY.
17911 RUBY_VERSION
17913 same as Ruby_VERSION.
17914 RUBY_FOUND
17916 same as Ruby_FOUND.
17917 Hints
17919 New in version 3.18.
17920 Ruby_ROOT_DIR
17923 Define the root directory of a Ruby installation.
17924 Ruby_FIND_VIRTUALENV
17926 This variable defines the handling of virtual environments man‐
17927 aged by rvm. It is meaningful only when a virtual environment is
17928 active (i.e. the rvm script has been evaluated or at least the
17929 MY_RUBY_HOME environment variable is set). The Ruby_FIND_VIR‐
17930 TUALENV variable can be set to empty or one of the following:
17931 • FIRST: The virtual environment is used before any other stan‐
17933 dard paths to look-up for the interpreter. This is the de‐
17934 fault.
17935 • ONLY: Only the virtual environment is used to look-up for the
17937 interpreter.
17938 • STANDARD: The virtual environment is not used to look-up for
17940 the interpreter (assuming it isn't still in the PATH...)
17941 FindSDL
17943 Locate the SDL library
17944 Imported targets
17946 New in version 3.19.
17947 This module defines the following IMPORTED target:
17950 SDL::SDL
17952 The SDL library, if found
17953 Result variables
17955 This module will set the following variables in your project:
17956 SDL_INCLUDE_DIRS
17958 where to find SDL.h
17959 SDL_LIBRARIES
17961 the name of the library to link against
17962 SDL_FOUND
17964 if false, do not try to link to SDL
17965 SDL_VERSION
17967 the human-readable string containing the version of SDL if found
17968 SDL_VERSION_MAJOR
17970 SDL major version
17971 SDL_VERSION_MINOR
17973 SDL minor version
17974 SDL_VERSION_PATCH
17976 SDL patch version
17977 New in version 3.19: Added the SDL_INCLUDE_DIRS, SDL_LIBRARIES and
17979 SDL_VERSION[_<PART>] variables.
17980 Cache variables
17983 These variables may optionally be set to help this module find the cor‐
17984 rect files:
17985 SDL_INCLUDE_DIR
17987 where to find SDL.h
17988 SDL_LIBRARY
17990 the name of the library to link against
17991 Variables for locating SDL
17993 This module responds to the flag:
17994 SDL_BUILDING_LIBRARY
17996 If this is defined, then no SDL_main will be linked in because
17997 only applications need main(). Otherwise, it is assumed you are
17998 building an application and this module will attempt to locate
17999 and set the proper link flags as part of the returned SDL_LI‐
18000 BRARY variable.
18001 Obsolete variables
18003 Deprecated since version 3.19.
18004 These variables are obsolete and provided for backwards compatibility:
18007 SDL_VERSION_STRING
18009 the human-readable string containing the version of SDL if
18010 found. Identical to SDL_VERSION
18011 Don't forget to include SDLmain.h and SDLmain.m your project for the OS
18013 X framework based version. (Other versions link to -lSDLmain which
18014 this module will try to find on your behalf.) Also for OS X, this mod‐
18015 ule will automatically add the -framework Cocoa on your behalf.
18016 Additional Note: If you see an empty SDL_LIBRARY_TEMP in your configu‐
18018 ration and no SDL_LIBRARY, it means CMake did not find your SDL library
18019 (SDL.dll, libsdl.so, SDL.framework, etc). Set SDL_LIBRARY_TEMP to
18020 point to your SDL library, and configure again. Similarly, if you see
18021 an empty SDLMAIN_LIBRARY, you should set this value as appropriate.
18022 These values are used to generate the final SDL_LIBRARY variable, but
18023 when these values are unset, SDL_LIBRARY does not get created.
18024 $SDLDIR is an environment variable that would correspond to the ./con‐
18026 figure --prefix=$SDLDIR used in building SDL. l.e.galup 9-20-02
18027 On OSX, this will prefer the Framework version (if found) over others.
18029 People will have to manually change the cache values of SDL_LIBRARY to
18030 override this selection or set the CMake environment CMAKE_INCLUDE_PATH
18031 to modify the search paths.
18032 Note that the header path has changed from SDL/SDL.h to just SDL.h This
18034 needed to change because "proper" SDL convention is #include "SDL.h",
18035 not <SDL/SDL.h>. This is done for portability reasons because not all
18036 systems place things in SDL/ (see FreeBSD).
18037 FindSDL_image
18039 Locate SDL_image library
18040 This module defines:
18042 SDL_IMAGE_LIBRARIES, the name of the library to link against
18044 SDL_IMAGE_INCLUDE_DIRS, where to find the headers
18045 SDL_IMAGE_FOUND, if false, do not try to link against
18046 SDL_IMAGE_VERSION_STRING - human-readable string containing the
18047 version of SDL_image
18048 For backward compatibility the following variables are also set:
18050 SDLIMAGE_LIBRARY (same value as SDL_IMAGE_LIBRARIES)
18052 SDLIMAGE_INCLUDE_DIR (same value as SDL_IMAGE_INCLUDE_DIRS)
18053 SDLIMAGE_FOUND (same value as SDL_IMAGE_FOUND)
18054 $SDLDIR is an environment variable that would correspond to the ./con‐
18056 figure --prefix=$SDLDIR used in building SDL.
18057 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
18059 but with modifications to recognize OS X frameworks and additional Unix
18060 paths (FreeBSD, etc).
18061 FindSDL_mixer
18063 Locate SDL_mixer library
18064 This module defines:
18066 SDL_MIXER_LIBRARIES, the name of the library to link against
18068 SDL_MIXER_INCLUDE_DIRS, where to find the headers
18069 SDL_MIXER_FOUND, if false, do not try to link against
18070 SDL_MIXER_VERSION_STRING - human-readable string containing the
18071 version of SDL_mixer
18072 For backward compatibility the following variables are also set:
18074 SDLMIXER_LIBRARY (same value as SDL_MIXER_LIBRARIES)
18076 SDLMIXER_INCLUDE_DIR (same value as SDL_MIXER_INCLUDE_DIRS)
18077 SDLMIXER_FOUND (same value as SDL_MIXER_FOUND)
18078 $SDLDIR is an environment variable that would correspond to the ./con‐
18080 figure --prefix=$SDLDIR used in building SDL.
18081 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
18083 but with modifications to recognize OS X frameworks and additional Unix
18084 paths (FreeBSD, etc).
18085 FindSDL_net
18087 Locate SDL_net library
18088 This module defines:
18090 SDL_NET_LIBRARIES, the name of the library to link against
18092 SDL_NET_INCLUDE_DIRS, where to find the headers
18093 SDL_NET_FOUND, if false, do not try to link against
18094 SDL_NET_VERSION_STRING - human-readable string containing the version of SDL_net
18095 For backward compatibility the following variables are also set:
18097 SDLNET_LIBRARY (same value as SDL_NET_LIBRARIES)
18099 SDLNET_INCLUDE_DIR (same value as SDL_NET_INCLUDE_DIRS)
18100 SDLNET_FOUND (same value as SDL_NET_FOUND)
18101 $SDLDIR is an environment variable that would correspond to the ./con‐
18103 figure --prefix=$SDLDIR used in building SDL.
18104 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
18106 but with modifications to recognize OS X frameworks and additional Unix
18107 paths (FreeBSD, etc).
18108 FindSDL_sound
18110 Locates the SDL_sound library
18111 This module depends on SDL being found and must be called AFTER Find‐
18113 SDL.cmake is called.
18114 This module defines
18116 SDL_SOUND_INCLUDE_DIR, where to find SDL_sound.h
18118 SDL_SOUND_FOUND, if false, do not try to link to SDL_sound
18119 SDL_SOUND_LIBRARIES, this contains the list of libraries that you need
18120 to link against.
18121 SDL_SOUND_EXTRAS, this is an optional variable for you to add your own
18122 flags to SDL_SOUND_LIBRARIES. This is prepended to SDL_SOUND_LIBRARIES.
18123 This is available mostly for cases this module failed to anticipate for
18124 and you must add additional flags. This is marked as ADVANCED.
18125 SDL_SOUND_VERSION_STRING, human-readable string containing the
18126 version of SDL_sound
18127 This module also defines (but you shouldn't need to use directly)
18129 SDL_SOUND_LIBRARY, the name of just the SDL_sound library you would link
18131 against. Use SDL_SOUND_LIBRARIES for you link instructions and not this one.
18132 And might define the following as needed
18134 MIKMOD_LIBRARY
18136 MODPLUG_LIBRARY
18137 OGG_LIBRARY
18138 VORBIS_LIBRARY
18139 SMPEG_LIBRARY
18140 FLAC_LIBRARY
18141 SPEEX_LIBRARY
18142 Typically, you should not use these variables directly, and you should
18144 use SDL_SOUND_LIBRARIES which contains SDL_SOUND_LIBRARY and the other
18145 audio libraries (if needed) to successfully compile on your system.
18146 Created by Eric Wing. This module is a bit more complicated than the
18148 other FindSDL* family modules. The reason is that SDL_sound can be
18149 compiled in a large variety of different ways which are independent of
18150 platform. SDL_sound may dynamically link against other 3rd party li‐
18151 braries to get additional codec support, such as Ogg Vorbis, SMPEG,
18152 ModPlug, MikMod, FLAC, Speex, and potentially others. Under some cir‐
18153 cumstances which I don't fully understand, there seems to be a require‐
18154 ment that dependent libraries of libraries you use must also be explic‐
18155 itly linked against in order to successfully compile. SDL_sound does
18156 not currently have any system in place to know how it was compiled. So
18157 this CMake module does the hard work in trying to discover which 3rd
18158 party libraries are required for building (if any). This module uses a
18159 brute force approach to create a test program that uses SDL_sound, and
18160 then tries to build it. If the build fails, it parses the error output
18161 for known symbol names to figure out which libraries are needed.
18162 Responds to the $SDLDIR and $SDLSOUNDDIR environmental variable that
18164 would correspond to the ./configure --prefix=$SDLDIR used in building
18165 SDL.
18166 On OSX, this will prefer the Framework version (if found) over others.
18168 People will have to manually change the cache values of SDL_LIBRARY to
18169 override this selectionor set the CMake environment CMAKE_INCLUDE_PATH
18170 to modify the search paths.
18171 FindSDL_ttf
18173 Locate SDL_ttf library
18174 This module defines:
18176 SDL_TTF_LIBRARIES, the name of the library to link against
18178 SDL_TTF_INCLUDE_DIRS, where to find the headers
18179 SDL_TTF_FOUND, if false, do not try to link against
18180 SDL_TTF_VERSION_STRING - human-readable string containing the version of SDL_ttf
18181 For backward compatibility the following variables are also set:
18183 SDLTTF_LIBRARY (same value as SDL_TTF_LIBRARIES)
18185 SDLTTF_INCLUDE_DIR (same value as SDL_TTF_INCLUDE_DIRS)
18186 SDLTTF_FOUND (same value as SDL_TTF_FOUND)
18187 $SDLDIR is an environment variable that would correspond to the ./con‐
18189 figure --prefix=$SDLDIR used in building SDL.
18190 Created by Eric Wing. This was influenced by the FindSDL.cmake module,
18192 but with modifications to recognize OS X frameworks and additional Unix
18193 paths (FreeBSD, etc).
18194 FindSelfPackers
18196 Find upx
18197 This module looks for some executable packers (i.e. software that com‐
18199 press executables or shared libs into on-the-fly self-extracting exe‐
18200 cutables or shared libs. Examples:
18201 UPX: http://wildsau.idv.uni-linz.ac.at/mfx/upx.html
18203 FindSquish
18205 -- Typical Use
18206 This module can be used to find Squish.
18208 SQUISH_FOUND If false, don't try to use Squish
18210 SQUISH_VERSION The full version of Squish found
18211 SQUISH_VERSION_MAJOR The major version of Squish found
18212 SQUISH_VERSION_MINOR The minor version of Squish found
18213 SQUISH_VERSION_PATCH The patch version of Squish found
18214 SQUISH_INSTALL_DIR The Squish installation directory
18216 (containing bin, lib, etc)
18217 SQUISH_SERVER_EXECUTABLE The squishserver executable
18218 SQUISH_CLIENT_EXECUTABLE The squishrunner executable
18219 SQUISH_INSTALL_DIR_FOUND Was the install directory found?
18221 SQUISH_SERVER_EXECUTABLE_FOUND Was the server executable found?
18222 SQUISH_CLIENT_EXECUTABLE_FOUND Was the client executable found?
18223 It provides the function squish_add_test() for adding a squish test to
18225 cmake using Squish >= 4.x:
18226 squish_add_test(cmakeTestName
18228 AUT targetName SUITE suiteName TEST squishTestName
18229 [SETTINGSGROUP group] [PRE_COMMAND command] [POST_COMMAND command] )
18230 Changed in version 3.18: In previous CMake versions, this function was
18232 named squish_v4_add_test.
18233 The arguments have the following meaning:
18236 cmakeTestName
18238 this will be used as the first argument for add_test()
18239 AUT targetName
18241 the name of the cmake target which will be used as AUT, i.e. the
18242 executable which will be tested.
18243 SUITE suiteName
18245 this is either the full path to the squish suite, or just the
18246 last directory of the suite, i.e. the suite name. In this case
18247 the CMakeLists.txt which calls squish_add_test() must be located
18248 in the parent directory of the suite directory.
18249 TEST squishTestName
18251 the name of the squish test, i.e. the name of the subdirectory
18252 of the test inside the suite directory.
18253 SETTINGSGROUP group
18255 deprecated, this argument will be ignored.
18256 PRE_COMMAND command
18258 if specified, the given command will be executed before starting
18259 the squish test.
18260 POST_COMMAND command
18262 same as PRE_COMMAND, but after the squish test has been exe‐
18263 cuted.
18264 enable_testing()
18266 find_package(Squish 6.5)
18267 if (SQUISH_FOUND)
18268 squish_add_test(myTestName
18269 AUT myApp
18270 SUITE ${CMAKE_SOURCE_DIR}/tests/mySuite
18271 TEST someSquishTest
18272 )
18273 endif ()
18274 For users of Squish version 3.x the macro squish_v3_add_test() is pro‐
18276 vided:
18277 squish_v3_add_test(testName applicationUnderTest testCase envVars testWrapper)
18279 Use this macro to add a test using Squish 3.x.
18280 enable_testing()
18282 find_package(Squish 3.0)
18283 if (SQUISH_FOUND)
18284 squish_v3_add_test(myTestName myApplication testCase envVars testWrapper)
18285 endif ()
18286 FindSQLite3
18288 New in version 3.14.
18289 Find the SQLite libraries, v3
18292 IMPORTED targets
18294 This module defines the following IMPORTED target:
18295 SQLite::SQLite3
18297 Result variables
18299 This module will set the following variables if found:
18300 SQLite3_INCLUDE_DIRS
18302 where to find sqlite3.h, etc.
18303 SQLite3_LIBRARIES
18305 the libraries to link against to use SQLite3.
18306 SQLite3_VERSION
18308 version of the SQLite3 library found
18309 SQLite3_FOUND
18311 TRUE if found
18312 FindSubversion
18314 Extract information from a subversion working copy
18315 The module defines the following variables:
18317 Subversion_SVN_EXECUTABLE - path to svn command line client
18319 Subversion_VERSION_SVN - version of svn command line client
18320 Subversion_FOUND - true if the command line client was found
18321 SUBVERSION_FOUND - same as Subversion_FOUND, set for compatibility reasons
18322 The minimum required version of Subversion can be specified using the
18324 standard syntax, e.g. find_package(Subversion 1.4).
18325 If the command line client executable is found two macros are defined:
18327 Subversion_WC_INFO(<dir> <var-prefix> [IGNORE_SVN_FAILURE])
18329 Subversion_WC_LOG(<dir> <var-prefix>)
18330 Subversion_WC_INFO extracts information of a subversion working copy at
18332 a given location. This macro defines the following variables if run‐
18333 ning Subversion's info command on <dir> succeeds; otherwise a SEND_ER‐
18334 ROR message is generated.
18335 New in version 3.13: The error can be ignored by providing the IG‐
18337 NORE_SVN_FAILURE option, which causes these variables to remain unde‐
18338 fined.
18339 <var-prefix>_WC_URL - url of the repository (at <dir>)
18342 <var-prefix>_WC_ROOT - root url of the repository
18343 <var-prefix>_WC_REVISION - current revision
18344 <var-prefix>_WC_LAST_CHANGED_AUTHOR - author of last commit
18345 <var-prefix>_WC_LAST_CHANGED_DATE - date of last commit
18346 <var-prefix>_WC_LAST_CHANGED_REV - revision of last commit
18347 <var-prefix>_WC_INFO - output of command `svn info <dir>'
18348 Subversion_WC_LOG retrieves the log message of the base revision of a
18350 subversion working copy at a given location. This macro defines the
18351 variable:
18352 <var-prefix>_LAST_CHANGED_LOG - last log of base revision
18354 Example usage:
18356 find_package(Subversion)
18358 if(SUBVERSION_FOUND)
18359 Subversion_WC_INFO(${PROJECT_SOURCE_DIR} Project)
18360 message("Current revision is ${Project_WC_REVISION}")
18361 Subversion_WC_LOG(${PROJECT_SOURCE_DIR} Project)
18362 message("Last changed log is ${Project_LAST_CHANGED_LOG}")
18363 endif()
18364 FindSWIG
18366 Find the Simplified Wrapper and Interface Generator (SWIG) executable.
18367 This module finds an installed SWIG and determines its version.
18369 New in version 3.18: If a COMPONENTS or OPTIONAL_COMPONENTS argument is
18371 given to the find_package() command, it will also determine supported
18372 target languages.
18373 New in version 3.19: When a version is requested, it can be specified
18376 as a simple value or as a range. For a detailed description of version
18377 range usage and capabilities, refer to the find_package() command.
18378 The module defines the following variables:
18381 SWIG_FOUND
18383 Whether SWIG and any required components were found on the sys‐
18384 tem.
18385 SWIG_EXECUTABLE
18387 Path to the SWIG executable.
18388 SWIG_DIR
18390 Path to the installed SWIG Lib directory (result of swig
18391 -swiglib).
18392 SWIG_VERSION
18394 SWIG executable version (result of swig -version).
18395 SWIG_<lang>_FOUND
18397 If COMPONENTS or OPTIONAL_COMPONENTS are requested, each avail‐
18398 able target language <lang> (lowercase) will be set to TRUE.
18399 Any COMPONENTS given to find_package should be the names of supported
18401 target languages as provided to the LANGUAGE argument of swig_add_li‐
18402 brary, such as python or perl5. Language names must be lowercase.
18403 All information is collected from the SWIG_EXECUTABLE, so the version
18405 to be found can be changed from the command line by means of setting
18406 SWIG_EXECUTABLE.
18407 Example usage requiring SWIG 4.0 or higher and Python language support,
18409 with optional Fortran support:
18410 find_package(SWIG 4.0 COMPONENTS python OPTIONAL_COMPONENTS fortran)
18412 if(SWIG_FOUND)
18413 message("SWIG found: ${SWIG_EXECUTABLE}")
18414 if(NOT SWIG_fortran_FOUND)
18415 message(WARNING "SWIG Fortran bindings cannot be generated")
18416 endif()
18417 endif()
18418 FindTCL
18420 TK_INTERNAL_PATH was removed.
18421 This module finds if Tcl is installed and determines where the include
18423 files and libraries are. It also determines what the name of the li‐
18424 brary is. This code sets the following variables:
18425 TCL_FOUND = Tcl was found
18427 TK_FOUND = Tk was found
18428 TCLTK_FOUND = Tcl and Tk were found
18429 TCL_LIBRARY = path to Tcl library (tcl tcl80)
18430 TCL_INCLUDE_PATH = path to where tcl.h can be found
18431 TCL_TCLSH = path to tclsh binary (tcl tcl80)
18432 TK_LIBRARY = path to Tk library (tk tk80 etc)
18433 TK_INCLUDE_PATH = path to where tk.h can be found
18434 TK_WISH = full path to the wish executable
18435 In an effort to remove some clutter and clear up some issues for people
18437 who are not necessarily Tcl/Tk gurus/developers, some variables were
18438 moved or removed. Changes compared to CMake 2.4 are:
18439 => they were only useful for people writing Tcl/Tk extensions.
18441 => these libs are not packaged by default with Tcl/Tk distributions.
18442 Even when Tcl/Tk is built from source, several flavors of debug libs
18443 are created and there is no real reason to pick a single one
18444 specifically (say, amongst tcl84g, tcl84gs, or tcl84sgx).
18445 Let's leave that choice to the user by allowing him to assign
18446 TCL_LIBRARY to any Tcl library, debug or not.
18447 => this ended up being only a Win32 variable, and there is a lot of
18448 confusion regarding the location of this file in an installed Tcl/Tk
18449 tree anyway (see 8.5 for example). If you need the internal path at
18450 this point it is safer you ask directly where the *source* tree is
18451 and dig from there.
18452 FindTclsh
18454 Find tclsh
18455 This module finds if TCL is installed and determines where the include
18457 files and libraries are. It also determines what the name of the li‐
18458 brary is. This code sets the following variables:
18459 TCLSH_FOUND = TRUE if tclsh has been found
18461 TCL_TCLSH = the path to the tclsh executable
18462 FindTclStub
18464 TCL_STUB_LIBRARY_DEBUG and TK_STUB_LIBRARY_DEBUG were removed.
18465 This module finds Tcl stub libraries. It first finds Tcl include files
18467 and libraries by calling FindTCL.cmake. How to Use the Tcl Stubs Li‐
18468 brary:
18469 http://tcl.activestate.com/doc/howto/stubs.html
18471 Using Stub Libraries:
18473 http://safari.oreilly.com/0130385603/ch48lev1sec3
18475 This code sets the following variables:
18477 TCL_STUB_LIBRARY = path to Tcl stub library
18479 TK_STUB_LIBRARY = path to Tk stub library
18480 TTK_STUB_LIBRARY = path to ttk stub library
18481 In an effort to remove some clutter and clear up some issues for people
18483 who are not necessarily Tcl/Tk gurus/developers, some variables were
18484 moved or removed. Changes compared to CMake 2.4 are:
18485 => these libs are not packaged by default with Tcl/Tk distributions.
18487 Even when Tcl/Tk is built from source, several flavors of debug libs
18488 are created and there is no real reason to pick a single one
18489 specifically (say, amongst tclstub84g, tclstub84gs, or tclstub84sgx).
18490 Let's leave that choice to the user by allowing him to assign
18491 TCL_STUB_LIBRARY to any Tcl library, debug or not.
18492 FindThreads
18494 This module determines the thread library of the system.
18495 Imported Targets
18497 New in version 3.1.
18498 This module defines the following IMPORTED target:
18501 Threads::Threads
18503 The thread library, if found.
18504 Result Variables
18506 The following variables are set:
18507 Threads_FOUND
18509 If a supported thread library was found.
18510 CMAKE_THREAD_LIBS_INIT
18512 The thread library to use. This may be empty if the thread func‐
18513 tions are provided by the system libraries and no special flags
18514 are needed to use them.
18515 CMAKE_USE_WIN32_THREADS_INIT
18517 If the found thread library is the win32 one.
18518 CMAKE_USE_PTHREADS_INIT
18520 If the found thread library is pthread compatible.
18521 CMAKE_HP_PTHREADS_INIT
18523 If the found thread library is the HP thread library.
18524 Variables Affecting Behavior
18526 THREADS_PREFER_PTHREAD_FLAG
18527 New in version 3.1.
18528 If the use of the -pthread compiler and linker flag is preferred
18531 then the caller can set this variable to TRUE. The compiler flag
18532 can only be used with the imported target. Use of both the im‐
18533 ported target as well as this switch is highly recommended for
18534 new code.
18535 This variable has no effect if the system libraries provide the
18537 thread functions, i.e. when CMAKE_THREAD_LIBS_INIT will be
18538 empty.
18539 FindTIFF
18541 Find the TIFF library (libtiff, https://libtiff.gitlab.io/libtiff/).
18542 Optional COMPONENTS
18544 This module supports the optional component CXX, for use with the COM‐
18545 PONENTS argument of the find_package() command. This component has an
18546 associated imported target, as described below.
18547 Imported targets
18549 New in version 3.5.
18550 This module defines the following IMPORTED targets:
18553 TIFF::TIFF
18555 The TIFF library, if found.
18556 TIFF::CXX
18558 New in version 3.19.
18559 The C++ wrapper libtiffxx, if requested by the COMPONENTS CXX
18562 option, if the compiler is not MSVC (which includes the C++
18563 wrapper in libtiff), and if found.
18564 Result variables
18566 This module will set the following variables in your project:
18567 TIFF_FOUND
18569 true if the TIFF headers and libraries were found
18570 TIFF_INCLUDE_DIR
18572 the directory containing the TIFF headers
18573 TIFF_INCLUDE_DIRS
18575 the directory containing the TIFF headers
18576 TIFF_LIBRARIES
18578 TIFF libraries to be linked
18579 Cache variables
18581 The following cache variables may also be set:
18582 TIFF_INCLUDE_DIR
18584 the directory containing the TIFF headers
18585 TIFF_LIBRARY_RELEASE
18587 the path to the TIFF library for release configurations
18588 TIFF_LIBRARY_DEBUG
18590 the path to the TIFF library for debug configurations
18591 TIFFXX_LIBRARY_RELEASE
18593 the path to the TIFFXX library for release configurations
18594 TIFFXX_LIBRARY_DEBUG
18596 the path to the TIFFXX library for debug configurations
18597 New in version 3.4: Debug and Release variants are found separately.
18599 FindUnixCommands
18602 Find Unix commands, including the ones from Cygwin
18603 This module looks for the Unix commands bash, cp, gzip, mv, rm, and tar
18605 and stores the result in the variables BASH, CP, GZIP, MV, RM, and TAR.
18606 FindVTK
18608 This module no longer exists.
18609 This module existed in versions of CMake prior to 3.1, but became only
18611 a thin wrapper around find_package(VTK NO_MODULE) to provide compati‐
18612 bility for projects using long-outdated conventions. Now find_pack‐
18613 age(VTK) will search for VTKConfig.cmake directly.
18614 FindVulkan
18616 New in version 3.7.
18617 Find Vulkan, which is a low-overhead, cross-platform 3D graphics and
18620 computing API.
18621 IMPORTED Targets
18623 This module defines IMPORTED targets if Vulkan has been found:
18624 Vulkan::Vulkan
18626 The main Vulkan library.
18627 Vulkan::glslc
18629 New in version 3.19.
18630 The GLSLC SPIR-V compiler, if it has been found.
18633 Vulkan::Headers
18635 New in version 3.21.
18636 Provides just Vulkan headers include paths, if found. No li‐
18639 brary is included in this target. This can be useful for appli‐
18640 cations that load Vulkan library dynamically.
18641 Vulkan::glslangValidator
18643 New in version 3.21.
18644 The glslangValidator tool, if found. It is used to compile GLSL
18647 and HLSL shaders into SPIR-V.
18648 Result Variables
18650 This module defines the following variables:
18651 Vulkan_FOUND - "True" if Vulkan was found
18653 Vulkan_INCLUDE_DIRS - include directories for Vulkan
18654 Vulkan_LIBRARIES - link against this library to use Vulkan
18655 The module will also define three cache variables:
18657 Vulkan_INCLUDE_DIR - the Vulkan include directory
18659 Vulkan_LIBRARY - the path to the Vulkan library
18660 Vulkan_GLSLC_EXECUTABLE - the path to the GLSL SPIR-V compiler
18661 Vulkan_GLSLANG_VALIDATOR_EXECUTABLE - the path to the glslangValidator tool
18662 Hints
18664 New in version 3.18.
18665 The VULKAN_SDK environment variable optionally specifies the location
18668 of the Vulkan SDK root directory for the given architecture. It is typ‐
18669 ically set by sourcing the toplevel setup-env.sh script of the Vulkan
18670 SDK directory into the shell environment.
18671 FindWget
18673 Find wget
18674 This module looks for wget. This module defines the following values:
18676 WGET_EXECUTABLE: the full path to the wget tool.
18678 WGET_FOUND: True if wget has been found.
18679 FindWish
18681 Find wish installation
18682 This module finds if TCL is installed and determines where the include
18684 files and libraries are. It also determines what the name of the li‐
18685 brary is. This code sets the following variables:
18686 TK_WISH = the path to the wish executable
18688 if UNIX is defined, then it will look for the cygwin version first
18690 FindwxWidgets
18692 Find a wxWidgets (a.k.a., wxWindows) installation.
18693 This module finds if wxWidgets is installed and selects a default con‐
18695 figuration to use. wxWidgets is a modular library. To specify the
18696 modules that you will use, you need to name them as components to the
18697 package:
18698 find_package(wxWidgets COMPONENTS core base ... OPTIONAL_COMPONENTS net
18700 ...)
18701 New in version 3.4: Support for find_package() version argument; web‐
18703 view component.
18704 New in version 3.14: OPTIONAL_COMPONENTS support.
18707 There are two search branches: a windows style and a unix style. For
18710 windows, the following variables are searched for and set to defaults
18711 in case of multiple choices. Change them if the defaults are not de‐
18712 sired (i.e., these are the only variables you should change to select a
18713 configuration):
18714 wxWidgets_ROOT_DIR - Base wxWidgets directory
18716 (e.g., C:/wxWidgets-2.6.3).
18717 wxWidgets_LIB_DIR - Path to wxWidgets libraries
18718 (e.g., C:/wxWidgets-2.6.3/lib/vc_lib).
18719 wxWidgets_CONFIGURATION - Configuration to use
18720 (e.g., msw, mswd, mswu, mswunivud, etc.)
18721 wxWidgets_EXCLUDE_COMMON_LIBRARIES
18722 - Set to TRUE to exclude linking of
18723 commonly required libs (e.g., png tiff
18724 jpeg zlib regex expat).
18725 For unix style it uses the wx-config utility. You can select between
18727 debug/release, unicode/ansi, universal/non-universal, and static/shared
18728 in the QtDialog or ccmake interfaces by turning ON/OFF the following
18729 variables:
18730 wxWidgets_USE_DEBUG
18732 wxWidgets_USE_UNICODE
18733 wxWidgets_USE_UNIVERSAL
18734 wxWidgets_USE_STATIC
18735 There is also a wxWidgets_CONFIG_OPTIONS variable for all other options
18737 that need to be passed to the wx-config utility. For example, to use
18738 the base toolkit found in the /usr/local path, set the variable (before
18739 calling the FIND_PACKAGE command) as such:
18740 set(wxWidgets_CONFIG_OPTIONS --toolkit=base --prefix=/usr)
18742 The following are set after the configuration is done for both windows
18744 and unix style:
18745 wxWidgets_FOUND - Set to TRUE if wxWidgets was found.
18747 wxWidgets_INCLUDE_DIRS - Include directories for WIN32
18748 i.e., where to find "wx/wx.h" and
18749 "wx/setup.h"; possibly empty for unices.
18750 wxWidgets_LIBRARIES - Path to the wxWidgets libraries.
18751 wxWidgets_LIBRARY_DIRS - compile time link dirs, useful for
18752 rpath on UNIX. Typically an empty string
18753 in WIN32 environment.
18754 wxWidgets_DEFINITIONS - Contains defines required to compile/link
18755 against WX, e.g. WXUSINGDLL
18756 wxWidgets_DEFINITIONS_DEBUG- Contains defines required to compile/link
18757 against WX debug builds, e.g. __WXDEBUG__
18758 wxWidgets_CXX_FLAGS - Include dirs and compiler flags for
18759 unices, empty on WIN32. Essentially
18760 "`wx-config --cxxflags`".
18761 wxWidgets_USE_FILE - Convenience include file.
18762 New in version 3.11: The following environment variables can be used as
18764 hints: WX_CONFIG, WXRC_CMD.
18765 Sample usage:
18768 # Note that for MinGW users the order of libs is important!
18770 find_package(wxWidgets COMPONENTS gl core base OPTIONAL_COMPONENTS net)
18771 if(wxWidgets_FOUND)
18772 include(${wxWidgets_USE_FILE})
18773 # and for each of your dependent executable/library targets:
18774 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
18775 endif()
18776 If wxWidgets is required (i.e., not an optional part):
18778 find_package(wxWidgets REQUIRED gl core base OPTIONAL_COMPONENTS net)
18780 include(${wxWidgets_USE_FILE})
18781 # and for each of your dependent executable/library targets:
18782 target_link_libraries(<YourTarget> ${wxWidgets_LIBRARIES})
18783 FindX11
18785 Find X11 installation
18786 Try to find X11 on UNIX systems. The following values are defined
18788 X11_FOUND - True if X11 is available
18790 X11_INCLUDE_DIR - include directories to use X11
18791 X11_LIBRARIES - link against these to use X11
18792 and also the following more fine grained variables and targets:
18794 New in version 3.14: Imported targets.
18796 X11_ICE_INCLUDE_PATH, X11_ICE_LIB, X11_ICE_FOUND, X11::ICE
18799 X11_SM_INCLUDE_PATH, X11_SM_LIB, X11_SM_FOUND, X11::SM
18800 X11_X11_INCLUDE_PATH, X11_X11_LIB, X11::X11
18801 X11_Xaccessrules_INCLUDE_PATH,
18802 X11_Xaccessstr_INCLUDE_PATH, X11_Xaccess_FOUND
18803 X11_Xau_INCLUDE_PATH, X11_Xau_LIB, X11_Xau_FOUND, X11::Xau
18804 X11_xcb_INCLUDE_PATH, X11_xcb_LIB, X11_xcb_FOUND, X11::xcb
18805 X11_X11_xcb_INCLUDE_PATH, X11_X11_xcb_LIB, X11_X11_xcb_FOUND, X11::X11_xcb
18806 X11_xcb_icccm_INCLUDE_PATH, X11_xcb_icccm_LIB, X11_xcb_icccm_FOUND, X11::xcb_icccm
18807 X11_xcb_util_INCLUDE_PATH, X11_xcb_util_LIB, X11_xcb_util_FOUND, X11::xcb_util
18808 X11_xcb_xfixes_INCLUDE_PATH, X11_xcb_xfixes_LIB, X11_xcb_xfixes_FOUND, X11::xcb_xfixes
18809 X11_xcb_xkb_INCLUDE_PATH, X11_xcb_xkb_LIB, X11_xcb_xkb_FOUND, X11::xcb_xkb
18810 X11_Xcomposite_INCLUDE_PATH, X11_Xcomposite_LIB, X11_Xcomposite_FOUND, X11::Xcomposite
18811 X11_Xcursor_INCLUDE_PATH, X11_Xcursor_LIB, X11_Xcursor_FOUND, X11::Xcursor
18812 X11_Xdamage_INCLUDE_PATH, X11_Xdamage_LIB, X11_Xdamage_FOUND, X11::Xdamage
18813 X11_Xdmcp_INCLUDE_PATH, X11_Xdmcp_LIB, X11_Xdmcp_FOUND, X11::Xdmcp
18814 X11_Xext_INCLUDE_PATH, X11_Xext_LIB, X11_Xext_FOUND, X11::Xext
18815 X11_Xxf86misc_INCLUDE_PATH, X11_Xxf86misc_LIB, X11_Xxf86misc_FOUND, X11::Xxf86misc
18816 X11_Xxf86vm_INCLUDE_PATH, X11_Xxf86vm_LIB X11_Xxf86vm_FOUND, X11::Xxf86vm
18817 X11_Xfixes_INCLUDE_PATH, X11_Xfixes_LIB, X11_Xfixes_FOUND, X11::Xfixes
18818 X11_Xft_INCLUDE_PATH, X11_Xft_LIB, X11_Xft_FOUND, X11::Xft
18819 X11_Xi_INCLUDE_PATH, X11_Xi_LIB, X11_Xi_FOUND, X11::Xi
18820 X11_Xinerama_INCLUDE_PATH, X11_Xinerama_LIB, X11_Xinerama_FOUND, X11::Xinerama
18821 X11_Xkb_INCLUDE_PATH,
18822 X11_Xkblib_INCLUDE_PATH, X11_Xkb_FOUND, X11::Xkb
18823 X11_xkbcommon_INCLUDE_PATH, X11_xkbcommon_LIB, X11_xkbcommon_FOUND, X11::xkbcommon
18824 X11_xkbcommon_X11_INCLUDE_PATH,X11_xkbcommon_X11_LIB,X11_xkbcommon_X11_FOUND,X11::xkbcommon_X11
18825 X11_xkbfile_INCLUDE_PATH, X11_xkbfile_LIB, X11_xkbfile_FOUND, X11::xkbfile
18826 X11_Xmu_INCLUDE_PATH, X11_Xmu_LIB, X11_Xmu_FOUND, X11::Xmu
18827 X11_Xpm_INCLUDE_PATH, X11_Xpm_LIB, X11_Xpm_FOUND, X11::Xpm
18828 X11_Xtst_INCLUDE_PATH, X11_Xtst_LIB, X11_Xtst_FOUND, X11::Xtst
18829 X11_Xrandr_INCLUDE_PATH, X11_Xrandr_LIB, X11_Xrandr_FOUND, X11::Xrandr
18830 X11_Xrender_INCLUDE_PATH, X11_Xrender_LIB, X11_Xrender_FOUND, X11::Xrender
18831 X11_XRes_INCLUDE_PATH, X11_XRes_LIB, X11_XRes_FOUND, X11::XRes
18832 X11_Xss_INCLUDE_PATH, X11_Xss_LIB, X11_Xss_FOUND, X11::Xss
18833 X11_Xt_INCLUDE_PATH, X11_Xt_LIB, X11_Xt_FOUND, X11::Xt
18834 X11_Xutil_INCLUDE_PATH, X11_Xutil_FOUND, X11::Xutil
18835 X11_Xv_INCLUDE_PATH, X11_Xv_LIB, X11_Xv_FOUND, X11::Xv
18836 X11_dpms_INCLUDE_PATH, (in X11_Xext_LIB), X11_dpms_FOUND
18837 X11_XShm_INCLUDE_PATH, (in X11_Xext_LIB), X11_XShm_FOUND
18838 X11_Xshape_INCLUDE_PATH, (in X11_Xext_LIB), X11_Xshape_FOUND
18839 X11_XSync_INCLUDE_PATH, (in X11_Xext_LIB), X11_XSync_FOUND
18840 X11_Xaw_INCLUDE_PATH, X11_Xaw_LIB X11_Xaw_FOUND X11::Xaw
18841 New in version 3.14: Renamed Xxf86misc, X11_Xxf86misc, X11_Xxf86vm,
18843 X11_xkbfile, X11_Xtst, and X11_Xss libraries to match their file names.
18844 Deprecated the X11_Xinput library. Old names are still available for
18845 compatibility.
18846 New in version 3.14: Added the X11_Xext_INCLUDE_PATH variable.
18849 New in version 3.18: Added the xcb, X11-xcb, xcb-icccm, xcb-xkb, xkb‐
18852 common, and xkbcommon-X11 libraries.
18853 New in version 3.19: Added the Xaw, xcb_util, and xcb_xfixes libraries.
18856 FindXalanC
18859 New in version 3.5.
18860 Find the Apache Xalan-C++ XSL transform processor headers and li‐
18863 braries.
18864 Imported targets
18866 This module defines the following IMPORTED targets:
18867 XalanC::XalanC
18869 The Xalan-C++ xalan-c library, if found.
18870 Result variables
18872 This module will set the following variables in your project:
18873 XalanC_FOUND
18875 true if the Xalan headers and libraries were found
18876 XalanC_VERSION
18878 Xalan release version
18879 XalanC_INCLUDE_DIRS
18881 the directory containing the Xalan headers; note XercesC_IN‐
18882 CLUDE_DIRS is also required
18883 XalanC_LIBRARIES
18885 Xalan libraries to be linked; note XercesC_LIBRARIES is also re‐
18886 quired
18887 Cache variables
18889 The following cache variables may also be set:
18890 XalanC_INCLUDE_DIR
18892 the directory containing the Xalan headers
18893 XalanC_LIBRARY
18895 the Xalan library
18896 FindXCTest
18898 New in version 3.3.
18899 Functions to help creating and executing XCTest bundles.
18902 An XCTest bundle is a CFBundle with a special product-type and bundle
18904 extension. The Mac Developer Library provides more information in the
18905 Testing with Xcode document.
18906 Module Functions
18908 xctest_add_bundle
18909 The xctest_add_bundle function creates a XCTest bundle named
18910 <target> which will test the target <testee>. Supported target
18911 types for testee are Frameworks and App Bundles:
18912 xctest_add_bundle(
18914 <target> # Name of the XCTest bundle
18915 <testee> # Target name of the testee
18916 )
18917 xctest_add_test
18919 The xctest_add_test function adds an XCTest bundle to the
18920 project to be run by ctest(1). The test will be named <name> and
18921 tests <bundle>:
18922 xctest_add_test(
18924 <name> # Test name
18925 <bundle> # Target name of XCTest bundle
18926 )
18927 Module Variables
18929 The following variables are set by including this module:
18930 XCTest_FOUND
18932 True if the XCTest Framework and executable were found.
18933 XCTest_EXECUTABLE
18935 The path to the xctest command line tool used to execute XCTest
18936 bundles.
18937 XCTest_INCLUDE_DIRS
18939 The directory containing the XCTest Framework headers.
18940 XCTest_LIBRARIES
18942 The location of the XCTest Framework.
18943 FindXercesC
18945 New in version 3.1.
18946 Find the Apache Xerces-C++ validating XML parser headers and libraries.
18949 Imported targets
18951 New in version 3.5.
18952 This module defines the following IMPORTED targets:
18955 XercesC::XercesC
18957 The Xerces-C++ xerces-c library, if found.
18958 Result variables
18960 This module will set the following variables in your project:
18961 XercesC_FOUND
18963 true if the Xerces headers and libraries were found
18964 XercesC_VERSION
18966 Xerces release version
18967 XercesC_INCLUDE_DIRS
18969 the directory containing the Xerces headers
18970 XercesC_LIBRARIES
18972 Xerces libraries to be linked
18973 Cache variables
18975 The following cache variables may also be set:
18976 XercesC_INCLUDE_DIR
18978 the directory containing the Xerces headers
18979 XercesC_LIBRARY
18981 the Xerces library
18982 New in version 3.4: Debug and Release variants are found separately.
18984 FindXMLRPC
18987 Find xmlrpc
18988 Find the native XMLRPC headers and libraries.
18990 XMLRPC_INCLUDE_DIRS - where to find xmlrpc.h, etc.
18992 XMLRPC_LIBRARIES - List of libraries when using xmlrpc.
18993 XMLRPC_FOUND - True if xmlrpc found.
18994 XMLRPC modules may be specified as components for this find module.
18996 Modules may be listed by running "xmlrpc-c-config". Modules include:
18997 c++ C++ wrapper code
18999 libwww-client libwww-based client
19000 cgi-server CGI-based server
19001 abyss-server ABYSS-based server
19002 Typical usage:
19004 find_package(XMLRPC REQUIRED libwww-client)
19006 FindZLIB
19008 Find the native ZLIB includes and library.
19009 IMPORTED Targets
19011 New in version 3.1.
19012 This module defines IMPORTED target ZLIB::ZLIB, if ZLIB has been found.
19015 Result Variables
19017 This module defines the following variables:
19018 ZLIB_INCLUDE_DIRS - where to find zlib.h, etc.
19020 ZLIB_LIBRARIES - List of libraries when using zlib.
19021 ZLIB_FOUND - True if zlib found.
19022 ZLIB_VERSION_STRING - The version of zlib found (x.y.z)
19024 ZLIB_VERSION_MAJOR - The major version of zlib
19025 ZLIB_VERSION_MINOR - The minor version of zlib
19026 ZLIB_VERSION_PATCH - The patch version of zlib
19027 ZLIB_VERSION_TWEAK - The tweak version of zlib
19028 New in version 3.4: Debug and Release variants are found separately.
19030 Backward Compatibility
19033 The following variable are provided for backward compatibility
19034 ZLIB_MAJOR_VERSION - The major version of zlib
19036 ZLIB_MINOR_VERSION - The minor version of zlib
19037 ZLIB_PATCH_VERSION - The patch version of zlib
19038 Hints
19040 A user may set ZLIB_ROOT to a zlib installation root to tell this mod‐
19041 ule where to look.
19042
19044 Deprecated Utility Modules
19045 AddFileDependencies
19046 Deprecated since version 3.20.
19047 Add dependencies to a source file.
19050 add_file_dependencies(<source> <files>...)
19052 Adds the given <files> to the dependencies of file <source>.
19054 Do not use this command in new code. It is just a wrapper around:
19056 set_property(SOURCE <source> APPEND PROPERTY OBJECT_DEPENDS <files>...)
19058 Instead use the set_property() command to append to the OBJECT_DEPENDS
19060 source file property directly.
19061 CMakeDetermineVSServicePack
19063 Deprecated since version 3.0: Do not use.
19064 The functionality of this module has been superseded by the
19067 CMAKE_<LANG>_COMPILER_VERSION variable that contains the compiler ver‐
19068 sion number.
19069 Determine the Visual Studio service pack of the 'cl' in use.
19071 Usage:
19073 if(MSVC)
19075 include(CMakeDetermineVSServicePack)
19076 DetermineVSServicePack( my_service_pack )
19077 if( my_service_pack )
19078 message(STATUS "Detected: ${my_service_pack}")
19079 endif()
19080 endif()
19081 Function DetermineVSServicePack sets the given variable to one of the
19083 following values or an empty string if unknown:
19084 vc80, vc80sp1
19086 vc90, vc90sp1
19087 vc100, vc100sp1
19088 vc110, vc110sp1, vc110sp2, vc110sp3, vc110sp4
19089 CMakeExpandImportedTargets
19091 Deprecated since version 3.4: Do not use.
19092 This module was once needed to expand imported targets to the underly‐
19095 ing libraries they reference on disk for use with the try_compile() and
19096 try_run() commands. These commands now support imported libraries in
19097 their LINK_LIBRARIES options (since CMake 2.8.11 for try_compile() and
19098 since CMake 3.2 for try_run()).
19099 This module does not support the policy CMP0022 NEW behavior or use of
19101 the INTERFACE_LINK_LIBRARIES property because generator expressions
19102 cannot be evaluated during configuration.
19103 CMAKE_EXPAND_IMPORTED_TARGETS(<var> LIBRARIES lib1 lib2...libN
19105 [CONFIGURATION <config>])
19106 CMAKE_EXPAND_IMPORTED_TARGETS() takes a list of libraries and replaces
19108 all imported targets contained in this list with their actual file
19109 paths of the referenced libraries on disk, including the libraries from
19110 their link interfaces. If a CONFIGURATION is given, it uses the re‐
19111 spective configuration of the imported targets if it exists. If no
19112 CONFIGURATION is given, it uses the first configuration from
19113 ${CMAKE_CONFIGURATION_TYPES} if set, otherwise ${CMAKE_BUILD_TYPE}.
19114 cmake_expand_imported_targets(expandedLibs
19116 LIBRARIES ${CMAKE_REQUIRED_LIBRARIES}
19117 CONFIGURATION "${CMAKE_TRY_COMPILE_CONFIGURATION}" )
19118 CMakeForceCompiler
19120 Deprecated since version 3.6: Do not use.
19121 The macros provided by this module were once intended for use by
19124 cross-compiling toolchain files when CMake was not able to automati‐
19125 cally detect the compiler identification. Since the introduction of
19126 this module, CMake's compiler identification capabilities have improved
19127 and can now be taught to recognize any compiler. Furthermore, the
19128 suite of information CMake detects from a compiler is now too extensive
19129 to be provided by toolchain files using these macros.
19130 One common use case for this module was to skip CMake's checks for a
19132 working compiler when using a cross-compiler that cannot link binaries
19133 without special flags or custom linker scripts. This case is now sup‐
19134 ported by setting the CMAKE_TRY_COMPILE_TARGET_TYPE variable in the
19135 toolchain file instead.
19136 ----
19139 Macro CMAKE_FORCE_C_COMPILER has the following signature:
19143 CMAKE_FORCE_C_COMPILER(<compiler> <compiler-id>)
19145 It sets CMAKE_C_COMPILER to the given compiler and the cmake internal
19147 variable CMAKE_C_COMPILER_ID to the given compiler-id. It also by‐
19148 passes the check for working compiler and basic compiler information
19149 tests.
19150 Macro CMAKE_FORCE_CXX_COMPILER has the following signature:
19152 CMAKE_FORCE_CXX_COMPILER(<compiler> <compiler-id>)
19154 It sets CMAKE_CXX_COMPILER to the given compiler and the cmake internal
19156 variable CMAKE_CXX_COMPILER_ID to the given compiler-id. It also by‐
19157 passes the check for working compiler and basic compiler information
19158 tests.
19159 Macro CMAKE_FORCE_Fortran_COMPILER has the following signature:
19161 CMAKE_FORCE_Fortran_COMPILER(<compiler> <compiler-id>)
19163 It sets CMAKE_Fortran_COMPILER to the given compiler and the cmake in‐
19165 ternal variable CMAKE_Fortran_COMPILER_ID to the given compiler-id. It
19166 also bypasses the check for working compiler and basic compiler infor‐
19167 mation tests.
19168 So a simple toolchain file could look like this:
19170 include (CMakeForceCompiler)
19172 set(CMAKE_SYSTEM_NAME Generic)
19173 CMAKE_FORCE_C_COMPILER (chc12 MetrowerksHicross)
19174 CMAKE_FORCE_CXX_COMPILER (chc12 MetrowerksHicross)
19175 CMakeParseArguments
19177 This module once implemented the cmake_parse_arguments() command that
19178 is now implemented natively by CMake. It is now an empty placeholder
19179 for compatibility with projects that include it to get the command from
19180 CMake 3.4 and lower.
19181 Documentation
19183 Deprecated since version 3.18: This module does nothing, unless policy
19184 CMP0106 is set to OLD.
19185 This module provides support for the VTK documentation framework. It
19188 relies on several tools (Doxygen, Perl, etc).
19189 MacroAddFileDependencies
19191 Deprecated since version 3.14.
19192 MACRO_ADD_FILE_DEPENDENCIES(<source> <files>...)
19195 Do not use this command in new code. It is just a wrapper around:
19197 set_property(SOURCE <source> APPEND PROPERTY OBJECT_DEPENDS <files>...)
19199 Instead use the set_property() command to append to the OBJECT_DEPENDS
19201 source file property directly.
19202 TestCXXAcceptsFlag
19204 Deprecated since version 3.0: See CheckCXXCompilerFlag.
19205 Check if the CXX compiler accepts a flag.
19208 CHECK_CXX_ACCEPTS_FLAG(<flags> <variable>)
19210 <flags>
19212 the flags to try
19213 <variable>
19215 variable to store the result
19216 UseJavaClassFilelist
19218 Changed in version 3.20: This module was previously documented by mis‐
19219 take and was never meant for direct inclusion by project code. See the
19220 UseJava module.
19221 UseJavaSymlinks
19224 Changed in version 3.20: This module was previously documented by mis‐
19225 take and was never meant for direct inclusion by project code. See the
19226 UseJava module.
19227 UsePkgConfig
19230 Obsolete pkg-config module for CMake, use FindPkgConfig instead.
19231 This module defines the following macro:
19233 PKGCONFIG(package includedir libdir linkflags cflags)
19235 Calling PKGCONFIG will fill the desired information into the 4 given
19237 arguments, e.g. PKGCONFIG(libart-2.0 LIBART_INCLUDE_DIR
19238 LIBART_LINK_DIR LIBART_LINK_FLAGS LIBART_CFLAGS) if pkg-config was NOT
19239 found or the specified software package doesn't exist, the variable
19240 will be empty when the function returns, otherwise they will contain
19241 the respective information
19242 Use_wxWindows
19244 Deprecated since version 2.8.10: Use find_package(wxWidgets) and in‐
19245 clude(${wxWidgets_USE_FILE}) instead.
19246 This convenience include finds if wxWindows is installed and set the
19249 appropriate libs, incdirs, flags etc. author Jan Woetzel <jw -at-
19250 mip.informatik.uni-kiel.de> (07/2003)
19251 USAGE:
19253 just include Use_wxWindows.cmake
19255 in your projects CMakeLists.txt
19256 include( ${CMAKE_MODULE_PATH}/Use_wxWindows.cmake)
19258 if you are sure you need GL then
19260 set(WXWINDOWS_USE_GL 1)
19262 *before* you include this file.
19264 WriteBasicConfigVersionFile
19266 Deprecated since version 3.0: Use the identical command write_ba‐
19267 sic_package_version_file() from module CMakePackageConfigHelpers.
19268 WRITE_BASIC_CONFIG_VERSION_FILE( filename
19271 [VERSION major.minor.patch]
19272 COMPATIBILITY (AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion)
19273 [ARCH_INDEPENDENT]
19274 )
19275 WriteCompilerDetectionHeader
19277 Deprecated since version 3.20: This module is available only if policy
19278 CMP0120 is not set to NEW. Do not use it in new code.
19279 New in version 3.1.
19282 This module provides the function write_compiler_detection_header().
19285 This function can be used to generate a file suitable for preprocessor
19287 inclusion which contains macros to be used in source code:
19288 write_compiler_detection_header(
19290 FILE <file>
19291 PREFIX <prefix>
19292 [OUTPUT_FILES_VAR <output_files_var> OUTPUT_DIR <output_dir>]
19293 COMPILERS <compiler> [...]
19294 FEATURES <feature> [...]
19295 [BARE_FEATURES <feature> [...]]
19296 [VERSION <version>]
19297 [PROLOG <prolog>]
19298 [EPILOG <epilog>]
19299 [ALLOW_UNKNOWN_COMPILERS]
19300 [ALLOW_UNKNOWN_COMPILER_VERSIONS]
19301 )
19302 This generates the file <file> with macros which all have the prefix
19304 <prefix>.
19305 By default, all content is written directly to the <file>. The OUT‐
19307 PUT_FILES_VAR may be specified to cause the compiler-specific content
19308 to be written to separate files. The separate files are then available
19309 in the <output_files_var> and may be consumed by the caller for instal‐
19310 lation for example. The OUTPUT_DIR specifies a relative path from the
19311 main <file> to the compiler-specific files. For example:
19312 write_compiler_detection_header(
19314 FILE climbingstats_compiler_detection.h
19315 PREFIX ClimbingStats
19316 OUTPUT_FILES_VAR support_files
19317 OUTPUT_DIR compilers
19318 COMPILERS GNU Clang MSVC Intel
19319 FEATURES cxx_variadic_templates
19320 )
19321 install(FILES
19322 ${CMAKE_CURRENT_BINARY_DIR}/climbingstats_compiler_detection.h
19323 DESTINATION include
19324 )
19325 install(FILES
19326 ${support_files}
19327 DESTINATION include/compilers
19328 )
19329 VERSION may be used to specify the API version to be generated. Future
19331 versions of CMake may introduce alternative APIs. A given API is se‐
19332 lected by any <version> value greater than or equal to the version of
19333 CMake that introduced the given API and less than the version of CMake
19334 that introduced its succeeding API. The value of the CMAKE_MINIMUM_RE‐
19335 QUIRED_VERSION variable is used if no explicit version is specified.
19336 (As of CMake version 3.22.2 there is only one API version.)
19337 PROLOG may be specified as text content to write at the start of the
19339 header. EPILOG may be specified as text content to write at the end of
19340 the header
19341 At least one <compiler> and one <feature> must be listed. Compilers
19343 which are known to CMake, but not specified are detected and a pre‐
19344 processor #error is generated for them. A preprocessor macro matching
19345 <PREFIX>_COMPILER_IS_<compiler> is generated for each compiler known to
19346 CMake to contain the value 0 or 1.
19347 Possible compiler identifiers are documented with the CMAKE_<LANG>_COM‐
19349 PILER_ID variable. Available features in this version of CMake are
19350 listed in the CMAKE_C_KNOWN_FEATURES and CMAKE_CXX_KNOWN_FEATURES
19351 global properties. See the cmake-compile-features(7) manual for infor‐
19352 mation on compile features.
19353 New in version 3.2: Added MSVC and AppleClang compiler support.
19355 New in version 3.6: Added Intel compiler support.
19358 Changed in version 3.8: The {c,cxx}_std_* meta-features are ignored if
19361 requested.
19362 New in version 3.8: ALLOW_UNKNOWN_COMPILERS and ALLOW_UNKNOWN_COM‐
19365 PILER_VERSIONS cause the module to generate conditions that treat un‐
19366 known compilers as simply lacking all features. Without these options
19367 the default behavior is to generate a #error for unknown compilers and
19368 versions.
19369 New in version 3.12: BARE_FEATURES will define the compatibility macros
19372 with the name used in newer versions of the language standard, so the
19373 code can use the new feature name unconditionally.
19374 Feature Test Macros
19377 For each compiler, a preprocessor macro is generated matching <PRE‐
19378 FIX>_COMPILER_IS_<compiler> which has the content either 0 or 1, de‐
19379 pending on the compiler in use. Preprocessor macros for compiler ver‐
19380 sion components are generated matching <PREFIX>_COMPILER_VERSION_MAJOR
19381 <PREFIX>_COMPILER_VERSION_MINOR and <PREFIX>_COMPILER_VERSION_PATCH
19382 containing decimal values for the corresponding compiler version compo‐
19383 nents, if defined.
19384 A preprocessor test is generated based on the compiler version denoting
19386 whether each feature is enabled. A preprocessor macro matching <PRE‐
19387 FIX>_COMPILER_<FEATURE>, where <FEATURE> is the upper-case <feature>
19388 name, is generated to contain the value 0 or 1 depending on whether the
19389 compiler in use supports the feature:
19390 write_compiler_detection_header(
19392 FILE climbingstats_compiler_detection.h
19393 PREFIX ClimbingStats
19394 COMPILERS GNU Clang AppleClang MSVC Intel
19395 FEATURES cxx_variadic_templates
19396 )
19397 #if ClimbingStats_COMPILER_CXX_VARIADIC_TEMPLATES
19399 template<typename... T>
19400 void someInterface(T t...) { /* ... */ }
19401 #else
19402 // Compatibility versions
19403 template<typename T1>
19404 void someInterface(T1 t1) { /* ... */ }
19405 template<typename T1, typename T2>
19406 void someInterface(T1 t1, T2 t2) { /* ... */ }
19407 template<typename T1, typename T2, typename T3>
19408 void someInterface(T1 t1, T2 t2, T3 t3) { /* ... */ }
19409 #endif
19410 Symbol Macros
19412 Some additional symbol-defines are created for particular features for
19413 use as symbols which may be conditionally defined empty:
19414 class MyClass ClimbingStats_FINAL
19416 {
19417 ClimbingStats_CONSTEXPR int someInterface() { return 42; }
19418 };
19419 The ClimbingStats_FINAL macro will expand to final if the compiler (and
19421 its flags) support the cxx_final feature, and the ClimbingStats_CONST‐
19422 EXPR macro will expand to constexpr if cxx_constexpr is supported.
19423 If BARE_FEATURES cxx_final was given as argument the final keyword will
19425 be defined for old compilers, too.
19426 The following features generate corresponding symbol defines and if
19428 they are available as BARE_FEATURES:
19429 ┌──────────────────┬────────────────────┬─────────────┬──────┐
19431 │Feature │ Define │ Symbol │ bare │
19432 └──────────────────┴────────────────────┴─────────────┴──────┘
19433 │c_restrict │ <PREFIX>_RE‐ │ restrict │ yes │
19437 │ │ STRICT │ │ │
19438 ├──────────────────┼────────────────────┼─────────────┼──────┤
19439 │cxx_constexpr │ <PREFIX>_CONST‐ │ constexpr │ yes │
19440 │ │ EXPR │ │ │
19441 ├──────────────────┼────────────────────┼─────────────┼──────┤
19442 │cxx_deleted_func‐ │ <PRE‐ │ = delete │ │
19443 │tions │ FIX>_DELETED_FUNC‐ │ │ │
19444 │ │ TION │ │ │
19445 ├──────────────────┼────────────────────┼─────────────┼──────┤
19446 │cxx_extern_tem‐ │ <PREFIX>_EX‐ │ extern │ │
19447 │plates │ TERN_TEMPLATE │ │ │
19448 ├──────────────────┼────────────────────┼─────────────┼──────┤
19449 │cxx_final │ <PREFIX>_FINAL │ final │ yes │
19450 ├──────────────────┼────────────────────┼─────────────┼──────┤
19451 │cxx_noexcept │ <PREFIX>_NOEXCEPT │ noexcept │ yes │
19452 ├──────────────────┼────────────────────┼─────────────┼──────┤
19453 │cxx_noexcept │ <PREFIX>_NOEX‐ │ noexcept(X) │ │
19454 │ │ CEPT_EXPR(X) │ │ │
19455 ├──────────────────┼────────────────────┼─────────────┼──────┤
19456 │cxx_override │ <PREFIX>_OVERRIDE │ override │ yes │
19457 └──────────────────┴────────────────────┴─────────────┴──────┘
19458 Compatibility Implementation Macros
19460 Some features are suitable for wrapping in a macro with a backward com‐
19461 patibility implementation if the compiler does not support the feature.
19462 When the cxx_static_assert feature is not provided by the compiler, a
19464 compatibility implementation is available via the <PREFIX>_STATIC_AS‐
19465 SERT(COND) and <PREFIX>_STATIC_ASSERT_MSG(COND, MSG) function-like
19466 macros. The macros expand to static_assert where that compiler feature
19467 is available, and to a compatibility implementation otherwise. In the
19468 first form, the condition is stringified in the message field of
19469 static_assert. In the second form, the message MSG is passed to the
19470 message field of static_assert, or ignored if using the backward com‐
19471 patibility implementation.
19472 The cxx_attribute_deprecated feature provides a macro definition <PRE‐
19474 FIX>_DEPRECATED, which expands to either the standard [[deprecated]]
19475 attribute or a compiler-specific decorator such as __attri‐
19476 bute__((__deprecated__)) used by GNU compilers.
19477 The cxx_alignas feature provides a macro definition <PREFIX>_ALIGNAS
19479 which expands to either the standard alignas decorator or a com‐
19480 piler-specific decorator such as __attribute__ ((__aligned__)) used by
19481 GNU compilers.
19482 The cxx_alignof feature provides a macro definition <PREFIX>_ALIGNOF
19484 which expands to either the standard alignof decorator or a com‐
19485 piler-specific decorator such as __alignof__ used by GNU compilers.
19486 ┌─────────────────┬──────────────────┬────────────────┬──────┐
19488 │Feature │ Define │ Symbol │ bare │
19489 ├─────────────────┼──────────────────┼────────────────┼──────┤
19490 │cxx_alignas │ <PREFIX>_ALIGNAS │ alignas │ │
19491 ├─────────────────┼──────────────────┼────────────────┼──────┤
19492 │cxx_alignof │ <PREFIX>_ALIGNOF │ alignof │ │
19493 ├─────────────────┼──────────────────┼────────────────┼──────┤
19494 │cxx_nullptr │ <PREFIX>_NULLPTR │ nullptr │ yes │
19495 ├─────────────────┼──────────────────┼────────────────┼──────┤
19496 │cxx_static_as‐ │ <PRE‐ │ static_assert │ │
19497 │sert │ FIX>_STATIC_AS‐ │ │ │
19498 │ │ SERT │ │ │
19499 ├─────────────────┼──────────────────┼────────────────┼──────┤
19500 │cxx_static_as‐ │ <PRE‐ │ static_assert │ │
19501 │sert │ FIX>_STATIC_AS‐ │ │ │
19502 │ │ SERT_MSG │ │ │
19503 ├─────────────────┼──────────────────┼────────────────┼──────┤
19504 │cxx_attri‐ │ <PREFIX>_DEPRE‐ │ [[deprecated]] │ │
19505 │bute_deprecated │ CATED │ │ │
19506 ├─────────────────┼──────────────────┼────────────────┼──────┤
19507 │cxx_attri‐ │ <PREFIX>_DEPRE‐ │ [[deprecated]] │ │
19508 │bute_deprecated │ CATED_MSG │ │ │
19509 ├─────────────────┼──────────────────┼────────────────┼──────┤
19510 │cxx_thread_local │ <PRE‐ │ thread_local │ │
19511 │ │ FIX>_THREAD_LO‐ │ │ │
19512 │ │ CAL │ │ │
19513 └─────────────────┴──────────────────┴────────────────┴──────┘
19514 A use-case which arises with such deprecation macros is the deprecation
19516 of an entire library. In that case, all public API in the library may
19517 be decorated with the <PREFIX>_DEPRECATED macro. This results in very
19518 noisy build output when building the library itself, so the macro may
19519 be may be defined to empty in that case when building the deprecated
19520 library:
19521 add_library(compat_support ${srcs})
19523 target_compile_definitions(compat_support
19524 PRIVATE
19525 CompatSupport_DEPRECATED=
19526 )
19527 Example Usage
19529 NOTE:
19530 This section was migrated from the cmake-compile-features(7) manual
19531 since it relies on the WriteCompilerDetectionHeader module which is
19532 removed by policy CMP0120.
19533 Compile features may be preferred if available, without creating a hard
19535 requirement. For example, a library may provide alternative implemen‐
19536 tations depending on whether the cxx_variadic_templates feature is
19537 available:
19538 #if Foo_COMPILER_CXX_VARIADIC_TEMPLATES
19540 template<int I, int... Is>
19541 struct Interface;
19542 template<int I>
19544 struct Interface<I>
19545 {
19546 static int accumulate()
19547 {
19548 return I;
19549 }
19550 };
19551 template<int I, int... Is>
19553 struct Interface
19554 {
19555 static int accumulate()
19556 {
19557 return I + Interface<Is...>::accumulate();
19558 }
19559 };
19560 #else
19561 template<int I1, int I2 = 0, int I3 = 0, int I4 = 0>
19562 struct Interface
19563 {
19564 static int accumulate() { return I1 + I2 + I3 + I4; }
19565 };
19566 #endif
19567 Such an interface depends on using the correct preprocessor defines for
19569 the compiler features. CMake can generate a header file containing
19570 such defines using the WriteCompilerDetectionHeader module. The module
19571 contains the write_compiler_detection_header function which accepts pa‐
19572 rameters to control the content of the generated header file:
19573 write_compiler_detection_header(
19575 FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
19576 PREFIX Foo
19577 COMPILERS GNU
19578 FEATURES
19579 cxx_variadic_templates
19580 )
19581 Such a header file may be used internally in the source code of a
19583 project, and it may be installed and used in the interface of library
19584 code.
19585 For each feature listed in FEATURES, a preprocessor definition is cre‐
19587 ated in the header file, and defined to either 1 or 0.
19588 Additionally, some features call for additional defines, such as the
19590 cxx_final and cxx_override features. Rather than being used in #ifdef
19591 code, the final keyword is abstracted by a symbol which is defined to
19592 either final, a compiler-specific equivalent, or to empty. That way,
19593 C++ code can be written to unconditionally use the symbol, and compiler
19594 support determines what it is expanded to:
19595 struct Interface {
19597 virtual void Execute() = 0;
19598 };
19599 struct Concrete Foo_FINAL {
19601 void Execute() Foo_OVERRIDE;
19602 };
19603 In this case, Foo_FINAL will expand to final if the compiler supports
19605 the keyword, or to empty otherwise.
19606 In this use-case, the project code may wish to enable a particular lan‐
19608 guage standard if available from the compiler. The CXX_STANDARD target
19609 property may be set to the desired language standard for a particular
19610 target, and the CMAKE_CXX_STANDARD variable may be set to influence all
19611 following targets:
19612 write_compiler_detection_header(
19614 FILE "${CMAKE_CURRENT_BINARY_DIR}/foo_compiler_detection.h"
19615 PREFIX Foo
19616 COMPILERS GNU
19617 FEATURES
19618 cxx_final cxx_override
19619 )
19620 # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
19622 # which will expand to 'final' if the compiler supports the requested
19623 # CXX_STANDARD.
19624 add_library(foo foo.cpp)
19625 set_property(TARGET foo PROPERTY CXX_STANDARD 11)
19626 # Includes foo_compiler_detection.h and uses the Foo_FINAL symbol
19628 # which will expand to 'final' if the compiler supports the feature,
19629 # even though CXX_STANDARD is not set explicitly. The requirement of
19630 # cxx_constexpr causes CMake to set CXX_STANDARD internally, which
19631 # affects the compile flags.
19632 add_library(foo_impl foo_impl.cpp)
19633 target_compile_features(foo_impl PRIVATE cxx_constexpr)
19634 The write_compiler_detection_header function also creates compatibility
19636 code for other features which have standard equivalents. For example,
19637 the cxx_static_assert feature is emulated with a template and ab‐
19638 stracted via the <PREFIX>_STATIC_ASSERT and <PREFIX>_STATIC_ASSERT_MSG
19639 function-macros.
19640 Deprecated Find Modules
19642 FindCUDA
19643 WARNING:
19644 Deprecated since version 3.10.
19645 It is no longer necessary to use this module or call find_package(CUDA)
19647 for compiling CUDA code. Instead, list CUDA among the languages named
19648 in the top-level call to the project() command, or call the enable_lan‐
19649 guage() command with CUDA. Then one can add CUDA (.cu) sources di‐
19650 rectly to targets similar to other languages.
19651 New in version 3.17: To find and use the CUDA toolkit libraries manu‐
19653 ally, use the FindCUDAToolkit module instead. It works regardless of
19654 the CUDA language being enabled.
19655 Documentation of Deprecated Usage
19658 Tools for building CUDA C files: libraries and build dependencies.
19659 This script locates the NVIDIA CUDA C tools. It should work on Linux,
19661 Windows, and macOS and should be reasonably up to date with CUDA C re‐
19662 leases.
19663 New in version 3.19: QNX support.
19665 This script makes use of the standard find_package() arguments of <VER‐
19668 SION>, REQUIRED and QUIET. CUDA_FOUND will report if an acceptable
19669 version of CUDA was found.
19670 The script will prompt the user to specify CUDA_TOOLKIT_ROOT_DIR if the
19672 prefix cannot be determined by the location of nvcc in the system path
19673 and REQUIRED is specified to find_package(). To use a different in‐
19674 stalled version of the toolkit set the environment variable
19675 CUDA_BIN_PATH before running cmake (e.g. CUDA_BIN_PATH=/usr/lo‐
19676 cal/cuda1.0 instead of the default /usr/local/cuda) or set CUDA_TOOL‐
19677 KIT_ROOT_DIR after configuring. If you change the value of CUDA_TOOL‐
19678 KIT_ROOT_DIR, various components that depend on the path will be relo‐
19679 cated.
19680 It might be necessary to set CUDA_TOOLKIT_ROOT_DIR manually on certain
19682 platforms, or to use a CUDA runtime not installed in the default loca‐
19683 tion. In newer versions of the toolkit the CUDA library is included
19684 with the graphics driver -- be sure that the driver version matches
19685 what is needed by the CUDA runtime version.
19686 Input Variables
19688 The following variables affect the behavior of the macros in the script
19689 (in alphabetical order). Note that any of these flags can be changed
19690 multiple times in the same directory before calling cuda_add_exe‐
19691 cutable(), cuda_add_library(), cuda_compile(), cuda_compile_ptx(),
19692 cuda_compile_fatbin(), cuda_compile_cubin() or cuda_wrap_srcs():
19693 CUDA_64_BIT_DEVICE_CODE (Default: host bit size)
19695 Set to ON to compile for 64 bit device code, OFF for 32 bit de‐
19696 vice code. Note that making this different from the host code
19697 when generating object or C files from CUDA code just won't
19698 work, because size_t gets defined by nvcc in the generated
19699 source. If you compile to PTX and then load the file yourself,
19700 you can mix bit sizes between device and host.
19701 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE (Default: ON)
19703 Set to ON if you want the custom build rule to be attached to
19704 the source file in Visual Studio. Turn OFF if you add the same
19705 cuda file to multiple targets.
19706 This allows the user to build the target from the CUDA file;
19708 however, bad things can happen if the CUDA source file is added
19709 to multiple targets. When performing parallel builds it is pos‐
19710 sible for the custom build command to be run more than once and
19711 in parallel causing cryptic build errors. VS runs the rules for
19712 every source file in the target, and a source can have only one
19713 rule no matter how many projects it is added to. When the rule
19714 is run from multiple targets race conditions can occur on the
19715 generated file. Eventually everything will get built, but if
19716 the user is unaware of this behavior, there may be confusion.
19717 It would be nice if this script could detect the reuse of source
19718 files across multiple targets and turn the option off for the
19719 user, but no good solution could be found.
19720 CUDA_BUILD_CUBIN (Default: OFF)
19722 Set to ON to enable and extra compilation pass with the -cubin
19723 option in Device mode. The output is parsed and register, shared
19724 memory usage is printed during build.
19725 CUDA_BUILD_EMULATION (Default: OFF for device mode)
19727 Set to ON for Emulation mode. -D_DEVICEEMU is defined for CUDA C
19728 files when CUDA_BUILD_EMULATION is TRUE.
19729 CUDA_LINK_LIBRARIES_KEYWORD (Default: "")
19731 New in version 3.9.
19732 The <PRIVATE|PUBLIC|INTERFACE> keyword to use for internal tar‐
19735 get_link_libraries() calls. The default is to use no keyword
19736 which uses the old "plain" form of target_link_libraries(). Note
19737 that is matters because whatever is used inside the FindCUDA
19738 module must also be used outside - the two forms of tar‐
19739 get_link_libraries() cannot be mixed.
19740 CUDA_GENERATED_OUTPUT_DIR (Default: CMAKE_CURRENT_BINARY_DIR)
19742 Set to the path you wish to have the generated files placed. If
19743 it is blank output files will be placed in CMAKE_CURRENT_BI‐
19744 NARY_DIR. Intermediate files will always be placed in
19745 CMAKE_CURRENT_BINARY_DIR/CMakeFiles.
19746 CUDA_HOST_COMPILATION_CPP (Default: ON)
19748 Set to OFF for C compilation of host code.
19749 CUDA_HOST_COMPILER (Default: CMAKE_C_COMPILER)
19751 Set the host compiler to be used by nvcc. Ignored if -ccbin or
19752 --compiler-bindir is already present in the CUDA_NVCC_FLAGS or
19753 CUDA_NVCC_FLAGS_<CONFIG> variables. For Visual Studio targets,
19754 the host compiler is constructed with one or more visual studio
19755 macros such as $(VCInstallDir), that expands out to the path
19756 when the command is run from within VS.
19757 New in version 3.13: If the CUDAHOSTCXX environment variable is
19759 set it will be used as the default.
19760 CUDA_NVCC_FLAGS, CUDA_NVCC_FLAGS_<CONFIG>
19763 Additional NVCC command line arguments. NOTE: multiple argu‐
19764 ments must be semi-colon delimited (e.g. --compiler-op‐
19765 tions;-Wall)
19766 New in version 3.6: Contents of these variables may use genera‐
19768 tor expressions.
19769 CUDA_PROPAGATE_HOST_FLAGS (Default: ON)
19772 Set to ON to propagate CMAKE_{C,CXX}_FLAGS and their configura‐
19773 tion dependent counterparts (e.g. CMAKE_C_FLAGS_DEBUG) automati‐
19774 cally to the host compiler through nvcc's -Xcompiler flag. This
19775 helps make the generated host code match the rest of the system
19776 better. Sometimes certain flags give nvcc problems, and this
19777 will help you turn the flag propagation off. This does not af‐
19778 fect the flags supplied directly to nvcc via CUDA_NVCC_FLAGS or
19779 through the OPTION flags specified through cuda_add_library(),
19780 cuda_add_executable(), or cuda_wrap_srcs(). Flags used for
19781 shared library compilation are not affected by this flag.
19782 CUDA_SEPARABLE_COMPILATION (Default: OFF)
19784 If set this will enable separable compilation for all CUDA run‐
19785 time object files. If used outside of cuda_add_executable() and
19786 cuda_add_library() (e.g. calling cuda_wrap_srcs() directly),
19787 cuda_compute_separable_compilation_object_file_name() and
19788 cuda_link_separable_compilation_objects() should be called.
19789 CUDA_SOURCE_PROPERTY_FORMAT
19791 New in version 3.3.
19792 If this source file property is set, it can override the format
19795 specified to cuda_wrap_srcs() (OBJ, PTX, CUBIN, or FATBIN). If
19796 an input source file is not a .cu file, setting this file will
19797 cause it to be treated as a .cu file. See documentation for
19798 set_source_files_properties on how to set this property.
19799 CUDA_USE_STATIC_CUDA_RUNTIME (Default: ON)
19801 New in version 3.3.
19802 When enabled the static version of the CUDA runtime library will
19805 be used in CUDA_LIBRARIES. If the version of CUDA configured
19806 doesn't support this option, then it will be silently disabled.
19807 CUDA_VERBOSE_BUILD (Default: OFF)
19809 Set to ON to see all the commands used when building the CUDA
19810 file. When using a Makefile generator the value defaults to
19811 VERBOSE (run make VERBOSE=1 to see output), although setting
19812 CUDA_VERBOSE_BUILD to ON will always print the output.
19813 Commands
19815 The script creates the following functions and macros (in alphabetical
19816 order):
19817 cuda_add_cufft_to_target(<cuda_target>)
19819 Adds the cufft library to the target (can be any target). Handles
19821 whether you are in emulation mode or not.
19822 cuda_add_cublas_to_target(<cuda_target>)
19824 Adds the cublas library to the target (can be any target). Handles
19826 whether you are in emulation mode or not.
19827 cuda_add_executable(<cuda_target> <file>...
19829 [WIN32] [MACOSX_BUNDLE] [EXCLUDE_FROM_ALL] [OPTIONS ...])
19830 Creates an executable <cuda_target> which is made up of the files spec‐
19832 ified. All of the non CUDA C files are compiled using the standard
19833 build rules specified by CMake and the CUDA files are compiled to ob‐
19834 ject files using nvcc and the host compiler. In addition CUDA_IN‐
19835 CLUDE_DIRS is added automatically to include_directories(). Some stan‐
19836 dard CMake target calls can be used on the target after calling this
19837 macro (e.g. set_target_properties() and target_link_libraries()), but
19838 setting properties that adjust compilation flags will not affect code
19839 compiled by nvcc. Such flags should be modified before calling
19840 cuda_add_executable(), cuda_add_library() or cuda_wrap_srcs().
19841 cuda_add_library(<cuda_target> <file>...
19843 [STATIC | SHARED | MODULE] [EXCLUDE_FROM_ALL] [OPTIONS ...])
19844 Same as cuda_add_executable() except that a library is created.
19846 cuda_build_clean_target()
19848 Creates a convenience target that deletes all the dependency files gen‐
19850 erated. You should make clean after running this target to ensure the
19851 dependency files get regenerated.
19852 cuda_compile(<generated_files> <file>... [STATIC | SHARED | MODULE]
19854 [OPTIONS ...])
19855 Returns a list of generated files from the input source files to be
19857 used with add_library() or add_executable().
19858 cuda_compile_ptx(<generated_files> <file>... [OPTIONS ...])
19860 Returns a list of PTX files generated from the input source files.
19862 cuda_compile_fatbin(<generated_files> <file>... [OPTIONS ...])
19864 New in version 3.1.
19866 Returns a list of FATBIN files generated from the input source files.
19869 cuda_compile_cubin(<generated_files> <file>... [OPTIONS ...])
19871 New in version 3.1.
19873 Returns a list of CUBIN files generated from the input source files.
19876 cuda_compute_separable_compilation_object_file_name(<output_file_var>
19878 <cuda_target>
19879 <object_files>)
19880 Compute the name of the intermediate link file used for separable com‐
19882 pilation. This file name is typically passed into CUDA_LINK_SEPARA‐
19883 BLE_COMPILATION_OBJECTS. output_file_var is produced based on
19884 cuda_target the list of objects files that need separable compilation
19885 as specified by <object_files>. If the <object_files> list is empty,
19886 then <output_file_var> will be empty. This function is called automat‐
19887 ically for cuda_add_library() and cuda_add_executable(). Note that
19888 this is a function and not a macro.
19889 cuda_include_directories(path0 path1 ...)
19891 Sets the directories that should be passed to nvcc (e.g. nvcc -Ipath0
19893 -Ipath1 ...). These paths usually contain other .cu files.
19894 cuda_link_separable_compilation_objects(<output_file_var> <cuda_target>
19896 <nvcc_flags> <object_files>)
19897 Generates the link object required by separable compilation from the
19899 given object files. This is called automatically for cuda_add_exe‐
19900 cutable() and cuda_add_library(), but can be called manually when using
19901 cuda_wrap_srcs() directly. When called from cuda_add_library() or
19902 cuda_add_executable() the <nvcc_flags> passed in are the same as the
19903 flags passed in via the OPTIONS argument. The only nvcc flag added au‐
19904 tomatically is the bitness flag as specified by CUDA_64_BIT_DE‐
19905 VICE_CODE. Note that this is a function instead of a macro.
19906 cuda_select_nvcc_arch_flags(<out_variable> [<target_CUDA_architecture> ...])
19908 Selects GPU arch flags for nvcc based on target_CUDA_architecture.
19910 Values for target_CUDA_architecture:
19912 • Auto: detects local machine GPU compute arch at runtime.
19914 • Common and All: cover common and entire subsets of architectures.
19916 • <name>: one of Fermi, Kepler, Maxwell, Kepler+Tegra, Kepler+Tesla,
19918 Maxwell+Tegra, Pascal.
19919 • <ver>, <ver>(<ver>), <ver>+PTX, where <ver> is one of 2.0, 2.1, 3.0,
19921 3.2, 3.5, 3.7, 5.0, 5.2, 5.3, 6.0, 6.2.
19922 Returns list of flags to be added to CUDA_NVCC_FLAGS in <out_variable>.
19924 Additionally, sets <out_variable>_readable to the resulting numeric
19925 list.
19926 Example:
19928 cuda_select_nvcc_arch_flags(ARCH_FLAGS 3.0 3.5+PTX 5.2(5.0) Maxwell)
19930 list(APPEND CUDA_NVCC_FLAGS ${ARCH_FLAGS})
19931 More info on CUDA architectures: https://en.wikipedia.org/wiki/CUDA.
19933 Note that this is a function instead of a macro.
19934 cuda_wrap_srcs(<cuda_target> <format> <generated_files> <file>...
19936 [STATIC | SHARED | MODULE] [OPTIONS ...])
19937 This is where all the magic happens. cuda_add_executable(),
19939 cuda_add_library(), cuda_compile(), and cuda_compile_ptx() all call
19940 this function under the hood.
19941 Given the list of files <file>... this macro generates custom commands
19943 that generate either PTX or linkable objects (use PTX or OBJ for the
19944 <format> argument to switch). Files that don't end with .cu or have
19945 the HEADER_FILE_ONLY property are ignored.
19946 The arguments passed in after OPTIONS are extra command line options to
19948 give to nvcc. You can also specify per configuration options by speci‐
19949 fying the name of the configuration followed by the options. General
19950 options must precede configuration specific options. Not all configu‐
19951 rations need to be specified, only the ones provided will be used. For
19952 example:
19953 cuda_add_executable(...
19955 OPTIONS -DFLAG=2 "-DFLAG_OTHER=space in flag"
19956 DEBUG -g
19957 RELEASE --use_fast_math
19958 RELWITHDEBINFO --use_fast_math;-g
19959 MINSIZEREL --use_fast_math)
19960 For certain configurations (namely VS generating object files with
19962 CUDA_ATTACH_VS_BUILD_RULE_TO_CUDA_FILE set to ON), no generated file
19963 will be produced for the given cuda file. This is because when you add
19964 the cuda file to Visual Studio it knows that this file produces an ob‐
19965 ject file and will link in the resulting object file automatically.
19966 This script will also generate a separate cmake script that is used at
19968 build time to invoke nvcc. This is for several reasons:
19969 • nvcc can return negative numbers as return values which confuses Vis‐
19971 ual Studio into thinking that the command succeeded. The script now
19972 checks the error codes and produces errors when there was a problem.
19973 • nvcc has been known to not delete incomplete results when it encoun‐
19975 ters problems. This confuses build systems into thinking the target
19976 was generated when in fact an unusable file exists. The script now
19977 deletes the output files if there was an error.
19978 • By putting all the options that affect the build into a file and then
19980 make the build rule dependent on the file, the output files will be
19981 regenerated when the options change.
19982 This script also looks at optional arguments STATIC, SHARED, or MODULE
19984 to determine when to target the object compilation for a shared li‐
19985 brary. BUILD_SHARED_LIBS is ignored in cuda_wrap_srcs(), but it is re‐
19986 spected in cuda_add_library(). On some systems special flags are added
19987 for building objects intended for shared libraries. A preprocessor
19988 macro, <target_name>_EXPORTS is defined when a shared library compila‐
19989 tion is detected.
19990 Flags passed into add_definitions with -D or /D are passed along to
19992 nvcc.
19993 Result Variables
19995 The script defines the following variables:
19996 CUDA_VERSION_MAJOR
19998 The major version of cuda as reported by nvcc.
19999 CUDA_VERSION_MINOR
20001 The minor version.
20002 CUDA_VERSION, CUDA_VERSION_STRING
20004 Full version in the X.Y format.
20005 CUDA_HAS_FP16
20007 New in version 3.6: Whether a short float (float16, fp16) is
20008 supported.
20009 CUDA_TOOLKIT_ROOT_DIR
20012 Path to the CUDA Toolkit (defined if not set).
20013 CUDA_SDK_ROOT_DIR
20015 Path to the CUDA SDK. Use this to find files in the SDK. This
20016 script will not directly support finding specific libraries or
20017 headers, as that isn't supported by NVIDIA. If you want to
20018 change libraries when the path changes see the FindCUDA.cmake
20019 script for an example of how to clear these variables. There
20020 are also examples of how to use the CUDA_SDK_ROOT_DIR to locate
20021 headers or libraries, if you so choose (at your own risk).
20022 CUDA_INCLUDE_DIRS
20024 Include directory for cuda headers. Added automatically for
20025 cuda_add_executable() and cuda_add_library().
20026 CUDA_LIBRARIES
20028 Cuda RT library.
20029 CUDA_CUFFT_LIBRARIES
20031 Device or emulation library for the Cuda FFT implementation (al‐
20032 ternative to cuda_add_cufft_to_target() macro)
20033 CUDA_CUBLAS_LIBRARIES
20035 Device or emulation library for the Cuda BLAS implementation
20036 (alternative to cuda_add_cublas_to_target() macro).
20037 CUDA_cudart_static_LIBRARY
20039 Statically linkable cuda runtime library. Only available for
20040 CUDA version 5.5+.
20041 CUDA_cudadevrt_LIBRARY
20043 New in version 3.7: Device runtime library. Required for sepa‐
20044 rable compilation.
20045 CUDA_cupti_LIBRARY
20048 CUDA Profiling Tools Interface library. Only available for CUDA
20049 version 4.0+.
20050 CUDA_curand_LIBRARY
20052 CUDA Random Number Generation library. Only available for CUDA
20053 version 3.2+.
20054 CUDA_cusolver_LIBRARY
20056 New in version 3.2: CUDA Direct Solver library. Only available
20057 for CUDA version 7.0+.
20058 CUDA_cusparse_LIBRARY
20061 CUDA Sparse Matrix library. Only available for CUDA version
20062 3.2+.
20063 CUDA_npp_LIBRARY
20065 NVIDIA Performance Primitives lib. Only available for CUDA ver‐
20066 sion 4.0+.
20067 CUDA_nppc_LIBRARY
20069 NVIDIA Performance Primitives lib (core). Only available for
20070 CUDA version 5.5+.
20071 CUDA_nppi_LIBRARY
20073 NVIDIA Performance Primitives lib (image processing). Only
20074 available for CUDA version 5.5 - 8.0.
20075 CUDA_nppial_LIBRARY
20077 NVIDIA Performance Primitives lib (image processing). Only
20078 available for CUDA version 9.0.
20079 CUDA_nppicc_LIBRARY
20081 NVIDIA Performance Primitives lib (image processing). Only
20082 available for CUDA version 9.0.
20083 CUDA_nppicom_LIBRARY
20085 NVIDIA Performance Primitives lib (image processing). Only
20086 available for CUDA version 9.0 - 10.2. Replaced by nvjpeg.
20087 CUDA_nppidei_LIBRARY
20089 NVIDIA Performance Primitives lib (image processing). Only
20090 available for CUDA version 9.0.
20091 CUDA_nppif_LIBRARY
20093 NVIDIA Performance Primitives lib (image processing). Only
20094 available for CUDA version 9.0.
20095 CUDA_nppig_LIBRARY
20097 NVIDIA Performance Primitives lib (image processing). Only
20098 available for CUDA version 9.0.
20099 CUDA_nppim_LIBRARY
20101 NVIDIA Performance Primitives lib (image processing). Only
20102 available for CUDA version 9.0.
20103 CUDA_nppist_LIBRARY
20105 NVIDIA Performance Primitives lib (image processing). Only
20106 available for CUDA version 9.0.
20107 CUDA_nppisu_LIBRARY
20109 NVIDIA Performance Primitives lib (image processing). Only
20110 available for CUDA version 9.0.
20111 CUDA_nppitc_LIBRARY
20113 NVIDIA Performance Primitives lib (image processing). Only
20114 available for CUDA version 9.0.
20115 CUDA_npps_LIBRARY
20117 NVIDIA Performance Primitives lib (signal processing). Only
20118 available for CUDA version 5.5+.
20119 CUDA_nvcuvenc_LIBRARY
20121 CUDA Video Encoder library. Only available for CUDA version
20122 3.2+. Windows only.
20123 CUDA_nvcuvid_LIBRARY
20125 CUDA Video Decoder library. Only available for CUDA version
20126 3.2+. Windows only.
20127 CUDA_nvToolsExt_LIBRARY
20129 New in version 3.16: NVIDA CUDA Tools Extension library. Avail‐
20130 able for CUDA version 5+.
20131 CUDA_OpenCL_LIBRARY
20134 New in version 3.16: NVIDA CUDA OpenCL library. Available for
20135 CUDA version 5+.
20136 FindPythonInterp
20139 Deprecated since version 3.12: Use FindPython3, FindPython2 or Find‐
20140 Python instead.
20141 Find python interpreter
20144 This module finds if Python interpreter is installed and determines
20146 where the executables are. This code sets the following variables:
20147 PYTHONINTERP_FOUND - Was the Python executable found
20149 PYTHON_EXECUTABLE - path to the Python interpreter
20150 PYTHON_VERSION_STRING - Python version found e.g. 2.5.2
20152 PYTHON_VERSION_MAJOR - Python major version found e.g. 2
20153 PYTHON_VERSION_MINOR - Python minor version found e.g. 5
20154 PYTHON_VERSION_PATCH - Python patch version found e.g. 2
20155 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
20157 of version numbers that should be taken into account when searching for
20158 Python. You need to set this variable before calling find_pack‐
20159 age(PythonInterp).
20160 If calling both find_package(PythonInterp) and find_package(Python‐
20162 Libs), call find_package(PythonInterp) first to get the currently ac‐
20163 tive Python version by default with a consistent version of PYTHON_LI‐
20164 BRARIES.
20165 NOTE:
20167 A call to find_package(PythonInterp ${V}) for python version V may
20168 find a python executable with no version suffix. In this case no
20169 attempt is made to avoid python executables from other versions.
20170 Use FindPython3, FindPython2 or FindPython instead.
20171 FindPythonLibs
20173 Deprecated since version 3.12: Use FindPython3, FindPython2 or Find‐
20174 Python instead.
20175 Find python libraries
20178 This module finds if Python is installed and determines where the in‐
20180 clude files and libraries are. It also determines what the name of the
20181 library is. This code sets the following variables:
20182 PYTHONLIBS_FOUND - have the Python libs been found
20184 PYTHON_LIBRARIES - path to the python library
20185 PYTHON_INCLUDE_PATH - path to where Python.h is found (deprecated)
20186 PYTHON_INCLUDE_DIRS - path to where Python.h is found
20187 PYTHON_DEBUG_LIBRARIES - path to the debug library (deprecated)
20188 PYTHONLIBS_VERSION_STRING - version of the Python libs found (since CMake 2.8.8)
20189 The Python_ADDITIONAL_VERSIONS variable can be used to specify a list
20191 of version numbers that should be taken into account when searching for
20192 Python. You need to set this variable before calling find_pack‐
20193 age(PythonLibs).
20194 If you'd like to specify the installation of Python to use, you should
20196 modify the following cache variables:
20197 PYTHON_LIBRARY - path to the python library
20199 PYTHON_INCLUDE_DIR - path to where Python.h is found
20200 If calling both find_package(PythonInterp) and find_package(Python‐
20202 Libs), call find_package(PythonInterp) first to get the currently ac‐
20203 tive Python version by default with a consistent version of PYTHON_LI‐
20204 BRARIES.
20205 FindQt
20207 Deprecated since version 3.14: This module is available only if policy
20208 CMP0084 is not set to NEW.
20209 Searches for all installed versions of Qt3 or Qt4.
20212 This module cannot handle Qt5 or any later versions. For those, see
20214 cmake-qt(7).
20215 This module should only be used if your project can work with multiple
20217 versions of Qt. If not, you should just directly use FindQt4 or
20218 FindQt3. If multiple versions of Qt are found on the machine, then The
20219 user must set the option DESIRED_QT_VERSION to the version they want to
20220 use. If only one version of qt is found on the machine, then the DE‐
20221 SIRED_QT_VERSION is set to that version and the matching FindQt3 or
20222 FindQt4 module is included. Once the user sets DESIRED_QT_VERSION,
20223 then the FindQt3 or FindQt4 module is included.
20224 QT_REQUIRED if this is set to TRUE then if CMake can
20226 not find Qt4 or Qt3 an error is raised
20227 and a message is sent to the user.
20228 DESIRED_QT_VERSION OPTION is created
20230 QT4_INSTALLED is set to TRUE if qt4 is found.
20231 QT3_INSTALLED is set to TRUE if qt3 is found.
20232 FindwxWindows
20234 Deprecated since version 3.0: Replaced by FindwxWidgets.
20235 Find wxWindows (wxWidgets) installation
20238 This module finds if wxWindows/wxWidgets is installed and determines
20240 where the include files and libraries are. It also determines what the
20241 name of the library is. This code sets the following variables:
20242 WXWINDOWS_FOUND = system has WxWindows
20244 WXWINDOWS_LIBRARIES = path to the wxWindows libraries
20245 on Unix/Linux with additional
20246 linker flags from
20247 "wx-config --libs"
20248 CMAKE_WXWINDOWS_CXX_FLAGS = Compiler flags for wxWindows,
20249 essentially "`wx-config --cxxflags`"
20250 on Linux
20251 WXWINDOWS_INCLUDE_DIR = where to find "wx/wx.h" and "wx/setup.h"
20252 WXWINDOWS_LINK_DIRECTORIES = link directories, useful for rpath on
20253 Unix
20254 WXWINDOWS_DEFINITIONS = extra defines
20255 OPTIONS If you need OpenGL support please
20257 set(WXWINDOWS_USE_GL 1)
20259 in your CMakeLists.txt before you include this file.
20261 HAVE_ISYSTEM - true required to replace -I by -isystem on g++
20263 For convenience include Use_wxWindows.cmake in your project's CMake‐
20265 Lists.txt using include(${CMAKE_CURRENT_LIST_DIR}/Use_wxWindows.cmake).
20266 USAGE
20268 set(WXWINDOWS_USE_GL 1)
20270 find_package(wxWindows)
20271 NOTES wxWidgets 2.6.x is supported for monolithic builds e.g. compiled
20273 in wx/build/msw dir as:
20274 nmake -f makefile.vc BUILD=debug SHARED=0 USE_OPENGL=1 MONOLITHIC=1
20276 DEPRECATED
20278 CMAKE_WX_CAN_COMPILE
20280 WXWINDOWS_LIBRARY
20281 CMAKE_WX_CXX_FLAGS
20282 WXWINDOWS_INCLUDE_PATH
20283 AUTHOR Jan Woetzel <http://www.mip.informatik.uni-kiel.de/~jw>
20285 (07/2003-01/2006)
20286 Legacy CPack Modules
20288 These modules used to be mistakenly exposed to the user, and have been
20289 moved out of user visibility. They are for CPack internal use, and
20290 should never be used directly.
20291 CPackArchive
20293 New in version 3.9.
20294 The documentation for the CPack Archive generator has moved here: CPack
20297 Archive Generator
20298 CPackBundle
20300 The documentation for the CPack Bundle generator has moved here: CPack
20301 Bundle Generator
20302 CPackCygwin
20304 The documentation for the CPack Cygwin generator has moved here: CPack
20305 Cygwin Generator
20306 CPackDeb
20308 The documentation for the CPack DEB generator has moved here: CPack DEB
20309 Generator
20310 CPackDMG
20312 The documentation for the CPack DragNDrop generator has moved here:
20313 CPack DragNDrop Generator
20314 CPackFreeBSD
20316 New in version 3.10.
20317 The documentation for the CPack FreeBSD generator has moved here: CPack
20320 FreeBSD Generator
20321 CPackNSIS
20323 The documentation for the CPack NSIS generator has moved here: CPack
20324 NSIS Generator
20325 CPackNuGet
20327 New in version 3.12.
20328 The documentation for the CPack NuGet generator has moved here: CPack
20331 NuGet Generator
20332 CPackPackageMaker
20334 The documentation for the CPack PackageMaker generator has moved here:
20335 CPack PackageMaker Generator
20336 CPackProductBuild
20338 New in version 3.7.
20339 The documentation for the CPack productbuild generator has moved here:
20342 CPack productbuild Generator
20343 CPackRPM
20345 The documentation for the CPack RPM generator has moved here: CPack RPM
20346 Generator
20347 CPackWIX
20349 The documentation for the CPack WIX generator has moved here: CPack WIX
20350 Generator
20351
20353 2000-2022 Kitware, Inc. and Contributors
203543.22.2 Jan 25, 2022 CMAKE-MODULES(7)